Bridge module

Bridge module is responsible for storing the information about threshold signature producers (parties) public keys, their RPC addresses and supported token pairs. All threshold signature producers have to fetch information about other parties from this module using the corresponding RPC queries.

State

Params

Bridge module params contains next fields:

• Module admin address - module admin is responsible for making changes in parties lists and thresholds, also only him can add new info about chains, tokens and transfers
• Parties list - parties list is the list of active validators which are parts of TSS protocol.
• Tss threshold - minimum required number of signers.

Definition:

// Params defines the parameters for the module.
message Params {
  string module_admin = 1;
  repeated Party parties = 2;
  uint32 tss_threshold = 3;
}

Example:

{
  "params": {
    "module_admin": "bridge1...",
    "parties": []
  }
}

Chain

Chain defines necessary chain properties used during bridging process.

Definition:

message Chain {
  string id = 1;
  ChainType type =2;
  // bridge_address is the address of the bridge contract on the chain
  string bridge_address = 3;
  // operator is the address of the operator of the bridge contract
  string operator = 4;
}

Example:

{
      "id": "0",
      "type": "BITCOIN",
      "bridge_address": "addr...",
      "operator": "addr...."
}

Referral

Referral defines referral properties that include the referral address to process withdrawal and the commission rate.

Definition:

message Referral {
      // stores a 16-bit unsigned integer
      uint32 id = 1; 
      string withdrawal_address = 2;
      string commission_rate = 3;
}

Example:

{
  "id": "0",
  "withdrawal_address": "zel1qqqqqnqaea03090u62sd7e42jfv2lhllf3v7ap",
  "commission_rate": "0.1"
}

Referral Rewards

ReferralRewards defines referral rewards properties that include the referral id, token id, amount to claim and total collected amount.

Definition

message ReferralRewards {
  uint32 referral_id = 1;
  uint64 token_id = 2;
  string to_claim = 3;
  string total_claimed_amount = 4;
}

Example

{
  "referral_id": 1,
  "token_id": 1,
  "to_claim": "10",
  "total_claimed_amount": "100"
}

Token

Token defines necessary token properties like id or decimals used during bridging process.

Definition:

message TokenInfo {
  string address = 1;
  uint64 decimals = 2;
  string chain_id = 3;;
  uint64 token_id = 4;
  bool is_wrapped = 5;
  string min_withdrawal_amount = 6;
}

message TokenMetadata {
  string name = 1;
  string symbol = 2;
  string uri = 3;
  string dex_name = 4;
}

message Token {
  uint64 id = 1;
  TokenMetadata metadata = 2 [(gogoproto.nullable) = false];
  // info is the token information on different chains
  repeated TokenInfo info = 3 [(gogoproto.nullable) = false];
  string commission_rate = 4;
}

Example:

{
  "id": "0",
  "commission_rate": "0.1",
  "metadata": {
    "name": "TESTNET",
    "symbol": "TEST",
    "uri": "",
    "dex_name": ""
  },
  "info": [
    {
      "address": "0x0000000000000000000000000000000000000000",
      "decimals": "18",
      "chain_id": "00000",
      "token_id": "1",
      "is_wrapped": true,
      "min_withdrawal_amount": "0"
    },
    {
      "address": "0x0000000000000000000000000000000000000000",
      "decimals": "18",
      "chain_id": "00000",
      "token_id": "1",
      "is_wrapped": false,
      "min_withdrawal_amount": "0"
    }
  ]
}

Transaction

Transaction defines bridge transaction details.

Definition:

message Transaction {
  string deposit_chain_id = 1;
  string deposit_tx_hash = 2;
  uint64 deposit_tx_index = 3;
  uint64 deposit_block = 4;
  string deposit_token = 5;
  string deposit_amount = 6;
  string depositor = 7;
  string receiver = 8;
  string withdrawal_chain_id = 9;
  string withdrawal_tx_hash = 10;
  string withdrawal_token = 11;
  string signature = 12;
  bool is_wrapped = 13;
  string withdrawal_amount = 14;
  string commission_amount = 15;
  string tx_data = 16;
  int32 referral_id = 17;
}

Example:

{
  "deposit_chain_id": "00000",
  "deposit_tx_hash": "0x0000000000000000000000000000000000000000",
  "deposit_tx_index": "0",
  "deposit_block": "0",
  "deposit_token": "0x0000000000000000000000000000000000000000",
  "deposit_amount": "00000",
  "depositor": "0x0000000000000000000000000000000000000000",
  "receiver": "0x0000000000000000000000000000000000000000",
  "withdrawal_chain_id": "00000",
  "withdrawal_tx_hash": "",
  "withdrawal_token": "0x0000000000000000000000000000000000000000",
  "signature": "0x0000000000000000000000000000000000000000",
  "is_wrapped": true,
  "withdrawal_amount": "0",
  "commission_amount": "0",
  "tx_data": "",
  "referral_id": 0
}

TransactionSubmission

message TransactionSubmissions{
  string tx_hash = 1;
  repeated string submitters = 2;
}

Example:

    {
      "tx_hash": "0x0000000000000000000000000000000000000000",
      "submitters": [
        "bridge1..."
      ]
    }

---

Messages

---

Chains

---

InsertChain

InsertChain - adds new chain data to core.

Message example:

message MsgInsertChain {
  string creator = 1;
  Chain chain  = 2 [(gogoproto.nullable) = false];
}

---

DeleteChain

DeleteChain-deletes chain data from core.

Message example:

message MsgDeleteChain {
  string creator = 1;
  string chain_id = 2;
}

---

Tokens

---

InsertToken

InsertToken - inserts token data to core.

Message example:

message MsgInsertToken {
  string creator = 1;
  Token token  = 2 [(gogoproto.nullable) = false];
}

---

UpdateToken

UpdateToken - updates queried token metadata on core.

Message example:

message MsgUpdateToken {
  string creator = 1;
  uint64 token_id = 2;
  TokenMetadata metadata = 3 [(gogoproto.nullable) = false];
}

---

DeleteToken

DeleteToken - deletes token data from core.

Message example:

message MsgDeleteToken {
  string creator = 1;
  uint64 token_id = 2;
}

---

Transactions

---

SubmitTransactions

SubmitTransactions - stores bridge transactions data to core.

Message definition:

message MsgSubmitTransactions {
  option (cosmos.msg.v1.signer) = "submitter";

  string submitter = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
  repeated core.bridge.Transaction transactions = 2 [(gogoproto.nullable) = false];
}

---

RemoveTransaction

RemoveTransaction - removes bridge transaction data from core.

Message definition:

message MsgRemoveTransaction{
  string creator = 1;

  string deposit_chain_id = 2;
  string deposit_tx_hash = 3;
  uint64 deposit_tx_index = 4;
}

---

TokenInfo

---

AddTokenInfo

AddTokenInfo - adds new token info to existing one on core.

Message example:

message MsgAddTokenInfo {
  string creator = 1;
  TokenInfo info = 3 [(gogoproto.nullable) = false];
}

---

RemoveTokenInfo

Message example:

message MsgRemoveTokenInfo {
  string creator = 1;
  uint64 token_id = 2;
  string chain_id = 3;
}

---

Referrals

---

SetReferral

Message definition:

message MsgSetReferral {
  string creator = 1;
  Referral referral = 2 [(gogoproto.nullable) = false];
}

---

RemoveReferral

Message definition:

message MsgRemoveReferral {
  string creator = 1;
  uint32 id = 2;
}

---

SetReferralRewards

Message definition:

message MsgSetReferralRewards {
  string creator = 1;
  ReferralRewards rewards = 4 [(gogoproto.nullable) = false];
}

---

RemoveReferralRewards

Message definition

message MsgRemoveReferralRewards {
  string creator = 1;
  uint32 referrer_id = 2;
  uint64 token_id = 3;
}

---

Parties

---

SetParties

Message example:

message MsgSetPartiesList {
  string creator =1;
  repeated Party parties = 2;
}

---

Threshold

---

SetTssThreshold

Message example:

message MsgSetTssThreshold {
  string creator =1;
  uint32  amount = 2;
}

---

CLI

---

Messages

---

Chains

---

InsertChain

InsertChain - adds new chain data to core.

zel-cored tx bridge chains insert bridge1... chain.json

Example of chain.json:

{
  "id": "0",
  "type": 0,
  "bridge_address": "0x0000000000000000000000000000000000000000",
  "operator": "0x0000000000000000000000000000000000000000"
}

---

DeleteChain

DeleteChain - deletes chain data by chain id from core.

 zel-cored tx bridge chains remove bridge1... 1

---

Referrals

---

SetReferral

SetReferral - adds new referral data to core.

zel-cored tx bridge referral set bridge1... referral-id=0 referral-withdrawal-address=bridge1... referral-commission-rate=5

---

RemoveReferral

RemoveReferral - removes referral data by referral id from core.

 zel-cored tx bridge referral remove bridge1... 0

---

SetReferralRewards

SetReferralRewards - adds new referral rewards data to core.

 zel-cored tx bridge referral-rewards set bridge1... referral-id=1 token-id=1 to-claim=10uzel total-collected-amount=100uzel

---

RemoveReferralRewards

RemoveReferralRewards - removes referral rewards data by referral id and token id from core.

 zel-cored tx bridge referral-rewards remove bridge1... 1 1

---

Tokens

---

InsertToken

InsertToken - inserts token data to core.

 zel-cored tx bridge tokens insert bridge1... token.json

Example of token.json:

{
  "id": 1,
  "commission_rate": "0.1",
  "metadata": {
    "name": "TESTNET",
    "symbol": "TEST",
    "uri": "https://example.com"
  },
  "info": [
    {
      "address": "0x0000000000000000000000000000000000000000",
      "decimals": 18,
      "chain_id": "00000",
      "token_id": 1,
      "is_wrapped": true
    },
    {
      "address": "0x0000000000000000000000000000000000000000",
      "decimals": 18,
      "chain_id": "00000",
      "token_id": 1,
      "is_wrapped": false
    }
  ]
}

---

UpdateToken

UpdateToken - updates queried token metadata on core.

zel-cored tx bridge tokens update bridge1... token.json

---

DeleteToken

DeleteToken - deletes token data by token id from core.

 zel-cored tx bridge tokens remove bridge1... 1

---

Transactions

---

SubmitTransactions

SubmitTransactions - stores bridge transactions data to core.

zel-cored tx bridge transactions submit bridge1... tx.json

---

TokenInfo

---

AddTokenInfo

AddTokenInfo - adds new token info to existing one on core.

zel-cored tx bridge tokens add-info bridge1... info.json

---

RemoveTokenInfo

zel-cored tx bridge tokens remove-info bridge1... 1 [token-id] 1 [chain-id]

---

Parties

---

SetParties

 zel-cored tx bridge parties set default bridge1... bridge1...,bridge1...

---

SetTssThreshold

 zel-cored tx bridge threshold set-tss-threshold bridge1... 5

---

Query

---

Params

zel-cored query bridge params

Response example:

params:
  module_admin: bridge1...
  parties:
  - address: bridge1...
  - address: bridge1...
  tss_threshold: 0

---

Chains

---

QueryChains

zel-cored query bridge chains

Response example:

chains:
- bridge_address: m4...
  id: "1"
  operator: m4...
  type: BITCOIN
- bridge_address: Zx...
  id: "2"
  operator: Zx...
  type: ZANO
- bridge_address: 0x...
  id: "3"
  operator: 0x...
  type: EVM
- bridge_address: 0x...
  id: "4"
  operator: 0x...
  type: EVM

---

QueryChainById

zel-cored query bridge chain 1

Response example:

chain:
  bridge_address: m4...
  id: "1"
  operator: m4...
  type: BITCOIN

---

Referrals

---

GetReferralById

 zel-cored query bridge referrals 1

Response example:

referral:
  commission_rate: "0.1"
  id: "1"
  withdrawal_address: zel1qqqqqnqaea03090u62sd7e42jfv2lhllf3v7ap

---

GetQueryGetReferrals

zel-cored query bridge referrals

Response example:

referrals: 
  - commission_rate: "0.1"
    id: "1"
    withdrawal_address: zel1qqqqqnqaea03090u62sd7e42jfv2lhllf3v7ap

---

GetReferralRewardsByToken

 zel-cored query bridge referral-rewards 1 1

Response example:

referral_rewards:
  referral_id: "1"
  to_claim: "10"
  token_id: "1"
  total_claimed_amount: "100"

---

GetQueryGetReferralsRewardsById

zel-cored query bridge referrals-rewards

Response example:

referrals_rewards:
- referral_id: "1"
  to_claim: "10"
  token_id: "1"
  total_claimed_amount: "100"

---

Tokens

---

QueryAllTokens

zel-cored query bridge tokens

Response example:

tokens:
- commission_rate: "0.5"
  id: "1"
  info:
  - address: 0x0000000000000000000000000000000000000000
    chain_id: "00000"
    decimals: "18"
    is_wrapped: true
    token_id: "1"
  - address: "0x0000000000000000000000000000000000000000"
    chain_id: "00000"
    decimals: "18"
    is_wrapped: false
    token_id: "1"
  metadata:
    name: TESTNET
    symbol: TEST
    uri: https://example.com

---

QueryTokenById

 zel-cored query bridge token 1

Response example:

tokens:
- commission_rate: "0.5"
  id: "1"
  info:
  - address: 0x0000000000000000000000000000000000000000
    chain_id: "00000"
    decimals: "18"
    is_wrapped: true
    token_id: "1"
  - address: "0x0000000000000000000000000000000000000000"
    chain_id: "00000"
    decimals: "18"
    is_wrapped: false
    token_id: "1"
  metadata:
    name: TESTNET
    symbol: TEST
    uri: https://example.com

---

QueryTokenPairs

zel-cored query bridge token-pairs 1 0x0000000000000000000000000000000000000000 2

Response example:

    address: 0x0000000000000000000000000000000000000000
    chain_id: "2"
    decimals: "18"
    is_wrapped: true
    token_id: "1"

---

TokenInfo

---

QueryTokenInfo

zel-cored query bridge token-info 1 0x...

Response example:

info:
  address: 0x0000000000000000000000000000000000000000
  chain_id: "00000"
  decimals: "18"
  is_wrapped: true
  token_id: "1"

---

Transactions

---

QueryAllTransactions

zel-cored query bridge transactions

Response example:

transactions:
- commission_amount: "0"
  deposit_amount: "00000"
  deposit_block: "0"
  deposit_chain_id: "0000"
  deposit_token: "0x0000000000000000000000000000000000000000"
  deposit_tx_hash: 0x0000000000000000000000000000000000000000
  deposit_tx_index: "0"
  depositor: 0x0000000000000000000000000000000000000000
  is_wrapped: true
  receiver: 0x0000000000000000000000000000000000000000
  signature: 0x0000000000000000000000000000000000000000
  tx_data: ""
  withdrawal_amount: "0"
  withdrawal_chain_id: "0"
  withdrawal_token: 0x0000000000000000000000000000000000000000
  withdrawal_tx_hash: ""

---

QueryTransactionById

Pass the source chain ID, deposit transaction hash, and deposit nonce as three separate arguments. For example, an Amoy deposit with event index 2:

zel-cored query bridge transaction 80002 0x8746c185266a81c240adf7293e656063a11ca1e43d3f81eb2a69a6a622e737d6 2

Response example:

transaction:
  commission_amount: "0"
  deposit_amount: "00000"
  deposit_block: "0"
  deposit_chain_id: "80002"
  deposit_token: "0x0000000000000000000000000000000000000000"
  deposit_tx_hash: "0x8746c185266a81c240adf7293e656063a11ca1e43d3f81eb2a69a6a622e737d6"
  deposit_tx_index: "2"
  depositor: 0x0000000000000000000000000000000000000000
  is_wrapped: true
  receiver: 0x0000000000000000000000000000000000000000
  signature: 0x0000000000000000000000000000000000000000
  tx_data: ""
  withdrawal_amount: "0"
  withdrawal_chain_id: "0"
  withdrawal_token: 0x0000000000000000000000000000000000000000
  withdrawal_tx_hash: ""

---

QueryAllTransactionsSubmissions

zel-cored query bridge transactions-submissions

Response example:

txs_submissions:
- submitters:
  - bridge1....
  tx_hash: 0x0000000000000000000000000000000000000000

---

QueryAllTransactionsSubmissions

zel-cored query bridge transaction-submissions 0x0000000000000000000000000000000000000000

Response example:

txs_submissions:
- submitters:
  - bridge1....
  tx_hash: 0x0000000000000000000000000000000000000000

---