Lona

Private cross-chain checkout. Customers pay from a shielded Zcash wallet; merchants receive USDC (or USDT) on Base, Arbitrum, Ethereum or Solana. Lona never holds funds: each payment is converted by NEAR Intents (1Click API) and sent straight to the merchant's wallet.

Read DESIGN.md before changing any UI.

What's in the MVP

• Merchant accounts with test and live modes
• Invoices priced in USD, with hosted checkout, QR code and live status
• Reusable payment links (each visit opens its own invoice)
• Settlement preferences: payout asset, payout wallet, fallback Zcash refund address
• Payment confirmation through the swap network's status API
• Signed webhooks (Lona-Signature, HMAC-SHA256) with retries for about a day
• REST API with secret keys (/api/v1/invoices, /api/v1/payment_links)
• Test mode simulator, since the swap network has no testnet
• Landing page, API docs, privacy policy and terms
• Accounts: email confirmation, password reset, password change; live mode needs a confirmed email and a payout wallet
• Settings: business profile, support email, default return page, customer receipt emails
• Webhook tooling: private-network guard on save and on every delivery, send test event, roll secret, retry now
• API safety: Idempotency-Key on every POST, per-key rate limits with headers, list filters and cursor paging
• Invoices: search, status filters and CSV export for accounting

Run locally

npm install
npm run dev        # http://localhost:3000
npm test           # payment lifecycle, webhooks, signatures, network guard, tokens, receipts, idempotency, rate limits,
                   # ZEC/USD conversion and rounding, quote guard, duplicate sign-ups
npm run test:e2e   # browser checks for signup, login, checkout amounts and the homepage demo
npm run test:full  # every merchant feature, the REST API and signed webhooks (start the server with
                   # ALLOW_PRIVATE_WEBHOOKS=1 CRON_SECRET=e2e-cron SANDBOX_ZEC_USD=1300; set SERVER_LOG to its log)
                   # (needs a running build at BASE_URL and Playwright with Chromium)

No database setup is needed locally: an embedded Postgres (PGlite) is created in .data/ and migrated on boot.

Try it: create an account, set a payout wallet under Settlement (any valid-looking address works in test mode), create an invoice, open checkout, click "Pay with Zcash", then "Pay in full".

Deploy (Vercel + Neon)

1. Create a Neon database and set DATABASE_URL.
2. Set the variables in .env.example, at minimum APP_URL, CRON_SECRET, ONECLICK_JWT, LONA_FEE_RECIPIENT, NEXT_PUBLIC_LEGAL_NAME, NEXT_PUBLIC_CONTACT_EMAIL.
3. Deploy. vercel.json runs migrations before each build and calls /api/cron/tick every minute (per-minute crons need a paid Vercel plan; on Hobby, run the tick from an external scheduler with the CRON_SECRET bearer header).

How a payment works

1. POST /api/v1/invoices creates an invoice in USD. No price yet.
2. The customer opens /pay/:id and clicks Pay. Lona asks 1Click for an EXACT_OUTPUT quote: the merchant receives exactly the invoice amount, and the customer's ZEC amount includes network costs and Lona's fee (appFees). The price is held for 20 minutes.
3. The customer sends ZEC to the quote's deposit address from their shielded balance.
4. Lona polls /v0/status (on page views and every minute from the scheduler) and moves the invoice through awaiting_payment, payment_received, converting and paid_out, emitting a webhook at each meaningful change. Status changes use compare-and-set, so each event fires once.

Code map: src/lib/invoices.ts (state machine), src/lib/providers/ (1Click adapter and sandbox, behind one interface so a second route such as Maya Protocol can be added), src/lib/webhooks.ts, src/app/api/.

Known limits, verify before going live

• Do one real swap first. There is no testnet. Send a small real payment through a live invoice and confirm the deposit, status flow and payout before onboarding merchants.
• Zcash deposit addresses are transparent. NEAR Intents documents Zcash support as transparent-only. A shielded wallet can pay it and the payer's wallet stays private, but the deposit amount is public. The landing page says so; keep it that way.
• Refunds go to transparent addresses. The merchant's fallback refund address, or one the customer enters at checkout.
• Asset IDs are resolved from 1Click's /v0/tokens at runtime, with known IDs as a fallback. Check the Solana USDC mapping against the live token list.
• Email needs RESEND_API_KEY and a verified sending domain in MAIL_FROM. Without it, confirmation, reset and receipt emails are only logged.
• Rate limits and idempotency are stored in Postgres, which is fine at launch volume; move them to Redis if traffic grows.
• One conversion route. Maya Protocol (which also supports shielded ZEC) can be added behind the same provider interface as a fallback.
• Legal pages are plain-language drafts. Have a lawyer review them, and get advice on whether your jurisdiction treats this as a regulated payment service.

Launch checklist

• Custom domain connected and APP_URL set to it
• Favicon (src/app/icon.svg)
• No "Made with" badges
• Privacy policy and terms pages (review with a lawyer)
• NEXT_PUBLIC_CONTACT_EMAIL set to a real inbox
• RESEND_API_KEY and MAIL_FROM set, sending domain verified
• One real end-to-end payment completed

Amounts and prices

• Live payments: the ZEC amount is NEAR Intents' quote for the exact invoice amount, made on the server. Lona rejects any quote that would pay out less than the invoice.
• Checkout shows the dollar value of the quoted ZEC, using the swap network's own figure when it gives one.
• Test mode prices ZEC at the live price plus a simulated 0.5% cost. Set SANDBOX_ZEC_USD only to pin a fixed test price.
• The homepage demo uses the same live price shown on the page. If the price cannot be fetched, the page says the amounts are examples.
• Lona's fee is LONA_FEE_BPS (default 50, so 0.5%). It is added to live quotes only when LONA_FEE_RECIPIENT is set.

Scheduled job

/api/cron/tick syncs payments in flight, expires old invoices, retries webhooks and prunes rate-limit state. It needs Authorization: Bearer $CRON_SECRET.

• Vercel Cron runs it once a day (the most the Hobby plan allows).
• .github/workflows/scheduled-tick.yml runs it every 30 minutes, which fits a private repo's free Actions minutes. Add CRON_SECRET as a repository secret.
• For webhooks within minutes, point a free external scheduler (cron-job.org) at the same URL every 5 minutes with the same header.
• The dashboard and invoice list also refresh the merchant's own payments in flight when opened.

Sign-in protection

Wrong passwords are counted per email and per IP in 15-minute windows (stored hashed). Defaults: 5 per email, 30 per IP for sign-in; 3 reset emails per address and 10 reset requests per IP; 10 new accounts per IP. A correct password clears the email's count. Override with AUTH_LOGIN_EMAIL_LIMIT, AUTH_LOGIN_IP_LIMIT, AUTH_FORGOT_EMAIL_LIMIT, AUTH_FORGOT_IP_LIMIT, AUTH_SIGNUP_IP_LIMIT.