@chromia/bridge-client
v3.0.6
Published
This is a client library with utilities for interacting with the Chromia Bridge.
Downloads
247
Keywords
Readme
Chromia Bridge Client 🌉
This is a client library with utilities for interacting with the Chromia Bridge.
Prerequisites
Contracts/dApps needed
- The address to a TokenBridge contract deployed on an EVM network.
- The address to an ERC20 token on the same EVM network.
- The blockchain RID to a Chromia blockchain that is using the hbridge Rell library.
Required configurations checklist
- The ERC20 token address has to be approved by the TokenBridge contract owner by calling the
allowToken
function in the TokenBridge contract. This is possible to do with@chromia/bridge-client
using the built in methodallowToken
:const contractTransactionResponse = await bcl.allowToken(token);
- In order to check the spending allowance, you can do so with the built in method
checkAllowance
:const allowance: bigint = await bcl.checkAllowance();
- The blockchain RID needs to be set in the
setBlockchainRid
function in the TokenBridge contract. This is possible to do with@chromia/bridge-client
using the built in methodsetBlockchainRid
:const contractTransactionResponse = await bcl.setBlockchainRid(rid);
- The pubkeys of the validating nodes in the Chromia network needs to be converted to EVM addresses and configured in the Validator contract, either during deployment or by calling the
updateValidators
function in the Validator contract.
Working with the client
Setup
The bridge client needs an active Session
to handle all Chromia related queries and operations, but it does however not need to be instantiated with it. In order to get an active Session
, you can set up your application with @chromia/ft4
like this:
// 1: Setup a connection to postchain through postchain-client
const pcl = await createClient({
nodeUrlPool: 'YOU_NODE_URL_POOL',
blockchainRid: 'YOUR_BLOCKCHAIN_RID',
});
// 2: Create an account
const evmKeyStore = await createWeb3ProviderEvmKeyStore(window.ethereum);
const ad = createSingleSigAuthDescriptorRegistration(
[AuthFlag.Account, AuthFlag.Transfer],
evmKeyStore.id
);
const response = await registerAccount(
pcl,
evmKeyStore,
registrationStrategy.open(ad)
);
// 3: Log in your user
const evmKeyStoreInteractor = createKeyStoreInteractor(pcl, evmKeyStore);
const accounts = await evmKeyStoreInteractor.getAccounts();
const session = await evmKeyStoreInteractor.getSession(accounts[0].id);
NOTE: Make sure that you also save your evmKeyStore
somewhere in your application state as some methods in @chromia/bridge-client
will require it.
Now that you have your Session
object, you can use it to initialize the bridge client. You will also need to provide an EVM Provider
, either a BrowserProvider
or a JsonRpcProvider
:
const provider = new BrowserProvider(window.ethereum);
const bcl = await bridgeClient(
{ bridgeAddress: 'YOUR_BRIDGE_ADDRESS', tokenAddress: 'YOUR_TOKEN_ADDRESS' },
provider,
session
);
If your application is setup in a way that makes it impossible to have an active Session
at the time you also need to instantiate the bridge client, you can still setup the client without the Session
:
const provider = new BrowserProvider(window.ethereum);
const bcl = await bridgeClient(
{ bridgeAddress: 'YOUR_BRIDGE_ADDRESS', tokenAddress: 'YOUR_TOKEN_ADDRESS' },
provider
);
When you later have access to the Session
, you can simply set it to the client through setSession(session: Session)
:
bcl.setSession(session);
Example usage: Bridge from EVM to Chromia and back
Make a deposit to the Chromia EVM bridge (bridge from EVM to Chromia)
First, make sure that the user approves spending of tokens by the token bridge:
const approvalResponse = await bcl.approveDepositAmount(BigInt(10));
To make a deposit to the Chromia EVM bridge, you need to use the method depositToEvmBridgeContract
. Here you will need to provide the amount
of tokens you want to bridge over.
const contractTransactionResponse = await bcl.depositToEvmBridgeContract(
BigInt(100)
);
After a deposit has been made, you can link the EVM account with the corresponding FT4 account that was created automatically in the deposit process, here you need to provide the evmKeyStore
you created earlier:
const accountLinkingResponse = await bcl.linkEvmEoaAccount(evmKeyStore);
NOTE: If the EVM account is already linked, it will be returned in the accountLinkingResponse
. Do note that an EVM account can have multiple FT4 accounts linked to it.
This is all you have to do in order to bridge tokens from EVM to Chromia, if the transaction is successful the user will now have their bridged tokens on Chromia.
Bridge from Chromia to EVM
To do this, you will first have to call the method bridgeFromChromia
, with the amount
and the assetId
:
// Network ID does not need to be provided as it will be fetched from the provider
const transactionResponse = await bcl.bridgeFromChromia(
BigInt(10),
Buffer.from('YOUR_ASSET_ID', 'hex')
);
Request withdrawal from EVM bridge
The previous action created a pending withdraw request, these need to be accepted by the user in order to start the withdrawal process, which is done with the requestEvmWithdraw
method. This process looks like this:
const erc20WithdrawalInfo = await bcl.getErc20WithdrawalByTransactionRid(
transactionResponse.receipt.transactionRid,
opIndex
);
// Get event proof for withdrawal
const eventProof = await bcl.getWithdrawRequestEventProof(
erc20WithdrawalInfo.event_hash
);
// Request withdrawal
const requestedWithdraw = await bcl.requestEvmWithdraw(eventProof);
Checking withdrawal status and finishing the withdrawal process
Depending on how the bridge contract has been configured, the user will have to wait X number of blocks on EVM in order to complete their withdrawal. This can be done with the getPendingWithdrawFromProof
method:
const { block_number } = await getPendingWithdrawFromProof(eventProof);
Once the block_number
has been reached on the target EVM chain, the user can withdraw their tokens:
const withdrawal = await bcl.evmWithdraw(eventProof.leaf as Buffer);
Additional methods
getErc20Deposits(filter?: DepositFilter, pageSize?: number, pageCursor?: string)
- Returns all deposits as specified by the filter.getErc20Withdrawals(filter?: WithdrawFilter, pageSize?: number, pageCursor?: string)
- Returns all withdrawals from the EVM bridge as specified by the filter.setBlockchainRid(blockchainRid: Buffer)
- Sets the blockchain RID.