Cosmos gateway

Overview

The cosmos gateway acts as a bridge between your cosmos node and the Marlin relay network, enabling them to understand and talk to each other. In addition, it handles most of the Marlin related interactions for you like optimizing peer sets, attesting messages, generating tickets, etc.

Quickstart

This section assumes that marlinctl is installed already. See here if you have not installed it.

Step 1: Generate a client identity for the gateway by running the below command and entering a passphrase when prompted

sudo marlinctl gateway cosmos keystore create

Step 2: Create the gateway

sudo marlinctl gateway cosmos create --bootstrap-addr "18.144.140.68:8002"

Step 3: Retrieve the cosmos node identity of the gateway by checking keyfile configuration (the alphanumeric NodeID would most likely be different for you).

INFO Keyfile information
 Key     Value                                    
 NodeId  cd276853b1c116f5bf8900b72694fb022800d276 

Step 4: Add the gateway as a persistent peer to your cosmos node by adding  NodeID@SYSTEM-IP:21900  (example cd276853b1c116f5bf8900b72694fb022800d276@127.0.0.1:21900 ) in file ~/.gaia/config/config.toml and restarting the cosmos node.

That's it!

 

Architecture

 

The cosmos gateway is comprised of two components

Manage using marlinctl

This page assumes that marlinctl is installed already. See here if you have not installed it.

Command tree

The marlinctl command subtree for managing Cosmos gateways resides under marlinctl gateway cosmos. As with all marlinctl commands, the subtree can be incrementally discovered with the --help parameter.

$ sudo marlinctl gateway cosmos --help

Cosmos Gateway

Usage:
  marlinctl gateway cosmos [command]

Available Commands:
  config      Configurations of project set on disk
  create      Create gateway for cosmos blockchain
  destroy     Destroy gateway for cosmos blockchain
  keystore    Create or Destroy keystore
  logs        Tail logs for running gateway (cosmos) instances
  recreate    Recreate end to end gateway (cosmos) instances
  restart     Restart services for gateway (cosmos) instances
  status      Show status of currently running gateway (cosmos) instances
  versions    Show available versions for use

Flags:
  -h, --help   help for cosmos

Global Flags:
      --config string       config file (default is $HOME/.marlin/ctl/state.yaml)
      --loglevel string     marlinctl loglevel (default is INFO) (default "info")
      --registry-sync       forceful registry sync from remote. May be used to check for upgrades.
      --skip-sync           skip registry sync during run
      --skip-update-check   skip update check during run

Use "marlinctl gateway cosmos [command] --help" for more information about a command.

 

Create a gateway

Gateways can be created using the create command.

$ sudo marlinctl gateway cosmos create --help

Create gateway for cosmos blockchain

Usage:
  marlinctl gateway cosmos create [flags]

Flags:
  -b, --bootstrap-addr string            Bridge bootstrap address
  -c, --contracts string                 mainnet/kovan (default "mainnet")
  -d, --discovery-addr string            Bridge discovery address (default "0.0.0.0:22002")
  -h, --help                             help for create
  -i, --instance-id string               instance-id of spawned up resource (default "001")
  -l, --internal-listen-address string   Bridge listen address (default "127.0.0.1:22401")
  -y, --keystore-pass-path string        Keystore pass path (default "")
  -k, --keystore-path string             Keystore Path (default "")
  -p, --pubsub-addr string               Bridge pubsub address (default "0.0.0.0:22000")
  -r, --runtime-args stringToString      runtime arguments while starting up (default [])
  -s, --skip-checksum                    skip checksum verification while starting up binaries
  -x, --version string                   runtime version override

Global Flags:
      --config string       config file (default is $HOME/.marlin/ctl/state.yaml)
      --loglevel string     marlinctl loglevel (default is INFO) (default "info")
      --registry-sync       forceful registry sync from remote. May be used to check for upgrades.
      --skip-sync           skip registry sync during run
      --skip-update-check   skip update check during run
Primary flags

While the following flags are optional for testing the connection between the gateway and the polkadot node, they are required parameters for interacting with the Marlin network.

Secondary flags

The following flags are useful for customizing the socket addresses used by the gateway in order to prevent any conflicts with other programs on the same system.

 

See logs

Logs can be tailed using the logs command.

$ sudo marlinctl gateway cosmos logs --help

Tail logs for running gateway (cosmos) instances

Usage:
  marlinctl gateway cosmos logs [flags]

Flags:
  -h, --help                 help for logs
  -i, --instance-id string   instance-id of resource to log (default "001")
  -n, --last int             number of last lines to tail in logfile (default 100)

Global Flags:
      --config string       config file (default is $HOME/.marlin/ctl/state.yaml)
      --loglevel string     marlinctl loglevel (default is INFO) (default "info")
      --registry-sync       forceful registry sync from remote. May be used to check for upgrades.
      --skip-sync           skip registry sync during run
      --skip-update-check   skip update check during run
Primary flags

 

Destroy a gateway

Gateways can be destroyed using the destroy command.

$ sudo marlinctl gateway cosmos destroy --help

Destroy gateway for cosmos blockchain

Usage:
  marlinctl gateway cosmos destroy [flags]

Flags:
  -h, --help                 help for destroy
  -i, --instance-id string   instance-id of resource to destroy (default "001")

Global Flags:
      --config string            config file (default is $HOME/.marlin/ctl/state.yaml)
      --forceful-registry-sync   forceful registry sync. Do not use if you don't know what this is for.
      --loglevel string          marlinctl loglevel (default is INFO) (default "info")
      --skip-registry-sync       skip registry sync during run
      --skip-update-check        skip update check during run

Manage manually

Prebuilt binaries

Prebuilt binaries for the components are available here. Please use latest available binaries >3.0.0.

Running the bridge

The bridge parameters can be discovered with the --help flag.

$ ./bridge_cosmos-linux-amd64 --help

USAGE: bridge [OPTIONS] 

OPTIONS:
    -d, --discovery-addr <discovery_addr>
    -p, --pubsub-addr <pubsub_addr>
    -b, --beacon-addr <beacon_addr>
    -l, --listen-addr <listen_addr>
    -k, --keystore-path <keystore_path>
    -k, --keystore-pass_path <keystore_pass_path>
    -c, --contracts <contracts>
    -h, --help <help>
    -v, --version <version>

 

Primary flags

While the following flags are optional for testing the connection between the gateway and the bridge, they are required parameters for interacting with the Marlin network.

Secondary flags

The following flags are useful for customizing the socket addresses used by the bridge in order to prevent any conflicts with other programs on the same system.

 

Running the gateway

The gateway parameters can be discovered with the --help parameters. It is advised that operators read up on https://github.com/supragya/TendermintConnector as well as below.

$ ./cosmos_gateway-linux_amd64 dataconnect -h
Act as a connector between Marlin Relay and cosmos

Usage:
  TendermintConnector dataconnect [flags]

Flags:
  -d, --dial                 Connector DIALs TMCore (gaia node) if flag is set, otherwise connector LISTENs for connections.
  -e, --direction string     Direction of connection [both/producer/consumer] (default "both")
  -h, --help                 help for dataconnect
  -k, --keyfile string       KeyFile to use for connection
  -l, --listenportpeer int   Port on which Connector should listen for incoming connections from cosmos peer (default 22400)
  -m, --marlinip string      Marlin TCP Bridge IP address (default "127.0.0.1")
  -n, --marlinport int       Marlin TCP Bridge port (default 22401)
  -i, --peerip string        Gaia node IP address (default "127.0.0.1")
  -p, --peerport int         Gaia node peer connection port (default 26656)
  -r, --rpcport int          Gaia node rpc port (default 26657)
  -s, --rpcsanity            Validate node information prior to connecting to TMCore. (RPC Sanity)

In dial mode (gateway dials TMCore), keyfile is not required however in listen more (gateway listens for incoming connections from TMCore), a keyfile is required. Create one using:

./cosmos_gateway-linux_amd64 keyfile --chain cosmos --filelocation cosmos_keyfile_ed25519.keyfile --generate

Node ID for gateway will be shown in a log line as follows:

[INFO]:2021-04-26 18:13:16 - ID for node after generating KeyPair: 6bf915b371f741f5b0aabdf84a033150a728e1ec

This can later be used in dataconnect as follows:

./cosmos_gateway-linux_amd64 dataconnect --direction producer --keyfile cosmos_keyfile_ed25519.keyfile