🤔Examples

Simple ERC20 bridging flow

A worked example for how to quote and bridge ERC20 funds between two EVM chains is as follows.

Let's say Alice has funds on Goerli wants to send herself UNI to the same address on Sepolia.

We know the following:

Source address : 0x8f058342605F6D819F1033e5e498dEc37a892e81
Source chain ID : 5
Token address : 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984 (UNI on Goerli)
Token amount : 0.1 (token is 18 decimals so this becomes 100000000000000000)
Destination address: 0x8f058342605F6D819F1033e5e498dEc37a892e81
Destination chain ID: 11155111
Destination token address : 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984 (UNI on Sepolia)

Step 1 : Quoting

Alice calls getBridgingQuote api with the parameters above to make sure the bridging params are acceptable.

/api/getBridgingQuote?chainFrom=5&chainTo=11155111&tokenFrom=0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984&tokenTo=0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984&amount=0.1

She might get a response akin to the following

{
	"destination_tokens_available": "1461465583173996160",
	"destination_tokens_available_dec": 1.46146558317399616,
	"error": "none",
	"estimated_bridge_time_seconds": 120,
	"fee_token_name": "UNI",
	"fee_token_total": "1916508538899431",
	"fee_token_total_dec": "0.001916508538899431",
	"fee_usd_equivalent_destination_dec": 0.0001,
	"fee_usd_equivalent_total_dec": 0.0101,
	"fee_usd_equivalent_volume_dec": 0
}

This shows her there are enough tokens at the destination and that her proposed bridging is allowed.

The response also shows her the fees she would expect to pay (fee_token_total_dec) as part of this transaction.

Step 2 : Building bridge tx

Alice would now build the payload data for the transaction based on the instructions found on the building bridge deposit page.

The expected structure of the payload is shown below, it contains information about where the funds she is bridging will be sent and an agreement of the amount she will receive and the fee that will be charged.

{
    "dest_chain": 11155111,
    "dest_token": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984 ",
    "dest_address": "0x8f058342605F6D819F1033e5e498dEc37a892e81",
    "dest_amount": 98083491461100600
}

This should then be encrypted and might yield something like this:

chpSgioHe5/O+To/4hx+CNyK4NkdQqWPxrvn56JuzGYEdjKK5VlGpMQbvaml7q9vsx4nxGdscxZuNeeWi8JB9+E6tp6TCuQ808JWoXMNgz/e3eQm4HENFsc5S6+m2m760Mstnx09ZRbRV8cTLiw5hK1oGL5pkqetYoTQQAs9QPp0EYP9UOXilCuzNVCnshVNb01dtol1i5U5QuvfEgJ7Oq8fiQx8A7MeUg3RBahMu1uDKqUPV/GK1qfri2r87NvZHDmo4jeiLTns/4VLNBfhSfEaWyLT3scCkctAriBrs8KPSXIpm47A6FLovzCfZd0Y7lwW6+HY1tg9+YQu0qeiBQ==

It is extremely important to correctly calculate the dest_amount as this will be the amount transferred at the destination. If this does not account for the fee (i.e. deposit amount - fee obtained from the API call) the transaction will be rejected.

Step 3 : Setting spending allowance

Alice should make sure she has granted sufficient allowance to the bridge contract.

To do this she would then call getBridgeContract on the chain she wants to bridge from, in this case Goerli. The call would might looks like this.

/api/getBridgeContract?chain=5

Returning

{
    "chain": "5",
    "contract": "0xa8e4f73333537abccbe51c6e122d68692b2b5ecc",
    "error": "none",
    "name": "Ethereum Goerli"
}

Using this address she can approve the bridge contract to spend 0.1 UNI.

Step 4 : Sending bridge tx

Bringing everything together, using this address and the payload information, Alice can then build and send her transaction to the bridge contract.

Once the transaction has been broadcast, she will see confirmation on chain.

Step 5 : Watch status of tx on neuron

Alice should then wait while the transaction is being confirmed by the chain watchers and credited at her destination chain.

She can do this by calling getHistory with the source transaction hash as the id paramater to see the current status of her bridge transaction.

{
    "destination_address": "0x8f058342605f6d819f1033e5e498dec37a892e81",
    "destination_amount": 0.0999946164629629,
    "destination_chain": "11155111",
    "destination_chain_tx": "",
    "destination_token": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984 ",
    "source_amount_dec": 0.1,
    "source_chain": "5",
    "source_chain_tx": "0x30885e4730b75852fd77fe57e5175176b60007a28534d913cb5ed916a78f22bb",
    "source_token": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984 ",
    "status": "Pending (0/10)",
    "timestamp": "23-07-12 12:27:45"
}

Step 6 : Funds credited at distination

Once the bridging is complete, the field destination_chain_tx will contain the transaction hash of the funds being credited at the destination chain.

Alice is happy.