Skip to content

Latest commit

 

History

History
348 lines (243 loc) · 20.3 KB

crosschain.md

File metadata and controls

348 lines (243 loc) · 20.3 KB

Balanced and xCall

Balanced supports cross-chain interactions, facilitating seamless asset and data transfers between different blockchain networks. This functionality is underpinned by a hub-and-spoke design, wherein all cross-chain communication, facilitated by the xCall protocol, either originates from or terminates at the ICON hub for all Balanced logic. The spokes, or individual blockchain networks, do not communicate directly with each other.

How Balanced Uses xCall

xCall is integral to Balanced’s cross-chain communication capabilities. It serves as the cross-chain messaging protocol that enables Balanced to transmit and receive messages between different blockchain networks. The protocol employs Recursive Length Prefix (RLP) encoding as its underlying mechanism to ensure standardized and efficient message encoding.

In the Balanced architecture, xCall Manager contracts are deployed on each spoke chain. These contracts are responsible for configuring and verifying the protocols specified by xCall, ensuring the integrity of cross-chain communications. Specifically, they manage the addresses of the intermediary contracts that xCall uses to facilitate these interactions.

The governance contract on the ICON (Hub) blockchain plays a critical role in the management of xCall protocols. It is responsible for setting and updating the protocols in the spoke chains, including the intermediary contract addresses that xCall will utilize. The governance contract uses xCall to propagate these protocol settings to the spoke chains, ensuring consistency and proper configuration across the entire network.

What Contracts Use xCall?

There are mainly three contracts that exist on all the Balanced spoke chains:

1. Asset Manager Contract

The spoke Asset Manager contract in the Balanced ecosystem plays a critical role in facilitating secure and efficient cross-chain transactions. By integrating with the ICON Asset Manager and the xCall Manager, it ensures smooth token deposits, withdrawals, and overall management of user assets. The contract's configuration and validation mechanisms, along with the rate limit feature, enhance the security and functionality of the Balanced platform.

Configuration and Validation

In the spoke Asset Manager contract, the ICON (hub) Asset Manager contract is set as an authorized entity. This configuration allows the spoke Asset Manager to send messages to the ICON Asset Manager contract. Additionally, the spoke Asset Manager is capable of validating incoming messages to ensure they originate from the ICON Asset Manager contract.

The spoke Asset Manager contract is also configured to interact with the spoke xCall Manager contract. This setup allows it to obtain the necessary protocols for performing cross-chain transactions via xCall. The xCall configuration within the Asset Manager ensures that it can identify xCall requests and validate messages received through xCall.

Rate Limits

The Asset Manager contract includes a rate limit feature, which is used to configure limits for each token deposited in Balanced. This ensures that a specified amount of each token must remain in the spoke Asset Manager contract, preventing excessive withdrawals and maintaining liquidity.

Token Deposits and Cross-Chain Transactions

The Asset Manager contract on the spoke chain accepts deposits of various tokens, including native tokens. Upon receiving a deposit, it locks the tokens within the contract. Subsequently, it sends a deposit message to the ICON (hub) Asset Manager contract via xCall. The ICON Asset Manager processes this message and mints an equivalent amount of wrapped tokens for the user on the ICON chain.

In the event that the cross-chain transaction fails at any point, a rollback transaction is initiated to refund the deposited tokens to the user.

Withdrawals

Users holding wrapped tokens on the ICON chain can initiate a withdrawal transaction. These wrapped tokens are treated as the real tokens within the Balanced platform. When a user requests a withdrawal, the ICON Asset Manager burns the wrapped tokens and sends a message to the spoke Asset Manager contract. The spoke Asset Manager then releases the corresponding amount of native tokens back to the user.

Utilization of Tokens in the Balanced Platform

Users with token balances from any chain within the Balanced platform can engage in various activities offered by the platform, such as swaps, cross-chain swaps, loans, and liquidity provision.

2. Balanced Dollar Contract

Balanced stablecoin, bnUSD, will be deployed as a native stablecoin on each spoke chain. To facilitate this, a dedicated Balanced Dollar contract will be implemented on each spoke chain. The integration of bnUSD across spoke chains enhances the liquidity and functionality of the Balanced ecosystem. By utilizing a burn and mint mechanism facilitated by xCall, users can seamlessly transfer and withdraw bnUSD between the ICON (Hub) and spoke chains. The careful configuration of the Balanced Dollar contracts ensures secure and efficient cross-chain operations, allowing users to leverage bnUSD for various financial activities across different blockchain networks.

Configuration and Validation

In the Balanced Dollar contract on each spoke chain, the ICON (Hub) Balanced Dollar contract is set as an authorized entity. This configuration allows the spoke Balanced Dollar contract to send messages to the ICON Balanced Dollar contract and validate incoming messages to ensure they originate from the ICON contract.

The spoke Balanced Dollar contract is also configured to interact with the xCall Manager contract. This setup allows it to obtain the necessary protocols for performing cross-chain transactions via xCall. The xCall configuration within the Balanced Dollar contract ensures that it can identify xCall requests and validate messages received through xCall.

Cross-Chain Transfer and Withdrawal Mechanism

Balanced employs a burn and mint mechanism for handling cross-chain transfers and withdrawals of bnUSD:

  • When a user initiates a cross-chain transfer in the spoke Balanced Dollar contract (i.e., transferring bnUSD to the ICON chain), the user's bnUSD balance is burned.
  • xCall is used to pass a cross-transfer message to the ICON Balanced Dollar contract.
  • Upon receiving the encoded message, the Balanced Dollar contract on the ICON chain decodes it and relays the message to the correct bnUSD contract on the target chain.
  • bnUSD is minted on the target chain. In the event that a cross-chain transaction fails at any point, a rollback transaction is initiated to refund the bnUSD to the user.

3. xCall Manager Contract

The xCall Manager contract is a crucial component in the Balanced ecosystem, responsible for managing and facilitating cross-chain communications. It ensures that messages and transactions between different blockchain networks are secure, validated, and properly routed.

Configuration and Validation

In the xCall Manager contract is the proxy of the ICON governance contract managing the Balanced DAO spoke contracts on a specific chain.

Ownership Proxy

TODO

Protocol Management

The ICON governance contract plays a crucial role in managing the protocols used for cross-chain communication:

  • Setting Protocols:

    • The ICON governance contract is responsible for setting the protocols in the spoke xCall Manager contract.
    • These protocols are essential for ensuring consistent and secure cross-chain interactions.

  • Removing and Modifying Protocols:

    • Protocols can also be removed or updated in the xCall Manager contract as needed.
    • The modified protocols can be retrieved through an API, ensuring that all components of the network are updated with the latest configurations.

  • Protocol Utilization:

    • The spoke Asset Manager and the spoke Balanced Dollar contracts use the same protocols that are configured on the xCall Manager contract, ensuring proper and clear cross-chain communication.

Internal Cross-Chain Message Structures in Balanced

Balanced is a multi-chain decentralized application (DApp) designed with a hub-and-spoke architecture, supporting various programming languages for smart contracts across different blockchains. To ensure efficient, secure, and reliable cross-chain transactions, messages transferred between the hub (ICON) and spokes must adhere to specific structures. These messages, transmitted via xCall, are encoded on one side and decoded on the other, maintaining consistency in data structure across all chains.

Regardless of the blockchain's external methods, the message structures must remain uniform. This consistency ensures that the ICON hub receives messages in the same format from any spoke chain, and vice versa. Below are the defined message structures used for cross-chain communication in the Balanced platform:

ICON RLP

TODO: explain differences of ICON RLP And EVM RLP

Asset Manager Contract

  1. Deposit This structure is used to deposit tokens from a spoke chain to the ICON hub.

    Data Structure:

    [
    "Deposit",
    Address <Token>,
    Address <Depositor>,
    NetworkAddress <Receiver>,
    Number <Amount>,
    Bytes <Data>
]

  2. Deposit Revert This structure handles reverting a deposit if the cross-chain transaction fails.

    Data Structure:

    [
    "DepositRevert",
    Address <Token>,
    Address <Receiver>,
    Number <Amount>
]

  3. Withdraw To This structure is used for withdrawing tokens from the ICON hub to a spoke chain.

    Data Structure:

    [
    "WithdrawTo",
    Address <Token>,
    NetworkAddress <Receiver>,
    Number <Amount>
]

Balanced Dollar Contract

  1. Cross Transfer This structure is used for transferring bnUSD across chains.

    Data Structure:

    [
    "CrossTransfer",
    Address <Token>,
    Address <Sender>,
    NetworkAddress <Receiver>,
    Number <Amount>
]

  2. Cross Transfer Revert This structure handles reverting a cross transfer if the transaction fails.

    Data Structure:

    [
    "CrossTransferRevert",
    Address <Token>,
    Address <Receiver>,
    Number <Amount>
]

xCall Manager Contract

  1. Configure Protocol

    This structure is used to configure protocols in the xCall Manager.

    Data Structure:

    [
    "ConfigureProtocol",
    String[] <Source protocols>,
    String[] <Destination protocols>
]

  2. Execute

    This structure is used to execute an arbitrary method as defined in the ExecutionData. As arbitrary method calls are not supported in some languages like SUI and Stellar, this is not included in those chains.

    Data Structure:

    [
    "Execute",
    Address <Manager>,
    NetworkAddress <ProtocolAddress>,
    Bytes <ExecutionData>
]

Consistent message structures are critical for maintaining the integrity and reliability of cross-chain transactions within the Balanced ecosystem. By adhering to these standardized formats, the platform ensures smooth and secure communication between the ICON hub and various spoke chains, regardless of their underlying programming languages or external methods.secure communication between the ICON hub and various spoke chains, regardless of their underlying programming languages or external methods.

Supported Blockchains on Balanced

Balanced currently supports all blockchains that are compatible with the xCall protocol. ICON serves as the hub, maintaining a record of balances for all tokens held by users across various spoke chains.

Balanced's support for a wide range of blockchains through the xCall protocol enables robust cross-chain functionality and interoperability. The carefully designed smart contracts, tailored to the specific languages and frameworks of each blockchain, ensure secure and efficient operations across the entire ecosystem. By leveraging the strengths of each blockchain's technology stack, Balanced provides a seamless and integrated experience for users across multiple networks. The supported spoke chains are:

  • Archway
  • Avalanche
  • Injective
  • Ethereum
  • Binance Smart Chain (BSC)
  • Base
  • Arbitrum
  • SUI
  • Stellar
  • Solana

Methods Involved in Cross-Chain Communications in Balanced

Cross-chain communication in the Balanced ecosystem involves multiple blockchains, each potentially supporting different programming languages for their smart contracts. Due to the inherent differences in language design, it is impractical to maintain identical external method signatures across all chains. Nevertheless, the Balanced architecture is designed to facilitate seamless cross-chain interactions, ensuring that while method signatures may vary, the core functionalities remain consistent.

Contract Details on Each Blockchain

Balanced utilizes a diverse codebase tailored to the programming languages and frameworks prevalent on each supported blockchain. The details of the smart contracts on each blockchain are as follows:

EVM-Compatible Blockchains (Ethereum, Binance Smart Chain, Avalanche, Base, Arbitrum)

  • Programming Language: Solidity
  • Role: Implements the same set of smart contracts across all EVM-compatible blockchains, ensuring uniform functionality and interoperability. These contracts handle token operations, cross-chain communication, and interaction with the xCall protocol.

Cosmos-Related Blockchains (Archway, Injective)

  • Programming Language: Rust
  • Role: Utilizes Rust for the development of smart contracts, ensuring robust and secure operations. These contracts are designed to manage token transactions and facilitate cross-chain activities using the xCall protocol.

SUI

  • Programming Language: SUI Move (a framework of Rust)
  • Role: The smart contracts on SUI are written in the SUI Move framework, leveraging Rust's safety and performance. These contracts manage token operations and cross-chain interactions specific to the SUI ecosystem.

For SUI Specific docs see : Balanced SUI

Stellar

  • Programming Language: Soroban (a framework of Rust)
  • Role: Stellar contracts are written using the Soroban framework, designed for the Stellar network. These contracts handle token transactions and cross-chain communications, ensuring seamless integration with the Balanced ecosystem.

Solana

  • Programming Language: Rust (Solana framework)
  • Role: Solana smart contracts are developed in Rust using the Solana framework. They manage token activities and cross-chain interactions, ensuring efficient and secure operations within the Solana network.