🏗️Building bridge deposit

To initiate a bridge transaction a user should send a transaction to the bridge smart contract on the source chain calling a specific method on the smart contract depending on whether native tokens or ERC20 tokens are being bridged.

Native token (ETH) interactions

Users should call the depositNative method on the source chain smart contract.

This function takes one parameter:

• payload(string): encrypted block with destination data

See payload encoding below to understand how to encode payload data.

Transactions with invalid payload data will be rejected and may result in funds locked in bridge contracts. It is extremely important to construct the payload according to instructions found in this documentation.

ERC20 interactions

Users should call the deposit method on the source chain smart contract.

This function takes three parameters:

• token(address): the address of the ERC20 being transferred

• amount(uint256): amound being transferred

• payload(string): encrypted block with destination data

See payload encoding below to understand how to encode payload data.

Transactions with invalid payload data will be rejected and may result in funds locked in bridge contracts. It is extremely important to construct the payload according to instructions found in this documentation.

Payload encoding

The payload is an encrypted json which is included as part of the contract call making the single blockchain interaction all that's required to trigger a private deposit process.

The expected structure of the payload is shown below.

{
    "dest_chain": 123456,
    "dest_token": "0x1234567890...",
    "dest_address": "0x1234567890...",
    "dest_amount": 1000000000000
}

The dest_amount param contains the value expected at the destination and is calculated based on the amount of the token that was deposited, minus the operator and broadcast fee that can be determined by calling getBridgingQuote.

This json block should be encrypted using the operator key below.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAstGb5VVGRCuXLNiYy5Lp
d0OydrxwS2A1ZRMTp41Q3NyaQuAVo5KYp5wPcZ2Rp+ExzNxDKMWWJXWXeUNEUMKM
8h5TO6khTShru2ffw2HMvnd6W9/MWiN/lGczsXrp9ITRcCu8F238u0s8vvlmkQnU
gUrU9Xk1TKWV1fno0fzPuFxQTaBuv0QAKIbxjDKgcHnUG1+NPlHfPTUd0SFIPKHq
vaCQhT+4rBztCg0xcd0OvOVRZUq4W11D+enPU9bAWTEMYo5B5YqDbPr7lDW31qNu
yew/0A4jhKS70+HfCr8fxwGJ7n+RhaLk9CtJ0Gz9G9hbAClNYnuhgviHROV7vW6R
QwIDAQAB
-----END PUBLIC KEY-----

An example of how this can be done using the JSEncrypt library is shown below.

function getEncryptedTxParams(destChain, destToken, destAddress, destAmountWei) {
    var crypt = new JSEncrypt();
    var pubkey =`-----BEGIN PUBLIC KEY-----...`;
    crypt.setKey(pubkey);

    var params = `{
        "dest_chain": ${destChain},
        "dest_token": "${destToken}",
        "dest_address": "${destAddress}",
        "dest_amount": ${destAmountWei}
    }`;
    
    var encParams = crypt.encrypt(params);
    return encParams;
}

For a detailed example of how to combine APIs with building a bridge deposit, see examples.

Mistakes to avoid

Invalid or unsupported dest_chain (check API)

Invalid or unsupported dest_token (check API - only some routes are permitted)

Destination amount too high or too low:

• if the destination amount is greater than the input amount deposited minus fee (check API) the deposit will be rejected and funds locked

• if the destination amount is set too low i.e. much lower than the input amount deposited minus fee it will be considered a fee and kept by the protocol, only the dest_amount will be credited at the destination

{
    "dest_chain": 123456,
    "dest_token": "0x1234567890...",
    "dest_address": "0x1234567890...",
    "dest_amount": 1000000000000
}

Partner integrations for referrals

To be eligible to collect referral rewards as part of the partnership program, an additional parameter is required within the bridging payload.

The ref key should contain the partner Ethereum address where payment will be sent.

{
    "dest_chain": 123456,
    "dest_token": "0x1234567890...",
    "dest_address": "0x1234567890...",
    "dest_amount": 1000000000000,
    "ref": "0x1234567890..."
}