Router EVM Gateway contracts

Router EVM Gateway contract will bridge EVM chains with the Router Chain. We can deploy this gateway contract on any EVM compatible chain.

Overview

The EVM gateway contract implements three funcitonlity.

1. Send request to the Router chain
2. Handle request from the Router chain
3. Update Validator set on the gateway contact.

Please use the following instruction to setup, test and deploy the project

Send Request to the Router Chain

To send request to router chain the user contract need to call the following function and needs to provide the bridge contract address & payload bytes

# Gateway contract address variable
Gateway public gatewayContract;

# User/ Application contract constructor
constructor(address gatewayAddress) {
    gatewayContract = Gateway(gatewayAddress);
}

# example of send request to the Router chain
function sendRequestToRouter(bytes memory payload, string memory routerBridgeContract) public payable {
    # implement the business logic
    gatewayContract.requestToRouter(payload, routerBridgeContract);
}

Handle Request from the Router

To handle request coming from the router chain, the user contract needs to implement the following function in their contract

function handleRequestFromRouter(string memory sender, bytes memory payload) external {
    # implement the business logic
}

In case of state update from the requestFromRouter function we are emitting the following event

# This is OutBound Request Acknowledgement event
event EventOutboundAck(
    string relayerRouterAddress,
    string outboundTxRequestedBy,
    string chainId,
    uint64 chainType,
    uint64 eventNonce,
    uint64 outboundTxNonce,
    bytes contractAckResponses,
    uint8 exeCode,
    bool status
);

Currently we are emitting this outbound acknowlegdement event in two cases only. The ChainType, ChainId, and OutboundTxNonce will have same values in all cases.

• When the txn is valid but It is getting executed past the timeout. In this scenario, we will update the nonce mapping to 1 as executed and event will have the following values

  emit EventOutboundAck(
      relayerRouterAddress,
      routerBridgeAddress,
      chainId,
      chainType,
      eventNonce,
      outboundTxNonce,
      "",
      1,
      false
  );
  

• When the txn is valid and executed its handler calls to user contract In this scenario, we will update the nonce mapping to 1 as executed and event will have the following values

  emit EventOutboundAck(
      relayerRouterAddress,
      routerBridgeAddress,
      chainId,
      chainType,
      eventNonce,
      outboundTxNonce,
      data,
      0,
      success
  );

  Here, data and success values are coming from the handlerExecuteCalls funciton. Data bytes can be decoded according to the success value. If it is true, then it will be array of bool values and if it is false, then it will string value.

Update Validator Set

This is used to update validator set on the gateway contract. This will be called by the router chain validator set only.

Setup

To run any command you need to have .env in your local

cd router-gateway-contracts/evm
cp .env.test .env

then update the value in .env file.

Compile Project

cd router-gateway-contracts/evm
npm install
npx hardhat compile

Run Tests

Use the following commands to run the test cases:

npx hardhat help
npx hardhat test
GAS_REPORT=true npx hardhat test

Deploy Gateway Contract on live network

Add gateway contract constructor arguments in args.json

cd router-gateway-contracts/evm
npx hardhat deploy:Gateway --network <network> --chaintype <chainType> --valsetnonce <valsetNonce> --validators <validators> --powers <powers>

Upgrade Gateway Contract on live network

cd router-gateway-contracts/evm
npx hardhat upgrade:Gateway --network <network>

Verify GateWay Contract on a network

cd router-gateway-contracts/evm
npx hardhat verify --constructor-args <args-file-path> <gateway-contract-address> --network <network-name>

Example:-

npx hardhat verify --constructor-args scripts/arguments.js 0x610aEe9387488398c25Aca6aDFBac662177DB24D --network polygonMumbai

Generate ABIs, BIN and GO bindings of the Gateway Contract

cd router-gateway-contracts
npm install
sh scripts/createBinding.sh