fix: doc fixes after testing

Author: Maikol

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

@@ -1,10 +1,11 @@
 # 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.
+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. Enable the `indexing-payments` profile in `.env` (or `.env.local`), then bring the stack up:
 
 ```bash
-# in the local-network checkout
-just up indexing-payments
+# in the local-network checkout — enable the profile in .env, then:
+COMPOSE_PROFILES=block-oracle,explorer,indexing-payments
+just up
 ```
 
 ## Contract Addresses — dynamic
@@ -33,7 +34,7 @@ Chain ID is `1337`.
 | 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 |
+| issuance → RAM (on-chain; no separate service) | funds the DIPS payer escrow: issuance routes GRT/block to `RecurringAgreementManager`, whose `beforeCollection()` tops up `PaymentsEscrow` before each collect. Configured by graph-contracts at deploy time. (Distinct from `graph-tally-escrow-manager`, which handles TAP query-fee escrow + signer authorization, not DIPS.) |
 | indexing-payments subgraph | indexes `Offer` + `indexingAgreements`; the agent's source of truth |
 | graph-node, postgres, ipfs | indexing, agent DB, deployment storage |
 

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

@@ -89,6 +89,10 @@ curl -s "$AGENT_URL" -H 'content-type: application/json' \
   -d '{"query":"{ indexingRules(merged:false){ identifier decisionBasis } }"}'
 ```
 
+> 💡 The `graph indexer rules` CLI is the usual way to set rules (it supplies the network via
+> `--network`). If you call `setIndexingRule` on the management API **directly**, the rule input
+> must include `protocolNetwork` (CAIP-2, e.g. `eip155:1337`) or the mutation is rejected.
+
 Active allocation for a deployment — network subgraph:
 
 ```bash
@@ -207,22 +211,30 @@ Two environment-note patterns recur:
 
 ### D-1.2 Baseline capture
 
-**Objective**: Capture a baseline — pick the target reward-earning deployment and identify the rewards-denied deployment for the D-4 sizing variant.
+**Objective**: Capture a baseline — pick the fixtures for the acceptance, reuse, and rewards-denied paths.
 
 **Prerequisites**: D-1.1 green.
 
-**Steps**: List deployment indexing rules and pick a target reward-earning deployment (one with an `always` rule); identify a separate rewards-denied deployment for the D-4 sizing variant. Record both IPFS hashes for downstream tests.
+**Steps**: Pick three fixtures and record their IPFS hashes. "Reward-earning" here means simply
+*not rewards-denied* — it does **not** require an `always` rule.
+
+- **DIP-driven target** — a reward-earning deployment with **no indexing rule and no active
+  allocation**. The accepted DIP agreement creates the allocation (D-3.2) and carries the
+  D-4.1/D-5/D-6/D-7 lifecycle. Do **not** put an `always` rule on it: an `always` rule makes the
+  agent continuously (re)open a plain allocation, which races/pre-empts the DIP's
+  `multicall(startService, acceptIndexingAgreement)` and defeats D-3.2.
+- **Reuse target** — a separate deployment with a **pre-existing active allocation** (e.g.
+  opened via an `always` rule), for the D-3.1 existing-allocation path.
+- **Rewards-denied deployment** — for the D-4.2 sizing variant.
 
-Baseline rules — Observation toolbox "Indexing rules", reading the identifiers so you can pick a target:
+Baseline rules — Observation toolbox "Indexing rules", to see current rules/allocations:
 
 ```bash
 curl -s "$AGENT_URL" -H 'content-type: application/json' \
   -d '{"query":"{ indexingRules(merged:false){ identifier identifierType decisionBasis allocationAmount } }"}' \
   | jq -r '.data.indexingRules[] | select(.identifierType=="deployment") | "\(.identifier)\t\(.decisionBasis)"'
 ```
 
-Pick a deployment whose `decisionBasis` is `always` (reward-earning target) and export it as `<HASH>` for later tests. The `identifier` is the IPFS hash to use downstream.
-
 > 💡 The rewards-denied deployment is the one flagged in the last prerequisite ("one rewards-denied deployment available"). Confirm it on-chain with `RewardsManager.isDenied(bytes32)` (returns `true`) and record its hash separately; it is only used in D-4.
 >
 > ```bash
@@ -231,31 +243,42 @@ Pick a deployment whose `decisionBasis` is `always` (reward-earning target) and
 
 **Pass Criteria**:
 
-- [ ] A target reward-earning deployment hash is chosen and recorded — it has an `always` rule in the toolbox "Indexing rules" output.
+- [ ] A DIP-driven reward-earning target is chosen and recorded — no indexing rule and no active allocation (the DIP acceptance will create the allocation in D-3.2).
+- [ ] A separate reuse target is chosen and recorded — it has a pre-existing active allocation (for D-3.1).
 - [ ] A rewards-denied deployment is identified and its hash recorded — reserved for the D-4 sizing variant.
 
 ---
 
 ## Cycle D-2 — Proposal origination (payer side)
 
-### D-2.1 Trigger origination (inject the indexing-requirement signal)
+### D-2.1 Trigger origination (set the target candidate count)
 
-**Objective**: Inject the indexing-requirement signal that drives the dipper to originate the agreement.
+**Objective**: Register the indexing request that drives the dipper to originate the agreement.
 
 **Prerequisites**: D-1 complete. The dipper and IISA are running; IISA can select the target indexer for the deployment.
 
-**Steps**: Produce an indexing-requirement message to the `indexing-requirements` Redpanda topic; the dipper's signal consumer reads it, runs IISA selection, and offers the agreement. Redpanda auto-create is off, so create the topic first if it doesn't exist.
+> ⚠️ **IISA prerequisite (do this first).** IISA only scores indexers that have **Redpanda
+> query history**. Send some gateway queries (against any subgraph — history is per-indexer,
+> not per-target) and run an IISA scoring pass before origination, or selection returns 0
+> candidates. Selection also uses: the indexer need not already index the target (it competes
+> in an "unsynced" pool), and the indexer's advertised DIPs price must be under the request's
+> `max_grt_per_30_days` ceiling.
 
-```bash
-# create the topic if absent (idempotent)
-docker exec redpanda rpk topic create indexing-requirements --brokers redpanda:9092 2>/dev/null || true
+**Steps**: Drive origination via the dipper admin RPC with `dipper-cli`: `set-target-candidates`
+registers (or updates) the desired candidate count for a `(deployment, chain)`; the dipper runs
+IISA selection and offers the agreement. There is no `indexing-requirements` Redpanda topic
+consumer in the current dipper.
 
-# produce the signal for the target deployment
-echo '{"subgraph_deployment_id":"<HASH>","redundancy_factor":1,"chain_id":1337,"version":1}' \
-  | docker exec -i redpanda rpk topic produce indexing-requirements --brokers redpanda:9092
+```bash
+# signing key = the gateway-operator / receiver key on dipper's admin allowlist
+dipper-cli indexings set-target-candidates \
+  --server-url http://localhost:9000 \
+  --signing-key <RECEIVER_KEY> \
+  <HASH> 1337 --num-candidates 1
 ```
 
-Message schema: `{ subgraph_deployment_id, redundancy_factor, chain_id, version }`.
+On success the CLI prints the indexing request UUID. `--num-candidates 0` cancels the request
+(and any agreement it drove — see D-8.1).
 
 **Pass Criteria**:
 
@@ -331,7 +354,7 @@ The agent's acceptance loop runs every `--dips-acceptance-interval` (default 5s)
 **Pass Criteria**:
 
 - [ ] The `pending_rca_proposals` row flips to `accepted` — Observation toolbox "Pending proposal row", look for status `accepted`.
-- [ ] A `dips` indexing rule exists for the deployment — Observation toolbox "Indexing rules", `decisionBasis == "dips"` and `identifier == <HASH>`.
+- [ ] The deployment is tracked as a DIPs agreement — on-chain agreement `Accepted` and active on the indexing-payments subgraph. Note: a **separate `dips` rule is added only when the deployment had no prior rule** (D-3.2). If the reused allocation came from an `always` rule, that `always` rule persists and no `dips` rule is added — the agent tracks the agreement via the on-chain/subgraph state, not the rule.
 - [ ] An active allocation exists for the deployment and the prior allocation id is reused — Observation toolbox "Active allocation".
 - [ ] On-chain agreement state is `Accepted` (=1) — Observation toolbox "On-chain agreement state" (`getAgreement`), last field is `1`.
 - [ ] The dipper agreement status is `ACCEPTED_ON_CHAIN` — read-only admin RPC `get_agreements_by_deployment_id` (filter by `<HASH>`).
@@ -386,7 +409,7 @@ The agent sizes the DIPS allocation by whether the deployment earns indexing rew
 
 ### D-4.2 Rewards-denied sizing
 
-**Objective**: A rewards-denied deployment's allocation uses `--dips-allocation-amount` (env `INDEXER_AGENT_DIPS_ALLOCATION_AMOUNT`), default `0`. A zero-token allocation is valid for DIPS — collection pays the RCA amount, independent of allocation size.
+**Objective**: A rewards-denied deployment's allocation uses `--dips-allocation-amount` (env `INDEXER_AGENT_DIPS_ALLOCATION_AMOUNT`). The value is parsed as a **GRT amount** (not wei): the documented default is `0` (a valid zero-token allocation, since collection pays the RCA amount independent of allocation size), but local-network currently sets it to `1` → a **1 GRT** allocation. Read the configured value; do not assume `0`.
 
 **Prerequisites**: The rewards-denied deployment from D-1. Subgraph availability oracle configured.
 
@@ -411,7 +434,7 @@ Read allocation tokens — Observation toolbox "Allocation tokens" (`getAllocati
 
 **Pass Criteria**:
 
-- [ ] The allocation `tokens` equals `--dips-allocation-amount` (default `0` → a valid zero-token allocation).
+- [ ] The allocation `tokens` equals `--dips-allocation-amount` interpreted as GRT (documented default `0` → zero-token allocation; local-network's `1` → `1000000000000000000` = 1 GRT). Distinct from the reward-earning sizing in D-4.1.
 
 ---
 
@@ -498,13 +521,19 @@ curl -s "$INDEXING_PAYMENTS_SUBGRAPH_URL" -H 'content-type: application/json' \
 
 **Prerequisites**: An accepted agreement that has not yet collected (`lastCollectionAt == 0`).
 
+> ⚠️ **N/A when `maxInitialTokens = 0`.** local-network's dipper currently offers RCAs with
+> `maxInitialTokens = 0`, so there is no bonus to observe — the first collection is just
+> `collectionSeconds × rate` like the rest. This check can only be demonstrated by configuring
+> dipper to offer a non-zero `maxInitialTokens`. Otherwise mark D-6.1 N/A and confirm only that
+> the first collection succeeds.
+
 **Steps**: Advance the first window and let the agent collect; capture the per-collection payout.
 
 > 💡 First-collection bonus: the first collection includes `maxInitialTokens` (a one-time amount added only when `lastCollectionAt == 0`); later collections do not. If you can read the per-collection payout, confirm the first is larger by roughly `maxInitialTokens`.
 
 **Pass Criteria**:
 
-- [ ] The first collection's payout is larger by roughly `maxInitialTokens` than subsequent collections — confirmed when `lastCollectionAt` was `0` at collection time.
+- [ ] With a non-zero `maxInitialTokens`: the first collection's payout is larger by roughly `maxInitialTokens` than subsequent collections — confirmed when `lastCollectionAt` was `0` at collection time. (N/A when `maxInitialTokens = 0` — local default.)
 - [ ] The agent log shows `Successfully collected indexing fees`.
 
 ---
@@ -525,17 +554,30 @@ curl -s "$INDEXING_PAYMENTS_SUBGRAPH_URL" -H 'content-type: application/json' \
 
 ---
 
-### D-6.3 Escrow drains cumulatively
+### D-6.3 Collection value accrues cumulatively
 
-**Objective**: The payer escrow balance decreases with each collection.
+**Objective**: The indexer's collected value grows with each collection.
+
+> ⚠️ **Escrow does not monotonically drain in the protocol-funded flow.** On local-network the
+> payer is the `RecurringAgreementManager` and issuance tops up its escrow before collection, so
+> `getBalance(payer, recurringCollector, indexer)` stays roughly **constant** even as the indexer
+> is paid. Verify cumulative **`tokensCollected`** instead of a decreasing escrow. Escrow drain
+> only applies to a fixed-deposit payer (e.g. a consumer/gateway that deposits once), which is
+> not the local-network DIPs setup.
 
 **Prerequisites**: D-6.2 in progress.
 
-**Steps**: Re-run `getBalance(payer, recurringCollector, indexer)` per cycle and compare.
+**Steps**: Sum `tokensCollected` across the `indexingFeeCollections` for the agreement per cycle
+and confirm it increases. (Optionally also read `getBalance`; expect it flat, not draining.)
+
+```bash
+curl -s "$INDEXING_PAYMENTS_SUBGRAPH_URL" -H 'content-type: application/json' \
+  -d '{"query":"{ indexingFeeCollections(where:{ agreement:\"<AGREEMENT_ID>\" }){ tokensCollected blockTimestamp } }"}'
+```
 
 **Pass Criteria**:
 
-- [ ] The payer escrow balance decreases with each collection (cumulative drain) — re-run `getBalance` per cycle and compare.
+- [ ] Cumulative `tokensCollected` for the agreement increases with each collection. (The payer escrow balance may stay constant due to issuance top-up — that is expected in the protocol-funded flow, not a failure.)
 
 ---
 
@@ -634,13 +676,21 @@ Two independent payer/SP cancellation paths plus the indexer opt-out. Each needs
 
 **Prerequisites**: A fresh `Accepted`, collecting agreement (re-run D-2/D-3).
 
-**Steps**: The payer cancels on-chain via `SubgraphService.cancelIndexingAgreementByPayer(bytes16)`, then advance time so the final collection window opens.
+**Steps**: The payer cancels the agreement, then advance time so the final collection window opens.
+
+> ⚠️ **The payer is the RAM contract, not an EOA.** On local-network the on-chain `payer` is the
+> `RecurringAgreementManager`, so there is no `$PAYER_SECRET` that can sign
+> `cancelIndexingAgreementByPayer` directly — the cancel must be routed through the payer side.
+> Drive it via `dipper-cli` by setting the request's target candidates to `0`; dipper cancels
+> the agreement through RAM as the payer, yielding `CanceledByPayer`.
 
-Payer cancel — payer key:
+Payer cancel — via dipper-cli (cancels through RAM):
 
 ```bash
-cast send --rpc-url "$RPC" --private-key "$PAYER_SECRET" \
-  "$SUBGRAPH_SERVICE" "cancelIndexingAgreementByPayer(bytes16)" "<AGREEMENT_ID>"
+dipper-cli indexings set-target-candidates \
+  --server-url http://localhost:9000 \
+  --signing-key <RECEIVER_KEY> \
+  <HASH> 1337 --num-candidates 0
 ```
 
 Advance time so the final collection window opens — local-network with `cast rpc --rpc-url "$RPC" anvil_mine <blocks> <interval>` as in D-6; a testnet waits the real elapsed time.