115 lines
3.7 KiB
Plaintext
115 lines
3.7 KiB
Plaintext
== Upstreams Configuration
|
|
|
|
Dshackle can connect to multiple independent APIs ("upstreams") and provides an unified API on top of it.
|
|
|
|
Supported upstream protocols:
|
|
|
|
- JSON RPC
|
|
- Websockets
|
|
- gRPC (i.e. can connect to another Dshackle)
|
|
|
|
Those protocols can be configures with additional security, TLS and authentication.
|
|
|
|
=== Example
|
|
|
|
.upstreams.yaml
|
|
[source,yaml]
|
|
----
|
|
version: v1
|
|
|
|
defaultOptions:
|
|
- chains:
|
|
- ethereum
|
|
options:
|
|
min-peers: 10
|
|
- chains:
|
|
- kovan
|
|
options:
|
|
min-peers: 2
|
|
|
|
upstreams:
|
|
- id: us-nodes
|
|
chain: auto
|
|
connection:
|
|
grpc:
|
|
host: 35.226.252.117
|
|
port: 443
|
|
tls:
|
|
ca: ca.crt
|
|
certificate: client.crt
|
|
key: client.p8.key
|
|
- id: infura-eth
|
|
chain: ethereum
|
|
labels:
|
|
provider: infura
|
|
options:
|
|
disable-validation: true
|
|
connection:
|
|
ethereum:
|
|
rpc:
|
|
url: "https://mainnet.infura.io/v3/${INFURA_USER}"
|
|
basic-auth:
|
|
username: ${INFURA_USER}
|
|
password: ${INFURA_PASSWD}
|
|
ws:
|
|
url: "wss://mainnet.infura.io/ws/v3/${INFURA_USER}"
|
|
basic-auth:
|
|
username: ${INFURA_USER}
|
|
password: ${INFURA_PASSWD}
|
|
----
|
|
|
|
There're two main segments for upstreams configuration:
|
|
|
|
- _upstreams_ - a list of API to connect to, with all configuration specific for upstream and chain
|
|
- and _default options_ as common configuration options applied to all nodes in that group
|
|
|
|
In the example above we have:
|
|
|
|
- default configuration for _Ethereum Mainnet_ which accepts upstream as valid when it not in fast synchronization mode
|
|
and has at least 10 peers. For _Kovan Testnet_ nodes the requirements are much relieved
|
|
- as upstreams it has 2 configurations
|
|
* balancer connects to another Dshackle/another machine by using gRPC protocol
|
|
** accepts (i.e. proxies) any blockchain available on that remote
|
|
** verifies TLS certificate of the server
|
|
** uses client certificate for authentication, i.e. remote server is accepting only clients authenticated by a
|
|
certificate
|
|
* connects to Infura provided _Ethereum Mainnet_
|
|
** configuration is using placeholders for `${INFURA_USER}` and `${INFURA_PASSWD}` which will be replaced with
|
|
corresponding environment variables values
|
|
** uses Basic Authentication to authenticate requests on Infura
|
|
** label `[provider: infura]` is set for that particular upstream, which can be selected during a request. For example for
|
|
some requests you may want to use nodes with that label only, i.e. _"send that tx to infura nodes only"_,
|
|
or _"read only from archive node, with label [archive: true]"_
|
|
** upstream validation (peers, sync status, etc) is disabled for that particular upstream
|
|
|
|
=== Configuration options
|
|
|
|
Options (default or as part of upstream config):
|
|
|
|
- `disable-validation` - if `true` then Dshackle would not try to verify status of the upstream (useful for a trusted cloud
|
|
provider such as Infura, but is not recommended for an own node)
|
|
- `min-peers` - do not use upstream with less than specified connected peers
|
|
|
|
=== Connection type
|
|
|
|
Dshackle currently supports
|
|
|
|
- `rpc` a standard Ethereum JSON RPC
|
|
- `ws` websocket connection (supposed to be used in addition to `rpc` connection)
|
|
- `grpc` connects to another Dshackle instance
|
|
|
|
=== Authentication
|
|
|
|
==== TLS
|
|
|
|
All connection types can use TLS secured connection, with optional client certificate authentication:
|
|
|
|
- `ca` path to certificate required from remote server
|
|
- optional `certificate` and `key` for client authentication. Please note that `key` is encoded with _PKCS 8_
|
|
|
|
==== Basic Authentication
|
|
|
|
For JSON RPC and Websockets a Basic Authentication can be used:
|
|
|
|
- `username` - username
|
|
- `password` - password |