Skip to content

tricodex/starc

BranchesTags

Repository files navigation

Starc Protocol

Unified stablecoin payment settlement layer on the Arc Network.

Overview

Starc enables merchants to accept USDC payments through Circle Programmable Wallets, settling them into an ERC4626 vault on Arc Testnet. The system provides payment link generation, transaction tracking, and basic treasury automation.

Core Files:

Features

Merchant Dashboard

  • Payment link and QR code generation for customer payments
  • Transaction history with status tracking (PENDING/COMPLETED)
  • Merchant profile management with PostgreSQL persistence

Implementation:

Payment Processing

  • Circle Wallet Integration: PIN-secured smart contract wallets via W3S SDK
  • Transaction Polling: Automatic transaction hash retrieval after PIN confirmation (up to 40 seconds)
  • Database Tracking: Payment requests stored with status updates and blockchain transaction links
  • Multi-Token Support: Native USDC (18 decimals, gas token at 0x36...00) and ERC20 mock tokens

Implementation:

Treasury Management

  • Payroll System: Database-driven employee payments
    • Individual or batch payment execution via Circle Wallet
    • Transaction receipt tracking with status and blockchain links
    • Employee records with wallet addresses and payroll amounts
  • CCTP Bridge Widget: Cross-chain USDC transfers via Circle's burn-and-mint protocol (V2)
    • Modal-based UI with transaction status feedback
    • Transaction hash polling and ArcScan explorer links
    • Arc Testnet → Ethereum Mainnet bridging

Implementation:

Starc Vault V2

  • ERC4626-compliant single-asset vault (USDC only)
  • Fee mechanism mints shares to treasury and risk fund (not asset withdrawal)
  • Pausable by risk manager role for emergency stops
  • Reentrancy guards on all state-changing functions

Implementation:

Starc Router

  • Unification layer that accepts alternative stablecoin assets (mARS, nARS, wARS)
  • Simulated swap to vault's base asset (USDC) via mock token minting
  • Deposits unified USDC into vault on behalf of merchant
  • Ensures merchants receive vault shares regardless of input token

Implementation:

AI Payment Agent

  • Gemini 2.5 Flash integration for natural language payment execution
  • Executes pending payment requests via Circle Wallet when user asks to "pay" them
  • Displays open payment requests with merchant address context
  • Rate-limited API endpoint (10 requests per 60 seconds via Upstash Redis)
  • NOT a treasury advisor - purely a payment request executor

Implementation:

Streaming Payments

  • Continuous payment streams with per-second calculations
  • Milestone-based escrows for project-based payments
  • Subscription management with automatic renewal
  • USDC-based (ERC20) for Circle prize compliance

Implementation:

Tech Stack

  • Frontend: Next.js 16 (App Router), React 19, Tailwind CSS v4
  • Blockchain: Arc Testnet (Chain ID: 5042002)
  • Smart Contracts: Solidity 0.8.24, OpenZeppelin (ERC4626)
  • Database: PostgreSQL (Neon), Prisma ORM
  • Infrastructure: Circle Web3 Services (W3S), Gemini AI
  • Rate Limiting: Upstash Redis

Deployed Contracts (Arc Testnet)

Contract Address Source
Native USDC 0x3600000000000000000000000000000000000000 Arc Native Token (18 decimals)
StarcVaultV2 0x6b9214D97aebd45D308F3dBdf599042f51B3D846 contracts/src/StarcVaultV2.sol
StarcRouter 0x1eda051D6C1cbD07026B63E3E8DF6e154239bBC4 contracts/src/StarcRouter.sol
ARS Vault (uARS) 0x4Ec59D328fFBbbe05E93E0a7D140a28eE4254B88 contracts/src/StarcVaultV2.sol
StreamingPayments 0x8572a110f6a41116d0ace7f24d7f744893385673 contracts/src/StreamingPayments.sol
LiquidityManager 0xfc4b34e57f348e2cb7b1f7396881e183e7611825 Liquidity management contract
CCTP TokenMessengerV2 0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA Circle's CCTP V2 (Arc Testnet)
Mock Oracle 0xed2ecEc90a6ad378c819391D585bf5598c73e896 Price oracle for testing
mUSDC 0x7504C2C43D0782Ba2CbbF741e845584168A1EF90 Mock USDC (6 decimals)
mARS 0xc9e86CdB5ACaFAD519A7c9018C45af5E93C258ee Mock ARS (18 decimals)
nARS 0x8b99629a10DbD2C4503A45A882EAC03f60ae8F15 Native ARS (18 decimals)
wARS 0xbb9086400A5fce3A3a771C0C1F39d7A0bEF04523 Wrapped ARS (18 decimals)
dARS 0x5AC020fc454e62379E4Fd7d05B413DfA990F7c0c Digital ARS (18 decimals)
bARS 0xFc9d1ECC6AbE3e2fD0b571fB5119B4d08bc189c1 Bridged ARS (18 decimals)

Configuration: app/config/assets.ts

Getting Started

Prerequisites

  • Bun v1.2+ (Required)
  • Foundry (for contract interactions)
  • Circle Developer Account (App ID & API Key)
  • Gemini API Key (for AI agent functionality)

Installation

  1. Clone the repository
  2. Install dependencies: 
    bun install
  3. Set up .env with required credentials:
    • Database URLs (Postgres)
    • Circle API credentials
    • Gemini API key
    • Optional: Upstash Redis for rate limiting
  4. Run database migrations: 
    bun run db:migrate
bun run db:seed
  5. Start development server: 
    bun run dev

Architecture

System Components

Frontend (Next.js 16): Server-rendered application managing Circle W3S SDK interactions and user sessions.

Backend API: Handles User Token generation, Challenge ID creation, merchant data persistence, and AI agent requests.

Blockchain (Arc Testnet): Settlement layer where all value transfers occur.

Database (PostgreSQL): Stores merchants, payment requests, employees, and payroll receipts.

StarcVault V2 (Smart Contract)

ERC4626-compliant vault designed for single-asset stability:

  • Single-Asset Design: Accepts only USDC to eliminate multi-asset risks
  • Fee Mechanism: Fees taken in shares (not assets) to preserve capital
    • Mints additional shares to treasury and risk fund on deposit/withdraw
    • Dilutes share price slightly but keeps 100% of assets deployed
  • Risk Controls:
    • Pausable by RISK_MANAGER_ROLE for emergency stops
    • ReentrancyGuard on all state-changing functions
    • 5% maximum fee cap enforced in contract

Files:

Starc Router (Unification)

Entry point for multi-token payments:

Flow: User Payment (Any Asset) → Router → Swap to USDC → Deposit to Vault → Merchant (Shares)

Purpose: Ensures merchants always settle in vault's base asset regardless of payment token.

Files:

Circle Programmable Wallets

Web3 Services (W3S) integration provides:

  • Smart Contract Accounts: Each user gets a smart contract wallet on Arc Testnet
  • PIN Authentication: Non-custodial control via sharded private keys
  • Challenge-Based Execution: All write operations (transfers, contract calls) require PIN confirmation
  • Session Management: User tokens and encryption keys rotate after each transaction
  • Transaction Polling: Frontend polls for transaction hash after PIN completion

Implementation:

Payment Flow Implementation

  1. Initiation: Frontend calls backend API with wallet ID and user ID
  2. Challenge Creation: Backend generates Circle API challenge and returns challenge ID + fresh credentials
  3. Authentication Update: Frontend persists new user token/encryption key to localStorage
  4. PIN Confirmation: W3S SDK prompts user for PIN to complete challenge
  5. Transaction Polling: Frontend polls /api/circle/wallet/transactions for transaction hash
  6. Database Update: Once hash received, payment request marked as COMPLETED with blockchain link

Key Files:

Payroll System

Database-driven employee payment system:

AI Payment Agent

Gemini 2.5 Flash model integration:

  • Fetches pending payment requests from database via /api/demo/requests
  • Parses natural language commands like "pay request [ID]" or "pay all requests"
  • Executes Circle Wallet transfers to merchant address for the requested amount
  • Returns JSON action format: {"action": "TRANSFER", "params": {"amount": "0.50", "token": "USDC", "recipient": "0x..."}}
  • Rate limiting at 10 requests per 60 seconds via Upstash Redis (configured in app/lib/ratelimit.ts)
  • Scope: Payment request executor only (not a treasury advisor or general assistant)

Implementation:

Asset Configuration

Arc Testnet has native USDC at 0x3600000000000000000000000000000000000000 with 18 decimals (non-standard). The system:

CCTP Configuration:

Known Limitations

  • Circle wallet session tokens expire; must use fresh userToken and encryptionKey after each API call
  • Transaction hash retrieval is asynchronous; polling required (up to 40 seconds, 20 attempts)
  • Native USDC decimals (18) differ from standard USDC (6)
  • Mock tokens (mARS, nARS) use public mint() for router swap simulation (not production-ready)
  • Contracts not audited; testnet use only

Development Notes

  • Use bun for all package management (not npm/yarn)
  • Circle transactions require both userToken (authentication) and encryptionKey (SDK initialization)
  • Backend API returns fresh credentials after each transaction; frontend must persist to localStorage
  • Decimal types from Prisma must be converted to strings before passing to client components
  • Payment polling uses fresh userToken from localStorage in X-User-Token header
  • All amounts must be parsed with correct decimals: parseUnits(amount, asset.decimals)
  • Native tokens (gas tokens) skip approval step; ERC20 tokens require approve before deposit/pay

Project Structure

app/
├── [merchant_id]/           # Merchant dashboard routes
│   ├── [payment_id]/        # Payment request pages
│   └── DashboardClient.tsx  # Main dashboard UI
├── api/                     # Backend API routes
│   ├── circle/wallet/       # Circle W3S integration
│   ├── chat/                # Gemini AI endpoint
│   ├── demo/                # Demo data seeding
│   ├── payroll/             # Employee payment APIs
│   ├── rpc/                 # RPC helper for contract reads
│   └── treasury/            # Treasury automation
├── components/              # React components
│   ├── AiAgent.tsx          # Gemini chat UI
│   ├── BridgeWidget.tsx     # CCTP bridge
│   ├── CircleWallet.tsx     # W3S SDK wrapper
│   ├── PayrollComponent.tsx # Employee payments
│   ├── StreamingWidget.tsx  # Streaming payments
│   └── UnifiedVaultWidget.tsx # Vault deposits
├── config/                  # Configuration
│   ├── abis.ts              # Contract ABIs
│   └── assets.ts            # Token addresses
├── context/                 # React context
│   └── CircleWalletContext.tsx
└── lib/                     # Utilities
    ├── circle.ts            # Circle SDK helpers
    ├── db.ts                # Prisma client
    └── ratelimit.ts         # Upstash Redis

contracts/
├── src/                     # Solidity contracts
│   ├── StarcVaultV2.sol     # ERC4626 vault
│   ├── StarcRouter.sol      # Multi-token router
│   └── StreamingPayments.sol # Payment streams
├── script/                  # Foundry deployment scripts
└── test/                    # Foundry tests

prisma/
└── schema.prisma            # Database schema

About

Unified Layer for Stablecoins

Resources

Readme
Activity

Stars

3 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages