Documentation

Pelion is a decentralized adjudication protocol for onchain contracts. This documentation covers the Python core — canonical schemas, the frontier-model judgment council, and runnable Bittensor miner and validator services.

Overview

Pelion routes contract questions — prediction-market resolutions, insurance claims, DAO disputes — to a council of frontier AI models on Bittensor subnets, aggregates their verdicts with evidence and reasoning, and returns a signed result that any contract on Base can consume.

Evidence-first — every verdict includes citations, reasoning, and a permanent evidence trail on IPFS/Arweave.
Economic security — Bittensor's TAO staking backs every verdict.
Honest abstention — UNRESOLVABLE is a first-class outcome.

Installation

Requires Python 3.11 or newer.

# Clone and install
git clone https://github.com/pelionprotocol/pelion-protocol
cd pelion-protocol
pip install -e ".[dev]"

# Optional extras
pip install -e ".[bittensor]"           # Bittensor SDK
pip install -e ".[frontier]"            # Anthropic, OpenAI, Google
pip install -e ".[bittensor,frontier,dev]"  # everything

# Run tests
pytest

Quick Start

Build a question and resolve it with the frontier council — no Bittensor required.

from pelion.schemas import Question, EvidencePolicy
from pelion.judgment import FrontierModelClient
from pelion.judgment.providers import AnthropicProvider, OpenAIProvider, GeminiProvider
import asyncio

q = Question(
    version="0.1",
    question_id="0x" + "a" * 64,
    requester="0x" + "b" * 40,
    text="Did SpaceX launch Starship on 2026-04-01?",
    resolution_criteria="YES iff a Starship reached orbit on the stated date.",
    resolution_time=1743465600,
    expiration_time=1743552000,
    evidence_policy=EvidencePolicy(
        allowed_source_categories=["news"],
        allowed_domains=["nasa.gov", "spacex.com"],
        max_age_hours=72,
        min_source_count=2,
    ),
    subnet_routing=[6, 28],
    reward="1000000",
    bond_amount="500000",
    submitted_at=1743379200,
)

async def main():
    client = FrontierModelClient(
        providers=[AnthropicProvider(), OpenAIProvider(), GeminiProvider()],
        min_responses=2,
        per_provider_timeout_s=60.0,
    )
    verdict = await client.judge(q)
    print(verdict.outcome_label, verdict.confidence)

asyncio.run(main())

Set ANTHROPIC_API_KEY, OPENAI_API_KEY, and GOOGLE_API_KEY before running.

pelion.schemas

Canonical types for the Pelion protocol. Pydantic v2, frozen, camelCase wire format.

Type	Description
Question	Question submitted for adjudication. Includes evidence policy, subnet routing, bond, and reward.
Verdict	Resolved outcome. Includes outcome_label, confidence, evidence citations, and reasoning.
PelionSynapse	Wire type exchanged between miners and validators on Bittensor subnets.
EvidencePolicy	Constraints on acceptable evidence sources for a given question.

pelion.judgment

Frontier model council. Fans a question to Anthropic, OpenAI, and Google in parallel and aggregates into a single Verdict.

Parameter	Type	Default	Description
providers	list[Provider]	—	Model providers to fan out to
min_responses	int	2	Minimum responses before aggregating
per_provider_timeout_s	float	60.0	Per-provider timeout in seconds

pelion.miner

Runnable Bittensor miner. Wraps FrontierModelClient behind a bt.Axon.

# Install and register
pip install -e ".[bittensor,frontier]"

btcli wallet new_coldkey --wallet.name pelion
btcli wallet new_hotkey --wallet.name pelion --wallet.hotkey miner-01
btcli subnet register --wallet.name pelion --wallet.hotkey miner-01 \
  --netuid <NETUID> --subtensor.network test

# Start miner
export ANTHROPIC_API_KEY=...
export OPENAI_API_KEY=...
export GOOGLE_API_KEY=...

pelion-miner --config miner.yaml

pelion.validator

Runnable Bittensor validator. Queries miners with a backtest set, scores responses, and sets TAO weights.

pelion-validator --config validator.yaml

Scoring weights

Outcome accuracy — 60%
Evidence quality — 25%
Reasoning coherence — 15%

Architecture

Layer	Runtime	Role
Application	Base (Solidity)	Prediction markets, insurance, DAOs.
Adapter	Base (Solidity)	Accept questions, escrow bonds, fire payout callbacks.
Router	Python (off-chain)	Translate questions to subnet queries, aggregate, pin evidence.
Judgment	Bittensor subnets	Miners produce verdicts, validators score, TAO-backed security.
Relay	Bonded cross-chain	Carry verdicts back to Base with challenge windows.

Outcomes

YES — event occurred per resolution criteria
NO — event did not occur
UNRESOLVABLE — insufficient evidence to settle the question

UNRESOLVABLE is a first-class outcome. Contracts must explicitly handle this case in their payout logic.

Evidence Policy

Field	Type	Description
allowed_source_categories	list[str]	news, official, academic, blockchain
allowed_domains	list[str]	Exact source domain allowlist
max_age_hours	int	Sources older than this are rejected
min_source_count	int	Minimum independent sources required

Examples

Prediction market

q = Question(
    text="Was ETH/USD closing price on Coinbase > 5000 on 2026-06-01?",
    resolution_criteria="YES iff the 00:00 UTC Coinbase close exceeded 5000 USDC.",
    evidence_policy=EvidencePolicy(
        allowed_domains=["coinbase.com", "coingecko.com"],
        max_age_hours=24, min_source_count=2,
    ),
    ...
)

Insurance claim

q = Question(
    text="Did flight UA123 on 2026-05-15 arrive more than 3 hours late?",
    resolution_criteria="YES iff actual arrival was >180 minutes after scheduled.",
    evidence_policy=EvidencePolicy(
        allowed_domains=["flightaware.com", "united.com"],
        max_age_hours=72, min_source_count=1,
    ),
    ...
)

← Home Whitepaper →