graphprotocol · Maikol · Jun 19, 2026
diff --git a/packages/subgraph-service/docs/dips/testing/LocalNetworkDetails.md b/packages/subgraph-service/docs/dips/testing/LocalNetworkDetails.md
@@ -0,0 +1,60 @@
+# Local Network — Details
+
+local-network runs the **full DIPS payer pipeline** (`iisa` + `dipper` + `indexer-service` + `indexer-agent`) locally — useful for development and before the payer services are live on your target network. Bring it up with the `indexing-payments` recipe.
+
+```bash
+# in the local-network checkout
+just up indexing-payments
+```
+
+## Contract Addresses — dynamic
+
+Contracts are redeployed on every `just up`, so addresses change per deploy. Do not hardcode them. Read them from the agent container's mounted config:
+
+```bash
+# Horizon contracts (RecurringCollector, PaymentsEscrow, RewardsManager, EpochManager, GraphTallyCollector, L2GraphToken)
+docker exec indexer-agent python3 -c \
+  "import json; d=json.load(open('/opt/config/horizon.json'))['1337']; print({k:v['address'] for k,v in d.items()})"
+
+# SubgraphService
+docker exec indexer-agent python3 -c \
+  "import json; print(json.load(open('/opt/config/subgraph-service.json'))['1337']['SubgraphService']['address'])"
+```
+
+Chain ID is `1337`.
+
+## Services (indexing-payments recipe)
+
+| Service | Role in DIPS |
+| --- | --- |
+| chain | EVM hosting Horizon + SubgraphService + RecurringCollector |
+| graph-contracts | deploys contracts; writes the address books read above |
+| indexer-agent | system under test — accept loop, reconcile, collection |
+| indexer-service | validates pushed proposals, queues `pending_rca_proposals` rows |
+| dipper | payer side — triggers DIPS origination; the on-chain offer is posted via RAM (`RecurringAgreementManager.offerAgreement`) |
+| iisa / iisa-scoring | indexer selection (the dipper calls it to choose indexers) |
+| escrow funding service (TBD) | funds the payer's escrow via `RecurringAgreementManager` / issuance, as part of the flow |
+| indexing-payments subgraph | indexes `Offer` + `indexingAgreements`; the agent's source of truth |
+| graph-node, postgres, ipfs | indexing, agent DB, deployment storage |
+
+## Endpoints (defaults)
+
+| Endpoint | Value |
+| --- | --- |
+| RPC | `http://localhost:8545` |
+| Agent management API | `http://localhost:7600` |
+| Network subgraph | `http://localhost:8000/subgraphs/name/graph-network` |
+| Indexing-payments subgraph | `http://localhost:8000/subgraphs/name/indexing-payments` |
+| Graph-node status | `http://localhost:8030/graphql` |
+| Dipper admin RPC | `http://localhost:${DIPPER_ADMIN_RPC_PORT}` |
+| Postgres | `localhost:5432` / db `indexer_components_1` |
+
+> Ports and the dipper RPC port come from the resolved `.env`; confirm against your checkout.
+
+## Time control
+
+local-network runs an automine chain — advance time with `cast rpc --rpc-url "$RPC" anvil_mine <blocks> <interval>` (bounded blocks, large intervals) rather than waiting real time. See the time-advancement notes in the plan.
+
+---
+
+- [← Back to DIPS testing](./README.md)
diff --git a/packages/subgraph-service/docs/dips/testing/LocalNetworkTestPlan.md b/packages/subgraph-service/docs/dips/testing/LocalNetworkTestPlan.md
diff --git a/packages/subgraph-service/docs/dips/testing/MainnetDetails.md b/packages/subgraph-service/docs/dips/testing/MainnetDetails.md
@@ -0,0 +1,33 @@
+# Arbitrum One — Mainnet Details
+
+> ⚠️ **DIPS is not yet deployed on mainnet.** `RecurringCollector` is absent from the Arbitrum One address book — the DIPS accept/collect path cannot run here. This file lists the Horizon contracts that do exist so it is ready when DIPS ships to mainnet. Run the test plan on [Arbitrum Sepolia](./TestnetDetails.md) or [local-network](./LocalNetworkDetails.md) until then.
+
+## Network Parameters
+
+| Parameter        | Value                                  |
+| ---------------- | -------------------------------------- |
+| Explorer         | <https://thegraph.com/explorer>        |
+| Gateway          | <https://gateway.thegraph.com>         |
+| RPC              | <https://arb1.arbitrum.io/rpc>         |
+| Chain ID         | `42161`                                |
+
+## Contract Addresses
+
+| Contract            | Address                                      |
+| ------------------- | -------------------------------------------- |
+| RecurringCollector  | **not deployed**                             |
+| SubgraphService     | `0xb2Bb92d0DE618878E438b55D5846cfecD9301105` |
+| PaymentsEscrow      | `0xf6Fcc27aAf1fcD8B254498c9794451d82afC673E` |
+| GraphPayments       | `0x7Aae8ae011927BC36Cb4d0d3e81f2E6E30daE06D` |
+| GraphTallyCollector | `0x8f69F5C07477Ac46FBc491B1E6D91E2bb0111A9e` |
+| RewardsManager      | `0x971B9d3d0Ae3ECa029CAB5eA1fB0F72c85e6a525` |
+| EpochManager        | `0x5A843145c43d328B9bB7a4401d94918f131bB281` |
+| HorizonStaking      | `0x00669A4CF01450B64E8A2A20E9b1FCB71E61eF03` |
+| L2GraphToken        | `0x9623063377AD1B27544C965cCd7342f7EA7e88C7` |
+| Controller          | `0x0a8491544221dd212964fbb96487467291b2C97e` |
+
+**Address sources**: `packages/horizon/addresses.json`, `packages/subgraph-service/addresses.json`. Update `RecurringCollector` here once the mainnet DIPS deployment lands.
+
+---
+
+- [← Back to DIPS testing](./README.md)
diff --git a/packages/subgraph-service/docs/dips/testing/README.md b/packages/subgraph-service/docs/dips/testing/README.md
@@ -0,0 +1,63 @@
+# DIPS Testing
+
+Test docs for Direct Indexer Payments (DIPS). Two plans, by audience:
+
+- **[TestnetIndexerGuide.md](./TestnetIndexerGuide.md)** — for **indexers** running a DIPS-enabled stack (indexer-service + indexer-agent) on **testnet**. Verify your stack accepts agreements, collects, and handles cancellation. You do not run the payer services.
+- **[LocalNetworkTestPlan.md](./LocalNetworkTestPlan.md)** — for **developers** exercising the **full pipeline** on **local-network**, including the payer side (`iisa`/`dipper`), proposal injection, and chain time-travel.
+
+> ⚠️ DIPS is deployed on **Arbitrum Sepolia**, **mainnet-pending** (`RecurringCollector` not yet on Arbitrum One).
+
+## Quick start
+
+**Indexer (testnet):**
+1. Read [TestnetIndexerGuide.md](./TestnetIndexerGuide.md) and load testnet addresses from [TestnetDetails](./TestnetDetails.md).
+2. Run a DIPS-enabled stack and pre-allocate per the guide's setup.
+3. Track progress → [support/Tracker.csv](./support/Tracker.csv) (import to Notion/Sheets; one column per runner).
+
+**Developer (local-network):**
+1. Bring up the `indexing-payments` recipe → [LocalNetworkDetails](./LocalNetworkDetails.md).
+2. Run [LocalNetworkTestPlan.md](./LocalNetworkTestPlan.md) top to bottom.
+
+## Documents
+
+| Document | Audience | Purpose |
+| --- | --- | --- |
+| [TestnetIndexerGuide.md](./TestnetIndexerGuide.md) | Indexers | Testnet runbook — receive/accept, sizing, recurring collection, protection, cancellation (T-1 – T-5) |
+| [LocalNetworkTestPlan.md](./LocalNetworkTestPlan.md) | Developers | Full-pipeline plan — cycles, edge cases, negative checks (34 tests) |
+| [TestnetDetails.md](./TestnetDetails.md) | both | Arbitrum Sepolia — addresses, params, RPC |
+| [MainnetDetails.md](./MainnetDetails.md) | both | Arbitrum One — addresses (DIPS mainnet-pending) |
+| [LocalNetworkDetails.md](./LocalNetworkDetails.md) | Developers | local-network — services, dynamic addresses, full pipeline |
+| [support/Tracker.csv](./support/Tracker.csv) | Indexers | Per-runner status tracker (follows the TestnetIndexerGuide) |
+
+Feature reference (in the [indexer repo](https://github.com/graphprotocol/indexer)): [DIPS indexer guide](https://github.com/graphprotocol/indexer/blob/main/docs/dips/dips-indexer-guide.md), [quick reference](https://github.com/graphprotocol/indexer/blob/main/docs/dips/dips-quick-reference.md), [common errors](https://github.com/graphprotocol/indexer/blob/main/docs/dips/dips-common-errors.md). _(TODO: fix links)_
+
+## Test coverage
+
+**TestnetIndexerGuide — indexer-facing**
+
+| Set | Area | Tests |
+| --- | --- | --- |
+| T-1 | Receive and accept (existing / new allocation) | T-1.1 – T-1.2 |
+| T-2 | Allocation sizing (reward / denied) | T-2.1 – T-2.2 |
+| T-3 | Recurring collection | T-3.1 – T-3.3 |
+| T-4 | Long-lived allocation protection | T-4.1 – T-4.2 |
+| T-5 | Cancellation (opt-out / observe payer cancel) | T-5.1 – T-5.2 |
+
+**LocalNetworkTestPlan — full pipeline**
+
+- Lifecycle cycles D-1 – D-8 (23 tests): readiness, proposal origination, acceptance, sizing, indexing/reconcile, recurring collection, protection, cancellation.
+- Edge cases E-1 – E-4; negative checks N-1 – N-7. See the plan's [Coverage map](./LocalNetworkTestPlan.md#coverage-map).
+
+## Network configuration
+
+- [Arbitrum Sepolia (testnet)](./TestnetDetails.md) — indexer target; DIPS contracts deployed
+- [Arbitrum One (mainnet)](./MainnetDetails.md) — DIPS pending
+- [local-network](./LocalNetworkDetails.md) — full pipeline for developer runs; dynamic addresses
+
+> **GraphQL note**: addresses in subgraph queries must be lowercase.
+
+## Testing approach
+
+1. **Audience-split** — indexers verify their own stack on testnet; developers drive the full pipeline (including payer services) on local-network.
+2. **Happy-path first** — prove documented behaviors, then edge and negative cases (developer plan).
+3. **Trackable** — one row per test in the CSV tracker, one column per runner.
diff --git a/packages/subgraph-service/docs/dips/testing/TestnetDetails.md b/packages/subgraph-service/docs/dips/testing/TestnetDetails.md
@@ -0,0 +1,59 @@
+# Arbitrum Sepolia — Testnet Details
+
+DIPS contracts are deployed on Arbitrum Sepolia. This is the primary target for the test plan.
+
+> ⚠️ Arbitrum Sepolia is the primary target for the full pipeline. It requires the payer services (`dipper`/`iisa`) reachable on this network in addition to the deployed contracts.
+
+## Network Parameters
+
+| Parameter               | Value                                          |
+| ----------------------- | ---------------------------------------------- |
+| Explorer                | <https://thegraph.com/explorer>                |
+| Gateway                 | <https://gateway.testnet.thegraph.com>         |
+| Network subgraph        | `3xQHhMudr1oh69ut36G2mbzpYmYxwqCeU6wwqyCDCnqV` |
+| RPC                     | <https://sepolia-rollup.arbitrum.io/rpc>       |
+| Chain ID                | `421614`                                       |
+| Epoch length            | ~554 blocks (~110 minutes)                     |
+| Max allocation lifetime | 8 epochs (~15 hours)                           |
+| Min indexer stake       | 100k GRT                                       |
+| Thawing period          | Shortened for faster testing                   |
+
+## Contract Addresses
+
+| Contract            | Address                                      |
+| ------------------- | -------------------------------------------- |
+| RecurringCollector  | `0x0b18befc60455121ad66ae6e4a647955fcde3900` |
+| SubgraphService     | `0xc24A3dAC5d06d771f657A48B20cE1a671B78f26b` |
+| PaymentsEscrow      | `0x4b5D3Da463F7E076bb7CDF5030960bf123245681` |
+| GraphPayments       | `0x57E70eC8905E26341d40aF60Dca56cDBA8C166E5` |
+| GraphTallyCollector | `0x382863e7B662027117449bd2c49285582bbBd21B` |
+| RewardsManager      | `0x1F49caE7669086c8ba53CC35d1E9f80176d67E79` |
+| EpochManager        | `0x88b3C7f37253bAA1A9b95feAd69bD5320585826D` |
+| HorizonStaking      | `0x865365C425f3A593Ffe698D9c4E6707D14d51e08` |
+| L2GraphToken        | `0xf8c05dCF59E8B28BFD5eed176C562bEbcfc7Ac04` |
+| Controller          | `0x9DB3ee191681f092607035d9BDA6e59FbEaCa695` |
+
+**Address sources**: `packages/horizon/addresses.json` (RecurringCollector, GraphTallyCollector, PaymentsEscrow, GraphPayments, RewardsManager, EpochManager, HorizonStaking, L2GraphToken, Controller), `packages/subgraph-service/addresses.json` (SubgraphService) — from the `deployment/testnet/2026-06-09/gip-0088` branch of the contracts repo.
+
+## Indexing-payments subgraph
+
+The agent reads agreement state from the indexing-payments subgraph (`--indexing-payments-subgraph-endpoint` or `--indexing-payments-subgraph-deployment`). There is no canonical public deployment id here — use the deployment your operator indexes or the endpoint your stack is configured with, and record it in the test plan's environment setup.
+
+## Environment variables
+
+```bash
+export RPC="https://sepolia-rollup.arbitrum.io/rpc"
+export RECURRING_COLLECTOR=0x0b18befc60455121ad66ae6e4a647955fcde3900
+export SUBGRAPH_SERVICE=0xc24A3dAC5d06d771f657A48B20cE1a671B78f26b
+export PAYMENTS_ESCROW=0x4b5D3Da463F7E076bb7CDF5030960bf123245681
+export REWARDS_MANAGER=0x1F49caE7669086c8ba53CC35d1E9f80176d67E79
+export EPOCH_MANAGER=0x88b3C7f37253bAA1A9b95feAd69bD5320585826D
+# Plus your own: $INDEXER, $PAYER, $PAYER_SECRET, $ORACLE_SECRET,
+# $AGENT_URL, $NETWORK_SUBGRAPH_URL, $INDEXING_PAYMENTS_SUBGRAPH_URL.
+```
+
+> **GraphQL note**: addresses in subgraph queries must be lowercase.
+
+---
+
+- [← Back to DIPS testing](./README.md)