# Blockchain node planning 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: 1. **Blockchain nodes (client-managed):** External components that represent the "source of truth" for a given blockchain. 2. **Indexers (client-deployed):** Internal platform components that read, parse, and store data from the nodes. ## Blockchain nodes ### What are blockchain 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. ### Why are they necessary? 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. ### Provisioning: Self-managed vs. third-party 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. | ### Node requirements Regardless of the strategy, these nodes must meet specific requirements. See [Unified Indexer Service > On-premises node requirements](/products/custody/v1.34/overview/architecture/unified-indexer-service#on-premises-node-requirements) for more details. ### High availability (HA) and disaster recovery (DR) 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 ### What are indexers? 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: 1. **Fetch** new blocks from the nodes. 2. **Parse** the block data. 3. **Identify** transactions relevant to your platform's accounts. 4. **Save** this structured data into the Ripple Custody PostgreSQL database, where the platform uses it for accounting. ### Why are they needed? 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. ### Ripple's Unified Indexer Service (UIS) 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:** As of Ripple Custody v1.26, UIS provides support for chains including Arbitrum, Base, Ethereum, Optimism, Polygon, Solana, Stellar, Tron, and XRPL. * **Migration and Configuration:** UIS is enabled for Solana and XRPL by default. Enable UIS for other chains by setting the `type` parameter to `"uis"` in that network's configuration block. Configure this via the Helm `values.yaml` file. See [Unified Indexer Service](/products/custody/v1.34/overview/architecture/unified-indexer-service) for more details. ### High availability (HA) and disaster recovery (DR) * **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. ## Network connectivity and security 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 `url` or `uri` of your node's load balancer) are specified in the Helm `values.yaml` file. * **Proxy:** The indexers can access the blockchain nodes directly or via an `http_proxy` for most ledgers. ## Checklist: Before you proceed ### Decisions made (per blockchain) 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 ### Artifacts ready - [ ] 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) ### Configuration reference See [Indexers configuration reference](/products/custody/v1.34/deployment/reference/indexers) for Helm values. ## Next step **Next:** [Database planning](/products/custody/v1.34/deployment/planning/database) - Plan your PostgreSQL database.