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

# Canonical schemas

> Field-by-field reference for Question, Verdict, EvidencePolicy, and PelionSynapse.

<Warning>
  Schemas are locked. Additive changes only, under explicit version bumps.
</Warning>

Every message the protocol touches uses one of these Pydantic v2 types. Frozen once constructed. Strict validation. Canonical JSON uses camelCase, Python attributes are snake\_case via `alias_generator=to_camel`.

## `Question`

The off-chain canonical question format. Spec §4.2.

| Field                | Type                    | Notes                                                                                                             |
| -------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `version`            | string, Literal "0.1"   | Schema version. Bumps on any breaking change.                                                                     |
| `questionId`         | 0x-prefixed 32-byte hex | Deterministic identifier, typically `sha256(canonical_params)`. Validated.                                        |
| `requester`          | 0x-prefixed 20-byte hex | Address of the requesting contract or EOA on mainnet. Validated.                                                  |
| `text`               | string                  | Natural-language question text. Human readable.                                                                   |
| `resolutionCriteria` | string                  | Explicit criteria for YES, NO, or UNRESOLVABLE. The rubric miners apply.                                          |
| `resolutionTime`     | int (unix seconds)      | Earliest time at which the question is eligible for resolution.                                                   |
| `expirationTime`     | int (unix seconds)      | After this, the requester may cancel if no verdict has finalized. Must be ≥ resolutionTime.                       |
| `evidencePolicy`     | `EvidencePolicy`        | Rules bounding admissible evidence.                                                                               |
| `subnetRouting`      | list of int             | Bittensor netuids the question is routed to. Order not significant. On-chain this is encoded as a uint256 bitmap. |
| `reward`             | decimal string          | USDC smallest-unit reward. String to avoid JS/JSON bigint precision loss.                                         |
| `bondAmount`         | decimal string          | USDC smallest-unit requester bond. String.                                                                        |
| `submittedAt`        | int (unix seconds)      | When the adapter accepted the submission on-chain.                                                                |

## `EvidencePolicy`

Nested in Question. Bounds what evidence a miner may cite.

| Field                     | Type           | Notes                                                                |
| ------------------------- | -------------- | -------------------------------------------------------------------- |
| `allowedSourceCategories` | list of string | For example, "government\_official", "major\_news\_outlets".         |
| `allowedDomains`          | list of string | Whitelisted domains miners may cite as evidence.                     |
| `maxAgeHours`             | int, ≥ 0       | Maximum age of evidence in hours, measured from resolutionTime.      |
| `minSourceCount`          | int, ≥ 1       | Minimum number of independent sources required to support a verdict. |

## `Verdict`

The canonical verdict format. Spec §4.2.

| Field                 | Type                    | Notes                                                                                           |
| --------------------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
| `version`             | string, Literal "0.1"   | Schema version.                                                                                 |
| `questionId`          | 0x-prefixed 32-byte hex | Matches the originating Question.                                                               |
| `outcome`             | signed int              | See `Outcome` constants below. `UNRESOLVABLE = -1`, `NO = 0`, `YES = 1`, multi-outcome ≥ 2.     |
| `outcomeLabel`        | non-empty string        | Human-readable label. "YES", "NO", "UNRESOLVABLE", or enumerated outcome name.                  |
| `confidence`          | int, 0 to 10000         | Consensus confidence in basis points.                                                           |
| `evidence`            | `Evidence`              | Nested evidence bundle.                                                                         |
| `reasoning`           | `Reasoning`             | Per-miner provenance plus the consensus rationale.                                              |
| `subnetMetadata`      | `SubnetMetadata`        | Bittensor-side metadata (subnet id, block height, validator set).                               |
| `validatorSignatures` | hex string              | Threshold signature or aggregated signatures from subnet validators. Format is subnet-specific. |
| `timestamp`           | int (unix seconds)      | When the verdict bundle was assembled.                                                          |

## `Evidence` and `EvidenceSource`

| Field (on Evidence) | Type                     | Notes                                              |
| ------------------- | ------------------------ | -------------------------------------------------- |
| `sources`           | list of `EvidenceSource` | Evidence sources consulted. Order not significant. |

| Field (on EvidenceSource) | Type                    | Notes                                                                      |
| ------------------------- | ----------------------- | -------------------------------------------------------------------------- |
| `url`                     | string                  | Canonical URL of the source document.                                      |
| `contentHash`             | algorithm-prefixed hash | "sha256:" + hex digest of retrieved content. Validated to have the prefix. |
| `retrievedAt`             | int (unix seconds)      | When the miner fetched the content.                                        |
| `relevantExcerpt`         | string                  | Short excerpt directly supporting the verdict.                             |

## `Reasoning` and `MinerProvenance`

| Field (on Reasoning) | Type                      | Notes                                                         |
| -------------------- | ------------------------- | ------------------------------------------------------------- |
| `minerProvenance`    | list of `MinerProvenance` | Per-miner verdicts and reasoning that fed into the consensus. |
| `consensusRationale` | string                    | Summary of how miner outputs were combined.                   |

| Field (on MinerProvenance) | Type                    | Notes                                                                                                                  |
| -------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `minerHotkey`              | ss58 or sentinel string | Bittensor hotkey, or a sentinel for non-subnet participants (frontier council uses "frontier-council:provider:model"). |
| `individualVerdict`        | signed int              | The miner's individual outcome. May differ from consensus.                                                             |
| `individualConfidence`     | int, 0 to 10000         | Miner-reported confidence in basis points.                                                                             |
| `reasoningText`            | string                  | The miner's natural-language reasoning.                                                                                |

## `SubnetMetadata`

| Field                        | Type       | Notes                                                                          |
| ---------------------------- | ---------- | ------------------------------------------------------------------------------ |
| `subnetId`                   | int, ≥ 0   | Bittensor netuid. Sentinel value `0` for the synthetic frontier-model council. |
| `blockHeight`                | int, ≥ 0   | Subtensor block height at which validator consensus was taken.                 |
| `validatorSetHash`           | hex string | Hash of the validator set active at blockHeight. Enables replayability.        |
| `weightedValidatorConsensus` | string     | Opaque subnet-native representation of the weighted consensus at blockHeight.  |

## `Outcome`

Sentinel integer values for the `outcome` field across Verdict, MinerProvenance, and PelionSynapse. Not an enum (enumerated markets require values outside the closed set).

| Name           | Value | Notes                                                              |
| -------------- | ----- | ------------------------------------------------------------------ |
| `UNRESOLVABLE` | -1    | Genuinely inconclusive council. First-class outcome, not an error. |
| `NO`           | 0     | Binary NO.                                                         |
| `YES`          | 1     | Binary YES.                                                        |
| (enumerated)   | ≥ 2   | Multi-outcome markets use values at or above 2.                    |

## `PelionSynapse`

Bittensor wire envelope. Subclass of `bt.Synapse`. Lives in `pelion.schemas.synapse` and requires the `bittensor` extra.

Inputs (validator populates, miner reads).

| Field                 | Type               |
| --------------------- | ------------------ |
| `question_id`         | string             |
| `text`                | string             |
| `resolution_criteria` | string             |
| `resolution_time`     | int (unix seconds) |
| `evidence_policy`     | `EvidencePolicy`   |
| `deadline`            | int (unix seconds) |

Outputs (miner populates, validator reads).

| Field            | Type                |
| ---------------- | ------------------- |
| `outcome`        | optional int        |
| `outcome_label`  | optional string     |
| `confidence`     | optional int        |
| `evidence`       | optional `Evidence` |
| `reasoning_text` | optional string     |

Input fields are included in the Synapse request hash. Changes to input field names or types are wire-breaking and require coordinated miner, validator, and router updates.

## Post-Task-1 spec amendments

Four ambiguities in the original spec were resolved and documented. They apply to all schema usage.

**`subnet_routing` encoding.** Canonical off-chain JSON uses `list[int]` matching spec §4.2. On-chain, `PelionAdapter.sol`'s `QuestionParams.subnetRouting` is a `uint256` bitmap. Bit `i` is set iff `i` is in `subnet_routing`. Caps at 256 netuids.

**`evidence_hash` and `reasoning_hash`.** The spec's Solidity Verdict struct has these as `bytes32`. The canonical off-chain Verdict does not carry them. Instead, they are computed at the router-to-adapter boundary as `sha256(canonical_json_bytes(evidence))` and `sha256(canonical_json_bytes(reasoning))`. Canonical JSON uses `model_dump_json(by_alias=True)` with compact separators. This matches IPFS CIDv0 convention. The 32-byte digest is exactly the content-identifier portion of `Qm<base58(digest)>`.

**`UNRESOLVABLE` sentinel value.** `-1`. Documented on the `Outcome` class.

**`callback_contract` and `callback_selector`.** Adapter-layer fields only. Not on canonical off-chain Question. The miner, validator, and router never see them.

The authoritative engineering reference lives at `pelion/schemas/README.md` in the repository.