github.com/supragya/TendermintConnector@v0.0.0-20210619045051-113e32b84fb1/README.md (about)

     1  <p align="center">
     2    <img src="banner.png?raw=true" alt="Tendermint Connector Banner"/>
     3  </p>
     4  
     5  # Tendermint Connector
     6  Tendermint Connector is a bridging application required for Tendermint based blockchains to interface with Marlin Protocol. Tendermint Connector connects as a peer to already running TM based blockchain and retrieves / pushes selective messages that the peer needs from / to Marlin Relays. Tendermint Connector also doubles up as a spam checker machanism for marlin relay.
     7  
     8  ## Serviced Blockchains
     9  Currently, the following blockchains are serviced by **TendermintConnector**:
    10  1. Irisnet Mainnet 0.16.3
    11  2. Cosmos-3 Mainnet
    12  
    13  ## Building the application
    14  Ensure that go is installed on the build system - ensure all is good using `go version`. This should return good version string. Proceed to build the application using:
    15  ```
    16  make
    17  make install
    18  ```
    19  
    20  ## Tendermint Connector concepts
    21  Tendermint Connector is an application that provides full support for tendermint to interplay with Marlin Relay Network. Consequently, there are many roles that Tendermint Connector needs to play with a few variations in all of them. Here are a few concepts that is essential in understanding of Tendermint Connector
    22  
    23  ### Organisation
    24  Tendermint Connector is organised in primarily two separate modules - **Marlin Side Connector** and **Peer Side Connector**. Marlin side connector is a module that is tasked with interactions pertaining to marlin relay network - interactions with bridge or relay abci are both handled by marlin side connector. Peer side connector is tasked with interactions pertaining to TMCore of different blockchains - These include recieving messages from Tendermint Core, validating, asking Marlin Side Connector to put messages onto relay, deliver messages recieved from relay to TMCore and also, check for spam messages if there are any.
    25  
    26  Consequently the connector can be thought of as follows:
    27  <p align="center">
    28    <img src="tm_connector_diagram.png?raw=true" alt="Tendermint Connector diagram"/>
    29  </p>
    30  
    31  ### Running modes
    32  Tendermint Connector runs in two different modes:
    33  1. **DataConnect mode**: Tendermint Connector acts as a connecting bridge between a real tendermint based blockchain application (Connector talks to real TMCore) and Marlin TCP bridge. Most users would like to use this mode. In this mode, connector connects as a peer to real TMCore is capable of both sending messages to marlin side connector and recieving from it while interacting with TMCore.
    34  
    35  2. **SpamFilter mode**: Tendermint Connector acts as a spamfilter servicing application at marlin relay nodes and interacts with `tm_abci`. Relay operators would like to use this mode.
    36  
    37  ### marlinTo and marlinFrom
    38  **marlinTo** and **marlinFrom** are two channels which act as a connecting buffer between the marlin side connector and peer side connector. Both of these are capable of holding upto 1000 messages in each direction and are supposed to make both sides (marlin side / peer side) be agnostic of wire protocols each of them use. In case of overflow, oldest messages are dropped and shown as warning by TendermintConnector.
    39  
    40  ### Selecting a Peer Side Connector
    41  Tendermint Connector aims to provide support for many tendermint based blockchains. Consequently, there needs to be quite similar however different peer side connectors that are engineered to support a specific blockchain. 
    42  
    43  Decision of which peer side connector to use is done during runtime and is based on the nodeInfo that TMCore provides. Based on Block version and chain id of node, Tendermint Connector chooses a peer side connector that best fits to service that particular blockchain.
    44  
    45  Currently, there is only one peer side connector written and supported:
    46  1. Irisnet Mainnet 0.16.3
    47  2. Cosmos-3 Mainnet
    48  
    49  ### Peer side connector TCP connections
    50  TMCore peers communicate with each other on TCP connections. Hence, if communication is to be established with real TMCore, one must dial the real TMCore or "be dialed" by the other side. Tendermint Core can do both - dial a real TMCore or be dialed. 
    51  
    52  Dialing a TMCore is simpler - Tendermint Connector generates keypair on the fly before connecting to TMCore - allowing Tendermint Connector to have different IDs between connections. This is ideal - since it circumvents issues when TMCore blacklists an ID (of Tendermint Connector) as a bad actor - since tendermint connector connects with a new identity.
    53  
    54  Being dialed however is a little tricky - Tendermint Connector needs to listen on a specific port with certain nodeID. In this case when Tendermint Connector is dialed, the Connector needs to have consistent ID across multiple connections and cannot use new generated IDs on the fly. This ID can be persisted on the disk to be used across connections and across process runs by saving it as a **keyfile** (Keyfiles save private key / public key pairs). An example keyfile is given in `keyfiles` directory here.
    55  
    56  There are certain time when being dialed is preferred way - by adding the Tendermint Connector fake peer as **persistent_peer** or **unconditional_peer** of real TMCore (More on how to do this below).
    57  
    58  ### Marlin side connector
    59  Tendermint Connector's marlin side connectivity is not always TCP. While in "dataconnect" mode, the marlin side connector interacts with Marlin Bridge. However, while in "spamfilter" mode, the marlin side connector relies on unix sockets to service spamfilter responses. Marlin side connector handles both in separate modes.
    60  
    61  
    62  ## Running the application
    63  The TendermintConnector application provides the following features:
    64  1. Full CLI interface (POSIX style flags)
    65  2. Automatic Blockchain detection based on Node Info of peer (RPC access to real TMCore required)
    66  3. Secured On the fly ED25519 key pair generation and handshake for every session in peerdial
    67  
    68  For finding version info of the application, supported chains and supported encodings for marlin relay, run:
    69  ```
    70  TendermintConnector --version
    71  ```
    72  
    73  This should return you information such as this:
    74  ```
    75  TendermintConnector version 0.1-rc-1
    76  + [Tendermint Chain]   IRISNet Mainnet 0.16.3 (Consensus State transfers) v0.1
    77  + [Marlin TM Protocol] Marlin Tendermint Data Transfer Protocol v1
    78  ```
    79  
    80  ### TendermintConnector as a dataconnector between TMCore and Marlin Relay
    81  ```
    82  TendermintConnector dataconnect --dial
    83  ```
    84  Tendermint connector will automatically try to connect using the default parameters.
    85  
    86  You can learn more about the *TendermintConnector connect* command using `TendermintConnector connect -h`.
    87  
    88  For configuring any of this for runtime, the following can be used for changed params:
    89  ```
    90  TendermintConnector --server_address 127.0.0.2 --rpc_port 21222
    91  ```
    92  
    93  ### TendermintConnector keyfiles for persistent peer connection between TMCore and TendermintConnector
    94  ```
    95  TendermintConnector keyfile
    96  ```
    97  Tendermint connector can act as a tendermint peer who listens for connections instead of dialing TMCore itself. For this, you may need a persistent node ID to put in `config.toml` file for your real tendermint node. This is of format: *ae239af43..9bd7@127.0.0.1:266657*. This is essentially **nodeID@IP:PORT**. A keyfile for TendermintConnector is a file which describes the nodeID for TendermintConnector to use across process runs; it provides TendermintConnector with keys for fulfilling it's job as the given nodeID.
    98  
    99  For example, you can generate a keyfile for irisnet chain using the following command:
   100  ```
   101  TendermintConnector keyfile --chain irisnet --filelocation irisnetkeys.json --generate
   102  ```
   103  
   104  This would return logs similar to below:
   105  ```
   106  [INFO]:2020-11-13 15:32:51 - Generating KeyPair for irisnet-0.16.3-mainnet
   107  [INFO]:2020-11-13 15:32:51 - ID for node after generating KeyPair: 376378adce3c6e3fde8201a4926b4adae6cb72e0
   108  [INFO]:2020-11-13 15:32:51 - Successfully written keyfile irisnetkeys.json
   109  ```
   110  
   111  This would create a new file `irisnetkeys.json` which contains keys relevant to peer nodeID `376378adce3c6e3fde8201a4926b4adae6cb72e0`. You can now put `376378adce3c6e3fde8201a4926b4adae6cb72e0@127.0.0.1:59001` (for localhost) as a persistent peer of your real tendermint node by editing your *config.toml* or passing peer as a command line argument.
   112  
   113  Subsequent runs of `TendermintConnector connect` would require this keyfile to be provided to the program using command such as follows:
   114  ```
   115  TendermintConnector connect --keyfile irisnetkeys.json
   116  ```
   117  
   118  You may wish to verify the integrity of generated keyfiles. This can be done by simply (no `--generate` flag):
   119  ```
   120  TendermintConnector keyfile --keyfile irisnetkeys.json --chain irisnet
   121  ```
   122  
   123  ### TendermintConnector as a spamfilter for Marlin Relay
   124  ```
   125  TendermintConnector spamfilter
   126  ```
   127  Tendermint connector will run as a spam filter endpoint for verifying messages recieved at any relay endpoint. The expected format of message in spamfilter mode is proto3 encoded Marlin Tendermint Data Transfer Protocol messages. Spamfilter replies with a single byte (0 or 1) for whether message is spam (0), hence to be blocked or not (1), hence to be allowed.
   128  
   129  You can learn more about the *TendermintConnector spamfilter* command using `TendermintConnector spamfilter -h`.
   130  
   131  For configuring any of this for runtime, the following can be used for changed params:
   132  ```
   133  TendermintConnector spamfilter --peerip 127.0.0.2 --rpcport 26667
   134  ```