Enhance README with detailed setup instructions and project layout fo… (#2)

…r stablecoin FX swaps using Circle Developer Controlled Wallets.

Author: akelani-circle

.env.example

@@ -0,0 +1,23 @@
+# Defaults for `supabase start` (local Supabase stack)
+# Run `npx supabase start` to boot the local instance, then copy the printed
+# values here as `.env.local` (the publishable key is deterministic across machines)
+NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
+SUPABASE_SECRET_KEY=
+
+# Circle dev-controlled wallets (https://console.circle.com)
+CIRCLE_API_KEY=
+# 32-byte hex (64 chars). Register once with Circle before use
+CIRCLE_ENTITY_SECRET=
+# Circle blockchain identifier for Arc Testnet
+CIRCLE_BLOCKCHAIN=ARC-TESTNET
+
+# Circle App Kit.
+KIT_KEY=
+NEXT_PUBLIC_ARC_CHAIN=Arc_Testnet
+
+# Application-level percentage fee applied to every swap
+APP_FEE_BPS=25
+# Address that receives swap fees. Run `npm run wallet:generate` to provision a
+# Circle wallet for the platform operator and auto-fill this value
+APP_FEE_RECIPIENT=

.gitignore

@@ -0,0 +1,44 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env.local
+
+# Circle entity secret recovery file (generated by `npm run wallet:generate`)
+circle-recovery.dat
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

README.md

@@ -1,2 +1,78 @@
 # arc-stablecoin-fx
-This sample app demonstrates stablecoin FX swaps between USDC and EURC using the App Kit Swap SDK on Arc.
+
+This sample app demonstrates stablecoin FX swaps between USDC and EURC using the App Kits Swap SDK and Circle Developer Controlled Wallets on Arc.
+
+<img alt="Arc Stablecoin Fx" src="public/screenshot.png" />
+
+## Getting started
+
+### Prerequisites
+
+- Node.js 20+ and npm
+- Docker (for local Supabase)
+- A [Circle](https://console.circle.com) account with API key + entity secret
+- A Circle App Kit `KIT_KEY`
+
+### 1. Install dependencies
+
+```sh
+npm install
+```
+
+### 2. Start the local Supabase stack
+
+```sh
+npm run db:start
+```
+
+This boots Postgres, Auth, etc. via the Supabase CLI and runs the migrations in
+`supabase/migrations/`. Use `npm run db:status` to print the local URLs and keys,
+`npm run db:reset` to wipe + re-migrate, and `npm run db:stop` to shut it down.
+
+### 3. Configure environment
+
+Copy the example file and fill in the blanks:
+
+```sh
+cp .env.example .env.local
+```
+
+- `NEXT_PUBLIC_SUPABASE_URL` / `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` /
+  `SUPABASE_SECRET_KEY` - from `npm run db:status`.
+- `CIRCLE_API_KEY` - from the Circle console.
+- `CIRCLE_ENTITY_SECRET` - your 32-byte hex entity secret. Must be registered
+  with Circle once before use.
+- `CIRCLE_BLOCKCHAIN` - Circle blockchain identifier (default `ARC-TESTNET`).
+- `KIT_KEY` - Circle App Kit key.
+- `NEXT_PUBLIC_ARC_CHAIN` - App Kit chain identifier (default `Arc_Testnet`).
+- `APP_FEE_BPS` - platform fee in basis points (default `25` = 0.25%).
+- `APP_FEE_RECIPIENT` - leave blank, then run the script below.
+
+### 4. Provision the platform fee wallet
+
+Creates a Circle wallet to receive swap fees and writes its address back to
+`.env.local` as `APP_FEE_RECIPIENT`:
+
+```sh
+npm run wallet:generate
+```
+
+### 5. Run the dev server
+
+```sh
+npm run dev
+```
+
+App is at http://localhost:3000.
+
+## Project layout
+
+- `src/app/(auth)/` - register / login flows
+- `src/app/(app)/dashboard/` - authenticated swap panel
+- `src/app/(app)/dashboard/history/` - trades history
+- `src/app/api/webhooks/circle/` - Circle webhook receiver
+- `src/components/swap/`, `src/components/trades/`, `src/components/wallet/` - feature UI
+- `src/lib/circle/`, `src/lib/appkit/` - Circle wallets + App Kit integration
+- `src/lib/supabase/` - Supabase client/server/admin helpers
+- `supabase/migrations/` - database schema
+- `scripts/` - one-off operator scripts

components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-nova",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;