Gnd test improvements (#6442)

* gnd: implement transaction receipt support for gnd test

Build mock receipts from block events and attach them to log triggers.
Events sharing the same txHash share a receipt whose logs contains all
their logs in declaration order; events without an explicit txHash each
get a unique auto-generated hash and their own single-log receipt.

Receipts are only attached to logs whose event selector (topic0) matches
a handler that declares receipt: true in the manifest, mirroring
production behaviour where graph-node only fetches receipts from the RPC
for those handlers. The selector is computed using the same normalisation
as graph-node's MappingEventHandler::topic0() to handle the manifest's
indexed-before-type convention (e.g. Transfer(indexed address,...)).

Most receipt fields (gas, from, to, status) are hardcoded stubs; only
receipt.logs reflects the actual test data.

* gnd: fix txHash deserialization in test schema

* gnd: add mock IPFS client for file data source testing

Replaces the dummy IpfsRpcClient with a MockIpfsClient that serves
pre-loaded CID → bytes from a "files" array in test JSON files.
Missing CIDs are reported with a clear error instead of a 60-second
timeout. Also adds IpfsResponse::for_test() helper and documents the
unmocked eth_call timeout in the troubleshooting guide.

* gnd: add mock Arweave resolver for file/arweave data source testing

Introduces `MockArweaveResolver` and the `arweaveFiles` schema field so
`gnd test` can serve pre-loaded Arweave content without hitting the
network. Unresolved tx IDs are collected and reported as a clear test
failure, mirroring the existing IPFS mock behaviour.

* gnd: add file data source tests and split fixture subgraphs

Add IPFS and Arweave file data source test fixtures and split the
monolithic gnd_test fixture into four focused subgraphs:

- token/            ERC20 events, eth_call mocking, dynamic templates
- blocks/           Block handlers (every, once, polling filters)
- receipts/         Transaction receipts (receipt: true handlers)
- file-data-sources/ IPFS and Arweave file data sources

Each fixture is a standalone subgraph with its own schema, mappings,
ABIs, and test JSON files. The Rust test harness is updated to use a
generic setup_fixture(name) helper, with one test function per fixture.

* gnd: trim verbose inline comments in test module

* gnd: replace eth_call cache with mock transport layer

Replace the pre-populated eth_call cache approach with a mock Alloy
transport that intercepts RPC calls at the transport level. This makes
tests exercise the real production code path end-to-end.

- Add MockTransport serving eth_call, eth_getBalance, eth_getCode
- Add TestRuntimeAdapterBuilder to convert PossibleReorg → Deterministic
- Add getBalanceCalls/hasCodeCalls to test JSON schema
- Unmocked RPC calls now fail immediately with descriptive errors
- Disable RPC retries in test mode for fast failure

* gnd: update test docs for mock transport and file data sources

- Document getBalanceCalls and hasCodeCalls mock fields
- Document IPFS and Arweave file data source mocking
- Update architecture section to describe mock transport
- Update troubleshooting for immediate unmocked call errors
- Update known limitations table

* gnd: Separate tests and fix retry count env var value

Signed-off-by: Maksim Dimitrov <dimitrov.maksim@gmail.com>

---------

Signed-off-by: Maksim Dimitrov <dimitrov.maksim@gmail.com>

Author: dimitrovmaksim

Cargo.lock

@@ -31,6 +31,7 @@ graph-store-postgres = { path = "../store/postgres" }
 # Test command dependencies
 hex = "0.4"
 async-trait = { workspace = true }
+tower = { workspace = true }
 
 # Direct dependencies from current dev.rs
 anyhow = { workspace = true }

gnd/Cargo.toml

@@ -22,7 +22,7 @@ gnd test --matchstick
 
 Tests are JSON files that define:
 - Mock blockchain blocks with events
-- Mock `eth_call` responses
+- Mock Ethereum RPC responses (`eth_call`, `eth_getBalance`, `eth_getCode`)
 - GraphQL assertions to validate entity state
 
 Place test files in a `tests/` directory with `.json` or `.test.json` extension.
@@ -82,6 +82,8 @@ Place test files in a `tests/` directory with `.json` or `.test.json` extension.
 | `baseFeePerGas` | No | None (pre-EIP-1559) | Base fee in wei |
 | `events` | No | Empty array | Log events in this block |
 | `ethCalls` | No | Empty array | Mock `eth_call` responses |
+| `getBalanceCalls` | No | Empty array | Mock `eth_getBalance` responses for `ethereum.getBalance()` |
+| `hasCodeCalls` | No | Empty array | Mock `eth_getCode` responses for `ethereum.hasCode()` |
 
 ### Empty Blocks
 
@@ -144,6 +146,56 @@ Event parameters are automatically ABI-encoded based on the signature. Supported
 }
 ```
 
+## Transaction Receipts
+
+Mock receipts are constructed for every log trigger and attached only to handlers that declare `receipt: true` in the manifest, mirroring production behaviour. Handlers without `receipt: true` receive a null receipt — the same as on a real node.
+
+**Limitation:** Only `receipt.logs` reflects your test data. All other receipt fields (`from`, `to`, `gas_used`, `status`, etc.) are hardcoded stubs and do not correspond to real transaction data. If your handler reads those fields, the values will be fixed defaults regardless of what you put in the test JSON.
+
+### How receipts are built
+
+Every event gets a mock receipt attached automatically. The key rule is **`txHash` grouping**:
+
+- Events sharing the same `txHash` share **one receipt** — `event.receipt!.logs` contains all of their logs in declaration order.
+- Events without an explicit `txHash` each get a unique auto-generated hash (`keccak256(block_number || log_index)`), so each gets its own single-log receipt.
+
+### Example: Two events sharing a receipt
+
+```json
+{
+  "events": [
+    {
+      "address": "0x1234...",
+      "event": "Transfer(address indexed from, address indexed to, uint256 value)",
+      "params": { "from": "0xaaaa...", "to": "0xbbbb...", "value": "100" },
+      "txHash": "0xdeadbeef0000000000000000000000000000000000000000000000000000000"
+    },
+    {
+      "address": "0x1234...",
+      "event": "Transfer(address indexed from, address indexed to, uint256 value)",
+      "params": { "from": "0xbbbb...", "to": "0xcccc...", "value": "50" },
+      "txHash": "0xdeadbeef0000000000000000000000000000000000000000000000000000000"
+    }
+  ]
+}
+```
+
+Both handlers receive a receipt where `receipt.logs` has two entries, in declaration order.
+
+### Mock receipt defaults
+
+| Field | Value |
+|-------|-------|
+| `status` | success |
+| `cumulative_gas_used` | `21000` |
+| `gas_used` | `21000` |
+| transaction type | `2` (EIP-1559) |
+| `from` | `0x000...000` |
+| `to` | `null` |
+| `effective_gas_price` | `0` |
+
+Handlers without `receipt: true` in the manifest are unaffected — they never access `event.receipt`.
+
 ## Block Handlers
 
 Block handlers are **automatically triggered** for every block. You don't need to specify block triggers in the JSON.
@@ -309,7 +361,7 @@ Mock contract calls made from mapping handlers using `contract.call()`:
 | `function` | Yes | Full signature: `"functionName(inputTypes)(returnTypes)"` |
 | `params` | Yes | Array of input parameters (as strings) |
 | `returns` | Yes | Array of return values (as strings, ignored if `reverts: true`) |
-| `reverts` | No | Default `false`. If `true`, the call is cached as `Retval::Null` |
+| `reverts` | No | Default `false`. If `true`, the mock transport returns an RPC error |
 
 ### Function Signature Format
 
@@ -364,6 +416,110 @@ From the ERC20 test:
 }
 ```
 
+## ethereum.getBalance() Mocking
+
+Mock balance lookups made from mapping handlers using `ethereum.getBalance()`:
+
+```json
+{
+  "getBalanceCalls": [
+    {
+      "address": "0xaaaa000000000000000000000000000000000000",
+      "value": "1000000000000000000"
+    }
+  ]
+}
+```
+
+### getBalanceCalls Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `address` | Yes | Account address (checksummed or lowercase hex) |
+| `value` | Yes | Balance in Wei as a decimal string |
+
+## ethereum.hasCode() Mocking
+
+Mock code existence checks made from mapping handlers using `ethereum.hasCode()`:
+
+```json
+{
+  "hasCodeCalls": [
+    {
+      "address": "0x1234000000000000000000000000000000000000",
+      "hasCode": true
+    }
+  ]
+}
+```
+
+### hasCodeCalls Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `address` | Yes | Contract address (checksummed or lowercase hex) |
+| `hasCode` | Yes | Whether the address has deployed bytecode |
+
+## File Data Sources
+
+Mock IPFS and Arweave file contents for file data source handlers. Files are defined at the top level of the test JSON (not inside blocks).
+
+### IPFS Files
+
+```json
+{
+  "name": "File data source test",
+  "files": [
+    {
+      "cid": "QmExample...",
+      "content": "{\"name\": \"Token\", \"description\": \"A token\"}"
+    },
+    {
+      "cid": "QmAnother...",
+      "file": "fixtures/metadata.json"
+    }
+  ],
+  "blocks": [...],
+  "assertions": [...]
+}
+```
+
+#### files Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `cid` | Yes | IPFS CID (`Qm...` or `bafy...`). The mock ignores hash/content relationship |
+| `content` | One of `content`/`file` | Inline UTF-8 content |
+| `file` | One of `content`/`file` | File path, resolved relative to the test JSON |
+
+### Arweave Files
+
+```json
+{
+  "name": "Arweave data source test",
+  "arweaveFiles": [
+    {
+      "txId": "abc123",
+      "content": "{\"name\": \"Token\"}"
+    },
+    {
+      "txId": "def456/metadata.json",
+      "file": "fixtures/arweave-data.json"
+    }
+  ],
+  "blocks": [...],
+  "assertions": [...]
+}
+```
+
+#### arweaveFiles Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `txId` | Yes | Arweave transaction ID or bundle path (e.g. `"txid/filename.json"`) |
+| `content` | One of `content`/`file` | Inline UTF-8 content |
+| `file` | One of `content`/`file` | File path, resolved relative to the test JSON |
+
 ## Assertions
 
 GraphQL queries to validate the indexed entity state after processing all blocks.
@@ -597,10 +753,12 @@ my-subgraph/
 |---------|--------|
 | Log events | ✅ Supported |
 | Block handlers (all filters) | ✅ Supported |
-| eth_call mocking | ✅ Supported |
+| `eth_call` mocking | ✅ Supported |
+| `ethereum.getBalance()` mocking | ✅ Supported |
+| `ethereum.hasCode()` mocking | ✅ Supported |
 | Dynamic/template data sources | ✅ Supported |
-| Transaction receipts (`receipt: true`) | ❌ Not implemented — handlers get `null` |
-| File data sources / IPFS mocking | ❌ Not implemented |
+| Transaction receipts (`receipt: true`) | ⚠️ Partial — `receipt.logs` is populated and grouped by `txHash`; other fields (gas, from, to, etc.) are hardcoded stubs (see [Transaction Receipts](#transaction-receipts)) |
+| File data sources (IPFS + Arweave) | ✅ Supported |
 | Call triggers (traces) | ❌ Not implemented |
 | `--json` CI output | ❌ Not implemented |
 | Parallel test execution | ❌ Not implemented |
@@ -714,10 +872,8 @@ GraphQL queries → Assertions
 **Key design principles:**
 
 - **Isolated database per test:** Each test gets a pgtemp database dropped on completion (default), or a shared persistent database with post-test cleanup (`--postgres-url`)
-- **Real WASM runtime:** Uses `EthereumRuntimeAdapterBuilder` with real `ethereum.call` host function
-- **Pre-populated call cache:** `eth_call` responses are cached before indexing starts
+- **Mock transport layer:** A mock Alloy transport serves `eth_call`, `eth_getBalance`, and `eth_getCode` from test JSON data. All three flow through the real production code path — only the transport returns mock responses. Unmocked RPC calls fail immediately with a descriptive error.
 - **No IPFS for manifest:** Uses `FileLinkResolver` to load manifest/WASM from build directory
-- **Dummy RPC adapter:** Registered at `http://0.0.0.0:0` for capability lookup; never actually called
 
 ## Troubleshooting
 
@@ -740,14 +896,19 @@ GraphQL queries → Assertions
 2. Simplify mapping logic
 3. Check for infinite loops in handler code
 
-### eth_call Returns Wrong Value
+### Unmocked RPC Call
+
+**Cause:** A mapping handler calls `ethereum.call`, `ethereum.getBalance`, or `ethereum.hasCode` for a call that has no matching mock entry.
 
-**Cause:** Call cache miss — no matching mock in `ethCalls`.
+**Symptom:** Test fails immediately with a descriptive error like:
+```
+gnd test: unmocked eth_call to 0x1234... at block hash 0xabcd...
+Add a matching 'ethCalls' entry to this block in your test JSON.
+```
 
 **Fix:**
-1. Verify `address`, `function`, and `params` exactly match the call from your mapping
-2. Check function signature format: `"functionName(inputTypes)(returnTypes)"`
-3. Ensure parameters are in correct order
+1. Add the missing mock to the appropriate field in your test block (`ethCalls`, `getBalanceCalls`, or `hasCodeCalls`)
+2. If the call is not supposed to happen, check the mapping logic — a code path may be executing unexpectedly
 
 ### Block Handler Not Firing
 

gnd/docs/gnd-test.md

@@ -77,13 +77,10 @@ async fn run_single_assertion(
     }
 }
 
-/// Reorder `actual` arrays to align with `expected`'s element ordering.
+/// Reorder `actual` arrays to match `expected`'s element order for cleaner diffs.
 ///
-/// When a test fails, the raw diff can be misleading if array elements appear
-/// in a different order — every line shows as changed even if only one field
-/// differs. This function reorders `actual` so that elements are paired with
-/// their closest match in `expected`, producing a diff that highlights only
-/// real value differences.
+/// Without this, out-of-order elements show every field as changed even when
+/// only one field differs.
 pub(super) fn align_for_diff(
     expected: &serde_json::Value,
     actual: &serde_json::Value,
@@ -132,12 +129,8 @@ pub(super) fn align_for_diff(
     }
 }
 
-/// Score how similar two JSON values are for use in [`align_for_diff`].
-///
-/// For objects, counts the number of fields whose values are equal in both.
-/// A matching `"id"` field is weighted heavily (+100) since it is the
-/// strongest signal that two objects represent the same entity.
-/// For all other value types, returns 1 if equal, 0 otherwise.
+/// Score JSON similarity for [`align_for_diff`].
+/// Objects: matching `"id"` = 100, other equal fields = 1. Non-objects: 0 or 1.
 fn json_similarity(a: &serde_json::Value, b: &serde_json::Value) -> usize {
     match (a, b) {
         (serde_json::Value::Object(a_obj), serde_json::Value::Object(b_obj)) => {
@@ -162,13 +155,9 @@ fn json_similarity(a: &serde_json::Value, b: &serde_json::Value) -> usize {
     }
 }
 
-/// Compare two JSON values for equality (ignoring key ordering in objects).
+/// Compare JSON values for equality, ignoring object key ordering.
 ///
-/// Also handles string-vs-number coercion: GraphQL returns `BigInt` and
-/// `BigDecimal` fields as JSON strings (e.g., `"1000000000000000000"`),
-/// but test authors may write them as JSON numbers. This function treats
-/// `String("123")` and `Number(123)` as equal when they represent the
-/// same value.
+/// Coerces string/number: `"123"` == `123` to handle GraphQL `BigInt`/`BigDecimal`.
 fn json_equal(a: &serde_json::Value, b: &serde_json::Value) -> bool {
     match (a, b) {
         (serde_json::Value::Null, serde_json::Value::Null) => true,

gnd/src/commands/test/assertion.rs

@@ -63,21 +63,15 @@ impl BlockStreamBuilder<Chain> for StaticStreamBuilder {
     }
 }
 
-/// A `Stream` that synchronously yields pre-defined blocks one at a time.
-///
-/// Each `poll_next` call returns the next block immediately (no async waiting).
-/// When all blocks have been emitted, returns `None` to signal stream completion,
-/// which tells the indexer that sync is done.
+/// A `Stream` that yields pre-defined blocks synchronously.
+/// Returns `None` when all blocks are emitted, signaling sync completion.
 struct StaticStream {
     blocks: Vec<BlockWithTriggers<Chain>>,
     current_idx: usize,
 }
 
 impl StaticStream {
-    /// Create a new stream, optionally skipping past already-processed blocks.
-    ///
-    /// `skip_to`: If `Some(i)`, start from block `i+1` (block `i` was already processed).
-    /// If `None`, start from the beginning.
+    /// `skip_to`: if `Some(i)`, start from block `i+1` (block `i` already processed).
     fn new(blocks: Vec<BlockWithTriggers<Chain>>, skip_to: Option<usize>) -> Self {
         Self {
             blocks,