Escrow management

[RembrandtK]

Draft proposal for discussion. Not final code, but enough to demonstrate the concept.

This model is simpler than the previous spike based on signal and involves no changes to staking, curation, disputes, token economics, or the collection/payment math itself. The existing signed RCA flow continues to work unchanged.

It does involve additional contract code. I think the code changes are minor and the new contract is quite simple. The value of using this approach is high IMO.

An alternative purely off-chain model would require an operator service that holds a payer key, monitors agreement state, calculates escrow requirements, and submits deposit transactions. The contracts here replace that service with a small set of on-chain primitives. The tradeoffs favour on-chain for this use case:

Reliability

An off-chain funding service is a single point of failure. The on-chain model makes escrow funding atomic with agreement offers, there is no window where an agreement exists but escrow doesn't cover it. Reconciliation is permissionless, so any party can top up escrow after a collection without depending on one operator's infrastructure.

State consistency

An off-chain service must reconstruct agreement state from chain events, and every state transition is a potential desync. The on-chain model delegates to RecurringCollector.getMaxNextClaim() as a single source of truth.

Operational simplicity

The off-chain model requires a hot wallet, a monitoring service, deposit scheduling, underfunding alerts, and a state database. The on-chain model requires calling offerAgreement and periodically calling reconcile.

Escrow efficiency

On-chain funding is precise and on-demand: escrow is sized to exactly the sum of worst-case next claims and adjusted after each collection. An off-chain service would need to over-allocate as a safety margin to account for timing uncertainty and latency in deposit transactions.

Transparency

Agreement terms, escrow balances, and funding deficits are all visible on-chain. Indexers and other participants can independently verify that escrow backing exists for their agreements rather than trusting an opaque off-chain service to maintain it. This also supports tighter escrow sizing because participants can be more comfortable with lower margins when top-ups are transparent and predictable.

Time to deliver

The on-chain contract is self-contained and deterministic. It can be tested with standard Foundry/Hardhat tooling and is easy to deploy. An off-chain escrow manager needs event-driven state reconstruction, race condition handling, transaction retry logic, its own infrastructure, and an independent deployment and monitoring pipeline. That's significantly more work to build, test, and get right.

[socket-security]

No dependency changes detected. Learn more about Socket for GitHub.

👍 No dependency changes detected in pull request

[openzeppelin-code]

Escrow management

Generated at commit: ad0b85847d68f1c65015eae7508f0e01c81c326b

🚨 Report Summary

	Severity Level	Results
Contracts	Critical High Medium Low Note Total	3 5 0 14 37 59
Dependencies	Critical High Medium Low Note Total	0 0 0 0 0 0

---

For more details view the full report in OpenZeppelin Code Inspector

[codecov]

Codecov Report

❌ Patch coverage is 0.62500% with 159 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.58%. Comparing base (5b9463f) to head (ad0b858).
⚠️ Report is 2 commits behind head on rem-baseline-merge.

Files with missing lines	Patch %	Lines
...ce/contracts/allocate/IndexingAgreementManager.sol	0.00%	159 Missing ⚠️

Additional details and impacted files

@@                  Coverage Diff                   @@
##           rem-baseline-merge    #1290      +/-   ##
======================================================
- Coverage               86.80%   81.58%   -5.22%     
======================================================
  Files                      46       47       +1     
  Lines                    2485     2644     +159     
  Branches                  743      787      +44     
======================================================
  Hits                     2157     2157              
- Misses                    328      487     +159     

Flag	Coverage Δ
unittests	81.58% <0.62%> (-5.22%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.