-
Notifications
You must be signed in to change notification settings - Fork 9
chore: housekeeping updates #5
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
akelani-circle
merged 1 commit into
circlefin:master
from
hjchen-circle:housekeeping-updates
Feb 4, 2026
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,85 +1,119 @@ | ||
| # Arc Commerce | ||
|
|
||
| This project demonstrates how to integrate USDC as a payment method for purchasing credits on Arc. | ||
| Integrate USDC as a payment method for purchasing credits on Arc. This sample application uses Next.js, Supabase, and Circle Developer Controlled Wallets to demonstrate a credit purchase flow with USDC payments on Arc testnet. | ||
|
|
||
| ## Table of Contents | ||
| <img width="830" height="646" alt="User dashboard for credit purchase" src="public/screenshot.png" /> | ||
|
|
||
| - [Clone and Run Locally](#clone-and-run-locally) | ||
| - [Environment Variables](#environment-variables) | ||
| ## Prerequisites | ||
|
|
||
| ## Clone and Run Locally | ||
| - Node.js 20.x or newer | ||
| - npm (automatically installed when Node.js is installed) | ||
| - Docker (for running Supabase locally) | ||
| - [ngrok](https://ngrok.com/) (for local webhook testing) | ||
| - Circle Developer Controlled Wallets [API key](https://console.circle.com/signin) and [Entity Secret](https://developers.circle.com/wallets/dev-controlled/register-entity-secret) | ||
|
|
||
| 1. **Clone and install dependencies:** | ||
| ## Getting Started | ||
|
|
||
| 1. Clone the repository and install dependencies: | ||
|
|
||
| ```bash | ||
| git clone git@github.com:circlefin/arc-commerce.git | ||
| cd top-up | ||
| cd arc-commerce | ||
| npm install | ||
| ``` | ||
|
|
||
| 2. **Set up environment variables:** | ||
| 2. Create a `.env.local` file in the project root: | ||
|
|
||
| ```bash | ||
| cp .env.example .env.local | ||
| ``` | ||
|
|
||
| Then edit `.env.local` and fill in all required values (see [Environment Variables](#environment-variables) section below). | ||
| Required variables: | ||
|
|
||
| ```bash | ||
| # Supabase | ||
| NEXT_PUBLIC_SUPABASE_URL=your_supabase_url | ||
| NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY=your_anon_key | ||
| SUPABASE_SERVICE_ROLE_KEY=your_service_role_key | ||
|
|
||
| # Circle | ||
| CIRCLE_API_KEY=your_circle_api_key | ||
| CIRCLE_ENTITY_SECRET=your_entity_secret | ||
| CIRCLE_BLOCKCHAIN=ARC-TESTNET | ||
| CIRCLE_USDC_TOKEN_ID=15dc2b5d-0994-58b0-bf8c-3a0501148ee8 | ||
|
|
||
| # Misc | ||
| ADMIN_EMAIL=admin@admin.com | ||
| ``` | ||
|
|
||
| 3. **Start Supabase locally** (requires Docker): | ||
| 3. Start Supabase locally: | ||
|
|
||
| ```bash | ||
| npx supabase start | ||
| npx supabase migration up | ||
| ``` | ||
|
|
||
| 4. **Start the development server:** | ||
| 4. Start the development server: | ||
|
|
||
| ```bash | ||
| npm run dev | ||
| ``` | ||
|
|
||
| The app will be available at [http://localhost:3000](http://localhost:3000/). The admin wallet will be automatically created on first startup. | ||
| The app will be available at `http://localhost:3000`. The admin wallet is automatically created on first startup. | ||
|
|
||
| 5. **Set up Circle Webhooks:** | ||
| 5. Set up Circle Webhooks (for local development): | ||
|
|
||
| In a separate terminal, start ngrok to expose your local server: | ||
| In a separate terminal, expose your local server: | ||
|
|
||
| ```bash | ||
| ngrok http 3000 | ||
| ``` | ||
|
|
||
| Copy the HTTPS URL from ngrok (e.g., `https://your-ngrok-url.ngrok.io`) and add it to your Circle Console webhooks section: | ||
| Add the webhook endpoint in Circle Console: | ||
| - Navigate to Circle Console → Webhooks | ||
| - Add a new webhook endpoint: `https://your-ngrok-url.ngrok.io/api/circle/webhook` | ||
| - Keep ngrok running while developing to receive webhook events | ||
| - Add endpoint: `https://your-ngrok-url.ngrok.io/api/circle/webhook` | ||
| - Keep ngrok running to receive webhook events | ||
|
|
||
| ## How It Works | ||
|
|
||
| - Built with [Next.js](https://nextjs.org/) and [Supabase](https://supabase.com/) | ||
| - Uses [Circle Developer Controlled Wallets](https://developers.circle.com/wallets/dev-controlled) for USDC transactions | ||
| - Wallet operations handled server-side with `@circle-fin/developer-controlled-wallets` | ||
| - Webhook signature verification ensures secure transaction notifications | ||
| - Admin wallet automatically initialized on first run | ||
|
|
||
| ## Environment Variables | ||
|
|
||
| Copy `.env.example` to `.env.local` and fill in the required values: | ||
| | Variable | Scope | Purpose | | ||
| | ------------------------------------- | ----------- | ------------------------------------------------------------------------ | | ||
| | `NEXT_PUBLIC_SUPABASE_URL` | Public | Supabase project URL | | ||
| | `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY` | Public | Supabase anonymous/public key | | ||
| | `SUPABASE_SERVICE_ROLE_KEY` | Server-side | Service role for privileged database operations | | ||
| | `CIRCLE_API_KEY` | Server-side | Circle API key for webhook signature verification | | ||
| | `CIRCLE_ENTITY_SECRET` | Server-side | Circle entity secret for wallet operations | | ||
| | `CIRCLE_BLOCKCHAIN` | Server-side | Blockchain network identifier (e.g., "ARC-TESTNET") | | ||
| | `CIRCLE_USDC_TOKEN_ID` | Server-side | USDC token ID for the specified blockchain | | ||
| | `ADMIN_EMAIL` | Server-side | Email address that determines which user gets admin dashboard access | | ||
|
|
||
| ```bash | ||
| # Supabase | ||
| NEXT_PUBLIC_SUPABASE_URL= | ||
| NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY= | ||
| SUPABASE_SERVICE_ROLE_KEY= | ||
| ## Usage Notes | ||
|
|
||
| # Circle | ||
| CIRCLE_API_KEY= | ||
| CIRCLE_ENTITY_SECRET= | ||
| CIRCLE_BLOCKCHAIN=ARC-TESTNET | ||
| CIRCLE_USDC_TOKEN_ID= | ||
| - Designed for Arc testnet only | ||
| - Requires valid Circle API credentials and Supabase configuration | ||
| - Admin wallet must have sufficient USDC and gas fees | ||
| - ngrok (or similar) required for local webhook testing | ||
|
|
||
| # Misc | ||
| ADMIN_EMAIL=admin@admin.com | ||
| ``` | ||
| ## Scripts | ||
|
|
||
| | Variable | Scope | Purpose | | ||
| | ------------------------------------- | ----------- | ------------------------------------------------------------------------ | | ||
| | `NEXT_PUBLIC_SUPABASE_URL` | Public | Supabase project URL. | | ||
| | `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY` | Public | Supabase anonymous/public key. | | ||
| | `SUPABASE_SERVICE_ROLE_KEY` | Server-side | Service role for privileged writes (e.g., transaction inserts). | | ||
| | `CIRCLE_API_KEY` | Server-side | Used to fetch Circle webhook public keys for signature verification. | | ||
| | `CIRCLE_ENTITY_SECRET` | Server-side | Circle entity secret for wallet operations. | | ||
| | `CIRCLE_BLOCKCHAIN` | Server-side | Blockchain network identifier (e.g., "ARC-TESTNET"). | | ||
| | `CIRCLE_USDC_TOKEN_ID` | Server-side | USDC token ID for the specified blockchain. | | ||
| | `ADMIN_EMAIL` | Server-side | Admin user email address. | | ||
| - `npm run dev`: Start Next.js development server with auto-reload | ||
| - `npx supabase start`: Start local Supabase instance | ||
| - `npx supabase migration up`: Apply database migrations | ||
|
|
||
| ## Security & Usage Model | ||
|
|
||
| This sample application: | ||
| - Assumes testnet usage only | ||
| - Handles secrets via environment variables | ||
| - Verifies webhook signatures for security | ||
| - 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since we are prefilling the blockchain, then we should prefill the token ID as well. It's not that easy to find the token ID at the moment.