Deploy a native crosschain token

In this quickstart, you deploy a new ERC-20 token on Arc Testnet, extend it to Base Sepolia so it exists on both blockchains, then mint tokens and transfer them crosschain. The deployment uses CREATE3 for deterministic addresses and Circle’s forwarding service to cover remote execution, so you only need gas on Arc Testnet.

Use the same wallet and salt on every blockchain. The tokenId is derived from (deployer address, salt). A different wallet or salt produces a different tokenId with no onchain error, and the bridge connection is silently broken.

Prerequisites

Before you begin, ensure that you’ve:

Installed Node.js v22+
Prepared an EVM testnet wallet whose private key you have available. This is the deployment wallet, and it must be the same wallet on every blockchain
- Added Arc Testnet to your wallet using the Testnet tab of Add Arc to a browser wallet in the Arc documentation
Funded the wallet with Arc Testnet USDC for gas from the Circle Faucet

Step 1: Set up the project

1.1. Create the project and install dependencies

mkdir cctpx-deploy
cd cctpx-deploy
npm init -y

npm pkg set type=module
npm pkg set scripts.start="tsx --env-file=.env index.ts"

npm install viem
npm install --save-dev @types/node tsx typescript

1.2. Configure TypeScript (optional)

This step is optional. It helps prevent missing types in your IDE or editor.

Create a tsconfig.json file:

npx tsc --init

Then, update the tsconfig.json file:

cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF

1.3. Set environment variables

Open .env in your editor and add:

PRIVATE_KEY=YOUR_DEPLOYER_PRIVATE_KEY

PRIVATE_KEY is the private key for the wallet that deploys the token. You must use this same wallet on every blockchain where you deploy.

Open .env in your editor rather than writing values with shell commands, and add .env to your .gitignore. This prevents credentials from leaking into your shell history or version control.

The npm run start command loads variables from .env using Node.js native env-file support.

This example uses one or more private keys for local testing. In production, use a secure key management solution and never expose or share private keys.

Step 2: Configure the script

Create index.ts and build it in three parts: clients, token params, then the service ABI used by later steps.

2.1. Set up clients and constants

import {
  createPublicClient,
  createWalletClient,
  encodePacked,
  formatUnits,
  http,
  keccak256,
  parseEventLogs,
  parseUnits,
  toBytes,
  zeroAddress,
  zeroHash,
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { arcTestnet, baseSepolia } from "viem/chains";

if (!process.env.PRIVATE_KEY) {
  throw new Error("Set PRIVATE_KEY in .env");
}

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

// CrossChainTokenService — same address on all testnets
const CCTS = "0x63753E722bd2C2A5DF6EE19C5106662208B81077" as const;
const IRIS = "https://iris-api-sandbox.circle.com";
const ARC_DOMAIN = 26;
const BASE_DOMAIN = 6;

const arc = createPublicClient({ chain: arcTestnet, transport: http() });
const arcWallet = createWalletClient({
  account,
  chain: arcTestnet,
  transport: http(),
});
const base = createPublicClient({ chain: baseSepolia, transport: http() });

You only need a Base public client for this path. Iris FORWARD submits the remote deploy and the destination mint, so no Base wallet is required.

2.2. Define token metadata and `DeploymentParams`

The salt and deployer address determine your tokenId and they must be identical on every blockchain. This example sets rateLimit and maxTransferAmount to type(uint256).max so transfers work once the token exists. For production caps, see Configure rate limits and transfer caps.

const NAME = "My Token";
const SYMBOL = "MTKN";
const DECIMALS = 6;
const SALT = keccak256(toBytes("my-token-v1"));
const MINT = parseUnits("100", DECIMALS);
const SEND = parseUnits("1", DECIMALS);
const MAX_UINT = 2n ** 256n - 1n;
const FINALITY = 2000; // standard transfer

// Encode addresses as 20-byte packed bytes (not ABI-padded 32-byte words).
const owner = encodePacked(["address"], [account.address]);
const params = {
  tokenManagerType: 0, // NATIVE_CROSSCHAIN_TOKEN
  tokenManagerOwner: owner,
  tokenManagerOperator: owner,
  tokenOwner: owner,
  tokenMinter: owner,
  tokenManagerSettings: {
    rateLimit: MAX_UINT,
    maxTransferAmount: MAX_UINT,
  },
} as const;

Sandbox omits initialSupply: Encoding a field the live ABI does not expect produces an empty revert. Some production layouts include it—verify the contract ABI for your target. See Contract reference.
rateLimit: 0 or maxTransferAmount: 0 blocks transfers: Defaults are zero if you omit non-zero values.
Pack addresses with encodePacked: encodeAbiParameters pads to 32 bytes and breaks the contract’s address decoding.

2.3. Add the `CrossChainTokenService` ABI

Add the service fragments this script calls:

deployCrossChainToken / deployRemoteCrossChainToken: home CREATE3 deploy and CCTP remote deploy
CrossChainTokenIdClaimed: source of tokenId after home deploy
resolveTokenAddress / resolveTokenManager: look up deployed addresses by tokenId
crossChainTransfer: initiate the Arc → Base transfer in step 7

const cctsAbi = [
  {
    type: "event",
    name: "CrossChainTokenIdClaimed",
    inputs: [
      { name: "tokenId", type: "bytes32", indexed: true },
      { name: "tokenAddress", type: "address", indexed: true },
      { name: "deployer", type: "address", indexed: false },
      { name: "salt", type: "bytes32", indexed: false },
    ],
  },
  {
    name: "resolveTokenAddress",
    type: "function",
    stateMutability: "view",
    inputs: [{ name: "tokenId", type: "bytes32" }],
    outputs: [{ type: "address" }],
  },
  {
    name: "resolveTokenManager",
    type: "function",
    stateMutability: "view",
    inputs: [{ name: "tokenId", type: "bytes32" }],
    outputs: [{ type: "address" }],
  },
  {
    name: "deployCrossChainToken",
    type: "function",
    stateMutability: "payable",
    inputs: [
      { name: "salt", type: "bytes32" },
      { name: "name", type: "string" },
      { name: "symbol", type: "string" },
      { name: "decimals", type: "uint8" },
      {
        name: "params",
        type: "tuple",
        components: [
          { name: "tokenManagerType", type: "uint8" },
          { name: "tokenManagerOwner", type: "bytes" },
          { name: "tokenManagerOperator", type: "bytes" },
          { name: "tokenOwner", type: "bytes" },
          { name: "tokenMinter", type: "bytes" },
          {
            name: "tokenManagerSettings",
            type: "tuple",
            components: [
              { name: "rateLimit", type: "uint256" },
              { name: "maxTransferAmount", type: "uint256" },
            ],
          },
        ],
      },
    ],
    outputs: [{ type: "bytes32" }],
  },
  {
    name: "deployRemoteCrossChainToken",
    type: "function",
    stateMutability: "payable",
    inputs: [
      { name: "salt", type: "bytes32" },
      { name: "destinationDomain", type: "uint32" },
      { name: "name", type: "string" },
      { name: "symbol", type: "string" },
      { name: "decimals", type: "uint8" },
      {
        name: "params",
        type: "tuple",
        components: [
          { name: "tokenManagerType", type: "uint8" },
          { name: "tokenManagerOwner", type: "bytes" },
          { name: "tokenManagerOperator", type: "bytes" },
          { name: "tokenOwner", type: "bytes" },
          { name: "tokenMinter", type: "bytes" },
          {
            name: "tokenManagerSettings",
            type: "tuple",
            components: [
              { name: "rateLimit", type: "uint256" },
              { name: "maxTransferAmount", type: "uint256" },
            ],
          },
        ],
      },
      {
        name: "signedFeeQuote",
        type: "tuple",
        components: [
          { name: "signedQuote", type: "bytes" },
          { name: "refundAddress", type: "address" },
        ],
      },
    ],
    outputs: [],
  },
  {
    name: "crossChainTransfer",
    type: "function",
    stateMutability: "payable",
    inputs: [
      { name: "tokenId", type: "bytes32" },
      { name: "amount", type: "uint256" },
      { name: "destinationDomain", type: "uint32" },
      { name: "destinationAddress", type: "bytes" },
      { name: "destinationCaller", type: "bytes32" },
      { name: "minFinalityThreshold", type: "uint32" },
      {
        name: "claim",
        type: "tuple",
        components: [
          { name: "signedQuote", type: "bytes" },
          { name: "refundAddress", type: "address" },
        ],
      },
      { name: "autoExecuteHookData", type: "bool" },
      { name: "hookData", type: "bytes" },
    ],
    outputs: [],
  },
] as const;

Step 3: Deploy on Arc Testnet

Call deployCrossChainToken on Arc Testnet. No fee quote is needed—this is a local CREATE3 deploy. The protocol creates the CrossChainToken ERC-20 and a NATIVE_CROSSCHAIN_TOKEN TokenManager in the same transaction. Read tokenId from the CrossChainTokenIdClaimed event on the receipt. Append steps 3–7 to index.ts in order. They form one try/catch block.

try {
  const homeHash = await arcWallet.writeContract({
    address: CCTS,
    abi: cctsAbi,
    functionName: "deployCrossChainToken",
    args: [SALT, NAME, SYMBOL, DECIMALS, params],
  });
  const homeReceipt = await arc.waitForTransactionReceipt({ hash: homeHash });
  if (homeReceipt.status !== "success") {
    throw new Error(`Home deploy reverted: ${homeHash}`);
  }

  const claimed = parseEventLogs({
    abi: cctsAbi,
    eventName: "CrossChainTokenIdClaimed",
    logs: homeReceipt.logs,
  })[0];
  if (!claimed) throw new Error("Missing CrossChainTokenIdClaimed");
  const tokenId = claimed.args.tokenId;

  console.log("Home deploy:", `https://explorer.testnet.arc.io/tx/${homeHash}`);
  console.log("tokenId:", tokenId);

For native deploys, CrossChainTokenIdClaimed emits tokenAddress as address(0). That is expected. Use tokenId from the event, then resolveTokenAddress for the real token address.
If home deploy already succeeded and you re-run this step with the same salt, the call reverts. Change the salt for a new token, or continue from the remote deploy using the existing tokenId.

Step 4: Quote and deploy remotely to Base Sepolia

Fetch an Iris fee quote with msgType: "DeployTokenMessage", then call deployRemoteCrossChainToken on Arc targeting Base Sepolia (domain 6). Pass the same salt, metadata, and DeploymentParams as the home deploy.

const deployQuoteRes = await fetch(
  `${IRIS}/v2/quote/cctpx/${tokenId}/${ARC_DOMAIN}/${BASE_DOMAIN}`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      amount: "1",
      feeToken: zeroAddress,
      requests: [
        {
          type: "FORWARD",
          params: {
            msgType: "DeployTokenMessage",
            autoExecuteHookData: false,
          },
        },
      ],
    }),
  },
);
if (!deployQuoteRes.ok) throw new Error(await deployQuoteRes.text());
const deployQuote = (await deployQuoteRes.json()) as {
  signedQuote: `0x${string}`;
  feeTotalAmount: string;
};

const remoteHash = await arcWallet.writeContract({
  address: CCTS,
  abi: cctsAbi,
  functionName: "deployRemoteCrossChainToken",
  args: [
    SALT,
    BASE_DOMAIN,
    NAME,
    SYMBOL,
    DECIMALS,
    params,
    {
      signedQuote: deployQuote.signedQuote,
      refundAddress: zeroAddress,
    },
  ],
  value: BigInt(deployQuote.feeTotalAmount),
});
if (
  (await arc.waitForTransactionReceipt({ hash: remoteHash })).status !==
  "success"
) {
  throw new Error(`Remote deploy reverted: ${remoteHash}`);
}
console.log(
  "Remote deploy:",
  `https://explorer.testnet.arc.io/tx/${remoteHash}`,
);

name, symbol, and decimals must match the home deploy. The protocol does not enforce consistency. A mismatch breaks user experience and indexers with no onchain error.

If the wallet already has gas on Base Sepolia, you can call deployCrossChainToken there with the same wallet, salt, and metadata instead of remote deploy, then continue from mint. That path skips the Iris deploy quote.

Step 5: Wait for the token on Base Sepolia

Poll resolveTokenAddress on Base until it returns a non-zero address. Iris typically delivers in a few minutes after the Arc transaction confirms.

let baseToken: `0x${string}` = zeroAddress;
const deployDeadline = Date.now() + 10 * 60_000;
while (baseToken === zeroAddress) {
  if (Date.now() > deployDeadline) {
    throw new Error("Timed out waiting for Base token");
  }
  await new Promise((r) => setTimeout(r, 15_000));
  try {
    baseToken = await base.readContract({
      address: CCTS,
      abi: cctsAbi,
      functionName: "resolveTokenAddress",
      args: [tokenId],
    });
  } catch {
    baseToken = zeroAddress;
  }
}
console.log("Base token:", baseToken);

Step 6: Mint on Arc Testnet

Mint supply to the deployer. tokenMinter in DeploymentParams must be your address (as in this example).

const arcToken = await arc.readContract({
  address: CCTS,
  abi: cctsAbi,
  functionName: "resolveTokenAddress",
  args: [tokenId],
});

const mintHash = await arcWallet.writeContract({
  address: arcToken,
  abi: [
    {
      name: "mint",
      type: "function",
      stateMutability: "nonpayable",
      inputs: [
        { name: "to", type: "address" },
        { name: "amount", type: "uint256" },
      ],
      outputs: [],
    },
  ] as const,
  functionName: "mint",
  args: [account.address, MINT],
});
if (
  (await arc.waitForTransactionReceipt({ hash: mintHash })).status !== "success"
) {
  throw new Error(`Mint reverted: ${mintHash}`);
}
console.log("Mint:", `https://explorer.testnet.arc.io/tx/${mintHash}`);

Step 7: Transfer Arc → Base with Iris FORWARD

Approve the Arc TokenManager, quote a TransferMessage with FORWARD, then call crossChainTransfer. Iris submits the destination mint so you do not need to call receiveMessage on Base, and you do not need Base ETH for this step.

  const manager = await arc.readContract({
    address: CCTS,
    abi: cctsAbi,
    functionName: "resolveTokenManager",
    args: [tokenId],
  });

  const approveHash = await arcWallet.writeContract({
    address: arcToken,
    abi: [
      {
        name: "approve",
        type: "function",
        stateMutability: "nonpayable",
        inputs: [
          { name: "spender", type: "address" },
          { name: "amount", type: "uint256" },
        ],
        outputs: [{ type: "bool" }],
      },
    ] as const,
    functionName: "approve",
    args: [manager, SEND],
  });
  if (
    (await arc.waitForTransactionReceipt({ hash: approveHash })).status !==
    "success"
  ) {
    throw new Error(`Approve reverted: ${approveHash}`);
  }

  const transferQuoteRes = await fetch(
    `${IRIS}/v2/quote/cctpx/${tokenId}/${ARC_DOMAIN}/${BASE_DOMAIN}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        amount: SEND.toString(),
        feeToken: zeroAddress,
        requests: [
          {
            type: "FORWARD",
            params: {
              msgType: "TransferMessage",
              destinationAddress: account.address,
            },
          },
        ],
      }),
    },
  );
  if (!transferQuoteRes.ok) throw new Error(await transferQuoteRes.text());
  const transferQuote = (await transferQuoteRes.json()) as {
    signedQuote: `0x${string}`;
    feeTotalAmount: string;
  };

  const transferHash = await arcWallet.writeContract({
    address: CCTS,
    abi: cctsAbi,
    functionName: "crossChainTransfer",
    args: [
      tokenId,
      SEND,
      BASE_DOMAIN,
      owner,
      zeroHash,
      FINALITY,
      {
        signedQuote: transferQuote.signedQuote,
        refundAddress: zeroAddress,
      },
      false,
      "0x",
    ],
    value: BigInt(transferQuote.feeTotalAmount),
  });
  if (
    (await arc.waitForTransactionReceipt({ hash: transferHash })).status !==
    "success"
  ) {
    throw new Error(`Transfer reverted: ${transferHash}`);
  }
  console.log(
    "Transfer:",
    `https://explorer.testnet.arc.io/tx/${transferHash}`,
  );

  const balanceOfAbi = [
    {
      name: "balanceOf",
      type: "function",
      stateMutability: "view",
      inputs: [{ name: "account", type: "address" }],
      outputs: [{ type: "uint256" }],
    },
  ] as const;

  const before = await base.readContract({
    address: baseToken,
    abi: balanceOfAbi,
    functionName: "balanceOf",
    args: [account.address],
  });
  const mintDeadline = Date.now() + 15 * 60_000;
  let baseBalance = before;
  while (baseBalance < before + SEND) {
    if (Date.now() > mintDeadline) {
      throw new Error("Timed out waiting for Base mint");
    }
    await new Promise((r) => setTimeout(r, 10_000));
    baseBalance = await base.readContract({
      address: baseToken,
      abi: balanceOfAbi,
      functionName: "balanceOf",
      args: [account.address],
    });
  }

  console.log(
    "Base balance:",
    `${formatUnits(baseBalance, DECIMALS)} ${SYMBOL}`,
  );
  console.dir({ tokenId, arcToken, baseToken }, { depth: null, colors: true });
} catch (error) {
  console.error(error);
  process.exit(1);
}

Run the script:

npm start

When Base balance prints, the token is deployed on both chains and a transfer has completed. Fast transfers require additional Circle coordination (FX pricing and backend indexing) before they work for newly deployed tokens—use FINALITY = 2000 (standard) until that is configured. To transfer other configured tokens with this same pattern, see Transfer EURC between Base and Arc and substitute your tokenId.

CCTP for USDC

CCTP for non-USDC

Gateway

Deploy a native crosschain token

Prerequisites

Step 1: Set up the project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

1.3. Set environment variables

Step 2: Configure the script

2.1. Set up clients and constants

2.2. Define token metadata and `DeploymentParams`

2.3. Add the `CrossChainTokenService` ABI

Step 3: Deploy on Arc Testnet

Step 4: Quote and deploy remotely to Base Sepolia

Step 5: Wait for the token on Base Sepolia

Step 6: Mint on Arc Testnet

Step 7: Transfer Arc → Base with Iris FORWARD

Prerequisites

Step 1: Set up the project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

1.3. Set environment variables

Step 2: Configure the script

2.1. Set up clients and constants

2.2. Define token metadata and DeploymentParams

2.3. Add the CrossChainTokenService ABI

Step 3: Deploy on Arc Testnet

Step 4: Quote and deploy remotely to Base Sepolia

Step 5: Wait for the token on Base Sepolia

Step 6: Mint on Arc Testnet

Step 7: Transfer Arc → Base with Iris FORWARD

2.2. Define token metadata and `DeploymentParams`

2.3. Add the `CrossChainTokenService` ABI