Skip to content

Commit 2ba0551

Browse files
committed
docs: add test plans for subgraph denial and reward conditions
Draft test plans covering issuance upgrade behavior changes beyond REO: - SubgraphDenialTestPlan: 6 cycles, 18 tests for deny/undeny lifecycle, accumulator freeze, allocation-level deferral, reward recovery - RewardsConditionsTestPlan: 7 cycles, 26 tests for reclaim system, below-minimum signal, zero allocated tokens, POI presentation paths, allocation resize/close, observability Updated README with dependency tree and coverage summaries. Added 44 new tests to NotionTracker.csv.
1 parent 5a71fcd commit 2ba0551

4 files changed

Lines changed: 1575 additions & 14 deletions

File tree

packages/issuance/docs/testing/reo/README.md

Lines changed: 68 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,22 @@
1-
# REO Testing Documentation
1+
# Issuance Upgrade Testing Documentation
22

3-
Comprehensive test plans for validating The Graph Network after the Rewards Eligibility Oracle (REO) upgrade. Two-layer approach: baseline indexer operations (upgrade-agnostic) plus REO-specific eligibility, oracle, and rewards tests.
3+
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.
44

55
## Quick Start
66

77
1. **Indexers start here** → Follow [IndexerTestGuide.md](IndexerTestGuide.md)
88
2. **Detailed baseline reference**[BaselineTestPlan.md](BaselineTestPlan.md)
9-
3. **Detailed REO reference**[ReoTestPlan.md](ReoTestPlan.md)
9+
3. **REO eligibility tests**[ReoTestPlan.md](ReoTestPlan.md)
10+
4. **Subgraph denial tests**[SubgraphDenialTestPlan.md](SubgraphDenialTestPlan.md)
11+
5. **Reward conditions tests**[RewardsConditionsTestPlan.md](RewardsConditionsTestPlan.md)
1012

1113
## Reading Order
1214

1315
1. **[BaselineTestPlan.md](BaselineTestPlan.md)** -- Upgrade-agnostic indexer operations (run first)
1416
2. **[ReoTestPlan.md](ReoTestPlan.md)** -- REO-specific eligibility, oracle, and rewards tests (run after baseline passes)
15-
3. **[IndexerTestGuide.md](IndexerTestGuide.md)** -- Condensed guide for indexers running eligibility tests (subset of ReoTestPlan)
17+
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)
18+
4. **[SubgraphDenialTestPlan.md](SubgraphDenialTestPlan.md)** -- Subgraph denial two-level handling, accumulator freeze, deferral, deny/undeny lifecycle (run after reclaim setup)
19+
5. **[IndexerTestGuide.md](IndexerTestGuide.md)** -- Condensed guide for indexers running eligibility tests (subset of ReoTestPlan)
1620

1721
```
1822
BaselineTestPlan (7 cycles, 22 tests)
@@ -23,6 +27,17 @@ BaselineTestPlan (7 cycles, 22 tests)
2327
│ Depends on: Baseline Cycles 1-7 pass first
2428
│ Cycle 2.3 opens allocations reused in Cycle 6
2529
30+
├──▶ RewardsConditionsTestPlan (7 cycles, 26 tests)
31+
│ Covers: reclaim config, below-minimum signal, zero allocated tokens,
32+
│ POI paths (stale/zero/too-young), allocation resize/close, observability
33+
│ Depends on: Baseline Cycles 1-7 pass first
34+
│ Cycle 1 configures reclaim addresses used by all reclaim tests
35+
36+
├──▶ SubgraphDenialTestPlan (6 cycles, 18 tests)
37+
│ Covers: deny/undeny state, accumulator freeze, allocation deferral,
38+
│ pre-denial reward recovery, edge cases
39+
│ Depends on: Baseline + RewardsConditionsTestPlan Cycle 1 (reclaim setup)
40+
2641
└──▶ IndexerTestGuide (5 sets, 8 tests)
2742
Covers: eligible/ineligible/recovery flows
2843
Depends on: Baseline Cycles 1-4 (staked, provisioned, can allocate)
@@ -33,18 +48,20 @@ BaselineTestPlan (7 cycles, 22 tests)
3348

3449
### Test Plans
3550

36-
| Document | Purpose | Status |
37-
| ------------------------------------------ | ---------------------------------------------------------------------------------- | ----------- |
38-
| [IndexerTestGuide.md](IndexerTestGuide.md) | Indexer eligibility tests: renew/expire/recover flows (5 sets, 8 tests) | ✅ Complete |
39-
| [BaselineTestPlan.md](BaselineTestPlan.md) | Detailed baseline indexer operational tests (7 cycles, 22 tests) | ✅ Complete |
40-
| [ReoTestPlan.md](ReoTestPlan.md) | Comprehensive REO behavior, eligibility logic, and edge cases (8 cycles, 31 tests) | ✅ Complete |
51+
| Document | Purpose | Status |
52+
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------- |
53+
| [BaselineTestPlan.md](BaselineTestPlan.md) | Detailed baseline indexer operational tests (7 cycles, 22 tests) | ✅ Complete |
54+
| [ReoTestPlan.md](ReoTestPlan.md) | REO eligibility, oracle, and rewards integration (8 cycles, 31 tests) | ✅ Complete |
55+
| [RewardsConditionsTestPlan.md](RewardsConditionsTestPlan.md) | Reclaim system, signal conditions, POI paths, allocation lifecycle (7 cycles, 26 tests) | ✅ Complete |
56+
| [SubgraphDenialTestPlan.md](SubgraphDenialTestPlan.md) | Subgraph denial: accumulator freeze, deferral, recovery (6 cycles, 18 tests) | ✅ Complete |
57+
| [IndexerTestGuide.md](IndexerTestGuide.md) | Condensed indexer eligibility tests (5 sets, 8 tests) | ✅ Complete |
4158

4259
### Support Files (`support/`)
4360

4461
| Document | Purpose | Status |
4562
| -------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------- |
4663
| [NotionSetup.md](support/NotionSetup.md) | Instructions for importing test tracker into Notion | ✅ Complete |
47-
| [NotionTracker.csv](support/NotionTracker.csv) | CSV export for Notion import (30 tests) | ✅ Complete |
64+
| [NotionTracker.csv](support/NotionTracker.csv) | CSV export for Notion import | ✅ Complete |
4865
| [IssuanceAllocatorTestPlan.md](support/IssuanceAllocatorTestPlan.md) | IssuanceAllocator tests (independent of REO, pending deployment) | ⏸️ Pending |
4966

5067
## Test Coverage
@@ -72,7 +89,7 @@ BaselineTestPlan (7 cycles, 22 tests)
7289
7. **Cycle 7: End-to-End Workflow** (1 test)
7390
- Complete operational cycle from allocation to revenue collection
7491

75-
### REO-Specific Tests
92+
### REO-Specific Tests (ReoTestPlan)
7693

7794
1. **Eligibility State Transitions**
7895
- Validation toggle, renewals, expiry, oracle timeout fail-open
@@ -89,6 +106,43 @@ BaselineTestPlan (7 cycles, 22 tests)
89106
5. **Deployment Verification**
90107
- Post-deploy role checks, parameter validation, proxy consistency
91108

109+
### Reward Conditions Tests (RewardsConditionsTestPlan)
110+
111+
1. **Reclaim System Configuration**
112+
- Per-condition addresses, default fallback, routing verification, access control
113+
114+
2. **Below-Minimum Signal**
115+
- Threshold changes, accumulator freeze, reclaim, restoration
116+
117+
3. **Zero Allocated Tokens**
118+
- Detection, reclaim, allocation resumption from stored baseline
119+
120+
4. **POI Presentation Paths**
121+
- Normal claim (NONE), stale POI reclaim, zero POI reclaim, too-young deferral
122+
123+
5. **Allocation Lifecycle**
124+
- Stale resize reclaim, non-stale resize pass-through, close allocation reclaim
125+
126+
6. **Observability**
127+
- POIPresented event on every presentation, RewardsReclaimed event context, view function freeze
128+
129+
### Subgraph Denial Tests (SubgraphDenialTestPlan)
130+
131+
1. **Denial State Management**
132+
- setDenied, isDenied, idempotent deny, access control
133+
134+
2. **Accumulator Freeze**
135+
- accRewardsForSubgraph freeze, getRewards freeze, reclaim during denial
136+
137+
3. **Allocation-Level Deferral**
138+
- POI defers (preserves rewards), multiple defers safe, continued POI presentation
139+
140+
4. **Undeny and Recovery**
141+
- Accumulator resumption, pre-denial rewards claimable, denial-period exclusion
142+
143+
5. **Edge Cases**
144+
- New allocation while denied, all-close-while-denied, rapid deny/undeny, denial vs eligibility precedence
145+
92146
See also: [IssuanceAllocatorTestPlan](support/IssuanceAllocatorTestPlan.md) (independent of REO, pending deployment)
93147

94148
## Network Configuration
@@ -102,9 +156,9 @@ See also: [IssuanceAllocatorTestPlan](support/IssuanceAllocatorTestPlan.md) (ind
102156

103157
1. **Testnet first** - All tests validated on Arbitrum Sepolia before mainnet
104158
2. **Reusable baseline** - Upgrade-agnostic tests reused across protocol upgrades
105-
3. **Incremental** - Baseline confidence first, then REO-specific scenarios
106-
4. **Two-layer validation** - Standard operations + upgrade-specific behavior
159+
3. **Incremental** - Baseline confidence first, then upgrade-specific scenarios
160+
4. **Three-layer validation** - Standard operations + REO eligibility + reward conditions/denial
107161

108162
---
109163

110-
_Test plans developed for The Graph Protocol REO upgrade validation._
164+
_Test plans developed for The Graph Protocol issuance upgrade validation._

0 commit comments

Comments
 (0)