diff --git a/blog/2025/rippled-2.5.0.md b/blog/2025/rippled-2.5.0.md new file mode 100644 index 0000000000..6a8c4b18db --- /dev/null +++ b/blog/2025/rippled-2.5.0.md @@ -0,0 +1,178 @@ +--- +category: 2025 +date: "2025-06-24" +template: '../../@theme/templates/blogpost' +seo: + title: Introducing XRP Ledger version 2.5.0 + description: rippled version 2.5.0 is now available. This version introduces new features and bug fixes. +labels: + - rippled Release Notes +markdown: + editPage: + hide: true +--- +# Introducing XRP Ledger version 2.5.0 + +Version 2.5.0 of `rippled`, the reference server implementation of the XRP Ledger protocol, is now available. This release adds new features and bug fixes, and introduces these amendments: + +- `TokenEscrow` +- `Batch` +- `PermissionedDEX` +- `PermissionDelegation` +- `AMMv1_3` +- `EnforceNFTokenTrustlineV2` +- `PayChanCancelAfter` + + +## Action Required + +If you run an XRP Ledger server, upgrade to version 2.5.0 as soon as possible to ensure service continuity. + +Additionally, new amendments are now open for voting according to the XRP Ledger's [amendment process](../../docs/concepts/networks-and-servers/amendments.md), which enables protocol changes following two weeks of >80% support from trusted validators. The exact time that protocol changes take effect depends on the voting decisions of the decentralized network. + + +## Install / Upgrade + +On supported platforms, see the [instructions on installing or updating `rippled`](../../docs/infrastructure/installation/index.md). + +| Package | SHA-256 | +|:--------|:--------| +| [RPM for Red Hat / CentOS (x86-64)](https://repos.ripple.com/repos/rippled-rpm/stable/rippled-2.5.0-1.el7.x86_64.rpm) | `7719be1889619a37a83795a9740d803bbc1c08b0bd8c755cbf266aeb68b875b6` | +| [DEB for Ubuntu / Debian (x86-64)](https://repos.ripple.com/repos/rippled-deb/pool/stable/rippled_2.5.0-1_amd64.deb) | `d935f678624349e422dff1944a40acaf3e287b11244b4f5b5056cb343fc31e9d` | +| [Portable Builds (Linux x86-64)](https://github.com/XRPLF/rippled-portable-builds) | (Use signature verification) | + +For other platforms, please [build from source](https://github.com/XRPLF/rippled/blob/master/BUILD.md). The most recent commit in the git log should be the change setting the version: + +```text +commit 1e01cd34f7a216092ed779f291b43324c167167a +Author: Michael Legleux +Date: Tue Jun 17 10:38:07 2025 -0700 + + Set version to 2.5.0 +``` + +{% admonition type="warning" name="Warning" %} After this release, we will no longer support GCC versions older than 12, Clang (including Apple Clang) versions older than 16, or Conan 1. {% /admonition %} + + +## Full Changelog + +### Amendments + +The following amendments are open for voting with this release: + +- **TokenEscrow (XLS-85)** - Enhances escrow functionality by enabling escrows to interact with trustline-based tokens (IOUs) and multi-purpose tokens (MPTs). ([#5185](https://github.com/XRPLF/rippled/pull/5185)) +- **Batch (XLS-56)** - Adds the ability to group multiple transactions and execute them atomically, improving efficiency and enabling complex multistep operations. ([#5060](https://github.com/XRPLF/rippled/pull/5060)) +- **PermissionedDEX (XLS-81)** - Adds permissioned decentralized exchanges that control who can participate, ensuring compliance with financial regulations. ([#5404](https://github.com/XRPLF/rippled/pull/5404)) +- **PermissionDelegation (XLS-75)** - Enables account holders to delegate specific permissions to other accounts for flexible account management and automation. ([#5354](https://github.com/XRPLF/rippled/pull/5354)) +- **AMMv1_3** - Adds invariant checking to AMM-related transactions. ([#5203](https://github.com/XRPLF/rippled/pull/5203)) +- **EnforceNFTokenTrustlineV2** - Fixes issues with NFT interactions bypassing the trustline authorization requirement. ([#5297](https://github.com/XRPLF/rippled/pull/5297)) +- **PayChanCancelAfter** - Fixes an issue that made it possible to create a payment channel when `CancelAfter` is in the past. ([#4717](https://github.com/XRPLF/rippled/pull/4717)) + + +### New Features + +- Increased network I/O capacity to handle higher transaction loads. ([#5464](https://github.com/XRPLF/rippled/pull/5464)) +- Enhanced transaction relay logic. ([#4985](https://github.com/XRPLF/rippled/pull/4985)) +- Added XRPL Commons as a new Bootstrap Cluster in the `rippled` configuration. ([#5263](https://github.com/XRPLF/rippled/pull/5263)) +- Improved how the `simulate` method handles transactions submitted from a multi-signing account. Also fixed an issue that allowed transactions when both single-signed and multi-signed keys were provided. ([#5479](https://github.com/XRPLF/rippled/pull/5479)) +- Updated code reviewers for RPC changes. ([#5266](https://github.com/XRPLF/rippled/pull/5266)) + + +### Bug Fixes + +- Fixed pseudo-account ID calculation to ensure correct account address generation. ([#5447](https://github.com/XRPLF/rippled/pull/5447)) +- Fixed a unity build error. ([#5459](https://github.com/XRPLF/rippled/pull/5459)) +- Fixed initializer list initialization issues for GCC-15 compatibility. ([#5443](https://github.com/XRPLF/rippled/pull/5443)) +- Resolved slow test performance issues on macOS pipeline. ([#5392](https://github.com/XRPLF/rippled/pull/5392)) +- Replaced the custom endpoint selection logic with sequential attempts to connect to available endpoints until one succeeds or all fail. ([#5365](https://github.com/XRPLF/rippled/pull/5365)) +- Fixed coverage file generation to ensure atomic generation. ([#5426](https://github.com/XRPLF/rippled/pull/5426)) +- Renamed _deadlock_ crash error to _stall_ in the event of severe CPU starvation. ([#5341](https://github.com/XRPLF/rippled/pull/5341)) +- Fixed an inaccurate error message in the `ledger_entry` RPC method when the account specified is not a string. ([#5344](https://github.com/XRPLF/rippled/pull/5344)) +- Fixed a crash that could occur when handling an invalid marker parameter in a gRPC call. ([#5317](https://github.com/XRPLF/rippled/pull/5317)) +- Fixed an issue with trust lines setting behavior around the `lsfDefaultRipple` flag. ([#5345](https://github.com/XRPLF/rippled/pull/5345)) +- Removed undefined behavior from `LogicError` to guarantee a stacktrace. ([#5338](https://github.com/XRPLF/rippled/pull/5338)) +- Updated links to the ripple binary codec definitions. ([#5355](https://github.com/XRPLF/rippled/pull/5355)) +- Fixed the consensus logic to prevent a consensus round taking too long to complete. ([#5277](https://github.com/XRPLF/rippled/pull/5277)) +- Fixed `undefined uint128_t` type on non-unity `Windows` builds. ([#5377](https://github.com/XRPLF/rippled/pull/5377)) +- Fixed a `uint128` issue that broke MacOS unity builds. ([#5386](https://github.com/XRPLF/rippled/pull/5386)) +- Fixed a memory ordering assertion failure. ([#5381](https://github.com/XRPLF/rippled/pull/5381)) +- Disabled `channel_authorize` when `signing_support` is disabled. ([#5385](https://github.com/XRPLF/rippled/pull/5385)) +- Fixed a webhook issue when using the `subscribe` admin RPC. ([#5163](https://github.com/XRPLF/rippled/pull/5163)) +- Fixed issues with CTID. ([#4738](https://github.com/XRPLF/rippled/pull/4738)) +- Temporarily disabled unit tests on macOS to investigate delays. ([#5397](https://github.com/XRPLF/rippled/pull/5397)) +- Fixed CTID to use the correct `ledger_index`. ([#5408](https://github.com/XRPLF/rippled/pull/5408)) +- Updated CODEOWNERS path configuration. ([#5440](https://github.com/XRPLF/rippled/pull/5440)) +- Removed unused code. ([#5475](https://github.com/XRPLF/rippled/pull/5475)) + + +### Other Improvements + +- Enabled passive squelching for validators to accept squelch messages from untrusted validators, reducing duplicate traffic they generate. ([#5358](https://github.com/XRPLF/rippled/pull/5358)) +- Improved squelching configuration. ([#5438](https://github.com/XRPLF/rippled/pull/5438)) +- Updated CPP reference source. ([#5453](https://github.com/XRPLF/rippled/pull/5453)) +- Added codecov badge and raised coverage thresholds. ([#5428](https://github.com/XRPLF/rippled/pull/5428)) +- Refactored codebase to use east const convention for code consistency. ([#5409](https://github.com/XRPLF/rippled/pull/5409)) +- Updated build instructions for Ubuntu 22.04+. ([#5292](https://github.com/XRPLF/rippled/pull/5292)) +- Updated build instructions to improve build times. ([#5288](https://github.com/XRPLF/rippled/pull/5288)) +- Updated example keyserver host in `SECURITY.md`. ([#5460](https://github.com/XRPLF/rippled/pull/5460)) +- Implemented `transitive_headers` when building with Conan 2. ([#5462](https://github.com/XRPLF/rippled/pull/5462)) +- Renamed documentation CI job for clarity. ([#5398](https://github.com/XRPLF/rippled/pull/5398)) +- Clarified the `lsfDefaultRipple` comment for better code documentation. ([#5410](https://github.com/XRPLF/rippled/pull/5410)) +- Cleaned up missing and unused headers. ([#5293](https://github.com/XRPLF/rippled/pull/5293)) +- Refactored code to update `numFeatures` automatically. ([#5324](https://github.com/XRPLF/rippled/pull/5324)) +- Improved ordering of headers with clang format. ([#5343](https://github.com/XRPLF/rippled/pull/5343)) +- Updated Conan dependencies. ([#5335](https://github.com/XRPLF/rippled/pull/5335)) +- Added PR numbers to the payload of `libXRPL` compatibility check workflows. ([#5310](https://github.com/XRPLF/rippled/pull/5310)) +- Updated TxQ unit tests to work with variable reference fees. ([#5118](https://github.com/XRPLF/rippled/pull/5118), [#5145](https://github.com/XRPLF/rippled/pull/5145)) +- Optimized SHAMap smart pointers for efficient memory use and lock-free synchronization. ([#5152](https://github.com/XRPLF/rippled/pull/5152)) +- Moved integration tests to another folder to make their purpose clear. ([#5367](https://github.com/XRPLF/rippled/pull/5367)) +- Enabled compile time parameter to change the reference fee value. ([#5159](https://github.com/XRPLF/rippled/pull/5159)) +- Cleaned up test logging messages to make it easier to search. ([#5396](https://github.com/XRPLF/rippled/pull/5396)) +- Improved CI jobs to only run on PRs that have a `DraftRunCI` label. ([#5400](https://github.com/XRPLF/rippled/pull/5400)) +- Updated `validators-example.txt` to fix XRPLF example URL configuration. ([#5384](https://github.com/XRPLF/rippled/pull/5384)) +- Changed ledger close in `env.meta` to be conditionally on, making it easier to debug issues if you closed the ledger outside of the `meta` function. ([#5457](https://github.com/XRPLF/rippled/pull/5457)) +- Collapsed log messages for easier readability. ([#5347](https://github.com/XRPLF/rippled/pull/5347)) + + +## Credits + +The following people contributed directly to this release: + +- Alex Kremer +- Ayaz Salikhov +- Bart Thomee +- Brett Mollin +- Bronek Kozicki +- Cindy Yan <120398799+cindyyan317@users.noreply.github.com> +- Darius Tumas +- David Fuelling +- Denis Angell +- Ed Hennis +- Elliot Lee +- Gregory Tsipenyuk +- Jingchen Wu +- Luc des Trois Maisons +- Mani Mounika Kunasani +- Mark Travis +- Matt Mankins +- Mayukha Vadari +- Michael Legleux +- Oleksandr Pidskopnyi +- Ramkumar SG +- Scott Determan +- Sergey Kuznetsov +- Sophia Xie +- Shawn Xie +- Valentin Balaschenko +- Vito Tumas +- Vladislav Vysokikh +- Wietse Wind +- Xun Zhao +- Yinyi Qian + + +## Bug Bounties and Responsible Disclosures + +We welcome reviews of the `rippled` code and urge researchers to responsibly disclose any issues they may find. + +To report a bug, please send a detailed report to: diff --git a/blog/sidebars.yaml b/blog/sidebars.yaml index c06020441f..cdecdf862e 100644 --- a/blog/sidebars.yaml +++ b/blog/sidebars.yaml @@ -6,6 +6,7 @@ - group: '2025' expanded: false items: + - page: 2025/rippled-2.5.0.md - page: 2025/fixes-enabled-dnfts-expected.md - page: 2025/clio-2.4.1.md - page: 2025/integrating-dia-oracles-on-xrpl.md diff --git a/docs/concepts/accounts/permission-delegation.md b/docs/concepts/accounts/permission-delegation.md new file mode 100644 index 0000000000..0ac735b126 --- /dev/null +++ b/docs/concepts/accounts/permission-delegation.md @@ -0,0 +1,108 @@ +--- +seo: + description: XRPL accounts can delegate both transaction permissions and granular permissions to other accounts. +labels: + - Accounts + - Permissions +status: not_enabled +--- +# Permission Delegation +XRPL accounts can delegate both transaction permissions and granular permissions to other accounts, enhancing flexibility and enabling use cases such as implementing role-based access control. This delegation is managed using the [`DelegateSet`](../../references/protocol/transactions/types/delegateset.md) transaction. + +_(Requires the [PermissionDelegation amendment][] {% not-enabled /%})_ + +## Assigning Permissions + +You can assign permissions to another account by submitting a `DelegateSet` transaction. + +```json +tx_json = { + "TransactionType": "DelegateSet", + "Account": "rDelegatingAccount", + "Authorize": "rDelegatedAccount", + "Permissions": [ + { + "Permission": { + "PermissionValue": "Payment" + } + } + ] +} +``` + +| Field | Description | +|-------|-------------| +| `Account` | The address of the account that is delegating the permission(s). | +| `Authorize` | The address of the account that is being granted the permission(s). | +| `Permissions` | An array of permission objects, specifying the permissions to delegate. Each permission is defined within a `Permission` object, using the `PermissionValue` field. See [XLS-74d, Account Permissions] for a complete list of valid `PermissionValues`. | + +## Revoking Permissions + +Permissions can be revoked using the `DelegateSet` transaction. There are two ways to revoke permissions: + +### Revoke All Permissions + +To revoke all permissions previously granted to a delegated account, send a `DelegateSet` transaction with an empty `Permissions` array: + +```json +tx_json = { + "TransactionType": "DelegateSet", + "Account": "rDelegatingAccount", + "Authorize": "rDelegatedAccount", + "Permissions": [] +} +``` + +### Revoke Specific Permissions + +To revoke specific permissions, send a `DelegateSet` transaction that includes _only_ the permissions that should remain active. Any permissions previously granted to the `Authorize` account that aren't included in the `Permissions` array are revoked. + +## Sending Transactions with Delegated Permissions + +When an account has been granted permissions, it can send transactions on behalf of the delegating account using the `Delegate` field. + +For example, if `rDelegatingAccount` has delegated the `TrustSet` permission to `rDelegatedAccount`, then `rDelegatedAccount` can submit a `TrustSet` transaction on behalf of `rDelegatingAccount` as follows: + +```json +transaction_json = { + "TransactionType": "TrustSet", + "Account": "rDelegatingAccount", + "Delegate": "rDelegatedAccount", + "LimitAmount": { + "currency": "USD", + "issuer": "rIssuerAccount", + "value": "1000" + } +} +``` + +| Field | Description | +|-------|-------------| +| `Account` | The address of the account that granted permission for the transaction (the _delegating_ account). | +| `Delegate` | The address of the account submitting and signing the transaction. This must be the account that was granted permission (the _delegated_ account). | + +The account that sends this transaction is _rDelegatedAccount_, although the Account field is the _rDelegatingAccount_. The secret for this transaction is the _rDelegatedAccount_ secret, which means _rDelegatedAccount_ signs the transaction. + +## Error Cases + +- If the `PermissionDelegation` feature is not enabled, return `temDISABLED`. + +- If the _rDelegatedAccount_ is not authorized by the _rDelegatingAccount_ for the transaction type or satisfying the granular permissions given by _rDelegatingAccount_, the transaction returns `tecNO_DELEGATE_PERMISSION`. + +- If the _rDelegatedAccount_ does not have enough balance to pay the transaction fee, the transaction returns `terINSUF_FEE_B` . (_rDelegatedAccount_ pays the fee, which is the sender in `Delegate` field, not the `Account` field). + +- If the transaction creates a ledger object, but _rDelegatingAccount_ does not have enough balance to cover the reserve, the transaction returns `tecINSUFFICIENT_RESERVE`. + +- If the key used to sign this account does not match with _rDelegatedAccount_, the transaction returns `rpcBAD_SECRET`. + +- If the `TradingFee` is invalid (non-XRP currency or negative value), return `temBAD_FEE`. + +Any other errors are the same as when the _rDelegatingAccount_ sends transaction for itself. + +{% admonition type="warning" name="Important" %} +* Delegating permissions grants significant control. Ensure you trust the delegated account. +* The account specified in the `Delegate` field is responsible for paying the transaction fee. +* A delegated account can only perform actions that have been explicitly permitted. +{% /admonition %} + +{% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/concepts/payment-types/escrow.md b/docs/concepts/payment-types/escrow.md index 16da562f5f..cb71c73413 100644 --- a/docs/concepts/payment-types/escrow.md +++ b/docs/concepts/payment-types/escrow.md @@ -10,7 +10,7 @@ labels: Traditionally, an escrow is a contract between two parties to facilitate financial transactions. An impartial third party receives and holds funds, and only releases them to the intended recipient when conditions specified by the contract are met. This method ensures both parties meet their obligations. -The XRP Ledger takes escrow a step further, replacing the third party with an automated system built into the ledger. An escrow locks up XRP, which can't be used or destroyed until conditions are met. +The XRP Ledger takes escrow a step further, replacing the third party with an automated system built into the ledger. An escrow locks up XRP or fungible tokens, which can't be used or destroyed until conditions are met. ## Types of Escrow @@ -24,15 +24,15 @@ The XRP Ledger supports three types of escrow: 1. The sender creates an escrow using the `EscrowCreate` transaction. This transaction defines: - - An amount of XRP to lock up. - - The conditions to release the XRP. - - The recipient of the XRP. + - An number of XRP or fungible tokens to lock up. + - The conditions to release the XRP or fungible tokens. + - The recipient of the XRP or fungible tokens. -2. When the transaction is processed, the XRP Ledger creates an `Escrow` object that holds the escrowed XRP. +2. When the transaction is processed, the XRP Ledger creates an `Escrow` object that holds the escrowed XRP or fungible token. -3. The recipient sends an `EscrowFinish` transaction to deliver the XRP. If the conditions have been met, this destroys the `Escrow` object and delivers the XRP to the recipient. +3. The recipient sends an `EscrowFinish` transaction to deliver the XRP or fungible tokens. If the conditions have been met, this destroys the `Escrow` object and delivers the XRP or fungible tokens to the recipient. - {% admonition type="info" name="Note" %}If the escrow has an expiration time and isn't successfully finished before then, the escrow becomes expired. An expired escrow remains in the ledger until an `EscrowCancel` transaction cancels it, destroying the `Escrow` object and returning the XRP to the sender.{% /admonition %} + {% admonition type="info" name="Note" %}If the escrow has an expiration time and isn't successfully finished before then, the escrow becomes expired. An expired escrow remains in the ledger until an `EscrowCancel` transaction cancels it, destroying the `Escrow` object and returning the escrowed XRP or fungible tokens to the sender.{% /admonition %} ## Escrow States @@ -51,7 +51,6 @@ The diagram shows three different cases for three possible combinations of the e ## Limitations -- Escrow only works with XRP, not tokens. - The costs can make it infeasible for small amounts. - Escrow requires two transactions: one to create the escrow, and one to finish or cancel it. Crypto-Conditions incur a higher [transaction cost](../transactions/transaction-cost.md) than usual. - While the escrow is incomplete, the sender is responsible for the [reserve requirement](../accounts/reserves.md) of the `Escrow` object. @@ -66,7 +65,7 @@ When using crypto-conditions, the EscrowFinish transaction must pay a [higher tr The additional transaction cost required is proportional to the size of the fulfillment. If the transaction is [multi-signed](../accounts/multi-signing.md), the cost of multi-signing is added to the cost of the fulfillment. -Currently, an EscrowFinish with a fulfillment requires a minimum transaction cost of **330 [drops of XRP](../../references/protocol/data-types/basic-data-types.md#specifying-currency-amounts) plus 10 drops per 16 bytes in the size of the fulfillment**. +Currently, an EscrowFinish with a fulfillment requires a minimum transaction cost of **330 [drops of XRP](../../references/protocol/data-types/basic-data-types.md#specifying-currency-amounts)** plus 10 drops per 16 bytes in the size of the fulfillment**. {% admonition type="info" name="Note" %}The above formula is based on the assumption that the reference cost of a transaction is 10 drops of XRP.{% /admonition %} @@ -90,7 +89,4 @@ For more information about Escrow in the XRP Ledger, see the following: - [Ledger Reference](../../references/protocol/ledger-data/index.md) - [Escrow object](../../references/protocol/ledger-data/ledger-entry-types/escrow.md) - -For more information on Ripple's 55-billion XRP lock-up, see [Ripple's Insights Blog](https://ripple.com/insights/ripple-to-place-55-billion-xrp-in-escrow-to-ensure-certainty-into-total-xrp-supply/). - {% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/concepts/payment-types/payment-channels.md b/docs/concepts/payment-types/payment-channels.md index b560aa6fcc..bc028d1a92 100644 --- a/docs/concepts/payment-types/payment-channels.md +++ b/docs/concepts/payment-types/payment-channels.md @@ -1,24 +1,22 @@ --- -html: payment-channels.html -parent: payment-types.html seo: - description: Payment Channels enable fast, asynchronous XRP payments that can be divided into very small increments and settled later. + description: Payment Channels enable fast, asynchronous payments that can be divided into very small increments and settled later. labels: - Payment Channels - Smart Contracts --- # Payment Channels -Payment Channels are an advanced feature for sending "asynchronous" XRP payments that can be divided into very small increments and settled later. +Payment Channels are an advanced feature for sending "asynchronous" payments that can be divided into very small increments and settled later. -The XRP for a payment channel is set aside temporarily. The sender creates _Claims_ against the channel, which the recipient verifies without sending an XRP Ledger transaction or waiting for a new ledger version to be approved by [consensus](../consensus-protocol/index.md). (This is an _asynchronous_ process because it happens separate from the usual pattern of getting transactions approved by consensus.) At any time, the recipient can _redeem_ a Claim to receive an amount of XRP authorized by that Claim. Settling a Claim like this uses a standard XRP Ledger transaction, as part of the usual consensus process. This single transaction can encompass any number of transactions guaranteed by smaller Claims. +The XRP or fungible tokens for a payment channel are set aside temporarily. The sender creates _Claims_ against the channel, which the recipient verifies without sending an XRP Ledger transaction or waiting for a new ledger version to be approved by [consensus](../consensus-protocol/index.md). (This is an _asynchronous_ process because it happens separate from the usual pattern of getting transactions approved by consensus.) At any time, the recipient can _redeem_ a Claim to receive an amount of XRP or fungible tokens authorized by that Claim. Settling a Claim like this uses a standard XRP Ledger transaction, as part of the usual consensus process. This single transaction can encompass any number of transactions guaranteed by smaller Claims. Because Claims can be verified individually but settled in bulk later, payment channels make it possible to conduct transactions at a rate only limited by the participants' ability to create and verify the digital signatures of those Claims. This limit is primarily based on the speed of the participants' hardware and the complexity of the signature algorithms. For maximum speed, use Ed25519 signatures, which are faster than the XRP Ledger's default secp256k1 ECDSA signatures. Research has [demonstrated the ability to create over Ed25519 100,000 signatures per second and to verify over 70,000 per second](https://ed25519.cr.yp.to/ed25519-20110926.pdf) on commodity hardware in 2011. ## Why Use Payment Channels -The process of using a payment channel always involves two parties, a payer and a payee. The payer is an individual person or institution using the XRP Ledger who is a customer of the payee. The payee is a person or business who receives XRP as payment for goods or services. +The process of using a payment channel always involves two parties, a payer and a payee. The payer is an individual person or institution using the XRP Ledger who is a customer of the payee. The payee is a person or business who receives XRP or fungible tokens as payment for goods or services. Payment Channels do not intrinsically specify anything about what you can buy and sell with them. However, the types of goods and services that are a good fit for payment channels are: @@ -26,18 +24,16 @@ Payment Channels do not intrinsically specify anything about what you can buy an - Inexpensive things, where the cost of processing a transaction is a non-trivial part of the price - Things normally bought in bulk, where the exact quantity desired is not known in advance - ## Payment Channel Lifecycle The following diagram summarizes the lifecycle of a payment channel: [{% inline-svg file="/docs/img/paychan-flow.svg" /%}](/docs/img/paychan-flow.svg "Payment Channel Flow Diagram") - ## See Also - **Related Concepts:** - - [Escrow](escrow.md), a similar feature for higher-value, lower-speed conditional XRP payments. + - [Escrow](escrow.md), a similar feature for higher-value, lower-speed conditional payments. - **Tutorials and Use Cases:** - [Use Payment Channels](../../tutorials/how-tos/use-specialized-payment-types/use-payment-channels/index.md), a tutorial stepping through the process of using a payment channel. - [Open a Payment Channel to Enable an Inter-Exchange Network](../../tutorials/how-tos/use-specialized-payment-types/use-payment-channels/open-a-payment-channel-to-enable-an-inter-exchange-network.md) diff --git a/docs/concepts/tokens/decentralized-exchange/permissioned-dex-roles.svg b/docs/concepts/tokens/decentralized-exchange/permissioned-dex-roles.svg new file mode 100644 index 0000000000..4fbbdbd77e --- /dev/null +++ b/docs/concepts/tokens/decentralized-exchange/permissioned-dex-roles.svg @@ -0,0 +1,160 @@ + + +Tracy(Trader inpermissioned DEX)Order BookUSD.Acme:FOO.WayGateDomainID: Domain A10 FOO : 10 USD – Marko9 FOO : 15 USD – Tracy...Domain AOwner: OwenAccepted Credentials:- "Accredited" issued by Isabel- "Accredited" issued by OwenOwen(credential issuer and domain owner)CredentialType: "Accredited"Issuer: OwenSubject: Tracyholdsgrants accessissues diff --git a/docs/concepts/tokens/decentralized-exchange/permissioned-dex-structure.svg b/docs/concepts/tokens/decentralized-exchange/permissioned-dex-structure.svg new file mode 100644 index 0000000000..1d3305a7c5 --- /dev/null +++ b/docs/concepts/tokens/decentralized-exchange/permissioned-dex-structure.svg @@ -0,0 +1,164 @@ + + +Order BookEUR:JPYDomainID: BOrder BookJPY:EURDomainID: BPermissioned DEX AOrder BookUSD:FOOOrder BookBAR:BAZOrder BookFOO:USDOrder BookFOO:XRPOrder BookXRP:FOOOpen DEXOrder BookEUR:JPYDomainID: AOrder BookUSD:FOODomainID: AOrder BookFOO:XRPDomainID: APermissioned DEX B diff --git a/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md b/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md new file mode 100644 index 0000000000..9ebbff4d4a --- /dev/null +++ b/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md @@ -0,0 +1,84 @@ +--- +seo: + description: The definition and details of a Permissioned Domain instance. +labels: + - Compliance + - Decentralized Exchange +--- +# Permissioned DEXes + +Permissioned DEXes are controlled environments for trading within the XRP Ledger's [decentralized exchange (DEX)](./index.md). Trading in a permissioned DEX works like trading in the open DEX, except that a [_permissioned domain_](./permissioned-domains.md) controls who can place and accept offers. By relying on permissioned DEXes, regulated businesses can participate in trading on the XRP Ledger while ensuring that all the counterparties they deal with have been properly vetted. + +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 + +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: + +- [Decentralized Exchange](./index.md) +- [Offers](./offers.md) +- [Permissioned Domains](./permissioned-domains.md) + + +## Roles + +To use a permissioned DEX, parties with the following roles and responsibilities need to exist: + +- At least two traders to place matching offers. For example, one selling USD for XRP and one selling XRP for USD. +- A permissioned domain owner, who controls which credentials give access to the domain. +- A credential issuer, who issues credentials to accounts they approve. + +It is possible for a single account to play more than one of these roles. For example, you could be the permissioned domain owner, credential issuer, _and_ a trader all at once. The only restriction is that the traders must be different accounts. + +{% inline-svg file="./permissioned-dex-roles.svg" /%} + +_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 + +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. + +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. + +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. + +In summary, see the following table summarizing what offers can match: + +| Offer/Payment Type | Open Offer | Hybrid Offer | Permissioned Offer | AMM | +|--------------------|------------|--------------|--------------------|-----| +| Open | ✅ | ✅ | ❌ | ✅ | +| 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. + +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. + +{% inline-svg file="./permissioned-dex-structure.svg" /%} + +_Figure: The open DEX, and two different permissioned DEXes, each containing order books for a subset of possible currency pairs._ + + +### 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: + +- 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. + +### Limitations + +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. + +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. diff --git a/docs/concepts/transactions/batch-transactions.md b/docs/concepts/transactions/batch-transactions.md new file mode 100644 index 0000000000..d91456d110 --- /dev/null +++ b/docs/concepts/transactions/batch-transactions.md @@ -0,0 +1,160 @@ +--- +seo: + description: Batch allows up to 8 transactions to be submitted as a single unit. +labels: + - Batch + - Transactions +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. + +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. +- Trying out a few offers: Submit multiple offers with different amounts of slippage, but only one will succeed. +- Platform fees: Package platform fees within the transaction itself, simplifying the process. +- Swaps (multi-account): Trustless token/NFT swaps between multiple accounts. +- Withdrawing accounts (multi-account): Attempt a withdrawal from your checking account, and if that fails, withdraw from your savings account instead. + +`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 + +There are four possible batch modes: `ALLORNOTHING`, `ONLYONE`, `UNTILFAILURE`, and `INDEPENDENT`. + +### All or Nothing + +In `ALLORNOTHING` mode, all inner transactions must succeed for any one of them to succeed. + +### Only One + +`ONLYONE` mode means that the first transaction to succeed is the only one to succeed. All other transactions either failed or were never tried. + +### Until Failure + +`UNTILFAILURE` applies all transactions until the first failure. All transactions after the first failure are not applied. + +### Independent + +All transactions are applied, even if one or more of the inner transactions fail. + +## Raw Transactions + +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. + +Each inner transaction: + +- Must set the `tfInnerBatchTxn` flag. +- Must not have a fee. It must use a fee value of _0_. +- Must not be signed (the global transaction is already signed by all relevant parties). They must instead have an empty string ("") in the `SigningPubKey` and `TxnSignature` fields. + +A transaction is considered a failure if it receives any result that is not `tesSUCCESS`. + +### Transaction Common Flag + +`Batch` adds a global transaction flag. + +| Flag Name | Value | +|-------------------|------------| +| `tfInnerBatchTxn` | 0x40000000 | + +This flag is only used if a transaction is an inner transaction in a Batch transaction. This signifies that the transaction isn't signed. Any normal transaction that includes this flag is rejected. + +### BatchSigners + +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`. It is only needed if multiple accounts' transactions are included in the `Batch` transaction; otherwise, the normal transaction signature provides the same security guarantees. + +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). + +Each object in this array contains the following fields: + +| Field Name | Required? | JSON Type | Internal Type | +|---------------|-----------|-----------|---------------| +| Account | yes | string | STAccount | +| SigningPubKey | no | string | STBlob | +| TxnSignature | no | string | STBlob | +| Signers | no | array | STArray | + +Either the `SigningPubKey` and `TxnSignature` fields must be included, or the `Signers` field. + +#### Account + +This is an account that has at least one inner transaction. + +#### SigningPubKey and TxnSignature + +These fields are included if the account is signing with a single signature (as opposed to multi-sign). They sign the `Flags` field and the hashes of the transactions in `RawTransactions`. + +#### Signers + +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 + +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: + +2 * (Base Fee) + SUM(Inner Transaction Fees) + An additional Base Fee for each additional signature + +The fees for the individual inner transactions are paid in the outer transaction rather than the inner transactions themselves, to ensure that fee escalation is calculated on the total cost of the batch transaction and not just the overhead. + +## Metadata + +Inner transactions are committed separately to the ledger and therefore have separate metadata. This ensures better backward compatibility for legacy systems, so that they can support `Batch` transactions without needing changes to their systems. + +For example, a ledger that only has one `Batch` transaction containing 2 inner transactions would look like this: + +``` +[ + OuterTransaction, + InnerTransaction1, + InnerTransaction2 +] +``` + +### Outer Transaction + +Each outer transaction contains the metadata for its sequence and fee processing, not for the inner transaction processing. Any error code is only based on the outer transaction processing (for example, sequence and fee), and it returns a tesSUCCESS error even if inner transaction processing fails. + +### Inner Transaction + +Each inner transaction contains the metadata for its own processing. Only the inner transactions that are actually committed to the ledger are included. This makes it easier for legacy systems to process `Batch` transactions as if they were normal. + +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: + +| Flag Name | Value | +|-----------------|------------| +| tfInnerBatchTxn | 0x40000000 | + +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 + +Batch transactions come with additional security considerations. + +### Trust Assumptions + +Regardless of how many accounts' transactions are included in a `Batch` transaction, all accounts need to sign the collection of transactions. + +#### Single Account + +In the single account case, the single account must approve all of the transactions it is submitting. No other accounts are involved. + +#### Multi Account + +The multi-account case is a bit more complicated and is best illustrated with an example. + +Alice and Bob are conducting a trustless swap via a multi-account `Batch`, with Alice providing 1000 XRP and Bob providing 1000 USD. Bob submits the `Batch` transaction, so Alice must provide her part of the swap to him. + +If Alice provides a fully autofilled and signed transaction to Bob, Bob can submit Alice's transaction on the ledger without submitting his and receive the 1000 XRP without losing his 1000 USD. Therefore, the inner transactions must be unsigned. + +If Alice just signs her part of the Batch transaction, Bob can modify his transaction to only provide 1 USD instead, thereby getting his 1000 XRP at a much cheaper rate. Therefore, the entire Batch transaction (and all its inner transactions) must be signed by all parties. + +### Inner Transaction Safety +An inner batch transaction is a special case. It doesn't include a signature or a fee (since those are both included in the outer transaction). Therefore, they must be handled carefully to ensure that someone can't somehow directly submit an inner `Batch` transaction without it being included in an outer transaction. + +Inner transactions cannot be broadcast (and won't be accepted if they happen to be broadcast, for example, from a malicious node). They must be generated from the `Batch` outer transaction instead. Inner transactions cannot be directly submitted via the submit RPC. diff --git a/docs/img/_sources/permissioned-dex-roles.uxf b/docs/img/_sources/permissioned-dex-roles.uxf new file mode 100644 index 0000000000..87cf4f0ebb --- /dev/null +++ b/docs/img/_sources/permissioned-dex-roles.uxf @@ -0,0 +1,131 @@ + + + 10 + + UMLPackage + + 300 + 290 + 140 + 80 + + Credential +-- +Type: "Accredited" +Issuer: Owen +Subject: Tracy +halign=left + + + + Relation + + 210 + 310 + 110 + 40 + + lt=<<. +issues + 90.0;20.0;10.0;20.0 + + + UMLActor + + 120 + 300 + 160 + 140 + + Owen +(credential issuer +and domain owner) + + + + Relation + + 170 + 150 + 270 + 180 + + lt=<<. +r1=grants access + 10.0;10.0;10.0;40.0;230.0;40.0;230.0;150.0;250.0;160.0 + + + UMLClass + + 290 + 60 + 190 + 140 + + Domain A +-- +Owner: Owen +Accepted Credentials: +- "Accredited" issued + by Isabel +*- "Accredited" issued* +* by Owen* + + + + UMLClass + + 20 + 20 + 200 + 140 + + Order Book +USD.Acme:FOO.WayGate +-- +*DomainID: Domain A* +-- +10 FOO : 10 USD – Marko +- +9 FOO : 15 USD – Tracy +-- +... + + + + Relation + + 190 + 60 + 120 + 30 + + lt=<<. + 100.0;10.0;10.0;10.0 + + + UMLActor + + 450 + 300 + 160 + 140 + + Tracy +(Trader in +permissioned DEX) + + + + Relation + + 430 + 310 + 110 + 40 + + lt=.>> +holds + 90.0;20.0;10.0;20.0 + + diff --git a/docs/img/_sources/permissioned-dex-structure.uxf b/docs/img/_sources/permissioned-dex-structure.uxf new file mode 100644 index 0000000000..6b37f3ed21 --- /dev/null +++ b/docs/img/_sources/permissioned-dex-structure.uxf @@ -0,0 +1,175 @@ + + + 10 + + UMLClass + + 540 + 30 + 250 + 290 + + lt=. +Permissioned DEX B + + + + UMLPackage + + 410 + 80 + 110 + 70 + + Order Book +-- +FOO:XRP +DomainID: A + + + + UMLPackage + + 290 + 160 + 110 + 70 + + Order Book +-- +USD:FOO +DomainID: A + + + + UMLPackage + + 410 + 240 + 110 + 70 + + Order Book +-- +EUR:JPY +DomainID: A + + + + UMLClass + + 20 + 30 + 250 + 290 + + lt=. +Open DEX + + + + UMLPackage + + 30 + 80 + 110 + 70 + + Order Book +-- +XRP:FOO + + + + UMLPackage + + 150 + 80 + 110 + 70 + + Order Book +-- +FOO:XRP + + + + UMLPackage + + 150 + 160 + 110 + 70 + + Order Book +-- +FOO:USD + + + + UMLPackage + + 30 + 240 + 110 + 70 + + Order Book +-- +BAR:BAZ + + + + UMLPackage + + 30 + 160 + 110 + 70 + + Order Book +-- +USD:FOO + + + + UMLClass + + 280 + 30 + 250 + 290 + + lt=. +Permissioned DEX A + + + + UMLPackage + + 550 + 240 + 110 + 70 + + Order Book +-- +JPY:EUR +DomainID: B + + + + UMLPackage + + 670 + 240 + 110 + 70 + + Order Book +-- +EUR:JPY +DomainID: B + + + diff --git a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_channels.md b/docs/references/http-websocket-apis/public-api-methods/account-methods/account_channels.md index 598645ad2e..e09a6cf166 100644 --- a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_channels.md +++ b/docs/references/http-websocket-apis/public-api-methods/account-methods/account_channels.md @@ -59,11 +59,14 @@ The request includes the following parameters: | Field | Type | Required? | Description | |:----------------------|:---------------------|:----------|-------------| | `account` | String - [Address][] | Yes | Look up channels where this account is the channel's owner/source. | +| `amount` | Object or String | No | The total amount allocated to this channel. | +| `balance` | Object or String | No | The total amount paid out from this channel, as of the ledger version used. (You can calculate the amount left in the channel by subtracting `balance` from `amount`). | | `destination_account` | String - [Address][] | No | A second account; if provided, filter results to payment channels whose destination is this account. | | `ledger_hash` | String | No | The unique hash of the ledger version to use. (See [Specifying Ledgers][]) | | `ledger_index` | Number or String | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) | | `limit` | Number | No | Limit the number of transactions to retrieve. Cannot be less than 10 or more than 400. Positive values outside this range are replaced with the closest valid option. The default is 200. | | `marker` | [Marker][] | No | Value from a previous paginated response. Resume retrieving data where that response left off. | +| `transfer_rate` | Number | No | The fee to charge when users make claims on a payment channel, initially set on the creation of a payment channel and updated on subsequent funding or claim transactions. | ## Response Format @@ -174,10 +177,10 @@ Each Channel Object has the following fields: | Field | Type | Description | |:----------------------|:-----------------|:----------------------------------| | `account` | String | The owner of the channel, as an [Address][]. | -| `amount` | String | The total amount of [XRP, in drops][] allocated to this channel. | -| `balance` | String | The total amount of [XRP, in drops][], paid out from this channel, as of the ledger version used. (You can calculate the amount of XRP left in the channel by subtracting `balance` from `amount`.) | +| `amount` | Object or String | The total amount of [XRP, in drops][] or fungible tokens allocated to this channel. | +| `balance` | String | The total amount of [XRP, in drops][] or fungible tokens paid out from this channel, as of the ledger version used. (You can calculate the amount left in the channel by subtracting `balance` from `amount`.) | | `channel_id` | String | A unique ID for this channel, as a 64-character hexadecimal string. This is also the [ID of the channel object](../../../protocol/ledger-data/ledger-entry-types/paychannel.md#paychannel-id-format) in the ledger's state data. | -| `destination_account` | String | The destination account of the channel, as an [Address][]. Only this account can receive the XRP in the channel while it is open. | +| `destination_account` | String | The destination account of the channel, as an [Address][]. Only this account can receive the `amount` in the channel while it is open. | | `settle_delay` | Unsigned Integer | The number of seconds the payment channel must stay open after the owner of the channel requests to close it. | | `public_key` | String | _(May be omitted)_ The public key for the payment channel in the XRP Ledger's [base58][] format. Signed claims against this channel must be redeemed with the matching key pair. | | `public_key_hex` | String | _(May be omitted)_ The public key for the payment channel in hexadecimal format, if one was specified at channel creation. Signed claims against this channel must be redeemed with the matching key pair. | diff --git a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines.md b/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines.md index ff7f7458f2..1ff39ac46b 100644 --- a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines.md +++ b/docs/references/http-websocket-apis/public-api-methods/account-methods/account_lines.md @@ -65,6 +65,8 @@ The request accepts the following parameters: | `limit` | Number | No | Limit the number of trust lines to retrieve. The server may return less than the specified limit, even if there are more pages of results. Must be within the inclusive range 10 to 400. Positive values outside this range are replaced with the closest valid option. The default is 200. | | `marker` | [Marker][] | No | Value from a previous paginated response. Resume retrieving data where that response left off. | | `peer` | String - [Address][] | No | A second account; if provided, filter results to trust lines connecting the two accounts. | +| `locked_balance` | Object | No | The total amount locked in payment channels or escrow. | +| `lock_count` | Number | UInt32 | No | the total number of lock balances on a RippleState ledger object. | The following parameters are deprecated and may be removed without further notice: `ledger` and `peer_index`. diff --git a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md b/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md index 69f9cdfac5..b59a919901 100644 --- a/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md +++ b/docs/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md @@ -79,11 +79,13 @@ The request includes the following parameters: | `Field` | Type | Required? | Description | |:-------------------------|:-----------------|:----------|-------------| | `account` | String | Yes | A unique identifier for the account, most commonly the account's [Address][]. | +| `amount` | Object or String | No | The amount to be delivered by the held payment. | | `deletion_blockers_only` | Boolean | No | If `true`, the response only includes objects that would block this account from [being deleted](../../../../concepts/accounts/deleting-accounts.md). The default is `false`. | | `ledger_hash` | [Hash][] | No | The unique hash of the ledger version to use. (See [Specifying Ledgers][]) | | `ledger_index` | [Ledger Index][] | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) | | `limit` | Number | No | The maximum number of objects to include in the results. Must be within the inclusive range `10` to `400` on non-admin connections. The default is `200`. | | `marker` | [Marker][] | No | Value from a previous paginated response. Resume retrieving data where that response left off. | +| `transfer_rate` | Number | No | The fee to charge when users finish an escrow, initially set on the creation of an escrow contract, and updated on subsequent finish transactions. | | `type` | String | No | Filter results to a specific type of ledger entry. This field accepts canonical ledger entry names (case insensitive) or short names. | Valid `type` field values are: diff --git a/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md b/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md index d2ce353a0c..1c60cdae1e 100644 --- a/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md +++ b/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md @@ -1,6 +1,4 @@ --- -html: book_offers.html -parent: path-and-order-book-methods.html seo: description: Get info about offers to exchange two currencies. labels: @@ -10,7 +8,7 @@ labels: # book_offers [[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/BookOffers.cpp "Source") -The `book_offers` method retrieves a list of [Offers](../../../../concepts/tokens/decentralized-exchange/offers.md) between two currencies, also known as an _order book_. The response omits [unfunded Offers](../../../../concepts/tokens/decentralized-exchange/offers.md#lifecycle-of-an-offer) and reports how much of each remaining Offer's total is currently funded. +The `book_offers` method retrieves a list of [offers](../../../../concepts/tokens/decentralized-exchange/offers.md) between two currencies, also known as an _order book_. The response omits [unfunded offers](../../../../concepts/tokens/decentralized-exchange/offers.md#lifecycle-of-an-offer) and reports how much of each remaining offer's total is currently funded. ## Request Format An example of the request format: @@ -71,11 +69,12 @@ The request includes the following parameters: | `Field` | Type | Required? | Description | |:---------------|:-----------------|:----------|-------------| -| `taker_gets` | Object | Yes | The asset the account taking the Offer would receive, as a [currency without an amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). | -| `taker_pays` | Object | Yes | The asset the account taking the Offer would pay, as a [currency without an amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). | +| `taker_gets` | Object | Yes | The asset the account taking the offer would receive, as a [currency without an amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). | +| `taker_pays` | Object | Yes | The asset the account taking the offer would pay, as a [currency without an amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). | +| `domain` | [Hash][] | No | The ledger entry ID of a permissioned domain. If provided, return offers from the corresponding [permissioned DEX](../../../../concepts/tokens/decentralized-exchange/permissioned-dexes.md) instead of using the open DEX. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | | `ledger_hash` | [Hash][] | No | The unique hash of the ledger version to use. (See [Specifying Ledgers][]) | | `ledger_index` | [Ledger Index][] | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) | -| `limit` | Number | No | The maximum number of Offers to return. The response may include fewer results. | +| `limit` | Number | No | The maximum number of offers to return. The response may include fewer results. | | `taker` | String | No | The [Address][] of an account to use as a perspective. The response includes this account's Offers even if they are unfunded. (You can use this to see what Offers are above or below yours in the order book.) | @@ -242,9 +241,9 @@ The response follows the [standard format][], with a successful result containin | `ledger_current_index` | [Ledger Index][] | _(Omitted if `ledger_current_index` is provided)_ The [ledger index][] of the current in-progress ledger version, which was used to retrieve this information. | | `ledger_index` | [Ledger Index][] | _(Omitted if `ledger_current_index` provided)_ The ledger index of the ledger version that was used when retrieving this data, as requested. | | `ledger_hash` | [Hash][] | _(May be omitted)_ The identifying hash of the ledger version that was used when retrieving this data, as requested. | -| `offers` | Array | Array of offer objects, each of which has the fields of an [Offer object](../../../protocol/ledger-data/ledger-entry-types/offer.md) | +| `offers` | Array | Array of offer objects, as described below: | -In addition to the standard Offer fields, the following fields may be included in members of the `offers` array: +Each member of the `offers` array contains canonical fields of an [Offer entry][] and can also contain the following additional fields: | `Field` | Type | Description | |:--------------------|:--------------------|:--------------------| diff --git a/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/path_find.md b/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/path_find.md index 8c8c23f346..bd8ecce764 100644 --- a/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/path_find.md +++ b/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/path_find.md @@ -55,14 +55,16 @@ An example of the request format: The request includes the following parameters: -| `Field` | Type | Description | -|:----------------------|:-----------------|:----------------------------------| -| `subcommand` | String | Use `"create"` to send the create sub-command | -| `source_account` | String | Unique address of the account to find a path from. (In other words, the account that would be sending a payment.) | -| `destination_account` | String | Unique address of the account to find a path to. (In other words, the account that would receive a payment.) | -| `destination_amount` | String or Object | [Currency Amount][] that the destination account would receive in a transaction. **Special case:** You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). | -| `send_max` | String or Object | _(Optional)_ [Currency Amount][] that would be spent in the transaction. Not compatible with `source_currencies`. | -| `paths` | Array | _(Optional)_ Array of arrays of objects, representing [payment paths](../../../../concepts/tokens/fungible-tokens/paths.md) to check. You can use this to keep updated on changes to particular paths you already know about, or to check the overall cost to make a payment along a certain path. | +| Field | Type | Required? | Description | +|:----------------------|:---------------------|:----------|:------------| +| `subcommand` | String | Yes | Use `"create"` to send the create sub-command | +| `source_account` | String - [Address][] | Yes | The account to find a path from. (In other words, the account that would be sending a payment.) | +| `destination_account` | String - [Address][] | Yes | The account to find a path to. (In other words, the account that would receive a payment.) | +| `destination_amount` | [Currency Amount][] | Yes | How much the destination account would receive. **Special case:** You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for tokens). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). | +| `domain` | String - [Hash][] | No | The ledger entry ID of a permissioned domain. If provided, only return paths that use the corresponding [permissioned DEX](../../../../concepts/tokens/decentralized-exchange/permissioned-dexes.md). _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | +| `paths` | Array | No | Array of arrays of objects, representing [payment paths](../../../../concepts/tokens/fungible-tokens/paths.md) to check. +| `send_max` | [Currency Amount][] | No | Maximum amount that would be spent. Not compatible with `source_currencies`. | +You can use this to keep updated on changes to particular paths you already know about, or to check the overall cost to make a payment along a certain path. | The server also recognizes the following fields, but the results of using them are not guaranteed: `source_currencies`, `bridges`. These fields should be considered reserved for future use. diff --git a/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/ripple_path_find.md b/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/ripple_path_find.md index dadc1988a8..1dc0bf439c 100644 --- a/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/ripple_path_find.md +++ b/docs/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/ripple_path_find.md @@ -85,15 +85,16 @@ rippled ripple_path_find '{"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 The request includes the following parameters: -| `Field` | Type | Description | -|:----------------------|:---------------------------|:------------------------| -| `source_account` | String | Unique address of the account that would send funds in a transaction | -| `destination_account` | String | Unique address of the account that would receive funds in a transaction | -| `destination_amount` | String or Object | [Currency Amount][] that the destination account would receive in a transaction. **Special case:** You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). | -| `send_max` | String or Object | _(Optional)_ [Currency Amount][] that would be spent in the transaction. Cannot be used with `source_currencies`. | -| `source_currencies` | Array | _(Optional)_ Array of currencies that the source account might want to spend. Each entry in the array should be a JSON object with a mandatory `currency` field and optional `issuer` field, like how [currency amounts][Currency Amount] are specified. Cannot contain more than **18** source currencies. By default, uses all source currencies available up to a maximum of **88** different currency/issuer pairs. | -| `ledger_hash` | String | _(Optional)_ The unique hash of the ledger version to use. (See [Specifying Ledgers][]) | -| `ledger_index` | String or Unsigned Integer | _(Optional)_ The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) | +| Field | Type | Required? | Description | +|:----------------------|:---------------------|:----------|:------------| +| `source_account` | String - [Address][] | Yes | The account that would send funds | +| `destination_account` | String - [Address][] | Yes | The account that would receive funds | +| `destination_amount` | [Currency Amount][] | Yes | How much the destination account would receive. **Special case:** You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for tokens). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). | +| `domain` | String - [Hash][] | No | The ledger entry ID of a permissioned domain. If provided, only return paths that use the corresponding [permissioned DEX](../../../../concepts/tokens/decentralized-exchange/permissioned-dexes.md). _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | +| `ledger_hash` | String - [Hash][] | No | The unique hash of the ledger version to use. (See [Specifying Ledgers][]) | +| `ledger_index` | [Ledger Index][] | No | The ledger index of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) | +| `send_max` | [Currency Amount][] | No | Maximum amount that would be spent. Cannot be used with `source_currencies`. | +| `source_currencies` | Array | No | Array of currencies that the source account might want to spend. Each entry in the array should be a JSON object with a mandatory `currency` field and optional `issuer` field, like how [currency amounts][Currency Amount] are specified. Cannot contain more than **18** source currencies. By default, uses all source currencies available up to a maximum of **88** different currency/issuer pairs. | ## Response Format diff --git a/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_authorize.md b/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_authorize.md index ee3273cd5e..f057876f24 100644 --- a/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_authorize.md +++ b/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_authorize.md @@ -11,7 +11,7 @@ labels: _(Added by the [PayChan amendment][] to be enabled.)_ -The `channel_authorize` method creates a signature that can be used to redeem a specific amount of XRP from a payment channel. +The `channel_authorize` method creates a signature that can be used to redeem a specific amount of XRP or fungible tokens from a payment channel. ## Request Format An example of the request format: @@ -67,7 +67,7 @@ The request includes the following parameters: | `seed_hex` | String | _(Optional)_ The secret seed to use to sign the claim. This must be the same key pair as the public key specified in the channel. Must be in hexadecimal format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `passphrase`. | | `passphrase` | String | _(Optional)_ A string passphrase to use to sign the claim. This must be the same key pair as the public key specified in the channel. The [key derived from this passphrase](../../../../concepts/accounts/cryptographic-keys.md#key-derivation) must match the public key specified in the channel. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `seed_hex`. | | `key_type` | String | _(Optional)_ The [signing algorithm](../../../../concepts/accounts/cryptographic-keys.md#signing-algorithms) of the cryptographic key pair provided. Valid types are `secp256k1` or `ed25519`. The default is `secp256k1`. | -| `amount` | String | Cumulative amount of XRP, in drops, to authorize. If the destination has already received a lesser amount of XRP from this channel, the signature created by this method can be redeemed for the difference. | +| `amount` | Object or String | Cumulative amount of XRP, in drops, or fungible tokens to authorize. If the destination has already received a lesser amount from this channel, the signature created by this method can be redeemed for the difference. | The request **must** specify exactly one of `secret`, `seed`, `seed_hex`, or `passphrase`. @@ -121,14 +121,14 @@ The response follows the [standard format][], with a successful result containin | Field | Type | Description | |-------|------|-------------| -| `signature` | String | The signature for this claim, as a hexadecimal value. To process the claim, the destination account of the payment channel must send a [PaymentChannelClaim transaction][] with this signature, the exact Channel ID, XRP amount, and public key of the channel. | +| `signature` | String | The signature for this claim, as a hexadecimal value. To process the claim, the destination account of the payment channel must send a [PaymentChannelClaim transaction][] with this signature, the exact Channel ID, amount, and public key of the channel. | ## Possible Errors * Any of the [universal error types][]. * `badKeyType` - The `key_type` parameter in the request is not a valid key type. (Valid types are `secp256k1` or `ed25519`.) * `badSeed` - The `secret` in the request is not a valid secret key. -* `channelAmtMalformed` - The `amount` in the request is not a valid [XRP amount][XRP, in drops]. +* `channelAmtMalformed` - The `amount` in the request is not a valid amount. * `channelMalformed` - The `channel_id` in the request is not a valid Channel ID. The Channel ID should be a 256-bit (64-character) hexadecimal string. {% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_verify.md b/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_verify.md index a39db789e4..9ec605ec34 100644 --- a/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_verify.md +++ b/docs/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_verify.md @@ -11,7 +11,7 @@ labels: _(Added by the [PayChan amendment][] to be enabled.)_ -The `channel_verify` method checks the validity of a signature that can be used to redeem a specific amount of XRP from a payment channel. +The `channel_verify` method checks the validity of a signature that can be used to redeem a specific amount of XRP or fungible tokens from a payment channel. ## Request Format An example of the request format: @@ -58,8 +58,8 @@ The request includes the following parameters: | Field | Type | Description | |-------|------|-------------| -| `amount` | String | The amount of [XRP, in drops][], the provided `signature` authorizes. | -| `channel_id` | String | The Channel ID of the channel that provides the XRP. This is a 64-character hexadecimal string. | +| `amount` | Object or String | The amount of [XRP, in drops][], or fungible tokens the provided `signature` authorizes. | +| `channel_id` | String | The Channel ID of the channel that provides the amount. This is a 64-character hexadecimal string. | | `public_key` | String | The public key of the channel and the key pair that was used to create the signature, in hexadecimal or the XRP Ledger's [base58][] format. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.90.0" %}Updated in: rippled 0.90.0{% /badge %} | | `signature` | String | The signature to verify, in hexadecimal. | @@ -114,7 +114,7 @@ The response follows the [standard format][], with a successful result containin |-------|------|-------------| | `signature_verified` | Boolean | If `true`, the signature is valid for the stated amount, channel, and public key. | -{% admonition type="warning" name="Caution" %}This does not indicate check that the channel has enough XRP allocated to it. Before considering a claim valid, you should look up the channel in the latest validated ledger and confirm that the channel is open and its `amount` value is equal or greater than the `amount` of the claim. To do so, use the [account_channels method][].{% /admonition %} +{% admonition type="warning" name="Caution" %}This does not check whether the channel has enough XRP allocated to it. Before considering a claim valid, you should look up the channel in the latest validated ledger and confirm that the channel is open and its `amount` value is equal or greater than the `amount` of the claim. To do so, use the [account_channels method][].{% /admonition %} ## Possible Errors diff --git a/docs/references/http-websocket-apis/public-api-methods/subscription-methods/subscribe.md b/docs/references/http-websocket-apis/public-api-methods/subscription-methods/subscribe.md index c4548185de..b592f11ca2 100644 --- a/docs/references/http-websocket-apis/public-api-methods/subscription-methods/subscribe.md +++ b/docs/references/http-websocket-apis/public-api-methods/subscription-methods/subscribe.md @@ -10,7 +10,7 @@ labels: - Smart Contracts --- # subscribe -[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/Subscribe.cpp "Source") +[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/rpc/handlers/Subscribe.cpp "Source") The `subscribe` method requests periodic notifications from the server when certain events happen. @@ -66,42 +66,47 @@ An example of the request format: The request includes the following parameters: -| `Field` | Type | Description | -|:--------------------|:-------|:----------------------------------------------| -| `streams` | Array | _(Optional)_ Array of string names of generic streams to subscribe to, as explained below | -| `accounts` | Array | _(Optional)_ Array with the unique addresses of accounts to monitor for validated transactions. The addresses must be in the XRP Ledger's [base58][] format. The server sends a notification for any transaction that affects at least one of these accounts. | -| `accounts_proposed` | Array | _(Optional)_ Like `accounts`, but include transactions that are not yet finalized. | -| `books` | Array | _(Optional)_ Array of objects defining [order books](http://www.investopedia.com/terms/o/order-book.asp) to monitor for updates, as detailed below. | -| `url` | String | (Optional for Websocket; Required otherwise) URL where the server sends a JSON-RPC callbacks for each event. *Admin-only.* | -| `url_username` | String | _(Optional)_ Username to provide for basic authentication at the callback URL. | -| `url_password` | String | _(Optional)_ Password to provide for basic authentication at the callback URL. | +| Field | Type | Required? | Description | +|:--------------------|:-------|:----------|:------------| +| `streams` | Array | No | Streams to subscribe to, as explained below. Each member of the array must be the string name of a stream. | +| `accounts` | Array | No | Array with the unique [addresses][Address] of accounts to monitor for validated transactions. The server sends a `transaction` type message whenever a transaction affects at least one of these accounts. | +| `accounts_proposed` | Array | No | Like `accounts`, but include transactions that are not yet finalized. | +| `books` | Array | No | Order books to monitor for updates. Each member of the array must be a [book object](#book-objects), as defined below. The server sends a `transaction` type message whenever a transaction affects this account. | +| `url` | String | Optional for Websocket; Required for JSON-RPC | **(Admin only)** URL where the server sends JSON-RPC callbacks for each event. | +| `url_username` | String | No | Username to provide for basic authentication at the callback URL. | +| `url_password` | String | No | Password to provide for basic authentication at the callback URL. | The following parameters are deprecated and may be removed without further notice: `user`, `password`, `rt_accounts`. The `streams` parameter provides access to the following default streams of information: -- `book_changes` - Sends a message with order book changes whenever the consensus process declares a new validated ledger. -- `consensus` - Sends a message whenever the server changes phase in the consensus cycle. -- `ledger` - Sends a message whenever the consensus process declares a new validated ledger. -- `manifests` - Sends a message whenever the server receives an update to a validator's ephemeral signing key. -- `peer_status` - **(Admin only)** Information about connected peer `rippled` servers, especially with regards to the consensus process. -- `transactions` - Sends a message whenever a transaction is included in a closed ledger. -- `transactions_proposed` - Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation. - {% admonition type="info" name="Note" %}[Even some transactions that don't succeed are included](../../../protocol/transactions/transaction-results/index.md) in validated ledgers, because they take the anti-spam transaction fee.{% /admonition %} -- `server` - Sends a message whenever the status of the `rippled` server (for example, network connectivity) changes. -- `validations` - Sends a message whenever the server receives a validation message, regardless of if the server trusts the validator. (An individual `rippled` declares a ledger validated when the server receives validation messages from at least a quorum of trusted validators.) +| Stream Name | Message Type | Description | +|:------------------------|:---------------------|:------------| +| `book_changes` | `bookChanges` | Sends order book changes whenever the consensus process declares a new validated ledger. | +| `consensus` | `consensusPhase` | Sends a message whenever the server changes phase in the consensus cycle. | +| `ledger` | `ledgerClosed` | Sends a message whenever the consensus process declares a new validated ledger. | +| `manifests` | `manifestReceived` | Sends a message whenever the server receives an update to a validator's ephemeral signing key. | +| `peer_status` | `peerStatusChange` | **(Admin only)** Information about connected peer `rippled` servers, especially with regards to the consensus process. | +| `transactions` | `transaction` | Sends a message whenever a transaction is included in a closed ledger. | +| `transactions_proposed` | `transaction` | Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation. {% admonition type="info" name="Note" %}[Even some transactions that don't succeed are included](../../../protocol/transactions/transaction-results/index.md) in validated ledgers, because they take the anti-spam transaction fee.{% /admonition %} | +| `server` | `serverStatus` | Sends a message whenever the status of the `rippled` server (for example, network connectivity) changes. | +| `validations` | `validationReceived` | Sends a message whenever the server receives a validation message, regardless of if the server trusts the validator. (An individual `rippled` declares a ledger validated when the server receives validation messages from at least a quorum of trusted validators.) | -{% admonition type="info" name="Note" %}The following streams are not available from Clio and `rippled` servers in [Reporting Mode][]: `server`, `peer_status`, `consensus`. Both will return the `reportingUnsupported` error if you request one of these streams. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.8.1" %}Updated in: rippled 1.8.1{% /badge %} {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" %}New in: Clio v2.0{% /badge %}{% /admonition %} +{% admonition type="info" name="Note" %}The following streams are not available from Clio servers: `server`, `peer_status`, `consensus`. If you request one of these streams, Clio returns the error `reportingUnsupported`. {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" %}New in: Clio v2.0{% /badge %}{% /admonition %} + +### Book Objects Each member of the `books` array, if provided, is an object with the following fields: -| `Field` | Type | Description | -|:-------------|:--------|:----------------------------------------------------| -| `taker_gets` | Object | Specification of which currency the account taking the Offer would receive, as a [currency object with no amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). | -| `taker_pays` | Object | Specification of which currency the account taking the Offer would pay, as a [currency object with no amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). | -| `taker` | String | Unique [account address](../../../../concepts/accounts/index.md) to use as a perspective for viewing offers, in the XRP Ledger's [base58][] format. (This affects the funding status and fees of [Offers](../../../../concepts/tokens/decentralized-exchange/offers.md).) | -| `snapshot` | Boolean | _(Optional)_ If `true`, return the current state of the order book once when you subscribe before sending updates. The default is `false`. | -| `both` | Boolean | _(Optional)_ If `true`, return both sides of the order book. The default is `false`. | +| Field | Type | Required? | Description | +|:-------------|:---------------------|:----------|:------------| +| `taker_gets` | Object - Currency | Yes | Specification of which currency the account taking the offer would receive, as a [currency object with no amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). | +| `taker_pays` | Object - Currency | Yes | Specification of which currency the account taking the offer would pay, as a [currency object with no amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). | +| `both` | Boolean | No | If `true`, return both sides of the order book. The default is `false`. | +| `domain` | String - [Hash][] | No | The ledger entry ID of a permissioned domain. If provided, subscribe to the order books for the corresponding [permissioned DEX](../../../../concepts/tokens/decentralized-exchange/permissioned-dexes.md) instead of the open DEX. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | +| `snapshot` | Boolean | No | If `true`, return the current state of the order book once when you subscribe before sending updates. The default is `false`. | +| `taker` | String - [Address][] | No | The acount to use as a perspective for viewing offers. This affects the funding status and fees of [offers](../../../../concepts/tokens/decentralized-exchange/offers.md). | + ## Response Format @@ -167,7 +172,7 @@ The `ledger` stream only sends `ledgerClosed` messages when [the consensus proce The fields from a ledger stream message are as follows: -| `Field` | Type | Description | +| Field | Type | Description | |:--------------------|:--------------------------|:---------------------------| | `type` | String | `ledgerClosed` indicates this is from the ledger stream | | `fee_base` | Number | The [reference transaction cost](../../../../concepts/transactions/transaction-cost.md#reference-transaction-cost) as of this ledger version, in [drops of XRP][]. If this ledger version includes a [SetFee pseudo-transaction](../../../protocol/transactions/pseudo-transaction-types/setfee.md) the new transaction cost applies starting with the following ledger version. | @@ -212,7 +217,7 @@ The validations stream sends messages whenever it receives validation messages, The fields from a validations stream message are as follows: -| `Field` | Type | Description | +| Field | Type | Description | |:------------------------|:-----------------|:--------------------------------| | `type` | String | The value `validationReceived` indicates this is from the validations stream. | | `amendments` | Array of Strings | _(May be omitted)_ The [amendments](../../../../concepts/networks-and-servers/amendments.md) this server wants to be added to the protocol. | @@ -333,7 +338,7 @@ Transaction stream messages have the following fields: {% tab label="API v2" %} -| `Field` | Type | Description | +| Field | Type | Description | |:------------------------|:--------------------------|:-----------------------| | `close_time_iso` | String | The ledger close time represented in ISO 8601 time format. | | `type` | String | `transaction` indicates this is the notification of a transaction, which could come from several possible streams. | @@ -352,7 +357,7 @@ Transaction stream messages have the following fields: {% tab label="API v1" %} -| `Field` | Type | Description | +| Field | Type | Description | |:------------------------|:--------------------------|:-----------------------| | `type` | String | `transaction` indicates this is the notification of a transaction, which could come from several possible streams. | | `engine_result` | String | String [Transaction result code](../../../protocol/transactions/transaction-results/index.md) | @@ -389,7 +394,7 @@ Example of a Peer Status stream message: Peer Status stream messages represent some event where the status of the peer `rippled` server changed. These messages are JSON objects with the following fields: -| `Field` | Value | Description | +| Field | Value | Description | |:-------------------|:-------|:-----------------------------------------------| | `type` | String | `peerStatusChange` indicates this comes from the Peer Status stream. | | `action` | String | The type of event that prompted this message. See [Peer Status Events](#peer-status-events) for possible values. | diff --git a/docs/references/protocol/ledger-data/ledger-entry-types/directorynode.md b/docs/references/protocol/ledger-data/ledger-entry-types/directorynode.md index 58bf047239..284638129e 100644 --- a/docs/references/protocol/ledger-data/ledger-entry-types/directorynode.md +++ b/docs/references/protocol/ledger-data/ledger-entry-types/directorynode.md @@ -6,14 +6,14 @@ labels: - Decentralized Exchange --- # DirectoryNode -[[Source]](https://github.com/XRPLF/rippled/blob/f64cf9187affd69650907d0d92e097eb29693945/include/xrpl/protocol/detail/ledger_entries.macro#L165-L179 "Source") +[[Source]](https://github.com/XRPLF/rippled/blob/7e24adbdd0b61fb50967c4c6d4b27cc6d81b33f3/include/xrpl/protocol/detail/ledger_entries.macro#L177-L192 "Source") The `DirectoryNode` ledger entry type provides a list of links to other entries in the ledger's state data. A single conceptual _Directory_ takes the form of a doubly linked list, with one or more DirectoryNode entries each containing up to 32 [IDs of other entries](../common-fields.md). The first DirectoryNode entry is called the root of the directory, and all entries other than the root can be added or deleted as necessary. There are three kinds of directory: * _Owner directories_ list other entries owned by an account, such as [`RippleState` (trust line)](ripplestate.md) or [`Offer`](offer.md) entries. -* _Offer directories_ list the offers available in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md). A single Offer directory contains all the offers that have the same exchange rate for the same token (currency code and issuer). +* _Offer directories_ list the offers available in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md). A single offer directory contains all the offers that have the same exchange rate for the same token (currency code and issuer). * _NFT Offer directories_ list buy and sell offers for NFTs. Each NFT has up to two directories, one for buy offers, the other for sell offers. All types of directories are automatically updated by the protocol as necessary. @@ -97,6 +97,7 @@ All types of directories are automatically updated by the protocol as necessary. | Name | JSON Type | [Internal Type][] | Required? | Description | |:--------------------|:----------|:------------------|:----------|:------------| +| `DomainID` | String | Hash256 | No | (Offer directories only) The ledger entry ID of a permissioned domain. If present, this order book belongs to the corresponding [Permissioned DEX](../../../../concepts/tokens/decentralized-exchange/permissioned-dexes.md). Otherwise, this order book is part of the open DEX. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | | `ExchangeRate` | String | UInt64 | No | (Offer directories only) **DEPRECATED**. Do not use. | | `Flags` | Number | UInt32 | Yes | A bit-map of boolean flags enabled for this object. Currently, the protocol defines no flags for `DirectoryNode` objects. The value is always `0`. | | `Indexes` | Array | Vector256 | Yes | The contents of this directory: an array of IDs of other objects. | @@ -136,8 +137,8 @@ Owner directories and offer directories for fungible tokens do not use flags; th There are three different formulas for creating the ID of a DirectoryNode, depending on which of the following the DirectoryNode represents: * The first page (also called the root) of an Owner or NFT Offer directory -* The first page of an Offer directory -* Later pages of either type +* The first page of an Offer directory, with variants for the open DEX and permissioned DEX _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ +* Later pages of any type The first page of an Owner directory or NFT Offer directory has an ID that is the [SHA-512Half][] of the following values, concatenated in order: @@ -151,6 +152,7 @@ The first page of an Offer directory has a special ID: the higher 192 bits defin * The 160-bit currency code from the `TakerGetsCurrency` * The AccountID from the `TakerPaysIssuer` * The AccountID from the `TakerGetsIssuer` +* The `DomainID` of the permissioned domain this order book belongs to, if part of a permissioned DEX. Omitted for order books in the open DEX. The lower 64 bits of an Offer directory's ID represent the `TakerPays` amount divided by `TakerGets` amount from the offer(s) in that directory as a 64-bit number in the XRP Ledger's internal amount format. diff --git a/docs/references/protocol/ledger-data/ledger-entry-types/escrow.md b/docs/references/protocol/ledger-data/ledger-entry-types/escrow.md index 7501e507c1..f532e9962e 100644 --- a/docs/references/protocol/ledger-data/ledger-entry-types/escrow.md +++ b/docs/references/protocol/ledger-data/ledger-entry-types/escrow.md @@ -40,7 +40,7 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | Name | JSON Type | [Internal Type][] | Required? | Description | |:--------------------|:----------|:------------------|:----------|:-----------------------| | `Account` | String | AccountID | Yes | The address of the owner (sender) of this escrow. This is the account that provided the XRP, and gets it back if the escrow is canceled. | -| `Amount` | String | Amount | Yes | The amount of XRP, in drops, currently held in the escrow. | +| `Amount` | Object or String | Amount | Yes | The amount to be delivered by the payment is escrow. | | `CancelAfter` | Number | UInt32 | No | The escrow can be canceled if and only if this field is present _and_ the time it specifies has passed. Specifically, this is specified as [seconds since the Ripple Epoch][] and it "has passed" if it's earlier than the close time of the previous validated ledger. | | `Condition` | String | Blob | No | A [PREIMAGE-SHA-256 crypto-condition](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02#section-8.1), as hexadecimal. If present, the [EscrowFinish transaction][] must contain a fulfillment that satisfies this condition. | | `Destination` | String | AccountID | Yes | The destination address where the XRP is paid if the escrow is successful. | @@ -52,6 +52,7 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | `PreviousTxnID` | String | Hash256 | Yes | The identifying hash of the transaction that most recently modified this entry. | | `PreviousTxnLgrSeq` | Number | UInt32 | Yes | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this entry. | | `SourceTag` | Number | UInt32 | No | An arbitrary tag to further specify the source for this escrow, such as a hosted recipient at the owner's address. | +| `TransferRate` | Number | UInt32 | No | The fee to charge when users finish an escrow, initially set on the creation of an escrow contract and updated on subsequent finish transactions. | ## {% $frontmatter.seo.title %} Flags diff --git a/docs/references/protocol/ledger-data/ledger-entry-types/offer.md b/docs/references/protocol/ledger-data/ledger-entry-types/offer.md index af0a6fa952..947090c90b 100644 --- a/docs/references/protocol/ledger-data/ledger-entry-types/offer.md +++ b/docs/references/protocol/ledger-data/ledger-entry-types/offer.md @@ -5,11 +5,11 @@ labels: - Decentralized Exchange --- # Offer -[[Source]](https://github.com/XRPLF/rippled/blob/f64cf9187affd69650907d0d92e097eb29693945/include/xrpl/protocol/detail/ledger_entries.macro#L229-L240 "Source") +[[Source]](https://github.com/XRPLF/rippled/blob/7e24adbdd0b61fb50967c4c6d4b27cc6d81b33f3/include/xrpl/protocol/detail/ledger_entries.macro#L242-L255 "Source") -An `Offer` ledger entry describes an [Offer](../../../../concepts/tokens/decentralized-exchange/offers.md) to exchange currencies in the XRP Ledger's [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md). (In finance, this is more traditionally known as an _order_.) You an create a new Offer entry by sending an [OfferCreate transaction][] that is not fully executed immediately. +An `Offer` ledger entry describes an [offer](../../../../concepts/tokens/decentralized-exchange/offers.md) to exchange currencies in the XRP Ledger's [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md). (In finance, this is more traditionally known as an _order_.) You an create a new offer entry by sending an [OfferCreate transaction][] that is not fully executed immediately. -An Offer can become unfunded through other activities in the network, while remaining in the ledger. When processing transactions, the network automatically removes any unfunded Offers that those transactions come across. (Otherwise, unfunded Offers remain, because _only_ transactions can change the ledger state.) +An offer can become unfunded through other activities in the network, while remaining in the ledger. When processing transactions, the network automatically removes any unfunded Offers that those transactions come across. (Otherwise, unfunded Offers remain, because _only_ transactions can change the ledger state.) ## Example {% $frontmatter.seo.title %} JSON @@ -39,19 +39,21 @@ An Offer can become unfunded through other activities in the network, while rema In addition to the [common fields](../common-fields.md), {% code-page-name /%} entries have the following fields: -| Name | JSON Type | [Internal Type][] | Required? | Description | -|:--------------------|:-----------------|:------------------|:----------|:------------| -| `Account` | String | AccountID | Yes | The address of the account that owns this Offer. | -| `BookDirectory` | String | Hash256 | Yes | The ID of the [Offer Directory](directorynode.md) that links to this Offer. | -| `BookNode` | String | UInt64 | Yes | A hint indicating which page of the offer directory links to this entry, in case the directory consists of multiple pages. | -| `Expiration` | Number | UInt32 | No | Indicates the time after which this Offer is considered unfunded. See [Specifying Time][] for details. | -| `LedgerEntryType` | String | UInt16 | Yes | The value `0x006F`, mapped to the string `Offer`, indicates that this is an Offer entry. | -| `OwnerNode` | String | UInt64 | Yes | A hint indicating which page of the owner directory links to this entry, in case the directory consists of multiple pages. | -| `PreviousTxnID` | String | Hash256 | Yes | The identifying hash of the transaction that most recently modified this entry. | -| `PreviousTxnLgrSeq` | Number | UInt32 | Yes | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. | -| `Sequence` | Number | UInt32 | Yes | The `Sequence` value of the [OfferCreate][] transaction that created this offer. Used in combination with the `Account` to identify this offer. | -| `TakerPays` | [Currency Amount][] | Amount | Yes | The remaining amount and type of currency requested by the Offer creator. | -| `TakerGets` | [Currency Amount][] | Amount | Yes | The remaining amount and type of currency being provided by the Offer creator. | +| Name | JSON Type | [Internal Type][] | Required? | Description | +|:--------------------|:---------------------|:------------------|:----------|:------------| +| `Account` | String - [Address][] | AccountID | Yes | The account that owns this offer. | +| `AdditionalBooks` | Array | Array | No | A list of additional offer directories that link to this offer. This field is only present if this is a hybrid offer in a [permissioned DEX](../../../../concepts/tokens/decentralized-exchange/permissioned-dexes.md). The array always contains exactly 1 entry. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | +| `BookDirectory` | String - [Hash][] | Hash256 | Yes | The ID of the [offer directory](directorynode.md) that links to this offer. | +| `BookNode` | String | UInt64 | Yes | A hint indicating which page of the offer directory links to this entry, in case the directory consists of multiple pages. | +| `DomainID` | String - [Hash][] | Hash256 | No | The ledger entry ID of a permissioned domain. If present, this offer belongs to the corresponding [Permissioned DEX](../../../../concepts/tokens/decentralized-exchange/permissioned-dexes.md). _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | +| `Expiration` | Number | UInt32 | No | Indicates the time after which this offer is considered unfunded. See [Specifying Time][] for details. | +| `LedgerEntryType` | String | UInt16 | Yes | The value `0x006F`, mapped to the string `Offer`, indicates that this is an offer entry. | +| `OwnerNode` | String | UInt64 | Yes | A hint indicating which page of the owner directory links to this entry, in case the directory consists of multiple pages. | +| `PreviousTxnID` | String - [Hash][] | Hash256 | Yes | The identifying hash of the transaction that most recently modified this entry. | +| `PreviousTxnLgrSeq` | Number | UInt32 | Yes | The [index of the ledger][Ledger Index] that contains the transaction that most recently modified this object. | +| `Sequence` | Number | UInt32 | Yes | The `Sequence` value of the [OfferCreate][] transaction that created this offer. Used in combination with the `Account` to identify this offer. | +| `TakerPays` | [Currency Amount][] | Amount | Yes | The remaining amount and type of currency requested by the offer creator. | +| `TakerGets` | [Currency Amount][] | Amount | Yes | The remaining amount and type of currency being provided by the offer creator. | ## Offer Flags @@ -59,9 +61,9 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | Flag Name | Hex Value | Decimal Value | Corresponding [OfferCreate Flag](../../transactions/types/offercreate.md#offercreate-flags) | Description | |--------------|--------------|---------------|-------------|------------------------| -| `lsfPassive` | `0x00010000` | 65536 | `tfPassive` | The offer was placed as "passive". This has no effect after the offer is placed into the ledger. | -| `lsfSell` | `0x00020000` | 131072 | `tfSell` | The offer was placed as a "Sell" offer. This has no effect after the offer is placed in the ledger, because `tfSell` only matters if you get a better rate than you asked for, which can only happen when the offer is initially placed. | - +| `lsfPassive` | `0x00010000` | 65536 | `tfPassive` | The offer was placed as passive. This has no effect after the offer is placed into the ledger. | +| `lsfSell` | `0x00020000` | 131072 | `tfSell` | The offer was placed as a sell offer. This has no effect after the offer is placed in the ledger, because `tfSell` only matters if you get a better rate than you asked for, which can only happen when the offer is initially placed. | +| `lsfHybrid` | `0x00040000` | 262144 | `tfHybrid` | The offer was placed as a hybrid offer, which means it is listed in a [permissioned DEX](/docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md) and the open DEX. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | ## {% $frontmatter.seo.title %} Reserve @@ -73,9 +75,9 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e The ID of an `Offer` entry is the [SHA-512Half][] of the following values, concatenated in order: * The Offer space key (`0x006F`) -* The AccountID of the account placing the Offer -* The Sequence number of the [OfferCreate transaction][] that created the Offer. +* The AccountID of the account placing the offer +* The Sequence number of the [OfferCreate transaction][] that created the offer. - If the OfferCreate transaction used a [Ticket](../../../../concepts/accounts/tickets.md), use the `TicketSequence` value instead. + If the OfferCreate transaction used a [ticket](../../../../concepts/accounts/tickets.md), use the `TicketSequence` value instead. {% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/protocol/ledger-data/ledger-entry-types/paychannel.md b/docs/references/protocol/ledger-data/ledger-entry-types/paychannel.md index 902a2fcd0d..b1a58d1ddb 100644 --- a/docs/references/protocol/ledger-data/ledger-entry-types/paychannel.md +++ b/docs/references/protocol/ledger-data/ledger-entry-types/paychannel.md @@ -42,8 +42,8 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | Name | JSON Type | [Internal Type][] | Required? | Description | |:--------------------|:----------|:------------------|:----------|:-----------------------| | `Account` | String | AccountID | Yes | The source address that owns this payment channel. This comes from the sending address of the transaction that created the channel. | -| `Amount` | String | Amount | Yes | Total [XRP, in drops][], that has been allocated to this channel. This includes XRP that has been paid to the destination address. This is initially set by the transaction that created the channel and can be increased if the source address sends a PaymentChannelFund transaction. | -| `Balance` | String | Amount | Yes | Total [XRP, in drops][], already paid out by the channel. The difference between this value and the `Amount` field is how much XRP can still be paid to the destination address with PaymentChannelClaim transactions. If the channel closes, the remaining difference is returned to the source address. | +| `Amount` | String | Amount | Yes | Total [XRP, in drops][] or tokens, that have been allocated to this channel. This includes amounts that have been paid to the destination address. This is initially set by the transaction that created the channel and can be increased if the source address sends a `PaymentChannelFund` transaction. | +| `Balance` | Object or String | Amount | Yes | Total already paid out by the channel. The difference between this value and the `Amount` field is how much can still be paid to the destination address with `PaymentChannelClaim` transactions. If the channel closes, the remaining difference is returned to the source address. | | `CancelAfter` | Number | UInt32 | No | The immutable expiration time for this payment channel, in [seconds since the Ripple Epoch][]. This channel is expired if this value is present and smaller than the previous ledger's [`close_time` field](../ledger-header.md). This is optionally set by the transaction that created the channel, and cannot be changed. | | `Destination` | String | AccountID | Yes | The destination address for this payment channel. While the payment channel is open, this address is the only one that can receive XRP from the channel. This comes from the `Destination` field of the transaction that created the channel. | | `DestinationTag` | Number | UInt32 | No | An arbitrary tag to further specify the destination for this payment channel, such as a hosted recipient at the destination address. | @@ -56,6 +56,7 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | `PublicKey` | String | Blob | Yes | Public key, in hexadecimal, of the key pair that can be used to sign claims against this channel. This can be any valid secp256k1 or Ed25519 public key. This is set by the transaction that created the channel and must match the public key used in claims against the channel. The channel source address can also send XRP from this channel to the destination without signed claims. | | `SettleDelay` | Number | UInt32 | Yes | Number of seconds the source address must wait to close the channel if it still has any XRP in it. Smaller values mean that the destination address has less time to redeem any outstanding claims after the source address requests to close the channel. Can be any value that fits in a 32-bit unsigned integer (0 to 2^32-1). This is set by the transaction that creates the channel. | | `SourceTag` | Number | UInt32 | No | An arbitrary tag to further specify the source for this payment channel, such as a hosted recipient at the owner's address. | +| `TransferRate` | Number | UInt32 | No | The fee to charge when users make claims on a payment channel, initially set on the creation of a payment channel and updated on subsequent funding or claim transactions. | ## Channel Expiration diff --git a/docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md b/docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md index ff2ff67efd..974b684c22 100644 --- a/docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md +++ b/docs/references/protocol/ledger-data/ledger-entry-types/ripplestate.md @@ -58,6 +58,8 @@ In addition to the [common fields](../common-fields.md), {% code-page-name /%} e | `HighQualityIn` | Number | UInt32 | No | The inbound quality set by the high account, as an integer in the implied ratio `HighQualityIn`:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value. | | `HighQualityOut` | Number | UInt32 | No | The outbound quality set by the high account, as an integer in the implied ratio `HighQualityOut`:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value. | | `LedgerEntryType` | String | UInt16 | Yes | The value `0x0072`, mapped to the string `RippleState`, indicates that this is a RippleState entry. | +| `LockCount` | Object or String | Amount | No | The total number of lock balances on a `RippleState` ledger object. | +| `LockedBalance` | Object or String | Amount | No | The total number of locked tokens on a `RippleState` ledger object. | | `LowLimit` | Object | Amount | Yes | The limit that the low account has set on the trust line. The `issuer` is the address of the low account that set this limit. | | `LowNode` | String | UInt64 | Yes | (Omitted in some historical ledgers) A hint indicating which page of the low account's owner directory links to this entry, in case the directory consists of multiple pages. | | `LowQualityIn` | Number | UInt32 | No | The inbound quality set by the low account, as an integer in the implied ratio `LowQualityIn`:1,000,000,000. As a special case, the value 0 is equivalent to 1 billion, or face value. | diff --git a/docs/references/protocol/transactions/common-fields.md b/docs/references/protocol/transactions/common-fields.md index 4a36e4e96e..090806f82f 100644 --- a/docs/references/protocol/transactions/common-fields.md +++ b/docs/references/protocol/transactions/common-fields.md @@ -17,6 +17,7 @@ Every transaction has the same set of common fields, plus additional fields base | `Fee` | String | Amount | _(Required; [auto-fillable][])_ Integer amount of XRP, in drops, to be destroyed as a cost for distributing this transaction to the network. Some transaction types have different minimum requirements. See [Transaction Cost][] for details. | | `Sequence` | Number | UInt32 | _(Required; [auto-fillable][])_ The [sequence number](../data-types/basic-data-types.md#account-sequence) of the account sending the transaction. A transaction is only valid if the `Sequence` number is exactly 1 greater than the previous transaction from the same account. The special case `0` means the transaction is using a [Ticket](../../../concepts/accounts/tickets.md) instead _(Added by the [TicketBatch amendment][].)_. | | [`AccountTxnID`](#accounttxnid) | String | Hash256 | _(Optional)_ Hash value identifying another transaction. If provided, this transaction is only valid if the sending account's previously-sent transaction matches the provided hash. | +| [`Delegate`](#delegate) | Object | Object | _(Optional)_ Stores a set of permissions that an XRPL account has delegated to another account. | | [`Flags`](#flags-field) | Number | UInt32 | _(Optional)_ Set of bit-flags for this transaction. | | `LastLedgerSequence` | Number | UInt32 | _(Optional; strongly recommended)_ Highest ledger index this transaction can appear in. Specifying this field places a strict upper limit on how long the transaction can wait to be validated or rejected. See [Reliable Transaction Submission](../../../concepts/transactions/reliable-transaction-submission.md) for more details. | | [`Memos`](#memos-field) | Array of Objects | Array | _(Optional)_ Additional arbitrary information used to identify this transaction. | @@ -45,7 +46,6 @@ One situation in which this is useful is if you have a primary system for submit The `AccountTxnID` field cannot be used on transactions that use [Tickets](../../../concepts/accounts/tickets.md). Transactions that use `AccountTxnID` cannot be placed in the [transaction queue](../../../concepts/transactions/transaction-queue.md). - ## Auto-fillable Fields Some fields can be automatically filled in before a transaction is signed, either by a `rippled` server or by a [client library](../../client-libraries.md). Auto-filling values requires an active connection to the XRP Ledger to get the latest state, so it cannot be done offline. The details can vary by library, but auto-filling always provides suitable values for at least the following fields: @@ -60,6 +60,45 @@ For a production system, we recommend _not_ leaving these fields to be filled by The [`Paths` field](types/payment.md#paths) of the [Payment transaction][] type can also be automatically filled in. +## Delegate + +The `Delegate` ledger object stores a set of permissions that an XRPL account has delegated to another account. You create `Delegate` objects using the [`DelegateSet`](./types/delegateset.md) transaction. + +### Structure + +A `Delegate` object has the following fields: + +| Field Name | Required? | JSON Type | Internal Type | Description | +|------------|-----------|-----------|---------------|-------------| +| `LedgerIndex` | ✔️ | string | Hash256 | The unique ID of the ledger object. | +| `LedgerEntryType` | ✔️ | string | UInt16 | The ledger object's type (`Delegate`) | +| `Account` | ✔️ | string | AccountID | The account that delegates permissions to another account. | +| `Authorize` | ✔️ | string | AccountID | The account to which permissions are delegated. | +| `Permissions` | ✔️ | string | STArray | The transaction permissions that the `Authorize` account has been granted. | +| `OwnerNode` | ✔️ | string | UInt64 | A hint indicating which page of the sender's owner directory links to this object, in case the directory consists of multiple pages. | +| `PreviousTxnID` | ✔️ | string | Hash256 | The identifying hash of the transaction that most recently modified this object. | +| `PreviousTxnLgrSeqNumber`| ✔️ | number | UInt32 |The index of the ledger that contains the transaction that most recently modified this object. | + +### Retrieving Delegate Objects + +You can retrieve `Delegate` ledger objects using the `ledger_entry` RPC method. The unique ID of a `Delegate` object is a hash of the `Account` and `Authorize` fields, combined with the unique space key for Delegate objects. + +### Account Deletion + +A `Delegate` object is not a deletion blocker. This means that deleting an account removes any `Delegate` objects associated with it. + +### Example Delegate JSON + +This sample `Delegate` object shows that the _rISAAC_ account has delegated `TrustLineAuthorize` permission to the _rKYLIE_ account. + +```json +{ + "LedgerEntryType": "Delegate", + "Account": "rISAAC......", + "Authorize": "rKYLIE......", + "Permissions": [{"Permission": {"PermissionValue": "TrustlineAuthorize"}}], +} +``` ## Flags Field @@ -73,11 +112,12 @@ Bits that are not defined as flags MUST be 0. (The [fix1543 amendment][] enforce ### Global Flags -The only flag that applies globally to all transactions is as follows: +The only flags that apply globally to all transactions are as follows: | Flag Name | Hex Value | Decimal Value | Description | |:----------------------|:-----------|:--------------|:--------------------------| | `tfFullyCanonicalSig` | `0x80000000` | 2147483648 | **DEPRECATED** No effect. (If the [RequireFullyCanonicalSig amendment][] is not enabled, this flag enforces a [fully-canonical signature](../../../concepts/transactions/finality-of-results/transaction-malleability.md#alternate-secp256k1-signatures).) | +| `tfInnerBatchTxn` | `0x40000000` | 1073741824 | This flag is only used if a transaction is an inner transaction in a Batch transaction. This signifies that the transaction isn't signed. Any normal transaction that includes this flag is rejected. | When using the [sign method][] (or [submit method][] in "sign-and-submit" mode), `rippled` adds a `Flags` field with `tfFullyCanonicalSig` enabled unless the `Flags` field is already present. The `tfFullyCanonicalSig` flag is not automatically enabled if `Flags` is explicitly specified. The flag is not automatically enabled when using the [sign_for method][] to add a signature to a multi-signed transaction. @@ -95,7 +135,6 @@ A transaction's `Flags` field can contain flags that apply at different levels o {% admonition type="info" name="Note" %}The [AccountSet transaction][] type has [its own non-bitwise flags](types/accountset.md#accountset-flags), which serve a similar purpose to type-based flags. [Ledger objects](../ledger-data/ledger-entry-types/index.md) also have a `Flags` field with different bitwise flag definitions.{% /admonition %} - ## Memos Field The `Memos` field includes arbitrary messaging data with the transaction. It is presented as an array of objects. Each object has only one field, `Memo`, which in turn contains another object with *one or more* of the following fields: diff --git a/docs/references/protocol/transactions/types/batch.md b/docs/references/protocol/transactions/types/batch.md new file mode 100644 index 0000000000..d1ecf3a213 --- /dev/null +++ b/docs/references/protocol/transactions/types/batch.md @@ -0,0 +1,392 @@ +--- +seo: + description: Create and submit a batch of up to 8 transactions. +labels: + - Batch + - Transactions +status: not_enabled +--- +# Batch +[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/app/tx/detail/Batch.cpp "Source") + +The `Batch` transaction submits up to eight transactions in a single batch. Each transaction is executed atomically in one of four modes: All or Nothing, Only One, Until Failure, and Independent. + +## Example Batch JSON + +In this example, the user is creating an offer while trading on a DEX UI, and the second transaction is a platform fee. The inner transactions are not signed, and the `BatchSigners` field is not needed on the outer transaction, since there is only one account involved. + +```json +{ + "TransactionType": "Batch", + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "Flags": "0x00010000", + "RawTransactions": [ + { + "RawTransaction": { + "TransactionType": "OfferCreate", + "Flags": 1073741824, + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "TakerGets": "6000000", + "TakerPays": { + "currency": "GKO", + "issuer": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc", + "value": "2" + }, + "Sequence": 4, + "Fee": "0", + "SigningPubKey": "" + } + }, + { + "RawTransaction": { + "TransactionType": "Payment", + "Flags": 1073741824, + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "Destination": "rDEXfrontEnd23E44wKL3S6dj9FaXv", + "Amount": "1000", + "Sequence": 5, + "Fee": "0", + "SigningPubKey": "" + } + } + ], + "Sequence": 3, + "Fee": "40", + "SigningPubKey": "022D40673B44C82DEE1DDB8B9BB53DCCE4F97B27404DB850F068DD91D685E337EA", + "TxnSignature": "3045022100EC5D367FAE2B461679AD446FBBE7BA260506579AF4ED5EFC3EC25F4DD1885B38022018C2327DB281743B12553C7A6DC0E45B07D3FC6983F261D7BCB474D89A0EC5B8" +} +``` + +### Sample Ledger Confirmation + +This example shows what the ledger looks like after the transaction is confirmed. +Note that the inner transactions are committed as normal transactions. + +```json +[ + { + "TransactionType": "Batch", + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "Flags": "0x00010000", + "RawTransactions": [ + { + "RawTransaction": { + "TransactionType": "OfferCreate", + "Flags": 1073741824, + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "TakerGets": "6000000", + "TakerPays": { + "currency": "GKO", + "issuer": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc", + "value": "2" + }, + "Sequence": 4, + "Fee": "0", + "SigningPubKey": "" + } + }, + { + "RawTransaction": { + "TransactionType": "Payment", + "Flags": 1073741824, + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "Destination": "rDEXfrontEnd23E44wKL3S6dj9FaXv", + "Amount": "1000", + "Sequence": 5, + "Fee": "0", + "SigningPubKey": "" + } + } + ], + "Sequence": 3, + "Fee": "40", + "SigningPubKey": "022D40673B44C82DEE1DDB8B9BB53DCCE4F97B27404DB850F068DD91D685E337EA", + "TxnSignature": "3045022100EC5D367FAE2B461679AD446FBBE7BA260506579AF4ED5EFC3EC25F4DD1885B38022018C2327DB281743B12553C7A6DC0E45B07D3FC6983F261D7BCB474D89A0EC5B8" + }, + { + "TransactionType": "OfferCreate", + "Flags": 1073741824, + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "TakerGets": "6000000", + "TakerPays": { + "currency": "GKO", + "issuer": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc", + "value": "2" + }, + "Sequence": 4, + "Fee": "0", + "SigningPubKey": "" + }, + { + "TransactionType": "Payment", + "Flags": 1073741824, + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "Destination": "rDEXfrontEnd23E44wKL3S6dj9FaXv", + "Amount": "1000", + "Sequence": 5, + "Fee": "0", + "SigningPubKey": "" + } +] +``` + +### Sample Ledger + +This example shows what the ledger will look like after the transaction is confirmed. Note that the inner transactions are committed as normal transactions, and the RawTransactions field is not included in the validated version of the outer transaction. + +```json +[ + { + "TransactionType": "Batch", + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "Flags": "1", + "TxnIDs": [ + "7EB435C800D7DC10EAB2ADFDE02EE5667C0A63AA467F26F90FD4CBCD6903E15E", + "EAE6B33078075A7BA958434691B896CCA4F532D618438DE6DDC7E3FB7A4A0AAB" + ], + "Sequence": 3, + "Fee": "40", + "SigningPubKey": "022D40673B44C82DEE1DDB8B9BB53DCCE4F97B27404DB850F068DD91D685E337EA", + "TxnSignature": "3045022100EC5D367FAE2B461679AD446FBBE7BA260506579AF4ED5EFC3EC25F4DD1885B38022018C2327DB281743B12553C7A6DC0E45B07D3FC6983F261D7BCB474D89A0EC5B8" + }, + { + "TransactionType": "OfferCreate", + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "TakerGets": "6000000", + "TakerPays": { + "currency": "GKO", + "issuer": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc", + "value": "2" + }, + "BatchTxn": { + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "OuterSequence": 3, + "BatchIndex": 0 + }, + "Sequence": 0, + "Fee": "0", + "SigningPubKey": "", + "TxnSignature": "" + }, + { + "TransactionType": "Payment", + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "Destination": "rDEXfrontEnd23E44wKL3S6dj9FaXv", + "Amount": "1000", + "BatchTxn": { + "Account": "rUserBSM7T3b6nHX3Jjua62wgX9unH8s9b", + "OuterSequence": 3, + "BatchIndex": 1 + }, + "Sequence": 0, + "Fee": "0", + "SigningPubKey": "", + "TxnSignature": "" + } +] +``` + +### Batch Fields + + + +| Field | JSON Type | [Internal Type][] | Description | +|:----------------|:--------------------|:------------------|:-------------------| +| TransactionType | string | UInt16 | | +| Account | string | STAccount | | +| Fee | string | STAmount | The fee 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). The fees for the individual inner transactions are paid here instead of in the inner transaction itself, to ensure that fee escalation is calculated on the total cost of the transaction instead of just the overhead. | +| Flags | number | UInt32 | The `Flags` field represents the batch mode of the transaction. Exactly one must be specified in a `Batch` transaction. See [Batch Flags](#batch-flags)| +| RawTransactions | array | STArray | RawTransactions contains the list of transactions that will be applied. See [Raw Transactions](#rawtransactions). | +| TxnIDs | array | Vector256 | `TxnIDs` contains a list of the transaction hashes/IDs for all the transactions contained in `RawTransactions`. This is the only part of the inner transactions that is saved as a part of the ledger within the `Batch` transaction, since the inner transactions themselves are their own transactions on-ledger. The hashes in TxnIDs must be in the same order as the raw transactions in `RawTransactions`. | +| BatchSigners | array | STArray | _Optional_. Only required if the `Batch` contains transactions for multiple accounts. See [BatchSigners](#batchsigners). | + + +### Batch Flags + +Transactions of the Batch type support additional values in the `Flags` field as follows: + +| Flag Name | Hex Value | Decimal Value | Description | +|:-------------------|:-------------| ------------: |:------------------------------| +| `ALLORNOTHING` | 0x00000001 | 1 | All or nothing. All transactions must succeed for any of them to succeed. | +| `ONLYONE` | 0x00000002 | 2 | The first transaction to succeed is the only one to succeed; all other transacitons either fail or are never tried. | +| `UNTILFAILURE` | 0x00000004 | 4 | All transactions are applied until the first failure; all transactions after the first failure are not applied. | +| `INDEPENDENT` | 0x00000008 | 8 | All transactions will be applied, regardless of failure. | + +### RawTransactions + +`RawTransactions` contains the list of transactions to be applied. There can be up to 8 transactions included. These transactions can come from one account or multiple accounts. + +Each inner transaction: + +- Must contain a BatchTxn field. +- Must not have a sequence number. It must use a sequence number value of 0. +- Must not have a fee. It must use a fee value of "0". +- Must not be signed (the global transaction is already signed by all relevant parties). They must instead have an empty string ("") in the SigningPubKey and TxnSignature fields. + +A transaction is considered a failure if it receives any result that is not `tesSUCCESS`. + +This field is not included in the validated transaction, nor is it used to compute the outer transaction signature(s), since all transactions are included separately as a part of the ledger. + +### BatchSigners + +This field operates similarly to multisign on the XRPL. It is only needed if multiple accounts' transactions are included in the Batch transaction; otherwise, the normal transaction signature provides the same security guarantees. + +Every account that has at least one inner transaction, excluding the outer account (if applicable), must have a BatchSigners field. + +| Field | JSON Type | [Internal Type][] | Description | +|:----------------|:--------------------|:------------------|:-------------------| +| Account | string | STAccount | This is an account that has at least one inner transaction. | +| SigningPubKey | string | STBlob | Included if the account is signing with a single signature. | +| Signature | string | STBlob | Included if the account is signing with a single signature. | +| Signers | array | STArray | 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 and TxnIDs fields. | + +## BatchTxn + +The `BatchTxn` inner object must be included in any inner transaction of a `Batch` transaction. Its inclusion: + +- Prevents hash collisions between identical transactions (since sequence numbers aren't included). +- Ensures that every transaction has a sequence number associated with it, so that created ledger objects that use it in their ID generation can still operate. +- Allows users to more easily organize their transactions in the correct order. + +The fields contained in this object are as follows. + +| Field | JSON Type | [Internal Type][] | Description | +|:---------------------|:-----------------|:------------------|:-----------------| +| `Account` | string | AccountID | Account that is submitting the outer `Batch` transaction. | +| `OuterSequence` | number | UInt32 | This is the sequence number of the outer `Batch` transaction. Its inclusion ensures that there are no hash collisions with other `Batch` transactions. | +| `Sequence` | number | UInt32 | _(Optional)_ This is the next available sequence number for the inner transaction's account. This only needs to be included in a multi-account Batch transaction. | +| `BatchIndex` | number | UInt8 | This is the (0-indexed) index of the inner transaction within the existing `Batch` transaction. The first inner transaction will have BatchIndex value 0, the second will be 1, and so on. Its inclusion ensures there are no hash collisions with other inner transactions within the same `Batch` transaction, and that the transactions are all placed in the right order. | + +## Example Multiple Account Batch JSON + +In this example, two users are atomically swapping their tokens, XRP for GKO. The inner transactions still are not signed, but the `BatchSigners` field is needed on the outer transaction, since there are two accounts' inner transactions in this `Batch` transaction. + +```json +{ + "TransactionType": "Batch", + "Account": "rUser1fcu9RJa5W1ncAuEgLJF2oJC6", + "Flags": "0x00010000", + "RawTransactions": [ + { + "RawTransaction": { + "TransactionType": "Payment", + "Flags": 1073741824, + "Account": "rUser1fcu9RJa5W1ncAuEgLJF2oJC6", + "Destination": "rUser2fDds782Bd6eK15RDnGMtxf7m", + "Amount": "6000000", + "Sequence": 5, + "Fee": "0", + "SigningPubKey": "" + } + }, + { + "RawTransaction": { + "TransactionType": "Payment", + "Flags": 1073741824, + "Account": "rUser2fDds782Bd6eK15RDnGMtxf7m", + "Destination": "rUser1fcu9RJa5W1ncAuEgLJF2oJC6", + "Amount": { + "currency": "GKO", + "issuer": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc", + "value": "2" + }, + "Sequence": 20, + "Fee": "0", + "SigningPubKey": "" + } + } + ], + "BatchSigners": [ + { + "BatchSigner": { + "Account": "rUser2fDds782Bd6eK15RDnGMtxf7m", + "SigningPubKey": "03C6AE25CD44323D52D28D7DE95598E6ABF953EECC9ABF767F13C21D421C034FAB", + "TxnSignature": "304502210083DF12FA60E2E743643889195DC42C10F62F0DE0A362330C32BBEC4D3881EECD022010579A01E052C4E587E70E5601D2F3846984DB9B16B9EBA05BAD7B51F912B899" + } + } + ], + "Sequence": 4, + "Fee": "60", + "SigningPubKey": "03072BBE5F93D4906FC31A690A2C269F2B9A56D60DA9C2C6C0D88FB51B644C6F94", + "TxnSignature": "30440220702ABC11419AD4940969CC32EB4D1BFDBFCA651F064F30D6E1646D74FBFC493902204E5B451B447B0F69904127F04FE71634BD825A8970B9467871DA89EEC4B021F8" +} +``` + +#### Sample Ledger Response + +```json +[ + { + "TransactionType": "Batch", + "Account": "rUser1fcu9RJa5W1ncAuEgLJF2oJC6", + "Flags": "0x00010000", + "RawTransactions": [ + { + "RawTransaction": { + "TransactionType": "Payment", + "Flags": 1073741824, + "Account": "rUser1fcu9RJa5W1ncAuEgLJF2oJC6", + "Destination": "rUser2fDds782Bd6eK15RDnGMtxf7m", + "Amount": "6000000", + "Sequence": 5, + "Fee": "0", + "SigningPubKey": "" + } + }, + { + "RawTransaction": { + "TransactionType": "Payment", + "Flags": 1073741824, + "Account": "rUser2fDds782Bd6eK15RDnGMtxf7m", + "Destination": "rUser1fcu9RJa5W1ncAuEgLJF2oJC6", + "Amount": { + "currency": "GKO", + "issuer": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc", + "value": "2" + }, + "Sequence": 20, + "Fee": "0", + "SigningPubKey": "" + } + } + ], + "BatchSigners": [ + { + "BatchSigner": { + "Account": "rUser2fDds782Bd6eK15RDnGMtxf7m", + "SigningPubKey": "03C6AE25CD44323D52D28D7DE95598E6ABF953EECC9ABF767F13C21D421C034FAB", + "TxnSignature": "304502210083DF12FA60E2E743643889195DC42C10F62F0DE0A362330C32BBEC4D3881EECD022010579A01E052C4E587E70E5601D2F3846984DB9B16B9EBA05BAD7B51F912B899" + } + } + ], + "Sequence": 4, + "Fee": "60", + "SigningPubKey": "03072BBE5F93D4906FC31A690A2C269F2B9A56D60DA9C2C6C0D88FB51B644C6F94", + "TxnSignature": "30440220702ABC11419AD4940969CC32EB4D1BFDBFCA651F064F30D6E1646D74FBFC493902204E5B451B447B0F69904127F04FE71634BD825A8970B9467871DA89EEC4B021F8" + }, + { + "TransactionType": "Payment", + "Flags": 1073741824, + "Account": "rUser1fcu9RJa5W1ncAuEgLJF2oJC6", + "Destination": "rUser2fDds782Bd6eK15RDnGMtxf7m", + "Amount": "6000000", + "Sequence": 5, + "Fee": "0", + "SigningPubKey": "" + }, + { + "TransactionType": "Payment", + "Flags": 1073741824, + "Account": "rUser2fDds782Bd6eK15RDnGMtxf7m", + "Destination": "rUser1fcu9RJa5W1ncAuEgLJF2oJC6", + "Amount": { + "currency": "GKO", + "issuer": "ruazs5h1qEsqpke88pcqnaseXdm6od2xc", + "value": "2" + }, + "Sequence": 20, + "Fee": "0", + "SigningPubKey": "" + } +] +``` diff --git a/docs/references/protocol/transactions/types/delegateset.md b/docs/references/protocol/transactions/types/delegateset.md new file mode 100644 index 0000000000..2345e4dc1b --- /dev/null +++ b/docs/references/protocol/transactions/types/delegateset.md @@ -0,0 +1,145 @@ +--- +seo: + description: An transaction that delegates a set of permissions to another account. +labels: + - Accounts + - Permissions + - Delegate +status: not_enabled +--- + +# DelegateSet +The `DelegateSet` transaction creates, modifies, or deletes a `Delegate` ledger object, thereby granting, changing, or revoking delegated permissions between accounts. + +_(Requires the [PermissionDelegation amendment][] {% not-enabled /%})_ + +## Example `DelegateSet` JSON + +```json +tx_json = { + "TransactionType": "DelegateSet", + "Account": "rDelegatingAccount", + "Authorize": "rDelegatedAccount", + "Permissions": [ + { + "Permission": { + "PermissionValue": "Payment" + } + }, + { + "Permission": { + "PermissionValue": "TrustSet" + } + } + ] +} +``` +## `DelegateSet` Fields + +In addition to the common fields, `DelegateSet` transactions have the following fields: + +| Field | Required? | JSON Type | Internal Type | Description | +|-------|-----------|-----------|---------------|-------------| +| `TransactionType` | Yes | string | UInt16 | The transaction type (DelegateSet). | +| `Account` | Yes | string | AccountID | The address of the account that is delegating the permission(s). | +| `Authorize`| Yes | string | AccountID | The address of the account that is being granted the permission(s). +| `Permissions` | Yes | string | STArray | An array of permission objects. Each object contains a `Permission` object with a `PermissionValue` field specifying the permission being granted. To modify permissions, include all desired permissions in the `Permissions` array. Omitted permissions are revoked. | + +## Updating Permissions + +Sending a new `DelegateSet` with the same `Account` and `Authorize` fields updates and replaces the permission list. + + +## Revoking Permissions + +Permissions are revoked using the `DelegateSet` transaction by specifying only the desired permissions and omitting any previous permissions that are no longer needed. + +### Revoke All Permissions + +To revoke all permissions, send a `DelegateSet` transaction with an empty `Permissions` array: + +```json +tx_json = { + "TransactionType": "DelegateSet", + "Account": "rDelegatingAccount", + "Authorize": "rDelegatedAccount", + "Permissions": [] +} +``` + +### Revoke Specific Permissions + +To revoke specific permissions, include only the permissions that should remain active in the `Permissions` array. + +## Security + +Giving permissions to other parties requires a high degree of trust, especially when the delegated account can potentially access funds (the `Payment` permission) or charge reserves (any transaction that can create objects). In addition, any account that has permissions for the entire `AccountSet`, `SetRegularKey`, or `SignerListSet` transactions can give themselves any permissions even if this was not originally part of the intention. + +With granular permissions, however, users can give permissions to other accounts for only parts of transactions without giving them full control. This is especially helpful for managing complex transaction types like `AccountSet`. + +### Granular Permissions + +These permissions support control over some smaller portion of a transaction, rather than being able to do all of the functionality that the transaction allows. + +These permissions fall into the gap between the size of the `UInt16` and the `UInt32` (the size of the `SignerListID` field). + +| Value | Name | Description | +|-------|-------|-------------| +|`65537`|`TrustlineAuthorize`|Authorize a trustline.| +|`65538`|`TrustlineFreeze`|Freeze a trustline.| +|`65539`|`TrustlineUnfreeze`|Unfreeze a trustline.| +|`65540`|`AccountDomainSet`|Modify the domain of an account.| +|`65541`|`AccountEmailHashSet`|Modify the `EmailHash` of an account.| +|`65542`|`AccountMessageKeySet`|Modify the `MessageKey` of an account.| +|`65543`|`AccountTransferRateSet`|Modify the transfer rate of an account.| +|`65544`|`AccountTickSizeSet`|Modify the tick size of an account.| +|`65545`|`PaymentMint`|Send a payment for a currency where the sending account is the issuer.| +|`65546`|`PaymentBurn`|Send a payment for a currency where the destination account is the issuer.| +|`65547`|`MPTokenIssuanceLock`|Use the `MPTIssuanceSet` transaction to lock (freeze) a holder.| +|`65548`|`MPTokenIssuanceUnlock`|Use the `MPTIssuanceSet` transaction to unlock (unfreeze) a holder.| + +For example, if an account is authorized by `TrustlineFreeze`, it can freeze a trust line by sending a `TrustSet` transaction. However, since it is only authorized to freeze trust lines, it cannot perform other `TrustSet` operations such as unfreezing a trust line, setting No Ripple, applying Deep Freeze, etc. +When an account is authorized by both `TrustlineFreeze` and `TrustSet`, the delegation is still valid, but the granular permission `TrustlineFreeze` has no effect, since the account is already permitted to perform all actions under `TrustSet`. + +For multi-signing a delegation transaction, which is sent by a delegated account, the multi signers must be the delegated account's signers instead of the delegating account's multi signers. + +### Limitations to Granular Permissions + +The set of permissions must be hard-coded. No custom configurations are allowed. For example, you cannot add permissions based on specific currencies. + +In addition, each permission needs to be implemented on its own in the source code. Adding a new permission requires an amendment. + + +## Failure Conditions + +The `DelegateSet` transaction fails if: + +- The `Permissions` array contains more than 10 entries. +- The `Permissions` array contains duplicate entries. +- Any of the specified `PermissionValues` are invalid. +- The `Authorize` account does not exist. + +## State Changes + +A successful `DelegateSet` transaction results in the creation, modification, or deletion of a `Delegate` ledger object. + +- If no `Delegate` object exists for the given `Account` and `Authorize` pair, a new one is created. +- If a `Delegate` object already exists, its `Permissions` field is updated. +- If the `Permissions` array is empty, the `Delegate` object is deleted. + +## Error Cases + +- If the `Account` is the same as `Authorize`, return `temMALFORMED`. + +- If the `Authorize` account does not exist, return `tecNO_TARGET`. + +- If the `Permissions` list size exceeds 10, return `temARRAY_TOO_LARGE`. + +- If `Permissions` contains a duplicate value, return `temMALFORMED`. + +- If `Permissions` contains transactions that are disabled for delegation, return `tecNO_PERMISSION`. +The transactions disabled for delegation include: `AccountSet`, `RegularKeySet`, `SignerListSet`, `AccountDelete`, `DelegateSet`, `EnableAmendment`, `SetFee`, `UNLModify`, `LedgerStateFix`. + +- If the Account does not have enough balance to meet the reserve requirement, (because `DelegateSet` will create a ledger object `ltDELEGATE`, whose owner is `Account`), return `tecINSUFFICIENT_RESERVE`. + +{% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/protocol/transactions/types/escrowcreate.md b/docs/references/protocol/transactions/types/escrowcreate.md index b6cfb2e2af..1be482a859 100644 --- a/docs/references/protocol/transactions/types/escrowcreate.md +++ b/docs/references/protocol/transactions/types/escrowcreate.md @@ -37,7 +37,7 @@ Sequester XRP until the escrow process either finishes or is canceled. | Field | JSON Type | [Internal Type][] | Description | |:-----------------|:----------|:------------------|:--------------------------| -| `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount], to deduct from the sender's balance and escrow. Once escrowed, the XRP can either go to the `Destination` address (after the `FinishAfter` time) or returned to the sender (after the `CancelAfter` time). | +| `Amount` | Object or String | Amount | Amount of XRP or fungible tokens to deduct from the sender's balance and escrow. Once escrowed, the payment can either go to the `Destination` address (after the `FinishAfter` time) or be returned to the sender (after the `CancelAfter` time). | | `Destination` | String | AccountID | Address to receive escrowed XRP. | | `CancelAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch][], when this escrow expires. This value is immutable; the funds can only be returned to the sender after this time. | | `FinishAfter` | Number | UInt32 | _(Optional)_ The time, in [seconds since the Ripple Epoch][], when the escrowed XRP can be released to the recipient. This value is immutable, and the funds can't be accessed until this time. | diff --git a/docs/references/protocol/transactions/types/offercreate.md b/docs/references/protocol/transactions/types/offercreate.md index b44a638311..b518923ae6 100644 --- a/docs/references/protocol/transactions/types/offercreate.md +++ b/docs/references/protocol/transactions/types/offercreate.md @@ -1,6 +1,4 @@ --- -html: offercreate.html -parent: transaction-types.html seo: description: Submit an order to exchange currency. labels: @@ -34,15 +32,15 @@ An OfferCreate transaction places an [Offer](../../../../concepts/tokens/decentr {% tx-example txid="0CD69FD1F0A890CC57CDA430213FD294F7D65FF4A0F379A0D09D07A222D324E6" /%} {% raw-partial file="/docs/_snippets/tx-fields-intro.md" /%} - -| Field | JSON Type | [Internal Type][] | Description | -|:---------------|:--------------------|:------------------|:------------------| -| [`Expiration`](../../../../concepts/tokens/decentralized-exchange/offers.md#offer-expiration) | Number | UInt32 | _(Optional)_ Time after which the Offer is no longer active, in [seconds since the Ripple Epoch][]. | -| `OfferSequence` | Number | UInt32 | _(Optional)_ An Offer to delete first, specified in the same way as [OfferCancel][]. | -| `TakerGets` | [Currency Amount][] | Amount | The amount and type of currency being sold. | -| `TakerPays` | [Currency Amount][] | Amount | The amount and type of currency being bought. | +| Field | JSON Type | [Internal Type][] | Required? | Description | +|:-----------------|:--------------------|:------------------|:----------|-------------| +| `DomainID` | String - [Hash][] | Hash256 | No | The ledger entry ID of a permissioned domain. If provided, restrict this offer to the [permissioned DEX](../../../../concepts/tokens/decentralized-exchange/permissioned-dexes.md) of that domain. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | +| [`Expiration`](../../../../concepts/tokens/decentralized-exchange/offers.md#offer-expiration) | Number | UInt32 | No | Time after which the Offer is no longer active, in [seconds since the Ripple Epoch][]. | +| `OfferSequence` | Number | UInt32 | No | An Offer to delete first, specified in the same way as [OfferCancel][]. | +| `TakerGets` | [Currency Amount][] | Amount | Yes | The amount and type of currency being sold. | +| `TakerPays` | [Currency Amount][] | Amount | Yes | The amount and type of currency being bought. | ## OfferCreate Flags @@ -50,31 +48,33 @@ Transactions of the OfferCreate type support additional values in the [`Flags` f | Flag Name | Hex Value | Decimal Value | Description | |:----------------------|:-------------|:--------------|:----------------------| -| `tfPassive` | `0x00010000` | 65536 | If enabled, the Offer does not consume Offers that exactly match it, and instead becomes an Offer object in the ledger. It still consumes Offers that cross it. | -| `tfImmediateOrCancel` | `0x00020000` | 131072 | Treat the Offer as an [Immediate or Cancel order](http://en.wikipedia.org/wiki/Immediate_or_cancel). The Offer never creates an [Offer object][] in the ledger: it only trades as much as it can by consuming existing Offers at the time the transaction is processed. If no Offers match, it executes "successfully" without trading anything. In this case, the transaction still uses the [result code](../transaction-results/index.md) `tesSUCCESS`. | -| `tfFillOrKill` | `0x00040000` | 262144 | Treat the offer as a [Fill or Kill order](http://en.wikipedia.org/wiki/Fill_or_kill). The Offer never creates an [Offer object][] in the ledger, and is canceled if it cannot be fully filled at the time of execution. By default, this means that the owner must receive the full `TakerPays` amount; if the `tfSell` flag is enabled, the owner must be able to spend the entire `TakerGets` amount instead. | +| `tfPassive` | `0x00010000` | 65536 | Do not consume offers that exactly match this one, only offers that cross it. This makes it possible to set up offers in the ledger that peg the exchange rate at a specific value. | +| `tfImmediateOrCancel` | `0x00020000` | 131072 | Treat the offer as an [Immediate or Cancel order](http://en.wikipedia.org/wiki/Immediate_or_cancel) and do not place an [Offer entry][] into the order books. The transaction trades as much as it can by consuming existing offers when it's processed. | +| `tfFillOrKill` | `0x00040000` | 262144 | Treat the offer as a [Fill or Kill order](http://en.wikipedia.org/wiki/Fill_or_kill), do not place an [Offer entry][] into the order books, and cancel the offer if it cannot be fully filled at the time of execution. By default, this means that the owner must receive the full `TakerPays` amount; if the `tfSell` flag is enabled, the owner must be able to spend the entire `TakerGets` amount instead. | | `tfSell` | `0x00080000` | 524288 | Exchange the entire `TakerGets` amount, even if it means obtaining more than the `TakerPays` amount in exchange. | +| `tfHybrid` | `0x00100000` | 1048576 | Make this a hybrid offer that can use both a permissioned DEX and the open DEX. The `DomainID` field must be provided when using this flag. | ## Error Cases | Error Code | Description | |:-------------------------|:--------------------------------------------------| -| `temINVALID_FLAG` | Occurs if the transaction specifies both `tfImmediateOrCancel` and `tfFillOrKill`. | -| `tecEXPIRED` | Occurs if the transaction specifies an `Expiration` time that has already passed. | -| `tecKILLED` | Occurs if the transaction specifies `tfFillOrKill`, and the full amount cannot be filled. If the _[ImmediateOfferKilled amendment][]_ is enabled, this result code also occurs when the transaction specifies `tfImmediateOrCancel` and executes without moving funds (previously, this would return `tesSUCCESS`). | -| `temBAD_EXPIRATION` | Occurs if the transaction contains an `Expiration` field that is not validly formatted. | -| `temBAD_SEQUENCE` | Occurs if the transaction contains an `OfferSequence` that is not validly formatted, or is higher than the transaction's own `Sequence` number. | -| `temBAD_OFFER` | Occurs if the Offer tries to trade XRP for XRP, or tries to trade an invalid or negative amount of a token. | -| `temREDUNDANT` | Occurs if the transaction specifies a token for the same token (same issuer and currency code). | -| `temBAD_CURRENCY` | Occurs if the transaction specifies a token with the currency code "XRP". | -| `temBAD_ISSUER` | Occurs if the transaction specifies a token with an invalid `issuer` value. | -| `tecNO_ISSUER` | Occurs if the transaction specifies a token whose `issuer` value is not a funded account in the ledger. | -| `tecFROZEN` | Occurs if the transaction involves a token on a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) trust line (including local and global freezes). Occurs if the `TakerPays` (buy amount) token has been deep-frozen by the issuer. | -| `tecUNFUNDED_OFFER` | Occurs if the owner does not hold a positive amount of the `TakerGets` currency. (Exception: if `TakerGets` specifies a token that the owner issues, the transaction can succeed.) | -| `tecNO_LINE` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the necessary trust line does not exist. | -| `tecNO_AUTH` | Occurs if the transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the the trust line that would receive the tokens exists but has not been authorized. | -| `tecINSUF_RESERVE_OFFER` | Occurs if the owner does not have enough XRP to meet the reserve requirement of adding a new Offer object to the ledger, and the transaction did not convert any currency. (If the transaction successfully traded any amount, the transaction succeeds with the result code `tesSUCCESS`, but does not create an Offer object in the ledger for the rest.) | -| `tecDIR_FULL` | Occurs if the owner owns too many items in the ledger, or the order book contains too many Offers at the same exchange rate already. | +| `tecDIR_FULL` | The owner owns too many items in the ledger, or the order book contains too many Offers at the same exchange rate already. | +| `tecEXPIRED` | The transaction specifies an `Expiration` time that has already passed. | +| `tecFROZEN` | The transaction involves a token on a [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) trust line (including local and global freezes). The `TakerPays` (buy amount) token has been deep-frozen by the issuer. | +| `tecINSUF_RESERVE_OFFER` | The owner does not have enough XRP to meet the reserve requirement of adding a new offer ledger entry, and the transaction did not convert any currency. (If the transaction successfully traded any amount, the transaction succeeds with the result code `tesSUCCESS`, but does not create an offer ledger entry for the remainder.) | +| `tecKILLED` | The transaction specifies `tfFillOrKill`, and the full amount cannot be filled. If the _[ImmediateOfferKilled amendment][]_ is enabled, this result code also occurs when the transaction specifies `tfImmediateOrCancel` and executes without moving funds (previously, an Immediate or Cancel offer would return `tesSUCCESS` even if no funds were moved). | +| `tecNO_AUTH` | The transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the the trust line that would receive the tokens exists but has not been authorized. | +| `tecNO_ISSUER` | The transaction specifies a token whose `issuer` value is not a funded account in the ledger. | +| `tecNO_LINE` | The transaction involves a token whose issuer uses [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) and the necessary trust line does not exist. | +| `tecNO_PERMISSION` | The transaction uses a `DomainID` but the sender is not a member of that domain. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | +| `tecUNFUNDED_OFFER` | The owner does not hold a positive amount of the `TakerGets` currency. (Exception: if `TakerGets` specifies a token that the owner issues, the transaction can succeed.) | +| `temBAD_CURRENCY` | The transaction specifies a fungible token incorrectly, such as a fungible token with the currency code "XRP". | +| `temBAD_EXPIRATION` | The transaction contains an `Expiration` field that is not validly formatted. | +| `temBAD_ISSUER` | The transaction specifies a token with an invalid `issuer` value. | +| `temBAD_OFFER` | The offer tries to trade XRP for XRP, or tries to trade an invalid or negative amount of a token. | +| `temBAD_SEQUENCE` | The transaction contains an `OfferSequence` that is not validly formatted, or is higher than the transaction's own `Sequence` number. | +| `temINVALID_FLAG` | The transaction specifies an invalid flag combination, such as both `tfImmediateOrCancel` and `tfFillOrKill`, or the transaction uses `tfHybrid` but omits the `DomainID` field. | +| `temREDUNDANT` | The transaction would trade a token for the same token (same issuer and currency code). | {% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/docs/references/protocol/transactions/types/payment.md b/docs/references/protocol/transactions/types/payment.md index 98231775e2..571e0828e4 100644 --- a/docs/references/protocol/transactions/types/payment.md +++ b/docs/references/protocol/transactions/types/payment.md @@ -1,6 +1,4 @@ --- -html: payment.html -parent: transaction-types.html seo: description: Send funds from one account to another. labels: @@ -10,7 +8,7 @@ labels: - Tokens --- # Payment -[[Source]](https://github.com/XRPLF/rippled/blob/5425a90f160711e46b2c1f1c93d68e5941e4bfb6/src/ripple/app/transactors/Payment.cpp "Source") +[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/app/tx/detail/Payment.cpp "Source") A Payment transaction represents a transfer of value from one account to another. (Depending on the path taken, this can involve additional exchanges of value, which occur atomically.) This transaction type can be used for several [types of payments](#types-of-payments). @@ -44,10 +42,11 @@ Payments are also the only way to [create accounts](#creating-accounts). | `Amount` | [Currency Amount][] | Amount | API v1: Yes | Alias to `DeliverMax`. | | `CredentialIDs` | Array of Strings | Vector256 | No | Set of Credentials to authorize a deposit made by this transaction. Each member of the array must be the ledger entry ID of a Credential entry in the ledger. _(Requires the [Credentials amendment][]._ {% not-enabled /%})_ | | `DeliverMax` | [Currency Amount][] | Amount | Yes | [API v2][]: The maximum amount of currency to deliver. [Partial payments](#partial-payments) can deliver less than this amount and still succeed; other payments fail unless they deliver the exact amount. {% badge href="https://github.com/XRPLF/rippled/releases/tag/2.0.0" %}New in: rippled 2.0.0{% /badge %} | -| `DeliverMin` | [Currency Amount][] | Amount | No | Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](../../../../concepts/payment-types/partial-payments.md). For non-XRP amounts, the nested field names are lower-case. | -| `Destination` | String | AccountID | Yes | The unique address of the account receiving the payment. | +| `DeliverMin` | [Currency Amount][] | Amount | No | Minimum amount of destination currency this transaction should deliver. Only valid if this is a [partial payment](#partial-payments). | +| `Destination` | String - [Address][] | AccountID | Yes | The account receiving the payment. | | `DestinationTag` | Number | UInt32 | No | Arbitrary tag that identifies the reason for the payment to the destination, or a hosted recipient to pay. | -| `InvoiceID` | String | Hash256 | No | Arbitrary 256-bit hash representing a specific reason or identifier for this payment. | +| `DomainID` | String - [Hash][] | Hash256 | No | The ledger entry ID of a permissioned domain. If this is a cross-currency payment, only use the corresponding [permissioned DEX](../../../../concepts/tokens/decentralized-exchange/permissioned-dexes.md) to convert currency. Both the sender and the recipient must have valid credentials that grant access to the specified domain. This field has no effect if the payment is not cross-currency. _(Requires the [PermissionedDEX amendment][] {% not-enabled /%})_ | +| `InvoiceID` | String - Hexadecimal | Hash256 | No | Arbitrary 256-bit value representing a specific reason or identifier for this payment. | | `Paths` | Array of path arrays | PathSet | No | _(Auto-fillable)_ Array of [payment paths](../../../../concepts/tokens/fungible-tokens/paths.md) to be used for this transaction. Must be omitted for XRP-to-XRP transactions. | | `SendMax` | [Currency Amount][] | Amount | No | Highest amount of source currency this transaction is allowed to cost, including [transfer fees](../../../../concepts/tokens/transfer-fees.md), exchange rates, and [slippage](http://en.wikipedia.org/wiki/Slippage_%28finance%29). Does not include the [XRP destroyed as a cost for submitting the transaction](../../../../concepts/transactions/transaction-cost.md). Must be supplied for cross-currency/cross-issue payments. Must be omitted for XRP-to-XRP payments. | @@ -65,7 +64,7 @@ The `Payment` transaction type functions differently depending on how you fill i | [Cross-currency Payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Send tokens from one holder to another. The `Amount` or `SendMax` can be XRP or tokens, but can't both be XRP. These payments [ripple through](../../../../concepts/tokens/fungible-tokens/rippling.md) the issuer and can take longer [paths](../../../../concepts/tokens/fungible-tokens/paths.md) through several intermediaries if the transaction specifies a path set. [Transfer fees](../../../../concepts/tokens/transfer-fees.md) set by the issuer(s) apply to this type of transaction. These transactions consume offers in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md) to connect different currencies, or currencies with the same currency code and different issuers. | | [Partial payment][] | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Usually required | No | Sends _up to_ a specific amount of any currency. Uses the [`tfPartialPayment` flag](#payment-flags). May include a `DeliverMin` amount specifying the minimum that the transaction must deliver to be successful; if the transaction does not specify `DeliverMin`, it can succeed by delivering _any positive amount_. | | Currency conversion | Object (non-XRP) / String (XRP) | Object (non-XRP) / String (XRP) | Required | Yes | Consumes offers in the [decentralized exchange](../../../../concepts/tokens/decentralized-exchange/index.md) to convert one currency to another, possibly taking [arbitrage](https://en.wikipedia.org/wiki/Arbitrage) opportunities. The `Amount` and `SendMax` cannot both be XRP. Also called a _circular payment_ because it delivers money to the sender. This type of transaction may be classified as an "exchange" and not a "payment". | -| MPT Payment | Object | Omitted | Omitted | Yes | Send MPTs to a holder. See [MPT Payments](#mpt-payments). | +| MPT Payment | Object | Omitted | Omitted | No | Send MPTs to a holder. See [MPT Payments](#mpt-payments). | [Direct XRP Payment]: ../../../../concepts/payment-types/direct-xrp-payments.md [Creating or redeeming tokens]: ../../../../concepts/tokens/index.md @@ -77,11 +76,14 @@ The `Payment` transaction type functions differently depending on how you fill i -Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates the issuer of a token. However, when describing payments, there are special rules for the `issuer` field in the `Amount` and `SendMax` fields of a payment. +Most of the time, the `issuer` field of a non-XRP [Currency Amount][] indicates the issuer of a token. However, when describing payments, there are special rules for the `issuer` field in the `DeliverMax` (or `Amount`) and `SendMax` fields of a payment. * There is only ever one balance between two addresses for the same currency code. This means that, sometimes, the `issuer` field of an amount actually refers to a counterparty, instead of the address that issued the token. -* When the `issuer` field of the destination `Amount` field matches the `Destination` address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all addresses to which the destination has trust lines with a positive limit, as well as tokens with the same currency code issued by the destination. -* When the `issuer` field of the `SendMax` field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." This includes creating new tokens on trust lines that other accounts have extended to the source account, and sending tokens the source account holds from other issuers. +* When the `issuer` field of the destination `DeliverMax` field matches the `Destination` address, it is treated as a special case meaning "any issuer that the destination accepts." This includes all addresses to which the destination has trust lines with a positive limit, as well as tokens issued by the destination itself. +* When the `issuer` field of the `SendMax` field matches the source account's address, it is treated as a special case meaning "any issuer that the source can use." The payment can send tokens the source account already holds, or issue new tokens to others who have trust lines with the source account. + +In all of these cases, the currency code must still match exactly. + ## Creating Accounts @@ -111,7 +113,7 @@ Transactions of the Payment type support additional values in the [`Flags` field | Flag Name | Hex Value | Decimal Value | Description | |:-------------------|:-------------|:--------------|:-----------------------------| | `tfNoRippleDirect` | `0x00010000` | 65536 | Do not use the default path; only use paths included in the `Paths` field. This is intended to force the transaction to take arbitrage opportunities. Most clients do not need this. | -| `tfPartialPayment` | `0x00020000` | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](../../../../concepts/payment-types/partial-payments.md) for more details. | +| `tfPartialPayment` | `0x00020000` | 131072 | If the specified `Amount` cannot be sent without spending more than `SendMax`, reduce the received amount instead of failing outright. See [Partial Payments](#partial-payments) for more details. | | `tfLimitQuality` | `0x00040000` | 262144 | Only take paths where all the conversions have an input:output ratio that is equal or better than the ratio of `Amount`:`SendMax`. See [Limit Quality](#limit-quality) for details. | ## Partial Payments @@ -186,6 +188,10 @@ The credentials provided in the `CredentialIDs` field must all be valid, meaning If you provide credentials even though the destination account does not use Deposit Authorization, the credentials are not needed but they are still checked for validity. +{% admonition type="info" name="Note" %} +The `CredentialIDs` field is only used for deposit authorization, not for trading in a [permissioned DEX](../../../../concepts/tokens/decentralized-exchange/permissioned-dexes.md), even though Permissioned DEXes also use credentials to grant access. To trade in a permissioned DEX, you use the `DomainID` field to specify a domain for which you hold valid credentials. +{% /admonition %} + ## Special Case for Destination Accounts Below the Reserve If an account has Deposit Authorization enabled, but its current XRP balance is less than the [reserve requirement](../../../../concepts/accounts/reserves.md), there is a special exception to Deposit Authorization where anyone can send a Payment transaction, without preauthorization, for up to the base account reserve; this exists as an emergency measure to prevent an account from getting "stuck" without enough XRP to transact. To qualify for this special case, the payment MUST NOT use the `CredentialIDs` field. diff --git a/docs/references/protocol/transactions/types/paymentchannelclaim.md b/docs/references/protocol/transactions/types/paymentchannelclaim.md index bde559aeae..82fcf3c6b5 100644 --- a/docs/references/protocol/transactions/types/paymentchannelclaim.md +++ b/docs/references/protocol/transactions/types/paymentchannelclaim.md @@ -11,23 +11,23 @@ labels: _Added by the [PayChan amendment][]._ -Claim XRP from a payment channel, adjust the payment channel's expiration, or both. This transaction can be used differently depending on the transaction sender's role in the specified channel: +Claim XRP or fungible tokens from a payment channel, adjust the payment channel's expiration, or both. This transaction can be used differently depending on the transaction sender's role in the specified channel: The **source address** of a channel can: -- Send XRP from the channel to the destination with _or without_ a signed Claim. +- Send XRP or fungible tokens from the channel to the destination with _or without_ a signed Claim. - Set the channel to expire as soon as the channel's `SettleDelay` has passed. - Clear a pending `Expiration` time. -- Close a channel immediately, with or without processing a claim first. The source address cannot close the channel immediately if the channel has XRP remaining. +- Close a channel immediately, with or without processing a claim first. The source address cannot close the channel immediately if the channel has any amount remaining. The **destination address** of a channel can: -- Receive XRP from the channel using a signed Claim. -- Close the channel immediately after processing a Claim, refunding any unclaimed XRP to the channel's source. +- Receive XRP or fungible tokens from the channel using a signed Claim. +- Close the channel immediately after processing a Claim, refunding any unclaimed amount to the channel's source. **Any address** sending this transaction can: -- Cause a channel to be closed if its `Expiration` or `CancelAfter` time is older than the previous ledger's close time. Any validly-formed PaymentChannelClaim transaction has this effect regardless of the contents of the transaction. +- Cause a channel to be closed if its `Expiration` or `CancelAfter` time is older than the previous ledger's close time. Any validly formed `PaymentChannelClaim` transaction has this effect, regardless of the contents of the transaction. ## Example {% $frontmatter.seo.title %} JSON @@ -50,8 +50,8 @@ The **destination address** of a channel can: | Field | JSON Type | [Internal Type][] | Required? | Description | |:------------|:----------|:------------------|:----------|:------------| -| `Amount` | String | Amount | No | The amount of [XRP, in drops][Currency Amount], authorized by the `Signature`. This must match the amount in the signed message. This is the cumulative amount of XRP that can be dispensed by the channel, including XRP previously redeemed. | -| `Balance` | String | Amount | No | Total amount of [XRP, in drops][Currency Amount], delivered by this channel after processing this claim. Required to deliver XRP. Must be more than the total amount delivered by the channel so far, but not greater than the `Amount` of the signed claim. Must be provided except when closing the channel. | +| `Amount` | Object or String | Amount | No | The amount of [XRP, in drops][Currency Amount], or fungible tokens authorized by the `Signature`. This must match the amount in the signed message. This is the cumulative amount of XRP and fungible tokens that can be dispensed by the channel, including funds previously redeemed. | +| `Balance` | String | Amount | No | Total amount of [XRP, in drops][Currency Amount], or fungible tokens delivered by this channel after processing this claim. Required to deliver XRP or fungible tokens. Must be more than the total amount delivered by the channel so far, but not greater than the `Amount` of the signed claim. Must be provided except when closing the channel. | | `Channel` | String | Hash256 | Yes | The unique ID of the channel, as a 64-character hexadecimal string. | | `CredentialIDs` | Array of Strings | Vector256 | No | Set of Credentials to authorize a deposit made by this transaction. Each member of the array must be the ledger entry ID of a Credential entry in the ledger. For details, see [Credential IDs](./payment.md#credential-ids). | | `PublicKey` | String | Blob | No | The public key used for the signature, as hexadecimal. This must match the `PublicKey` stored in the ledger for the channel. Required unless the sender of the transaction is the source address of the channel and the `Signature` field is omitted. (The transaction includes the public key so that `rippled` can check the validity of the signature before trying to apply the transaction to the ledger.) | @@ -62,7 +62,7 @@ If the payment channel was created before the [fixPayChanRecipientOwnerDir amend ## PaymentChannelClaim Flags -Transactions of the PaymentChannelClaim type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows: +Transactions of the `PaymentChannelClaim` type support additional values in the [`Flags` field](../common-fields.md#flags-field), as follows: | Flag Name | Hex Value | Decimal Value | Description | |:----------|:-------------|:--------------|:----------------------------------| diff --git a/docs/references/protocol/transactions/types/paymentchannelcreate.md b/docs/references/protocol/transactions/types/paymentchannelcreate.md index ef8d63f2d8..d2801c0ddc 100644 --- a/docs/references/protocol/transactions/types/paymentchannelcreate.md +++ b/docs/references/protocol/transactions/types/paymentchannelcreate.md @@ -1,6 +1,4 @@ --- -html: paymentchannelcreate.html -parent: transaction-types.html seo: description: Open a new payment channel. labels: @@ -36,7 +34,7 @@ Create a [payment channel](../../../../concepts/payment-types/payment-channels.m | Field | JSON Type | [Internal Type][] | Description | |:-----------------|:----------|:------------------|:--------------------------| -| `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount], to deduct from the sender's balance and set aside in this channel. While the channel is open, the XRP can only go to the `Destination` address. When the channel closes, any unclaimed XRP is returned to the source address's balance. | +| `Amount` | Object or String | Amount | Amount to deduct from the sender's balance and set aside in this channel. While the channel is open, the amount can only go to the `Destination` address. When the channel closes, any unclaimed amount is returned to the source account's balance.| | `Destination` | String | AccountID | Address to receive XRP claims against this channel. This is also known as the "destination address" for the channel. Cannot be the same as the sender (`Account`). | | `SettleDelay` | Number | UInt32 | Amount of time the source address must wait before closing the channel if it has unclaimed XRP. | | `PublicKey` | String | Blob | The 33-byte public key of the key pair the source will use to sign claims against this channel, in hexadecimal. This can be any secp256k1 or Ed25519 public key. For more information on key pairs, see [Key Derivation](../../../../concepts/accounts/cryptographic-keys.md#key-derivation) | diff --git a/docs/references/protocol/transactions/types/paymentchannelfund.md b/docs/references/protocol/transactions/types/paymentchannelfund.md index 699b8f4469..544a2c5540 100644 --- a/docs/references/protocol/transactions/types/paymentchannelfund.md +++ b/docs/references/protocol/transactions/types/paymentchannelfund.md @@ -11,7 +11,7 @@ labels: _Added by the [PayChan amendment][]._ -Add additional [XRP](../../../../introduction/what-is-xrp.md) to an open [payment channel](../../../../concepts/payment-types/payment-channels.md), and optionally update the expiration time of the channel. Only the source address of the channel can use this transaction. +Add an additional amount to an open [payment channel](../../../../concepts/payment-types/payment-channels.md), and optionally update the expiration time of the channel. Only the source account of the channel can use this transaction. Example PaymentChannelFund: @@ -33,7 +33,7 @@ Example PaymentChannelFund: | Field | JSON Type | [Internal Type][] | Description | |:-------------|:----------|:------------------|:------------------------------| | `Channel` | String | Hash256 | The unique ID of the channel to fund, as a 64-character hexadecimal string. | -| `Amount` | String | Amount | Amount of [XRP, in drops][Currency Amount] to add to the channel. Must be a positive amount of XRP. | +| `Amount` | Object or String | Amount | Amount to add to the channel. Must be a positive amount. | | `Expiration` | Number | UInt32 | _(Optional)_ New `Expiration` time to set for the channel, in [seconds since the Ripple Epoch][]. This must be later than either the current time plus the `SettleDelay` of the channel, or the existing `Expiration` of the channel. After the `Expiration` time, any transaction that would access the channel closes the channel without taking its normal action. Any unspent XRP is returned to the source address when the channel closes. (`Expiration` is separate from the channel's immutable `CancelAfter` time.) For more information, see the [PayChannel ledger object type](../../ledger-data/ledger-entry-types/paychannel.md). | ## Error Cases @@ -46,8 +46,8 @@ Besides errors that can occur for all transactions, {% $frontmatter.seo.title %} | `tecNO_DST` | The destination account of the channel has been deleted. This is only possible if the payment channel was created before the [fixPayChanRecipientOwnerDir amendment](/resources/known-amendments.md#fixpaychanrecipientownerdir) became enabled (on 2020-05-01). | | `tecNO_ENTRY` | The Payment Channel identified by the `Channel` field does not exist. | | `tecNO_PERMISSION` | The sender of the transaction is not the source address for the channel. | -| `tecUNFUNDED` | The sending account does not have enough XRP to fund the channel with the requested amount and still meet the [reserve requirement](../../../../concepts/accounts/reserves.md). | -| `temBAD_AMOUNT` | The `Amount` field of the transaction is invalid. The amount must be XRP and it cannot be zero or negative. | +| `tecUNFUNDED` | The sending account does not have enough XRP or fungible tokens to fund the channel with the requested amount and still meet the [reserve requirement](../../../../concepts/accounts/reserves.md). | +| `temBAD_AMOUNT` | The `Amount` field of the transaction is invalid. The amount must either be XRP or fungible tokens and cannot be zero or negative. | | `temBAD_EXPIRATION` | The `Expiration` field is invalid. | {% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/resources/known-amendments.md b/resources/known-amendments.md index bdd1a0fbd3..ce3ffa49ad 100644 --- a/resources/known-amendments.md +++ b/resources/known-amendments.md @@ -17,6 +17,13 @@ This list is updated manually. For a live view of amendment voting, see the Amen | Name | Introduced | Status | |:----------------------------------|:-----------|:------------------------------| +| [Batch][] | v2.5.0 | {% badge href="https://xrpl.org/blog/2025/rippled-2.5.0" %}Open for Voting: 2025-06-24{% /badge %} | +| [PermissionDelegation][] | v2.5.0 | {% badge href="https://xrpl.org/blog/2025/rippled-2.5.0" %}Open for Voting: 2025-06-24{% /badge %} | +| [PermissionedDEX][] | v2.5.0 | {% badge href="https://xrpl.org/blog/2025/rippled-2.5.0" %}Open for Voting: 2025-06-24{% /badge %} | +| [TokenEscrow][] | v2.5.0 | {% badge href="https://xrpl.org/blog/2025/rippled-2.5.0" %}Open for Voting: 2025-06-24{% /badge %} | +| [fixAMMv1_3][] | v2.5.0 | {% badge href="https://xrpl.org/blog/2025/rippled-2.5.0" %}Open for Voting: 2025-06-24{% /badge %} | +| [fixEnforceNFTokenTrustlineV2][] | v2.5.0 | {% badge href="https://xrpl.org/blog/2025/rippled-2.5.0" %}Open for Voting: 2025-06-24{% /badge %} | +| [fixPayChanCancelAfter][] | v2.5.0 | {% badge href="https://xrpl.org/blog/2025/rippled-2.5.0" %}Open for Voting: 2025-06-24{% /badge %} | | [DynamicNFT][] | v2.4.0 | {% badge href="https://xrpl.org/blog/2025/fixes-enabled-dnfts-expected" %}Expected: 2025-06-11{% /badge %} | | [PermissionedDomains][] | v2.4.0 | {% badge href="https://xrpl.org/blog/2025/rippled-2.4.0" %}Open for Voting: 2025-03-06{% /badge %} | | [Credentials][] | v2.3.0 | {% badge href="https://xrpl.org/blog/2024/rippled-2.3.0" %}Open for Voting: 2024-11-26{% /badge %} | @@ -113,14 +120,7 @@ The following is a list of [amendments](../docs/concepts/networks-and-servers/am | [Hooks][] | {% badge %}In Development: TBD{% /badge %} | [XRPL Hooks](https://hooks.xrpl.org/) | | [InvariantsV1_1][] | {% badge %}In Development: TBD{% /badge %} | | | [OwnerPaysFee][] | {% badge %}In Development: TBD{% /badge %} | | -| [Batch][] | {% badge %}In Development: TBD{% /badge %} | | -| [fixAMMv1_3][] | {% badge %}In Development: TBD{% /badge %} | | -| [fixEnforceNFTokenTrustlineV2][] | {% badge %}In Development: TBD{% /badge %} | | -| [fixPayChanCancelAfter][] | {% badge %}In Development: TBD{% /badge %} | | -| [PermissionDelegation][] | {% badge %}In Development: TBD{% /badge %} | | -| [PermissionedDEX][] | {% badge %}In Development: TBD{% /badge %} | | | [SingleAssetVault][] | {% badge %}In Development: TBD{% /badge %} | | -| [TokenEscrow][] | {% badge %}In Development: TBD{% /badge %} | | {% admonition type="success" name="Tip" %} This list is updated manually. If you're working on an amendment and have a private network to test the changes, you can edit this page to add your in-development amendment to this list. For more information on contributing to the XRP Ledger, see [Contribute Code to the XRP Ledger](contribute-code/index.md). @@ -201,7 +201,7 @@ For details, see the [XLS-73: AMMClawback specification](https://github.com/XRPL | Amendment | Batch | |:-------------|:------| | Amendment ID | 894646DD5284E97DECFE6674A6D6152686791C4A95F8C132CCA9BAF9E5812FB6 | -| Status | In Development | +| Status | Open for Voting | | Default Vote (Latest stable release) | No | | Pre-amendment functionality retired? | No | @@ -810,7 +810,7 @@ Fixes two bugs in Automated Market Maker (AMM) transaction processing: | Amendment | fixAMMv1_3 | |:-------------|:-----------| | Amendment ID | 7CA70A7674A26FA517412858659EBC7EDEEF7D2D608824464E6FDEFD06854E14 | -| Status | In Development | +| Status | Open for Voting | | Default Vote (Latest stable release) | No | | Pre-amendment functionality retired? | No | @@ -1147,7 +1147,7 @@ See [Issue 4373](https://github.com/XRPLF/rippled/issues/4373). | Amendment | fixPayChanCancelAfter | |:-------------|:----------------------| | Amendment ID | D3456A862DC07E382827981CA02E21946E641877F19B8889031CC57FDCAC83E2 | -| Status | In Development | +| Status | Open for Voting | | Default Vote (Latest stable release) | No | | Pre-amendment functionality retired? | No | @@ -1673,7 +1673,7 @@ For more information, see the [Payment Channels Tutorial](../docs/tutorials/how- | Amendment | PermissionDelegation | |:-------------|:---------------------| | Amendment ID | AE6AB9028EEB7299EBB03C7CBCC3F2A4F5FBE00EA28B8223AA3118A0B436C1C5 | -| Status | In Development | +| Status | Open for Voting | | Default Vote (Latest stable release) | No | | Pre-amendment functionality retired? | No | @@ -1688,7 +1688,7 @@ Specification: [XLS-75](https://github.com/XRPLF/XRPL-Standards/tree/master/XLS- | Amendment | PermissionedDEX | |:-------------|:----------------| | Amendment ID | 677E401A423E3708363A36BA8B3A7D019D21AC5ABD00387BDBEA6BDE4C91247E | -| Status | In Development | +| Status | Open for Voting | | Default Vote (Latest stable release) | No | | Pre-amendment functionality retired? | No | @@ -1853,7 +1853,7 @@ Introduces a `TickSize` field to accounts, which can be set with the [AccountSet | Amendment | TokenEscrow | |:-------------|:------------| | Amendment ID | 138B968F25822EFBF54C00F97031221C47B1EAB8321D93C7C2AEAF85F04EC5DF | -| Status | In Development | +| Status | Open for Voting | | Default Vote (Latest stable release) | No | | Pre-amendment functionality retired? | No | diff --git a/sidebars.yaml b/sidebars.yaml index 91d565bff8..d6acf43f65 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -76,6 +76,7 @@ - page: docs/concepts/transactions/index.md expanded: false items: + - page: docs/concepts/transactions/batch-transactions.md - page: docs/concepts/transactions/fees.md - page: docs/concepts/transactions/reliable-transaction-submission.md - page: docs/concepts/transactions/secure-signing.md @@ -149,6 +150,7 @@ - page: docs/concepts/tokens/decentralized-exchange/ticksize.md - page: docs/concepts/tokens/decentralized-exchange/automated-market-makers.md - page: docs/concepts/tokens/decentralized-exchange/permissioned-domains.md + - page: docs/concepts/tokens/decentralized-exchange/permissioned-dexes.md - page: docs/concepts/accounts/index.md expanded: false items: @@ -161,6 +163,7 @@ - page: docs/concepts/accounts/multi-signing.md - page: docs/concepts/accounts/depositauth.md - page: docs/concepts/accounts/tickets.md + - page: docs/concepts/accounts/permission-delegation.md - page: docs/concepts/xrpl-sidechains/index.md expanded: false items: @@ -383,6 +386,7 @@ - page: docs/references/protocol/transactions/types/ammdeposit.md - page: docs/references/protocol/transactions/types/ammvote.md - page: docs/references/protocol/transactions/types/ammwithdraw.md + - page: docs/references/protocol/transactions/types/batch.md - page: docs/references/protocol/transactions/types/credentialaccept.md - page: docs/references/protocol/transactions/types/credentialcreate.md - page: docs/references/protocol/transactions/types/credentialdelete.md @@ -391,6 +395,7 @@ - page: docs/references/protocol/transactions/types/checkcreate.md - page: docs/references/protocol/transactions/types/clawback.md - page: docs/references/protocol/transactions/types/depositpreauth.md + - page: docs/references/protocol/transactions/types/delegateset.md - page: docs/references/protocol/transactions/types/diddelete.md - page: docs/references/protocol/transactions/types/didset.md - page: docs/references/protocol/transactions/types/escrowcancel.md