From 3130cc229fef560ae7c2e71549d09af7dd70d185 Mon Sep 17 00:00:00 2001 From: ddawson Date: Fri, 18 Nov 2022 14:36:22 -0800 Subject: [PATCH] tokens and accounts --- content/concepts/accounts/account-creating.md | 7 ++ content/concepts/accounts/account-deleting.md | 7 ++ .../concepts/accounts/account-structure.md | 7 ++ content/concepts/accounts/account-types.md | 12 +- content/concepts/accounts/accounts.md | 18 --- content/concepts/accounts/addresses.md | 11 +- content/concepts/accounts/balances.md | 3 - .../concepts/accounts/cryptographic-keys.md | 21 ++-- .../accounts/deposit-authorization.md | 9 +- content/concepts/accounts/history.md | 3 - content/concepts/accounts/reserves.md | 7 ++ content/concepts/accounts/sequence.md | 3 - .../concepts/tokens/authorized-trust-lines.md | 7 ++ .../common-misunderstandings-about-freezes.md | 7 ++ content/concepts/tokens/freezing-tokens.md | 7 ++ content/concepts/tokens/fungible.md | 3 - .../concepts/tokens/nftoken-batch-minting.md | 9 +- .../tokens/non-fungible-token-transfers.md | 8 +- content/concepts/tokens/non-fungible.md | 14 ++- content/concepts/tokens/paths.md | 15 ++- content/concepts/tokens/rippling.md | 13 +- content/concepts/tokens/token-types.md | 7 ++ dactyl-config.yml | 115 +++++++++++++++++- 23 files changed, 251 insertions(+), 62 deletions(-) delete mode 100644 content/concepts/accounts/balances.md delete mode 100644 content/concepts/accounts/history.md delete mode 100644 content/concepts/accounts/sequence.md delete mode 100644 content/concepts/tokens/fungible.md diff --git a/content/concepts/accounts/account-creating.md b/content/concepts/accounts/account-creating.md index 83d93dc5fe..3c11ccbd04 100644 --- a/content/concepts/accounts/account-creating.md +++ b/content/concepts/accounts/account-creating.md @@ -1,3 +1,10 @@ +--- +html: account-creating.html +parent: accounts.html +blurb: Create an account by sending a minimum reserve amount to a valid address. +labels: + - Accounts +--- # Creating Accounts There is not a dedicated "create account" transaction. The `Payment` transaction automatically creates a new account if a payment sends XRP equal to or greater than the account reserve to a mathematically valid address that does not already have an account. This is called _funding_ an account, and creates an AccountRoot object in the ledger. No other transaction can create an account. diff --git a/content/concepts/accounts/account-deleting.md b/content/concepts/accounts/account-deleting.md index a314fbb1ec..deaee530b3 100644 --- a/content/concepts/accounts/account-deleting.md +++ b/content/concepts/accounts/account-deleting.md @@ -1,3 +1,10 @@ +--- +html: account-deleting.html +parent: accounts.html +blurb: Delete an account by fulfilling several requirements. +labels: + - Accounts +--- # Deleting Accounts The DeletableAccounts amendment (enabled 2020-05-08) made it possible to delete accounts. diff --git a/content/concepts/accounts/account-structure.md b/content/concepts/accounts/account-structure.md index 1375a60186..6c44033288 100644 --- a/content/concepts/accounts/account-structure.md +++ b/content/concepts/accounts/account-structure.md @@ -1,3 +1,10 @@ +--- +html: account-structure.html +parent: accounts.html +blurb: The core elements of an account. +labels: + - Accounts +--- # Account Structure The core elements of an account are: diff --git a/content/concepts/accounts/account-types.md b/content/concepts/accounts/account-types.md index c0827a07c9..185fbfe54b 100644 --- a/content/concepts/accounts/account-types.md +++ b/content/concepts/accounts/account-types.md @@ -1,3 +1,10 @@ +--- +html: account-types.html +parent: accounts.html +blurb: Common account types include issuing accounts, standby accounts, and operational accounts. +labels: + - Accounts +--- # Account Types In the XRP Ledger, financial institutions typically use multiple XRP Ledger accounts to minimize the risk associated with a compromised secret key. The industry standard is to separate roles as follows: @@ -48,9 +55,8 @@ If a standby account is compromised, the consequences are like an operational ac When a token issuer follows this separation of roles, funds tend to flow in specific directions, as in the following diagram: - + +{{ include_svg("img/issued-currency-funds-flow.svg", "Diagram: Funds flow from the issuing account to standby accounts, to operational accounts, to customer and partner accounts, and finally back to the issuing account.")}} The issuing account creates tokens by sending payments to standby accounts. These tokens have negative value from the perspective of the issuing account, since they (often) represent obligations. The same tokens have positive value from other perspectives, including from the perspective of a standby account. diff --git a/content/concepts/accounts/accounts.md b/content/concepts/accounts/accounts.md index 1b866c6813..21fa94d8be 100644 --- a/content/concepts/accounts/accounts.md +++ b/content/concepts/accounts/accounts.md @@ -8,21 +8,3 @@ labels: # Accounts An "Account" in the XRP Ledger represents a holder of XRP and a sender of transactions. - -## Account Structure - -The core elements of an account are: - -- An identifying **address**, such as `rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn`. -- An **XRP balance**. Some of this XRP is set aside for the account reserve. -- A **sequence number**, which helps make sure any transactions this account sends are applied in the correct order and only once. To execute a transaction, the transaction's sequence number and its sender's sequence number must match. Then, as part of applying the transaction, the account's sequence number increases by 1. -- A **history of transactions** that affected this account and its balances. -- One or more ways to authorize transactions, possibly including: - - A master key pair intrinsic to the account. (This can be disabled, but not changed.) - - A "regular" key pair that can be rotated. - - A signer list for multi-signing. (Stored separately from the account's core data.) - -In the ledger's data tree, an account's core data is stored in the AccountRoot ledger object type. An account can also be the owner (or partial owner) of several other types of data. - -**Tip:** An "Account" in the XRP Ledger is somewhere between the financial usage (like "bank account") and the computing usage (like "UNIX account"). Non-XRP currencies and assets are not stored in an XRP Ledger Account itself; each such asset is stored in an accounting relationship called a "Trust Line" that connects two parties. - diff --git a/content/concepts/accounts/addresses.md b/content/concepts/accounts/addresses.md index 41d1b786cc..042dc53da8 100644 --- a/content/concepts/accounts/addresses.md +++ b/content/concepts/accounts/addresses.md @@ -1,4 +1,11 @@ -## Addresses +--- +html: addresses.html +parent: accounts.html +blurb: Accounts in the XRP Ledger are identified by an address in the XRP Ledger's base58 format. +labels: + - Accounts +--- +# Addresses Accounts in the XRP Ledger are identified by an address in the XRP Ledger's base58 format. The address is derived from the account's master [public key](https://en.wikipedia.org/wiki/Public-key_cryptography), which is in turn derived from a secret key. An address is represented as a string in JSON and has the following characteristics: @@ -13,7 +20,7 @@ Accounts in the XRP Ledger are identified by an address in the XRP Ledger's base > The XRP Ledger protocol only supports "classic" addresses natively, but many client libraries support X-addresses too. -For more information, see [Accounts](accounts.md). +For more information, see [Accounts](accounts.html). Any valid address can become an account in the XRP Ledger by being funded. You can also use an address that has not been funded to represent a regular key or a member of a signer list. Only a funded account can be the sender of a transaction. diff --git a/content/concepts/accounts/balances.md b/content/concepts/accounts/balances.md deleted file mode 100644 index 19e6c9db4e..0000000000 --- a/content/concepts/accounts/balances.md +++ /dev/null @@ -1,3 +0,0 @@ -# Balances - -Placeholder for details of the account balances. \ No newline at end of file diff --git a/content/concepts/accounts/cryptographic-keys.md b/content/concepts/accounts/cryptographic-keys.md index 492abe4159..c2a87f01eb 100644 --- a/content/concepts/accounts/cryptographic-keys.md +++ b/content/concepts/accounts/cryptographic-keys.md @@ -1,3 +1,10 @@ +--- +html: cryptographic-keys.html +parent: accounts.html +blurb: To make a digital signature, you use a cryptographic key pair associated with the transaction's sending account. +labels: + - Accounts +--- # Cryptographic Keys In the XRP Ledger, a digital signature _authorizes_ a [transaction](../transactions/transactions.md) to do a specific set of actions. Only signed transactions can be submitted to the network and included in a validated ledger. @@ -8,7 +15,7 @@ To make a digital signature, you use a cryptographic key pair associated with th ## Generating Keys -Many [client libraries](../../../references/client-libraries.md) and applications can generate a key pair suitable for use with the XRP Ledger. However, you should only use keypairs that were generated with devices and software you trust. Compromised applications can expose your secret to malicious users who can then send transactions from your account later. +Many [client libraries](client-libraries.html) and applications can generate a key pair suitable for use with the XRP Ledger. However, you should only use keypairs that were generated with devices and software you trust. Compromised applications can expose your secret to malicious users who can then send transactions from your account later. ## Key Components @@ -17,7 +24,7 @@ A cryptographic key pair is a **private key** and a **public key** that are conn When dealing with the XRP Ledger, you may also use some related values such as a passphrase, seed, account ID, or address. -{{ include_svg("../../../img/cryptographic-keys.svg", "Diagram: Passphrase → Seed → Private Key → Public Key → Account ID ←→ Address") }} +{{ include_svg("img/cryptographic-keys.svg", "Diagram: Passphrase → Seed → Private Key → Public Key → Account ID ←→ Address") }} _Figure: A simplified view of the relationship between cryptographic key values._ @@ -37,7 +44,7 @@ The passphrase is secret information, so you must protect it very carefully. Any ### Seed -A _seed_ value is a compact value that is used to derive the actual private and public keys for an account. In a `wallet_propose` method response, the `master_key`, `master_seed`, and `master_seed_hex` all represent the same seed value, in various formats. Any of these formats can be used to sign transactions in the rippled APIs and some [other XRP Ledger software](../xrpl/xrpl-ecosystem.md). Despite being prefixed with `master_`, the keys this seed represents are not necessarily the master keys for an account; you can use a key pair as a regular key or a member of a multi-signing list as well. +A _seed_ value is a compact value that is used to derive the actual private and public keys for an account. In a `wallet_propose` method response, the `master_key`, `master_seed`, and `master_seed_hex` all represent the same seed value, in various formats. Any of these formats can be used to sign transactions in the rippled APIs and some [other XRP Ledger software](xrpl-ecosystem.html). Despite being prefixed with `master_`, the keys this seed represents are not necessarily the master keys for an account; you can use a key pair as a regular key or a member of a multi-signing list as well. The seed value is secret information, so you must protect it very carefully. Anyone who has knows an address's seed value has effectively full control over that address. @@ -98,11 +105,11 @@ Keeping your master key pair offline means not putting the secret information (p - Disable the master key pair. -- Permanently give up the ability to [freeze](../tokens/freezing-tokens.md#no-freeze). +- Permanently give up the ability to [freeze](freezing-tokens.html#no-freeze). - Send a special key reset transaction with a transaction cost of 0 XRP. -A regular key or multi-signature can do anything else the same as the master key pair. Notably, after you have disabled the master key pair, you can re-enable it using a regular key pair or multi-signature. You can also [delete an account](account-deleting.md) if it meets the requirements for deletion. +A regular key or multi-signature can do anything else the same as the master key pair. Notably, after you have disabled the master key pair, you can re-enable it using a regular key pair or multi-signature. You can also [delete an account](account-deleting.html) if it meets the requirements for deletion. ## Regular Key Pair @@ -181,7 +188,7 @@ The key derivation processes described here are implemented in multiple places a ### secp256k1 Key Derivation [[Source]](https://github.com/ripple/rippled/blob/develop/src/ripple/protocol/impl/SecretKey.cpp "Source") -{{ include_svg("../../../img/key-derivation-secp256k1.svg", "Passphrase → Seed → Root Key Pair → Intermediate Key Pair → Master Key Pair") }} +{{ include_svg("img/key-derivation-secp256k1.svg", "Passphrase → Seed → Root Key Pair → Intermediate Key Pair → Master Key Pair") }} Key derivation for secp256k1 XRP Ledger account keys involves more steps than Ed25519 key derivation for a couple reasons: @@ -237,7 +244,7 @@ The steps to derive the XRP Ledger's secp256k1 account key pair from a seed valu 6. When serializing an account's public key to its base58 format, use the account public key prefix, `0x23`. - See [Address Encoding](addresses.md#address-encoding) for information and sample code to convert from an account's public key to its address. + See [Address Encoding](addresses.html#address-encoding) for information and sample code to convert from an account's public key to its address. -In both types of steps, each intermediate address gains and loses approximately equal value: either a balance ripples from a trust line to another trust line in the same currency, or they exchange currencies according to a previously-placed order. In some cases, the amounts gained and lost may not be exactly equivalent, due to [transfer fees](transfer-fees.md), trust line quality settings, or rounding. +In both types of steps, each intermediate address gains and loses approximately equal value: either a balance ripples from a trust line to another trust line in the same currency, or they exchange currencies according to a previously-placed order. In some cases, the amounts gained and lost may not be exactly equivalent, due to [transfer fees](transfer-fees.html), trust line quality settings, or rounding. {{ include_svg("img/paths-examples.svg", "Diagram of three example paths") }} @@ -38,11 +45,11 @@ Finding paths is a very challenging problem that changes slightly every few seco ## Implied Steps -By convention, several steps of a path are implied by the [fields of the Payment transaction](../transactions/payments/payment-types.md): specifically, the `Account` (sender), `Destination` (receiver), `Amount` (currency and amount to be delivered) and `SendMax` (currency and amount to be sent, if specified). The implied steps are as follows: +By convention, several steps of a path are implied by the [fields of the Payment transaction](payment-types.html): specifically, the `Account` (sender), `Destination` (receiver), `Amount` (currency and amount to be delivered) and `SendMax` (currency and amount to be sent, if specified). The implied steps are as follows: * The first step of a path is always implied to be the sender of the transaction, as defined by the transaction's `Account` field. * If the transaction includes a `SendMax` field with an `issuer` that is not the sender of the transaction, that issuer is implied to be the second step of the path. - * If `issuer` of the `SendMax` _is_ the sending address, then the path starts at the sending address, and may use any of that address's trust lines for the given currency code. See [special values for `SendMax` and `Amount`](../transactions/payments/payment-types.md) for details. + * If `issuer` of the `SendMax` _is_ the sending address, then the path starts at the sending address, and may use any of that address's trust lines for the given currency code. See [special values for `SendMax` and `Amount`](payment-types.html) for details. * If the `Amount` field of the transaction includes an `issuer` that is not the same as the `Destination` of the transaction, that issuer is implied to be the second-to-last step of the path. * Finally, last step of a path is always implied to be the receiver of a transaction, as defined by the transaction's `Destination` field. diff --git a/content/concepts/tokens/rippling.md b/content/concepts/tokens/rippling.md index 14ca7dccf0..f44c2fb2cd 100644 --- a/content/concepts/tokens/rippling.md +++ b/content/concepts/tokens/rippling.md @@ -1,10 +1,17 @@ +--- +html: rippling.html +parent: tokens.html +blurb: _Rippling__ occurs when more than one trust line is adjusted to make a payment. +labels: + - Tokens +--- # Rippling -In the XRP Ledger, "rippling" describes a process of atomic net settlement between multiple connected parties who have [trust lines](../transactions/trust-lines-and-issuing.md) for the same token. Rippling is essential, because it allows users who hold tokens to send those to each other with the issuer as a passive intermediary. In a sense, rippling is like a passive, two-way exchange order with no limit and a 1:1 exchange rate for two tokens with the same currency code but different issuers. +In the XRP Ledger, "rippling" describes a process of atomic net settlement between multiple connected parties who have [trust lines](trust-lines-and-issuing.html) for the same token. Rippling is essential, because it allows users who hold tokens to send those to each other with the issuer as a passive intermediary. In a sense, rippling is like a passive, two-way exchange order with no limit and a 1:1 exchange rate for two tokens with the same currency code but different issuers. -Rippling only occurs along the [paths](paths.md) of a payment. [Direct XRP-to-XRP payments](../transactions/payments/direct-xrp-payments.md) do not involve rippling. +Rippling only occurs along the [paths](paths.html) of a payment. [Direct XRP-to-XRP payments](direct-xrp-payments.html) do not involve rippling. For non-issuing accounts, rippling can be undesirable because it lets other users shift obligations between tokens with the same currency code but different issuers. The [No Ripple Flag](#the-no-ripple-flag) disables rippling by default when others open trust lines to your account, unless you enable rippling by default using the [Default Ripple flag](#the-default-ripple-flag). @@ -76,7 +83,7 @@ To enable the No Ripple flag, send a `TrustSet` transaction with the `tfSetNoRip In the case of two accounts that mutually trust each other, the No Ripple flag is tracked separately for each account. -Using the HTTP/WebSocket APIs or your preferred [client library](../../../references/client-libraries.md), look up trust lines with the `account_lines method`. For each trust line, the `no_ripple` field shows whether the current address has enabled the No Ripple flag on that trust line, and the `no_ripple_peer` field shows whether the counterparty has enabled the No Ripple flag. +Using the HTTP/WebSocket APIs or your preferred [client library](client-libraries.html), look up trust lines with the `account_lines method`. For each trust line, the `no_ripple` field shows whether the current address has enabled the No Ripple flag on that trust line, and the `no_ripple_peer` field shows whether the counterparty has enabled the No Ripple flag.