Gateway

Gateways enable people to connect their blockchain nodes to the Marlin network to send and receive messages.

Polkadot

Documentation for the polkadot gateway is available here.

Near

Usage (using marlinctl)

$ sudo marlinctl gateway near create --help
NAME:
   marlinctl gateway near create - create a new gateway

USAGE:
   marlinctl gateway near create [command options] [arguments...]

OPTIONS:
   --bootstrap-addr value  --bootstrap-addr "<IP:PORT>" (default: "127.0.0.1:8002")
   --version value         --version <NUMBER> (default: "latest")
   --help, -h              show help (default: false)

Run

$ sudo marlinctl gateway near create --bootstrap-addr "54.219.22.51:8002"

Connect

You need to connect your blockchain node to the gateway to send and receive data from it.

Step 1: Get the gateway identity

$ sudo supervisorctl tail near_gateway
...
[2020-12-06 16:20:45.648] [info] [OnRampNear.hpp:63] Node identity: Ar5vnFLiYeX8jHTNCKBJuTND1ez85fHZN5Q4ikanFtU
...

The above command prints logs which contain the identity key of the gateway. This step only needs to performed once since the key is stored locally for future runs.

For advanced users, the key is stored as a file (.marlin/keys/near_gateway). You can supply your own pre-generated key files to make the above step deterministic (useful for automation scripts).

Step 2: Add as a peer

The gateway now needs to be added as a peer. There are a variety of ways to do this, here's an example using the commandline while starting the near node:

# Use the key obtained above
$ ./target/release/neard run --boot-nodes "Ar5vnFLiYeX8jHTNCKBJuTND1ez85fHZN5Q4ikanFtU@<gateway_ip>:21400"

That's it!

Irisnet

The irisnet gateway comprises of two programs:

  • Gateway
  • Bridge

Usage (using marlinctl)

$ sudo marlinctl gateway iris create --help
NAME:
   marlinctl gateway iris create - create a new gateway
USAGE:
   marlinctl gateway iris create [command options] [arguments...]
OPTIONS:
   --bootstrapaddr value   --bootstrapaddr "<IP1:PORT1>" (default: "127.0.0.1:8002")
   --listenportpeer value  --listenportpeer "PORT" (default: "59001")
   --peerip value          --peerip "IP" (default: "127.0.0.1")
   --peerport value        --peerport "PORT" (default: "26656")
   --rpcport value         --rpcport "PORT" (default: "26657")
   --version value         --version <NUMBER> (default: "latest")
   --help, -h              show help (default: false)

Run

sudo marlinctl gateway iris create --bootstrapaddr "52.8.52.100:8002"

The bridge is automatically setup for you.

Connect

You need to connect your blockchain node to the gateway to send and receive data from it.

Step 1: Get the gateway identity

$ ls ~/.marlin/ctl/configs/iris_keyfile*
/home/exampleuser/.marlin/ctl/configs/iris_keyfile-0.0.1.json
$ grep IdString /home/exampleuser/.marlin/ctl/configs/iris_keyfile-0.0.1.json
    "IdString": "f4d35da5490d9e5962b0b3041ccc2980b0dec5dd",

The above command prints the node ID of the gateway. This keyfile is initially pulled from remote to help get the system up and running as soon as possible for end user. However, you can also generate your own keyfile and save it at the same place (/home/exampleuser/.marlin/ctl/configs/iris_keyfile-0.0.1.json) for gateway to use for future runs.

New keys can be generated using the following:

$ cd ~/.marlin/ctl/bin/
$ ./iris_gateway-0.0.1 keyfile -g -f /home/exampleuser/.marlin/ctl/configs/iris_keyfile-0.0.1.json -c irisnet

This would respond with:

[INFO]:2020-12-05 11:29:10 - Generating KeyPair for irisnet-0.16.3-mainnet
[INFO]:2020-12-05 11:29:10 - ID for node after generating KeyPair: 6f5c8faeb8d14bb0c28e9dda22cc2d580e7af929
[INFO]:2020-12-05 11:29:10 - Successfully written keyfile /home/exampleuser/.marlin/ctl/configs/iris_keyfile-0.0.1.json

Hence, 6f5c8faeb8d14bb0c28e9dda22cc2d580e7af929 is the new nodeID. Verify the same using:

$ grep IdString /home/exampleuser/.marlin/ctl/configs/iris_keyfile-0.0.1.json

Step 2: Restart Irisnet node with gateway as persistent peer

Kill your iris instance running with iris start command. Then, open the config file for iris using:

$ vim ~/.iris/config/config.toml

Change persistent peer configuration from

# Comma separated list of nodes to keep persistent connections to
persistent_peers = ""

to:

# Comma separated list of nodes to keep persistent connections to
persistent_peers = "f4d35da5490d9e5962b0b3041ccc2980b0dec5dd@127.0.0.1:59001"

Make note: Here, correct node ID which your system has should be entered along with IP and Port in the format nodeID@ip:port. Failure to do so could lead to gateway not being able to connect.

Save the configuration file and exit using ESC -> :wq -> RETURN and begin iris using iris start

Step 3: Run the gateway

Run the gateway using run command given above.

Note: Run the gateway post running the iris node only, since the gateway needs to do RPC calls to the iris node to find the chain and verify compatibility before running.

That's it!

Fantom

The gateway for Fantom is undergoing testing. Please feel free to register at https://form.typeform.com/to/mx9BbUM0. You will receive a notification once the gateway is ready. Your delegators will be made eligible for FlowMint immediately for a grace period till the gateway is not ready and installed.

Matic

The gateway for Matic is undergoing testing. Please feel free to register at https://form.typeform.com/to/mx9BbUM0. You will receive a notification once the gateway is ready. Your delegators will be made eligible for FlowMint immediately for a grace period till the gateway is not ready and installed.

Discussion

What exactly is a gateway?

Gateways are basically a stripped down version of the blockchain node (called a shadow node) which implement only the p2p networking parts. Most notably, there's no discovery, sync, storage or consensus, so the gateway is extremely lean.

On one side, since the gateway implements the p2p networking stack, you can add the gateway as a peer to your blockchain node and it will automatically communicate with it (no invasive code changes). On the other side, it automatically discovers and maintains connections with Marlin relay nodes and is able to send and receive data from it.

Why is a bridge sometimes needed?

The two sides of the gateway are occasionally incompatible with each other. This might be due to a variety of reasons including different event loops, incompatible languages/libraries, etc. Hence, the two sides are split into two parts which communicate between each other through the network instead.

Does it affect the safety/stability of my node?

Not more than connecting to any other peer. The shadow node approach is designed to affect the real blockchain node as little as possible:

  • there are no codebase changes
  • the blockchain node still verifies all messages and runs its consensus engine as always
  • communication is strictly through its own p2p networking stack
  • the blockchain node doesn't interact with the Marlin network directly (in fact, it doesn't even know that Marlin exists)
  • the gateway can be run in a different VM separate from the node to further isolate it

Hence, the "attack surface" is pretty much the same as another peer that your node connects to.

My node doesn't connect to other (random) peers though.

The blockchain node still needs to get the data from some other node in your control. E.g. some chains secure their validator nodes by running them behind sentry nodes which insulate the validator against rogue peers. You can simply choose to run the gateway beside the sentry node instead of the validator.