docs: update RecurringAgreementManager doc and refocus on consumer perspective#1348
Draft
RembrandtK wants to merge 3 commits into
Draft
docs: update RecurringAgreementManager doc and refocus on consumer perspective#1348RembrandtK wants to merge 3 commits into
RembrandtK wants to merge 3 commits into
Conversation
…rspective - correct interface count (eight) and add IEmergencyRoleControl - document minResidualEscrowFactor, residual-drop cleanup, and emergencyRevokeRole - fix IAgreementOwner role (collection callbacks; ERC-165 contract-payer), and describe signatureless acceptance via the stored on-chain offer - note RAM is collector-agnostic (RC is the example), and that the fully-funded relation is the Full-basis target, not an invariant - add funding-not-guaranteed caveat and AGREEMENT_MANAGER_ROLE over-commit responsibility - reframe cleanup table around the single maxNextClaim==0 trigger - restructure: lead with public surface, move deep mechanics into Key Concepts
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the RecurringAgreementManager (RAM) documentation to better reflect the current contract behavior and present it from an integrator/consumer perspective (with deeper mechanics deferred to NatSpec).
Changes:
- Reframes RAM as a collector-agnostic contract payer and documents key lifecycle flows (offer/accept/collect/reconcile/cleanup).
- Expands and clarifies roles, interfaces, and operational caveats (e.g., funding not guaranteed; emergency role revocation; residual escrow cleanup).
- Reorganizes escrow behavior explanations (configured vs effective basis; degradation thresholds) and adds monitoring/configuration guidance.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| If RAM is paused, these callbacks revert (low-level calls, so the collection itself still succeeds) and escrow accounting drifts until RAM is unpaused and reconciled. To fully halt collections, pause `RecurringCollector` too. | ||
|
|
||
| Collection flows through `SubgraphService → RecurringCollector → PaymentsEscrow`. RecurringCollector then calls `IAgreementOwner.afterCollection` on the payer, which triggers automatic reconciliation and escrow top-up in the same transaction. Manual reconcile is still available as a fallback. | ||
| Reconciliation can also be triggered manually at any time (permissionless): |
| ### Reconciliation | ||
| | Agreement State | maxNextClaim | | ||
| | --------------------------- | -------------------------------------------------------------------- | | ||
| | NotAccepted (pre-offered) | Stored estimate from `offerAgreement` | |
|
|
||
| - **`cancelAgreement`** — routes cancellation through the collector's `cancel` function (passing the terms hash), then reconciles locally. Cancels un-accepted offers, accepted agreements, or pending updates depending on the `versionHash` provided. Requires AGREEMENT_MANAGER_ROLE. | ||
| - **`forceRemoveAgreement`** — operator escape hatch for agreements whose collector is unresponsive (broken upgrade, permanent pause). Zeroes the agreement's maxNextClaim, removes it from pair tracking, and triggers pair reconciliation. Requires OPERATOR_ROLE. | ||
| - **`cancelAgreement(collector, agreementId, versionHash, options)`** — routes cancellation through the collector, then reconciles. Depending on `versionHash`, cancels an un-accepted offer, an accepted agreement, or a pending update. Requires `AGREEMENT_MANAGER_ROLE`. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1348 +/- ##
=======================================
Coverage 91.16% 91.16%
=======================================
Files 81 81
Lines 5319 5319
Branches 1128 1128
=======================================
Hits 4849 4849
Misses 448 448
Partials 22 22
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
- Full-basis target sums maxNextClaim over all tracked agreements (not just active) - note reconcile is blocked while RAM is paused (whenNotPaused) - maxNextClaim always read from collector getMaxNextClaim (active+pending); NotAccepted value is the collector's time-dependent conservative max, not RAM-stored - cancelAgreement scope is driven by the options bitmask; versionHash matches terms
- underfunding: a collection reverts (escrow never partially drawn); a shortfall beyond one maxSecondsPerCollection window forfeits uncollected time, under-paying - pause: collection succeeds only while escrow already covers it; no JIT while paused, so an over-escrow collection reverts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The doc had drifted from the contract implementation and talked in terms implementation detail.
This brings it current and reorients it toward integrators/devs (overview + concepts; NatSpec carries the depth).
Doc-only; no code changes.
IEmergencyRoleControlminResidualEscrowFactor, residual-drop cleanup, andemergencyRevokeRoleIAgreementOwnerrole (collection callbacks; ERC-165 contract-payer), and describe signatureless acceptance via the stored on-chain offerAGREEMENT_MANAGER_ROLEover-commit responsibilitymaxNextClaim==0trigger