ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 11:45:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3150 from XRPLF/rippled-2.5.0

Browse Source 
Rippled 2.5.0
This commit is contained in:
oeggert
2025-06-24 11:44:17 -07:00
committed by GitHub
parent 55934e03b8 f3f783b07e
commit a253e654db
36 changed files with 1951 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/references/protocol/transactions/common-fields.md
View File

@@ -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:

392
docs/references/protocol/transactions/types/batch.md Normal file
View File

@@ -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
<!-- {% include '_snippets/tx-fields-intro.md' %} -->
| 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": ""
}
]
```

145
docs/references/protocol/transactions/types/delegateset.md Normal file
View File

@@ -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" /%}

2
docs/references/protocol/transactions/types/escrowcreate.md
View File

@@ -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. |

56
docs/references/protocol/transactions/types/offercreate.md
View File

@@ -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" /%}
<!--{# fix md highlighting_ #}-->
| 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" /%}

28
docs/references/protocol/transactions/types/payment.md
View File

@@ -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
<!-- SPELLING_IGNORE: sendmax -->
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.

18
docs/references/protocol/transactions/types/paymentchannelclaim.md
View File

@@ -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 |
|:----------|:-------------|:--------------|:----------------------------------|

4
docs/references/protocol/transactions/types/paymentchannelcreate.md
View File

@@ -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) <!-- STYLE_OVERRIDE: will --> |

8
docs/references/protocol/transactions/types/paymentchannelfund.md
View File

@@ -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" /%}