refactor: move agreement lifecycle and state to RecurringCollector

Move agreement lifecycle management into RecurringCollector:
- State model: replace AgreementState enum with uint16 bitmask flags
  (REGISTERED, ACCEPTED, NOTICE_GIVEN, SETTLED, BY_PAYER, etc.)
- API: two-phase offer/accept flow replaces single-call accept(rca, sig)
- Drop ECDSA signing and Authorizable from RC
- Callback model: _shouldCallback + _notifyStateChange with gas caps
  (MAX_CALLBACK_GAS) and PayerCallbackFailed events baked in
- Extract RecurringCollectorHashing library
- RAM: nested storage per collector, pair-keyed enumeration
- SS: callback integration (acceptAgreement, afterAgreementStateChange)
  replacing direct accept/update/cancel methods
- Error simplification: drop RecurringCollector prefix from all errors

Includes callback hardening (TRST-H-1, L-1, H-2, H-4, SR-4) as part
of the new callback design rather than as a separate bolt-on.

feat: make RecurringCollector upgradeable

Convert RC to upgradeable proxy pattern:
- Add Initializable
- Move agreements mapping into ERC-7201 namespaced storage
- Split constructor into constructor + initialize()
- Add Ignition deployment modules for RC proxy
- Update test setups to deploy behind TransparentUpgradeableProxy

feat: pause RecurringCollector and RecurringAgreementManager (TRST-L-3)

Add PausableUpgradeable to RC with pause guardian management:
- pause/unpause/setPauseGuardian functions
- whenNotPaused on collect, offer, accept, cancel
- Pause guardian storage in ERC-7201 namespace

Add IEmergencyRoleControl + emergencyRevokeRole to
RecurringAgreementManager for role revocation as alternative to pause.

Author: RembrandtK

docs/PaymentsTrustModel.md

@@ -99,7 +99,7 @@ RecurringCollector adds payer callbacks when the payer is a contract:
 Caveats on effective escrow (contract payers introduce additional trust requirements — see caveat 3):
 
 1. **Thawing reduces effective balance** — a payer can initiate a thaw; once the thaw period completes, those tokens are withdrawable. The receiver should account for the thawing period and any in-progress thaws when assessing available escrow.
-2. **Cancellation freezes the collection window** at `canceledAt` — the receiver can still collect for the period up to cancellation (with `minSecondsPerCollection` bypassed), but no further.
+2. **Cancellation freezes the collection window** at `collectableUntil` — the receiver can still collect for the period up to cancellation; `minSecondsPerCollection` is enforced during the notice period and bypassed only after `collectableUntil` is reached.
 3. **Contract payers can block** — if the payer is a contract that implements `IProviderEligibility`, it can deny collection via `isEligible` (see [RecurringCollector Extensions](#recurringcollector-extensions)).
 
 **Mitigation**: The thawing period provides a window for the receiver to collect before funds are withdrawn. The escrow balance and thaw state are publicly visible on-chain.

packages/horizon/contracts/payments/collectors/RecurringCollector.sol

@@ -3,6 +3,7 @@ import { ethers } from 'ethers'
 
 import GraphPaymentsArtifact from '../../../build/contracts/contracts/payments/GraphPayments.sol/GraphPayments.json'
 import PaymentsEscrowArtifact from '../../../build/contracts/contracts/payments/PaymentsEscrow.sol/PaymentsEscrow.json'
+import RecurringCollectorArtifact from '../../../build/contracts/contracts/payments/collectors/RecurringCollector.sol/RecurringCollector.json'
 import { MigrateControllerGovernorModule } from '../periphery/Controller'
 import GraphPeripheryModule from '../periphery/periphery'
 import { deployGraphProxy } from '../proxy/GraphProxy'
@@ -40,12 +41,21 @@ export default buildModule('HorizonProxies', (m) => {
     { id: 'setContractProxy_PaymentsEscrow' },
   )
 
+  // Deploy RecurringCollector proxy (not registered in Controller — RC reads from Controller but is not looked up by others)
+  const { Proxy: RecurringCollectorProxy, ProxyAdmin: RecurringCollectorProxyAdmin } =
+    deployTransparentUpgradeableProxy(m, {
+      name: 'RecurringCollector',
+      artifact: RecurringCollectorArtifact,
+    })
+
   return {
     HorizonStakingProxy,
     GraphPaymentsProxy,
     PaymentsEscrowProxy,
+    RecurringCollectorProxy,
     GraphPaymentsProxyAdmin,
     PaymentsEscrowProxyAdmin,
+    RecurringCollectorProxyAdmin,
   }
 })
 
@@ -62,7 +72,21 @@ export const MigrateHorizonProxiesDeployerModule = buildModule('HorizonProxiesDe
     artifact: PaymentsEscrowArtifact,
   })
 
-  return { GraphPaymentsProxy, PaymentsEscrowProxy, GraphPaymentsProxyAdmin, PaymentsEscrowProxyAdmin }
+  // Deploy RecurringCollector proxy
+  const { Proxy: RecurringCollectorProxy, ProxyAdmin: RecurringCollectorProxyAdmin } =
+    deployTransparentUpgradeableProxy(m, {
+      name: 'RecurringCollector',
+      artifact: RecurringCollectorArtifact,
+    })
+
+  return {
+    GraphPaymentsProxy,
+    PaymentsEscrowProxy,
+    RecurringCollectorProxy,
+    GraphPaymentsProxyAdmin,
+    PaymentsEscrowProxyAdmin,
+    RecurringCollectorProxyAdmin,
+  }
 })
 
 export const MigrateHorizonProxiesGovernorModule = buildModule('HorizonProxiesGovernor', (m) => {

packages/horizon/ignition/modules/core/HorizonProxies.ts

@@ -0,0 +1,42 @@
+import { buildModule } from '@nomicfoundation/hardhat-ignition/modules'
+
+import RecurringCollectorArtifact from '../../../build/contracts/contracts/payments/collectors/RecurringCollector.sol/RecurringCollector.json'
+import GraphPeripheryModule from '../periphery/periphery'
+import { deployImplementation } from '../proxy/implementation'
+import { upgradeTransparentUpgradeableProxy } from '../proxy/TransparentUpgradeableProxy'
+import HorizonProxiesModule from './HorizonProxies'
+
+export default buildModule('RecurringCollector', (m) => {
+  const { Controller } = m.useModule(GraphPeripheryModule)
+  const { RecurringCollectorProxyAdmin, RecurringCollectorProxy } = m.useModule(HorizonProxiesModule)
+
+  const governor = m.getAccount(1)
+
+  // Deploy RecurringCollector implementation - requires periphery and proxies to be registered in the controller
+  const RecurringCollectorImplementation = deployImplementation(
+    m,
+    {
+      name: 'RecurringCollector',
+      artifact: RecurringCollectorArtifact,
+      constructorArgs: [Controller],
+    },
+    { after: [GraphPeripheryModule, HorizonProxiesModule] },
+  )
+
+  // Upgrade proxy to implementation contract
+  const RecurringCollector = upgradeTransparentUpgradeableProxy(
+    m,
+    RecurringCollectorProxyAdmin,
+    RecurringCollectorProxy,
+    RecurringCollectorImplementation,
+    {
+      name: 'RecurringCollector',
+      artifact: RecurringCollectorArtifact,
+      initArgs: [],
+    },
+  )
+
+  m.call(RecurringCollectorProxyAdmin, 'transferOwnership', [governor], { after: [RecurringCollector] })
+
+  return { RecurringCollector, RecurringCollectorProxyAdmin, RecurringCollectorImplementation }
+})

packages/horizon/ignition/modules/core/RecurringCollector.ts

@@ -4,12 +4,15 @@ import GraphPaymentsModule, { MigrateGraphPaymentsModule } from './GraphPayments
 import GraphTallyCollectorModule, { MigrateGraphTallyCollectorModule } from './GraphTallyCollector'
 import HorizonStakingModule, { MigrateHorizonStakingDeployerModule } from './HorizonStaking'
 import PaymentsEscrowModule, { MigratePaymentsEscrowModule } from './PaymentsEscrow'
+import RecurringCollectorModule from './RecurringCollector'
 
 export default buildModule('GraphHorizon_Core', (m) => {
   const { HorizonStaking, HorizonStakingImplementation } = m.useModule(HorizonStakingModule)
   const { GraphPaymentsProxyAdmin, GraphPayments, GraphPaymentsImplementation } = m.useModule(GraphPaymentsModule)
   const { PaymentsEscrowProxyAdmin, PaymentsEscrow, PaymentsEscrowImplementation } = m.useModule(PaymentsEscrowModule)
   const { GraphTallyCollector } = m.useModule(GraphTallyCollectorModule)
+  const { RecurringCollectorProxyAdmin, RecurringCollector, RecurringCollectorImplementation } =
+    m.useModule(RecurringCollectorModule)
 
   return {
     HorizonStaking,
@@ -21,10 +24,13 @@ export default buildModule('GraphHorizon_Core', (m) => {
     PaymentsEscrow,
     PaymentsEscrowImplementation,
     GraphTallyCollector,
+    RecurringCollectorProxyAdmin,
+    RecurringCollector,
+    RecurringCollectorImplementation,
   }
 })
 
-export const MigrateHorizonCoreModule = buildModule('GraphHorizon_Core', (m) => {
+export const MigrateHorizonCoreModule = buildModule('MigrateGraphHorizon_Core', (m) => {
   const { HorizonStakingProxy: HorizonStaking, HorizonStakingImplementation } = m.useModule(
     MigrateHorizonStakingDeployerModule,
   )

packages/horizon/ignition/modules/core/core.ts

@@ -31,6 +31,9 @@ export default buildModule('GraphHorizon_Deploy', (m) => {
     PaymentsEscrow,
     PaymentsEscrowImplementation,
     GraphTallyCollector,
+    RecurringCollectorProxyAdmin,
+    RecurringCollector,
+    RecurringCollectorImplementation,
   } = m.useModule(GraphHorizonCoreModule)
 
   const governor = m.getAccount(1)
@@ -74,5 +77,8 @@ export default buildModule('GraphHorizon_Deploy', (m) => {
     Transparent_Proxy_PaymentsEscrow: PaymentsEscrow,
     Implementation_PaymentsEscrow: PaymentsEscrowImplementation,
     GraphTallyCollector,
+    Transparent_ProxyAdmin_RecurringCollector: RecurringCollectorProxyAdmin,
+    Transparent_Proxy_RecurringCollector: RecurringCollector,
+    Implementation_RecurringCollector: RecurringCollectorImplementation,
   }
 })

packages/horizon/ignition/modules/deploy.ts

@@ -65,5 +65,9 @@ export function upgradeTransparentUpgradeableProxy(
     [proxy, implementation, m.encodeFunctionCall(implementation, 'initialize', metadata.initArgs)],
     options,
   )
-  return loadProxyWithABI(m, proxy, metadata, { ...options, after: [upgradeCall] })
+  return loadProxyWithABI(m, proxy, metadata, {
+    ...options,
+    id: `${metadata.name}_UpgradedProxyWithABI`,
+    after: [upgradeCall],
+  })
 }

packages/horizon/ignition/modules/proxy/TransparentUpgradeableProxy.ts

@@ -13,11 +13,12 @@ export function loadProxyWithABI(
   contract: ImplementationMetadata,
   options?: ContractOptions,
 ) {
+  const { id: customId, ...rest } = options ?? {}
   let proxyWithABI
   if (contract.artifact === undefined) {
-    proxyWithABI = m.contractAt(contract.name, proxy, options)
+    proxyWithABI = m.contractAt(customId ?? contract.name, proxy, rest)
   } else {
-    proxyWithABI = m.contractAt(`${contract.name}_ProxyWithABI`, contract.artifact, proxy, options)
+    proxyWithABI = m.contractAt(customId ?? `${contract.name}_ProxyWithABI`, contract.artifact, proxy, rest)
   }
   return proxyWithABI
 }

packages/horizon/ignition/modules/proxy/utils.ts

@@ -13,12 +13,9 @@ contract BareAgreementOwner is IAgreementOwner {
         authorizedHashes[agreementHash] = true;
     }
 
-    function approveAgreement(bytes32 agreementHash) external view override returns (bytes4) {
-        if (!authorizedHashes[agreementHash]) return bytes4(0);
-        return IAgreementOwner.approveAgreement.selector;
-    }
-
     function beforeCollection(bytes16, uint256) external override {}
 
     function afterCollection(bytes16, uint256) external override {}
+
+    function afterAgreementStateChange(bytes16, bytes32, uint16) external override {}
 }

packages/horizon/test/unit/payments/recurring-collector/BareAgreementOwner.t.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.27;
+
+import { IAgreementOwner } from "@graphprotocol/interfaces/contracts/horizon/IAgreementOwner.sol";
+
+/// @notice Malicious payer that returns empty data from supportsInterface(),
+/// causing an ABI decoding revert on the caller side that escapes try/catch.
+contract MalformedERC165Payer is IAgreementOwner {
+    mapping(bytes32 => bool) public authorizedHashes;
+
+    function authorize(bytes32 agreementHash) external {
+        authorizedHashes[agreementHash] = true;
+    }
+
+    function beforeCollection(bytes16, uint256) external override {}
+
+    function afterCollection(bytes16, uint256) external override {}
+
+    function afterAgreementStateChange(bytes16, bytes32, uint16) external override {}
+
+    /// @notice Responds to supportsInterface with empty returndata.
+    /// The call succeeds at the EVM level but the caller cannot ABI-decode the result.
+    fallback() external {
+        // solhint-disable-next-line no-inline-assembly
+        assembly {
+            return(0, 0)
+        }
+    }
+}