merge Implement multichain wallet architecture with Gateway improvements (#5) into master (#6)

this is for merging #5 to master, squash merged the PR into a temp
branch to workaround commit signing issues.

Co-authored-by: Frederico Dal Grande <32470527+dalgrande@users.noreply.github.com>
Co-authored-by: Anthony Kelani <anthony.kelani@circle.com>
Co-authored-by: HJ Chen <221941357+hjchen-circle@users.noreply.github.com>

Author: 4 people

.github/workflows/ci.yml

@@ -18,12 +18,12 @@ jobs:
       - name: Install dependencies
         run: npm install
 
-  scan:
-    needs: lint-and-test
-    if: ${{ github.event_name == 'pull_request' && github.event.repository.private == false }}
-    uses: circlefin/circle-public-github-workflows/.github/workflows/pr-scan.yaml@v1
+  # scan:
+  #   needs: lint-and-test
+  #   if: ${{ github.event_name == 'pull_request' && github.event.repository.private == false }}
+  #   uses: circlefin/circle-public-github-workflows/.github/workflows/pr-scan.yaml@v1
 
-  release-sbom:
-    needs: lint-and-test
-    if: github.event_name == 'push'
-    uses: circlefin/circle-public-github-workflows/.github/workflows/attach-release-assets.yaml@v1
+  # release-sbom:
+  #   needs: lint-and-test
+  #   if: github.event_name == 'push'
+  #   uses: circlefin/circle-public-github-workflows/.github/workflows/attach-release-assets.yaml@v1

README.md

@@ -20,7 +20,7 @@ A sample application demonstrating how to build optimal USDC interoperability UX
    cd arc-multichain-wallet
    npm install
    ```
-
+   
 2. Create a `.env.local` file in the project root:
 
    ```bash
@@ -39,10 +39,21 @@ A sample application demonstrating how to build optimal USDC interoperability UX
    CIRCLE_ENTITY_SECRET=your_entity_secret
    ```
 
-3. Start Supabase locally:
+3. Set up Supabase (Local)
+   This project uses **local Supabase** via Docker for development:
 
    ```bash
+   # Start local Supabase (requires Docker)
    npx supabase start
+
+   # Push database migrations
+   npx supabase db push
+   ```
+   **Note:** If you prefer cloud-hosted Supabase, you can use:
+   
+   ```bash
+   npx supabase link
+   npx supabase db push
    ```
 
 4. Start the development server:
@@ -108,6 +119,34 @@ This sample application:
 
 See `SECURITY.md` for vulnerability reporting guidelines. Please report issues privately via Circle's bug bounty program.
 
+## Getting Testnet USDC
+
+To test the application, you'll need testnet USDC on the supported chains. Use the Circle Faucet to get free testnet tokens:
+
+### Using the Circle Faucet
+
+1. **Get Your Wallet Address**: After signing up, your Circle Wallet addresses will be displayed in the dashboard
+2. **Visit the Faucet**: Go to [https://faucet.circle.com/](https://faucet.circle.com/)
+3. **Request Tokens**: 
+   - Enter your wallet address
+   - Select the desired testnet (Arc Testnet, Base Sepolia, or Avalanche Fuji)
+   - Request USDC
+4. **Wait for Confirmation**: Transactions typically confirm within a few minutes
+5. **Deposit to Gateway**: Once received, use the "Deposit" tab to add USDC to your Gateway balance
+
+### Supported Testnets
+
+- **Arc Testnet**: Primary chain for deposits and Gateway operations
+- **Base Sepolia**: Ethereum Layer 2 testnet
+- **Avalanche Fuji**: Avalanche testnet
+
+### Note on Gas Fees
+
+When transferring USDC cross-chain, you'll need native tokens on the destination chain to pay for gas fees:
+- **Arc Testnet**: USDC (no additional gas token needed)
+- **Base Sepolia**: ETH (get from [Base Sepolia Faucet](https://www.alchemy.com/faucets/base-sepolia))
+- **Avalanche Fuji**: AVAX (get from [Avalanche Faucet](https://core.app/tools/testnet-faucet/))
+
 ## Resources
 
 - [Circle Gateway Documentation](https://developers.circle.com/gateway)

app/api/gateway/deposit/route.ts

@@ -24,6 +24,8 @@ import {
 import { createClient } from "@/lib/supabase/server";
 
 export async function POST(req: NextRequest) {
+  let requestBody: any = {};
+  
   try {
     const supabase = await createClient();
     const {
@@ -34,7 +36,8 @@ export async function POST(req: NextRequest) {
       return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
     }
 
-    const { chain, amount } = await req.json();
+    requestBody = await req.json();
+    const { chain, amount } = requestBody;
 
     if (!chain || !amount) {
       return NextResponse.json(
@@ -73,26 +76,42 @@ export async function POST(req: NextRequest) {
 
     const amountInAtomicUnits = BigInt(Math.floor(parsedAmount * 1_000_000));
 
-    // Custodial flow (Circle Wallet)
+    // Get the user's multichain SCA wallet
     const { data: wallets, error: walletError } = await supabase
       .from("wallets")
-      .select("circle_wallet_id")
+      .select("circle_wallet_id, wallet_set_id, address")
       .eq("user_id", user.id)
+      .eq("type", "sca")
       .limit(1);
 
-    if (walletError || !wallets || wallets.length === 0) {
+    if (walletError) {
+      console.error("Database error fetching wallets:", walletError);
       return NextResponse.json(
-        { error: "No Circle wallet found for this user." },
+        { error: "Database error when fetching wallets." },
+        { status: 500 }
+      );
+    }
+
+    if (!wallets || wallets.length === 0) {
+      console.log(`No SCA wallet found for user ${user.id}`);
+      return NextResponse.json(
+        { error: "No Circle wallet found. Please ensure wallet is created during signup." },
         { status: 404 }
       );
     }
 
     const wallet = wallets[0];
 
+    // Get or create EOA signer wallet (multichain)
+    const { getOrCreateGatewayEOAWallet } = await import("@/lib/circle/create-gateway-eoa-wallets");
+    const { address: eoaAddress } = await getOrCreateGatewayEOAWallet(user.id, chain);
+
+    // Deposit to Gateway and add EOA as delegate (allows EOA to sign burn intents)
     const txHash = await initiateDepositFromCustodialWallet(
       wallet.circle_wallet_id,
       chain as SupportedChain,
-      amountInAtomicUnits
+      amountInAtomicUnits,
+      eoaAddress as `0x${string}`
     );
 
     // Store transaction in database
@@ -126,14 +145,13 @@ export async function POST(req: NextRequest) {
         data: { user },
       } = await supabase.auth.getUser();
 
-      if (user) {
-        const body = await req.json();
+      if (user && requestBody.chain) {
         await supabase.from("transaction_history").insert([
           {
             user_id: user.id,
-            chain: body.chain,
+            chain: requestBody.chain,
             tx_type: "deposit",
-            amount: parseFloat(body.amount || 0),
+            amount: parseFloat(requestBody.amount || 0),
             status: "failed",
             reason: error.message || "Unknown error",
             created_at: new Date().toISOString(),

app/api/gateway/eoa-wallets/route.ts

@@ -0,0 +1,71 @@
+/**
+ * Copyright 2026 Circle Internet Group, Inc.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+import { createClient } from "@/lib/supabase/server";
+import { circleDeveloperSdk } from "@/lib/circle/sdk";
+import type { SupportedChain } from "@/lib/circle/gateway-sdk";
+
+export async function GET(req: NextRequest) {
+  const supabase = await createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  try {
+    const { getGatewayEOAWalletId } = await import("@/lib/circle/create-gateway-eoa-wallets");
+    
+    const chains = ["BASE-SEPOLIA", "AVAX-FUJI", "ARC-TESTNET"];
+    const chainMap: Record<string, SupportedChain> = {
+      "BASE-SEPOLIA": "baseSepolia",
+      "AVAX-FUJI": "avalancheFuji",
+      "ARC-TESTNET": "arcTestnet",
+    };
+    
+    const wallets = await Promise.all(
+      chains.map(async (blockchain) => {
+        try {
+          const { walletId, address } = await getGatewayEOAWalletId(user.id, blockchain);
+          return {
+            chain: chainMap[blockchain],
+            blockchain,
+            walletId,
+            address,
+          };
+        } catch (error) {
+          console.error(`Error fetching EOA wallet for ${blockchain}:`, error);
+          return null;
+        }
+      })
+    );
+
+    return NextResponse.json({
+      wallets: wallets.filter(w => w !== null),
+    });
+  } catch (error: any) {
+    console.error("Error fetching EOA wallets:", error);
+    return NextResponse.json(
+      { error: error.message || "Failed to fetch EOA wallets" },
+      { status: 500 }
+    );
+  }
+}

app/api/gateway/init-eoa-wallets/route.ts

@@ -0,0 +1,81 @@
+/**
+ * Copyright 2026 Circle Internet Group, Inc.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { NextRequest, NextResponse } from "next/server";
+import { createClient } from "@/lib/supabase/server";
+import { storeGatewayEOAWalletForUser } from "@/lib/circle/create-gateway-eoa-wallets";
+
+export async function POST(req: NextRequest) {
+  const supabase = await createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+
+  if (!user) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  try {
+    // Check if EOA wallet already exists for this user
+    const { data: existingWallet } = await supabase
+      .from("wallets")
+      .select("circle_wallet_id, address")
+      .eq("user_id", user.id)
+      .eq("type", "gateway_signer")
+      .limit(1);
+
+    if (existingWallet && existingWallet.length > 0) {
+      return NextResponse.json({
+        success: true,
+        message: "Gateway EOA wallet already exists for this user",
+        wallet: existingWallet[0],
+      });
+    }
+
+    // Get the user's wallet_set_id from their SCA wallet
+    const { data: scaWallet, error: scaError } = await supabase
+      .from("wallets")
+      .select("wallet_set_id")
+      .eq("user_id", user.id)
+      .eq("type", "sca")
+      .limit(1)
+      .single();
+
+    if (scaError || !scaWallet) {
+      return NextResponse.json(
+        { error: "No SCA wallet found. Please create a wallet first." },
+        { status: 404 }
+      );
+    }
+
+    // Create multichain EOA wallet for the user
+    const wallet = await storeGatewayEOAWalletForUser(user.id, scaWallet.wallet_set_id);
+
+    return NextResponse.json({
+      success: true,
+      message: "Gateway EOA wallet created successfully",
+      wallet: wallet[0],
+    });
+  } catch (error: any) {
+    console.error("Error initializing EOA wallet:", error);
+    return NextResponse.json(
+      { error: error.message || "Failed to initialize EOA wallet" },
+      { status: 500 }
+    );
+  }
+}