diff --git a/docs/concepts/accounts/addresses.md b/docs/concepts/accounts/addresses.md index af7fd30d0a..33940a26a5 100644 --- a/docs/concepts/accounts/addresses.md +++ b/docs/concepts/accounts/addresses.md @@ -15,15 +15,15 @@ Creating a valid address is a strictly mathematical task starting with a key pai ## Special Addresses -Some addresses have special meaning, or historical uses, in the XRP Ledger. In many cases, these are "black hole" addresses, meaning the address is not derived from a known secret key. Since it is effectively impossible to guess a secret key from only an address, any XRP possessed by black hole addresses is lost forever. +Some addresses have special meaning, or historical uses, in the XRP Ledger. In many cases, these are blackhole addresses, meaning the address is not derived from a known secret key. Since it is effectively impossible to guess a secret key from only an address, any XRP possessed by blackhole addresses is lost forever. See [Blackholed Accounts](blackholed-accounts.md). -| Address | Name | Meaning | Black Hole? | +| Address | Name | Meaning | Blackhole? | |-------------------------------|------|---------|-------------| | `rrrrrrrrrrrrrrrrrrrrrhoLvTp` | ACCOUNT\_ZERO | An address that is the XRP Ledger's [base58][] encoding of the value `0`. In peer-to-peer communications, `rippled` uses this address as the issuer for XRP. | Yes | | `rrrrrrrrrrrrrrrrrrrrBZbvji` | ACCOUNT\_ONE | An address that is the XRP Ledger's [base58][] encoding of the value `1`. In the ledger, [RippleState entries](../../references/protocol/ledger-data/ledger-entry-types/ripplestate.md) use this address as a placeholder for the issuer of a trust line balance. | Yes | | `rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh` | The genesis account | When `rippled` starts a new genesis ledger from scratch (for example, in stand-alone mode), this account holds all the XRP. This address is generated from the seed value `masterpassphrase` which is [hard-coded](https://github.com/XRPLF/rippled/blob/70d5c624e8cf732a362335642b2f5125ce4b43c1/src/xrpld/app/ledger/Ledger.cpp#L184). | No | -| `rrrrrrrrrrrrrrrrrNAMEtxvNvQ` | Ripple Name reservation black-hole | In the past, Ripple asked users to send XRP to this account to reserve Ripple Names.| Yes | +| `rrrrrrrrrrrrrrrrrNAMEtxvNvQ` | Ripple Name reservation blackhole | In the past, Ripple asked users to send XRP to this account to reserve Ripple Names.| Yes | | `rrrrrrrrrrrrrrrrrrrn5RM1rHd` | NaN Address | Old JavaScript client libraries generated this address when encoding the value [NaN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN) using the XRP Ledger's [base58][] string encoding format. | Yes | diff --git a/docs/concepts/accounts/blackholed-accounts.md b/docs/concepts/accounts/blackholed-accounts.md new file mode 100644 index 0000000000..5cb94de6ef --- /dev/null +++ b/docs/concepts/accounts/blackholed-accounts.md @@ -0,0 +1,61 @@ +--- +seo: + description: A blackholed account is an XRP Ledger account that can never send transactions again because its signing authority has been permanently removed. +labels: + - Accounts +--- +# Blackholed Accounts + +A blackholed account is an account whose signing authority has been permanently and verifiably removed. Once an account is blackholed, no one can ever send transactions from it again. + +## Why Blackhole an Account + +Blackholing an account is an extreme measure that most account owners will never need to consider. Use cases include: +- **Proving a fixed token supply.** By blackholing an issuing account, the owner proves to users and token holders that the account can no longer mint additional tokens, change transfer fees, or freeze balances. +- **Decommissioning an account that can't be deleted.** If an account has [deletion blockers](deleting-accounts.md#deletion-blockers), it cannot be deleted. Blackholing permanently removes the account's signing authority, preventing further activity. Unlike deletion, the account remains on the ledger and its reserves stay locked. + +## Requirements + +To be considered blackholed, an account must meet all of the following conditions: +- The master key is disabled. +- The regular key is set to a known [blackhole address](addresses.md#special-addresses). +- The account has no [signer list](multi-signing.md). +- The account has no [delegates](permission-delegation.md). {% amendment-disclaimer name="PermissionDelegation" /%} + +## Checking Whether an Account Is Blackholed + +There is no cryptographic certificate of blackholing. You can only verify that an account meets the conditions above. + +To check, call the [account_info method][] and confirm all of the following: +1. The `lsfDisableMaster` flag is set. +2. The `RegularKey` field is set to a known [blackhole address](addresses.md#special-addresses) (either `rrrrrrrrrrrrrrrrrrrrrhoLvTp` for ACCOUNT_ZERO or `rrrrrrrrrrrrrrrrrrrrBZbvji` for ACCOUNT_ONE). +3. No [SignerList entry][] exists for the account, confirmed by calling the [account_objects method][]. +4. No [Delegate ledger entry][] exists for the account, confirmed by calling the [account_objects method][]. + +ACCOUNT_ZERO and ACCOUNT_ONE are considered known blackhole addresses because they are derived from the integers 0 and 1 instead of a private key. This makes it effectively impossible for anyone to produce a matching private key. + +If the regular key is set to an arbitrary address rather than a known blackhole address, there is no way to verify that no one holds the corresponding private key. + +{% admonition type="info" name="Note" %} +A blackholed account's transaction history will continue to show activity from other accounts using its tokens or completing transactions involving it. The blackholed account itself is not sending these transactions. +{% /admonition %} + +## Risks and Limitations + +Blackholing is irreversible. Before blackholing an account, be aware of the following: +- Any XRP held by the account is permanently lost and cannot be retrieved. +- The account cannot send any transactions after blackholing. Any misconfigured settings (such as transfer fees, freeze authority, or rippling) are permanently locked in. +- Existing ledger entries created before blackholing (such as open offers, escrows, payment channels, or checks) can still complete, meaning additional tokens could be issued or XRP could leave the account after blackholing. + +## See Also + +- **Concepts:** + - [Deleting Accounts](deleting-accounts.md) + - [Cryptographic Keys](cryptographic-keys.md) + - [Multi-Signing](multi-signing.md) + - [Special Addresses](addresses.md#special-addresses) +- **Tutorials:** + - [Disable Master Key Pair](../../tutorials/best-practices/key-management/disable-master-key-pair.md) + - [Assign a Regular Key Pair](../../tutorials/best-practices/key-management/assign-a-regular-key-pair.md) + +{% raw-partial file="/docs/_snippets/common-links.md" /%} \ No newline at end of file diff --git a/docs/concepts/accounts/index.md b/docs/concepts/accounts/index.md index 66067a5dc5..cdcb2b4f62 100644 --- a/docs/concepts/accounts/index.md +++ b/docs/concepts/accounts/index.md @@ -36,7 +36,7 @@ An account's core data is stored in an [AccountRoot](../../references/protocol/l There is not a dedicated "create account" transaction. The [Payment transaction][] automatically creates a new account if the payment sends enough XRP to a mathematically-valid address that does not already have an account. This is called _funding_ an account, and creates an [AccountRoot entry](../../references/protocol/ledger-data/ledger-entry-types/accountroot.md) in the ledger. No other transaction can create an account. -{% admonition type="warning" name="Caution" %}Funding an account **does not** give you any special privileges over that account. Whoever has the secret key corresponding to the account's address has full control over the account and all XRP it contains. For some addresses, it's possible that no one has the secret key, in which case the account is a [black hole](addresses.md#special-addresses) and the XRP is lost forever.{% /admonition %} +{% admonition type="warning" name="Caution" %}Funding an account **does not** give you any special privileges over that account. Whoever has the secret key corresponding to the account's address has full control over the account and all XRP it contains. For some addresses, it's possible that no one has the secret key, in which case the account is a [blackholed account](blackholed-accounts.md) and the XRP is lost forever.{% /admonition %} The typical way to get an account in the XRP Ledger is as follows: @@ -56,6 +56,7 @@ The typical way to get an account in the XRP Ledger is as follows: - [Reserves](reserves.md) - [Cryptographic Keys](cryptographic-keys.md) - [Issuing and Operational Addresses](account-types.md) + - [Blackholed Accounts](blackholed-accounts.md) - **References:** - [account_info method][] - [wallet_propose method][] diff --git a/docs/concepts/tokens/fungible-tokens/stablecoins/settings.md b/docs/concepts/tokens/fungible-tokens/stablecoins/settings.md index fcbd1354fd..99f952dce5 100644 --- a/docs/concepts/tokens/fungible-tokens/stablecoins/settings.md +++ b/docs/concepts/tokens/fungible-tokens/stablecoins/settings.md @@ -95,4 +95,4 @@ To create a fixed supply: 1. Create a distribution wallet with settings similar to your issuing wallet. 2. Set up a trust line between the issuing wallet and the distribution wallet. 3. Send all tokens from the issuing wallet to the distribution wallet. -4. Black hole the issuing account. +4. Blackhole the issuing account. diff --git a/docs/concepts/tokens/nfts/guaranteeing-a-fixed-supply.md b/docs/concepts/tokens/nfts/guaranteeing-a-fixed-supply.md index 8df6fb4324..32c188c1ed 100644 --- a/docs/concepts/tokens/nfts/guaranteeing-a-fixed-supply.md +++ b/docs/concepts/tokens/nfts/guaranteeing-a-fixed-supply.md @@ -2,7 +2,7 @@ html: nft-fixed-supply.html parent: non-fungible-tokens.html seo: - description: Use a new account to mint a fixed number of NFTs, then black hole the account. + description: Use a new account to mint a fixed number of NFTs, then blackhole the account. labels: - Non-fungible Tokens, NFTs --- @@ -16,8 +16,8 @@ To guarantee a fixed number of NFTs: 1. Use `AccountSet` to assign your operational wallet as an authorized minter for the issuer. See [Authorizing Another Account to Mint Your NFTs](authorizing-another-minter.md). 1. Use your operational account to mint the tokens using `NFTokenMint`. The operational wallet holds all of the tokens minted for the Issuer. See [Batch Minting](batch-minting.md). 1. Use `AccountSet` to remove your operational wallet as an authorized minter for the Issuer. -1. “Blackhole” the Issuer account. See [Disable Master Key Pair](../../../tutorials/best-practices/key-management/disable-master-key-pair.md). +1. Blackhole the Issuer account. See [Blackholed Accounts](../../accounts/blackholed-accounts.md) and [Disable Master Key Pair](../../../tutorials/best-practices/key-management/disable-master-key-pair.md). At this point, it is impossible for any new tokens to be minted with the issuer’s address as the issuing account. -{% admonition type="warning" name="Caution" %}Once you "blackhole" the account, no one, including you, receives transfer fees for future sales of the NFTs.{% /admonition %} +{% admonition type="warning" name="Caution" %}Once you blackhole the account, no one, including you, receives transfer fees for future sales of the NFTs.{% /admonition %} diff --git a/docs/references/protocol/ledger-data/ledger-header.md b/docs/references/protocol/ledger-data/ledger-header.md index 7aa023953b..104a4a1da9 100644 --- a/docs/references/protocol/ledger-data/ledger-header.md +++ b/docs/references/protocol/ledger-data/ledger-header.md @@ -22,7 +22,7 @@ Every [ledger version](../../../concepts/ledgers/index.md) has a unique header t | `close_time_resolution` | Number | Uint8 | An integer in the range \[2,120\] indicating the maximum number of seconds by which the `close_time` could be rounded. | | `closed` | Boolean | Boolean | If `true`, this ledger version is no longer accepting new transactions. (However, unless this ledger version is validated, it might be replaced by a different ledger version with a different set of transactions.) | | `parent_hash` | String | UInt256 | The `ledger_hash` value of the previous ledger version that is the direct predecessor of this one. If there are different versions of the previous ledger index, this indicates from which one the ledger was derived. | -| `total_coins` | String | UInt64 | The total number of [drops of XRP][] owned by accounts in the ledger. This omits XRP that has been destroyed by transaction fees. The actual amount of XRP in circulation is lower because some accounts are "black holes" whose keys are not known by anyone. | +| `total_coins` | String | UInt64 | The total number of [drops of XRP][] owned by accounts in the ledger. This omits XRP that has been destroyed by transaction fees. The actual amount of XRP in circulation is lower because some accounts are [blackholes](../../../concepts/accounts/blackholed-accounts.md) whose keys are not known by anyone. | | `transaction_hash` | String | UInt256 | The [SHA-512Half][] of the transactions included in this ledger. | diff --git a/docs/tutorials/best-practices/key-management/disable-master-key-pair.md b/docs/tutorials/best-practices/key-management/disable-master-key-pair.md index a0f918f1a1..97e16b9c01 100644 --- a/docs/tutorials/best-practices/key-management/disable-master-key-pair.md +++ b/docs/tutorials/best-practices/key-management/disable-master-key-pair.md @@ -83,7 +83,7 @@ Before you can disable the master key pair, your account must have another way o {% /tab %} {% /tabs %} -{% admonition type="success" name="Tip" %}If your goal is to make the account a [black hole](/docs/concepts/accounts/addresses#special-addresses) that cannot send transactions at all, you still need to set a regular key. Instead of generating a key pair, use a known black hole address such as **rrrrrrrrrrrrrrrrrrrrrhoLvTp**.{% /admonition %} +{% admonition type="success" name="Tip" %}If your goal is to make the account a [blackhole](/docs/concepts/accounts/blackholed-accounts) that cannot send transactions at all, you still need to set a regular key. Instead of generating a key pair, use a known blackhole address such as **rrrrrrrrrrrrrrrrrrrrrhoLvTp**.{% /admonition %} ### 4. Disable the master key pair diff --git a/docs/use-cases/tokenization/stablecoin-issuer.md b/docs/use-cases/tokenization/stablecoin-issuer.md index de6ad3edfa..89418599cc 100644 --- a/docs/use-cases/tokenization/stablecoin-issuer.md +++ b/docs/use-cases/tokenization/stablecoin-issuer.md @@ -179,11 +179,11 @@ See [Partial Payments](../../concepts/payment-types/partial-payments.md). One way to manage the value of a token is to destroy, or _burn_ tokens, which reduces the number of tokens in circulation. On the XRP Ledger, fungible tokens are automatically "burned" when they are sent to the issuing address. However, the issuer can freely create more tokens. -To ensure a limited supply, you can "black hole" the issuer after issuing tokens, by setting its regular key to an address like `rrrrrrrrrrrrrrrrrrrrrhoLvTp` for which no one knows the private key, and disabling the master key pair. +To ensure a limited supply, you can blackhole the issuer after issuing tokens, by setting its regular key to an address like `rrrrrrrrrrrrrrrrrrrrrhoLvTp` for which no one knows the private key, and disabling the master key pair. -{% admonition type="danger" name="Warning" %}A black hole account has no way to send transactions of any kind, so you cannot update any settings or do any maintenance on the account afterwards!{% /admonition %} +{% admonition type="danger" name="Warning" %}A blackhole account has no way to send transactions of any kind, so you cannot update any settings or do any maintenance on the account afterwards!{% /admonition %} -See [Disable Master Key Pair](../../tutorials/best-practices/key-management/disable-master-key-pair.md). +See [Blackholed Accounts](../../concepts/accounts/blackholed-accounts.md) and [Disable Master Key Pair](../../tutorials/best-practices/key-management/disable-master-key-pair.md). ### Reliable Transaction Submission diff --git a/resources/contribute-documentation/index.md b/resources/contribute-documentation/index.md index 12c60c4ad6..2402633300 100644 --- a/resources/contribute-documentation/index.md +++ b/resources/contribute-documentation/index.md @@ -141,6 +141,7 @@ Use the following words and phrases as described: | Term | Terms to Avoid | Notes | |-------------------|----------------|-------| | API, APIs | API's, RPC | Application Programming Interface, a set of functions and definitions for software to connect to other software. | +| blackhole, blackholed, blackholing | black hole, black-hole | An account is blackholed when its signing authority has been permanently and verifiably removed, so that no one can ever send transactions from it again. Always one word. | | core server, core XRP Ledger server | `rippled` | The `rippled` name is probably going to be retired in the near future, so it's better to refer to it by the more generic name. When necessary, refer to `rippled` in all lowercase and code font. (It's pronounced "ripple dee", and the "d" stands for "daemon" per UNIX tradition.) | financial institution | bank, FI, PSP (payment services provider) | This term encompasses a wider range of businesses than just _bank_ or other terms and does not rely on an understanding of industry jargon. | | ledger entry | ledger object, node | A single object inside the state data of the XRP Ledger. The term _ledger object_ could refer to one of these or to the whole ledger. The term _node_ was sometimes used for this case because the ledger's state data can be envisioned as a graph, but this is confusing because _node_ has other uses. | diff --git a/resources/known-amendments.md b/resources/known-amendments.md index 3c67d20c47..784e585535 100644 --- a/resources/known-amendments.md +++ b/resources/known-amendments.md @@ -1042,7 +1042,7 @@ Adds flag checks for `CredentialCreate`, `CredentialAccept`, `CredentialDelete`, Fixes a bug where accounts can set their regular key pair to match their master key pair, but cannot send transactions signed by the key if the master key is disabled. -Without this fix, a user can unintentionally "black hole" their account by setting the regular key to match the master key, then disabling the master key. The network rejects transactions signed with the both-master-and-regular key pair because the code interprets them as being signed with the disabled master key before it recognizes that they are signed by the currently-enabled regular key. +Without this fix, a user can unintentionally [blackhole](../docs/concepts/accounts/blackholed-accounts.md) their account by setting the regular key to match the master key, then disabling the master key. The network rejects transactions signed with the both-master-and-regular key pair because the code interprets them as being signed with the disabled master key before it recognizes that they are signed by the currently-enabled regular key. With this amendment enabled, a SetRegularKey transaction cannot set the regular key to match the master key; such a transaction results in the transaction code `temBAD_REGKEY`. Additionally, this amendment changes the signature verification code so that accounts which _already_ have their regular key set to match their master key can send transactions successfully using the key pair. diff --git a/sidebars.yaml b/sidebars.yaml index 77def64bbc..5ca14b2bc5 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -164,6 +164,7 @@ - page: docs/concepts/accounts/account-types.md - page: docs/concepts/accounts/configuring-accounts.md - page: docs/concepts/accounts/deleting-accounts.md + - page: docs/concepts/accounts/blackholed-accounts.md - page: docs/concepts/accounts/reserves.md - page: docs/concepts/accounts/addresses.md - page: docs/concepts/accounts/cryptographic-keys.md