Skip to content

Latest commit

 

History

History
752 lines (615 loc) · 14.3 KB

reference-configuration.adoc

File metadata and controls

752 lines (615 loc) · 14.3 KB
Raw

Configuration Reference

Table of Contents

Example

Example configuration with most options configured
host: 0.0.0.0
port: 2449

tls:
  enabled: true
  server:
    certificate: "/path/127.0.0.1.crt"
    key: "/path/127.0.0.1.p8.key"
  client:
    require: true
    ca: "/path/ca.dshackle.test.crt"

monitoring:
  enabled: true
  jvm: false
  extended: false
  prometheus:
    enabled: true
    bind: 127.0.0.1
    port: 8081
    path: /metrics

health:
  port: 8082
  host: 127.0.0.1
  path: /health
  blockchains:
   - chain: ethereum
     min-availability: 1

cache:
  redis:
    enabled: true
    host: redis-master
    port: 6379
    db: 0
    password: I1y0dGKy01by

proxy:
  host: 0.0.0.0
  port: 8080
  websocket: true
  tls:
    enabled: true
    server:
      certificate: "/path/127.0.0.1.crt"
      key: "/path/127.0.0.1.p8.key"
    client:
      require: true
      ca: "/path/ca.dshackle.test.crt"
  routes:
    - id: eth
      blockchain: ethereum
    - id: kovan
      blockchain: kovan

tokens:
  - id: dai
    blockchain: ethereum
    name: DAI
    type: ERC-20
    address: 0x6B175474E89094C44Da98b954EedeAC495271d0F
  - id: tether
    blockchain: ethereum
    name: Tether
    type: ERC-20
    address: 0xdac17f958d2ee523a2206206994597c13d831ec7

accessLog:
  enabled: true
  filename: /var/log/dshackle/access_log.jsonl

cluster:
  defaults:
    - chains:
        - ethereum
      options:
        min-peers: 10
    - chains:
        - kovan
      options:
        min-peers: 3
  include:
    - "upstreams-extra.yaml"
  upstreams:
    - id: local
      chain: ethereum
      labels:
        fullnode: true
      methods:
        enabled:
          - name: "parity_trace"
        disabled:
          - name: "admin_shutdown"
      connection:
        ethereum:
          rpc:
            url: "http://localhost:8545"
          ws:
            url: "ws://localhost:8546"
            origin: "http://localhost"
            basic-auth:
              username: 9c199ad8f281f20154fc258fe41a6814
              password: 258fe4149c199ad8f2811a68f20154fc
    - id: infura
      chain: ethereum
      options:
        disable-validation: true
      connection:
        ethereum:
          rpc:
            url: "https://mainnet.infura.io/v3/fa28c968191849c1aff541ad1d8511f2"
            basic-auth:
              username: 4fc258fe41a68149c199ad8f281f2015
              password: 1a68f20154fc258fe4149c199ad8f281
    - id: bitcoin
      chain: bitcoin
      options:
        # use the node to fetch balances
        balance: true
      connection:
        bitcoin:
          rpc:
            url: "http://localhost:8332"
            basic-auth:
              username: bitcoin
              password: e984af45bb888428207c290
          # uses Esplora index to fetch balances and utxo for an address
          esplora:
            url: "http://localhost:3001"
    - id: remote
      connection:
        grpc:
          host: "10.2.0.15"
          tls:
            ca: /path/ca.dshackle.test.crt
            certificate: /path/client1.dshackle.test.crt
            key: /path/client1.dshackle.test.key

Top level config

Option Default Value Description

host

127.0.0.0

Host to bind gRPC server

port

2449

Port to bind gRPC server

tls

Setup TLS configuration for the gRPC server. See TLS server config section

monitoring

Setup Prometheus monitoring. See Monitoring section

health

Setup Health Check endpoint See Health Check endpoint section

proxy

Setup HTTP proxy that emulates all standard JSON RPC requests. See Proxy config section

accessLog

Configure access logging. See Access Log config section

tokens

Configure tokens for tracking balance. See Tokens config section

cache

Caching configuration. See Cache config section.

cluster

Setup connection to remote nodes.See Cluster section

TLS server config

tls:
  enabled: true
  server:
    certificate: "/path/127.0.0.1.crt"
    key: "/path/127.0.0.1.p8.key"
  client:
    require: true
    ca: "/path/ca.dshackle.test.crt"
Option Default Value Description

enabled

true if any value is set

Enable/Disable TLS

server.certificate

Path to x509 certificate

server.key

Path to a private key to the certificate.The key MUST BE in PKCS 8 format

client.require

If true then the server will required certificate from a client, otherwise client authentication is optional

client.ca

Certificate to validate client authentication

Monitoring

Configure Prometheus monitoring

monitoring:
  enabled: true
  jvm: false
  extended: false
  prometheus:
    enabled: true
    bind: 127.0.0.1
    port: 8081
    path: /metrics
Option Default Value Description

enabled

true

Enable/Disable monitoring endpoint

jvm

false

Enable/Disable JVM metrics (threads, GC, memory, etc)

extended

false

Enable/Disable additional metrics (query selectors, etc)

prometheus.enabled

true

Enable/Disable monitoring endpoint. Reserved for future use, in case of multiple different types of endpoints.

prometheus.bind

127.0.0.1

Host to bind the server

prometheus.port

8081

Port to bind the server

prometheus.path

/metrics

HTTP path to bind the server

Health Check endpoint

health:
  port: 8082
  host: 127.0.0.1
  path: /health
  blockchains:
    - chain: ethereum
      min-available: 2
    - chain: bitcoin
      min-available: 1
Option Default Value Description

port

8082

HTTP port to bind the server

host

127.0.0.1

HTTP host to bind the server

path

/health

HTTP path to respond on requests

blockchains

List of blockchains that must be available to consider the server healthy

[blockchain].chain

Blockchain id

[blockchain].min-available

1

How many available upstreams for the blockchain is required to pass

Proxy config

proxy:
  host: 0.0.0.0
  port: 8080
  tls:
    enabled: true
    server:
      certificate: "/path/127.0.0.1.crt"
      key: "/path/127.0.0.1.p8.key"
    client:
      require: true
      ca: "/path/ca.dshackle.test.crt"
  routes:
    - id: eth
      blockchain: ethereum
    - id: kovan
      blockchain: kovan
Table 1. Top config
Option Default Value Description

host

127.0.0.0

Host to bind HTTP server

port

8080

Port to bind HTT server

websocket

true

Enable WebSocket Proxy

tls

Setup TLS configuration for the Proxy server. See TLS server config section

routes

Routing paths for Proxy. The proxy will handle requests as https://${HOST}:${PORT}/${ROUTE_ID} (or http:// if TLS is not enabled). For WebSocket it’s wss / ws, accordingly.
Table 2. Route config
Option Default Value Description

id

Internal alphanumeric id, and a path of binding url - https://${HOST}:${PORT}/${ROUTE_ID}.

blockchain

A blockchain that must be used to handle that route.

Access Log config

accessLog:
  enabled: true
  filename: /var/log/dshackle/access_log.jsonl
Table 3. Access Log config
Option Default Description

enabled

false

Enable/Disable Access logging

filename

access_log.jsonl

Path to the access log file

Tokens config

tokens:
  - id: dai
    blockchain: ethereum
    name: DAI
    type: ERC-20
    address: 0x6B175474E89094C44Da98b954EedeAC495271d0F
  - id: tether
    blockchain: ethereum
    name: Tether
    type: ERC-20
    address: 0xdac17f958d2ee523a2206206994597c13d831ec7

Tokens config enables tracking of a balance amount in the configured tokens. After making the configuration above you can request balance (GetBalance), or subscribe to balance changes (SubscribeBalance), using enhanced protocol

Table 4. Token config
Option Description

id

Internal id for reference (used in logging, etc)

blockchain

An ethereum-based blockchain where the contract is deployed

name

Name of the token, used for balance response as asset code (as converted to UPPERCASE)

type

Type of token.Only ERC-20 is supported at this moment

address

Address of the deployed contract

Cache config

cache:
  redis:
    enabled: true
    host: redis-master
    port: 6379
    db: 0
    password: I1y0dGKy01by
Table 5. Redis Config
Option Default Value Description

enabled

false

Enable/disable Redis cache

host

127.0.0.1

Redis host address

port

6379

Redis port

db

0

Redis DB to select

password

Password for connection, if required

Cluster

The cluster config is the main part, that defines all connection to nodes and other servers

cluster:
  defaults:
    - chains:
        - ethereum
      options:
        min-peers: 10
  upstreams:
    - id: local
      chain: ethereum
      connection:
        ethereum:
          rpc:
            url: "http://localhost:8545"
          ws:
            url: "ws://localhost:8546"
            origin: "http://localhost"
  include:
    - "upstreams-extra.yaml"

Main Cluster Configuration

Table 6. Top Level Config
Option Description

defaults

Default options applied to all upstreams within the specified blockchain. It’s an optional configuration, and may be omitted for most of the situations.

upstreams

List of upstream servers. The main part of the config. There are two types of upstream: JSON RPC Upstream and Dshackle Upstream.

include

Path(s) to include configurations for upstream servers. Same as upstreams, but load it from an external file.

JSON RPC Upstream

- id: local
  chain: ethereum
  role: standard
  labels:
    fullnode: true
  methods:
    enabled:
      - name: "parity_trace"
        quorum: "not_empty"
    disabled:
      - name: "admin_shutdown"
  connection:
    ethereum:
      rpc:
        url: "http://localhost:8545"
      ws:
        url: "ws://localhost:8546"
        origin: "http://localhost"
        basic-auth:
          username: 9c199ad8f281f20154fc258fe41a6814
          password: 258fe4149c199ad8f2811a68f20154fc
        frameSize: 5mb
        msgSize: 15mb
Table 7. Main Config
Option Required Description

id

yes

Per-cluster identifier of an upstream

role

no

standard (default) or fallback. Fallback role mean that the upstream is used only after other upstreams failed or didn’t return quorum

chain

yes

Blockchain which is the provided by the upstream. Cluster may have multiple upstreams for a single blockchain. Accepted types: bitcoin, bitcoin-testnet, ethereum, ethereum-classic, kovan-testnet, rinkeby-testnet, ropsten-testnet, or goerli-testnet

enabled

no

true (default) or false. Enable/disable the upstream.

labels

no

Key-Value pairs that are assigned to the upstream. Used to select an upstream per-request. See Quorum and Selectors

methods

no

Enable (enabled) or disable (disabled) additional JSON RPC methods that are provided by that particular upstream

methods.enabled.name, methods.disabled.name

yes

Name of the RPC method to enable/disable.

methods.enabled.quorum

no

Set quorum criteria to accept a response. always (default) - accept any response; not_empty - accept not null value, otherwise retry another upstream; not_lagging - accept response only from a fully synced upstream.

connection.ethereum

yes

Connection configuration for Ethereum API

connection.bitcoin

yes

Connection configuration for Bitcoin API
Table 8. Connection Config
Option Description

rpc.url

HTTP URL to connect to.This is required for a connection.
URL can be configured with Environment Variable placeholders ${ENV_VAR_NAME}.
Example: https://kovan.infura.io/v3/${INFURA_USER}

rpc.basic-auth + rpc.basic-auth.username, rpc.basic-auth.password

HTTP Basic Auth configuration, if required by the remote server.
Values can also reference env variables, for example:

rpc:
  url: "https://ethereum.com:8545"
  basic-auth:
    username: "${ETH_USERNAME}"
    password: "${ETH_PASSWORD}"

ws.url

WebSocket URL to connect to. Optional, but optimizes performance if it’s available.

ws.origin

HTTP Origin if required by WebSocket remote server.

ws.basic-auth + …​

WebSocket Basic Auth configuration, if required by the remote server

ws.frameSize

WebSocket frame size limit. Ex 1kb, 1024 (same as 1kb), `2mb, etc. Default is 5Mb

ws.msgSize

Total limit for a message size consisting from multiple frames. Ex 1kb, 1024 (same as 1kb), `2mb, etc. Default is 15Mb

Dshackle Upstream

Another option is using another Dshackle server as an upstream. It’s more effective, easier to secure connection, and allows to build a distributed network of servers.

- id: test1
  connection:
    grpc:
      host: eu-api.mycompany.com
      port: 2449
      tls:
        ca: ca.api.mycompany.crt
        certificate: client-1.api.mycompany.crt
        key: client-1.api.mycompany.p8.key
Table 9. Main Config
Option Required Description

id

yes

Per-cluster identifier of an upstream

connection.grpc

yes

Connection configuration for Dshackle gRPC
Table 10. Connection Config
Option Description

host and port

Address to connect to

tls

TLC configuration for the connection. In general it’s an optional configuration, but it’s strongly recommended. Also HTTP2 + gRPC is designed to be used with TLS, and some of the related software is unable to use it without TLS.
See Authentication docs and TLS server config.

tls.ca

Path to x509 certificate to verify remote server

tls.certificate + tls.key

Client certificate (x509) and its private key (PKCS 8) used for authentication on the remote server.