Skip to content
Document

Bridging BYOC by sending transactions

This guide explains how to use transactions to bridge liquid cryptocurrencies recognized by PBC, generally referred to as Bring Your Own Coin (BYOC), from and to external chains.

For a guide to the bridging of BYOC with the bridge's UI see here.

A Partisia Blockchain account holds the necessary information enabling the user to perform transactions. Among other fields the account state includes a balance of BYOC. Users can transfer BYOC between accounts internally on PBC, we call this BYOC transfer. It is also possible to transfer BYOC from and to other chains, we call this action bridging.

How does the bridge work

The idea behind the bridge is to move cryptocurrencies to and from PBC. In the deposit and withdrawal examples below, we will show how to bridge ETH. The method works for all BYOCs on PBC. Currently, BYOCs include ETH, WMPC, BNB, USDC, MATIC and USDT.

Below you will learn which contracts and invocations are used for deposits and withdrawals. PBC nodes can read information on the native chains of the cryptocurrencies used for BYOC. In the case of a withdrawal, the user needs to provide information from the state of the withdrawal contract on PBC to the small oracle contract on the foreign chain. The transfer of cryptocurrencies to and from PBC is facilitated by deposit and withdrawal oracles.

Every time the bridge is used, 0.1% of transferred value is subtracted as a fee to pay for the service provided by oracle nodes. If you bridge 1 ETH, then 0.999 ETH is transferred and 0.001 ETH is paid to the oracle nodes.

How to make a deposit

BYOC acts as IOUs that can only be created when the equal sum of value is locked on the chain where the deposit comes from. The deposited coins are locked to the oracle contract on that chain. A deposit oracle consists of three PBC nodes, which monitor the BYOC contract for activity. When activity is detected and two out of three nodes of the oracle confirms a users locked funds, it invokes a contract action resulting in the minting of equivalent funds on PBC called BYOC.

DepositBridge

Deposit n amount of ETH from an ETH account to a PBC account

  1. Invoke the contract action deposit on the Small oracle contract on Ethereum:

    deposit(bytes21 destination, uint amount)
    
    • destination is the receiving PBC address decoded to bytes
    • amount is ETH converted to Wei, minimum amount is 0.01 ETH
  2. The contract locks n ETH

  3. The oracle nodes read the incoming transaction on the Small oracle contract on Ethereum
  4. The action deposit is invoked on ETH Deposit by the oracle nodes (the invocation requires 2/3 nodes to invoke with same input)
  5. Given that 2 of 3 oracle nodes invoked deposit the contract mints n BYOC twins
  6. (n - fee) ETH are added to the balance the PBC account
  7. The PBC wallet reads the account balance, now you have access to the deposited funds

How to make a withdrawal

When you withdraw funds from PBC the BYOCs are first burned on PBC, then when the withdrawal oracle nodes confirm this, they each generate a signature. You need these to unlock the funds from the contract on the native chain.

WithdrawBridge

Withdraw n amount of ETH from a PBC account

  1. Add a pending withdrawal on PBC by invoking the action addPendingWithdrawal at ETH Withdrawal:
 public ByocOutgoingContractState addPendingWithdrawal(
    SysContractContext context,
    ByocOutgoingContractState state,
    EthereumAddressRpc receiver,
    Unsigned256 amount)
  1. The ETH Withdrawal contract burns n ETH twins minus the fee to pay the oracle nodes
  2. When the ETH Withdrawal oracle confirms the ETH twins have been burned, they generate the signatures necessary for a release from the ETH contract. The signatures are available in the state of ETH Withdraw
  3. Retrieve the withdrawal nonce, signatures and bitmask from the ETH Withdrawal contract state, and wait until your withdrawal has received at least two out of three signatures (this takes from zero to a few minutes, depending on activity level of the bridge)
  4. Invoke the contract action withdraw on the small oracle contract on Ethereum, the action take an account address and the transferred amount:

    withdraw(uint64 withdrawNonce,
       address destination,
       uint amount,
       uint32 bitmask,
       bytes calldata signatures)
    
    • withdrawNonce is found in the JSON state field named "key"
    • you must subtract 0.1% (fee for oracle services) of the uint amount compared with the amount in step 1
    • uint32 bitmask express which oracle nodes that have signed the withdrawal, e.g. 101 first and last node signed, input the three bits as the equivalent decimal number: (101)2 = 5
    • For each signature, 27 is added to the recovery id of the PBC-signature. This id needs to be moved to the end of the signature. e.g. a PBC-signature with a hex value of 01/.../ gives ETH-signature /.../1c
  5. (n - fee) ETH are released from the Small oracle contract on Ethereum and again available for use by the owner the ETH account

Resources to get you started

You can use the MetaMask wallet to sign and send transaction for Ethereum, Polygon and BNB smartchain. This wallet is primarily designed for Ethereum, but can interact with the other chains as well.

On Partisia Blockchain the easiest solution is to use Partisia MetaMask Snap to sign your transaction. Alternatively you can use the Partisia Wallet.

Besides the wallets, you will need the addresses of the oracle contracts you want to interact with. Below is a complete list of our BYOC contracts on PBC and connected chains. On the testnet, test BYOC from the ETH Sepolia testnet is available to bridge in.

To use a standardized digital asset on PBC you need to align with the MPC-20 standard format.

Bridgeable coins on Mainnet

Currency Deposit oracle on PBC Withdrawal oracle on PBC Token contract on PBC Small oracle on native chain Large oracle on native chain Decimals
BNB BNB Deposit on PBC BNB Withdrawal on PBC BNB MPC20 on PBC Small oracle contract on BNB Smart Chain (0x05...9ac1) Large oracle contract on BNB Smart Chain 18
ETH ETH Deposit on PBC ETH Withdrawal on PBC ETH MPC20 on PBC Small oracle contract on Ethereum (0xf3...8e3c) Large oracle contract on Ethereum 18
USDT (Ethereum) ETHEREUM_USDT Deposit on PBC ETHEREUM_USDT Withdrawal on PBC ETHEREUM_USDT MPC20 on PBC Small oracle contract on Ethereum (0x74...4cA4) Large oracle contract on Ethereum 6
MATIC MATIC Deposit on PBC MATIC Withdrawal on PBC MATIC MPC20 on PBC Small oracle contract on Polygon (0xe9...7CC1) Large oracle contract on Polygon 18
USDC (Polygon) POLYGON_USDC Deposit on PBC POLYGON_USDC Withdrawal on PBC POLYGON_USDC MPC20 on PBC Small oracle contract on Polygon (0x4c...c26f) Large oracle contract on Polygon 6
WMPC WMPC Deposit on PBC WMPC Withdrawal on PBC WMPC MPC20 on PBC Small oracle contract on Ethereum (0x36...456e) Large oracle contract on Ethereum 4
WBTC (Ethereum) ETHEREUM_WBTC Deposit on PBC ETHEREUM_WBTC Withdrawal on PBC ETHEREUM_WBTC MPC20 on PBC Small oracle contract on Ethereum (0x71...1fd4) Large oracle contract on Ethereum 8

Bridgeable coins on Testnet and test coin faucet

Testnet Coin Deposit oracle on PBC Withdrawal oracle on PBC Token Contract on PBC Small oracle on native chain Large oracle on native chain Decimals
ETH SEPOLIA ETH_SEPOLIA Deposit on PBC testnet ETH_SEPOLIA Withdrawal on PBC testnet ETH_SEPOLIA MPC20 on PBC testnet Small oracle contract on Sepolia (0x54...F726) Large oracle contract on Sepolia 18
ETH GOERLI (Deprecated) ETH_GOERLI Deposit on PBC testnet ETH_GOERLI Withdrawal on PBC testnet ETH_GOERLI MPC20 on PBC testnet Small oracle contract on Ethereum testnet (0x48...31f3) Large oracle contract on Ethereum testnet 18
TEST COIN (not bridgeable) TEST_COIN Faucet NA TEST COIN Token on PBC testnet NA NA 0
WMPC WMPC Deposit on PBC testnet WMPC Withdrawal on PBC testnet WMPC MPC20 on PBC testnet Small oracle contract on Sepolia testnet Large oracle contract on Sepolia testnet 4