fix(contributions): keep gift and tip confirmation pending until finality

[knzeng-e]

Outcome

Gifts and tips now show a calm pending state while Dotify checks finality. Recovery resumes from the saved intent after reload, never submits a second payment, and no longer polls the shared RPC indefinitely.

Issue and context

Refs #229; scope: native gifts and tips. A short confirmation timeout previously replaced progress with an ambiguous manual-check screen. The first fix kept checking forever; review correctly identified that Product finalized-event reads could then scan full history repeatedly.

Architecture and key concepts

The local journal is a reservation, not proof of payment. The connected payer, network, runtime and work identify it. A first attempt may submit once; later checks use its hash or intent ID only. A matching finalized contribution event produces success. A finalized reverted EVM receipt proves failure. Missing events and read-network errors remain pending because absence of evidence is not proof of failure.

How it works

1. Reserve the intent before wallet submission.
2. Product performs one finalized-event read per reconciliation cycle, followed by six bounded delays: 5s, 15s, 30s, 60s, 120s and 300s.
3. Checks pause while the document is hidden. Closing the sheet may leave the current bounded window active.
4. After the window, automatic checks pause and the saved contribution exposes only Check status again, never a new payment action.
5. Reloading and reopening the contribution resumes the saved intent for the connected payer.

Design decisions and tradeoffs

The bounded backoff reduces shared-RPC pressure while still observing finality for almost nine minutes. Explicit rechecks start another bounded read-only window. Product may expose no usable receipt for a failed native extrinsic; in that case Dotify cannot truthfully promise a terminal result, and the journal stays pending until independently reconcilable.

Security, failure, and operations

No signing key or secret is persisted. Storage reservation failure blocks submission; ambiguous host/network failures preserve the journal. An uncertain state cannot offer Send another. Do not clear Product cache or manually repeat an unresolved contribution. No contract, payment policy, deployed CID or production environment changed.

Review guide

Suggested order

1. web/src/features/donations/contributionFlow.ts: journal, read-only recovery and proof-bound terminal states.
2. web/src/features/donations/contributionReconciliation.ts: bounded schedule, visibility pause and cancellation.
3. web/src/components/ArtistDonationButton.tsx: one Product read per cycle and safe paused-state actions.
4. Tests and web/README.md: no-resend, scan-count and operational boundaries.

Verify carefully

• Can timeout, reload, dialog close, hidden-page state or RPC failure trigger a second submission?
• Can unresolved monitoring continue forever or scan while the page is hidden?
• Can a nonfinal, reorged or mismatched receipt produce success or failure?

Validation

Evidence	What it proves
16 focused unit tests	Journal recovery, final revert classification, bounded schedule, visibility pause and cancellation
3 targeted Playwright scenarios	Close/reopen, interrupted recovery and timeout all avoid a second payment; first timeout performs one finalized read before backoff
Web production build	The frontend and new scheduler compile
Changed-file ESLint, Prettier and diff checks	Changed sources are clean
W01 CI at 463a3d8	All required jobs pass, including the complete Playwright suite and Product DevNet build

Raw npm run lint still traverses historical minified bundles in local .data/ and fails there; changed-file lint passes. No funded Product-host tip was attempted.

Known limitations and follow-ups

Product native failure without a receipt remains unprovable from the current read path. Live-host validation and reconciliation of earlier pending intents remain open under #229.

Metadata checklist

• Backlog issue referenced without closing it; local scope linked
• Ready-for-review state intentional; live-host validation remains a release gate
• Project 5 and mirrored issue fields
• Assignee, labels and applicable milestone checked
• No known independent reviewer to request

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-04T19:48:16.082044Z	b1120df	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b1120df82a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".