SDK - Biconomy

Search…
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 make the Hyphen integration too easy. Even though you can just interact with LiquidityPool smart contract directly and deposit the tokens using the 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.
Let's 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 the first argument and an option object as the 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. The 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. Initialization
After the SDK object is instantiated you need to initialize the SDK by calling its init function. The initialization is kept separated from the constructor to give flexibility to the developer to use await statement for initializing 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 initialization.
Time to do a Cross-Chain Transfer
Before we proceed let's 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
LiquidityPool
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 need to be done and some pre-actions need 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 need to be transferred.
Given token-address and chain ids should be supported.
Enough approval should be given by the user to LiquidityPool 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, whether 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.depositManager.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 infiniteApproval = false;
16
  let useBiconomy = false;
17
  let approveTx = await hyphen.tokens.approveERC20(tokenAddress, 
18
                    preTransferStatus.depositContract, amount.toString(),
19
                    infiniteApproval, useBiconomy
20
                  );
21
​
22
  // ⏱Wait for the transaction to confirm, pass a number of blocks to wait as param
23
  await approveTx.wait(2);
24
  
25
  // NOTE: Whenever there is a transaction done via SDK, all responses
26
  // will be ethers.js compatible with an async wait() function that
27
  // can be called with 'await' to wait for transaction confirmation.
28
  
29
  // 🆗Now proceed to do the deposit transaction
30
  
31
} else if (preTransferStatus.code === RESPONSE_CODES.UNSUPPORTED_NETWORK) {
32
  // ❌ Target chain id is not supported yet
33
} else if (preTransferStatus.code === RESPONSE_CODES.NO_LIQUIDITY) {
34
  // ❌ No liquidity available on target chain for given tokenn
35
} else if (preTransferStatus.code === RESPONSE_CODES.UNSUPPORTED_TOKEN) {
36
  // ❌ Requested token is not supported on fromChain yet
37
} else {
38
  // ❌ Any other unexpected error
39
}
Copied!
Pre-Actions
If the approval for the token to be transferred is not given to LiquidityPool contract on fromChain then the 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 LiquidityPool 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.tokens.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 LiquidityPool on fromChain and the rest will be done by Hyphen.
Let's 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.depositManager.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: "LiquidityPool 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
    tag: "Dapp specific identifier" // Can be any string, emitted from the contract during the deposit call; used for analytics
11
});
12
​
13
// Wait for 1 block confirmation
14
await depositTx.wait(1);
Copied!
The 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 LiquidityPool 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 the 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 5 min after your successful deposit transaction.
Enable Network Agnostic Gasless Transactions
You can enable network agnostic gasless transactions using Biconomy so that the user can make Approve and Deposit transactions on a chain e.g., Polygon while still keeping his wallet pointing to the 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 the 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 the 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 the 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 walletProviderobject passed and the user will get a signature popup on his wallet.
Once the user provides his signatures, the transaction is routed via Biconomy and the transaction will be executed on the fromChain pointed by Provider Object 1.
Signing Transactions Using An Imported Private Key
In some cases, the SDK may be used outside of the browser and will require an automated experience. The following snippet demonstrates how to perform the same steps above but with your private key.
Instantiate Hyphen and an Ethers Wallet
1
import { RESPONSE_CODES } from "@biconomy/hyphen";
2
import { ethers } from "ethers";
3
​
4
const providerURL = process.env.PROVIDER_URL;
5
const provider = new ethers.providers.JsonRpcProvider(providerURL);
6
​
7
const privateKey = process.env.PRIVATE_KEY!;
8
const wallet = new ethers.Wallet(privateKey);
9
const signer = wallet.connect(provider);
10
​
11
// instantiate hyphen
12
let hyphen = new Hyphen(signer.provider, {
13
  debug: true,            // If 'true', it prints debug logs on console window
14
  environment: "test",    // It can be "test" or "prod"
15
  onFundsTransfered: (data) => {
16
    // Optional Callback method which will be called when funds transfer across
17
    // chains will be completed
18
  },
19
  // signatureType: SIGNATURE_TYPES.PERSONAL,
20
  infiniteApproval: false,
21
  transferCheckInterval: -1, // Interval in milli seconds to check for transfer status
22
  biconomy: {
23
      enable: false,
24
      apiKey: "<your_biconomy_api_key>",
25
      debug: true
26
  }
27
});
Copied!
Pre-Deposit Operations
These are the same as before except that the approveERC20 function receives the wallet object.
1
let preTransferStatus = await hyphen.depositManager.preDepositStatus({
2
    tokenAddress: "", // Token address on fromChain which needs to be transferred
3
    amount: "", // Amount of tokens to be transferred in smallest unit eg wei
4
    fromChainId: "" // Chain id from where tokens needs to be transferred
5
    toChainId: "", // Chain id where tokens are supposed to be sent
6
    userAddress: "" // User wallet address who want's to do the transfer
7
});
8
​
9
if (preTransferStatus.code === RESPONSE_CODES.OK) {
10
  // ✅ ALL CHECKS PASSED. Proceed to do deposit transaction
11
} else if(preTransferStatus.code === RESPONSE_CODES.ALLOWANCE_NOT_GIVEN) {
12
  // ❌ Not enough apporval from user address on LiquidityPoolManager contract on fromChain
13
  let infiniteApproval = false;
14
  let useBiconomy = false;
15
  let approveTx = await hyphen.tokens.approveERC20(tokenAddress, 
16
                  preTransferStatus.depositContract, amount.toString(),
17
                  infiniteApproval, useBiconomy,
18
                  wallet); // !!!NOTE: the previously created wallet is added here
19
​
20
  // ⏱Wait for the transaction to confirm, pass a number of blocks to wait as param
21
  await approveTx.wait(2);
22
  
23
  // NOTE: Whenever there is a transaction done via SDK, all responses
24
  // will be ethers.js compatible with an async wait() function that
25
  // can be called with 'await' to wait for transaction confirmation.
26
  
27
  // 🆗Now proceed to do the deposit transaction
28
  
29
} else if (preTransferStatus.code === RESPONSE_CODES.UNSUPPORTED_NETWORK) {
30
  // ❌ Target chain id is not supported yet
31
} else if (preTransferStatus.code === RESPONSE_CODES.NO_LIQUIDITY) {
32
  // ❌ No liquidity available on target chain for given tokenn
33
} else if (preTransferStatus.code === RESPONSE_CODES.UNSUPPORTED_TOKEN) {
34
  // ❌ Requested token is not supported on fromChain yet
35
} else {
36
  // ❌ Any other unexpected error
37
}
Copied!
Perform the Deposit Transaction
The wallet object is passed as the last parameter to the deposit function.
1
let depositTx = await hyphen.depositManager.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: "LiquidityPool 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
    tag: "Dapp specific identifier" // Can be any string, emitted from the contract during the deposit call; used for analytics
11
}, wallet);  // !!!NOTE: the previously created wallet is added here
12
​
13
// Wait for 1 block confirmation
14
await depositTx.wait(1);
Copied!
Products - Previous
Hyphen - Instant Cross-Chain Transfers
DepositManager
Last modified 20d ago
Copy link
Contents
Introduction
Let's get started
1. Installation
2. Importing and Instantiation
3. Initialization
Time to do a Cross-Chain Transfer
Let's do the Deposit Transaction
Enable Network Agnostic Gasless Transactions
Signing Transactions Using An Imported Private Key