GasPay SDK

1. Initialization

1.1 install

// npm
npm install @aabank/sdk
// yarn
yarn add @aabank/sdk
// pnpm
pnpm add @aabank/sdk

1.2 init

Contact us to auth you an appId

import AAbankSDK from '@aabank/sdk';

type extraConfig {
    isDebug: Boolean;
    ...
}

const appId = "000000";

const initSdk = async () => {
    const provider = await connector?.getProvider() 
    // window.etherum.sendAsync or wagmi getProvider
    const sdk = new AABank(provider, appId, { isDebug: true })
    const { caAddress, publicKeyDerived } = await sdk.init()
    ...
}

2. Methods (API)

2.1 init()

Init the SDK to continue use SDK method

2.2 isCaAddress()

CA address will create after the first deposit operation

// return current account address whether is a ca address
const isCaAddress: boolean = await sdk.isCaAddress()

// return the address whether is a ca address
const isCaAddress: boolean = await sdk.isCaAddress('0x000...0000') 

// return the multiple address whether is ca address
const isCaAddress: boolean[] = await sdk.isCaAddress(['0x00...00', '0x00...00']) 

2.3 getBalance()

const data = await sdk.getBalance('ETH')
//return 
[{
	"chainId": "421614",
	"tokenInfos": [{
		"tokenName": "ETH",
		"amount": "0",
		"tokenAddress": "0x0000000000000000000000000000000000000000"
	}]
}, {
	"chainId": "84532",
	"tokenInfos": [{
		"tokenName": "ETH",
		"amount": "0.1",
		"tokenAddress": "0x0000000000000000000000000000000000000000"
	}]
}, {
	"chainId": "11155420",
	"tokenInfos": [{
		"tokenName": "ETH",
		"amount": "0.994",
		"tokenAddress": "0x0000000000000000000000000000000000000000"
	}]
}]

2.4 getTransferInfo()

const { fee, messageId, encodeTransactionParams, expirationTimestamp }
  = await sdk.getTransferInfo(MessageMode.Transfer, [{
      toChainId: network,
      receiver,
      amount,
      symbol: 'ETH',
  },{
      toChainId: network,
      receiver,
      amount,
      symbol: 'ETH',
  }])

// return
{
  "fee": {
    "tokenName": "ETH",
    "crossFee": "0.00002",
    "tradeFee": "0.00002",
    "vizingGasFee": "0.002",
    "totalFee": "0.0022420689" // if amount > 0, amount should greater then totalFee.
  },
  "messageId": "20240524112209485237422107787190",
  "encodeTransactionParams": ["0x.....", "0x....."],
  "expirationTimestamp": 1716549760 // messageId expiration time
}

2.5 getTransactionInfo()

const { fee, messageId, encodeTransactionParams, expirationTimestamp }
  = await sdk.getTransactionInfo(MessageMode.Transaction, [{
      toChainId: network,
      targetChainContract,
      customMessage,
  },{
      toChainId: network,
      targetChainContract,
      customMessage,
  }])

// return
{
  "fee": {
    "tokenName": "ETH",
    "crossFee": "0.00002",
    "tradeFee": "0.00002",
    "vizingGasFee": "0.002",
    "totalFee": "0.0022420689" // if amount > 0, amount should greater then totalFee.
  },
  "messageId": "20240524112209485237422107787190",
  "encodeTransactionParams": ["0x.....", "0x....."],
  "expirationTimestamp": 1716549760 // messageId expiration time
}

2.6 sendTransaction()

const { fee, messageId, encodeTransactionParams, expirationTimestamp }
  = await sdk.getTransferInfo(MessageMode.Transfer, [{
      toChainId: network,
      receiver,
      amount,
      symbol: 'ETH',
  },{
      toChainId: network,
      receiver,
      amount,
      symbol: 'ETH',
  }])

// you should call sendTransaction method before expirationTimestamp
const hash = await sdk.sendTransaction(messageId, encodeTransactionParams)

2.7 getTransactionStatus()

const hash = '0x...'

const txStatusInfo = await sdk.getTransactionStatus(hash);

// return 
[{
  "status": 99,// 0: Pending; 97: Failed; 98: (Success)Waiting confirm; 99: Success
  "sourceChainHash": "0x...",
  "targetChainId": "421614",
  "targetChainHash": "0x...",
  "timestamp": 1716379103
 },{
  "status": 98,// 0: Pending; 97: Failed; 98: (Success)Waiting confirm; 99: Success
  "sourceChainHash": "0x...",
  "targetChainId": "84532",
  "targetChainHash": "0x...",
  "timestamp": 1716379103
 },{
  "status": 97,// 0: Pending; 97: Failed; 98: (Success)Waiting confirm; 99: Success
  "sourceChainHash": "0x...",
  "targetChainId": "11155420",
  "targetChainHash": "0x...",
  "timestamp": 1716379103
 }]
 

2.8 getTradeHistory()

// const history = sdk.getTradeHistory(1, 50, ["transfer", "transaction"]);
const history = sdk.getTradeHistory(1, 50, ["transfer", "transaction"], 1721404800, 1722268800);
// history
{
  "totalCount": 2,
  "list": [{
    "targetChainId": "421614",
    "receiver": "0xE127D50B2e720dc9abe448365435DCcC82c38Eae",
    "eventType": "transfer",
    "amount": "0.001",
    "receiverAmount": "0.0008836720512",
    "totalFee": "0.0001163279488",
    "tokenName": "ETH",
    "hash": "0x07639d313be8229551f040e52d80a2b4a125b377cf42fd6e32d0a2430380d702",
    "success": true, // target chain success
    "targetChainHash": "0x07639d313be822....0a2430380d702",
    "createdAt": 1723103678,
    "sourceChainSuccess": true // vizing success
  },{
    "targetChainId": "421614",
    "receiver": "0xE127D50B2e720dc9abe448365435DCcC82c38Eae",
    "eventType": "transaction",
    "amount": "0.001",
    "receiverAmount": "0.0008836720512",
    "totalFee": "0.0001163279488",
    "tokenName": "ETH",
    "hash": "0x07639d313be8229551f040e52d80a2b4a125b377cf42fd6e32d0a2430380d702",
    "success": true,
    "targetChainHash": "0x07639d313be822....0a2430380d702",
    "createdAt": 1723103678,
    "sourceChainSuccess": true
  }]
}

2.9 getDepositHistory()

// const history = sdk.getDepositHistory(1, 50); 
const history = sdk.getDepositHistory(1, 50, 1721404800, 1722268800);
// history
{
  "totalCount": 2,
  "list": [{
    "targetChainId": "421614",
    "receiver": "0xE127D50B2e720dc9abe448365435DCcC82c38Eae",
    "amount": "0.001",
    "tokenName": "ETH",
    "hash": "0x07639d313be8229551f040e52d80a2b4a125b377cf42fd6e32d0a2430380d702",
    "success": true,
    "createdAt": 1723103678,
  },{
    "targetChainId": "421614",
    "receiver": "0xE127D50B2e720dc9abe448365435DCcC82c38Eae",
    "amount": "0.001",
    "tokenName": "ETH",
    "hash": "0x07639d313be8229551f040e52d80a2b4a125b377cf42fd6e32d0a2430380d702",
    "success": true,
    "createdAt": 1723103678,
  }]
}

2.10 withdraw()

const { fee, messageId, encodeTransactionParams, expirationTimestamp }
  = await sdk.getTransferInfo(MessageMode.WithDraw, [{
      toChainId: network,
      receiver, // receiver must be a EOA or Contract, can not be a other ca account.
      amount, // amount must greater then zeroAmount totalFee
      symbol: 'ETH',
      mode: MessageMode.WithDraw,
  }])


const hash = await sdk.withdraw(messageId, encodeTransactionParams)

3. Business Scene

3.1 Transfer

Transfer Timeline

const { fee, messageId, encodeTransactionParams, expirationTimestamp }
  = await sdk.getTransferInfo(MessageMode.Transfer, [{
      toChainId: network,
      receiver,
      amount, // amount can be zero but if amount > 0, amount should greater then the totalFee
      symbol: 'ETH',
  }])

// you should call transfer method before expirationTimestamp
const hash = await sdk.sendTransaction(messageId, encodeTransactionParams)

3.2 Withdraw

const { fee, messageId, encodeTransactionParams, expirationTimestamp }
 = await sdk.getTransferInfo(MessageMode.WithDraw, [{
      toChainId: network,
      receiver, // receiver must be a EOA or Contract, can not be a other ca account.
      amount, // amount must greater then totalFee
      symbol: 'ETH',
  }])

const hash = await sdk.withdraw(messageId, encodeTransactionParams)

3.3 Transaction

Send custom message to vizing omni contract

const { fee, messageId, encodeTransactionParams, expirationTimestamp }
  = await sdk.getTransactionInfo(MessageMode.Transaction, [{
      toChainId: network,
      targetChainContract,
      customMessage,
  }])

// you should call sendTransaction method before expirationTimestamp
const hash = await sdk.sendTransaction(messageId, encodeTransactionParams)

4. Error

If an ApiError is caught, you can get the corresponding error code and error information from the ApiError object.

Code	Message	Desc
1001	Balance not enough	The account balance not enough for start a transaction
1002	From chainId and to chainId can not be the same
1003	Invalid CA address	Account address is not a CA address
1004	Cross chain amount not enough
1005	Vizing API error
1006	Amount less than min fee	Transfer amount is less then total fee
1007	Transaction info expired	Call transfer method after expiration timestamp
1008	Signature validation failed
1009	Withdraw operation receiver can not be a ca address
1010	Exchange rate not found	Can't calculate fee for transfer ERC20 token
1011	Handle transaction time out
1012	Handle transaction failed
1013	Transaction info not found

5. React

5.1 Hooks (Child Component)

// next.js
'use client'

import { createContext, useContext, useState } from 'react'
import { AABank } from '@aabank/sdk'

interface SDKContextType {
    sdk?: AABank
    setSdk: (sdk: AABank) => void
    caAddress: string
    setCaAddress: (caAddress: string) => void
}

const SDKContext = createContext({} as SDKContextType)

export function useSDK() {
    return useContext(SDKContext)
}

const SDKProvider = ({ children }: { children: React.ReactNode }) => {
    const [sdk, setSdk] = useState<AABank>()
    const [caAddress, setCaAddress] = useState('')

    return (
        <SDKContext.Provider
            value={{
                sdk,
                setSdk,
                caAddress,
                setCaAddress,
            }}
        >
            {children}
        </SDKContext.Provider>
    )
}
export default SDKProvider


'use client'
import * as React from 'react'
import { NextUIProvider } from '@nextui-org/system'
import { useRouter } from 'next/navigation'
import { ThemeProvider as NextThemesProvider } from 'next-themes'
import { ThemeProviderProps } from 'next-themes/dist/types'
import AppProvider from '@/common/providers/app-provider'
import SDKProvider from '@/common/providers/sdk-provider'

export interface ProvidersProps {
    children: React.ReactNode
    themeProps?: ThemeProviderProps
}

export function Providers({ children, themeProps }: ProvidersProps) {
    const router = useRouter()

    return (
        <NextUIProvider navigate={router.push}>
            <NextThemesProvider {...themeProps}>
                <AppProvider>
                    <SDKProvider>{children}</SDKProvider>
                </AppProvider>
            </NextThemesProvider>
        </NextUIProvider>
    )
}