# Chain Gateway

Source: https://docs.settlemint.com/docs/architecture/components/infrastructure/chain-gateway
The Chain Gateway is DALP's eRPC-based gateway for outbound EVM JSON-RPC
traffic. It routes application requests through configured upstream RPC
endpoints with method-aware timeouts, retries, hedging, and caching.




## Overview [#overview]

The Chain Gateway is DALP's eRPC-based gateway for outbound EVM JSON-RPC traffic. DALP services call the gateway instead of connecting directly to every blockchain node or provider endpoint.

The gateway gives operators one place to configure upstream RPC endpoints, request policies, cache storage, ingress exposure, and service health dependencies. Application code can keep using the configured DALP RPC URL while the gateway handles routing and failure handling behind that endpoint.

## Architecture [#architecture]

<Mermaid
  chart="`flowchart TB
  subgraph APP[&#x22;DALP services&#x22;]
    DAPI(DAPI)
    SIGNER(Transaction Signer)
    INDEXER(Chain Indexer)
    EXPLORER(Block explorer)
  end

  subgraph GW[&#x22;Chain Gateway&#x22;]
    ERPC(eRPC gateway)
    REDIS(Redis cache and shared state)
  end

  subgraph RPC[&#x22;Configured EVM upstreams&#x22;]
    U1(RPC upstream 1)
    U2(RPC upstream 2)
    U3(RPC upstream 3)
  end

  DAPI --> ERPC
  SIGNER --> ERPC
  INDEXER --> ERPC
  EXPLORER --> ERPC
  ERPC --> REDIS
  ERPC --> U1
  ERPC --> U2
  ERPC --> U3

  style DAPI fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style SIGNER fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style INDEXER fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style EXPLORER fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style ERPC fill:#b661d9,stroke:#8a3fb3,stroke-width:2px,color:#fff
  style REDIS fill:#f5a623,stroke:#c78314,stroke-width:2px,color:#fff
  style U1 fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style U2 fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style U3 fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff`"
/>

## What operators configure [#what-operators-configure]

The deployment chart enables the gateway by default and exposes it internally as `dalp-erpc`. The gateway configuration is grouped under `erpc` in the DALP Helm values.

| Area                   | What it controls                                                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Upstreams              | The EVM RPC endpoints the gateway can route to. Each upstream has an identifier, endpoint URL, EVM settings, and optional upstream-specific failsafe rules.        |
| Network integrity      | EVM request integrity checks, including highest-block consistency and `eth_getLogs` block-range enforcement.                                                       |
| Failsafe policies      | Method-aware timeouts, retries, retry jitter, exponential backoff, and hedged requests.                                                                            |
| Cache and shared state | Redis-backed response caching and shared gateway state.                                                                                                            |
| Exposure               | Optional Ingress, HTTPRoute, or OpenShift Route settings for publishing the JSON-RPC endpoint outside the cluster. The chart creates the network entry point only. |
| Startup dependencies   | A TCP dependency check that waits for Redis before the gateway starts.                                                                                             |

## Configure upstreams for load distribution [#configure-upstreams-for-load-distribution]

Add one `upstreams` entry for each RPC endpoint the gateway can use. Multiple upstreams give the gateway more than one target for failover and load distribution while DALP services keep calling the same internal gateway URL.

```yaml
erpc:
  config:
    projects:
      - id: settlemint
        networks:
          - architecture: evm
        upstreams:
          - id: primary-rpc
            endpoint: https://primary.example.com
            evm: {}
            allowMethods:
              - "*"
            autoIgnoreUnsupportedMethods: false
          - id: secondary-rpc
            endpoint: https://secondary.example.com
            evm: {}
            allowMethods:
              - "*"
            autoIgnoreUnsupportedMethods: false
```

Use upstream identifiers that make sense to your operations team. Keep endpoint URLs in your deployment configuration or secret-management process, not in application code. Keep `autoIgnoreUnsupportedMethods: false` on DALP upstreams so a transient `unsupported` response from one provider does not make the gateway silently stop sending that method to the upstream later.

## Node connection model and security boundary [#node-connection-model-and-security-boundary]

DALP does not require one fixed RPC node hosting model. The Chain Gateway can route to self-hosted full nodes, cloud-hosted nodes, managed RPC providers, or a mix of those upstreams. A bank can operate a dedicated full node and add it as one of the gateway upstreams, provided that node exposes an EVM JSON-RPC interface DALP can reach.

<Mermaid
  chart="`flowchart LR
  DALP[&#x22;DALP services&#x22;] --> GW[&#x22;Chain Gateway&#x22;]
  GW --> SELF[&#x22;Bank-operated full node&#x22;]
  GW --> CLOUD[&#x22;Cloud-hosted node&#x22;]
  GW --> PROVIDER[&#x22;Managed RPC provider&#x22;]
  GW --> REDIS[&#x22;Redis cache and shared state&#x22;]

  style DALP fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style GW fill:#b661d9,stroke:#8a3fb3,stroke-width:2px,color:#fff
  style SELF fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style CLOUD fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style PROVIDER fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style REDIS fill:#f5a623,stroke:#c78314,stroke-width:2px,color:#fff`"
/>

| Question                        | DALP answer                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Node source                     | Configure each upstream endpoint explicitly. The upstream can be a bank-operated full node, a cloud-hosted node, or a managed RPC provider.                                                                                                                                                                                                                                            |
| RPC authentication              | Put upstream credentials, tokens, certificates, or provider-specific authentication in the gateway and infrastructure configuration rather than in application code. For externally exposed gateway access, add caller authentication and authorization at the ingress, gateway, service-mesh, or edge layer.                                                                          |
| Tampered or malicious responses | The gateway can enforce EVM request integrity checks such as highest-block consistency and `eth_getLogs` block-range validation. It does not replace consensus validation by a trusted full node, provider trust controls, or operational monitoring for conflicting upstream responses. Use a bank-operated or otherwise trusted full node when independent verification is required. |
| Dedicated bank node             | Supported as an upstream pattern. Point the gateway to the bank-operated full node and keep direct node credentials and network policy under the bank's operating model.                                                                                                                                                                                                               |
| Failover                        | Add multiple upstreams behind the gateway for shared routing and failsafe policy. Use ordered `rpc.urls` only when a DALP client should also fall back directly between endpoints.                                                                                                                                                                                                     |
| mTLS and encryption             | The chart can publish the endpoint through TLS-capable Ingress, HTTPRoute, or OpenShift Route configuration, and upstream endpoints should use encrypted `https` or `wss` URLs. Mutual TLS is an environment control provided by the ingress controller, service mesh, edge gateway, or upstream node/provider; it is not an application-layer guarantee added by DALP itself.         |

This boundary keeps the public claim precise: DALP centralizes EVM RPC routing and failover, while node ownership, upstream authentication, mTLS policy, and independent node validation are deployment controls chosen for the environment.

<Callout type="warning" title="Secure external RPC exposure before enabling it">
  Enabling `erpc.ingress.enabled`, `erpc.httpRoute.enabled`, or `erpc.openShiftRoute.enabled` makes the JSON-RPC endpoint reachable from outside the cluster. The default Ingress, HTTPRoute, and OpenShift Route templates configure host, path, TLS, and gateway attachment only.

  Before exposing the endpoint, keep it internal or put these boundary controls in front of it:

  * authentication and authorization for RPC callers
  * strict IP allowlists, or another internal-only exposure model
  * rate limiting or request throttling
  * network-level protections from your Kubernetes, OpenShift, ingress controller, or edge gateway policy
</Callout>

## Request policies [#request-policies]

DALP ships gateway policies for the request patterns that commonly stress EVM RPC infrastructure. The default policy set is method-aware, so long-running log queries and trace calls get different limits from current-state reads.

| Request pattern               | Default timeout | Retry policy            | Gateway behaviour                                               |
| ----------------------------- | --------------- | ----------------------- | --------------------------------------------------------------- |
| `eth_getLogs`                 | 45 seconds      | 3 attempts with backoff | Handles large log ranges with retries, jitter, and one hedge.   |
| Trace and debug methods       | 90 seconds      | 1 attempt               | Gives trace calls more time without repeatedly replaying them.  |
| Block and transaction reads   | 6 seconds       | 2 attempts with backoff | Keeps common read paths responsive during transient failures.   |
| Unfinalized or realtime reads | 4 seconds       | 2 attempts with jitter  | Keeps latest-state reads short and adds one hedge request.      |
| Finalized reads               | 20 seconds      | 4 attempts with backoff | Gives finalized historical reads more recovery room.            |
| Default requests              | 12 seconds      | 3 attempts with backoff | Applies a catch-all timeout, retry, jitter, and hedging policy. |

These policies reduce the chance that a transient RPC endpoint issue becomes an application-level failure. Operators still need healthy upstream endpoints and monitoring for the gateway and chain nodes.

## Node endpoint operating model [#node-endpoint-operating-model]

**Direct answer.** DALP connects to EVM networks through configured HTTP, HTTPS, WS, or WSS RPC endpoints. Those endpoints can be bank-operated full nodes, managed cloud RPC services, or third-party providers. Application services call the Chain Gateway, which routes traffic to one or more upstream endpoints. A bank can operate dedicated full-node endpoints and register them as upstream RPC URLs; DALP does not require a specific node hosting model.

**DALP mechanism.** Operators model each supported EVM network as a chain configuration, then register upstream RPC URLs for the gateway. Network configuration can provide a single primary RPC URL or an ordered list of RPC URLs for clients that support multiple endpoints. The gateway applies method-aware timeouts, retries, hedging, and integrity checks before responses reach DALP services.

| Infrastructure choice                                | How DALP connects                                                                                                                    | RPC access protection                                                                                                                                                              | Failover when the primary endpoint is unavailable                                                                                                              | Malicious or inconsistent RPC responses                                                                                                                                         |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Self-hosted full node or validator-adjacent RPC node | Configure the node's internal HTTP, HTTPS, WS, or WSS endpoint as an upstream RPC URL.                                               | The operator controls endpoint exposure, network policy, and any credentials embedded in the RPC URL. DALP stores endpoint URLs in deployment configuration, not application code. | Add more than one gateway upstream, or configure an ordered RPC URL list so the gateway and chain clients can route around a failed endpoint.                  | The gateway enforces consistent highest-block reporting across upstreams and valid `eth_getLogs` block ranges, then applies method-aware retries and hedging on routed traffic. |
| Managed or cloud-hosted RPC endpoint                 | Configure the provider endpoint as an upstream. Use more than one upstream when the environment needs failover or load distribution. | Manage provider API keys, auth headers, or URL-embedded credentials, plus rotation and rate-limit procedures.                                                                      | Configure multiple gateway upstream entries and keep provider outage runbooks for switching traffic.                                                           | Same gateway integrity checks and request policies apply to provider-backed upstreams.                                                                                          |
| Private or permissioned EVM network                  | Configure the chain as a custom EVM network with its chain ID, currency metadata, RPC endpoint, and finality settings.               | The consensus operator protects node RPC access with the same endpoint, credential, and network controls used for the private chain.                                               | Use multiple upstreams where the network exposes them. When the chain does not support the `finalized` block tag, set an explicit finality confirmation depth. | Same gateway integrity checks. Operators monitor node lag, finality depth, and consensus health alongside gateway metrics.                                                      |
| Public EVM network                                   | Configure the public chain and route DALP traffic through the gateway or configured RPC endpoints.                                   | Select approved providers, manage provider credentials in configuration, and apply ingress or edge controls when RPC is exposed outside the cluster.                               | Configure multiple upstreams and ordered RPC URLs so traffic can move to a secondary provider or node endpoint.                                                | Same gateway integrity checks and monitoring vocabulary used for other EVM networks.                                                                                            |

**Deployment and evidence boundary.** DALP owns the application, gateway, indexing, signing, and monitoring surfaces around EVM connectivity. The target environment owns blockchain node infrastructure, upstream endpoint credentials, private network links, and any mutual TLS or client-certificate policy on node or ingress boundaries. DALP validates RPC URLs as HTTP, HTTPS, WS, or WSS; it does not ship one platform-wide mutual-TLS profile for every RPC hop. Operators encrypt upstream connectivity with TLS or mutual TLS where their network policy requires it, including on bank-operated nodes, provider links, and external ingress. Before enabling external JSON-RPC exposure, put authentication, authorization, IP allowlists, rate limits, and TLS in front of the published endpoint.

**Where to read next.** See [EVM RPC Node](/docs/architecture/components/infrastructure/evm-rpc-node) for the node layer behind the gateway and [Blockchain monitoring](/docs/developer-guides/operations/blockchain-monitoring) for gateway and chain health signals.

## How DALP services use it [#how-dalp-services-use-it]

DALP service configuration points to the gateway URL as the default RPC endpoint. The default in-cluster form is:

```text
http://dalp-erpc:4000/settlemint/evm/<chain-id>
```

A DALP network can define either one RPC endpoint or an ordered endpoint list. Use this distinction to decide where failover should live:

| Configuration shape | How DALP uses it                                                                                                                                          | When to use it                                                                                             |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `rpc.url` only      | DALP treats it as the primary endpoint.                                                                                                                   | Use this when the URL points to the Chain Gateway or to one managed endpoint.                              |
| `rpc.urls` only     | DALP treats the first entry as the primary endpoint for callers that need one URL and builds fallback transports for clients that support endpoint lists. | Use this when an application client should fail over directly between several endpoints.                   |
| Both fields         | Single-endpoint callers use `rpc.url`. Fallback-capable clients use the ordered `rpc.urls` list.                                                          | Put the Chain Gateway first in `rpc.urls` if fallback-capable clients should try it before direct backups. |

```yaml
networks:
  arbitrum:
    chainId: 42161
    name: Arbitrum One
    rpc:
      url: http://dalp-erpc:4000/settlemint/evm/42161
      urls:
        - http://dalp-erpc:4000/settlemint/evm/42161
        - https://secondary-rpc.example.com
```

HTTP and WebSocket endpoints can be listed together. DALP separates the URLs by protocol when it builds the chain configuration for clients that expose HTTP and WebSocket RPC lists separately.

Block explorer components also use the same gateway for JSON-RPC and trace requests, so explorer reads follow the same routing layer as the rest of the deployment.

## Where resilience is applied [#where-resilience-is-applied]

The Chain Gateway and DALP application clients both have RPC resilience controls, but they operate at different layers. Keep the boundary clear when designing an environment.

| Layer               | Control                            | Behavior                                                                                                                                                                                                |
| ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chain Gateway       | Upstream routing and shared policy | eRPC receives requests at the configured gateway URL, routes them to configured upstreams, applies method-aware failsafe policies, and uses Redis for cache and shared state.                           |
| DALP network config | Client transport selection         | Network configuration requires `rpc.url` or `rpc.urls`. DALP picks `rpc.url` first, falls back to the first `rpc.urls` entry when needed, and can build fallback transports from multi-entry URL lists. |
| Chain Indexer       | Log-fetch limits                   | Per-network `rpc.limits` control `eth_getLogs` address batching, block-range size, and concurrent calls before requests reach the gateway or upstream node.                                             |
| EVM RPC Node        | Execution client behavior          | The upstream node or provider still determines supported JSON-RPC methods, finality behavior, trace/debug availability, mempool behavior, and rate limits.                                              |

For production-style deployments, point DALP services at the Chain Gateway unless a component has a specific reason to use direct endpoint fallback. This keeps upstream credentials and request policy in one operational place while preserving DALP's per-network client limits.

## Operational notes [#operational-notes]

* Configure at least one upstream RPC endpoint for each EVM network the deployment serves.
* Use multiple upstreams when the environment needs failover or load distribution.
* Keep Redis available because the gateway uses it for response caching and shared state.
* Expose the gateway through Ingress, HTTPRoute, or an OpenShift Route only when external RPC access is required.
* Track request volume, latency, upstream health, cache behaviour, consensus errors, and rate-limiter responses in your observability tooling.
* Monitor gateway latency, errors, and upstream health alongside the chain node metrics.

## See also [#see-also]

* [EVM RPC Node](/docs/architecture/components/infrastructure/evm-rpc-node) for the node endpoint behind the gateway
* [Chain Indexer](/docs/architecture/data-availability/chain-indexer) for event processing
* [Transaction Signer](/docs/architecture/components/infrastructure/transaction-signer) for transaction submission
* [Self-hosting architecture](/docs/architecture/self-hosting) for the wider deployment model
* [Observability](/docs/architecture/operability/observability) for monitoring