Providers
NodeCore setup instructions

NodeCore setup instructions

We are not onboarding new providers at the moment. This guide is for existing dRPC providers.

NodeCore is a proxy used by dRPC as an entry point for your provider. It allows you to aggregate multiple nodes under one provider and routes each request to a node that is able to serve it. NodeCore is open source, the code and the full documentation are on GitHub (opens in a new tab).

If you run Dshackle today, start with Migrating from Dshackle. It converts your existing config, and then this page describes everything you need to run and maintain NodeCore.

NodeCore Deployment Considerations#

Running multiple NodeCore servers behind a single DNS name is not supported. If you want to run multiple NodeCore servers (in the same region or in different regions), please deploy each server with its own DNS name and an SSL certificate for that name.

Common NodeCore Deployment Schemes:

  • One NodeCore server per data center: For example, if you have blockchain nodes in a data center in Frankfurt, you can deploy a NodeCore server in the same data center and connect the nodes you host there to it.

Provider name#

Your provider name is a unique identifier for your nodes in dRPC. The convention is to name it using your-company-name + any-suffix.

Install NodeCore#

The easiest way to install NodeCore is by using the docker image (opens in a new tab).

For Kubernetes there is a Helm chart (opens in a new tab).

Docker-compose example#

Create docker-compose.yaml file with the following content:

services:
  nodecore:
    container_name: nodecore
    image: drpcorg/nodecore:latest
    environment:
      - NODECORE_CONFIG_PATH=/etc/nodecore/nodecore.yml
    volumes:
      - "/path_to_config:/etc/nodecore"
      - "/path_to_ssl_certs:/path_to_ssl_certs"
      - "/path_to_keys:/path_to_keys"
    ports:
      - "12448:12448"
      - "127.0.0.1:9093:9093"

You can start it by docker compose up -d command.

A few things to keep in mind:

  • /path_to_config is the directory that contains your nodecore.yml. Mount the directory, not the file itself, otherwise config reload may not see your changes.
  • NODECORE_CONFIG_PATH tells NodeCore where the config is. Without it NodeCore starts with the default config that is built into the image and ignores yours.
  • NodeCore runs inside the container as a non-root user with uid 65532. The config, the keys and the SSL certificate and key must be readable by this user, for example chown 65532 /path_to_keys/private-provider-name.p8.key. Otherwise NodeCore stops at startup with a permission denied error.
  • 12448 is the port dRPC connects to. 9093 is the metrics port, it is published for the local machine only.

ATTENTION: NodeCore also opens an HTTP port (9090 by default) that serves JSON-RPC requests without authorization. dRPC doesn't use it. Do not publish this port. If you run NodeCore without Docker or with host networking, close this port with a firewall.

Minimal provider config#

This configuration defines the simplest possible provider with two nodes that will serve requests. You can add any number of additional nodes as needed.

Note: We expect you to set up your NodeCore instance with TLS enabled and a valid SSL certificate.

ATTENTION: Connect your nodes to NodeCore ONLY directly, without any load balancers in between. Using a load balancer between your nodes and NodeCore can lead to errors and inconsistent node states. NodeCore acts as a load balancer itself.

server:
  grpc-port: 12448
  metrics-port: 9093
  tls:
    enabled: true
    certificate: /path_to_ssl_certs/your_ssl_cert.crt
    key: /path_to_ssl_certs/your_ssl_key.p8.key
  grpc-auth:
    enabled: true
    public-key-owner: drpc # always drpc
    provider-private-key-path: /path_to_keys/private-provider-name.p8.key
    external-public-key-path: /path_to_keys/public-drpc.pem
 
upstream-config:
  mode: strict # required
  balancing-strategy: base # required
  upstreams:
    - id: ethnode1
      chain: ethereum
      connectors:
        - type: json-rpc
          url: "http://example1.com:8545"
        - type: websocket
          url: "ws://example1.com:8545"
    - id: ethnode2
      chain: ethereum
      connectors:
        - type: json-rpc
          url: "http://example2.com:8545"
        - type: websocket
          url: "ws://example2.com:8545"

Required settings

These two settings must be present in the config of every dRPC provider:

Connectors

Each node is described by its connectors. For an EVM node these are json-rpc and websocket. Other chains use other connector types, for example rest for the Beacon Chain or tendermint for Cosmos SDK chains. The full list is in the connectors (opens in a new tab) reference.

Methods and node history

There is nothing to configure here:

  • NodeCore detects which methods each node serves, including the trace, debug and filter methods.
  • NodeCore detects how far back each node keeps its state, blocks, logs, transactions, receipts, traces and proofs, and reports it to dRPC.

Supported chains#

The chain names are listed in chains.yaml (opens in a new tab).

NodeCore doesn't serve Ripple and Kadena for now. Nodes of these chains have to stay on Dshackle.

An upstream that points to another Dshackle instance is not supported for now either.

Full configuration reference#

The detailed documentation is on GitHub:

Reload config#

You can change the list of nodes under upstream-config.upstreams in your nodecore.yml and then reload it in order to pick the changes up without NodeCore restart. All other settings are applied on restart only.

You can do it via sending a kill command with HUP signal to your container, for example docker kill --signal SIGHUP nodecore. And then you will see the reloading logs:

reloading the config file /etc/nodecore/nodecore.yml (signal hangup)
upstreams reloaded: added [ethnode3], removed [], changed [], failed []

If the new config is not valid, NodeCore logs an error and keeps working with the previous list of nodes.

NodeCore can also check the file itself and reload it when it changes:

config-reload:
  watch-interval: 30s

Attention: your volume in docker must be the directory with nodecore.yml, not the file itself. With a single file mounted, the container may keep the old version of the file after you replace it.

See Config reload (opens in a new tab) for more details.

Authorization#

Our authorization algorithm is based on public/private key pairs and JWT tokens. We hold our private key and your public key, while you retain your private key and our public key. Using these keys, both sides generate JWT tokens, verify their validity, and if the verification succeeds, authorization is successfully established.

Currently, we support only RSA keys. You can use the following script to generate a key pair, specifying the key suffix as the first argument:

rsa-key-generator.sh:

#!/bin/sh
if [ -z "$1" ]
  then
    echo "Please, specify key suffix"
    exit 1
fi
 
echo "Generating RSA key pair"
 
openssl genrsa -out private-$1.pem 2048
openssl rsa -in private-$1.pem -pubout -out public-$1.pem
openssl pkcs8 -topk8 -inform PEM -outform PEM -in private-$1.pem -out private-$1.p8.key -nocrypt
rm private-$1.pem
 
echo "Key pair is generated"

For example, if you want to generate your pair with the provider-name suffix, you would execute ./rsa-key-generator.sh provider-name. After that, you will receive a pair of keys: a private key named private-provider-name.p8.key and a public key named public-provider-name.pem. Please share your public key with the dRPC team.

To enable authentication, add the following configuration to your nodecore.yml:

server:
  grpc-auth:
    enabled: true
    public-key-owner: drpc # always drpc
    provider-private-key-path: /path_to_keys/private-provider-name.p8.key # your private key
    external-public-key-path: /path_to_keys/public-drpc.pem # dRPC public key

external-public-key-path is the dRPC public key public-drpc.pem:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmi3CFtWG5a2NNXazozqX
ie8BckDC7BeH+0bF/GfU/HwhR+4q89s4RhnT+mGGo9egty9rRPESF91pKsy8Co8g
dBJ+jKxToCTXVN2L4BxnF6dr8FT55qrYFojobQcWrQNI4sl/X0OLscAHJegL9sH3
QNBMv0MiFk8NmXTCjFNKvTXinBlQ99VEVVVjert6KB6TRVjrEnyyPNBFMaQg2Cjz
j212Gnc/d32s5O9/9ABvdQjPYLQSM5YvNN4BsAyo2ij2fjDAnt6dYAMnTUs9deA5
4m8ME6+x5tqvAkK4aOM4AtgBrPuoezM1/euGE7hwJeL1z/RFNIkyZJcG7Mk9xI7/
0wIDAQAB
-----END PUBLIC KEY-----

Don't forget to add an additional volume (if it's necessary) with path_to_keys path. NodeCore doesn't start if one of the two key files is missing or can't be read.

Attention: Using this form of authorization does not imply that you can remove the TLS section from your configuration without taking further action. Your connection must remain secure. You can use your own SSL certificates (e.g., Let's Encrypt), or you can remove the TLS configuration and utilize TLS termination on your reverse proxy.

For example, you can add the following configuration for TLS with your own SSL certificate and key

server:
  tls:
    enabled: true
    certificate: /path_to_ssl_certs/your_ssl_cert.crt
    key: /path_to_ssl_certs/your_ssl_key.p8.key

NodeCore behind a reverse proxy

NodeCore can work behind a reverse proxy: dRPC connects to the reverse proxy with a valid SSL certificate, and the proxy passes requests to NodeCore. You need to terminate SSL on your reverse proxy and run NodeCore with TLS disabled, which means without the server.tls section in nodecore.yml.

Example of a docker-compose configuration with Traefik that proxies port 12448 to 12448 on NodeCore:

version: '3'
services:
  traefik:
    image: traefik:latest
    ports:
      - "443:443"
      - "12448:12448"
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.websecure.address=:443"
      - "--entryPoints.grpc.address=:12448"
      - "--certificatesresolvers.myresolver.acme.tlschallenge=true"
      - "--certificatesresolvers.myresolver.acme.email=$MAIL"
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
    volumes:
      - "./traefik/letsencrypt:/letsencrypt"
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
  nodecore:
    image: drpcorg/nodecore:latest
    environment:
      - NODECORE_CONFIG_PATH=/etc/nodecore/nodecore.yml
    volumes:
      - "/path_to_config:/etc/nodecore"
      - "/path_to_keys:/path_to_keys"
    labels:
      - "traefik.enable=true"
      - "traefik.http.services.drpc.loadbalancer.server.scheme=h2c"
      - "traefik.http.services.drpc.loadbalancer.server.port=12448"
      - "traefik.http.routers.drpc.entrypoints=grpc"
      - "traefik.http.routers.drpc.tls.certresolver=myresolver"
      - "traefik.http.routers.drpc.rule=Host(`$DOMAIN`)"

Example of a Nginx configuration:

location / {
    set $host_grpc_pass "grpc://<nodecore-server-address>:<nodecore-server-port>";
    grpc_pass $host_grpc_pass;
}

Example of a ingress-nginx configuration:

metadata:
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: GRPC

Using Other Reverse Proxies

The most important requirement is that your reverse proxy must support gRPC, as dRPC communicates with your NodeCore server using the gRPC protocol.

Check that it works#

After the start, check the logs and the metrics.

Logs

docker logs nodecore shows what NodeCore does at startup. You should see these lines:

starting dshackle grpc server on port 12448
starting metrics server on port 9093
upstreams will be started in strict mode

After that NodeCore checks every node and prints what it has detected, for example the client type and version of each node. Warnings like method debug_storageRangeAt is not available on upstream 'ethnode1' are expected: NodeCore found out that the node doesn't serve this method.

If there is a mistake in the config, or a file can't be read, NodeCore stops at startup and the last log lines name the problem.

A node that NodeCore can't reach is easy to find by its id:

upstream http request failed error="... connect: connection refused" upstream=ethnode3

Metrics

The metrics are available on the metrics-port. If your config has no server.metrics-port, add it, the metrics are switched off without it.

Check the status of your nodes:

curl -s localhost:9093/metrics | grep nodecore_upstream_availability_status
nodecore_upstream_availability_status{chain="ethereum",upstream="ethnode1"} 1
nodecore_upstream_availability_status{chain="ethereum",upstream="ethnode2"} 1

Every node from your config must be in this list with the value 1:

ValueMeaning
1available
2immature, for example not enough peers
3syncing
4unavailable

If a node is not in the list at all, it hasn't passed the checks NodeCore runs before it starts using a node. Look for its id in the logs to find out why.

nodecore_upstream_head_lag shows how many blocks each node is behind the current head of its chain.

All metrics are described in Prometheus metrics (opens in a new tab).

Creating dRPC account#

Providers can use dRPC for free, as long as they use it to query their own infrastructure. The benefits include:

  1. A single interface for all your endpoints and keys
  2. Detailed statistics
  3. Automatic fallback mechanism

Also, we need to associate your account with a specific provider in our dRPC configuration. For now, this is done manually. The association is based on your Team ID.

Register on drpc.org

  1. Go to https://drpc.org (opens in a new tab)
  2. Select your preferred authorization method (MetaMask, email, etc)
  3. Go to Settings -> Team
  4. Copy your Team ID and send it to the dRPC team

NodeCore Upgrade#

We release new versions of NodeCore quite often, improving stability and performance while adding support for new networks. Providers should stay up to date and install new versions as soon as possible, as using outdated versions may impact your earnings on our platform.

To upgrade, pull the new image and recreate the container: docker compose pull && docker compose up -d.

You can track updates on GitHub Releases - https://github.com/drpcorg/nodecore/releases (opens in a new tab)

You can subscribe to new releases on GitHub through various options, such as GitHub Notifications (Watching) or external services like https://newreleases.io (opens in a new tab)