Merge branch 'feat/multichain-wallet-gateway-improvements' of github.com:akelani-circle/arc-multichain-wallet into feat/multichain-wallet-gateway-improvements

Author: akelani-circle

README.md

@@ -1,70 +1,76 @@
 # 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.
 
-## Prerequisites
-
-### Clone the Repository
-
-```bash
-git clone https://github.com/circlefin/arc-multichain-wallet.git
-cd arc-multichain-wallet
-```
-
-### Install Dependencies
+<img width="830" height="658" alt="Interface for depositing to and transfering from a Gateway balance" src="public/screenshot.png" />
 
-This project uses **npm** as the package manager. Make sure you have Node.js 18+ installed.
+## Prerequisites
 
-```bash
-npm install
-```
+- 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)
 
-### Configure Environment Variables
+## Getting Started
 
-```bash
-cp .env.example .env
-```
+1. Clone the repository and install dependencies:
 
-Update `.env` with your credentials:
+   ```bash
+   git clone git@github.com:circlefin/arc-multichain-wallet.git
+   cd arc-multichain-wallet
+   npm install
+   ```
+   
+2. Create a `.env.local` file in the project root:
 
-```ini
-# Supabase
-NEXT_PUBLIC_SUPABASE_URL=your-project-url
-NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-publishable-or-anon-key
+   ```bash
+   cp .env.example .env.local
+   ```
 
-# Circle
-CIRCLE_API_KEY=your-circle-api-key
-CIRCLE_ENTITY_SECRET=your-circle-entity-secret
-```
+   Required variables:
 
-### Set Up Supabase (Local)
+   ```bash
+   # Supabase
+   NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
+   NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your_publishable_or_anon_key
 
-This project uses **local Supabase** via Docker for development:
+   # Circle
+   CIRCLE_API_KEY=your_circle_api_key
+   CIRCLE_ENTITY_SECRET=your_entity_secret
+   ```
 
-```bash
-# Start local Supabase (requires Docker)
-npx supabase start
+3. Set up Supabase (Local)
+   This project uses **local Supabase** via Docker for development:
 
-# Push database migrations
-npx supabase db push
-```
+   ```bash
+   # Start local Supabase (requires Docker)
+   npx supabase start
 
-**Note:** If you prefer cloud-hosted Supabase, you can use:
-```bash
-npx supabase link
-npx supabase db push
-```
+   # 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
+   ```
 
-### Run Development Server
+4. Start the development server:
 
-```bash
-npm run dev
-```
+   ```bash
+   npm run dev
+   ```
 
-Visit [http://localhost:3000/wallet](http://localhost:3000/wallet)
+   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`
@@ -82,13 +88,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.
 
 ## Getting Testnet USDC
 

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",