Transaction Common Fields
Last updated
Last updated
Every transaction has the same set of common fields, plus additional fields based on the transaction type. Field names are case-sensitive. The common fields for all transactions are:
Field | JSON Type | [Internal Type][] | Description |
---|---|---|---|
[Removed in: rippled 0.28.0][]: The PreviousTxnID
field of transactions was replaced by the AccountTxnID
field. This String / Hash256 field is present in some historical transactions. This is unrelated to the field also named PreviousTxnID
in some ledger objects.
The AccountTxnID
field lets you chain your transactions together, so that a current transaction is not valid unless the previous transaction sent from the same account has a specific [transaction hash][identifying hash].
Unlike the PreviousTxnID
field, which tracks the last transaction to modify an account (regardless of sender), the AccountTxnID
tracks the last transaction sent by an account. To use AccountTxnID
, you must first enable the asfAccountTxnID
flag, so that the ledger keeps track of the ID for the account's previous transaction. (PreviousTxnID
, by comparison, is always tracked.)
One situation in which this is useful is if you have a primary system for submitting transactions and a passive backup system. If the passive backup system becomes disconnected from the primary, but the primary is not fully dead, and they both begin operating at the same time, you could potentially have serious problems like some transactions sending twice and others not at all. Chaining your transactions together with AccountTxnID
ensures that, even if both systems are active, only one of them can submit valid transactions at a time.
The AccountTxnID
field cannot be used on transactions that use Tickets. Transactions that use AccountTxnID
cannot be placed in the transaction queue.
Some fields can be automatically filled in before a transaction is signed, either by a xahaud
server or by a client library. Auto-filling values requires an active connection to Xahau 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:
Fee
- Automatically fill in the [Transaction Cost][] based on the network.
Note: When using xahaud
's [sign command][], you can limit the maximum possible auto-filled value, using the fee_mult_max
and fee_mult_div
parameters.)
Sequence
- Automatically use the next sequence number for the account sending the transaction.
For a production system, we recommend not leaving these fields to be filled by the server. For example, if transaction costs become high due to a temporary spike in network load, you may want to wait for the cost to decrease before sending some transactions, instead of paying the temporarily-high cost.
The Paths
field of the [Payment transaction][] type can also be automatically filled in.
The Flags
field can contain various options that affect how a transaction should behave. The options are represented as binary values that can be combined with bitwise-or operations to set multiple flags at once.
To check whether a transaction has a given flag enabled, use the bitwise-and operator on the flag's value and the Flags
field. A result of zero indicates the flag is disabled, and a result equal to the flag value indicates the flag is enabled. (If you got any other result, you did something wrong.)
Most flags only have meaning for a specific transaction type. The same bitwise value may be reused for flags on different transaction types, so it is important to pay attention to the TransactionType
field when setting and reading flags.
Bits that are not defined as flags MUST be 0. (The [fix1543 amendment][] enforces this rule on some transaction types. Most transaction types enforce this rule by default.)
The only flag that applies globally to all transactions is as follows:
When using the [sign method][] (or [submit method][] in "sign-and-submit" mode), xahaud
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.
Note: The tfFullyCanonicalSig
flag was used from 2014 until 2020 to protect against transaction malleability while maintaining compatibility with legacy signing software. The [RequireFullyCanonicalSig amendment][] ended compatibility with such legacy software and made the protections the default for all transactions. If you are using a parallel network that does not have RequireFullyCanonicalSig enabled, you should always enable the tfFullyCanonicalSig
flag to protect against transaction malleability.
A transaction's Flags
field can contain flags that apply at different levels or contexts. Flags for each context are limited to the following ranges:
Note: The [AccountSet transaction][] type has its own non-bitwise flags, which serve a similar purpose to type-based flags. Ledger objects also have a Flags
field with different bitwise flag definitions.
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:
The MemoType
and MemoFormat
fields should only consist of the following characters: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%
The Memos
field is limited to no more than 1 KB in size (when serialized in binary format).
Example of a transaction with a Memos field:
[New in: rippled 1.11.0][]
The NetworkID
field is a protection against "cross-chain" transaction replay attacks, preventing the same transaction from being copied over and executing on a parallel network that it wasn't intended for. For compatibility with existing chains, the NetworkID
field must be omitted on any network with a Network ID of 1024 or less, but must be included on any network with a Network ID of 1025 or greater. The following table shows the status and values for various known networks:
Transaction replay attacks are theoretically possible, but require specific conditions on the second network. All of the following must be true:
The transaction's sender is a funded account on the second network.
The sender's Sequence
number on the second network matches the transaction's Sequence
, or the transaction uses a Ticket that's available on the second network.
Either the transaction does not have a LastLedgerSequence
field, or it specifies a value that is higher than the current ledger index on the second ledger.
Mainnet generally has a higher ledger index than test networks or sidechains, so it is easier to replay Mainnet transactions on a sidechain or test network than the other way around, when transactions use LastLedgerSequence
as intended.
Either the networks both have IDs of 1024 or less, both networks use the same ID, or the second network does not require the NetworkID
field.
The Signers
field contains a multi-signature, which has signatures from up to 8 key pairs, that together should authorize the transaction. The Signers
list is an array of objects, each with one field, Signer
. The Signer
field has the following nested fields:
The SigningPubKey
must be a key that is associated with the Account
address. If the referenced Account
is a funded account in the ledger, then the SigningPubKey
can be that account's current Regular Key if one is set. It could also be that account's Master Key, unless the lsfDisableMaster
flag is enabled. If the referenced Account
address is not a funded account in the ledger, then the SigningPubKey
must be the master key associated with that address.
Because signature verification is a compute-intensive task, multi-signed transactions cost additional XAH to relay to the network. Each signature included in the multi-signature increases the [transaction cost][] required for the transaction. For example, if the current minimum transaction cost to relay a transaction to the network is 10000
drops, then a multi-signed transaction with 3 entries in the Signers
array would need a Fee
value of at least 40000
drops to relay.
An EmitDetails
object has the following fields:
The HookParameters
field is an array of objects that specify the parameters of the hook. Each parameter object has the following fields:
Flag Name | Hex Value | Decimal Value | Description |
---|---|---|---|
Range Name | Bit Mask | Description |
---|---|---|
Field | Type | [Internal Type][] | Description |
---|---|---|---|
Field | Type | [Internal Type][] | Description |
---|---|---|---|
Field | JSON Type | [Internal Type][] | Required? | Description |
---|---|---|---|---|
Field | JSON Type | Internal Type | Description |
---|---|---|---|
Account
String
AccountID
(Required) The unique address of the account that initiated the transaction.
TransactionType
String
UInt16
(Required) The type of transaction. Valid transaction types include: Payment
, OfferCreate
, TrustSet
, and many others.
Fee
String
Amount
(Required; auto-fillable) Integer amount of XAH, 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 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 instead (Added by the [TicketBatch amendment][].).
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.
Flags
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 for more details.
Memos
Array of Objects
Array
(Optional) Additional arbitrary information used to identify this transaction.
NetworkID
Number
UInt32
(Network-specific) The network ID of the chain this transaction is intended for. MUST BE OMITTED for Mainnet and some test networks. REQUIRED on chains whose network ID is 1025 or higher.
Signers
Array
Array
(Optional) Array of objects that represent a multi-signature which authorizes this transaction.
SourceTag
Number
UInt32
(Optional) Arbitrary integer used to identify the reason for this payment, or a sender on whose behalf this transaction is made. Conventionally, a refund should specify the initial payment's SourceTag
as the refund payment's DestinationTag
.
SigningPubKey
String
Blob
(Automatically added when signing) Hex representation of the public key that corresponds to the private key used to sign this transaction. If an empty string, indicates a multi-signature is present in the Signers
field instead.
TicketSequence
Number
UInt32
(Optional) The sequence number of the ticket to use in place of a Sequence
number. If this is provided, Sequence
must be 0
. Cannot be used with AccountTxnID
.
TxnSignature
String
Blob
(Automatically added when signing) The signature that verifies this transaction as originating from the account it says it is from.
EmitDetails
Object
Object
Contains details about the emission. This includes the generation of the emission, the burden of the emission, the callback address, the hash of the hook that emitted the transaction, the nonce of the emission, and the ID of the parent transaction.
HookParameters
Array
Array
The hook parameters of the tx.
tfFullyCanonicalSig
0x80000000
2147483648
DEPRECATED No effect. (If the [RequireFullyCanonicalSig amendment][] is not enabled, this flag enforces a fully-canonical signature.)
Universal Flags
0xff000000
Flags that apply equally to all transaction types.
Type-based Flags
0x00ff0000
Flags with different meanings depending on the transaction type that uses them.
Reserved Flags
0x0000ffff
Flags that are not currently defined. A transaction is only valid if these flags are disabled.
MemoData
String
Blob
Arbitrary hex value, conventionally containing the content of the memo.
MemoFormat
String
Blob
Hex value representing characters allowed in URLs. Conventionally containing information on how the memo is encoded, for example as a MIME type.
MemoType
String
Blob
Hex value representing characters allowed in URLs. Conventionally, a unique relation (according to RFC 5988) that defines the format of this memo.
Network
ID
NetworkID
Field
Mainnet
0
Disallowed
Testnet
1
Disallowed
Devnet
2
Disallowed
AMM Devnet
25
Disallowed
Sidechains Devnet Locking Chain
2551
Disallowed, but will become required after an update
Sidechains Devnet Issuing Chain
2552
Disallowed, but will become required after an update
Xahau Testnet
21338
Required
Xahau Mainnet
21337
Required
Account
String
AccountID
The address associated with this signature, as it appears in the signer list.
TxnSignature
String
Blob
A signature for this transaction, verifiable using the SigningPubKey
.
SigningPubKey
String
Blob
The public key used to create this signature.
EmitGeneration
Number
UInt32
Yes
This field keeps track of a chain of emitted transactions that in turn cause other transactions to be emitted.
EmitBurden
String
UInt64
Yes
This field is a heuristic for detecting forkbombs. Fees are based on burden and will increase exponentially when a chain reaction is started to prevent the network becoming overun by self-reinforcing emitted transactions.
EmitParentTxnID
String
Hash256
Yes
The Hook Execution that emitted the transaction is connected to the Originating Transaction. Therefore this field is always required for the efficient tracing of behaviour.
EmitNonce
String
Hash256
Yes
Emitted Transactions would be identical with the same fields and therefore have identical transaction hashes if a nonce were not used. However every node on the network needs to agree on the nonce, so a special Hook API to produce a deterministic nonce is made available.
EmitCallback
String
AccountID
No
This field is used by xahld when it needs to intitate a callback, such that it knows which Hook and account to initate the callback on. Callbacks happen when an emitted transaction is accepted into a ledger.
EmitHookHash
String
Hash256
Yes
The SHA512H of the Hook at the time it was executed.
Name
String
Blob
The name of the parameter.
Value
String
Blob
The value of the parameter.