Merge pull request #1776 from XRPLF/accountset-1100-updates

Update docs for DisallowIncoming amendment.
2025-11-16 01:35:50 +00:00 · 2023-03-07 16:14:45 -08:00
parent ccc0e8891d 8dd2170ebd
commit 271bf0569c
8 changed files with 58 additions and 26 deletions
--- a/content/_snippets/rippled-api-links.md
+++ b/content/_snippets/rippled-api-links.md
@@ -196,6 +196,7 @@
  "DeletableAccounts",
  "DepositAuth",
  "DepositPreauth",
+  "DisallowIncoming",
  "EnforceInvariants",
  "Escrow",
  "ExpandedSignerList",
--- a/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md
+++ b/content/references/protocol-reference/ledger-data/ledger-object-types/accountroot.md
@@ -68,11 +68,15 @@ There are several options which can be either enabled or disabled for an account
 AccountRoot objects can have the following flag values:

 | Flag Name                         | Hex Value    | Decimal Value | Corresponding [AccountSet Flag](accountset.html#accountset-flags) | Description |
-|---------------------|--------------|---------------|--------------------|----|
+|-----------------------------------|--------------|-------------------|-----------------------------------|----|
 | `lsfAMM` :not_enabled:            | `0x02000000` | 33554432          | (None)                            | This account is an Automated Market Maker instance. :not_enabled: |
 | `lsfDefaultRipple`                | `0x00800000` | 8388608           | `asfDefaultRipple`                | Enable [rippling](rippling.html) on this addresses's trust lines by default. Required for issuing addresses; discouraged for others. |
 | `lsfDepositAuth`                  | `0x01000000` | 16777216          | `asfDepositAuth`                  | This account can only receive funds from transactions it sends, and from [preauthorized](depositauth.html#preauthorization) accounts. (It has [DepositAuth](depositauth.html) enabled.) |
 | `lsfDisableMaster`                | `0x00100000` | 1048576           | `asfDisableMaster`                | Disallows use of the master key to sign transactions for this account. |
+| `lsfDisallowIncomingCheck`        | `0x08000000` | 134217728         | `asfDisallowIncomingCheck`        | This account is blocking incoming checks. _(Added by the [DisallowIncoming amendment][].)_ |
+| `lsfDisallowIncomingNFTokenOffer` | `0x04000000` | 67108864          | `asfDisallowIncomingNFTokenOffer` | This account is blocking incoming NFToken offers. _(Added by the [DisallowIncoming amendment][].)_ |
+| `lsfDisallowIncomingPayChan`      | `0x10000000` | 268435456         | `asfDisallowIncomingPayChan`      | This account is blocking incoming payment channels. _(Added by the [DisallowIncoming amendment][].)_ |
+| `lsfDisallowIncomingTrustline`    | `0x20000000` | 536870912         | `asfDisallowIncomingTrustline`    | This account is blocking incoming trust lines. _(Added by the [DisallowIncoming amendment][].)_ |
 | `lsfDisallowXRP`                  | `0x00080000` | 524288            | `asfDisallowXRP`                  | Client applications should not send XRP to this account. Not enforced by `rippled`. |
 | `lsfGlobalFreeze`                 | `0x00400000` | 4194304           | `asfGlobalFreeze`                 | All assets issued by this address are frozen. |
 | `lsfNoFreeze`                     | `0x00200000` | 2097152           | `asfNoFreeze`                     | This address cannot freeze trust lines connected to it. Once enabled, cannot be disabled. |
--- a/content/references/protocol-reference/transactions/transaction-types/accountset.md
+++ b/content/references/protocol-reference/transactions/transaction-types/accountset.md
@@ -40,7 +40,7 @@ An AccountSet transaction modifies the properties of an [account in the XRP Ledg
 | `NFTokenMinter`  | String           | Blob              | _(Optional)_ Another account that can [mint NFTokens for you](authorize-minter.html). _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
 | [`SetFlag`](#accountset-flags) | Number | UInt32        | _(Optional)_ Integer flag to enable for this account. |
 | [`TransferRate`](#transferrate) | Number | UInt32       | _(Optional)_ The fee to charge when users transfer this account's tokens, represented as billionths of a unit. Cannot be more than `2000000000` or less than `1000000000`, except for the special case `0` meaning no fee. |
-| [`TickSize`](ticksize.html) | Number | UInt8            | _(Optional)_ Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are `3` to `15` inclusive, or `0` to disable. _(Added by the [TickSize amendment][].)_ |
+| [`TickSize`](ticksize.html) | Number | UInt8            | _(Optional)_ Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are `3` to `15` inclusive, or `0` to disable. |
 | `WalletLocator`    | String           | Hash256           | _(Optional)_ An arbitrary 256-bit value. If specified, the value is stored as part of the account but has no inherent meaning or requirements. |
 | `WalletSize`       | Number           | UInt32            | _(Optional)_ Not used. This field is valid in AccountSet transactions but does nothing. |

@@ -72,19 +72,23 @@ All flags are disabled by default.
 The available AccountSet flags are:

 | Flag Name                         | Decimal Value | Corresponding Ledger Flag         | Description   |
-|:-------------------|:--------------|:--------------------------|:--------------|
+|:----------------------------------|:--------------|:----------------------------------|:--------------|
 | `asfAccountTxnID`                 | 5             | (None)                            | Track the ID of this account's most recent transaction. Required for [`AccountTxnID`](transaction-common-fields.html#accounttxnid) |
-| `asfAuthorizedNFTokenMinter`| 10         | (None)       | Enable to allow another account to mint non-fungible tokens (NFTokens) on this account's behalf. Specify the authorized account in the `NFTokenMinter` field of the [AccountRoot](accountroot.html) object. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
-| `asfDefaultRipple` | 8             | `lsfDefaultRipple`        | Enable [rippling](rippling.html) on this account's trust lines by default. [New in: rippled 0.27.3][] |
+| `asfAuthorizedNFTokenMinter`      | 10            | (None)                            | Enable to allow another account to mint non-fungible tokens (NFTokens) on this account's behalf. Specify the authorized account in the `NFTokenMinter` field of the [AccountRoot](accountroot.html) object. _(Added by the [NonFungibleTokensV1_1 amendment][].)_ |
+| `asfDefaultRipple`                | 8             | `lsfDefaultRipple`                | Enable [rippling](rippling.html) on this account's trust lines by default. |
 | `asfDepositAuth`                  | 9             | `lsfDepositAuth`                  | Enable [Deposit Authorization](depositauth.html) on this account. _(Added by the [DepositAuth amendment][].)_ |
 | `asfDisableMaster`                | 4             | `lsfDisableMaster`                | Disallow use of the master key pair. Can only be enabled if the account has configured another way to sign transactions, such as a [Regular Key](cryptographic-keys.html) or a [Signer List](multi-signing.html). |
+| `asfDisallowIncomingCheck`        | 13            | `lsfDisallowIncomingCheck`        | Block incoming checks to the account; enforced by `rippled`. _(Added by the [DisallowIncoming amendment][].)_ |
+| `asfDisallowIncomingNFTokenOffer` | 12            | `lsfDisallowIncomingNFTokenOffer` | Block incoming NFToken offers to the account; enforced by `rippled`. _(Added by the [DisallowIncoming amendment][].)_ |
+| `asfDisallowIncomingPayChan`      | 14            | `lsfDisallowIncomingPayChan`      | Block incoming payment channels to the account; enforced by `rippled`. _(Added by the [DisallowIncoming amendment][].)_ |
+| `asfDisallowIncomingTrustline`    | 15            | `lsfDisallowIncomingTrustline`    | Block incoming trust lines to the account; enforced by `rippled`. _(Added by the [DisallowIncoming amendment][].)_ |
 | `asfDisallowXRP`                  | 3             | `lsfDisallowXRP`                  | XRP should not be sent to this account. (Enforced by client applications, not by `rippled`) |
 | `asfGlobalFreeze`                 | 7             | `lsfGlobalFreeze`                 | [Freeze](freezes.html) all assets issued by this account. |
 | `asfNoFreeze`                     | 6             | `lsfNoFreeze`                     | Permanently give up the ability to [freeze individual trust lines or disable Global Freeze](freezes.html). This flag can never be disabled after being enabled. |
 | `asfRequireAuth`                  | 2             | `lsfRequireAuth`                  | Require authorization for users to hold balances issued by this address. Can only be enabled if the address has no trust lines connected to it. |
 | `asfRequireDest`                  | 1             | `lsfRequireDestTag`               | Require a destination tag to send transactions to this account. |

-To enable the `asfDisableMaster` or `asfNoFreeze` flags, you must [authorize the transaction](transaction-basics.html#authorizing-transactions) by signing it with the master key pair. You cannot use a regular key pair or a multi-signature. You can disable `asfDisableMaster` (that is, re-enable the master key pair) using a regular key pair or multi-signature. [New in: rippled 0.28.0][]
+To enable the `asfDisableMaster` or `asfNoFreeze` flags, you must [authorize the transaction](transaction-basics.html#authorizing-transactions) by signing it with the master key pair. You cannot use a regular key pair or a multi-signature. You can disable `asfDisableMaster` (that is, re-enable the master key pair) using a regular key pair or multi-signature.

 The following [Transaction flags](transaction-common-fields.html#flags-field) (`tf` flags), specific to the AccountSet transaction type, serve the same purpose. Due to limited space, some settings do not have associated `tf` flags, and new `tf` flags are not being added to the `AccountSet` transaction type. You can use a combination of `tf` and `asf` flags to enable multiple settings with a single transaction.

@@ -102,12 +106,23 @@ The following [Transaction flags](transaction-common-fields.html#flags-field) (`

 ### Blocking Incoming Transactions

+<!-- This concept info should be moved to another topic after the IA.v2 migration. -->
+
 Incoming transactions with unclear purposes may be an inconvenience for financial institutions, who would have to recognize when a customer made a mistake, and then potentially refund accounts or adjust balances depending on the mistake. The `asfRequireDest` and `asfDisallowXRP` flags are intended to protect users from accidentally sending funds in a way that is unclear about the reason the funds were sent.

 For example, a destination tag is typically used to identify which hosted balance should be credited when a financial institution receives a payment. If the destination tag is omitted, it may be unclear which account should be credited, creating a need for refunds, among other problems. By using the `asfRequireDest` tag, you can ensure that every incoming payment has a destination tag, which makes it harder for others to send you an ambiguous payment by accident.

 You can protect against unwanted incoming payments for non-XRP currencies by not creating trust lines in those currencies. Since XRP does not require trust, the `asfDisallowXRP` flag is used to discourage users from sending XRP to an account. However, this flag is not enforced in `rippled` because it could potentially cause accounts to become unusable. (If an account did not have enough XRP to send a transaction that disabled the flag, the account would be completely unusable.) Instead, client applications should disallow or discourage XRP payments to accounts with the `asfDisallowXRP` flag enabled.

+You also have the option to block all incoming checks, NFToken offers, payment channels, and trust lines, using these account flags:
+
+- `asfDisallowIncomingCheck`
+- `asfDisallowIncomingNFTOffer`
+- `asfDisallowIncomingPayChan`
+- `asfDisallowIncomingTrustline`
+
+If a destination account has these flags enabled, `rippled` won't create the corresponding object on the ledger and returns the error code `tecNO_PERMISSION`.
+
 ## TransferRate

 The `TransferRate` field specifies a fee to charge whenever counterparties transfer the currency you issue. See [Transfer Fees](transfer-fees.html) for more information.
--- a/content/references/protocol-reference/transactions/transaction-types/checkcreate.md
+++ b/content/references/protocol-reference/transactions/transaction-types/checkcreate.md
@@ -42,6 +42,7 @@ Create a Check object in the ledger, which is a deferred payment that can be cas

 ## Error Cases

+- If the `Destination` is blocking incoming checks, the transaction fails with the result code `tecNO_PERMISSION`. _(Added by the [DisallowIncoming amendment][].)_
 - If the `Destination` is the sender of the transaction, the transaction fails with the result code `temREDUNDANT`.
 - If the `Destination` [account](accounts.html) does not exist in the ledger, the transaction fails with the result code `tecNO_DST`.
 - If the `Destination` account has the `RequireDest` flag enabled but the transaction does not include a `DestinationTag` field, the transaction fails with the result code `tecDST_TAG_NEEDED`.
--- a/content/references/protocol-reference/transactions/transaction-types/nftokencreateoffer.md
+++ b/content/references/protocol-reference/transactions/transaction-types/nftokencreateoffer.md
@@ -65,6 +65,7 @@ Besides errors that can occur for all transactions, {{currentpage.name}} transac
 | `tecNO_ENTRY`                    | The `NFToken` is not owned by the expected account. |
 | `tecNO_ISSUER`                   | The issuer specified in the `Amount` field does not exist. |
 | `tecNO_LINE`                     | The `Amount` field is denominated in fungible tokens, but the `NFToken`'s issuer does not have a trust line for those tokens and the `NFToken` does not have the [`lsfTrustLine` flag](nftoken.html#nftoken-flags) enabled. |
+| `tecNO_PERMISSION`               | The `Destination` is blocking incoming NFToken offers. _(Added by the [DisallowIncoming amendment][].)_
 | `tecUNFUNDED_OFFER`              | For a buy offer, the sender does have the funds specified in the `Amount` field available. If the `Amount` is XRP, this could be due to the reserve requirement; if the `Amount` is denominated in fungible tokens, this could be because they are [frozen](freezes.html). |
 | `tefNFTOKEN_IS_NOT_TRANSFERABLE` | The `NFToken` has the [`lsfTransferable` flag](nftoken.html#nftoken-flags) disabled and this transaction would not transfer the `NFToken` to or from the issuer. |

--- a/content/references/protocol-reference/transactions/transaction-types/paymentchannelcreate.md
+++ b/content/references/protocol-reference/transactions/transaction-types/paymentchannelcreate.md
@@ -43,6 +43,9 @@ Create a unidirectional channel and fund it with XRP. The address sending this t
 | `CancelAfter`    | Number    | UInt32            | _(Optional)_ The time, in [seconds since the Ripple Epoch][], when this channel expires. Any transaction that would modify the channel after this time closes the channel without otherwise affecting it. This value is immutable; the channel can be closed earlier than this time but cannot remain open after this time. |
 | `DestinationTag` | Number    | UInt32            | _(Optional)_ Arbitrary tag to further specify the destination for this payment channel, such as a hosted recipient at the destination address. |

+If the `Destination` is blocking incoming NFToken offers, the transaction fails with result code `tecNO_Permission`. _(Added by the [DisallowIncoming amendment][].)_
+
+
 <!--{# common link defs #}-->
 {% include '_snippets/rippled-api-links.md' %}
 {% include '_snippets/tx-type-links.md' %}
--- a/content/references/protocol-reference/transactions/transaction-types/trustset.md
+++ b/content/references/protocol-reference/transactions/transaction-types/trustset.md
@@ -43,6 +43,8 @@ Create or modify a trust line linking two accounts.
 | `QualityIn`              | Number    | UInt32            | _(Optional)_ Value incoming balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of `0` is shorthand for treating balances at face value. |
 | `QualityOut`             | Number    | UInt32            | _(Optional)_ Value outgoing balances on this trust line at the ratio of this number per 1,000,000,000 units. A value of `0` is shorthand for treating balances at face value. |

+If the `LimitAmount.issuer` is blocking incoming trust lines, the transaction fails with result code `tecNO_Permission`. _(Added by the [DisallowIncoming amendment][].)_
+

 ## TrustSet Flags

--- a/dactyl-config.yml
+++ b/dactyl-config.yml
@@ -2531,6 +2531,7 @@ pages:
        targets:
            - en

+        # TODO: update translation
    -   md: references/protocol-reference/transactions/transaction-types/accountset.ja.md
        targets:
            - ja
@@ -2593,6 +2594,7 @@ pages:
        targets:
            - en

+        # TODO: update translation
    -   md: references/protocol-reference/transactions/transaction-types/checkcreate.ja.md
        targets:
            - ja
@@ -2657,6 +2659,7 @@ pages:
        targets:
            - en

+        # TODO: update translation
    -   md: references/protocol-reference/transactions/transaction-types/nftokencreateoffer.ja.md
        targets:
            - ja
@@ -2706,6 +2709,7 @@ pages:
        targets:
            - en

+        # TODO: update translation
    -   md: references/protocol-reference/transactions/transaction-types/paymentchannelcreate.ja.md
        targets:
            - ja
@@ -2746,6 +2750,7 @@ pages:
        targets:
            - en

+        # TODO: update translation
    -   md: references/protocol-reference/transactions/transaction-types/trustset.ja.md
        targets:
            - ja