# Transaction processing

Executive summary
**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.


Why this matters
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.

Prerequisites
Before reading this page, you should understand:

- [Transactions](/products/custody/v1.34/concepts/transactions) - The overall transaction lifecycle and flow
- [Transaction initiation](/products/custody/v1.34/concepts/transactions-initiation) - How to start a transaction


## Blockchain concepts

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


## Transaction statuses

A blockchain transaction moves through the following statuses:

![Transaction statuses](/assets/transaction-flow.4e35830e7eec539a1421f98cae754303bbca92d5978029330f8d007f7064accc.f8619c9e.png)

The flow is the same for all ledgers, apart from Bitcoin-type ledgers, which go through an additional step.

### Ripple Custody statuses

While still in Ripple Custody, the transaction can have the following statuses:

| Status | Description | What this means |
|  --- | --- | --- |
| `Pending` | Transaction order is approved by the policy engine. | 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 a signature of executability for the vault, which will verify, construct, and sign the transaction. | The governance engine has approved the transaction for 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](/products/custody/v1.34/concepts/transactions-reference#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:Expiration dateBlockchain embedded limitationLow fees (the vault rejects the transaction).Deterministic failure to broadcastInvalid endpointNotary rejection due to invalid signature or unexpected payload version (could be recovered by updating the corresponding component) | Something went wrong. Check the error details to understand what happened. |


In addition, Ripple Custody includes status `Interrupted` for internal use only.

### Ledger statuses

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](/products/custody/v1.34/concepts/transactions-reference#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. |


When is my transaction truly complete?
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](/products/custody/v1.34/concepts/transactions-reference#transaction-finality) for details.

For a complete status summary table, see [Transactions reference](/products/custody/v1.34/concepts/transactions-reference#transaction-status-reference).

### Transaction failure

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.


## Vault transaction flows

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](/products/custody/v1.34/overview/architecture).

### Transaction flow overview

The following table describes the complete transaction flow. Steps 1-10 are identical for both hot and cold vaults. The flow diverges at step 11, where the vault receives the operation query.

![Hot vault flow ](/assets/custody-hot-vault-flow.679997ad4a66588a7a8a74fe027f202e11d6e5812a509471dac800067ca4813d.f8619c9e.png)

#### Common steps (hot and cold vaults)

| 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 | Governance → notary | The governance engine polls the notary bridge for new messages via gRPC stream. | The system checks for new requests. |
| 3 | notary → Governance | The notary bridge returns the signed intent. | The request is passed to governance. |
| 4 | Governance | The governance engine verifies the user signature and applies the related policy. | The system checks if this user can make this request. |
| 5 | Governance → notary | The governance engine submits the validated intent to the notary bridge. | The request is queued for approval. |
| 6 | Operator → API | `Operator 2` approves the transaction via HTTPS POST to the API gateway. | Another user approves the transaction. |
| 7 | Governance → notary | The governance engine polls the notary bridge for approval messages. | The system checks for approvals. |
| 8 | notary → Governance | The notary bridge returns the signed approval. | The approval is passed to governance. |
| 9 | Governance | The governance engine verifies the approval. With all required approvals, it generates and signs an operation query for the vault. | All approvals received — ready for signing. |
| 10 | Governance → notary | The governance engine submits the signed operation query to the notary bridge. | The transaction is sent to the vault for signing. |


#### Hot vault: steps 11-16

| Step | Component | Description | What's happening |
|  --- | --- | --- | --- |
| 11 | vault → API | The vault polls the API gateway for new operation queries via HTTPS GET. | The vault checks for transactions to sign. |
| 12 | API → vault | The API gateway returns the signed operation query. | The vault receives the transaction. |
| 13 | vault | The vault verifies the governance signature, builds the transaction, and signs it. | The vault signs the transaction with the private key. |
| 14 | vault → API | The vault submits the signed transaction via HTTPS POST. | The signed transaction is returned. |
| 15 | API → Ledger Service | The API gateway requests the ledger accounting service to broadcast. | The system prepares to send to blockchain. |
| 16 | Ledger Service → Blockchain | The signed transaction is broadcast to the blockchain. | Your transaction is sent to the blockchain network. |


Cold vault difference
In a cold vault deployment, steps 11-16 are replaced by a manual process involving an operator who physically transfers data between the online system and the air-gapped vault.

#### Cold vault: steps 11-22

![Cold vault flow ](/assets/custody-cold-vault-flow.7915dd698183d930143c7441b9736c9b3000f5ebccac9da3a1e73e17ba44511f.f8619c9e.png)

| Step | Component | Description | What's happening |
|  --- | --- | --- | --- |
| 11 | Operator → API | The cold vault operator requests pending operations from the API gateway. | An operator downloads the transaction request. |
| 12 | API → Operator | The API gateway returns the signed operation query. | The operator receives the transaction data. |
| 13 | 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. |
| 14 | vault → Cold Bridge | The vault polls the cold bridge for new operation queries. | The cold vault checks for transactions to sign. |
| 15 | Cold Bridge → vault | The cold bridge returns the signed operation query. | The cold vault receives the transaction. |
| 16 | vault | The vault verifies the governance signature, builds the transaction, and signs it. | The cold vault signs with the private key. |
| 17 | vault → Cold Bridge | The vault submits the signed transaction to the cold bridge. | The signed transaction is ready for pickup. |
| 18-19 | Operator → Cold Bridge | The operator retrieves the signed transaction from the cold bridge. | The operator downloads the signed transaction. |
| 20 | Operator → API | The operator **physically moves** back and submits the signed transaction to the API gateway. | The operator returns and uploads the signed transaction. |
| 21 | API → Ledger Service | The API gateway requests the ledger accounting service to broadcast. | The system prepares to send to blockchain. |
| 22 | Ledger Service → Blockchain | The signed transaction is broadcast to the blockchain. | Your transaction is sent to the blockchain network. |


### Choosing between hot and cold vaults

| 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) |


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

## Transaction fees

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 more information, see [Dry run intents (UI)](/products/custody/v1.34/ui/get-started/key-operations) or [Dry run intents (API)](/products/custody/v1.34/api/get-started/key-operations/update/dry-run).

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](/products/custody/v1.34/concepts/transactions-reference#fee-strategies-by-ledger).

## Transaction finality

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](/products/custody/v1.34/concepts/transactions-reference#transaction-finality).

## Next steps

- [Transactions reference](/products/custody/v1.34/concepts/transactions-reference) - Detailed fee and finality tables, troubleshooting
- [System architecture](/products/custody/v1.34/overview/architecture) - Learn about notary, vault, and other components
- Send assets: [UI](/products/custody/v1.34/ui/accounting/send-assets) | [API](/products/custody/v1.34/api/accounting/send-assets) - Guide for creating transactions