Payment rail
Arc Testnet + USDC
Durable media
Supabase Storage
Apps
Merchant Studio + Storefront
What this project does
Only what exists in this repo: generation jobs, Arc payment proof, storage persistence, and storefront publishing.
ARC ties together three moving parts into a single, demoable pipeline: (1) a merchant-facing studio, (2) an API, and (3) a consumer storefront. The critical constraint is that the payment proof (Arc tx hash) and the deliverables (images/video) stay linked and durable.
Core contract (product truth)
- A job represents one paid generation run.
- A job stores the Arc tx hash (payment proof), plus generation logs and outputs.
- A product stores the final media URLs and publish state.
- Storefront lists published products directly from the API.
View system map (apps + services)
apps/ merchant-studio/ → merchant UI (create jobs, track jobs/products, billing, testing) storefront/ → consumer UI (browse products, preview video, checkout UI) services/ api/ → Express API (jobs, products, orders, generation, web3 lab tools) Supabase (Postgres + Storage) tables: products, jobs, job_logs buckets: uploads (source files), generated (final durable assets) Arc testnet (USDC) tx hash is captured + verified and stored with the job/product
Architecture (repo truth)
Where each capability lives in this monorepo.
Merchant Studio
- Job creation UX: uploads + variants + payment step.
- Live job tracking: status, tx hash, logs, deliverables.
- Product management: publish/unpublish, preview media.
- Testing page: AI pipeline + Web3 lab in one place.
Location: `apps/merchant-studio/`
API (source of truth)
- Products: list/search, publish state, media URLs.
- Jobs: quote (402), create (requires payment), status + logs.
- Generation: prompts → images → video → persistence.
- Web3 lab: Arc RPC + Circle wallet tools + test payer.
Location: `services/api/`
Storefront
- Fetches published products from the API and renders a luxury/brutalist grid.
- Uses product `assets.video` for hover preview where available.
- Product detail page renders a video + image grid for the product.
Location: `apps/storefront/`
End-to-end flow
From merchant upload → on-chain payment proof → durable media → storefront listing.
Step 0 — Merchant inputs
- Upload reference images (front/back) used as the visual anchor.
- Choose category + variants (e.g. S/M/L).
- The UI prepares a job request but does not create a job until payment proof exists.
Step 1 — Quote (x402-style)
The API supports a paywall-like quote endpoint: it returns HTTP 402 with a `PAYMENT-REQUIRED` header describing recipient + amount + chain.
Pricing is deterministic: 0.05 USDC base + 0.01 USDC per extra variant.
Step 2 — Pay (Arc tx hash)
- A payment is executed on Arc testnet in USDC.
- The resulting Arc transaction hash becomes the “payment signature” carried to the API.
- The API only proceeds if it can verify the tx status and (best-effort) that the recipient received at least the required amount.
Step 3 — Create job + persist inputs
- The API uploads input files into Supabase Storage bucket `uploads`.
- A product record is created/updated in Supabase Postgres.
- A job record is inserted, including the tx hash and initial logs.
Step 4 — Generate deliverables + make them durable
- Prompts are built, then images and a looping video are generated.
- If outputs are transient URLs (e.g. Replicate delivery links), the API downloads and re-uploads them to Supabase Storage bucket `generated`.
- The job/product are updated with final public Supabase URLs.
Payments + verification (Arc + USDC)
What the backend actually checks before accepting a job.
The backend treats the incoming payment proof as an Arc transaction hash. Verification is RPC-based and uses receipt + logs so the demo can show a real explorer link.
Verification logic
- Fetch transaction receipt from Arc RPC.
- Require receipt status 0x1 (success).
- If a merchant recipient address is configured, accept either:
- Native transfer: tx.to matches the recipient.
- ERC-20 transfer: receipt logs contain an ERC-20 Transfer to the recipient with value \(\ge\) required USDC amount (6 decimals).
View how the API asks for payment (402 header)
If the client calls the quote endpoint (or tries to create a job without a payment signature), the API responds with HTTP 402 and a `PAYMENT-REQUIRED` header that includes:
- recipient (merchant pay-to address)
- amount (USDC)
- rpcUrl + explorerBase for Arc testnet
AI generation pipeline
Prompt planning → image generation → looping video generation.
Safety + cost mode
The API supports a dummy generation mode by default to avoid expensive model calls during demos. When enabled, it returns stable placeholder assets; when disabled, it runs the full pipeline.
Prompt builder
- Uses OpenAI to generate a structured prompt plan.
- Produces multiple image prompts + a video prompt that stay consistent with the product.
Image model
- Replicate model: google/nano-banana
- Generates multiple product visuals from the reference images.
Video model
- Replicate model: google/veo-3.1-fast
- Uses the same base image as first and last frame for a seamless loop.
- Defaults to vertical, fashion-friendly output (9:16, 1080p) with audio disabled.
Persistence (Supabase Postgres + Storage)
The part that makes this a real product pipeline rather than a one-off generation demo.
Tables
- `products`: name/category/price, images[], assets, published.
- `jobs`: tx hash, variants, status, files, assets, metadata, receipt.
- `job_logs`: structured log stream used by the UI to show progress.
Storage buckets
- uploads: raw merchant-provided inputs (front/back images).
- generated: durable public deliverables (final images + video).
Why we persist deliverables
Model providers often return time-bound URLs. ARC makes deliverables stable by re-hosting them in Supabase Storage and storing only the Supabase public URLs in `products` and `jobs`.
Storefront publishing
How a generated product becomes shoppable content.
Testing tools (Web Lab)
A combined testing surface for both the AI pipeline and the Arc/Circle flows.
What’s inside /web-lab
- Arc RPC health + tx verification (receipt + explorer link).
- Circle wallet utilities (user-controlled flows: initialize, create wallet, balances).
- Faucet drip helper for demos (cooldown-protected).
- Test payer endpoints for sponsored payments (developer-controlled wallet).
- x402-like paywall demo endpoints (quote + payment-required response).