Add Node Payout Doc section by mkysel · Pull Request #243 · xmtp/smart-contracts

mkysel · 2025-12-18T14:23:14Z

Add Node Payout documentation and restructure payer reports in payer-reports.md

Update payer-reports.md with the Node Payout section, sequence diagrams, PayerReport accounting model, onchain contract interactions, signature requirements, immutable submission parameters, and settlement semantics.

📍Where to Start

Start with the new "Node Payout" section and the updated "PayerReport" overview in payer-reports.md.

Macroscope summarized 5437d59.

Summary by CodeRabbit

Documentation
- Expanded payer report documentation with detailed workflow descriptions, including report submission, settlement, and node payout processes.
- Added JSON examples and improved error handling coverage.
- Enhanced readability with clearer organization and explicit section headings.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2025-12-18T14:23:25Z

Walkthrough

Documentation expansion for payer-report system, replacing high-level exposition with detailed descriptions of PayerReport structure, attestation/signing requirements, onchain submission, settlement mechanics, node payout lifecycle, and protocol-fee handling. Added JSON examples, explicit subheadings, sequence diagram context, and workflow clarifications.

Changes

Cohort / File(s)	Change Summary
Payer Report Documentation Expansion `doc/payer-reports.md`	Expanded and restructured offchain message handling documentation with detailed PayerReport structure including JSON example, clarified attestation/signing with explicit subheadings and ordering requirements, added onchain submission narrative with sequence diagram context, expanded settlement mechanics and node payout lifecycle (pull-based flow with DistributionManager), clarified protocol-fee accrual and settlement, improved error handling coverage and general formatting.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Multiple interrelated sections reorganized and expanded (PayerReport structure, attestation, settlement, payout lifecycle) requiring verification of consistency across sections
Addition of concrete examples (JSON snippet) and diagram references requiring accuracy validation
Clarifications around contract coordination (PayerReportManager, PayerRegistry, DistributionManager) and flow sequencing need careful review against system design

Possibly related PRs

Documentation on payer reports #131 — Modifies the same documentation file and expands PayerReport specification/lifecycle
doc: Updates to some docs and Proxy/Factory/Migration documentation #132 — Updates documentation for the same on-chain components (PayerReportManager, DistributionManager) and payer-report/settlement handling
Settlement chain smart contract overview docs #116 — Updates documentation covering the same settlement-chain components (PayerReportManager, PayerRegistry, DistributionManager, Merkle-signed reports)

Suggested labels

documentation

Suggested reviewers

fbac
deluca-mike
neekolas

Poem

🐰 A rabbit hops through payer flows,
Where reports and settle-dance now grows,
Signatures ordered, nodes align,
Node payouts pull—a design so fine!
Through Merkle trees and fee refrain,
Clear docs now guide us once again! 📋✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add Node Payout Doc section' accurately describes the main change: expanding documentation for node payout lifecycle and related concepts in the payer-reports.md file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch mkysel/add-node-payout-doc

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bfc44bf and 5437d59.

📒 Files selected for processing (1)

doc/payer-reports.md (6 hunks)

🧰 Additional context used

🧠 Learnings (6)

📚 Learning: 2025-05-13T06:06:51.203Z

Learnt from: deluca-mike
Repo: xmtp/smart-contracts PR: 59
File: src/settlement-chain/DistributionManager.sol:90-99
Timestamp: 2025-05-13T06:06:51.203Z
Learning: The DistributionManager.claim() function should perform array length validation between originatorNodeIds_ and payerReportIndices_ arrays using the ArrayLengthMismatch() custom error (already defined in IPayerReportManager) before calling getPayerReports(), even though PayerReportManager also performs this check. This provides proper separation of concerns and makes the contract more robust by catching errors earlier.

Applied to files:

doc/payer-reports.md

📚 Learning: 2025-05-13T06:02:34.726Z

Learnt from: deluca-mike
Repo: xmtp/smart-contracts PR: 59
File: src/settlement-chain/DistributionManager.sol:102-108
Timestamp: 2025-05-13T06:02:34.726Z
Learning: The `DistributionManager` contract's `claim` function assumes that the array returned by `PayerReportManager.getPayerReports()` preserves the same order as the input arrays. This is a deliberate design decision since both are first-party contracts, and integration tests are expected to catch any issues if implementations change.

Applied to files:

doc/payer-reports.md

📚 Learning: 2025-05-13T06:06:51.203Z

Learnt from: deluca-mike
Repo: xmtp/smart-contracts PR: 59
File: src/settlement-chain/DistributionManager.sol:90-99
Timestamp: 2025-05-13T06:06:51.203Z
Learning: The DistributionManager.claim() function should perform array length validation for originatorNodeIds_ and payerReportIndices_ parameters before calling getPayerReports(), even though PayerReportManager also performs this check. This ensures proper separation of concerns and increased robustness. The same error type (ArrayLengthMismatch) should be used for consistency with PayerReportManager.

Applied to files:

doc/payer-reports.md

📚 Learning: 2025-05-13T06:06:51.203Z

Learnt from: deluca-mike
Repo: xmtp/smart-contracts PR: 59
File: src/settlement-chain/DistributionManager.sol:90-99
Timestamp: 2025-05-13T06:06:51.203Z
Learning: The DistributionManager.claim() function should perform its own validation of array lengths between originatorNodeIds_ and payerReportIndices_ parameters before calling getPayerReports(), even though PayerReportManager.getPayerReports() also performs this check. This ensures proper separation of concerns and increased robustness.

Applied to files:

doc/payer-reports.md

📚 Learning: 2025-05-06T08:42:22.906Z

Learnt from: deluca-mike
Repo: xmtp/smart-contracts PR: 56
File: src/settlement-chain/PayerReportManager.sol:325-333
Timestamp: 2025-05-06T08:42:22.906Z
Learning: The XMTP protocol limits canonical nodes to a maximum that can fit in a `uint8` (255 nodes), which is why the `validSignatureCount_` variable in `PayerReportManager` is typed as `uint8`.

Applied to files:

doc/payer-reports.md

📚 Learning: 2025-05-14T08:30:12.114Z

Learnt from: deluca-mike
Repo: xmtp/smart-contracts PR: 64
File: src/settlement-chain/SettlementChainGateway.sol:17-18
Timestamp: 2025-05-14T08:30:12.114Z
Learning: The SettlementChainGateway contract in the xmtp/smart-contracts repository follows the CEI (checks, effects, interactions) pattern as a defense against reentrancy attacks. The team prefers to wait for formal audits to determine if explicit ReentrancyGuard implementations are necessary rather than adding them preemptively.

Applied to files:

doc/payer-reports.md

🪛 LanguageTool

doc/payer-reports.md

[grammar] ~22-~22: Ensure spelling is correct
Context: ...LS message types are published directly onchain, and payers interacting through the Gat...