Skip to main content

XBI Specification

Global XBI Types​

pub type AccountId32 = sp_runtime::AccountId32;
pub type AccountId20 = sp_core::H160;
pub type AssetId = u32;
pub type Data = Vec<u8>;
pub type Id = sp_core::H256;
pub type Gas = u64;
pub type Value = u128; 
pub type ValueEvm = sp_core::U256;
pub type Target = u32;
pub type Timeout = u32;

XBI Metadata​

pub struct XBIMetadata {
    pub id: Id,
    pub dest_para_id: Target,
    pub src_para_id: Target,
    pub sent: Timeout,
    pub delivered: Timeout,
    pub executed: Timeout,
    pub max_exec_cost: Value,
    pub max_notifications_cost: Value,
    pub maybe_known_origin: Option<AccountId32>,
    pub maybe_fee_asset_id: Option<AssetId>,
}

id​

Assign your ID to XBI, enabling the search engines to scrape through the XBI Orders across the Parachains Storage Only XBI Orders with distinct IDs are dispatched via XCM.

dest_para_id​

Parachain ID targeted to execute XBI.

src_para_id​

Parachain ID dispatching the XBI.

sent​

Timeout in seconds (hence independent of source Parachain block time) before XBI is sent from source Parachain via XCM. Resolves XBI::Result with ErrorSentTimeoutExceeded if dispatch queues from the source took too long to dispatch.

delivered​

Timeout in seconds (hence independent of target/transition Parachain block time) before XBI is delivered and reaches destination Parachain. Resolves XBI::Result with ErrorDeliveryTimeoutExceeded if before the dispatch to XBI check-in queue on the target Parachain the delivery timeout measured relatively to the sent timeout was exceeded.

executed​

Timeout in seconds (hence independent of target Parachain block time) before XBI starts executing. Resolves XBI::Result with ErrorExecutionTimeoutExceeded if before the execution on target Parachain the executed timeout measured relatively to the delivered timeout was exceeded.

max_exec_cost​

Maximum allowed execution costs on the destination Parachain. If no maybe_fee_asset_id is set, it's measured as the Parachain native currency units. Injects automatically into gas_limit for Smart Contract calls.

max_notifications_cost​

Maximum allowed notification costs of the spending to retrieve a result from either source or destination Parachains. If no maybe_fee_asset_id is set, it's measured in the units of native to Parachain currency.

maybe_known_origin​

Optional Metadata field allowing to specify the dispatching Origin.

maybe_fee_asset_id​

Optional Metadata field that changes max_exec_cost and max_notifications_cost as well as actual_aggregated_costs of XBI::Result to different currency with defined trade mechanics on source Parachain.

XBI Instructions​

Dynamically defined (without the necessity of runtime upgrades to all Parachains that communicate using XBI) set of Instructions to dispatch on target using XBI Format. It is expected for Parachains to only support a selected set of XBI Instructions, defaulting to XBI::Unknown if a given XBI Instruction isn't supported by the target. This is enabled thanks to the custom XBI codec.

0 - Unknown​

Default to all of the unknown to target Parachain XBI Instructions

    // 0
    Unknown {
        identifier: u8,
        params: Vec<u8>,
    }

1 - CallNative​

Very generic Instruction assuming target Parachain implements the rules of decoding payload into dispatchable arguments to any Substrate Runtime Call.

    // 1
    CallNative {
      payload: Data,
    }

2 - CallEvm​

Call an EVM smart contract on the target Parachain.

    // 2
    CallEvm {
      source: AccountId20,
      target: AccountId20,
      value: ValueEvm,
      input: Data,
      gas_limit: Gas,
      max_fee_per_gas: ValueEvm,
      max_priority_fee_per_gas: Option<ValueEvm>,
      nonce: Option<ValueEvm>,
      access_list: Vec<(AccountId20, Vec<Id>)>,
    }

3 - CallWasm​

Call a WASM smart contract (implemented by Substrate's Pallet Contracts) on the target Parachain.

    // 3
    CallWasm {
      dest: AccountId32,
      value: Value,
      gas_limit: Gas,
      storage_deposit_limit: Option<Value>,
      data: Data,
    }

4 - CallCustomVM​

Call a custom smart contract Virtual Machine on target Parachain.

    // 4
    CallCustomVM {
      caller: AccountId32,
      dest: AccountId32,
      value: Value,
      input: Data,
      limit: Gas,
      additional_params: Data,
  }

5 - Transfer​

Transfer native to source Parachain currency to target

    // 5
    Transfer {
        dest: AccountId32,
        value: Value,
    }

6 - TransferAssets​

Transfer fungible currency of given asset_id supported by source Parachain to a target supporting the same currency. 

    // 6
    TransferAssets {
        currency_id: AssetId,
        dest: AccountId32,
        value: Value,
    },

7 - Swap​

Swap fungible currency of the given asset_in to another currency of asset_out. Target Parachain implements asset ids' trade mechanics and conversions to fungible currencies.

    // 7
    Swap {
      asset_out: AssetId,
      asset_in: AssetId,
      amount: Value,
      max_limit: Value,
      discount: bool,
    },

8 - Add Liquidity​

Add liquidity in two fungible currencies, A and B, to a DeFi pool implemented on target Parachain. Target Parachain implements the conversions of asset ids to fungible currencies.

    // 8
    AddLiquidity {
        asset_a: AssetId,
        asset_b: AssetId,
        amount_a: Value,
        amount_b_max_limit: Value,
    },

9 - Remove Liquidity​

Remove liquidity of two fungible currencies, A and B, from a DeFi pool implemented on target Parachain based on the amount of LP-share (liquidity amount). Target Parachain implements the conversions of asset ids to fungible currencies.

    // 9
    RemoveLiquidity {
        asset_a: AssetId,
        asset_b: AssetId,
        liquidity_amount: Value,
    },

10 - Get Price​

Gets the price exchanging amount of currency A to currency B on Target Parachain that implements the trade mechanics and conversions of asset ids to fungible currencies.

    // 10
    GetPrice {
        asset_a: AssetId,
        asset_b: AssetId,
        amount: Value,
    },

255 - Result​

XBI Result accompanying each XBI Instruction. With XBI, users get the guarantee that each XBI order will be resolved with one of the following outcomes:

pub enum XBICheckOutStatus {
  // Success scenario
  SuccessfullyExecuted,
  
  // Failed execution scenarios
  ErrorFailedExecution,
  ErrorFailedOnXCMDispatch,
  
  // Failed with exceeded costs scenarios
  ErrorExecutionCostsExceededAllowedMax,
  ErrorNotificationsCostsExceededAllowedMax,
  
  // Failed with exceeded timeout scenarios
  ErrorSentTimeoutExceeded,
  ErrorDeliveryTimeoutExceeded,
  ErrorExecutionTimeoutExceeded,
}

The future extensions to XBI foresee communication with remote to Polkadot consensus systems. Therefore field witness is already included as part of XBI Result and defaults to an empty bytes vector for all executions that target Parachain.

    // 255
    Result {
        outcome: XBICheckOutStatus,
        output: Data,
        witness: Data,
        actual_aggregated_costs: Value,
    },