Add payment ledger view aliases

[punk6529]

Summary

• add ADR-style local payment-ledger view aliases across current value-holding contracts
• expose StreamDrops fixed-price poster/protocol/curator-reserve category aliases plus totalReserved() and surplus()
• assert the new aliases in the bounded payment invariant and update roadmap/status docs for P0-PAY-002 traceability

This PR is intentionally additive: it does not change payment behavior, storage layout, authorization, custody, or withdrawal semantics. It closes the remaining local-ledger view-surface gap for #26; a protocol-wide shared ledger or aggregation layer remains future work only if the project chooses that architecture.

Closes #26

Validation

• forge test --match-path test\StreamPaymentsInvariant.t.sol -vvv
• make check (188 tests)
• powershell -ExecutionPolicy Bypass -File scripts\check.ps1 (188 tests)
• forge fmt --check smart-contracts\StreamDrops.sol smart-contracts\AuctionContract.sol smart-contracts\StreamCuratorsPool.sol smart-contracts\StreamMinter.sol smart-contracts\RandomizerRNG.sol test\StreamPaymentsInvariant.t.sol
• git diff --check
• rg -n "totalReserved\(\)|surplus\(\)|P0-PAY-002|Add payment ledger view aliases" smart-contracts test docs ops
• Slither with accepted baseline unchanged: 693 total findings; High 4, Medium 19, Low 82, Informational 577, Optimization 11

Summary by CodeRabbit

• New Features

  • Payment contracts now expose standardized accounting views and category-specific owed/reserved breakdowns for clearer balance visibility.

• Refactor

  • Emergency withdrawal logic unified to consistently surface withdrawable surplus across contracts.

• Documentation

  • Clarified owed vs reserved semantics in architecture and updated the payment accounting roadmap and run-state notes.

• Tests

  • Invariant tests expanded to validate accounting aliases and reserve/withdrawal boundaries across payment surfaces.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[punk6529]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[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: efeda52a-aaf1-43fd-af0d-0d25bbfad760

📥 Commits

Reviewing files that changed from the base of the PR and between 7e39893 and dc8b206.

📒 Files selected for processing (1)

• ops/AUTONOMOUS_RUN.md

🚧 Files skipped from review as they are similar to previous changes (1)

• ops/AUTONOMOUS_RUN.md

---

📝 Walkthrough

Walkthrough

Adds ADR-styled read-only view aliases (totalReserved(), surplus()) across five payment contracts to expose local-ledger accounting boundaries. Refactors emergencyWithdrawable() to delegate to surplus(). StreamDrops adds category-specific owed/reserved breakdowns. Extends invariant test assertions to validate alias relationships and boundary coherence.

Changes

Payment Ledger View Aliases

Layer / File(s)	Summary
ADR specification and documentation clarification docs/adr/0003-payment-accounting.md, docs/known-blockers.md, docs/status.md, ops/ROADMAP.md	ADR 0003 clarifies local-ledger baseline: totalOwed covers every withdrawable or reserved amount, totalReserved covers non-withdrawable reserve subsets, category aliases report zero for unowned categories. Roadmap, blockers, and status pages document this scope and track remaining future work (shared-ledger abstraction, randomizer reserve lifecycle, production governance).
Smart contract view alias implementations smart-contracts/AuctionContract.sol, smart-contracts/RandomizerRNG.sol, smart-contracts/StreamCuratorsPool.sol, smart-contracts/StreamDrops.sol, smart-contracts/StreamMinter.sol	All payment contracts add totalReserved() view (pure stub or delegating to existing reserves). emergencyWithdrawable() refactored to return surplus() instead of inline balance-minus-owed logic. StreamDrops adds category-specific getters: totalPosterOwed(), totalProtocolOwed(), totalCuratorReserved().
Invariant test assertions for alias validation test/README.md, test/StreamPaymentsInvariant.t.sol	Test documentation clarified to include ADR-style local-ledger alias verification. Invariant tests expanded to assert surplus() equals emergencyWithdrawable(), minter/randomizer total-reserved assertions, drops category-total aliases, and auction/curator reserved-boundary relationships after each fuzz step.
PR tracking and autonomous decision log ops/AUTONOMOUS_RUN.md	Current state updated to PR #78 (codex/add-payment-ledger-view-aliases) with branch, timestamp, and queue position (Queue Item 36). Worklog records PR #77 merge and PR #78 implementation scope (added aliases and invariant assertions). Decision log records PR #77 completion, Queue Item 36 selection, and PR #78 CodeRabbit review request.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• [P0-PAY-001] Add pull-payment accounting #25: The changes add and wire ADR-0003 payment-accounting view functions (totalReserved/totalOwed/surplus/emergencyWithdrawable) across multiple contracts and tests, directly implementing the pull-payment accounting behavior requested in that issue.

Possibly related PRs

• 6529-Collections/6529Stream#58: Overlaps AuctionContract accounting refactor and surplus/totalReserved interface changes.
• 6529-Collections/6529Stream#77: Related payment invariant baseline changes extended by this PR.
• Convert fixed-price payouts to pull credits #60: Related StreamDrops fixed-price→pull-credit accounting work that serves as basis for category aliases.

Poem

🐰 With twitching nose and careful care,
I've added views both clear and fair—
surplus() hops where emergency sleeps,
totalReserved counts what each ledger keeps.
Contracts now hum in tidy rows, and balance shows.

🚥 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 'Add payment ledger view aliases' directly and accurately summarizes the main change: exposing ADR-style read API aliases (totalReserved, surplus, category-specific getters) across payment contracts.
Linked Issues check	✅ Passed	The PR fully addresses issue #26 coding requirements: exposes required views (totalOwed, totalReserved, surplus, emergencyWithdrawable, category-specific aliases), implements ADR 0003 semantics across all contracts, adds invariant assertions for view consistency, and maintains storage/behavior unchanged.
Out of Scope Changes check	✅ Passed	All changes are in-scope: smart contract view additions implement ADR 0003 local-ledger semantics, documentation updates reflect the payment-ledger view work, and test updates validate the new views—no unrelated changes detected.
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/add-payment-ledger-view-aliases

---

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

[coderabbitai]

🧹 Nitpick comments (1)

ops/AUTONOMOUS_RUN.md (1)

3057-3057: ⚡ Quick win

Update the section header to use the concrete PR number.

The section header says "PR TBD" but line 3061 shows the PR is #78, and the decision log at line 3371 confirms PR #78 was opened. For consistency with the established pattern (e.g., "PR #77" at line 2963), update the header to "PR #78: Add payment ledger view aliases (Queue Item 36)".

📝 Suggested header correction

-### PR TBD: Add payment ledger view aliases (Queue Item 36)
+### PR `#78`: Add payment ledger view aliases (Queue Item 36)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ops/AUTONOMOUS_RUN.md` at line 3057, Update the section header that currently
reads "PR TBD: Add payment ledger view aliases (Queue Item 36)" to use the
concrete PR number by replacing "PR TBD" with "PR `#78`" so the header becomes "PR
`#78`: Add payment ledger view aliases (Queue Item 36)"; locate the header string
in the AUTONOMOUS_RUN.md section around the existing "Add payment ledger view
aliases (Queue Item 36)" title and update it accordingly to match the pattern
used elsewhere (e.g., "PR `#77`").

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@ops/AUTONOMOUS_RUN.md`:
- Line 3057: Update the section header that currently reads "PR TBD: Add payment
ledger view aliases (Queue Item 36)" to use the concrete PR number by replacing
"PR TBD" with "PR `#78`" so the header becomes "PR `#78`: Add payment ledger view
aliases (Queue Item 36)"; locate the header string in the AUTONOMOUS_RUN.md
section around the existing "Add payment ledger view aliases (Queue Item 36)"
title and update it accordingly to match the pattern used elsewhere (e.g., "PR
`#77`").

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 65b33d13-0d4d-4e61-b9c3-5a2464b2015f

📥 Commits

Reviewing files that changed from the base of the PR and between 9f23370 and 7e39893.

📒 Files selected for processing (12)

• docs/adr/0003-payment-accounting.md
• docs/known-blockers.md
• docs/status.md
• ops/AUTONOMOUS_RUN.md
• ops/ROADMAP.md
• smart-contracts/AuctionContract.sol
• smart-contracts/RandomizerRNG.sol
• smart-contracts/StreamCuratorsPool.sol
• smart-contracts/StreamDrops.sol
• smart-contracts/StreamMinter.sol
• test/README.md
• test/StreamPaymentsInvariant.t.sol