1003 lines
22 KiB
Plaintext
1003 lines
22 KiB
Plaintext
= Configuration Reference
|
||
:toc:
|
||
:toclevels: 2
|
||
|
||
toc::[]
|
||
|
||
== Example
|
||
|
||
.Example configuration with most options configured
|
||
[source,yaml]
|
||
----
|
||
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
|
||
|
||
auth:
|
||
enabled: false
|
||
|
||
proxy:
|
||
host: 0.0.0.0
|
||
port: 8080
|
||
websocket: true
|
||
preserve-batch-order: false
|
||
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:
|
||
generic:
|
||
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:
|
||
generic:
|
||
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
|
||
# use Esplora index to fetch balances and utxo for an address
|
||
esplora:
|
||
url: "http://localhost:3001"
|
||
# connect via ZeroMQ to get notifications about new blocks
|
||
zeromq:
|
||
address: "http://localhost:5555"
|
||
- 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
|
||
|
||
[cols="2a,2,5"]
|
||
|===
|
||
| 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>> section
|
||
|
||
| `monitoring`
|
||
|
|
||
| Setup Prometheus monitoring.
|
||
See <<monitoring>> section
|
||
|
||
| `health`
|
||
|
|
||
| Setup Health Check endpoint See <<health>> section
|
||
|
||
| `proxy`
|
||
|
|
||
| Setup HTTP proxy that emulates all standard JSON RPC requests.
|
||
See <<proxy>> section
|
||
|
||
| `accessLog`
|
||
|
|
||
| Configure access logging.
|
||
See <<accessLog>> section
|
||
|
||
|
||
| `tokens`
|
||
|
|
||
| Configure tokens for tracking balance.
|
||
See <<tokens>> section
|
||
|
||
| `cache`
|
||
|
|
||
| Caching configuration.
|
||
See <<cache>> section.
|
||
|
||
| `auth`
|
||
|
|
||
| Authorization and response signing.
|
||
See <<auth>> section.
|
||
|
||
| `cluster`
|
||
|
|
||
| Setup connection to remote nodes.See <<cluster>> section
|
||
|
||
|===
|
||
|
||
[#tls]
|
||
== TLS server config
|
||
|
||
[source,yaml]
|
||
----
|
||
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"
|
||
----
|
||
|
||
[cols="2a,2,5"]
|
||
|===
|
||
| Option | Default Value | Description
|
||
|
||
| `enabled`
|
||
a| `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]
|
||
== Monitoring
|
||
|
||
Configure Prometheus monitoring
|
||
|
||
[source,yaml]
|
||
----
|
||
monitoring:
|
||
enabled: true
|
||
jvm: false
|
||
extended: false
|
||
prometheus:
|
||
enabled: true
|
||
bind: 127.0.0.1
|
||
port: 8081
|
||
path: /metrics
|
||
----
|
||
|
||
[cols="2a,2a,5"]
|
||
|===
|
||
| 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]
|
||
== Health Check endpoint
|
||
|
||
[source,yaml]
|
||
----
|
||
health:
|
||
port: 8082
|
||
host: 127.0.0.1
|
||
path: /health
|
||
blockchains:
|
||
- chain: ethereum
|
||
min-available: 2
|
||
- chain: bitcoin
|
||
min-available: 1
|
||
----
|
||
|
||
[cols="2a,2a,5"]
|
||
|===
|
||
| 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]
|
||
== Proxy config
|
||
|
||
[source,yaml]
|
||
----
|
||
proxy:
|
||
host: 0.0.0.0
|
||
port: 8080
|
||
preserve-batch-order: false
|
||
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
|
||
----
|
||
|
||
.Top config
|
||
[cols="2a,2,5"]
|
||
|===
|
||
| Option | Default Value | Description
|
||
|
||
| `host`
|
||
| `127.0.0.0`
|
||
| Host to bind HTTP server
|
||
|
||
| `port`
|
||
| `8080`
|
||
| Port to bind HTT server
|
||
|
||
| `port`
|
||
| `false`
|
||
| Should proxy preserve request-response correspondence when sending batch request via http
|
||
|
||
| `websocket`
|
||
| `true`
|
||
| Enable WebSocket Proxy
|
||
|
||
| `tls`
|
||
|
|
||
| Setup TLS configuration for the Proxy server.
|
||
See <<tls>> section
|
||
|
||
| `preserve-batch-order`
|
||
| false
|
||
| If `false` Dshackle may produce _batch_ response in different order, which is correct as per JSON RPC Spec.
|
||
If set to `true` then Dshackle preserves _batch_ order based on request order.
|
||
Note that latter is ineffective and use this option only when a client cannot reference responses by their IDs.
|
||
|
||
| `cors-origin`
|
||
|
|
||
| Access-Control-Allow-Origin contents. If empty the header will be omitted in response
|
||
|
||
| `cors-allowed-headers`
|
||
| `Content-Type`
|
||
| Access-Control-Allow-Headers contents. Takes effect only if сors-origi is present in config
|
||
|
||
| `routes`
|
||
|
|
||
a| 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.
|
||
|===
|
||
|
||
.Route config
|
||
[cols="2a,2,5"]
|
||
|===
|
||
| 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.
|
||
|
||
|===
|
||
|
||
[#accessLog]
|
||
== Access Log config
|
||
|
||
[source,yaml]
|
||
----
|
||
accessLog:
|
||
enabled: true
|
||
filename: /var/log/dshackle/access_log.jsonl
|
||
----
|
||
|
||
.Access Log config
|
||
[cols="2a,3a,7"]
|
||
|===
|
||
| Option | Default | Description
|
||
|
||
| `enabled`
|
||
| `false`
|
||
| Enable/Disable Access logging
|
||
|
||
| `include-messages`
|
||
| `false`
|
||
| Include request params and response result/error (i.e., a JSON) in access log.
|
||
It's an expensive operation, use it for debugging only.
|
||
Note that for errors it provides only error message, not the error response itself.
|
||
|
||
| `filename`
|
||
| `access_log.jsonl`
|
||
| Path to the access log file
|
||
|
||
|===
|
||
|
||
[#tokens]
|
||
== Tokens config
|
||
|
||
[source,yaml]
|
||
----
|
||
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 xref:07-methods.adoc[enhanced protocol]
|
||
|
||
.Token config
|
||
[cols="2a,7"]
|
||
|===
|
||
| 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]
|
||
== Cache config
|
||
|
||
[source,yaml]
|
||
----
|
||
cache:
|
||
redis:
|
||
enabled: true
|
||
host: redis-master
|
||
port: 6379
|
||
db: 0
|
||
password: I1y0dGKy01by
|
||
----
|
||
|
||
.Redis Config
|
||
[cols="2a,2,5"]
|
||
|===
|
||
| 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
|
||
|
||
|===
|
||
|
||
[#auth]
|
||
== Authorization
|
||
|
||
dshackle supports optional client authentication via signed JWT tokens (RS256). When
|
||
`auth.enabled` is `true`, dshackle validates tokens issued by a trusted provider and
|
||
rejects unauthenticated requests.
|
||
|
||
[source,yaml]
|
||
----
|
||
auth:
|
||
enabled: true
|
||
publicKeyOwner: "token-issuer-name"
|
||
server:
|
||
keys:
|
||
provider-private-key: "/etc/dshackle/auth/jwt-rsa.pem"
|
||
external-public-key: "/etc/dshackle/auth/jwt-rsa.pub"
|
||
----
|
||
|
||
|===
|
||
| Name | Default | Description
|
||
|
||
| `enabled`
|
||
| `false`
|
||
| Enables authorization and response signing.
|
||
|
||
| `publicKeyOwner`
|
||
|
|
||
| Expected value of the `iss` claim on inbound JWT tokens.
|
||
|
||
| `server.keys.provider-private-key`
|
||
|
|
||
| Path to a PKCS#8 PEM RSA private key. Used both to sign session JWTs issued by
|
||
dshackle and to sign `NativeCall` response payloads (see <<response-signing>>).
|
||
|
||
| `server.keys.external-public-key`
|
||
|
|
||
| Path to a PEM-encoded RSA public key (X.509 SubjectPublicKeyInfo) used to verify
|
||
the JWTs clients present to `emerald.Auth/Authenticate`.
|
||
|===
|
||
|
||
[#response-signing]
|
||
==== Response Signing
|
||
|
||
When `auth.enabled` is `true` and `auth.server.keys.provider-private-key` points to a
|
||
valid PKCS#8 RSA private key, dshackle automatically signs gRPC responses with
|
||
`SHA256withRSA` for any `NativeCall` request that provides a non-zero `nonce`. The same
|
||
key used for issuing JWT tokens (RS256) is reused for response signatures — no separate
|
||
configuration is required.
|
||
|
||
The signed blob is `DSHACKLESIG/<nonce>/<upstream_id>/<hex-sha256(payload)>`. The
|
||
returned `NativeCallReplySignature` carries the original `nonce`, the signature bytes
|
||
and a `key_id` (first 8 bytes of the SHA-256 of the public key). Clients verify with
|
||
the public half of `provider-private-key`.
|
||
|
||
If a client sends a nonce but the signing key is not configured (auth disabled or the
|
||
path is empty), dshackle returns an error with code `-32603` and message
|
||
"Response signing requested via nonce but signing key is not configured".
|
||
|
||
A runnable end-to-end example (dshackle config, demo RSA keys and a Go client) lives
|
||
in `demo/response-signing/` in the repository.
|
||
|
||
[#cluster]
|
||
== Cluster
|
||
|
||
The cluster config is the main part, that defines all connection to nodes and other servers
|
||
|
||
[source,yaml]
|
||
----
|
||
cluster:
|
||
defaults:
|
||
- chains:
|
||
- ethereum
|
||
options:
|
||
min-peers: 10
|
||
upstreams:
|
||
- id: local
|
||
chain: ethereum
|
||
connection:
|
||
generic:
|
||
rpc:
|
||
url: "http://localhost:8545"
|
||
ws:
|
||
url: "ws://localhost:8546"
|
||
origin: "http://localhost"
|
||
include:
|
||
- "upstreams-extra.yaml"
|
||
----
|
||
|
||
=== Main Cluster Configuration
|
||
|
||
.Top Level Config
|
||
[cols="2a,5"]
|
||
|===
|
||
| 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: <<upstream-json>> and <<upstream-dshackle>>.
|
||
|
||
| `include`
|
||
| Path(s) to include configurations for upstream servers. Same as `upstreams`, but load it from an external file.
|
||
|
||
|===
|
||
|
||
[#upstream-json]
|
||
=== JSON RPC Upstream
|
||
|
||
[source,yaml]
|
||
----
|
||
- id: local
|
||
chain: ethereum
|
||
role: standard
|
||
labels:
|
||
fullnode: true
|
||
methods:
|
||
enabled:
|
||
- name: "parity_trace"
|
||
quorum: "not_empty"
|
||
disabled:
|
||
- name: "admin_shutdown"
|
||
connection:
|
||
generic:
|
||
rpc:
|
||
url: "http://localhost:8545"
|
||
ws:
|
||
url: "ws://localhost:8546"
|
||
origin: "http://localhost"
|
||
basic-auth:
|
||
username: 9c199ad8f281f20154fc258fe41a6814
|
||
password: 258fe4149c199ad8f2811a68f20154fc
|
||
frameSize: 5mb
|
||
msgSize: 15mb
|
||
----
|
||
|
||
.Main Config
|
||
[cols="2a,1a,5"]
|
||
|===
|
||
| Option | Required | Description
|
||
|
||
| `id`
|
||
| yes
|
||
| Per-cluster identifier of an upstream
|
||
|
||
| `role`
|
||
| no
|
||
| `primary` (default), `secondary` or `fallback`.
|
||
First it makes the requests to the upstreams with role `primary`, then if none are available to upstreams with role `secondary`.
|
||
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` or `ropsten-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 xref:09-quorum-and-selectors.adoc[Quorum and Selectors]
|
||
|
||
| `options`
|
||
|
|
||
| Other configuration options. See <<general-options>>
|
||
|
||
| `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.generic`
|
||
| yes
|
||
| Generic connection configuration for most of networks e.g. Ethereum
|
||
|
||
| `connection.bitcoin`
|
||
| yes
|
||
| Connection configuration for Bitcoin API
|
||
|
||
|===
|
||
|
||
[#general-options]
|
||
=== General Upstream Options
|
||
|
||
[cols="2a,1,1a,5"]
|
||
|===
|
||
| Option | Type | Default | Description
|
||
|
||
| `disable-validation`
|
||
| boolean
|
||
| `false`
|
||
| Disables all the validations of the upstream. I.e., it turns off `validate-peers` and `validate-syncing` checks if set to `true`.
|
||
|
||
| `validate-chain`
|
||
| boolean
|
||
| `true`
|
||
| Disables validation of the chain settings of the upstream. Prevent of creating an upstream with incorrect chain if it relates to a node with another chain.
|
||
|
||
| `validation-interval`
|
||
| number
|
||
| `30`
|
||
| Period in seconds to re-validate the upstream.
|
||
|
||
| `validate-peers`
|
||
| boolean
|
||
| `true`
|
||
| Disables validation of the peers connected to the upstream (as `net_peerCount` method).
|
||
Dshackle assumes that if there are too few peers then the Upstream is just started and may produce invalid/outdated responses
|
||
|
||
| `min-peers`
|
||
| number
|
||
| `1`
|
||
| The minimum number of connected peer to consider the upstream valid if `validate-peers` is enabled.
|
||
If it's set to `0` it essentially disables the peer validation.
|
||
|
||
| `validate-syncing`
|
||
| boolean
|
||
| `true`
|
||
| Disables checking for the state of syncing on the upstream (as `eth_syncing` method).
|
||
If the Upstream is in _syncing_ state then the Dshackle doesn't use it for call until it reaches the blockchain head.
|
||
|
||
| `validate-call-limit`
|
||
| boolean
|
||
| `true`
|
||
| Enable/Disable the call limit validation. Size of call limit is defined by `call-limit` option.
|
||
If it's enabled configuration parameter for chain `call-limit-contract` is required.
|
||
|
||
| `validate-gas-price`
|
||
| boolean
|
||
| `true`
|
||
| Enable/Disable the gas price validation. If it's enabled, the Dshackle will check the gas price of the upstream and compare it with the gas price conditions in chain.yaml
|
||
Check conditions can contain multiple values presented as a list of pair operator and value. The operator can be `eq`, `ne`, `gt`, `ge`, `lt`, `le`. Value is a Long number.
|
||
|
||
| `call-limit-size`
|
||
| number
|
||
| `1000000`
|
||
| For all eth-like chains (except zkSync). The maximum size of the call limit. If the upstream exceeds this limit, it will be considered as failed.
|
||
|
||
| `timeout`
|
||
| number
|
||
| `60`
|
||
| Timeout in seconds to wait for an answer from the upstream before considering it as failed.
|
||
|
||
| `balance`
|
||
| boolean
|
||
|
|
||
| Suitable for Bitcoin upstream.
|
||
Tells if the Upstream can be used to call balance methods, which requires that the node has the indexing as turned on.
|
||
|
||
|===
|
||
|
||
==== Ethereum Connection Options
|
||
|
||
.Connection Config for Ethereum Upstream
|
||
[cols="2a,5"]
|
||
|===
|
||
| Option | Description
|
||
|
||
| `rpc.url`
|
||
a| 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`
|
||
a| HTTP Basic Auth configuration, if required by the remote server. +
|
||
Values can also reference env variables, for example:
|
||
[source,yaml]
|
||
----
|
||
rpc:
|
||
url: "https://ethereum.com:8545"
|
||
basic-auth:
|
||
username: "${ETH_USERNAME}"
|
||
password: "${ETH_PASSWORD}"
|
||
----
|
||
|
||
| `rpc.bearer-auth` + `rpc.bearer-auth.token`
|
||
a| HTTP Bearer token authorization (`Authorization: Bearer <token>` header), if required by the remote server. +
|
||
Cannot be used together with `basic-auth`.
|
||
Value can also reference env variables, for example:
|
||
[source,yaml]
|
||
----
|
||
rpc:
|
||
url: "https://ethereum.com:8545"
|
||
bearer-auth:
|
||
token: "${ETH_TOKEN}"
|
||
----
|
||
|
||
| `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.bearer-auth` + `ws.bearer-auth.token`
|
||
| WebSocket Bearer token authorization, 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
|
||
|
||
| `ws.connections`
|
||
| How many concurrent connection to make. If more than one, each used in a robin-round fashion.
|
||
Defaults is `1`
|
||
|===
|
||
|
||
==== PoS Ethereum Connection Options
|
||
.Connection Config for PoS Ethereum Upstream
|
||
[cols="2a,5"]
|
||
|===
|
||
| Option | Description
|
||
|
||
| `execution`
|
||
a| Here you can specify any option from plain ethereum connection options listed above +
|
||
This is your connection to an execution layer of PoS Ethereum
|
||
|
||
| `upstream-rating`
|
||
a| Rating for this upstream. We will always consider the head of the chain to be +
|
||
the latest block we saw from the upstream with the highest rating.
|
||
|
||
|===
|
||
|
||
==== Bitcoin Connection Options
|
||
|
||
.Connection Config for Bitcoin Upstream
|
||
[cols="2a,5"]
|
||
|===
|
||
| Option | Description
|
||
|
||
| `rpc.url`
|
||
a| HTTP URL to connect to. This is required for a connection. +
|
||
URL can be configured with Environment Variable placeholders `${ENV_VAR_NAME}`. +
|
||
Example: `http://${NODE_HOST}:${NODE_PORT}`
|
||
|
||
| `rpc.basic-auth` + `rpc.basic-auth.username`, `rpc.basic-auth.password`
|
||
a| HTTP Basic Auth configuration, which is required by the Bitcoind server. +
|
||
Values can also reference env variables, for example:
|
||
[source,yaml]
|
||
----
|
||
rpc:
|
||
url: "http://127.0.0.1:8332"
|
||
basic-auth:
|
||
username: "${NODE_USERNAME}"
|
||
password: "${NODE_PASSWORD}"
|
||
----
|
||
|
||
| `zeromq.address`
|
||
a| Set up an additional connection via ZeroMQ protocol to subscribe to the new blocks.
|
||
The node must be launched with the same address specified as `-zmqpubhashblock="tcp://${HOST}:${POST}"` or in `bitcoin.conf`
|
||
[source,yaml]
|
||
----
|
||
zeromq:
|
||
address: "127.0.0.1:5555"
|
||
----
|
||
|
||
|===
|
||
|
||
[#upstream-dshackle]
|
||
=== 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.
|
||
|
||
[source,yaml]
|
||
----
|
||
- id: test1
|
||
labels:
|
||
provider: some
|
||
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
|
||
----
|
||
|
||
.Main Config
|
||
[cols="2a,1a,5"]
|
||
|===
|
||
| Option | Required | Description
|
||
|
||
| `id`
|
||
| yes
|
||
| Per-cluster identifier of an upstream
|
||
|
||
| `labels`
|
||
| no
|
||
| Defines the labels can be used for the proper upstream instance selection. Overrides the labels retrieved by the `describe` method
|
||
|
||
| `connection.grpc`
|
||
| yes
|
||
| Connection configuration for Dshackle gRPC
|
||
|===
|
||
|
||
.Connection Config
|
||
[cols="2a,5"]
|
||
|===
|
||
| Option | Description
|
||
|
||
| `host` and `port`
|
||
| Address to connect to
|
||
|
||
| `tls`
|
||
a| 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 xref:08-authentication.adoc[Authentication] docs and <<tls>>.
|
||
|
||
| `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.
|
||
|
||
|===
|