Payload Contract

A Depth payload is intended to be read as a structured evidence artifact, not as a score or recommendation. The contract surface exists so consumers can reliably answer:

• what facts are present
• what policy outcomes are present
• what was not computed
• what remains unknown

Consumers should treat the payload as:

• deterministic under declared versions
• explicit about uncertainty
• strict about object boundaries
• conservative about unsupported or unmodeled sections

Consumers should not treat the payload as:

• a trading recommendation
• a scalar risk score
• a guarantee of execution outcomes
• a claim of exhaustive pool discovery

Each pool payload is partitioned into four primary objects.

The most important payload invariant is the separation between evidence, policy, structure, and computation. Consumers should rely on the following:

• structural issues do not appear as coverage notes
• coverage notes do not act as policy reasons
• policy ineligibility reasons do not stand in for computation disclosure
• computation reasons do not redefine structural support

If these lines blur, the payload becomes harder to reason about. The contract explicitly rejects that blurring.

At a high level, each pool record may expose:

• pool address
• normalized pool type
• paired token information
• liquidity control mechanisms
• execution structure where supported

Current normalized pool types: v2, v3, aerodrome_volatile, aerodrome_concentrated, aerodrome_stable, unknown.

Consumers should not collapse execution eligibility and computation state into one concept.

A pool may be:

• execution-eligible — but still have one or more sections marked not_modeled
• observed — but execution-ineligible

This is intentional and part of the contract.

Coverage is epistemic. It describes what was observed. It does not make a recommendation.

Consumers should interpret coverage as:

• evidence availability
• evidence bounds
• evidence freshness posture

They should not interpret coverage alone as approval for execution-sensitive use.

TVL is present when Depth could compute it under the current valuation policy.

Consumers should treat:

• present TVL as computed under the declared methodology
• absent TVL as intentionally unavailable, not silently zero
• hop-derived TVL as a disclosed fallback posture that does not upgrade execution eligibility under the current policy

This is a critical contract rule.

Consumers should interpret:

• null — unknown, unavailable, not computed, or not applicable
• 0 — computed and equal to zero, only when that is actually true

A missing computation must not be mistaken for a zero-value computation.

Reason fields and note fields are part of the contract surface.

Consumers should:

• rely on documented public reason categories
• treat unknown future categories as non-fatal unless otherwise documented
• avoid collapsing categories across the four objects

Depth payloads are best-effort with respect to pool inclusion in beta.

Consumers should not assume:

• exhaustive market coverage
• every long-tail pool is present
• absence from a payload equals non-existence onchain

The pool set should be interpreted as the tracked candidate set for that snapshot under the current discovery posture.

Consumers should read payloads together with their declared versions.

At minimum:

• spec_version defines the payload contract boundary
• execution_policy.policy_version defines the eligibility semantics boundary

If one of those versions changes, consumers should assume semantics may have changed and review the relevant contract document.