Integrating with Multisig Accounts

In order to make it easily and quickly for other Cosmos Eco projects without integrated ICA features to get their own liquid staking derivatives, StaFiHub has developed a Liquid Staking SDK and identified a complete integration process.

In general, integrating a new rToken does not require any development, mainly to run the rToken relay service.

The whole program is divided into three parts:

StaFiHub chain

Based on cosmos-sdk, the on-chain module implements rToken-related functions, such as mint rToken, unbond function for user, exchange rate update, etc. In addition, there are some modules for rToken application scenarios, such as rDEX.

When integrating a new rToken, the StaFiHub chain does not require additional development, only need to register the relevant information of the new rToken.

rToken relay service

It mainly deals with cross-chain related logic (similar to the functions as a cross-chain bridge). Multiple relay nodes jointly manage multi-signature accounts and initiate related multi-signature transactions, such as delegate, undelegate, and withdrawDelegationReward on the target chain, and also need to interact with the StaFiHub chain.

StaFiHub App

The front-end interactive DApp, on which users can stake the target chain token, unbond the token, participate in DEX transactions, etc. StaFiHub holds the app that integrates all rTokens, and you can easily add a new chain configuration to integrate a new rToken.

The above rToken relay service and the DApp are also openly designed, and the access party can also do some customized logic and design based on this, or run the DApp independently, etc.

Here are the detail steps about the entire integration process of the SDK.


Step 1

Contact StaFiHub, please join in the Discord and contact the @CoreDev to talk about the integration.

Then, we need to confirm the following access parameters, which will eventually be registered on the StaFiHub chain:



The denomination used by the target chain.



Decimal points to covert minimal denomination to user-facing denomination



Prefix of account address.



Prefix of validator address.


pool(multi-signature account)

The multi-signature account. Generally co-generated with StaFiHub and others.



Sub accounts(relay accounts) of the multi-signature account(pool). Each rToken realy service needs to import an account to initiate transactions with the target chain(like Cosmos). 7 accounts recommended on mainnet.



Pubkeys of sub accounts(relay accounts). Each rToken realy service needs to import other pubkeys to generate the multi-signature account locally.



Threshold of the multi-signature account(pool). 4 recommended on mainnet.



Relay accounts of StaFiHub. Each rToken realy service needs to import an account to initiate transactions with the StaFiHub. 7 accounts recommended on mainnet.



Threshold of the relayers. 4 recommended on mainnet.



Gas price. Ensure that each rToken realy service can successfully initiate a transaction to the target chain.



Unbonding time of the target chain.



Minimum staking amount to mint rToken(Optional). Usually decided by StaFiHub.


The most important of these parameters is the pool account, which is a multi-signature account used to manage token assets(like ATOM) of the target chain and initiate transactions such as staking and transfer on the target chain. So we need to ensure the security of the multi-signature account to prevent risks such as asset loss.

StaFi foundation strongly recommends decentralizing the key-holder of sub-accounts due to the risk. At the early stage, the decentralization transition can be initiated from the foundation, known community members, trusty third parties to the governance, we would recommend that StaFi Foundation hold 3 sub-accounts and the foundation of the target chain needs to hold 4 sub-accounts. Target chain foundation can choose trustworthy community members to hold some sub-accounts, but at present we recommend that the community should hold no more than 2 sub-accounts. And we will open more in the future if necessary.

Risk: As we know, once a multi-signature account is generated, it cannot be changed, and sub-accounts cannot be replaced either. So all members must be stable and trustworthy. If some sub-accounts are permanently lost, we need to migrate the assets on the multi-signature account in time.

Step 2

One of the relay service's tasks is to invoke staking related calls based on the multi-signature pool accounts on the target chain. Multiple relay services work together to manager these pool accounts which are secure only if as many parties as possible are running the relay service.

  1. Check the staking mechanism of the target chain. Current code of relay service is perfectly aligned with the current staking module of the Cosmos-SDK, however, if the target chain does not adopt staking Module of the Cosmos-SDK, instead, a self-built staking module is used, then the SDK for the target chain on which relay service depends needs to be rebuild to fit that module.

  2. Prepare RPC endpoints. A relay service connects both StaFiHub and the target chain, so RPC endpoints of both two chains are needed to provide. In addition, to ensure that a relay service will not break down due to the disconnection of an RPC endpoint, it is best to configure multiple RPC endpoints. We suggest that the target chain run the nodes themselves, or cooperate with other validators and node service providers in the network.

  3. Prepare the configuration file for the relay service like this.

    • Install Go.

    • Use the key tool to build keys for the relay service.

  4. Run relay service. You can refer to the file under the project.

Note:If you hold multiple sub-accounts, you also need to run multiple rToken relay services.


(1) Install go

cd $HOME
wget -O go1.18.2.linux-amd64.tar.gz
rm -rf /usr/local/go && tar -C /usr/local -xzf go1.18.2.linux-amd64.tar.gz && rm go1.18.2.linux-amd64.tar.gz
echo 'export GOROOT=/usr/local/go' >> $HOME/.bashrc
echo 'export GOPATH=$HOME/go' >> $HOME/.bashrc
echo 'export GO111MODULE=on' >> $HOME/.bashrc
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> $HOME/.bashrc && . $HOME/.bashrc
go version

(2) build

cd $HOME
mkdir ratom
cd ratom
mkdir blockstore keys
git clone
cd rtoken-relay-core
git checkout <latest-release-tag>
make build

(3) Generate key

Note: To ensure security, we strongly recommend generating these keys offline and backing up the mnemonic phrases and the passwords, and then migrating the keyring-file to the server running the rToken relay service.

In addition, if you hold for example 3 sub-accounts, you need to generate multiple keys, such as stafihub-relay-1, stafihub-relay-2, stafihub-relay-3 and cosmos-relay-1, cosmos-relay-2, cosmos-relay-3. But please remember that each keyring-file only contains the private key information of one sub account to prevent the loss of multiple sub-accounts at one time.

### Add a new stafi relay account
./build/relay keys add stafihub-relay-1 --prefix stafi --keyring-backend file -i --home $HOME/ratom/keys/stafihub

### Check the stafi realy account
./build/relay keys list --prefix stafi --keyring-backend file --home $HOME/ratom/keys/stafihub

### Add a new cosmos relay account
./build/relay keys add cosmos-relay-1 --prefix cosmos --keyring-backend file -i --home $HOME/ratom/keys/cosmoshub

### Check the cosmos realy account
./build/relay keys list --prefix cosmos --keyring-backend file --home $HOME/ratom/keys/cosmoshub

key example:

- name: stafihub-relay-1
  type: local
  address: stafi17yl0s0zh7u87uhluzn2egg5ru2hy3jqxfspdlp
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"Ak3QK15yi5i1FrpPpJT/OjlTk8QbaYqgfs3tgzlqgD2G"}'
  mnemonic: ""

### Record the cosmos pubkey, which will be used by others when generating the multi-signature account
- name: cosmos-relay-1
  type: local
  address: cosmos1lyqrtft9x286gfsf30rf8vtvmc3jgd0mevd8p3
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"Apd6n7lU/YOEvsHPvETl6p+joYtddcKenjGmceAp7trz"}'
  mnemonic: ""

(4) Generate multi-signature account(pool)

### Add other pubkeys of cosmos realy accounts(other sub accounts)

./build/relay keys add cosmos-relay-2 --pubkey '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A+Ec4Y+Z9l+vekXhBLw6tZbAMOtrzFpiMQVk6ZXLpev4"}' --prefix cosmos --keyring-backend file --home $HOME/ratom/keys/cosmoshub
./build/relay keys add cosmos-relay-3 --pubkey '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A4qYOu0cibA5a0PkGgmsUW0luKH5aY1yfTrO1YZKg/um"}' --prefix cosmos --keyring-backend file --home $HOME/ratom/keys/cosmoshub

### Generate the multi-signature account
./build/relay keys add multisig1 --multisig-threshold=2 --multisig=cosmos-relay-1,cosmos-relay-2,cosmos-relay-3 --prefix cosmos --keyring-backend file --home $HOME/ratom/keys/cosmoshub

Note: Each rToken relay service needs to import pubkeys of all other relay accounts(sub accounts), and then generate the multi-signature account locally. Because each rToken relay service needs to configure the multi-signature account in the local configuration file.

(5) Prepare config.json

cd $HOME/ratom
vi config.json

### example
  "blockstorePath": "/home/stafihub/ratom/blockstore",
  "nativeChain": {
    "name": "StaFiHub chain",
    "endpointList": [
    "keystorePath": "/home/stafihub/ratom/keys/stafihub",
    "opts": {
      "startBlock": 0,
      "gasPrice": "0.02ufis",
      "account": "stafihub-relay-1"
  "externalChain": {
    "name": "CosmosHub chain",
    "endpointList": [
    "rsymbol": "uratom",
    "keystorePath": "/home/stafihub/ratom/keys/cosmoshub",
    "opts": {
      "startBlock": 0,
      "pools": {
        "multisig1": "cosmos-relay-1"

startBlock: When starting the rToken relay for the first time, startBlock needs to be configured as the current block of the network. Under normal circumstances, the startBlock does not need to be modified during subsequent restarts (the latest block of the chain will be recorded in the blockstore when the relay service running).

blockstorePath/keystorePath/account: Please replace with your own configuration.

endpointList: Chain RPC list. It is strongly recommended to configure at least two RPCs to ensure the stability of the rToken service.

multisig1: The multi-signature account name, please replace with your own configuration.

(6) Run

Use the following command to run the service in the background. Maybe you can create a systemd service or use some commands like screen or nohup, or some other tools.

./build/relay start --config $HOME/ratom/config.json --log_level info

Step 3

Please follow this.

Last updated