Deployment

This section describes the installation and deployment of the bloXroute Gateway software.

Installation

Users may install the bloXroute Gateway using pip or run a Docker container including the bloXroute Gateway. Running the bloXroute Gateway using a Docker container is the recommended approach. It is recommended that you install the Gateway on a separate server from your full node with low latency to your full node.

To install the bloXroute Gateway using Pip, please visit our PyPI page.

To install the bloXroute Gateway using a Docker container, please visit our Dockerhub page.

Running the Gateway

The gateway accepts various parameters as described in the Gateway Parameters section below. The parameters may be passed to provide the IP address and port of the full node, etc. Three parameters are required to correctly run the Gateway and software and are shown in the table below.

Required Gateway Parameters

Parameter Description Example
blockchain-protocol Blockchain protocol gateway is connecting to. Ethereum
blockchain-network Blockchain network gateway is connecting to (Mainnet or Testnet). This test is only on the Mainnet. Mainnet
node-public-key (Ethereum only) Node ID of your ethereum node. You can retrieve your node ID using the ethereum rpc command admin.nodeInfo. N/A

Docker

Run the Docker as a daemon. The gateway accepts various command line arguments as described in the Command Line Arguments section of this document. Arguments should be passed in the run command to provide the IP address and port of the full node.

For example, to run on the Ethereum network:

docker run -d --name gateway -p 9001:9001 bloxroute/bxgateway:latest --blockchain-protocol Ethereum --blockchain-network Mainnet --blockchain-ip 172.17.0.1 --blockchain-port 30303 --node-public-key="<YOUR NODE ID>"

Pip

When running from a pip install, launching the Gateway is as simple as running

bloxroute_gateway --blockchain-protocol <protocol> --blockchain-network <network>

For example, on the Bitcoin network:

bloxroute_gateway --blockchain-protocol Bitcoin --blockchain-network Mainnet

And, on the Ethereum network:

bloxroute_gateway --blockchain-protocol Ethereum --blockchain-network Mainnet --node-public-key="<YOUR NODE ID>"

You may determine your node ID using the Ethereum Javascript console command admin.nodeInfo. The hexadecimal node ID is encoded in the username portion of the enode URL, separated from the host by an @ sign (For more, see https://github.com/ethereum/wiki/wiki/enode-url-format).

Command Line Arguments

Required Gateway Parameters

The following parameters are required for Gateway operation. Each argument is prefixed with two dashes. Parameters are indicated by chevrons, e.g., "< parameter >", and defaults are noted, when available.

--blockchain-protocol <protocol>
Blockchain protocol that the Gateway is connected to, for example, Bitcoin, Ethereum.
--blockchain-network <network>
Blockchain network of the Blockchain node the Gateway will connect to. Valid networks are Mainnet and Testnet. For Ethereum, Testnet refers to Ropsten.
--node-public-key <node public key>
(Ethereum only.) Node ID of your ethereum node. You can retrieve your node ID using the ethereum rpc command admin.nodeInfo.

Optional Gateway Parameters

Below is a list of optional command line arguments accepted by the bloXroute Gateway. Each argument is prefixed with two dashes. Parameters are indicated by chevrons, e.g., "< parameter >", and defaults are noted, when available.

--blockchain-ip <IP>
The Blockchain node IP of the Gateway. Default is 127.0.0.1.
--blockchain-port <port>
The Blockchain node port of the Gateway. The default is determined based on the “blockchain-protocol” and “blockchain-network” provided. For example, the default for Ethereum is 30303.
--blockchain-protocol <protocol>
Blockchain protocol that the Gateway is connected to, for example, Bitcoin, Ethereum.
--blockchain-network <network>
Blockchain network of the Blockchain node the Gateway will connect to. Valid networks are Mainnet and Testnet. For Ethereum, Testnet refers to Ropsten.
--external-ip <IP address>
External IP is the external network IP of the Gateway on which the gateway can receive external connections from other gateways in the network. Please specify your IP address using external-ip if the gateway cannot access the url "http://checkip.dyndns.org/" to automatically detect its IP address.
--external-port <port>
External port is the port on which the gateway can receive external connections from other gateways in the network. The default is 9001.
--continent <continent>
The continent of your Ethereum full node. Valid continent values are NA (North America), SA (South and Central America), EU (Europe), OC (Oceania), AS (Asia), AF (Africa), AN (Antarctica).
--country <country>
The country of the Gateway.
--hostname <hostname>
Hostname the Gateway is running on.
--log-path <path>
Path location of the directory to store log files in.
--to-stdout
Sends gateway logs to stdout. When this flag is used, log files are not generated.
--log-level <log level>
Set log level of the Gateway. Refer to Logging section below for possible values.
--sdn-url <Control Plane IP or DNS>
IP or dns of the bloxroute Control Plane to connect to. Each bloXroute BDN has a separate Control Plane, and the specification of the Control Plane specifies the bloXroute BDN to connect to. Possible values for "Control Plane IP or DNS" include blxrbdn.com (the default), or testnet.blxrbdn.com.
--transaction-pool-memory-limit <Maximum size>
Maximum size of transactions to keep in memory pool (MB).
--use-extensions <True or False>
If true than the node will use the compiled extension module for some tasks like block compression.
--thread-pool-parallelism-degree <number of threads>
The number of threads to use when running task on a concurrent thread pool when the extension module is active. The default is determined as the number of CPUs minus 1.
--tx-mem-pool-bucket-size <bucket size>
The size of each bucket of the transaction mem pool. In order to efficiently iterate the mem pool concurrently, it is being split into buckets.
--peer-gateways <Gateway 1> <Gateway 2> …
Optional gateway peer ip/ports that will always be connected to. Should be in the format ip1:port1,ip2:port2,...
--min-peer-gateways <number of gateways>
Minimum number of peer gateways before node will contact SDN for more. Default is 1.

Bitcoin-specific Arguments

--blockchain-version <version>
Blockchain protocol version
--blockchain-nonce <nonce>
Blockchain nonce

Ethereum Specific Arguments

--node-public-key <node public key>
Node ID of your ethereum node. You can retrieve your node ID using the ethereum rpc command admin.nodeInfo.
--private-key <private key>
Private key for encrypted communication with Ethereum node. This argument is optional, and the Gateway will generate a random private key if one is not provided.
--network-id <network id>
Ethereum network id. This argument is optional and the Control Plane will provide a default based on the network provided.
--genesis-hash <hash>
Genesis block hash of Ethereum network. Optional, a default is provided.
--chain-difficulty <difficulty>
Difficulty of genesis block Ethereum network (in hex). Optional, a default is provided.

Upgrading

The following sections describe how to upgrade the bloXroute Gateway depending on the method used to install the Gateway. If your Gateway was installed as a Docker container, consult the Docker section below, otherwise, please consult the Pip section for Gateways installed using pip.

Docker

Upgrading via Docker is as simple as pulling the latest gateway.

First stop and remove the existing gateway:

docker stop <gateway container>  
docker rm <gateway container>

Next, pull the Gateway Docker image from Docker Hub:

docker pull bloxroute/bxgateway:latest

Finally, launch the Gateway in the same manner as before, for example:

docker run -d --name gateway -p 9001:9001 bloxroute/bxgateway:latest --blockchain-protocol Ethereum --blockchain-network Mainnet --blockchain-ip 172.17.0.1 --blockchain-port 30303 --node-public-key="<YOUR NODE ID>"

Pip

Upgrading via pip is straightforward:

pip install --upgrade bloxroute-gateway

The Gateway software may then be run as before.

Logging

The bloXroute Gateway logs information about it operations such as transactions and blocks that it sends and receives. Users may modify the amount of information sent to the logs by updating the Gateway’s log level using the --log-level command line argument. The Gateway log levels are listed below in order from most verbose (DEBUG) to least verbose (OFF).

DEBUG
TRACE
INFO
WARN
ERROR
FATAL
STATS
OFF

Gateway log items are JSON formatted. An example of a log item is shown below. As shown, each log item specifies its log level, timestamp, the Gateway instance reporting the log item and message including the content of the log item.

{"level": "STATS", "timestamp": "2019-08-16T22:35:27.384763", "instance": "6f6ad658-8712-4135-b76f-519118708a1a", "msg": {"data": {"event_name": "TxReceivedFromBlockchainNode", "event_logic": "0", "event_subject_id": "18be87ccabcad13901c210a1f9713889b9269f63383439ab13f0016c78edf201", "node_id": "6f6ad658-8712-4135-b76f-519118708a1a", "start_date_time": "2019-08-16T22:35:27.384755", "end_date_time": "2019-08-16T22:35:27.384755", "extra_data": {"network_num": 5, "peer": "172.17.0.1 30303"}}, "type": "TransactionInfo"}}

Gateway log items include statistics on the operation of the Gateway. Gateways do not currently send this information to bloXroute, but bloXroute does collect this information for Gateways that it runs to monitor the performance of the BDN, detect issues with the BDN, and to find areas of future improvement.