# Every Action Leaves a Trace

**Every Action Leaves a Trace.** For an agent, provenance is a usable evidence record, not an adjective attached to an answer.

## Ask for the exact identity and window

After a successful read, keep its bound-function ID, returned field names, and resolved half-open block interval. Invoke `provenance` with the same identity and window. It takes no `attribute` or `key` selector; the evidence describes the bound function's window. A different window is a different evidence request.

```json
{"tool":"provenance","arguments":{"bound_function_id":"<BOUND_FUNCTION_ID>","from_block":100,"to_block":110}}
```

Provenance is a separate tool call. Do not claim that every read automatically contains the expanded source-block list.

## What to preserve

The implementation expands contributing blocks into an ordered list with block numbers and hashes, a block count, and a recomputed digest when the contributing list is non-empty. An empty `blocks` list means enumeration found nothing; missing `blocks` means evidence is not enumerated. Do not invent absent digests. When a result supplies a compact digest-bound `ChainRange`, compare the expanded `digest` with that corresponding `ChainRange.digest`. A REST data row carries `provenance.digest` for its own block; expand `[block, block+1)` to compare it.

Persist the identity, chain, measure, window, compact record where supplied, expanded source list, digest, and comparison outcome. Preserve the algorithm and encoding supplied by the contract if independently recomputing; an invented concatenation of hashes is not a valid verification procedure.

## Canonical source-digest encoding

The observed implementation sorts contributing pairs by ascending block number, then hashes UTF-8 lines in this exact form:

```text
{chain_id}:{block_number}:{lowercase_0x_block_hash}\n
```

The result is `sha256:` followed by lowercase SHA-256 hex. The newline is one actual LF byte per pair, including the final pair. Chain ID and block number are decimal integers. Use the exact contributing set returned by the contract; do not add every block in the enclosing span.

A verifier can reproduce that digest locally:

```python
import hashlib

def source_digest(chain_id, blocks):
    ordered = sorted(blocks, key=lambda block: block["number"])
    encoded = "".join(
        f"{chain_id}:{block['number']}:{block['block_hash'].lower()}\n"
        for block in ordered
    ).encode("utf-8")
    return "sha256:" + hashlib.sha256(encoded).hexdigest()
```

This verifies encoding consistency for the supplied list. For independent source verification, obtain the corresponding canonical block hashes independently as well.

**Two range conventions differ:** tool requests use the exclusive `to_block`, while a compact `ChainRange` citation's `from` and `to` are the **inclusive minimum and maximum contributing block numbers**. Its `block_count` is the actual contributing count and may be smaller than the enclosing span because of gaps. Do not pass the citation's inclusive end directly into a half-open tool request.

## Source evidence and computation evidence

Matching source hashes establishes the requested source evidence's consistency with its digest. It does not, by itself, prove the metric definition matches the operator's intent or independently replay the computation. Distinguish source verification, definition review, and independent recomputation in the final answer.

## Missing coverage and empty blocks

A block with no matching event can be legitimate evidence. A missing block is unavailable coverage. Do not conflate them or collapse both into a zero value. Provenance requires its stated window to be covered; inspect the reported geometry and complete missing work before asserting verification.

## Bounded expansion

Expansion is limited to 10,000 contributing blocks per response. For larger requests, use smaller meaningful windows and retain the boundaries of each verification record. Do not claim that independently expanded subwindows match one whole-window digest unless the contract supplies a valid composition rule.

## Credentials stay out of evidence

Agent-facing source descriptions should identify providers or chains without exposing credential-bearing RPC URLs. Block numbers, hashes, function identity, and reproducible definitions are more useful evidence than a secret endpoint string.