diff --git a/docs/_snippets/common-links.md b/docs/_snippets/common-links.md index 2e2df23691..f5723f195f 100644 --- a/docs/_snippets/common-links.md +++ b/docs/_snippets/common-links.md @@ -192,6 +192,7 @@ [Payment]: /docs/references/protocol/transactions/types/payment.md [PermissionDelegation amendment]: /resources/known-amendments.md#permissiondelegation [PermissionedDEX amendment]: /resources/known-amendments.md#permissioneddex +[Permissioned DEXes]: /docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md [PermissionedDomainSet transaction]: /docs/references/protocol/transactions/types/permissioneddomainset.md [PermissionedDomainSetトランザクション]: /@l10n/ja/docs/references/protocol/transactions/types/permissioneddomainset.md [PermissionedDomains amendment]: /resources/known-amendments.md#permissioneddomains diff --git a/docs/concepts/accounts/permission-delegation.md b/docs/concepts/accounts/permission-delegation.md index d2181b16d3..61c4cf7db2 100644 --- a/docs/concepts/accounts/permission-delegation.md +++ b/docs/concepts/accounts/permission-delegation.md @@ -1,6 +1,6 @@ --- seo: - description: XRPL accounts can delegate both transaction permissions and granular permissions to other accounts. + description: Learn how XRPL Account Permission Delegation enables secure, granular control over your account transactions. Explore DelegateSet transactions for comprehensive permission and access management on the XRP Ledger. labels: - Accounts - Permissions @@ -13,14 +13,14 @@ Permission delegation is the function of granting various permissions to another _(Requires the [PermissionDelegation amendment][] {% not-enabled /%}.)_ -## Background +## Background: The Need for Permission Delegation Managing your [cryptographic keys](./cryptographic-keys.md) is one of the more challenging parts of using a blockchain. As part of a defense-in-depth strategy, a secure configuration should limit the damage that can occur if a secret key is compromised. One way to do this is to rotate keys regularly and to keep master keys off of computers that are always connected to the internet and serving user traffic. However, many use cases involve frequently and automatically signing transactions, which typically requires having secret keys on an internet-connected server. Permission Delegation can reduce this problem by granting very limited permissions to separate accounts that have their keys available online for day-to-day tasks. Meanwhile, the keys with full control over the account can be kept offline, so that you only use them for special tasks, like issuing tokens. This is especially helpful when using compliance features like [Authorized Trust Lines](../tokens/fungible-tokens/authorized-trust-lines.md) that require a stablecoin issuer to individually approve each user after meeting regulatory requirements like Know Your Customer rules. With a proper configuration, you can minimize the consequences of a delegate's keys being compromized. -## How It Works +## How Permission Delegation Works The account on whose behalf transactions are being sent is called the _delegator_. The account sending the transactions is called the _delegate_. @@ -39,7 +39,7 @@ The delegate can only send transactions that match the permissions it has. Permi For a complete list of transaction types that can or cannot be delegated as well as a list of granular permissions, see [Permission Values](/docs/references/protocol/data-types/permission-values.md). -### Limitations +### Limitations of Permission Delegation The main limiting factor on how many delegates you can have is that you must hold enough XRP to meet the [reserve requirement](./reserves.md). Each delegate's permissions are tracked with a [Delegate ledger entry][], which counts as one item towards the delegator's owner reserve. diff --git a/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md b/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md index 9ebbff4d4a..a45b2fc144 100644 --- a/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md +++ b/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md @@ -12,9 +12,11 @@ Permissioned DEXes are controlled environments for trading within the XRP Ledger There can be multiple permissioned DEXes within the XRP Ledger blockchain. Each one is uniquely associated with a permissioned domain, which acts as an allow-list for accessing that DEX. Trades placed within a permissioned DEX can only execute against other trades in the same permissioned DEX. Each permissioned DEX can have order books for any number of currency pairs, as needed. -## Background +## Background: The Need for Permissioned DEXes -The XRP Ledger has had a single, _open DEX_ since it launched. Anyone with an XRPL account can trade in this DEX, and the system automatically executes matching orders, also called offers, with no regard for who placed them. Orders also provide liquidity to cross-currency payments, which can potentially execute several trades as part of one atomic transaction. Since the system inherently knows nothing about the people and organizations behind the accounts, there is no certainty who the counterparties are for any given trade. However, economic sanctions and financial regulations often place strict rules against transacting with criminals, terrorists, or specific countries. Given these limitations, regulated financial institutions may not be willing to take the risk of trading in the open DEX. +The XRP Ledger has had a single, _open DEX_ since it launched. Anyone with an XRPL account can trade in this DEX, and the system automatically executes matching orders, also called offers, with no regard for who placed them. Orders also provide liquidity to cross-currency payments, which can potentially execute several trades as part of one atomic transaction. + +Since the system inherently knows nothing about the people and organizations behind the accounts, there is no certainty who the counterparties are for any given trade. However, economic sanctions and financial regulations often place strict rules against transacting with criminals, terrorists, or specific countries. Given these limitations, regulated financial institutions may not be willing to take the risk of trading in the open DEX. More background reading: @@ -23,7 +25,7 @@ More background reading: - [Permissioned Domains](./permissioned-domains.md) -## Roles +## Key Roles in a Permissioned DEX To use a permissioned DEX, parties with the following roles and responsibilities need to exist: @@ -38,13 +40,28 @@ It is possible for a single account to play more than one of these roles. For ex _Figure: A permissioned order book, linked to a permissioned domain. Owen is both the domain owner and the issuer of one of the domain's accepted credentials. Tracy is able to trade in the permissioned order book because she holds an appropriate credential issued by Owen._ -## Structure +## Understanding the Permissioned DEX Structure: Offer Types and Interaction -With the permissioned DEXes feature, a trade offer can be _open_, _permissioned_, or _hybrid_. An open offer uses the open DEX and can be matched by anyone else's open offer, hybrid offer, an [Automated Market Maker (AMM)](./automated-market-makers.md), or a combination of offers and an AMM. _Open offers_ are unchanged from how the XRPL's DEX works without permissioned DEXes. +With the permissioned DEXes feature, a trade offer can be _open_, _permissioned_, or _hybrid_. -A permissioned offer specifies a domain ID, and is only valid if a permissioned domain with the matching ID exists and the account placing the offer has access to that domain because they hold the correct credentials. Permissioned offers are placed into an order book for the given domain and currency pair, separate from the open DEX's order book for that currency pair. Permissioned offers can only execute by matching other permissioned offers that specify the same domain ID. [Cross-currency payments](../../payment-types/cross-currency-payments.md) can also specify a domain ID, in which case they are restricted to only consuming offers from the corresponding permissioned DEX. Trades in a permissioned DEX can still use [auto-bridging](./autobridging.md) as long as the necessary orders all exist in the same permissioned DEX. +### Open Offers -A hybrid offer specifies a domain ID and a flag marking it as hybrid. Like a permissioned offer, it is only valid if the specified permissioned domain exists and the account placing the offer has access to that domain. However, a hybrid offer can match offers in both the specified DEX and the open DEX. Hybrid offers are tracked in both the open DEX order book and the domain-specific order book for their currency pair, and can be consumed by matching offers from either. When placed, they preferentially match offers from the permissioned DEX. +An open offer uses the open DEX and can be matched by anyone else's open offer, hybrid offer, an [Automated Market Maker (AMM)](./automated-market-makers.md), or a combination of offers and an AMM. _Open offers_ are unchanged from how the XRPL's DEX works without permissioned DEXes. + +### Permissioned Offers + +A permissioned offer specifies a domain ID and is only valid if a permissioned domain with the matching ID exists and the account placing the offer has access to that domain because they hold the correct credentials. Permissioned offers are placed into an order book for the given domain and currency pair, separate from the open DEX's order book for that currency pair. + +Permissioned offers can only execute by matching other permissioned offers that specify the same domain ID. [Cross-currency payments](../../payment-types/cross-currency-payments.md) can also specify a domain ID, in which case they are restricted to only consuming offers from the corresponding permissioned DEX. Trades in a permissioned DEX can still use [auto-bridging](./autobridging.md) as long as the necessary orders all exist in the same permissioned DEX. + +### Hybrid Offers + +A hybrid offer specifies a domain ID and a flag marking it as hybrid. Like a permissioned offer, it is only valid if the specified permissioned domain exists and the account placing the offer has access to that domain. However, a hybrid offer can match offers in both the specified DEX and the open DEX. + +Hybrid offers are tracked in both the open DEX order book and the domain-specific order book for their currency pair, and can be consumed by matching offers from either. When placed, they preferentially match offers from the permissioned DEX. + + +### How Open, Hybrid, and Permissioned Offers Match In summary, see the following table summarizing what offers can match: @@ -54,7 +71,9 @@ In summary, see the following table summarizing what offers can match: | Hybrid | ✅ | ✅ | ✅ (same domain) | ✅ | | Permissioned | ❌ | ❌ | ✅ (same domain) | ❌ | -There is no single ledger entry to represent a given permissioned DEX: it implicitly exists as all the order books with the same domain ID. Order books with a given domain ID are implicitly created when valid offers are placed using that domain ID, and those order books are automatically deleted when they are empty. A single transaction can use multiple order books with the same domain ID—in other words, different currency pairs in the same permissioned DEX—either as part of a longer cross-currency payment or through auto-bridging. A hybrid offer can match a mix of permissioned and open offers, but a transaction cannot use multiple different domains. +There is no single ledger entry to represent a given permissioned DEX: it implicitly exists as all the order books with the same domain ID. Order books with a given domain ID are created when valid offers are placed using that domain ID, and those order books are automatically deleted when they are empty. + +A single transaction can use multiple order books with the same domain ID—in other words, different currency pairs in the same permissioned DEX—either as part of a longer [cross-currency payment](../../payment-types/cross-currency-payments.md) or through auto-bridging. A hybrid offer can match a mix of permissioned and open offers, but a transaction cannot use multiple different domains. The amount of liquidity and the best exchange rate available in any given DEX may vary depending on the offers placed in that DEX. Some traders may choose to trade in multiple permissioned DEXes and the open DEX to arbitrage price differences, while other traders may trade strictly in one domain, depending on their compliance requirements. @@ -65,20 +84,30 @@ _Figure: The open DEX, and two different permissioned DEXes, each containing ord ### Invalid Permissioned Offers -In addition to the ways offers can be unfunded in the open DEX, offers in a permissioned DEX can become _invalid_. Invalid offers are treated the same way as unfunded offers, and are automatically removed whenever a transaction modifies the order book containing them. They can remain in the ledger data indefinitely until a transaction removes them, but they cannot be executed if they are invalid. Reasons that a permissioned offer can become invalid include: +In addition to the ways offers can be unfunded in the open DEX, offers in a permissioned DEX can become _invalid_. Invalid offers are treated the same way as unfunded offers and are automatically removed whenever a transaction modifies the order book containing them. They can remain in the ledger data indefinitely until a transaction removes them, but they cannot be executed if they are invalid. + +Reasons a permissioned offer can become invalid include: - A credential, held by the account placing the offer, has expired or has been deleted. - The permissioned domain has been updated to change the set of credentials that grant access, and the account placing the offer does not hold any of the new credentials. - The permissioned domain has been deleted. -Like with unfunded offers, it is possible for an offer to become temporarily invalid, then become valid again. For example, if a trader's credential that grants access to a permissioned domain expires, their offers in the corresponding permissioned DEX would be invalid; but if they get the credential renewed, any offers that hadn't already been removed automatically become valid again. +Like with unfunded offers, it is possible for an offer to become temporarily invalid and then become valid again. For example, if a trader's credential that grants access to a permissioned domain expires, their offers in the corresponding permissioned DEX would be invalid; but if they get the credential renewed, any offers that hadn't already been removed automatically become valid again. -### Limitations +### Limitations of Permissioned DEXes The permissioned DEXes feature is enabled by the **PermissionedDEX** amendment, and relies on the [Credentials](../../decentralized-storage/credentials.md) and [Permissioned Domains](./permissioned-domains.md) amendments, so it cannot be used until _all_ of those amendments have been enabled. -Permissioned DEXes are incompatible with Automated Market Makers (AMMs). Permissioned offers and permissioned payments cannot be filled by AMMs, and access to AMMs cannot be restricted by a permissioned domain. Trades that use the open DEX can sometimes consume a hybrid offer and use an AMM in the same transaction, but transactions that specify a domain cannot use any AMMs. +#### Not Compatible with AMMs + +Permissioned DEXes are incompatible with [Automated Market Makers (AMMs)](../../tokens/decentralized-exchange/automated-market-makers.md). Permissioned offers and permissioned payments cannot be filled by AMMs, and access to AMMs cannot be restricted by a permissioned domain. Trades that use the open DEX can sometimes consume a hybrid offer and use an AMM in the same transaction, but transactions that specify a domain cannot use any AMMs. + +**Permissioned DEXes are independent** Each permissioned DEX is separate, with its own order books and offers. A single transaction cannot trade in multiple permissioned DEXes or aggregate liquidity from multiple permissioned DEXes. Hybrid offers can use a mix of one permissioned DEX and the open DEX, but they cannot use multiple different permissioned DEXes. -The security and fairness of a permissioned DEX depend on the owner of the permissioned domain and the issuers of credentials that grant access to it. At a baseline, the definition of each credential and the requirements for getting that credential are defined and enforced by the credential issuer, so the existence of a permissioned domain does not inherently mean anything about who is able to use it in practice. A credential issuer can issue or revoke credentials at their discretion. If they are unreliable or compromised, so is any permissioned domain that accepts their credentials. Similarly, the domain owner can modify the domain's list of accepted credentials to grant or deny access to the domain arbitrarily, so if they are untrustworthy or compromised, the domain is as well. +#### Security Considerations for Permissioned DEXes + +The security and fairness of a permissioned DEX depend on the owner of the permissioned domain and the issuers of credentials that grant access to it. At a baseline, the definition of each credential and the requirements for getting that credential are defined and enforced by the credential issuer, so the existence of a permissioned domain does not inherently mean anything about who is able to use it in practice. + +A credential issuer can issue or revoke credentials at their discretion. If they are unreliable or compromised, so is any permissioned domain that accepts their credentials. Similarly, the domain owner can modify the domain's list of accepted credentials to grant or deny access to the domain arbitrarily, so if they are untrustworthy or compromised, the domain is as well. diff --git a/docs/concepts/tokens/decentralized-exchange/permissioned-domains.md b/docs/concepts/tokens/decentralized-exchange/permissioned-domains.md index 4817615417..ab21159264 100644 --- a/docs/concepts/tokens/decentralized-exchange/permissioned-domains.md +++ b/docs/concepts/tokens/decentralized-exchange/permissioned-domains.md @@ -1,13 +1,13 @@ --- seo: - description: The definition and details of a Permissioned Domain instance. + description: Learn how Permissioned Domains on the XRP Ledger enable controlled, secure blockchain environments. Explore their role in decentralized exchanges (DEXes) and lending protocols. labels: - Compliance - Permissioned Domains --- # Permissioned Domains -Permissioned domains are controlled environments within the broader ecosystem of the XRP Ledger blockchain. Domains do nothing on their own, but features such as Permissioned DEXes and Lending Protocols can use domains to restrict access, so that traditional financial institutions can offer services on chain while complying with various compliance rules. +Permissioned domains are controlled environments within the broader ecosystem of the XRP Ledger blockchain. Domains do nothing on their own, but features such as [Permissioned DEXes][] and Lending Protocols can use domains to restrict and manage access, so traditional financial institutions can offer services on chain while complying with various compliance rules. The only configurable rule for a domain is the set of accepted [credentials][]. Future amendments may add new and different types of rules to encompass any limits that a financial institution may need to follow to maintain compliance with the laws of the jurisdictions where they do business. @@ -29,7 +29,7 @@ A domain serves as an abstraction layer between credentials and a resource being Users do not need to apply to join or leave a domain. When a transaction requires access to a resource that is restricted by a domain, the transaction automatically checks if the account holds a credential matching that domain's accepted credentials, and fails if they have none. The user's credential must be accepted and not expired. -## Uses for Domains +## Uses for Permissioned Domains Currently, there are no available XRP Ledger features that use permissioned domains. However, amendments that are in development and use domains include: diff --git a/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens.md b/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens.md index 9b643fffaf..9b52dcacac 100644 --- a/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens.md +++ b/docs/concepts/tokens/fungible-tokens/multi-purpose-tokens.md @@ -1,5 +1,6 @@ --- -blurb: Multi-purpose tokens offer a more compact, flexible token type than trust lines. +seo: + description: Learn about multi-purpose tokens (MPTs) on XRP Ledger. MPTs are a flexible way to issue fungible tokens with built-in metadata, compliance, and transfer controls. labels: - Tokens - MPTs @@ -10,48 +11,78 @@ status: not_enabled _(Requires the [MPTokensV1 amendment][] {% not-enabled /%})_ -Multi-purpose tokens (MPTs) are a more compact and flexible type of fungible token. +Multi-purpose tokens (MPTs) are a more compact and flexible type of [fungible token](./index.md) on the XRP Ledger. -MPTs let you take advantage of ready-to-use tokenization features with a few lines of code. You can create many token experiences from one token program itself. Notable features include: +MPTs let you take advantage of ready-to-use tokenization features with a few lines of code. You can create many token experiences from one token program itself. + +## Key Features of MPTs on XRPL + +The following are notable features of MPTs on XRPL. + +**On-Chain Metadata Storage** - MPTs store their metadata directly on the XRPL blockchain. Once set, the metadata is immutable. - A 1024-byte URI field provides a metadata pointer that allows you to use an off-chain source for metadata in addition to the on-chain source. This lets your application access necessary information directly from the chain, prompting higher interoperability for tokens, without losing the ability to attach additional information. + +**Transferability and Supply Controls** + - MPTs can have a fixed token supply where you set a cap on the maximum number of tokens that can be minted. - You can define MPTs as non-transferable, tokens that can only be transferred back to the issuer, but not among tokenholders. Useful for cases such as issuing airline credits or loyalty rewards. - Issuers can set transfer fees to collect on-chain revenue each time the token is traded among tokenholders. -- MPTs also have advanced compliance features: - - The ability to lock tokens held by a tokenholder to support compliance requirements. - - The ability to set a global lock for all MPT balances across all tokenholders. - - The issuer can configure MPTs that can be clawed back from tokenholder wallets, either to revoke them, or to reassign them in the case of lost wallet keys. - - An opt-in feature can allow only wallets authorized by the issuer to hold issued tokens. + +**Built-In Compliance Features** + +MPTs also have advanced compliance features, including: + - The ability to lock tokens held by a tokenholder to support compliance requirements. + - The ability to set a global lock for all MPT balances across all tokenholders. + - The issuer can configure MPTs that can be clawed back from tokenholder wallets, either to revoke them, or to reassign them in the case of lost wallet keys. + - An opt-in feature can allow only wallets authorized by the issuer to hold issued tokens. ## MPTs versus Trust Lines -Unlike trust lines, MPTs do not represent bidirectional debt relationships. Instead, MPTs function more like a unidirectional trust line with only one balance. This reduces the overhead to support common tokenization requirements, including non-monetary use cases such as tracking reputation points in an online game. +These are the primary differences between MPTs and [trust lines](/docs/concepts/tokens/fungible-tokens#trust-lines). -MPTs offer a less complicated conceptual model than trust lines. +**Conceptual Differences** -MPTs require significantly less space than trust lines. They require roughly 52 bytes for each MPT held by a token holder, compared to at least 234 bytes for every new trust line. +- Unlike trust lines, MPTs do not represent bidirectional debt relationships. Instead, MPTs function more like a unidirectional trust line with only one balance. This reduces the overhead to support common tokenization requirements, including non-monetary use cases such as tracking reputation points in an online game. -They reduce the long-term infrastructure and storage burdens for node operators, increasing network resiliency. +- MPTs offer a less complicated conceptual model than trust lines. -MPTs also improve node perfomance when processing large volumes of transactions. +**Ledger Storage and Performance** -MPTs are unidirectional. While trust lines use "balance netting," MPTs have only a single balance. +- MPTs require significantly less space than trust lines. They require roughly 52 bytes for each MPT held by a token holder, compared to at least 234 bytes for every new trust line. -An account can issue a maximum of 32 unique MPT issuances. If an issuer wants to support more than this number of MPTs, they can open additional accounts. +- They reduce the long-term infrastructure and storage burdens for node operators, increasing network resiliency. -Since token holders will not acquire an MPT without first making an off-ledger trust decision, MPTs have no trust limits. For example, a common use case for an MPT is a fiat-backed stablecoin, where a token holder wouldn't purchase more stablecoins than they would feel comfortable holding. +- MPTs also improve node perfomance when processing large volumes of transactions. -Unlike some existing capabilities of the ledger, MPTs are not subject to rippling, and do not require configurability settings related to that functionality. +**Transfer Logic and Directionality** + +- MPTs are unidirectional. While trust lines use "balance netting," MPTs have only a single balance. +- An account can issue a maximum of 32 unique MPT issuances. If an issuer wants to support more than this number of MPTs, they can open additional accounts. +- Since token holders will not acquire an MPT without first making an off-ledger trust decision, MPTs have no trust limits. For example, a common use case for an MPT is a [fiat-backed stablecoin](/docs/concepts/tokens/fungible-tokens/stablecoins#fiat-backed), where a token holder wouldn't purchase more stablecoins than they would feel comfortable holding. +- Unlike some existing capabilities of the ledger, MPTs are not subject to [rippling](/docs/concepts/tokens/fungible-tokens/rippling) and do not require configurability settings related to that functionality. ## MPTs versus IOUs -On a technical level, MPTs provide a fundamentally different way to represent fungible tokens on the ledger. While IOUs are represented by trustlines and have bilateral debt relationships, MPTs use a simpler, unilateral relationship captured by an MPToken object. This results in substantial space savings on the ledger. The representation of a fungible token as a token object instead of a trustline makes it easier to enable functionality for real-world financial assets on-chain, such as token-level metadata, fixed supply, and fixed-point balance. +MPTs are different from IOUs in the following ways. -On a usage level, MPTs provide a straightforward conceptual model compared to trustlines and rippling. Developers can more easily build web3 applications around `MPToken` and `MPTokenIssuance` objects, with some similarities to the conceptual model of XLS-20 NFTs. It is also simpler for ordinary users to understand what tokens are available, what tokens they have issued, and what they hold in their wallet. For both issuers and holders of MPTs, there will typically be a smaller XRP reserve compared to the equivalent representations with IOU trustlines. +**Technical Representation on the Ledger** -MPTs are intended to be complementary to IOUs. While there might be use cases where either MPTs or IOUs might be suitable, there will likely be a need for both over the long term. There will be use cases such as credit lines for lending and borrowing that might be better represented by IOUs long term. The MPT feature set should evolve in an incremental manner to unlock more common use cases first and deliver additional feature support at a later time. During the MPT development period, some cases might still be better represented by an IOU, then later be better supported with MPTs. +On a technical level, MPTs provide a fundamentally different way to represent fungible tokens on the ledger. While IOUs are represented by trustlines and have bilateral debt relationships, MPTs use a simpler, unilateral relationship captured by an MPToken object. This results in substantial space savings on the ledger. + +The representation of a fungible token as a token object instead of a trustline makes it easier to enable functionality for real-world financial assets on-chain, such as token-level metadata, fixed supply, and fixed-point balance. + +**Developer Experience and App Design** +On a usage level, MPTs provide a straightforward conceptual model compared to [trustlines](/docs/concepts/tokens/fungible-tokens#trust-lines) and [rippling](/docs/concepts/tokens/fungible-tokens/rippling). Developers can more easily build web3 applications around `[MPToken](/docs/references/protocol/ledger-data/ledger-entry-types/mptoken)` and `[MPTokenIssuance](/docs/references/protocol/ledger-data/ledger-entry-types/mptokenissuance)` objects, with some similarities to the conceptual model of XLS-20 NFTs. + +It is also simpler for ordinary users to understand what tokens are available, what tokens they have issued, and what they hold in their wallet. + +For both issuers and holders of MPTs, there will typically be a smaller XRP reserve compared to the equivalent representations with IOU trustlines. + +## Use Case and Long-Term Considerations + +MPTs are intended to be complementary to IOUs. While there might be use cases where either MPTs or IOUs might be suitable, there will likely be a need for both over the long term. There will be use cases such as credit lines for lending and borrowing that might be better represented by IOUs long term. The MPT feature set should evolve in an incremental manner to unlock more common use cases first and deliver additional feature support at a later time. During the MPT development period, some cases might still be better represented by an IOU, and then later be better supported with MPTs. ## See Also diff --git a/docs/concepts/transactions/batch-transactions.md b/docs/concepts/transactions/batch-transactions.md index d91456d110..1dd1701c70 100644 --- a/docs/concepts/transactions/batch-transactions.md +++ b/docs/concepts/transactions/batch-transactions.md @@ -1,6 +1,6 @@ --- seo: - description: Batch allows up to 8 transactions to be submitted as a single unit. + description: Discover how XRPL Batch Transactions streamline multiple blockchain operations into a single secure transaction. Learn about batch modes, execution details, and security considerations. labels: - Batch - Transactions @@ -8,7 +8,9 @@ status: not_enabled --- # Batch Transactions -`Batch` lets you package multiple transactions together and execute them as a single unit. It eliminates the risk of partial completion and unexpected outcomes, giving you a more reliable and predictable experience for complex operations. Up to eight transactions can be submitted in a single batch. +XRPL Batch Transactions let you package multiple [transactions](/docs/concepts/transactions) together and execute them as a single unit. It eliminates the risk of partial completion and unexpected outcomes, giving you a more reliable and predictable experience for complex operations. Up to eight transactions can be submitted in a single batch. + +## XRPL Batch Use Cases Some potential uses for `Batch` include the following. - All or nothing: You can mint an NFT and create an offer for it in one transaction. If the offer creation fails, the NFT mint is reverted as well. @@ -19,7 +21,11 @@ Some potential uses for `Batch` include the following. `Batch` transactions are comprised of the _outer transaction_, the wrapper `Batch` transaction itself, and the _inner transactions_, each of which is executed atomically. The precise way that the inner transactions are processed is determined by the batch _mode_. -## Batch Mode +
+ +
+ +## XRPL Batch Transaction Modes There are four possible batch modes: `ALLORNOTHING`, `ONLYONE`, `UNTILFAILURE`, and `INDEPENDENT`. @@ -39,9 +45,9 @@ In `ALLORNOTHING` mode, all inner transactions must succeed for any one of them All transactions are applied, even if one or more of the inner transactions fail. -## Raw Transactions +## XRPL Raw Transactions Object -The `RawTransactions` object is a container for the list of transactions to be applied. You can include up to eight transactions in a sincle batch. The transactions can come from one account or multiple accounts. +The `RawTransactions` object is a container for the list of transactions to be applied. You can include up to eight transactions in a single batch. The transactions can come from one account or multiple accounts. Each inner transaction: @@ -67,6 +73,8 @@ This field is included if the account is signing with multi-sign (as opposed to This field must be provided if more than one account has inner transactions included in the Batch. In that case, this field must contain signatures from all accounts whose inner transactions are included, excluding the account signing the outer transaction (if applicable). +#### Fields Used for XRPL Batch Transactions + Each object in this array contains the following fields: | Field Name | Required? | JSON Type | Internal Type | @@ -90,7 +98,7 @@ These fields are included if the account is signing with a single signature (as This field is included if the account is signing with multi-sign (as opposed to a single signature). It operates equivalently to the `Signers` field used in standard transaction multi-sign. This field holds the signatures for the `Flags` field and the hashes of the transactions in `RawTransactions`. -## Transaction Fee +## XRPL Batch Transaction Fees The fee for the outer transaction is twice the base fee (a total of 20 drops when there is no fee escalation), plus the sum of the transaction fees of all the inner transactions (which incorporates factors like higher fees for `multisign` or `AMMCreate`), plus an additional base fee amount for each additional signature in the transaction (for example, from `BatchSigners`). Expressed as an equation: @@ -124,7 +132,7 @@ There is also a pointer back to the parent outer transaction (`ParentBatchID`). ## Transaction Common Fields -This standard doesn't add any new fields to the transaction common fields, but it does add another global transaction flag: +This standard doesn't add any new fields to the [transaction common fields](/docs/references/protocol/transactions/common-fields.md), but it does add another global transaction flag: | Flag Name | Value | |-----------------|------------| @@ -132,7 +140,7 @@ This standard doesn't add any new fields to the transaction common fields, but i This flag should be used only if a transaction is an inner transaction in a `Batch` transaction. This signifies that the transaction shouldn't be signed. Any normal transaction that includes this flag should be rejected. -## Security +## Security for XRPL Batch Transactions Batch transactions come with additional security considerations.