mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-23 13:15:49 +00:00
DepositAuth: concept & ref changes (draft)
This commit is contained in:
mDuo13
59
content/concept-depositauth.md
Normal file
59
content/concept-depositauth.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Deposit Authorization
|
||||
|
||||
_(Requires the [DepositAuth amendment](reference-amendments.html#depositauth).)_
|
||||
|
||||
Deposit Authorization is an optional feature of an [account](concept-accounts.html) in the XRP 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 XRP and issued currencies.
|
||||
|
||||
## Background
|
||||
|
||||
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 XRP 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 XRP Ledger to become compliant 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 it to receive the money.
|
||||
|
||||
Deposit Authorization is intended to be used with [Checks](reference-amendments.html#checks), [Escrow](concept-escrow.html), and [Payment Channels](reference-amendments.html#paychan). The "two-step" transaction model allows the sender to first authorize the sending of funds, then the destination to authorize the receipt of funds. Deposit Authorization cannot be used with [Payment transactions][] at present.
|
||||
|
||||
## Recommended Usage
|
||||
|
||||
To get the full effect of Deposit Authorization, Ripple recommends also doing the following:
|
||||
|
||||
- Always maintain an XRP balance higher than the minimum [reserve requirement](concept-reserves.html).
|
||||
- Keep the DefaultRipple flag in its default (disabled) state. Do not enable [rippling](concept-noripple.html) on any trust lines.
|
||||
- Do not place [Offers](reference-transaction-format.html#offercreate). 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 **one exception**:
|
||||
- If the account's XRP balance is equal to or below the minimum account [reserve requirement](concept-reserves.html), it can be the destination of a Payment whose `Amount` is equal or less than the minimum account reserve (currently 20 XRP). This is to prevent an account from becoming "stuck" by being unable to send transactions but also unable to receive XRP. The account's owner reserve does not matter for this case.
|
||||
- Can receive XRP from [PaymentChannelClaim transactions][] **only if** the sender of the PaymentChannelClaim transaction is the destination of the payment channel.
|
||||
- Can receive XRP from [EscrowFinish transactions][] **only if** the sender of the EscrowFinish transaction is the destination of the escrow.
|
||||
- **Can** receive XRP or issued currencies by sending a [CheckCash][] transaction. _(Requires the [Checks amendment](reference-amendments.html#checks).)_
|
||||
- **Can** receive XRP or issued currencies by sending [OfferCreate transactions][]. ***TODO: test this***
|
||||
- If the account sends an OfferCreate transaction that is not fully executed immediately, it **can** receive the remainder of the ordered XRP or issued currency later when the offer is consumed by other accounts' [Payment][] and [OfferCreate][] transactions. ***TODO: test this***
|
||||
- If the account has created any trust lines, or issued currency on trust lines created by other accounts, the account **can** receive the issued currencies of those trust lines in [Payment transactions][] as a result of [rippling](concept-noripple.html). It cannot be the destination of those transactions. ***TODO: test this***
|
||||
- If the account has not created any trust lines with a nonzero limit, and has not issued currency on trust lines created by others, it **cannot** receive any issued currencies in any transaction.
|
||||
|
||||
The following table summarizes whether a transaction type can deposit money with DepositAuth enabled or disabled:
|
||||
|
||||
{% include 'snippets/depositauth-semantics-table.html' %}
|
||||
|
||||
|
||||
## 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](reference-transaction-format.html#accountset-flags).
|
||||
|
||||
## Checking Whether an Account Has DepositAuth Enabled
|
||||
|
||||
To see whether an account has Deposit Authorization enabled, use the [`account_info` command](reference-rippled.html#account-info) to look up the account. Compare the value of the `Flags` field (in the `result.account_data` object) with the [boolean flags defined for an AccountRoot ledger object](reference-ledger-format.html#accountroot-flags).
|
||||
|
||||
If the result of the `Flags` value boolean-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.
|
||||
|
||||
## See Also
|
||||
|
||||
- The [Authorized Accounts](tutorial-gateway-guide.html#authorized-accounts) feature (`RequireAuth` flag) limits which counterparties can hold non-XRP currencies issued by an account.
|
||||
- The `DisallowXRP` flag indicates that an account should not receive XRP. This is a softer protection than Deposit Authorization, and is not enforced by the XRP 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](tutorial-gateway-guide.html#source-and-destination-tags). 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](concept-partial-payments.html) provide a way for accounts to return unwanted payments while subtracting [transfer fees](concept-transfer-fees.html) and exchange rates from the amount delivered instead of adding them to the amount sent.
|
||||
|
||||
{% include 'snippets/tx-type-links.md' %}
|
||||
@@ -52,7 +52,7 @@ AccountRoot objects can have the following flag values:
|
||||
|
||||
| Flag Name | Hex Value | Decimal Value | Description | Corresponding [AccountSet Flag](reference-transaction-format.html#accountset-flags) |
|
||||
|-----------|-----------|---------------|-------------|-------------------------------|
|
||||
| lsfPasswordSpent | 0x00010000 | 65536 | Indicates that the account has used its free SetRegularKey transaction. | (None) |
|
||||
| lsfPasswordSpent | 0x00010000 | 65536 | The account has used its free SetRegularKey transaction. | (None) |
|
||||
| lsfRequireDestTag | 0x00020000 | 131072 | Requires incoming payments to specify a Destination Tag. | asfRequireDest |
|
||||
| lsfRequireAuth | 0x00040000 | 262144 | This account must individually approve other users for those users to hold this account's issuances. | asfRequireAuth |
|
||||
| lsfDisallowXRP | 0x00080000 | 524288 | Client applications should not send XRP to this account. Not enforced by `rippled`. | asfDisallowXRP |
|
||||
@@ -60,6 +60,7 @@ AccountRoot objects can have the following flag values:
|
||||
| lsfNoFreeze | 0x00200000 | 2097152 | This address cannot freeze trust lines connected to it. Once enabled, cannot be disabled. | asfNoFreeze |
|
||||
| lsfGlobalFreeze | 0x00400000 | 4194304 | All assets issued by this address are frozen. | asfGlobalFreeze |
|
||||
| lsfDefaultRipple | 0x00800000 | 8388608 | Enable [rippling](concept-noripple.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. | asfDefaultRipple |
|
||||
| lsfDepositAuth | 0x01000000 | 16777216 | This account can only receive funds from transactions it sends. |
|
||||
|
||||
### AccountRoot ID Format
|
||||
|
||||
|
||||
@@ -89,6 +89,8 @@ When an account enables this flag, Payment transactions fail if the account is t
|
||||
|
||||
As an exception, accounts with `DepositAuth` enabled can receive Payment transactions for small amounts of XRP (equal or less than the minimum [account reserve](concept-reserves.html)) if their current XRP balance is below the account reserve.
|
||||
|
||||
Also fixes a bug in the EscrowCreate and PaymentChannelCreate transactions where they mistakenly enforced the DisallowXRP flag, which is meant to be a non-binding advisory flag. (By not enforcing DisallowXRP in the ledger itself an account can still receive the necessary XRP to meet its [account reserve](concept-reserves.html) and pay [transaction costs](concept-transaction-cost.html).)
|
||||
|
||||
**Caution:** This amendment is [in development](https://github.com/ripple/rippled/pull/2239) and is expected for `rippled` v0.90.0.
|
||||
|
||||
|
||||
|
||||
@@ -709,7 +709,7 @@ For the most part, transactions with `tec` codes take no action other than to de
|
||||
| `tecNO_LINE` | 135 | The `TakerPays` field of the [OfferCreate transaction][] specifies an asset whose issuer has `lsfRequireAuth` enabled, and the account making the offer does not have a trust line for that asset. (Normally, making an offer implicitly creates a trust line if necessary, but in this case it does not bother because you cannot hold the asset without authorization.) If the trust line exists, but is not authorized, `tecNO_AUTH` occurs instead. |
|
||||
| `tecNO_LINE_INSUF_RESERVE` | 126 | The transaction failed because the sending account does not have enough XRP to create a new trust line. (See: [Reserves](concept-reserves.html)) This error occurs when the counterparty does not have a trust line to this account for the same currency. (See `tecINSUF_RESERVE_LINE` for the other case.) |
|
||||
| `tecNO_LINE_REDUNDANT` | 127 | The transaction failed because it tried to set a trust line to its default state, but the trust line did not exist. |
|
||||
| `tecNO_PERMISSION` | 139 | The sender does not have permission to do this operation. For example, the [EscrowFinish transaction][] tried to release a held payment before its `FinishAfter` time, or someone tried to use [PaymentChannelFund][] on a channel the sender does not own. |
|
||||
| `tecNO_PERMISSION` | 139 | The sender does not have permission to do this operation. For example, the [EscrowFinish transaction][] tried to release a held payment before its `FinishAfter` time, someone tried to use [PaymentChannelFund][] on a channel the sender does not own, or a [Payment][] tried to deliver funds to an account with the "DepositAuth" flag enabled. |
|
||||
| `tecNO_REGULAR_KEY` | 131 | The [AccountSet transaction][] tried to disable the master key, but the account does not have another way to [authorize transactions](#authorizing-transactions). If [multi-signing](#multi-signing) is enabled, this code is deprecated and `tecNO_ALTERNATIVE_KEY` is used instead. |
|
||||
| `tecNO_TARGET` | 138 | The transaction referenced an Escrow or PayChannel ledger object that doesn't exist, either because it never existed or it has already been deleted. (For example, another [EscrowFinish transaction][] has already executed the held payment.) Alternatively, the destination account has `asfDisallowXRP` set so it cannot be the destination of this [PaymentChannelCreate][] or [EscrowCreate][] transaction. |
|
||||
| `tecOVERSIZE` | 145 | This transaction could not be processed, because the server created an excessively large amount of metadata when it tried to apply the transaction. [New in: rippled 0.29.0-hf1][] |
|
||||
|
||||
122
content/snippets/depositauth-semantics-table.html
Normal file
122
content/snippets/depositauth-semantics-table.html
Normal file
@@ -0,0 +1,122 @@
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>DepositAuth status:</th>
|
||||
<th colspan="2" class="depauth-status">Disabled</th>
|
||||
<th colspan="2" class="depauth-status">Enabled</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Transaction Type</th>
|
||||
<th>Sent by Destination</th><th>Sent by Others</th>
|
||||
<th>Sent by Destination</th><th>Sent by Others</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td class="depauth-txtype">AccountSet</td>
|
||||
<td colspan="4" class="depauth-na">(This transaction type never sends money.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">CheckCancel</td>
|
||||
<td colspan="4" class="depauth-na">(This transaction type never sends money.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">CheckCash</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-no">No Permission</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-no">No Permission</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">CheckCreate</td>
|
||||
<td colspan="4" class="depauth-na">(This transaction type never sends money.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">EscrowCancel</td>
|
||||
<td class="depauth-maybe" colspan="4">(Can return XRP from an expired escrow)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">EscrowCreate</td>
|
||||
<td colspan="4" class="depauth-na">(This transaction type can only debit XRP, not credit it.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">EscrowFinish</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-maybe">No Permission</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">OfferCancel</td>
|
||||
<td colspan="4" class="depauth-na">(This transaction type never sends money.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">OfferCreate</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-maybe">(Only if account previously created a matching offer)</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-maybe">(Only if account previously created a matching offer)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">Payment (if account has no trust lines or offers)</td>
|
||||
<td class="depauth-maybe">(Cross-currency payments only)</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-no">No Permission</td>
|
||||
<td class="depauth-no">No Permission</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">Payment (if account has trust lines or offers)</td>
|
||||
<td class="depauth-maybe">(Cross-currency payments only)</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-no">No Permission</td>
|
||||
<td class="depauth-maybe"><b>(TODO: Maybe By consuming offers or rippling?)</b></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">PaymentChannelClaim</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-ok">OK</td>
|
||||
<td class="depauth-no">No Permission</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">PaymentChannelCreate</td>
|
||||
<td colspan="4" class="depauth-na">(This transaction type can only debit XRP, not credit it.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">PaymentChannelFund</td>
|
||||
<td class="depauth-maybe" colspan="4">(Can return XRP when closing a channel created by self)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">SetRegularKey</td>
|
||||
<td colspan="4" class="depauth-na">(This transaction type never sends money.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">SignerListSet</td>
|
||||
<td colspan="4" class="depauth-na">(This transaction type never sends money.)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class="depauth-txtype">TrustSet</td>
|
||||
<td colspan="4" class="depauth-na">(This transaction type never sends money.)</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<style type="text/css">
|
||||
.depauth-txtype {
|
||||
font-weight: bold;
|
||||
}
|
||||
.depauth-status {
|
||||
text-align: center;
|
||||
}
|
||||
.depauth-na {
|
||||
background-color: #999;
|
||||
}
|
||||
.depauth-ok {
|
||||
background-color: #afa;
|
||||
}
|
||||
.depauth-no {
|
||||
background-color: #faa;
|
||||
}
|
||||
.depauth-maybe {
|
||||
background-color: #ffa;
|
||||
}
|
||||
</style>
|
||||
@@ -64,6 +64,7 @@ The available AccountSet flags are:
|
||||
| asfNoFreeze | 6 | lsfNoFreeze | Permanently give up the ability to [freeze individual trust lines or disable Global Freeze](concept-freeze.html). This flag can never be disabled after being enabled. |
|
||||
| asfGlobalFreeze | 7 | lsfGlobalFreeze | [Freeze](concept-freeze.html) all assets issued by this account. |
|
||||
| asfDefaultRipple | 8 | lsfDefaultRipple | Enable [rippling](concept-noripple.html) on this account's trust lines by default. [New in: rippled 0.27.3][] |
|
||||
| asfDepositAuth | 9 | lsfDepositAuth | Enable [Deposit Authorization](concept-depositauth.html) on this account. |
|
||||
|
||||
To enable the `asfDisableMaster` or `asfNoFreeze` flags, you must [authorize the transaction](#authorizing-transactions) by signing it with the master key. You cannot use a regular key or a multi-signature. [New in: rippled 0.28.0][]
|
||||
|
||||
|
||||
@@ -82,6 +82,7 @@ targets:
|
||||
"concept-money.html": https://ripple.com/build/money-xrp-ledger/
|
||||
"reference-currency.html": https://ripple.com/build/currency-format/
|
||||
"concept-demurrage.html": https://ripple.com/build/demurrage/
|
||||
# "concept-depositauth.html": https://ripple.com/build/depositauth/ #TODO: make this page on ripple.com
|
||||
image_subs:
|
||||
"img/funds_flow_diagram.png": https://cdn.ripple.com/wp-content/uploads/2016/03/funds_flow_diagram.png
|
||||
"img/e2g-01.png": https://ripple.com/wp-content/themes/ripple-beta/assets/img/e2g-01.png
|
||||
@@ -288,6 +289,12 @@ pages:
|
||||
- local
|
||||
- ripple.com
|
||||
|
||||
- md: concept-depositauth.md
|
||||
category: Features
|
||||
targets:
|
||||
- local
|
||||
- ripple.com
|
||||
|
||||
- md: concept-escrow.md
|
||||
category: Features
|
||||
targets:
|
||||
|
||||
Reference in New Issue
Block a user