Integrate Web App

Estimated time to read: 3 minutes

Integrate 'Web3' apps with the Arcana CA SDK to enable:

Unified balance
Chain abstracted transactions

App users can spend funds on any chain. They do not need to switch chains or bridge assets.

Prerequisites

Download and install the SDK.

npm install --save @arcana/ca-sdk

Initialize

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
}

ca.init()

Use await until the init() call is complete. Then call any other CA method listed in the Arcana CA SDK Reference.

Unified Balance

Get unified balance on the supported source chains:

View the total EOA balance for all supported tokens and chains.
View the total EOA balance for a specified token across all chains.

//total chain abstracted unified balance across all chains/tokens
const balances = await ca.getUnifiedBalances();
//total balance for a specific token across all chains 
const usdtBalance = await ca.getUnifiedBalance("usdt");

CA Transactions

Enable chain abstracted transactions through:

transfer
request
bridge

`transfer`

Use unified balance for chain abstracted transactions.

const handler = await ca.transfer({
  to: "0x...",
  amount: 5,
  chainID: 10,  //optional, defaults to current chain
  token: "eth",
});

// Execute the transfer
const hash = await handler.exec();

// Simulate the transfer, returns intent data and token info
const response = await handler.simulate();

`request`

Replace the standard EIP-1193 provider with a chain-abstracted one using getEVMProviderWithCA. Then use it to call request with eth_sendTransaction to use unified balance.

const providerWithCA = ca.getEVMProviderWithCA();

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

Bridge

Use the unified balance to deposit tokens on a different chain. Chain abstracted transactions handle the transfer.

const handler = await ca.bridge({
  token: "usdt",
  amount: 10,
  chainID: 137,
});

// Execute the bridge
await handler.exec();

// Simulate the bridge, returns intent data and token info
const response = await handler.simulate();

Allowance

Allowances are set to unlimited by default for all supported chains and tokens. Developers can update the allowance settings via setOnAllowanceHook(). App users can approve chain abstracted transactions. They cannot change the allowance set by the app developers.

`setOnAllowanceHook`

Use setOnAllowanceHook to set up allowances for chain abstracted transactions. The default value is set to unlimited for all chains.

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
})

Get Allowance

Get allowance values configured for the chain abstracted transactions.

// 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()

Intents

`setOnIntentHook`

Use setOnIntentHook to show the intent details such as the source of funds, applicable fees.

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)
  })

Get Intents

Get the list of intents representing user's request for funds.

import type { RFF } from "@arcana/ca-sdk"

const page = 1
const intentList: RFF[] = await ca.getMyIntents(page);

Events

Keep track of the user intent processing stages.

Set up a listener to monitor various intent processing stages during a chain abstracted transaction.

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 'Web3' app is all set to let users spend on any chain via unified balance and chain abstracted transactions.