Raiden Network Smart Contracts

Raiden Network Smart Contract specs

Prerequisites

• Python 3.8 or 3.9
• https://pip.pypa.io/en/stable/

Installation

Recommended:

pip install raiden-contracts

Finding Deployed Contract Instances

All smart contracts in this repository are made available WITHOUT ANY REPRESENTATION OR WARRANTY; without even the (implied) warranty of FITNESS FOR ANY PARTICULAR PURPOSE. Use at your own risk.

If you want to use the deployed contracts, please use the raiden_contracts/data_<CONTRACTS_VERSION>/contracts.json file to get the ABI and bytecode for initializing the contract instances.

You can find the addresses of the deployed contracts in raiden_contracts/data_<CONTRACTS_VERSION>/deployment_*.json. All contracts under raiden_contracts/contracts/test/ are only for testing purposes and they should not be used in production.

You can find other useful constants that you can import in raiden_contracts/constants.py.

Note

This package supports many contract versions, including:

• Development 0.3._ contracts version (from 0.3.0 package release: https://github.com/raiden-network/raiden-contracts/releases/tag/v0.3.0). No limits on the number of tokens registered; has a limit of 100 tokens per channel). Source code: https://github.com/raiden-network/raiden-contracts/tree/fc1c79329a165c738fc55c3505cf801cc79872e4/raiden_contracts/contracts
• Red Eyes Mainnet 0.4.0 contracts version (from 0.7.0 package release: https://github.com/raiden-network/raiden-contracts/releases/tag/v0.7.0). Source code: https://github.com/raiden-network/raiden-contracts/tree/fac73623d5b92b7c070fdde2b446648ec9117474/raiden_contracts/contracts
• current !development version corresponding with the master branch (might not be stable).

The current policy is to add all new deployment data together with the sources.

If you want to use the officially deployed contracts, please use the raiden_contracts/data_<CONTRACTS_VERSION> files to get the precompiled data (ABI, bytecode etc.) and addresses for initializing the contract instances. Alternatively, in Python scripts, with raiden-contracts package, you can find the already deployed contract instances like:

from raiden_contracts.contract_manager import (
    ContractManager,
    contracts_precompiled_path,
    get_contracts_deployment_info,
)
from raiden_contracts.constants import (
    CONTRACT_TOKEN_NETWORK_REGISTRY,
    CONTRACT_MONITORING_SERVICE,
    CONTRACTS_VERSION,
    EVENT_TOKEN_NETWORK_CREATED,
)

# ``raiden-contracts`` provides ``contracts_version``s like
# ``0.9.0``, ``'0.4.0'`` and ``'0.3._'``.  They are explained below.

# Uses the newest test net release available on Kovan, Rinkeby and Ropsten.
contracts_version = CONTRACTS_VERSION

# Uses Red Eyes, Mainnet enabled version with deposit limits.
# The version is also available on Kovan, Rinkeby and Ropsten.
contracts_version = '0.4.0'

# Uses the pre-red-eyes development version, probably without
# deposit limits. Available only on Kovan, Rinkeby and Ropsten.
# The Solidity source of this version is unknown on Etherscan.
# See https://github.com/raiden-network/raiden-contracts/issues/543
contracts_version = '0.3._'

manager = ContractManager(contracts_precompiled_path(contracts_version))
compiled_contract_data = manager.get_contract(CONTRACT_TOKEN_NETWORK_REGISTRY)

deployment_data = get_contracts_deployment_info(web3.eth.chainId)
TOKEN_NETWORK_REGISTRY_ADDRESS = deployment_data['contracts'][CONTRACT_TOKEN_NETWORK_REGISTRY]["address"]

# And then use:
# compiled_contract_data['abi']
# compiled_contract_data['bin']
# TOKEN_NETWORK_REGISTRY_ADDRESS
# to initialize the contract instance

# To use one of the 3rd party services contracts:
compiled_ms_contract = manager.get_contract(CONTRACT_MONITORING_SERVICE)
MONITORING_SERVICE_ADDRESS = deployment_data['contracts'][CONTRACT_MONITORING_SERVICE]["address"]

Looking Up Gas Consumption

Each contracts_version (at least 0.8.0) comes with gas consumption measurements:

gas = gas_measurements(contracts_version)
gas["TokenNetwork.setTotalDeposit"]

evaluates to something like 45000.

Test-only Contracts

All contracts under raiden_contracts/contracts/test/ are only for testing purposes and they should not be used in production.

Development

If you want to test and further develop outside the officially provided source code, compiled files and deployed addresses, you can do it at your own risk.

If you want to install the package from source:

make install-dev

To verify that the precompiled raiden_contracts/data/contracts.json file corresponds to the source code of the contracts:

make verify_contracts

Compile the contracts

Needed if you have made changes to the source code.

make compile_contracts

Updating gas costs

To update the gas costs run

make update_gas_costs

Testing

If you want to write tests, check /raiden_contracts/tests/README.md first.

# tests
pytest
pytest raiden_contracts/tests/test_token_network.py

# Recommended for speed:
pip install pytest-xdist==1.17.1
pytest -n NUM_OF_CPUs

If you are using the raiden-contracts package in your project, you can also test the source code directly (not only the precompiled contract data):

from raiden_contracts.contract_manager import (
    ContractManager,
    contracts_source_path,
)

manager = ContractManager(contracts_source_path(<CONTRACTS_VERSION>))

Deployment on a testnet

• get the source code from the latest stable release

• install development dependencies:

  pip install -r requirements-dev.txt
  

Note

If deploying on your own private chain, you need to start geth with --networkid <chainID_from_genesis.json>. The private chain must be running the Byzantium protocol (or a later version) at the time of deployment.

If you want to use a particular version of the contracts that is supported, you can use the deploy script with -- contracts-version "0.4.0".

Check deployment options:

python -m raiden_contracts.deploy --help

Deploying the main Raiden Network contracts with the raiden command:

python -m raiden_contracts.deploy raiden --rpc-provider http://127.0.0.1:8545 --private-key /path/to/your/private_key/file --gas-price 10 --gas-limit 6000000 --max-token-networks 1

When the raiden command is passed the optional argument --secret-registry-from-deployment-file <deployment-file>, the command tries to reuse SecretRegistry instance found in <deployment-file>. For example, some deployment files are found under raiden_contracts/data*/deployment_*.json.

Deploying the mock token contract for paying for the services (not to be done on the mainnet):

python -m raiden_contracts.deploy token --rpc-provider http://127.0.0.1:8545 --private-key /path/to/your/private_key/file --gas-price 10 --token-supply 20000000 --token-name ServiceToken --token-decimals 18 --token-symbol SVT

Deploying the 3rd party service contracts with the services command:

python -m raiden_contracts.deploy services --rpc-provider http://127.0.0.1:8545 --private-key /path/to/your/private_key/file --gas-price 10 --gas-limit 6000000 --token-address TOKEN_USED_TO_PAY_SERVICES --user-deposit-whole-limit MAX_TOTAL_AMOUNT_OF_TOKENS_DEPOSITED_IN_USER_DEPOSIT --service-deposit-bump-numerator NUMERATOR_OF_PRICE_DUMP --service-deposit-bump-denominator DENOMINATOR_OF_PRICE_DUMP --service-deposit-decay-constant DECAY_CONSTANT --initial-service-deposit-price INITIAL_PRICE --service-deposit-min-price MIN_PRICE --service-registration-duration REGISTRATION_DURATION_IN_SECS --token-network-registry-address TOKEN_NETWORK_REGISTRY_ADDRESS

When the services command is passed the optional argument --service-registry-from-deployment-file <deployment-file>, the command tries to reuse ServiceRegistry instance found in <deployment-file>. For example, some deployment files are found under raiden_contracts/data*/deployment_*.json.

Deploying a token for testing purposes (please DO NOT use this for production purposes) with the token command:

python -m raiden_contracts.deploy token --rpc-provider http://127.0.0.1:8545 --private-key /path/to/your/private_key/file --gas-price 10 --token-supply 10000000 --token-name TestToken --token-decimals 18 --token-symbol TTT

Registering a token with the TokenNetworkRegistry contract, so it can be used by the Raiden Network, with the register command:

python -m raiden_contracts.deploy register --rpc-provider http://127.0.0.1:8545 --private-key /path/to/your/private_key/file --gas-price 10 --token-address TOKEN_TO_BE_REGISTERED_ADDRESS --token-network-registry-address TOKEN_NETWORK_REGISTRY_ADDRESS --channel-participant-deposit-limit 115792089237316195423570985008687907853269984665640564039457584007913129639935 --token-network-deposit-limit 115792089237316195423570985008687907853269984665640564039457584007913129639935

Note

Registering a token only works once. All subsequent transactions will fail.

Deployment information is stored in a deployment_[CHAIN_NAME].json file corresponding to the chain on which it was deployed. To verify that the deployed contracts match the compiled data in contracts.json and also match the deployment information in the file, we can run:

python -m raiden_contracts.deploy verify --rpc-provider http://127.0.0.1:8545

# Based on the network id, the script verifies the corresponding deployment_[CHAIN_NAME].json file
# using the chain name-id mapping from constants.py

Deployment on an Arbitrum based network

In case the target network is based on Arbitrum, it needs some extra care in terms of the gas. Gas works differently here and therefore the associated commandline parameter requires different values. First of all the --gas-limit parameter should not be set. This gets done automatically and in adaption to Arbitrum. Second, the --gas-price parameter has a different effect. On Arbitrum this defines the highest price the transactor is willing to pay. This means up-on execution the Arbitrum node will reduce the price automatically to the current price and no more. So this can be seen as --max-gas-price. The amount has no impact on how fast the transaction gets through. The default 5 Gwei should be enough for most cases. To be sure, just check the current gas price on an official Arbitrum block explorer. In case the value is too low, the Arbitrum node will just reject the transaction with a respective error message.

Verification with Etherscan

python -m raiden_contracts.deploy.etherscan_verify --apikey ETHERSCAN_APIKEY --chain-id 3

If the command exists with status code 0, Etherscan has verified all contracts against Solidity sources.

Utilities for minting, balance checking, token transfer

You can mint tokens from a CustomToken contract, WETH contract from any testnet and query balances from the commandline using the token_ops.py Sample usage

• Minting tokens

  python token_ops.py mint --rpc-url http://127.0.0.1:8545 --private-key ~/priv_chain/blkchain1/keystore/private_net_address --token-address 0x2feEd0E54238051dddCc01bF3960B143e887a9B7 --amount 1000
  

• Minting tokens with a password file

  python token_ops.py mint --rpc-url https://rpc.slock.it/goerli --private-key ~/.ethereum/keystore/UTC--2019-04-25T07-10-37.872928741Z--f8608ad00ab66b3a2aa21253c7915413034d0be5 --password ~/.ethereum/keystore/passwd_F8608A.txt --token-address 0x610f3c3C1998FAd6A659A9f5Bb83962DA27eAf1d --amount 1000
  

• Getting weth tokens

  python token_ops.py weth --rpc-url http://127.0.0.1:8545 --private-key ~/priv_chain/blkchain1/keystore/private_net_address --token-address 0xdf048aa8cbA44f9590F888BAb5e5AC78AAb503C8 --amount 1000
  

• Query account balance in any token

  python token_ops.py balance --rpc-url http://127.0.0.1:8545 --token-address 0xdf048aa8cbA44f9590F888BAb5e5AC78AAb503C8 --address 0xb8eb60F2E45667c9B2cFf861b82656452659C6dE
  

• Transfer tokens

  python token_ops.py transfer --rpc-url http://127.0.0.1:8545 --private-key ~/priv_chain/blkchain1/keystore/private_net_address --token-address 0xdf048aa8cbA44f9590F888BAb5e5AC78AAb503C8 --amount 1000 --destination 0x7ba5f1c08548f80d52856c21e87fcca05c5e40e3
  

Making a Release

See Release Process Document.

Directory Structure

• raiden_contracts

  • contracts

    • lib - libraries used by core contracts
    • services - contains 3rd party services contracts
    • test - test contracts used to test core contracts
    • raiden core contracts files

  • data - compiled contracts data & deployment information
  • data_0.3._ - compiled contracts data & deployment information for an older version with only a channel limit of 100 tokens
  • data_0.4.0 - compiled contracts data & deployment information for Red Eyes release
  • data_0.x.y - compiled contracts data & deployment information only for test nets
  • deploy - deployment & verification scripts

  • tests

    • fixtures - fixtures used by all tests
    • property - property tests for core contracts
    • unit - unit tests for internal functions in core contracts
    • utils - specific utilities for tests, closely related to the contracts logic
    • main test files for both core & service contracts

  • utils

    • general utilities for tests (signing, merkle trees, logs), independent of the contracts logic
    • some utilities related to the contracts logic that might be exported by projects using the package

  • constants.py - package deliverable, constants used by projects that import the package
  • contract_manager.py - package deliverable, used by projects that import the package, gets the correct compiled contracts data based on version

• setup files for requirements, builds etc.

FAQ

Why am I seeing many version numbers?

You are seeing a version number of the PyPI package and several version numbers of smart contract sources. This same PyPI package provides access to multiple deployments of smart contracts. People use raiden-contracts PyPI package to interact with a mainnet deployment made a while ago, an older testnet deployment without deposit limits, or a newer testnet deployment with deposit limits and with service contracts.

Why does the same package provide different versions of smart contracts?

Because a prominent user (raiden) uses a single version of this package. They might one day start using multiple TokenNetwork deployments from multiple contracts versions.

Are the package version and the smart contracts versions related?

Yes, especially since package version 0.33.3. Whenever there is a new contracts version, the package version and the contracts version get a minor upgrade (Y increases in 0.Y.Z), and they look similar. When a package upgrade only contains Python changes, the package version only gets a patch upgrade (Z increases in 0.Y.Z).

How to find the addresses of deployed contracts?

Search above for get_contracts_deployed and see the usage.

How to mint the tokens on the test network?

Each contract that receives a token has a public variable Token public token. On the test networks, they might be CustomToken contract so you can call mint(how_many) function of the CustomToken contract to get some new tokens.

I see block gas exceeded

Perhaps you've added --gas-limit option with a too big integer. Try dropping the option.