Skip to main content

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.

The specification is v0.1, a working draft. Material changes are versioned and announced.
The canonical technical specification is the authoritative source for every component design, interface, state machine, parameter, and open decision. This page describes where the spec lives, what it covers, and how it relates to the other documentation.

​
Where to find it

The spec lives in the source repository at docs/spec/pelion_technical_spec.md. It is a single markdown file, versioned in git, and is the authoritative source for every downstream artifact (engineering READMEs, this documentation site, whitepapers, any future formal audit). When the spec and this documentation disagree, the spec is correct. This documentation is a distilled external framing and is expected to lag minor spec changes.

​
What each section covers

Executive summary (§1). The thesis in one paragraph. Problem statement, solution approach, and the specific innovations that differentiate Pelion from prior oracle designs. Problem and motivation (§2). UMA’s structural failure modes with the July 2025 Zelensky case study. Quantitative argument for why token-weighted voting cannot be patched. System architecture (§3). The five-layer stack. Mental model, data flow, and trust boundaries. Core components (§4). The bulk of the document. Each component has its own section with interface sketches, state machines, edge cases, and the specific parameters that require governance decision.
  • §4.1 Base Adapter Contracts
  • §4.2 Question and Verdict Schemas (canonical off-chain formats)
  • §4.3 Router Services
  • §4.4 Bittensor Integration Layer (the scoring rubric is here, and it is the core IP)
  • §4.5 Cross-Chain Relay (v1 bonded federated, v2 light-client roadmap)
  • §4.6 Treasury System
  • §4.7 Token Contract
Economic security model (§5). Quantitative attack cost analysis. Single-subnet and multi-subnet defense math. Comparison to UMA. Dataset and transparency layer (§6). IPFS and Arweave archival design. What gets published, what gets embargoed, why the dataset matters as a moat. Governance (§7). Three-tier design. Quadratic voting. Escalation council. Progressive decentralization milestones. Build plan (§8). Phase 0 through Phase 4 with deliverables and rough timelines. Technology choices (§9). The specific stack (Solidity 0.8.24, Python 3.11+, FastAPI, Postgres, etc.) with rationale. Open questions (§10). Decisions the spec flags as needing resolution during early build. These are load-bearing, and any investor-level read of the spec should include §10. Immediate build priorities (§11). The priority-ordered task list an implementing engineer would follow.

​
How to read it

First pass. §1, §2, §3. 15 minutes. Covers the thesis, the problem, and the mental model. Technical deep-read. §4 and §5. One to two hours. This is the full system design. Token-focused read. §4.6 (treasury), §4.7 (token), §7 (governance). 30 minutes. Build-focused read. §8 (phases), §11 (priorities), §10 (open questions). 20 minutes.

​
Relationship to this documentation

The documentation here is a distilled version organized for investor reading. It covers the narrative arc, not the exhaustive interface specifications. Specific mappings.
This doc pageSpec section
UMA’s structural failures§2
Why now§2
Architecture§3
Question lifecycle§4.1
Economic security§5
UNRESOLVABLE and calibration§4.4 (scoring), §4.2 (schema)
Token mechanics§4.7
Treasury§4.6
Governance§7
Canonical schemas§4.2
Repository and modules§8 (build status)
Benchmark methodology§11 (Priority 1)

​
Versioning

The spec is currently at v0.1. It is a working draft, and material changes happen as ambiguities surface during implementation. When a change is made. A new version is tagged. The changelog (in the spec file itself) describes what changed and why. Dependent engineering artifacts (schemas, READMEs, this site) are updated to match. The spec is not a static document. It is a living reference that gets refined as the protocol gets built. The commitment is that every version is internally consistent and has been through review before being published.

​
Why a monolithic spec

Some protocols split their documentation across many smaller documents. Pelion’s choice is a single monolithic spec plus distilled external documentation. The rationale. Monolithic specs are easier to keep internally consistent. A single file prevents accidental contradictions between, say, the schema spec and the adapter interface spec. Engineers implementing the protocol need one source of truth. Having to cross-reference seven different design documents to implement a single component is how inconsistencies get introduced. Investors and auditors evaluating the protocol benefit from a single comprehensive reference. It makes “read the spec” a concrete and complete instruction, not a scavenger hunt. The cost is that the single file is long. This is handled by aggressive sectioning, a table of contents, and the distilled external docs (this site) for readers who don’t need the full depth.