Deposit Authorization

(Added by the DepositAuth amendment.)

Deposit Authorization is an optional feature of an account in the XAG Ledger. With Deposit Authorization enabled, transactions cannot send value of any kind to the account unless the sender of those transactions is the account itself. This includes transfers of XAG and issued currencies.

By default, new accounts have DepositAuth disabled.


Financial services regulations and licenses may require that a business or entity must know the sender of all transactions it receives. This presents a challenge on a decentralized system like the XAG Ledger where participants are identified by pseudonyms which can be freely generated and the default behavior is for any address to be able to pay any other.

The Deposit Authorization flag introduces an option for those using the XAG Ledger to comply with such regulations without changing the fundamental nature of the decentralized ledger. With Deposit Authorization enabled, an account can only receive funds it explicitly approves by sending a transaction. The owner of an account using Deposit Authorization can perform the due diligence necessary to identify the sender of any funds before sending the transaction that causes the account to receive the money.

To receive money from Payment transactions when you have Deposit Authorization enabled, you must preauthorize the senders of those Payments. (Added by the DepositPreauth amendment.)

To get the full effect of Deposit Authorization, Ripple recommends also doing the following:

  • Always maintain an XAG balance higher than the minimum reserve requirement.
  • Keep the DefaultRipple flag in its default (disabled) state. Do not enable rippling on any trust lines. When sending TrustSet transactions, always use the tfSetNoRipple flag.
  • Do not place Offers. It is impossible to know in advance which matching offers will be consumed to execute such a trade.

Precise Semantics

An account with Deposit Authorization enabled:

  • Cannot be the destination of Payment transactions, with the following exceptions:
    • If the destination has preauthorized the sender of the Payment. (Added by the DepositPreauth amendment)
    • If the account's XAG balance is equal to or below the minimum account reserve requirement, it can be the destination of an XAG Payment whose Amount is equal or less than the minimum account reserve (currently 20 XAG). This is to prevent an account from becoming "stuck" by being unable to send transactions but also unable to receive XAG. The account's owner reserve does not matter for this case.
  • The destination of the EscrowFinish transaction has preauthorized the sender of the EscrowFinish. (Added by the DepositPreauth amendment)
  • Can receive XAG or issued currencies by sending a CheckCash transaction. (Added by the Checks amendment.)
  • Can receive XAG or issued currencies by sending OfferCreate transactions.
    • If the account sends an OfferCreate transaction that is not fully executed immediately, it can receive the remainder of the ordered XAG or issued currency later when the offer is consumed by other accounts' Payment and OfferCreate transactions.
  • If the account has created any trust lines without the NoRipple flag enabled, or has enabled the DefaultRipple flag and issued any currency, the account can receive the issued currencies of those trust lines in Payment transactions as a result of rippling. It cannot be the destination of those transactions.
  • In general, an account in the XAG Ledger cannot receive any non-XAG currencies in the XAG Ledger as long as all of the following are true. (This rule is not specific to the DepositAuth flag.)
    • The account has not created any trust lines with a nonzero limit.
    • The account has not issued currency on trust lines created by others
    • The account has not placed any offers.
  • The following table summarizes whether a transaction type can deposit money with DepositAuth enabled or disabled:

      DepositAuth Disabled   DepositAuth Enabled
    Transaction Type Sent by DestinationSent by Others   Sent by DestinationSent by OthersSent by Preauthorized Others
    AccountSet (This transaction type never sends money.)
    OfferCancel This transaction type never sends money.
    OfferCreate OK Only if account previously created a matching offer   OK Only if account previously created a matching offer Only if account previously created a matching offer
    (If account has more than the minimum XAG reserve, enables NoRipple on all trust lines, and places no offers)
    Cross-currency only OK   Cross-currency only1 No Permission OK
    (If account XAG balance is below the minimum XAG reserve)
    Cross-currency only OK   Cross-currency only1 XAG payments up to the minimum reserve OK
    (If account has any trust lines with NoRipple disabled)
    Cross-currency only OK   Cross-currency only1 Balance changes from rippling OK
    (If account has placed offers)
    Cross-currency only OK   Cross-currency only1 Balance changes from executing offers OK
    PaymentChannelClaim OK OK   OK No Permission OK
    SetRegularKey (This transaction type never sends money.)
    SignerListSet (This transaction type never sends money.)
    TrustSet (This transaction type never sends money.)

    1: The DepositPreauth amendment fixes a bug in DepositAuth which causes cross-currency payments to oneself to fail if the account requires deposit authorization. If the DepositPreauth amendment is not enabled, these cases result in "No Permission" instead.

    Enabling or Disabling Deposit Authorization

    An account can enable deposit authorization by sending an AccountSet transaction with the SetFlag field set to the asfDepositAuth value (9). The account can disable deposit authorization by sending an AccountSet transaction with the ClearFlag field set to the asfDepositAuth value (9). For more information on AccountSet flags, see AccountSet flags.

    Checking Whether an Account Has DepositAuth Enabled

    To see whether an account has Deposit Authorization enabled, use the account_info method to look up the account. Compare the value of the Flags field (in the result.account_data object) with the bitwise flags defined for an AccountRoot ledger object.

    If the result of the Flags value bitwise-AND the lsfDepositAuth flag value (0x01000000) is nonzero, then the account has DepositAuth enabled. If the result is zero, then the account has DepositAuth disabled.


    (Added by the DepositPreauth amendment.)

    Accounts with DepositAuth enabled can preauthorize certain senders, to allow payments from those senders to succeed even with DepositAuth enabled. This allows specific senders to send funds directly without the receiver taking action on each transaction individually. Preauthorization is not required to use DepositAuth, but can make certain operations more convenient.

    Preauthorization is currency-agnostic. You cannot preauthorize accounts for specific currencies only.

    To preauthorize a particular sender, send a DepositPreauth transaction with the address of another account to preauthorize in the Authorize field. To revoke preauthorization, provide the other account's address in the Unauthorize field instead. Specify your own address in the Account field as usual. You can preauthorize or unauthorize accounts even if you do not currently have DepositAuth enabled; the preauthorization status you set for other accounts is saved, but has no effect unless you enable DepositAuth. An account cannot preauthorize itself. Preauthorizations are one-directional, and have no effect on payments going the opposite direction.

    Preauthorizing another account adds a DepositPreauth object to the ledger, which increases the owner reserve of the account providing the authorization. If the account revokes this preauthorization, doing so removes the object and the reserve decreases accordingly.

    After the DepositPreauth transaction has been processed, the authorized account can send funds to your account, even if you have DepositAuth enabled, using any of the following transaction types:

    Preauthorization has no effect on the other ways to send money to an account with DepositAuth enabled. See Precise Semantics for the exact rules.

    Checking for Authorization

    You can use the deposit_authorized method to see if an account is authorized to deposit to another account. This method checks two things:

    • Whether the destination account requires Deposit Authorization. (If it does not require authorization, then all source accounts are considered authorized.)
    • Whether the source account is preauthorized to send money to the destination.

    See Also

    • The DepositPreauth transaction reference.
    • The DepositPreauth ledger object type.
    • The deposit_authorized method of the rippled API.
    • The Authorized Trust Lines feature (RequireAuth flag) limits which counterparties can hold non-XAG currencies issued by an account.
    • The DisallowXAG flag indicates that an account should not receive XAG. This is a softer protection than Deposit Authorization, and is not enforced by the XAG Ledger. (Client applications should honor this flag or at least warn about it.)
    • The RequireDest flag indicates that an account can only receive currency amounts if the sending transaction specifies a Destination Tag. This protects users from forgetting to indicate the purpose of a payment, but does not protect recipients from unknown senders, who can make up arbitrary destination tags.
    • Partial Payments provide a way for accounts to return unwanted payments while subtracting transfer fees and exchange rates from the amount delivered instead of adding them to the amount sent.