Co-Sign Checkout Demo

cosign-demo is a standalone Nitrolite example app for shared approvals. Two participants create a cart, co-sign checkout actions, move funds between their Shared Wallet and the checkout cart, and close the cart when they are done.

If you are building with this example, start with:

1. this README
2. docs/architecture/overview.md
3. docs/architecture/feature-map.md
4. AGENTS.md if you are using Claude Code or another coding agent

Product Overview

The app presents two related balance layers:

• Shared Wallet: each participant's Nitrolite balance for the room asset
• Checkout Cart: a shared Nitrolite app session for this cart only

Typical flow:

1. Create a shared cart with a friend.
2. Start Shared Checkout and have both participants approve it.
3. Add funds into Shared Wallet if needed.
4. Move funds from Shared Wallet into the checkout cart.
5. Propose a purchase and have both participants approve it.
6. Finish Checkout to close the cart and return the final split to Shared Wallet balances.
7. Withdraw from Shared Wallet back to the on-chain wallet if desired.

Important behavior:

• Shared Wallet actions work even when there is no active cart.
• Withdraw To Wallet moves funds from Shared Wallet back on-chain.
• Propose Purchase currently reallocates funds inside the checkout session. It does not pay an external merchant.
• Finish Checkout closes the checkout session and returns the final split to Shared Wallet balances.
• Smooth approvals via session keys are supported to reduce repeat approval friction.
• The demo currently uses YUSD and YELLOW on Ethereum Sepolia.

Architecture Snapshot

Current reality:

• src/components/CosignDemoApp.tsx still acts as the main application brain.
• API routes under src/app/api handle rooms, proposals, signatures, submission, health, and expiration.
• Integration helpers live under src/lib.
• The repo is standalone and vendors the SDK tarballs it was tested against under vendor/.

Read next:

• docs/architecture/overview.md
• docs/architecture/feature-map.md

Working With Claude Code

Repo-specific agent assets are checked in:

• AGENTS.md
• CLAUDE.md
• .claude/rules
• .claude/skills
• .claude/agents

These are part of the repo contract. If architecture, contributor workflow, or runtime expectations change, update them with the code.

.mcp.json preconfigures Next.js devtools MCP. The repo is currently on Next.js 15.5.9.

Starter Commands

If you use Claude Code in this repo, start with these skills:

Command	When to use
/trace-checkout-flow	Before editing a flow; traces the path from UI action through API, SDK, and state
/wallet-channel-debug	When deposits, withdrawals, channel actions, or checkout/session actions fail
/extract-feature-slice	When pulling a bounded concern out of src/components/CosignDemoApp.tsx
/proposal-contract-change	Before changing proposal payloads, signing paths, or app-session-related contracts

Run these inside a Claude Code session opened at the repo root.

Runtime

Implemented today:

• real Uses Supabase, the Yellow sandbox Clearnode, and Sepolia RPCs.

Local Development

Requirements

• Node.js 20+
• npm 10+
• A Supabase project with the schema from supabase/schema.sql
• A reachable Clearnode websocket endpoint
• Ethereum Sepolia RPC access

Setup

git clone <your-fork-or-org-repo-url>
cd cosign-demo
npm install
cp .env.example .env.local

Populate .env.local with:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• NEXT_PUBLIC_CLEARNODE_WS_URL
• NEXT_PUBLIC_BLOCKCHAIN_RPCS
• SUPABASE_SERVICE_ROLE_KEY
• CRON_SECRET

Then run:

npm run dev

Validation

npm run typecheck
npm run build

Run validation sequentially, not in parallel. npm run build assumes the required environment variables from .env.example are populated, and the build script clears .next first to avoid stale route-artifact failures while the repo still relies on generated .next/types.

Supabase

Apply supabase/schema.sql to your project before running the app. The demo expects:

• rooms
• proposals
• events

The API routes use the service role key for privileged server-side actions, including proposal state updates and expiration cleanup.

Data Reset Utility

This repository includes a safe row-clear utility that preserves the schema:

npm run supabase:clear
npm run supabase:clear -- --yes

Deployment

Vercel

1. Push this repository to the target GitHub org.
2. Import the repo into Vercel.
3. Set the required environment variables for Preview and Production.
4. Ensure the deployment can reach your Clearnode websocket and Sepolia RPC provider.
5. Keep vercel.json enabled so Vercel invokes /api/proposals/expire.
6. Set CRON_SECRET in Vercel and ensure the API route validates the same secret.

Required Environment Variables

Variable	Used by	Notes
NEXT_PUBLIC_SUPABASE_URL	Browser + server	Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	Browser + server	Public anon key
NEXT_PUBLIC_CLEARNODE_WS_URL	Browser	Clearnode websocket endpoint
NEXT_PUBLIC_BLOCKCHAIN_RPCS	Browser	chainId:https://rpc pairs
SUPABASE_SERVICE_ROLE_KEY	API routes	Required for server writes
CRON_SECRET	Vercel cron	Required by /api/proposals/expire

Vendored SDK Tarballs

This repository intentionally vendors the SDK tarballs instead of consuming npm releases directly. That is a temporary packaging strategy until the tested SDK state is published.

See vendor/README.md for package provenance.

Utility Scripts

The scripts/ directory contains helpers for local diagnosis and operator workflows:

• npm run node:check
• npm run node:diag:validators
• npm run channel:repair:void
• npm run vault:deposit
• npm run supabase:clear

These are optional for normal app usage, but useful when debugging node connectivity, validator support, or stuck channels.

Troubleshooting

Cart shows "session not visible on the current Clearnode"

Check that:

• the cart was created against the same Clearnode configured in NEXT_PUBLIC_CLEARNODE_WS_URL
• both participants are connected to the same room and asset
• the vendored SDK tarballs still match the tested Nitrolite state

Shared Wallet or checkout actions fail unexpectedly

Check:

• the selected asset and chain match the configured environment
• whether the failing path goes through compat or a direct inner SDK call
• whether live node state and local UI state are aligned

Use docs/architecture/feature-map.md and .claude/skills/wallet-channel-debug/SKILL.md as the first debugging entrypoints.