Accept payment accounting ADR

[punk6529]

Summary

• Add docs/adr/0003-payment-accounting.md as the accepted payment accounting design for Gate B1.
• Define pull-payment credits, reserve categories, total owed/reserved/surplus views, failed-withdrawal behavior, forced/direct ETH handling, and surplus-only emergency withdrawal.
• Link the ADR index, roadmap, test matrix, autonomous run state, and payment implementation issues [P0-PAY-001] Add pull-payment accounting #25 through [P0-PAY-007] Bound emergency withdrawals by surplus #31.

Scope

Docs and roadmap/state only. This PR does not implement Solidity payment logic, tests, CI, or deployment scripts.

Issues

• Closes [P0-PAY-ADR] Accept payment accounting design #24
• Tracks implementation follow-up: [P0-PAY-001] Add pull-payment accounting #25, [P0-PAY-002] Add credit ledger storage and total-owed views #26, [P0-PAY-003] Convert fixed-price payouts to credits #27, [P0-PAY-004] Convert auction outbid refunds to credits #28, [P0-PAY-005] Convert curator reward claims to credits #29, [P0-PAY-006] Add withdrawal functions and failed-withdrawal behavior #30, [P0-PAY-007] Bound emergency withdrawals by surplus #31
• Related: [P0-PAY-008] Bound emergency withdrawals and prove owed-balance invariants #8, [P0-AUCT-002] Fix auction bidding reentrancy and convert outbid refunds to pull credits #12, [P0-AUCT-001] Formalize auction custody, settlement, and lifecycle state machine #22

Validation

• rg -n "^#|^##|^###" docs/adr/0003-payment-accounting.md docs/adr/README.md ops/ROADMAP.md ops/AUTONOMOUS_RUN.md
• rg -n "P0-PAY-ADR|issues/24|issues/25|issues/26|issues/27|issues/28|issues/29|issues/30|issues/31|totalAuctionBidEscrow|totalRandomnessReserved|emergencyWithdrawable|forced ETH|failed withdrawal" docs/adr/0003-payment-accounting.md ops/ROADMAP.md docs/adr/README.md ops/AUTONOMOUS_RUN.md
• git diff --cached --check
• make check passed with 17 tests and known compiler/NatSpec warnings
• powershell -ExecutionPolicy Bypass -File scripts\check.ps1 passed with 17 tests and known compiler/NatSpec warnings

Notes for Reviewers

• ADR 0003 deliberately treats active highest bids and randomness provider funds as reserved balances, not surplus.
• Withdrawal pause policy is limited here to payment-safety constraints; ADR 0004 will decide pause authority and governance actors.
• Gate A and Gate B1 are marked In Progress rather than complete because remaining exit criteria still need formal closure.

Summary by CodeRabbit

• Documentation
  • Added and marked ADR 0003 “Payment Accounting” as Accepted, defining the pull-payment credit ledger model, withdrawal and emergency rules, reserves, and required invariants.
  • Updated ADR index and README to reflect acceptance.
  • Updated roadmap with payment accounting gating, acceptance criteria, and test matrix additions.
  • Updated autonomous run/worklog and decision log entries to record ADR progression and related PR/work item states.

[claude]

⚠️ Code review skipped — your organization's overage spend limit has been reached.

Code review is billed via overage credits. To resume reviews, an organization admin can raise the monthly limit at claude.ai/admin-settings/claude-code.

Once credits are available, push a new commit or reopen this pull request to trigger a review.

[punk6529]

@claude please review this payment accounting ADR PR.

Focus areas:

• ADR 0003 consistency with ADR 0001 drop authorization and ADR 0002 auction custody.
• Whether active auction bid escrow, curator reserve, protocol credits, and randomness reserves are correctly separated from withdrawable credits and surplus.
• Whether withdrawal failure behavior and withdrawal pause policy are precise enough for implementation.
• Whether emergency withdrawal is sufficiently bounded by owed/reserved balances.
• Whether issue traceability ([P0-PAY-ADR] Accept payment accounting design #24 through [P0-PAY-007] Bound emergency withdrawals by surplus #31, plus [P0-PAY-008] Bound emergency withdrawals and prove owed-balance invariants #8/[P0-AUCT-002] Fix auction bidding reentrancy and convert outbid refunds to pull credits #12/[P0-AUCT-001] Formalize auction custody, settlement, and lifecycle state machine #22) is complete enough for the next implementation PRs.

This is intentionally docs/roadmap/state only; no Solidity implementation is in scope for this PR.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dc9f1467-42ad-4ca9-82d0-68d3870bf80e

📥 Commits

Reviewing files that changed from the base of the PR and between e160bda and 4ee5d8d.

📒 Files selected for processing (1)

• ops/AUTONOMOUS_RUN.md

✅ Files skipped from review due to trivial changes (1)

• ops/AUTONOMOUS_RUN.md

---

📝 Walkthrough

Walkthrough

This PR adds ADR 0003 "Payment Accounting" describing a pull-payment credit ledger and detailed accounting rules for minting, auctions, curator claims, withdrawals, emergency withdrawals, reserves, invariants, and events, and updates ADR index, roadmap, and autonomous run worklog to reflect ADR acceptance and implementation planning.

Changes

Payment Accounting ADR 0003 & Documentation

Layer / File(s)	Summary
Payment Accounting ADR Design docs/adr/0003-payment-accounting.md	ADR 0003 specifies a pull-payment ledger model with credit/reserve categories (Poster, Bidder, Curator, CuratorReserve, Protocol, AuctionBidEscrow, RandomnessReserve), accounting rules for fixed-price minting and auction bidding/settlement, curator reward claims, direct/forced ETH semantics, randomness reserve handling, withdrawal and emergency-withdrawal semantics, required ledger views and invariants, event schema, and test/rollout guidance.
ADR Index & Acceptance Status docs/adr/README.md	ADR 0003 "Payment accounting" marked as Accepted with corresponding issue reference in the ADR index.
Roadmap & Implementation Planning ops/ROADMAP.md	Gate B1 "P0 Protocol Decisions Accepted" advanced to "In Progress"; Payment accounting ADR added to "Protocol Decisions Required Before Implementation"; P0-PAY-ADR queue item added; P0-AUCT-002 and P0-PAY-001 dependency links updated; P0-PAY-001 expanded with accounting categories and acceptance criteria, and new test matrix rows for ledger totals, failed-withdrawal preservation, emergency surplus boundary, randomness reserve accounting, and forced/direct ETH.
Execution State & Worklog ops/AUTONOMOUS_RUN.md	Repository state updated with active branch and timestamp; PR #23 (Auction custody ADR) marked merged with validation details; PR #32 (Payment accounting ADR) worklog added/expanded with status "Merge-ready", created issues (#24–#31), validation checklist, and decision-log entries documenting the ADR lifecycle.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• [P0-PAY-001] Add pull-payment accounting #25: Main implementation issue (P0-PAY-001) to implement the pull-payment accounting model specified by ADR 0003.
• [P0-AUCT-ADR] Accept auction custody and settlement state-machine design #21: ADR 0003 supplies payment-accounting rules referenced by the auction custody ADR and its settlement semantics.
• [P0-PAY-006] Add withdrawal functions and failed-withdrawal behavior #30: Addresses withdrawal API and failed-withdrawal semantics defined by ADR 0003 (P0-PAY-006 implementation target).

Possibly related PRs

• 6529-Collections/6529Stream#3: Related autonomous planning/docs work updating ops/AUTONOMOUS_RUN.md and ops/ROADMAP.md.
• 6529-Collections/6529Stream#23: Prior auction-custody ADR work that was merged and whose worklog states are advanced by this PR.

Poem

🐰 I hopped through ledgers, gentle and spry,

Credits in burrows, coins stacked high,
No forced pushes, only withdrawals neat,
Escrows and reserves keep balances sweet,
A tidy ADR makes accounting spry.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: acceptance of the payment accounting ADR, which is the primary objective of this documentation PR.
Linked Issues check	✅ Passed	The PR successfully implements all primary coding-related requirements from issue #24: ADR 0003 defines payment accounting model, credit categories, views/invariants, withdrawal semantics, payment flow rules, and event schema.
Out of Scope Changes check	✅ Passed	All changes are scoped to documentation and state tracking: ADR 0003 acceptance, roadmap/index updates, and autonomous run worklog entries directly supporting the linked issue objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/payment-accounting-adr

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}