settlekit/apps/circle-bridge-kit-transfer
caelum0x c37ecca9d7 fix(apps): batch-1 bug-hunt across adopted apps (security + correctness)
Multi-agent bug-fix pass over the 11 adopted Arc/Circle apps; 21 files in 9 apps,
all build-verified. Highlights:
- arc-escrow: authorization bypass on validate-work/fund-release (any logged-in
  user could trigger withdraw/RELEASE_PAYMENT for any agreement) + USDC float
  rounding (8.2*1e6 -> 8199999.99) in on-chain amount conversion.
- arc-commerce: open redirect in /auth/confirm (unvalidated next param) +
  null-deref 500 on wallet-set.
- arc-fintech / arc-multichain-wallet / arc-nanopayments / arc-p2p-payments:
  input validation (400 vs 500), wallet-set null-deref guards, transfer/withdraw
  error handling.
- arc-prediction-markets, circle-bridge-kit, circle-cctp-crosschain: validation +
  hook/state fixes.

Reported-not-fixed (need product decisions): arc-commerce unauthenticated
openzeppelin webhook, unbounded Iris attestation poll, maxFee=amount-1, ETH
Sepolia USDC address mismatch — see workflow notes.
2026-06-21 23:09:45 +03:00
..
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:25 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:13 +03:00
2026-06-21 18:45:25 +03:00
2026-06-21 18:45:13 +03:00

Circle Bridge Kit Transfer

This sample app demonstrates how to use Circle's Bridge Kit to transfer USDC across chains with a wallet-connect experience for both EVM and Solana testnets.

App interface showing Metamask approval for burn

Prerequisites

  • Node.js 24+ (recommended LTS) and npm
  • An EVM wallet (e.g., MetaMask) and a Solana wallet (e.g., Phantom)
  • Testnet USDC on the relevant chains and native tokens for gas fees

Getting Started

  1. Install dependencies:

    npm install
    
  2. Start the app in development:

    npm run dev
    

This runs both:

  • Client (Vite) on http://localhost:5173
  • Preview server (Hono) on http://localhost:8787

The Vite dev server proxies /api to the preview server per vite.config.ts.

  1. Build for production:

    npm run build
    

Outputs static assets to dist/ and type-checks the project.

  1. Preview the production build locally:

    npm run preview
    

Serves dist/ using the Hono server on http://localhost:8787.

How It Works

  • Supported chains are fetched from Bridge Kit at runtime and mapped to Wagmi in src/lib/wagmiConfig.ts and src/lib/mapChains.ts.
  • Wallet wiring:
    • useEvmAdapter builds a Bridge Kit EVM adapter from the active Wagmi connector provider.
    • useSolanaWallet connects to window.solana and builds a Solana adapter.
  • The main flow is in src/App.tsx:
    • Pick source and destination chains (testnets), enter USDC amount, connect wallets.
    • On submit, we optionally switch the EVM network, then call useBridge().bridge(...).
    • Bridge Kit emits events; the UI updates progress and logs.
    • On success, balances refresh and success UI appears.
  • USDC balances are queried via Bridge Kit actions (usdc.balanceOf) in src/hooks/useUsdcBalance.ts.

File Highlights

  • src/App.tsx: Main UI and bridging flow
  • src/lib/wagmiConfig.ts: Dynamically builds Wagmi config from Bridge Kit chains
  • src/lib/mapChains.ts: Maps Bridge Kit chain metadata to Wagmi Chain
  • src/hooks/useBridge.ts: Thin wrapper around BridgeKit().bridge(...) with event handling
  • src/hooks/useEvmAdapter.ts: Creates EVM adapter from Wagmi provider
  • src/hooks/useSolanaWallet.ts: Connects Solana wallet and creates adapter
  • src/hooks/useUsdcBalance.ts: Reads USDC balances per chain
  • api/server.ts: Hono server to serve the built app (dist/)

Usage Notes

  • This sample is scoped to testnets (filters Bridge Kit chains by isTestnet === true).
  • If multiple EVM providers are present (e.g., Phantom EVM + MetaMask), the app attempts a sane default; you can switch via the wallet UI.
  • If wallet network switching is rejected, the bridging flow will skip and you can try again.
  • After use, disconnecting directly from your wallet UI can improve reliability between sessions.

Scripts

  • npm run dev: Run preview server and Vite dev server concurrently
  • npm run dev:server: Start the Hono preview server with live reload
  • npm run dev:client: Start Vite dev server
  • npm run build: Build static assets and run type-checking
  • npm run preview: Serve dist/ via Hono server

Security & Usage Model

This sample application:

  • Assumes testnet or sandbox usage only
  • Does not store private keys in plaintext
  • Uses environment variables for secrets
  • Is not intended for production use without modification

See SECURITY.md for vulnerability reporting guidelines. Please report issues privately via Circle's bug bounty program.

License

License