Integrate Web App

Estimated time to read: 4 minutes

Integrate 'Web' Web3 apps with the Arcana CA SDK to enable unified balance.

With unified balance, Web3 app users can access funds across chains. They can spend assets on any chain using chain abstraction. No need to switch chains or bridge assets for gas.

Prerequisites

Download and install the SDK.

npmyarn

npm install --save @arcana/ca-sdk

yarn add @arcana/ca-sdk

Initialize `CA`

import { CA } from '@arcana/ca-sdk'

const provider = window.ethereum
const ca = new CA();
//Set the EVM provider  
ca.setEVMProvider(provider);

try {
  await ca.init()
} catch (e) {
  // Handle exception case
}

Initialize First!

The app must use await until the init() call is complete, before invoking any of the other Arcana CA SDK functions listed in Arcana CA SDK Reference.

Set up Allowance

Use the setOnAllowanceHook to enable unified balance by letting the app users confirm allowances for chain abstracted transactions.

ca.setOnAllowanceHook(async ({ allow, deny, sources }) => {
    // This is a hook for the dev to show user the allowances that need to be setup for the current tx to happen

    // sources: an array of objects with minAllowance, chainID, token symbol etc
    // allow(allowances): allowances is an array with allowance for each source (len(sources) == len(allowances))
    // deny(): stop the flow
})

Use the setOnIntentHook UI hook to show the intent, funds source, and fees. Let users confirm the transaction before spending on the target chain.

ca.setOnIntentHook(({ intent, allow, deny, refresh }) => {
    // This is a hook for the dev to show user the intent, the sources and associated fees

    // intent: Intent data containing sources and fees for display purpose
    // allow(): accept the current intent
    // deny(): deny the intent and stop the flow
    // refresh(): should be on a timer of 5s to refresh the intent (if not refreshed old intents might fail due to fee changes)
  })

Access Unified Balance

Use getUnifiedBalances to get the unified balance that covers all the supported tokens across all the chains in the wallet. It shows the total of every token across all chains in the wallet.

const balances = await ca.getUnifiedBalances()

Use getUnifiedBalance to get the total balance of a specified token. It sums up the input token balance across all chains in your wallet.

const usdtBalance = await ca.getUnifiedBalance("usdt")

CA Transaction

Transfer

Use the transfer function to send funds from the unified balance to any wallet (EOA) on any chain using approved source chain funds.

await ca.transfer().to("0x...").amount(5).chain(10).token("eth").exec()

chain() is optional, it will use the current chain as input if not specified.

Request

Use EIP-1193 request to issue eth_sendTransaction operation that deposits unified balance funds to any smart contract.

await ca.request({
    method: "eth_sendTransaction",
    params: [{
        to: "0xEa46Fb4b4Dc7755BA29D09Ef2a57C67bab383A2f", 
        from: "0x7f521A827Ce5e93f0C6D773525c0282a21466f8d",
        value: "0x001"
    }],
})

Depositing funds: EOA vs. SC

Send to EOA	Send to SC
Use `transfer` method.	Use EIP-1193 `request` function.

Advanced

The SDK supports eth_sendTransaction for basic transfers. It also offers chain abstracted bridge and transfer operations.

Bridge

Use the bridge function to get tokens on any chain. Chain abstraction uses your allowed funds from other chains to complete the transfer.

The function uses your current chain when you don't specify a chain() parameter. This is effectively swapping tokens on the current chain.

await ca.bridge().token("pol").amount(10).chain(137).exec();

Manage Allowance

Use the following functions to get, set and revoke allowance limits in the EOA for the supported source chains and tokens.

Get Allowance

// Get USDC allowance for Polygon
await ca.allowance().tokens(["USDC"]).chain(137).get()
// Get USDC & USDT allowance for all supported chains
await ca.allowance().tokens(["USDC", "USDT"]).get()
// Get all supported token allowances for all supported chains
await ca.allowance().get()

Set Allowance

await ca.allowance().tokens(["USDC"]).chain(42161).amount("max").set()

// You can specify custom values for tokens and amount in hex, for example
// await ca.allowance().tokens(["USDC"]).chain(42161).amount("0x989680").set()

// Alternatively, you can also specify the amount 10,000,000 for USDC tokens as follows:
// await ca.allowance().tokens(["USDC"]).chain(42161).amount("10000000").set()

Revoke Allowance

await ca.allowance().tokens(["USDC"]).chain(42161).revoke()

Handle Events

Web3 apps integrating with the SDK can listen to user intent processing and display the various stages of intent processing when a chain abstracted transaction is in progress.

Learn more about intents and various intent processing events associated with chain abstracted transactions.

Add Listener

ca.addCAEventListener((data) => {
    switch(data.type) {
        case "EXPECTED_STEPS":{
            // store data.data(an array of steps which will be followed)
            state.value.steps = data.data.map(s => ({ ...s, done: false }))
            state.value.inProgress = true
            break;
        }
        case "STEP_DONE": {
            const v = state.value.steps.find(s => {
                return s.typeID === data.data.typeID
            })
            if (v) {
                v.done = true
            }
            break;
        }
    }
});

Remove Listener

ca.removeCAEventListener((data) => {...})

Check out the integration example code.

Finished.

The 'Web' app is all set to let users spend on any chain via unified balance and chain abstracted transactions.