@cyberlab/cyber-account v2.3.4

CyberAccount SDK

CyberAccount SDK is the official NPM package that implements CyberConnect V3 account abstraction.

Examples

• Particle sample

Supported Chains

• Optimism / Optimism Goerli
• Polygon / Polygon Mumbai
• Base / Base Goerli
• Linea / Linea Goerli
• Arbitrum / Arbitrum Goerli
• opBNB / opBNB Goerli

Installation

npm install @cyberlab/cyber-account

Getting Started

const cyberBundler = new CyberBundler({
  rpcUrl: "https://api.stg.cyberconnect.dev/cyberaccount/bundler/v1/rpc",
  appId: "ab23459a-32d7-4235-8129-77bd5de27fb1",
});

const walletClient = createWalletClient({
  chain: optimismGoerli,
  transport: custom(window.ethereum),
});

const accounts = await walletClient.requestAddresses();
const ownerAddress = accounts[0];

const sign = async (message) => {
  return await walletClient.signMessage({
    account: ownerAddress,
    message: { raw: message },
  });
};

// Optional: Paymaster
const cyberPaymaster = new CyberPaymaster({
  rpcUrl: "<rpcUrl>",
  appId: "<appId>",
  generateJwt: (cyberAccountAddress) => jwt,
});

const cyberAccount = new CyberAccount({
  chain: {
    id: 420,
    testnet: true,
  },
  owner: {
    address: ownerAddress,
    signMessage: sign,
  },
  bundler: cyberBundler,
  paymaster: cyberPaymaster,
});

Sending Native Token

cyberAccount.sendTransaction({
  to: "0x1e6754b227c6ae4b0ca61d82f79d60660737554a",
  value: parseUnits("0.0001", 18),
  data: "0x",
});

• to - Address of the token receiver
• value - The amount of the native token to send
• data - The encoded data of the transaction

Sending ERC20 Tokens

Sending ERC20 tokens is different from sending the native token, it requires two steps:

1. Encode the transaction data with the ERC20 contract ABI

   const encoded = encodeFunctionData({
     abi: erc20ABI,
     functionName: "transfer",
     args: [
       "0x85AAc6211aC91E92594C01F8c9557026797493AE",
       parseUnits("0.5", 18),
     ],
   });

   Argument list:

   • Address - The address of the token receiver
   • Amount - The amount of the token to send

2. Send the transaction with the encoded data

   cyberAccount.sendTransaction({
     to: "0x32307adfFE088e383AFAa721b06436aDaBA47DBE",
     value: BigInt(0),
     data: encoded,
   });

• to - Address of the ERC20 token contract
• value - The amount of native token to send, it should be 0
• data - The encoded ERC20 token transaction detail

CyberAccount

class CyberAccount({chain, owner, bundler, paymaster})

Parameters

• chain: The target chain of the CyberAccount is deployed on.

  type Chain = {
    id: number;
    testnet?: boolean;
    rpcUrl?: string;
  };

• owner: The owner of a CyberAccount (Check Signing the user operation hash section for the details).

  type Owner = {
    address: Address;
    signMessage: async (message: string) => Promise<Hash>;
  }

• bundler (CyberBundler): An instance of CyberBundler for handling the CyberAccount user operations.

• paymaster (CyberPaymaster - Optional): An instance of CyberPaymaster for sponsoring the CyberAccount transactions.

Signing the user operation hash

By default, both Ethers and Viem will convert a message string to UTF-8 bytes when signing a message, for siging userOperationHash we need to avoid this conversion.

• Signing userOperationHash using Viem

const walletClient = createWalletClient({
  chain: optimismGoerli,
  transport: custom(window.ethereum),
});

const accounts = await walletClient.requestAddresses();
const ownerAddress = accounts[0];

const sign = async (userOperationHash) => {
  return await walletClient.signMessage({
    account: ownerAddress,
    message: { raw: userOperationHash }, // pass the UO hash as a raw message
  });
};

• Signing userOperationHash using Ethers

const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

const sign = async (userOperationHash) => {
  return await signer.signMessage(hexToBytes(userOperationHash)); // convert the UO hash into bytes before passing into the signer
};

Properties

• chain Chain - The target chain that the CyberAccount is deployed on.
• owner Owner - The owner of the CyberAccount
• address Address - The contract address of the CyberAccount
• bundler CyberBundler - The Bundler for handling the CyberAccount user operations.
• paymaster CyberPaymaster - The Paymaster for sponsoring the CyberAccount transactions.

Methods

• isAccountDeployed: async () => boolean; - Checks if the CyberAccount is deployed.
• getAccountInitCode: async () => Hex; - Returns the init code of the CyberAccount.
• getCallData: (userOperationCallData: UserOperationCallData); - Get the encoded executable call data.
• getSignature: (rawSig: Hash) => Hash; - Get the wrapped signature for validation.
• sendTransaction: async (transcationData: TransactionData, {disablePaymaster?: boolean}) => Promise<Hash | null> - Send a transaction using the CyberAccount.
• estimateTransaction: async (transcationData: TransactionData, {disablePaymaster?: boolean}) => Promise<EstimateUserOperationReturn> - Estimate the credit cost of a transaction using the CyberAccount if the CyberPaymaster is provided, otherwise return the estimated gas from the bundler.

CyberBundler

CyberBundler is a standard ERC-4337 bundler class.

const cyberBundler = new CyberBundler({
  rpcUrl: "https://api.stg.cyberconnect.dev/cyberaccount/bundler/v1/rpc",
  appId: "ab23459a-32d7-4235-8129-77bd5de27fb1",
});

RPC Urls

• For development

  https://api.stg.cyberconnect.dev/cyberaccount/bundler/v1/rpc

• For production

  https://api.cyberconnect.dev/cyberaccount/bundler/v1/rpc

Methods

• sendUserOperation - Sends a user operation transaction to a bundler.
• getUserOperationReceipt - Gets a user operation receipt based on the userOperationHash.
• getUserOperationByHash - Returns a user operation based on the userOperationHash.
• estimateUserOperationGas - Estimate the gas cost of a user operation.
• supportedEntryPoints - Returns an array of the entryPoint addresses supported by the client.

CyberPaymaster

CyberPaymaster is a Paymaster class for sponsoring CyberAccount transactions.

const cyberPaymaster = new CyberPaymaster({
  rpcUrl: "<rpcUrl>",
  appId: "<appId>",
  generateJwt: (cyberAccountAddress) => jwt,
});

RPC Urls

• For development

  https://api.stg.cyberconnect.dev/cyberaccount/paymaster/v1/rpc

• For production

  https://api.cyberconnect.dev/cyberaccount/paymaster/v1/rpc

Methods

• getUserCredit - Returns the user credit.
• estimateUserOperation - Estimate the credit cost of a user operation.
• sponsorUserOperation - Returns the complete ready-for-sign user operation with paymasterAndData.
• rejectUserOperation - Rejects a user operation.
• listPendingUserOperations - Returns a list of pending user operations.
• topUp: ({amount, chainId, sender, to, writeContract}) => Promise<Hash> - Tops up the user credit, it returns the top up transaction hash.
  • amount - The amount of credit to top up.
  • chainId - The target chain id.
  • sender - (Optional) The address of the top up payer, it's CyberAccount owner address by default.,
  • to - (Optional) The address of the gas credit consumer, it's CyberAccount address by default.
  • writeContract: (request: TopUpContractRequest) => Promise<Hash> - (Optional) Overrides the default contract writing function.

RPC Errors

The RPC errors from the SDK are error instances from Viem. Two types of RPC errors can be thrown from the SDK:

1. Provider RPC errors
2. RPC Request errors

Properties

• name - The RPC error name
• code - The RPC error code
• details - The RPC error details
• shortMessage - The RPC error short message

We recommend using the code property to create a custom error handler.

Provider RPC Errors

Check all possible provider RPC errors here.

RPC Request Errors

Bundler RPC errors

For the bundler RPC errors, you can find the details in ERC-4337.

Paymaster RPC errors (CyberPaymaster)