> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cryptocheckout.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Known issues

> Everything currently broken, wrong, or unverified, with the consequence of each.

Consolidated from the 2026-07-28 production-readiness audit and subsequent work. Fixed items are in [Status](/overview/status).

## Blocking

<AccordionGroup>
  <Accordion title="Migration tooling is broken; the repo is not the source of truth for the prod schema">
    `supabase db reset` and `npx supabase test db` fail: migration `20260529090000` references `public.rate_limits` before any migration creates it. Two duplicate version timestamps were fixed, but that was only the first blocker.

    Production tracks 86 migrations and does not record the local colliding versions. The pgTAP test `supabase/tests/quotes_anon_write_lockout.sql` cannot run until this is repaired.

    **Consequence:** no local reproduction of the production schema, and no database tests.
  </Accordion>

  <Accordion title="Mainnet keeper wallet is unfunded on every chain">
    A launch blocker independent of the audit and legal gates. Needs funding plus low-balance alerting, and — once merchants bear sweep gas — a native-gas inventory buffer sized to expected monthly spend.
  </Accordion>

  <Accordion title="Three inconsistent forwarder gas measurements">
    423,918 / 451,643 / 495,529 across three different issues, and one reports a **cloned** sweep at 24,988 against the original's 54,383. A proxy cannot make an identical sweep cheaper — the hop only adds. Either the sweep logic changed between measurements or they were taken on different harnesses.

    **Consequence:** the break-even floor, the reimbursement ledger, and the per-customer crossover all rest on a number nobody has pinned. Re-measure the same logic both ways on one harness.
  </Accordion>

  <Accordion title="DEM attribution is unknown">
    Does TRON's Dynamic Energy Model attribute delegatecall energy to the implementation or the proxy? TIP-491's worked example uses `CALL`, and neither the TIP nor the docs resolve it.

    **Consequence:** blocks the per-customer forwarder design. The decision is irreversible once proxies are deployed.
  </Accordion>
</AccordionGroup>

## Correctness

<AccordionGroup>
  <Accordion title="railEconomics floor values are 62–127x wrong">
    Two compounding errors: the cost basis assumes 230,000 gas against a measured 495,529, and the floor is set equal to the gas cost rather than divided by the take rate. A $0.30 Ethereum order earns $0.00225 against \$0.139 of gas.

    Also fails **open** to 0 for an unknown chain, which for an economics gate means quoting a guaranteed loss.
  </Accordion>

  <Accordion title="Late payments to settled forwarders are invisible">
    `WATCH_STATUSES` in `pool-indexer-poll` omits `swept` and `settled`. Once an intent terminalises, its forwarder stops being watched forever — no event, no status change, no webhook, nothing on any dashboard. Funds are recoverable because the forwarder is re-callable, but nothing surfaces them.
  </Accordion>

  <Accordion title="Connect rail waits for the sweep before confirming">
    Capture on the connect rail is defined as the deposit confirmation, but the embed's `payment_confirmed` event and the done state gate on the subsequent keeper sweep. The UX is stricter than the policy, delaying the merchant's completion signal.
  </Accordion>

  <Accordion title="Underpaid invoices have no exit path">
    With `refund()` removed, a partial payment sits in a forwarder with no way to complete or return it without manual intervention. Needs a customer top-up prompt plus a merchant sweep-and-refund action.
  </Accordion>

  <Accordion title="Late payments honour the expired quote's amount">
    A post-expiry arrival is settled at the original quoted amount with no time limit, however stale. The locked decision is to re-quote at the current rate and re-check the tolerance band.
  </Accordion>

  <Accordion title="Payment links: single-use not enforced, amount overridable">
    `payment_links.status` is never flipped to `paid` server-side, so a settled link keeps opening a working checkout. The checkout page feeds the wizard from editable URL parameters rather than the resolved link row, so a fixed amount is not authoritative. Comma-locale amounts parse as `NaN`.
  </Accordion>

  <Accordion title="RouterFee V3_SWAP_EXACT_OUT mis-encoding">
    Encoded as `0x09`, which is V2's opcode. Requires a redeploy. Phase 2 only, so not currently on the default path — but do not build on `payWithSwap`.
  </Accordion>
</AccordionGroup>

## Visibility and trust surfaces

<AccordionGroup>
  <Accordion title="Partner earnings always display $0.00">
    Plus incomplete partner-visible merchants RLS. Beyond the dashboard bug, this means a regression in the partner's 0.25% share would be **invisible** — which is why fee changes need an explicit regression test.
  </Accordion>

  <Accordion title="Webhook 'none' secret and signature mismatch">
    A `'none'` secret option exists, and test and live signatures do not match.
  </Accordion>

  <Accordion title="TRON has no on-chain recipient anchor">
    The client-side trust guarantee does not extend to TRON. Any statement about routing non-custody must be scoped to EVM.
  </Accordion>

  <Accordion title="Legacy atomic rail is outside the trust anchor">
    Default-recipient merchants and the atomic rail are a separately tracked gap. The go-live attestation gate for that rail is open.
  </Accordion>

  <Accordion title="Contract source links disabled">
    `VITE_CONTRACTS_REPO_URL` is unset because the marketed repository URL 404s. The audit PDF was also being served as SPA fallback HTML. Both dead trust links were removed rather than left broken.
  </Accordion>
</AccordionGroup>

## Documented and accepted

* **`paymentId` replay keyed on `paymentId` alone**, not `(merchant, paymentId)`. Infeasible to exploit at 128 bits of randomness (\~2⁻⁶⁴). Deferred to a future redeploy.
* **TRON keeper drops expired intents.**
* **Two flaky tests** — `App.test.tsx`, `LandingFooter` — pass in isolation.
* **Chunk-size build warnings** are pre-existing.

## Landmines

Things that are not bugs but will bite.

| Landmine                                               | Consequence                                                 |
| ------------------------------------------------------ | ----------------------------------------------------------- |
| `forge test` rewrites `contracts/deployments.json`     | Breaks the shared contracts module and `/verify` at runtime |
| Editing `public/sdk.js` without regenerating `SDK_SRI` | Browsers refuse to execute the SDK on every merchant site   |
| Patching CSP in only one of two places                 | Silent breakage; the more restrictive wins                  |
| Re-adding a static import of `@/config/appkit`         | 5.0 MB entry chunk, 4,908 ms first paint                    |
| SPA rewrite without the `/api/` exclusion              | API routes rewritten to `index.html`                        |
| Case-normalising a TRON `T…` address                   | Corrupts base58; addresses are case-sensitive               |
| Scaling a TRON burn price to a rent price              | Rental discounts energy only, never bandwidth               |
| Porting EVM cold/warm gas reasoning to TVM             | TRON has no EIP-2929; `DELEGATECALL` is 40 energy           |