chore: update readme and patch wallet error (#4)

This PR:
- updates the README to the recommended format for sample apps
- fixes a breaking issue when there is more than 1 connected wallet
- removes unused dependencies and updates Circle SDKs to latest versions

Author: hjchen-circle

.github/workflows/ci.yml

@@ -15,11 +15,8 @@ jobs:
       - name: Install Node
         uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
 
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
-
       - name: Install dependencies
-        run: pnpm install
+        run: npm install
 
   scan:
     needs: lint-and-test

README.md

@@ -1,45 +1,65 @@
 # Arc Multichain Wallet
 
-This sample app demonstrates how developers can build the best USDC interoperability UX for wallets using Arc and Gateway.
+A sample application demonstrating how to build optimal USDC interoperability UX for wallets using Arc and Circle Gateway. This app showcases unified balance management, deposits, and cross-chain transfers across multiple EVM chains using Next.js and Supabase.
 
-### Install dependencies
+<img width="830" height="658" alt="Interface for depositing to and transfering from a Gateway balance" src="public/screenshot.png" />
 
-```bash
-# Install dependencies
-pnpm install
+## Prerequisites
 
-# Configure environment variables
-cp .env.example .env.local
-```
+- Node.js 20.x or newer
+- npm (automatically installed when Node.js is installed)
+- Docker (for running Supabase locally)
+- Circle Developer Controlled Wallets [API key](https://console.circle.com/signin) and [Entity Secret](https://developers.circle.com/wallets/dev-controlled/register-entity-secret)
 
-Update `.env.local`:
+## Getting Started
 
-```ini
-# Supabase
-NEXT_PUBLIC_SUPABASE_URL=your-project-url
-NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-publishable-or-anon-key
+1. Clone the repository and install dependencies:
 
-# Circle
-CIRCLE_API_KEY=your-circle-api-key
-CIRCLE_ENTITY_SECRET=your-circle-entity-secret
-```
+   ```bash
+   git clone git@github.com:circlefin/arc-multichain-wallet.git
+   cd arc-multichain-wallet
+   npm install
+   ```
 
-### Start Supabase
+2. Create a `.env.local` file in the project root:
 
-```bash
-pnpx supabase start
-```
+   ```bash
+   cp .env.example .env.local
+   ```
 
-### Run Development Server
+   Required variables:
 
-```bash
-pnpm run dev
-```
+   ```bash
+   # Supabase
+   NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
+   NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your_publishable_or_anon_key
 
-Visit [http://localhost:3000/wallet](http://localhost:3000/wallet)
+   # Circle
+   CIRCLE_API_KEY=your_circle_api_key
+   CIRCLE_ENTITY_SECRET=your_entity_secret
+   ```
+
+3. Start Supabase locally:
+
+   ```bash
+   npx supabase start
+   ```
+
+4. Start the development server:
+
+   ```bash
+   npm run dev
+   ```
+
+   The app will be available at `http://localhost:3000`.
 
 ## How It Works
 
+- Built with [Next.js](https://nextjs.org/) and [Supabase](https://supabase.com/)
+- Uses [Circle Gateway](https://developers.circle.com/gateway) for unified USDC balance and cross-chain transfers
+- Integrates [Circle Developer Controlled Wallets](https://developers.circle.com/wallets/dev-controlled) for server-side wallet operations
+- Demonstrates wallet connectivity with [Wagmi](https://wagmi.sh/) and [Viem](https://viem.sh/)
+
 ### Unified Balance
 
 When you deposit USDC to the Gateway Wallet, it becomes part of your unified balance accessible from any supported chain. The Gateway Wallet uses the same address on all chains: `0x0077777d7EBA4688BDeF3E311b846F25870A19B9`
@@ -57,13 +77,36 @@ When you deposit USDC to the Gateway Wallet, it becomes part of your unified bal
 3. Call `gatewayMint()` on destination chain
 4. USDC minted on destination
 
-## Security Notes
+## Environment Variables
+
+| Variable                              | Scope       | Purpose                                                                  |
+| ------------------------------------- | ----------- | ------------------------------------------------------------------------ |
+| `NEXT_PUBLIC_SUPABASE_URL`            | Public      | Supabase project URL                                                     |
+| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | Public     | Supabase anonymous/public key                                            |
+| `CIRCLE_API_KEY`                      | Server-side | Circle API key for Gateway operations                                    |
+| `CIRCLE_ENTITY_SECRET`                | Server-side | Circle entity secret for wallet operations                               |
 
-- This is a **testnet demonstration** only
+## Usage Notes
+
+- Designed for testnet only
+- Requires valid Circle API credentials and Supabase configuration
 - Private keys are processed server-side and never stored
 - Never use mainnet private keys with this application
-- Always use HTTPS in production
-- Consider hardware wallet integration for production use
+
+## Scripts
+
+- `npm run dev`: Start Next.js development server with auto-reload
+- `npx supabase start`: Start local Supabase instance
+
+## Security & Usage Model
+
+This sample application:
+- Assumes testnet usage only
+- Handles secrets via environment variables
+- Processes private keys server-side without storage
+- 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.
 
 ## Resources
 

app/api/gateway/deposit/route.ts

@@ -74,19 +74,21 @@ export async function POST(req: NextRequest) {
     const amountInAtomicUnits = BigInt(Math.floor(parsedAmount * 1_000_000));
 
     // Custodial flow (Circle Wallet)
-    const { data: wallet, error: walletError } = await supabase
+    const { data: wallets, error: walletError } = await supabase
       .from("wallets")
       .select("circle_wallet_id")
       .eq("user_id", user.id)
-      .single();
+      .limit(1);
 
-    if (walletError || !wallet) {
+    if (walletError || !wallets || wallets.length === 0) {
       return NextResponse.json(
         { error: "No Circle wallet found for this user." },
         { status: 404 }
       );
     }
 
+    const wallet = wallets[0];
+
     const txHash = await initiateDepositFromCustodialWallet(
       wallet.circle_wallet_id,
       chain as SupportedChain,

app/api/gateway/transfer/route.ts

@@ -74,19 +74,21 @@ export async function POST(req: NextRequest) {
     const amountInAtomicUnits = BigInt(Math.floor(parseFloat(amount) * 1_000_000));
 
     // Custodial flow (Circle Wallet)
-    const { data: wallet, error: walletError } = await supabase
+    const { data: wallets, error: walletError } = await supabase
       .from("wallets")
       .select("circle_wallet_id")
       .eq("user_id", user.id)
-      .single();
+      .limit(1);
 
-    if (walletError || !wallet?.circle_wallet_id) {
+    if (walletError || !wallets || wallets.length === 0) {
       return NextResponse.json(
         { error: "No Circle wallet found for this user." },
         { status: 404 }
       );
     }
 
+    const wallet = wallets[0];
+
     const transferResult = await transferUnifiedBalanceCircle(
       wallet.circle_wallet_id,
       amountInAtomicUnits,

package.json

@@ -7,9 +7,7 @@
     "lint": "eslint ."
   },
   "dependencies": {
-    "@circle-fin/circle-sdk": "^2.9.0",
-    "@circle-fin/developer-controlled-wallets": "^9.2.1",
-    "@circle-fin/smart-contract-platform": "^9.2.1",
+    "@circle-fin/developer-controlled-wallets": "^10.0.1",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
@@ -26,17 +24,15 @@
     "@wagmi/core": "^2.22.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "dotenv": "^17.2.3",
     "lucide-react": "^0.548.0",
     "next": "latest",
     "next-themes": "^0.4.6",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.3.1",
-    "uuid": "^13.0.0",
-    "viem": "^2.38.5",
-    "wagmi": "^2.19.1"
+    "viem": "^2.44.4",
+    "wagmi": "^2.19.5"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
@@ -50,6 +46,5 @@
     "tailwindcss": "^4.1.16",
     "tailwindcss-animate": "^1.0.7",
     "typescript": "^5.9.3"
-  },
-  "packageManager": "pnpm@10.24.0+sha512.01ff8ae71b4419903b65c60fb2dc9d34cf8bb6e06d03bde112ef38f7a34d6904c424ba66bea5cdcf12890230bf39f9580473140ed9c946fef328b6e5238a345a"
+  }
 }