If you run on-premise infrastructure, verify with your node providers that your Bitcoin nodes will not enforce BIP-110. Nodes that enforce BIP-110 risk losing synchronization with the majority chain. See Bitcoin network events: BIP-110 and eCash fork.
This plan outlines the conceptual strategy and responsibilities for connecting the Ripple Custody platform to external blockchain networks. This connection is fundamental for monitoring accounts, processing transactions, and maintaining an accurate ledger.
The architecture involves two key sets of components:
- Blockchain nodes (client-managed): External components that represent the "source of truth" for a given blockchain.
- Indexers (client-deployed): Internal platform components that read, parse, and store data from the nodes.
Blockchain nodes are servers that run a specific blockchain's software (e.g., Geth for Ethereum). They connect to the blockchain's peer-to-peer network, validate transactions, and store a copy of the ledger's history.
For Ripple Custody, two types of nodes are relevant:
- Full nodes: Store the complete transaction history.
- Archive nodes: Store the full history and all historical states, which the platform often requires to look up past balances or transaction details.
Ripple Custody does not run its own public blockchain nodes. It must connect to nodes to "read" on-chain data. This is essential to:
- Monitor wallets for incoming deposits.
- Confirm that the network has broadcast and finalized outgoing transactions.
- Fetch on-chain data to calculate account balances.
You are fully responsible for provisioning, managing, and maintaining the blockchain nodes for each ledger supported. This is a critical prerequisite. You have two primary options for this:
| Strategy | Pros | Cons |
|---|---|---|
| Self-managed nodes | • Complete control over infrastructure. • Data remains within your private network, supporting strict "on-soil" data residency policies. | • High operational overhead (setup, patching, monitoring). • Requires deep blockchain-specific expertise. • Client handles HA and DR. |
| Third-party | • Rapid deployment and easy setup. • Managed service, reducing operational overhead. • Provider typically handles HA/DR. | • Reliance on an external vendor. • May have data privacy or residency implications. • Ongoing subscription costs. |
Regardless of the strategy, these nodes must meet specific requirements. See Unified Indexer Service > On-premises node requirements for more details.
You are responsible for the HA and DR of the blockchain nodes.
- HA Strategy: We recommend using a load balancer to provide a single, highly-available endpoint. This endpoint routes traffic to multiple redundant nodes. Configure the Ripple Custody Indexers to point to this single load balancer URI.
- DR Strategy: Your DR approach depends on the provisioning model. For self-managed nodes, you restore nodes from snapshots. For third-party nodes, you rely on the vendor's DR capabilities.
Indexers are Ripple Custody platform components that run within your Kubernetes/OpenShift environment. They act as the intermediary between the platform's Ledger Accounting Service and your blockchain nodes.
Their job is to continuously:
- Fetch new blocks from the nodes.
- Parse the block data.
- Identify transactions relevant to your platform's accounts.
- Save this structured data into the Ripple Custody PostgreSQL database, where the platform uses it for accounting.
Querying raw data directly from a blockchain node is inefficient. It cannot handle the complex accounting and balance tracking that Ripple Custody requires. Indexers translate this raw, chronological data into a clean, indexed, and queryable database of only relevant transactions.
The Unified Indexer Service (UIS) is Ripple's modern indexing technology. This is the standard for all new chain integrations.
- Benefits: The UIS architecture allows for much faster support for new blockchains and tokens. It aligns the on-premises platform with the SaaS platform's core technology.
- Supported Chains: UIS provides support for chains including Arbitrum, Base, Ethereum, Optimism, Polygon, Solana, Stellar, TRON, and XRPL.
- Migration and Configuration: UIS is enabled for Solana, TRON, and XRPL by default. For chains that require or optionally support explicit UIS enablement, set the
typeparameter to"uis"in that network's configuration block. Configure this via the Helmvalues.yamlfile. See Unified Indexer Service for more details.
- HA Strategy: The indexers store their state in the central PostgreSQL database. If an indexer pod fails, the container orchestration platform (e.g., Kubernetes) automatically restarts it. The new pod reads its last-known state from the database and resumes indexing from where it left off.
- DR Strategy: The indexers are effectively stateless (their state lives in the database). Redeploy them using Helm. They recover state from the restored PostgreSQL database. The indexer DR plan is covered by the platform's primary database DR plan.
Connecting the internal indexers to the external blockchain nodes is a client responsibility and a key part of your network security plan.
- Firewall rules: Update your firewall rules to allow outbound traffic from the Kubernetes/OpenShift cluster (where the indexers are deployed) to the endpoints of your blockchain nodes.
- Configuration: The connection details (e.g., the
urloruriof your node's load balancer) are specified in the Helmvalues.yamlfile. - Proxy: The indexers can access the blockchain nodes directly or via an
http_proxyfor most ledgers.
For each chain you want to support, decide whether nodes will be:
- Self-managed or third-party (if third-party, select a provider)
- Node type (full/archive)
- HA strategy: Load balancer planned for each chain's node endpoints
- UIS enablement: Decision made on which chains use Unified Indexer Service
- Node endpoints documented per chain (URL/URI)
- Authentication credentials documented (if required by provider)
- Load balancer endpoints provisioned (for HA)
- Firewall rules updated: Kubernetes cluster to Node endpoints (outbound)
For node endpoint, ledger, and indexer Helm values, see Blockchain nodes configuration, Ledgers configuration, and Indexers configuration.
Next: Database planning - Plan your PostgreSQL database.