Typescript Integration

👨🏻‍💻 Integrate Circulator with TypeScript

Circulator Documentation

Basic Setup

We recommend using viem to integrate with the contract:

import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { baseSepolia } from 'viem/chains'; 

const privateKey = '0x...';
const rpc = 'Put in your RPC';

// create viem account
const account = privateKeyToAccount(privateKey);

const user = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(rpc),
});

Standard Mode

Link to Deployed Addresses

import { http, encodeFunctionData, erc20Abi, pad, parseAbi } from 'viem';

const inputAmount = BigInt(10_000000);
const outputAmount = BigInt(9_900000); // Minimum amount you want to receive
const recipient = user.account.address;
// Please refer to the "Deployed Addresses"
const usdc = '0x...';
const circulator = '0x...';
const destDomain = 0;
const fillDeadline = BigInt(Math.floor(Date.now() / 1000) + 3600); // 1 hour from now
const circulateType = 0; // 0 for CCTP, 1 for AcrossV3

const approveTx = await user.sendTransaction({
  to: usdc,
  data: encodeFunctionData({
    functionName: 'approve',
    abi: erc20Abi,
    args: [circulator, inputAmount],
  }),
});

const txHash = await user.sendTransaction({
  to: circulator,
  data: encodeFunctionData({
    functionName: 'circulate',
    abi: parseAbi([
      'function circulate(uint256 _inputAmount, uint256 _outputAmount, address _recipient, uint32 _destinationDomain, uint32 _fillDeadline, uint8 _type) external returns (uint64 nonce)',
    ]),
    args: [
      inputAmount,
      outputAmount,
      recipient,
      destDomain,
      fillDeadline,
      circulateType,
    ],
  }),
});

Gasless Mode

Gasless mode requires the user to sign 2 signatures, and then interact with our API server to relay the transaction.

Getting Permit Signature

// Permit.ts
import { WalletClient, slice, hexToNumber, Hex } from 'viem';

export type PermitSignature = {
  r: Hex;
  s: Hex;
  v: number;
};

export type SignPermitProps = {
  /** Address of the token to approve */
  contractAddress: Hex;
  /** Name of the token to approve.
   * Corresponds to the `name` method on the ERC-20 contract. Please note this must match exactly byte-for-byte */
  erc20Name: string;
  /** Owner of the tokens. Usually the currently connected address. */
  ownerAddress: Hex;
  /** Address to grant allowance to */
  spenderAddress: Hex;
  /** Expiration of this approval, in SECONDS */
  deadline: bigint;
  /** Numerical chainId of the token contract */
  chainId: number;
  /** Defaults to 1. Some tokens need a different version, check the [PERMIT INFORMATION](<https://github.com/vacekj/wagmi-permit/blob/main/PERMIT.md>) for more information */
  permitVersion?: string;
  /** Permit nonce for the specific address and token contract. You can get the nonce from the `nonces` method on the token contract. */
  nonce: bigint;
};

export type Eip2612Props = SignPermitProps & {
  /** Amount to approve */
  value: bigint;
};

export const signPermit = async (
  walletClient: WalletClient,
  {
    contractAddress,
    erc20Name,
    ownerAddress,
    spenderAddress,
    value,
    deadline,
    nonce,
    chainId,
    permitVersion,
  }: Eip2612Props,
): Promise<PermitSignature> => {
  // nonce, name and version can be read from USDC

  const types = {
    Permit: [
      { name: 'owner', type: 'address' },
      { name: 'spender', type: 'address' },
      { name: 'value', type: 'uint256' },
      { name: 'nonce', type: 'uint256' },
      { name: 'deadline', type: 'uint256' },
    ],
  };

  const domainData = {
    name: erc20Name ?? 'USDC',
    version: permitVersion ?? '2',
    chainId: chainId,
    verifyingContract: contractAddress,
  };

  const message = {
    owner: ownerAddress,
    spender: spenderAddress,
    value,
    nonce,
    deadline,
  };

  const signature = await walletClient.signTypedData({
    account: ownerAddress,
    message,
    domain: domainData,
    primaryType: 'Permit',
    types,
  });
  const [r, s, v] = [slice(signature, 0, 32), slice(signature, 32, 64), slice(signature, 64, 65)];
  return { r, s, v: hexToNumber(v) };
};

Getting DelegateCirculate Signature

import { Address, Hex, hexToNumber, slice, type WalletClient } from 'viem';

export type Signature = {
  r: Hex;
  s: Hex;
  v: number;
};

export enum CirculateType {
  Cctp = 0,
  AcrossV3 = 1,
}

export type DelegateProps = {
  /** Address of the circulator contract */
  contractAddress: Hex;
  /** Signer */
  signer: Address;
  /** Address to grant allowance to */
  recipient: Address;
  /** Numerical chainId of the token contract */
  chainId: number;
  /** Numerical chainId of the destination chain */
  destinationDomain: number;
  /** Circulate type */
  circulateType: CirculateType;
  /** Nonce */
  nonce: bigint;
  /** Fill deadline timestamp */
  fillDeadline: number;
};

export const signDelegate = async (
  walletClient: WalletClient,
  {
    contractAddress,
    signer,
    recipient,
    chainId,
    nonce,
    destinationDomain,
    circulateType,
    fillDeadline,
  }: DelegateProps,
): Promise<Signature> => {
  const types = {
    DelegateCirculate: [
      { name: 'destinationDomain', type: 'uint32' },
      { name: 'fillDeadline', type: 'uint32' },
      { name: 'circulateType', type: 'uint8' },
      { name: 'recipient', type: 'address' },
      { name: 'outputAmount', type: 'uint256' },
      { name: 'nonce', type: 'uint256' },
    ],
  };

  const domainData = {
    name: 'Circulator',
    version: 'v1',
    chainId: chainId,
    verifyingContract: contractAddress,
  };

  const message = {
    destinationDomain: destinationDomain,
    recipient,
    nonce,
    fillDeadline: fillDeadline,
    circulateType: circulateType,
    outputAmount: BigInt(0),
  };

  const signature = await walletClient.signTypedData({
    account: signer,
    message,
    domain: domainData,
    primaryType: 'DelegateCirculate',
    types,
  });
  const [r, s, v] = [slice(signature, 0, 32), slice(signature, 32, 64), slice(signature, 64, 65)];
  return { r, s, v: hexToNumber(v) };
};

API Endpoint

• URL: /api/delegate

• Method: POST

• Content-Type: application/json

Request Body

Field	Type	Description
sender	string	The address of the sender (e.g., "0x...")
recipient	string	The address of the recipient (e.g., "0x...")
sourceChain	string	The key identifier of the source chain
destinationDomain	number	The numerical identifier of the destination domain (must be a valid CCTP chain ID)
amount	string	The amount of tokens to be circulated
deadline	string	The deadline for the permit signature
fillDeadline	string	The deadline for filling the circulate request
circulateType	number	The type of circulation (0 for CCTP, 1 for AcrossV3)
permitV	number	The v component of the permit signature
permitR	string	The r component of the permit signature
permitS	string	The s component of the permit signature
delegateV	number	The v component of the delegate signature
delegateR	string	The r component of the delegate signature
delegateS	string	The s component of the delegate signature

Note: All fields are required. The destinationDomain must be a valid CCTP chain ID.

Response

• Success Response:

  • Code: 200

  • Content: { "txHash": "0x..." }

• Error Response:

  • Code: 400

  • Content: { "error": "Missing fields" }

Usage Example

const CIRCULATOR_API_DOMAIN = 'https://circulator-monorepo.vercel.app/';

const callCirculatorAPI = async (
  sender,
  recipient,
  sourceChain,
  destinationDomain,
  amount,
  deadline,
  fillDeadline,
  circulateType,
  permitSig,
  delegateSig
) => {
  const response = await fetch(`${CIRCULATOR_API_DOMAIN}/api/delegate`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sender,
      recipient,
      sourceChain,
      destinationDomain,
      amount,
      deadline,
      fillDeadline,
      circulateType,
      permitV: permitSig.v,
      permitR: permitSig.r,
      permitS: permitSig.s,
      delegateV: delegateSig.v,
      delegateR: delegateSig.r,
      delegateS: delegateSig.s,
    }),
  });

  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`API call failed: ${errorData.error}`);
  }
  
  const result = await response.json();
  console.log('Transaction Hash:', result.txHash);
  
  return result;
};

Full Example: Sending Delegate request to our API

const CIRCULATOR_API_DOMAIN = 'https://circulator-monorepo.vercel.app/';

const amount = BigInt(10_000000);
const deadline = BigInt(Math.floor(Date.now() / 1000) + 3600);
const fillDeadline = Math.floor(Date.now() / 1000) + 3600;
const recipient = user.account.address;
// Please refer to the "Deployed Addresses"
const usdc = '0x...';
const circulator = '0x...';
const destDomain = 0; // Must be a valid CCTP chain ID
const sourceChain = 'BASE_SEPOLIA'; // Example chain key
const circulateType = 0; // 0 for CCTP, 1 for AcrossV3

// get all info from USDC
const [name, version, nonce] = await Promise.all([
  // ... [implementation details]
])

const permitSig = await signPermit(user, {
  contractAddress: usdc,
  erc20Name: name,
  ownerAddress: user.account.address,
  spenderAddress: circulator,
  value: amount,
  deadline,
  nonce,
  chainId: chainId,
  permitVersion: versionFromContract,
});

// get nonce from Circulator
const [delegateNonce] = await Promise.all([
  // ... [implementation details]
])

const delegateSig = await signDelegate(user, {
  contractAddress: circulator,
  signer: user.account.address,
  recipient,
  chainId: chainId,
  nonce: delegateNonce,
  destinationDomain: destDomain,
  circulateType,
  fillDeadline,
});

// send to our API
const result = await callCirculatorAPI(
  user.account.address,
  recipient,
  sourceChain,
  destDomain,
  amount.toString(),
  deadline.toString(),
  fillDeadline.toString(),
  circulateType,
  permitSig,
  delegateSig
);

console.log('Transaction Hash:', result.txHash);