Emerald Dshackle

Emerald Dshackle is a fault-tolerant load balancer for blockchain APIs (Bitcoin and Ethereum). It ensures reliable routing to multiple nodes by evaluating node characteristics such as location, state, current height, and available RPC methods.

Key features include:

• Intelligent Routing: Based on data availability (peers, height, sync status).
• Automatic Failover: Temporarily removes lagging or offline nodes and reinstates them once resolved.
• Multi-Protocol Support: Provides standard JSON RPC (HTTP/WebSocket) and an advanced gRPC-based API.
• Caching: Blockchain-aware edge caching using in-memory or Redis.
• Security: Supports TLS with optional client authentication.
• Consistency: Ensures data consistency by providing the most up-to-date state.

While Dshackle supports standard JSON RPC, its native protocol is based on gRPC (Protobuf over HTTP/2). Using the gRPC protocol provides access to more advanced Dshackle features and better performance.

Advantages of gRPC over JSON RPC:

• Enhanced Functionality: Access to additional parameters and Dshackle-specific data not available in standard upstream APIs.
• Performance: Low latency via HTTP/2 features like compression, server push, pipelining, and multiplexing.
• Asynchronous Responses: Supports pushing new data from the server or sending responses asynchronously as soon as they are executed on an upstream.
• Security: Native support for TLS encryption and authentication.
• Developer Experience: Availability of bindings and code generators for most major languages and frameworks.

For Proof-of-Stake (PoS) blockchains (like Ethereum), Dshackle uses the priority setting to resolve forks. When two upstreams produce different blocks at the same height, Dshackle routes traffic to the upstream with the highest priority value.

Note:

• Priority is used for fork decisions and does not change the general traffic priority.
• This setting is not used for Proof-of-Work (PoW) blockchains; PoW blockchains use the 'Total Work' consensus rule.

- id: eth-one
  blockchain: ethereum
  priority: 10

- id: eth-two
  blockchain: ethereum
  priority: 20

- id: eth-three
  blockchain: ethereum
  priority: 15

Dshackle uses roles to control the order in which upstreams are queried. By default, Dshackle uses a Round-Robin approach. You can override this using the following roles:

• primary (default): Standard upstreams used in the initial request cycle.
• secondary: Standard upstreams used after primary upstreams fail.
• fallback: Used only as a last resort when all primary and secondary upstreams fail or return inconsistent responses.

Internal Request Order:

1. Try primary upstreams.
2. Try secondary upstreams.
3. Delay (starting at 100ms, increasing per iteration).
4. Repeat steps 1-2.
5. Try fallback upstreams.
6. Repeat steps 3-5 until a valid response is received or a timeout occurs.

Dshackle uses a two-tier caching strategy to store blockchain data:

1. Hot Cache (In-memory): Dshackle keeps the latest blocks in memory by default (defaulting to 64 blocks). This provides high-speed access to the most recent data.
2. Cold Cache (Redis): An optional Redis-based cache can be used to store blocks and transactions. Values are typically cached for up to 1 hour, though fresh blocks and transactions are cached for shorter periods. Reusing the same Redis cache across multiple Dshackle instances is recommended.

Dshackle manages cache consistency automatically. If data is removed from the blockchain (e.g., a block is replaced at the same height), Dshackle immediately evicts the outdated values from both the in-memory and Redis caches.

The cluster configuration is the core of Dshackle, defining connections to upstream nodes.

Key components:

• defaults: Applies settings to all upstreams for specific blockchains (e.g., min-peers).
• upstreams: A list of upstream servers. These can be JSON RPC nodes or other Dshackle instances.
• include: Allows loading upstream configurations from external YAML files.

Upstreams can have roles (primary, secondary, fallback) to manage availability and priority.

cluster:
  defaults:
    - blockchains: [ethereum]
      min-peers: 10
  upstreams:
    - id: local
      blockchain: ethereum
      connection:
        ethereum:
          rpc: { url: "http://localhost:8545" }

Dshackle servers can be connected to each other via secure, encrypted, and authenticated connections to form a distributed network. This architecture allows for:

• Regional Deployment: Deploying Dshackle nodes in different geographic regions.
• Network Isolation: Running blockchain nodes (which require open firewalls for P2P and execute untrusted smart contract code) in a separate, isolated environment from your main business applications.
• Fault Tolerance: Building scalable, fail-safe systems by distributing the load across a network of Dshackle instances.

Dshackle provides a standard JSON RPC proxy interface to upstream blockchain nodes. When using Dshackle as a proxy, you benefit from the following features:

• Upstream Routing: Only routes requests to 'alive' upstreams (nodes that are synchronized and have sufficient peers).
• Load Balancing: Distributes requests across available upstreams.
• Request Retry: Automatically retries requests when upstream errors occur.
• Local Caching: Supports both in-memory and Redis-based caching to reduce upstream load.
• Advanced Execution: Supports broadcasting and quorum-based requests.

To run Dshackle via Docker, ensure you have your environment variables (like INFURA_USER) set, and mount your configuration directory to /etc/dshackle inside the container.

1. Set the environment variable:

   export INFURA_USER=your_infura_user

2. Run the container:

   docker run -p 2449:2449 -p 8545:8545 -v $(pwd):/etc/dshackle -e "INFURA_USER=$INFURA_USER" emeraldpay/dshackle:{version-short}

This maps the gRPC port (2449) and the JSON RPC port (8545) to your localhost.

export INFURA_USER=...
docker run -p 2449:2449 -p 8545:8545 -v $(pwd):/etc/dshackle -e "INFURA_USER=$INFURA_USER" emeraldpay/dshackle:{version-short}