fast-bridge-protocol

RB Fast bridge is one-way decentralized trustless bridge created to speed up transfers from Near to Ethereum.

How it works

1. User initiate unique transfer {nonce, amount, {fee_token, fee_amount}, recipient, valid_till} that is valid for some reasonably small period of time. That locks amount and fee_amount on NearErc20FastBridge contract
2. NearErc20FastBridge contract generates FastBridgeTransferEvent with the following metadata {nonce, valid_till, transfer: {token_near, token_eth, amount}, fee: {token, amount}, recipient}
3. LP-relayer receives an event and makes a decision to process or not the transfer
4. LP-Relayer transfers amount to recipient on Ethereum side via EthErc20FastBridge on Ethereum side
5. Light-client Relayer submits the block to EthOnNearClient contract and after the needed amount of confirmations is done, the LP-relayer is ready to receive the amount and fee for the fast bridge transfer.
6. LP-relayer provides proof for the NearErc20FastBridge that exact transfer was done on Ethereum via EthErc20FastBridge and receives the amount and fee for the transfer.

Build

The bridge consist of three main components:

• Bridge node
• Near contracts
• Ethereum contracts

Ethereum

Described in the corresponding README

Near

Described in the corresponding README

EthErc20Bridge scripts

Below given command will help user to deploy and interact with contracts on the network provided as arg to below command, if no arg is provided it will use default network from hardhat-config.

First set up your .env file in spectere-bridge-protocol/.env, for help .env.example is provided in spectere-bridge-protocol directory.

1. First copy content of .env.example file
2. Create a new file in spectere-bridge-protocol directory and name it .env
3. Paste copied content in .env file
4. Fill up details as required as per used in hardhat.config.json file.

Then, to run below scripts go to spectere-bridge-protocol/eth directory, i.e. run command cd eth

example : to deploy EthErc20FastBridge on network (network-name must be defined in hardhat-config.json's networks) npm run deploy:bridge -- <network-name>

Deployment script

Running ths script will deploy bridge proxy and store proxy and implementation address in spectre-bridge-protocol/eth/scripts/deployment/deploymentAddresses.json To execute this script => run command yarn run deploy:bridge -- <network-name> example : to deploy bridge on goerli run command yarn run deploy:bridge -- goerli

Deploy and verify

Running this script will first deploy and then verify bridge. To execute this script => run command yarn run deploy:verify:bridge -- <network-name> example : to deploy and verify bridge on goerli run command yarn run deploy:verify:bridge -- goerli

Upgrade script

To upgrade bridge contract(using hardhat's upgrades plugin), use spectre-bridge-protocol/eth/scripts/EthErc20FastBridge/upgrade_bridge.js script.

To execute this script => run command yarn run upgrade:bridge -- <network-name> example : to upgrade on goerli run command yarn run deploy:verify:bridge -- goerli

Whitelisting

To interact with EthErc20FastBridge whitelisting methods use methods defined in spectre-bridge-protocol/eth/scripts/EthErc20FastBridge/whitelistTokens.js

• To bulk update whitelist status of tokens import and use method bulkWhitelistStatusUpdate from above mentioned file with an array of token addresses, an array of their corresponding status and a signer with WHITELISTING_TOKENS_ADMIN_ROLE as parameters.

• To whitelist one token import and use method addTokenToWhitelist from above mentioned file with a token address and a signer with WHITELISTING_TOKENS_ADMIN_ROLE as parameters.

• To remove one token from whitelist use method removeTokenFromWhitelist from above mentioned file with tokens address and signer with WHITELISTING_TOKENS_ADMIN_ROLE as parameters.

• To check whether a token is whitelisted or not import and use method isTokenInWhitelist from above mentioned file with tokens address and signer with WHITELISTING_TOKENS_ADMIN_ROLE as parameters.

example : If you want whitelist whitelist one token, script would like,

const { ethers } = require("hardhat");
const { addTokenToWhitelist } = require("./whitelistTokens");

const WETH = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2";

async function main() {
    const [signer] = await ethers.getSigners(); // signer must have WHITELISTING_TOKENS_ADMIN_ROLE
    await addTokenToWhitelist(WETH, signer);
}

main().catch((error) => {
    console.error(error);
    process.exitCode = 1;
});

And to run above script run npx hardhat run <path_to_script/script.js> -- from eth folder.

Pause/Unpause transfers

To interact with EthErc20FastBridge pause and unpause methods use methods defined in spectre-bridge-protocol/eth/scripts/EthErc20FastBridge/pause_unPause.js

• To pause transfers import and use pauseTransfer method from above mentioned file with a signer with PAUSABLE_ADMIN_ROLE as parameter.

• To unpause transfers import and use unpauseTransfer method from above mentioned file with a signer with UNPAUSABLE_ADMIN_ROLE as parameter.

These methods can be used in similar to above example

To interact with above methods use script spectre-bridge-protocol/eth/scripts/EthErc20FastBridge/interact_with_bridge.js

Follow below steps to execute script and start interacting

1. First, create your .env file(mentioned in EthErc20Bridge scripts section's starting)
2. Go to spectre-bridge-protocol/eth directory in terminal
3. Run command npm run interact:bridge -- <network_name_as_defined_in_hardhat_config>
4. Follow guide in terminal Note: bridge address will be picked from deploymentAddress[network].new.bridge (from spectre-bridge-protocol/eth/scripts/deployment/deploymentAddresses.json)

To interact with FastBridge using hardhat task

To call any method of EthErc20FastBridge use hardhat task method Run command npx hardhat method --jsonstring <json_string_input>

to create `json_string_input`
1. create json with `signature` and `arguments` properties in below example format

 {
    "signature": "setWhitelistedTokens(address[],bool[])",
    "argcount": "2",
    "arguments": {
        "arg1": [
            "0xdAC17F958D2ee523a2206206994597C13D831ec7",
            "0xB8c77482e45F1F44dE1745F52C74426C631bDD52",
            "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
        ],
        "arg2": [
            true,
            true,
            true
        ]
    }
}

2. pass below json to JSON.stringify() and use output as `json_string_input`

example: to call setWhitelistedTokens method run command npx hardhat method --jsonstring '{"signature":"setWhitelistedTokens","arguments":{"arg1":["0xdAC17F958D2ee523a2206206994597C13D831ec7"],"arg2":[true]}}'