Convert curator reward claims to pull credits

[punk6529]

Summary

Converts StreamCuratorsPool.claimRewards from a synchronous ETH push payout into ADR 0003-style curator pull credits.

The claim path now validates the Merkle proof, checks local curator-pool surplus before consuming the claim, records curatorCredits[rewardAddress], increments totalCuratorOwed, and emits a curator-credit event. Reward recipients are no longer called during claim consumption, so reverting reward addresses cannot block valid claims.

This PR also adds guarded curator-credit withdrawals, local owed/surplus views, surplus-bounded curator-pool emergency withdrawal, focused tests, and roadmap/status traceability.

Closes #29.

Roadmap

• Gate: Gate C / Gate D payment-accounting work
• Roadmap issue or ADR: [P0-PAY-005] Convert curator reward claims to credits #29, ADR 0003, partial [P0-PAY-008] Bound emergency withdrawals and prove owed-balance invariants #8 Slither emergency-withdraw progress
• Scope type: contracts / tests / docs
• Scope intentionally excluded: shared protocol-wide payment ledger, cross-contract reserve movement from StreamDrops fixed-price curator reserves or auction curator credits into StreamCuratorsPool, randomizer reserves, and the remaining [P0-PAY-001] Add pull-payment accounting #25/[P0-PAY-002] Add credit ledger storage and total-owed views #26/[P0-PAY-006] Add withdrawal functions and failed-withdrawal behavior #30/[P0-PAY-007] Bound emergency withdrawals by surplus #31/[P0-PAY-008] Bound emergency withdrawals and prove owed-balance invariants #8 work outside this local curator-pool boundary.

Security And Maturity

• This PR does not claim production readiness unless the relevant launch gate evidence is merged.
• Security-sensitive behavior is identified, or this PR is docs/tooling-only.
• New external behavior is documented.
• No private keys, signer material, RPC secrets, or production deployment secrets are included.

Review Routing

• Protocol review is required or not applicable.
• Security review is required or not applicable.
• Tooling/CI review is required or not applicable.
• Docs review is required or not applicable.

Validation

Local commands run:

forge test --match-contract "Stream(CuratorsPool|AuctionPayments|FixedPricePayments)Test" -vvv
# 38 passed, 0 failed

make check
# 109 passed, 0 failed; known compiler/NatSpec/lint warning baseline remains

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\check.ps1
# 109 passed, 0 failed; known compiler/NatSpec/lint warning baseline remains

forge fmt --check smart-contracts\StreamCuratorsPool.sol test\StreamCuratorsPool.t.sol
# passed

git diff --check
# passed

.venv-tools\Scripts\slither.exe . --config-file slither.config.json --foundry-compile-all --json <temp-file>
# exits -1 for existing baseline findings and intentional test helpers;
# arbitrary-send-eth now lists only RandomizerRNG and StreamMinter, not StreamCuratorsPool

• make check or platform equivalent passed.
• Tests were added/updated, or this PR explains why no tests are required.
• CI is green.
• Bot and human review comments are resolved or explicitly accepted with rationale.

Impact

• Test impact: adds StreamCuratorsPool.t.sol coverage for valid claims, duplicate/invalid/unfunded claims, delegation, rejecting reward addresses, failed withdrawal preservation, withdrawal reentrancy, abi.encode reward leaves, local owed/surplus accounting, and forced ETH surplus.
• Docs impact: updates ADR 0003, status/blockers, test README, roadmap matrix, Slither baseline, and autonomous run state.
• Known limitations or follow-up issues: curator reward claims now require local StreamCuratorsPool surplus before claim consumption. Shared ledger and reserve movement from other contracts into the curator pool remain future work and are intentionally not claimed here.

Reviewer Notes

Please focus on the local accounting boundary: this PR intentionally prevents unfunded curator credits instead of trying to move reserves across contracts in the same change. It also changes reward Merkle leaf hashing from packed encoding to abi.encode(rewardAddress, collectionID, amount) as a pre-beta target-state safety fix.

Summary by CodeRabbit

• New Features

  • Curator rewards are now recorded as withdrawable curator credits and can be withdrawn via new withdrawal endpoints.

• Bug Fixes

  • Emergency withdrawals are limited to surplus above owed curator credits to prevent over-withdrawal.
  • Claim and withdrawal flows are protected against reentrancy and failing recipient transfers do not erase credits.

• Tests

  • New test suite validating credit-based claims, withdrawal safety, Merkle claim validation, and emergency/surplus behavior.

• Documentation

  • Updated docs, status, roadmap, and runbooks to reflect the curator credit accounting and rollout status.

[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.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2b631c7c-472a-4736-8321-9c6bd9890ec7

📥 Commits

Reviewing files that changed from the base of the PR and between f7390f2 and 8353d56.

📒 Files selected for processing (9)

• docs/adr/0003-payment-accounting.md
• docs/known-blockers.md
• docs/status.md
• ops/AUTONOMOUS_RUN.md
• ops/ROADMAP.md
• ops/SLITHER_BASELINE.md
• smart-contracts/StreamCuratorsPool.sol
• test/README.md
• test/StreamCuratorsPool.t.sol

---

📝 Walkthrough

Walkthrough

This PR implements curator reward claim credits for StreamCuratorsPool (P0-PAY-005): curator reward claims now validate Merkle proofs and record withdrawable credits instead of pushing ETH; the contract tracks per-curator credit balances and aggregate owed state; emergency withdrawal is bounded to surplus above curator owed amounts. Tests and documentation updated to reflect and validate the new semantics.

Changes

Curator Reward Claim Credits (P0-PAY-005)

Layer / File(s)	Summary
ADR and blocker/status updates docs/adr/0003-payment-accounting.md, docs/known-blockers.md, docs/status.md, ops/SLITHER_BASELINE.md	ADR and ops/docs updated to record P0-PAY-005: curator claims validate Merkle leaves and record withdrawable curator credits instead of push-paying ETH; emergencyWithdraw is bounded to surplus above totalCuratorOwed; blocker/status/Slither entries adjusted accordingly.
StreamCuratorsPool credit-based implementation smart-contracts/StreamCuratorsPool.sol	Contract now inherits ReentrancyGuard, tracks curatorCredits and totalCuratorOwed, adds hashRewardLeaf, makes claimRewards verify Merkle proofs and credit curators (requiring emergencyWithdrawable() sufficiency), and provides withdrawCuratorCredit/withdrawCuratorCreditTo, totalOwed, and emergencyWithdrawable. emergencyWithdraw withdraws only surplus above owed.
StreamCuratorsPool test suite with helpers test/StreamCuratorsPool.t.sol	Foundry tests validate claim-to-credit flow, duplicate/invalid/unfunded claim handling, delegated claims, rejection-preserving-credit, zero-recipient rejection, reentrancy resistance, emergency-withdraw surplus behavior, forced-ETH surplus, and hashRewardLeaf correctness. Helper contracts simulate rejecting recipients, reentrancy, and forced ETH.
Test coverage documentation test/README.md	Documents target-state tests for curator reward claims and withdrawal invariants implemented in the new test suite.
Operational state and work tracking ops/AUTONOMOUS_RUN.md, ops/ROADMAP.md	Ops docs updated to mark fixed-price pull-payments merged and to track curator-claim-credits work as in progress; Slither baseline and roadmap/test-matrix adjusted to reflect P0-PAY-005 changes and remaining protocol-wide ledger work.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• [P0-PAY-005] Convert curator reward claims to credits #29: Main issue tracking P0-PAY-005 (StreamCuratorsPool Merkle-validated crediting and owed/withdraw flows) — this PR implements that change.
• [P0-PAY-001] Add pull-payment accounting #25: Broader pull-payment accounting (P0-PAY-001); this PR implements local curator-pool credits but not the protocol-wide shared ledger requested there.

Possibly related PRs

• 6529-Collections/6529Stream#32: ADR/pull-payment documentation changes that align with the StreamCuratorsPool behavior implemented here.

Poem

A pool of credits hums with cheer,
Merkle leaves guard each claim so clear.
No pushed ETH that can be stalled,
Withdrawals guarded, reentrancy called.
The rabbit hops — credits safe and sound. 🐰✨

🚥 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 'Convert curator reward claims to pull credits' directly reflects the main change: converting StreamCuratorsPool.claimRewards from synchronous ETH push payouts to pull-credit-based accounting.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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/curator-claim-credits

---

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

[punk6529]

@claude please review this PR for security and protocol-accounting correctness.

Focus areas:

• StreamCuratorsPool.claimRewards no longer push-pays reward addresses; it validates the Merkle proof, consumes the claim, and creates local curator credits only when local surplus can fund them.
• withdrawCuratorCredit / withdrawCuratorCreditTo should preserve credit on failed transfers and resist withdrawal reentrancy.
• emergencyWithdrawable() / emergencyWithdraw() should exclude curator credits owed.
• Reward leaf hashing intentionally moves from packed encoding to abi.encode(rewardAddress, collectionID, amount) as pre-beta target-state behavior.
• Cross-contract reserve movement/shared-ledger work is intentionally out of scope for this PR.

[punk6529]

@coderabbitai review

CI is green on latest head 8353d5623fde59ad5e02bbc2e993cb552cc23387; please refresh/finalize review status for the latest commit. No inline review threads are currently visible.

[coderabbitai]

@punk6529, acknowledged — CI is green on 8353d5623fde59ad5e02bbc2e993cb552cc23387. Triggering a fresh full review against the latest head now, with focus on the areas you outlined (pull-credit accounting, withdrawal reentrancy, emergencyWithdrawable surplus exclusion, and Merkle leaf hashing).

✅ Action performed

Full review finished.

[punk6529]

Merge-readiness note for latest head 8353d5623fde59ad5e02bbc2e993cb552cc23387:

• CI run 27271375494 completed successfully.
• Local validation passed before publish: focused 38-test payment suite, full make check with 109 tests, Windows scripts/check.ps1 with 109 tests, format check, whitespace check, and Slither delta evidence.
• Claude review was explicitly requested in comment 4669369055, but Claude skipped review because the organization overage limit was reached.
• CodeRabbit generated the PR summary and acknowledged an explicit latest-head refresh request in comment 4669408525, but the commit status remains pending with the PR comment still showing review in progress and no visible inline review threads.
• I rechecked PR comments, review submissions, review threads, and commit status after the refresh. No actionable bot comments are visible.

Proceeding under the same stale-status exception pattern used for prior PRs in this autonomous run.