ERC20 Bridge

Search…
ERC20 Bridge
Cross chain transfer of erc20 tokens
Before we continue, please ensure that you have had a look at our Supported Ethereum Chains, followed the steps in Install Etherspot SDK and how to Bootstrap Etherspot SDK. We're assuming that you have completed these steps before going forward.
In this example, we're going to show you how to transfer from ERC20 token available on Ropsten Testnet to ERC20 token available on Sokol Testnet.
​🛑
 Before we continue...
We're going to be using four Etherspot SDK instances here:
A ropsten Etherspot SDK for our user wallet
A ropsten Etherspot SDK for the Payment Hub on this network
​↗
 We will use this instance to send our DAI from and ETH to pay the gas fees.
A sokol Etherspot SDK for our user wallet
A sokol Etherspot SDK for the Payment Hub on this network
​↘
 We will use this instance to receive our xDai on the xDai chain.
​⚠
 Make sure you've checked out Supported Ethereum Chains before you continue as we also show you the code to instantiate ropsten and sokol versions of the SDK. Remember to use the same private key or authentication for both SDK instances to get the same Ethereum address on both Ropsten Testnet and Sokol Testnet.
Getting started
First, let's install a prerequisite NPM package we're going to need. The erc-20-abi package will provide us with the ERC20 token interface to interact with.
NPM
YARN
1
npm i erc-20-abi
Copied!
1
yarn erc-20-abi
Copied!
Next, let's retrieve the the abi from the erc-20-abi package.
1
import { abi } from 'erc-20-abi';
Copied!
We're going to use two of the four instances of the Etherspot SDK as "Payment Hubs". 
Payment Hubs are nothing more than instances of the Etherspot SDK, but exist purely to hold funds for cross-chain transfer.
For this guide, we're going to transfer ETH from the Ropsten network to the Sokol network. To achieve this, we're going to send ETH from our user wallet to the Ropsten Payment Hub (which itself is an instance of the Etherspot SDK), and the Sokol Payment Hub (which, again, is another instance of the Etherspot SDK) will send the transferred amount back to the user's wallet on the Sokol network.
We're going to assume that we're working with the following definitions:
1
/**
2
* Payment Hubs
3
* - Network: Ropsten
4
* - const ropstenEtherspotPaymentHub
5
*
6
* - Network: Sokol
7
* - const sokolEtherspotPaymentHub
8
*
9
* User Wallets
10
* - Network: Ropsten
11
* - const ropstenEtherspotUser
12
*
13
* - Network: Sokol
14
* - const sokolEtherspotUser
15
*
16
* ERC20 Token Address
17
* - Network: Ropsten
18
* - const ropstenTopkenAddress
19
* - Network: Sokol
20
* - const sokolTokenAddress
21
*/
Copied!
Ensure Payment Hubs are funded
For this process to work, we need to make sure that the Payment Hubs have enough liquidity in them to facilitate the bridge transfer. We're going to be working with the p2pDepositAddress from the Payment Hub Etherspot SDKs. We can get this address as follows:
1
const { p2pDepositAddress } = ropstenEtherspotPaymentHub.state;
Copied!
The p2pDepositAddress exists purely to provide liquidity for other operations. Your address is unaffected.
We now need to add Test ETH from the Ropsten Faucet. Please follow the instructions on the Ropsten Faucet website to receive Test ETH to the p2pDepositAddress.
Once you have received the Test ETH and ERC20 tokens to the p2pDepositAddress in the ropstenEtherspotPaymentHub instance, we need to perform the same set of operations for the Sokol Payment Hub Etherspot SDK.
1
const { p2pDepositAddress } = sokolEtherspotPaymentHub.state;
Copied!
We now need to add Test ETH from the Sokol Faucet. Please follow the instructions on the Sokol Faucet website to receive Test ETH to the p2pDepositAddress.
We also need to fund ERC20 tokens to their respective chains. Some Test ERC20 tokens can be minted from their Contract methods or you can itself create ERC20 tokens and deploy on your desired chains.
Once both p2pDepositAddress from Sokol and Ropsten are funded with Test ETH from their respective faucets and ERC20 tokens from minting/deploying, we're ready to move on.
Add liquidity to the Payment Hubs
Now that our Payment Hubs are funded with Test ETH and ERC20 Tokens to their respective p2pDepositAddress, the next step is to update the Payment Hubs with the amount of liquidity we wish to provide from our respective p2pDepositAddress.
1
/**
2
* We're going to add 1 ERC20 Token(18 decimals) of liquidity to the
3
* Ropsten Payment Hub which is taken from the
4
* p2pDepositAddress.
5
*/ 
6
await ropstenHubSdk.updatePaymentHub({
7
  liquidity: ethers.utils.parseEther(1), // Token amount
8
  token: ropstenTokenAddress // erc20 token address you wish to transfer
9
})
10
.catch(console.error);
11
​
12
/**
13
* We're going to add 1 ERC20 Token(18 decimals) of liquidity to the
14
* Sokol Payment Hub which is taken from the
15
* p2pDepositAddress.
16
*/ 
17
await sokolHubSdk.updatePaymentHub({
18
  liquidity: ethers.utils.parseEther(1), // Token amount
19
  token: sokolTokenAddress // erc20 token you wish to withdraw as
20
})
21
.catch(console.error);
Copied!
Please ensure that the p2pDepositAddress has received enough erc20 tokens before adding liquidity using the code above.
Once we've completed the liquidity addition operation, we're ready to move on.
Activate the Payment Hub Bridge
In order to allow transfer from one chain to another, we need to activate the Payment Hub Bridge using the destination Payment Hub SDK instance. Here's how to achieve this:
1
import { NetworkNames } from 'etherspot';
2
​
3
await sokolEtherspotPaymentHub
4
 .activatePaymentHubBridge({
5
   acceptedNetworkName: "ropsten" as NetworkNames,
6
   acceptedToken: ropstenTokenAddress,
7
   token: sokolTokenAddress
8
 })
9
 .catch(console.error);
Copied!
Once the above step is completed, the destination Sokol Payment Hub bridged with the Ropsten network name and you're ready to move on to the next step.
Exchanging with the Payment Hubs
From our Ropsten user wallet, we first need to transfer the amount of ETH that we want to exchange to ETH on Sokol to our Ropsten user wallet's p2pDepositAddress. We will do this in the normal way that we usually send Transactions.
Before we continue, let's clear the Ropsten Etherspot SDK Transaction Batch queue. We're keeping the house clean 🧹
 
1
await ropstenEtherspotSdk.clearGatewayBatch();
Copied!
Next, we are going to encode the transaction data with parameters required to transfer the erc20 tokens using the abi method.
1
const erc20Contract = await ropstenHubSdk.registerContract('erc20Contract', abi, ropstenTokenAddress);
2
const transactionRequest = erc20Contract.encodeTransfer(
3
  ropstenHubSdk.state.p2pPaymentDepositAddress,
4
  ethers.utils.parseEther(value), // value you wish to transfer
5
);
Copied!
We're going to perform a series of steps to:
1.Add the encoded transaction to the batch
2.Estimate the gas required to perform this transaction
3.Send the batch to Etherspot to be processed
1
/**
2
* Step 1: Add the transaction (which instructs the DAI
3
* contract to perform a transfer to the Token Bridge
4
* contract address) to a clean "batch" of transactions.
5
*
6
* Note: You can batch many transactions together and
7
* submit them as one request for a more gas-efficient
8
* operation. Here, we're just adding 1 transaction to
9
* this batch.
10
*/
11
const batchResponse = await ropstenEtherspotSdk
12
  .batchExecuteAccountTransaction(transactionRequest)
13
  .catch(console.error);
14
​
15
/**
16
* Step 2: Estimate the gas required to perform this
17
* operation. This is useful for presenting to users
18
* and allowing them to make a final decision.
19
*/
20
const estimateResponse = await ropstenEtherspotSdk
21
  .estimateGatewayBatch()
22
  .catch(console.error);
23
​
24
/**
25
* Step 3: Finally, send this batch to Etherspot for
26
* processing. We'll manage the transaction, queuing,
27
* retries and endevour to do whatever it takes to
28
* get this transaction on the chosen blockchain.
29
*/
30
const submissionResponse = await ropstenEtherspotSdk
31
  .submitGatewayBatch()
32
  .catch(console.error);
Copied!
Make sure to transfer native tokens less than the available liquidity on the Payment Hubs.
Once the above batch transaction has been confirmed, we need to perform two steps:
1.Call the updatePaymentHubDeposit method on our users Ropsten Etherspot SDK with the reference to the Ropsten Payment Hub, and the amount we wish to make available from our p2pDepositAddress to the Ropsten Payment Hub
2.Call the transferPaymentHubDeposit method on our users Ropsten Etherspot SDK, which will instruct the Payment Hub to move the funds from one Payment Hub to the destination Payment Hub.
1
const exchangeAmount = ethers.utils.parseEther(valueInEth);
2
​
3
await ropstenEtherspotSdk.updatePaymentHubDeposit({
4
    hub: ropstenEtherspotPaymentHub.state.accountAddress,
5
    token: ropstenTokenAddress, // token you wish to exchange from
6
    totalAmount: exchangeAmount
7
}).catch(console.error);
8
​
9
await ropstenEtherspotSdk.transferPaymentHubDeposit({
10
    hub: ropstenEtherspotPaymentHub.state.accountAddress,
11
    token: ropstenTokenAddress, // token you wish to exchange from
12
    targetToken: sokolTokenAddress, // token you wish to exchange to
13
    targetHub: sokolEtherspotPaymentHub.state.accountAddress,
14
    targetNetworkName: "sokol" as NetworkNames,
15
    value: exchangeAmount,
16
}).catch(console.error);
Copied!
Once the above has been completed, the internal ledger operations of the Payment Hub mechanisms will move the available liquidity from the source Payment Hub on Ropsten to the destination Payment Hub on Sokol. We're now ready to withdraw the funds on the destination Payment Hub on Sokol.
Withdraw from the destination Payment Hub
To be able to withdraw the above exchangeAmount from the destination Sokol Payment Hub, we need to perform a few final steps. 
We're now working primarily with the Sokol Payment Hub Etherspot SDK and the Sokol User Etherspot SDK.
First, we need to instruct the Sokol User Etherspot SDK instance that we are going to make a withdrawal by calling the updatePaymentHubDeposit method on the Sokol Etherspot User's SDK instance.
1
/**
2
* Note: Setting `totalAmount` to 0 instructs the
3
* PaymentHub that we want to make a withdrawal.
4
*/
5
await sokolEtherspotUser.updatePaymentHubDeposit({
6
  hub: ropstenEtherspotPaymentHub.state.accountAddress,
7
  token: sokolTokenAddress, // token address on receiver's chain(sokol)
8
  totalAmount: 0, // See note above.
9
}).catch(console.error);
Copied!
Internally a new hash has been created, which we will later find and sign to allow the withdrawal to take place. This process allows Etherspot to make the necessary liquidity checks before allowing the withdrawal to take place.
The next step is to find the transaction hash which needs to be signed from the Sokol Payment Hub. We'll  first retrieve a list of uncommitted Payment Hub transaction items.
1
const uncommittedPaymentChannels = await sokolEtherspotPaymentHub
2
  .getP2PPaymentChannels({
3
    uncommittedOnly: true, // Filter to return uncommitted Payment channels by the receiver
4
  })
5
  .catch(console.error);
Copied!
We then need to find the transaction hash to be signed. For the purposes of this guide, we're going to assume that there is just one uncommitted Payment Channel returned from the getP2PPaymentChannels method call.
1
const paymentHubChannel = uncommittedPaymentChannels.items[0];
Copied!
Once we have this information, we're going to perform a basic validation check to check two things:
1.That the paymentHubChannel.state is "Opened"
2.That the sokolEtherspotUser.state.accountAddress and the paymentHubChannel.recipient are the same
1
let paymentChannelHash = null;
2
​
3
if (
4
  paymentHubChannel.state == "Opened" &&
5
  sokolEtherspotUser.state.accountAddress === paymentHubChannel.recipient
6
) {
7
  paymentChannelHash = paymentHubChannel.hash;
8
}
Copied!
Providing that the two above validation points are true, we can sign the Payment Channel hash and commit the Payment Channel. 
1
await sokolEtherspotPaymentHub
2
  .signP2PPaymentChannel({
3
    paymentChannelHash,
4
  })
5
  .catch(console.error);
6
    
7
// `paymentChannelHash` has now been signed by the Payment Hub
Copied!
Committing the Payment Channel with with the signed hash from the previous code example moves the exchangeAmount to the final destination address.
1
/*
2
* Remember to clear your batch and keep the house clean!
3
*/
4
await sokolEtherspotUser.clearGatewayBatch();
5
​
6
/**
7
* Next, commit the Payment Channel. The 
8
* batchCommitP2PPaymentChannel takes an object with two
9
* properties:
10
* - paymentChannelHash: the previously signed Payment channel hash
11
* - deposit: 
12
* - - true: the exchange amount is transferred to the p2pDepositAddress.
13
* - - false: the exchange amount is transferred to the accountAddress
14
*/
15
await sokolEtherspotUser.batchCommitP2PPaymentChannel({
16
  paymentChannelHash,
17
  deposit: false, // See notes above
18
}).catch(console.error);
19
​
20
/**
21
* Next, we estimate the cost of the transaction...
22
*/
23
await sokolEtherspotUser
24
 .estimateGatewayBatch();
25
​
26
/**
27
* And finally we submit this to the ETherspot Gateway.
28
*/
29
await sokolEtherspotUser
30
  .submitGatewayBatch();
Copied!
Once you have finished making one or more transactions against the hubs, we are going to commit the Payment Channels that was created by the sender Payment Hub. This is the last step to be completed with the Payment Hub transactions as there could be many transfers between the Etherspot User SDK and the Payment Hub. The next step will total-up the amount transferred so that just a single, minimal gas fee is paid.
To commit the Payment Channel, we need to get the hash generated for the Payment Channel that was previously created. This can be obtained by calling getP2PPaymentChannels on the Etherspot SDK.
Firstly, retrieve a list of uncommitted Payment Hub transaction items.
1
/**
2
* uncommittedOnly: true - Filter to return uncommitted 
3
* Payment Channels.
4
*/
5
const uncommittedPaymentChannels = await ropstenEtherspotPaymentHub
6
  .getP2PPaymentChannels({
7
    uncommittedOnly: true, // See note above
8
  })
9
  .catch(console.error);
Copied!
For the purposes of this guide, we're going to assume that there is just one uncommitted Payment Channel returned from the getP2PPaymentChannels method call.
1
const paymentHubChannel = uncommittedPaymentChannels.items[0];
Copied!
Once we have this information, we're going to perform a basic validation check to check two things:
1.That the paymentHubChannel.state is "Signed"
2.That the ropstenEtherspotUser.state.accountAddress and the paymentHubChannel.recipient are the same
1
let paymentChannelHash = null;
2
​
3
if (
4
  paymentHubChannel.state == "Signed" &&
5
  ropstenEtherspotUser.state.accountAddress === paymentHubChannel.recipient
6
) {
7
  paymentChannelHash = paymentHubChannel.hash;
8
}
Copied!
Providing that the two above validation points are true, we can commit the Payment Channel to receive the total amount of funds transferred from your Etherspot SDK p2pDepositAddress  to sender's Payment Hub p2pDepositAddress.
1
/*
2
* Remember to clear your batch and keep the house clean!
3
*/
4
await ropstenEtherspotUser.clearGatewayBatch();
5
​
6
/**
7
* Next, commit the Payment Channel. The 
8
* batchCommitP2PPaymentChannel takes an object with two
9
* properties:
10
* - paymentChannelHash: the previously signed Payment channel hash
11
* - deposit: 
12
* - - true: the exchange amount is transferred to the p2pDepositAddress.
13
* - - false: the exchange amount is transferred to the accountAddress
14
*/
15
await ropstenEtherspotUser.batchCommitP2PPaymentChannel({
16
  paymentChannelHash,
17
  deposit: true, // See notes above
18
}).catch(console.error);
19
​
20
/**
21
* Next, we estimate the cost of the transaction...
22
*/
23
await ropstenEtherspotUser
24
 .estimateGatewayBatch();
25
​
26
/**
27
* And finally we submit this to the ETherspot Gateway.
28
*/
29
await ropstenEtherspotUser
30
  .submitGatewayBatch();
Copied!
​🎉
 Finished!