exSat Network
  • 🔗Important Links
  • 🌌Our Approach
    • What is exSat
      • exSat’s Docking Layer Approach
      • The Paradigm Shift of the Bitcoin Economic Ecosystem
      • Challenges Addressed by exSat
    • Architecture
      • Data Consensus Protocol
        • Network launch phases
        • Decentralized UTXO index
        • Synchronizers and Validators
        • Hybrid Consensus Mechanism
        • Decentralized execution
      • Decentralized Asset Custody (Coming soon)
      • Enhancing the Bitcoin Ecosystem with Smart Contract Capabilities
      • Expanding Possibilities with Rollups
    • $XSAT Tokenomics
      • Total Supply and Issuance
      • Rewards to Synchronizers and Validators
  • 🛠️Guides of Data Consensus
    • Quick Start
    • UTXO Initialization
      • Data preparation
      • Analysis on the UTXO data tobe uploaded
      • Verify the data uploaded to exSat
    • Run a Sychronizer
      • Requirements for Synchronizers
      • Rewards for synchronizers
      • Run as Synchronizer
        • Run from source code
        • Run with Docker
    • Run a BTC Validator
      • Requirements and rewards for BTC Validators
      • Run as BTC validator
        • Run from source code
        • Run with docker
    • Run a XSAT Validator
      • Run as XSAT Validator
        • Run from source code
        • Run with docker
      • Run multiple XSAT Validators
    • Others
      • Operation references
        • Preparation Before You Start
          • Account Preparation
          • Run a BTC node
          • Environment requirements
          • Prerequisites
        • Synchronizer operations
          • Create New Synchronizer Account
          • Synchronizer Registration
          • Execute the synchronizer client
          • Revote For Consensus
          • Change Reward Address
          • Check and claim rewards for synchronizer
          • Update to new Docker version for Synchronizer
        • Validator operations
          • Create New BTC Validator Account
          • Create New XSAT Validator Account
          • Stake for Validator and claim rewards
          • Change Stake Address
          • Change Commission Address
          • Change Commission Ratio
          • Configure Display Information for Your Validator Account
          • Execute the validator client
          • Update to new Docker version for Validator
        • Common operations
          • Import from seed phrase
          • Import from Private Key
          • Set BTC RPC Node
          • Refill BTC for Gas Fees
          • Export private key
          • Remove Your Account
          • Upgrade to new version
          • View Logs
          • Environment variables
  • 👨‍💻Developer Guides
    • Quick Start
    • Native Layer Developer Guides
      • exSat consensus contracts
        • Pool Register Contract
        • UTXO Management Contract
        • Reward Distribution Contract
        • Block Consensus Contract
        • Block Synchronization Contract
        • Validator Management Contract
        • Staking Contract
      • Run exSat native layer RPC Node
    • Trustless Bridge for Native Tokens
    • Trustless Bridge For ERC20 Tokens
    • Brief Intro to the Cross-Chain Communication
    • Brief Intro to the Custodian Bridge Services
    • Custodian Bridge for Non-BTC Tokens
    • Custodian Bridge for BTC
  • 🖥️User Guides
    • Wallet Setup
    • Bridge Your Assets
    • Earn Rewards via BTC Staking
    • Explore Our Ecosystem
  • Popular Token Contract Addresses
  • Set Up a Safe Wallet
  • 📚Reference
  • 📦Cutodian Guides
  • 🔐Security Reports
    • Audit Report From Blocksec
    • Audit Report From CertiK
  • 🔡Terms and Conditions
    • Terms Of Service
    • Privacy Policy
  • 🎁PR & Press
  • ☎️Contact US
Powered by GitBook
On this page
  • Basic concepts:
  • Reserved Address
  • Runtime Contract
  • Bridge Balance
  • EVM to Vaulta
  • Prerequisites:
  • Sending Messages
  • Fees
  • Error Handling
  • Vaulta to EVM
  • Prerequisites:
  • Generate EVM Transactions
  • Perform Read-only calls
  • Fees
  1. Developer Guides

Brief Intro to the Cross-Chain Communication

PreviousTrustless Bridge For ERC20 TokensNextBrief Intro to the Custodian Bridge Services

Last updated 3 days ago

The Exsat-EVM allow communication between the EVM layer and the native Vaulta layer. This doc will cover this topic.

Basic concepts:

Reserved Address

Each Vaulta account has a mapped reserved EVM address. The rule is using the uint64 value of the Vaulta name as the last 8 bytes of the EVM address, and then pad the rest with 0xbb. E.g. the name “eosio.evm” is mapped to “0xbbbbbbbbbbbbbbbbbbbbbbbb5530ea015b900000”

We will use addr_evm(vaulta_acct) to represent the reserved address of the vaulta_acct.

Runtime Contract

The Vaulta-EVM system is run in a way that each EVM transaction is actually part of Vaulta transactions. The EVM runtime contract will process Vaulta transactions invoking EVM transactions.

We will use evm_runtime to represent the Vaulta account of the evm runtime contract. Thus the reserved address of the evm runtime contract will be addr_evm(evm_runtime)

Bridge Balance

Each Vaulta account can call “open” action of EVM runtime to open a bridge balance. This balance can be used to hold “dusts” beyond Vaulta token precision and to hold the gas for call EVM contracts. User can deposit to this balance by sending some tokens to evm_runtime with the vaulta name of the target balance (in string) as memo.

We will call this balance the bridge balance.

EVM to Vaulta

Sending messages from EVM to Vaulta is done by the Bridge Massage mechanism.

Prerequisites:

The receiver Vaulta account receiver registered a message channel.

bridgereg(eosio::name receiver, eosio::name handler, const eosio::asset& min_fee)

A handler can be assigned to process this message. It can be the same account as the receiver.

The min_fee sets a minimum bridge fee for bridge messages in this channel. Details will be covered below.

Sending Messages

The EVM contracts should call bridgeMsgV0(string,bool,bytes) function at addr_evm(evm_runtime)

The three parameter for this call should be:

string receiver: the receiver vaulta name in string representation.

bool force_atomic: whether the call is atomic or not. Currently only atomic mode is supported. So this parameter should always be true.

bytes data: The message data sent to the Vaulta side.

The method is payable. Users can set a value to pay with the call.

After detected such calls, the EVM runtime contract will generate inline actons calling onbridgemsg(const bridge_message_t &message) action of the registered handler for the receiver

The message received by the handler is defined as:

struct bridge_message_v0 {
        eosio::name receiver;
        bytes sender;
        eosio::time_point timestamp;
        bytes value;
        bytes data;

        EOSLIB_SERIALIZE(bridge_message_v0, (receiver)(sender)(timestamp)(value)(data));
    };

Where

eosio::name receiver; // The receiver of the message. Handlers can use this to distinguish messages from different channels if a handler is linked to multiple receivers.
bytes sender; // The EVM address of the message sender.
eosio::time_point timestamp; // timestamp for the message
bytes value; // The value paid in the bridgeMsgV0 call
bytes data; // The actual message data

Fees

As mentioned above, the bridgeMsgV0 method is payable. Users can set a value to pay with the call. The value paid will go into the receiver’s balance in evm runtime contract. If a min_fee is set, the evm runtime will fail the call if the requirement is not met.

Error Handling

bridgeMsgV0 will ALWAYS succeed viewed from the EVM side. No logic should rely on the result of the call.

If anything is wrong during the message processing, the handler should consider failing the whole transaction if it does not want the EVM state to change.

Vaulta to EVM

Vaulta to EVM communication can be done by letting the Vaulta account generate EVM transactions by code.

Prerequisites:

The sender should call “open” at evm_runtime to open the bridge balance to pay for the EVM calls.

The sender should deposit some gas token to its bridge balance.

Generate EVM Transactions

Someone could call this action of the evm_runtime to generate an EVM transaction.

typedef std::vector<char>       bytes;

void call(eosio::name from, const bytes &to, const bytes& value, const bytes &data, uint64_t gas_limit);
eosio::name from // the eos_caller should be put here. Obviously you need the authorization from the eos_caller to proceed.
 const bytes &to // destination EVM address
 const bytes& value // payment value
 const bytes &data // calldata
 uint64_t gas_limit // gas limit

Perform Read-only calls

One could also call the exec action to call the view functions of EVM contracts. Currently the caller can only get the result via call_backs. Support for synchronously calls will be available after the next major Vaulta upgrade.

typedef std::vector<char>       bytes;

struct exec_input {
   std::optional<bytes> context;
   std::optional<bytes> from;
   bytes                to;
   bytes                data;
   std::optional<bytes> value;
};

struct exec_callback {
   name contract;
   name action;
};

// The callback action should accept this as input
struct exec_output {
   int32_t              status;
   bytes                data;
   std::optional<bytes> context;
};

void exec(const exec_input& input, const std::optional<exec_callback>& callback);

Fees

Payment value and gas fee will be deducted from the bridge balance of the vaulta_caller

👨‍💻