Products
Tutorials
Get in touch
SDK
Javascript SDK for doing cross-chain transactions
Introduction
Hyphen SDK, is a javascript based SDK written in typescript that helps in integrating Hyphen services easily. It provides some helper methods that makes the Hyphen integration too easy. Even though you can just interact with LiquidityPoolManager smart contract directly and deposit the tokens using depositErc20 method from your DApp and do the deposit transactions but using SDK is recommended as it provides methods like checking available liquidity before doing the transaction, checking exit transaction status, checking approvals etc.
Lets get started
1. Installation
Via NPM
Via Yarn
1
npm install @biconomy/hyphen
Copied!
1
yarn add @biconomy/hyphen
Copied!
2. Importing and Instantiation
HYPHEN accepts a provider object as first argument and an option object as second argument.
1
import { Hyphen, SIGNATURE_TYPES } from "@biconomy/hyphen";
2
β
3
let hyphen = new Hyphen(<Provider Object>, {
4
debug: true, // If 'true', it prints debug logs on console window
5
environment: "test", // It can be "test" or "prod"
6
onFundsTransfered: (data) => {
7
// Optional Callback method which will be called when funds transfer across
8
// chains will be completed
9
}
10
});
Copied!
Note: <Provider Object> is the provider object exposed by your connected wallet. It can be window.ethereum for Metamask or portis.provider for Portis and so on. First provider object should be a provider object with accounts information.
It can be a JSON RPC Provider object or HttpProvider object with an RPC URL also given that you have passed walletProvider object in the options and Biconomy support is present. Check Network Agnostic Support section.
3. Initialisation
After the SDK object is instantiated you need to initialise the SDK by calling its init function. The initialisation is kept separated from the constructor to give flexibility to developer to use await statement for initialising the SDK.
1
await hyphen.init();
Copied!
Keep your code in a try-catch block to catch any error that might be thrown from the SDK during instantiation or initialisation.
Time to do a Cross-Chain Transfer
Before we proceed lets define some terms which will be used frequently in this documentation
Terms
Definition
toChain
Target chain where the funds needs to be transferred.
fromChain
Source chain from where the funds needs to be transferred to toChain
toChainId
chain id of the target chain where funds needs to be transferred
fromChainId
chain id of the source chain from where funds needs to be transferred
LiquidityPoolManager
Smart Contract where liquidity is present. It is pre-deployed on each supported chains by Biconomy.
Now that we have initialised the SDK and defined the terms we can do the cross-chain transfer transaction. In order to do a cross-chain transfer some pre-checks needs to be done and some pre-actions needs to be taken if required.
SDK provides methods to do these pre-checks and do some pre-actions so you don't have to write extra code to do the same.
Pre-Checks
- There should be enough liquidity on toChain where funds needs to be transferred.
- Given token address and chain ids should be supported.
- Enough approval should be given by the user to LiquidityPoolManager contract on fromChain for the given token which needs to be transferred.
These checks can be done using the method preDepositStatus that will check for a given fromChainId, toChainId, tokenAddress, userAddress and amount, wether there is enough liquidity on toChain, the given tokenAddress is supported, enough approval is given by the user to LiquidityPoolManager contract on fromChain and the networks are supported or not.
1
import { RESPONSE_CODES } from "@biconomy/hyphen";
2
β
3
let preTransferStatus = await hyphen.preDepositStatus({
4
tokenAddress: "", // Token address on fromChain which needs to be transferred
5
amount: "", // Amount of tokens to be transferred in smallest unit eg wei
6
fromChainId: "" // Chain id from where tokens needs to be transferred
7
toChainId: "", // Chain id where tokens are supposed to be sent
8
userAddress: "" // User wallet address who want's to do the transfer
9
});
10
β
11
if (preTransferStatus.code === RESPONSE_CODES.OK) {
12
// β
ALL CHECKS PASSED. Proceed to do deposit transaction
13
} else if(preTransferStatus.code === RESPONSE_CODES.ALLOWANCE_NOT_GIVEN) {
14
// β Not enough apporval from user address on LiquidityPoolManager contract on fromChain
15
let approveTx = await hyphen.approveERC20(tokenAddress,
16
preTransferStatus.depositContract, amount.toString());
17
β
18
// β±Wait for transaction to confirm, pass number of blocks to wait as param
19
await approveTx.wait(2);
20
21
// NOTE: Whenever there is a transaction done via SDK, all responses
22
// will be ethers.js compatible with an async wait() function that
23
// can be called with 'await' to wait for transaction confirmation.
24
25
// πNow proceed to do the deposit transaction
26
27
} else if (preTransferStatus.code === RESPONSE_CODES.UNSUPPORTED_NETWORK) {
28
// β Target chain id is not supported yet
29
} else if (preTransferStatus.code === RESPONSE_CODES.NO_LIQUIDITY) {
30
// β No liquidity available on target chain for given tokenn
31
} else if (preTransferStatus.code === RESPONSE_CODES.UNSUPPORTED_TOKEN) {
32
// β Requested token is not supported on fromChain yet
33
} else {
34
// β Any other unexpected error
35
}
Copied!
Pre-Actions
If the approval for the token to be transferred is not given to LiquidityPoolManager contract on fromChain then first approval transaction needs to be done. You can directly interact with the token contract and call its approve or permit method but to make things simple SDK also provides a method to do this.
1
/**
2
* tokenAddress Token address whose approval needs to be given
3
* spender LiquidityPoolManager address on fromChain
4
* amount Amount to be transferred. It should be in the smallest unit on token eg in wei
5
* userAddress User address who is giving the approval
6
* infiniteApproval Boolean flag whether to give infinite approval for the selected token
7
* useBiconomy Boolean flag whether to use Biconomy for gasless transaction for approval
8
*/
9
let approveTx = await hyphen.approveERC20(tokenAddress, spender, amount,
10
userAddress, infiniteApproval, useBiconomy);
11
β
12
// Wait for 1 block confirmation
13
await approveTx.wait(1);
Copied!
Once the approvals are checked and if required approval transaction is done. All you need to do is make only one deposit transaction on LiquidityPoolManager on fromChain and rest of the work will be done by Hyphen.
Lets do the Deposit Transaction
You can call the deposit method provided in the SDK to initiate a deposit transaction. Make sure to call preDepositStatus method before calling deposit method.
1
let depositTx = await hyphen.deposit({
2
sender: "User wallet address",
3
receiver: "Receiver address on toChain. Can be different than sender",
4
tokenAddress: "Address of the token on fromChain to be transferred",
5
depositContractAddress: "LiquidityPoolManager address on fromChain",
6
amount: "30000000000", //Amount to be transferred. Denoted in smallest unit eg in wei",
7
fromChainId: 137, // chainId of fromChain
8
toChainId: 1, // chainId of toChain
9
useBiconomy: true // OPTIONAL boolean flag specifying whether to use Biconomy for gas less transaction or not
10
});
11
β
12
// Wait for 1 block confirmation
13
await depositTx.wait(1);
Copied!
Deposit method checks if there's enough liquidity available on toChain for the given amount of tokens to be transferred considering all the pending transactions also for the same token. It also checks if there's enough approval given to LiquidityPoolManager contract by the sender address for the given amount of tokens to be transferred.
Once the deposit transaction is confirmed, rest of the transactions to make cross-chain transfer will be done by off-chain Executor nodes run by Biconomy. Now you can wait for the cross-chain transfer transaction to be done.
In the next section, we'll see how to listen for the status of our cross chain transfers once our deposit transaction is successful. Or what if you don't get the funds on the destination chain within 1 min after your successful deposit transaction.
Enable Network Agnostic Gasless Transactions
You can enable network agnostic gasless transactions using Biconomy so that user can make Approve and Deposit transactions on a chain e.g., Polygon while still keeping his wallet pointing to Ethereum chain.
To enable this, you need to pass 'walletProvider' object and 'biconomy' options in the second parameter of Hyphen constructor as mentioned below:
1
let hyphen = new Hyphen(<Provider Object 1>, {
2
...
3
walletProvider: <Provider Object 2>, // Pass this to enable network agnostic transfers
4
biconomy: {
5
enable: true,
6
debug: true,
7
apiKey: "Biconomy API Key for meta transaction support"
8
},
9
signatureType: SIGNATURE_TYPES.EIP712, // Optional. To specify signature types in case of meta transactions
10
...
11
});
Copied!
Here, Provider Object 1 is the JSON RPC provider object pointing to the 'fromChain' where user will be depositing his tokens. It doesn't need to have any accounts information.
Provider Object 2 has to be a provider object from the connected user wallet. It doesn't matter on which network the User Wallet is because we'll be using this provider object to just get the user signatures to do gasless transactions on the chain pointed by Provider Object 1.
So when user initiates a deposit transaction using deposit method, Hyphen SDK will use Biconomy SDK to send the deposit transaction, internally Biconomy SDK will check the details of called method and smart contract from Biconomy Dashboard. This step is mandatory and the called method needs to be registered on the Biconomy Dashboard.
Once the details are matched with the Biconomy dashboard data, Biconomy SDK will ask the user for the signature using 'walletProvider' object passed and user will get a signature popup on his wallet.
Once user provides his signatures, transaction is routed via Biconomy and the transaction will be executed on the 'fromChain' pointed by Provider Object 1.
Last modified 2mo ago