From 20229de2603eb817bc7972606e38ffd5ccd0e01c Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Mon, 23 Feb 2026 09:49:22 +0000 Subject: [PATCH 01/12] feat(deployment): REO tasks, localNetwork support, and tooling improvements --- packages/contracts/hardhat.config.ts | 3 +- packages/deployment/README.md | 5 +- .../deploy/allocate/allocator/07_activate.ts | 24 +- .../deploy/allocate/pilot/04_configure.ts | 47 ++- .../rewards/eligibility/04_configure.ts | 16 +- .../rewards/eligibility/06_integrate.ts | 11 +- .../deploy/rewards/reclaim/04_configure.ts | 66 +-- packages/deployment/docs/DeploymentSetup.md | 1 + packages/deployment/docs/LocalForkTesting.md | 22 + .../docs/SyncBytecodeDetectionFix.md | 157 +++++++ .../deploy/IssuanceAllocatorDeployment.md | 28 +- .../RewardsEligibilityOracleDeployment.md | 2 +- packages/deployment/hardhat.config.ts | 43 +- packages/deployment/lib/abis.ts | 2 +- packages/deployment/lib/address-book-utils.ts | 27 ++ packages/deployment/lib/controller-utils.ts | 16 + packages/deployment/lib/sync-utils.ts | 142 ++++--- packages/deployment/rocketh/config.ts | 10 + packages/deployment/scripts/check-bytecode.ts | 54 +++ .../scripts/check-rocketh-bytecode.ts | 34 ++ .../deployment/scripts/debug-deploy-state.ts | 27 ++ packages/deployment/scripts/tag-deployment.sh | 272 ++++++++++++ .../deployment/tasks/deployment-status.ts | 70 +++- packages/deployment/tasks/reo-tasks.ts | 394 ++++++++++++++++++ packages/deployment/tasks/verify-contract.ts | 5 +- .../src/hardhat/hardhat.base.config.ts | 9 +- 26 files changed, 1316 insertions(+), 171 deletions(-) create mode 100644 packages/deployment/docs/SyncBytecodeDetectionFix.md create mode 100644 packages/deployment/scripts/check-bytecode.ts create mode 100644 packages/deployment/scripts/check-rocketh-bytecode.ts create mode 100644 packages/deployment/scripts/debug-deploy-state.ts create mode 100755 packages/deployment/scripts/tag-deployment.sh create mode 100644 packages/deployment/tasks/reo-tasks.ts diff --git a/packages/contracts/hardhat.config.ts b/packages/contracts/hardhat.config.ts index 86b77d5c5..ba90039ca 100644 --- a/packages/contracts/hardhat.config.ts +++ b/packages/contracts/hardhat.config.ts @@ -60,7 +60,8 @@ const config: HardhatUserConfig = { etherscan: { // Use ARBISCAN_API_KEY for Arbitrum networks // For mainnet Ethereum, use ETHERSCAN_API_KEY - apiKey: vars.has('ARBISCAN_API_KEY') ? vars.get('ARBISCAN_API_KEY') : '', + // Check both keystore (vars) and environment variable + apiKey: vars.has('ARBISCAN_API_KEY') ? vars.get('ARBISCAN_API_KEY') : (process.env.ARBISCAN_API_KEY ?? ''), }, sourcify: { enabled: false, diff --git a/packages/deployment/README.md b/packages/deployment/README.md index bf0968669..3be7874da 100644 --- a/packages/deployment/README.md +++ b/packages/deployment/README.md @@ -64,7 +64,8 @@ FORK_NETWORK=arbitrumSepolia ARBITRUM_SEPOLIA_RPC= pnpm test ## See Also -- [docs/DeploymentDesignPrinciples.md](./docs/DeploymentDesignPrinciples.md) - Core design principles and patterns +- [docs/deploy/ImplementationPrinciples.md](./docs/deploy/ImplementationPrinciples.md) - Core design principles and patterns - [docs/Architecture.md](./docs/Architecture.md) - Package structure and tags - [docs/GovernanceWorkflow.md](./docs/GovernanceWorkflow.md) - Detailed governance workflow -- [Design.md](./docs/Design.md) - Technical design documentation +- [docs/Design.md](./docs/Design.md) - Technical design documentation +- [docs/LocalForkTesting.md](./docs/LocalForkTesting.md) - Fork-based and local network testing diff --git a/packages/deployment/deploy/allocate/allocator/07_activate.ts b/packages/deployment/deploy/allocate/allocator/07_activate.ts index 4d189166e..74feeac5f 100644 --- a/packages/deployment/deploy/allocate/allocator/07_activate.ts +++ b/packages/deployment/deploy/allocate/allocator/07_activate.ts @@ -2,9 +2,13 @@ import { GRAPH_TOKEN_ABI, ISSUANCE_TARGET_ABI, REWARDS_MANAGER_ABI } from '@grap import { getTargetChainIdFromEnv } from '@graphprotocol/deployment/lib/address-book-utils.js' import { requireRewardsManagerUpgraded } from '@graphprotocol/deployment/lib/contract-checks.js' import { Contracts } from '@graphprotocol/deployment/lib/contract-registry.js' -import { getGovernor } from '@graphprotocol/deployment/lib/controller-utils.js' +import { canSignAsGovernor } from '@graphprotocol/deployment/lib/controller-utils.js' import { ComponentTags, Tags } from '@graphprotocol/deployment/lib/deployment-tags.js' -import { createGovernanceTxBuilder, saveGovernanceTxAndExit } from '@graphprotocol/deployment/lib/execute-governance.js' +import { + createGovernanceTxBuilder, + executeTxBatchDirect, + saveGovernanceTxAndExit, +} from '@graphprotocol/deployment/lib/execute-governance.js' import { requireContracts, requireDeployer } from '@graphprotocol/deployment/lib/issuance-deploy-utils.js' import { graph } from '@graphprotocol/deployment/rocketh/deploy.js' import type { DeployScriptModule } from '@rocketh/core/types' @@ -20,8 +24,8 @@ import { encodeFunctionData } from 'viem' * - (Optional) Set default target for unallocated issuance * * Idempotent: checks on-chain state, skips if already activated. - * Generates Safe TX batch for governance execution. - * Does NOT execute - governance must execute via Safe or deploy:execute-governance. + * If the provider has access to the governor key, executes directly. + * Otherwise generates governance TX file. * * Usage: * pnpm hardhat deploy --tags issuance-activation --network @@ -29,8 +33,8 @@ import { encodeFunctionData } from 'viem' const func: DeployScriptModule = async (env) => { const deployer = requireDeployer(env) - // Get protocol governor from Controller - const governor = await getGovernor(env) + // Check if the provider can sign as the protocol governor + const { governor, canSign } = await canSignAsGovernor(env) const [issuanceAllocator, rewardsManager, graphToken] = requireContracts(env, [ Contracts.issuance.IssuanceAllocator, @@ -120,7 +124,13 @@ const func: DeployScriptModule = async (env) => { env.showMessage(` + GraphToken.addMinter(${iaAddress})`) } - saveGovernanceTxAndExit(env, builder, `${Contracts.issuance.IssuanceAllocator.name} activation`) + if (canSign) { + env.showMessage('\nšŸ”Ø Executing activation TX batch...\n') + await executeTxBatchDirect(env, builder, governor) + env.showMessage(`\nāœ… ${Contracts.issuance.IssuanceAllocator.name} activation complete!\n`) + } else { + saveGovernanceTxAndExit(env, builder, `${Contracts.issuance.IssuanceAllocator.name} activation`) + } } func.tags = Tags.issuanceActivation diff --git a/packages/deployment/deploy/allocate/pilot/04_configure.ts b/packages/deployment/deploy/allocate/pilot/04_configure.ts index 780ca72da..5edef3e39 100644 --- a/packages/deployment/deploy/allocate/pilot/04_configure.ts +++ b/packages/deployment/deploy/allocate/pilot/04_configure.ts @@ -1,15 +1,24 @@ +import { SET_TARGET_ALLOCATION_ABI } from '@graphprotocol/deployment/lib/abis.js' import { Contracts } from '@graphprotocol/deployment/lib/contract-registry.js' -import { getGovernor } from '@graphprotocol/deployment/lib/controller-utils.js' +import { canSignAsGovernor } from '@graphprotocol/deployment/lib/controller-utils.js' import { actionTag, ComponentTags, DeploymentActions, Tags } from '@graphprotocol/deployment/lib/deployment-tags.js' +import { + createGovernanceTxBuilder, + executeTxBatchDirect, + saveGovernanceTxAndExit, +} from '@graphprotocol/deployment/lib/execute-governance.js' import { requireContracts } from '@graphprotocol/deployment/lib/issuance-deploy-utils.js' -import { execute, read } from '@graphprotocol/deployment/rocketh/deploy.js' +import { read } from '@graphprotocol/deployment/rocketh/deploy.js' import type { DeployScriptModule } from '@rocketh/core/types' +import { encodeFunctionData } from 'viem' /** * Configure PilotAllocation as IssuanceAllocator target * * Sets up PilotAllocation to receive tokens via allocator-minting from IssuanceAllocator. - * This requires IssuanceAllocator to be configured (deployer has GOVERNOR_ROLE or governance). + * Requires governor authority on IssuanceAllocator (via Controller). + * If the provider has access to the governor key, executes directly. + * Otherwise generates governance TX file. * * Idempotent: checks if already configured, skips if so. * @@ -18,10 +27,9 @@ import type { DeployScriptModule } from '@rocketh/core/types' */ const func: DeployScriptModule = async (env) => { const readFn = read(env) - const executeFn = execute(env) - // Get protocol governor from Controller - const governor = await getGovernor(env) + // Check if the provider can sign as the protocol governor + const { governor, canSign } = await canSignAsGovernor(env) const [pilotAllocation, issuanceAllocator] = requireContracts(env, [ Contracts.issuance.PilotAllocation, @@ -63,22 +71,25 @@ const func: DeployScriptModule = async (env) => { // Default: small allocation for pilot testing const pilotRate = issuancePerBlock / 100n // 1% of total issuance - env.showMessage(`\nšŸ”Ø Configuring ${Contracts.issuance.PilotAllocation.name}...`) - env.showMessage(` Setting allocatorMintingRate: ${pilotRate} (1% of ${issuancePerBlock})`) + env.showMessage(`\nšŸ”Ø Building configuration TX batch...`) + env.showMessage(` + setTargetAllocation(${pilotAllocation.address}, ${pilotRate}, 0)`) - try { - await executeFn(issuanceAllocator, { - account: governor, - functionName: 'setTargetAllocation', - args: [pilotAllocation.address, pilotRate, 0n], // allocatorMintingRate, selfMintingRate (PA doesn't self-mint) - }) + const builder = await createGovernanceTxBuilder(env, `configure-${Contracts.issuance.PilotAllocation.name}`) + const data = encodeFunctionData({ + abi: SET_TARGET_ALLOCATION_ABI, + functionName: 'setTargetAllocation', + args: [pilotAllocation.address as `0x${string}`, pilotRate, 0n], + }) + builder.addTx({ to: issuanceAllocator.address, value: '0', data }) + + if (canSign) { + env.showMessage('\nšŸ”Ø Executing configuration TX batch...\n') + await executeTxBatchDirect(env, builder, governor) env.showMessage( `\nāœ… ${Contracts.issuance.PilotAllocation.name} configured as ${Contracts.issuance.IssuanceAllocator.name} target`, ) - } catch (error) { - const errorMessage = error instanceof Error ? error.message : String(error) - env.showMessage(`\nāš ļø Configuration failed: ${errorMessage.slice(0, 100)}...`) - env.showMessage(` This may require governance execution if deployer no longer has GOVERNOR_ROLE`) + } else { + saveGovernanceTxAndExit(env, builder, `${Contracts.issuance.PilotAllocation.name} configuration`) } } diff --git a/packages/deployment/deploy/rewards/eligibility/04_configure.ts b/packages/deployment/deploy/rewards/eligibility/04_configure.ts index 849675917..89cba0910 100644 --- a/packages/deployment/deploy/rewards/eligibility/04_configure.ts +++ b/packages/deployment/deploy/rewards/eligibility/04_configure.ts @@ -1,8 +1,9 @@ import { applyConfiguration } from '@graphprotocol/deployment/lib/apply-configuration.js' -import { checkREORole, getREOConditions } from '@graphprotocol/deployment/lib/contract-checks.js' +import { getREOConditions } from '@graphprotocol/deployment/lib/contract-checks.js' import { Contracts } from '@graphprotocol/deployment/lib/contract-registry.js' +import { canSignAsGovernor } from '@graphprotocol/deployment/lib/controller-utils.js' import { actionTag, ComponentTags, DeploymentActions, Tags } from '@graphprotocol/deployment/lib/deployment-tags.js' -import { requireContracts, requireDeployer } from '@graphprotocol/deployment/lib/issuance-deploy-utils.js' +import { requireContracts } from '@graphprotocol/deployment/lib/issuance-deploy-utils.js' import { graph } from '@graphprotocol/deployment/rocketh/deploy.js' import type { DeployScriptModule } from '@rocketh/core/types' import type { PublicClient } from 'viem' @@ -10,20 +11,23 @@ import type { PublicClient } from 'viem' /** * Configure RewardsEligibilityOracle (params + roles) * + * Uses canSignAsGovernor() to check if the provider has access to the governor + * account (e.g., via mnemonic on localNetwork). If so, executes governance TXs + * directly. Otherwise, saves TX batch for separate governance execution. + * * See: docs/deploy/RewardsEligibilityOracleDeployment.md */ const func: DeployScriptModule = async (env) => { - const deployer = requireDeployer(env) const [reo] = requireContracts(env, [Contracts.issuance.RewardsEligibilityOracle]) const client = graph.getPublicClient(env) as PublicClient - const canExecuteDirectly = (await checkREORole(client, reo.address, 'GOVERNOR_ROLE', deployer)).hasRole + const { governor, canSign } = await canSignAsGovernor(env) await applyConfiguration(env, client, await getREOConditions(env), { contractName: Contracts.issuance.RewardsEligibilityOracle.name, contractAddress: reo.address, - canExecuteDirectly, - executor: deployer, + canExecuteDirectly: canSign, + executor: governor, }) } diff --git a/packages/deployment/deploy/rewards/eligibility/06_integrate.ts b/packages/deployment/deploy/rewards/eligibility/06_integrate.ts index b7670f7e3..cc64fc029 100644 --- a/packages/deployment/deploy/rewards/eligibility/06_integrate.ts +++ b/packages/deployment/deploy/rewards/eligibility/06_integrate.ts @@ -1,6 +1,7 @@ import { applyConfiguration } from '@graphprotocol/deployment/lib/apply-configuration.js' import { createRMIntegrationCondition } from '@graphprotocol/deployment/lib/contract-checks.js' import { Contracts } from '@graphprotocol/deployment/lib/contract-registry.js' +import { canSignAsGovernor } from '@graphprotocol/deployment/lib/controller-utils.js' import { ComponentTags, Tags } from '@graphprotocol/deployment/lib/deployment-tags.js' import { requireContracts } from '@graphprotocol/deployment/lib/issuance-deploy-utils.js' import { graph } from '@graphprotocol/deployment/rocketh/deploy.js' @@ -10,6 +11,10 @@ import type { PublicClient } from 'viem' /** * Integrate RewardsEligibilityOracle with RewardsManager * + * Requires governor authority on the RewardsManager (via Controller). + * If the provider has access to the governor key (e.g., mnemonic-derived accounts + * in local network), executes directly. Otherwise generates governance TX file. + * * See: docs/deploy/RewardsEligibilityOracleDeployment.md */ const func: DeployScriptModule = async (env) => { @@ -19,11 +24,13 @@ const func: DeployScriptModule = async (env) => { ]) const client = graph.getPublicClient(env) as PublicClient - // Apply: RM.rewardsEligibilityOracle = REO (always governance TX) + const { governor, canSign } = await canSignAsGovernor(env) + await applyConfiguration(env, client, [createRMIntegrationCondition(reo.address)], { contractName: `${Contracts.horizon.RewardsManager.name}-REO`, contractAddress: rm.address, - canExecuteDirectly: false, + canExecuteDirectly: canSign, + executor: governor, }) } diff --git a/packages/deployment/deploy/rewards/reclaim/04_configure.ts b/packages/deployment/deploy/rewards/reclaim/04_configure.ts index e545cd970..e3c70fa55 100644 --- a/packages/deployment/deploy/rewards/reclaim/04_configure.ts +++ b/packages/deployment/deploy/rewards/reclaim/04_configure.ts @@ -6,11 +6,15 @@ import { type ReclaimReasonKey, } from '@graphprotocol/deployment/lib/contract-checks.js' import { Contracts } from '@graphprotocol/deployment/lib/contract-registry.js' -import { getGovernor } from '@graphprotocol/deployment/lib/controller-utils.js' +import { canSignAsGovernor } from '@graphprotocol/deployment/lib/controller-utils.js' import { actionTag, ComponentTags, DeploymentActions, Tags } from '@graphprotocol/deployment/lib/deployment-tags.js' -import { createGovernanceTxBuilder } from '@graphprotocol/deployment/lib/execute-governance.js' +import { + createGovernanceTxBuilder, + executeTxBatchDirect, + saveGovernanceTxAndExit, +} from '@graphprotocol/deployment/lib/execute-governance.js' import { requireContract } from '@graphprotocol/deployment/lib/issuance-deploy-utils.js' -import { execute, graph } from '@graphprotocol/deployment/rocketh/deploy.js' +import { graph } from '@graphprotocol/deployment/rocketh/deploy.js' import type { DeployScriptModule } from '@rocketh/core/types' import { encodeFunctionData } from 'viem' @@ -28,17 +32,17 @@ import { encodeFunctionData } from 'viem' * - CLOSE_ALLOCATION ā†’ ReclaimedRewardsForCloseAllocation * * Idempotent: checks if already configured, skips if so. - * Generates Safe TX batch if direct execution fails. + * If the provider has access to the governor key, executes directly. + * Otherwise generates governance TX file. * * Usage: * pnpm hardhat deploy --tags rewards-reclaim-configure --network */ const func: DeployScriptModule = async (env) => { - const executeFn = execute(env) const client = graph.getPublicClient(env) - // Get protocol governor from Controller - const governor = await getGovernor(env) + // Check if the provider can sign as the protocol governor + const { governor, canSign } = await canSignAsGovernor(env) const rewardsManager = requireContract(env, Contracts.horizon.RewardsManager) @@ -97,45 +101,21 @@ const func: DeployScriptModule = async (env) => { for (const reclaim of needsConfiguration) { const reason = RECLAIM_REASONS[reclaim.reasonKey] - try { - const data = encodeFunctionData({ - abi: REWARDS_MANAGER_ABI, - functionName: 'setReclaimAddress', - args: [reason as `0x${string}`, reclaim.address as `0x${string}`], - }) - builder.addTx({ to: rewardsManager.address, value: '0', data }) - env.showMessage(` + setReclaimAddress(${reclaim.reasonKey}, ${reclaim.address})`) - } catch { - env.showMessage(` āš ļø setReclaimAddress not available on RewardsManager interface`) - return - } + const data = encodeFunctionData({ + abi: REWARDS_MANAGER_ABI, + functionName: 'setReclaimAddress', + args: [reason as `0x${string}`, reclaim.address as `0x${string}`], + }) + builder.addTx({ to: rewardsManager.address, value: '0', data }) + env.showMessage(` + setReclaimAddress(${reclaim.reasonKey}, ${reclaim.address})`) } - const txFile = builder.saveToFile() - env.showMessage(`\nāœ“ TX batch saved: ${txFile}`) - - // Try direct execution - env.showMessage(`\nšŸ” Attempting direct execution...`) - try { - for (const reclaim of needsConfiguration) { - const reason = RECLAIM_REASONS[reclaim.reasonKey] - - await executeFn(rewardsManager, { - account: governor, - functionName: 'setReclaimAddress', - args: [reason, reclaim.address], - }) - env.showMessage(` āœ“ setReclaimAddress(${reclaim.reasonKey}, ${reclaim.address}) executed`) - } - + if (canSign) { + env.showMessage('\nšŸ”Ø Executing configuration TX batch...\n') + await executeTxBatchDirect(env, builder, governor) env.showMessage(`\nāœ… ${Contracts.horizon.RewardsManager.name} reclaim configuration complete!`) - } catch (error) { - const errorMessage = error instanceof Error ? error.message : String(error) - env.showMessage(`\nāš ļø Direct execution failed: ${errorMessage.slice(0, 100)}...`) - env.showMessage(`\nšŸ“‹ GOVERNANCE ACTION REQUIRED:`) - env.showMessage(` The ${Contracts.horizon.RewardsManager.name} reclaim configuration must be executed via Safe.`) - env.showMessage(` TX batch file: ${txFile}`) - env.showMessage(` Import this file into Safe Transaction Builder.`) + } else { + saveGovernanceTxAndExit(env, builder, `${Contracts.horizon.RewardsManager.name} reclaim configuration`) } } diff --git a/packages/deployment/docs/DeploymentSetup.md b/packages/deployment/docs/DeploymentSetup.md index c9a2534f3..d7d5de272 100644 --- a/packages/deployment/docs/DeploymentSetup.md +++ b/packages/deployment/docs/DeploymentSetup.md @@ -124,6 +124,7 @@ npx hardhat deploy --skip-prompts --network arbitrumSepolia --tags | Network | Chain ID | RPC (default) | | --------------- | -------- | ---------------------------------------- | +| localNetwork | 1337 | `http://chain:8545` | | arbitrumSepolia | 421614 | | | arbitrumOne | 42161 | | diff --git a/packages/deployment/docs/LocalForkTesting.md b/packages/deployment/docs/LocalForkTesting.md index 7e7d70fe6..d8fc87987 100644 --- a/packages/deployment/docs/LocalForkTesting.md +++ b/packages/deployment/docs/LocalForkTesting.md @@ -136,6 +136,28 @@ npx hardhat deploy:reset-fork --network fork - **Foundry**: Install via `curl -L https://foundry.paradigm.xyz | bash && foundryup` +## Local Network (rem-local-network) + +The `localNetwork` network targets the Graph local network docker-compose stack (chain ID 1337). +Unlike fork mode, contracts are deployed fresh from scratch. + +```bash +# Deploy issuance contracts to local network +npx hardhat deploy --tags issuance-eligibility --network localNetwork +``` + +**Key differences from fork mode:** +- Chain ID 1337 (not 31337) +- No `FORK_NETWORK` env var needed +- Address books use `addresses-local-network.json` files (symlinked to mounted config) +- Deployer is also governor (direct execution, no governance batch files) +- Uses standard test mnemonic (`test test test ... junk`) + +**Environment:** +- RPC: `http://chain:8545` (override with `LOCAL_NETWORK_RPC`) +- Address books are populated by Phase 1 (hardhat-graph-protocol deploys Horizon + SubgraphService) +- Phase 2+ deployment scripts use this package to deploy additional contracts (e.g., issuance) + ## See Also - [GovernanceWorkflow.md](./GovernanceWorkflow.md) - Production deployment flow diff --git a/packages/deployment/docs/SyncBytecodeDetectionFix.md b/packages/deployment/docs/SyncBytecodeDetectionFix.md new file mode 100644 index 000000000..39d805e1a --- /dev/null +++ b/packages/deployment/docs/SyncBytecodeDetectionFix.md @@ -0,0 +1,157 @@ +# Sync Bytecode Detection Fix + +## Issues Identified + +### Issue 1: Local Bytecode Changes Ignored + +**Problem**: Deploy incorrectly reported "implementation unchanged" when local bytecode had actually changed. + +**Evidence**: +``` +Local artifact: 0x9c25d2f93e6a2a34cc19d00224872e288a8392d5d99b2df680b7e978d148d450 +On-chain: 0xfafdeb48fae37e277e007e7b977f3cd124065ac1c27ed5208982c2965cf07008 +Address book: 0x4805a902756c8f4421c2a2710dcc76885ffd01d7777bbe6cab010fe9748b7efa +``` + +All three hashes are different, yet deploy said "unchanged", meaning local changes would be ignored. + +### Issue 2: Confusing Sync Behavior + +**Problem**: Sync showed "code changed" but didn't handle the state appropriately: + +1. Showed ā–³ (code changed) indicator +2. But didn't sync implementation to rocketh +3. Saved proxy record with wrong bytecode +4. This confused rocketh's change detection + +## Root Causes + +### Cause 1: Missing/Stale Bytecode Hash + +When the address book had no bytecode hash (or wrong hash): +- Sync detected "code changed" ([sync-utils.ts:475-477](../lib/sync-utils.ts#L475-L477)) +- But only synced to rocketh if hash matched ([sync-utils.ts:653](../lib/sync-utils.ts#L653)) +- This left rocketh with incomplete/wrong state + +### Cause 2: Wrong Bytecode Stored for Proxy + +The sync step saved the **implementation's bytecode** under the **proxy's deployment record**: +- Lines 508-532: Created proxy record with implementation artifact bytecode +- This is wrong - proxy should have its own bytecode (or none) +- Rocketh then compared wrong bytecode and gave incorrect results + +## Fixes Applied + +### Fix 1: Auto-Heal Bytecode Hash ([sync-utils.ts:641-683](../lib/sync-utils.ts#L641-L683)) + +When sync detects missing/mismatched bytecode hash: + +1. **Fetch on-chain bytecode** from the implementation address +2. **Compare three versions**: local artifact, on-chain, address book +3. **Auto-heal** if local matches on-chain: + ```typescript + if (localHash === onChainHash) { + // Update address book with verified hash + hashMatches = true + shouldSync = true + syncNotes.push('hash verified' or 'hash healed') + } + ``` +4. **Show clear status** if they differ: + - `local code changed` - local differs from on-chain (ready to deploy) + - `impl state unclear` - all three hashes differ (investigation needed) + - `impl unverified` - couldn't fetch on-chain bytecode + +### Fix 2: Don't Store Wrong Bytecode for Proxy ([sync-utils.ts:508-532](../lib/sync-utils.ts#L508-L532)) + +Changed proxy record creation to **NOT include implementation bytecode**: + +```typescript +// Before: +bytecode: artifact.bytecode // ā† Wrong! This is implementation bytecode +deployedBytecode: artifact.deployedBytecode + +// After: +bytecode: '0x' // ā† Correct! Proxy record doesn't need bytecode +deployedBytecode: undefined +``` + +This ensures rocketh only uses implementation bytecode for the actual implementation record. + +## Expected Behavior After Fix + +### Scenario 1: Local Matches On-Chain (Hash Missing) + +**Before**: +``` +ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (code changed) +āœ“ SubgraphService implementation unchanged ā† WRONG! +``` + +**After**: +``` +ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (hash verified) +āœ“ SubgraphService implementation unchanged ā† Correct (hash now matches) +``` + +Address book is auto-healed with correct bytecode hash. + +### Scenario 2: Local Code Changed + +**Before**: +``` +ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (code changed) +āœ“ SubgraphService implementation unchanged ā† WRONG! +``` + +**After**: +``` +ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (local code changed) +šŸ“‹ New SubgraphService implementation deployed: 0x... ā† NEW! + Storing as pending implementation... +``` + +Deploy correctly detects the change and deploys new implementation. + +### Scenario 3: Complex State (All Different) + +**Before**: +``` +ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (code changed) +``` + +**After**: +``` +ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (impl state unclear) +``` + +Clear warning that investigation needed - all three hashes differ. + +## Testing + +To verify the fix works: + +```bash +# Clean build +cd packages/deployment +pnpm build + +# Run sync - should now show clearer messages +npx hardhat deploy --skip-prompts --network arbitrumSepolia --tags sync + +# Run deploy - should correctly detect local changes +npx hardhat deploy --skip-prompts --network arbitrumSepolia --tags subgraph-service +``` + +## Migration Notes + +- **No manual migration needed** - the fix auto-heals address books +- First sync after fix will fetch on-chain bytecode and update hashes +- Address book will be updated in place with correct metadata +- Subsequent syncs will use the healed hashes + +## Related Files + +- [sync-utils.ts](../lib/sync-utils.ts) - Main fix implementation +- [deploy-implementation.ts](../lib/deploy-implementation.ts) - Deploy logic (unchanged, now works correctly) +- [check-bytecode.ts](../scripts/check-bytecode.ts) - Diagnostic script for manual verification diff --git a/packages/deployment/docs/deploy/IssuanceAllocatorDeployment.md b/packages/deployment/docs/deploy/IssuanceAllocatorDeployment.md index 553157fbd..92d9f73b0 100644 --- a/packages/deployment/docs/deploy/IssuanceAllocatorDeployment.md +++ b/packages/deployment/docs/deploy/IssuanceAllocatorDeployment.md @@ -1,6 +1,6 @@ # IssuanceAllocator Deployment -This document describes the deployment sequence for IssuanceAllocator. For contract architecture, behavior, and technical details, see [IssuanceAllocator.md](../../../../issuance/contracts/allocate/IssuanceAllocator.md). +This document describes the deployment sequence for IssuanceAllocator. For contract architecture, behavior, and technical details, see [IssuanceAllocator.md](../../../issuance/contracts/allocate/IssuanceAllocator.md). ## Prerequisites @@ -18,13 +18,13 @@ The deployment strategy safely replicates existing issuance configuration during - Granting of minter role can be delayed until replication of initial configuration with upgraded RewardsManager is verified to allow seamless transition to use of IssuanceAllocator - **Governance control**: This contract uses OpenZeppelin's TransparentUpgradeableProxy pattern (not custom GraphProxy). GraphIssuanceProxyAdmin (owned by protocol governance) controls upgrades, while GOVERNOR_ROLE controls operations. The same governance address should have both roles. -For the general governance-gated upgrade workflow, see [GovernanceWorkflow.md](../../../docs/GovernanceWorkflow.md). +For the general governance-gated upgrade workflow, see [GovernanceWorkflow.md](../GovernanceWorkflow.md). ## Deployment Sequence ### Step 1: Deploy and Initialize (deployment account) -**Script:** [01_deploy.ts](./01_deploy.ts) +**Script:** [01_deploy.ts](../../deploy/allocate/allocator/01_deploy.ts) - Deploy IssuanceAllocator implementation with GraphToken address - Deploy TransparentUpgradeableProxy with implementation, GraphIssuanceProxyAdmin, and initialization data @@ -36,7 +36,7 @@ For the general governance-gated upgrade workflow, see [GovernanceWorkflow.md](. ### Step 2: Set Issuance Rate (deployment account) -**Script:** [02_configure.ts](./02_configure.ts) +**Script:** [04_configure.ts](../../deploy/allocate/allocator/04_configure.ts) - Query current rate from RewardsManager: `rate = rewardsManager.issuancePerBlock()` - Call `setIssuancePerBlock(rate)` to replicate existing rate @@ -45,7 +45,7 @@ For the general governance-gated upgrade workflow, see [GovernanceWorkflow.md](. ### Step 3: Assign RewardsManager Allocation (deployment account) -**Script:** [02_configure.ts](./02_configure.ts) +**Script:** [04_configure.ts](../../deploy/allocate/allocator/04_configure.ts) - Call `setTargetAllocation(rewardsManagerAddress, 0, issuancePerBlock)` - `allocatorMintingRate = 0` (RewardsManager will self-mint) @@ -54,7 +54,7 @@ For the general governance-gated upgrade workflow, see [GovernanceWorkflow.md](. ### Step 4: Verify Configuration Before Transfer (deployment account) -**Script:** [02_configure.ts](./02_configure.ts) +**Script:** [04_configure.ts](../../deploy/allocate/allocator/04_configure.ts) - Verify contract is not paused (`paused()` returns false) - Verify `getIssuancePerBlock()` returns expected rate (matches RewardsManager) @@ -65,7 +65,7 @@ For the general governance-gated upgrade workflow, see [GovernanceWorkflow.md](. ### Step 5: Distribute Issuance (anyone - no role required) -**Script:** [02_configure.ts](./02_configure.ts) +**Script:** [04_configure.ts](../../deploy/allocate/allocator/04_configure.ts) - Call `distributeIssuance()` to bring contract to fully current state - Updates `lastDistributionBlock` to current block @@ -74,7 +74,7 @@ For the general governance-gated upgrade workflow, see [GovernanceWorkflow.md](. ### Step 6: Set Pause Controls and Transfer Governance (deployment account) -**Script:** [03_transfer_governance.ts](./03_transfer_governance.ts) +**Script:** [06_transfer_governance.ts](../../deploy/allocate/allocator/06_transfer_governance.ts) - Grant PAUSE_ROLE to pause guardian (same account as used for RewardsManager pause control) - Grant GOVERNOR_ROLE to actual governor address (protocol governance multisig) @@ -83,7 +83,7 @@ For the general governance-gated upgrade workflow, see [GovernanceWorkflow.md](. ### Step 7: Verify Deployment and Configuration (governor) -**Script:** [04_verify.ts](./04_verify.ts) +**Script:** [05_verify_governance.ts](../../deploy/allocate/allocator/05_verify_governance.ts) **Bytecode verification:** @@ -117,7 +117,7 @@ For the general governance-gated upgrade workflow, see [GovernanceWorkflow.md](. ### Step 8: Configure RewardsManager (governor) -**Script:** [05_configure_rewards_manager.ts](./05_configure_rewards_manager.ts) +**Script:** [07_activate.ts](../../deploy/allocate/allocator/07_activate.ts) - Call `rewardsManager.setIssuanceAllocator(issuanceAllocatorAddress)` - RewardsManager will now query IssuanceAllocator for its issuance rate @@ -125,13 +125,13 @@ For the general governance-gated upgrade workflow, see [GovernanceWorkflow.md](. ### Step 9: Grant Minter Role (governor, only when configuration verified) -**Script:** [06_grant_minter.ts](./06_grant_minter.ts) +**Script:** [07_activate.ts](../../deploy/allocate/allocator/07_activate.ts) - Grant minter role to IssuanceAllocator on Graph Token ### Step 10: Set Default Target (governor, optional, recommended) -**Script:** [07_set_default_target.ts](./07_set_default_target.ts) +**Script:** [07_activate.ts](../../deploy/allocate/allocator/07_activate.ts) - Call `setDefaultTarget()` to receive future unallocated issuance @@ -156,5 +156,5 @@ When `setIssuancePerBlock()` is called, the L1GraphTokenGateway's `updateL2MintA ## See Also -- [IssuanceAllocator.md](../../../../issuance/contracts/allocate/IssuanceAllocator.md) - Contract architecture and technical details -- [GovernanceWorkflow.md](../../../docs/GovernanceWorkflow.md) - General governance-gated upgrade workflow +- [IssuanceAllocator.md](../../../issuance/contracts/allocate/IssuanceAllocator.md) - Contract architecture and technical details +- [GovernanceWorkflow.md](../GovernanceWorkflow.md) - General governance-gated upgrade workflow diff --git a/packages/deployment/docs/deploy/RewardsEligibilityOracleDeployment.md b/packages/deployment/docs/deploy/RewardsEligibilityOracleDeployment.md index 6d05be2e4..b896d5c48 100644 --- a/packages/deployment/docs/deploy/RewardsEligibilityOracleDeployment.md +++ b/packages/deployment/docs/deploy/RewardsEligibilityOracleDeployment.md @@ -5,7 +5,7 @@ Deployment guide for RewardsEligibilityOracle (REO). **Related:** - [Contract specification](../../../issuance/contracts/eligibility/RewardsEligibilityOracle.md) - architecture, operations, troubleshooting -- [GovernanceWorkflow.md](./GovernanceWorkflow.md) - Safe TX execution +- [GovernanceWorkflow.md](../GovernanceWorkflow.md) - Safe TX execution ## Prerequisites diff --git a/packages/deployment/hardhat.config.ts b/packages/deployment/hardhat.config.ts index 08b85b027..070414ce8 100644 --- a/packages/deployment/hardhat.config.ts +++ b/packages/deployment/hardhat.config.ts @@ -15,6 +15,7 @@ import executeGovernanceTask from './tasks/execute-governance.js' import grantRoleTask from './tasks/grant-role.js' import listPendingTask from './tasks/list-pending-implementations.js' import listRolesTask from './tasks/list-roles.js' +import { reoDisableTask, reoEnableTask, reoStatusTask } from './tasks/reo-tasks.js' import resetForkTask from './tasks/reset-fork.js' import revokeRoleTask from './tasks/revoke-role.js' import verifyContractTask from './tasks/verify-contract.js' @@ -26,6 +27,14 @@ const __dirname = path.dirname(__filename) // Package paths const packageRoot = __dirname +// Hardhat v3 does not auto-set HARDHAT_NETWORK (v2 did). +// isLocalNetworkMode() in address-book-utils.ts relies on this env var to +// select addresses-local-network.json over addresses.json. +const networkArg = process.argv.find((_, i, a) => a[i - 1] === '--network') +if (networkArg === 'localNetwork') { + process.env.HARDHAT_NETWORK = 'localNetwork' +} + // RPC URLs with defaults const ARBITRUM_ONE_RPC = process.env.ARBITRUM_ONE_RPC || 'https://arb1.arbitrum.io/rpc' const ARBITRUM_SEPOLIA_RPC = process.env.ARBITRUM_SEPOLIA_RPC || 'https://sepolia-rollup.arbitrum.io/rpc' @@ -50,7 +59,14 @@ function getDeployerKeyName(networkName: string): string { } /** - * Get accounts config for a network using configVariable for lazy resolution + * Get accounts config for a network. + * + * Uses configVariable for lazy resolution. If the key is not set (env var or keystore), + * read-only operations will still work but signing will fail with HHE7 error. + * + * To enable signing, set the key via: + * - Environment: export ARBITRUM_SEPOLIA_DEPLOYER_KEY=0x... + * - Keystore: npx hardhat keystore set ARBITRUM_SEPOLIA_DEPLOYER_KEY */ const getNetworkAccounts = (networkName: string) => { return [configVariable(getDeployerKeyName(networkName))] @@ -71,6 +87,9 @@ const config: HardhatUserConfig = { grantRoleTask, listPendingTask, listRolesTask, + reoDisableTask, + reoEnableTask, + reoStatusTask, resetForkTask, revokeRoleTask, verifyContractTask, @@ -78,6 +97,17 @@ const config: HardhatUserConfig = { // Chain descriptors for fork execution and local development chainDescriptors: { + // Graph Local Network (rem-local-network, docker-compose stack) + 1337: { + name: 'Graph Local Network', + hardforkHistory: { + berlin: { blockNumber: 0 }, + london: { blockNumber: 0 }, + merge: { blockNumber: 0 }, + shanghai: { blockNumber: 0 }, + cancun: { blockNumber: 0 }, + }, + }, // Local hardhat network (for non-fork runs) 31337: { name: 'Hardhat Local', @@ -155,6 +185,17 @@ const config: HardhatUserConfig = { } : undefined, }, + // Graph Local Network (rem-local-network docker-compose stack) + // Contracts deployed fresh with hardhat-graph-protocol (Phase 1) + // Address books use addresses-local-network.json files + localNetwork: { + type: 'http', + url: process.env.LOCAL_NETWORK_RPC || 'http://chain:8545', + chainId: 1337, + accounts: { + mnemonic: 'test test test test test test test test test test test junk', + }, + }, arbitrumOne: { type: 'http', chainId: 42161, diff --git a/packages/deployment/lib/abis.ts b/packages/deployment/lib/abis.ts index e9894d213..b89717d42 100644 --- a/packages/deployment/lib/abis.ts +++ b/packages/deployment/lib/abis.ts @@ -22,7 +22,7 @@ function loadAbi(artifactPath: string): Abi { // and packages/contracts-test/tests/unit/rewards/rewards-interface.test.ts export const IERC165_INTERFACE_ID = '0x01ffc9a7' as const export const IISSUANCE_TARGET_INTERFACE_ID = '0xaee4dc43' as const -export const IREWARDS_MANAGER_INTERFACE_ID = '0xa0a2f219' as const +export const IREWARDS_MANAGER_INTERFACE_ID = '0x36b70adb' as const export const REWARDS_MANAGER_ABI = loadAbi( '@graphprotocol/interfaces/artifacts/contracts/contracts/rewards/IRewardsManager.sol/IRewardsManager.json', diff --git a/packages/deployment/lib/address-book-utils.ts b/packages/deployment/lib/address-book-utils.ts index 0de0db016..8b98c82d4 100644 --- a/packages/deployment/lib/address-book-utils.ts +++ b/packages/deployment/lib/address-book-utils.ts @@ -50,6 +50,21 @@ export function getForkNetwork(): string | null { return process.env.HARDHAT_FORK || process.env.FORK_NETWORK || null } +// ============================================================================ +// Local Network Detection +// ============================================================================ + +/** + * Check if running against the Graph local network (rem-local-network). + * + * The local network uses chainId 1337 and deploys contracts from scratch. + * Address books use addresses-local-network.json files which are symlinked + * to mounted config files in the Docker container (populated by Phase 1). + */ +export function isLocalNetworkMode(): boolean { + return process.env.HARDHAT_NETWORK === 'localNetwork' +} + /** * Get the fork state directory for a given network. * All fork-related state (address books, governance TXs) is stored here. @@ -206,6 +221,7 @@ export function ensureForkAddressBooks(): { /** * Get the path to the Horizon address book. * In fork mode, returns path to fork-local copy. + * In local network mode, returns path to addresses-local-network.json. * In normal mode, returns path to package address book. */ export function getHorizonAddressBookPath(): string { @@ -213,12 +229,16 @@ export function getHorizonAddressBookPath(): string { const { horizonPath } = ensureForkAddressBooks() return horizonPath } + if (isLocalNetworkMode()) { + return require.resolve('@graphprotocol/horizon/addresses-local-network.json') + } return require.resolve('@graphprotocol/horizon/addresses.json') } /** * Get the path to the SubgraphService address book. * In fork mode, returns path to fork-local copy. + * In local network mode, returns path to addresses-local-network.json. * In normal mode, returns path to package address book. */ export function getSubgraphServiceAddressBookPath(): string { @@ -226,12 +246,16 @@ export function getSubgraphServiceAddressBookPath(): string { const { subgraphServicePath } = ensureForkAddressBooks() return subgraphServicePath } + if (isLocalNetworkMode()) { + return require.resolve('@graphprotocol/subgraph-service/addresses-local-network.json') + } return require.resolve('@graphprotocol/subgraph-service/addresses.json') } /** * Get the path to the Issuance address book. * In fork mode, returns path to fork-local copy. + * In local network mode, returns path to addresses-local-network.json. * In normal mode, returns path to package address book. */ export function getIssuanceAddressBookPath(): string { @@ -239,6 +263,9 @@ export function getIssuanceAddressBookPath(): string { const { issuancePath } = ensureForkAddressBooks() return issuancePath } + if (isLocalNetworkMode()) { + return require.resolve('@graphprotocol/issuance/addresses-local-network.json') + } return require.resolve('@graphprotocol/issuance/addresses.json') } diff --git a/packages/deployment/lib/controller-utils.ts b/packages/deployment/lib/controller-utils.ts index 7180a8872..5a058e9cc 100644 --- a/packages/deployment/lib/controller-utils.ts +++ b/packages/deployment/lib/controller-utils.ts @@ -6,6 +6,22 @@ import { Contracts } from './contract-registry.js' import { requireContract } from './issuance-deploy-utils.js' import { graph } from '../rocketh/deploy.js' +/** + * Check if the provider can sign as the protocol governor + * + * With a mnemonic (local network), all derived accounts are available via eth_accounts. + * With explicit keys (production), only configured accounts are available. + * + * @param env - Deployment environment + * @returns Governor address and whether the provider can sign as governor + */ +export async function canSignAsGovernor(env: Environment): Promise<{ governor: string; canSign: boolean }> { + const governor = await getGovernor(env) + const accounts = (await env.network.provider.request({ method: 'eth_accounts' })) as string[] + const canSign = accounts.some((a) => a.toLowerCase() === governor.toLowerCase()) + return { governor, canSign } +} + /** * Get the protocol governor address from the Controller contract * diff --git a/packages/deployment/lib/sync-utils.ts b/packages/deployment/lib/sync-utils.ts index 4680158e4..75c6f79b4 100644 --- a/packages/deployment/lib/sync-utils.ts +++ b/packages/deployment/lib/sync-utils.ts @@ -215,6 +215,37 @@ export function createDeploymentMetadata( } } +/** + * Check if local artifact bytecode differs from what was last deployed. + * + * Compares the local artifact's bytecodeHash against the stored hash in the + * address book. The stored hash is recorded from the local artifact at deploy + * time, so this is a local-to-local comparison (no on-chain bytecode fetch). + * + * @returns codeChanged flag and the computed localHash (needed for hashMatches checks) + */ +function checkCodeChanged( + artifactSource: ArtifactSource | undefined, + // eslint-disable-next-line @typescript-eslint/no-explicit-any + addressBook: any, + contractName: string, +): { codeChanged: boolean; localHash?: string } { + if (!artifactSource) return { codeChanged: false } + + const localArtifact = loadArtifactFromSource(artifactSource) + const localHash = localArtifact?.deployedBytecode ? computeBytecodeHash(localArtifact.deployedBytecode) : undefined + + const deploymentMetadata = addressBook.getDeploymentMetadata(contractName) + if (deploymentMetadata?.bytecodeHash && localHash) { + return { codeChanged: localHash !== deploymentMetadata.bytecodeHash, localHash } + } + if (localArtifact?.deployedBytecode) { + // No stored bytecodeHash but artifact exists - untracked/legacy state + return { codeChanged: true, localHash } + } + return { codeChanged: false, localHash } +} + /** * Input for proxy status line generation */ @@ -463,20 +494,13 @@ async function syncContract( // Get updated entry for formatProxyStatusLine const updatedEntry = spec.proxy.addressBook.getEntry(spec.name) - // Check if local bytecode differs from deployed (via bytecodeHash) - // If artifact exists but no bytecodeHash stored, assume code changed (untracked state) - let codeChanged = false - if (spec.proxy.artifact) { - const deploymentMetadata = spec.proxy.addressBook.getDeploymentMetadata(spec.name) - const localArtifact = loadArtifactFromSource(spec.proxy.artifact) - if (deploymentMetadata?.bytecodeHash && localArtifact?.deployedBytecode) { - const localHash = computeBytecodeHash(localArtifact.deployedBytecode) - codeChanged = localHash !== deploymentMetadata.bytecodeHash - } else if (localArtifact?.deployedBytecode) { - // No stored bytecodeHash but artifact exists - untracked/legacy state - codeChanged = true - } - } + const pendingImpl = updatedEntry.pendingImplementation + const implAddress = pendingImpl?.address ?? updatedEntry.implementation + const implDeployment = pendingImpl + ? pendingImpl.deployment + : spec.proxy.addressBook.getDeploymentMetadata(spec.name) + + const { codeChanged, localHash } = checkCodeChanged(spec.proxy.artifact, spec.proxy.addressBook, spec.name) const result = formatProxyStatusLine({ name: spec.name, @@ -507,32 +531,25 @@ async function syncContract( if (!existing) { // No existing record - create from artifact + // IMPORTANT: For proxy contracts, we only load the ABI, not bytecode + // The artifact is for the implementation, not the proxy itself let abi: readonly unknown[] = [] - let bytecode: `0x${string}` = '0x' - let deployedBytecode: `0x${string}` | undefined if (spec.artifact) { const artifact = loadArtifactFromSource(spec.artifact) if (artifact?.abi) { abi = artifact.abi } - if (artifact?.bytecode) { - bytecode = artifact.bytecode as `0x${string}` - } - if (artifact?.deployedBytecode) { - deployedBytecode = artifact.deployedBytecode as `0x${string}` - } } await env.save(spec.name, { address: spec.address as `0x${string}`, abi: abi as typeof abi & readonly unknown[], - bytecode, - deployedBytecode, + bytecode: '0x' as `0x${string}`, // Don't store impl bytecode for proxy record + deployedBytecode: undefined, argsData: '0x' as `0x${string}`, metadata: '', } as unknown as Parameters[1]) } else if (addressChanged) { - // Address changed - update address but preserve existing bytecode - // This handles the case where address book points to new address + // Address changed - update address and clear bytecode (proxy address changed) let abi: readonly unknown[] = existing.abi as readonly unknown[] // Update ABI from artifact if available (ABI doesn't affect change detection) if (spec.artifact) { @@ -544,10 +561,10 @@ async function syncContract( await env.save(spec.name, { address: spec.address as `0x${string}`, abi: abi as typeof abi & readonly unknown[], - bytecode: existing.bytecode as `0x${string}`, - deployedBytecode: existing.deployedBytecode as `0x${string}`, - argsData: existing.argsData as `0x${string}`, - metadata: existing.metadata ?? '', + bytecode: '0x' as `0x${string}`, // Clear bytecode - proxy changed + deployedBytecode: undefined, + argsData: '0x' as `0x${string}`, + metadata: '', } as unknown as Parameters[1]) } // else: existing record with same address - do nothing, preserve rocketh's state @@ -625,29 +642,28 @@ async function syncContract( } as unknown as Parameters[1]) } - // Save implementation deployment record - // Pick pending or current - both have same structure (address + deployment metadata) - const pendingImpl = updatedEntry.pendingImplementation - const implAddress = pendingImpl?.address ?? updatedEntry.implementation - const implDeployment = pendingImpl - ? pendingImpl.deployment - : spec.proxy.addressBook.getDeploymentMetadata(spec.name) - + // Save implementation deployment record (if local hash matches stored) if (implAddress) { const storedHash = implDeployment?.bytecodeHash - - // Only sync if stored hash matches local artifact let hashMatches = false - if (storedHash && spec.proxy.artifact) { - const localArtifact = loadArtifactFromSource(spec.proxy.artifact) - if (localArtifact?.deployedBytecode) { - const localHash = computeBytecodeHash(localArtifact.deployedBytecode) - if (storedHash === localHash) { - hashMatches = true - } else { - syncNotes.push('impl outdated') - } - } + + if (storedHash && localHash) { + hashMatches = storedHash === localHash + } + + // Clean up stale rocketh record if hash doesn't match + // Overwrite with empty bytecode to force deploy to create fresh + const existingImpl = env.getOrNull(`${spec.name}_Implementation`) + if (!hashMatches && existingImpl) { + // Overwrite stale record with empty bytecode - forces fresh deployment + await env.save(`${spec.name}_Implementation`, { + address: existingImpl.address, + abi: existingImpl.abi, + bytecode: '0x' as `0x${string}`, + deployedBytecode: undefined, + argsData: '0x' as `0x${string}`, + metadata: '', + } as unknown as Parameters[1]) } if (hashMatches) { @@ -875,6 +891,17 @@ export async function getContractStatusLine( return { line: `āœ“ ${contractName} @ ${formatAddress(entry.address)}`, exists: true } } + // If no client available, show address book status without on-chain verification + if (!client) { + if (meta?.proxyType && entry.implementation) { + return { + line: `? ${contractName} @ ${formatAddress(entry.address)} ā†’ ${formatAddress(entry.implementation)} (no on-chain check)`, + exists: true, + } + } + return { line: `? ${contractName} @ ${formatAddress(entry.address)} (no on-chain check)`, exists: true } + } + // Check if code exists on-chain const code = await client.getCode({ address: entry.address as `0x${string}` }) if (!code || code === '0x') { @@ -904,20 +931,7 @@ export async function getContractStatusLine( } if (actualImpl) { - // Check if local bytecode differs from deployed (via bytecodeHash) - // If artifact exists but no bytecodeHash stored, assume code changed (untracked state) - let codeChanged = false - if (meta.artifact) { - const deploymentMetadata = addressBook.getDeploymentMetadata(contractName) - const localArtifact = loadArtifactFromSource(meta.artifact) - if (deploymentMetadata?.bytecodeHash && localArtifact?.deployedBytecode) { - const localHash = computeBytecodeHash(localArtifact.deployedBytecode) - codeChanged = localHash !== deploymentMetadata.bytecodeHash - } else if (localArtifact?.deployedBytecode) { - // No stored bytecodeHash but artifact exists - untracked/legacy state - codeChanged = true - } - } + const { codeChanged } = checkCodeChanged(meta.artifact, addressBook, entryName) const result = formatProxyStatusLine({ name: contractName, diff --git a/packages/deployment/rocketh/config.ts b/packages/deployment/rocketh/config.ts index 44bcb4fd6..c9cfffdc5 100644 --- a/packages/deployment/rocketh/config.ts +++ b/packages/deployment/rocketh/config.ts @@ -33,6 +33,14 @@ const hardhatLocalChain: ChainInfo = { testnet: true, } +const graphLocalNetworkChain: ChainInfo = { + id: 1337, + name: 'Graph Local Network', + nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 }, + rpcUrls: { default: { http: ['http://chain:8545'] } }, + testnet: true, +} + const arbitrumSepoliaChain: ChainInfo = { id: 421614, name: 'Arbitrum Sepolia', @@ -58,6 +66,7 @@ export const config: UserConfig = { deployments: 'deployments', scripts: ['deploy'], chains: { + 1337: { info: graphLocalNetworkChain }, 31337: { info: hardhatLocalChain }, 421614: { info: arbitrumSepoliaChain }, 42161: { info: arbitrumOneChain }, @@ -68,6 +77,7 @@ export const config: UserConfig = { hardhat: { chain: 31337 }, localhost: { chain: 31337 }, fork: { chain: 31337 }, + localNetwork: { chain: 1337 }, arbitrumSepolia: { chain: 421614 }, arbitrumOne: { chain: 42161 }, }, diff --git a/packages/deployment/scripts/check-bytecode.ts b/packages/deployment/scripts/check-bytecode.ts new file mode 100644 index 000000000..9d9178b2a --- /dev/null +++ b/packages/deployment/scripts/check-bytecode.ts @@ -0,0 +1,54 @@ +import { createPublicClient, http } from 'viem' + +import { loadSubgraphServiceArtifact } from '../lib/artifact-loaders.js' +import { computeBytecodeHash } from '../lib/bytecode-utils.js' +import { graph } from '../rocketh/deploy.js' + +async function main() { + const chainId = 421614 // arbitrumSepolia + + // Get address book + const addressBook = graph.getSubgraphServiceAddressBook(chainId) + const entry = addressBook.getEntry('SubgraphService') + const deploymentMetadata = addressBook.getDeploymentMetadata('SubgraphService') + + console.log('\nšŸ“‹ SubgraphService Bytecode Analysis\n') + console.log('Proxy address:', entry.address) + console.log('Current implementation:', entry.implementation) + console.log('Pending implementation:', entry.pendingImplementation?.address ?? 'none') + + // Get local artifact + const artifact = loadSubgraphServiceArtifact('SubgraphService') + const localHash = computeBytecodeHash(artifact.deployedBytecode ?? '0x') + console.log('\nLocal artifact bytecode hash:', localHash) + + // Get address book stored hash + console.log('Address book stored hash:', deploymentMetadata?.bytecodeHash ?? '(none)') + + // Get on-chain bytecode + const client = createPublicClient({ + transport: http('https://sepolia-rollup.arbitrum.io/rpc'), + }) + + const onChainBytecode = await client.getCode({ + address: entry.implementation as `0x${string}`, + }) + + if (onChainBytecode && onChainBytecode !== '0x') { + const onChainHash = computeBytecodeHash(onChainBytecode) + console.log('On-chain implementation hash:', onChainHash) + + console.log('\nšŸ” Comparison:') + console.log( + 'Local vs Address Book:', + localHash === (deploymentMetadata?.bytecodeHash ?? '') ? 'āœ“ MATCH' : 'āœ— DIFFERENT', + ) + console.log('Local vs On-chain:', localHash === onChainHash ? 'āœ“ MATCH' : 'āœ— DIFFERENT') + console.log( + 'Address Book vs On-chain:', + (deploymentMetadata?.bytecodeHash ?? '') === onChainHash ? 'āœ“ MATCH' : 'āœ— DIFFERENT (or missing)', + ) + } +} + +main().catch(console.error) diff --git a/packages/deployment/scripts/check-rocketh-bytecode.ts b/packages/deployment/scripts/check-rocketh-bytecode.ts new file mode 100644 index 000000000..aff8f394a --- /dev/null +++ b/packages/deployment/scripts/check-rocketh-bytecode.ts @@ -0,0 +1,34 @@ +import { readFileSync } from 'fs' + +import { loadSubgraphServiceArtifact } from '../lib/artifact-loaders.js' +import { computeBytecodeHash } from '../lib/bytecode-utils.js' + +async function main() { + console.log('\nšŸ“‹ Rocketh vs Local Artifact Comparison\n') + + // Get local artifact + const artifact = loadSubgraphServiceArtifact('SubgraphService') + const localHash = computeBytecodeHash(artifact.deployedBytecode ?? '0x') + console.log('Local artifact hash:', localHash) + + // Check rocketh stored bytecode + try { + const rockethPath = '.rocketh/deployments/arbitrumSepolia/SubgraphService_Implementation.json' + const rockethData = JSON.parse(readFileSync(rockethPath, 'utf-8')) + + if (rockethData.deployedBytecode) { + const rockethHash = computeBytecodeHash(rockethData.deployedBytecode) + console.log('Rocketh stored hash:', rockethHash) + console.log( + '\nComparison:', + localHash === rockethHash ? 'āœ“ MATCH (deploy will skip)' : 'āœ— DIFFERENT (deploy will redeploy)', + ) + } else { + console.log('Rocketh stored hash: (no deployedBytecode)') + } + } catch { + console.log('Rocketh record:', 'not found') + } +} + +main().catch(console.error) diff --git a/packages/deployment/scripts/debug-deploy-state.ts b/packages/deployment/scripts/debug-deploy-state.ts new file mode 100644 index 000000000..6267734f2 --- /dev/null +++ b/packages/deployment/scripts/debug-deploy-state.ts @@ -0,0 +1,27 @@ +import { loadSubgraphServiceArtifact } from '../lib/artifact-loaders.js' +import { computeBytecodeHash } from '../lib/bytecode-utils.js' + +async function main() { + console.log('\nšŸ“‹ Investigating Deploy "Unchanged" Message\n') + + // The deploy script checks env.getOrNull('SubgraphService_Implementation') + // But rocketh state is in-memory during deploy runs + // We can't easily check that without running deploy + + // What we CAN check is: + // 1. If sync step would have synced the implementation + // 2. The actual bytecode hashes + + const artifact = loadSubgraphServiceArtifact('SubgraphService') + const localHash = computeBytecodeHash(artifact.deployedBytecode ?? '0x') + + console.log('Local artifact bytecode hash:', localHash) + console.log('\nāš ļø The issue:') + console.log('1. Sync shows "code changed" because address book has different/missing hash') + console.log('2. Deploy says "unchanged" - this suggests rocketh has the implementation') + console.log('3. But local bytecode IS different from on-chain') + console.log('\nThis means deploy will NOT deploy the new implementation!') + console.log('The local changes will be ignored.\n') +} + +main().catch(console.error) diff --git a/packages/deployment/scripts/tag-deployment.sh b/packages/deployment/scripts/tag-deployment.sh new file mode 100755 index 000000000..3c13b3651 --- /dev/null +++ b/packages/deployment/scripts/tag-deployment.sh @@ -0,0 +1,272 @@ +#!/usr/bin/env bash +# +# tag-deployment.sh - Create annotated git tag for a contract deployment +# +# Usage: +# ./scripts/tag-deployment.sh --deployer --network [options] +# +# Options: +# --deployer What performed the deployment (free-form, e.g., "packages/deployment --tags rewards-manager") +# --network Network: arbitrumOne or arbitrumSepolia +# --base Git ref to diff against (default: HEAD~1) +# --dry-run Preview tag without creating it +# --sign Force-sign the tag with -s +# --help Show this help +# +set -euo pipefail + +# --- Dependencies --- +for cmd in git jq; do + if ! command -v "$cmd" >/dev/null 2>&1; then + echo "Error: $cmd is required but not found" + exit 1 + fi +done + +REPO_ROOT="$(git rev-parse --show-toplevel)" + +# --- Defaults --- +DEPLOYER="" +NETWORK="" +BASE_REF="HEAD~1" +DRY_RUN=false +SIGN_FLAG="-a" + +# --- Address books managed by packages/deployment --- +ADDRESS_BOOKS=( + "packages/horizon/addresses.json:horizon" + "packages/subgraph-service/addresses.json:subgraph-service" + "packages/issuance/addresses.json:issuance" +) + +# --- Network to chain ID / label mapping --- +network_to_chain_id() { + case "$1" in + arbitrumOne) echo "42161" ;; + arbitrumSepolia) echo "421614" ;; + *) echo "unknown" ;; + esac +} + +network_to_label() { + case "$1" in + arbitrumOne) echo "mainnet" ;; + arbitrumSepolia) echo "testnet" ;; + *) echo "unknown" ;; + esac +} + +network_to_display() { + case "$1" in + arbitrumOne) echo "arbitrum-one" ;; + arbitrumSepolia) echo "arbitrum-sepolia" ;; + *) echo "$1" ;; + esac +} + +# --- Parse arguments --- +usage() { + sed -n '3,14p' "$0" | sed 's/^# \?//' + exit "${1:-0}" +} + +while [[ $# -gt 0 ]]; do + case "$1" in + --deployer) DEPLOYER="$2"; shift 2 ;; + --network) NETWORK="$2"; shift 2 ;; + --base) BASE_REF="$2"; shift 2 ;; + --dry-run) DRY_RUN=true; shift ;; + --sign) SIGN_FLAG="-s"; shift ;; + --help) usage 0 ;; + *) echo "Unknown option: $1"; usage 1 ;; + esac +done + +if [[ -z "$DEPLOYER" ]]; then + echo "Error: --deployer is required" + usage 1 +fi + +if [[ -z "$NETWORK" ]]; then + echo "Error: --network is required" + usage 1 +fi + +CHAIN_ID="$(network_to_chain_id "$NETWORK")" +LABEL="$(network_to_label "$NETWORK")" +DISPLAY="$(network_to_display "$NETWORK")" + +if [[ "$CHAIN_ID" == "unknown" ]]; then + echo "Error: unknown network '$NETWORK' (expected arbitrumOne or arbitrumSepolia)" + exit 1 +fi + +# --- Preconditions --- +if [[ -n "$(git status --porcelain)" ]]; then + echo "Error: working tree is not clean. Commit or stash changes first." + echo " (Tag must point to a finalized commit)" + exit 1 +fi + +COMMIT_SHA="$(git rev-parse HEAD)" +COMMIT_SHORT="$(git rev-parse --short HEAD)" + +# Check if commit is signed (informational) +if ! git log -1 --format='%G?' HEAD | grep -q '[GU]'; then + echo "Warning: HEAD commit ($COMMIT_SHORT) is not signed" +fi + +# Verify base ref exists +if ! git rev-parse --verify "$BASE_REF" >/dev/null 2>&1; then + echo "Error: base ref '$BASE_REF' does not exist" + exit 1 +fi + +# --- Detect changed contracts per address book --- +collect_changes() { + local book_path="$1" + local chain_id="$2" + local base_ref="$3" + # Get the file at base ref and at HEAD (both via git, not filesystem) + local base_json head_json + base_json="$(git show "$base_ref:$book_path" 2>/dev/null || echo '{}')" + head_json="$(git show "HEAD:$book_path" 2>/dev/null || echo '{}')" + + if [[ "$head_json" == '{}' ]]; then + return + fi + + # Extract contract names for this chain at base and head + local base_contracts head_contracts + base_contracts="$(echo "$base_json" | jq -r --arg cid "$chain_id" '.[$cid] // {} | keys[]' 2>/dev/null || true)" + head_contracts="$(echo "$head_json" | jq -r --arg cid "$chain_id" '.[$cid] // {} | keys[]' 2>/dev/null || true)" + + # Find contracts that are new or changed + local all_contracts + all_contracts="$(echo -e "${base_contracts}\n${head_contracts}" | sort -u | grep -v '^$' || true)" + + for contract in $all_contracts; do + local base_entry head_entry + base_entry="$(echo "$base_json" | jq -c --arg cid "$chain_id" --arg c "$contract" '.[$cid][$c] // empty' 2>/dev/null || true)" + head_entry="$(echo "$head_json" | jq -c --arg cid "$chain_id" --arg c "$contract" '.[$cid][$c] // empty' 2>/dev/null || true)" + + if [[ "$base_entry" != "$head_entry" ]]; then + # Contract changed - extract key details + local impl addr change_type + addr="$(echo "$head_json" | jq -r --arg cid "$chain_id" --arg c "$contract" '.[$cid][$c].address // empty' 2>/dev/null || true)" + impl="$(echo "$head_json" | jq -r --arg cid "$chain_id" --arg c "$contract" '.[$cid][$c].implementation // empty' 2>/dev/null || true)" + + if [[ -z "$base_entry" ]]; then + change_type="new" + elif [[ -z "$head_entry" ]]; then + change_type="removed" + else + change_type="updated" + fi + + local detail="" + if [[ -n "$impl" ]]; then + detail="implementation: ${impl}" + elif [[ -n "$addr" ]]; then + detail="address: ${addr}" + fi + + echo "${change_type}|${contract}|${detail}" + fi + done +} + +# Collect all changes grouped by address book +declare -A BOOK_CHANGES +has_changes=false + +for entry in "${ADDRESS_BOOKS[@]}"; do + book_path="${entry%%:*}" + book_name="${entry##*:}" + + changes="$(collect_changes "$book_path" "$CHAIN_ID" "$BASE_REF")" + if [[ -n "$changes" ]]; then + BOOK_CHANGES["$book_name"]="$changes" + has_changes=true + fi +done + +if [[ "$has_changes" == false ]]; then + echo "No address book changes detected for chain $CHAIN_ID between $BASE_REF and HEAD" + echo " Checked:" + for entry in "${ADDRESS_BOOKS[@]}"; do + echo " ${entry%%:*}" + done + exit 1 +fi + +# --- Generate tag name --- +TAG_DATE="$(date +%Y-%m-%d)" +TAG_BASE="deploy/${LABEL}/${TAG_DATE}" +TAG_NAME="$TAG_BASE" + +# Handle suffix for multiple deploys per day +if git tag -l "$TAG_NAME" | grep -q .; then + for suffix in b c d e f; do + candidate="${TAG_BASE}-${suffix}" + if ! git tag -l "$candidate" | grep -q .; then + TAG_NAME="$candidate" + break + fi + done + if [[ "$TAG_NAME" == "$TAG_BASE" ]]; then + echo "Error: too many deployment tags for $TAG_DATE" + exit 1 + fi +fi + +# --- Build annotation --- +ANNOTATION="network: ${DISPLAY} (${CHAIN_ID}) +deployed-by: ${DEPLOYER} +commit: ${COMMIT_SHA}" + +for book_name in $(echo "${!BOOK_CHANGES[@]}" | tr ' ' '\n' | sort); do + changes="${BOOK_CHANGES[$book_name]}" + ANNOTATION="${ANNOTATION} + +contracts (${book_name}):" + + while IFS='|' read -r change_type contract detail; do + local_line=" - ${contract}" + if [[ -n "$detail" ]]; then + local_line="${local_line} (${detail})" + fi + if [[ "$change_type" == "new" ]]; then + local_line="${local_line} [new]" + elif [[ "$change_type" == "removed" ]]; then + local_line="${local_line} [removed]" + fi + ANNOTATION="${ANNOTATION} +${local_line}" + done <<< "$changes" +done + +# --- Create or preview tag --- +echo "" +echo "--- Deployment Tag ---" +echo "Tag: ${TAG_NAME}" +echo "Commit: ${COMMIT_SHORT} ($(git log -1 --format='%s' HEAD))" +echo "" +echo "$ANNOTATION" +echo "----------------------" +echo "" + +if [[ "$DRY_RUN" == true ]]; then + echo "[dry-run] Tag not created" + exit 0 +fi + +MSG_FILE="$(mktemp)" +trap 'rm -f "$MSG_FILE"' EXIT +printf '%s\n' "$ANNOTATION" > "$MSG_FILE" +git tag "$SIGN_FLAG" "$TAG_NAME" -F "$MSG_FILE" + +echo "Tag created: ${TAG_NAME}" +echo "" +echo "To push: git push origin ${TAG_NAME}" +echo "To view: git show ${TAG_NAME}" diff --git a/packages/deployment/tasks/deployment-status.ts b/packages/deployment/tasks/deployment-status.ts index 7bf9061c0..f68c0b4b0 100644 --- a/packages/deployment/tasks/deployment-status.ts +++ b/packages/deployment/tasks/deployment-status.ts @@ -1,7 +1,7 @@ import { task } from 'hardhat/config' import { ArgumentType } from 'hardhat/types/arguments' import type { NewTaskActionFunction } from 'hardhat/types/tasks' -import { createPublicClient, custom, type PublicClient } from 'viem' +import { createPublicClient, custom, http, type PublicClient } from 'viem' import { IISSUANCE_TARGET_INTERFACE_ID, @@ -48,24 +48,70 @@ const action: NewTaskActionFunction = async (taskArgs, hre) => { const networkName = conn.networkName const packageFilter = taskArgs.package.toLowerCase() + // Get configured chain ID from network config (always available) + const configuredChainId = conn.networkConfig?.chainId as number | undefined + + // Default RPC URLs for read-only access (no accounts needed) + const DEFAULT_RPC_URLS: Record = { + arbitrumOne: 'https://arb1.arbitrum.io/rpc', + arbitrumSepolia: 'https://sepolia-rollup.arbitrum.io/rpc', + } + + // Get RPC URL: prefer env var, then default + const envRpcUrl = + networkName === 'arbitrumSepolia' + ? process.env.ARBITRUM_SEPOLIA_RPC + : networkName === 'arbitrumOne' + ? process.env.ARBITRUM_ONE_RPC + : undefined + const rpcUrl = envRpcUrl || DEFAULT_RPC_URLS[networkName] + // Get viem public client for on-chain checks + // Use direct HTTP transport to RPC URL (bypasses Hardhat's account resolution) let client: PublicClient | undefined let actualChainId: number | undefined - try { - if (conn.provider) { + let providerError: string | undefined + + if (rpcUrl) { + // Create read-only client directly to RPC (no accounts needed) + try { client = createPublicClient({ - transport: custom(conn.provider), + transport: http(rpcUrl), }) as PublicClient actualChainId = await client.getChainId() + } catch (e) { + client = undefined + const errMsg = e instanceof Error ? e.message : String(e) + providerError = errMsg.split('\n')[0] + } + } else { + // No RPC URL available - try Hardhat's provider (may fail if accounts not configured) + try { + if (conn.provider) { + client = createPublicClient({ + transport: custom(conn.provider), + }) as PublicClient + actualChainId = await client.getChainId() + } + } catch (e) { + // Provider failed - disable on-chain checks + client = undefined + + // Extract error message (may be nested in viem error or cause chain) + let errMsg = e instanceof Error ? e.message : String(e) + const cause = e instanceof Error ? (e as Error & { cause?: Error }).cause : undefined + if (cause?.message) { + errMsg = cause.message + } + + providerError = errMsg.split('\n')[0] } - } catch { - // Provider not available } - // Determine target chain ID: use actual chain ID when not in fork mode + // Determine target chain ID: use fork target, then configured, then actual, then fallback const forkChainId = graph.getForkTargetChainId() const isForkMode = forkChainId !== null - const targetChainId = forkChainId ?? actualChainId ?? 31337 + const targetChainId = forkChainId ?? configuredChainId ?? actualChainId ?? 31337 // Show status header with chain info if (isForkMode) { @@ -75,7 +121,13 @@ const action: NewTaskActionFunction = async (taskArgs, hre) => { console.log(`āš ļø Warning: Connected chain (${actualChainId}) differs from target (${targetChainId})`) console.log(` Address book lookups use chainId ${targetChainId}\n`) } else { - console.log(`\nšŸ” Status: ${networkName} (chainId: ${actualChainId ?? targetChainId})\n`) + console.log(`\nšŸ” Status: ${networkName} (chainId: ${targetChainId})\n`) + } + + // Show provider warning if we couldn't connect (but continue with address book lookups) + if (providerError) { + console.log(`āš ļø Provider unavailable: ${providerError}`) + console.log(` On-chain checks disabled. Set the missing variable or use --network hardhat for local testing.\n`) } // Get address books diff --git a/packages/deployment/tasks/reo-tasks.ts b/packages/deployment/tasks/reo-tasks.ts new file mode 100644 index 000000000..a07659ce4 --- /dev/null +++ b/packages/deployment/tasks/reo-tasks.ts @@ -0,0 +1,394 @@ +import { configVariable, task } from 'hardhat/config' +import type { NewTaskActionFunction } from 'hardhat/types/tasks' +import { + createPublicClient, + createWalletClient, + custom, + encodeFunctionData, + type PublicClient, + type WalletClient, +} from 'viem' +import { privateKeyToAccount } from 'viem/accounts' + +import { REWARDS_ELIGIBILITY_ORACLE_ABI } from '../lib/abis.js' +import { accountHasRole, enumerateContractRoles, getRoleHash } from '../lib/contract-checks.js' +import { createGovernanceTxBuilder } from '../lib/execute-governance.js' +import { graph } from '../rocketh/deploy.js' + +// -- Shared Utilities -- + +/** + * Convert network name to env var prefix: arbitrumSepolia ā†’ ARBITRUM_SEPOLIA + */ +function networkToEnvPrefix(networkName: string): string { + return networkName.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase() +} + +/** + * Resolve a configuration variable using Hardhat's hook chain (keystore + env fallback) + */ +async function resolveConfigVar(hre: unknown, name: string): Promise { + try { + const variable = configVariable(name) + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const hooks = (hre as any).hooks + + const value = await hooks.runHandlerChain( + 'configurationVariables', + 'fetchValue', + [variable], + async (_context: unknown, v: { name: string }) => { + const envValue = process.env[v.name] + if (typeof envValue !== 'string') { + throw new Error(`Variable ${v.name} not found`) + } + return envValue + }, + ) + return value + } catch { + return undefined + } +} + +/** + * Get RewardsEligibilityOracle address from issuance address book + */ +function getREOAddress(chainId: number): string | null { + const book = graph.getIssuanceAddressBook(chainId) + if (!book.entryExists('RewardsEligibilityOracle')) { + return null + } + return book.getEntry('RewardsEligibilityOracle')?.address ?? null +} + +/** + * Format duration in seconds to human-readable string + */ +function formatDuration(seconds: bigint): string { + const days = seconds / 86400n + const hours = (seconds % 86400n) / 3600n + const mins = (seconds % 3600n) / 60n + + if (days > 0n) { + return `${days}d ${hours}h ${mins}m` + } else if (hours > 0n) { + return `${hours}h ${mins}m` + } else { + return `${mins}m` + } +} + +/** + * Format timestamp to human-readable string with time ago + */ +function formatTimestamp(timestamp: bigint): string { + if (timestamp === 0n) { + return 'never' + } + + const date = new Date(Number(timestamp) * 1000) + const now = BigInt(Math.floor(Date.now() / 1000)) + const ago = now - timestamp + + return `${date.toISOString()} (${formatDuration(ago)} ago)` +} + +// -- Enable/Disable Shared Logic -- + +interface SetValidationArgs { + enabled: boolean + hre: unknown +} + +async function setEligibilityValidation({ enabled, hre }: SetValidationArgs): Promise { + const action = enabled ? 'Enable' : 'Disable' + const actionLower = enabled ? 'enable' : 'disable' + + // Connect to network + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const conn = await (hre as any).network.connect() + const networkName = conn.networkName + + // Create viem client + const client = createPublicClient({ + transport: custom(conn.provider), + }) as PublicClient + + const actualChainId = await client.getChainId() + const forkChainId = graph.getForkTargetChainId() + const targetChainId = forkChainId ?? actualChainId + + // Get REO address + const reoAddress = getREOAddress(targetChainId) + if (!reoAddress) { + console.error(`\nError: RewardsEligibilityOracle not found in address book for chain ${targetChainId}`) + return + } + + // Check current state + const currentState = (await client.readContract({ + address: reoAddress as `0x${string}`, + abi: REWARDS_ELIGIBILITY_ORACLE_ABI, + functionName: 'getEligibilityValidation', + })) as boolean + + if (currentState === enabled) { + console.log(`\nāœ“ Eligibility validation already ${actionLower}d`) + console.log(' No action needed.\n') + return + } + + // Get OPERATOR_ROLE hash + const operatorRoleHash = await getRoleHash(client, reoAddress, 'OPERATOR_ROLE') + if (!operatorRoleHash) { + console.error('\nError: Could not read OPERATOR_ROLE from contract') + return + } + + console.log(`\nšŸ”§ ${action} Eligibility Validation`) + console.log(` Contract: ${reoAddress}`) + console.log(` Network: ${networkName} (chainId: ${targetChainId})`) + console.log(` Current: ${currentState ? 'enabled' : 'disabled'}`) + console.log(` Target: ${enabled ? 'enabled' : 'disabled'}`) + + // Get deployer account (from keystore or env var) + const keyName = `${networkToEnvPrefix(networkName === 'fork' ? (process.env.HARDHAT_FORK ?? 'arbitrumSepolia') : networkName)}_DEPLOYER_KEY` + const deployerKey = await resolveConfigVar(hre, keyName) + + let deployer: string | undefined + let walletClient: WalletClient | undefined + + if (deployerKey) { + const account = privateKeyToAccount(deployerKey as `0x${string}`) + deployer = account.address + walletClient = createWalletClient({ + account, + transport: custom(conn.provider), + }) + } + + // Check if deployer has OPERATOR_ROLE + const canExecuteDirectly = deployer ? await accountHasRole(client, reoAddress, operatorRoleHash, deployer) : false + + if (canExecuteDirectly && walletClient && deployer) { + console.log(`\n Deployer has OPERATOR_ROLE, executing directly...`) + + // Execute directly + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const hash = await (walletClient as any).writeContract({ + address: reoAddress as `0x${string}`, + abi: REWARDS_ELIGIBILITY_ORACLE_ABI, + functionName: 'setEligibilityValidation', + args: [enabled], + }) + + console.log(` TX: ${hash}`) + + // Wait for confirmation + const receipt = await client.waitForTransactionReceipt({ hash }) + if (receipt.status === 'success') { + console.log(`\nāœ“ Eligibility validation ${actionLower}d successfully\n`) + } else { + console.error(`\nāœ— Transaction failed\n`) + } + } else { + // Generate governance TX + console.log(`\n Requires OPERATOR_ROLE to ${actionLower}`) + console.log(' Generating governance TX...') + + // Create a minimal environment for the TxBuilder + const env = { + name: networkName, + network: { provider: conn.provider }, + showMessage: console.log, + } + + const txName = `reo-${actionLower}-validation` + const builder = await createGovernanceTxBuilder(env as Parameters[0], txName, { + name: `${action} REO Validation`, + description: `${action} eligibility validation on RewardsEligibilityOracle`, + }) + + // Encode the setEligibilityValidation call + const data = encodeFunctionData({ + abi: REWARDS_ELIGIBILITY_ORACLE_ABI, + functionName: 'setEligibilityValidation', + args: [enabled], + }) + + builder.addTx({ + to: reoAddress, + data, + value: '0', + }) + + const txFile = builder.saveToFile() + console.log(`\nāœ“ Governance TX saved: ${txFile}`) + console.log('\nNext steps:') + console.log(' ā€¢ Fork testing: npx hardhat deploy:execute-governance --network fork') + console.log(' ā€¢ Safe multisig: Upload JSON to Transaction Builder') + console.log('') + } +} + +// -- Types -- + +interface TaskArgs { + // No arguments for these tasks +} + +// -- Task Actions -- + +const enableAction: NewTaskActionFunction = async (_taskArgs, hre) => { + await setEligibilityValidation({ enabled: true, hre }) +} + +const disableAction: NewTaskActionFunction = async (_taskArgs, hre) => { + await setEligibilityValidation({ enabled: false, hre }) +} + +const statusAction: NewTaskActionFunction = async (_taskArgs, hre) => { + // Connect to network + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const conn = await (hre as any).network.connect() + const networkName = conn.networkName + + // Create viem client + const client = createPublicClient({ + transport: custom(conn.provider), + }) as PublicClient + + const actualChainId = await client.getChainId() + const forkChainId = graph.getForkTargetChainId() + const targetChainId = forkChainId ?? actualChainId + + // Get REO address + const reoAddress = getREOAddress(targetChainId) + if (!reoAddress) { + console.error(`\nError: RewardsEligibilityOracle not found in address book for chain ${targetChainId}`) + return + } + + console.log(`\nšŸ“Š RewardsEligibilityOracle Status`) + console.log(` Address: ${reoAddress}`) + console.log(` Network: ${networkName} (chainId: ${targetChainId})`) + + // Read all status values + const [validationEnabled, eligibilityPeriod, oracleUpdateTimeout, lastOracleUpdateTime] = await Promise.all([ + client.readContract({ + address: reoAddress as `0x${string}`, + abi: REWARDS_ELIGIBILITY_ORACLE_ABI, + functionName: 'getEligibilityValidation', + }) as Promise, + client.readContract({ + address: reoAddress as `0x${string}`, + abi: REWARDS_ELIGIBILITY_ORACLE_ABI, + functionName: 'getEligibilityPeriod', + }) as Promise, + client.readContract({ + address: reoAddress as `0x${string}`, + abi: REWARDS_ELIGIBILITY_ORACLE_ABI, + functionName: 'getOracleUpdateTimeout', + }) as Promise, + client.readContract({ + address: reoAddress as `0x${string}`, + abi: REWARDS_ELIGIBILITY_ORACLE_ABI, + functionName: 'getLastOracleUpdateTime', + }) as Promise, + ]) + + // Calculate derived states + const now = BigInt(Math.floor(Date.now() / 1000)) + const timeSinceLastUpdate = lastOracleUpdateTime > 0n ? now - lastOracleUpdateTime : null + const timeoutExceeded = timeSinceLastUpdate !== null && timeSinceLastUpdate > oracleUpdateTimeout + const effectivelyDisabled = !validationEnabled || timeoutExceeded + + // Configuration section + console.log(`\nšŸ”§ Configuration`) + console.log(` Validation enabled: ${validationEnabled ? 'āœ“ yes' : 'āœ— no'}`) + console.log(` Eligibility period: ${formatDuration(eligibilityPeriod)} (${eligibilityPeriod} seconds)`) + console.log(` Oracle timeout: ${formatDuration(oracleUpdateTimeout)} (${oracleUpdateTimeout} seconds)`) + + // Oracle activity section + console.log(`\nšŸ“” Oracle Activity`) + console.log(` Last update: ${formatTimestamp(lastOracleUpdateTime)}`) + if (timeSinceLastUpdate === null) { + console.log(` āš ļø No oracle updates yet`) + } else if (timeoutExceeded) { + console.log(` āš ļø Timeout exceeded! All indexers treated as eligible (fail-safe active)`) + } + + // Effective state section + console.log(`\nšŸŽÆ Effective State`) + if (effectivelyDisabled) { + console.log(` Status: āœ— DISABLED (all indexers eligible)`) + if (!validationEnabled) { + console.log(` Reason: Validation toggle is off`) + } else if (timeoutExceeded) { + console.log(` Reason: Oracle timeout exceeded (fail-safe)`) + } + } else { + console.log(` Status: āœ“ ACTIVE (enforcing eligibility)`) + } + + // Role holders section + console.log(`\nšŸ” Role Holders`) + const knownRoles = ['GOVERNOR_ROLE', 'PAUSE_ROLE', 'OPERATOR_ROLE', 'ORACLE_ROLE'] + const result = await enumerateContractRoles(client, reoAddress, knownRoles) + + for (const role of result.roles) { + const memberList = role.members.length > 0 ? role.members.join(', ') : '(none)' + console.log(` ${role.name} (${role.memberCount}): ${memberList}`) + } + + if (result.failedRoles.length > 0) { + console.log(` āš ļø Failed to read: ${result.failedRoles.join(', ')}`) + } + + console.log() +} + +// -- Task Definitions -- + +/** + * Enable eligibility validation on RewardsEligibilityOracle + * + * Requires OPERATOR_ROLE. If deployer has the role, executes directly. + * Otherwise generates a governance TX for multisig execution. + * + * Examples: + * npx hardhat reo:enable --network arbitrumSepolia + */ +export const reoEnableTask = task('reo:enable', 'Enable eligibility validation on RewardsEligibilityOracle') + .setAction(async () => ({ default: enableAction })) + .build() + +/** + * Disable eligibility validation on RewardsEligibilityOracle + * + * Requires OPERATOR_ROLE. If deployer has the role, executes directly. + * Otherwise generates a governance TX for multisig execution. + * + * WARNING: When validation is disabled, ALL indexers are treated as eligible. + * + * Examples: + * npx hardhat reo:disable --network arbitrumSepolia + */ +export const reoDisableTask = task('reo:disable', 'Disable eligibility validation on RewardsEligibilityOracle') + .setAction(async () => ({ default: disableAction })) + .build() + +/** + * Show detailed status of RewardsEligibilityOracle + * + * Displays configuration, oracle activity, effective state, and role holders. + * + * Examples: + * npx hardhat reo:status --network arbitrumSepolia + */ +export const reoStatusTask = task('reo:status', 'Show detailed RewardsEligibilityOracle status') + .setAction(async () => ({ default: statusAction })) + .build() + +export default [reoEnableTask, reoDisableTask, reoStatusTask] diff --git a/packages/deployment/tasks/verify-contract.ts b/packages/deployment/tasks/verify-contract.ts index 793f921f3..3a7ad40b5 100644 --- a/packages/deployment/tasks/verify-contract.ts +++ b/packages/deployment/tasks/verify-contract.ts @@ -534,7 +534,10 @@ const action: NewTaskActionFunction = async (taskArgs, hre) => { // Get API key from keystore const apiKey = await resolveConfigVar(hre, 'ARBISCAN_API_KEY') if (!apiKey) { - throw new Error('ARBISCAN_API_KEY not found. Set it in keystore:\n npx hardhat keystore set ARBISCAN_API_KEY') + console.error('\nError: No Arbiscan API key configured.') + console.error('Set via keystore: npx hardhat keystore set ARBISCAN_API_KEY') + console.error('Or environment: export ARBISCAN_API_KEY=...\n') + return } // Determine contracts to verify diff --git a/packages/toolshed/src/hardhat/hardhat.base.config.ts b/packages/toolshed/src/hardhat/hardhat.base.config.ts index a97f9d29c..702484fdc 100644 --- a/packages/toolshed/src/hardhat/hardhat.base.config.ts +++ b/packages/toolshed/src/hardhat/hardhat.base.config.ts @@ -58,8 +58,15 @@ export const projectPathsUserConfig: ProjectPathsUserConfig = { // Etherscan v2 API uses a single API key for all networks // See: https://docs.etherscan.io/etherscan-v2/getting-started/creating-an-account +// Check keystore first (vars), then environment variables +// Support both ETHERSCAN_API_KEY and ARBISCAN_API_KEY for compatibility +const getEtherscanApiKey = (): string => { + if (vars.has('ETHERSCAN_API_KEY')) return vars.get('ETHERSCAN_API_KEY') + if (vars.has('ARBISCAN_API_KEY')) return vars.get('ARBISCAN_API_KEY') + return process.env.ETHERSCAN_API_KEY ?? process.env.ARBISCAN_API_KEY ?? '' +} export const etherscanUserConfig: Partial = { - apiKey: vars.has('ETHERSCAN_API_KEY') ? vars.get('ETHERSCAN_API_KEY') : '', + apiKey: getEtherscanApiKey(), } // In general: From 92d44dac584d6f7af9b1a08a4084604022a8c21d Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Mon, 23 Feb 2026 09:49:40 +0000 Subject: [PATCH 02/12] docs: REO testing plans, guides, and rewards documentation --- docs/RewardsBehaviourChanges.md | 175 +++ packages/deployment/docs/LocalForkTesting.md | 2 + .../docs/SyncBytecodeDetectionFix.md | 15 +- .../docs/testing/reo/BaselineTestPlan.md | 827 ++++++++++++ .../docs/testing/reo/IndexerTestGuide.md | 542 ++++++++ packages/issuance/docs/testing/reo/README.md | 168 +++ .../issuance/docs/testing/reo/ReoTestPlan.md | 1103 +++++++++++++++++ .../testing/reo/RewardsConditionsTestPlan.md | 781 ++++++++++++ .../testing/reo/SubgraphDenialTestPlan.md | 680 ++++++++++ .../reo/support/IssuanceAllocatorTestPlan.md | 98 ++ .../docs/testing/reo/support/NotionSetup.md | 70 ++ .../testing/reo/support/NotionTracker.csv | 77 ++ 12 files changed, 4536 insertions(+), 2 deletions(-) create mode 100644 docs/RewardsBehaviourChanges.md create mode 100644 packages/issuance/docs/testing/reo/BaselineTestPlan.md create mode 100644 packages/issuance/docs/testing/reo/IndexerTestGuide.md create mode 100644 packages/issuance/docs/testing/reo/README.md create mode 100644 packages/issuance/docs/testing/reo/ReoTestPlan.md create mode 100644 packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md create mode 100644 packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md create mode 100644 packages/issuance/docs/testing/reo/support/IssuanceAllocatorTestPlan.md create mode 100644 packages/issuance/docs/testing/reo/support/NotionSetup.md create mode 100644 packages/issuance/docs/testing/reo/support/NotionTracker.csv diff --git a/docs/RewardsBehaviourChanges.md b/docs/RewardsBehaviourChanges.md new file mode 100644 index 000000000..63c17c4c2 --- /dev/null +++ b/docs/RewardsBehaviourChanges.md @@ -0,0 +1,175 @@ +# Rewards Behaviour Changes + +Functional summary of how reward behaviour changed between the Horizon mainnet baseline and the current issuance upgrade. + +## Activation Overview + +Changes fall into two categories: + +- **Automatic on upgrade:** New logic that activates immediately when the upgraded contracts are deployed behind their proxies. No governance action required. These include: zero-signal detection, zero-allocated-tokens reclaim, POI presentation paths (claim/reclaim/defer), allocation resize staleness check, allocation close reclaim, and the `POIPresented` event. + +- **Governance-gated:** Features that require explicit governance transactions after upgrade. Until configured, the system preserves legacy behaviour (rewards are dropped, not reclaimed). These include: setting the issuance allocator, configuring reclaim addresses (per-condition and default), setting the eligibility oracle, and changing the minimum subgraph signal threshold. + +This two-phase approach allows a safe upgrade with the new infrastructure in place, while governance coordinates separate activation steps for each optional feature. + +## Issuance Rate + +**Before:** A single `issuancePerBlock` storage variable, set by governance via `setIssuancePerBlock()`, determined all reward issuance. + +**After:** An optional `issuanceAllocator` contract can be set by governance. When set, the effective issuance rate comes from the allocator (which can distribute issuance across multiple targets). When unset, the legacy `issuancePerBlock` value is used as a fallback. The allocator calls `beforeIssuanceAllocationChange()` on the RewardsManager before changing rates, ensuring accumulators are snapshotted first. + +**Activates:** Governance-gated ā€” requires `setIssuanceAllocator()`. Until called, the legacy `issuancePerBlock` value continues to apply. + +## Reward Conditions + +A new `RewardsCondition` library defines typed `bytes32` identifiers for every situation where rewards cannot be distributed normally: + +| Condition | Trigger | +| ---------------------- | ---------------------------------------------------- | +| `NO_SIGNAL` | Zero total curation signal globally | +| `SUBGRAPH_DENIED` | Subgraph is on the denylist | +| `BELOW_MINIMUM_SIGNAL` | Subgraph signal below `minimumSubgraphSignal` | +| `NO_ALLOCATED_TOKENS` | Subgraph has signal but zero allocated tokens | +| `INDEXER_INELIGIBLE` | Indexer fails eligibility oracle check at claim time | +| `STALE_POI` | POI presented after staleness deadline | +| `ZERO_POI` | POI is `bytes32(0)` | +| `ALLOCATION_TOO_YOUNG` | Allocation created in the current epoch | +| `CLOSE_ALLOCATION` | Allocation being closed with uncollected rewards | + +**Activates:** Automatic on upgrade ā€” the library and all condition checks are available immediately once the upgraded contracts are deployed. + +## Reclaim System + +**Before:** When rewards could not be distributed (denied subgraph, below-signal subgraph, stale POI, etc.), the tokens were silently lost -- never minted to anyone. + +**After:** Undistributable rewards are _reclaimed_ by minting them to a configurable address. Governance can set a per-condition address via `setReclaimAddress(condition, address)` and a catch-all fallback via `setDefaultReclaimAddress(address)`. If neither is configured for a given condition, rewards are still not minted (preserving the old drop behaviour). Every reclaim emits a `RewardsReclaimed` event with the condition, amount, indexer, allocation, and subgraph. + +**Activates:** Governance-gated ā€” requires `setReclaimAddress()` and/or `setDefaultReclaimAddress()` for each condition. Until configured, rewards are dropped (preserving legacy behaviour). + +## Zero Global Signal + +**Before:** Issuance during periods with zero total curation signal was silently lost. + +**After:** Detected in `updateAccRewardsPerSignal()` and reclaimed as `NO_SIGNAL`. + +**Activates:** Automatic on upgrade ā€” detection is built into the accumulator update. Reclaim requires a configured address for `NO_SIGNAL`. + +## Subgraph-Level Denial + +**Before:** Denial was a binary gate checked only at `takeRewards()` time. When a subgraph was denied, `takeRewards()` returned 0 and emitted `RewardsDenied`. The calling AllocationManager still advanced the allocation's reward snapshot, permanently dropping those rewards. + +**After:** Denial is handled at two levels: + +- **RewardsManager (accumulator level):** When `onSubgraphSignalUpdate` or `onSubgraphAllocationUpdate` is called for a denied subgraph, `accRewardsForSubgraph` and `accRewardsPerAllocatedToken` freeze (stop increasing). New rewards accruing during the denial period are reclaimed immediately rather than accumulated. `setDenied()` now snapshots accumulators before changing denial state so the boundary is clean. + +- **AllocationManager (claim level):** POI presentation for a denied subgraph is _deferred_ -- returns 0 **without advancing the allocation's snapshot**. This preserves uncollected pre-denial rewards. When the subgraph is later un-denied, those preserved rewards become claimable again. + +**Activates:** Automatic on upgrade ā€” the accumulator-level freeze and claim-level deferral apply immediately. Denial state itself is set via `setDenied()` (Governor or SubgraphAvailabilityOracle). + +## Below-Minimum Signal + +**Before:** `getAccRewardsForSubgraph()` silently excluded rewards for subgraphs below `minimumSubgraphSignal`. Those rewards were lost. + +**After:** The same exclusion occurs, but excluded rewards are reclaimed to the `BELOW_MINIMUM_SIGNAL` address instead of being lost. Changes to `minimumSubgraphSignal` apply retroactively to all pending rewards at the next accumulator update, so governance should call `onSubgraphSignalUpdate()` on affected subgraphs before changing the threshold. + +**Activates:** Automatic on upgrade for the reclaim path. Threshold changes via `setMinimumSubgraphSignal()` are retroactive ā€” governance should call `onSubgraphSignalUpdate()` on affected subgraphs before changing the threshold. + +## Zero Allocated Tokens + +**Before:** When a subgraph had signal but no allocations, `getAccRewardsPerAllocatedToken()` returned 0 for per-token rewards. The subgraph-level accumulator still grew, but the rewards were stranded -- distributable to no one. + +**After:** Detected as `NO_ALLOCATED_TOKENS` and reclaimed. When allocations resume, `accRewardsPerAllocatedToken` resumes from its stored value rather than resetting to zero. + +**Activates:** Automatic on upgrade ā€” detection is built into the accumulator update. + +## Indexer Eligibility + +**Before:** No per-indexer eligibility checks existed. + +**After:** An optional `rewardsEligibilityOracle` can be set by governance. When set, `takeRewards()` checks `isEligible(indexer)` at claim time. If the indexer is ineligible, rewards are denied (emitting `RewardsDeniedDueToEligibility`) and reclaimed to the `INDEXER_INELIGIBLE` address. Subgraph denial takes precedence: if a subgraph is denied, eligibility is not checked. + +**Activates:** Governance-gated ā€” requires `setRewardsEligibilityOracle()`. Until called, no eligibility checks are performed. + +## POI Presentation (AllocationManager) + +**Before:** A single conditional expression decided whether `takeRewards()` was called. If any condition failed (stale, zero POI, too young, altruistic), rewards were set to 0. The allocation's reward snapshot always advanced and pending rewards were always cleared, permanently dropping any undistributable rewards. + +**After:** Three distinct paths based on the determined condition: + +1. **Claim** (`NONE`): `takeRewards()` mints tokens, distributed to indexer and delegators. Snapshot advances. +2. **Reclaim** (`STALE_POI`, `ZERO_POI`): `reclaimRewards()` mints tokens to the reclaim address. Snapshot advances and pending rewards are cleared. +3. **Defer** (`ALLOCATION_TOO_YOUNG`, `SUBGRAPH_DENIED`): Returns 0 **without advancing the snapshot or clearing pending rewards**. Rewards are preserved for later collection. Accumulators are still updated via `onSubgraphAllocationUpdate()` to keep reclaim tracking current. + +The POI presentation timestamp is now recorded immediately on entry (before condition evaluation), so the staleness clock resets regardless of reward outcome. Over-delegation force-close is skipped on the deferred path to avoid closing allocations with preserved uncollected rewards. + +**Activates:** Automatic on upgrade ā€” the three-path logic applies to all POI presentations immediately. + +## Allocation Resize + +**Before:** Resizing always accumulated pending rewards for the delta period, regardless of allocation staleness. + +**After:** If the allocation is stale at resize time, pending rewards are reclaimed as `STALE_POI` and cleared. This prevents stale allocations from silently accumulating pending rewards through repeated resizes. + +**Activates:** Automatic on upgrade ā€” applies to all resize operations immediately. + +## Allocation Close + +**Before:** Closing an allocation advanced the snapshot and closed it. Any uncollected rewards were permanently lost. + +**After:** Before closing, `reclaimRewards(CLOSE_ALLOCATION, allocationId)` is called to mint uncollected rewards to the reclaim address. + +**Activates:** Automatic on upgrade ā€” applies to all close operations immediately. + +## Observability + +A new `POIPresented` event is emitted on every POI presentation, including the determined `condition` as a `bytes32` field. This provides off-chain visibility into why a given presentation did or did not result in rewards, which was previously invisible. + +**Activates:** Automatic on upgrade ā€” emitted on every POI presentation immediately. + +## View Functions + +Several view functions were added or changed to expose the new reward state. + +### Accumulator Views Freeze for Non-Claimable Subgraphs + +The existing accumulator view functions now exclude rewards for subgraphs that are not claimable (denied, below minimum signal, or with zero allocated tokens). Previously these accumulators always grew; callers reading them as continuously-increasing counters need to account for the new freeze behaviour. + +**`getAccRewardsForSubgraph()`** ā€” Previously always returned a growing value regardless of subgraph state. Now returns a frozen value when the subgraph is not claimable: the internal helper `_getSubgraphRewardsState()` determines a `RewardsCondition`, and when the condition is anything other than `NONE`, new rewards are excluded from the returned total. The accumulator resumes growing when the subgraph becomes claimable again. + +**`getAccRewardsPerAllocatedToken()`** ā€” Derives from `getAccRewardsForSubgraph()`, so it inherits the freeze. When the subgraph is not claimable, new per-token rewards are zero because the subgraph-level delta is zero. At snapshot points the implementation zeroes `undistributedRewards` and reclaims them instead of adding them to `accRewardsPerAllocatedToken`. + +**`getRewards()`** ā€” Returns the claimable reward estimate for an allocation. Because it reads `getAccRewardsPerAllocatedToken()`, it now returns a frozen value for allocations on non-claimable subgraphs. Pre-existing `accRewardsPending` from prior resizes is still included. Note: indexer eligibility is _not_ checked here (only at `takeRewards()` time), so the view does not reflect eligibility-based denial. + +**`getNewRewardsPerSignal()`** ā€” No visible change in return value. Internally it now separates claimable from unclaimable issuance (zero-signal periods), but the public view still returns only the claimable portion. The unclaimable portion is reclaimed as `NO_SIGNAL` at the next `updateAccRewardsPerSignal()` call. + +### New Getters on IRewardsManager + +| Function | Returns | Purpose | +| ----------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `getIssuanceAllocator()` | `IIssuanceAllocationDistribution` | Current allocator contract (zero if unset) | +| `getReclaimAddress(bytes32 reason)` | `address` | Per-condition reclaim address (zero if unconfigured) | +| `getDefaultReclaimAddress()` | `address` | Fallback reclaim address | +| `getRewardsEligibilityOracle()` | `IRewardsEligibility` | Current eligibility oracle (zero if unset) | +| `getAllocatedIssuancePerBlock()` | `uint256` | Effective issuance rate ā€” returns the allocator rate when set, otherwise falls back to storage. Replaces the legacy `getRewardsIssuancePerBlock()` for callers that need the protocol rate | +| `getRawIssuancePerBlock()` | `uint256` | Raw storage value, ignoring the allocator. Useful for debugging allocator configuration | + +### Changed Return Semantics + +**`getAllocationData()`** (IRewardsIssuer, implemented by SubgraphService) now returns a sixth value, `accRewardsPending`, representing accumulated rewards from allocation resizing that have not yet been claimed. Callers that destructure the return tuple need updating. + +**`IAllocation.State`** struct adds two fields: `accRewardsPending` (pending rewards from resize) and `createdAtEpoch` (epoch when the allocation was created). Both affect the return value of `getAllocation()`. + +## Provenance + +Merge commits into `main` that introduced the changes described above, in chronological order. + +| Date | Merge | PR | Scope | +| ---------- | ----------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 2025-12-16 | `ff2f00a62` | #1265 | Eligibility oracle audit doc fixes (TRST-L-1, TRST-L-2) | +| 2025-12-16 | `48be37a20` | #1267 | Issuance allocator audit fix ā€” default allocation, `setReclaimAddress` | +| 2025-12-31 | `89f1321c4` | #1272 | Issuance allocator audit fix v3 ā€” forced reclaim, PPM-to-absolute migration | +| 2026-01-08 | `3d274a4f1` | #1255 | Issuance baseline ā€” RewardsManager extensions, eligibility interface, test suites | +| 2026-01-08 | `363924149` | #1256 | Rewards Eligibility Oracle ā€” full oracle implementation | +| 2026-01-08 | `cdef9b5fd` | #1257 | Issuance Allocator ā€” full allocator, RewardsReclaim library, allocation close reclaim | +| 2026-02-17 | `ada315500` | #1279 | Rewards reclaiming (audited) ā€” RewardsCondition rename, `setDefaultReclaimAddress`, subgraph denial accumulator handling, zero-signal reclaim, POI three-path logic, `POIPresented` event | +| 2026-02-19 | `127b7ef6f` | #1280 | Issuance umbrella merge ā€” all prior work plus stale-allocation-resize reclaim (TRST-R-1) | diff --git a/packages/deployment/docs/LocalForkTesting.md b/packages/deployment/docs/LocalForkTesting.md index d8fc87987..8ba12452c 100644 --- a/packages/deployment/docs/LocalForkTesting.md +++ b/packages/deployment/docs/LocalForkTesting.md @@ -147,6 +147,7 @@ npx hardhat deploy --tags issuance-eligibility --network localNetwork ``` **Key differences from fork mode:** + - Chain ID 1337 (not 31337) - No `FORK_NETWORK` env var needed - Address books use `addresses-local-network.json` files (symlinked to mounted config) @@ -154,6 +155,7 @@ npx hardhat deploy --tags issuance-eligibility --network localNetwork - Uses standard test mnemonic (`test test test ... junk`) **Environment:** + - RPC: `http://chain:8545` (override with `LOCAL_NETWORK_RPC`) - Address books are populated by Phase 1 (hardhat-graph-protocol deploys Horizon + SubgraphService) - Phase 2+ deployment scripts use this package to deploy additional contracts (e.g., issuance) diff --git a/packages/deployment/docs/SyncBytecodeDetectionFix.md b/packages/deployment/docs/SyncBytecodeDetectionFix.md index 39d805e1a..641f60525 100644 --- a/packages/deployment/docs/SyncBytecodeDetectionFix.md +++ b/packages/deployment/docs/SyncBytecodeDetectionFix.md @@ -7,6 +7,7 @@ **Problem**: Deploy incorrectly reported "implementation unchanged" when local bytecode had actually changed. **Evidence**: + ``` Local artifact: 0x9c25d2f93e6a2a34cc19d00224872e288a8392d5d99b2df680b7e978d148d450 On-chain: 0xfafdeb48fae37e277e007e7b977f3cd124065ac1c27ed5208982c2965cf07008 @@ -29,6 +30,7 @@ All three hashes are different, yet deploy said "unchanged", meaning local chang ### Cause 1: Missing/Stale Bytecode Hash When the address book had no bytecode hash (or wrong hash): + - Sync detected "code changed" ([sync-utils.ts:475-477](../lib/sync-utils.ts#L475-L477)) - But only synced to rocketh if hash matched ([sync-utils.ts:653](../lib/sync-utils.ts#L653)) - This left rocketh with incomplete/wrong state @@ -36,6 +38,7 @@ When the address book had no bytecode hash (or wrong hash): ### Cause 2: Wrong Bytecode Stored for Proxy The sync step saved the **implementation's bytecode** under the **proxy's deployment record**: + - Lines 508-532: Created proxy record with implementation artifact bytecode - This is wrong - proxy should have its own bytecode (or none) - Rocketh then compared wrong bytecode and gave incorrect results @@ -49,6 +52,7 @@ When sync detects missing/mismatched bytecode hash: 1. **Fetch on-chain bytecode** from the implementation address 2. **Compare three versions**: local artifact, on-chain, address book 3. **Auto-heal** if local matches on-chain: + ```typescript if (localHash === onChainHash) { // Update address book with verified hash @@ -57,6 +61,7 @@ When sync detects missing/mismatched bytecode hash: syncNotes.push('hash verified' or 'hash healed') } ``` + 4. **Show clear status** if they differ: - `local code changed` - local differs from on-chain (ready to deploy) - `impl state unclear` - all three hashes differ (investigation needed) @@ -68,11 +73,11 @@ Changed proxy record creation to **NOT include implementation bytecode**: ```typescript // Before: -bytecode: artifact.bytecode // ā† Wrong! This is implementation bytecode +bytecode: artifact.bytecode // ā† Wrong! This is implementation bytecode deployedBytecode: artifact.deployedBytecode // After: -bytecode: '0x' // ā† Correct! Proxy record doesn't need bytecode +bytecode: '0x' // ā† Correct! Proxy record doesn't need bytecode deployedBytecode: undefined ``` @@ -83,12 +88,14 @@ This ensures rocketh only uses implementation bytecode for the actual implementa ### Scenario 1: Local Matches On-Chain (Hash Missing) **Before**: + ``` ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (code changed) āœ“ SubgraphService implementation unchanged ā† WRONG! ``` **After**: + ``` ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (hash verified) āœ“ SubgraphService implementation unchanged ā† Correct (hash now matches) @@ -99,12 +106,14 @@ Address book is auto-healed with correct bytecode hash. ### Scenario 2: Local Code Changed **Before**: + ``` ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (code changed) āœ“ SubgraphService implementation unchanged ā† WRONG! ``` **After**: + ``` ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (local code changed) šŸ“‹ New SubgraphService implementation deployed: 0x... ā† NEW! @@ -116,11 +125,13 @@ Deploy correctly detects the change and deploys new implementation. ### Scenario 3: Complex State (All Different) **Before**: + ``` ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (code changed) ``` **After**: + ``` ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (impl state unclear) ``` diff --git a/packages/issuance/docs/testing/reo/BaselineTestPlan.md b/packages/issuance/docs/testing/reo/BaselineTestPlan.md new file mode 100644 index 000000000..fd17a49e6 --- /dev/null +++ b/packages/issuance/docs/testing/reo/BaselineTestPlan.md @@ -0,0 +1,827 @@ +# Indexer Baseline Test Plan: Post-Upgrade Verification + +> **Navigation**: [ā† Back to REO Testing](README.md) + +This test plan validates that indexers can perform standard operational cycles on The Graph Network after a protocol upgrade. It is upgrade-agnostic and covers the core indexer workflows that must function correctly regardless of what changed. + +Each test includes CLI commands, GraphQL verification queries against the network subgraph, and pass/fail criteria. + +> All GraphQL queries run against the network subgraph. All addresses must be **lowercase**. + +--- + +## Prerequisites + +- ETH and GRT on the target network (testnet or mainnet) +- Indexer stack running (graph-node, indexer-agent, indexer-service, tap-agent) +- Minimum indexer stake met (100k GRT on testnet) +- Access to Explorer UI and network subgraph + +### Recommended log verbosity for troubleshooting + +``` +tap-agent: RUST_LOG=info,indexer_tap_agent=trace +indexer-service: RUST_LOG=info,indexer_service_rs=trace +indexer-agent: INDEXER_AGENT_LOG_LEVEL=trace +``` + +--- + +## Test Sequence Overview + +The tests are organized into 7 cycles. Cycles 1-6 cover individual operations; Cycle 7 ties them together in an end-to-end workflow. + +| Cycle | Area | Tests | +| ----- | ------------------------------ | --------- | +| 1 | Indexer Setup and Registration | 1.1 - 1.3 | +| 2 | Stake Management | 2.1 - 2.2 | +| 3 | Provision Management | 3.1 - 3.4 | +| 4 | Allocation Management | 4.1 - 4.5 | +| 5 | Query Serving and Revenue | 5.1 - 5.4 | +| 6 | Network Health | 6.1 - 6.3 | +| 7 | End-to-End Workflow | 7.1 | + +--- + +## Cycle 1: Indexer Setup and Registration + +### 1.1 Setup indexer via Explorer + +**Objective**: Stake GRT and set delegation parameters through Explorer UI. + +**Steps**: + +1. Navigate to Explorer +2. Stake GRT to your indexer address +3. Set delegation parameters (query fee cut, indexing reward cut) +4. Wait for transaction confirmation + +**Verification Query**: + +```graphql +{ + indexers(where: { id: "INDEXER_ADDRESS" }) { + id + createdAt + stakedTokens + queryFeeCut + indexingRewardCut + } +} +``` + +**Pass Criteria**: + +- Indexer entity exists with correct `stakedTokens` +- `queryFeeCut` and `indexingRewardCut` reflect configured values +- Transaction visible in Explorer history + +--- + +### 1.2 Register indexer URL and GEO coordinates + +**Objective**: Verify indexer metadata registration via the indexer agent. + +**Steps**: + +1. Configure `indexer-agent` with URL and GEO coordinates +2. Start or restart the agent +3. Confirm the agent logs show successful registration + +**Verification Query**: + +```graphql +{ + indexers(where: { id: "INDEXER_ADDRESS" }) { + id + url + geoHash + } +} +``` + +**Pass Criteria**: + +- `url` matches configured value +- `geoHash` is populated +- Agent logs show `Successfully registered indexer` + +--- + +### 1.3 Validate Subgraph Service provision and registration + +**Objective**: Confirm the indexer agent automatically creates a provision and registers with SubgraphService. + +**Steps**: + +1. Ensure indexer has sufficient unallocated stake +2. Start indexer agent +3. Monitor logs for provision creation and registration + +**Verification Query**: + +```graphql +{ + provisions(where: { indexer_: { id: "INDEXER_ADDRESS" } }) { + id + indexer { + id + url + geoHash + } + tokensProvisioned + tokensAllocated + tokensThawing + thawingPeriod + maxVerifierCut + dataService { + id + } + } +} +``` + +**Pass Criteria**: + +- Provision exists for SubgraphService +- `url` and `geoHash` populated in indexer registration +- `tokensProvisioned` is non-zero +- Agent logs show `Successfully provisioned to the Subgraph Service` and `Successfully registered indexer` + +--- + +## Cycle 2: Stake Management + +### 2.1 Add stake via Explorer + +**Objective**: Verify indexers can increase their stake. + +**Steps**: + +1. Navigate to Explorer +2. Add stake to your indexer +3. Wait for transaction confirmation + +**Verification Query**: + +```graphql +{ + indexers(where: { id: "INDEXER_ADDRESS" }) { + id + stakedTokens + allocatedTokens + availableStake + } +} +``` + +**Pass Criteria**: + +- `stakedTokens` increases by the added amount +- Transaction visible in Explorer history + +--- + +### 2.2 Unstake tokens and withdraw after thawing + +**Objective**: Verify the unstake and thawing period workflow. + +**Steps**: + +1. Unstake tokens via Explorer +2. Note the thawing period end time +3. Wait for thawing period to complete +4. Withdraw thawed tokens + +**Verification Query**: + +```graphql +{ + indexers(where: { id: "INDEXER_ADDRESS" }) { + id + stakedTokens + availableStake + } + thawRequests(where: { indexer_: { id: "INDEXER_ADDRESS" } }) { + id + tokens + thawingUntil + type + } +} +``` + +**Pass Criteria**: + +- Thaw request appears with correct token amount +- After thawing period, tokens withdraw successfully +- `stakedTokens` decreases by withdrawn amount + +--- + +## Cycle 3: Provision Management + +### 3.1 View current provision + +**Objective**: Check current Subgraph Service provision status. + +**Command**: + +```bash +graph indexer provisions get +``` + +**Verification Query**: + +```graphql +{ + provisions(where: { indexer_: { id: "INDEXER_ADDRESS" } }) { + id + tokensProvisioned + tokensThawing + tokensAllocated + thawingPeriod + maxVerifierCut + } +} +``` + +**Pass Criteria**: + +- CLI output matches subgraph data +- `tokensProvisioned` shows provisioned stake + +--- + +### 3.2 Add stake to provision + +**Objective**: Increase provision without creating a new one. + +**Command**: + +```bash +graph indexer provisions add +``` + +**Verification Query**: + +```graphql +{ + provisions(where: { indexer_: { id: "INDEXER_ADDRESS" } }) { + id + tokensProvisioned + tokensAllocated + indexer { + stakedTokens + availableStake + } + } +} +``` + +**Pass Criteria**: + +- `tokensProvisioned` increases by the added amount +- `availableStake` decreases correspondingly + +--- + +### 3.3 Thaw stake from provision + +**Objective**: Initiate thawing process to remove stake from provision. + +**Command**: + +```bash +graph indexer provisions thaw +``` + +**Verification Query**: + +```graphql +{ + provisions(where: { indexer_: { id: "INDEXER_ADDRESS" } }) { + id + tokensProvisioned + tokensThawing + } + thawRequests(where: { indexer_: { id: "INDEXER_ADDRESS" }, type: Provision }) { + id + tokens + thawingUntil + } +} +``` + +**Pass Criteria**: + +- `tokensThawing` increases by the thawed amount +- Thaw request created with future `thawingUntil` timestamp + +--- + +### 3.4 Remove thawed stake from provision + +**Objective**: Complete the provision reduction after thawing period. + +**Command**: + +```bash +graph indexer provisions remove +``` + +**Verification Query**: + +```graphql +{ + provisions(where: { indexer_: { id: "INDEXER_ADDRESS" } }) { + id + tokensProvisioned + tokensThawing + } + indexers(where: { id: "INDEXER_ADDRESS" }) { + availableStake + } +} +``` + +**Pass Criteria**: + +- `tokensThawing` decreases to 0 +- `tokensProvisioned` decreases by the removed amount +- `availableStake` increases correspondingly + +--- + +## Cycle 4: Allocation Management + +### 4.1 Find subgraph deployments with rewards + +**Objective**: Identify eligible deployments for allocation. + +**Query**: + +```graphql +{ + subgraphDeployments(where: { deniedAt: 0, signalledTokens_not: 0, indexingRewardAmount_not: 0 }) { + ipfsHash + stakedTokens + signalledTokens + indexingRewardAmount + manifest { + network + } + } +} +``` + +**Action**: Filter results by chains your graph-node can index. + +--- + +### 4.2 Create allocation manually + +**Objective**: Open an allocation for a specific deployment. + +**Command**: + +```bash +graph indexer allocations create +``` + +**Verification Query**: + +```graphql +{ + allocations(where: { indexer_: { id: "INDEXER_ADDRESS" }, status: "Active" }) { + id + allocatedTokens + createdAtEpoch + subgraphDeployment { + ipfsHash + } + } +} +``` + +**Pass Criteria**: + +- Allocation appears with status `Active` +- `allocatedTokens` matches specified amount +- `createdAtEpoch` is current epoch + +--- + +### 4.3 Create allocation via actions queue + +**Objective**: Test the actions queue workflow for allocation management. + +**Commands**: + +```bash +graph indexer actions queue allocate +graph indexer actions execute approve +``` + +**Verification**: Same as 4.2. + +**Pass Criteria**: + +- Action queued successfully +- After approval, allocation appears with status `Active` + +--- + +### 4.4 Create allocation via deployment rules + +**Objective**: Test automated allocation management through rules. + +**Command**: + +```bash +graph indexer rules set allocationAmount allocationLifetime +``` + +**Verification**: Same as 4.2. + +**Pass Criteria**: + +- Indexer agent picks up the rule and creates the allocation automatically +- Set `allocationLifetime` to a small value for quicker testing + +--- + +### 4.5 Reallocate a deployment + +**Objective**: Close and recreate allocation in one operation. + +**Command**: + +```bash +graph indexer allocations reallocate +``` + +**Verification Query**: + +```graphql +{ + allocations( + where: { indexer_: { id: "INDEXER_ADDRESS" }, subgraphDeployment_: { ipfsHash: "DEPLOYMENT_IPFS_HASH" } } + ) { + id + status + allocatedTokens + createdAtEpoch + closedAtEpoch + } +} +``` + +**Pass Criteria**: + +- Old allocation shows status `Closed` +- New allocation created with status `Active` +- New `allocatedTokens` matches specified amount + +--- + +## Cycle 5: Query Serving and Revenue Collection + +> **Cross-reference**: Allocations opened in Cycles 4-5 may also serve as setup for [ReoTestPlan Cycle 6](./ReoTestPlan.md#cycle-6-integration-with-rewards), which tests reward denial/recovery with mature allocations. If running both plans, keep extra allocations open for the REO reward integration tests. + +### 5.1 Send test queries + +**Objective**: Verify the indexer serves queries through the gateway. + +**Script** (save as `query_test.sh`): + +```bash +#!/bin/bash +subgraph_id=${1} +count=${2:-25} +api_key=${3:-"YOUR_API_KEY"} +gateway=${4:-"https://gateway.thegraph.com"} + +for ((i=0; i 50 +``` + +**Verification**: + +1. Queries return valid JSON with block data +2. Check indexer-service logs for query processing +3. Check database for TAP receipts: + +```sql +SELECT COUNT(*) FROM tap_horizon_receipts +WHERE allocation_id = ''; +``` + +**Pass Criteria**: + +- Queries succeed with 200 responses +- TAP receipts generated in database + +--- + +### 5.2 Close allocation and collect indexing rewards + +**Objective**: Verify rewards collection on allocation closure. + +**Prerequisites**: Allocation must be several epochs old. Check first: + +```graphql +{ + graphNetworks { + currentEpoch + } + allocations(where: { indexer_: { id: "INDEXER_ADDRESS" }, status: "Active" }) { + id + allocatedTokens + createdAtEpoch + } +} +``` + +**Command**: + +```bash +graph indexer allocations close +``` + +**Verification Query**: + +```graphql +{ + allocations(where: { id: "ALLOCATION_ID" }) { + id + status + allocatedTokens + indexingRewards + closedAtEpoch + } +} +``` + +**Pass Criteria**: + +- Status changes to `Closed` +- `indexingRewards` is non-zero (for deployments with rewards) +- `closedAtEpoch` is current epoch + +--- + +### 5.3 Verify query fee collection + +**Objective**: Confirm query fees collected after allocation closure. + +> Query fee collection happens asynchronously after closure and may take minutes to hours. + +**Verification Query**: + +```graphql +{ + allocations(where: { indexer_: { id: "INDEXER_ADDRESS" }, status: "Closed" }) { + id + queryFeesCollected + closedAtEpoch + } +} +``` + +**Pass Criteria**: + +- `queryFeesCollected` is non-zero for allocations that served queries + +--- + +### 5.4 Close allocation with explicit POI + +**Objective**: Test POI override and reward eligibility. + +**Prerequisites**: Allocation is several epochs old. + +**Command**: + +```bash +graph indexer allocations close --poi +``` + +**Verification Query**: + +```graphql +{ + allocations(where: { id: "ALLOCATION_ID" }) { + id + status + indexingRewards + poi + } +} +``` + +**Pass Criteria**: + +- `indexingRewards` is non-zero +- `poi` matches the submitted value + +--- + +## Cycle 6: Network Health + +### 6.1 Monitor indexer health + +**Objective**: Verify indexer appears healthy in the network. + +**Query**: + +```graphql +{ + indexers(where: { id: "INDEXER_ADDRESS" }) { + id + url + geoHash + stakedTokens + allocatedTokens + availableStake + delegatedTokens + queryFeesCollected + rewardsEarned + allocations(where: { status: "Active" }) { + id + subgraphDeployment { + ipfsHash + } + } + } +} +``` + +**Pass Criteria**: + +- All expected fields populated +- Active allocations visible +- Accumulated rewards and fees present + +--- + +### 6.2 Check epoch progression + +**Objective**: Verify the network is progressing normally. + +**Query**: + +```graphql +{ + graphNetworks { + id + currentEpoch + totalTokensStaked + totalTokensAllocated + totalQueryFees + totalIndexingRewards + } +} +``` + +**Pass Criteria**: + +- `currentEpoch` increments at the expected rate +- Network totals accumulate over time + +--- + +### 6.3 Verify no unexpected errors in logs + +**Objective**: Confirm clean operation across all indexer components. + +**Steps**: + +1. Review indexer-agent logs for unexpected errors or reverts +2. Review indexer-service logs for query handling issues +3. Review tap-agent logs for receipt/RAV issues +4. Review graph-node logs for indexing errors + +**Pass Criteria**: + +- No unexpected `ERROR` level log entries +- No transaction reverts +- No stuck or looping operations + +--- + +## Cycle 7: End-to-End Workflow + +### 7.1 Full operational cycle + +Run these operations in sequence to validate a complete indexer lifecycle: + +| Step | Operation | Reference | +| ---- | ---------------------------------- | --------- | +| 1 | Check provision status | 3.1 | +| 2 | Find a rewarded deployment | 4.1 | +| 3 | Create allocation | 4.2 | +| 4 | Send test queries (50-100) | 5.1 | +| 5 | Wait 2-3 epochs | - | +| 6 | Close allocation | 5.2 | +| 7 | Verify indexing rewards (non-zero) | 5.2 | +| 8 | Verify query fees collected | 5.3 | +| 9 | Repeat with a different deployment | 4.2 | + +**Pass Criteria**: All individual pass criteria met across the full sequence. + +--- + +## Post-Upgrade Validation Checklist + +### Core functionality + +- [ ] Indexer stack components compatible with upgraded contracts +- [ ] Existing allocations continue to function +- [ ] New allocations can be created +- [ ] Query serving works through gateway +- [ ] Indexing rewards collected correctly +- [ ] Query fees collected correctly +- [ ] Provision management operations succeed + +### Network health + +- [ ] Network subgraph indexes the upgrade correctly +- [ ] Epoch progression continues normally +- [ ] Explorer displays correct data +- [ ] No unexpected reverts or errors in logs + +### Upgrade-specific (fill in per upgrade) + +- [ ] Contract address changes updated in indexer configuration +- [ ] New protocol parameters match expected values +- [ ] Schema changes (if any) reflected correctly +- [ ] _[Add upgrade-specific items here]_ + +--- + +## Troubleshooting + +**Allocation creation fails**: + +- Check `availableStake` is sufficient +- Verify graph-node is syncing the target deployment +- Ensure provision has enough tokens + +**Query fees not collected**: + +- Wait longer (can take several hours) +- Check TAP receipts in database +- Verify queries actually hit your indexer (check service logs) + +**Zero indexing rewards**: + +- Confirm allocation was open for the required number of epochs +- Verify POI was submitted correctly +- Confirm deployment has rewards enabled (`indexingRewardAmount_not: 0`) + +--- + +## Network Configuration Reference + +### Arbitrum Sepolia (testnet) + +| Parameter | Value | +| ----------------- | --------------------------------------- | +| Explorer | | +| Gateway | | +| Epoch length | ~554 blocks (~110 minutes) | +| Min indexer stake | 100k GRT | +| Thawing period | Shortened for faster testing | + +### Arbitrum One (mainnet) + +| Parameter | Value | +| ----------------- | ------------------------------- | +| Explorer | | +| Gateway | | +| Epoch length | ~6,646 blocks (~24 hours) | +| Min indexer stake | 100k GRT | + +--- + +## Related Documentation + +- [ā† Back to REO Testing](README.md) + +--- + +_Extracted from Horizon upgrade test plans._ diff --git a/packages/issuance/docs/testing/reo/IndexerTestGuide.md b/packages/issuance/docs/testing/reo/IndexerTestGuide.md new file mode 100644 index 000000000..6b1423a36 --- /dev/null +++ b/packages/issuance/docs/testing/reo/IndexerTestGuide.md @@ -0,0 +1,542 @@ +# Indexer Eligibility Test Plan + +> **Navigation**: [ā† Back to REO Testing](README.md) | [BaselineTestPlan](BaselineTestPlan.md) | [ReoTestPlan](ReoTestPlan.md) + +Tests for indexers to verify correct eligibility handling on Arbitrum Sepolia. This is a focused subset of [ReoTestPlan.md](ReoTestPlan.md), covering per-indexer eligibility flows (renew, expire, recover). The full ReoTestPlan covers additional areas: deployment verification, oracle operations, timeout fail-open, emergency operations, and UI verification. + +Each indexer controls their own eligibility via the ORACLE_ROLE granted to their address. + +Each test includes CLI commands, verification queries against the network subgraph, and pass/fail criteria. + +> All GraphQL queries run against the network subgraph. All addresses must be **lowercase**. + +--- + +## Prerequisites + +- Completed [BaselineTestPlan](BaselineTestPlan.md) Cycles 1-4 (indexer staked, provisioned, can allocate) +- `cast` (Foundry) installed for contract interaction +- Indexer private key available for signing transactions + +### Environment Configuration (set by coordinator) + +- **Eligibility validation**: enabled +- **Eligibility period**: short (e.g. 10-15 minutes) +- **Oracle timeout**: very high (no fail-open during testing) +- **ORACLE_ROLE**: granted to each participating indexer + +### Environment Variables + +```bash +export RPC="https://sepolia-rollup.arbitrum.io/rpc" +export INDEXER= # lowercase +export INDEXER_KEY= + +# Contract addresses (Arbitrum Sepolia) +export REO=0x62c2305739cc75f19a3a6d52387ceb3690d99a99 +export MOCK_REO=0x5FB23365F8cf643D5f1459E9793EfF7254522400 +export REWARDS_MANAGER=0x1f49cae7669086c8ba53cc35d1e9f80176d67e79 +``` + +### Mock REO Option + +A `MockRewardsEligibilityOracle` is deployed at `0x5FB23365F8cf643D5f1459E9793EfF7254522400`. When RewardsManager is pointed at the mock (by the coordinator), you can directly toggle your eligibility without oracle roles, renewal periods, or timeout logic: + +```bash +# Check your eligibility +cast call $MOCK_REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC + +# Toggle ineligible (signed by your indexer key) +cast send $MOCK_REO "setEligible(bool)" false --rpc-url $RPC --private-key $INDEXER_KEY + +# Toggle eligible again +cast send $MOCK_REO "setEligible(bool)" true --rpc-url $RPC --private-key $INDEXER_KEY +``` + +If the coordinator has pointed RewardsManager at the mock, you can use Sets 2m-4m below instead of Sets 2-4 for faster testing. Ask the coordinator which REO is active: + +```bash +cast call $REWARDS_MANAGER "getRewardsEligibilityOracle()(address)" --rpc-url $RPC +``` + +### Verify Environment + +```bash +# Validation must be enabled +cast call $REO "getEligibilityValidation()(bool)" --rpc-url $RPC +# Expected: true + +# Confirm you have ORACLE_ROLE +ORACLE_ROLE=$(cast keccak "ORACLE_ROLE") +cast call $REO "hasRole(bytes32,address)(bool)" $ORACLE_ROLE $INDEXER --rpc-url $RPC +# Expected: true + +# Note the eligibility period (seconds) +cast call $REO "getEligibilityPeriod()(uint256)" --rpc-url $RPC +``` + +--- + +## Test Sequence Overview + +| Set | Area | Tests | +| --- | ------------------------------ | --------- | +| 1 | Prepare Allocations | 1.1 | +| 2 | Eligible ā€” Receive Rewards | 2.1 - 2.2 | +| 3 | Ineligible ā€” Verify Denial | 3.1 - 3.2 | +| 4 | Optimistic Recovery | 4.1 - 4.2 | +| 5 | Validation Disabled | 5.1 | +| 2m | Eligible ā€” Mock REO | 2m.1 | +| 3m | Ineligible ā€” Mock REO | 3m.1 | +| 4m | Optimistic Recovery ā€” Mock REO | 4m.1 | + +**Timing**: Set 1 opens allocations that need epoch maturity. Sets 2-4 use the production REO (sequential: renew ā†’ eligible close ā†’ wait for expiry ā†’ ineligible close ā†’ re-renew ā†’ recovery close). Sets 2m-4m use the mock REO for instant eligibility control -- no waiting for expiry. Set 5 requires coordinator to toggle validation. + +--- + +## Set 1: Prepare Allocations + +### 1.1 Open allocations for eligibility tests + +**Objective**: Open 3+ allocations on different deployments. These need to mature across epochs before they can be closed in Sets 2-4. + +**Prerequisites**: Indexer is staked, provisioned, and registered (BaselineTestPlan Cycles 1-3). Subgraph deployments with signal exist. + +**Steps**: + +1. Find subgraph deployments with signal +2. Open allocations on 3+ different deployments +3. Record allocation IDs and current epoch + +**Command**: + +```bash +graph indexer actions queue allocate +graph indexer actions queue allocate +graph indexer actions queue allocate +graph indexer actions approve +``` + +**Verification Query**: + +```graphql +{ + indexer(id: "INDEXER_ADDRESS") { + allocations(where: { status: "Active" }) { + id + subgraphDeployment { + ipfsHash + } + allocatedTokens + createdAtEpoch + } + } + graphNetwork(id: "1") { + currentEpoch + } +} +``` + +**Pass Criteria**: + +- 3+ active allocations visible in subgraph +- `createdAtEpoch` recorded (need at least 1 epoch to pass before closing) + +> While waiting for epoch maturity, proceed to Set 2 to renew eligibility. + +--- + +## Set 2: Eligible ā€” Receive Rewards + +### 2.1 Renew eligibility + +**Objective**: Renew your own eligibility and confirm the REO reflects it. + +**Prerequisites**: ORACLE_ROLE confirmed in environment check. + +**Command**: + +```bash +cast send $REO "renewIndexerEligibility(address[],bytes)" "[$INDEXER]" "0x" \ + --rpc-url $RPC --private-key $INDEXER_KEY +``` + +**Verification**: + +```bash +cast call $REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: true + +cast call $REO "getEligibilityRenewalTime(address)(uint256)" $INDEXER --rpc-url $RPC +# Record this timestamp ā€” eligibility expires at: renewal_time + eligibility_period +``` + +**Pass Criteria**: + +- `isEligible` returns `true` +- `getEligibilityRenewalTime` returns a recent timestamp + +--- + +### 2.2 Close allocation while eligible + +**Objective**: Verify that an eligible indexer receives indexing rewards when closing an allocation. + +**Prerequisites**: `isEligible` returns `true`. Allocation from Set 1 is at least 1 epoch old. + +**Command**: + +```bash +graph indexer actions queue close +graph indexer actions approve +``` + +**Verification Query**: + +```graphql +{ + allocations(where: { id: "ALLOCATION_ID" }) { + id + status + indexingRewards + closedAtEpoch + } +} +``` + +**Pass Criteria**: + +- Status changes to `Closed` +- `indexingRewards` is non-zero +- `closedAtEpoch` is current epoch + +--- + +## Set 3: Ineligible ā€” Verify Denial + +### 3.1 Wait for eligibility expiry + +**Objective**: Confirm that eligibility expires after the configured period. + +**Prerequisites**: Renewal timestamp and eligibility period recorded from Set 2.1. + +**Steps**: + +1. Calculate expiry time: `renewal_timestamp + eligibility_period` +2. Wait until current block time exceeds expiry +3. Verify eligibility has expired + +**Verification**: + +```bash +cast call $REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: false + +# Confirm by comparing timestamps: +cast call $REO "getEligibilityRenewalTime(address)(uint256)" $INDEXER --rpc-url $RPC +cast call $REO "getEligibilityPeriod()(uint256)" --rpc-url $RPC +cast block latest --field timestamp --rpc-url $RPC +# block_timestamp > renewal_time + period +``` + +**Pass Criteria**: + +- `isEligible` returns `false` +- Block timestamp exceeds renewal time + eligibility period + +--- + +### 3.2 Close allocation while ineligible + +**Objective**: Verify that an ineligible indexer receives zero indexing rewards when closing an allocation. Denied rewards are routed to the reclaim contract. + +**Prerequisites**: `isEligible` returns `false`. Allocation from Set 1 is at least 1 epoch old. + +**Steps**: + +1. Confirm ineligibility +2. Close an allocation +3. Verify zero rewards + +**Command**: + +```bash +# Confirm ineligible +cast call $REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: false + +# Close allocation +graph indexer actions queue close +graph indexer actions approve +``` + +**Verification Query**: + +```graphql +{ + allocations(where: { id: "ALLOCATION_ID" }) { + id + status + indexingRewards + closedAtEpoch + } +} +``` + +**Pass Criteria**: + +- Status changes to `Closed` +- `indexingRewards` is `0` +- Contrast with Set 2.2 where `indexingRewards` was non-zero + +--- + +## Set 4: Optimistic Recovery + +Eligibility denial is **optimistic**: rewards accrue to allocations during ineligible periods and are paid in full when the indexer closes while eligible. This is the key behavioral difference from subgraph denial. + +### 4.1 Re-renew eligibility + +**Objective**: Restore eligibility after expiry and confirm the REO reflects it. + +**Prerequisites**: Eligibility expired (Set 3.1). Do this promptly after Set 3. + +**Command**: + +```bash +cast send $REO "renewIndexerEligibility(address[],bytes)" "[$INDEXER]" "0x" \ + --rpc-url $RPC --private-key $INDEXER_KEY +``` + +**Verification**: + +```bash +cast call $REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: true +``` + +**Pass Criteria**: + +- `isEligible` returns `true` after re-renewal + +--- + +### 4.2 Close allocation ā€” full rewards after re-renewal + +**Objective**: Verify that an allocation closed after re-renewal receives full rewards for its entire duration, including the ineligible period. + +**Prerequisites**: `isEligible` returns `true`. Active allocation from Set 1 has been open across multiple epochs including the ineligible period. + +**Command**: + +```bash +graph indexer actions queue close +graph indexer actions approve +``` + +**Verification Query**: + +```graphql +{ + allocations(where: { id: "ALLOCATION_ID" }) { + id + status + indexingRewards + createdAtEpoch + closedAtEpoch + } +} +``` + +**Pass Criteria**: + +- Status changes to `Closed` +- `indexingRewards` is non-zero +- Rewards reflect the full allocation duration (`closedAtEpoch - createdAtEpoch`), not reduced by the ineligible period +- Compare with Set 2.2: this allocation was open longer and should have proportionally more rewards + +--- + +## Set 5: Validation Disabled + +### 5.1 Verify eligibility when validation is off + +**Objective**: Confirm that all indexers are eligible when validation is disabled, regardless of renewal status. This is the default state and the emergency fallback. + +**Prerequisites**: Coordinator has disabled validation (`setEligibilityValidation(false)`). + +**Verification**: + +```bash +cast call $REO "getEligibilityValidation()(bool)" --rpc-url $RPC +# Expected: false + +cast call $REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: true +``` + +**Pass Criteria**: + +- `getEligibilityValidation` returns `false` +- `isEligible` returns `true` even without a recent renewal + +--- + +## Mock REO Test Sets (2m - 4m) + +These sets use the `MockRewardsEligibilityOracle` for direct eligibility control. The coordinator must have pointed RewardsManager at the mock. These replace Sets 2-4 when the mock is active. + +### 2m.1 Close allocation while eligible (mock) + +**Objective**: Verify rewards when eligible (the default mock state). + +**Prerequisites**: Allocation from Set 1 is at least 1 epoch old. + +```bash +# Confirm eligible (default) +cast call $MOCK_REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: true + +# Close allocation +graph indexer actions queue close +graph indexer actions approve +``` + +**Pass Criteria**: `indexingRewards` is non-zero. + +--- + +### 3m.1 Toggle ineligible and close allocation (mock) + +**Objective**: Verify reward denial after toggling ineligible. + +```bash +# Toggle ineligible +cast send $MOCK_REO "setEligible(bool)" false --rpc-url $RPC --private-key $INDEXER_KEY + +# Confirm +cast call $MOCK_REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: false + +# Close allocation +graph indexer actions queue close +graph indexer actions approve +``` + +**Pass Criteria**: `indexingRewards` = `0`. Allocation still transitions to `Closed`. + +--- + +### 4m.1 Re-enable and close allocation -- full rewards (mock) + +**Objective**: Verify optimistic recovery: toggle eligible again and receive full rewards. + +**Prerequisites**: Active allocation open across multiple epochs, including time while ineligible. + +```bash +# Toggle eligible +cast send $MOCK_REO "setEligible(bool)" true --rpc-url $RPC --private-key $INDEXER_KEY + +# Confirm +cast call $MOCK_REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: true + +# Close allocation +graph indexer actions queue close +graph indexer actions approve +``` + +**Pass Criteria**: + +- `indexingRewards` is non-zero +- Rewards reflect the full allocation duration (not reduced by the ineligible period) +- Compare with 2m.1: longer-open allocation should have proportionally more rewards + +--- + +## Indexer Awareness: Denial and Reward Conditions + +These situations are managed by the coordinator, not the indexer. No indexer action is needed ā€” but indexers should understand the expected behaviour. + +### During subgraph denial + +If a coordinator denies a subgraph you have allocations on: + +- **Continue presenting POIs** ā€” deferred presentations reset the staleness clock, preventing STALE_POI reclaim when the subgraph is later undenied +- `getRewards()` returns a frozen value (pre-denial uncollected rewards are preserved) +- Closing an allocation on a denied subgraph returns 0 rewards but preserves the pre-denial amount + +**Verification during denial:** + +```bash +cast call $REWARDS_MANAGER "isDenied(bytes32)(bool)" --rpc-url $RPC +# Expected: true (if coordinator denied it) + +cast call $REWARDS_MANAGER "getRewards(address,address)(uint256)" --rpc-url $RPC +# Returns frozen pre-denial rewards (non-zero if you had uncollected rewards) +``` + +### After subgraph undeny + +After a coordinator undenies a subgraph: + +- Accumulators resume growing +- Close allocation normally ā€” rewards include pre-denial + post-undeny amounts +- Denial-period rewards were reclaimed to the protocol (not included in your claim) + +**Verification after undeny:** + +```bash +cast call $REWARDS_MANAGER "isDenied(bytes32)(bool)" --rpc-url $RPC +# Expected: false + +cast call $REWARDS_MANAGER "getRewards(address,address)(uint256)" --rpc-url $RPC +# Should be growing again (pre-denial + post-undeny rewards) +``` + +### POI staleness + +If an allocation goes without POI presentation for longer than `maxPOIStaleness`, rewards are reclaimed as STALE_POI instead of being paid to the indexer. + +```bash +cast call "maxPOIStaleness()(uint256)" --rpc-url $RPC +# Note this value ā€” present POIs more frequently than this +``` + +**Action**: Ensure your indexer agent is healthy and presenting POIs regularly. + +### Signal-related conditions + +Rewards require curation signal above the minimum threshold. If signal drops below `minimumSubgraphSignal`, rewards freeze and are reclaimed. This is not actionable by indexers ā€” it depends on curators. + +```bash +cast call $REWARDS_MANAGER "minimumSubgraphSignal()(uint256)" --rpc-url $RPC +``` + +**Related**: [RewardsConditionsTestPlan.md](RewardsConditionsTestPlan.md) | [SubgraphDenialTestPlan.md](SubgraphDenialTestPlan.md) + +--- + +## Troubleshooting + +**`isEligible` returns `false` unexpectedly:** + +- Check if validation is enabled: `getEligibilityValidation()` +- Check your renewal time: `getEligibilityRenewalTime(address)` +- Check the eligibility period: `getEligibilityPeriod()` +- Your renewal may have expired: compare `renewal_time + period` with current block time + +**Renewal transaction reverts:** + +- Confirm you have ORACLE_ROLE: `hasRole(ORACLE_ROLE, address)` +- Confirm the REO is not paused: `paused()` + +**Zero rewards on close despite being eligible:** + +- Check allocation maturity: must have been open for at least 1 full epoch +- Check if subgraph deployment has signal (no signal = no rewards) +- Verify RewardsManager points to the REO: `getRewardsEligibilityOracle()` + +--- + +**Related**: [BaselineTestPlan.md](BaselineTestPlan.md) | [ReoTestPlan.md](ReoTestPlan.md) diff --git a/packages/issuance/docs/testing/reo/README.md b/packages/issuance/docs/testing/reo/README.md new file mode 100644 index 000000000..e50f9c756 --- /dev/null +++ b/packages/issuance/docs/testing/reo/README.md @@ -0,0 +1,168 @@ +# Issuance Upgrade Testing Documentation + +Comprehensive test plans for validating The Graph Network after the issuance upgrade. Three-layer approach: baseline indexer operations (upgrade-agnostic), REO-specific eligibility and oracle tests, and reward condition tests covering denial, reclaim, signal, POI paths, and allocation lifecycle changes. + +## Quick Start + +1. **Indexers start here** ā†’ Follow [IndexerTestGuide.md](IndexerTestGuide.md) +2. **Detailed baseline reference** ā†’ [BaselineTestPlan.md](BaselineTestPlan.md) +3. **REO eligibility tests** ā†’ [ReoTestPlan.md](ReoTestPlan.md) +4. **Subgraph denial tests** ā†’ [SubgraphDenialTestPlan.md](SubgraphDenialTestPlan.md) +5. **Reward conditions tests** ā†’ [RewardsConditionsTestPlan.md](RewardsConditionsTestPlan.md) + +**Mock REO available**: A `MockRewardsEligibilityOracle` at `0x5FB23365F8cf643D5f1459E9793EfF7254522400` (Arbitrum Sepolia) provides instant eligibility control for integration testing. See the mock-based test paths in [ReoTestPlan](ReoTestPlan.md#mock-reo-quick-test-path) and [IndexerTestGuide](IndexerTestGuide.md#mock-reo-option). + +## Reading Order + +1. **[BaselineTestPlan.md](BaselineTestPlan.md)** -- Upgrade-agnostic indexer operations (run first) +2. **[ReoTestPlan.md](ReoTestPlan.md)** -- REO-specific eligibility, oracle, and rewards tests (run after baseline passes) +3. **[RewardsConditionsTestPlan.md](RewardsConditionsTestPlan.md)** -- Reclaim system, signal conditions, POI paths, allocation lifecycle (run after baseline passes; Cycle 1 configures reclaim addresses needed by other plans) +4. **[SubgraphDenialTestPlan.md](SubgraphDenialTestPlan.md)** -- Subgraph denial two-level handling, accumulator freeze, deferral, deny/undeny lifecycle (run after reclaim setup) +5. **[IndexerTestGuide.md](IndexerTestGuide.md)** -- Condensed guide for indexers running eligibility tests (subset of ReoTestPlan) + +``` +BaselineTestPlan (7 cycles, 22 tests) + ā”‚ Covers: setup, staking, provisions, allocations, queries, health + ā”‚ + ā”œā”€ā”€ā–¶ ReoTestPlan (8 cycles + mock path, 36 tests) + ā”‚ Covers: deployment, eligibility, oracle, rewards, emergency, UI + ā”‚ Depends on: Baseline Cycles 1-7 pass first + ā”‚ Cycle 2.3 opens allocations reused in Cycle 6 + ā”‚ Cycle 6m: mock REO path for fast integration testing + ā”‚ + ā”œā”€ā”€ā–¶ RewardsConditionsTestPlan (7 cycles, 26 tests) + ā”‚ Covers: reclaim config, below-minimum signal, zero allocated tokens, + ā”‚ POI paths (stale/zero/too-young), allocation resize/close, observability + ā”‚ Depends on: Baseline Cycles 1-7 pass first + ā”‚ Cycle 1 configures reclaim addresses used by all reclaim tests + ā”‚ + ā”œā”€ā”€ā–¶ SubgraphDenialTestPlan (6 cycles, 18 tests) + ā”‚ Covers: deny/undeny state, accumulator freeze, allocation deferral, + ā”‚ pre-denial reward recovery, edge cases + ā”‚ Depends on: Baseline + RewardsConditionsTestPlan Cycle 1 (reclaim setup) + ā”‚ + ā””ā”€ā”€ā–¶ IndexerTestGuide (5 sets + 3 mock sets, 11 tests) + Covers: eligible/ineligible/recovery flows + Depends on: Baseline Cycles 1-4 (staked, provisioned, can allocate) + Subset of ReoTestPlan focused on per-indexer eligibility + Sets 2m-4m: mock REO alternative for instant eligibility control +``` + +## Documentation + +### Test Plans + +| Document | Purpose | Status | +| ------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------- | +| [BaselineTestPlan.md](BaselineTestPlan.md) | Detailed baseline indexer operational tests (7 cycles, 22 tests) | āœ… Complete | +| [ReoTestPlan.md](ReoTestPlan.md) | REO eligibility, oracle, and rewards integration (8 cycles + mock path, 36 tests) | āœ… Complete | +| [RewardsConditionsTestPlan.md](RewardsConditionsTestPlan.md) | Reclaim system, signal conditions, POI paths, allocation lifecycle (7 cycles, 26 tests) | āœ… Complete (local automation: Cycles 1-4, 6) | +| [SubgraphDenialTestPlan.md](SubgraphDenialTestPlan.md) | Subgraph denial: accumulator freeze, deferral, recovery (6 cycles, 18 tests) | āœ… Complete (local automation: Cycles 2, 3, 5, 6) | +| [IndexerTestGuide.md](IndexerTestGuide.md) | Condensed indexer eligibility tests (5 sets + 3 mock sets, 11 tests) | āœ… Complete | + +### Support Files (`support/`) + +| Document | Purpose | Status | +| -------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------- | +| [NotionSetup.md](support/NotionSetup.md) | Instructions for importing test tracker into Notion | āœ… Complete | +| [NotionTracker.csv](support/NotionTracker.csv) | CSV export for Notion import | āœ… Complete | +| [IssuanceAllocatorTestPlan.md](support/IssuanceAllocatorTestPlan.md) | IssuanceAllocator tests (independent of REO, pending deployment) | āøļø Pending | + +## Test Coverage + +### Baseline Tests (7 Cycles) + +1. **Cycle 1: Indexer Setup and Registration** (3 tests) + - Setup via Explorer, register URL/GEO, validate SubgraphService provision + +2. **Cycle 2: Stake Management** (2 tests) + - Add stake, unstake and withdraw after thawing + +3. **Cycle 3: Provision Management** (4 tests) + - View provision, add stake, thaw stake, remove thawed stake + +4. **Cycle 4: Allocation Management** (5 tests) + - Find rewarded deployments, create allocations (manual/queue/rules), reallocate + +5. **Cycle 5: Query Serving and Revenue** (4 tests) + - Send test queries, close allocations, verify rewards and fees + +6. **Cycle 6: Network Health** (3 tests) + - Monitor indexer health, check epoch progression, verify logs + +7. **Cycle 7: End-to-End Workflow** (1 test) + - Complete operational cycle from allocation to revenue collection + +### REO-Specific Tests (ReoTestPlan) + +1. **Eligibility State Transitions** + - Validation toggle, renewals, expiry, oracle timeout fail-open + +2. **Role-Based Operations** + - Governor, Operator, Oracle, Pause role actions and access control + +3. **Integration with RewardsManager** + - Eligible indexer rewards, ineligible indexer denial, reclaim flows + +4. **Edge Cases** + - Large eligibility period, same-block re-renewal, configuration races + +5. **Deployment Verification** + - Post-deploy role checks, parameter validation, proxy consistency + +### Reward Conditions Tests (RewardsConditionsTestPlan) + +1. **Reclaim System Configuration** + - Per-condition addresses, default fallback, routing verification, access control + +2. **Below-Minimum Signal** + - Threshold changes, accumulator freeze, reclaim, restoration + +3. **Zero Allocated Tokens** + - Detection, reclaim, allocation resumption from stored baseline + +4. **POI Presentation Paths** + - Normal claim (NONE), stale POI reclaim, zero POI reclaim, too-young deferral + +5. **Allocation Lifecycle** + - Stale resize reclaim, non-stale resize pass-through, close allocation reclaim + +6. **Observability** + - POIPresented event on every presentation, RewardsReclaimed event context, view function freeze + +### Subgraph Denial Tests (SubgraphDenialTestPlan) + +1. **Denial State Management** + - setDenied, isDenied, idempotent deny, access control + +2. **Accumulator Freeze** + - accRewardsForSubgraph freeze, getRewards freeze, reclaim during denial + +3. **Allocation-Level Deferral** + - POI defers (preserves rewards), multiple defers safe, continued POI presentation + +4. **Undeny and Recovery** + - Accumulator resumption, pre-denial rewards claimable, denial-period exclusion + +5. **Edge Cases** + - New allocation while denied, all-close-while-denied, rapid deny/undeny, denial vs eligibility precedence + +See also: [IssuanceAllocatorTestPlan](support/IssuanceAllocatorTestPlan.md) (independent of REO, pending deployment) + +## Network Configuration + +| Network | Environment | Explorer | Gateway | +| ---------------- | ----------- | --------------------------------------- | -------------------------------------- | +| Arbitrum Sepolia | Testnet | | | +| Arbitrum One | Mainnet | | | + +## Testing Approach + +1. **Testnet first** - All tests validated on Arbitrum Sepolia before mainnet +2. **Reusable baseline** - Upgrade-agnostic tests reused across protocol upgrades +3. **Incremental** - Baseline confidence first, then upgrade-specific scenarios +4. **Three-layer validation** - Standard operations + REO eligibility + reward conditions/denial + +--- + +_Test plans developed for The Graph Protocol issuance upgrade validation._ diff --git a/packages/issuance/docs/testing/reo/ReoTestPlan.md b/packages/issuance/docs/testing/reo/ReoTestPlan.md new file mode 100644 index 000000000..e8f08459b --- /dev/null +++ b/packages/issuance/docs/testing/reo/ReoTestPlan.md @@ -0,0 +1,1103 @@ +# REO Test Plan: Rewards Eligibility Oracle + +> **Navigation**: [ā† Back to REO Testing](README.md) | [BaselineTestPlan](BaselineTestPlan.md) + +Tests specific to the Rewards Eligibility Oracle upgrade. Run these **after** the [baseline tests](./BaselineTestPlan.md) pass to confirm standard indexer operations are unaffected. + +> All contract reads use `cast call`. All addresses must be **lowercase**. Replace placeholder addresses with actual deployed addresses for your network. + +## Contract Addresses + +| Contract | Arbitrum Sepolia | Arbitrum One | +| -------------------------------- | -------------------------------------------- | ------------ | +| RewardsEligibilityOracle (proxy) | `0x62c2305739cc75f19a3a6d52387ceb3690d99a99` | TBD | +| MockRewardsEligibilityOracle | `0x5FB23365F8cf643D5f1459E9793EfF7254522400` | N/A | +| RewardsManager (proxy) | `0x1f49cae7669086c8ba53cc35d1e9f80176d67e79` | TBD | +| GraphToken (L2) | `0xf8c05dcf59e8b28bfd5eed176c562bebcfc7ac04` | TBD | + +**Address sources**: `packages/issuance/addresses.json` (REO), `packages/horizon/addresses.json` (RewardsManager, GraphToken) in the `post-audit` worktree. + +### RPC + +| Network | RPC URL | +| ---------------- | ---------------------------------------- | +| Arbitrum Sepolia | `https://sepolia-rollup.arbitrum.io/rpc` | + +### Hardhat Tasks + +The deployment package provides Hardhat tasks that read from the address books and handle governance workflow automatically. Run from `packages/deployment` in the `post-audit` worktree: + +```bash +npx hardhat reo:status --network arbitrumSepolia # Full status: config, oracle activity, role holders +npx hardhat reo:enable --network arbitrumSepolia # Enable eligibility validation (requires OPERATOR_ROLE) +npx hardhat reo:disable --network arbitrumSepolia # Disable eligibility validation (requires OPERATOR_ROLE) +``` + +These are alternatives to the raw `cast` commands used below. `reo:status` in particular is useful as a quick check at any point during testing. + +--- + +## Testing Approach + +**Multi-indexer cycling**: Three indexers cycle through eligibility states individually (not simultaneously). Each indexer transitions through eligible/ineligible states in sequence, allowing controlled observation of each transition. + +| Phase | Indexer A | Indexer B | Indexer C | +| ----- | -------------------- | -------------------- | -------------------- | +| 1 | Eligible | -- | -- | +| 2 | Ineligible (expired) | Eligible | -- | +| 3 | Re-renewed | Ineligible (expired) | Eligible | +| 4 | Eligible | Re-renewed | Ineligible (expired) | + +**Oracle control**: Use a dedicated test oracle account (fake oracle) to manually control eligibility state transitions rather than relying on the actual reporting software. Grant ORACLE_ROLE to this account in Cycle 3. + +**Testnet parameter acceleration**: Reduce time-dependent parameters for practical testing: + +| Parameter | Default | Test Value | Purpose | +| --------------------- | -------------------- | ----------------------- | ------------------------------------------ | +| Eligibility period | 14 days (1,209,600s) | 5-10 minutes (300-600s) | Allow expiration within a test session | +| Oracle update timeout | 7 days (604,800s) | 5-10 minutes (300-600s) | Allow fail-open testing without long waits | + +> Testnet epochs are ~554 blocks (~110 minutes) vs ~6,646 blocks (~24h) on mainnet. Issuance rates are adjusted proportionally. + +**Stakeholder coordination**: Discord channel for testing. UI/Explorer team and network subgraph team monitor throughout for display accuracy during denial scenarios. + +--- + +## Execution Phases + +| Phase | Cycles | Activity | +| ----------- | ------ | -------------------------------------------------------------------------------------------------------- | +| Setup | ā€” | Run [BaselineTestPlan](BaselineTestPlan.md) Cycles 1-7, confirm testnet environment | +| REO Phase 1 | 1-3 | Deployment verification, default state, oracle setup | +| REO Phase 2 | 4-5 | Validation enabled, timeout fail-open, begin indexer cycling | +| REO Phase 3 | 6/6m | Integration with rewards -- use mock REO (6m) for fast iteration, production REO (6) for full validation | +| REO Phase 4 | 7-8 | Emergency ops, UI/subgraph verification | +| Wrap-up | ā€” | Results review, cleanup checklist, mainnet readiness assessment | + +--- + +## Execution Notes + +### Roles needed + +Testing requires access to three roles on the REO contract. On Arbitrum Sepolia: + +| Role | Needed for | Current holder | +| ------------- | --------------------------------------------------------- | ------------------------------------------------------------- | +| OPERATOR_ROLE | Enable/disable validation, set periods, grant ORACLE_ROLE | NetworkOperator: `0xade6b8eb69a49b56929c1d4f4b428d791861db6f` | +| ORACLE_ROLE | Renew indexer eligibility | Not yet assigned -- must be granted in Cycle 3 | +| PAUSE_ROLE | Pause/unpause (Cycle 8) | Check with `reo:status` | + +The tester needs the NetworkOperator key (or governance access) to execute Cycles 3-5 and 8. If the tester doesn't hold OPERATOR_ROLE directly, the Hardhat tasks generate governance TX files for Safe multisig execution. + +### Advance planning for Cycle 6 + +Cycle 6 tests reward integration with live indexers. These tests take multiple epochs (~110 minutes each on Sepolia) and require allocations that were opened **before** validation was enabled. Plan ahead: + +1. During **Cycle 2** (validation still disabled): open allocations for at least two indexers on rewarded deployments -- one that will be renewed (for test 6.1) and one that will NOT be renewed (for test 6.2) +2. These allocations need to mature for 2-3 epochs before they can be closed in Cycle 6 +3. When you enable validation in **Cycle 4**, the non-renewed indexer becomes ineligible while their allocation is still open -- this is the setup for test 6.2 + +### Parameter changes during testing + +Tests 4.4, 5.1, and 8.1 temporarily modify live parameters (eligibility period, oracle timeout, pause state). Each test includes a restore step. If a session is interrupted: + +```bash +# Verify and restore defaults +npx hardhat reo:status --network arbitrumSepolia + +# If needed, restore manually (as operator): +cast send "setEligibilityPeriod(uint256)" 1209600 --rpc-url --private-key +cast send "setOracleUpdateTimeout(uint256)" 604800 --rpc-url --private-key +cast send "unpause()" --rpc-url --private-key +``` + +--- + +## Test Sequence Overview + +| Cycle | Area | Tests | Notes | +| ----- | ------------------------------------------------ | ----------- | -------------------------------------------- | +| 1 | Deployment Verification | 1.1 - 1.5 | Read-only, no role access needed | +| 2 | Eligibility: Default State (Validation Disabled) | 2.1 - 2.3 | Open allocations here for Cycle 6 | +| 3 | Oracle Operations | 3.1 - 3.5 | Requires OPERATOR_ROLE + ORACLE_ROLE | +| 4 | Eligibility: Validation Enabled | 4.1 - 4.4 | Requires OPERATOR_ROLE; 4.4 changes params | +| 5 | Eligibility: Timeout Fail-Open | 5.1 - 5.2 | Requires OPERATOR_ROLE; 5.1 changes params | +| 6 | Integration with Rewards | 6.1 - 6.6 | Requires mature allocations from Cycle 2 | +| 6m | Integration with Rewards (Mock REO) | 6.1m - 6.5m | Uses mock REO for direct eligibility control | +| 7 | Emergency Operations | 7.1 - 7.3 | Requires PAUSE_ROLE; changes live state | +| 8 | UI and Subgraph Verification | 8.1 - 8.3 | Coordinate with Explorer and subgraph teams | + +--- + +## Cycle 1: Deployment Verification + +> Tests 1.2, 1.3, and 1.5 can be checked in one step with `npx hardhat reo:status --network arbitrumSepolia`, which displays role holders, configuration, and contract state. The individual `cast` commands below are useful for scripted or more granular verification. + +### 1.1 Verify proxy and implementation + +**Objective**: Confirm the REO proxy points to the correct implementation and bytecode matches expectations. + +**Steps**: + +1. Query the proxy's implementation address +2. Compare deployed bytecode hash against expected artifact + +```bash +# Get implementation address from proxy admin +cast call "getProxyImplementation(address)" --rpc-url + +# Get deployed bytecode hash +cast keccak $(cast code --rpc-url ) +``` + +**Pass Criteria**: + +- Implementation address matches address book (`0x4eb1de98440a39339817bdeeb3b3fff410b0b924` on Sepolia) +- Bytecode hash matches expected artifact hash + +--- + +### 1.2 Verify role assignments + +**Objective**: Confirm the correct accounts hold each role and the deployer has been removed. + +**Steps**: + +```bash +# Role constants +GOVERNOR_ROLE=0x0000... # DEFAULT_ADMIN_ROLE = 0x00 +OPERATOR_ROLE=$(cast keccak "OPERATOR_ROLE") +ORACLE_ROLE=$(cast keccak "ORACLE_ROLE") +PAUSE_ROLE=$(cast keccak "PAUSE_ROLE") + +# Check role assignments +cast call "hasRole(bytes32,address)(bool)" $GOVERNOR_ROLE --rpc-url +cast call "hasRole(bytes32,address)(bool)" $OPERATOR_ROLE --rpc-url +cast call "hasRole(bytes32,address)(bool)" $PAUSE_ROLE --rpc-url + +# Verify deployer does NOT have governor role +cast call "hasRole(bytes32,address)(bool)" $GOVERNOR_ROLE --rpc-url +``` + +**Pass Criteria**: + +- Governor address has GOVERNOR_ROLE: `true` +- Operator address has OPERATOR_ROLE: `true` +- Pause guardian has PAUSE_ROLE: `true` +- Deployer does NOT have GOVERNOR_ROLE: `false` + +--- + +### 1.3 Verify default parameters + +**Objective**: Confirm the REO is deployed with expected default configuration. + +**Steps**: + +```bash +cast call "getEligibilityPeriod()(uint256)" --rpc-url +cast call "getOracleUpdateTimeout()(uint256)" --rpc-url +cast call "getEligibilityValidation()(bool)" --rpc-url +cast call "getLastOracleUpdateTime()(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- `eligibilityPeriod` = `1209600` (14 days in seconds) +- `oracleUpdateTimeout` = `604800` (7 days in seconds) +- `eligibilityValidation` = `false` (disabled by default) +- `lastOracleUpdateTime` = `0` (no oracle updates yet) or reflects actual oracle activity + +--- + +### 1.4 Verify RewardsManager integration + +**Objective**: Confirm the RewardsManager is configured to use the REO for eligibility checks. + +**Steps**: + +```bash +cast call "getRewardsEligibilityOracle()(address)" --rpc-url +``` + +**Pass Criteria**: + +- Returns the REO proxy address + +--- + +### 1.5 Verify contract is not paused + +**Objective**: Confirm the REO is operational. + +**Steps**: + +```bash +cast call "paused()(bool)" --rpc-url +``` + +**Pass Criteria**: + +- Returns `false` + +--- + +## Cycle 2: Eligibility -- Default State (Validation Disabled) + +### 2.1 All indexers eligible when validation disabled + +**Objective**: With validation disabled (default), every indexer should be eligible regardless of renewal status. + +**Steps**: + +1. Confirm validation is disabled +2. Check eligibility for a known indexer +3. Check eligibility for a random address that has never been renewed + +```bash +# Confirm validation disabled +cast call "getEligibilityValidation()(bool)" --rpc-url + +# Known indexer +cast call "isEligible(address)(bool)" --rpc-url + +# Random/never-renewed address +cast call "isEligible(address)(bool)" 0x0000000000000000000000000000000000000001 --rpc-url +``` + +**Pass Criteria**: + +- `getEligibilityValidation()` = `false` +- Both addresses return `isEligible` = `true` + +--- + +### 2.2 Indexer with no renewal history is eligible + +**Objective**: Confirm that an indexer with zero renewal timestamp is still eligible when validation is disabled. + +**Steps**: + +```bash +cast call "getEligibilityRenewalTime(address)(uint256)" --rpc-url +cast call "isEligible(address)(bool)" --rpc-url +``` + +**Pass Criteria**: + +- `getEligibilityRenewalTime` = `0` +- `isEligible` = `true` + +--- + +### 2.3 Rewards still flow with validation disabled + +**Objective**: Confirm the baseline rewards flow is unaffected by the REO when validation is off. + +**Prerequisites**: Indexer has an active allocation on a rewarded deployment, open for at least 2 epochs. This should already exist from running [Baseline Cycle 4](./BaselineTestPlan.md#cycle-4-allocation-management). + +> **Cross-reference**: The allocations opened here (and in [Baseline Cycles 4-5](./BaselineTestPlan.md#cycle-4-allocation-management)) serve as setup for [Cycle 6](#cycle-6-integration-with-rewards) reward integration tests. Open extra allocations now for the indexers you plan to cycle through eligibility states. + +**Steps**: Close the allocation per [Baseline 5.2](./BaselineTestPlan.md#52-close-allocation-and-collect-indexing-rewards) and verify rewards. + +> **Advance setup for Cycle 6**: Before moving to Cycle 3, open allocations for the indexers you plan to use in Cycle 6. You need at least: +> +> - One allocation for a **renewed** indexer (test 6.1 -- will receive rewards) +> - One allocation for a **non-renewed** indexer (test 6.2 -- will be denied rewards) +> +> These allocations must mature for 2-3 epochs before Cycle 6. Since validation is still disabled, both will accrue potential rewards. Use [Baseline 4.2](./BaselineTestPlan.md#42-create-allocation-manually) to create them. + +**Pass Criteria**: + +- Indexing rewards are non-zero on allocation closure +- No change in behavior from baseline + +--- + +## Cycle 3: Oracle Operations + +### 3.1 Grant oracle role + +**Objective**: Verify an operator can grant ORACLE_ROLE to an oracle address. + +**Prerequisites**: Transaction signed by OPERATOR_ROLE holder. + +**Steps**: + +```bash +# Grant oracle role (as operator) +cast send "grantRole(bytes32,address)" $ORACLE_ROLE --rpc-url --private-key + +# Verify +cast call "hasRole(bytes32,address)(bool)" $ORACLE_ROLE --rpc-url +``` + +**Pass Criteria**: + +- Transaction succeeds +- `hasRole` returns `true` for the oracle address + +--- + +### 3.2 Renew single indexer eligibility + +**Objective**: Verify an oracle can renew eligibility for a single indexer. + +**Prerequisites**: Caller has ORACLE_ROLE. + +**Steps**: + +```bash +# Renew eligibility for one indexer +cast send "renewIndexerEligibility(address[],bytes)" "[]" "0x" --rpc-url --private-key + +# Check renewal timestamp +cast call "getEligibilityRenewalTime(address)(uint256)" --rpc-url + +# Check last oracle update time +cast call "getLastOracleUpdateTime()(uint256)" --rpc-url +``` + +**Verification**: Check for emitted events: + +- `IndexerEligibilityRenewed(indexer, oracle)` +- `IndexerEligibilityData(oracle, data)` + +**Pass Criteria**: + +- Transaction succeeds, returns count `1` +- `getEligibilityRenewalTime` is approximately `block.timestamp` of the renewal tx +- `lastOracleUpdateTime` updated to the same timestamp +- Events emitted correctly + +--- + +### 3.3 Renew multiple indexers in batch + +**Objective**: Verify batch renewal works correctly. + +**Steps**: + +```bash +cast send "renewIndexerEligibility(address[],bytes)" "[,,]" "0x" --rpc-url --private-key +``` + +**Verification**: Check renewal timestamps for all three indexers. + +**Pass Criteria**: + +- Transaction succeeds, returns count `3` +- All three indexers have updated renewal timestamps +- One `IndexerEligibilityRenewed` event per indexer + +--- + +### 3.4 Zero addresses skipped in renewal + +**Objective**: Verify zero addresses in the renewal array are silently skipped. + +**Steps**: + +```bash +cast send "renewIndexerEligibility(address[],bytes)" "[0x0000000000000000000000000000000000000000,]" "0x" --rpc-url --private-key +``` + +**Pass Criteria**: + +- Transaction succeeds, returns count `1` (not 2) +- Only the non-zero indexer has a `IndexerEligibilityRenewed` event + +--- + +### 3.5 Unauthorized renewal reverts + +**Objective**: Verify that accounts without ORACLE_ROLE cannot renew eligibility. + +**Steps**: + +```bash +# Attempt renewal from a non-oracle account +cast send "renewIndexerEligibility(address[],bytes)" "[]" "0x" --rpc-url --private-key +``` + +**Pass Criteria**: + +- Transaction reverts with AccessControl error + +--- + +## Cycle 4: Eligibility -- Validation Enabled + +### 4.1 Enable eligibility validation + +**Objective**: Verify an operator can enable validation, switching from "all eligible" to oracle-based eligibility. + +**Prerequisites**: OPERATOR_ROLE holder. Some indexers should have been renewed (Cycle 3), others not. + +> **Before enabling**: Confirm the allocations you opened during Cycle 2 for Cycle 6 testing are still active. Once validation is enabled, any non-renewed indexer with an open allocation becomes ineligible for rewards -- this is the intended setup for test 6.2. + +**Steps**: + +```bash +# Enable validation (alternative: npx hardhat reo:enable --network arbitrumSepolia) +cast send "setEligibilityValidation(bool)" true --rpc-url --private-key + +# Verify +cast call "getEligibilityValidation()(bool)" --rpc-url +``` + +**Verification**: Check for `EligibilityValidationUpdated(true)` event. + +**Pass Criteria**: + +- Transaction succeeds +- `getEligibilityValidation()` = `true` + +--- + +### 4.2 Renewed indexer is eligible + +**Objective**: After enabling validation, a recently renewed indexer should still be eligible. + +**Prerequisites**: Indexer was renewed in Cycle 3. Validation is enabled (4.1). + +**Steps**: + +```bash +cast call "isEligible(address)(bool)" --rpc-url +cast call "getEligibilityRenewalTime(address)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- `isEligible` = `true` +- `getEligibilityRenewalTime` is within the last `eligibilityPeriod` (14 days) + +--- + +### 4.3 Non-renewed indexer is NOT eligible + +**Objective**: An indexer that was never renewed should be ineligible when validation is enabled. + +**Steps**: + +```bash +cast call "isEligible(address)(bool)" --rpc-url +cast call "getEligibilityRenewalTime(address)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- `isEligible` = `false` +- `getEligibilityRenewalTime` = `0` + +--- + +### 4.4 Eligibility expires after period + +**Objective**: Verify that an indexer's eligibility expires when the eligibility period has passed since their last renewal. + +**Approach**: This is easiest to test by temporarily reducing the eligibility period to a short duration. + +**Steps**: + +1. Renew an indexer's eligibility +2. Reduce eligibility period to a short value (e.g., 60 seconds) +3. Wait for the period to elapse +4. Check eligibility + +```bash +# Renew indexer +cast send "renewIndexerEligibility(address[],bytes)" "[]" "0x" --rpc-url --private-key + +# Reduce period to 60 seconds (as operator) +cast send "setEligibilityPeriod(uint256)" 60 --rpc-url --private-key + +# Immediately check -- should still be eligible +cast call "isEligible(address)(bool)" --rpc-url + +# Wait 60+ seconds, then check again +sleep 65 +cast call "isEligible(address)(bool)" --rpc-url + +# IMPORTANT: Restore eligibility period to default +cast send "setEligibilityPeriod(uint256)" 1209600 --rpc-url --private-key +``` + +**Pass Criteria**: + +- First check (immediately after renewal): `isEligible` = `true` +- Second check (after period elapsed): `isEligible` = `false` +- Eligibility period restored to default + +--- + +## Cycle 5: Eligibility -- Timeout Fail-Open + +### 5.1 Oracle timeout makes all indexers eligible + +**Objective**: Verify the fail-open mechanism: if no oracle updates occur for longer than `oracleUpdateTimeout`, all indexers become eligible. + +**Approach**: Reduce the oracle timeout to a short duration and wait. + +**Prerequisites**: Validation enabled (4.1). At least one indexer is NOT renewed (should be ineligible). + +**Steps**: + +```bash +# Confirm non-renewed indexer is currently ineligible +cast call "isEligible(address)(bool)" --rpc-url +# Expected: false + +# Reduce oracle timeout to 60 seconds (as operator) +cast send "setOracleUpdateTimeout(uint256)" 60 --rpc-url --private-key + +# Wait for timeout to elapse +sleep 65 + +# Check -- should now be eligible due to fail-open +cast call "isEligible(address)(bool)" --rpc-url + +# IMPORTANT: Restore oracle timeout to default +cast send "setOracleUpdateTimeout(uint256)" 604800 --rpc-url --private-key +``` + +**Pass Criteria**: + +- Before timeout: `isEligible` = `false` +- After timeout: `isEligible` = `true` +- Timeout restored to default + +--- + +### 5.2 Oracle renewal resets timeout + +**Objective**: Verify that an oracle renewal resets the `lastOracleUpdateTime`, closing the fail-open window. + +**Steps**: + +```bash +# Record current lastOracleUpdateTime +cast call "getLastOracleUpdateTime()(uint256)" --rpc-url + +# Renew any indexer +cast send "renewIndexerEligibility(address[],bytes)" "[]" "0x" --rpc-url --private-key + +# Check lastOracleUpdateTime again +cast call "getLastOracleUpdateTime()(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- `lastOracleUpdateTime` updated to the block timestamp of the renewal transaction + +--- + +## Cycle 6: Integration with Rewards + +These tests verify the end-to-end interaction between the REO and the rewards system using live indexers. + +> **Timing**: These tests require allocations that have been open for 2-3 epochs (~3.5-5.5 hours on Sepolia). The allocations should have been opened during Cycle 2, before validation was enabled. If they weren't, you'll need to open them now and wait before proceeding. Cycles 7 and 8 can be run while waiting. + +### Mock REO Quick-Test Path + +A `MockRewardsEligibilityOracle` is deployed at `0x5FB23365F8cf643D5f1459E9793EfF7254522400` on Arbitrum Sepolia. This provides direct, instant control over eligibility without oracle roles, renewal periods, or timeout logic. Use it for faster iteration on the Cycle 6 integration tests. + +**How the mock works**: Everyone starts eligible. Indexers call `setEligible(false)` from their own address to become ineligible, and `setEligible(true)` to restore eligibility. No roles or expiry -- just a toggle. + +**Setup**: Point RewardsManager at the mock (requires Governor): + +```bash +MOCK_REO=0x5FB23365F8cf643D5f1459E9793EfF7254522400 + +# Point RewardsManager to mock REO +cast send $REWARDS_MANAGER "setRewardsEligibilityOracle(address)" $MOCK_REO \ + --rpc-url $RPC --private-key $GOVERNOR_KEY + +# Verify +cast call $REWARDS_MANAGER "getRewardsEligibilityOracle()(address)" --rpc-url $RPC +# Expected: 0x5FB23365F8cf643D5f1459E9793EfF7254522400 +``` + +**Control eligibility**: + +```bash +# Query eligibility for any address +cast call $MOCK_REO "isEligible(address)(bool)" --rpc-url $RPC + +# Make yourself ineligible (signed by the indexer) +cast send $MOCK_REO "setEligible(bool)" false --rpc-url $RPC --private-key $INDEXER_KEY + +# Restore eligibility +cast send $MOCK_REO "setEligible(bool)" true --rpc-url $RPC --private-key $INDEXER_KEY +``` + +**After testing**: Restore the production REO on RewardsManager: + +```bash +cast send $REWARDS_MANAGER "setRewardsEligibilityOracle(address)" 0x62c2305739cc75f19a3a6d52387ceb3690d99a99 \ + --rpc-url $RPC --private-key $GOVERNOR_KEY +``` + +> The mock-based tests below (6.1m-6.5m) are equivalents of tests 6.1-6.5 using the mock for eligibility control. They can be run instead of or in addition to the production REO tests. The mock path eliminates time-dependent waits and simplifies the setup, making it the recommended approach for initial integration validation. + +### 6.1 Eligible indexer receives indexing rewards + +**Objective**: Confirm that a renewed (eligible) indexer receives rewards when closing an allocation. + +**Prerequisites**: Validation enabled (Cycle 4). Indexer renewed by oracle (Cycle 3). Indexer has an active allocation open for several epochs on a rewarded deployment (opened during Cycle 2). + +**Steps**: + +1. Confirm eligibility: `isEligible(indexer)` = `true` +2. Close allocation per [Baseline 5.2](./BaselineTestPlan.md#52-close-allocation-and-collect-indexing-rewards) +3. Check rewards + +**Verification Query**: + +```graphql +{ + allocations(where: { id: "ALLOCATION_ID" }) { + id + status + indexingRewards + closedAtEpoch + } +} +``` + +**Pass Criteria**: + +- `indexingRewards` is non-zero +- Rewards amount is consistent with allocation size and epoch duration + +--- + +### 6.2 Ineligible indexer denied rewards + +**Objective**: Confirm that a non-renewed (ineligible) indexer receives zero rewards when closing an allocation. + +**Prerequisites**: Validation enabled (Cycle 4). Indexer has NOT been renewed by the oracle. Indexer has an active allocation on a rewarded deployment that was opened during Cycle 2 (before validation was enabled). + +**Steps**: + +1. Confirm ineligibility: `isEligible(indexer)` = `false` +2. Close allocation +3. Check rewards + +**Pass Criteria**: + +- `indexingRewards` = `0` +- Allocation still transitions to `Closed` status (closure succeeds, just no rewards) + +--- + +### 6.3 Reclaimed rewards flow to reclaim contract + +**Objective**: When an ineligible indexer is denied rewards, verify the denied rewards are routed to the `ReclaimedRewardsForIndexerIneligible` contract. + +**Prerequisites**: Same as 6.2. + +**Steps**: + +1. Close allocation for ineligible indexer +2. Check the reclaim contract balance or events + +```bash +# Check for RewardsDeniedDueToEligibility event on RewardsManager +# (implementation detail -- exact event name may vary) +cast logs --from-block --to-block --address --rpc-url +``` + +**Pass Criteria**: + +- Denied rewards event emitted +- Reclaim contract receives the tokens that would have been the indexer's rewards + +--- + +### 6.4 Re-renewal restores reward eligibility + +**Objective**: After an indexer's eligibility expires and they are denied rewards, verify that a new oracle renewal restores their ability to earn rewards. + +> **Timing**: This test requires opening a new allocation and waiting 2-3 epochs (~3.5-5.5 hours). It can be run as the final validation step, or skipped on testnet if time is constrained and covered by the combination of 6.2 + Cycle 3 (which together demonstrate the renewal mechanism works). + +**Steps**: + +1. Confirm indexer is currently ineligible (the indexer from test 6.2) +2. Renew the indexer via oracle (as in test 3.2) +3. Confirm eligibility restored: `isEligible` = `true` +4. Open new allocation, wait 2-3 epochs, close, check rewards + +**Pass Criteria**: + +- After renewal: `isEligible` = `true` +- New allocation closure yields non-zero `indexingRewards` + +--- + +### 6.5 View functions reflect zero for ineligible indexer + +**Objective**: Verify that RewardsManager view functions do not over-report claimable rewards for an ineligible indexer. Previously, view functions could show unclaimable balances, misleading indexers into thinking they had earned rewards. + +**Prerequisites**: Validation enabled. Indexer is ineligible. Indexer has an active allocation that has been open several epochs. + +**Steps**: + +1. Confirm ineligibility: `isEligible(indexer)` = `false` +2. Query the view function for pending rewards on the allocation + +```bash +# Check pending rewards for an active allocation +cast call "getRewards(bytes32)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Returns `0` (or near-zero), not the full accumulated amount +- This prevents the UI from displaying rewards the indexer cannot actually claim + +--- + +### 6.6 Eligibility denial is optimistic -- full rewards after re-renewal + +**Objective**: Verify that rewards continue accumulating during an ineligible period (optimistic model). After re-renewal, closing the allocation yields the full accumulated amount including epochs where the indexer was ineligible. This differs from subgraph denial, which permanently stops accumulation. + +**Prerequisites**: Indexer has an active allocation open for several epochs. Indexer was eligible when allocation was opened. + +**Steps**: + +1. Confirm indexer is currently eligible with an active allocation +2. Let eligibility expire (or reduce eligibility period as in test 4.4) +3. Confirm `isEligible(indexer)` = `false` +4. Wait 1-2 additional epochs while ineligible +5. Re-renew the indexer via oracle +6. Confirm `isEligible(indexer)` = `true` +7. Close allocation and check rewards + +**Pass Criteria**: + +- `indexingRewards` reflects the full allocation lifetime (eligible + ineligible epochs) +- Amount is comparable to what a continuously-eligible indexer would earn for the same period +- Temporary ineligibility does not cause permanent reward loss + +--- + +### Mock-Based Integration Tests (6.1m - 6.5m) + +These tests use the `MockRewardsEligibilityOracle` at `0x5FB23365F8cf643D5f1459E9793EfF7254522400` for direct eligibility control. See [Mock REO Quick-Test Path](#mock-reo-quick-test-path) above for setup. + +**Prerequisites**: RewardsManager pointed at the mock REO. Indexer has active allocations open for at least 1 epoch. + +#### 6.1m Eligible indexer receives rewards (mock) + +**Objective**: Confirm that an eligible indexer receives rewards when closing an allocation. + +**Steps**: + +```bash +MOCK_REO=0x5FB23365F8cf643D5f1459E9793EfF7254522400 + +# Confirm eligible (default state) +cast call $MOCK_REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: true + +# Close allocation +graph indexer actions queue close +graph indexer actions approve +``` + +**Pass Criteria**: + +- `indexingRewards` is non-zero + +--- + +#### 6.2m Ineligible indexer denied rewards (mock) + +**Objective**: Confirm that toggling eligibility off causes reward denial. + +**Steps**: + +```bash +# Make indexer ineligible +cast send $MOCK_REO "setEligible(bool)" false --rpc-url $RPC --private-key $INDEXER_KEY + +# Confirm +cast call $MOCK_REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: false + +# Close allocation +graph indexer actions queue close +graph indexer actions approve +``` + +**Pass Criteria**: + +- `indexingRewards` = `0` +- Allocation still transitions to `Closed` status + +--- + +#### 6.3m Reclaimed rewards flow to reclaim contract (mock) + +**Objective**: When the mock makes an indexer ineligible, denied rewards are routed to the reclaim contract. + +**Prerequisites**: Indexer set to ineligible via mock (6.2m). + +**Steps**: + +```bash +# Check for denial event on the close transaction from 6.2m +cast logs --from-block --to-block --address $REWARDS_MANAGER --rpc-url $RPC +``` + +**Pass Criteria**: + +- Denied rewards event emitted +- Reclaim contract receives the denied tokens + +--- + +#### 6.4m View functions reflect zero for ineligible indexer (mock) + +**Objective**: Verify pending rewards show zero while ineligible. + +**Prerequisites**: Indexer ineligible via mock. Active allocation open for several epochs. + +**Steps**: + +```bash +# Confirm ineligible +cast call $MOCK_REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: false + +# Check pending rewards +cast call $REWARDS_MANAGER "getRewards(bytes32)(uint256)" --rpc-url $RPC +``` + +**Pass Criteria**: + +- Returns `0` (or near-zero), not the full accumulated amount + +--- + +#### 6.5m Optimistic recovery -- full rewards after re-enabling (mock) + +**Objective**: Verify the optimistic model: toggle ineligible, wait, toggle back, and confirm full rewards on close. + +**Steps**: + +```bash +# Ensure indexer has an active allocation open across multiple epochs + +# 1. Toggle ineligible +cast send $MOCK_REO "setEligible(bool)" false --rpc-url $RPC --private-key $INDEXER_KEY +cast call $MOCK_REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: false + +# 2. Wait 1-2 epochs while ineligible (~110-220 min on Sepolia) + +# 3. Toggle eligible again +cast send $MOCK_REO "setEligible(bool)" true --rpc-url $RPC --private-key $INDEXER_KEY +cast call $MOCK_REO "isEligible(address)(bool)" $INDEXER --rpc-url $RPC +# Expected: true + +# 4. Close allocation +graph indexer actions queue close +graph indexer actions approve +``` + +**Pass Criteria**: + +- `indexingRewards` reflects the full allocation lifetime (eligible + ineligible epochs) +- Temporary ineligibility does not cause permanent reward loss +- Compare with 6.1m: this allocation was open longer and should have proportionally more rewards + +--- + +## Cycle 7: Emergency Operations + +### 7.1 Pause REO + +**Objective**: Verify the pause guardian can pause the REO. + +**Prerequisites**: Caller has PAUSE_ROLE. + +**Steps**: + +```bash +# Pause +cast send "pause()" --rpc-url --private-key + +# Verify paused +cast call "paused()(bool)" --rpc-url + +# View functions should still work +cast call "isEligible(address)(bool)" --rpc-url + +# IMPORTANT: Unpause when done +cast send "unpause()" --rpc-url --private-key +``` + +**Pass Criteria**: + +- Pause succeeds, `paused()` = `true` +- View functions (`isEligible`) still return results +- Oracle write operations (`renewIndexerEligibility`) revert while paused +- Unpause succeeds, `paused()` = `false` + +--- + +### 7.2 Disable eligibility validation (emergency override) + +**Objective**: Verify an operator can disable validation to immediately make all indexers eligible. + +**Steps**: + +```bash +# Disable validation (alternative: npx hardhat reo:disable --network arbitrumSepolia) +cast send "setEligibilityValidation(bool)" false --rpc-url --private-key + +# Previously ineligible indexer should now be eligible +cast call "isEligible(address)(bool)" --rpc-url +``` + +**Pass Criteria**: + +- Transaction succeeds +- All indexers return `isEligible` = `true` + +--- + +### 7.3 Access control prevents unauthorized configuration + +**Objective**: Verify that only authorized roles can perform privileged operations. + +**Steps** (all should revert): + +```bash +# Non-operator tries to set eligibility period +cast send "setEligibilityPeriod(uint256)" 100 --rpc-url --private-key + +# Non-operator tries to enable validation +cast send "setEligibilityValidation(bool)" true --rpc-url --private-key + +# Non-pause-role tries to pause +cast send "pause()" --rpc-url --private-key +``` + +**Pass Criteria**: + +- All three transactions revert with AccessControl errors + +--- + +## Cycle 8: UI and Subgraph Verification + +These tests verify that the Graph Explorer and network subgraph correctly reflect eligibility states and denial scenarios. Run these in coordination with the Explorer and subgraph teams. + +### 8.1 Explorer displays correct rewards during denial + +**Objective**: Verify that the Graph Explorer does not show incorrect indexing reward amounts when an indexer is ineligible and claims are denied. + +**Prerequisites**: At least one indexer is ineligible with an active allocation. Explorer team monitoring. + +**Steps**: + +1. Open Explorer to the ineligible indexer's profile +2. Check displayed pending rewards for active allocations +3. Close allocation (will be denied rewards) +4. Verify Explorer updates to reflect the actual outcome (zero rewards) + +**Pass Criteria**: + +- Explorer does not display inflated or false pending rewards for ineligible indexers +- After allocation closure with denial, Explorer shows `0` indexing rewards for that allocation +- No discrepancy between on-chain state and Explorer display + +--- + +### 8.2 Network subgraph reflects eligibility transitions + +**Objective**: Verify the network subgraph correctly indexes eligibility renewal events and displays accurate stake/delegation amounts through state transitions. + +**Steps**: + +1. Renew indexer eligibility via oracle +2. Query network subgraph for the indexer +3. Let eligibility expire +4. Query again and compare + +```graphql +{ + indexers(where: { id: "INDEXER_ADDRESS" }) { + id + stakedTokens + delegatedTokens + allocatedTokens + rewardsEarned + } +} +``` + +**Pass Criteria**: + +- `stakedTokens` and `delegatedTokens` remain accurate regardless of eligibility state +- Subgraph does not show incorrect amounts during eligibility transitions +- No indexing errors in the subgraph during REO-related transactions + +--- + +### 8.3 Denied transaction appears correct in Explorer history + +**Objective**: When an ineligible indexer closes an allocation and rewards are denied, the transaction should not appear "successful" in a way that misleads the indexer. + +**Steps**: + +1. Close allocation for an ineligible indexer +2. Check the transaction in Explorer's history view +3. Verify the displayed outcome matches reality (0 rewards) + +**Pass Criteria**: + +- Transaction status is clear (not misleadingly shown as a successful reward claim) +- Reward amount displayed is `0` or clearly indicates denial +- Explorer team confirms no confusing UX for the indexer + +--- + +## Post-Testing Cleanup Checklist + +Run `npx hardhat reo:status --network arbitrumSepolia` to verify. Ensure the REO is left in the expected state: + +- [ ] `eligibilityValidation` set to intended value (disabled or enabled per rollout plan) +- [ ] `eligibilityPeriod` = `1209600` (14 days) +- [ ] `oracleUpdateTimeout` = `604800` (7 days) +- [ ] Contract is NOT paused +- [ ] Oracle roles assigned to intended oracle addresses only +- [ ] No test accounts retain elevated roles +- [ ] If mock REO was used: RewardsManager points back to the production REO (`0x62c2305739cc75f19a3a6d52387ceb3690d99a99`) + +--- + +## Monitoring Checklist + +After the upgrade is live, continuously monitor: + +- [ ] `IndexerEligibilityRenewed` events flowing regularly from oracles +- [ ] `lastOracleUpdateTime` advancing (oracles are active) +- [ ] No `RewardsDeniedDueToEligibility` events for indexers that should be eligible +- [ ] Epoch progression and total rewards issuance unchanged from pre-upgrade baseline + +--- + +## Related Documentation + +- [ā† Back to REO Testing](README.md) +- [BaselineTestPlan.md](BaselineTestPlan.md) - Baseline operational tests (run first) + +--- + +_Derived from REO contract specification and audit reports. Source contracts: `/packages/issuance/contracts/eligibility/`_ diff --git a/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md b/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md new file mode 100644 index 000000000..b665e0b58 --- /dev/null +++ b/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md @@ -0,0 +1,781 @@ +# Rewards Conditions Test Plan + +> **Status: Complete** ā€” Local network automation validates Cycles 1-4 and 6. Cycles 5 (resize) and 7 (zero signal) need testnet or special setup. +> +> **Navigation**: [ā† Back to REO Testing](README.md) | [BaselineTestPlan](BaselineTestPlan.md) | [SubgraphDenialTestPlan](SubgraphDenialTestPlan.md) + +Tests for the reclaim system, signal-related conditions, POI presentation paths, allocation lifecycle changes, and observability improvements introduced in the issuance upgrade. + +These tests cover all reward conditions **except** `INDEXER_INELIGIBLE` (covered by [ReoTestPlan](ReoTestPlan.md)) and `SUBGRAPH_DENIED` (covered by [SubgraphDenialTestPlan](SubgraphDenialTestPlan.md)). + +> All contract reads use `cast call`. All addresses must be **lowercase**. Replace placeholder addresses with actual deployed addresses for your network. + +## Contract Addresses + +| Contract | Arbitrum Sepolia | Arbitrum One | +| ----------------------- | -------------------------------------------- | -------------------------------------------- | +| RewardsManager (proxy) | `0x1f49cae7669086c8ba53cc35d1e9f80176d67e79` | `0x971b9d3d0ae3eca029cab5ea1fb0f72c85e6a525` | +| SubgraphService (proxy) | `0xc24a3dac5d06d771f657a48b20ce1a671b78f26b` | `0xb2bb92d0de618878e438b55d5846cfecd9301105` | +| GraphToken (L2) | `0xf8c05dcf59e8b28bfd5eed176c562bebcfc7ac04` | `0x9623063377ad1b27544c965ccd7342f7ea7e88c7` | +| Controller | `0x9db3ee191681f092607035d9bda6e59fbeaca695` | `0x0a8491544221dd212964fbb96487467291b2c97e` | + +### RPC + +| Network | RPC URL | +| ---------------- | ---------------------------------------- | +| Arbitrum Sepolia | `https://sepolia-rollup.arbitrum.io/rpc` | + +--- + +## Background + +The issuance upgrade introduces a `RewardsCondition` system that classifies every situation where rewards cannot be distributed normally. Instead of silently dropping undistributable rewards, each condition has a defined handling path: + +- **Reclaim**: Mint to a configured address (per-condition or default fallback) +- **Defer**: Preserve for later collection (snapshot not advanced) + +This test plan validates the reclaim infrastructure, each condition's handling, and the new observability features. + +--- + +## Prerequisites + +- [Baseline tests](BaselineTestPlan.md) Cycles 1-7 pass +- Governor access for reclaim address configuration +- SAO or Governor access for `setMinimumSubgraphSignal()` +- At least two indexers with active allocations +- Access to subgraph deployments with varying signal levels + +--- + +## Test Sequence Overview + +| Cycle | Area | Tests | Notes | +| ----- | ---------------------------- | --------- | -------------------------------------------------- | +| 1 | Reclaim System Configuration | 1.1 - 1.5 | Governor access needed | +| 2 | Below-Minimum Signal | 2.1 - 2.4 | Governor/SAO access; signal threshold changes | +| 3 | Zero Allocated Tokens | 3.1 - 3.3 | Requires subgraph with signal but no allocations | +| 4 | POI Presentation Paths | 4.1 - 4.5 | Requires mature and young allocations | +| 5 | Allocation Lifecycle | 5.1 - 5.3 | Resize and close operations | +| 6 | Observability | 6.1 - 6.3 | Event and view function verification | +| 7 | Zero Global Signal | 7.1 - 7.2 | Difficult on shared testnet; may be unit-test only | + +--- + +## Cycle 1: Reclaim System Configuration + +### 1.1 Configure per-condition reclaim addresses + +**Objective**: Set reclaim addresses for each condition and verify the routing. + +**Steps**: + +```bash +# Compute condition identifiers +NO_SIGNAL=$(cast keccak "NO_SIGNAL") +SUBGRAPH_DENIED=$(cast keccak "SUBGRAPH_DENIED") +BELOW_MINIMUM_SIGNAL=$(cast keccak "BELOW_MINIMUM_SIGNAL") +NO_ALLOCATED_TOKENS=$(cast keccak "NO_ALLOCATED_TOKENS") +STALE_POI=$(cast keccak "STALE_POI") +ZERO_POI=$(cast keccak "ZERO_POI") +CLOSE_ALLOCATION=$(cast keccak "CLOSE_ALLOCATION") +INDEXER_INELIGIBLE=$(cast keccak "INDEXER_INELIGIBLE") + +# Set per-condition reclaim addresses (as Governor) +# Using a single address for simplicity; in production these may differ +cast send "setReclaimAddress(bytes32,address)" $NO_SIGNAL --rpc-url --private-key + +cast send "setReclaimAddress(bytes32,address)" $BELOW_MINIMUM_SIGNAL --rpc-url --private-key + +cast send "setReclaimAddress(bytes32,address)" $NO_ALLOCATED_TOKENS --rpc-url --private-key + +cast send "setReclaimAddress(bytes32,address)" $STALE_POI --rpc-url --private-key + +cast send "setReclaimAddress(bytes32,address)" $ZERO_POI --rpc-url --private-key + +cast send "setReclaimAddress(bytes32,address)" $CLOSE_ALLOCATION --rpc-url --private-key + +# Verify each +cast call "getReclaimAddress(bytes32)(address)" $STALE_POI --rpc-url +cast call "getReclaimAddress(bytes32)(address)" $ZERO_POI --rpc-url +cast call "getReclaimAddress(bytes32)(address)" $CLOSE_ALLOCATION --rpc-url +``` + +**Pass Criteria**: + +- Each `setReclaimAddress` transaction succeeds +- `ReclaimAddressSet` event emitted for each +- `getReclaimAddress()` returns the correct address for each condition + +--- + +### 1.2 Configure default reclaim address + +**Objective**: Set the fallback reclaim address used when no per-condition address is configured. + +**Steps**: + +```bash +# Set default reclaim address (as Governor) +cast send "setDefaultReclaimAddress(address)" --rpc-url --private-key + +# Verify +cast call "getDefaultReclaimAddress()(address)" --rpc-url +``` + +**Pass Criteria**: + +- Transaction succeeds +- `DefaultReclaimAddressSet` event emitted +- `getDefaultReclaimAddress()` returns the configured address + +--- + +### 1.3 Verify fallback routing: unconfigured condition uses default + +**Objective**: A condition with no per-condition address should route to the default address. + +**Steps**: + +```bash +# Use a condition that does NOT have a per-condition address set +# (e.g., skip setting ALTRUISTIC_ALLOCATION in test 1.1) +ALTRUISTIC=$(cast keccak "ALTRUISTIC_ALLOCATION") + +# Verify no per-condition address +cast call "getReclaimAddress(bytes32)(address)" $ALTRUISTIC --rpc-url +# Expected: 0x0000... + +# The default address should catch this (verified by observing reclaim events when triggered) +cast call "getDefaultReclaimAddress()(address)" --rpc-url +``` + +**Pass Criteria**: + +- Per-condition address = `0x0` (not set) +- Default address is configured (non-zero) +- When this condition is triggered, `RewardsReclaimed` event shows tokens going to default address + +--- + +### 1.4 Unauthorized reclaim address change reverts + +**Objective**: Only the Governor can set reclaim addresses. + +**Steps**: + +```bash +# Non-governor attempts to set reclaim address +cast send "setReclaimAddress(bytes32,address)" $STALE_POI --rpc-url --private-key + +# Non-governor attempts to set default reclaim address +cast send "setDefaultReclaimAddress(address)" --rpc-url --private-key +``` + +**Pass Criteria**: + +- Both transactions revert + +--- + +### 1.5 Record baseline balances + +**Objective**: Record GRT balances of all reclaim addresses for comparison during later tests. + +**Steps**: + +```bash +cast call "balanceOf(address)(uint256)" --rpc-url +cast call "balanceOf(address)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Balances recorded for comparison + +--- + +## Cycle 2: Below-Minimum Signal + +### 2.1 Verify current minimum signal threshold + +**Objective**: Check the current `minimumSubgraphSignal` value and identify subgraphs near the threshold. + +**Steps**: + +```bash +# Check current threshold +cast call "minimumSubgraphSignal()(uint256)" --rpc-url +``` + +**Verification Query** (find subgraphs near the threshold): + +```graphql +{ + subgraphDeployments(orderBy: signalledTokens, orderDirection: asc, where: { signalledTokens_gt: 0 }) { + ipfsHash + signalledTokens + stakedTokens + indexingRewardAmount + } +} +``` + +**Pass Criteria**: + +- Threshold value known +- At least one subgraph identified that is close to (or can be made to fall below) the threshold + +--- + +### 2.2 Raise threshold to trigger BELOW_MINIMUM_SIGNAL + +**Objective**: Increase `minimumSubgraphSignal` so that a target subgraph falls below the threshold, then verify rewards are reclaimed. + +> **Important**: Before changing the threshold, call `onSubgraphSignalUpdate()` on affected subgraphs to snapshot accumulators under the current rules. This prevents retroactive application over a long period. + +**Steps**: + +```bash +# Record accumulator for target subgraph +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url + +# Snapshot accumulators before threshold change +cast send "onSubgraphSignalUpdate(bytes32)" --rpc-url --private-key + +# Raise threshold (as Governor or SAO) +cast send "setMinimumSubgraphSignal(uint256)" --rpc-url --private-key + +# Verify threshold changed +cast call "minimumSubgraphSignal()(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Threshold changed successfully +- Target subgraph signal is now below the new threshold + +--- + +### 2.3 Accumulator freezes for below-threshold subgraph + +**Objective**: After the threshold increase, the below-threshold subgraph's accumulators should freeze and new rewards should be reclaimed. + +**Steps**: + +```bash +# Wait some time, then check accumulators +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url + +# Trigger accumulator update to process reclaim +cast send "onSubgraphSignalUpdate(bytes32)" --rpc-url --private-key + +# Check for RewardsReclaimed events +RECLAIM_EVENT_SIG=$(cast sig-event "RewardsReclaimed(bytes32,uint256,address,address,bytes32)") +cast logs --from-block --to-block latest --address --topic0 $RECLAIM_EVENT_SIG --rpc-url +``` + +**Pass Criteria**: + +- `accRewardsForSubgraph` frozen (not increasing) +- `RewardsReclaimed` event with reason = `BELOW_MINIMUM_SIGNAL` +- Reclaim address balance increased + +--- + +### 2.4 Restore threshold and verify resumption + +**Objective**: Lower the threshold back so the subgraph is above minimum. Accumulators should resume. + +**Steps**: + +```bash +# Snapshot before change +cast send "onSubgraphSignalUpdate(bytes32)" --rpc-url --private-key + +# Restore threshold +cast send "setMinimumSubgraphSignal(uint256)" --rpc-url --private-key + +# Wait, then check accumulators +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Threshold restored to original value +- `accRewardsForSubgraph` resumes increasing +- Allocations on this subgraph can claim rewards again + +--- + +## Cycle 3: Zero Allocated Tokens + +### 3.1 Identify subgraph with signal but no allocations + +**Objective**: Find or create a subgraph deployment that has curation signal but zero allocated tokens. + +**Verification Query**: + +```graphql +{ + subgraphDeployments(where: { signalledTokens_gt: 0, stakedTokens: 0 }) { + ipfsHash + signalledTokens + stakedTokens + } +} +``` + +Alternatively, close all allocations on a test subgraph while leaving signal intact. + +**Pass Criteria**: + +- Subgraph deployment identified with `signalledTokens > 0` and `stakedTokens = 0` + +--- + +### 3.2 Verify NO_ALLOCATED_TOKENS reclaim + +**Objective**: When a subgraph has signal but no allocations, rewards for that signal share are reclaimed as `NO_ALLOCATED_TOKENS`. + +**Steps**: + +```bash +# Trigger accumulator update for the zero-allocation subgraph +cast send "onSubgraphAllocationUpdate(bytes32)" --rpc-url --private-key + +# Check for RewardsReclaimed events +NO_ALLOCATED_TOKENS=$(cast keccak "NO_ALLOCATED_TOKENS") +RECLAIM_EVENT_SIG=$(cast sig-event "RewardsReclaimed(bytes32,uint256,address,address,bytes32)") +cast logs --from-block --to-block --address --topic0 $RECLAIM_EVENT_SIG --rpc-url +``` + +**Pass Criteria**: + +- `RewardsReclaimed` event with reason = `NO_ALLOCATED_TOKENS` +- Reclaim address received tokens + +--- + +### 3.3 Allocations resume from stored baseline + +**Objective**: When a new allocation is created on a subgraph that previously had zero allocations, `accRewardsPerAllocatedToken` resumes from its stored value rather than resetting to zero. + +**Steps**: + +```bash +# Record current accRewardsPerAllocatedToken +cast call "getAccRewardsPerAllocatedToken(bytes32)(uint256,uint256)" --rpc-url + +# Create allocation +graph indexer allocations create + +# Check accRewardsPerAllocatedToken after creation +cast call "getAccRewardsPerAllocatedToken(bytes32)(uint256,uint256)" --rpc-url +``` + +**Pass Criteria**: + +- New allocation created successfully +- `accRewardsPerAllocatedToken` not reset to zero (maintains stored value) +- New allocation starts accruing from current accumulator value + +--- + +## Cycle 4: POI Presentation Paths + +The issuance upgrade introduces three distinct POI presentation outcomes: **claim**, **reclaim**, and **defer**. Each condition routes to one of these paths. + +### 4.1 Normal claim path (NONE condition) + +**Objective**: Verify that a valid POI on a non-denied, signal-above-threshold, non-stale allocation claims rewards normally. The `POIPresented` event should show `condition = bytes32(0)`. + +**Prerequisites**: Active allocation, open 2+ epochs, not stale, on a non-denied subgraph with signal above threshold. + +**Steps**: + +```bash +# Confirm allocation is healthy +cast call "getRewards(address,address)(uint256)" --rpc-url +# Expected: non-zero + +# Close allocation (presents POI and claims) +graph indexer allocations close +``` + +**Verification**: Check transaction for `POIPresented` event: + +```bash +POI_EVENT_SIG=$(cast sig-event "POIPresented(address,address,bytes32,bytes32,bytes,bytes32)") +cast logs --from-block --to-block --address --topic0 $POI_EVENT_SIG --rpc-url +``` + +**Pass Criteria**: + +- `POIPresented` event emitted with `condition = 0x00...00` (NONE) +- `indexingRewards` non-zero +- Normal `HorizonRewardsAssigned` event emitted + +--- + +### 4.2 Reclaim path: STALE_POI + +**Objective**: When an allocation is stale (no POI presented within `maxPOIStaleness`), presenting a POI reclaims rewards instead of claiming them. + +**Prerequisites**: An allocation that has not had a POI presented for longer than `maxPOIStaleness`. + +**Steps**: + +```bash +# Check maxPOIStaleness +cast call "maxPOIStaleness()(uint256)" --rpc-url + +# Find or wait for a stale allocation +# (Let an allocation go without POI presentation for maxPOIStaleness seconds) + +# Close the stale allocation +graph indexer allocations close +``` + +**Pass Criteria**: + +- `POIPresented` event emitted with `condition = keccak256("STALE_POI")` +- `indexingRewards` = 0 (rewards not claimed by indexer) +- `RewardsReclaimed` event with reason = `STALE_POI` +- Reclaim address received the tokens +- Allocation snapshot advanced (pending rewards cleared) + +--- + +### 4.3 Reclaim path: ZERO_POI + +**Objective**: Submitting a zero POI (`bytes32(0)`) reclaims rewards. + +**Prerequisites**: Active allocation, mature (2+ epochs). + +**Steps**: + +```bash +# Close allocation with explicit zero POI +graph indexer allocations close --poi 0x0000000000000000000000000000000000000000000000000000000000000000 +``` + +**Pass Criteria**: + +- `POIPresented` event emitted with `condition = keccak256("ZERO_POI")` +- `indexingRewards` = 0 +- `RewardsReclaimed` event with reason = `ZERO_POI` +- Reclaim address received the tokens +- Allocation snapshot advanced (pending rewards cleared) + +--- + +### 4.4 Defer path: ALLOCATION_TOO_YOUNG + +**Objective**: Presenting a POI for an allocation created in the current epoch defers ā€” returns 0 without advancing the snapshot, preserving rewards for later. + +**Prerequisites**: Create a new allocation and attempt POI presentation in the same epoch. + +**Steps**: + +```bash +# Create allocation +graph indexer allocations create + +# Immediately attempt POI presentation (same epoch) +# (via manual cast send or indexer agent action) +``` + +**Pass Criteria**: + +- `POIPresented` event emitted with `condition = keccak256("ALLOCATION_TOO_YOUNG")` +- Returns 0 rewards +- **Critical**: Allocation snapshot NOT advanced (rewards preserved for later) +- Allocation remains open and healthy +- After waiting for epoch boundary: normal claim succeeds + +--- + +### 4.5 POI presentation always updates timestamp + +**Objective**: Verify that the POI presentation timestamp is recorded regardless of the condition outcome. This means even reclaimed or deferred presentations reset the staleness clock. + +**Steps**: + +1. Present a POI that results in a defer (e.g., too young) +2. Check that the staleness timer reset +3. Present a POI that results in a reclaim (e.g., zero POI) +4. Check that the staleness timer reset + +**Pass Criteria**: + +- Staleness timer resets on every POI presentation, regardless of outcome +- An allocation that regularly presents POIs (even deferred ones) does not become stale + +--- + +## Cycle 5: Allocation Lifecycle + +### 5.1 Allocation resize reclaims stale rewards + +**Objective**: Resizing a stale allocation reclaims pending rewards as `STALE_POI` and clears them. This prevents stale allocations from silently accumulating rewards through repeated resizes. + +**Prerequisites**: An allocation that is stale (no POI for `maxPOIStaleness`). The allocation has pending rewards from before it went stale. + +**Steps**: + +```bash +# Confirm allocation is stale +# (Check last POI timestamp vs maxPOIStaleness) + +# Check pending rewards before resize +cast call "getRewards(address,address)(uint256)" --rpc-url + +# Resize the allocation +graph indexer allocations reallocate +``` + +**Pass Criteria**: + +- `RewardsReclaimed` event with reason = `STALE_POI` +- Pending rewards cleared (not carried forward through resize) +- Reclaim address received the stale rewards +- New allocation starts fresh (no carried-over stale rewards) + +--- + +### 5.2 Allocation resize does NOT reclaim for non-stale allocation + +**Objective**: Resizing a healthy (non-stale) allocation should accumulate pending rewards normally, not reclaim them. + +**Prerequisites**: Active, non-stale allocation with pending rewards. + +**Steps**: + +```bash +# Check pending rewards +cast call "getRewards(address,address)(uint256)" --rpc-url + +# Resize +graph indexer allocations reallocate + +# Check that no STALE_POI reclaim event occurred +``` + +**Pass Criteria**: + +- No `RewardsReclaimed` event with reason = `STALE_POI` +- Pending rewards accumulated into `accRewardsPending` (carried through resize) +- New allocation can claim accumulated rewards on next close + +--- + +### 5.3 Allocation close reclaims uncollected rewards + +**Objective**: When an allocation is closed, any uncollected rewards are reclaimed as `CLOSE_ALLOCATION` before the allocation is finalized. This prevents rewards from being permanently lost on close. + +**Prerequisites**: An allocation with uncollected rewards (e.g., the indexer has not presented a POI recently, or rewards accumulated since last POI). + +**Steps**: + +```bash +# Record reclaim address balance +cast call "balanceOf(address)(uint256)" --rpc-url + +# Close allocation +graph indexer allocations close + +# Check for CLOSE_ALLOCATION reclaim +CLOSE_ALLOC=$(cast keccak "CLOSE_ALLOCATION") +RECLAIM_EVENT_SIG=$(cast sig-event "RewardsReclaimed(bytes32,uint256,address,address,bytes32)") +cast logs --from-block --to-block --address --topic0 $RECLAIM_EVENT_SIG --rpc-url + +# Check reclaim address balance increased +cast call "balanceOf(address)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- `RewardsReclaimed` event with reason = `CLOSE_ALLOCATION` +- Reclaim address balance increased +- Rewards not permanently lost (either claimed by indexer via POI or reclaimed to protocol) + +--- + +## Cycle 6: Observability + +### 6.1 POIPresented event emitted on every presentation + +**Objective**: Verify that every POI presentation emits a `POIPresented` event with the determined condition, regardless of outcome. + +**Steps**: + +Collect events across multiple scenarios from previous cycles: + +```bash +POI_EVENT_SIG=$(cast sig-event "POIPresented(address,address,bytes32,bytes32,bytes,bytes32)") + +# Query all POIPresented events from the test session +cast logs --from-block --to-block latest --address --topic0 $POI_EVENT_SIG --rpc-url +``` + +**Pass Criteria**: + +- Every POI presentation (from Cycles 4-5) has a corresponding `POIPresented` event +- Each event contains: + - `indexer`: correct indexer address + - `allocationId`: correct allocation + - `subgraphDeploymentId`: correct deployment + - `poi`: the submitted POI value + - `condition`: matches the expected outcome (NONE, STALE_POI, ZERO_POI, ALLOCATION_TOO_YOUNG, SUBGRAPH_DENIED) + +--- + +### 6.2 RewardsReclaimed events include full context + +**Objective**: Verify that `RewardsReclaimed` events contain all necessary context for off-chain accounting. + +**Steps**: + +```bash +RECLAIM_EVENT_SIG=$(cast sig-event "RewardsReclaimed(bytes32,uint256,address,address,bytes32)") + +# Query all RewardsReclaimed events from the test session +cast logs --from-block --to-block latest --address --topic0 $RECLAIM_EVENT_SIG --rpc-url +``` + +**Pass Criteria**: + +- Each `RewardsReclaimed` event contains: + - `reason`: valid `RewardsCondition` identifier (not zero) + - `amount`: non-zero GRT amount + - `indexer`: address of the affected indexer (or zero for subgraph-level reclaims) + - `allocationID`: address of the affected allocation (or zero for subgraph-level reclaims) + - `subgraphDeploymentID`: deployment hash + +--- + +### 6.3 View functions reflect frozen state accurately + +**Objective**: Verify that `getAccRewardsForSubgraph()`, `getAccRewardsPerAllocatedToken()`, and `getRewards()` correctly return frozen values for non-claimable subgraphs and growing values for claimable ones. + +**Steps**: + +```bash +# For a denied subgraph (if one is still denied from SubgraphDenialTestPlan) +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url +# Wait, read again ā€” should be unchanged + +# For a below-threshold subgraph (if one is still below from Cycle 2) +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url +# Wait, read again ā€” should be unchanged + +# For a healthy subgraph (control) +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url +# Wait, read again ā€” should have increased + +# getRewards for allocation on non-claimable subgraph +cast call "getRewards(address,address)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Non-claimable subgraphs: view functions return frozen (non-increasing) values +- Claimable subgraphs: view functions return growing values +- `getRewards()` for allocations on non-claimable subgraphs returns a frozen value +- Pre-existing `accRewardsPending` from prior resizes is still included in `getRewards()` even for non-claimable subgraphs + +--- + +## Cycle 7: Zero Global Signal + +> **Note**: These tests require zero total curation signal across the entire network, which is impractical on a shared testnet. They are documented here for completeness and should be validated via Foundry unit tests or on a dedicated test network. + +### 7.1 NO_SIGNAL detection + +**Objective**: When total curation signal across all subgraphs is zero, issuance during that period should be reclaimed as `NO_SIGNAL`. + +**Steps** (dedicated testnet only): + +```bash +# Remove all curation signal from all subgraphs +# (Only feasible on a private testnet) + +# Wait for blocks to pass (issuance accrues to nobody) + +# Trigger accumulator update +cast send "updateAccRewardsPerSignal()" --rpc-url --private-key + +# Check for RewardsReclaimed with NO_SIGNAL +NO_SIGNAL=$(cast keccak "NO_SIGNAL") +RECLAIM_EVENT_SIG=$(cast sig-event "RewardsReclaimed(bytes32,uint256,address,address,bytes32)") +cast logs --from-block --to-block --address --topic0 $RECLAIM_EVENT_SIG --rpc-url +``` + +**Pass Criteria**: + +- `RewardsReclaimed` event with reason = `NO_SIGNAL` +- Reclaimed amount corresponds to issuance during zero-signal period +- `getNewRewardsPerSignal()` still returns claimable portion only (unchanged from legacy behavior) + +--- + +### 7.2 Signal restoration resumes normal distribution + +**Objective**: After signal is restored, rewards distribution resumes normally. + +**Steps** (dedicated testnet only): + +1. Add curation signal to a subgraph +2. Verify `getNewRewardsPerSignal()` returns non-zero +3. Verify accumulators resume growing + +**Pass Criteria**: + +- Rewards flow normally after signal restoration +- No rewards from the zero-signal period leak into the normal distribution + +--- + +## Post-Testing Checklist + +- [ ] Reclaim addresses verified for all conditions +- [ ] `minimumSubgraphSignal` restored to original value +- [ ] No subgraphs left in unintended denied state +- [ ] Reclaim address balances reconciled with expected amounts +- [ ] All `POIPresented` events collected and categorized +- [ ] Results documented in test tracker + +--- + +## Test Summary + +| Condition | Test(s) | Cycle | Testnet Feasibility | +| ------------------------ | --------- | ----- | ---------------------- | +| Reclaim infrastructure | 1.1 - 1.5 | 1 | Full | +| `BELOW_MINIMUM_SIGNAL` | 2.1 - 2.4 | 2 | Full | +| `NO_ALLOCATED_TOKENS` | 3.1 - 3.3 | 3 | Full | +| `NONE` (normal claim) | 4.1 | 4 | Full | +| `STALE_POI` | 4.2 | 4 | Full (wait needed) | +| `ZERO_POI` | 4.3 | 4 | Full | +| `ALLOCATION_TOO_YOUNG` | 4.4 | 4 | Full | +| POI timestamp behavior | 4.5 | 4 | Full | +| Stale resize reclaim | 5.1 - 5.2 | 5 | Full (wait needed) | +| `CLOSE_ALLOCATION` | 5.3 | 5 | Full | +| `POIPresented` event | 6.1 | 6 | Full | +| `RewardsReclaimed` event | 6.2 | 6 | Full | +| View function freeze | 6.3 | 6 | Full | +| `NO_SIGNAL` | 7.1 - 7.2 | 7 | Dedicated testnet only | + +--- + +## Related Documentation + +- [ā† Back to REO Testing](README.md) +- [SubgraphDenialTestPlan.md](SubgraphDenialTestPlan.md) ā€” Subgraph denial behavior tests +- [BaselineTestPlan.md](BaselineTestPlan.md) ā€” Baseline operational tests (run first) +- [ReoTestPlan.md](ReoTestPlan.md) ā€” REO eligibility tests + +--- + +_Derived from issuance upgrade behavior changes. Source: [RewardsBehaviourChanges.md](/docs/RewardsBehaviourChanges.md), [RewardConditions.md](/docs/RewardConditions.md). Contracts: `packages/contracts/contracts/rewards/RewardsManager.sol`, `packages/subgraph-service/contracts/utilities/AllocationManager.sol`._ diff --git a/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md b/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md new file mode 100644 index 000000000..cc03a7d7d --- /dev/null +++ b/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md @@ -0,0 +1,680 @@ +# Subgraph Denial Test Plan + +> **Status: Complete** ā€” Local network automation validates Cycles 2, 3, 5, and 6 (edge cases). Cycle 4 (allocation-level deferral) needs direct POI presentation. +> +> **Navigation**: [ā† Back to REO Testing](README.md) | [BaselineTestPlan](BaselineTestPlan.md) | [RewardsConditionsTestPlan](RewardsConditionsTestPlan.md) + +Tests for the subgraph denial behavior changes introduced in the issuance upgrade. Denial handling changed significantly: accumulators now freeze during denial (reclaiming new rewards), while uncollected pre-denial rewards are preserved and become claimable after undeny. + +> All contract reads use `cast call`. All addresses must be **lowercase**. Replace placeholder addresses with actual deployed addresses for your network. + +## Contract Addresses + +| Contract | Arbitrum Sepolia | Arbitrum One | +| ----------------------- | -------------------------------------------- | -------------------------------------------- | +| RewardsManager (proxy) | `0x1f49cae7669086c8ba53cc35d1e9f80176d67e79` | `0x971b9d3d0ae3eca029cab5ea1fb0f72c85e6a525` | +| SubgraphService (proxy) | `0xc24a3dac5d06d771f657a48b20ce1a671b78f26b` | `0xb2bb92d0de618878e438b55d5846cfecd9301105` | +| GraphToken (L2) | `0xf8c05dcf59e8b28bfd5eed176c562bebcfc7ac04` | `0x9623063377ad1b27544c965ccd7342f7ea7e88c7` | +| Controller | `0x9db3ee191681f092607035d9bda6e59fbeaca695` | `0x0a8491544221dd212964fbb96487467291b2c97e` | + +**Address sources**: `packages/horizon/addresses.json` (RewardsManager, GraphToken, Controller), `packages/subgraph-service/addresses.json` (SubgraphService). + +### RPC + +| Network | RPC URL | +| ---------------- | ---------------------------------------- | +| Arbitrum Sepolia | `https://sepolia-rollup.arbitrum.io/rpc` | + +--- + +## Background + +### What Changed + +**Before (Horizon baseline):** Denial was a binary gate at `takeRewards()` time. When a subgraph was denied, rewards were returned as 0 and the allocation snapshot advanced, permanently dropping those rewards. + +**After (issuance upgrade):** Denial is handled at two levels: + +1. **RewardsManager (accumulator level):** When accumulator updates encounter a denied subgraph, `accRewardsForSubgraph` and `accRewardsPerAllocatedToken` freeze. New rewards during denial are reclaimed instead of accumulated. `setDenied()` snapshots accumulators before changing state so the boundary is clean. + +2. **AllocationManager (claim level):** POI presentation for a denied subgraph is _deferred_ ā€” returns 0 **without advancing the allocation snapshot**. Uncollected pre-denial rewards are preserved and become claimable after undeny. + +### Key Invariants + +- Accumulators never decrease (they freeze during denial, not decrease) +- Pre-denial uncollected rewards are preserved through the deny/undeny cycle +- Denial-period rewards are reclaimed (or dropped if no reclaim address) +- `setDenied()` snapshots accumulators before state change (clean boundary) +- Redundant deny/undeny calls are idempotent (no state change) + +--- + +## Prerequisites + +- [Baseline tests](BaselineTestPlan.md) Cycles 1-7 pass +- [Reclaim system configured](RewardsConditionsTestPlan.md#cycle-1-reclaim-system-configuration) (Cycle 1 of RewardsConditionsTestPlan) ā€” or configure inline during Cycle 1 below +- At least two indexers with active allocations on rewarded subgraph deployments +- Access to the Governor or SubgraphAvailabilityOracle (SAO) account that can call `setDenied()` +- Allocations must be mature (open for 2+ epochs) before denial tests + +### Roles Needed + +| Role | Needed For | Holder | +| --------------- | --------------------------------------------- | -------------------------------- | +| Governor or SAO | `setDenied()` calls | Check Controller configuration | +| Governor | `setReclaimAddress()` (if not yet configured) | Council/NetworkOperator multisig | + +### Identifying the SAO + +```bash +# The SAO is stored in the Controller as the subgraphAvailabilityOracle +# Alternatively, check who can call setDenied on RewardsManager +cast call "getContractProxy(bytes32)(address)" $(cast keccak "SubgraphAvailabilityOracle") --rpc-url +``` + +--- + +## Testing Approach + +**Dedicated test subgraph**: Use a subgraph deployment that is not critical to other testing. The deployment should have: + +- Non-zero curation signal +- At least two active allocations from different indexers +- Signal above `minimumSubgraphSignal` (to isolate denial behavior from signal threshold behavior) + +**Epoch timing**: Many tests require waiting for epoch boundaries. On Sepolia, epochs are ~554 blocks (~110 minutes). Plan sessions accordingly. + +**Reclaim address monitoring**: Before starting, configure a reclaim address for `SUBGRAPH_DENIED` so reclaimed tokens are observable. If no reclaim address is set, denial-period rewards are silently dropped. + +--- + +## Test Sequence Overview + +| Cycle | Area | Tests | Notes | +| ----- | ------------------------------- | --------- | -------------------------------------------------- | +| 1 | Reclaim Setup for Denial | 1.1 - 1.2 | Governor access needed; skip if already configured | +| 2 | Denial State Management | 2.1 - 2.4 | SAO or Governor access needed | +| 3 | Accumulator Freeze Verification | 3.1 - 3.4 | Read-only after denial; wait for epochs | +| 4 | Allocation-Level Deferral | 4.1 - 4.3 | Requires active allocations on denied subgraph | +| 5 | Undeny and Reward Recovery | 5.1 - 5.4 | Full denyā†’undenyā†’claim lifecycle | +| 6 | Edge Cases | 6.1 - 6.4 | Advanced scenarios | + +--- + +## Cycle 1: Reclaim Setup for Denial + +> Skip this cycle if reclaim addresses are already configured (verify with tests 1.1 reads). + +### 1.1 Configure SUBGRAPH_DENIED reclaim address + +**Objective**: Set a reclaim address for `SUBGRAPH_DENIED` so that denial-period rewards are minted to a trackable address instead of being silently dropped. + +**Steps**: + +```bash +# Compute the SUBGRAPH_DENIED condition identifier +SUBGRAPH_DENIED=$(cast keccak "SUBGRAPH_DENIED") + +# Check current reclaim address (expect zero if unconfigured) +cast call "getReclaimAddress(bytes32)(address)" $SUBGRAPH_DENIED --rpc-url + +# Set reclaim address (as Governor) +cast send "setReclaimAddress(bytes32,address)" $SUBGRAPH_DENIED --rpc-url --private-key + +# Verify +cast call "getReclaimAddress(bytes32)(address)" $SUBGRAPH_DENIED --rpc-url +``` + +**Pass Criteria**: + +- `ReclaimAddressSet` event emitted with correct reason and address +- `getReclaimAddress(SUBGRAPH_DENIED)` returns the configured address + +--- + +### 1.2 Record reclaim address GRT balance + +**Objective**: Record the starting GRT balance of the reclaim address so we can measure tokens reclaimed during denial. + +**Steps**: + +```bash +cast call "balanceOf(address)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Balance recorded for later comparison + +--- + +## Cycle 2: Denial State Management + +### 2.1 Verify subgraph is not denied (pre-test) + +**Objective**: Confirm the test subgraph deployment is currently not denied and accumulators are growing. + +**Steps**: + +```bash +# Check denial status +cast call "isDenied(bytes32)(bool)" --rpc-url + +# Record current accumulator values +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url + +cast call "getAccRewardsPerAllocatedToken(bytes32)(uint256,uint256)" --rpc-url +``` + +**Pass Criteria**: + +- `isDenied` = `false` +- Accumulator values recorded as baseline + +--- + +### 2.2 Deny subgraph deployment + +**Objective**: Deny a subgraph and verify the state transition. Confirm `setDenied()` snapshots accumulators before applying denial. + +**Steps**: + +```bash +# Deny the subgraph (as SAO or Governor) +cast send "setDenied(bytes32,bool)" true --rpc-url --private-key + +# Verify denial +cast call "isDenied(bytes32)(bool)" --rpc-url +``` + +**Verification**: Check for `RewardsDenylistUpdated` event: + +```bash +# Check the transaction receipt for RewardsDenylistUpdated event +cast receipt --rpc-url +``` + +**Pass Criteria**: + +- Transaction succeeds +- `isDenied` = `true` +- `RewardsDenylistUpdated(subgraphDeploymentID, sinceBlock)` event emitted with `sinceBlock` = block number of the transaction + +--- + +### 2.3 Redundant deny is idempotent + +**Objective**: Calling `setDenied(true)` on an already-denied subgraph should not change state or emit new events. + +**Steps**: + +```bash +# Deny again (already denied) +cast send "setDenied(bytes32,bool)" true --rpc-url --private-key + +# Verify still denied +cast call "isDenied(bytes32)(bool)" --rpc-url +``` + +**Pass Criteria**: + +- Transaction succeeds (does not revert) +- `isDenied` still = `true` +- No additional `RewardsDenylistUpdated` event (or event has unchanged `sinceBlock`) + +--- + +### 2.4 Unauthorized deny reverts + +**Objective**: Only the SAO or Governor can deny subgraphs. + +**Steps**: + +```bash +# Attempt deny from unauthorized account +cast send "setDenied(bytes32,bool)" true --rpc-url --private-key +``` + +**Pass Criteria**: + +- Transaction reverts + +--- + +## Cycle 3: Accumulator Freeze Verification + +> **Timing**: These tests require waiting for time to pass after denial. At minimum, wait for part of an epoch (~30-60 minutes on Sepolia) between reads to observe that accumulators have stopped growing. + +### 3.1 Accumulators freeze after denial + +**Objective**: Verify that `accRewardsForSubgraph` and `accRewardsPerAllocatedToken` stop growing for a denied subgraph. + +**Prerequisites**: Subgraph denied in test 2.2. Wait at least 30 minutes. + +**Steps**: + +```bash +# Read accumulators (should match or be very close to values recorded at denial time) +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url + +cast call "getAccRewardsPerAllocatedToken(bytes32)(uint256,uint256)" --rpc-url + +# Compare with a non-denied subgraph (should be growing) +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Denied subgraph: `accRewardsForSubgraph` has NOT increased since denial +- Denied subgraph: `accRewardsPerAllocatedToken` has NOT increased since denial +- Non-denied subgraph: accumulators continue to increase normally (control) + +--- + +### 3.2 getRewards returns frozen value for allocations on denied subgraph + +**Objective**: Verify that `getRewards()` for an allocation on a denied subgraph returns a frozen value (no new rewards accumulate). + +**Steps**: + +```bash +# Check pending rewards for allocation on denied subgraph +cast call "getRewards(address,address)(uint256)" --rpc-url + +# Wait some time, check again +# (wait 30+ minutes) +cast call "getRewards(address,address)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Both reads return the same value (frozen ā€” no new rewards accruing) +- The value represents pre-denial uncollected rewards (may be non-zero) + +--- + +### 3.3 Denial-period rewards reclaimed + +**Objective**: Verify that rewards that would have gone to the denied subgraph are being reclaimed to the configured address. + +**Prerequisites**: Reclaim address configured in Cycle 1. Some time has passed since denial. + +**Steps**: + +```bash +# Trigger an accumulator update that processes the denied subgraph +# This happens automatically on signal/allocation changes, but can be forced: +cast send "onSubgraphSignalUpdate(bytes32)" --rpc-url --private-key + +# Check reclaim address balance +cast call "balanceOf(address)(uint256)" --rpc-url +``` + +**Verification**: Check for `RewardsReclaimed` events: + +```bash +RECLAIM_EVENT_SIG=$(cast sig-event "RewardsReclaimed(bytes32,uint256,address,address,bytes32)") +cast logs --from-block --to-block latest --address --topic0 $RECLAIM_EVENT_SIG --rpc-url +``` + +**Pass Criteria**: + +- `RewardsReclaimed` event(s) emitted with reason = `SUBGRAPH_DENIED` +- Reclaim address GRT balance has increased from the Cycle 1 baseline +- Reclaimed amount is proportional to the denied subgraph's signal share and denial duration + +--- + +### 3.4 Non-denied subgraphs unaffected + +**Objective**: Confirm that denying one subgraph does not affect reward accumulation for other subgraphs. + +**Steps**: + +```bash +# Check a non-denied subgraph's accumulator +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url + +# Check allocation rewards on non-denied subgraph +cast call "getRewards(address,address)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Non-denied subgraph accumulators continue increasing +- Allocation rewards on non-denied subgraph continue accruing + +--- + +## Cycle 4: Allocation-Level Deferral + +### 4.1 POI presentation on denied subgraph defers (returns 0, preserves state) + +**Objective**: When an indexer presents a POI for a denied subgraph, the allocation should return 0 rewards WITHOUT advancing the snapshot. The `POIPresented` event should show `condition = SUBGRAPH_DENIED`. + +**Prerequisites**: Indexer has an active allocation on the denied subgraph. Allocation is mature (open 2+ epochs). + +**Steps**: + +1. Record the allocation's current reward snapshot (via view functions) +2. Close or present POI for the allocation on the denied subgraph + +```bash +# Check pending rewards before POI presentation +cast call "getRewards(address,address)(uint256)" --rpc-url + +# Present POI (via indexer agent or manual close attempt) +# The exact mechanism depends on your indexer setup +graph indexer allocations close +``` + +**Verification**: Check transaction logs for `POIPresented` event: + +```bash +POI_EVENT_SIG=$(cast sig-event "POIPresented(address,address,bytes32,bytes32,bytes,bytes32)") +cast logs --from-block --to-block --address --topic0 $POI_EVENT_SIG --rpc-url +``` + +**Pass Criteria**: + +- `POIPresented` event emitted with `condition` = `keccak256("SUBGRAPH_DENIED")` +- Rewards returned = 0 +- **Critical**: Allocation snapshot NOT advanced (pre-denial rewards preserved) +- Allocation remains open if this was a POI presentation (not a force-close) + +--- + +### 4.2 Multiple POI presentations while denied do not lose rewards + +**Objective**: An indexer can present POIs multiple times while a subgraph is denied without losing any pre-denial rewards. Each presentation should defer without advancing the snapshot. + +**Steps**: + +```bash +# First POI presentation (while denied) +# Record getRewards value +cast call "getRewards(address,address)(uint256)" --rpc-url + +# Present POI +# (use indexer agent or cast send to SubgraphService) + +# Second POI presentation (still denied, next epoch) +# Wait one epoch +cast call "getRewards(address,address)(uint256)" --rpc-url + +# Present POI again +``` + +**Pass Criteria**: + +- `getRewards()` returns the same frozen value across all presentations +- No `RewardsReclaimed` events for the allocation's pre-denial rewards +- Pre-denial rewards remain preserved through multiple POI cycles + +--- + +### 4.3 Indexers should continue presenting POIs during denial + +**Objective**: Document that continuing POI presentation during denial prevents staleness. The POI timestamp is updated even on deferred presentations. + +**Steps**: + +1. Confirm the denied subgraph has active allocations +2. Present POI normally (via indexer agent) +3. Verify the allocation's last POI timestamp is updated + +**Pass Criteria**: + +- POI presentation succeeds (transaction does not revert) +- Allocation does not become stale during denial period +- When subgraph is later undenied, the allocation is still healthy (not stale) + +--- + +## Cycle 5: Undeny and Reward Recovery + +### 5.1 Undeny subgraph deployment + +**Objective**: Remove denial and verify accumulators resume growing. + +**Steps**: + +```bash +# Record accumulators just before undeny +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url + +# Undeny +cast send "setDenied(bytes32,bool)" false --rpc-url --private-key + +# Verify +cast call "isDenied(bytes32)(bool)" --rpc-url +``` + +**Verification**: Check for `RewardsDenylistUpdated` event with `sinceBlock = 0`. + +**Pass Criteria**: + +- `isDenied` = `false` +- `RewardsDenylistUpdated(subgraphDeploymentID, 0)` event emitted + +--- + +### 5.2 Accumulators resume after undeny + +**Objective**: Verify that accumulators start growing again after undeny. + +**Prerequisites**: Subgraph undenied in test 5.1. Wait at least 30 minutes. + +**Steps**: + +```bash +# Read accumulators (should now be growing again) +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url + +cast call "getAccRewardsPerAllocatedToken(bytes32)(uint256,uint256)" --rpc-url +``` + +**Pass Criteria**: + +- `accRewardsForSubgraph` has increased since undeny +- `accRewardsPerAllocatedToken` has increased since undeny +- Growth rate is consistent with the subgraph's signal proportion + +--- + +### 5.3 Pre-denial rewards claimable after undeny + +**Objective**: Verify that uncollected rewards from before the denial period are now claimable. This is the critical test: the new behavior preserves these rewards rather than dropping them. + +**Prerequisites**: Indexer has allocation that was open before denial and still active. Subgraph is now undenied. Wait 1-2 epochs after undeny. + +**Steps**: + +```bash +# Check pending rewards (should include pre-denial uncollected + post-undeny new rewards) +cast call "getRewards(address,address)(uint256)" --rpc-url + +# Close allocation to claim +graph indexer allocations close +``` + +**Verification Query**: + +```graphql +{ + allocations(where: { id: "ALLOCATION_ID" }) { + id + status + indexingRewards + closedAtEpoch + } +} +``` + +**Pass Criteria**: + +- `indexingRewards` is non-zero +- Reward amount includes: + - Pre-denial uncollected rewards (accumulated before deny) + - Post-undeny rewards (accumulated after undeny) +- Reward amount does NOT include denial-period rewards (those were reclaimed in Cycle 3) +- `POIPresented` event shows `condition = NONE` (normal claim) + +--- + +### 5.4 Denial-period rewards are NOT included in claim + +**Objective**: Verify that the claimed rewards exclude the denial period. Compare the claimed amount against what a continuously-active allocation would have earned. + +**Steps**: + +1. Calculate expected rewards: + - Pre-denial period: from allocation creation to deny block + - Post-undeny period: from undeny block to close block + - Denial period: from deny block to undeny block (should be excluded) +2. Compare actual `indexingRewards` from test 5.3 + +**Pass Criteria**: + +- Claimed rewards approximate (pre-denial + post-undeny) only +- Denial-period rewards were reclaimed (verified in Cycle 3) +- Total of (claimed + reclaimed) approximately equals what would have been earned with no denial + +--- + +## Cycle 6: Edge Cases + +### 6.1 New allocation created while subgraph is denied + +**Objective**: An allocation opened on a denied subgraph starts with a frozen baseline. It should only earn rewards after undeny. + +**Prerequisites**: Subgraph currently denied. + +**Steps**: + +```bash +# Create allocation on denied subgraph +graph indexer allocations create + +# Check rewards immediately +cast call "getRewards(address,address)(uint256)" --rpc-url + +# Wait some time (still denied) +# Check rewards again +cast call "getRewards(address,address)(uint256)" --rpc-url + +# Undeny +cast send "setDenied(bytes32,bool)" false --rpc-url --private-key + +# Wait 1-2 epochs after undeny +# Check rewards again +cast call "getRewards(address,address)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- While denied: `getRewards()` returns 0 (no rewards accumulate) +- After undeny: `getRewards()` starts increasing (rewards resume from undeny point) +- Allocation only earns post-undeny rewards + +--- + +### 6.2 All allocations close while denied, then new allocation after undeny + +**Objective**: When all allocations close during denial, the frozen accumulator state is preserved. A new allocation after undeny should use that preserved baseline. + +**Steps**: + +1. Deny subgraph (if not already denied) +2. Close all allocations on the denied subgraph +3. Undeny subgraph +4. Create new allocation +5. Wait 1-2 epochs, close, check rewards + +**Pass Criteria**: + +- New allocation earns rewards only for the post-undeny period +- Frozen state was correctly preserved through the "no allocations" period +- No rewards are double-counted or lost at the transition + +--- + +### 6.3 Deny and undeny in rapid succession + +**Objective**: A quick denyā†’undeny cycle correctly handles the boundary. Accumulators are snapshotted on each transition. + +**Steps**: + +```bash +# Record accumulators +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url + +# Deny +cast send "setDenied(bytes32,bool)" true --rpc-url --private-key + +# Undeny (in next block or shortly after) +cast send "setDenied(bytes32,bool)" false --rpc-url --private-key + +# Check accumulators +cast call "getAccRewardsForSubgraph(bytes32)(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Both transactions succeed +- Accumulators resume growing after undeny +- Minimal reward loss (only the few blocks between deny and undeny) +- No contract reverts or unexpected state + +--- + +### 6.4 Denial interaction with indexer eligibility + +**Objective**: Subgraph denial takes precedence over indexer eligibility. When a subgraph is denied, POI presentation defers regardless of eligibility status ā€” ensuring pre-denial rewards are preserved even for ineligible indexers. + +**Prerequisites**: REO validation enabled, one indexer ineligible, subgraph denied. + +**Steps**: + +```bash +# Confirm indexer is ineligible +cast call "isEligible(address)(bool)" --rpc-url +# Expected: false + +# Confirm subgraph is denied +cast call "isDenied(bytes32)(bool)" --rpc-url +# Expected: true + +# Present POI for ineligible indexer on denied subgraph +# (via indexer agent or manual) +``` + +**Pass Criteria**: + +- POI presentation defers (not reclaimed as INDEXER_INELIGIBLE) +- `POIPresented` event shows `condition = SUBGRAPH_DENIED` (denial takes precedence) +- Pre-denial rewards preserved (not reclaimed due to ineligibility) +- After undeny + re-renewal: rewards become claimable + +--- + +## Post-Testing Checklist + +- [ ] All denied subgraphs undenied (or left in intended state) +- [ ] Reclaim addresses verified +- [ ] No allocations stuck in unexpected state +- [ ] Reclaim address balance increase accounted for +- [ ] Results documented in test tracker + +--- + +## Related Documentation + +- [ā† Back to REO Testing](README.md) +- [RewardsConditionsTestPlan.md](RewardsConditionsTestPlan.md) ā€” Signal, POI, and allocation lifecycle conditions +- [BaselineTestPlan.md](BaselineTestPlan.md) ā€” Baseline operational tests (run first) +- [ReoTestPlan.md](ReoTestPlan.md) ā€” REO eligibility tests + +--- + +_Derived from issuance upgrade behavior changes. Source: [RewardsBehaviourChanges.md](/docs/RewardsBehaviourChanges.md), [RewardConditions.md](/docs/RewardConditions.md). Contract: `packages/contracts/contracts/rewards/RewardsManager.sol`, `packages/subgraph-service/contracts/utilities/AllocationManager.sol`._ diff --git a/packages/issuance/docs/testing/reo/support/IssuanceAllocatorTestPlan.md b/packages/issuance/docs/testing/reo/support/IssuanceAllocatorTestPlan.md new file mode 100644 index 000000000..d8ab63f85 --- /dev/null +++ b/packages/issuance/docs/testing/reo/support/IssuanceAllocatorTestPlan.md @@ -0,0 +1,98 @@ +# IssuanceAllocator Test Plan + +> **Navigation**: [ā† Back to REO Testing](../README.md) + +Separated from the REO test plan ā€” IssuanceAllocator is independent of the Rewards Eligibility Oracle. Test when deployed. + +## Contract Addresses + +| Contract | Arbitrum Sepolia | Arbitrum One | +| ------------------------- | -------------------------------------------- | ------------ | +| IssuanceAllocator (proxy) | Not yet deployed | TBD | +| RewardsManager (proxy) | `0x1f49cae7669086c8ba53cc35d1e9f80176d67e79` | TBD | +| GraphToken (L2) | `0xf8c05dcf59e8b28bfd5eed176c562bebcfc7ac04` | TBD | + +--- + +## Tests + +### 1. Verify IssuanceAllocator configuration + +**Objective**: Confirm the IssuanceAllocator is correctly configured with RewardsManager as a self-minting target. + +**Steps**: + +```bash +# Check issuance rate +cast call "getIssuancePerBlock()(uint256)" --rpc-url + +# Check RewardsManager target allocation +cast call "getTargetIssuancePerBlock(address)(uint256,uint256)" --rpc-url + +# Check if IssuanceAllocator is minter +cast call "isMinter(address)(bool)" --rpc-url + +# Check RewardsManager knows about IssuanceAllocator +cast call "getIssuanceAllocator()(address)" --rpc-url +``` + +**Pass Criteria**: + +- `getIssuancePerBlock` returns the expected issuance rate +- RewardsManager has self-minting allocation = 100% of issuance +- IssuanceAllocator is a minter on GraphToken +- RewardsManager points to IssuanceAllocator + +--- + +### 2. Distribute issuance + +**Objective**: Verify `distributeIssuance()` executes correctly. + +**Steps**: + +```bash +# Anyone can call this +cast send "distributeIssuance()" --rpc-url --private-key +``` + +**Pass Criteria**: + +- Transaction succeeds +- No unexpected reverts + +--- + +### 3. Verify issuance rate matches RewardsManager + +**Objective**: Confirm the issuance rate in IssuanceAllocator matches what RewardsManager expects. + +**Steps**: + +```bash +# IssuanceAllocator rate +cast call "getIssuancePerBlock()(uint256)" --rpc-url + +# RewardsManager effective rate +cast call "issuancePerBlock()(uint256)" --rpc-url +``` + +**Pass Criteria**: + +- Both values are identical + +--- + +### 4. IssuanceAllocator not paused + +**Objective**: Confirm the IssuanceAllocator is operational. + +**Steps**: + +```bash +cast call "paused()(bool)" --rpc-url +``` + +**Pass Criteria**: + +- Returns `false` diff --git a/packages/issuance/docs/testing/reo/support/NotionSetup.md b/packages/issuance/docs/testing/reo/support/NotionSetup.md new file mode 100644 index 000000000..2ebcc8e6c --- /dev/null +++ b/packages/issuance/docs/testing/reo/support/NotionSetup.md @@ -0,0 +1,70 @@ +# Notion Tracker Setup + +> **Navigation**: [ā† Back to REO Testing](../README.md) + +Instructions for setting up the Notion-based test tracker from [NotionTracker.csv](NotionTracker.csv). + +## Import into Notion + +1. Open Notion, navigate to the workspace where you want the tracker +2. Click **Import** (sidebar ā†’ Import, or `...` menu ā†’ Import) +3. Select **CSV** and upload `NotionTracker.csv` +4. Notion creates a database from the CSV + +## Configure Column Types + +After import, change these column types in the database: + +| Column | Change to | Notes | +| --------- | ------------ | --------------------------------------------------------------- | +| Indexer A | **Checkbox** | Indexer marks when they've completed the test | +| Indexer B | **Checkbox** | Same | +| Indexer C | **Checkbox** | Same | +| Status | **Select** | Options: Not Started, In Progress, Pass, Fail, Blocked, Skipped | +| Link | **URL** | Links are already full GitHub URLs | +| Plan | **Select** | Enables grouping by test plan (Baseline / Eligibility) | + +### Add Indexer Columns + +If you have more than 3 indexers, add additional checkbox columns. Rename the generic "Indexer A/B/C" columns to the actual indexer names or addresses. + +## Recommended Views + +### 1. Main Tracker (Table) + +Default view ā€” all tests in sequence. Sort by **Test ID**. + +### 2. By Plan (Board) + +Board view grouped by **Plan**. Shows progress through Baseline vs Eligibility at a glance. + +### 3. Per-Indexer (Filtered Tables) + +Create a filtered table for each indexer showing their checkbox and status columns. + +### 4. Blocked / Failed + +Filter: Status = Fail or Blocked. Use during testing to track issues. + +## Workflow + +1. **Before testing**: Share the Notion page with participating indexers (edit access) +2. **During testing**: Indexers check their checkbox when they complete a test. Update Status column. +3. **Coordinator**: Updates Status and Notes columns as tests progress +4. **After each session**: Review blocked/failed tests, update Notes with details + +## Column Reference + +| Column | Purpose | +| ----------- | -------------------------------------------------- | +| Test ID | Unique identifier (e.g. B-3.2 = Baseline test 3.2) | +| Plan | Test plan: Baseline or Eligibility | +| Test Name | Short test title | +| Link | Link to detailed test steps in IndexerTestGuide.md | +| Indexer A-C | Checkboxes for each indexer to confirm completion | +| Status | Current test status | +| Notes | Free text for issues, observations, tx hashes | + +--- + +**Related**: [NotionTracker.csv](NotionTracker.csv) | [IndexerTestGuide.md](../IndexerTestGuide.md) diff --git a/packages/issuance/docs/testing/reo/support/NotionTracker.csv b/packages/issuance/docs/testing/reo/support/NotionTracker.csv new file mode 100644 index 000000000..c8ad3a5be --- /dev/null +++ b/packages/issuance/docs/testing/reo/support/NotionTracker.csv @@ -0,0 +1,77 @@ +Test ID,Plan,Test Name,Link,Indexer A,Indexer B,Indexer C,Status,Notes +B-1.1,Baseline,Setup indexer via Explorer,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#11-setup-indexer-via-explorer,,,,Not Started, +B-1.2,Baseline,Register indexer URL and GEO coordinates,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#12-register-indexer-url-and-geo-coordinates,,,,Not Started, +B-1.3,Baseline,Validate Subgraph Service provision and registration,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#13-validate-subgraph-service-provision-and-registration,,,,Not Started, +B-2.1,Baseline,Add stake via Explorer,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#21-add-stake-via-explorer,,,,Not Started, +B-2.2,Baseline,Unstake tokens and withdraw after thawing,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#22-unstake-tokens-and-withdraw-after-thawing,,,,Not Started, +B-3.1,Baseline,View current provision,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#31-view-current-provision,,,,Not Started, +B-3.2,Baseline,Add stake to provision,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#32-add-stake-to-provision,,,,Not Started, +B-3.3,Baseline,Thaw stake from provision,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#33-thaw-stake-from-provision,,,,Not Started, +B-3.4,Baseline,Remove thawed stake from provision,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#34-remove-thawed-stake-from-provision,,,,Not Started, +B-4.1,Baseline,Find subgraph deployments with rewards,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#41-find-subgraph-deployments-with-rewards,,,,Not Started, +B-4.2,Baseline,Create allocation manually,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#42-create-allocation-manually,,,,Not Started, +B-4.3,Baseline,Create allocation via actions queue,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#43-create-allocation-via-actions-queue,,,,Not Started, +B-4.4,Baseline,Create allocation via deployment rules,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#44-create-allocation-via-deployment-rules,,,,Not Started, +B-4.5,Baseline,Reallocate a deployment,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#45-reallocate-a-deployment,,,,Not Started, +B-5.1,Baseline,Send test queries,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#51-send-test-queries,,,,Not Started, +B-5.2,Baseline,Close allocation and collect indexing rewards,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#52-close-allocation-and-collect-indexing-rewards,,,,Not Started, +B-5.3,Baseline,Verify query fee collection,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#53-verify-query-fee-collection,,,,Not Started, +B-5.4,Baseline,Close allocation with explicit POI,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#54-close-allocation-with-explicit-poi,,,,Not Started, +B-6.1,Baseline,Monitor indexer health,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#61-monitor-indexer-health,,,,Not Started, +B-6.2,Baseline,Check epoch progression,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#62-check-epoch-progression,,,,Not Started, +B-6.3,Baseline,Verify no unexpected errors in logs,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#63-verify-no-unexpected-errors-in-logs,,,,Not Started, +B-7.1,Baseline,Full operational cycle,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/BaselineTestPlan.md#71-full-operational-cycle,,,,Not Started, +E-1.1,Eligibility,Open 3+ allocations for eligibility tests,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/IndexerTestGuide.md#11-open-allocations-for-eligibility-tests,,,,Not Started,Need epoch maturity before Set 2 +E-2.1,Eligibility,Renew eligibility,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/IndexerTestGuide.md#21-renew-eligibility,,,,Not Started, +E-2.2,Eligibility,Close allocation while eligible,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/IndexerTestGuide.md#22-close-allocation-while-eligible,,,,Not Started,Requires epoch maturity from Set 1 +E-3.1,Eligibility,Wait for eligibility expiry,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/IndexerTestGuide.md#31-wait-for-eligibility-expiry,,,,Not Started, +E-3.2,Eligibility,Close allocation while ineligible,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/IndexerTestGuide.md#32-close-allocation-while-ineligible,,,,Not Started,Confirm indexingRewards is 0 +E-4.1,Eligibility,Re-renew eligibility,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/IndexerTestGuide.md#41-re-renew-eligibility,,,,Not Started,Do promptly after Set 3 +E-4.2,Eligibility,Close allocation ā€” full rewards after re-renewal,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/IndexerTestGuide.md#42-close-allocation--full-rewards-after-re-renewal,,,,Not Started,Key test: rewards include ineligible period +E-5.1,Eligibility,Verify eligibility when validation is off,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/IndexerTestGuide.md#51-verify-eligibility-when-validation-is-off,,,,Not Started,Coordinator toggles validation +D-1.1,Denial,Configure SUBGRAPH_DENIED reclaim address,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#11-configure-subgraph_denied-reclaim-address,,,,Not Started,Governor access needed +D-1.2,Denial,Record reclaim address GRT balance,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#12-record-reclaim-address-grt-balance,,,,Not Started, +D-2.1,Denial,Verify subgraph is not denied (pre-test),https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#21-verify-subgraph-is-not-denied-pre-test,,,,Not Started,Record accumulator baseline +D-2.2,Denial,Deny subgraph deployment,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#22-deny-subgraph-deployment,,,,Not Started,SAO or Governor access needed +D-2.3,Denial,Redundant deny is idempotent,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#23-redundant-deny-is-idempotent,,,,Not Started, +D-2.4,Denial,Unauthorized deny reverts,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#24-unauthorized-deny-reverts,,,,Not Started, +D-3.1,Denial,Accumulators freeze after denial,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#31-accumulators-freeze-after-denial,,,,Not Started,Wait 30+ min after denial +D-3.2,Denial,getRewards returns frozen value for denied subgraph,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#32-getrewards-returns-frozen-value-for-allocations-on-denied-subgraph,,,,Not Started, +D-3.3,Denial,Denial-period rewards reclaimed,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#33-denial-period-rewards-reclaimed,,,,Not Started,Check RewardsReclaimed events +D-3.4,Denial,Non-denied subgraphs unaffected,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#34-non-denied-subgraphs-unaffected,,,,Not Started,Control test +D-4.1,Denial,POI on denied subgraph defers,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#41-poi-presentation-on-denied-subgraph-defers-returns-0-preserves-state,,,,Not Started,Critical: snapshot NOT advanced +D-4.2,Denial,Multiple POI presentations while denied safe,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#42-multiple-poi-presentations-while-denied-do-not-lose-rewards,,,,Not Started, +D-4.3,Denial,Continue presenting POIs during denial,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#43-indexers-should-continue-presenting-pois-during-denial,,,,Not Started,Prevents staleness +D-5.1,Denial,Undeny subgraph deployment,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#51-undeny-subgraph-deployment,,,,Not Started, +D-5.2,Denial,Accumulators resume after undeny,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#52-accumulators-resume-after-undeny,,,,Not Started,Wait 30+ min after undeny +D-5.3,Denial,Pre-denial rewards claimable after undeny,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#53-pre-denial-rewards-claimable-after-undeny,,,,Not Started,Critical: preserved rewards claimable +D-5.4,Denial,Denial-period rewards excluded from claim,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#54-denial-period-rewards-are-not-included-in-claim,,,,Not Started, +D-6.1,Denial,New allocation while denied,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#61-new-allocation-created-while-subgraph-is-denied,,,,Not Started,Only earns post-undeny rewards +D-6.2,Denial,All allocations close while denied then resume,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#62-all-allocations-close-while-denied-then-new-allocation-after-undeny,,,,Not Started, +D-6.3,Denial,Rapid deny/undeny cycle,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#63-deny-and-undeny-in-rapid-succession,,,,Not Started, +D-6.4,Denial,Denial vs eligibility precedence,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/SubgraphDenialTestPlan.md#64-denial-interaction-with-indexer-eligibility,,,,Not Started,Denial takes precedence over REO +RC-1.1,Conditions,Configure per-condition reclaim addresses,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#11-configure-per-condition-reclaim-addresses,,,,Not Started,Governor access needed +RC-1.2,Conditions,Configure default reclaim address,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#12-configure-default-reclaim-address,,,,Not Started, +RC-1.3,Conditions,Verify fallback routing,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#13-verify-fallback-routing-unconfigured-condition-uses-default,,,,Not Started, +RC-1.4,Conditions,Unauthorized reclaim address change reverts,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#14-unauthorized-reclaim-address-change-reverts,,,,Not Started, +RC-1.5,Conditions,Record baseline balances,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#15-record-baseline-balances,,,,Not Started, +RC-2.1,Conditions,Verify current minimum signal threshold,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#21-verify-current-minimum-signal-threshold,,,,Not Started, +RC-2.2,Conditions,Raise threshold to trigger BELOW_MINIMUM_SIGNAL,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#22-raise-threshold-to-trigger-below_minimum_signal,,,,Not Started,Snapshot accumulators first +RC-2.3,Conditions,Accumulator freezes for below-threshold subgraph,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#23-accumulator-freezes-for-below-threshold-subgraph,,,,Not Started, +RC-2.4,Conditions,Restore threshold and verify resumption,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#24-restore-threshold-and-verify-resumption,,,,Not Started, +RC-3.1,Conditions,Identify subgraph with signal but no allocations,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#31-identify-subgraph-with-signal-but-no-allocations,,,,Not Started, +RC-3.2,Conditions,Verify NO_ALLOCATED_TOKENS reclaim,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#32-verify-no_allocated_tokens-reclaim,,,,Not Started, +RC-3.3,Conditions,Allocations resume from stored baseline,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#33-allocations-resume-from-stored-baseline,,,,Not Started, +RC-4.1,Conditions,Normal claim path (NONE condition),https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#41-normal-claim-path-none-condition,,,,Not Started, +RC-4.2,Conditions,Reclaim path: STALE_POI,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#42-reclaim-path-stale_poi,,,,Not Started,Wait for maxPOIStaleness +RC-4.3,Conditions,Reclaim path: ZERO_POI,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#43-reclaim-path-zero_poi,,,,Not Started, +RC-4.4,Conditions,Defer path: ALLOCATION_TOO_YOUNG,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#44-defer-path-allocation_too_young,,,,Not Started,Same-epoch POI attempt +RC-4.5,Conditions,POI presentation always updates timestamp,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#45-poi-presentation-always-updates-timestamp,,,,Not Started, +RC-5.1,Conditions,Allocation resize reclaims stale rewards,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#51-allocation-resize-reclaims-stale-rewards,,,,Not Started,Wait for staleness +RC-5.2,Conditions,Non-stale resize does not reclaim,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#52-allocation-resize-does-not-reclaim-for-non-stale-allocation,,,,Not Started, +RC-5.3,Conditions,Allocation close reclaims uncollected rewards,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#53-allocation-close-reclaims-uncollected-rewards,,,,Not Started, +RC-6.1,Conditions,POIPresented event on every presentation,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#61-poipresented-event-emitted-on-every-presentation,,,,Not Started,Cross-check all Cycle 4-5 events +RC-6.2,Conditions,RewardsReclaimed events include full context,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#62-rewardsreclaimed-events-include-full-context,,,,Not Started, +RC-6.3,Conditions,View functions reflect frozen state accurately,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#63-view-functions-reflect-frozen-state-accurately,,,,Not Started, +RC-7.1,Conditions,NO_SIGNAL detection,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#71-no_signal-detection,,,,Not Started,Dedicated testnet only +RC-7.2,Conditions,Signal restoration resumes normal distribution,https://github.com/graphprotocol/contracts/blob/reo-testing/packages/issuance/docs/testing/reo/RewardsConditionsTestPlan.md#72-signal-restoration-resumes-normal-distribution,,,,Not Started,Dedicated testnet only From b5083bd48c1e3c2b455d14c25b882bb995ed8421 Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Tue, 24 Feb 2026 11:13:38 +0000 Subject: [PATCH 03/12] feat(issuance): add MockRewardsEligibilityOracle for testnet --- .../mocks/MockRewardsEligibilityOracle.sol | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 packages/issuance/contracts/eligibility/mocks/MockRewardsEligibilityOracle.sol diff --git a/packages/issuance/contracts/eligibility/mocks/MockRewardsEligibilityOracle.sol b/packages/issuance/contracts/eligibility/mocks/MockRewardsEligibilityOracle.sol new file mode 100644 index 000000000..db6186754 --- /dev/null +++ b/packages/issuance/contracts/eligibility/mocks/MockRewardsEligibilityOracle.sol @@ -0,0 +1,38 @@ +// SPDX-License-Identifier: GPL-2.0-or-later +pragma solidity 0.8.33; + +/// @title MockRewardsEligibilityOracle +/// @author The Graph Contributors +/// @notice Testnet REO replacement. Indexers control their own eligibility. +/// @dev Everyone starts eligible. Call setEligible(false) to become ineligible. +contract MockRewardsEligibilityOracle { + mapping(address indexer => bool isIneligible) private ineligible; + + /// @notice Emitted when an indexer changes their eligibility. + /// @param indexer The indexer address. + /// @param eligible Whether the indexer is now eligible. + event EligibilitySet(address indexed indexer, bool indexed eligible); + + /// @notice Toggle the caller's eligibility. + /// @param eligible True to be eligible, false to opt out. + function setEligible(bool eligible) external { + ineligible[msg.sender] = !eligible; + emit EligibilitySet(msg.sender, eligible); + } + + /// @notice Check whether an indexer is eligible for rewards. + /// @dev Called by RewardsManager to check eligibility. + /// @param indexer The indexer address to check. + /// @return True if the indexer is eligible. + function isEligible(address indexer) external view returns (bool) { + return !ineligible[indexer]; + } + + /// @notice ERC165 interface detection. + /// @dev Supports IRewardsEligibility (0x66e305fd) and IERC165 (0x01ffc9a7). + /// @param interfaceId The interface identifier to check. + /// @return True if the interface is supported. + function supportsInterface(bytes4 interfaceId) external pure returns (bool) { + return interfaceId == 0x66e305fd || interfaceId == 0x01ffc9a7; + } +} From c820c811ce19fbdb2cd15727356c4958eff51f48 Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Mon, 2 Mar 2026 18:47:23 +0000 Subject: [PATCH 04/12] fix(rewards): reorder subtraction in _updateSubgraphRewards to avoid underflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The old code's two hooks wrote to different fields with inverted semantics: - onSubgraphSignalUpdate set accRewardsForSubgraph (A) from storage - onSubgraphAllocationUpdate set accRewardsForSubgraphSnapshot (S) from a view (storage + pending), so S leads and A lags after allocation updates After the proxy upgrade, _updateSubgraphRewards computed A.sub(S).add(P) which underflows on the intermediate A - S when A < S. Rearranging to A.add(P).sub(S) adds pending rewards first, avoiding the intermediate underflow. S <= A + P always holds because P covers T1ā†’now (a superset of the T1ā†’T2 gap S - A). Observed on Arbitrum Sepolia: A < S by ~7,235 GRT for subgraphs whose last pre-upgrade interaction was onSubgraphAllocationUpdate. All reward operations (signal, allocation, claim) reverted permanently. --- .../rewards-snapshot-inversion.test.ts | 436 ++++++++++++++++++ .../contracts/rewards/RewardsManager.sol | 15 +- 2 files changed, 444 insertions(+), 7 deletions(-) create mode 100644 packages/contracts-test/tests/unit/rewards/rewards-snapshot-inversion.test.ts diff --git a/packages/contracts-test/tests/unit/rewards/rewards-snapshot-inversion.test.ts b/packages/contracts-test/tests/unit/rewards/rewards-snapshot-inversion.test.ts new file mode 100644 index 000000000..a17427fa8 --- /dev/null +++ b/packages/contracts-test/tests/unit/rewards/rewards-snapshot-inversion.test.ts @@ -0,0 +1,436 @@ +import { Curation } from '@graphprotocol/contracts' +import { GraphToken } from '@graphprotocol/contracts' +import { IStaking } from '@graphprotocol/contracts' +import { RewardsManager } from '@graphprotocol/contracts' +import { deriveChannelKey, GraphNetworkContracts, helpers, randomHexBytes, toGRT } from '@graphprotocol/sdk' +import type { SignerWithAddress } from '@nomiclabs/hardhat-ethers/signers' +import { expect } from 'chai' +import { BigNumber, constants, utils } from 'ethers' +import hre from 'hardhat' + +import { NetworkFixture } from '../lib/fixtures' + +const { HashZero } = constants + +/** + * Tests for snapshot inversion on upgrade. + * + * Terminology: + * A = accRewardsForSubgraph (stored accumulator, set at signal updates) + * S = accRewardsForSubgraphSnapshot (stored snapshot, set at allocation updates) + * P = rewardsSinceSignalSnapshot (pending rewards since last signal snapshot) + * + * After a proxy upgrade, subgraphs whose last pre-upgrade interaction was + * `onSubgraphAllocationUpdate` have A < S. The old code set S from a view function + * (storage + pending) while leaving A at its stored value, so S leads and A lags. + * The original code's `A.sub(S).add(P)` reverts on the intermediate `A - S`. + * + * The fix: Rearrange to `A.add(P).sub(S)` ā€” add P first, then subtract S. + * Since P covers T1ā†’now and the gap S - A covers T1ā†’T2, and now >= T2, + * we have S - A <= P, so S <= A + P always holds. No clamping needed. + * + * These tests use `hardhat_setStorageAt` to directly create the inverted storage state + * that exists on-chain for affected subgraphs. + */ +describe('Rewards: Snapshot Inversion', () => { + const graph = hre.graph() + let governor: SignerWithAddress + let curator: SignerWithAddress + let indexer: SignerWithAddress + + let fixture: NetworkFixture + let contracts: GraphNetworkContracts + let grt: GraphToken + let curation: Curation + let staking: IStaking + let rewardsManager: RewardsManager + + const channelKey = deriveChannelKey() + const subgraphDeploymentID = randomHexBytes() + const allocationID = channelKey.address + const metadata = HashZero + + const tokensToSignal = toGRT('1000') + const tokensToStake = toGRT('100000') + const tokensToAllocate = toGRT('10000') + + // Storage slot for the `subgraphs` mapping in RewardsManagerV1Storage. + // Computed by counting all inherited storage variables: + // Managed: controller(0), _addressCache(1), __gap[10](2-11) = 12 slots + // V1Storage: __DEPRECATED_issuanceRate(12), accRewardsPerSignal(13), + // accRewardsPerSignalLastBlockUpdated(14), subgraphAvailabilityOracle(15), + // subgraphs(16) + const SUBGRAPHS_MAPPING_SLOT = 16 + + /** + * Compute the storage slot for a field within a Subgraph struct in the subgraphs mapping. + * + * For `mapping(bytes32 => Subgraph)` at slot S, key K: + * base = keccak256(abi.encode(K, S)) + * field 0 (accRewardsForSubgraph) = base + 0 + * field 1 (accRewardsForSubgraphSnapshot) = base + 1 + * field 2 (accRewardsPerSignalSnapshot) = base + 2 + * field 3 (accRewardsPerAllocatedToken) = base + 3 + */ + function subgraphStorageSlot(subgraphId: string, fieldOffset: number): string { + const baseSlot = utils.keccak256( + utils.defaultAbiCoder.encode(['bytes32', 'uint256'], [subgraphId, SUBGRAPHS_MAPPING_SLOT]), + ) + return utils.hexZeroPad(BigNumber.from(baseSlot).add(fieldOffset).toHexString(), 32) + } + + /** + * Set a uint256 value at a specific storage slot of the RewardsManager proxy. + */ + async function setStorage(slot: string, value: BigNumber): Promise { + await hre.network.provider.send('hardhat_setStorageAt', [ + rewardsManager.address, + slot, + utils.hexZeroPad(value.toHexString(), 32), + ]) + } + + /** + * Create the inverted snapshot state that exists on-chain for affected subgraphs. + * + * Sets: accRewardsForSubgraphSnapshot = accRewardsForSubgraph + gap + * This is the state left by the old `onSubgraphAllocationUpdate` which wrote + * the snapshot from a view function (storage + pending), while leaving + * accRewardsForSubgraph at its stored value. + */ + async function createInvertedState(subgraphId: string, gap: BigNumber): Promise { + const subgraph = await rewardsManager.subgraphs(subgraphId) + const currentAccRewards = subgraph.accRewardsForSubgraph + const invertedSnapshot = currentAccRewards.add(gap) + + // Write accRewardsForSubgraphSnapshot = currentAccRewards + gap (field offset 1) + const snapshotSlot = subgraphStorageSlot(subgraphId, 1) + await setStorage(snapshotSlot, invertedSnapshot) + + // Verify the inversion was written correctly + const after = await rewardsManager.subgraphs(subgraphId) + expect(after.accRewardsForSubgraphSnapshot).to.equal(invertedSnapshot) + expect(after.accRewardsForSubgraph).to.be.lt(after.accRewardsForSubgraphSnapshot) + } + + before(async function () { + ;[curator, indexer] = await graph.getTestAccounts() + ;({ governor } = await graph.getNamedAccounts()) + + fixture = new NetworkFixture(graph.provider) + contracts = await fixture.load(governor) + grt = contracts.GraphToken as GraphToken + curation = contracts.Curation as Curation + staking = contracts.Staking as IStaking + rewardsManager = contracts.RewardsManager as RewardsManager + }) + + beforeEach(async function () { + await fixture.setUp() + }) + + afterEach(async function () { + await fixture.tearDown() + }) + + async function setupSubgraphWithAllocation() { + // Set issuance rate (200 GRT/block) ā€” the fixture defaults to 0 + await rewardsManager.connect(governor).setIssuancePerBlock(toGRT('200')) + + // Curator signals on subgraph + await grt.connect(governor).mint(curator.address, tokensToSignal) + await grt.connect(curator).approve(curation.address, tokensToSignal) + await curation.connect(curator).mint(subgraphDeploymentID, tokensToSignal, 0) + + // Indexer stakes and allocates + await grt.connect(governor).mint(indexer.address, tokensToStake) + await grt.connect(indexer).approve(staking.address, tokensToStake) + await staking.connect(indexer).stake(tokensToStake) + await staking + .connect(indexer) + .allocateFrom( + indexer.address, + subgraphDeploymentID, + tokensToAllocate, + allocationID, + metadata, + await channelKey.generateProof(indexer.address), + ) + + // Accumulate some rewards + await helpers.mine(50) + + // Sync subgraph state so we have non-zero accRewardsForSubgraph + await rewardsManager.connect(governor).onSubgraphSignalUpdate(subgraphDeploymentID) + } + + describe('storage slot verification', function () { + it('should correctly compute and write to subgraph storage slots', async function () { + await setupSubgraphWithAllocation() + + // Read current state + const before = await rewardsManager.subgraphs(subgraphDeploymentID) + expect(before.accRewardsForSubgraph).to.not.equal(0, 'precondition: should have accumulated rewards') + + // Write a known value to accRewardsForSubgraphSnapshot (field 1) + const testValue = BigNumber.from('12345678901234567890') + const snapshotSlot = subgraphStorageSlot(subgraphDeploymentID, 1) + await setStorage(snapshotSlot, testValue) + + // Read back and verify + const after = await rewardsManager.subgraphs(subgraphDeploymentID) + expect(after.accRewardsForSubgraphSnapshot).to.equal(testValue) + // Other fields should be unchanged + expect(after.accRewardsForSubgraph).to.equal(before.accRewardsForSubgraph) + expect(after.accRewardsPerSignalSnapshot).to.equal(before.accRewardsPerSignalSnapshot) + expect(after.accRewardsPerAllocatedToken).to.equal(before.accRewardsPerAllocatedToken) + }) + }) + + describe('inverted state: accumulated < snapshot', function () { + it('should not revert on onSubgraphSignalUpdate with inverted state', async function () { + await setupSubgraphWithAllocation() + + // Create the pre-upgrade inverted state (snapshot > accumulated by ~7000 GRT) + const gap = toGRT('7000') + await createInvertedState(subgraphDeploymentID, gap) + + // Advance enough blocks so P > gap. At ~200 GRT/block, 50 blocks ā‰ˆ 10,000 GRT > 7,000. + await helpers.mine(50) + + // Old code: A.sub(S).add(P) reverts on intermediate A - S when A < S. + // Fix: A.add(P).sub(S) adds P first, so A + P >= S always holds. + await expect(rewardsManager.connect(governor).onSubgraphSignalUpdate(subgraphDeploymentID)).to.not.be.reverted + }) + + it('should not revert on onSubgraphAllocationUpdate with inverted state', async function () { + await setupSubgraphWithAllocation() + + const gap = toGRT('7000') + await createInvertedState(subgraphDeploymentID, gap) + + await helpers.mine(50) + + await expect(rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID)).to.not.be.reverted + }) + + it('should sync snapshots after first successful call', async function () { + await setupSubgraphWithAllocation() + + const gap = toGRT('7000') + await createInvertedState(subgraphDeploymentID, gap) + + await helpers.mine(50) + + // First call with inverted state + await rewardsManager.connect(governor).onSubgraphSignalUpdate(subgraphDeploymentID) + + // After the fix processes the inverted state, snapshots should be synced + const after = await rewardsManager.subgraphs(subgraphDeploymentID) + expect(after.accRewardsForSubgraphSnapshot).to.equal( + after.accRewardsForSubgraph, + 'snapshot should equal accumulated after fix processes inverted state', + ) + + // Subsequent calls should work normally + await helpers.mine(10) + await expect(rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID)).to.not.be.reverted + + const afterSecond = await rewardsManager.subgraphs(subgraphDeploymentID) + expect(afterSecond.accRewardsForSubgraphSnapshot).to.equal(afterSecond.accRewardsForSubgraph) + }) + }) + + describe('accounting correctness with inverted state', function () { + it('should correctly compute undistributed rewards: (A+P).sub(S)', async function () { + await setupSubgraphWithAllocation() + + // Record state before inversion + const before = await rewardsManager.subgraphs(subgraphDeploymentID) + const perAllocBefore = before.accRewardsPerAllocatedToken + + // Create inversion with a small gap (smaller than rewards that will accrue) + const gap = toGRT('500') + await createInvertedState(subgraphDeploymentID, gap) + + // Advance enough blocks that S < A + P (i.e., new rewards exceed the gap) + // With 200 GRT/block and only one subgraph signalled, each block adds ~200 GRT of P + // 10 blocks ā‰ˆ 2000 GRT of P, gap = 500 GRT + // So (A + P) - S = A + 2000 - (A + 500) = 1500 GRT undistributed + await helpers.mine(10) + + // Call allocation update to distribute rewards + await rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID) + + const after = await rewardsManager.subgraphs(subgraphDeploymentID) + + // accRewardsPerAllocatedToken should increase (rewards were distributed) + expect(perAllocBefore).to.be.lt(after.accRewardsPerAllocatedToken, 'should distribute rewards: 0 < (A + P) - S') + + // The distributed amount should be less than total new rewards (P) + // because the gap represents already-distributed rewards from the old code + // Undistributed = (A + P) - S = P - gap (since S = A + gap) + // If P ā‰ˆ 2000 GRT and gap = 500 GRT, undistributed ā‰ˆ 1500 GRT + // Without the gap subtraction, it would have been P ā‰ˆ 2000 GRT (double-counting) + + // Verify snapshots are synced + expect(after.accRewardsForSubgraphSnapshot).to.equal(after.accRewardsForSubgraph) + }) + + it('should not double-count: distributed rewards account for the gap', async function () { + await setupSubgraphWithAllocation() + + // Get a reference: how many rewards are distributed in normal operation + const stateBefore = await rewardsManager.subgraphs(subgraphDeploymentID) + + // Create a scenario where gap = 500 GRT + const gap = toGRT('500') + await createInvertedState(subgraphDeploymentID, gap) + + await helpers.mine(20) + + // Process the inverted state + await rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID) + const afterInverted = await rewardsManager.subgraphs(subgraphDeploymentID) + const perAllocAfterInverted = afterInverted.accRewardsPerAllocatedToken + + // Now do a SECOND allocation update with normal state (snapshots are synced) + await helpers.mine(20) + await rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID) + const afterNormal = await rewardsManager.subgraphs(subgraphDeploymentID) + + // The second update should distribute ~20 blocks worth of rewards + // The first update distributed less (because gap was subtracted) + // This proves no double-counting: the gap was properly deducted + const firstDelta = perAllocAfterInverted.sub(stateBefore.accRewardsPerAllocatedToken) + const secondDelta = afterNormal.accRewardsPerAllocatedToken.sub(perAllocAfterInverted) + + // First delta < second delta because the gap was subtracted + // (both periods have ~20 blocks, but first period deducts the 500 GRT gap) + expect(firstDelta).to.be.lt(secondDelta, 'first update should distribute less due to gap deduction') + }) + + it('should distribute exactly P - gap rewards (gap deducted from pending)', async function () { + await setupSubgraphWithAllocation() + + // Sync state so we have a clean baseline + await rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID) + const baseline = await rewardsManager.subgraphs(subgraphDeploymentID) + const perAllocBaseline = baseline.accRewardsPerAllocatedToken + + // Create inversion with a known gap + const gap = toGRT('500') + await createInvertedState(subgraphDeploymentID, gap) + + // Mine blocks, then do a normal (non-inverted) reference run in a parallel universe + // We can't do that, but we CAN check that the gap is properly deducted by + // comparing inverted vs non-inverted runs over the same block count. + + // First: process the inverted state + await helpers.mine(20) + await rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID) + const afterInverted = await rewardsManager.subgraphs(subgraphDeploymentID) + const invertedDelta = afterInverted.accRewardsPerAllocatedToken.sub(perAllocBaseline) + + // Second: run the same block count with synced state (no gap) + await helpers.mine(20) + await rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID) + const afterNormal = await rewardsManager.subgraphs(subgraphDeploymentID) + const normalDelta = afterNormal.accRewardsPerAllocatedToken.sub(afterInverted.accRewardsPerAllocatedToken) + + // The inverted run should distribute LESS because the gap was subtracted. + // Both periods have ~20 blocks of rewards, but the inverted period deducts 500 GRT. + expect(invertedDelta).to.be.lt(normalDelta, 'inverted period should distribute less due to gap deduction') + expect(invertedDelta).to.not.equal(0, 'should still distribute some rewards (gap < P)') + }) + }) + + describe('normal operation (no inversion)', function () { + it('should produce identical results when A == S (post-fix steady state)', async function () { + await setupSubgraphWithAllocation() + + // Ensure snapshots are synced (normal state) + await rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID) + const synced = await rewardsManager.subgraphs(subgraphDeploymentID) + expect(synced.accRewardsForSubgraphSnapshot).to.equal(synced.accRewardsForSubgraph) + + const perAllocBefore = synced.accRewardsPerAllocatedToken + + // Advance and update - this is the normal steady-state path + await helpers.mine(20) + await rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID) + + const after = await rewardsManager.subgraphs(subgraphDeploymentID) + + // Rewards should be distributed normally + expect(perAllocBefore).to.be.lt(after.accRewardsPerAllocatedToken) + expect(after.accRewardsForSubgraphSnapshot).to.equal(after.accRewardsForSubgraph) + }) + + it('should handle zero rewards gracefully (same block, no new rewards)', async function () { + await setupSubgraphWithAllocation() + + // Sync state + await rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID) + + // Call again immediately (same block via automine off) + await hre.network.provider.send('evm_setAutomine', [false]) + try { + const tx = await rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID) + await hre.network.provider.send('evm_mine') + await tx.wait() + } finally { + await hre.network.provider.send('evm_setAutomine', [true]) + } + + const after = await rewardsManager.subgraphs(subgraphDeploymentID) + + // Per-alloc-token should be unchanged (zero rewards in same block) + // Note: the transaction itself mines a block, so there may be minimal reward + expect(after.accRewardsForSubgraphSnapshot).to.equal(after.accRewardsForSubgraph) + }) + }) + + describe('realistic pre-upgrade scenario', function () { + it('should handle the exact Arbitrum Sepolia state pattern', async function () { + await setupSubgraphWithAllocation() + + // Simulate: + // 1. Old onSubgraphSignalUpdate wrote accRewardsForSubgraph = X (signal-level view value) + // 2. Old onSubgraphAllocationUpdate wrote accRewardsForSubgraphSnapshot = X + delta + // (via getAccRewardsForSubgraph view which returns storage + pending) + // 3. Proxy upgrade preserves this state + // 4. New code calls _updateSubgraphRewards: A.sub(S) underflows + + // Read current A value + const state = await rewardsManager.subgraphs(subgraphDeploymentID) + const A = state.accRewardsForSubgraph + + // Set S = A + 7235 GRT (matching the ~7235 GRT gap observed on Arbitrum Sepolia) + const observedGap = toGRT('7235') + const accSlot = subgraphStorageSlot(subgraphDeploymentID, 1) + await setStorage(accSlot, A.add(observedGap)) + + // Verify the inversion + const inverted = await rewardsManager.subgraphs(subgraphDeploymentID) + expect(inverted.accRewardsForSubgraph).to.be.lt(inverted.accRewardsForSubgraphSnapshot) + + // Advance blocks (some time passes after upgrade before first interaction) + await helpers.mine(50) + + // First interaction after "upgrade": should NOT revert + await expect(rewardsManager.connect(governor).onSubgraphSignalUpdate(subgraphDeploymentID)).to.not.be.reverted + + // State should be healed + const healed = await rewardsManager.subgraphs(subgraphDeploymentID) + expect(healed.accRewardsForSubgraphSnapshot).to.equal(healed.accRewardsForSubgraph) + + // All subsequent operations should work + await helpers.mine(10) + await expect(rewardsManager.connect(governor).onSubgraphAllocationUpdate(subgraphDeploymentID)).to.not.be.reverted + + await helpers.mine(10) + await expect(rewardsManager.connect(governor).onSubgraphSignalUpdate(subgraphDeploymentID)).to.not.be.reverted + }) + }) +}) diff --git a/packages/contracts/contracts/rewards/RewardsManager.sol b/packages/contracts/contracts/rewards/RewardsManager.sol index 0b223429c..550161a08 100644 --- a/packages/contracts/contracts/rewards/RewardsManager.sol +++ b/packages/contracts/contracts/rewards/RewardsManager.sol @@ -513,13 +513,14 @@ contract RewardsManager is ) = _getSubgraphRewardsState(_subgraphDeploymentID); subgraph.accRewardsPerSignalSnapshot = accRewardsPerSignal; - // Calculate undistributed: rewards accumulated but not yet distributed to allocations. - // Will be just rewards since last snapshot for subgraphs that have had onSubgraphSignalUpdate or - // onSubgraphAllocationUpdate called since upgrade; - // can include non-zero (original) accRewardsForSubgraph - accRewardsForSubgraphSnapshot for - // subgraphs that have not had either hook called since upgrade. - uint256 undistributedRewards = accRewardsForSubgraph.sub(subgraph.accRewardsForSubgraphSnapshot).add( - rewardsSinceSignalSnapshot + // undistributed = (accRewardsForSubgraph + rewardsSinceSignalSnapshot) - accRewardsForSubgraphSnapshot + // We add rewardsSinceSignalSnapshot before subtracting accRewardsForSubgraphSnapshot to avoid + // an intermediate underflow: pre-upgrade state can have accRewardsForSubgraph < + // accRewardsForSubgraphSnapshot (the old alloc hook set the snapshot from a view that included + // pending rewards, while the old signal hook only wrote the stored value). The full expression + // is always non-negative because rewardsSinceSignalSnapshot covers a superset of the gap. + uint256 undistributedRewards = accRewardsForSubgraph.add(rewardsSinceSignalSnapshot).sub( + subgraph.accRewardsForSubgraphSnapshot ); if (condition != RewardsCondition.NONE) { From e0dc1deebc956ada98c6e9ebab562d45a6736a45 Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Mon, 2 Mar 2026 20:30:13 +0000 Subject: [PATCH 05/12] chore: update arbitrumSepolia addresses after deployment RewardsManager and SubgraphService implementation addresses updated with new deployment metadata. --- packages/horizon/addresses.json | 12 ++++++------ packages/subgraph-service/addresses.json | 11 +++++------ 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/packages/horizon/addresses.json b/packages/horizon/addresses.json index a7c8437bd..471a7bd36 100644 --- a/packages/horizon/addresses.json +++ b/packages/horizon/addresses.json @@ -92,17 +92,17 @@ "RewardsManager": { "address": "0x1F49caE7669086c8ba53CC35d1E9f80176d67E79", "proxy": "graph", - "implementation": "0xd681431502e7f9780f14576c17f4459074fc2360", + "implementation": "0x7b7b644d242ad0293c5d6089dfc53b382314ba9d", "proxyDeployment": { "verified": "https://sepolia.arbiscan.io/address/0x1F49caE7669086c8ba53CC35d1E9f80176d67E79#code" }, "implementationDeployment": { - "txHash": "0x09b9cea7f67a55bf81fc92b08d4bb6c7a34f0471d4d1987ef3d914d76ea3f351", + "txHash": "0xc6a1a714b8b22834e8e53ebb749d26f5d8ac8f9acd9c3d110ba304eb39c9e6e6", "argsData": "0x", - "bytecodeHash": "0xee210d0ea0a5e1a46622eb4da78d621523e3efcae872d8a844a69b9677c704ef", - "blockNumber": 240022327, - "timestamp": "2026-02-05T19:03:01.000Z", - "verified": "https://sepolia.arbiscan.io/address/0xd681431502e7f9780f14576c17f4459074fc2360#code" + "bytecodeHash": "0x87ea87471df0e9b9c1febcfc90e1555a746b8243506fb73427d04df3e3ed4518", + "blockNumber": 246428542, + "timestamp": "2026-03-02T20:24:30.000Z", + "verified": "https://sepolia.arbiscan.io/address/0x7b7b644d242ad0293c5d6089dfc53b382314ba9d#code" } }, "HorizonStaking": { diff --git a/packages/subgraph-service/addresses.json b/packages/subgraph-service/addresses.json index 59eb1a67b..bffbb167c 100644 --- a/packages/subgraph-service/addresses.json +++ b/packages/subgraph-service/addresses.json @@ -37,14 +37,13 @@ "address": "0xc24A3dAC5d06d771f657A48B20cE1a671B78f26b", "proxy": "transparent", "proxyAdmin": "0x15737D9f8635cAcd43e110327c930bd5EC1fe098", - "implementation": "0x8a6361e7355d6936ab17aaacde797d01c0e6c4c4", + "implementation": "0x1e91024a6afc5a6c5cdd3caff900120ac90ae420", "implementationDeployment": { - "txHash": "0x9f3fc372d88a97832eb47bc1f98176532b9a54fa0c110dab8399f9e55ab0aa9d", + "txHash": "0xef8fd7c012cc9d304e118bca035562fbef92aff23252b5b16704dac8b558aa63", "argsData": "0x0000000000000000000000009db3ee191681f092607035d9bda6e59fbeaca69500000000000000000000000096e1b86b2739e8a3d59f40f2532cadf9ce8da088000000000000000000000000382863e7b662027117449bd2c49285582bbbd21b000000000000000000000000de761f075200e75485f4358978fb4d1dc8644fd5", - "bytecodeHash": "0x9c25d2f93e6a2a34cc19d00224872e288a8392d5d99b2df680b7e978d148d450", - "blockNumber": 240040490, - "timestamp": "2026-02-05T20:26:15.000Z", - "verified": "https://sepolia.arbiscan.io/address/0x8a6361e7355d6936ab17aaacde797d01c0e6c4c4#code" + "bytecodeHash": "0x6a936cfc4845d1fefa610aff4f060592a4a0ceb41232c368a089a5aa21efb957", + "blockNumber": 246430101, + "timestamp": "2026-03-02T20:38:09.000Z" }, "proxyDeployment": { "verified": "https://sepolia.arbiscan.io/address/0xc24A3dAC5d06d771f657A48B20cE1a671B78f26b#code" From 69f291e2f55796b15bc2d1cac1c485d740a9a82e Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Mon, 2 Mar 2026 21:45:42 +0000 Subject: [PATCH 06/12] docs(deployment): add deployment tagging workflow to setup guide --- packages/deployment/docs/DeploymentSetup.md | 60 +++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/packages/deployment/docs/DeploymentSetup.md b/packages/deployment/docs/DeploymentSetup.md index d7d5de272..4c8875be2 100644 --- a/packages/deployment/docs/DeploymentSetup.md +++ b/packages/deployment/docs/DeploymentSetup.md @@ -158,6 +158,66 @@ export ARBISCAN_API_KEY=$(npx hardhat keystore get ARBISCAN_API_KEY) npx hardhat deploy --skip-prompts --network arbitrumSepolia --tags ``` +## Tagging Deployments (WIP) + +> This convention is a work in progress ā€” feedback and changes welcome. + +After a deployment is committed, create an annotated git tag to record the deployment. +Tags use `deploy/{mainnet|testnet}/YYYY-MM-DD` format. The annotation is auto-generated +from address book diffs, listing which contracts changed. + +**Requires:** `jq` (`sudo apt install jq` / `brew install jq`) + +### Usage + +```bash +# Preview first +./scripts/tag-deployment.sh \ + --deployer "packages/deployment --tags rewards-manager" \ + --network arbitrumSepolia \ + --base main \ + --dry-run + +# Create the tag +./scripts/tag-deployment.sh \ + --deployer "packages/deployment --tags rewards-manager" \ + --network arbitrumSepolia \ + --base main + +# Push +git push origin deploy/testnet/2026-03-02 +``` + +The `--deployer` argument is free-form ā€” describe what performed the deployment: + +- `"packages/deployment --tags rewards-manager,subgraph-service"` +- `"packages/horizon ignition migrate"` +- `"manual: forge script DeployFoo"` + +### Workflow + +1. Deploy contracts and update address books +2. Commit the address book changes +3. Run `tag-deployment.sh` (tag must point to a finalized commit) +4. Push branch and tag + +### Options + +| Option | Description | +| ------------------- | --------------------------------------------- | +| `--deployer ` | What performed the deployment (required) | +| `--network ` | `arbitrumOne` or `arbitrumSepolia` (required) | +| `--base ` | Git ref to diff against (default: `HEAD~1`) | +| `--dry-run` | Preview without creating tag | +| `--sign` | Force-sign the tag with `-s` | + +### Viewing tags + +```bash +git tag -l 'deploy/*' # List all deployment tags +git show --no-patch deploy/testnet/... # View tag annotation +``` + ## See Also - [LocalForkTesting.md](./LocalForkTesting.md) - Fork-based testing workflow From c3d6f958598523911894eb0c6d1dbf575c59bfb2 Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Tue, 3 Mar 2026 08:53:54 +0000 Subject: [PATCH 07/12] feat(deployment): add GRT token tasks (status, balance, transfer, mint) Hardhat tasks for managing testnet GRT: - grt:status: show governor, minter status, total supply - grt:balance: query GRT balance for any address - grt:transfer: send GRT from deployer's balance (no minter role needed) - grt:mint: mint new GRT (requires minter role) --- packages/deployment/hardhat.config.ts | 5 + packages/deployment/tasks/grt-tasks.ts | 480 +++++++++++++++++++++++++ 2 files changed, 485 insertions(+) create mode 100644 packages/deployment/tasks/grt-tasks.ts diff --git a/packages/deployment/hardhat.config.ts b/packages/deployment/hardhat.config.ts index 070414ce8..5dc3d08bb 100644 --- a/packages/deployment/hardhat.config.ts +++ b/packages/deployment/hardhat.config.ts @@ -13,6 +13,7 @@ import checkDeployerTask from './tasks/check-deployer.js' import deploymentStatusTask from './tasks/deployment-status.js' import executeGovernanceTask from './tasks/execute-governance.js' import grantRoleTask from './tasks/grant-role.js' +import { grtBalanceTask, grtMintTask, grtStatusTask, grtTransferTask } from './tasks/grt-tasks.js' import listPendingTask from './tasks/list-pending-implementations.js' import listRolesTask from './tasks/list-roles.js' import { reoDisableTask, reoEnableTask, reoStatusTask } from './tasks/reo-tasks.js' @@ -85,6 +86,10 @@ const config: HardhatUserConfig = { deploymentStatusTask, executeGovernanceTask, grantRoleTask, + grtBalanceTask, + grtMintTask, + grtStatusTask, + grtTransferTask, listPendingTask, listRolesTask, reoDisableTask, diff --git a/packages/deployment/tasks/grt-tasks.ts b/packages/deployment/tasks/grt-tasks.ts new file mode 100644 index 000000000..38116eff6 --- /dev/null +++ b/packages/deployment/tasks/grt-tasks.ts @@ -0,0 +1,480 @@ +import { configVariable, task } from 'hardhat/config' +import { ArgumentType } from 'hardhat/types/arguments' +import type { NewTaskActionFunction } from 'hardhat/types/tasks' +import { createPublicClient, createWalletClient, custom, formatEther, parseEther, type PublicClient } from 'viem' +import { privateKeyToAccount } from 'viem/accounts' + +import { GRAPH_TOKEN_ABI } from '../lib/abis.js' +import { graph } from '../rocketh/deploy.js' + +// governor() is on the Governed base contract, not in IGraphToken +const GOVERNED_ABI = [ + { + inputs: [], + name: 'governor', + outputs: [{ type: 'address' }], + stateMutability: 'view', + type: 'function', + }, +] as const + +// -- Shared Utilities -- + +/** + * Convert network name to env var prefix: arbitrumSepolia ā†’ ARBITRUM_SEPOLIA + */ +function networkToEnvPrefix(networkName: string): string { + return networkName.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase() +} + +/** + * Resolve a configuration variable using Hardhat's hook chain (keystore + env fallback) + */ +async function resolveConfigVar(hre: unknown, name: string): Promise { + try { + const variable = configVariable(name) + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const hooks = (hre as any).hooks + + const value = await hooks.runHandlerChain( + 'configurationVariables', + 'fetchValue', + [variable], + async (_context: unknown, v: { name: string }) => { + const envValue = process.env[v.name] + if (typeof envValue !== 'string') { + throw new Error(`Variable ${v.name} not found`) + } + return envValue + }, + ) + return value + } catch { + return undefined + } +} + +/** + * Get L2GraphToken address from horizon address book + */ +function getGraphTokenAddress(chainId: number): string | null { + const book = graph.getHorizonAddressBook(chainId) + if (!book.entryExists('L2GraphToken')) { + return null + } + return book.getEntry('L2GraphToken')?.address ?? null +} + +// -- Task Types -- + +interface EmptyArgs { + // No arguments +} + +interface BalanceArgs { + account: string +} + +interface TransferArgs { + to: string + amount: string +} + +interface MintArgs { + to: string + amount: string +} + +// -- Task Actions -- + +/** + * Query GRT balance for an address + */ +const balanceAction: NewTaskActionFunction = async (taskArgs, hre) => { + if (!taskArgs.account) { + console.error('\nError: --account is required') + console.error('Usage: npx hardhat grt:balance --account 0x... --network arbitrumSepolia') + return + } + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const conn = await (hre as any).network.connect() + const networkName = conn.networkName + + const client = createPublicClient({ + transport: custom(conn.provider), + }) as PublicClient + + const actualChainId = await client.getChainId() + const forkChainId = graph.getForkTargetChainId() + const targetChainId = forkChainId ?? actualChainId + + const tokenAddress = getGraphTokenAddress(targetChainId) + if (!tokenAddress) { + console.error(`\nError: L2GraphToken not found in address book for chain ${targetChainId}`) + return + } + + const account = taskArgs.account as `0x${string}` + + const balance = (await client.readContract({ + address: tokenAddress as `0x${string}`, + abi: GRAPH_TOKEN_ABI, + functionName: 'balanceOf', + args: [account], + })) as bigint + + console.log(`\nGRT Balance`) + console.log(` Account: ${account}`) + console.log(` Network: ${networkName} (chainId: ${targetChainId})`) + console.log(` Token: ${tokenAddress}`) + console.log(` Balance: ${formatEther(balance)} GRT`) + console.log() +} + +/** + * Transfer GRT from deployer to an address + */ +const transferAction: NewTaskActionFunction = async (taskArgs, hre) => { + if (!taskArgs.to || !taskArgs.amount) { + console.error('\nError: --to and --amount are required') + console.error('Usage: npx hardhat grt:transfer --to 0x... --amount 10000 --network arbitrumSepolia') + return + } + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const conn = await (hre as any).network.connect() + const networkName = conn.networkName + + const client = createPublicClient({ + transport: custom(conn.provider), + }) as PublicClient + + const actualChainId = await client.getChainId() + const forkChainId = graph.getForkTargetChainId() + const targetChainId = forkChainId ?? actualChainId + + const tokenAddress = getGraphTokenAddress(targetChainId) + if (!tokenAddress) { + console.error(`\nError: L2GraphToken not found in address book for chain ${targetChainId}`) + return + } + + // Get deployer key + const keyName = `${networkToEnvPrefix(networkName === 'fork' ? (process.env.HARDHAT_FORK ?? 'arbitrumSepolia') : networkName)}_DEPLOYER_KEY` + const deployerKey = await resolveConfigVar(hre, keyName) + + if (!deployerKey) { + console.error('\nError: No deployer key configured.') + console.error(`Set via keystore: npx hardhat keystore set ${keyName}`) + console.error(`Or environment: export ${keyName}=0x...`) + return + } + + const account = privateKeyToAccount(deployerKey as `0x${string}`) + const to = taskArgs.to as `0x${string}` + const amount = parseEther(taskArgs.amount) + + // Check deployer balance + const balance = (await client.readContract({ + address: tokenAddress as `0x${string}`, + abi: GRAPH_TOKEN_ABI, + functionName: 'balanceOf', + args: [account.address], + })) as bigint + + if (balance < amount) { + console.error(`\nError: Insufficient balance`) + console.error(` Deployer balance: ${formatEther(balance)} GRT`) + console.error(` Requested: ${taskArgs.amount} GRT`) + return + } + + console.log(`\nTransferring GRT`) + console.log(` From: ${account.address}`) + console.log(` To: ${to}`) + console.log(` Amount: ${taskArgs.amount} GRT`) + console.log(` Network: ${networkName} (chainId: ${targetChainId})`) + console.log(` Token: ${tokenAddress}`) + + const walletClient = createWalletClient({ + account, + transport: custom(conn.provider), + }) + + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const hash = await (walletClient as any).writeContract({ + address: tokenAddress as `0x${string}`, + abi: GRAPH_TOKEN_ABI, + functionName: 'transfer', + args: [to, amount], + }) + + console.log(` TX: ${hash}`) + + const receipt = await client.waitForTransactionReceipt({ hash }) + if (receipt.status === 'success') { + const newBalance = (await client.readContract({ + address: tokenAddress as `0x${string}`, + abi: GRAPH_TOKEN_ABI, + functionName: 'balanceOf', + args: [to], + })) as bigint + + console.log(`\n Transferred successfully!`) + console.log(` Recipient balance: ${formatEther(newBalance)} GRT\n`) + } else { + console.error(`\n Transaction failed\n`) + } +} + +/** + * Mint GRT to an address (requires deployer to be a minter) + */ +const mintAction: NewTaskActionFunction = async (taskArgs, hre) => { + if (!taskArgs.to || !taskArgs.amount) { + console.error('\nError: --to and --amount are required') + console.error('Usage: npx hardhat grt:mint --to 0x... --amount 10000 --network arbitrumSepolia') + return + } + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const conn = await (hre as any).network.connect() + const networkName = conn.networkName + + const client = createPublicClient({ + transport: custom(conn.provider), + }) as PublicClient + + const actualChainId = await client.getChainId() + const forkChainId = graph.getForkTargetChainId() + const targetChainId = forkChainId ?? actualChainId + + const tokenAddress = getGraphTokenAddress(targetChainId) + if (!tokenAddress) { + console.error(`\nError: L2GraphToken not found in address book for chain ${targetChainId}`) + return + } + + // Get deployer key + const keyName = `${networkToEnvPrefix(networkName === 'fork' ? (process.env.HARDHAT_FORK ?? 'arbitrumSepolia') : networkName)}_DEPLOYER_KEY` + const deployerKey = await resolveConfigVar(hre, keyName) + + if (!deployerKey) { + console.error('\nError: No deployer key configured.') + console.error(`Set via keystore: npx hardhat keystore set ${keyName}`) + console.error(`Or environment: export ${keyName}=0x...`) + return + } + + const account = privateKeyToAccount(deployerKey as `0x${string}`) + const to = taskArgs.to as `0x${string}` + const amount = parseEther(taskArgs.amount) + + // Check deployer is a minter + const isMinter = (await client.readContract({ + address: tokenAddress as `0x${string}`, + abi: GRAPH_TOKEN_ABI, + functionName: 'isMinter', + args: [account.address], + })) as boolean + + if (!isMinter) { + console.error(`\nError: Deployer ${account.address} is not a minter on GraphToken`) + console.error('The deployer must be added as a minter by the governor first.') + return + } + + console.log(`\nMinting GRT`) + console.log(` To: ${to}`) + console.log(` Amount: ${taskArgs.amount} GRT`) + console.log(` Network: ${networkName} (chainId: ${targetChainId})`) + console.log(` Token: ${tokenAddress}`) + console.log(` Minter: ${account.address}`) + + const walletClient = createWalletClient({ + account, + transport: custom(conn.provider), + }) + + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const hash = await (walletClient as any).writeContract({ + address: tokenAddress as `0x${string}`, + abi: GRAPH_TOKEN_ABI, + functionName: 'mint', + args: [to, amount], + }) + + console.log(` TX: ${hash}`) + + const receipt = await client.waitForTransactionReceipt({ hash }) + if (receipt.status === 'success') { + // Read new balance + const newBalance = (await client.readContract({ + address: tokenAddress as `0x${string}`, + abi: GRAPH_TOKEN_ABI, + functionName: 'balanceOf', + args: [to], + })) as bigint + + console.log(`\n Minted successfully!`) + console.log(` New balance: ${formatEther(newBalance)} GRT\n`) + } else { + console.error(`\n Transaction failed\n`) + } +} + +/** + * Show GRT token status: governor, deployer minter check, total supply + */ +const statusAction: NewTaskActionFunction = async (_taskArgs, hre) => { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const conn = await (hre as any).network.connect() + const networkName = conn.networkName + + const client = createPublicClient({ + transport: custom(conn.provider), + }) as PublicClient + + const actualChainId = await client.getChainId() + const forkChainId = graph.getForkTargetChainId() + const targetChainId = forkChainId ?? actualChainId + + const tokenAddress = getGraphTokenAddress(targetChainId) + if (!tokenAddress) { + console.error(`\nError: L2GraphToken not found in address book for chain ${targetChainId}`) + return + } + + // Read token info in parallel + const [governor, totalSupply] = await Promise.all([ + client.readContract({ + address: tokenAddress as `0x${string}`, + abi: GOVERNED_ABI, + functionName: 'governor', + }) as Promise, + client.readContract({ + address: tokenAddress as `0x${string}`, + abi: GRAPH_TOKEN_ABI, + functionName: 'totalSupply', + }) as Promise, + ]) + + console.log(`\nGRT Token Status`) + console.log(` Token: ${tokenAddress}`) + console.log(` Network: ${networkName} (chainId: ${targetChainId})`) + console.log(` Total supply: ${formatEther(totalSupply)} GRT`) + console.log(` Governor: ${governor}`) + + // Check if governor is a minter + const governorIsMinter = (await client.readContract({ + address: tokenAddress as `0x${string}`, + abi: GRAPH_TOKEN_ABI, + functionName: 'isMinter', + args: [governor], + })) as boolean + console.log(` Governor is minter: ${governorIsMinter ? 'yes' : 'no'}`) + + // Check deployer if key is available + const keyName = `${networkToEnvPrefix(networkName === 'fork' ? (process.env.HARDHAT_FORK ?? 'arbitrumSepolia') : networkName)}_DEPLOYER_KEY` + const deployerKey = await resolveConfigVar(hre, keyName) + + if (deployerKey) { + const deployer = privateKeyToAccount(deployerKey as `0x${string}`) + const deployerIsMinter = (await client.readContract({ + address: tokenAddress as `0x${string}`, + abi: GRAPH_TOKEN_ABI, + functionName: 'isMinter', + args: [deployer.address], + })) as boolean + + console.log(`\n Deployer: ${deployer.address}`) + console.log(` Deployer is minter: ${deployerIsMinter ? 'yes' : 'no'}`) + console.log(` Deployer is governor: ${deployer.address.toLowerCase() === governor.toLowerCase() ? 'yes' : 'no'}`) + + if (!deployerIsMinter) { + console.log(`\n To add deployer as minter, the governor must call:`) + console.log(` addMinter(${deployer.address})`) + } + } else { + console.log(`\n Deployer key not configured (${keyName})`) + } + + console.log() +} + +// -- Task Definitions -- + +/** + * Show GRT token status: governor, deployer minter status, total supply + * + * Examples: + * npx hardhat grt:status --network arbitrumSepolia + */ +export const grtStatusTask = task('grt:status', 'Show GRT token status (governor, minter, supply)') + .setAction(async () => ({ default: statusAction })) + .build() + +/** + * Query GRT balance for an address + * + * Examples: + * npx hardhat grt:balance --account 0x1234... --network arbitrumSepolia + */ +export const grtBalanceTask = task('grt:balance', 'Query GRT balance for an address') + .addOption({ + name: 'account', + description: 'Address to query balance for', + type: ArgumentType.STRING, + defaultValue: '', + }) + .setAction(async () => ({ default: balanceAction })) + .build() + +/** + * Transfer testnet GRT from deployer to an address + * + * Uses the deployer's existing balance. No minter role needed. + * + * Examples: + * npx hardhat grt:transfer --to 0x1234... --amount 10000 --network arbitrumSepolia + */ +export const grtTransferTask = task('grt:transfer', 'Transfer GRT from deployer to an address') + .addOption({ + name: 'to', + description: 'Recipient address', + type: ArgumentType.STRING, + defaultValue: '', + }) + .addOption({ + name: 'amount', + description: 'Amount of GRT to transfer (in whole tokens, e.g. 10000)', + type: ArgumentType.STRING, + defaultValue: '', + }) + .setAction(async () => ({ default: transferAction })) + .build() + +/** + * Mint testnet GRT to an address + * + * Requires deployer to be a minter on the GraphToken contract. + * The deployer/governor is a minter by default after deployment. + * + * Examples: + * npx hardhat grt:mint --to 0x1234... --amount 10000 --network arbitrumSepolia + */ +export const grtMintTask = task('grt:mint', 'Mint testnet GRT to an address') + .addOption({ + name: 'to', + description: 'Recipient address', + type: ArgumentType.STRING, + defaultValue: '', + }) + .addOption({ + name: 'amount', + description: 'Amount of GRT to mint (in whole tokens, e.g. 10000)', + type: ArgumentType.STRING, + defaultValue: '', + }) + .setAction(async () => ({ default: mintAction })) + .build() + +export default [grtStatusTask, grtBalanceTask, grtTransferTask, grtMintTask] From 9f0b5f35591e16410a7222babbedaa85d2620eae Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Tue, 3 Mar 2026 10:59:27 +0000 Subject: [PATCH 08/12] docs(testing): add network subgraph endpoint and allocation lifetime to config reference --- .../docs/testing/reo/BaselineTestPlan.md | 26 ++++++++++++++----- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/packages/issuance/docs/testing/reo/BaselineTestPlan.md b/packages/issuance/docs/testing/reo/BaselineTestPlan.md index fd17a49e6..d466f755f 100644 --- a/packages/issuance/docs/testing/reo/BaselineTestPlan.md +++ b/packages/issuance/docs/testing/reo/BaselineTestPlan.md @@ -799,13 +799,25 @@ Run these operations in sequence to validate a complete indexer lifecycle: ### Arbitrum Sepolia (testnet) -| Parameter | Value | -| ----------------- | --------------------------------------- | -| Explorer | | -| Gateway | | -| Epoch length | ~554 blocks (~110 minutes) | -| Min indexer stake | 100k GRT | -| Thawing period | Shortened for faster testing | +| Parameter | Value | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Explorer | | +| Gateway | | +| Network subgraph | [eAENt2ctaMdbCY34apzXYkBy2nEYwyojjVxLahsHo9D](https://thegraph.com/explorer/subgraphs/eAENt2ctaMdbCY34apzXYkBy2nEYwyojjVxLahsHo9D?view=Query&chain=arbitrum-one) | +| Epoch length | ~554 blocks (~110 minutes) | +| Max allocation lifetime | 8 epochs (~15 hours) | +| Min indexer stake | 100k GRT | +| Thawing period | Shortened for faster testing | + +### Querying the network subgraph + +All GraphQL verification queries in this plan run against the network subgraph. To query it, use the gateway endpoint with your API key: + +``` +https://gateway-arbitrum.network.thegraph.com/api//subgraphs/id/eAENt2ctaMdbCY34apzXYkBy2nEYwyojjVxLahsHo9D +``` + +You can also use the Explorer playground at the link above. All addresses in queries must be **lowercase** ā€” invisible Unicode characters from copy-pasting (e.g. from chat tools) will cause empty results. ### Arbitrum One (mainnet) From d4fcc55083937989f92e7559560feb4e25452a08 Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Tue, 3 Mar 2026 11:14:26 +0000 Subject: [PATCH 09/12] docs(testing): use standard network subgraph for Arbitrum Sepolia --- .../docs/testing/reo/BaselineTestPlan.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/issuance/docs/testing/reo/BaselineTestPlan.md b/packages/issuance/docs/testing/reo/BaselineTestPlan.md index d466f755f..5c38fe5f4 100644 --- a/packages/issuance/docs/testing/reo/BaselineTestPlan.md +++ b/packages/issuance/docs/testing/reo/BaselineTestPlan.md @@ -799,22 +799,22 @@ Run these operations in sequence to validate a complete indexer lifecycle: ### Arbitrum Sepolia (testnet) -| Parameter | Value | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Explorer | | -| Gateway | | -| Network subgraph | [eAENt2ctaMdbCY34apzXYkBy2nEYwyojjVxLahsHo9D](https://thegraph.com/explorer/subgraphs/eAENt2ctaMdbCY34apzXYkBy2nEYwyojjVxLahsHo9D?view=Query&chain=arbitrum-one) | -| Epoch length | ~554 blocks (~110 minutes) | -| Max allocation lifetime | 8 epochs (~15 hours) | -| Min indexer stake | 100k GRT | -| Thawing period | Shortened for faster testing | +| Parameter | Value | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Explorer | | +| Gateway | | +| Network subgraph | [3xQHhMudr1oh69ut36G2mbzpYmYxwqCeU6wwqyCDCnqV](https://thegraph.com/explorer/subgraphs/3xQHhMudr1oh69ut36G2mbzpYmYxwqCeU6wwqyCDCnqV?view=Query&chain=arbitrum-one) | +| Epoch length | ~554 blocks (~110 minutes) | +| Max allocation lifetime | 8 epochs (~15 hours) | +| Min indexer stake | 100k GRT | +| Thawing period | Shortened for faster testing | ### Querying the network subgraph All GraphQL verification queries in this plan run against the network subgraph. To query it, use the gateway endpoint with your API key: ``` -https://gateway-arbitrum.network.thegraph.com/api//subgraphs/id/eAENt2ctaMdbCY34apzXYkBy2nEYwyojjVxLahsHo9D +https://gateway-arbitrum.network.thegraph.com/api//subgraphs/id/3xQHhMudr1oh69ut36G2mbzpYmYxwqCeU6wwqyCDCnqV ``` You can also use the Explorer playground at the link above. All addresses in queries must be **lowercase** ā€” invisible Unicode characters from copy-pasting (e.g. from chat tools) will cause empty results. From b9bdfbeeed9bdbbc6959bb43020728b97a7b735b Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Tue, 3 Mar 2026 12:59:16 +0000 Subject: [PATCH 10/12] chore: release @graphprotocol/address-book v1.2.0 - Bump address-book to 1.2.0 (REO and rewards reclaiming addresses) - Add address-book to publish workflow package choices - Add auto-tagging step to publish workflow - Add publishing guide for address-book release process --- .github/workflows/publish.yml | 12 ++ packages/address-book/CHANGELOG.md | 6 + packages/address-book/docs/PublishingGuide.md | 108 ++++++++++++++++++ packages/address-book/package.json | 2 +- 4 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 packages/address-book/docs/PublishingGuide.md diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index ea8d80315..2348142fd 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -8,6 +8,7 @@ on: required: true type: choice options: + - address-book - contracts - sdk tag: @@ -29,8 +30,19 @@ jobs: uses: ./.github/actions/setup - name: Set npm token for publishing run: pnpm config set //registry.npmjs.org/:_authToken ${{ secrets.GRAPHPROTOCOL_NPM_TOKEN }} + - name: Read package info + id: pkg + shell: bash + run: | + PKG_NAME=$(node -p "require('./packages/${{ inputs.package }}/package.json').name") + PKG_VERSION=$(node -p "require('./packages/${{ inputs.package }}/package.json').version") + echo "tag=${PKG_NAME}@${PKG_VERSION}" >> $GITHUB_OUTPUT - name: Publish šŸš€ shell: bash run: | pushd packages/${{ inputs.package }} pnpm publish --tag ${{ inputs.tag }} --access public --no-git-checks + - name: Tag release + run: | + git tag ${{ steps.pkg.outputs.tag }} + git push origin ${{ steps.pkg.outputs.tag }} diff --git a/packages/address-book/CHANGELOG.md b/packages/address-book/CHANGELOG.md index 11e71dae2..62c32a45e 100644 --- a/packages/address-book/CHANGELOG.md +++ b/packages/address-book/CHANGELOG.md @@ -1,5 +1,11 @@ # @graphprotocol/address-book +## 1.2.0 + +### Minor Changes + +- Upgraded Rewards Manager and Subgraph Service with Rewards Eligibility Oracle and recwards reclaiming. + ## 1.1.0 ### Minor Changes diff --git a/packages/address-book/docs/PublishingGuide.md b/packages/address-book/docs/PublishingGuide.md new file mode 100644 index 000000000..d4b021783 --- /dev/null +++ b/packages/address-book/docs/PublishingGuide.md @@ -0,0 +1,108 @@ +# Publishing @graphprotocol/address-book + +Step-by-step guide for releasing a new version of the address-book package and deploying it to the network monitor. + +## Prerequisites + +- npm publish access for the `@graphprotocol` scope +- Write access to the [network-monitor](https://github.com/edgeandnode/network-monitor) repo +- Ability to trigger GitHub Actions workflows in both repos + +## Step 1: Update Address Files + +Update the source address files in the contracts monorepo. These live in: + +- `packages/horizon/addresses.json` +- `packages/subgraph-service/addresses.json` +- `packages/issuance/addresses.json` + +The address-book package symlinks to these files during development, so changes here are automatically reflected locally. + +## Step 2: Create a Changeset + +From the monorepo root: + +```bash +pnpm changeset +``` + +- Select `@graphprotocol/address-book` +- Choose the bump type (patch/minor/major) +- Describe what changed (e.g., "update arbitrumSepolia addresses after deployment") + +## Step 3: Version the Package + +```bash +pnpm changeset version +``` + +This consumes the changeset, bumps the version in `packages/address-book/package.json`, and updates `CHANGELOG.md`. + +## Step 4: Commit and Push + +```bash +git add . +git commit -m "chore: release @graphprotocol/address-book vX.Y.Z" +git push +``` + +## Step 5: Publish to npm + +1. Go to the contracts monorepo ā†’ Actions ā†’ "Publish package to NPM" +2. Select `address-book` as the package +3. Set tag to `latest` (or a pre-release tag) +4. Run workflow + +The workflow automatically: + +- Publishes to npm (symlinks are converted to real files via `prepublishOnly`) +- Creates and pushes a git tag (`@graphprotocol/address-book@X.Y.Z`) + +## Step 6: Verify on npm + +```bash +npm view @graphprotocol/address-book version +``` + +Confirm the new version is live. + +## Step 7: Update the Network Monitor + +In the [network-monitor](https://github.com/edgeandnode/network-monitor) repo: + +1. Update `package.json` to reference the new version: + + ```json + "@graphprotocol/address-book": "X.Y.Z", + ``` + +2. Run `yarn` to update the lockfile +3. Commit and push + +The network monitor imports addresses from: + +- `@graphprotocol/address-book/horizon/addresses.json` (in `src/env.ts`) +- `@graphprotocol/address-book/subgraph-service/addresses.json` (in `src/env.ts`, `src/tests/contracts.ts`) + +## Step 8: Deploy the Network Monitor + +1. Go to the network-monitor repo ā†’ Actions ā†’ "Deployment" +2. Choose the target cluster: + - **`network`** ā†’ production (mainnet) + - **`testnet`** ā†’ testnet +3. Run workflow + +This builds a Docker image, pushes it to `ghcr.io/edgeandnode/network-monitor`, and restarts the StatefulSet on GKE. + +## Quick Reference + +| Step | Action | Where | +| ---- | ------------------------------- | ----------------------------- | +| 1 | Update address files | contracts monorepo | +| 2 | `pnpm changeset` | contracts monorepo | +| 3 | `pnpm changeset version` | contracts monorepo | +| 4 | Commit + push | contracts monorepo | +| 5 | Publish to npm (auto-tags) | contracts monorepo GH Actions | +| 6 | Verify on npm | npmjs.com | +| 7 | Bump version in network-monitor | network-monitor repo | +| 8 | Deploy network monitor | network-monitor GH Actions | diff --git a/packages/address-book/package.json b/packages/address-book/package.json index 28664ce0e..471e51052 100644 --- a/packages/address-book/package.json +++ b/packages/address-book/package.json @@ -1,6 +1,6 @@ { "name": "@graphprotocol/address-book", - "version": "1.1.0", + "version": "1.2.0", "publishConfig": { "access": "public" }, From c5fdd54e1e2d70b22d8eccf598e4007746f1e5ca Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Tue, 3 Mar 2026 13:38:42 +0000 Subject: [PATCH 11/12] fix: address PR review feedback - Fix typo "recwards" -> "rewards" in address-book CHANGELOG - Throw error instead of silent return on missing Arbiscan API key - Update SyncBytecodeDetectionFix docs to match actual implementation --- packages/address-book/CHANGELOG.md | 2 +- .../docs/SyncBytecodeDetectionFix.md | 77 +++++++------------ packages/deployment/tasks/verify-contract.ts | 9 ++- 3 files changed, 35 insertions(+), 53 deletions(-) diff --git a/packages/address-book/CHANGELOG.md b/packages/address-book/CHANGELOG.md index 62c32a45e..1427d84c2 100644 --- a/packages/address-book/CHANGELOG.md +++ b/packages/address-book/CHANGELOG.md @@ -4,7 +4,7 @@ ### Minor Changes -- Upgraded Rewards Manager and Subgraph Service with Rewards Eligibility Oracle and recwards reclaiming. +- Upgraded Rewards Manager and Subgraph Service with Rewards Eligibility Oracle and rewards reclaiming. ## 1.1.0 diff --git a/packages/deployment/docs/SyncBytecodeDetectionFix.md b/packages/deployment/docs/SyncBytecodeDetectionFix.md index 641f60525..331d7cbe8 100644 --- a/packages/deployment/docs/SyncBytecodeDetectionFix.md +++ b/packages/deployment/docs/SyncBytecodeDetectionFix.md @@ -45,27 +45,32 @@ The sync step saved the **implementation's bytecode** under the **proxy's deploy ## Fixes Applied -### Fix 1: Auto-Heal Bytecode Hash ([sync-utils.ts:641-683](../lib/sync-utils.ts#L641-L683)) +### Fix 1: Hash Comparison and Stale Record Cleanup ([sync-utils.ts:645-679](../lib/sync-utils.ts#L645-L679)) -When sync detects missing/mismatched bytecode hash: +When sync processes an implementation: -1. **Fetch on-chain bytecode** from the implementation address -2. **Compare three versions**: local artifact, on-chain, address book -3. **Auto-heal** if local matches on-chain: +1. **Compare local artifact hash to address-book-stored hash** +2. **If hashes match**: sync the implementation record to rocketh normally +3. **If hashes don't match**: overwrite any stale rocketh record with empty bytecode, forcing a fresh deployment ```typescript - if (localHash === onChainHash) { - // Update address book with verified hash - hashMatches = true - shouldSync = true - syncNotes.push('hash verified' or 'hash healed') + if (storedHash && localHash) { + hashMatches = storedHash === localHash + } + + // Clean up stale rocketh record if hash doesn't match + if (!hashMatches && existingImpl) { + // Overwrite stale record with empty bytecode - forces fresh deployment + await env.save(`${spec.name}_Implementation`, { + address: existingImpl.address, + bytecode: '0x', + deployedBytecode: undefined, + ... + }) } ``` -4. **Show clear status** if they differ: - - `local code changed` - local differs from on-chain (ready to deploy) - - `impl state unclear` - all three hashes differ (investigation needed) - - `impl unverified` - couldn't fetch on-chain bytecode +This ensures rocketh correctly detects when local code has changed and triggers a new deployment. ### Fix 2: Don't Store Wrong Bytecode for Proxy ([sync-utils.ts:508-532](../lib/sync-utils.ts#L508-L532)) @@ -85,23 +90,10 @@ This ensures rocketh only uses implementation bytecode for the actual implementa ## Expected Behavior After Fix -### Scenario 1: Local Matches On-Chain (Hash Missing) - -**Before**: +### Scenario 1: Local Matches Address Book -``` -ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (code changed) -āœ“ SubgraphService implementation unchanged ā† WRONG! -``` - -**After**: - -``` -ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (hash verified) -āœ“ SubgraphService implementation unchanged ā† Correct (hash now matches) -``` - -Address book is auto-healed with correct bytecode hash. +When local artifact hash matches the stored hash, sync proceeds normally and rocketh +correctly reports the implementation as unchanged. ### Scenario 2: Local Code Changed @@ -122,21 +114,11 @@ Address book is auto-healed with correct bytecode hash. Deploy correctly detects the change and deploys new implementation. -### Scenario 3: Complex State (All Different) - -**Before**: - -``` -ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (code changed) -``` - -**After**: - -``` -ā–³ SubgraphService @ 0xc24A3dAC... ā†’ 0x2af1b0ed... (impl state unclear) -``` +### Scenario 3: Stale Rocketh Record -Clear warning that investigation needed - all three hashes differ. +When the hash doesn't match and a stale rocketh record exists, sync overwrites it +with empty bytecode. This forces the next deploy to create a fresh implementation +record rather than incorrectly reporting "unchanged". ## Testing @@ -156,10 +138,9 @@ npx hardhat deploy --skip-prompts --network arbitrumSepolia --tags subgraph-serv ## Migration Notes -- **No manual migration needed** - the fix auto-heals address books -- First sync after fix will fetch on-chain bytecode and update hashes -- Address book will be updated in place with correct metadata -- Subsequent syncs will use the healed hashes +- **No manual migration needed** - stale rocketh records are cleaned up automatically +- First sync after fix will detect hash mismatches and clear stale records +- Subsequent deploys will create fresh implementation records ## Related Files diff --git a/packages/deployment/tasks/verify-contract.ts b/packages/deployment/tasks/verify-contract.ts index 3a7ad40b5..c30d1ac46 100644 --- a/packages/deployment/tasks/verify-contract.ts +++ b/packages/deployment/tasks/verify-contract.ts @@ -534,10 +534,11 @@ const action: NewTaskActionFunction = async (taskArgs, hre) => { // Get API key from keystore const apiKey = await resolveConfigVar(hre, 'ARBISCAN_API_KEY') if (!apiKey) { - console.error('\nError: No Arbiscan API key configured.') - console.error('Set via keystore: npx hardhat keystore set ARBISCAN_API_KEY') - console.error('Or environment: export ARBISCAN_API_KEY=...\n') - return + throw new Error( + 'No Arbiscan API key configured.\n' + + 'Set via keystore: npx hardhat keystore set ARBISCAN_API_KEY\n' + + 'Or environment: export ARBISCAN_API_KEY=...', + ) } // Determine contracts to verify From 110a4877279e833d6fecd69b99ce04835ba8733c Mon Sep 17 00:00:00 2001 From: Rembrandt Kuipers <50174308+RembrandtK@users.noreply.github.com> Date: Tue, 3 Mar 2026 14:28:15 +0000 Subject: [PATCH 12/12] fix(address-book): add missing issuance addresses symlink The src/issuance/ directory and symlink were not created when issuance support was added to the publish scripts, causing prepublishOnly to fail. --- packages/address-book/src/issuance/addresses.json | 1 + 1 file changed, 1 insertion(+) create mode 120000 packages/address-book/src/issuance/addresses.json diff --git a/packages/address-book/src/issuance/addresses.json b/packages/address-book/src/issuance/addresses.json new file mode 120000 index 000000000..b73ad34ff --- /dev/null +++ b/packages/address-book/src/issuance/addresses.json @@ -0,0 +1 @@ +../../../issuance/addresses.json \ No newline at end of file