RCF Phase 1: Protocol

[kethcode]

Top Level: 678
Phase Ticket: 685

P1-S1: Revolving factory interface and skeleton
P1-S2: Revolving deploy path and validation rules
P1-S3: Revolving market contract behavior
P1-S4: Unified lens market and borrower/template reads
P1-S5: Deployment scripting, template sync, and handoff artifact

Feature

A new market type implmeneting RCF (Revolving Credit Facility) behavior, while keeping legacy market behavior and ABI surfaces unchanged.

Core product behavior:

• Revolving markets accrue a commitment fee on deposited capacity
• Revolving markets accrue additional interest on drawn capital for the duration of the draw
• Revolving markets track drawn principal explicitly
• Legacy markets continue to behave exactly as before

Fee math

Interest accrued to lenders:

• = linear(commitmentFeeBips, deltaTime) + (linear(annualInterestBips, deltaTime) * utilization)

• Undrawn (utilization = 0): only commitment fee accrues

• Fully drawn (utilization = 1): commitment fee + full annual interest accrues

• Partially drawn (0 < utilization< 1): annual interest is utilization-weighted, commitment fee always applies.

• deltaTime = 0 or totalSupply = 0: no accrual

all other math remains unchanged.

Changes

New factory, not retrofitting old factory:

• Added HooksFactoryRevolving (separate deployment)
• Existing HooksFactory remains canonical for legacy market deployments

New market contract for revolving behavior:

• Added WildcatMarketRevolving
• New revolving variables live in market storage (drawnAmount, commitmentFeeBips), not MarketState

Backward-compatibility:

• MarketState was not changed
• Existing hooks payload (hooksData) remains hook-owned and is forwarded unchanged
• Revolving-only deploy metadata is passed separately as marketData

Primary new/updated contracts:

• src/IHooksFactoryRevolving.sol
• src/HooksFactoryRevolving.sol
• src/interfaces/IWildcatMarketRevolving.sol
• src/market/WildcatMarketRevolving.sol
• src/market/WildcatMarket.sol (new hook support)
• src/market/WildcatMarketBase.sol (new hook support)
• src/market/WildcatMarketWithdrawals.sol (new hook support)
• src/lens/MarketData.sol (forge fmt makes this look worse than it is)
• src/lens/MarketLens.sol (forge fmt, additive functionality)

Important supporting changes (clanker, needs review):

• Deploy/runbook/handoff artifacts for local/testnet rollout:
  • script/DeployHooksFactoryRevolving.sol
  • script/DeployMarketLens.sol
  • docs/rcf-v2-deployment-runbook.md
  • docs/rcf-v2-handoff.schema.json

Lens/read-path updates

Phase 1 lens changes are additive:

• MarketDataV2 now exposes optional revolving fields with explicit presence flags
• Lens supports mixed populations (legacy + revolving) across multiple hooks factories
• Added both:
  • factory-parameterized endpoints (explicit per-factory reads)
  • aggregated endpoints (convenience reads across active factories)
• Added a factory-scoped aggregated templates endpoint to avoid collapsing factory-specific template metadata:
  • getAggregatedHooksTemplatesForBorrowerWithFactory

Deployment

HooksFactoryRevolving deploy methods now require marketData:

• Expected encoding: abi.encode(uint8 version, uint16 commitmentFeeBips)
• Current version: 1
• Validation is strict: length, version, and bounds are checked

Compatibility:

This feature is intentionally low-disruption:

• No migration of existing markets
• Legacy factory remains unchanged for legacy deploys
• MarketState ABI remains unchanged
• Existing hook payload assumptions remain unchanged
• Existing MarketDeployed listeners keep working

Test coverage

Added/expanded:

• test/HooksFactoryRevolving.t.sol
• test/market/WildcatMarketRevolving.t.sol
• test/lens/MarketLensMultiFactory.t.sol

these cover deploy validation, revolving accounting and accrual behavior, and mixed-factory lens read correctness.