Skip to main content

​
Branching

main is the single source of truth and the production line. Pushing to main auto-deploys production through the GitHub–Vercel integration.
Never push directly to main. Every change lands via a pull request. The PR is the deploy gate.
Short-lived branches: feat/<name>, fix/<name>, docs/<name>, one per unit of work, deleted on merge. Use git worktrees for isolation, branching from main. .worktrees/ is gitignored. There is no integration branch. The old integration-to-main promotion model was retired in the 2026-05-21 cleanup. Vercel preview deploys on each PR cover the staging need. Link the PR to its Linear issue with a magic word — Fixes CRY-7 — in the title or body. Linear auto-links and moves the issue to Done on merge.

​
Frontend

Normally nothing to do: merging to main triggers the deploy.
vercel --yes alone deploys to Preview. Production needs --prod.
Verify a deploy actually fired by checking that the main alias deployment’s githubCommitSha matches the merged HEAD. If the GitHub integration silently did not fire, fall back to a manual vercel --prod --yes --archive=tgz.

​
Edge functions

Prefer the Supabase CLI. A personal access token lives in .env as SUPABASE_ACCESS_TOKEN.
All functions are verify_jwt: false because they use custom cc_session or bearer authentication.
Use the MCP deploy_edge_function only for tiny single-file functions. It cannot follow out-of-tree imports such as ../../../contracts/deployments.json, and it truncates string literals over 8KB — which silently corrupts contract bytecode and produces wrong CREATE2 predictions.
The CLI bundles real on-disk source with eszip: byte-exact, follows JSON and ABI imports natively, no truncation. Proven deploying ~66KB bundles dominated by contract bytecode, where the MCP path could not ship reliably. The token can be re-minted at supabase.com/dashboard/account/tokens.

​
Contracts

Mainnet deploys require explicit human GO, per chain. Guardrail number one. No agent or automation may broadcast to a mainnet.
Before any broadcast:
1

Reset deployments.json

git checkout -- contracts/deployments.json. A forge test run pollutes it with fixtures.
2

Confirm the factory path

Deployment goes through the canonical CREATE2 factory, not the EOA. Predict with the factory address.
3

For TRON, re-prove 0x41

Any new init code needs its 0x41 CREATE2 derivation re-proven on Nile before an address is shown as a QR. A mismatch strands funds permanently.
4

Plan the drain window

Any init-code change moves every address. In-flight invoices quoted under the old scheme must drain, or use a versioned predictor.

​
CSP changes

CSP lives in two places — the vercel.json header and the <meta http-equiv> tag in index.html. The more restrictive wins. Patch both or it silently breaks.
Also confirm the SPA fallback rewrite still excludes /api/, or API routes get rewritten to index.html.

​
After changing the SDK

Regenerate the SRI pin. A stale pin makes browsers refuse to execute the SDK on every merchant site.
Then update SDK_SRI in src/lib/sdk/embedSnippet.ts.

​
Migrations

Local migration tooling is broken and production tracks 86 migrations that the repository cannot reproduce. Treat production schema changes as manual and verified, not as a db reset away. See Known issues.

​
Post-deploy checks

  • Live site console clean on /, /verify, and the demo widget panel.
  • /verify renders the chain list from deployments.json, not a hardcoded list.
  • An RLS-gated read with a freshly minted JWT returns rows.
  • Bundle budget still passes; the entry chunk has not regained wallet-vendor.