@rsksmart/rif-relay-contracts

RIF Relay Contracts

This project is part of the RIF Relay ecosystem. It contains all the smart contracts that the system uses.

Table of Contents

• Installation
  • Pre-requisites
  • Dependencies
• Smart Contracts
  • Deployment
  • Addresses
• System usage
  • Managing tokens
  • Managing destination contracts
  • UtilToken Minting
• Library usage
  • As a dependency
  • Development
    • Adding new files
    • Contract addresses
    • Husky and linters
    • Generating a new distributable version
      • For GitHub
      • For NPM
      • For direct use (no publishing)

Installation

Pre-requisites

• An RSKJ Node running locally
• Node version 12.18

Dependencies

Install all dependencies by running npm install.

The project is ready to be used at this point.

Smart Contracts

Deployment

The contracts can be deployed in the following way:

• Configure the hardhat.config.ts file on the root of the project to set your network
• Run npx hardhat deploy --network <NETWORK_NAME>; this is suggested for testing purposes only, since it deploys all the contracts. If you want to have more control please use the following flags:

• --relay-hub: to deploy the RelayHub and the related contracts;
• --default-smart-wallet: to deploy the default SmartWallet and the related contracts (tempate, factory, deploy verifier and relay verifier);
• --custom-smart-wallet: to deploy the CustomSmartWallet and the related contracts (tempate, factory, deploy verifier and relay verifier);
• --native-holder-smart-wallet: to deploy the NativeHolderSmartWallet and the related contracts (tempate, factory, deploy verifier and relay verifier);
• --boltz-smart-wallet: to deploy the BoltzSmartWallet and the related contracts (tempate, factory, deploy verifier and relay verifier);
• --minimal-boltz-smart-wallet: to deploy the MinimalBoltzSmartWallet and the related contracts (tempate, factory, deploy verifier and relay verifier);
• --util-token: to deploy an ERC20 Token UtilToken (for Testnet/Regtest only);
• --version-registry: : to deploy the VersionRegistry contract.

e.g.:

// to deploy RelayHub and SmartWallet
npx hardhat deploy --network regtest --relay-hub --default-smart-wallet

// to deploy RelayHub and SmartWallet and UtilToken
npx hardhat deploy --network regtest --relay-hub --default-smart-wallet --util-token

For further information, please check the help included in the command: npx hardhat deploy --help.

This will start the migration on <NETWORK_NAME>; at the end of it you should see a summary with all the contract addresses.

To use a specific account to deploy the contracts, we could either set the private key (PK) or the mnemonic (MNEMONIC) as env variables.

MNEMONIC='MNEMONIC WORDS HERE' npx hardhat deploy --network <NETWORK_NAME>
// or
PK='PRIVATE_KEY_HERE_WITHOUT_0X' npx hardhat deploy --network <NETWORK_NAME>

Collector Deployment

To deploy a collector, we need to the script collector:deploy. It receives the following parameters:

• config-file-name: optional, used to specify the collector owner and the partners configuration (addresses and shares). If not specified, the file deploy-collector.input.json will be used. Please have a look at deploy-collector.input.sample.json for a sample file.
• outputFile: optional, used to log the main information of the collector deployment. If not specified, the file revenue-sharing-addresses.json will be used.

Usage:

npx hardhat collector:deploy --network "<network>" --config-file-name "<input_config_file.json>" --output-file-name "output_config_file.json"

Example:

npx hardhat collector:deploy --network regtest --config-file-name "deploy-collector.input.json" --output-file-name "collector-output.json"

Change partner shares

Pre-requirements:

• the collector we want to change must be deployed. See the related section to deploy a collector;
• there must be no shares to be distributed among the partners otherwise the transaction will fail; please be sure that the current balance is less than or equal to the number of partners;
• only the owner can execute this transaction.

The collector:change-partners is a utility script that can be run to change the partner shares of a collector already deployed. It receives the following parameters:

• collector-address: mandatory, it's the address of the collector we want to change;
• partner-config: it includes the new partner shares we want to set;
• gas-limit: optional, it's the gas limit used for the transaction. If the transaction fails, we may probably need to specify an higher value; default value is 150000;

Usage:

npx hardhat collector:change-partners --collector-address "<collector_address>" --partner-config "<file_including_partners_config.json>" --gas-limit "<gas_limit>" --network regtest

Example:

npx hardhat collector:change-partners --collector-address "0x9b91c655AaE10E6cd0a941Aa90A6e7aa97FB02F4" --partner-config "partner-shares.json" --gas-limit "200000" --network regtest

Add collector token

Pre-requirements:

• the collector we want to change must be deployed. See the related section to deploy a collector.

Usage:

npx hardhat collector:addToken --collector-address "<collector_address>" --token-address "<token_address>" --network regtest

Example:

npx hardhat collector:addToken --collector-address "0xeFb80DB9E2d943A492Bd988f4c619495cA815643" --token-address "0xfD1dda8C3BC734Bc1C8e71F69F25BFBEe9cE9535" --network regtest

Get collector tokens

Pre-requirements:

• the collector we want to change must be deployed. See the related section to deploy a collector.

Usage:

npx hardhat collector:getTokens --collector-address "<collector_address>" --network regtest

Example:

npx hardhat collector:getTokens --collector-address "0xeFb80DB9E2d943A492Bd988f4c619495cA815643" --network regtest

Remove collector token

Pre-requirements:

• the collector we want to change must be deployed. See the related section to deploy a collector;
• the token that we want to remove should have no balance for the collector we're modifying;

Usage:

npx hardhat collector:removeToken --collector-address "<collector_address>" --token-address "<token_address>" --network regtest

Example:

npx hardhat collector:removeToken --collector-address "0xeFb80DB9E2d943A492Bd988f4c619495cA815643" --token-address "0x39B12C05E8503356E3a7DF0B7B33efA4c054C409" --network regtest   

Addresses

Each time the smart contracts are deployed, the contract-addresses.json file is updated. This file contains all contracts addresses for the network they were selected to be deployed on.

This change can be committed so that this repository is updated with the new version of the file; addresses for Testnet and Mainnet should be kept up to date.

This file also is being exported on the distributable version to provide the consumers a way to know the contract addresses on Testnet and Mainnet when we begin to release the project as a Node.js dependency.

System usage

Managing tokens

Once the smart contracts are deployed, tokens must be individually allowed to be able to work with the RIF Relay system. In the same way, tokens can be removed from the list of previously allowed tokens. There are some helpful commands for this:

• To allow a specific token, run npx hardhat allow-tokens --network <NETWORK_NAME> --token-list <TOKEN_ADDRESSES> where:
  • <TOKEN_ADDRESSES> is a comma-separated list of the token addresses to be allowed on the available verifiers
  • <NETWORK_NAME> is an optional parameter for the network name, taken from the hardhat.config.ts file (default value is hardhat) important! This should be the same network name as the one used to deploy the contracts If you want to modify just one or few verifiers, please specify it with the argument --verifier-list in a comma-separated format: npx hardhat allow-tokens --network <NETWORK_NAME> --token-list <TOKEN_ADDRESSES> --verifier-list <address1,address2>
• To query allowed tokens run npx hardhat allowed-tokens --network <NETWORK_NAME>. This will display them on the console. If you want to query just one or few verifiers, please specify it with the argument --verifier-list in a comma-separated format: npx hardhat allowed-tokens --network <NETWORK_NAME> --verifier-list <address1,address2>
• To remove a specific token, run npx hardhat remove-tokens --network <NETWORK_NAME> --token-list <TOKEN_ADDRESSES> where:
  • <TOKEN_ADDRESSES> is a comma-separated list of the token addresses to be removed on the available verifiers.
  • <NETWORK_NAME> is an optional parameter for the network name, taken from the hardhat.config.ts file (default value is hardhat) important! This should be the same network name as the one used to deploy the contracts. If you want to modify just one or few verifiers, please specify it with the argument --verifier-list in a comma-separated format: npx hardhat remove-tokens --network <NETWORK_NAME> --token-list <TOKEN_ADDRESSES> --verifier-list <address1,address2>

Managing destination contracts

Once the smart contracts are deployed, contracts must be individually allowed to be able to work with the RIF Relay system. In the same way, contracts can be removed from the list of previously allowed contracts. There are some helpful commands for this:

• To allow a specific contract, run npx hardhat allow-contracts --network <NETWORK_NAME> --contract-list <CONTRACT_ADDRESSES> where:
  • <CONTRACT_ADDRESSES> is a comma-separated list of the contract addresses to be allowed on the available verifiers
  • <NETWORK_NAME> is an optional parameter for the network name, taken from the hardhat.config.ts file (default value is hardhat) important! This should be the same network name as the one used to deploy the contracts If you want to modify just one or few verifiers, please specify it with the argument --verifier-list in a comma-separated format: npx hardhat allow-contracts --network <NETWORK_NAME> --contract-list <CONTRACT_ADDRESSES> --verifier-list <address1,address2>
• To query allowed contracts run npx hardhat allowed-contracts --network <NETWORK_NAME>. This will display them on the console. If you want to query just one or few verifiers, please specify it with the argument --verifier-list in a comma-separated format: npx hardhat allowed-contracts --network <NETWORK_NAME> --verifier-list <address1,address2>
• To remove a specific contract, run npx hardhat remove-contracts --network <NETWORK_NAME> --contract-list <CONTRACT_ADDRESSES> where:
  • <CONTRACT_ADDRESSES> is a comma-separated list of the contract addresses to be removed on the available verifiers.
  • <NETWORK_NAME> is an optional parameter for the network name, taken from the hardhat.config.ts file (default value is hardhat) important! This should be the same network name as the one used to deploy the contracts. If you want to modify just one or few verifiers, please specify it with the argument --verifier-list in a comma-separated format: npx hardhat remove-contracts --network <NETWORK_NAME> --contract-list <CONTRACT_ADDRESSES> --verifier-list <address1,address2>

UtilToken Minting

Once the smart contracts are deployed, UtilTokens can be minted and transferred by using the related script:

npx hardhat mint --token-address <0xabc123> --amount <amount_in_wei> --receiver <0xabc123> --network <NETWORK_NAME> 

Parameters:

• token-address: the address of the token that will be minted. The ERC20 token that will be used, needs to have a mint function.
• amount: the amount of tokens that will be minted and transferred.
• receiver: the address of the account the token will be transferred to.

Warning message

Truffle doesn’t support additional arguments natively when running truffle exec command, so the user can ignore the warning shown when the command is executed.

Warning: possible unsupported (undocumented in help) command line option(s): --tokenReceiver,--amount

For further info about truffle exec, please have a look at its official documentation.

Withdraw

To withdraw (share) the funds from the Collector contract, the repository provides the utility script collector:withdraw. It allows the user to call either the withdraw() or withdrawToken() function from the Collector contract. It receives the following parameters:

• collector-address: Mandatory. It's the address of the collector;
• token-address: Optional. It's the address of the token contract to withdraw. If provided, the function withdrawToken() will be called with this specific value, otherwise the function withdraw() will be called and the withdraw will be executed on all the allowed tokens;
• gas-limit: Optional. It's the gas limit used for the transaction. Default value is 200000;

npx hardhat collector:withdraw --collector-address '<0xcollector_address>' --token-address '<0xtoken_address>'  --gas-limit <gas_limit> --network <network-name>

Example:

npx hardhat collector:withdraw --collector-address "0x0Aa058aD63E36bC2f98806f2D638353AE89C3634" --token-address "0x6f217dEd6c86A57f1211F464302e6fA544045B4f" --gas-limit 500000 --network regtest 

Library usage

As a dependency

You can install this project like any other dependency through:

npm i --save @rsksmart/rif-relay-contracts

which will provide you with a way to use the contracts and interfaces, e.g.:

import {RelayHub, IForwarder} from '@rsksmart/rif-relay-contracts';

const relayHubContractAbi = RelayHub.abi;
const iForwarderAbi = IForwarder.abi;

Development

Adding new files

New solidity files can be added inside the contracts folder at the root of this repository, but note that:

• If your new file is not meant to be used outside this repository (internal contract or contract that will not be manually instantiated) then you don’t need to worry about anything else than just making solidity compile using npm run compile and making the linter work running npm run lint:sol.
• If your file is a contract that needs to be manually instantiated or referenced from outside this project, you’ll also need to run npm run compile and npm run lint:sol. If everything goes well, go to the index.ts file at the root of this project and add those new contracts/interfaces to the import/export declarations:

const SomeContract = require('./build/contracts/SomeContract.json');

export {
   ...,
   SomeContract
};

Testing

Testing is done using hardhat (mocha), chai, chai-as-promised, hardhat-chai-matchers, and smock for faking and mocking.

• npm run test: to run the test suite
• npm run tdd: to run the testsuite in watch-mode for faster TDD
• npm run ci:test: to compile and run test

Contract addresses

During development, the smart contract addresses config file can be expected to be updated each time a migration is executed.

To automatically use these new addresses each time a change is made, use the npm link mechanism (https://docs.npmjs.com/cli/v8/commands/npm-link).

Husky and linters

We use Husky to check linters and code style for every commit. If commiting changes fails on lint or prettier checks you can use these commands to check and fix the errors before trying again:

• npm run lint: to check/fix all linter bugs
• npm run lint:ts: to check/fix linter bugs for typescript
• npm run lint:sol: to check/fix linter bugs for solidity
• npm run format: to check/fix all code style errors
• npm run format:ts: to check/fix code style errors for typescript
• npm run format: to check/fix code style errors for solidity
• npm run ci:lint: to check all linter bugs
• npm run ci:format: to check all code style errors

Deploy to network

• Modify deployment scripts if needed
• Add configuration for your network
• Run npx hardhat deploy --network <NETWORK> to run deployment scripts

Generating a new distributable version

• Run the npm run compile command to delete all generated folders and recompile
• Bump the version on the package.json file (not strictly needed).
• Commit and push any changes, including the version bump.

For GitHub

• Create a new tag with the new version (from package.json) and github actions will update npm

For NPM

• Run npm login to login to your account on npm registry.
• Run npm publish to generate the distributable version for NodeJS.

For direct use (no publishing)

No extra steps are needed beyond generating the dist folder and merging it to master.