Skip to content

Commit c48f3f7

Browse files
MaikolMaikol
committed
docs: dips integration test plan
1 parent 3393327 commit c48f3f7

7 files changed

Lines changed: 1618 additions & 0 deletions

File tree

‎packages/subgraph-service/docs/dips/testing/LocalNetworkDetails.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Local Network — Details
2+
3+
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.
4+
5+
```bash
6+
# in the local-network checkout
7+
just up indexing-payments
8+
```
9+
10+
## Contract Addresses — dynamic
11+
12+
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:
13+
14+
```bash
15+
# Horizon contracts (RecurringCollector, PaymentsEscrow, RewardsManager, EpochManager, GraphTallyCollector, L2GraphToken)
16+
docker exec indexer-agent python3 -c \
17+
"import json; d=json.load(open('/opt/config/horizon.json'))['1337']; print({k:v['address'] for k,v in d.items()})"
18+
19+
# SubgraphService
20+
docker exec indexer-agent python3 -c \
21+
"import json; print(json.load(open('/opt/config/subgraph-service.json'))['1337']['SubgraphService']['address'])"
22+
```
23+
24+
Chain ID is `1337`.
25+
26+
## Services (indexing-payments recipe)
27+
28+
| Service | Role in DIPS |
29+
| --- | --- |
30+
| chain | EVM hosting Horizon + SubgraphService + RecurringCollector |
31+
| graph-contracts | deploys contracts; writes the address books read above |
32+
| indexer-agent | system under test — accept loop, reconcile, collection |
33+
| indexer-service | validates pushed proposals, queues `pending_rca_proposals` rows |
34+
| dipper | payer side — triggers DIPS origination; the on-chain offer is posted via RAM (`RecurringAgreementManager.offerAgreement`) |
35+
| iisa / iisa-scoring | indexer selection (the dipper calls it to choose indexers) |
36+
| escrow funding service (TBD) | funds the payer's escrow via `RecurringAgreementManager` / issuance, as part of the flow |
37+
| indexing-payments subgraph | indexes `Offer` + `indexingAgreements`; the agent's source of truth |
38+
| graph-node, postgres, ipfs | indexing, agent DB, deployment storage |
39+
40+
## Endpoints (defaults)
41+
42+
| Endpoint | Value |
43+
| --- | --- |
44+
| RPC | `http://localhost:8545` |
45+
| Agent management API | `http://localhost:7600` |
46+
| Network subgraph | `http://localhost:8000/subgraphs/name/graph-network` |
47+
| Indexing-payments subgraph | `http://localhost:8000/subgraphs/name/indexing-payments` |
48+
| Graph-node status | `http://localhost:8030/graphql` |
49+
| Dipper admin RPC | `http://localhost:${DIPPER_ADMIN_RPC_PORT}` |
50+
| Postgres | `localhost:5432` / db `indexer_components_1` |
51+
52+
> Ports and the dipper RPC port come from the resolved `.env`; confirm against your checkout.
53+
54+
## Time control
55+
56+
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.
57+
58+
---
59+
60+
- [← Back to DIPS testing](./README.md)

‎packages/subgraph-service/docs/dips/testing/LocalNetworkTestPlan.md‎

Lines changed: 960 additions & 0 deletions
Large diffs are not rendered by default.

‎packages/subgraph-service/docs/dips/testing/MainnetDetails.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Arbitrum One — Mainnet Details
2+
3+
> ⚠️ **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.
4+
5+
## Network Parameters
6+
7+
| Parameter | Value |
8+
| ---------------- | -------------------------------------- |
9+
| Explorer | <https://thegraph.com/explorer> |
10+
| Gateway | <https://gateway.thegraph.com> |
11+
| RPC | <https://arb1.arbitrum.io/rpc> |
12+
| Chain ID | `42161` |
13+
14+
## Contract Addresses
15+
16+
| Contract | Address |
17+
| ------------------- | -------------------------------------------- |
18+
| RecurringCollector | **not deployed** |
19+
| SubgraphService | `0xb2Bb92d0DE618878E438b55D5846cfecD9301105` |
20+
| PaymentsEscrow | `0xf6Fcc27aAf1fcD8B254498c9794451d82afC673E` |
21+
| GraphPayments | `0x7Aae8ae011927BC36Cb4d0d3e81f2E6E30daE06D` |
22+
| GraphTallyCollector | `0x8f69F5C07477Ac46FBc491B1E6D91E2bb0111A9e` |
23+
| RewardsManager | `0x971B9d3d0Ae3ECa029CAB5eA1fB0F72c85e6a525` |
24+
| EpochManager | `0x5A843145c43d328B9bB7a4401d94918f131bB281` |
25+
| HorizonStaking | `0x00669A4CF01450B64E8A2A20E9b1FCB71E61eF03` |
26+
| L2GraphToken | `0x9623063377AD1B27544C965cCd7342f7EA7e88C7` |
27+
| Controller | `0x0a8491544221dd212964fbb96487467291b2C97e` |
28+
29+
**Address sources**: `packages/horizon/addresses.json`, `packages/subgraph-service/addresses.json`. Update `RecurringCollector` here once the mainnet DIPS deployment lands.
30+
31+
---
32+
33+
- [← Back to DIPS testing](./README.md)

‎packages/subgraph-service/docs/dips/testing/README.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# DIPS Testing
2+
3+
Test docs for Direct Indexer Payments (DIPS). Two plans, by audience:
4+
5+
- **[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.
6+
- **[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.
7+
8+
> ⚠️ DIPS is deployed on **Arbitrum Sepolia**, **mainnet-pending** (`RecurringCollector` not yet on Arbitrum One).
9+
10+
## Quick start
11+
12+
**Indexer (testnet):**
13+
1. Read [TestnetIndexerGuide.md](./TestnetIndexerGuide.md) and load testnet addresses from [TestnetDetails](./TestnetDetails.md).
14+
2. Run a DIPS-enabled stack and pre-allocate per the guide's setup.
15+
3. Track progress → [support/Tracker.csv](./support/Tracker.csv) (import to Notion/Sheets; one column per runner).
16+
17+
**Developer (local-network):**
18+
1. Bring up the `indexing-payments` recipe → [LocalNetworkDetails](./LocalNetworkDetails.md).
19+
2. Run [LocalNetworkTestPlan.md](./LocalNetworkTestPlan.md) top to bottom.
20+
21+
## Documents
22+
23+
| Document | Audience | Purpose |
24+
| --- | --- | --- |
25+
| [TestnetIndexerGuide.md](./TestnetIndexerGuide.md) | Indexers | Testnet runbook — receive/accept, sizing, recurring collection, protection, cancellation (T-1 – T-5) |
26+
| [LocalNetworkTestPlan.md](./LocalNetworkTestPlan.md) | Developers | Full-pipeline plan — cycles, edge cases, negative checks (34 tests) |
27+
| [TestnetDetails.md](./TestnetDetails.md) | both | Arbitrum Sepolia — addresses, params, RPC |
28+
| [MainnetDetails.md](./MainnetDetails.md) | both | Arbitrum One — addresses (DIPS mainnet-pending) |
29+
| [LocalNetworkDetails.md](./LocalNetworkDetails.md) | Developers | local-network — services, dynamic addresses, full pipeline |
30+
| [support/Tracker.csv](./support/Tracker.csv) | Indexers | Per-runner status tracker (follows the TestnetIndexerGuide) |
31+
32+
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)_
33+
34+
## Test coverage
35+
36+
**TestnetIndexerGuide — indexer-facing**
37+
38+
| Set | Area | Tests |
39+
| --- | --- | --- |
40+
| T-1 | Receive and accept (existing / new allocation) | T-1.1 – T-1.2 |
41+
| T-2 | Allocation sizing (reward / denied) | T-2.1 – T-2.2 |
42+
| T-3 | Recurring collection | T-3.1 – T-3.3 |
43+
| T-4 | Long-lived allocation protection | T-4.1 – T-4.2 |
44+
| T-5 | Cancellation (opt-out / observe payer cancel) | T-5.1 – T-5.2 |
45+
46+
**LocalNetworkTestPlan — full pipeline**
47+
48+
- Lifecycle cycles D-1 – D-8 (23 tests): readiness, proposal origination, acceptance, sizing, indexing/reconcile, recurring collection, protection, cancellation.
49+
- Edge cases E-1 – E-4; negative checks N-1 – N-7. See the plan's [Coverage map](./LocalNetworkTestPlan.md#coverage-map).
50+
51+
## Network configuration
52+
53+
- [Arbitrum Sepolia (testnet)](./TestnetDetails.md) — indexer target; DIPS contracts deployed
54+
- [Arbitrum One (mainnet)](./MainnetDetails.md) — DIPS pending
55+
- [local-network](./LocalNetworkDetails.md) — full pipeline for developer runs; dynamic addresses
56+
57+
> **GraphQL note**: addresses in subgraph queries must be lowercase.
58+
59+
## Testing approach
60+
61+
1. **Audience-split** — indexers verify their own stack on testnet; developers drive the full pipeline (including payer services) on local-network.
62+
2. **Happy-path first** — prove documented behaviors, then edge and negative cases (developer plan).
63+
3. **Trackable** — one row per test in the CSV tracker, one column per runner.

‎packages/subgraph-service/docs/dips/testing/TestnetDetails.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Arbitrum Sepolia — Testnet Details
2+
3+
DIPS contracts are deployed on Arbitrum Sepolia. This is the primary target for the test plan.
4+
5+
> ⚠️ 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.
6+
7+
## Network Parameters
8+
9+
| Parameter | Value |
10+
| ----------------------- | ---------------------------------------------- |
11+
| Explorer | <https://thegraph.com/explorer> |
12+
| Gateway | <https://gateway.testnet.thegraph.com> |
13+
| Network subgraph | `3xQHhMudr1oh69ut36G2mbzpYmYxwqCeU6wwqyCDCnqV` |
14+
| RPC | <https://sepolia-rollup.arbitrum.io/rpc> |
15+
| Chain ID | `421614` |
16+
| Epoch length | ~554 blocks (~110 minutes) |
17+
| Max allocation lifetime | 8 epochs (~15 hours) |
18+
| Min indexer stake | 100k GRT |
19+
| Thawing period | Shortened for faster testing |
20+
21+
## Contract Addresses
22+
23+
| Contract | Address |
24+
| ------------------- | -------------------------------------------- |
25+
| RecurringCollector | `0x0b18befc60455121ad66ae6e4a647955fcde3900` |
26+
| SubgraphService | `0xc24A3dAC5d06d771f657A48B20cE1a671B78f26b` |
27+
| PaymentsEscrow | `0x4b5D3Da463F7E076bb7CDF5030960bf123245681` |
28+
| GraphPayments | `0x57E70eC8905E26341d40aF60Dca56cDBA8C166E5` |
29+
| GraphTallyCollector | `0x382863e7B662027117449bd2c49285582bbBd21B` |
30+
| RewardsManager | `0x1F49caE7669086c8ba53CC35d1E9f80176d67E79` |
31+
| EpochManager | `0x88b3C7f37253bAA1A9b95feAd69bD5320585826D` |
32+
| HorizonStaking | `0x865365C425f3A593Ffe698D9c4E6707D14d51e08` |
33+
| L2GraphToken | `0xf8c05dCF59E8B28BFD5eed176C562bEbcfc7Ac04` |
34+
| Controller | `0x9DB3ee191681f092607035d9BDA6e59FbEaCa695` |
35+
36+
**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.
37+
38+
## Indexing-payments subgraph
39+
40+
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.
41+
42+
## Environment variables
43+
44+
```bash
45+
export RPC="https://sepolia-rollup.arbitrum.io/rpc"
46+
export RECURRING_COLLECTOR=0x0b18befc60455121ad66ae6e4a647955fcde3900
47+
export SUBGRAPH_SERVICE=0xc24A3dAC5d06d771f657A48B20cE1a671B78f26b
48+
export PAYMENTS_ESCROW=0x4b5D3Da463F7E076bb7CDF5030960bf123245681
49+
export REWARDS_MANAGER=0x1F49caE7669086c8ba53CC35d1E9f80176d67E79
50+
export EPOCH_MANAGER=0x88b3C7f37253bAA1A9b95feAd69bD5320585826D
51+
# Plus your own: $INDEXER, $PAYER, $PAYER_SECRET, $ORACLE_SECRET,
52+
# $AGENT_URL, $NETWORK_SUBGRAPH_URL, $INDEXING_PAYMENTS_SUBGRAPH_URL.
53+
```
54+
55+
> **GraphQL note**: addresses in subgraph queries must be lowercase.
56+
57+
---
58+
59+
- [← Back to DIPS testing](./README.md)

0 commit comments

Comments
 (0)