@chromia/bridge-client

Chromia Bridge Client 🌉

This is a client library with utilities for interacting with the Chromia Bridge.

Prerequisites

Contracts/dApps needed

1. The address to a TokenBridge contract deployed on an EVM network.
2. The address to an ERC20 token on the same EVM network.
3. The blockchain RID to a Chromia blockchain that is using the hbridge Rell library.

Required configurations checklist

1. 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 method allowToken:

   const contractTransactionResponse = await bcl.allowToken(token);
   

2. In order to check the spending allowance, you can do so with the built in method checkAllowance:

   const allowance: bigint = await bcl.checkAllowance();
   

3. 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 method setBlockchainRid:

   const contractTransactionResponse = await bcl.setBlockchainRid(rid);
   

4. 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.depositToEvmBridgeContract(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.

For the user one of two things will happen:

1. No Session or evmKeyStore was provided, account linking is skipped completely
2. The user already has a linked account; in this case, they will only need to sign the deposit transaction.
3. The user does not have a linked account; in this case, they will also have to sign the account linking transaction.

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.

---

Changelog

2.2.2 (2024-06-25)

📝 Documentation changes

• update README.md (3ef310e)

📝 Code refactor

• client: move account linking logic to separate function (fc59417)