> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletwall.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Evidence Model (WWEP)

> How WalletWall reasons about evidence: sources, observations and assertions; support, authority, freshness and finality; and how an assessment becomes a WallPrint.

The **WalletWall Evidence Profile** (WWEP, version `0.1`, draft) is the model behind every WalletWall
MCP result. It defines a structured record of *what evidence was presented, from where, with what
authority and with what limits*, and a deterministic procedure that classifies how well that evidence
supports a claim.

WWEP is a WalletWall-defined profile. It is not an industry standard and has not been reviewed outside
WalletWall. Its normative text is served by the server as `walletwall://spec/wwep` and published as
[`spec/EVIDENCE_PROFILE.md`](https://github.com/Wallet-Wall/walletwall-copilot/blob/main/spec/EVIDENCE_PROFILE.md).
Where that draft text and the engine differ (it describes every object as closed, addresses as compared
case-insensitively, and the content digest as the duplicate detector), this page follows the engine.

> [!NOTE]
>
> **The rule behind every state.** A WWEP state describes the sufficiency of *presented* evidence under
> a *published* policy. `ESTABLISHED` means "the presented evidence satisfies the policy for this claim
> type", never "this is verified truth".

## From source to resolver

```mermaid theme={null}
flowchart TD
    accTitle: The WWEP evidence chain
    accDescr: A source produces observations. Observations support assertions. Each assertion is evaluated for support, authority, freshness and finality against the bundled policies, registry and rules, and that evaluation is WalletWall's assessment. A WallPrint commits an assessment as a disclosure record, and a receipt or the public resolver proves the record's bytes and locates it. Transport is recorded but never treated as authority, and conflicts, staleness and gaps stay visible.

    source["Source<br/>where evidence came from"]
    observation["Observation<br/>one reading, with its result and finality"]
    assertion["Assertion<br/>a claim about a subject"]
    evaluation{"Support · authority<br/>freshness · finality"}
    assessment["WalletWall assessment<br/>a support state per claim,<br/>a readiness classification"]
    wallprint[("WallPrint<br/>a committed disclosure record")]
    resolver["Receipt / public resolver<br/>proves bytes, locates the record"]
    transport["transport.retrievedVia<br/>recorded, never authority"]
    policy[("Authority policies,<br/>registry and rules")]
    gaps["Conflicts, staleness and gaps<br/>stay visible, never collapsed"]

    source --> observation
    observation --> assertion
    assertion --> evaluation
    policy --> evaluation
    evaluation --> assessment
    assessment --> wallprint
    wallprint --> resolver
    transport -.-> source
    evaluation -.-> gaps

    class source,observation input;
    class assertion process;
    class evaluation decision;
    class assessment output;
    class wallprint,policy datastore;
    class resolver security;
    class transport external;
    class gaps risk;

    classDef input fill:#FAF8F3,stroke:#C9A47A,color:#1E1A14,stroke-width:1.5px;
    classDef process fill:#BF4E32,stroke:#8B3120,color:#FAF8F3,stroke-width:1.5px;
    classDef decision fill:#C9A47A,stroke:#8B6F47,color:#1E1A14,stroke-width:1.5px;
    classDef output fill:#E6DED2,stroke:#9A9186,color:#1E1A14,stroke-width:1.5px;
    classDef risk fill:#8B3120,stroke:#1E1A14,color:#FAF8F3,stroke-width:1.5px;
    classDef datastore fill:#1E1A14,stroke:#9A9186,color:#FAF8F3,stroke-width:1.5px;
    classDef external fill:#FAF8F3,stroke:#9A9186,color:#1E1A14,stroke-width:1.5px;
    classDef security fill:#1E1A14,stroke:#C9A47A,color:#FAF8F3,stroke-width:1.5px;
```

Everything up to the assessment happens inside WalletWall MCP, on your machine, every time you call a
tool. WallPrint and the public resolver are a separate, deliberate publication step; see
[WallPrint](https://docs.walletwall.org/mcp/wallprint.md).

## 1. Source

A **source** says where evidence came from. It *produces* or *supports* observations; it never
asserts anything by itself.

```json theme={null}
{ "id": "src-chain", "kind": "CHAIN_STATE", "transport": { "retrievedVia": "ExampleRpcProvider" }, "independenceGroup": "grp-chain" }
```

| Kind | What it is |
| - | - |
| `CHAIN_STATE` | Canonical chain state at an identified block |
| `ISSUER_PUBLICATION` | A publication by the issuer or protocol that is the authority for a claim; carries an `authorityId` |
| `PROVIDER_ENDPOINT` | A third party reporting a value on its own behalf, such as a price feed or a label |
| `USER_INPUT` | A value supplied by the person using the tool |
| `WALLETWALL_RULES` | WalletWall's published rules, for derived values |

`transport.retrievedVia` records *how the bytes arrived* (an RPC provider, an indexer, a local node).
It is metadata, never authority: a balance read through a provider's RPC endpoint is still a
`CHAIN_STATE` reading, and the provider does not become the authority for Ethereum state.

`independenceGroup` says which sources can fail independently. Sources in the same group count once
toward corroboration, and every source that declares no group falls into one shared group, so listing
several endpoints never makes them independent.

## 2. Observation

An **observation** is one reading from one source.

```json theme={null}
{
  "id": "obs-balance",
  "sourceId": "src-chain",
  "origin": "CHAIN_OBSERVED",
  "observedAt": "2026-10-23T12:00:00Z",
  "finality": "FINALIZED",
  "result": "VALUE",
  "subject": { "chainId": "1", "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "holder": "0x1234567890123456789012345678901234567890", "blockNumber": "21000000", "blockHash": "0xabababababababababababababababababababababababababababababababab" },
  "payload": { "balanceAtomic": "1500000", "decimals": "6" }
}
```

* `result` is `VALUE`, `NO_RESULT` or `ERROR`. Only `VALUE` carries a value; the other two record that
  a source was consulted and produced nothing usable.
* `finality` is `FINALIZED`, `UNFINALIZED` or `UNKNOWN_FINALITY`, as the reading declares it.
* `origin` classifies the evidence, and each origin pairs with exactly one source kind:

| Origin | Source kind | Meaning |
| - | - | - |
| `CHAIN_OBSERVED` | `CHAIN_STATE` | Read from canonical chain state at an identified block |
| `AUTHORITY_ATTESTED` | `ISSUER_PUBLICATION` | Stated by the issuer or protocol that is the authority for the claim |
| `PROVIDER_OBSERVED` | `PROVIDER_ENDPOINT` | Reported by a third party on its own behalf |
| `USER_SUPPLIED` | `USER_INPUT` | Supplied by the user |
| `WALLETWALL_DERIVED` | `WALLETWALL_RULES` | Computed by a published WalletWall rule |

An observation whose source kind does not match its origin does not count as evidence of that origin
(`ORIGIN_SOURCE_KIND_MISMATCH`).

**Observations are not automatically assertions.** A reading supports nothing until an assertion cites
it, and the assertion's subject and value must match the observation's subject and payload.

## 3. Assertion

An **assertion** is a claim about a subject, backed by observations or by a derivation.

```json theme={null}
{
  "id": "a-balance",
  "claimType": "TOKEN_BALANCE_AT_BLOCK",
  "origin": "CHAIN_OBSERVED",
  "temporality": "PINNED",
  "subject": { "chainId": "1", "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "holder": "0x1234567890123456789012345678901234567890", "blockNumber": "21000000", "blockHash": "0xabababababababababababababababababababababababababababababababab" },
  "value": { "balanceAtomic": "1500000", "decimals": "6" },
  "observationIds": ["obs-balance"],
  "assertedAt": "2026-10-23T12:00:00Z"
}
```

* `temporality` is `CURRENT` (a claim about now, which must be fresh) or `PINNED` (a claim about a
  fixed point, such as a block).
* `subject` and `value`, like an observation's `payload`, are flat maps of up to 16 entries; keys the
  claim's contract does not use are accepted and ignored. `value` may be `null`, and an assertion with
  no observation and no derivation must not carry one.
* `declared` (optional) lets an author state the support, freshness, finality and corroboration they
  *believe* apply. The engine never trusts it, and reports any excess as a violation: of the specific
  invariant it breaks, or of `INV-00`.
* A **derivation** applies a WalletWall rule to *assertions*, never to raw observations. WWEP 0.1 has
  two rules: `wwdr.usd-value` and `wwvr.vault-technical-readiness`.

WWEP 0.1 defines five claim types, and **each rests on different evidence**:

| Claim type | Authority that may establish it | May only corroborate | Finality | Max age when `CURRENT` |
| - | - | - | - | - |
| `ASSET_IDENTITY` | An issuer or protocol publication whose `authorityId` equals the registry's for that deployment | Chain or provider readings, capped at `PARTIAL` | n/a | 30 days |
| `TOKEN_BALANCE_AT_BLOCK` | Canonical finalized chain state at the identified block | Provider readings, capped at `SUPPORTED` | Required for `ESTABLISHED` | 120 seconds |
| `TOKEN_USD_PRICE` | None: a market price has no canonical authority | Provider or chain readings, capped at `SUPPORTED` | n/a | 300 seconds |
| `TOKEN_USD_VALUE` | WalletWall rule `wwdr.usd-value`, derived only | n/a | Inherited | Inherited |
| `VAULT_TECHNICAL_READINESS` | WalletWall rule `wwvr.vault-technical-readiness`, derived only | n/a | Inherited | Inherited |

A stablecoin symbol never establishes identity. An on-chain `symbol()` reading can be spoofed, so it
can only corroborate. These policies are served as `walletwall://policies/authority`.

## 4. Evaluation: support, authority, freshness and finality

`inspect_evidence` evaluates every assertion. Evaluation is a pure function of the bundle, the
evaluation time, and the bundled registry, policies and rules. The engine never reads a clock, so the
same inputs always give the same states.

### Support

| State | Meaning |
| - | - |
| `ESTABLISHED` | An observation from an origin the policy names as authoritative, from a source of the matching kind and authority, agrees with the asserted value; finality is satisfied where required, the evidence is fresh where the claim is `CURRENT`, nothing conflicts, and every dependency of a derived claim is `ESTABLISHED` |
| `SUPPORTED` | Meets the policy except for authority or finality: an authoritative reading that is not finalized, or corroboration by enough independent groups without an authoritative reading |
| `PARTIAL` | Some usable evidence, but not enough: a single or non-independent provider, user input only, an asset identity outside the registry, an identity or balance on a chain outside the registry, unknown rules, unknown freshness for a current claim. A balance of a token outside the registry is only flagged `NOT_IN_REGISTRY` |
| `CONFLICTING` | Observations or assertions about the same claim disagree, or a conflict is declared |
| `STALE` | A `CURRENT` claim whose newest observation is older than the policy allows, or whose dependency was superseded |
| `SUPERSEDED` | A supersession record names this assertion as replaced; the old assertion stays in the bundle, and a supersession whose successor is missing, earlier or about another claim is reported under `INV-12` |
| `UNKNOWN` | Sources were consulted but returned only `NO_RESULT` or `ERROR`; not false, not zero |
| `NOT_ESTABLISHED` | No admissible basis: no source, a wrong subject or value, invalid values, a registry mismatch, a missing dependency, a disallowed derivation, a cycle |

When states combine across dependencies, the **weakest member wins**, in this order from strongest to
weakest:

```text theme={null}
ESTABLISHED > SUPPORTED > PARTIAL > STALE > SUPERSEDED > UNKNOWN > CONFLICTING > NOT_ESTABLISHED
```

### Authority

Authority is **claim-specific**. There is no global ranking such as "chain beats issuer beats provider".
Each claim type's policy names which origins may *establish* the claim and which may only
*corroborate* it, and corroboration alone can never reach `ESTABLISHED`.

**Authority is not correctness.** An authoritative source can be wrong, and a caller can present
fabricated evidence that is perfectly well formed. The engine evaluates evidence as presented: it
cannot verify that a chain reading was faithfully retrieved, and it attaches
`TRANSPORT_FIDELITY_NOT_VERIFIED` to every chain reading to say so. `authority.satisfied: true` means
the policy's authority requirement was met by the evidence in the bundle, nothing more.

**Corroboration counts independence, not volume.** Observations in one independence group that report
the same value count once (`DUPLICATE_EVIDENCE_COLLAPSED`). Two provider endpoints in one
independence group are one witness. `independentCorroboration` reports the number of distinct groups.

### Freshness

Freshness decides whether evidence can support a claim **about the present**.

| State | Meaning |
| - | - |
| `CURRENT` | A `CURRENT` claim whose newest observation is within the policy's maximum age and not in the future |
| `STALE` | A `CURRENT` claim older than the maximum age. A stale result never satisfies a current claim |
| `PINNED` | A claim about a fixed point, such as a block; recency does not apply |
| `UNKNOWN_FRESHNESS` | No maximum age applies, an observation is timestamped after the evaluation time, a current claim depends on pinned evidence, or evaluation stopped before freshness was judged (no source, only empty results, a shape failure, a disagreement or a mismatch) |

Because `evaluatedAt` is an input, freshness is always relative to a time you choose. The published
`identity-established` example evaluates as `ESTABLISHED` at its own `evaluatedAt` of
`2026-10-23T12:00:30Z`; the same bundle evaluated at `2026-12-01T00:00:00Z`, more than 30 days later,
is `STALE` with `STALE_EVIDENCE`. An observation dated after `evaluatedAt` makes freshness
`UNKNOWN_FRESHNESS`, with the limitation `OBSERVATION_FROM_FUTURE`.

### Finality

| State | Meaning |
| - | - |
| `FINALIZED` | Every observation relied on states a finalized block |
| `UNFINALIZED` | At least one states that it is not finalized |
| `UNKNOWN_FINALITY` | At least one does not state finality, and none states `UNFINALIZED` |
| `null` | Finality does not apply to the claim type (asset identity, price) |

Finality matters for chain-derived observations: a balance can be `ESTABLISHED` only at a finalized
block. The same balance read at an unfinalized block is `SUPPORTED`, with authority satisfied and the
limitation `NOT_FINALIZED`; with unknown finality it is `SUPPORTED` with `FINALITY_UNKNOWN`. When
observations disagree about finality, the least final is reported.

### Limitations

Evaluations carry **limitations**: codes from a closed list that explain why a result is weaker than it
might look. Some of the most common:

| Code | Meaning |
| - | - |
| `TRANSPORT_FIDELITY_NOT_VERIFIED` | A chain reading is evaluated as presented; its retrieval was not verified |
| `REGISTRY_VERIFIED_POINT_IN_TIME` | The registry record was verified once, on a stated date |
| `NO_AUTHORITATIVE_OBSERVATION` | No observation from an origin that may establish the claim |
| `INSUFFICIENT_INDEPENDENT_CORROBORATION` | Not enough independent groups to corroborate |
| `SYMBOL_NOT_AUTHORITY` | A symbol was relied on, and symbols never establish identity |
| `STALE_EVIDENCE` / `NOT_FINALIZED` / `FINALITY_UNKNOWN` | The freshness or finality requirement was not met |
| `NO_SOURCE` / `NO_RESULT` | No observation at all, or a cited observation that returned no value |
| `OBSERVATION_DISAGREEMENT` | Observations of the same claim disagree |
| `WALLETWALL_DERIVED_NOT_UPSTREAM_AUTHORITY` | A WalletWall-derived result, not a statement by any upstream authority |

The complete list is the limitation enumeration in `walletwall://schemas/evidence`.

### Conflicts and supersession

**Conflicting evidence is never silently collapsed.** When two chain readings of the same balance
disagree, the balance is `CONFLICTING` with `OBSERVATION_DISAGREEMENT`: WalletWall does not pick one,
average them or rank their sources. A conflict propagates to every claim that depends on it, and it
never lets readiness reach `CRITERIA_MET`: the criteria it touches cannot be decided, so the
classification is `NOT_ESTABLISHED` unless another criterion has definitely failed
(`CRITERIA_NOT_MET`).

**History is superseded, never rewritten.** A supersession record replaces an older assertion with a
newer one about the same claim; the older assertion stays in the bundle and is reported `SUPERSEDED`,
and claims that depend on it are treated as `STALE` (`DEPENDENCY_SUPERSEDED`).

### Evaluation order

For one assertion backed directly by observations:

1. No observation: `NOT_ESTABLISHED` (`NO_SOURCE`).
2. Only `NO_RESULT` or `ERROR`: `UNKNOWN`.
3. An invalid or mismatched subject, or invalid values: `NOT_ESTABLISHED`.
4. Observations disagree: `CONFLICTING`.
5. The asserted value differs from the observed value: `NOT_ESTABLISHED` (`VALUE_MISMATCH`).
6. Registry checks of identity and decimals: `NOT_ESTABLISHED` on a mismatch.
7. Authority, corroboration and finality: `ESTABLISHED`, `SUPPORTED` or `PARTIAL`.
8. Freshness, for `CURRENT` claims: may lower the result to `STALE` or `PARTIAL`.
9. Lifecycle: supersession overrides to `SUPERSEDED`, and a conflict overrides to `CONFLICTING`.

Derived assertions are evaluated through their dependencies, recursively, with cycles detected and
reported, and they keep every limitation of their inputs.

## 5. WalletWall assessment

WalletWall's **assessment** is the result of evaluation, in two forms:

* **Per claim**: the support, freshness and finality states, authority, limitations and conflicts that
  `inspect_evidence` returns for each assertion.
* **Per question**: a classification derived by a published rule. In WWEP 0.1 that is
  `VAULT_TECHNICAL_READINESS`, returned by `assess_vault_readiness` as `CRITERIA_MET`,
  `CRITERIA_NOT_MET` or `NOT_ESTABLISHED`, criterion by criterion.

An assessment is WalletWall's conclusion under its own published policy. Per-claim states keep the
assertion's own origin; the readiness classification and every derived claim are WalletWall-derived and
carry `WALLETWALL_DERIVED_NOT_UPSTREAM_AUTHORITY`. Processing never increases the authority of its
inputs.

**When required evidence is absent, WalletWall refuses or qualifies.** A missing issuer attestation
leaves the identity `PARTIAL`, which leaves readiness criterion C1 `INDETERMINATE` and the
classification `NOT_ESTABLISHED` (the published example for this case also names the smallest
measurement that could change the outcome). The engine never fills a
gap, never upgrades an `UNKNOWN`, and never answers a generic "ready". The
[Quickstart](https://docs.walletwall.org/mcp/quickstart.md) shows both outcomes.

## 6. WallPrint

A **WallPrint** freezes one assessment into a disclosure record: the evidence references, every claim's
computed evaluation, the assessments, provenance, limitations, conflicts and invariant violations, and
the policy, rule and registry versions in force, serialized canonically and identified by a digest.
WallPrint adds no evidence state of its own; it records the engine's. Corrections and supersessions add
new records and never edit old ones. See [WallPrint](https://docs.walletwall.org/mcp/wallprint.md).

## 7. Receipt and public resolver

A **receipt** shows that a disclosed WallPrint record matches its committed bytes. The **public
resolver** at `walletwall.org/wallprint` locates a deliberately published record from its portable
reference, proves its bytes in your browser, and shows it. Both prove integrity, not truth: a matching
digest says the bytes are the committed ones, not that any claim in them is correct.

## Distinctions WalletWall enforces

| Principle | How WWEP enforces it |
| - | - |
| A source produces or supports observations | An observation's origin must match its source's kind (`ORIGIN_SOURCE_KIND_MISMATCH`, `INV-13`) |
| Observations are not automatically assertions | An assertion needs cited observations or a derivation before it can carry a value (`NO_SOURCE`, `INV-01`) |
| Assertions can rest on different evidence | Each claim type has its own contract and authority policy (`walletwall://schemas/claims`) |
| Authority is not correctness | `ESTABLISHED` means policy satisfied; chain readings carry `TRANSPORT_FIDELITY_NOT_VERIFIED` |
| Freshness decides whether evidence is usable for a current claim | A stale result never satisfies a current claim (`INV-02`) |
| Finality matters for chain-derived observations | A balance is `ESTABLISHED` only at a finalized block (`NOT_FINALIZED` otherwise) |
| Conflicting evidence is never silently collapsed | `CONFLICTING` never satisfies `ESTABLISHED`, and conflicts are never auto-resolved (`INV-03`) |
| Incomplete evidence stays incomplete | `NO_RESULT` never becomes zero and `UNKNOWN` never becomes false; derived results keep their dependencies' limitations (`INV-04`, `INV-05`, `INV-10`) |
| Required evidence absent means refuse or qualify | The weakest member wins; readiness is `NOT_ESTABLISHED` when a criterion cannot be decided |

## The invariants

`check_invariants` reports violations of these; several fire only when an author's `declared` states
claim more than the engine computed. Executable conformance tests in the source repository cover each
one.

| ID | Invariant |
| - | - |
| `INV-00` | Declared states must not exceed states computed by the published rules. It is also the engine-rule check that reports dangling references, duplicate source, observation or derivation IDs, and derived values that do not recompute |
| `INV-01` | No source, no fact: an assertion with no observation and no derivation must not carry a value or be presented as `PARTIAL` or stronger |
| `INV-02` | `STALE` must not satisfy `CURRENT` |
| `INV-03` | `CONFLICTING` must not satisfy `ESTABLISHED` |
| `INV-04` | `NO_RESULT` must not become zero |
| `INV-05` | `UNKNOWN` must not become false |
| `INV-06` | `WALLETWALL_DERIVED` must not masquerade as upstream authority |
| `INV-07` | Processing evidence must not increase the authority of its inputs |
| `INV-08` | Duplicate evidence must not increase independent corroboration |
| `INV-09` | Multiple provider endpoints must not automatically imply independent authority |
| `INV-10` | Derived results retain the limitations of their dependencies |
| `INV-11` | Token quantity must not silently become USD value without explicit price evidence |
| `INV-12` | Historical assertions are superseded, never silently rewritten |
| `INV-13` | Source transport and source authority are separate concepts |

## Canonical form and digests

* Evidence objects are serialized with the **RFC 8785** JSON Canonicalization Scheme and hashed with
  **SHA-256**. Ordinary `JSON.stringify` output is never hashed.
* Every evidence-critical value is a string. A JSON number in evidence is rejected, so no quantity can
  lose precision.
* Quantities are canonical atomic-unit decimal strings no larger than 2²⁵⁶ − 1, with `decimals` at most
  36\. Arithmetic uses integers, and decimal renderings are exact and unrounded.
* An observation has two digests: the **evidence digest** of the whole observation, and the
  **content digest** of its `result`, `subject` and `payload` only. When counting corroboration, the
  engine collapses readings from one independence group that report the same value
  (`DUPLICATE_EVIDENCE_COLLAPSED`).

> [!TIP]
>
> Use lowercase hexadecimal addresses everywhere in a bundle; `normalize_observation` lowercases them
> for you. Matching an observation to its assertion ignores address case, but conflict grouping and
> supersession compare subjects exactly, so the same address in two letter cases would be treated as
> two subjects. EIP-55 checksums are not verified.

## Versions and known limitations of 0.1

* A bundle must declare `wwepVersion: "0.1"`; any other value is rejected, not coerced. A different
  `registryVersion` or `rulesVersion` is evaluated with the engine's own data and reported with
  `REGISTRY_VERSION_MISMATCH` or `RULES_VERSION_MISMATCH`.
* Evidence is evaluated **as presented**: the engine cannot tell a faithful reading from an invented
  one.
* The registry is verified at a point in time; later contract changes are not observed.
* The engine has **no live providers**: every piece of evidence comes from the caller.
* Five claim types exist, and the authority policies are WalletWall-authored drafts that have not been
  reviewed outside WalletWall.

## Related in the WalletWall application

> [card] [Wallet Evidence Model](https://docs.walletwall.org/architecture/wallet-evidence-model.md)
>
> The application's own provenance layer over provider data: a different schema that shares the rule that unknown is never zero.

> [card] [Independent Authority](https://docs.walletwall.org/architecture/independent-authority.md)
>
> Why agreement is strong evidence only when the agreeing things can fail independently — the same principle behind independence groups here.

> [card] [WallPrint](https://docs.walletwall.org/mcp/wallprint.md)
>
> How an assessment becomes a deliberately published disclosure record.

> [card] [Tools](https://docs.walletwall.org/mcp/tools.md)
>
> The six read-only tools that compute the states defined on this page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.