After initiation, transactions progress through governance approval, signing, broadcast, and blockchain confirmation, each with distinct statuses.
- Internal statuses: Pending → Preparing → Reserved → Prepared → Broadcasting → Completed.
- Ledger statuses: Detected → Confirmed (or Replaced/Expired).
- Hot vaults sign automatically. Cold vaults require manual intervention.
- Finality is blockchain-specific. Some chains confirm in seconds, others take minutes.
Understanding transaction statuses is essential for operations and support. Each status indicates where a transaction is in the pipeline and what might be blocking it. "Preparing" often means fee conditions aren't met; "Pending" means awaiting approvals; "Broadcasting" means it's on the network awaiting confirmation. Cold vault transactions require additional operational procedures.
For architects and operators: Set up monitoring and alerting on transaction status distributions. Define SLAs for each phase. For cold vault deployments, establish clear procedures for the air-gapped signing process and ensure operators understand the workflow.
Before reading this page, you should understand:
- Transactions - The overall transaction lifecycle and flow
- Transaction initiation - How to start a transaction
To understand transaction processing, you need to be familiar with a few blockchain concepts:
| Concept | Description | Non-technical explanation |
|---|---|---|
| UTXO | Unspent transaction output - a digital currency resource used for transactions on Bitcoin-type ledgers. It represents a certain amount of cryptocurrency that was authorized by a sender and is available to be spent by a beneficiary. | Think of UTXOs as individual coins in your wallet. When you spend, you use whole coins and receive change back. |
| Nonce | A transaction counter, starting at 0, that represents the number of operations sent to an Ethereum Virtual Machine (EVM) blockchain from an account. | A sequence number that ensures your transactions are processed in order, and prevents duplicates. |
| Gas | A measure of how much a transaction costs on an Ethereum Virtual Machine blockchain. | The "fuel" required to run your transaction—more complex operations need more gas. |
A blockchain transaction moves through the following statuses:
The flow is the same for all ledgers, apart from Bitcoin-type ledgers, which go through an additional step.
While still in Ripple Custody, the transaction can have the following statuses:
| Status | Description | What this means |
|---|---|---|
Pending | Transaction order is approved by policy evaluation. | Your transaction passed governance checks and is queued for processing. |
Preparing | The ledger accounting service fetches the executable transaction order and retrieves data from the ledger nodes (for example, nonce, UTXO, or fees). The information is stored in the database. Note that the transaction remains on hold (Preparing status) until the network conditions make it possible to broadcast it within the acceptable fee levels. | The system is gathering blockchain data needed to build your transaction. If fees are too high, it waits here. |
Reserved | The necessary resources were allocated for the transaction (for example, nonce or UTXO), which impacts the Reserved balance of the account. | Funds are set aside for this transaction and won't be used for other transactions. |
Prepared | The notary has produced an attestation for the vault, which will verify, construct, and sign the transaction. | The operation is authorized and ready for vault verification and signing. |
Broadcasting | The ledger accounting service broadcasts the transaction and tracks its status. | Your transaction has been sent to the blockchain network. |
Completed | All processing is complete and the transaction was successfully broadcast. The transaction is no longer within the control of Ripple Custody. The amount of time for the transaction to be processed depends on the number of blocks the ledger needs to reach finality. For more details, see Transaction finality. | Ripple Custody has done its job — now we're waiting for the blockchain to confirm it. |
Failed | A transaction can fail for multiple reasons, such as:
| Something went wrong. Check the error details to understand what happened. |
In addition, Ripple Custody includes status Interrupted for internal use only.
Once on chain, the transaction can have a number of blockchain-specific statuses:
| Status | Description | What this means |
|---|---|---|
Detected | The transaction is visible in the first block of the ledger. For Bitcoin ledgers, this status applies if the transaction is either visible in the mempool or the first block. | The blockchain has received your transaction and included it in a block. |
Replaced | Following a user request to replace a transaction with a new one, the transaction is being replaced on-chain. | You requested a replacement transaction (e.g., with higher fees), and it's being processed. |
Confirmed | The transaction is validated in the required number of blocks to reach finality. For more information, see Transaction finality. | Your transaction is complete and irreversible. The blockchain has permanently recorded it. |
Expired | Confirmation was not reached within the set time. | The transaction wasn't confirmed in time. You may need to resubmit. |
A transaction is fully complete when it reaches Confirmed status. At this point, the transaction has been validated by the blockchain and is irreversible. The number of confirmations required varies by blockchain—see Transaction finality for details.
For a complete status summary table, see Transactions reference.
When a transaction reaches the Confirmed status on the ledger, the transaction sent by the user is included in a block of the chain, however, this does not automatically mean that the action described in the transaction was executed. The action is not executed if the transaction breaks a rule on the ledger or the transaction contains a mistake, for example:
- The data string sent to a smart contract is malformed.
- The operation is reverted for lack of gas.
- A non-authorized staking operation is submitted.
- The address of the recipient is faulty.
- A token was sent that was not previously associated with the recipient address.
Ripple Custody supports two vault architectures for transaction signing: hot vaults (network-connected) and cold vaults (air-gapped). Both follow the same governance and approval process, but differ in how the signed transaction reaches the blockchain.
For more information about the system components described in these flows, see System architecture.
The following table describes the complete transaction flow. The initial workflow is identical for hot and cold vaults. The flow diverges when the vault receives the notary-attested operation query.
| Step | Component | Description | What's happening |
|---|---|---|---|
| 1 | Operator → API | Operator 1 submits a signed intent containing transaction data via HTTPS POST to the API gateway. | A user requests a transaction. |
| 2 | API → Operator | The API gateway returns 202 Accepted with a requestId when the request is accepted for processing. | The request is scheduled; execution has not completed yet. |
| 3 | API → AMQP | The API gateway queues the workflow task. | The transaction enters the asynchronous workflow. |
| 4 | Workflow → Notary Bridge | The workflow makes the signed request available to the notary boundary. | The system starts policy evaluation. |
| 5 | Notary | The notary retrieves the signed request, verifies the user signature, evaluates policy, and checks trusted state. | The system checks whether this user can make this request. |
| 6 | Operator → API | If the policy requires another approval, Operator 2 approves the transaction via HTTPS POST to the API gateway. | Another user approves the transaction. |
| 7 | API → AMQP | The API gateway accepts the approval for asynchronous processing and queues it. | The approval enters the same workflow. |
| 8 | Notary | The notary retrieves and verifies the signed approval. | The approval is checked against policy requirements. |
| 9 | Notary → Notary KMS | When policy conditions are satisfied, the notary updates trusted state and signs the attestation. | All approvals are received and the operation is attested. |
| 10 | Ledger Accounting → PostgreSQL | Ledger Accounting persists the resulting operational state and prepares ledger resources such as fees, nonce, or UTXO selection. | The transaction is prepared for signing. |
| 11 | API | The notary-attested operation query becomes available for the vault. | The transaction is ready for vault verification and signing. |
| Step | Component | Description | What's happening |
|---|---|---|---|
| 12 | Vault → API | The vault polls the API gateway for new operation queries via HTTPS GET. | The vault checks for transactions to sign. |
| 13 | API → Vault | The API gateway returns the notary-attested operation query. | The vault receives the transaction work. |
| 14 | Vault | The vault verifies the notary attestation, Merkle proof, and request data, then builds the ledger-specific transaction. | The vault confirms the operation is authorized. |
| 15 | Vault → KMS | The vault requests the protected blockchain transaction signature from its KMS, HSM, or MPC backend. | The protected key signs without leaving the backend. |
| 16 | Vault → API | The vault submits the signed transaction via HTTPS POST. | The signed transaction is returned. |
| 17 | API → Ledger Accounting | The API gateway requests broadcast and tracking. | The system prepares to send the transaction to the blockchain. |
| 18 | Ledger Accounting → Blockchain | Ledger Accounting broadcasts the signed transaction and tracks it through ledger status updates. | Your transaction is sent to the blockchain network. |
In a cold vault deployment, the online vault polling and upload steps are replaced by a manual process involving an operator who physically transfers data between the online system and the air-gapped vault.
| Step | Component | Description | What's happening |
|---|---|---|---|
| 12 | Operator → API | The cold vault operator requests pending operations from the API gateway. | An operator downloads the transaction request. |
| 13 | API → Operator | The API gateway returns the notary-attested operation query. | The operator receives the transaction data. |
| 14 | Operator → Cold Bridge | The operator physically moves to the air-gapped system and submits the operation query to the cold bridge. | The operator walks to the secure room with the cold vault. |
| 15 | Vault → Cold Bridge | The vault polls the cold bridge for new operation queries. | The cold vault checks for transactions to sign. |
| 16 | Cold Bridge → Vault | The cold bridge returns the notary-attested operation query. | The cold vault receives the transaction work. |
| 17 | Vault | The vault verifies the notary attestation, Merkle proof, and request data, then builds and signs the ledger-specific transaction through its protected backend. | The cold vault signs only after verification. |
| 18 | Vault → Cold Bridge | The vault submits the signed transaction to the cold bridge. | The signed transaction is ready for pickup. |
| 19-20 | Operator → Cold Bridge | The operator retrieves the signed transaction from the cold bridge. | The operator downloads the signed transaction. |
| 21 | Operator → API | The operator physically moves back and submits the signed transaction to the API gateway. | The operator returns and uploads the signed transaction. |
| 22 | API → Ledger Accounting | The API gateway requests broadcast and tracking. | The system prepares to send the transaction to the blockchain. |
| 23 | Ledger Accounting → Blockchain | Ledger Accounting broadcasts the signed transaction and tracks it through ledger status updates. | Your transaction is sent to the blockchain network. |
| Factor | Hot vault | Cold vault |
|---|---|---|
| Security | Network-connected (higher attack surface) | Air-gapped (maximum isolation) |
| Transaction speed | Seconds to minutes | Hours to days (manual process) |
| Automation | Fully automated | Requires operator intervention |
| Use case | Frequent transactions, trading, payments | Large treasury reserves, cold storage |
| Operational cost | Lower (no manual steps) | Higher (dedicated operators, physical security) |
Use a hybrid approach: maintain a hot vault for operational liquidity (daily transactions) and a cold vault for long-term reserves. Set governance policies that require cold vault signing for transactions above a threshold amount.
When you transact on a ledger, the fees you pay are a combination of the fees set by the ledger itself and a strategy you specify in Ripple Custody to trade off priority against cost.
At transaction execution, Ripple Custody calculates the fee by calling the dry run operation, then adjusts based on your fee strategy and ledger requirements. For an API workflow that includes dry run before submission, see Send assets with the API.
Ripple Custody supports several fee strategy types:
| Type | Description |
|---|---|
| Priority | Fee calculated based on priority level (Low, Medium, High). Required for transfer orders. |
| Specified rate | You specify the exact fee rate. EIP 1559 variant available for Ethereum. |
| Specified additional fee | Your specified amount added on top of the ledger base fee. |
| Predefined | The ledger calculates fees using its own criteria (e.g., Hedera). |
| Beneficiary pays | The recipient pays the transaction fees. |
Set a maximum fee as a safeguard to cap transaction costs. If network fees exceed your maximum, Ripple Custody holds the transaction in Preparing status until conditions improve.
For detailed fee strategies by ledger, see Transactions reference.
Transaction finality is the point at which a blockchain transaction becomes irreversible. Ripple Custody implements probabilistic finality, treating transactions as confirmed after a sufficient number of blocks.
Different blockchains require different confirmation thresholds:
| Category | Examples | Confirmation Blocks |
|---|---|---|
| Fast finality | XRP Ledger, Stellar, Algorand, Hedera, Avalanche, Polkadot | 1 |
| Medium finality | Bitcoin, Dash, Cardano, Tezos, Solana | 2-31 |
| High confirmation | Ethereum, BSC, Polygon | 96-200 |
For complete finality settings by network, see Transactions reference.
- Transactions reference - Detailed fee and finality tables, troubleshooting
- System architecture - Learn about notary, vault, and other components
- Send assets: UI | API - Guide for creating transactions