Credentials as a gate

By default, anyone can pay any account on the XRP Ledger. Some businesses cannot allow that. The rules they work under say they must know who pays them.

The ledger has a switch for this, called Deposit Authorization. With it on, an account rejects payments unless it approved the sender first.

Approving senders one at a time does not scale. A business with ten thousand customers would need ten thousand approvals.

Credentials fix that. The business says once: "I accept payments from any account that holds this credential from this issuer." After that:

• A new customer gets vetted by the issuer and accepts the credential.
• The customer can pay the business right away.
• The business did nothing for that customer.

The customer shows the credential by naming it in the payment. The ledger checks it on the spot.

The match is strict. If the business asked for two credentials together, the payer must name those two, no more and no fewer.

If the issuer later deletes the credential, the gate closes for that customer. Nothing else has to change.

The same idea opens other doors. A permissioned domain is a named list of accepted credentials. Features built on domains, such as the permissioned DEX, let in only accounts that hold one.

Setting the gate. The receiver enables Deposit Authorization, then sends DepositPreauth with exactly one of four fields:

Each member of AuthorizeCredentials is an object with Issuer and CredentialType. A set holds 1 to 8 credentials. To be preauthorized, a sender must hold all of them. Each DepositPreauth entry costs the receiver one owner reserve. tecNO_ISSUER means a named issuer does not exist.

Passing the gate. The sender adds CredentialIDs, an array of Credential entry IDs. The Credentials amendment added the field to Payment, EscrowFinish, PaymentChannelClaim and AccountDelete.

The set must exactly match a DepositPreauth entry of the destination. Every credential must be valid:

• It exists.
• The subject has accepted it.
• It is not expired.
• The sender of the transaction is its subject.

If the destination does not use Deposit Authorization, the credentials are not needed but are still checked for validity.

Checking ahead. deposit_authorized takes a source, a destination and an optional credentials array. A set that does not exactly match a preauthorized one is not authorized, even when a subset would be. That mirrors transaction processing.

Limits of the gate

• Preauthorization is currency-agnostic. It cannot apply to some currencies only.
• It is one-directional. It does not affect payments going the other way.
• An account at or below its reserve can still receive a small XRP payment, up to the base reserve, so it cannot get stuck.
• Deposit Authorization does not stop the account from receiving funds through its own actions, such as cashing a check or placing an offer.

Not the same field. CredentialIDs is only for deposit authorization. To trade in a permissioned DEX, a transaction names the domain in DomainID. The ledger then checks that the account holds a credential the domain accepts.

Related: Permissioned Domains and DEX, Checks.