What is Pyde

What Pyde is, what it removes, and how it operates — so the spec chapters land on intuition, not acronyms.

Pyde, in one paragraph

Pyde is a Layer 1 blockchain network. Post-quantum from day one, MEV-resistant by construction, and cross-chain by certificate. It removes the two trust problems crypto-native businesses cannot solve today — front-running that taxes users 1–5% per trade, and bridges that have lost over $3 billion since 2021 — both fixed at the protocol level, not by policy. It is the chain you build on when execution has to be fair, finality has to mean final, and verification has to outlive the cryptography it was built with.

What Pyde removes

Two structural taxes vanish at the protocol layer:

Front-running. Transactions are encrypted in the mempool until after the network commits to their order. No validator, sequencer, or searcher can read a transaction before its place in line is locked. Sandwich attacks, JIT liquidity, and proposer extraction are not auctioned or mitigated — they are structurally impossible. Users keep the price they signed.

Bridge custody risk. Any chain — Ethereum, Solana, a parachain, an L1 not built yet — can verify a Pyde transaction directly using its FALCON-signed finality certificate. No multisig, no custodian, no third party to trust. Value crossing chains never sits in a contract someone else controls.

What makes Pyde different

Three properties ship as defaults at genesis. No production chain combines them today.

Post-quantum cryptography. FALCON-512 signatures, Kyber-768 (ML-KEM) threshold encryption, Poseidon2 + Blake3 hybrid hashing. No pre-quantum primitive on any consensus or account path. The network still settles after a working quantum computer breaks what today's chains run on.

Structural MEV resistance. Threshold-encrypted mempool with commit-before-reveal ordering. Fairness is not enforced by policy or auctioned to the highest bidder — it is a property of the protocol.

Portable cross-chain certificate. A Pyde finality certificate verifies anywhere it lands. Cross-chain interop is cryptography, not a multisig.

Other chains can add any one of these. None can add all three without a hard fork that breaks every deployed app. Pyde ships them as one architecture, day one.

What's in the name

Pyde (pronounced pied, rhymes with tide). The name carries two senses at once, and both are intentional.

The older sense is tide. A tide is an inescapable, continuous current — it does not ask permission, it does not stop for the night, it does not wait for any single drop to arrive before moving the next. Pyde the network was designed to feel like that. The throughput of a blockchain is rarely about how fast one transaction can land; it is about whether the assembly line ever empties. Pyde's assembly line does not empty. The protocol commits in waves — not poetic waves, literal ones, the way water commits to shore — and the rest state of the system is motion. The factory metaphor that runs through this book is the tide made mechanical.

The surface sense is pied — a casual, phonetic spelling. The name was picked to sit quietly: short, easy to say, easy to type in a hurry, distinctive enough to search for. pyde.network, @pydenet, t.me/pydenet — the rhythm matters when you will type it ten thousand times. It was picked knowing it would mostly be written lowercase, in DMs, by people whose hands are tired.

There is no third sense. No hidden Greek letter, no acronym backing it out, no "Programmable Yield Decentralization Engine" trying to sneak in through the back door. The name is just the name.

The mark

The mark is based on atomic structure — a nucleus and its orbital.

The vertical form is the core. Dense, gravitational, everything pulls toward it. Pyde's architecture is monolithic: consensus and execution unified in one gravitational center.

The circle to its right is in orbit. Independent, in motion, but bound to the core by an invisible force. External chains, bridges, and light clients orbit Pyde freely — verified, not trusted.

The two are separate on purpose. Related but sovereign. The same way a Pyde finality certificate can prove itself anywhere without depending on the chain it came from.

The core is wide at the poles and compressed at the center. Finality under pressure. Stress-tested and held.

No sharp edges. No network imagery. Nothing decorative. The mark looks like a physical law, not a trend.

Grayscale only. Works as a favicon, on a sticker, in metal, as a watermark. Full brand rules live in the Brand Reference.

The mark is the architecture

The atomic reading is not visual flavour. It is the design.

Pyde is the core. Consensus and execution live in one system. State lives where transactions are ordered. The DAG, the JMT, the wasmtime executor — one process, one gravitational well. Most modern chains split these into layers. Pyde does not.

Verification is the binding force. Nothing orbiting the core is trusted. Light clients, bridges, foreign chains, wallets running local previews — they all bind through cryptographic proof. FALCON-signed finality certificates, JMT inclusion proofs, threshold decryption shares. The orbits are mathematical, not political.

Things orbit without merging. A Pyde finality certificate can travel to Ethereum and prove itself there without phoning home. A parachain has its own sub-orbit inside Pyde's well — its own validators, its own state subtree — and stays sovereign. Sovereignty without isolation.

Compression is BFT under pressure. Wave commits run under adversarial conditions. The 85-of-128 quorum, the slashing schedule, the structural MEV resistance — they exist so the core holds when squeezed. Stress-tested.

One core. Many orbits. Bound by physics, not by trust.

How Pyde operates

Most blockchain explanations start with cryptography and end with consensus, leaving the reader holding a bag of acronyms. We are going to do this differently.

Pyde is a factory. Goods (transactions) arrive at the loading dock from outside. They are sorted, lifted onto a continuously-moving assembly line, and arranged by a series of robotic arms working in parallel. Every few hundred milliseconds, the great press slams down and locks a batch as final — the slam you feel when the factory floor shakes is a wave commit. After the slam, the audit ledger is stamped, exhaust rises from the chimney (eviction, pruning), a receipt is sent out the front door, and the line keeps moving without ever stopping.

The continuous rotation is the throughput. Pyde is not a fast database; it is a deep pipeline.

The Pyde cycle, ~2-3 times a second on commodity hardware. Each pass is one wave commit.

The eleven stages

The full cycle, end-to-end, from a user's keypress to a receipt landing back in their wallet, is eleven stages. Five are happening to your transaction. The other six are happening to other people's transactions concurrently, on the same factory floor, because the line never stops.

Stage 0 — Workshop floor (the user)

A user opens a wallet and asks it to send 100 PYDE to alice.pyde. The wallet quietly does five things before showing a "Sign" button: it resolves the recipient name via JSON-RPC, fetches the sender's account state, fetches any relevant contract bytecode, runs the transaction locally inside a wasmtime sandbox embedded in the wallet itself (Tier 1 client-side preview, see Chapter 17 §17.4b), and shows the user a preview: "This tx will send 100 PYDE, cost ~21,000 gas, leave your balance at 900 PYDE." Only then does the user sign with their FALCON-512 key, and only then does the tx leave their machine.

If the user opted for confidentiality, the wallet also encrypts the payload with the current epoch's threshold pubkey before signing — the recipient and amount become opaque ciphertext that no validator can read until the wave commits.

Stage 1 — Loading dock (RPC ingress)

The transaction lands at any RPC node. RPC nodes are stateless ingress: they hold no validator key, sign nothing, and have no consensus role. They parse the JSON, do a shape check, rate-limit, return the tx hash to the wallet synchronously, and then shovel the transaction into the libp2p Gossipsub mempool topic. From the wallet's perspective the trip is done. In reality it has just begun.

Stage 2 — Sorting room (mempool)

Every node — and especially every committee validator — runs a validation pipeline on each incoming tx: signature verify (FALCON-512, batchable), nonce window check (the tx's nonce must be within sixteen of the sender's last committed nonce), balance sufficiency, gas-limit cap, attribute coherence. Passes go into the local mempool DashMap, organised by gas-price descending. Failures are dropped and the gossip score of the peer that sent it is docked. Encrypted transactions land here too: the envelope is validated, but the payload stays sealed until threshold decryption fires at commit.

Stage 3 — Assembly-line dispatch (batches and vertices)

Inside each of the 128 committee members for this epoch, two things happen continuously. First, every hundred milliseconds or so, the member packs the highest-fee transactions into a Batch (~50-200 txs, ~4 MB cap) and broadcasts it on the /pyde/batches/1.0.0 topic. Second, every round (~150-500 ms, structurally paced — see below), the member emits a Vertex that references ≥85 parent vertices from the previous round, references whichever batches it wants to include, carries piggybacked decryption shares for any encrypted transactions in the subdag, contributes a VRF beacon share, attests to the previous anchor, and is signed by the member's epoch key. Vertices broadcast on /pyde/dag/1.0.0 and form the next floor of the DAG.

The round advances when the member has seen ≥85 vertices from the current round, not when its own timer fires. This is the structural-pacing trick that makes Mysticeti elegant: the floor speed is the median peer speed, not the slowest peer's speed. A single laggard cannot stall the line.

Stage 4 — The foreman picks the lead (anchor selection)

Every K rounds (typically K=3), an anchor is picked, deterministically and verifiably, by all 128 members simultaneously:

anchor_validator_id = VRF(beacon_combined, round, prev_state_root) mod 128

The beacon is the XOR of the prior round's VRF shares (public randomness). The previous state root locks anchor selection to canonical history, so an adversary who reorders the DAG cannot retroactively choose a more favourable anchor. Mod 128 picks which member's vertex at this round wears the crown. Every honest member computes the same answer.

Stage 5 — The press slams (wave commit) 💥

Once the anchor has accumulated ≥85 attestations from later-round vertices (other members' vertices that reach the anchor transitively through parent links), the commit threshold trips. The press comes down.

What the slam does, in three lines:

1. BFS subdag walk — starting at the anchor, walk every parent reference recursively. The set of touched vertices is the subdag being committed.
2. Canonical sort — order the subdag by (round, author_id, batch_list_order). Every honest member produces the same order.
3. Dedupe + flatten — same transaction may appear in multiple batches across multiple members; keep the first appearance. The result is the wave's ordered_list, a fully deterministic transaction sequence.

That sequence is what gets executed. Before the slam the DAG is ambiguous; after the slam it is fixed. See Chapter 6 §5b–5c for round-vs-wave terminology, missing-vertex handling, and the 5-skip recovery walkthrough.

Stage 6 — Unboxing the sealed crates (threshold decryption)

Encrypted transactions in the ordered list were opaque until now. Each was sealed with a one-time symmetric key encrypted under the epoch's threshold pubkey. Every vertex committed in the wave piggybacked a decryption share for each encrypted tx in the committable subdag. By commit time, ≥85 shares per encrypted tx are already in hand.

For each encrypted transaction: Lagrange interpolation across the shares recovers the decryption key, the payload is decrypted in-memory, and the now-revealed transaction is re-validated (nonce, balance) one final time before execution. If the decrypted transaction is invalid, it is dropped — but the sender still pays a small gas bond from their plaintext balance (anti-spam). The order-then-decrypt design is what gives Pyde its MEV protection: validators cannot front-run, sandwich, or censor based on transaction content, because they could not read it when they ordered it.

Stage 7 — Robotic arms picking and ordering (execution)

The wave's ordered_list enters the Block-STM scheduler. First, the scheduler walks every tx's declared access list and unions every (addr, slot) pair into a single prefetch set, then issues one batched state_cf.multi_get (PIP-3) to warm the dashmap (PIP-4) before any worker starts — the access list is a prefetch hint only, never used to partition the wave or affect correctness. Then every tx runs optimistically in parallel on a rayon pool, reading + writing through a multi-version concurrency control (MVCC) layer addressed by (tx_index, attempt). The validate pass checks every read against the canonical tx_index order; reads that have since been invalidated by a lower-tx_index write abort the tx, drop its writes, and re-incarnate it at attempt+1. The cycle repeats until every tx is validated — fixpoint — then the highest-tx_index's last write per slot is flushed to the JMT. Aptos's measured production numbers (10-30K real-world TPS) anchor Pyde's v1 throughput target.

For each transaction, the dispatch looks at the type. Native transactions (Transfer, ValidatorRegister, Stake, Unstake) skip wasmtime entirely — direct calls into native handlers, ~21K gas, no WASM cost. Contract calls and contract deploys enter the wasmtime path: load (or fetch and Cranelift-compile) the contract module from state, instantiate it with a 64 MB linear-memory cap and gas_limit of fuel, invoke the entrypoint, run host functions (sload, sstore, sdelete, log, cross_call) through a per-transaction overlay that snapshots reads and isolates writes. Success merges the overlay into the wave overlay; trap discards it; either way the gas actually consumed is deducted (no refunds in v1, see Chapter 10 §10.1). Cross-contract calls nest overlays recursively so a failed sub-call rolls back cleanly without touching the caller's state.

Stage 8 — Inventory audit (state root computation)

After execution, the wave overlay holds every write and every emitted event. Now the audit stamp goes on. Each (slot_hash, value) write lands in two places: the state_cf flat table (live state, O(1) reads later) and the jmt_cf versioned tree (proofs and state root). JMT internal nodes touched by this wave are recomputed with dual hashes — Blake3 for fast native verification, Poseidon2 for future ZK light clients (see Chapter 4 §4.1b). Events land in three more column families — events_cf (primary, ordered by wave) plus events_by_topic_cf and events_by_contract_cf (indexes for fast filtering) — and the wave commit record carries an events_root (Blake3 Merkle tree over canonical-ordered events) plus a 256-byte events_bloom so light clients can verify event inclusion identically to how they verify state. The new state root, the events root + bloom, the wave commit record, the receipts, and the tx-to-wave mapping all land in a single atomic RocksDB WriteBatch. Either the entire wave commits or none of it does. There is no such thing as a half-committed wave.

Stage 9 — Exhaust from the chimney (eviction and pruning) 💨

The DashMap write-back cache layer holds writes from recent waves in memory; reads against hot accounts are near-free here. On every wave boundary, the cache is flushed and LRU eviction trims it back under its size cap. Hot accounts (token contracts, popular pools) stay resident; cold accounts get evicted and next access pays one disk read against state_cf. Pruning policy varies by node tier: archive nodes keep everything; full nodes drop state-tree versions older than ninety days; committee validators keep thirty days. The mempool drops every transaction that just committed and every transaction whose nonce window has now closed.

The plume rising from the chimney is the eviction. The exhaust trailing it is the pruning. The factory shrinks back to a clean working volume ready for the next round.

Stage 10 — Receipt out the front door (back to the user)

The wallet has been holding a WebSocket subscription on the transaction hash since Stage 1. The moment Stage 8's WriteBatch lands, the RPC layer pushes:

{
  "tx_hash": "0x...",
  "status": "success",
  "wave_id": 1234567,
  "gas_used": 21000,
  "events": [{ "topic": "Transfer", "to": "0xabc...", "amount": "100" }],
  "state_root": "0x..."
}

The wallet updates the user's view: "Transferred 100 PYDE to alice.pyde. Confirmed." For light clients (mobile wallets, browser dApps), the same wave commits as a 200-byte header signed by the committee threshold — the light client verifies the threshold signature against the committee pubkeys it already trusts and has now verified the entire wave's integrity without downloading a single transaction. See Chapter 17 §17.3 for the SDK surface and Companion: State Sync for the light-client model.

Stage 11 — The eternal rotation 🔁

Everything you have just read is happening in parallel for different waves. While Stage 7's arms execute wave 1,234,567, round R+1 has already advanced, decryption shares for round R+5's encrypted transactions are piggybacking through the gossip layer, the next anchor is already known by VRF, the mempool is already sorting transactions that will land in wave 1,234,568, and somebody's wallet on the other side of the world is running a Tier-1 preview for a transaction that does not yet exist. The pipeline is deep. The conveyor belts overlap. The press slams roughly twice a second.

The continuous rotation is the throughput. No single transaction is faster than on a slower chain — but the assembly line never empties.

What the metaphor catches that the spec sometimes loses

• Pipelining is everything. Stages 1–11 run concurrently for different waves. No stage waits for another stage to finish.
• The slam is real. Wave commit is a discrete moment that locks order. Before the slam the DAG is ambiguous; after the slam it is canonical.
• Exhaust is not waste — it is necessary. Eviction and pruning are first-class. Without them the factory clogs on its own inventory.
• The user only sees the loading dock and the receipt window. Everything in between is hidden machinery. The wallet's job is to make the slam feel like an instant click.

Where to read next

If you want the detailed mechanics of any stage:

• Stages 1–2 (ingress, mempool): Chapter 12 — Networking
• Stages 3–5 (DAG, anchor, commit): Chapter 6 — Consensus
• Stage 6 (threshold decryption): Chapter 6 §11 and Chapter 9 — MEV Protection
• Stage 7 (execution, Block-STM, per-tx overlay): Chapter 3 — Execution Layer
• Stage 8 (state model, JMT, dual hash): Chapter 4 — State Model
• Stage 9 (eviction, pruning): Chapter 4 §4.1b and Companion: State Sync
• Stage 10 (wallets, SDKs, RPC): Chapter 17 — Developer Tools

And if you want the deep historical narrative on how Pyde arrived at this design: The Pivot.

Why Pyde

Pyde is the chain you'd build if you started today — with the post-quantum cryptography NIST standardized in 2024, the Mysticeti consensus Mysten Labs proved in production in 2024, and the WebAssembly runtime Fastly and Microsoft ship at scale. Nothing here is exotic. The combination is.

Most production chains had to pick which properties to ship first and migrate the rest later. Pyde was built greenfield to ship all of them at once — which is why this page is organized by the people who'll feel the difference, not by the layers of the stack.

• For businesses — settlement that holds through the next cryptographic generation, no invisible tax on customer trades, predictable fees, verifiable receipts.
• For developers — familiar tools, real extensibility (build your own parachain), honest performance numbers, production-grade runtime.
• For users — no sandwich attacks, sub-second confirmations, see-what-you-sign wallets, quantum-proof funds.

If you want the technical depth behind any of the claims below, the chapters that follow are where the protocol-level evidence lives. The Whitepaper is the single-document reference; the chapters break it apart at the granularity of a working engineer.

For businesses

The properties production needs, defaulted from day one — not retrofitted to a chain holding live value.

Quantum-proof from genesis. Every other production Layer 1 — Bitcoin, Ethereum, Solana, Cardano, Sui, Aptos — secures account paths with classical cryptography that breaks the day a cryptographically-relevant quantum computer exists. NIST standardized the post-quantum replacements in 2024, but retrofitting them into a chain holding trillions in value is a multi-year coordination problem none have solved. Pyde uses FALCON-512 signatures, Kyber-768 encryption, and Poseidon2 hashing from block zero. Long-tail contracts — insurance policies, multi-year escrows, intellectual-property registries, legal records — remain cryptographically valid into the quantum era, with no migration to budget for.

MEV protection at the protocol layer, not via a trusted relayer. Other chains' answer to MEV is a third-party relayer — Flashbots on Ethereum, Jito on Solana — a service businesses must opt into and trust to behave. On Pyde, MEV-sensitive transactions are encrypted under a threshold key held jointly by 128 validators. The committee commits to a canonical order before any decryption share is released. The information asymmetry MEV needs to exist on simply doesn't. Your users keep what they paid; you don't owe anyone a trust assumption you can't independently verify.

Settlement in ~500 milliseconds. Mysticeti-style consensus reaches finality at roughly half a second median. Your customer's payment confirms before their hand leaves the mouse. On Ethereum that's 12 seconds — long enough for users to refresh, retry, or abandon. Checkout abandonment drops. Cash flow accelerates. Customer-support tickets stop being about "I paid but it didn't go through."

Predictable fees under load. EIP-1559 base fee. No tips. No MEV race driving gas competition during popular drops. When an NFT mints on Ethereum, gas can 10x in 30 seconds and your unit economics break. Pyde's structural absence of MEV competition combined with the no-tip fee model keeps cost predictable. You can quote your operations team a number that's true tomorrow.

Cryptographic receipts your auditors can verify offline. Every committed transaction comes with a HardFinalityCert — a FALCON quorum certificate signed by 85 of 128 independent validators. Your compliance team doesn't trust the chain; they verify the math. The certificate is portable: any external system that can verify FALCON signatures can verify a Pyde commitment, on or off chain.

Run your own validator on a normal machine. Most high-throughput chains have made validation a premium-hosting business — Solana production validators run on 12+ cores and 256+ GB RAM, costing $20K+/month. A Pyde committee validator runs on 8 cores, 16 GB RAM, and a 500 Mbps – 1 Gbps connection. Your enterprise can verify Pyde independently without an infrastructure budget that defeats the purpose of running your own node.

For developers

Familiar tools. Honest performance. Real extensibility.

Write in any language that compiles to WebAssembly. Rust, AssemblyScript, Go (TinyGo), C, C++, Zig — anything that targets wasm32. No Solidity to learn. No Move. No Cairo. No proprietary VM to internalize. Your team uses the stack they already know. The otigen developer toolchain handles scaffolding, build, ABI generation, and deployment regardless of source language.

Build your own parachain — a chain inside the chain. This is what no other production Layer 1 offers without auctioned slots or central gatekeeping. Pyde's parachain framework lets you author a WASM module that runs as its own execution environment with its own state, validated by Pyde's committee. Want to ship a privacy-first application chain? A custom VM optimized for your domain? A confidential-vote chain? An oracle network? A gaming-specific subchain with its own throughput profile? Build a parachain. Pyde validators stake PYDE to run yours; they earn the fees you set. Your parachain inherits Pyde's HardFinalityCert, cross-parachain messaging, security model, and threshold-encryption infrastructure for free.

This is how dev communities get built around real innovation — you bring the logic, Pyde brings the substrate. No auction. No bidding war. No "we'll consider your team in the next batch."

Cross-parachain composability through one cryptographic primitive. Pyde's HardFinalityCert is portable. Any chain that can verify FALCON signatures can verify a Pyde commit. Your parachain talks to other parachains, to Pyde's main chain, and (post-mainnet) to external chains through a single signed certificate. No bridge multisig to trust. No oracle latency to budget for. No fragile relayer in the middle.

Hybrid parallel execution. Pyde's execution layer is a uniform Block-STM scheduler: every transaction runs optimistically in parallel through an MVCC layer, conflicts are caught at validation, and losers re-execute. Wallets can attach an access list per tx as an optional prefetch hint — the chain warms its cache (PIP-3 multiget) before workers start. The hybrid Solana-+-Aptos framing was the older intermediate proposal; v1 ships uniform Block-STM with access lists as a prefetch optimisation only.

Performance numbers you can defend in production. The v1 mainnet throughput target is established by a multi-region harness with real network latency before any number is published. We publish only what the harness measures under sustained, production-realistic conditions — never lab extrapolations or microbenchmark peaks. If we promise it, you can build on it.

Runtime that already powers production at scale. wasmtime + Cranelift AOT — the same WebAssembly runtime Fastly serves edge functions on, Microsoft ships in Hyperlight, Shopify uses for app extensions, and the Bytecode Alliance maintains with 50+ corporate contributors. Not a homegrown VM with a 1.0 release ahead of it.

Native session keys and programmable accounts are planned. v1 ships native multisig (up to 16 signers). v2 ships scoped session keys and programmable accounts at the protocol layer — not retrofitted like Ethereum's ERC-4337. Your dApp gets bounded, revocable delegation as a first-class primitive: gaming sessions, AI-agent delegation, recurring payments, all without a wallet popup per action. v1 reserves the protocol surface so contracts written today survive the v2 upgrade unchanged.

16 concurrent transactions per account. Most chains lock you to one in-flight transaction per account. If one stalls, your queue stalls. Pyde maintains a 16-slot nonce window — submit up to 16 transactions concurrently per account, out of order within the window. Wallet UX, exchange settlement, and high-frequency dApps all benefit.

For users

Your transactions. Your funds. Kept yours.

No more sandwich attacks. On most chains, bots watch the mempool and trade against your transaction — buying before your swap to push the price, selling after for profit. You lose 1-5% of trade value to actors you don't know exist. Pyde encrypts your transaction's content under a threshold key held jointly by 128 validators. The order is committed before any decryption share is released. The information asymmetry MEV needs cannot structurally exist. You keep the price you signed.

Confirmations in half a second. ~500ms to finality at the median. Your wallet shows the result immediately. No "12 seconds and counting" spinner. No refresh-and-pray.

Predictable fees. Your $5 swap costs $5 in fees. Not $5 plus $80 of MEV extraction. Not $50 because someone launched an NFT mint at the same moment.

See exactly what you're signing — before you sign. Pyde wallets run your transaction locally first (deterministic wasmtime simulation) and show every state change — balances moved, contracts called, events emitted — before asking for your signature. No "approve this transaction" leap of faith. No surprise approval draining your wallet a week later.

Quantum-proof funds. Your funds stay yours even when quantum hardware can break the cryptography securing Bitcoin and Ethereum. Built in from genesis, not a retrofit you have to wait for.

Cross-chain by certificate, not by trusted bridge. Custodial bridge multisigs have lost over $3B since 2021. Pyde's cross-chain finality is verified cryptographically by 85+ validator signatures — math your wallet checks, not a multisig you have to trust.

Where to go from here

• Read the Whitepaper for the single-document technical reference (downloadable PDF at pyde.network/whitepaper.pdf).
• Read How Pyde Works for the high-level visual explainer.
• Start at Chapter 1 — Introduction for the technical entry point into the chapters.
• Browse the Companion specs for the depth-first treatment of each subsystem.

Get Started

Pick the path that fits you.

I want to build on Pyde →

You're a developer or technical founder. You want to write a contract, spin up a local devnet, deploy something, integrate with the chain. Start here for the toolchain, the host-function ABI, language-specific examples, and the local-devnet flow.

I want to use Pyde →

You're an end user. You want to hold PYDE, send transactions, run a node, or follow the project's mainnet path. Start here for the wallet story, post-quantum guarantees in plain English, what makes Pyde different from other L1s, and what's available pre-mainnet vs post-mainnet.

Not sure which path? If you're going to type cargo build at any point, take the developer track. If you only ever interact with Pyde through a wallet or a dApp, the user track is where you belong.

Both paths converge at the same set of canonical specs in the book — chapters 1–20 and the companion files — when you need to go deep on a specific topic.

Get Started — for Developers

You're here because you want to build something on Pyde. This page is the on-ramp: enough orientation to land you on the right specs, without reproducing them.

What you can build

Pyde supports two contract surfaces:

1. Smart contracts — sandboxed WASM modules deployed to the chain. Standard L1 contract development; read Chapter 3 — Execution Layer for the runtime model.
2. Parachains — permissionless side-runtimes that share Pyde's finality and validator set, with their own state subtree and an extended ABI for cross-chain messaging + threshold cryptography. Read Chapter 13 — Parachains.

Both compile to WebAssembly. Pyde executes them via wasmtime + Cranelift AOT — deterministic feature subset, per-tx overlay isolation, fuel-metered gas.

What language?

Whatever targets wasm32. Pyde doesn't ship per-language SDKs; authors compile their .wasm themselves and use the otigen toolchain to package + deploy it. First-class examples ship for:

• Rust — cargo build --target wasm32-unknown-unknown --release
• AssemblyScript — npx asc contract.ts -o contract.wasm
• Go (TinyGo) — tinygo build -target wasm-unknown -o contract.wasm
• C / C++ — clang --target=wasm32 -nostdlib -Wl,--no-entry

The chain only sees the bytes. Pick what fits your team.

The five things to read

In order:

1. Chapter 1 — Introduction — 10-minute orientation. Why Pyde exists, what it's not.
2. Chapter 3 — Execution Layer — the runtime, the per-tx overlay, the determinism contract.
3. Host Function ABI v1.0 — every pyde::* function your WASM can import. Signatures, semantics, gas costs, error codes. This is the contract the chain stands on.
4. Chapter 5 — Otigen Toolchain — how otigen builds, tests, deploys, and manages wallets.
5. Otigen Binary Spec v1.0 — the CLI surface. Every command, every flag.
6. Otigen Test Spec v1.0 — the contract-behaviour test framework (Foundry-grade, TOML). Read once you have a working contract.

Bookmark these. The rest of the book (state model, gas, accounts, consensus, networking, parachains, slashing, governance) you read on demand.

The minimum loop (once mainnet ships)

# 1. Scaffold a project
otigen init my-token --lang rust

# 2. Edit src/lib.rs + otigen.toml; write tests/contract.test.toml

# 3. Build (you run cargo; otigen post-processes)
cargo build --target wasm32-unknown-unknown --release
otigen build

# 4. Run the behaviour tests
otigen test

# 5. Deploy to devnet / testnet / mainnet
otigen deploy --network devnet

This loop is detailed in OTIGEN_BINARY_SPEC §3.2 + §3.10. The TOML format for tests/contract.test.toml is documented in OTIGEN_TEST_SPEC.md.

Pre-mainnet status (today)

Pyde is pre-mainnet. What's already shippable:

• The protocol spec (everything in this book).
• The post-quantum cryptography crate: pyde-crypto.
• The engine workspace's interface layer (MC-0 — phase-0-foundation tag on pyde-net/engine).
• The marketing site you arrived from.

What's in active build-out:

• The engine (execution + consensus + node binary). MC-1 in flight across two parallel streams — see Implementation Plan §3.2.
• The otigen toolchain. MC-1 Stream α — see pyde-net/otigen.

What you can do right now:

• Read the spec, file issues, propose PIPs.
• Watch the repos.
• Track the launch plan.

Where to ask

• GitHub Discussions — design questions, spec ambiguities.
• Telegram — quick chat, anything that doesn't need a paper trail.
• PIPs — propose a protocol change.

Welcome aboard.

Get Started — for Users

You're not here to write contracts. You want to use Pyde — hold PYDE, send a transaction, run a node, or follow the project's path to mainnet. This page is your map.

What's different about Pyde

Three things, in plain language:

1. It survives the quantum era

Every signature on Pyde uses FALCON-512, a NIST-standardised post-quantum signature scheme. Every encryption uses Kyber-768 (ML-KEM), NIST's post-quantum key-encapsulation scheme.

Translation: when a quantum computer powerful enough to break Bitcoin

• Ethereum signatures shows up, Pyde keeps working. There is no migration window because there's no ECDSA legacy to migrate away from.

Read more: Chapter 8 — Cryptography.

2. Front-running is structurally impossible

On most chains, the order of transactions inside a block is decided by whoever proposes the block — and that ordering is profitable. MEV bots pay validators to insert their trade in front of yours, drain your slippage, and move on.

Pyde encrypts transactions in the mempool with a key only the committee collectively holds. The committee commits to an order before any decryption share is released. By the time anyone can read what's inside a transaction, the ordering is already final. There is no profitable front-run because there's no information to front-run on.

Read more: Chapter 9 — MEV Protection.

3. Your account doesn't die when one key leaks

Native multisig is a protocol feature, not a contract every wallet re-implements. Lose a key, the rest of the keys still control the account. Coming post-mainnet: programmable accounts with spend limits, time locks, social recovery, and per-app session keys that can be revoked at any time.

Read more: Chapter 11 — Account Model.

Honest status (today)

Pyde is pre-mainnet. That means:

The sections below track the path from "pre-mainnet engineering" to "mainnet live".

What you can do right now

1. Read the whitepaper. 30 minutes; covers everything at a digestible depth.
2. Follow the launch plan. Phased to mainnet — no calendar dates; each phase ships when its bar is met.
3. Join Telegram for project chat.
4. Follow @pydenet on X for milestone announcements.
5. Watch the GitHub org if you want to see the work as it lands.

When mainnet ships

You'll do the things you'd do on any L1, with two structural differences:

• Your address is 32 bytes (0x + 64 hex chars). Pyde doesn't truncate addresses the way Ethereum does. You'll see this in any Pyde-native wallet.
• Your account survives single-key compromise if you set up native multisig at registration. The wallet UX will surface this as the default for non-trivial balances.

Gas works like Ethereum's EIP-1559 (no priority fees on Pyde — inclusion order isn't biddable), and the chain commits a wave every ~500 ms. Transactions land fast and final.

Where to follow along

• Launch Strategy — the phased path to mainnet.
• GitHub org — every repo, every commit.
• Telegram — community chat.
• X (@pydenet) — milestone announcements.
• info@pyde.network — formal contact.

Welcome to the pre-mainnet phase. It's the most honest place to be.

Introduction

What is Pyde?

Pyde is a Layer 1 blockchain built greenfield to deliver four properties no chain in production combines today:

1. Post-quantum cryptography by default — FALCON-512 signatures, Kyber-768 threshold encryption, Poseidon2 hashing
2. MEV resistance by structure — threshold-encrypted mempool + commit-before-reveal ordering eliminates proposer extraction
3. Sub-second finality — Mysticeti-style consensus, ~500ms median finality
4. Commodity decentralization — modest hardware for validators not currently on the active committee; equal voting power within the active committee

The execution layer is WebAssembly via wasmtime, with Cranelift ahead-of-time compilation and a uniform Block-STM scheduler — every tx runs optimistically in parallel through an MVCC layer, conflicts are detected at runtime, losers re-execute until fixpoint. Wallet-attached access lists from pyde_simulateTransaction drive PIP-3 multiget prefetch into the dashmap cache before execution starts; the lists are performance hints, not scheduling decisions. Smart contracts can be authored in Rust, AssemblyScript, Go (TinyGo), or C — whatever language the team already uses — and bundled by the otigen developer toolchain.

Cross-chain interactions — calling functions on other chains, querying oracles, off-chain compute — happen through a permissionless parachain layer (post-mainnet) with operators who stake PYDE and earn gas fees from contracts that call them. No custodial multisigs, no auctioned slots.

The Pivots

Pyde has gone through two clean pivots that materially changed the architecture. Both are documented honestly in the preface (The Pivot) and supported by full historical design records in pivot/.

• Consensus pivot — from an in-house HotStuff variant (whose 400ms tail-latency wedges proved structural rather than tunable) to Mysticeti-style DAG consensus. The HotStuff-era consensus crates are archived; the Mysticeti-based rebuild is in progress.
• Execution pivot — from a custom virtual machine (pyde-vm), a custom AOT compiler (pyde-aot), and a custom language (Otigen) to WebAssembly via wasmtime. The Otigen name lives on as the developer toolchain (otigen). The original Otigen Book is preserved as a historical artifact.

This book reflects the post-pivot architecture. The work that preceded each pivot is preserved both in code (archive/) and in design documentation (pivot/).

Why a New Layer 1?

The Quantum Problem

Every major Layer 1 in production today — Bitcoin, Ethereum, Solana, Cardano, Polkadot — uses classical cryptography (secp256k1, Ed25519, BLS12-381) vulnerable to Shor's algorithm. NIST's 2024 standardization of FALCON, ML-DSA, and ML-KEM unblocked post-quantum primitives, but retrofitting them into a live chain is a multi-year coordinated migration. Pyde ships PQ at genesis without retrofitting.

The MEV Problem

Maximum Extractable Value has hardened into a multi-billion-dollar tax paid by retail users to validator-builder coalitions. Sandwich attacks, front-running, and proposer extraction are not bugs — they are structural consequences of public mempools and single-proposer block production. Pyde eliminates the structural conditions via threshold encryption + commit-before-reveal ordering with no single proposer to exploit.

The Decentralization Problem

Chains optimizing for throughput have ended up requiring datacenter-class validator hardware. Chains optimizing for decentralization have ended up with throughput unusable for serious applications. Pyde scales hardware requirements by role — commodity for validators awaiting committee selection, modest professional for validators on the active committee at production targets, datacenter only for aspirational TPS levels.

What's New (Post-Pivot)

• Mysticeti DAG consensus replaces HotStuff. No view changes, no single proposer, sub-second commit latency targeted (implementation in progress)
• WebAssembly execution via wasmtime, with Cranelift AOT. Smart contracts written in Rust, AssemblyScript, Go, or C/C++ — same language ecosystem authors already work in
• Worker / Primary split (Narwhal pattern) for data dissemination separate from consensus
• Uniform Block-STM scheduler — optimistic parallel execution + MVCC validation; access lists from pyde_simulateTransaction drive PIP-3 prefetch into the dashmap cache before workers start
• JMT state tree (Jellyfish Merkle Tree, radix-16) replaces fixed-depth SMT — with dual Blake3 + Poseidon2 roots so standard light clients and future ZK light clients verify against the same tree
• PIP-2 clustered slot keys + PIP-3 prefetch + PIP-4 write-back cache — three-layer state performance stack
• Encryption opt-in per-tx — MEV protection where needed, no overhead where not
• otigen developer toolchain — zero-extra-code authoring: write contract logic + otigen.toml, the tool handles everything else
• Honest performance targets — the v1 throughput target is validated by a multi-region performance harness before any number is published
• Phased mainnet plan — external audit + incentivized testnet before launch

Honest Status

This book describes designed architecture, with implementation in various stages:

Mainnet ships when the implementation is complete, audited, and validated by an incentivized testnet — no public schedule. See Chapter 19: Launch Strategy for the phased path.

Performance Targets

Throughput is validated by a multi-region production-realistic harness (mandatory before any external claim). Pyde publishes no forward throughput number — the v1 honest throughput target is established only once the harness measures it under sustained, production-realistic conditions. Latency targets, by contrast, are concrete:

The HotStuff Lesson: the pre-pivot implementation hit ~4K TPS in practice despite a higher claimed design target. Pyde now adopts the discipline of publishing only what the harness measures under sustained, production-realistic conditions — never lab extrapolations or microbenchmark peaks. No external TPS claim without harness evidence.

Reading Path

This book is the comprehensive technical reference. Different paths for different audiences:

For a researcher / cryptographer:

1. Chapter 2: Architecture Overview
2. Chapter 6: Consensus (Mysticeti DAG)
3. Chapter 8: Cryptography
4. Chapter 9: MEV Protection
5. Companion: Whitepaper

For an implementer / contributor:

1. Chapter 2: Architecture Overview
2. Chapter 3: Execution Layer (WASM)
3. Chapter 4: State Model
4. Chapter 5: Otigen Toolchain
5. Chapter 11: Account Model
6. Chapter 12: Networking
7. Companion: Architecture (Design Doc)
8. Preface: The Pivot for context on architectural choices

For a validator operator:

1. Chapter 6: Consensus
2. Chapter 7: State Sync & Chain Halt
3. Chapter 16: Security & Threat Model
4. Companions: Validator Lifecycle, Slashing, Chain Halt & Recovery

For an investor / decision-maker:

1. This Introduction
2. Chapter 14: Tokenomics
3. Chapter 19: Launch Strategy
4. Companion: Tokenomics Detail

For someone doing security review / audit:

1. Chapter 16: Security & Threat Model
2. Chapter 6: Consensus (safety arguments)
3. Chapter 8: Cryptography
4. Companions: Threat Model, Failure Scenarios, Network Protocol, Performance Harness

License

Pyde is licensed under Apache-2.0. The full text lives in LICENSE at the root of each Pyde repository. The book content is licensed under CC BY-SA 4.0.

Status

Living document. Updated as the design evolves.

The Pivot

A note on how this book came to describe what it describes, and what changed along the way.

Starting from a question

Pyde began with a simple question that turned out to be much harder than it looked:

Can we build a post-quantum L1 that is actually fast?

Not "fast in the abstract." Not "fast in a research paper." Fast enough that real users would not notice it was post-quantum at all. Fast enough that the security upgrade was free at the point of use.

That question is what this book is about. Everything else — the consensus choice, the execution model, the state layer, the crypto primitives — is downstream of trying to answer it honestly.

This preface is the story of the answers we tried, the answers we kept, and the answers we threw away.

The first instinct: a small, sandboxed VM

The earliest sketches of Pyde leaned on something close to a BPF-style virtual machine. Solana had shown that a tight, sandboxed, register-based VM could run blockchain workloads at speeds that older designs (the EVM in particular) had no path to. The appeal was obvious: instead of inheriting a heavy stack-based VM with decades of cruft, start lean.

The thinking was: a small instruction set, a tight verifier, a fast interpreter or AOT, and crypto-friendly opcodes. Let the rest of the system inherit that lightness.

What we did not appreciate at the time — and what took building to learn — was that the VM is rarely the bottleneck on a blockchain. The bottleneck is consensus tail latency, signature verification, network bandwidth, and disk I/O, in roughly that order. The VM is the part you write last and that matters least. We would learn this the hard way, more than once.

But the BPF idea seeded something useful. It taught us to think in terms of sandboxing as a first-class property, not an afterthought. It taught us that "your own VM" is a commitment to building, maintaining, and securing an entire compiler toolchain — not a one-shot decision. Those lessons stuck. The specific implementation did not.

The HotStuff phase and a 400-millisecond wedge

For the full design record of this era, see hotstuff-consensus-era.

For consensus, we tried HotStuff first. It is the orthodoxy of modern BFT — used by Diem (the version that did not ship), Aptos, several other production chains. The literature is clean. The proofs are tight. The reference implementations are credible.

We picked it up and started integrating it.

For a while, things looked promising. Throughput was reasonable. The committee structure made sense. The pipeline of view changes felt mostly orderly. We started building around it: the mempool, the block production, the early state machine.

And then we ran into a wedge.

Under load, in adversarial conditions — partial network partitions, slow validators, particular orderings of messages — HotStuff's tail latency would balloon. We saw commits taking 400 milliseconds where the median was under 100. That tail was not a curiosity. It meant a real chain running under real conditions would routinely freeze for fractions of a second, and that was unacceptable for the kind of UX we wanted Pyde to enable.

We spent weeks trying to engineer around it. Tuning timeouts. Re-ordering message handlers. Experimenting with leader rotation strategies. Adjusting the view-change protocol. Some of these helped at the margin. None of them got the tail under control.

Eventually the honest read became: HotStuff is not the right base for what we are trying to build. The tail latency is not a tuning problem; it is a structural property of how leader-based BFT handles adversarial conditions. We could keep grinding on it for another year and not get there.

That was the first hard pivot.

We turned to the DAG family — Mysticeti, Narwhal, Blueshark. The DAG approach decouples data availability from ordering, removes the single-leader bottleneck per round, and gives the kind of tail latency profile we needed. Mysticeti specifically had the freshest design and the best throughput numbers in the literature.

We adopted it as the consensus design direction. The implementation is currently in progress — the HotStuff-era consensus crates are archived, and the new Mysticeti-based consensus layer is being built design-first against the post-pivot architecture. The architecture chapters that follow describe Mysticeti as the design Pyde is being built around, not as code that has already shipped.

The HotStuff work was not wasted. Building it taught us what a BFT pipeline really looks like under load. The instinct that "the latency tail is what kills UX" carried forward. But the code itself got archived. We learned, and we moved.

A smaller pivot worth recording: SMT to JMT

Around the same time we were working on the consensus layer, we were also evaluating the state-commitment structure. The clean theoretical answer was a Sparse Merkle Tree — a fixed-depth-256 tree, one of the most studied constructions for accountable state. Beautiful on paper.

Expensive in practice. Every state read or write touches roughly 256 nodes because of the fixed depth. At realistic TPS, that overhead dominates the disk IO budget. The math did not close.

We switched to the Jellyfish Merkle Tree (JMT) — radix-16, path-compressed, production-validated by Diem and Aptos. Same authentication properties (Merkle commitment, inclusion and exclusion proofs), but roughly 5-10 nodes touched per operation instead of 256. The IO budget closes. The chain ships at a realistic TPS instead of an aspirational one.

The SMT lessons did not disappear. They informed the current dual-hash JMT design, where the Poseidon2 path gives us the ZK-proof properties SMTs are known for, while the JMT structure underneath keeps the IO cost manageable. This was a smaller pivot than the consensus and execution ones, but it followed the same pattern: pick the cleanest theoretical answer first, run the numbers, switch to the production-grade variant when the cleanest answer does not survive contact with reality.

Building Otigen the language

For the full design record of this era, see otigen-language-era. The complete language reference, syntax, semantics, and standard library documentation are preserved in the otigen-book (now with a pivot-notice preface).

Around the same time, we made another decision that would also need revisiting later.

We decided to design and build our own smart-contract language.

Looking back, this was not an irrational decision. Given what we knew then, it was rational. The argument went like this: if Pyde is going to be opinionated about consensus, about cryptography, about state — about every layer of the stack — then the smart-contract language should be opinionated too. Otigen would be designed from day one around Pyde's semantics. Encryption-friendly. Threshold-decryption-aware. Nonce-window-native. Tight gas accounting. A clean compilation target for our pVM bytecode.

So we built it.

We built the compiler (otic). We built the bytecode interpreter (pyde-vm). We built the Cranelift-based ahead-of-time compiler (pyde-aot). We built the standard library. We built the developer toolchain (wright). We wrote a book about it (the otigen-book, still preserved as historical reference). We documented opcodes. We designed type semantics. We dogfooded contracts.

Real engineering. Real months of work.

For a while, the bet looked good. Otigen had personality. Its syntax was clean. The pVM was lean. The integration with Pyde's primitives — threshold encryption, access lists, nonce windows — was tighter than any general-purpose VM could match.

What we did not see clearly at the time was that building a smart-contract language is not a one-shot deliverable. It is a permanent commitment to a category of work that competes against everything else the chain needs. A language has to keep up with the host platform (toolchain updates, Cranelift API churn, security advisories). It has to add features real applications need that we did not predict in version one. It has to maintain backwards compatibility, or pay the cost of breaking it. It has to be fuzzed, audited, and hardened against an open adversary. It has to be documented for new developers, supported in IDEs, debuggers, profilers, linters, formatters. It has to be taught.

The deeper question, the one we eventually had to ask honestly, was whether all that ongoing work was paying for the right things. The language was not Pyde's differentiator. Solana's BPF is not why people use Solana. Polkadot's WASM is not why people use Polkadot. Aptos's Move-language is closer to a differentiator, but even there the chain competes on consensus and security, not on Move itself. Smart-contract languages are tools. They matter for developer experience. They do not move the needle on the question Pyde was created to answer — can we build a post-quantum L1 that is actually fast?

The work we were spending on the language was work we were not spending on the answer.

So we ran the honest math.

The honest reckoning

The decision was not made all at once. It accumulated.

There was the moment when a routine Cranelift API update broke the AOT compiler and took two days to chase down. There was the moment when a community developer asked whether they could write contracts in Rust, and we had to say "no, you have to learn Otigen first."

There was the moment when we read another paper on zk-WASM proving and realized that the WASM ecosystem was approaching native ZK execution proofs — work being pushed forward by several research groups in parallel — while a zk-Otigen prover would have to be built from scratch by us, and audited from scratch, and maintained from scratch.

There was the moment when we counted the audit surface honestly. A custom VM means:

• An internal audit of the bytecode interpreter, the AOT compiler, the sandbox boundary, the gas accounting, the trap handling.
• An external audit of all of the above, by a specialist firm willing to learn an instruction set that exists only here.
• Continuous fuzzing of the interpreter and the AOT against adversarial inputs.
• Re-audits whenever the language or the VM evolves.
• The same audit work, repeated, every year, indefinitely.

A WebAssembly runtime means: wasmtime, which is already vetted as production infrastructure by Bytecode Alliance, deployed at scale by Microsoft, Fastly, Shopify, and others. The sandbox has been fuzzed continuously for years. The instruction set is a public standard with academic and industrial scrutiny. We inherit that work at zero engineering cost. Our remaining audit surface shrinks to the host-function ABI and the chain-side integration — a small fraction of what a custom-VM audit would cost.

That was not a marginal saving. That was a reframe of how much engineering capacity Pyde would have to put into proving its own execution layer was safe, on a recurring basis, every year going forward.

And then there was the moment that settled it: we ran the numbers honestly.

The argument for keeping a custom VM had always rested on a quiet assumption — that our custom AOT, hand-tuned for our opcodes, would outperform a general-purpose WASM runtime. The reasoning sounded plausible: bespoke beats generic, surely. We had built pyde-aot carefully. It used Cranelift, the best open-source code generator outside of LLVM. It produced real native machine code. We had spent months on it.

So we looked at wasmtime. And we found out something that changed the whole equation.

Wasmtime also uses Cranelift. The exact same backend. The same code-generation passes. The same register allocator. The same machine-code emitter. The difference between pyde-aot and wasmtime's AOT was not the optimizer — it was the front-end that fed instructions into Cranelift.

And the WASM front-end is the path Cranelift was originally optimized for. WebAssembly is the workload Cranelift was built to serve well. Years of optimization passes, edge cases, calling-convention refinements — all targeted at WASM. Our Otigen front-end, by comparison, was new code touching the same backend. It had not been adversarially fuzzed. It had not benefited from a hundred outside contributors finding obscure miscompiles. It worked, but it was newer, less battle-tested, with smaller margins for the optimizer to extract performance from.

We then ran our own benchmarks instead of guessing. Real measurements on the existing PVM stack, on a developer workstation:

• PVM interpreter, ALU dispatch: ~279 million instructions per second.
• PVM AOT, ALU dispatch: ~2.9 billion instructions per second. A 10× speedup on tight compute loops.
• PVM AOT, DEX swap (constant-product AMM): ~100 million swaps per second, 3.7× faster than interpreted.
• PVM AOT, token transfer (storage-bound): ~243K transfers per second — essentially identical to the interpreter's ~231K. Storage IO dominates; the AOT compute advantage disappears.
• AOT compilation cost: under one millisecond for contracts under 256 instructions.

These numbers are single-thread micro-benchmarks of the execution layer in isolation — one VM, one workload, no consensus, no network, no parallel scheduling. They measure raw VM throughput, not end-to-end TPS. Full-chain TPS is governed by consensus latency, signature verification, network bandwidth, parallel scheduling, and disk IO in addition to VM execution; Pyde's realistic v1 throughput target (awaiting harness measurement) reflects all of those layers combined. The numbers above are useful for the VM-vs-VM comparison; they are not the chain's TPS.

Hardware used: Apple M4 Pro, 14 cores, 24 GB RAM, macOS 26.3.1.

Reproduce these numbers yourself: see pivot/03-running-benchmarks.md for the exact commands and the expected output shape.

Those are real numbers, not extrapolations. They tell us several things about where the VM actually matters.

The 10× speedup is on tight ALU loops. Real smart contracts are not tight ALU loops. They are storage reads, storage writes, signature checks, event emissions — workloads where the AOT-versus-interpreter gap collapses to roughly 1× because the bottleneck moves to RocksDB and to cryptographic verification, neither of which the VM can speed up. So the actual workload Pyde runs barely cares which VM compiles it.

When we mapped this against published wasmtime numbers — Cranelift-AOT WASM landing within 80-95% of native speed on compute, the interpreter at 10-30% of native — the comparison sat in the same range as our measurements. The two stacks are not in different leagues. They are in the same league, on the same backend, for the same reasons.

The interpreted comparison told the same story. A WASM interpreter (the fallback path when AOT cache is cold) achieves roughly the same throughput as our PVM interpreter — both sit in that 10-30 percent of native range, because both pay the dispatch cost. There was no meaningful interpreted-vs-interpreted advantage either.

So the speed argument for keeping Otigen quietly disappeared. The custom VM was not faster on the workloads that matter. It was just smaller-team-maintained, less-fuzzed, and lonelier.

What WASM offered was not just a comparable runtime. It was an already-vetted one. Production-deployed at Fastly and Microsoft and Shopify. Continuously fuzzed by an open community. Maintained by an entity that exists to maintain it. And we would pay essentially zero engineering capacity to inherit all of that — no compiler to support, no language to teach, no security maintenance to schedule. We got the speed plus the platform plus the ecosystem, in exchange for retiring a custom stack we had built for reasons that no longer held.

There was the moment when we looked at the surface area a credible v1 requires — consensus correctness, threshold cryptography, state sync, slashing, validator lifecycle, network protocol, parachain framework, audit prep — and realized that an in-house language committed us to maintaining a parallel track of work that competed with all of those for attention. Not because the language was harder than the consensus or the crypto. Because the language was optional in a way the others were not. Every chain ships consensus and crypto and state. Few chains ship their own language. The ones that do (Move, Vyper, Otigen) carry that as a perpetual obligation, and it is rarely the thing that determines whether the chain ships well.

We decided that Pyde would compete on what is actually unique to Pyde — post-quantum consensus, threshold-decrypted mempool, the cryptography stack — and inherit the rest from established WebAssembly tooling.

Pyde's execution layer pivoted to WebAssembly via wasmtime. Authors write contracts in Rust, AssemblyScript, Go, or C — whatever they already know. The compilation target is well-defined, the runtime is battle-tested in production at Fastly and Microsoft and Shopify, the sandboxing is verified by years of fuzzing, the gas-metering is built in, and the ZK-readiness path has actual researchers working on it.

This was not a defeat. It was the right call. The work we did building Otigen taught us what mattered (sandboxing, determinism, gas semantics, tight integration with Pyde primitives) and what did not (a custom syntax we had to teach the world). Everything that mattered carried forward into how we expose Pyde's primitives as WebAssembly host functions. The work was not wasted. The language was retired, but its lessons live in the new architecture.

The Otigen safety goodies are preserved

Worth being explicit about this because it is easy to assume a language-retirement loses the safety properties the language enforced. It does not.

Otigen's design defaults — reentrancy blocked by default, checked arithmetic, typed storage, no tx.origin, compile-time access list inference, the #[view] / #[payable] / #[reentrant] / #[sponsored] / #[constructor] attribute set — are all preserved unchanged in the WASM era. They are now expressed as language-native attributes (Rust #[pyde::view], AssemblyScript @pyde.view, Go //pyde:view, C PYDE_VIEW) that the build tool extracts into the ABI; the runtime applies the same guards it would have applied under Otigen.

Reentrancy is still blocked by default. The reentrancy guard is enforced at the WASM execution layer for every function not marked #[reentrant]. The author who writes nothing is still protected — exactly as in the Otigen era. See Chapter 5: Otigen Toolchain §5.6 for the full attribute surface and per-language declaration syntax.

The mechanism changed (build-time metadata + runtime enforcement instead of language compiler). The author experience and the safety guarantees did not.

What we got from the pivot

Worth naming explicitly, so the trade-offs are visible:

• An already-vetted execution platform. Wasmtime is production infrastructure at Microsoft, Fastly, Shopify, and many others. The sandbox boundary, the determinism guarantees, the fuel-metered gas, the validation pipeline — all of it has been fuzzed continuously and hardened in adversarial conditions for years. We did not have to build any of it.

• A dramatically smaller audit surface. A custom VM means auditing the interpreter, the AOT compiler, the sandbox, the gas accounting, the traps, and the language compiler — all from scratch, internally first and then externally, then re-audited as the system evolves. With wasmtime, our audit surface is the host-function ABI and the chain-side integration. Smaller scope, lower cost, faster turnaround, fewer specialists required.

• Years of compounding maintenance work avoided. No language to keep current. No compiler to keep current. No AOT to keep current. No standard library to maintain. No IDE plugins, no debuggers, no formatters, no linters to write from scratch. The maintenance burden of a custom-language stack is permanent; pivoting away from it returns that capacity to Pyde's actual differentiators.

• A clean ZK readiness path. zk-WASM is an active research area with multiple groups pushing it toward production. When mature, the provers slot in over our existing wasmtime execution — no re-tooling required on our end. zk-Otigen, by contrast, did not exist and would have been a multi-year side project for us alone.

• Multi-language support out of the box. Authors write Pyde contracts in Rust, AssemblyScript, Go (via TinyGo), or C/C++. The barrier to entry is "the language you already use," not "the language Pyde wants you to learn." Developer adoption stops being gated by syntax familiarity.

• A larger ecosystem of tooling. Block explorers, debuggers, profilers, fuzzers, formal verification tools — all exist for WebAssembly. We inherit them. Pyde-specific tooling can layer on top instead of starting from zero.

• Time savings, measured honestly. The engineering capacity we would have spent maintaining Otigen — language design, compiler bug fixes, AOT bug fixes, standard library work, security advisories, ecosystem support — flows directly into the work Pyde actually competes on: post-quantum consensus, threshold cryptography, state-layer performance, validator lifecycle, parachain framework.

The trade-off we accepted: a small overhead on tight compute loops (which the benchmarks show is negligible for blockchain workloads, where storage IO dominates) and the loss of "Pyde has its own VM" as a marketing line (which was never a real differentiator anyway). For that price we got everything above.

The Otigen name lives on too. The new developer toolchain — the binary that scaffolds projects, generates state bindings, builds WASM artifacts, and deploys them — is called otigen. The same name, repurposed for the role it serves best: making the ergonomics layer feel as opinionated and integrated as the language was meant to be. The original otigen-book is preserved as a historical artifact, a snapshot of an earlier design phase that taught us what we needed to learn.

This is the same posture Rust's cargo takes (named for shipping containers, not for a programming concept) or Foundry's forge and cast take (craft-naming for tools). The name describes the role in the workflow, not the underlying technology.

Where we are now

The architecture that this book describes is the architecture after the pivots:

• Consensus: Mysticeti-style DAG, anchor-every-round, tail-latency-aware.
• Execution: WebAssembly via wasmtime, with Cranelift AOT for hot paths.
• State: Jellyfish Merkle Tree with dual hashing (Blake3 + Poseidon2), PIP-2 clustered slot keys for cache locality, dual roots so we can serve both standard light clients and future ZK light clients from the same tree.
• Cryptography: FALCON for signatures (post-quantum), threshold decryption as an opt-in mempool privacy path, Poseidon2 as our ZK-friendly hash, Blake3 for fast general hashing.
• Developer experience: the otigen binary owns the entire authoring lifecycle. Authors write only their contract logic and a otigen.toml. Everything else — language detection, build invocation, state binding generation, ABI emission, deploy-tx submission — is handled by the tool.
• Parachains: WASM runtime per parachain, equal-power governance, full upgrade history retention, ENS-style name registration.

Each of these is the result of trying something else first, hitting a wall, and learning what the wall was made of. The book chapters that follow describe each layer in detail. This preface is here so that when you read about Mysticeti instead of HotStuff, or WASM instead of Otigen-the-language, you know that those choices were the outcome of work, not first instincts.

The first instincts were wrong, mostly. The current architecture is what was left after the wrong ones were honestly retired.

What this pivot does not change

It is worth being explicit about what stays the same, because the changes have been substantial and a casual reader could conclude that everything is in flux. It is not.

The core thesis is unchanged: post-quantum from day one, practical performance, decentralized validator set, light-client-verifiable state, opt-in transaction privacy via threshold decryption.

The consensus model is unchanged from the Mysticeti pivot onward: DAG-based, anchor-per-round, equal-power VRF-rotated committee.

The state layer is unchanged from the JMT decision onward: versioned Merkle tree, hash-friendly to both general hashing and ZK provers, PIP-2 clustering for locality.

The cryptography is unchanged: FALCON, Poseidon2, Blake3, threshold decryption via DKG.

The PIPs (Pyde Improvement Proposals) — PIP-2 clustered state keys, PIP-3 scheduler-level prefetch, PIP-4 application-level write-back cache, the dual-hash JMT — all carry forward unchanged. They are layer-agnostic. The execution VM does not affect them.

The pivot is localized. Most of Pyde's design carries through.

What this book is, and is not

This book is the current architecture of Pyde, as honestly as we can describe it. It is updated as design decisions land. The chapters that follow assume the pivots described here have happened; they do not repeatedly say "after the WASM pivot" or "before the consensus change." Read those as historical facts that informed what is described here.

This book is not a marketing document. It does not promise speeds we have not measured. It does not list partnerships that do not exist. It does not paper over the parts of the design that are still hard. Where something is uncertain, we say so. Where we have changed our minds, we say that too.

If you came here looking for a clean, never-pivoted, always-knew-the-answer story — that is not what Pyde is, and not what this book is. Pyde is what happens when someone decides to build a post-quantum L1, runs into every wall the architecture has to offer, and writes down what remained after the dust settled.

For the deep technical material on the earlier iterations — the HotStuff consensus design that preceded Mysticeti, and the Otigen language design that preceded WebAssembly — see the Pivot folder, which includes the design records and a step-by-step guide to running the pivot-era benchmarks on your own machine. The narrative is here; the design records are there.

The book starts now.

Pivot — Historical Design References

This directory preserves Pyde's earlier architectural iterations as first-class historical material. Pyde has gone through two clean pivots that materially changed the protocol design, and the work that preceded each pivot is documented here so it can be studied, learned from, and properly credited.

Read the preface first if you have not already — it is the narrative companion to this directory. The preface tells the story; this directory holds the design records.

Contents

Each document summarizes what was designed, what was built, what was learned, and where the deep technical material lives (which archived repos, which book, which design docs). The summaries are not re-derivations of the original work — they are pointers + context for reading the originals correctly.

Why this exists

Three reasons:

1. The work is real. Building these systems taught us what mattered and what did not. The current architecture is informed throughout by lessons from these earlier iterations. Pretending the work never happened would be both dishonest and counterproductive — future architects (Pyde or otherwise) can learn from the trade-offs we explored.

2. Honesty is the project's posture. Pyde's design has changed in response to evidence. Documenting the changes openly is the same discipline that made the changes possible. A reader who lands here looking for "why did Pyde stop using X?" deserves a real answer with real material, not a 404.

3. Some of these designs are independently interesting. The Otigen language, the custom register-based VM, the pre-Mysticeti HotStuff integration, the early access-list scheduler — these are not generic patterns. They were thought through carefully. Someone designing a similar system elsewhere may find the trade-offs documented here useful.

How to read what's here

Each document follows the same shape:

• What we built — the design, in summary form.
• Why we built it that way — the constraints and reasoning at the time.
• What we learned — what survived the pivot, intellectually.
• Where the original material lives — links to archived code, archived docs, and the otigen-book for language-specific content.

Read in the order presented (01 then 02). The two pivots happened in sequence; the second was informed by lessons from the first.

Reading order for the whole pivot story

1. Preface: The Pivot — the narrative.
2. This directory's 01 — HotStuff Era and 02 — Otigen Era — the design records.
3. The main book chapters — the current architecture.

01 — The HotStuff Consensus Era

The first consensus protocol Pyde adopted was an in-house variant of HotStuff. This document summarizes that design, why we chose it, what it taught us, and where the original material lives.

What we built

A linear, pipelined HotStuff variant tuned for Pyde's committee model:

• Three-phase commit pipeline — prepare, pre-commit, commit, decide, with each phase carrying a quorum certificate (QC) from the prior phase.
• Leader-driven block production — one leader per view, leaders rotate per view via deterministic rotation.
• 128-validator committee — the same committee size we still use today (preserved across the pivot).
• 400ms slot timing — target round duration of 400ms, with adaptive timeouts on view changes.
• FALCON-512 quorum certificates — 85-of-128 signatures aggregated into a QC, with the FALCON signature scheme preserved across the pivot.
• Pipelined view changes — to avoid the canonical HotStuff round-trip stall, view changes were pipelined into the steady-state flow.

The architecture lived in a consensus crate inside the engine workspace, alongside the (then-) PVM execution layer and the state crate.

Why we built it that way

HotStuff was the orthodoxy of modern BFT at the time. Used by Diem (Meta's version that did not ship), adopted by Aptos, validated in academic literature, with reference implementations available. The properties looked right for Pyde:

• Linear message complexity (vs PBFT's quadratic).
• Optimistic responsiveness (commits at the speed of the network, not at fixed timeouts).
• Simple safety + liveness proofs.
• Established ecosystem of HotStuff variants to learn from (LibraBFT, AptosBFT, HotStuff-2).

The constraint set Pyde faced — equal-power validators, sub-second commits, geographic-distribution-tolerant — looked like a clean HotStuff fit on paper.

So we built it.

What went wrong

Under load, in adversarial conditions — partial network partitions, slow validators, particular orderings of messages — HotStuff's commit latency tail ballooned. Median commits stayed under 100ms; tail commits ran out to 400ms and beyond. The chain "wedged" intermittently: not formally halted, just unable to deliver low-latency commits when conditions degraded.

We engineered against the tail for weeks. Tuning timeouts, re-ordering message handlers, experimenting with different leader-rotation schedules, adjusting the view-change protocol. Some of these helped at the margin. None of them got the tail under control structurally.

The honest read became: HotStuff's latency tail is not a tuning problem. It is a structural property of leader-based BFT under adversarial conditions. Different parameters give different tail shapes; none of them give a flat tail. We could keep grinding for another year and still ship a chain that wedged.

What we learned

Three lessons survived the pivot intact:

1. Tail latency is the UX killer, not median latency. A chain that commits in 100ms on average but stalls for 400ms in the tail will feel broken to users. The current Mysticeti-based design is specifically chosen for its better tail-latency profile under adversarial conditions, not for its median performance.

2. DAG consensus is structurally different from leader-based BFT, in ways that matter. The single-leader bottleneck in HotStuff is what produces the tail; removing the bottleneck (per-round, every validator can produce a vertex) removes the structural source of the tail.

3. Build to learn, but be willing to throw it away. The HotStuff integration was real engineering work. We did not regret building it — we regretted not pivoting away from it sooner. The retrospective lesson: when the data says "this won't get there," act on it. Do not engineer-around the structural problem.

What survived

Several pieces of the HotStuff-era architecture carried forward into the current Mysticeti-based design without change:

• The 128-validator committee size with 85-quorum threshold.
• The FALCON-512 signature scheme for quorum certificates.
• The equal-power, VRF-rotated committee selection model.
• The general wave abstraction (a periodic commit unit with an associated state root).
• Much of the supporting infrastructure: state layer, mempool admission, transaction types, validator lifecycle.

The pivot was localized to the consensus core. Everything that touched consensus from above or below stayed.

Where the original material lives

• Source code — archive/crates/consensus/ (in the umbrella repo). The HotStuff implementation, including the QC types, view-change protocol, and leader-rotation logic.
• Design notes — archive/crates/consensus/CONSENSUS_INVARIANTS.md documents the consensus invariants the HotStuff implementation upheld.
• Original whitepaper — archive/WHITEPAPER.md describes the early-architecture vision including HotStuff as the consensus choice.
• Pre-pivot engine crates — archive/crates/ more broadly contains the consensus-adjacent crates from this era (mempool integration, transaction processing under HotStuff semantics).

The archive directory is preserved with git history intact. Anyone wanting to study the HotStuff-era implementation can browse it directly or check out the git revision before the consensus pivot.

Reading on

• 02 — The Otigen Language Era — the second pivot, on the execution layer.
• Chapter 6: Consensus (Mysticeti DAG) — the current consensus design.
• Preface: The Pivot — the narrative version of both pivots.

02 — The Otigen Language Era

The second large pivot Pyde went through was the retirement of the custom execution stack — language, VM, AOT, toolchain — in favor of WebAssembly via wasmtime. This document summarizes what we built in the Otigen-language era, why we built it that way, what we learned, and where the original material lives.

What we built

A complete custom execution stack for Pyde, four interlocking components:

Otigen — the language

.oti source files, surface syntax inspired by Rust, semantics tuned for blockchain execution:

• Reentrancy blocked by default; opt-in via the #[reentrant] attribute.
• Checked arithmetic by default; wrapping operations explicit.
• Typed storage via the storage { ... } block.
• No tx.origin — the language did not expose it.
• #[view] / #[payable] / #[constructor] function attributes.
• Compile-time access-list inference for the parallel scheduler.
• 4-byte function selectors derived from signature hashes.

otic — the compiler

.oti source → PVM bytecode + JSON ABI. Architecturally a four-stage pipeline: lex → parse → resolve → typecheck → safety analysis → bytecode emit. Implemented in Rust as a standalone library + binary.

pyde-vm — the virtual machine

A custom register-based VM:

• 16 × 64-bit general-purpose registers.
• 8 × 256-bit wide registers (for token amounts, hashes, signature components).
• 32-bit fixed-width instruction encoding.
• 62 opcodes covering ALU, memory, storage, crypto, host calls, and control flow.
• Static 4MB memory map with gas-metered page allocation.
• Trap-on-overflow by default.

pyde-aot — the ahead-of-time compiler

PVM bytecode → native x86 / aarch64 machine code, via the Cranelift code generator. Compiled at contract deploy time; the resulting native function was cached forever (contracts were immutable).

wright — the developer toolchain

Project-level CLI (init, build, test, deploy, wallet, console) analogous to Foundry for Solidity. Wrapped the otic compiler with project conventions and a deployment client.

Why we built it that way

The original argument: Pyde was going to be opinionated about every layer (consensus, cryptography, state, MEV protection), so the language layer should be opinionated too. Otigen would be designed from day one around Pyde's semantics — encryption-aware, threshold-decryption-friendly, nonce-window-native, with tight gas accounting and a clean compilation target.

The constraints we wanted the language to address:

• Reentrancy footguns in Solidity contributed to billions of dollars of lost funds historically. Block by default.
• Arithmetic overflow caused the bZx incidents, the YAM rebase bug, others. Check by default.
• Untyped storage in EVM led to slot-collision bugs. Type it.
• tx.origin was a phishing vector. Do not expose it.
• Dynamic dispatch unpredictability broke parallel execution in EVM. Infer access lists at compile time.

These were real problems we wanted addressed structurally, not via developer discipline.

We also believed at the time that a custom VM with a custom instruction set, tightly designed for blockchain operations, would outperform a general-purpose runtime. The PVM's wide-register file was specifically designed for 256-bit token amounts and hash operations.

So we built the whole stack.

What went right

Several pieces of the design worked exactly as intended:

• Otigen's safety defaults caught a class of contract bugs at compile time that would have been runtime failures in EVM.
• Compile-time access-list inference enabled the parallel scheduler to run non-conflicting transactions concurrently, a real performance win.
• The wide-register file was clean for 256-bit operations.
• The AOT compiler produced native code via Cranelift; benchmarks showed 10× speedup on tight ALU loops vs the interpreter.
• The wright toolchain offered a Foundry-quality developer experience.

The engineering work was real. The design was coherent. The team built it carefully.

What went wrong

Two things, accumulating over time:

One — the maintenance commitment was not one-shot

Building a language is a permanent commitment, not a one-time deliverable. Toolchain churn (Cranelift API updates breaking the AOT), feature requests from authors, security advisories, fuzzing, audit prep, documentation, IDE support — all of it had to be sustained continuously. The language was a parallel track of work that competed with the rest of the protocol for attention.

Two — the speed argument did not hold

The case for keeping a custom VM rested on the assumption that custom-AOT would outperform a general-purpose WASM runtime. Investigation showed otherwise:

• Both pyde-aot and wasmtime use the same Cranelift backend.
• WebAssembly is the workload Cranelift was originally optimized for.
• Our Otigen front-end was newer, less battle-tested, less fuzzed.
• Direct benchmarks showed wasmtime-AOT throughput in the same range as pyde-aot.
• On storage-bound workloads (the workload shape that matters for blockchain TPS), the AOT-vs-interpreter advantage collapsed to roughly 1× regardless of which AOT was running.

Measured numbers from the existing PVM stack on commodity hardware:

Token transfer — the canonical real-world workload — showed no meaningful AOT advantage because RocksDB IO dominates. WASM-AOT sits in the same range as PVM-AOT on the same backend. The custom VM was not faster on the workloads that matter.

What we learned

The lessons that survived the pivot intact, expressed now in the WASM-era architecture:

1. The VM is not the bottleneck. Real blockchain throughput is signature verification + IO + consensus + network bandwidth, in roughly that order. The VM is the fifth contributor. A 10% VM-level slowdown is invisible to TPS.

2. Sandboxing, determinism, gas semantics matter. All three. The WASM execution layer enforces them via wasmtime's feature-flag config, fuel-based metering, and deploy-time validation. The Otigen-era discipline about these properties carried forward.

3. Author safety is a property of host functions, not language syntax. Reentrancy guards, checked arithmetic, type-safe storage access — all of these can be expressed as patterns in the WASM host-function ABI and the binding generators, without requiring authors to learn a new language. The current otigen toolchain (the binary; same name, new role) emits language-specific bindings that preserve these guarantees in Rust, AssemblyScript, Go, and C.

4. Compile-time access lists work, regardless of source language. The current architecture preserves access-list inference (from the binding generators deriving from otigen.toml) as a prefetch optimization within the uniform Block-STM scheduler; the lists are now produced by the binding generators from the otigen.toml state schema rather than by the Otigen compiler. Same property, different surface.

5. A custom language costs more than its benefit returns. The language was not Pyde's differentiator. The work spent on it was work not spent on the post-quantum consensus + crypto + state stack that actually is the differentiator. The pivot redirected that work.

What survived

A lot, in fact:

• The safety properties Otigen aimed for — reentrancy guards, checked arithmetic, typed storage, no tx.origin — are preserved in the host-function ABI and the binding generators.
• The compile-time access-list inference is preserved (now produced by the binding generators from otigen.toml). It now functions as a prefetch optimization in the uniform Block-STM scheduler rather than a scheduling mechanism; the lists are never used to partition execution.
• The state model (JMT, PIP-2 clustering, dual-hash) was already architecturally separate from the VM; no changes needed.
• The wave model, gas accounting, threshold encryption, and all the consensus-side properties were preserved without change.
• The otigen name itself — repurposed for the developer toolchain, where it now describes the role of "making the ergonomics layer feel coherent and opinionated."

The pivot was localized to the VM and the language. Everything around it stayed.

Where the original material lives

• The otigen-book — the canonical reference for the Otigen language. Preserved as a published historical artifact at pyde-net/otigen-book with a pivot-notice preface explaining the current status.
• otic compiler source — pyde-net/otic repo, archived (read-only).
• wright toolchain source — pyde-net/wright repo, archived (read-only).
• pyde-vm and pyde-aot crate source — archive/crates/pvm/ and archive/crates/aot/ in the umbrella repo, preserved with git history.
• Original Otigen-era documentation — archive/ more broadly contains the pre-pivot READMEs, design notes, and benchmark plans.
• Benchmark numbers — see the bench files in archive/crates/pvm/benches/ and archive/crates/aot/benches/. The numbers used in this document and in the preface were captured by running those benchmarks one final time before archival.

Reading on

• 01 — The HotStuff Consensus Era — the first pivot.
• Chapter 3: Execution Layer (WASM) — the current execution model.
• Chapter 5: Otigen Toolchain — the new role for the Otigen name.
• Preface: The Pivot — the narrative version of both pivots.

03 — Running the Pivot-Era Benchmarks

This document is the reproducer for the benchmark numbers cited in the pivot preface and in 02 — The Otigen Language Era.

The benchmarks measure the pre-pivot PVM execution layer (the now-retired pyde-vm interpreter and pyde-aot Cranelift-AOT compiler) in isolation. The benchmark code lives in the archive repository at archive/crates/pvm/benches/ and archive/crates/aot/benches/ (preserved after engine cleanup). You can run it today on any machine that has Rust installed.

The point of running these is not to validate Pyde TPS. The point is to see for yourself the relationship between interpreter throughput, AOT throughput, and storage-bound real-world workloads — the relationship that drove the WASM-pivot decision. The numbers favor WASM because they show that on storage-bound workloads (the ones that determine real chain TPS), the AOT advantage collapses, which means the VM choice does not move the needle.

Reference machine for the numbers in the book

If your machine is faster, you will see higher numbers. If slower, lower. The ratios (AOT-vs-interpreter speedup, storage-bound vs compute-bound) should hold across hardware.

Prerequisites

You need:

• A clone of the pyde-net/archive repository (where the retired pre-pivot crates live).
• A stable Rust toolchain. rustup install stable if you do not have it.

That is all. No extra build tools, no test fixtures to download.

Step by step

# 1. Get to the archive workspace.
cd <your-pyde-checkout>/archive

# 2. Run the PVM interpreter benchmark.
cargo bench -p pyde-vm --bench interpreter_bench

Expected output shape:

=== 0236: Interpreter throughput ===

--- ALU dispatch (no memory, no storage) ---

  Loop iterations:   100000
  Instructions/run:  800005
  Runs:              100
  Total time:        ~270-300ms (depends on CPU)
  Throughput:        ~280-300 million instructions/sec
  Latency:           ~3-4 ns/instruction

--- ALU dispatch (with trace recording) ---

  Throughput:        ~310-340 million instructions/sec
  (slightly faster than no-trace by design — see bench comments)

=== 0237: Token transfer execution time ===

--- Token transfer: setup cost ---
  Latency:           ~2-3 µs/setup

--- Token transfer: execution only ---
  Throughput:        ~220-240 thousand transfers/sec (execution only)
  Latency:           ~4-5 µs/transfer

--- Token transfer: full lifecycle ---
  Throughput:        ~140-160 thousand transfers/sec
  Latency:           ~6-7 µs/transfer

# 3. Run the AOT-vs-interpreter benchmark.
cargo bench -p pyde-aot --bench aot_bench

Expected output shape:

=== AOT vs Interpreter throughput ===

  Interpreter:        ~280 million instr/sec
  AOT:                ~2.9 billion instr/sec
  Speedup:            ~10x (compute-bound)

=== AOT Token Transfer ===

  Interpreter (exec only):   ~230 thousand transfers/sec
  AOT (exec only):           ~240 thousand transfers/sec
  Speedup:                   ~1.0x  (storage-bound — this is the point)

=== AOT DEX Swap (constant-product AMM) ===

  Interpreter:        ~27 million swaps/sec
  AOT:                ~100 million swaps/sec
  Speedup:            ~3.7x  (mixed compute + state)

=== AOT compilation time ===

      4 instructions:   ~50 µs
     16 instructions:   ~100 µs
     64 instructions:   ~250 µs
    256 instructions:   ~950 µs

That is everything. Two cargo-bench invocations, two text reports.

What the numbers mean — and what they don't

These are single-thread micro-benchmarks of the execution layer in isolation. There is no consensus running, no network, no parallel scheduling, no real RocksDB IO under sustained write pressure. They measure how fast one VM runs one workload on one thread.

What you should take from them:

• AOT crushes interpreter on tight compute (10× on ALU loops, 3.7× on AMM math). Cranelift is doing real work.
• AOT advantage collapses on storage-bound workloads (token transfer: 1×). This is the workload shape that dominates real blockchain throughput. The VM is not the bottleneck for real applications; storage IO is.
• The interpreter is already fast, around 280 million instructions per second on this hardware. Cold-cache execution paths in production do not have catastrophic latency.

What you should not take from them:

• These are not Pyde's TPS numbers. Full-chain TPS depends on consensus latency, signature verification throughput, network bandwidth, the parallel scheduler, and disk IO in addition to VM execution. Pyde's realistic v1 throughput target — awaiting the multi-region performance harness — reflects all of those layers combined, not just the VM.
• These do not include parallel execution. Each benchmark above runs one workload on one thread. The production scheduler runs many workloads in parallel via uniform Block-STM; wallet-attached access lists serve as prefetch hints to warm the cache before workers start. That compounds throughput but is measured separately by the full-chain harness, not here.
• These do not separate memory reads from memory writes, or from disk IO. The token-transfer benchmark exercises storage IO end-to-end as a single number; it does not isolate "Sload cost" from "Sstore cost" from "leaf-hash recomputation cost." That level of decomposition is the job of the per-component micro-benchmark suite (in flight; see below) and the full-chain performance harness.

More detailed benchmarks (in flight)

The benchmarks above are deliberately simple — they were enough to drive the pivot decision. A more sophisticated suite is part of the planned performance harness work, covering:

• Per-host-function micro-benchmarks — measuring the cost of each WASM host function (sload, sstore, transfer, threshold_*, hashing primitives, etc.) in isolation, so the gas-cost table can be calibrated against real hardware.
• Sequential vs parallel execution — measuring how the Block-STM parallel scheduler, optimized with access-list prefetch, scales with core count on workloads with various access-conflict ratios.
• Memory read vs memory write vs disk IO — splitting state-layer cost by category, so the JMT + RocksDB + write-back cache (PIP-4) stack can be profiled independently.
• Workload mixes — realistic blends of transfer / token-op / DEX / NFT-mint / encrypted txs, with the realistic-mix fraction tracked over time.
• Multi-region full-chain TPS — the end-to-end measurement with consensus, network, and IO all under load.

Those benchmarks live with the performance harness, not in the engine bench files. See the Performance Harness document for the full testing methodology, what's planned, and the publishing discipline that governs how numbers are released — publish only what the harness measures under sustained, production-realistic conditions, never lab extrapolations or microbenchmark peaks.

What you can do with this guide

• Reproduce the pivot-decision numbers on your own hardware — see the ratios for yourself.
• Sanity-check the WASM-pivot reasoning — confirm that storage-bound workloads neutralize the AOT advantage, the empirical observation that drives the "VM choice does not move TPS" claim.
• Establish a baseline for comparing future WASM-execution numbers — once the WASM execution layer ships, equivalent benchmarks can be run against it; the numbers should sit in the same ballpark (within ~10%) per the pivot's expected outcome.

Where the benchmark code lives

The benchmark files live in the archive repository under archive/crates/pvm/benches/ and archive/crates/aot/benches/ — preserved with git history intact, runnable indefinitely. When the WASM execution layer ships in the freshly-cut post-pivot engine repo, equivalent benchmarks will be added under wasm-exec/benches/ so the same workload shapes can be measured on the WASM stack for comparison.

Reading on

• Preface: The Pivot — narrative context for these numbers.
• 02 — The Otigen Language Era — the full design record for the system being benchmarked.
• Performance Harness — the multi-layer testing methodology that succeeds these micro-benchmarks.
• Chapter 3: Execution Layer — the WASM execution architecture that replaces what's being measured here.

Architecture Overview

System Architecture

Pyde is a monolithic Layer 1 — consensus, execution, and state in a single binary. Validators and full nodes run the same pyde process; role differentiation is configuration (whether the node stakes, whether it joins the active committee, whether it serves RPC).

┌─────────────────────────────────────────────┐
│ Application Layer                           │
│ WASM smart contracts, dApps, wallets, RPC   │
├─────────────────────────────────────────────┤
│ Execution Layer                             │
│ WebAssembly (wasmtime + Cranelift AOT),     │
│ Block-STM scheduler, MVCC, access-list      │
│ prefetch                                    │
├─────────────────────────────────────────────┤
│ State Layer                                 │
│ Jellyfish Merkle Tree (JMT), dual-hash      │
│ Blake3 + Poseidon2 per node, PIP-2 clusters │
├─────────────────────────────────────────────┤
│ Consensus Layer                             │
│ Mysticeti DAG, anchor selection, finality   │
├─────────────────────────────────────────────┤
│ Cryptography Layer                          │
│ FALCON-512, Kyber-768 threshold, DKG        │
├─────────────────────────────────────────────┤
│ Network Layer                               │
│ libp2p + QUIC, Gossipsub, worker/primary    │
└─────────────────────────────────────────────┘

Worker / Primary Split (Narwhal Pattern)

Within each validator, the consensus role is split:

• Workers (N processes per validator): handle transaction ingress, build batches of incoming transactions, gossip batches peer-to-peer with other validators' workers
• Primary (one process per validator): handles consensus — produces vertices each round, gathers parent references, signs state roots

This separation decouples high-volume data dissemination from low-volume consensus structure. Transactions travel the network exactly once (via worker gossip); consensus vertices stay tiny (carry only batch hashes by reference).

┌────────────────────────────────────────────────────┐
│ Validator Process                                  │
│                                                    │
│  ┌──────────────┐    ┌──────────────────────────┐ │
│  │   Workers    │    │       Primary            │ │
│  │  (1 or more) │◄───┤  - Produces vertices     │ │
│  │              │    │  - Tracks DAG            │ │
│  │ - Tx ingress │    │  - Signs state roots     │ │
│  │ - Build      │    │  - Runs DKG ceremonies   │ │
│  │   batches    │    │  - Executes WASM         │ │
│  │ - Gossip     │    └──────────────────────────┘ │
│  │   batches    │                                  │
│  └──────────────┘                                  │
└────────────────────────────────────────────────────┘

Workers can be scaled independently of the primary. A validator with high incoming traffic can run 4-8 workers; a quieter validator can run 1.

Consensus: Mysticeti DAG

Pyde's consensus is a Mysticeti-style DAG protocol. Every round (~150ms), each committee member's primary produces exactly one vertex. The vertex contains:

• Batch hashes (data layer references)
• 85+ parent vertex hashes (consensus structure, from prior round)
• State root signatures (attestations on recent commits)
• Anchor attestation (prior round's anchor vertex hash)
• Decryption shares (piggybacked partial decryptions)
• FALCON signature

Vertices form a Directed Acyclic Graph: parents must be strictly from prior rounds. This is purely a consensus structure; transaction data lives in batches referenced by hash.

Each round has a deterministically-selected anchor:

anchor_member = Hash(beacon, round, prev_state_root) mod 128

When the anchor vertex collects sufficient support from later rounds (Mysticeti 3-stage support), a commit fires. ~95% of rounds commit successfully; ~5% skip (next round absorbs the skip).

End-to-end commit latency: ~500ms median.

Execution: WebAssembly + Block-STM

After consensus commits a wave (canonical ordered transactions), the execution layer:

1. Threshold decryption for encrypted transactions (≥85 partials combined per tx)
2. Access-list prefetch — one batched state_cf.multi_get (PIP-3) over the union of every tx's declared (addr, slot) pairs lands warm values in the dashmap (PIP-4) before workers start. The lists are hints only; they never partition the wave or affect correctness.
3. Block-STM scheduler runs every tx in parallel on a rayon pool: optimistic execute against an MVCC layer + validate against canonical tx_index order + cascade-invalidate + re-incarnate on conflict + fixpoint. Final state per slot is the highest-tx_index's last write. Full algorithm in companion/BLOCK_STM_EXECUTION.md.
4. wasmtime executes each tx with Cranelift AOT and fuel-based gas metering. Smart contracts compile from Rust, AssemblyScript, Go, or C/C++ to WASM.
5. State root computed — dual-hash (Blake3 + Poseidon2) per JMT node
6. Committee FALCON-signs state root (piggybacked on next vertices)
7. Finality when ≥85 state root signatures collected

State: Jellyfish Merkle Tree

Account state and contract storage are stored in a Jellyfish Merkle Tree (JMT) — radix-16, path-compressed. Compared to a fixed-depth-256 Sparse Merkle Tree:

• ~5-10 nodes touched per state operation (vs ~256)
• Substantial I/O savings at high TPS
• Same authentication properties (Merkle commitment, inclusion / exclusion proofs)
• Production-proven (Diem, Aptos)

State commitment is dual-rooted:

• Blake3 root: fast native verification (committee + validators)
• Poseidon2 root: ZK-circuit-friendly (future light clients, validity proofs)

Cryptography Layer

Three primitives form the cryptographic foundation:

FALCON-512 (Signatures)

NIST FIPS 206 standard. Used for: user tx authorization, vertex production, state root attestations, decryption share authentication. 666-byte signature, ~80μs verification.

Kyber-768 Threshold (Encryption)

NIST FIPS 203 standard with threshold variant. Per-epoch public key from DKG; ≥85 partials decrypt any ciphertext. Enables encrypted-mempool MEV resistance.

Poseidon2 + Blake3 (Hashing)

Hybrid layered: Blake3 for high-volume native paths (JMT internals), Poseidon2 for ZK-bearing paths (state root commitment exposed to future ZK proofs, address derivation, FALCON sig hashing inside ZK circuits).

Network Layer

• Transport: QUIC over UDP (no HOL blocking, TLS 1.3 built-in, mature in Rust via quinn). TCP fallback.
• P2P library: libp2p (Rust) — mature, audited, used by Ethereum/Filecoin/Polkadot
• Peer discovery: layered (hardcoded → DNS → on-chain validator registry → PEX → cache). No DHT.
• Gossip: Gossipsub with per-topic meshes
• DoS protection: 4-layer (connection / message / peer-scoring / application)
• Committee defense: sentry node pattern (Cosmos-style)

Committee NIC requirement at v1's honest throughput target (to be established by the multi-region performance harness) is ≥500 Mbps. Higher-throughput regimes are post-mainnet scaling work; the v1 target is what mainnet hardware is sized against.

Account Model

Accounts hold:

• nonce (8 bytes)
• balance (16 bytes, u128)
• gas_tank (16 bytes — pre-deposited gas for encrypted submission)
• auth_keys (variable: Single | Multisig | Programmable)
• code_hash (32 bytes, for contracts)
• storage_root (32 bytes, JMT subtree for contract storage)
• key_nonce (4 bytes, FALCON key rotation counter)

Native multisig at v1 — AuthKeys::Multisig(M, [pubkey_1, ..., pubkey_N]) with max 16 signers. Better than Gnosis Safe contract-multisig (Ethereum), which reimplements the same logic with subtle bugs across projects.

Programmable accounts and session keys ship post-mainnet. v1 reserves the Programmable enum variant so contracts written today survive the upgrade without rewriting.

16-slot nonce window — accounts can have up to 16 transactions in-flight out-of-order within the window. Decouples user-level submission from consensus-level execution ordering.

Transaction Lifecycle

1. Wallet constructs tx
2. Wallet → RPC: pyde_estimateAccess(tx) → returns gas_estimate + access_list
3. Wallet attaches access_list to tx
4. Wallet FALCON-signs tx hash
5. (Optional) Wallet encrypts signed_tx + access_list with epoch Kyber PK
6. Wallet submits: pyde_sendRawTransaction or pyde_sendRawEncryptedTransaction
7. RPC node validates wire format, forwards to nearest worker
8. Worker (plaintext) verifies sig, batches, gossips
9. Primary produces vertex, gossips
10. Commit fires (Mysticeti, sub-second target): anchor selected, subdag walked, canonical order emitted
11. (Encrypted) threshold decryption ceremony per encrypted tx (batches contain a mix of plaintext + encrypted txs)
12. wasmtime executes WASM modules in canonical order
13. JMT updates (dual-hash per node), state root signed
14. Finality declared (≥85 state root sigs)

Cross-Chain (Post-Mainnet)

Cross-chain interactions happen through a permissionless parachain layer — operators implement a Pyde-published specification, stake PYDE, follow protocol rules, and earn gas fees from contracts that call them via the cross_call! macro.

The protocol-level surface (cross_call! macro, HardFinalityCert primitive, unified gas model) is settled at v1 genesis. The actual parachain layer ships post-mainnet.

Three-Tier Node Model

RPC providers (Infura/Alchemy analog) fit Tier 3 — no stake, no slashing risk.

Key Differentiators

Next Chapters

• Chapter 3: Execution Layer — wasmtime runtime, host function ABI, Cranelift AOT, fuel-based gas, determinism boundary
• Chapter 4: State Model — JMT details, dual-hash strategy, PIP-2 clustering
• Chapter 5: Otigen Toolchain — the developer-facing binary (build, deploy, wallet, ABI extraction, per-language attribute declaration)
• Chapter 6: Consensus — full Mysticeti DAG specification
• Chapter 7: State Sync & Chain Halt — operational protocols
• Chapter 8: Cryptography — FALCON, Kyber, Poseidon2, DKG, threshold details
• Chapter 9: MEV Protection — threshold encryption + commit-before-reveal architecture

Chapter 3: Execution Layer

Pyde's execution layer is WebAssembly via wasmtime, with ahead-of-time compilation through Cranelift. Smart contracts and parachains run in sandboxed wasmtime instances, interacting with the chain through a fixed set of host functions that the engine implements in Rust.

This chapter covers the runtime architecture, the host function ABI surface, how compilation and caching work, gas metering, the determinism boundary, and the performance properties of the layer.

For context on why Pyde uses WebAssembly rather than a custom virtual machine, read the preface (The Pivot).

3.1 Why WebAssembly

WebAssembly was designed to be a compilation target: a small, well-specified, sandboxed instruction set that any source language can lower into and any runtime can execute deterministically. For Pyde, this gives us four properties simultaneously, none of which a custom VM could deliver without years of additional work.

1. Universal language support. Authors write contracts in whatever language they already know. Rust is the primary path; AssemblyScript, Go (via TinyGo), and C/C++ (via clang's --target=wasm32) are first-class alternatives. The chain does not impose a language preference.

2. Battle-tested runtime. Wasmtime is maintained by the Bytecode Alliance, used in production at Fastly, Microsoft, and Shopify, continuously fuzzed under adversarial workloads, and audited as a security-critical system. Pyde inherits this hardening at zero engineering cost.

3. Strong sandbox. WebAssembly's linear memory model and structured control flow eliminate entire categories of vulnerabilities (buffer overflows, control-flow hijacks, type confusion). The validation step at module load rejects any malformed binary before it can run. Importing forbidden functions (network, filesystem, threads) is gated at deploy time.

4. ZK-ready path. Active research on zero-knowledge proving of WebAssembly execution (zk-WASM) is converging on practical provers within a multi-year horizon. Pyde's contract bytecode is positioned to benefit from this without re-tooling — when zk-WASM provers mature, they slot in as an attestation layer over execution that has already happened.

The price for these properties: a small overhead on the order of 5-15% relative to a hand-tuned custom VM on tight compute loops, vanishing entirely for storage-bound workloads where the VM is not the bottleneck. The performance section at the end of this chapter quantifies this with real numbers.

3.2 Runtime Architecture

Execution sits inside the wasm-exec crate of the engine workspace. The crate exposes a single WasmExecutor type that owns the wasmtime engine, the compiled-module cache, and the host function bindings. The transaction pipeline calls into WasmExecutor per invocation; the executor handles the rest.

┌────────────────────────────────────────────────────────────┐
│  Engine transaction pipeline                                │
│  (mempool → Block-STM scheduler [with access-list prefetch] │
│   → execution dispatch)                                     │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
              ┌───────────────┐
              │ WasmExecutor   │  ← single per node, owned by node
              └──────┬────────┘
                     │
       ┌─────────────┼──────────────────┐
       ▼             ▼                  ▼
  ┌─────────┐  ┌──────────┐     ┌─────────────────┐
  │ wasmtime │  │ Module    │     │ Host functions  │
  │ Engine   │  │ cache     │     │ (host_fns.rs)   │
  │ (Crane-  │  │ (per-     │     │ — sload         │
  │  lift)   │  │ contract) │     │ — sstore        │
  └─────────┘  └──────────┘     │ — transfer       │
                                  │ — emit_event    │
                                  │ — threshold_*    │
                                  │ — hash_*         │
                                  │ — cross_call    │
                                  │ — ...            │
                                  └─────────────────┘
                                            │
                                            ▼
                                  ┌─────────────────┐
                                  │ JMT state, fee  │
                                  │ accounting,     │
                                  │ event log, etc. │
                                  └─────────────────┘

WasmExecutor responsibilities:

• Hold the wasmtime Engine (singleton, configured at startup with deterministic feature flags).
• Cache compiled Modules by contract address (compile once, reuse across invocations).
• Instantiate per-invocation Stores with isolated linear memory and the current execution context.
• Wire host function calls through the linker.
• Track fuel consumption (gas).
• Handle trap conditions and propagate them as transaction failures.

Engine configuration (set once at node startup):

#![allow(unused)]
fn main() {
let mut config = wasmtime::Config::new();
config.strategy(wasmtime::Strategy::Cranelift);
config.cranelift_opt_level(wasmtime::OptLevel::Speed);
config.consume_fuel(true);
config.epoch_interruption(true);

// Determinism enforcement:
config.cranelift_nan_canonicalization(true);
config.wasm_threads(false);
config.wasm_simd(false);
config.wasm_relaxed_simd(false);
config.wasm_reference_types(false);
config.wasm_bulk_memory(true);  // safe, deterministic, useful
config.wasm_multi_memory(false);
config.wasm_memory64(false);
config.wasm_function_references(false);
config.wasm_gc(false);
config.wasm_component_model(false);
// (No WASI imports allowed; not enabled at all.)
}

This config produces deterministic execution suitable for consensus: every validator running the same module on the same input produces bit-identical state changes and identical fuel consumption.

3.3 The Host Function ABI

Smart contracts cannot directly access state, signatures, or anything outside their sandbox. They reach the chain through host functions — Rust functions registered with wasmtime's linker that contracts call by name. The full set of host functions is the Host Function ABI, versioned and documented in the canonical Host Function ABI v1.0 Specification.

This section gives the conceptual surface; the spec gives the binary signatures.

Storage:

• sload(slot_ptr, out_ptr, out_max_len) -> i32 — read a slot. Slot keys are 32 bytes (Poseidon2 of the contract address ‖ logical slot ID); slot values are variable-length raw bytes, up to MAX_STORAGE_VALUE_BYTES = 16 KB. Caller passes a max length and an out-pointer; host writes min(actual, out_max_len) bytes and returns the actual length (or SLOAD_MISSING = -1 for a never-written slot).
• sstore(slot_ptr, val_ptr, val_len) -> () — write a slot. val_len is arbitrary up to the 16 KB cap; exceed it and the host fn traps. Costs are GAS_SSTORE_BASE = 5_000 + 32/byte value (the per-byte component is what makes large writes proportionally expensive).
• sdelete(slot_ptr) -> () — explicitly delete a slot (lower cost than sstore; no refund in v1, per Chapter 10).

Why variable-length values, not EVM-style 32-byte words. Pyde isn't word-oriented at the VM level — WASM operates on linear memory, not 256-bit words. Forcing slot values into 32 bytes would (a) require contracts to manually pack/unpack any non-uint256 data, and (b) burn one slot per logical field regardless of size, blowing up state-tree node count for the common case of small structs. The variable-length model lets a contract Borsh-encode an entire small struct into one slot (e.g. a Position { trader, size, entry, leverage } at ~80 bytes → one slot, one read, one decode) — closer to a key-value store than a word array. For larger logical values, contracts use standard chunking patterns: slot[H(base ‖ i)] = chunk_i for chunked sequential data, or slot[H(base ‖ key)] = value for mapping-style access. The 16 KB cap is a RocksDB write-amplification budget (per-slot write costs scale with size; >16 KB starts to hurt LSM compaction); it's a chain-spec parameter, tunable via a future PIP if real workloads demand it.

Balances and transfers:

• balance(addr) -> u128 — read an account's PYDE balance.
• transfer(to_addr, amount) — move PYDE from the caller to to_addr. Fails if insufficient balance.

Execution context:

• caller() -> addr — the address that invoked the current call.
• origin() -> addr — the externally-owned address that initiated the transaction. (Deliberately distinct from caller() to avoid the tx.origin footgun from Ethereum.)
• wave_id() -> u64, wave_timestamp() -> u64.
• chain_id() -> u64.

Events:

• emit_event(topic, data) — append a 32-byte topic + opaque bytes payload to the transaction's event log. Each event is buffered in the current overlay (per-tx, per-cross-call); reverted (sub-)calls' events are discarded. At wave commit, all surviving events are committed via events_root (Merkle tree) + events_bloom in the wave commit record. Recommended encoding for data is Borsh; topics are typically Blake3(canonical_event_signature). Full storage / indexing / subscription mechanics: see Host Function ABI Spec §15.

Hashing primitives:

• hash_keccak256(input) -> hash32 — for compatibility with cross-chain interfaces.
• hash_blake3(input) -> hash32 — fast general-purpose hashing.
• hash_poseidon2(input) -> hash32 — ZK-friendly hashing (used in state commitments).

Post-quantum cryptography:

• threshold_encrypt(plaintext) -> ciphertext — encrypt a payload under the current committee's threshold key. Available to parachains only.
• threshold_decrypt(ciphertext) -> plaintext — combine pre-collected committee shares to decrypt. Available to parachains only.
• falcon_verify(pubkey, message, signature) -> bool — verify a FALCON-512 signature.

Cross-contract calls:

• cross_call(target, fn_name, calldata, value, gas_limit, ...) — synchronous call into another contract. Sub-call runs in a nested overlay; merges on success, discards on trap.
• cross_call_static(target, fn_name, calldata, gas_limit, ...) — view-only sub-call. Free for the caller (only the 50-gas dispatch base charged); bounded by a per-call VIEW_FUEL_CAP (default 10M fuel ≈ 3ms commodity).
• delegate_call(target, fn_name, calldata, gas_limit, ...) — execute target's code in the caller's storage context. self_address() and caller() preserve outer-call identity. For proxy / upgradeable patterns.

Randomness:

• beacon_get() -> hash32 — current wave's committee-derived VRF beacon (XOR of all members' beacon shares). Deterministic across validators, publicly readable.

Gas:

• consume_gas(amount) — explicit metering for operations the runtime cannot price automatically (used by binding generators for collection-traversal patterns).

Forbidden by design:

• Network calls (any kind).
• Filesystem access.
• System clock (use wave_timestamp instead — deterministic).
• Non-deterministic entropy (use a VRF-based host function when randomness is needed).
• Direct RocksDB access (everything routes through sload/sstore).

The deploy-time validator rejects any WASM module whose import section references functions outside this allowlist. Hard-enforced.

3.4 Compilation and Caching

The wasmtime engine compiles WebAssembly bytecode to native machine code via Cranelift. Compilation is expensive (tens to hundreds of milliseconds per contract); execution after compilation is fast. The cache strategy makes this acceptable.

Compilation lifecycle:

Deploy time
  │
  ├─ Wasm bytes submitted with deploy transaction
  ├─ Engine validates bytes (wasmtime::Module::validate)
  ├─ Engine rejects forbidden imports
  ├─ Engine compiles bytes via Cranelift → Module
  ├─ Engine serializes Module to bytes (Module::serialize)
  ├─ Engine stores both source bytes AND serialized Module in state
  └─ Contract is live

Subsequent invocations
  │
  ├─ Engine looks up contract address in module cache
  │     ├─ Hit: use cached Module immediately
  │     └─ Miss: read serialized Module from state, deserialize, cache it
  ├─ Engine creates per-invocation Store with execution context
  ├─ Engine instantiates Module against Store (sub-millisecond)
  └─ Engine calls the entry function

Cache properties:

• In-memory cache keyed by contract address.
• LRU-style eviction with a configurable size budget (default ~256 modules resident).
• Serialized modules persist on disk so cold validators warm quickly.
• On contract upgrade, the cache entry is invalidated; the new module is compiled and cached on next use.

Per-contract compilation cost (measured on commodity hardware against PVM-era proxies; WASM-era numbers to be re-measured):

• A simple contract (~100 instructions): ~10ms.
• A medium contract (~1000 instructions): ~50-100ms.
• A large contract (~10000 instructions): ~500ms-1s.

These costs are paid once per contract per node restart, then amortized across all subsequent invocations.

3.5 Gas Metering

Pyde uses wasmtime's fuel mechanism for gas accounting. Fuel is a per-execution budget; every WebAssembly instruction consumes a configurable amount of fuel, and execution traps when fuel reaches zero. Host function calls also consume fuel manually (charged by the host based on operation cost — sstore is heavier than add, for example).

Gas-to-fuel mapping: At node startup, the engine establishes a deterministic mapping from gas units (the chain-level metering unit) to wasmtime fuel units. The mapping accounts for:

• Per-instruction baseline cost (each WASM instruction costs a fixed amount of fuel).
• Per-host-function cost (specific to each host function, defined in the ABI gas table).
• Per-byte storage costs (sload reads, sstore writes, allocation surcharge for new slots).
• Per-byte event emission cost.

A transaction declares its gas budget at submission; the engine converts that to fuel and runs the contract with that fuel limit. The fuel actually consumed is converted back to gas for the transaction receipt.

Why fuel and not opcode-counting: Fuel is built into wasmtime's Cranelift backend. Every basic block is instrumented to decrement a fuel counter; when the counter goes negative, execution traps with an out-of-fuel error. The instrumentation is efficient enough not to dominate execution time. Implementing custom opcode-counting on top of wasmtime would be slower and add maintenance burden for no functional gain.

Charging model — no refunds in v1: The ingress check confirms balance ≥ gas_limit × base_fee, but only gas_used × base_fee is actually debited at execution time. Unused fuel costs the sender nothing — it is never debited and therefore never refunded. Pyde v1 has no operation-level gas refunds either (no sstore_refund, no sdelete refund). See Chapter 10 §10.1 for the full charging pipeline and the EIP-3529 reasoning.

3.5b Per-Transaction Execution Isolation

Every transaction executes against an overlay layered on top of the shared DashMap state cache. The overlay isolates the tx's writes and its emitted events so a revert can throw them away without affecting other txs in the same wave.

Per-tx isolation:

  Before tx execution:
    tx_overlay: {
      state_writes: HashMap<SlotHash, Vec<u8>>,
      events:       Vec<EventRecord>,
    } = empty

  During execution:
    Reads (state):
      1. check tx_overlay.state_writes  (any writes this tx made)
      2. check dashmap                   (prior committed-in-this-wave writes from other txs)
      3. check state_cf                  (current persistent state on disk)
    Writes (state):
      go into tx_overlay.state_writes only (not dashmap yet)
    emit_event:
      append to tx_overlay.events only

  On successful completion:
    merge tx_overlay.state_writes into dashmap (marking entries Dirty)
    append tx_overlay.events to the wave's canonical events list
    generate success receipt
    drop tx_overlay (memory freed)

  On trap (revert):
    discard tx_overlay entirely — state AND events
    state unchanged in dashmap
    no events emitted to the wave's list
    generate revert receipt with reason
    sender still pays gas_used × base_fee (see Chapter 10)

Events follow the same merge/discard discipline as state writes. A reverted (sub-)call's events are discarded along with its state writes — the chain never sees events from a path that didn't commit. The wave's final events list (committed via events_root + events_bloom; see Host Function ABI Spec §15) is the topmost overlay's events buffer at wave commit time.

Why no separate undo log: failed writes never landed in shared state. Dropping the overlay throws them away. Simpler than journaled undo.

Nested cross-calls: when tx A calls contract B which calls contract C, each call gets its own overlay layered on top:

A's overlay
  ↓
B's overlay (reads check B's overlay first, then A's, then dashmap, then state_cf)
  ↓
C's overlay (reads check C's, then B's, then A's, then dashmap, then state_cf)

Inner call succeeds → merge inner overlay into parent overlay
Inner call traps    → drop inner overlay; parent continues
Outer tx traps      → drop outer overlay (including all merged inner state)

This is standard transactional-memory layering. wasmtime's host functions are aware of the active overlay and route reads/writes through it.

Memory bounds on the overlay

The overlay can grow during a tx, but is bounded by two factors:

1. Gas budget. Every write into the overlay charges fuel via sstore. A tx with gas_limit = 10_000_000 can write at most ~50K slots (varying by slot size). Author can't write infinitely without paying.

2. Linear memory cap. wasmtime's per-instance linear memory is capped (64MB default, configurable per chain release). Even if gas were infinite, the WASM module can't allocate beyond this cap.

Together: a tx can use up to (gas_limit / sstore_cost) × value_size of overlay memory, but capped by linear memory. We don't impose a separate "tx overlay memory cap" — gas + wasmtime config bound it.

3.6 The Determinism Boundary

For consensus to hold, every validator must produce bit-identical state changes when executing the same transaction. This requires deterministic execution at every layer.

Deterministic-by-default in WebAssembly:

• Integer arithmetic (well-specified, no platform-dependent behavior).
• Memory operations (bounds-checked, no undefined behavior).
• Control flow (structured, no goto, no jump tables that vary by platform).

Determinism risks WebAssembly admits, which we disable:

• Floating-point: most operations are deterministic by IEEE-754, but NaN bit patterns can vary. We enable cranelift_nan_canonicalization so NaN outputs are canonicalized identically across all validators.
• Threads: non-deterministic by definition; we disable the threads proposal.
• SIMD: most SIMD is deterministic, but certain operations (relaxed SIMD) are not. We disable both the SIMD and relaxed-SIMD proposals for now; we may re-enable a deterministic-only SIMD subset in a future version.
• Reference types, GC, function references, component model: complexity surface we don't need yet, disabled.

Determinism risks the runtime introduces, which we control:

• Module compilation may produce different machine code on different platforms (different architectures, different Cranelift versions). We pin the wasmtime version per chain release and require validators to upgrade in coordinated forks. Cached serialized modules are not portable across versions.
• Fuel consumption per host function is defined in the gas table, identical across validators.

What contracts cannot observe:

• Wall-clock time. Use wave_timestamp (deterministic, set by consensus).
• True randomness. Use a VRF-derived host function when randomness is required (deterministic per block, unpredictable beforehand).
• The host machine. No CPU info, no OS info, no environment access.

Deploy-time validation: Every contract's WASM is validated at deploy time against the determinism rules. Any module that imports a forbidden function, uses a disabled feature, or fails wasmtime's structural validator is rejected. The validation gate is non-negotiable — it prevents bad code from ever reaching consensus.

3.7 State Access from the Author's Perspective

Host functions are low-level: they take pointers + lengths into WASM linear memory and return raw bytes. Contract authors write the slot derivation themselves in their source language, following the PIP-2 slot layout described in Chapter 4: State Model. The otigen toolchain does NOT generate code; authors write a small helper module (or copy one from a canonical example) that turns ergonomic API calls into the right pyde_storage_read / pyde_storage_write host calls.

The pattern (in Rust):

#![allow(unused)]
fn main() {
// Author writes (or copies from the canonical example):

// 1. Host function imports (one-time declaration):
extern "C" {
    fn pyde_storage_read(slot_hash_ptr: *const u8, slot_hash_len: usize) -> i64;
    fn pyde_storage_write(slot_hash_ptr: *const u8, slot_hash_len: usize, value_ptr: *const u8, value_len: usize);
    fn pyde_poseidon2(input_ptr: *const u8, input_len: usize, out_ptr: *mut u8);
}

// 2. Contract-name prefix, derived once at startup:
//    (Rust patterns include lazy_static!, OnceCell, const fn — author's choice.)
fn contract_addr_prefix() -> &'static [u8; 16] { /* ... */ }

// 3. Discriminator constants from otigen.toml [state] section:
const BALANCE_DISC: u8 = 0;       // matches [state] balance.disc

// 4. Slot derivation following PIP-2 layout (address[..16] || hash(disc||key)[..16]):
fn balance_slot(addr: &[u8; 32]) -> [u8; 32] {
    let mut slot = [0u8; 32];
    slot[..16].copy_from_slice(contract_addr_prefix());
    let mut input = [0u8; 33];
    input[0] = BALANCE_DISC;
    input[1..].copy_from_slice(addr);
    let mut inner = [0u8; 32];
    unsafe { pyde_poseidon2(input.as_ptr(), input.len(), inner.as_mut_ptr()); }
    slot[16..].copy_from_slice(&inner[..16]);
    slot
}

// 5. Ergonomic accessor (author writes this small wrapper):
fn read_balance(addr: &[u8; 32]) -> u128 {
    let slot = balance_slot(addr);
    let mut value = [0u8; 32];
    unsafe { /* call pyde_storage_read, copy into value */ }
    u128::from_le_bytes(value[..16].try_into().unwrap())
}
}

Where the hashing happens:

• The contract-name prefix (contract_addr_prefix()) is computed once at startup using whatever caching pattern the author's language provides. Rust authors use OnceCell / lazy_static! / a const fn if possible. AssemblyScript uses a module-level constant initializer. Go uses init(). C uses a static const array initialized at first call. After the first computation, it's free.
• The discriminator (BALANCE_DISC = 0) is a compile-time constant — never re-hashed.
• The dynamic part (the addr argument) is hashed at runtime — one pyde_poseidon2 call per slot reference. That's the irreducible cost.

This is the same end-state as if otigen were generating bindings — same hash count at runtime, same memory layout, same gas profile. The difference: the author owns the code, can inspect it, can audit it, can replace pieces with optimized hot-path versions, and isn't dependent on a chain-team-maintained code generator. The canonical example projects in pyde-net/otigen ship one workable pattern per supported language as a starting point.

The same pattern adapts to AssemblyScript, Go (TinyGo), and C/C++ — each language has its own idioms for module-level constants, lazy initialization, and FFI to host functions. See pyde-net/otigen/examples/ for a working version in each language.

3.8 Performance Characteristics

The honest numbers, measured against PVM-era proxies (WASM-era numbers will replace these as benchmarks are re-run):

Compute-bound workloads (tight ALU loops):

• Wasmtime AOT runs within roughly 80-95% of native code on most workloads. Measured benchmarks on PVM-era code showed AOT throughput around 2.9 billion instructions per second for ALU dispatch; wasmtime-AOT sits in the same range because both use the same Cranelift backend.
• Interpreted execution (cold cache, no AOT yet) runs at roughly 10-30% of native. Pyde's WASM interpreter path is similar in throughput to the previous PVM interpreter measured at ~279 million instructions per second.

Storage-bound workloads (typical real-world smart contracts):

• The AOT-vs-interpreter advantage collapses. Token transfers measured around 231K tps interpreted and 243K tps AOT — essentially identical, because RocksDB IO dominates and neither the interpreter nor the AOT can speed it up.
• This is the workload shape that actually determines blockchain throughput. The VM choice barely affects it.

Module compilation:

• Sub-millisecond for small contracts.
• ~1 second for the largest realistic contracts.
• Paid once per contract per node startup, then cached forever.

End-to-end TPS: The v1 honest throughput target on commodity validator hardware (for both the plaintext and encrypted regimes) is to be established by the multi-region performance harness — it comes from the full-chain harness (consensus + execution + state + network), not from VM microbenchmarks alone. The VM is approximately the fifth-most-important contributor to that number, behind signature verification, network bandwidth, consensus latency, and disk I/O.

The publishing discipline applies: published TPS numbers are derived conservatively from sustained measurement under realistic conditions, never from microbenchmark peaks or lab extrapolations.

3.9 Failure Modes and Traps

When a contract execution fails, it traps. The transaction reverts, no state changes persist, the sender pays gas up to the trap point.

Trap conditions:

• Out of fuel — exceeded the transaction's gas budget.
• Out of bounds — WASM linear memory access outside allocated range.
• Integer overflow (when checked arithmetic is requested by host function gating).
• Forbidden import attempt — caught at deploy, not at runtime; deploy fails instead.
• Stack overflow — wasmtime's configurable stack limit reached.
• Unreachable — the WebAssembly unreachable instruction was executed (typically Rust's panic!() lowers to this).
• Host function error — sstore to a write-locked slot, transfer with insufficient balance, etc.

Engine-level protections:

• Per-call wall-clock timeout (epoch interruption). Prevents a buggy contract from spinning forever even if fuel accounting is somehow bypassed.
• Per-call linear memory limit (capped well below host memory).
• Per-call stack depth limit.

Trap conditions are reported in transaction receipts as structured error codes, queryable by clients.

3.9b Native Transactions vs WASM Calls

Not every transaction invokes wasmtime. Pyde has a small set of native transaction types that the engine executes directly, without WASM overhead.

Native tx types (no wasmtime invocation)

- Transfer        — move PYDE between two accounts; ~21,000 gas; engine handles balance update directly
- ValidatorRegister — stake-account-binding system tx
- ValidatorUnbond  — initiate unbonding
- ValidatorRotateKey — FALCON key rotation
- ValidatorUnjail   — exit jailed state after grace period
- Multisig          — treasury / governance multisig spend
- Slashing          — system-emitted from evidence

These all bypass wasmtime and execute as Rust code in the engine. They're cheaper, faster, and don't carry the per-tx WASM instantiation cost.

WASM tx types (wasmtime executes)

- ContractCall    — invoke a function on a deployed WASM contract
- ContractDeploy  — register new WASM bytes + ABI as a contract
- ParachainCall   — invoke a function on a deployed parachain WASM (cross-call routing)

These instantiate the target module via wasmtime, call the entry function, execute under the per-tx overlay, and produce a receipt.

Why split this way

• Performance. Simple transfers don't need a sandbox or fuel metering — they're trivially provable state updates.
• Gas predictability. Native transfers have a fixed gas cost (~21K) known in advance; no fuel-counting needed.
• Common-case optimization. Simple value transfers are the most common tx type on any chain. Avoiding WASM overhead per-transfer materially improves end-to-end TPS for high-volume payment workloads.

WASM contracts that need to move value internally still call pyde_transfer as a host function, which does the same balance-update logic the native transfer does. Authors don't have to choose; the chain serves both paths.

3.10 Contract Lifecycle

Author writes contract → otigen build → .wasm + ABI
       │
       ▼
Author runs otigen deploy
       │
       ├─ Pays registration fee for name (ENS-style, see Account Model chapter)
       ├─ Pays owner deposit (forfeit on misbehavior)
       └─ Submits deploy tx with .wasm bytes
              │
              ▼
       Engine validates module (validator, deterministic-features gate, import allowlist)
              │
              ▼
       Engine compiles via Cranelift, caches serialized module
              │
              ▼
       Engine writes (contract_address → wasm_hash, serialized_module, owner, deposit) to state
              │
              ▼
       Contract is live; callable by anyone holding its address or name

Upgrade path mirrors deploy but routes through governance for parachain contracts. Smart contracts (non-parachain) follow a simpler owner-only upgrade flow with grace periods to give users time to verify the new code.

3.11 Where the Code Lives

The WASM execution layer is implemented post-pivot in a fresh engine workspace that does not exist yet. The pre-pivot pvm and aot crates are preserved in pyde-net/archive for historical reference and bench comparison. The table below names the components and their planned crate layout once the fresh engine repo is cut.

3.12 Open Questions

These are tracked as planned work and resolved as the execution layer matures:

• Re-enabling deterministic SIMD. Pyde currently disables SIMD entirely. A deterministic SIMD subset (excluding relaxed operations) would benefit crypto-heavy contracts. Pending implementation work and conservative validation.
• WASM module hash-content-addressing. Two contracts with identical WASM bytes could share a single compiled module entry. Optimization opportunity; not blocking.
• zk-WASM proving integration. When zk-WASM provers reach production quality, slot one in as an optional execution attestation layer. Tracked as a v2/v3 direction.
• Hot-reload of compiled modules across version pins. Currently a wasmtime version bump invalidates the cache; coordinated upgrades are required. Hot-reload research may relax this.

3.13 Reading on

• Chapter 4: State Model — how sload and sstore reach the JMT.
• Chapter 5: Otigen Toolchain — how authors interact with the execution layer through the developer tool.
• Chapter 6: Consensus — how execution outcomes commit to the chain.
• Chapter 8: Cryptography — what FALCON, Kyber, and Poseidon2 actually do, and how the host functions expose them.
• Preface: The Pivot — why the execution layer is WebAssembly rather than a custom VM.

Chapter 4: State Model

Every blockchain is a replicated state machine. Transactions transform state; consensus ensures every honest node agrees on the result. The quality of the state model decides how fast you commit, how cheap you sync, and how well you parallelize execution.

Pyde stores all state in a Jellyfish Merkle Tree (JMT), persisted in RocksDB, with hybrid hashing: Blake3 on high-volume native paths, Poseidon2 on ZK-bearing paths. The state commitment is dual-rooted — Blake3 for fast native verification by committee and validators, Poseidon2 for future ZK light clients and validity proofs.

The JMT replaces the fixed-depth Sparse Merkle Tree the project initially shipped — a swap made because JMT's radix-16 path compression delivers roughly 40× faster commits. Hybrid hashing was adopted post-pivot once the performance cost of running Poseidon2 over every internal JMT node became clear; Blake3 is ~50× faster on commodity CPUs without sacrificing the ZK-friendly properties where they matter (state root, address derivation, FALCON-sig-hashing inside circuits).

4.1 The Jellyfish Merkle Tree

The JMT is a radix-16 path-compressed Merkle tree. Each internal node has up to 16 children (one per nibble), and runs of single-child nodes are compressed into a single edge labelled with the shared key prefix. Empty subtrees are not materialized.

Why JMT over a fixed-depth Sparse Merkle Tree?

The headline number — 40× faster commits — was the deciding factor. JMT removes the per-key 256-Poseidon2 cost, replacing it with a path that follows the actual key density in the tree.

The implementation lives in crates/state/src/jmt_store.rs. The persistent wrapper exposes a small surface:

#![allow(unused)]
fn main() {
PersistentJMT {
    fn insert(key: H256, value: Vec<u8>) -> ...
    fn get(key: H256) -> Option<Vec<u8>>
    fn update_all(updates: &[(H256, Option<Vec<u8>>)]) -> ...
    fn root() -> H256
    fn delete(key: H256) -> ...
    fn is_empty() -> bool
}
}

A HybridJmtHasher adapter implements the jmt::SimpleHasher trait, delegating internal node hashes to Blake3 (the high-volume path) and exposing Poseidon2 for state-root and address-derivation paths. The JMT internals use Blake3; the snapshot manifest and ZK-bearing exports use Poseidon2. Both roots are computed and signed (Chapter 6).

4.1b Two-Table Architecture: state_cf + jmt_cf

Pyde maintains state in two RocksDB column families, each optimized for a different access pattern:

┌────────────────────────────────────────────────────────────────────────┐
│  state_cf — flat key-value index for live reads                         │
│                                                                          │
│    key   = slot_hash (32 bytes, PIP-2 layout)                           │
│    value = current slot value (raw bytes)                               │
│                                                                          │
│    O(1) point lookup. Updated on every state change.                    │
│    Used by: live execution path (sload), RPC queries, range scans.       │
└────────────────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────────────────┐
│  jmt_cf — versioned tree structure for proofs + state root              │
│                                                                          │
│    key   = NodeKey(version: u64, NibblePath)                            │
│    value = JmtNode { children_fingerprints[], value_bytes (if leaf) }    │
│                                                                          │
│    O(depth) walk for proofs. Updated at every wave commit.              │
│    Used by: state-root computation, Merkle proofs for light clients,    │
│            historical state queries (on archive nodes).                  │
└────────────────────────────────────────────────────────────────────────┘

Why two tables instead of one:

The JMT alone can serve every read, but each read is O(depth) — typically 6-8 RocksDB gets to walk from root to leaf. For live execution at thousands of TPS, that's too expensive.

state_cf keeps a flat denormalized index of the current value for every slot. A single get returns the value. PIP-2's clustered slot_hash layout keeps state_cf entries spatially clustered by contract, so range scans and multigets stay cheap.

The JMT structure is still maintained alongside, because it's needed for:

• State-root computation: hash up from leaves to root, deterministically, across all validators
• Merkle proofs: light clients verify (value, proof) → state_root without holding full state
• Versioned reads: archive nodes serve historical state by walking older JMT versions

The read path:

fn read_slot(slot_hash) -> Option<Bytes>:
  1. dashmap.get(slot_hash)                ← PIP-4 in-memory cache (most live reads)
  2. state_cf.get(slot_hash)                ← ONE disk read (cache miss path)
  
  Total: one disk get, sometimes amortized to zero.

The JMT is not in the live read path. Reads use state_cf. The JMT is reached only for proofs or for state-root computation at commit time.

The write path (at wave commit):

fn commit_wave(dirty_changes: Vec<(SlotHash, Bytes)>):
  1. For each (slot_hash, new_value) in dirty_changes:
       jmt.update(slot_hash, new_value, new_version)
         → JMT recomputes leaf_hash + internal hashes up the affected path
       state_cf.put(slot_hash, new_value)
  
  2. new_state_root = jmt.root_hash(new_version)
  
  3. Both writes happen in a single RocksDB WriteBatch (atomic).

The two tables stay in lockstep. They are never out of sync because every write touches both atomically.

Cost of duplication: roughly 2× storage for the state itself (the leaves' values appear in both state_cf and the JMT's leaf records). This is the trade-off — extra storage in exchange for O(1) live reads while still preserving authenticated proofs.

Retention split:

4.1c Events Storage: events_cf + Indexes

State is not the only thing the chain stores. Events emitted via pyde::emit_event (see Chapter 3 §3.3 and Host Function ABI Spec §15) live in three additional column families parallel to state_cf + jmt_cf:

events_cf (primary, ordered by wave)
  key:   wave_id (8 BE) || tx_index (4 BE) || event_index (4 BE)
  value: borsh_encode(EventRecord)

events_by_topic_cf (index)
  key:   topic (32) || wave_id (8 BE) || tx_index (4 BE) || event_index (4 BE)
  value: ()                    -- empty; key carries lookup info

events_by_contract_cf (index)
  key:   contract_addr (32) || wave_id (8 BE) || tx_index (4 BE) || event_index (4 BE)
  value: ()

Atomicity: at every wave commit, the engine writes one RocksDB WriteBatch containing updates to state_cf + jmt_cf + events_cf + events_by_topic_cf + events_by_contract_cf + the wave commit record. Either all five land or none does.

On-chain commitment: each wave commit record carries two summaries of the wave's events:

• events_root (Blake3) — binary Merkle tree over canonical-ordered events, suitable for inclusion proofs.
• events_bloom (256-byte, 2048-bit, 3-hash) — probabilistic summary for cheap "any event matching X in this wave?" checks.

Both are threshold-signed as part of the wave's HardFinalityCert, so light clients verify event inclusion identically to how they verify state.

Retention:

Pruning is in lockstep across all three event column families.

For query semantics (pyde_getLogs), subscriptions (pyde_subscribe), and the Borsh-recommended event encoding, see Host Function ABI Spec §14–§15.

4.2 Hybrid Hashing: Blake3 + Poseidon2

Pyde uses two hashes in different layers, chosen for what each is best at:

The split rule: every hash that lives entirely off-chain or inside a trusted committee-signed structure can be Blake3. Every hash that may be exposed to a future ZK proof (state root, addresses, signature payloads) is Poseidon2.

Poseidon2 (Goldilocks)

Poseidon2 is the algebraic hash used everywhere in Pyde — the JMT, contract storage-key derivation, transaction hashing, the threshold MAC, the VRF, and the poseidon2 WASM host function. The parameter set (see Chapter 8 for full detail):

The hash is exposed as three primitives:

The _pair form is exposed for compatibility but JMT internal nodes use Blake3 (blake3_pair); Poseidon2's _hash form is what storage-key derivation, address derivation, and the poseidon2 WASM host function use; the _many form is what the threshold scheme uses to combine epoch randomness shares.

Blake3

Used in the high-volume paths where ZK-friendliness is irrelevant:

- JMT internal node hashes (hybrid-mode hasher)
- Batch hashes referenced from vertices
- Vertex hashes in the DAG
- Gossip message de-duplication keys
- RocksDB cache keys

Blake3 is configured in its default tree-hashing mode with 256-bit output. Native verification of a JMT inclusion proof against the Blake3 state root takes ~5-10 hash operations and completes in microseconds — fast enough that the snapshot manifest verification (Chapter 7) doesn't dominate sync time.

4.3 Account Storage Layout

Every account in crates/account/src/types.rs has a fixed layout:

#![allow(unused)]
fn main() {
struct Account {
    address:      Address,    // 32 bytes (Poseidon2 hash of FALCON pubkey)
    nonce:        u64,        // 8 bytes (sliding window base — see Chapter 11)
    balance:      u128,       // 16 bytes, in quanta (10^9 quanta = 1 PYDE)
    code_hash:    H256,       // 32 bytes (zero for EOAs)
    storage_root: H256,       // 32 bytes (zero for empty contracts)
    account_type: AccountType,// 1 byte (EOA=0, Contract=1, System=2)
    auth_keys:    AuthKeys,   // variable (FALCON pubkey or multisig set)
    gas_tank:     u128,       // 16 bytes (sponsored-tx pool)
    key_nonce:    u32,        // 4 bytes (rotation counter)
}
}

Fixed portion: 141 bytes plus the variable auth_keys field.

The address is a 32-byte Poseidon2 hash. Three derivation paths exist:

EOA address     = Poseidon2(falcon_public_key_bytes)              // 897-byte FALCON pk
CREATE address  = Poseidon2(deployer_address || nonce_bytes)
CREATE2 address = Poseidon2(0xFF || deployer_address || salt || code_hash)

The 32-byte length matches the natural Poseidon2 output (4 Goldilocks field elements ≈ 256 bits) and avoids the birthday-bound concerns of 20-byte truncated addresses at chain scale.

4.4 Storage Keys and Slots

Pyde uses a flat storage layout. Account fields and contract storage slots all live in the same JMT, distinguished by discriminator bytes in the key derivation.

The key derivation pattern is:

key = Poseidon2(account_address || discriminator || sub_key)

Some discriminators currently in use (defined in crates/state/src/keys.rs):

This flat scheme means a single Merkle path can prove any state claim — there is no nested account-trie / storage-trie indirection (the classic Patricia-trie pattern). One proof, one Poseidon2-walk to the root.

Contract storage layout

The otigen developer toolchain's state binding generator assigns slot identifiers to storage fields declared in otigen.toml. Each contract defines its state schema once and gets language-specific bindings that encode the slot derivation as build-time constants. Single-value fields lower to:

key = Poseidon2(contract_address, slot_index)

Maps lower to a doubled hash:

key = Poseidon2(contract_address, Poseidon2(slot_index, map_key))

Nested maps add another inner Poseidon2 per nesting level. This is the machinery that makes self.balances[user_addr] a single Sload opcode in the compiled bytecode.

4.5 The Block Witness

Pyde's block witness is the data needed to verify and re-execute a block from scratch given only the previous state root. It lives in crates/state/src/witness.rs:

#![allow(unused)]
fn main() {
pub struct BlockWitness {
    pub entries:         Vec<WitnessEntry>,
    pub proof:           SparseMerkleProof,   // single batched proof
    pub pre_state_root:  H256,
    pub post_state_root: H256,                // populated by finalize_witness
}
}

The shape:

• entries — every state slot the block touched, with its pre-execution value.
• proof — a single batched Merkle proof covering all entries against pre_state_root. JMT supports batch verification, so the proof is asymptotically smaller than len(entries) independent paths.
• pre_state_root — the state root before this block executes (taken from the parent block's header).
• post_state_root — the state root after execution, set by set_post_state_root() or finalize_witness() once the block is executed.

Critically, post_state_root is not auto-populated at witness generation time. The witness is built before execution; the post-root is filled in afterwards. is_finalized() returns false until that step happens.

The 1 MB witness size cap

A hostile transaction could theoretically force a witness containing millions of entries (e.g., touching deep, sparse storage paths). Pyde caps witness size hard:

#![allow(unused)]
fn main() {
pub const MAX_WITNESS_SIZE: usize = 1024 * 1024;  // 1 MB
}

verify_witnesses() rejects any witness exceeding this cap before doing the work of proof verification. The block as a whole is rejected.

4.6 RocksDB Layout

The JMT and witness logic both persist through RocksDB (JmtRocksStore in crates/state/src/jmt_store.rs). The key prefixes are:

LRU caches sit in front of node and value reads (256k entries each, sized for the working set of an active validator). Compression is LZ4 for the L0–L1 levels and ZSTD for cold levels; the block cache is 512 MB and the memtable pool is 256 MB. These are tuned for the steady-state validator workload, not for peak burst sync.

Writes to consensus-critical state use WriteOptions::set_sync(true) (see Chapter 6) — JMT updates do not, because the canonical truth is the chain itself; on restart, a validator can rebuild any missing state from blocks.

4.7 The Wave-Application Pipeline

When a wave commits, the state pipeline runs in this order:

1. Open a batch against the current JMT (the wave's pre_state_root).
2. Prefetch every (addr, slot) pair declared across the wave's tx access lists in one batched state_cf.multi_get (PIP-3). Returned values land in the dashmap (PIP-4) marked Clean. Access lists are prefetch hints only — they never partition the wave or affect correctness.
3. Execute every tx in parallel via the Block-STM scheduler: optimistic execute through an MVCC layer → validate against canonical tx_index order → cascade-invalidate + re-incarnate on conflict → fixpoint. The final state per slot is the highest-tx_index's last write.
4. Apply the Block-STM finalize output to the batch as one ordered slot-write set.
5. Distribute fees: 70% to the burn counter (TOTAL_BURNED discriminator), 20% to the epoch reward pool (distributed at epoch end by stake × uptime), 10% to the treasury account.
6. Commit the batch with update_all. The new root is post_state_root.
7. Set the WaveCommitRecord's state_root and emit the per-wave WaveCommitInputs for the wave-committer.

The Block-STM correctness contract guarantees that two honest validators given the same canonical tx list + same pre_state_root produce bit-identical post_state_root and receipts, regardless of how many re-execution attempts each validator's scheduler needed to reach fixpoint. Attempt order, thread interleaving, and wall-clock duration can all differ; the final state cannot. Disagreement on post_state_root is a slashing-grade safety violation per Chapter 6 §12.

4.8 State Sync

A new node joining the network does not replay every block from genesis — at production TPS, full replay would take longer than the chain has existed. Pyde defines three sync modes (full spec: companion/STATE_SYNC.md, operational summary: Chapter 7):

1. Snapshot sync (default for new full nodes). Download a committee-signed SnapshotManifest (~5 KB) carrying both Blake3 and Poseidon2 state roots plus chunk references. Verify ≥85 FALCON signatures. Download chunks (~4 MB each) in parallel from peers, verify each against the manifest, reconstruct the JMT, recompute the Blake3 root, compare. Then replay the tail blocks (≤ 8 epochs ≈ 24 hours of tx) to reach the current head. Total time on commodity (100 Mbps): ~40 minutes.

2. Light client sync. Headers only + cared-about accounts via JMT inclusion proofs. ~600 KB/year for a typical wallet. Verifies FALCON signatures on the headers it receives.

3. Full sync (archive nodes). Replay every block from genesis. Slowest option; provides full historical state lookup for explorers / indexers.

Chain-of-trust bootstrap. A new node verifies the chain of snapshot manifests from genesis forward: genesis hardcodes committee_0's pubkeys; each subsequent epoch-boundary manifest is signed by the prior committee and contains the next committee's pubkeys.

Weak-subjectivity checkpoints published by the foundation and reputable infrastructure providers let new nodes trust a recent checkpoint and skip the chain-of-trust walk. Beyond a one-epoch rollback window, contradicting a finality checkpoint is impossible without a hard fork.

4.9 What Is NOT in the State

A few things deliberately do not live in the JMT:

• Receipts. Stored in an in-memory ring buffer (crates/node/src/receipt_store.rs, MAX_RECEIPT_SLOTS = 10_000). At ~500 ms per commit, this is roughly 80 minutes of recent receipt history. Persistent receipt storage (archive-node mode) is tracked as post-mainnet hardening.

• Mempool contents. Encrypted transactions live in process memory, bounded per sender by the rate-limiting subsystem (10 tx/s, 100 concurrent per sender).

• Consensus protocol state. pending_votes, seen_proposals, seen_votes, and pending evidence live in their own RocksDB column under the consensus_store, with set_sync(true) writes — see Chapter 6.

• Finality checkpoints. Stored in the consensus_store with their own key (FINALITY_CHECKPOINT_KEY), not in the JMT itself.

The line is drawn deliberately: the JMT holds canonical chain state that everyone agrees on. Operational state (consensus liveness, mempool ingress, receipt cache) lives outside the consensus root because it does not need to be globally agreed.

4.10 Summary

The next chapter covers the developer toolchain (otigen) that sits on top of this state model — how a contract's [state] declaration in otigen.toml becomes the slot identifiers the JMT actually sees, via language-specific state binding generators that pre-compute slot prefix constants at build time.

Chapter 5: Otigen Toolchain

otigen is Pyde's developer toolchain — a single binary that scaffolds projects (from a language template or canonical example), validates the author's WASM build, runs behaviour tests against the compiled .wasm, generates the ABI from otigen.toml, packages the deploy bundle, manages FALCON-512 keystores, and handles on-chain lifecycle commands (deploy, upgrade, pause, kill, inspect, verify, console).

What otigen deliberately does NOT do: it does not compile WASM, it does not generate code, it does not interface with any language's build pipeline. Authors run their own cargo build / asc / tinygo build / clang --target=wasm32 and otigen checks the result. This keeps the toolchain minimal and language-agnostic, and lets authors keep their full native toolchain experience.

The name carries forward from an earlier design phase, when Otigen was Pyde's domain-specific smart-contract language. The language is retired; the name now describes the role it occupies best — the lightweight verifier and packager that makes WebAssembly deployment on Pyde coherent without forcing authors out of their language ecosystems. See The Pivot for the full story.

This chapter covers the toolchain's design, the subcommand surface, the otigen.toml schema, the per-language workflow, build verification, attributes, deploy/upgrade, wallet, behaviour tests, and the console.

For the underlying execution layer that contracts run on, read Chapter 3: Execution Layer. For the host functions contracts call, read the Host Function ABI spec.

5.1 Design Principles

The toolchain is built around four principles, each chosen deliberately.

Author owns the build; otigen verifies

By default otigen does not compile WASM. The author runs their language's native build command (cargo build --target wasm32-unknown-unknown --release, npm run build, tinygo build -target=wasi -o build/contract.wasm ., make) themselves. They get the full diagnostics, the full IDE integration, the full test workflow their language ecosystem provides.

otigen build then verifies the result: confirms the .wasm file exists at the path declared in otigen.toml, validates the WASM module structure, cross-checks that the module imports only allowed host functions and exports every function declared in [functions], and generates the deploy bundle. If anything is missing or wrong, otigen says so; if everything checks out, it prints "ready to deploy."

This keeps the toolchain minimal (no per-language compiler invocation logic to maintain) and respects the author's native toolchain.

For the common iterate-on-a-contract case there is also otigen build --compile: an opt-in flag that runs the per-language default build command first (the same invocation the templates document + init's "next:" hint prints), then proceeds with the same verify + package pipeline. Both paths produce byte-identical bundles when the inputs are equivalent — --compile is a UX convenience, not a different build. Authors with custom build flags continue to compile manually and call otigen build (no flag) afterwards; that verify-only path stays supported forever.

Zero extra code in the author's project

A contract project contains only the author's contract logic and an otigen.toml. No bundler files, no glue code, no manifest-handling boilerplate. The author writes what their language requires (a Cargo.toml for Rust, package.json for AssemblyScript, go.mod for Go, Makefile for C/C++) and the contract source itself.

State access and host-function calls go through whatever helper pattern the author or community provides for their language. otigen doesn't ship those helpers, doesn't generate them, doesn't depend on them. It only requires that the resulting .wasm imports the Host Function ABI correctly.

Two test layers, one toolchain

Pyde splits contract testing by layer. Language-native test frameworks (cargo test, npm test, go test, the author's C test harness) cover pure helpers — math, parsing, formatting — at the function-internals layer. The toolchain doesn't wrap them; authors keep their language's standard test workflow.

otigen test covers the layer above: contract behaviour — does transfer decrement the right balance, emit the right event, revert on the right input. It runs the compiled .wasm inside a wasmtime sandbox with mock implementations of every pyde::* host function declared in the Host Function ABI, driven by a TOML test spec (named accounts, named storage slots, time / wave / chain cheats, multi-call sequences, named event matching, named-or-substring revert assertions). The TOML format is language-agnostic — the same .test.toml runs against the contract regardless of source language. Full schema and semantics: OTIGEN_TEST_SPEC.

The split mirrors Foundry's forge test (behaviour) vs Rust's cargo test (unit) — neither subsumes the other, both shipping in one toolchain doesn't compromise the language-agnostic posture.

Attributes and ABI declared in otigen.toml, enforced at runtime

Function attributes (view, payable, reentrant, sponsored, constructor, fallback, receive, entry) and state schema are declared in otigen.toml. otigen build reads them, builds a ContractAbi struct, Borsh-encodes it, and injects it as a WASM custom section named pyde.abi directly into the .wasm artifact the language compiler produced. There is no separate abi.json file at deploy time — the ABI travels with the code as one binary. At runtime, the WASM execution layer extracts the pyde.abi section once, caches the parsed ABI alongside the compiled Module, and applies attribute-driven guards before every call (reentrancy block, view-mode state-write rejection, payable-mode value check, sponsored gas-tank debit, etc.). The WASM module itself does not carry attribute markers — the engine enforces them at the call boundary based on the parsed ABI. Full mechanics: Host Function ABI Spec §3.5–§3.7.

5.2 Subcommand Surface

Every row links to its canonical OTIGEN_BINARY_SPEC section — the spec is authoritative on flag tables, exit codes, and the per-command pipeline. This chapter is the narrative companion.

There is no otigen compile. Authors use their language's native compiler (cargo build --target wasm32-unknown-unknown --release, asc, tinygo build -target=wasi, clang --target=wasm32). The --compile flag on otigen build is an opt-in convenience that invokes the language's default command — not a separate compile subcommand.

5.3 The otigen.toml Schema

A single TOML file declares everything otigen needs to know about the project. The full schema with field-by-field validation rules is documented in OTIGEN_BINARY_SPEC.md §4; the shape below is the canonical reference.

[contract]
name        = "my-token"          # required; lowercase + hyphens (ENS-style)
version     = "1.0.0"             # required; semver
description = "Example token"     # optional
type        = "contract"          # "contract" (default) or "parachain"

[contract.lang]
language = "rust"                 # required; rust | as | go | c
output   = "target/wasm32-unknown-unknown/release/my_token.wasm"
                                  # required; path the author's compiler emits

[contract.lang.toolchain]
rust_channel   = "stable"         # rust only — informational, surfaced in manifest.json
# asc_version, tinygo_version, clang_version for the other languages

[deploy]
gas_limit     = 10_000_000        # default per-deploy gas budget
gas_price     = "auto"            # "auto" = use current base_fee; or fixed quanta
owner_deposit = 1000              # PYDE locked at deploy time (parachain only)

[wallet]
default_keystore = "~/.pyde/keystore.json"   # optional; --keystore overrides
default_account  = "deployer"                # optional; --from overrides

[network.default]
name = "testnet"                  # selects one of the named [network.X] entries

[network.mainnet]
rpc_url      = "https://rpc.pyde.network"
chain_id     = 1
explorer_url = "https://explorer.pyde.network"

[network.testnet]
rpc_url      = "https://rpc-testnet.pyde.network"
chain_id     = 2

[network.devnet]
rpc_url      = "http://localhost:9933"
chain_id     = 31337

[state]
# State schema; each entry declares a top-level field name + type.
# Used for ABI emission (state_schema_hash) + explorer decoding.
# Authors still write their own slot derivation in contract code —
# otigen does not generate accessor bindings.
schema = [
    { name = "owner",         type = "address" },
    { name = "total_supply",  type = "uint128" },
    { name = "balances",      type = "mapping(address -> uint128)" },
]

[functions.transfer]
attributes  = ["entry", "payable"]
inputs      = ["address", "uint128"]
outputs     = ["bool"]
access_list = [                  # optional; prefetch hint for cache warm-up
    "balances[caller()]",
    "balances[args.0]",
]

[functions.balance_of]
attributes = ["entry", "view"]
inputs     = ["address"]
outputs    = ["uint128"]

[functions.init]
attributes = ["constructor"]      # callable only at deploy time
inputs     = ["uint128"]

# ─────────────────────────────────────────────────────────────────
# Custom types — referenced by bare name in [functions.X].inputs/outputs,
# and via struct(...) / vec(...) wrappers in [state].schema.
# ─────────────────────────────────────────────────────────────────

[types.Order]
fields = [
    { name = "id",     type = "uint64"  },
    { name = "maker",  type = "address" },
    { name = "amount", type = "uint128" },
    { name = "paid",   type = "bool"    },
]

[types.Status]
variants = [
    { name = "Pending" },
    { name = "Active"  },
    { name = "Cancelled" },
]

[events.Transfer]
signature = "Transfer(address,address,uint128)"
fields = [
    { name = "from",   type = "address",  indexed = true },
    { name = "to",     type = "address",  indexed = true },
    { name = "amount", type = "uint128" },
]

Schema notes

[contract] — identity + version + type (contract or parachain). name is the ENS-style on-chain name (globally unique; see Ch 11 §11.2). The address is derived from the FALCON pubkey at deploy time, not from name; the registry binds name → address.

[contract.lang] — declares which language the author compiled with and where their compiler emits the .wasm. language ∈ {rust, as, go, c}. output is the path otigen build reads. Optional [contract.lang.toolchain] pins specific toolchain versions (surfaced in manifest.json for reproducible-build verification).

[deploy] — defaults for otigen deploy. gas_limit caps the deploy tx's gas. gas_price = "auto" uses the current chain base fee; a fixed integer overrides. owner_deposit is only meaningful for parachain deploys.

[wallet] — points at the default keystore + the default account. Both fields are optional; the global --keystore <path> and per-command --from <name> flags override.

[network.*] — [network.default.name] selects which other [network.<name>] table the toolchain talks to. Each named entry carries rpc_url, chain_id, and an optional explorer_url. The global --network <name> flag overrides at the command line.

[state] — the schema of the contract's storage. Used by otigen build to compute state_schema_hash (which the chain compares against on every state read for type-safety enforcement) and emitted in abi.json for explorers. The author's contract code still derives the storage slots itself — Pyde does not ship per-language storage bindings.

[functions.<name>] — every callable function the runtime should dispatch to. attributes is the safety + dispatch attribute set documented in §5.6. otigen build cross-checks every [functions.X] has a matching WASM export named X and rejects exports that aren't declared. Optional access_list declares the storage slots the function touches; accurate lists optimize cache prefetch performance in the uniform Block-STM scheduler (declaring nothing still works — the chain just runs with a colder cache).

[types.<Name>] — author-declared custom types. Two shapes: a struct declares fields = [{ name, type }, ...]; an enum declares variants = [{ name = "X" }, ...] (v1 is unit-only — no data-carrying variants). Functions reference custom types by bare name in [functions.X].inputs / outputs (e.g. "Order"); storage references them via the struct(<Name>) wrapper in [state].schema (e.g. { name = "current_order", type = "struct(Order)" }), and vec(<Name>) similarly wraps for arrays. Rust contract code needs #[derive(BorshSerialize, BorshDeserialize)] on every custom type — the macro substrate's typed storage + entry-arg decoders depend on it.

[events.<name>] — emitted-event declarations. signature is the canonical string the chain hashes (Blake3) to derive the topic-0 value. Indexed fields are searchable via pyde_getLogs; non-indexed fields are Borsh-encoded into data.

[parachain] (parachain only) — consensus preset, validator constraints, slashing preset. Detailed in Chapter 13.

5.4 Per-Language Workflow

Each language has its own template (scaffolded by otigen init) and its own native build command. The author runs the build; then otigen build verifies + packages.

Rust

otigen init my-contract --lang rust
cd my-contract
# Edit src/lib.rs with contract logic; declare entries + state +
# events in otigen.toml.

# Author runs their own build:
cargo build --release --target wasm32-unknown-unknown

# otigen verifies and packages:
otigen build
otigen deploy --network devnet

Scaffolded project tree:

my-contract/
├── otigen.toml      # contract identity, network, [functions.*], [state], [events.*]
├── Cargo.toml       # cdylib + release profile tuned for WASM size;
│                    # depends on `pyde-host` (the canonical Rust SDK)
├── src/
│   └── lib.rs       # #![no_std] template with the macro substrate:
│                    # `pyde::declare_storage!()` emits typed storage accessors
│                    # from the [state] schema, `pyde::declare_events!()` emits
│                    # typed event structs from [events.*], `#[pyde::entry]`
│                    # wraps each user fn with the () -> () ABI shim. Authors
│                    # write idiomatic Rust against typed args + return values;
│                    # no hand-written `extern "C"` blocks or `*const u8`
│                    # buffer staging.
└── .gitignore

otigen build does:

• Read otigen.toml; validate schema (§5.3) + attribute combinations.
• Locate the .wasm at [contract.lang.output] (target/wasm32-unknown-unknown/release/<crate>.wasm).
• Validate the WASM module (parses cleanly via wasmparser, every import declares module pyde, every imported function is on the HOST_FN_ABI_SPEC allowlist, every [functions.X] has a matching export, only deterministic WASM features used).
• Run the static call-graph view check: any view-attributed function whose transitive call graph reaches a state-mutating host function is rejected.
• Build the ContractAbi from otigen.toml, Borsh-encode it, inject as the pyde.abi custom section via wasm-encoder.
• Write <out>/<contract_name>.bundle/ containing contract.wasm (with pyde.abi embedded), otigen.toml (verbatim), abi.json (human-readable mirror), manifest.json (hashes, build timestamp, otigen version, target chain_id).

AssemblyScript

otigen init my-contract --lang as
cd my-contract
# Edit assembly/index.ts; declare entries + state in otigen.toml.

npm install && npm run build        # delegates to: asc assembly/index.ts --config asconfig.json --target release

otigen build                         # verify + package
otigen deploy --network testnet

The scaffold pins runtime: "minimal" in asconfig.json so the resulting WASM imports nothing outside pyde — anything else would fail the chain's import allowlist.

Go (TinyGo)

otigen init my-contract --lang go
cd my-contract
# Edit main.go; declare entries + state in otigen.toml.

tinygo build -target=wasi -o build/contract.wasm .

otigen build                         # verify + package
otigen deploy --network testnet

The scaffold uses //go:wasmexport ping to mark the entry point and documents the //go:wasmimport pyde caller pattern (commented out) for host-fn imports. TinyGo requires a main(); the chain dispatcher never calls it.

C / C++

otigen init my-contract --lang c
cd my-contract
# Edit contract.c; declare entries + state in otigen.toml.

make                                 # delegates to: clang --target=wasm32 -nostdlib -Wl,--no-entry ...

otigen build                         # verify + package
otigen deploy --network testnet

The scaffold's Makefile pins -nostdlib so libc never leaks into the resulting WASM (which would fail the allowlist). Host-fn imports go through __attribute__((import_module("pyde"), import_name(<fn>))); the scaffold ships one commented-out example. Exports use __attribute__((export_name(<fn>))).

Why this split

Authors keep their full language toolchain (build errors, IDE integration, dependency management, test runners, fuzzers, profilers — everything). The chain-specific concerns (ABI generation, deploy packaging, on-chain lifecycle) are owned by otigen. The interface between them is the .wasm file + the otigen.toml schema; both are inspectable, neither is generated by the other.

5.5 Build Verification + Packaging

otigen build is purely a validator + packager. It runs in this order:

1. Load otigen.toml; validate schema (§5.3) + attribute combinations per
   HOST_FN_ABI_SPEC §3.5.1.
2. Locate the .wasm at the path declared in [contract.lang.output];
   reject (exit 2) if the file doesn't exist.
3. Parse the .wasm via wasmparser; reject if the binary is malformed.
4. Walk the WASM import table; reject any import whose module is not
   "pyde" or whose function name is not on the HOST_FN_ABI_SPEC
   allowlist (and, for non-parachain contract types, reject any
   parachain-only host functions).
5. Walk the WASM export table; cross-check every [functions.X] has a
   matching export named X, and reject any export that isn't declared.
6. Validate the WASM feature set is in the deterministic subset
   (no threads, no SIMD, no reference types, etc.).
7. Run the static call-graph view check: for each `view`-attributed
   function, walk its transitive call graph. Reject if any reachable
   function imports a state-mutating host call (sstore, sdelete,
   transfer, emit_event, parachain_storage_write, etc.).
8. Build the ContractAbi from [functions.*] + [events.*] + [state]
   (computing 4-byte selectors as blake3(fn_name)[..4], topic
   signature hashes, state schema hash).
9. Borsh-encode the ContractAbi.
10. Inject the encoded ABI into the .wasm as a custom section named
    `pyde.abi`, using the `wasm-encoder` crate. The code section is
    untouched; reproducible builds still verify byte-identical.
11. Write the bundle to <out>/<contract_name>.bundle/:
      - contract.wasm        (.wasm with pyde.abi custom section)
      - otigen.toml          (verbatim copy of the source config)
      - abi.json             (human-readable ABI mirror)
      - manifest.json        (blake3 hashes, build timestamp, otigen
                              version, language toolchain pins,
                              target chain_id)
12. Print "✓ built <name> → <bundle_path>" with the wasm + abi sizes
    and blake3 prefixes (16 hex chars) per artifact.

Exit codes: 0 on success, 1 on validation failure (with a structured error listing every violation), 2 if the .wasm was not found at the expected path. No partial bundles are ever written — the bundle dir is created last, after every validation has passed.

How Rust authors do state access (macro substrate)

The Rust scaffold ships a thin SDK — pyde-host + the #[pyde::entry] macro + pyde::declare_storage!() + pyde::declare_events!() — that hides the WASM ABI entirely. Authors declare a typed state schema once and call generated module-path functions; the macros emit the void-void entry shim (HOST_FN_ABI §3.5.2), unpack borsh calldata into typed arguments, derive Poseidon2(self_address ‖ field [‖ keys]) slots, and call the chain's sstore_scalar / sload_scalar / sstore_map<N> / sload_map<N> host fns.

#![allow(unused)]
fn main() {
// src/lib.rs — Rust macro substrate.
#![no_std]
use pyde::Address;

pyde::declare_storage! {
    [state]
    total_supply: u128,
    balances: mapping(Address => u128),
}

pyde::declare_events! {
    Transfer { from: Address, to: Address, amount: u128 }
}

#[pyde::entry]
fn transfer(to: Address, amount: u128) {
    let from = pyde::caller();
    let from_bal = storage::balances().get(&from);
    if from_bal < amount { pyde::revert("transfer: insufficient balance"); }
    storage::balances().set(&from, from_bal - amount);
    storage::balances().set(&to, storage::balances().get(&to) + amount);
    events::Transfer { from, to, amount }.emit();
}
}

The matching otigen.toml declares the same schema (canonical form or Solidity-style sugar):

[state.fields]
total_supply = "uint128"
balances     = "mapping(address => uint128)"

[functions.transfer]
attributes = ["entry"]
inputs     = ["address", "uint128"]

The #[pyde::entry] macro generates the void-void shim that reads the borsh-encoded calldata via pyde::calldata_size + pyde::calldata_copy, decodes each declared input, calls the typed transfer body, and (if the function returns a value) writes the encoded bytes via pyde::return. There is no hand-rolled FFI; otigen build's spec-entry check (HOST_FN_ABI §3.5.2) passes automatically.

Non-Rust languages

The other three languages (TinyGo, AssemblyScript, C) don't ship a Pyde-supplied SDK. Authors declare a void-void exported entry, read calldata via pyde::calldata_* host fns, and call host functions directly through the language's FFI mechanism (//go:wasmimport, @external, __attribute__((import_module))). The canonical reference patterns live in pyde-net/otigen/examples/counter-{go,as,c}/. The WASM_AUTHOR_GUIDE companion doc walks the per-language details.

5.6 Safety Attributes via otigen.toml

Otigen the language had a set of compiler attributes that made common safety properties default and explicit. Every one of those properties carries forward unchanged in the WASM era. Authors declare them in otigen.toml [functions.<name>] attributes = [...]; otigen build includes them in the generated ABI; the runtime enforces them by reading the ABI before invocation and applying the appropriate guards.

The mechanism changed (config-declared metadata enforced at the call boundary instead of compiler-extracted markers in bytecode), but the safety guarantees are identical to the Otigen-language era.

Reentrancy is still blocked by default

This is the most important property to preserve. Every public function gets an automatically generated reentrancy guard. To opt OUT of the guard — for a function that genuinely needs to allow re-entry — add the #[reentrant] attribute.

If you write nothing, you are protected.

The attribute set

For attribute compatibility rules (which combinations are rejected at build + deploy), see HOST_FN_ABI_SPEC §3.5.1.

How attributes are declared

Attributes are declared in otigen.toml, per function. The author writes plain TOML; the source code is whatever they write in their language. No per-language macro syntax is needed and no source-code parsing is required.

[functions.balance]
attributes = ["entry", "view"]
inputs     = ["address"]
outputs    = ["uint128"]

[functions.deposit]
attributes = ["entry", "payable"]
inputs     = []

[functions.complex_callback]
attributes = ["entry", "reentrant"]   # opts INTO reentrancy; default is BLOCKED
inputs     = ["bytes"]

[functions.user_signup]
attributes = ["entry", "sponsored"]   # gas paid by contract's gas_tank
inputs     = ["address"]

[functions.init]
attributes = ["constructor"]          # callable only at deploy time
inputs     = ["uint128"]

The author writes the corresponding WASM exports in their language as a void-void function (HOST_FN_ABI §3.5.2). In Rust, the #[pyde::entry] fn balance(owner: Address) -> u128 macro emits the void-void shim. In AssemblyScript, export function balance(): void. In Go (TinyGo), //go:wasmexport balance on a func balance(). In C, __attribute__((export_name("balance"))) void balance(void). Standard WASM-export idioms for each language; the void-void contract is non-negotiable — otigen build's entry-shape validator rejects any non-void-void export declared in [functions.<name>].

What the build tool does with attributes

otigen build validates them (e.g., a function cannot be both view and payable) and writes them into the generated ABI:

{
  "functions": [
    {
      "name": "transfer",
      "selector": "0xa9059cbb",
      "attributes": ["entry"],
      "inputs": [...],
      "outputs": [...]
    },
    {
      "name": "balance",
      "selector": "0x70a08231",
      "attributes": ["entry", "view"],
      "inputs": [...],
      "outputs": [...]
    },
    {
      "name": "user_signup",
      "selector": "0x...",
      "attributes": ["entry", "sponsored"],
      "inputs": [...],
      "outputs": [...]
    }
  ]
}

How the runtime enforces them

The WASM execution layer reads the function's attribute set from the deployed ABI before invocation and applies the appropriate behavior:

This is identical behavior to Otigen the language. The change is implementation venue: attributes now ride on the ABI declared in otigen.toml rather than on compiler-extracted markers in bytecode. The safety guarantees are the same. The author's per-function declaration moves from source-code annotation to a config file. Both equally explicit; the config form keeps otigen decoupled from per-language source parsing.

Other Otigen design choices preserved

Beyond function attributes, several broader Otigen design choices carry forward as runtime properties of the engine:

The safety floor that Otigen provided is preserved end-to-end. The mechanism is different; the contract author's experience is the same.

5.7 Deploy and Upgrade Flow

Deploy

otigen deploy --network testnet

What happens, per spec §3.3:

1. otigen resolves the bundle dir (default ./artifacts/<name>.bundle/ from otigen.toml's [contract.name], override via --bundle <path>).
2. otigen loads the bundle (manifest.json + otigen.toml + contract.wasm) and re-validates WASM + ABI consistency — defense in depth even though the bundle came from otigen build.
3. otigen resolves the network from --network or [network.default.name] and the signer wallet from --from or [wallet.default_account]. Prompts for the wallet password (no echo).
4. otigen fetches the sender's nonce via pyde_getTransactionCount.
5. otigen builds the canonical Tx:

   Tx {
     from:       sender (32-byte Poseidon2(falcon_pubkey)),
     to:         Address::ZERO,
     value:      0,
     data:       borsh(DeployData { name, wasm_bytes, contract_type, init_calldata }),
     gas_limit:  from [deploy.gas_limit] (default 10_000_000),
     nonce:      fetched above,
     signature:  filled in next step,
     fee_payer:  Sender,
     access_list: [],
     deadline:   None,
     chain_id:   from [network.<name>.chain_id],
     tx_type:    Deploy (0x01),
   }
   

6. otigen computes the canonical Poseidon2 tx hash (Ch 11 §"Transaction hash") and FALCON-signs it. The signature is NOT included in the hashed payload.
7. --dry-run mode: print tx hash + wire size and exit 0 without submitting.
8. Otherwise: Borsh-encode the full Tx and submit via pyde_sendRawTransaction. Print the server-returned tx hash.
9. Unless --no-wait, poll pyde_getTransactionReceipt (60 s timeout, 1 s interval) until included. Report success / reverted / out-of-gas.

Exit codes: 0 on inclusion + success, 1 on validation failure, 2 on RPC / network / inclusion-timeout, 3 on revert, 4 on wallet failure.

Upgrade

otigen upgrade <target> --bundle <new-bundle-dir>     # contract path

What happens (contract path):

1. otigen resolves <target> — 0x-prefixed address or registered name (auto-resolved via pyde_resolveName).
2. otigen reads the new wasm from --wasm <file> or <bundle>/contract.wasm.
3. Same signing pipeline as deploy, but the wire shape is Tx { tx_type: Standard, to: <target>, data: borsh(LifecyclePayload::Upgrade { new_wasm }) }. The chain decodes the payload, re-runs ABI validation against the new bytes, stores the new code, and bumps current_version.

For parachain upgrades, the chain requires equal-power validator-quorum certs collected separately per PARACHAIN_DESIGN §6.2. The CLI flow for parachain governance (--parachain / --finalize <proposal-id>) is deferred to the parachain rollout post-mainnet.

5.8 Wallet Management

The wallet is built into the otigen binary directly — no separate wallet daemon, no external dependency, no extra install step. The cryptographic primitives (FALCON-512 keypair generation, AES-256-GCM keystore encryption, Argon2id key derivation, in-memory key unlock with zeroize-on-drop) carry forward from the archived wright toolchain; the on-disk format was redesigned for the WASM era to match spec §7.1.

Subcommand surface

otigen wallet new <name>
    # Generate a new FALCON-512 keypair. Prompts for a password (twice).
    # Adds the encrypted keypair to ~/.pyde/keystore.json under <name>.

otigen wallet import <name> --from-file <path>
otigen wallet import --from-devnet
    # Two modes: --from-file restores a previously-exported encrypted backup;
    # --from-devnet bulk-imports the 10 deterministic prefunded devnet
    # accounts (`Blake3("pyde-devnet-v1/" || i)`) — no network call.

otigen wallet list
    # List every account in the keystore (name + address).

otigen wallet show <name>
    # Print the account's address + public key. No password needed —
    # public material is stored unencrypted.

otigen wallet delete <name> [--yes]
    # Remove an account from the keystore. Requires retyping the name
    # to confirm unless --yes is passed.

otigen wallet password <name>
    # Rotate the account's encryption password. Decrypts with the old
    # password, generates a fresh salt + nonce, re-encrypts. The keypair
    # itself is unchanged.

otigen wallet export <name> --out <path>
    # Emit an encrypted backup blob for migration / cold storage.

otigen wallet sign <name> --message <msg>
    # Off-chain FALCON-512 signature over arbitrary bytes (NOT chain txs).

otigen wallet verify [name] --message <msg> --signature <hex>
    # Verify a FALCON-512 signature against a message and either a named
    # account's pubkey or `--pubkey <hex>` directly.

Override the default keystore location via the global --keystore <path> flag (e.g. otigen --keystore ./test-keys.json wallet list).

Keystore format

Per spec §7.1, a single JSON file at ~/.pyde/keystore.json holds every account. Schema:

{
  "version": 1,
  "accounts": {
    "deployer": {
      "address":    "0x" + 64 hex chars,
      "pubkey":     "0x" + hex of FALCON-512 public key (897 bytes → 1794 chars),
      "ciphertext": "0x" + hex of AES-256-GCM ciphertext of the FALCON secret key,
      "salt":       "0x" + 32 hex chars (16-byte Argon2id salt),
      "nonce":      "0x" + 24 hex chars (12-byte AES-GCM nonce),
      "kdf": {
        "name":        "argon2id",
        "memory_kb":   65536,    // 64 MiB
        "iterations":  3,
        "parallelism": 4
      }
    },
    "deployer-staging": { ... },
    "alice":            { ... }
  }
}

KDF parameters are embedded per-entry so a future tightening of the pinned values still decrypts old entries.

Unix file permissions are set to 0700 on ~/.pyde/ and 0600 on the keystore file. The plaintext secret key is decrypted in memory only when needed for signing and wiped on drop via zeroize::Zeroizing. The Wallet struct's Debug impl is hand-rolled to redact the secret key bytes so accidental unwrap_err() on a Result<Wallet, _> cannot dump key material into a panic message.

Signing flow

When otigen deploy, otigen upgrade, otigen pause, otigen unpause, or otigen kill is invoked:

1. Resolve the wallet name from --from <name> or [wallet.default_account].
2. Resolve the keystore path from --keystore <path> or the default (~/.pyde/keystore.json).
3. Prompt for the password via rpassword (no TTY echo).
4. Derive the AES-256 key from the password + per-account salt via Argon2id.
5. Decrypt the FALCON-512 secret key into a zeroize::Zeroizing wrapper.
6. Construct the canonical Tx, compute the Poseidon2 tx hash, FALCON-sign the digest.
7. Submit the signed Tx via pyde_sendRawTransaction. Zeroize the secret-key buffer on scope exit.

AES-GCM decryption failures all surface as the same Error::DecryptionFailed variant, regardless of cause (wrong password, tampered ciphertext, corrupt nonce). This avoids a timing oracle that would distinguish "you typed the wrong password" from "someone modified your keystore."

Deferred surface

Only one wallet operation from spec §3.7 is deferred:

• rotate <name> — submits a chain-side KeyRotationTx so an existing account can move to a fresh FALCON keypair without changing its address. Distinct from password (which only re-encrypts the local keystore entry). Blocked on the engine accepting the KeyRotationTx variant.

Hardware-wallet bridges and HSM-backed signing (spec §7.4) are post-mainnet; no FALCON-aware hardware wallets exist yet.

5.9 The Console

otigen console is an interactive REPL against a Pyde node — the natural shape for exploration and ad-hoc debugging once a contract is deployed and you want to poke at it without re-typing connection info on every command.

Pair it with pyde devnet for the canonical local loop: one terminal runs the devnet, another runs otigen console against it. Session-scoped --network + --from bind once at startup so every command in the session reuses the same RPC URL + sender; wallet unlock is lazy (view-only commands never prompt, first tx asks for the password once).

Shipping commands

Address arguments accept either 0x-hex or a registered name (when pyde_resolveName lands; today only hex resolves).

How state compares to inspect --state-field

Both use the same Poseidon2 slot derivation and the same primitive-type decoder. The difference is the workflow:

• inspect --state-field is the scriptable path — one-shot, --json-able, designed for CI / deploy scripts that want to assert a single value after a deploy.
• console state is the interactive path — drop into a REPL, poke at multiple fields across multiple contracts without re-typing the RPC URL or sender, exit when you're done.

Implementation lives in a single otigen-cli::state_decode module both surfaces consume, so the decoder vocabulary stays in lockstep.

History and editing

Line-edited via rustyline with persisted history at ~/.otigen_console_history. Up-arrow recalls prior commands across sessions.

Deferred surface

Two REPL commands are reserved by spec but blocked on engine work:

• events <addr> [--from N] [--to N] — historical event-log query. Needs pyde_getLogs (filtered + cursor-paginated). Ask filed.
• subscribe <addr> — live event tail. Needs both pyde_getLogs and a websocket transport on the devnet.

Both will land in a follow-up once the chain-side methods ship.

5.10 What the Toolchain Does NOT Do

Deliberately omitted:

• Language-native unit-test runner — use cargo test / npm test / go test / the author's C test harness for pure-helper unit tests. otigen test covers contract behaviour (state changes, events, reverts), not language-internal function testing. The two layers are complementary, not overlapping (§5.1, OTIGEN_TEST_SPEC).
• Linter / formatter — use the language's native tooling (rustfmt, prettier, gofmt, clang-format).
• IDE integration — uses the language's standard LSP; no Otigen-specific IDE extension required.
• Documentation generator — use the language's standard (rustdoc, typedoc, etc.).
• Dependency manager — use the language's standard (cargo, npm, go mod, etc.).
• Custom syntax — there is none; the contract is whatever the language allows.

The toolchain wraps deployment-specific concerns + the chain-aware behaviour-test layer. Everything else stays in the language ecosystems the authors already know.

5.11 Performance

The whole toolchain side of the pipeline — parse otigen.toml, validate every cross-cutting rule, walk the compiled .wasm for imports + exports + deterministic-feature compliance, build the canonical ContractAbi, Borsh-encode it, inject the pyde.abi custom section — measures in single-digit microseconds end-to-end. Validation work is essentially free against the file-system overhead of reading the .wasm and writing the four bundle files; a typical otigen build invocation is dominated by I/O (~1–5 ms in practice), not by validator CPU.

Reference numbers on an Apple M-series dev machine (arm64, macOS 15), measured by the criterion benches committed under crates/<crate>/benches/baseline/*.json in the pyde-net/otigen repo. Reproduce with cargo bench -p otigen-toml --bench parse_validate and cargo bench -p otigen-abi --bench abi_pipeline.

These numbers are tracked from commit pyde-net/otigen#6 forward. Future regressions surface on PRs that run cargo bench --baseline=v1.

The benches are intentionally tight scope — they measure the toolchain-side work, not the chain-side deploy validator (which redoes every check at deploy time per HOST_FN_ABI_SPEC.md §3.7 layer 3) and not the wasmtime AOT compilation step (which happens on the chain at first invocation of a deployed contract, not at otigen build time).

5.12 Contract Behaviour Tests (otigen test)

The toolchain ships a TOML-driven contract test runner. Authors write tests/<name>.test.toml, run otigen test, and get pass / fail per scenario — the same workflow Foundry users know from forge test, adapted to Pyde's host-function surface.

The full schema, name-resolution rules, cheatcode catalogue, mock host-function behaviour, and limitations are documented in OTIGEN_TEST_SPEC.md. The short overview:

What gets tested

• State changes — assert balances / counters / mappings after a call sequence.
• Return values — assert a function returned the expected scalar.
• Events — assert Transfer(from, to, amount) (or any declared event) emitted with the right indexed + non-indexed fields.
• Reverts — assert a call traps with a reason substring ("InsufficientBalance").
• Multi-step scenarios — assert "alice transfers to bob, then bob transfers to carol; final state is …" across multiple calls in one test.
• Time / wave / chain conditions — cheatcode now, wave_id, chain_id per test.

What it looks like

# tests/contract.test.toml

[accounts]
alice = { balance = "0x100" }
bob = {}

[[tests]]
name = "transfer_moves_balance"

[tests.setup]
storage.balances.alice = "100"
storage.balances.bob   = "0"

[[tests.calls]]
function = "transfer"
from     = "alice"
args     = ["bob", "10"]
expect.return_value = "1"
expect.events = [
  { name = "Transfer", from = "alice", to = "bob", amount = "10" },
]

[tests.expect]
storage.balances.alice = "90"
storage.balances.bob   = "10"

Named accounts resolve to 32-byte addresses via the chain's name registry; storage field names resolve to Poseidon2 slots (Poseidon2(self_address ‖ field_name ‖ keys...)) per the contract's [state] schema. Authors never type slot hashes by hand.

How it runs

otigen test discovers tests/*.test.toml, spins up a wasmtime engine, loads the contract's .wasm from ./artifacts/<name>.bundle/contract.wasm, and executes each test against a fresh TestEnv that mocks every pyde::* host function:

• Real hash_poseidon2 / hash_blake3 / falcon_verify (via pyde-crypto) so author-side slot derivation + signature verification match the runner exactly.
• Mock storage (sload / sstore / sdelete), account (balance / transfer), context (caller / self_address / wave_id / wave_timestamp / chain_id), tx (tx_value), events (emit_event), halt (revert), cross-call (cross_call / delegate_call), and parachain §8 host fns (parachain_storage_{read,write,delete} / parachain_id / parachain_version / parachain_emit_event) against an in-memory state map.
• Test-only pyde::debug_log printf-style host fn captured in the call's debug log buffer; rejected by otigen build (strict is the default) and always rejected by otigen deploy. Use otigen build --no-strict for local inspection only.
• Host fns that trap with UnsupportedHostFn in v1: origin, tx_hash, tx_gas_remaining, calldata_size, calldata_copy, hash_keccak256, cross_call_static, consume_gas, beacon_get, plus the DKG / threshold-encryption surface. Each either depends on chain-derived state the runner doesn't model, or no canonical example exercises it yet.

What it doesn't do (v1)

• No parallel-execution simulation; calls run sequentially.
• No fuzzing / property tests; example-based only (reserved for a future polish item).
• No multi-tx context — each test starts from fresh state; "deploy in tx1, then call from a different sender in tx2 within one test" isn't expressible (use otigen devnet + otigen call for multi-tx flows).
• No simulating chain-side validators (mempool, access-list, nonce window) — those run on a real node; pair with otigen deploy --network devnet for end-to-end verification.

Every limitation has a future-phase plan in OTIGEN_TEST_SPEC.md §9. The v1 surface is deliberately scoped to what most contract authors need on day one — behaviour, state, events, reverts, gas tracking, cross-contract, FALCON sigs, schema-aware typed args, parachain extension surface — without buying the complexity of fuzz / multi-tx orchestration up front.

When to use what

The three layers (unit / behaviour / integration) compose; each catches things the others miss. otigen test is the middle layer that didn't exist before this rev of the toolchain.

5.13 Reading on

• Chapter 3: Execution Layer — the runtime that contracts compile into.
• Chapter 4: State Model — what sload and sstore see.
• Chapter 11: Account Model — the ENS-style name registry that the toolchain registers against.
• Chapter 13: Cross-Chain (Parachains) — parachain-specific deploy and upgrade flows.
• HOST_FN_ABI_SPEC.md — the locked binary contract between WASM modules and the engine; every imported function the toolchain accepts is in its allowlist.
• OTIGEN_BINARY_SPEC.md — the canonical specification for this binary. Every subcommand, flag, otigen.toml schema rule, bundle format, exit code, and validation pass is defined there. If the implementation and the spec disagree, the spec is right and the code is a bug.
• OTIGEN_TEST_SPEC.md — the canonical specification for otigen test: TOML schema, name resolution, cheatcode catalogue, mock host functions, limitations.

Consensus: Mysticeti DAG

Note: This chapter reflects the post-2026 pivot. The previous HotStuff variant is archived in archive/.

Pyde's consensus is a Mysticeti-style DAG protocol. A committee of 128 validators participates each epoch; every round (~150ms), each member produces exactly one vertex; commits flow continuously at the round rate; finality lands at ~500ms median.

There is no single proposer, no view changes, and no separate prove-then-commit pipeline. Order emerges deterministically from the DAG by every honest validator independently.

1. Why DAG (Why Not HotStuff)

Pyde's previous architecture used a modified pipelined HotStuff with VRF proposer selection. Persistent wedges, head-divergence deadlocks, and view-change cascades motivated a rebuild.

The DAG approach removes the fragile parts:

The same lab/laptop devnet that hit ~4K TPS under pre-pivot HotStuff is the baseline against which DAG performance will be measured. The v1 honest throughput target (to be established by the multi-region performance harness) covers both plaintext and encrypted regimes under production-realistic conditions.

2. Worker / Primary Split (Narwhal Pattern)

Each validator runs:

• Workers (1 or more processes): handle high-volume transaction ingress, build batches, gossip batches peer-to-peer
• Primary (1 process per validator): handles consensus — produces vertices, gathers parents, signs state roots

┌──────────────────────────────────────────────────┐
│ Validator                                        │
│                                                  │
│  ┌───────────────┐   ┌────────────────────────┐ │
│  │   Workers     │   │       Primary          │ │
│  │  (N parallel) │   │                        │ │
│  │               │   │  - One vertex / round  │ │
│  │ - Tx ingress  │◄──┤  - Tracks local DAG    │ │
│  │ - Encryption  │   │  - Anchor selection    │ │
│  │   (if needed) │   │  - State root signing  │ │
│  │ - Batches     │   │  - DKG participation   │ │
│  │ - Gossip      │   └────────────────────────┘ │
│  └───────────────┘                                │
└──────────────────────────────────────────────────┘

This separation is load-bearing: it lets data flow at network-rate while consensus messages stay small (~few KB).

3. The Vertex

#![allow(unused)]
fn main() {
struct Vertex {
    round: u64,
    member_id: u32,                          // committee position
    batch_refs: Vec<BatchHash>,              // batches I have, by hash
    parent_vertex_refs: Vec<VertexHash>,     // ≥85 round-(N-1) hashes
    state_root_sigs: Vec<StateRootSig>,      // attestations on recent commits
    prev_anchor_attestation: VertexHash,     // attests prior anchor
    decryption_shares: Vec<DecryptionShare>, // piggybacked partials
    falcon_sig: FalconSig,                   // sig over the vertex
}
}

Three categories of references in a vertex:

• batch_refs: point to data (batch blobs in worker storage)
• parent_vertex_refs: point to consensus structure (prior round's vertices)
• state_root_sigs + prev_anchor_attestation: point to consensus output (recent commits)

A vertex is dual-role: header (declaring what data I have) AND attestation (acknowledging prior-round work via parent refs). Parent refs ARE the implicit votes — no separate vote messages.

Vertex Size

Compact-encoded (parent refs as bitmap, hash truncation):

• Minimal: ~830 bytes
• Heavy (50 batches + 5 sigs + 85 partials): ~25 KB
• Hard limit: 64 KB

4. Rounds

A round is a layer in the DAG. The round counter is data-driven, not clock-driven:

A member ticks from round N to N+1 the moment they collect ≥85 valid round-N parent vertices in their local DAG view. Slow members lag behind in their counter; the slowest 43 of 128 don't block anyone (128 − 85 = 43 can lag without holding up the rest).

Round 5: [128 vertices, one per member]
            ↑↑↑↑↑ each refs ≥85 of layer 4 ↑↑↑↑↑
Round 4: [128 vertices]
            ↑↑↑↑↑ each refs ≥85 of layer 3 ↑↑↑↑↑
Round 3: [128 vertices]
... etc

Parent rule: parents must be strictly from prior round (round_N - 1). No skip edges in v1. This guarantees acyclicity; violations are slashable.

Round rate: ~5-10 rounds/sec depending on network conditions. Faster than 400ms slots while requiring no clock-based timeouts.

5. Anchor Selection

Each round has a deterministically-selected anchor:

anchor_member_id = Hash(beacon, round, prev_state_root) mod 128

Components:

• beacon: epoch-scoped randomness, published in last wave of prior epoch
• round: current round number
• prev_state_root: state root from N=3 rounds ago (limits anchor predictability to ~450ms)

Properties:

• Deterministic — every honest validator computes the same answer
• Unpredictable — depends on state root that wasn't known until recently
• No single proposer authority — anchor doesn't propose, it's just a starting point for the subdag walk

5b. Round vs Wave — terminology

The distinction matters because the two terms diverge under skips:

• Round = a horizontal layer in the DAG. Every committee member produces exactly one vertex per round. Round numbers always advance (~150ms each), never skip.
• Wave = a successful commit. Wave IDs only increment when an anchor commits. Wave IDs are sparse when rounds skip.

If round 5's anchor (Hash(beacon, 5, prev_state_root) mod 128 = validator 88) is missing:

• Round 5 still happens. The other 127 validators produce their round-5 vertices.
• No wave commits for round 5.
• Round 6 happens; its anchor is a different validator (probably).
• If round 6's anchor succeeds, that wave commits the subdag spanning rounds 5 + 6.

Chain cannot get stuck on one missing anchor. Each round picks a new anchor candidate via the formula, so consecutive failures require consecutive bad luck (or multi-validator outage). The protocol only enters hard-halt territory beyond ~20 consecutive failed anchors (per Chain Halt & Recovery).

Skipped rounds in the chain log

Wave commit records carry both the current anchor_round and the prior_anchor_round. Skipped rounds are implicit from the gap:

WaveCommitRecord(wave_id=6, anchor_round=10, prior_anchor_round=Some(9))   → no skips
WaveCommitRecord(wave_id=7, anchor_round=16, prior_anchor_round=Some(10))  → rounds 11-15 skipped (5 consecutive)

No separate skipped_rounds[] table. The gap IS the record.

5c. Missing-Vertex Handling

When a validator needs a vertex it doesn't have (either the anchor or any vertex in the subdag walk), it fetches the vertex from peers via the dedicated consensus channel.

Validator's local processing:

  Walking anchor → parent V_a → V_a's parent V_b ...
  Hits a missing vertex V_x referenced by some V in the subdag.

  Issues fetch request: get_vertex(V_x_hash) to up-to-8 peers in parallel.
  
  Outcome 1 (typical, ~99.9% of cases):
    A peer responds within <500ms with V_x.
    Validator verifies V_x's FALCON sig, places it in local DAG.
    Continues subdag walk.
    Wave commits normally.

  Outcome 2 (rare):
    No peer responds within the structural timeout (~rounds R+3 materialized).
    Validator marks this commit as "cannot complete."
    Wave does NOT commit; same handling as anchor-skip.
    Vertices stay in DAG; next anchor will retry.

Critical principle: validators NEVER assume "the vertex wasn't gossipped" when missing it. They assume "I haven't received it yet" and fetch. Dropping waves on missing vertices would make the chain trivially censurable.

The fetch protocol lives in the network layer (Chapter 12 + companion/NETWORK_PROTOCOL.md) as a libp2p request-response stream, separate from gossipsub. The fetch is fire-and-retry — ask peer A, if no response in 500ms ask peer B, etc.

Skipped-round recovery walkthrough

5 consecutive skips (rounds 11-15), commit at round 16:

Round:    10      11      12      13      14      15      16
Outcome:  WAVE 6  skip    skip    skip    skip    skip    WAVE 7
                  (vertices still produced;
                   accumulate in DAG)
                                                          ↑
                                                          subdag walk goes back
                                                          to wave 6's frontier

At round 16's commit (wave 7):
  Subdag walk from v_r16_anchor:
    - v_r16_anchor's parents = 85+ round-15 vertices
    - each round-15 vertex's parents = 85+ round-14 vertices
    - ...continue back through rounds 14, 13, 12, 11
    - round-11 vertices' parents = 85+ round-10 vertices ← STOP
                                    (these were committed in wave 6)
  
  Subdag = vertices from rounds 11, 12, 13, 14, 15, 16
         ≈ 6 × 128 = 768 vertices total

  Execute all txs in canonical order (round ascending → member_id → list_order)
  Compute state_root after applying all changes
  Compute events_root (Blake3 Merkle tree over canonical-ordered events) + events_bloom
  Sign HardFinalityCert(wave_id=7, state_root, events_root, events_bloom)
  Wave 7 record: WaveCommitRecord(wave_id=7, anchor_round=16, prior_anchor_round=Some(10),
                                  state_root=..., events_root=..., events_bloom=...,
                                  events_count=..., tx_count=..., gas_used=...)

The wave commit record carries both state and events summaries; both are threshold-signed in the HardFinalityCert so light clients verify event inclusion identically to state. Full structure + indexing mechanics: Host Function ABI Spec §15.2.

Properties:

• Zero tx loss. Every vertex produced eventually commits.
• Bounded latency cost. Each skip adds ~150-300ms to confirmation time.
• No special "catch up" code. The standard subdag-walk handles it. The BFS just walks more rounds when there's a wider gap.

6. Commit

When the anchor vertex collects sufficient support from later rounds (Mysticeti 3-stage support), a commit fires:

1. Anchor selected (deterministic by formula above)
2. Walk anchor's parent_vertex_refs transitively → collect "subdag"
3. Sort subdag deterministically:
     - primary key: round number ascending
     - secondary key: member_id
     - tertiary key: list order within vertex
4. For each vertex in sorted order, dereference batch_refs
5. For each batch, threshold-decrypt (pipelined ceremony — partials already in flight)
6. wasmtime executes decrypted batches in canonical order
7. State root computed (Blake3 + Poseidon2 dual)
8. ≥85 committee FALCON-sign state root (piggybacked on next-round vertices)
9. ≥85 state-root sigs collected → finality declared

Commit Rate

• ~95% of rounds commit successfully in steady state
• ~5% skip (anchor offline or insufficient support); next round absorbs the data
• Average finality: ~500ms median, ~1s p99

No Skip Penalty

When a round skips, its vertices aren't lost — the next round's commit absorbs them via parent-chain traversal. Slow validators just contribute slightly later.

7. Committee

Size & Selection

• 128 active committee members per epoch, selected from the global validator pool
• Selection: uniform random from all validators with stake ≥ MIN_VALIDATOR_STAKE = 10,000 PYDE (single-tier model; no separate committee vs non-committee stake floor)
• Anti-Sybil: operator identity binding, max 3 validators per operator
• Epoch length: ~3 hours wall-clock (commit count varies with network conditions — typically ~21,600 commits at the 500 ms median cadence)

# T-30min in epoch N: beacon_N+1 has just been finalized (see §9).
# Every staked validator now derives the committee for epoch N+1:
eligible = [v for v in all_validators
            if v.stake >= MIN_VALIDATOR_STAKE and not v.jailed]
for slot in 0..128:
    seed = Hash(beacon_N+1, slot)
    member = uniform_random_pick(eligible, seed)
    committee[slot] = member
    eligible.remove(member)  # without replacement
# Committee N+1 immediately begins DKG — see §10 for the boundary timing.

Equal Power Within Committee

All 128 members have equal voting weight, equal vertex production rate, equal anchor probability (uniform over members). Stake influences only:

• (a) eligibility (must meet MIN_VALIDATOR_STAKE = 10,000 PYDE)
• (b) proportion of the stake-weighted reward pool (yield distributes by stake × uptime)

Activity rewards within the committee are contribution-weighted, not stake-weighted.

Why No Stake-Weighted Voting

• Sybil attack mitigated by operator identity cap (not by stake weight)
• Within-committee equality aligns with classical BFT theory
• Reduces plutocracy pressure
• Simpler protocol math (no stake weights in BFT thresholds)

8. BFT Properties

For n=128 validators:

• f = ⌊(n-1)/3⌋ = 42 (maximum Byzantine)
• threshold = 2f+1 = 85 (quorum for commit / vertex cert / threshold decrypt)

The number 85 appears throughout the protocol:

• Vertex certification (parent refs in next round)
• Commit support
• Threshold decryption shares
• State root signatures
• DKG share threshold

Consistent across the protocol — avoids attack edges from boundary mismatches.

Safety

Holds under any network conditions assuming at most f = 42 Byzantine members (the BFT tolerance ⌊(n-1)/3⌋ with n = 128). Safety property: no two conflicting commits.

Liveness

Holds under partial synchrony (messages eventually delivered, bounded clock skew).

9. Randomness Beacon

Each epoch's beacon is produced by the previous epoch's committee. The beacon for epoch N+1 must be finalized with enough lead time for committee N+1 to be selected (via VRF on beacon_N+1) and run DKG before the epoch boundary. The architectural target uses a threshold-signature primitive; v1 ships a FALCON-aggregate approximation (called out below).

Target design (threshold-sig — long-term)

1. All 128 committee N members sign known message "epoch_N+1_beacon" with
   threshold-share keys (DKG'd at the start of epoch N)
2. ≥85 shares Lagrange-combine into ONE deterministic aggregated signature
3. beacon_N+1 = Hash(aggregated_signature) → 32 bytes
4. Finalized at T-30min (last 30 min of epoch N) — see §10 for why

Properties of the target design:

• Deterministic given any 85 of 128 shares (Lagrange invariance — same aggregated sig regardless of which 85 contribute)
• Unpredictable until ≥85 shares combine (no single party knows it)
• Bias-resistant — shares determined by DKG-derived keys, no individual member can grind by choosing whether to participate; the aggregated output doesn't depend on subset selection

v1 implementation (FALCON-aggregate approximation)

pyde-crypto does not yet ship a post-quantum threshold-signature primitive — post-quantum threshold sigs are research-level (see WHITEPAPER §3 honest-tradeoffs section). v1 ships a FalconBeaconScheme that approximates the target by hash-concatenating individual FALCON sigs:

1. Each member i signs the epoch message with their own individual FALCON
   beacon keypair (persisted on disk, separate from consensus FALCON keypair)
2. Shares gossip via pyde/beacon-shares/1
3. Combine: lowest-member-id 85 shares are sorted, concatenated, and
   blake3-hashed → beacon_N+1

The v1 approximation deviates from the target design in two ways:

• Subset disagreement is structurally possible because the hash depends on which 85 shares are included, not just that 85 contributed. v1 fixes this by hardcoding a canonical-subset rule (combine MUST use exactly the lowest-member_id 85 shares) so every validator deterministically agrees on the same 85.
• Last-signer grinding bias (~1 bit per epoch): a member who signs late sees prior shares and could compute beacon_if_I_sign vs beacon_if_I_withhold. Bounded by the prev_beacon hash-chain (compounds against the adversary across epochs) and by the ≥85 honest sigs always inside the hash. Full elimination waits for true threshold sigs.

When pyde-crypto ships threshold-FALCON or an equivalent post-quantum threshold-sig primitive, the BeaconScheme trait swaps cleanly to the target design without consensus-side changes.

10. DKG (Distributed Key Generation)

Each epoch transition, the new committee runs DKG to produce a fresh threshold encryption key. The "old committee makes beacon, new committee runs DKG" split keeps key generation truly distributed (only the new committee members contribute their own per-member randomness to the new key) while the old committee handles the bootstrap randomness via the beacon.

Pedersen DKG, multi-round protocol (~30-60s in background):

Round 1: Each member i picks random secret polynomial f_i(x), degree 84
Round 2: Each member broadcasts public commitments to f_i's coefficients
Round 3: Member i sends f_i(j) to each other member j (encrypted point-to-point)
Round 4: Member j verifies received shares against public commitments,
         sums valid shares: s_j = Σ f_i(j) = f(j)
         where f(x) = Σ f_i(x) is the combined polynomial

Result:
  - Each member j holds s_j = f(j) (private share)
  - Public key PK derived from public commitments
  - SK = f(0) is NEVER computed
  - Threshold = 85 of 128

Mathematical foundation: any 85 points on a degree-84 polynomial uniquely determine it (Lagrange interpolation). 84 points don't.

Timing: ~30 min tail window of the prior epoch

DKG runs during the last ~30 minutes of epoch N so committee N+1 has its threshold key ready by the epoch boundary. The full chicken-and-egg sequence:

T-30min (last 30 min of epoch N):
  ├── beacon_N+1 finalized (see §9 — old committee's combine ceremony)
  ├── every staked validator runs VRF(validator_sk, beacon_N+1)
  ├── lowest 128 VRF outputs become committee N+1
  ├── committee N+1 begins DKG IMMEDIATELY
  │   (Pedersen-style rounds + complaint window propagate within minutes;
  │    ~30 min leaves comfortable margin for stragglers and retries)
  └── committee N continues serving consensus + threshold decryption

EPOCH BOUNDARY (T=3hr):
  ├── DKG complete → committee N+1 has threshold encryption key
  ├── committee N hands over instantly
  └── threshold decryption continuous — no downtime

Important: beacon production in v1 does NOT depend on DKG — each member signs beacon shares with their individual FALCON beacon keypair (the BeaconKeypair, distinct from the consensus FALCON keypair). DKG is purely for threshold decryption. So:

• Consensus + beacon handover is instant at epoch boundary
• DKG propagation delay only blocks threshold decryption (encrypted txs), never consensus
• If DKG ever fails to complete in the tail window (network partition, complaint storm), encrypted txs queue until DKG finishes — plaintext consensus continues unaffected

Why ~30 min and not less: DKG rounds + complaints + gossip diameter across a 128-member global committee land in the 30-60 second range under good conditions, but the complaint protocol can re-run if any member is contested. 30 min absorbs the worst-case retry path at the 3-hour epoch length.

11. Threshold Decryption Ceremony

Encryption is per-transaction, not per-batch. A batch can contain any mix of plaintext and encrypted transactions. The threshold-decryption ceremony runs per encrypted transaction.

After commit fires, for each encrypted transaction across the canonical-ordered subdag:

Each committee member i (during prior rounds — pipelined):
  - For each encrypted tx observed in mempool batches:
      partial_i = ApplyShare(s_i, ciphertext_of_tx)
      (single elliptic-curve op or polynomial multiplication, ~100μs-1ms)
      + FALCON sig over (partial_i, tx_hash)
  - Piggyback the partial(s) on next-round vertex (no separate message channel)

At commit time:
  - Subdag walk identifies all encrypted txs in the wave
  - Collect their partials from the subdag's vertices (decryption_shares field)
  - For each encrypted tx:
      - Verify each partial's FALCON sig (~80μs per share)
      - Once ≥85 valid partials collected: Lagrange interpolation → plaintext
  - Batch the combine work: share-application math vectorizes well on SIMD/GPU
  - wasmtime executes decrypted (plus already-plaintext) txs in canonical order

Pipelining

Partials are computed as soon as the encrypted tx enters the mempool DAG, before the commit fires. By commit time, partials are typically 80%+ propagated through vertex gossip. Effective post-commit decryption latency: tens of milliseconds.

Scale via batched share-combine

Headroom analysis, not a v1 claim. v1's honest encrypted-throughput target is to be established by the multi-region performance harness. The math below sizes what it would take to push encrypted throughput well beyond that — useful for understanding the scaling lever, not a v1 promise.

At encrypted throughput well beyond the v1 target:

• Per-tx ceremony: 85 partials × ~80μs verify + ~1ms Lagrange = ~8ms CPU work
• Multiplied across a high transaction rate, that per-tx cost overruns a single core's per-second budget — naive sequential combine isn't feasible. But share-combine vectorizes:
  • Group partials by ciphertext, combine in parallel across cores
  • GPU acceleration on the share-combine path is the realistic post-v1 scale lever

See WHITEPAPER §11 for honest scaling limits.

12. State Root Attestation

After wasmtime execution, each member computes the state root locally (deterministic from input). Members FALCON-sign the state root with explicit hash inclusion:

#![allow(unused)]
fn main() {
struct StateRootSig {
    commit_id: u64,
    state_root_hash: Hash,        // explicit — both Blake3 and Poseidon2
    signer_id: u32,
    falcon_sig: FalconSig,        // FALCON over (commit_id || root_hash)
}
}

Sigs piggyback on next-round vertices. Finality requires:

• ≥85 sigs
• All attesting the same root hash
• All FALCON sigs verify

If sigs attest different roots → fork detected → hard halt (see CHAIN_HALT.md).

13. Failure Detection & Halts

Three types of halts:

See CHAIN_HALT.md for full halt + recovery procedures. Rollback is bounded to 1 epoch (~3 hours) — operational flexibility without arbitrary commit reversibility.

14. Slashing

Equivocation, bad state-root signatures, invalid vertices, bad decryption shares, DKG failure, share withholding, extended downtime — all slashable. See SLASHING.md for the full catalog.

Correlated slashing applies a 2× multiplier when many validators offend simultaneously (punishes coordination, protects isolated failures).

15. Recovery Properties

• Single validator offline: other 127 continue normally. Validator catches up via gossip; loses activity rewards.
• 43+ validators offline (at the BFT quorum boundary, 85 active = 2f+1 with no margin): soft stall; downtime slashing PAUSES (partition-aware); resumes when active count returns to 86+ (one above the quorum minimum).
• Network partition: majority-side continues if quorum maintained; minority stalls.
• State root divergence: hard halt; investigation; rollback within 1 epoch; slashing for wrong-root signers.

The chain self-heals from any subset failure that maintains ≥85 functional validators.

16. Comparison

17. Implementation Status

🔴 Mysticeti DAG implementation: not yet built. Pre-pivot HotStuff archived in archive/.

Implementation strategies:

• Option A: Fork Sui's Mysticeti (open source) and adapt to FALCON sigs. Saves substantial consensus engineering — Mysten Labs has spent years getting the algorithm correct.
• Option B: Write from scratch for full control. Larger surface to audit, more bugs to find.

Recommendation: Option A for v1. The work is audit + adaptation for FALCON sigs; correctness of the core algorithm leverages Mysten Labs' existing engineering.

References & Cross-References

• Full design: DESIGN.md §Consensus
• Threat model (consensus threats): THREAT_MODEL.md §Consensus Layer
• Failure scenarios: FAILURE_SCENARIOS.md
• Chain halt: CHAIN_HALT.md
• Slashing: SLASHING.md
• Validator lifecycle: VALIDATOR_LIFECYCLE.md
• Research papers:
  • Mysticeti (Babel et al., 2024) — https://arxiv.org/abs/2310.14821
  • Bullshark (Spiegelman et al., 2022)
  • Narwhal (Danezis et al., 2021)

State Sync & Chain Halt

This chapter covers how new nodes join the network (state sync) and what happens when consensus encounters problems (chain halt + recovery). Both are operational concerns that the design must address explicitly — the HotStuff pre-pivot architecture lacked clear procedures for both, contributing to the wedges that motivated the pivot.

Part 1: State Sync

The Problem

At the chain's sustained throughput, replaying every block from genesis is infeasible (the transaction count runs into the trillions per year). A new node joining the network needs a way to reach current state without full replay.

Three Sync Modes

Snapshot Architecture

Decoupled signing and chunk generation:

• Committee signs state root (cheap, every epoch boundary)
• Volunteers generate chunks (heavier, daily cadence)

#![allow(unused)]
fn main() {
struct SnapshotManifest {
    epoch: u64,
    snapshot_state_root_blake3: Hash,
    snapshot_state_root_poseidon2: Hash,
    chunk_manifest: Vec<ChunkRef>,
    current_committee_pubkeys: Vec<FalconPubkey>,  // chain-of-trust
    signatures: Vec<FalconSig>,                     // ≥85 from prior committee
}
}

Why dual roots: Blake3 for fast native verification by syncing nodes; Poseidon2 for future ZK light-client compatibility.

Snapshot Cadence

• Committee root signing: every epoch boundary (cheap, ~5 KB manifest)
• Chunk publishing: every 8 epochs (~daily) by volunteer infrastructure
• Tail sync window: up to 24 hours of txs to catch up

Verification Flow

Phase 1: Discover & Verify Manifest
  1. Bootstrap from seed peers
  2. Discover manifest URLs/hashes from peers
  3. Download signed manifest (~5 KB)
  4. Verify ≥85 FALCON sigs against trusted committee pubkeys

Phase 2: Download Chunks
  5. Discover peers serving snapshot
  6. Download chunks in parallel (4 MB each)
  7. Verify each chunk_hash against manifest
  8. Bad chunks → ban peer, retry

Phase 3: Reconstruct State
  9. Apply chunks to JMT
  10. Compute Blake3 state root locally
  11. Compare to manifest
  12. Accept if match

Phase 4: Recent Sync (Tail)
  13. Download blocks from snapshot point to current
  14. Replay txs against snapshot state
  15. Reach current state

Phase 5: Active Operation
  16. Subscribe to gossip; begin participation

Chain-of-Trust Bootstrap

A new node verifies the chain of snapshot manifests from genesis:

Genesis block: contains committee_0.pubkeys (hardcoded)
  ↓
Snapshot at epoch 8: signed by committee 0, contains committee_8.pubkeys
  ↓
... etc forward, each signed by prior committee

For nodes that prefer speed over trustless verification: weak subjectivity checkpoints are published by foundation + reputable infrastructure providers. New nodes can trust a recent checkpoint and sync from there.

Light Client Mode

For mobile wallets, browser dApps:

• Storage: block headers only + cared-about accounts
• Operations: verify FALCON sigs on headers (~7ms), query accounts via JMT inclusion proofs
• Bandwidth: ~600 KB/year typical wallet usage

Time Estimates (Commodity, 100 Mbps)

Bootstrap from genesis (small):       ~5 seconds
Manifest verification (85 FALCON):    ~7 ms
Snapshot download (3 GB):             ~4 minutes
JMT reconstruction:                   ~5 minutes
Recent tail sync (8 epochs):          ~30 minutes
Total:                                ~40 minutes

See STATE_SYNC.md for complete protocol details.

Part 2: Chain Halt + Recovery

The HotStuff pre-pivot architecture suffered persistent wedges with no clear halt → investigate → recover procedure. The team patched live, accumulating safety subtleties. Pyde's post-pivot design EXPLICITLY:

• Separates three halt types
• Defines authority + procedure for each
• Builds drills into the operational plan

Three Halt Types

Detection

Soft stall (automatic):

• No commit > 5 rounds (~5 sec)
• <85 vertices certified
• Active committee count < 86

Hard halt (automatic):

• State root divergence (2+ signed contradictory roots)
• Equivocation cluster (10+ in single epoch)
• DKG output mismatch
• Execution layer critical invariant violation
• DAG fork detected (should be impossible)

Emergency halt (manual):

• Critical bug discovery (off-chain)
• Active exploit
• Hard-fork coordination

What Happens During Halt

Key invariant: slashing evidence accepted during halt — attackers cannot escape consequences by triggering a halt.

Recovery Procedures

1. Wait it out (soft stalls) — auto-recover
2. Software update + replay (hard halts from bugs) — patch, verify, resume
3. Rollback (max 1 epoch back, governance authorized) — controversial but bounded
4. Hard fork (irreconcilable splits) — coordinated upgrade
5. Emergency unhalt (false positives) — multisig releases

Rollback Policy

Bounded operational pragmatism:

• Maximum rollback window: 1 epoch (~3 hours)
• Within window: governance multisig can authorize
• Beyond window: only hard fork (community coordination required)

This is "weak finality with sunset" — operational flexibility for early detection without arbitrary commit reversibility. Industry standard pattern.

Test Plan

Mandatory drills before mainnet:

1. Soft stall: deliberately offline 43 validators
2. Hard halt: inject state divergence
3. Emergency halt: practice multisig coordination
4. Rollback: 1-epoch procedure
5. Hard fork: coordinated upgrade

Frequency: quarterly in testnet, annually in mainnet. Runbooks per scenario, updated after every drill.

The HotStuff Lesson Applied

HotStuff broke because there was no clear halt procedure — patches accumulated under pressure. Pyde now has:

• Automatic detection of safety violations
• Explicit halt classification
• Pre-rehearsed recovery procedures
• Drill schedule

See CHAIN_HALT.md and FAILURE_SCENARIOS.md for complete operational specs.

References

• Full state sync spec: STATE_SYNC.md
• Full halt spec: CHAIN_HALT.md
• Failure scenarios + drills: FAILURE_SCENARIOS.md
• Validator lifecycle (jail mechanics): VALIDATOR_LIFECYCLE.md

Chapter 8: Cryptography

Pyde's cryptographic stack is post-quantum from genesis. There are no elliptic curves anywhere in the protocol — no secp256k1, no ed25519, no BLS12-381. Every primitive used to authenticate transactions, exchange keys, hash state, or prove randomness is built on lattices or hash functions.

This chapter specifies every primitive with the parameters Pyde actually ships, where they live in the codebase, and how they fit together.

8.1 Design Principles

Three constraints shape every choice:

1. Post-quantum security. Every primitive must resist both classical and known quantum attacks (Shor for factoring/DLP, Grover for brute force). This rules out RSA, ECDSA, EdDSA, BLS, ECDH, and anything else built on elliptic curves or integer factorization.

2. No trusted setup. No ceremony, no toxic waste. Every public parameter is either a NIST standard or a transparent algebraic constant.

3. Hybrid hashing — Blake3 for speed, Poseidon2 for ZK. Bitwise hashes (Blake3) saturate modern CPUs at multi-GB/s and dominate the high-volume native paths (JMT internals, gossip de-dup, batch hashes). Algebraic hashes (Poseidon2) are 30-50× slower in native execution but roughly 1000× cheaper inside an algebraic constraint system (STARK, future ZK validity proof). Pyde uses both: Blake3 where the work is off-chain or committee-signed, Poseidon2 where the hash may be exposed to a ZK circuit (state root, address derivation, signature payloads).

Traditional blockchain crypto stack:
  Signatures:   ECDSA (secp256k1)        broken by quantum
  Key exchange: ECDH                      broken by quantum
  Hashing:      Keccak-256                quantum-safe; not ZK-native
  Randomness:   BLS-based VRF             broken by quantum

Pyde crypto stack:
  Signatures:   FALCON-512                lattice (NIST FIPS 206)
  Key exchange: Kyber-768 / ML-KEM        lattice (NIST FIPS 203)
  Hashing:      Blake3 + Poseidon2        hybrid: speed + ZK-friendly
                  Blake3 (Goldilocks-free, ~3 GB/s)
                    JMT internals, batch hashes, vertex hashes, gossip
                  Poseidon2 (Goldilocks field, ZK-native)
                    state root, addresses, MAC, VRF output, RNG mix
  Threshold:    Shamir over Goldilocks + Kyber + Poseidon2 KDF/MAC
  PSS resharing: Lagrange interpolation over Goldilocks
  Randomness:   Lattice VRF (FALCON-proof + Poseidon2 output)
  Symmetric:    AES-256-GCM (hardware-accelerated)

The whole stack lives under crates/crypto.

8.2 FALCON-512: Digital Signatures

FALCON (Fast Fourier Lattice-based Compact Signatures over NTRU) is Pyde's signature scheme. NIST standardized it as part of FIPS 206. Pyde uses the FALCON-512 parameter set (LOGN = 9, dimension 512).

Why FALCON-512 over Dilithium / SPHINCS+

A blockchain hashes signatures into every transaction, every consensus vote, and every finality certificate. A 666 B FALCON sig × 128 committee × per-slot finality cert × 10K blocks/hour adds up — Dilithium's 2420 B would inflate that by 3.6×, SPHINCS+ by ~12×. FALCON's compactness is what keeps the bandwidth budget reasonable.

Parameter set

API

crates/crypto/src/falcon.rs exposes:

#![allow(unused)]
fn main() {
pub fn falcon_keygen() -> (FalconPublicKey, FalconSecretKey);
pub fn falcon_sign(sk: &FalconSecretKey, msg: &[u8]) -> FalconSignature;
pub fn falcon_verify(pk: &FalconPublicKey, msg: &[u8], sig: &FalconSignature) -> bool;
pub fn falcon_batch_verify(items: &[(&FalconPublicKey, &[u8], &FalconSignature)]) -> bool;
}

Determinism

Signing is deterministic. The implementation ties the FALCON Gaussian sampler to a deterministic context derived from the input message, so the same (secret_key, message) always produces the same signature. This is what makes the lattice VRF (§8.7) work — the output is a deterministic function of the inputs.

The domain-separation tag b"pyde-falcon-v1" is mixed into the signing context to prevent cross-protocol signature reuse.

Where FALCON-512 is used

1. Transaction signing — every transaction carries a FALCON-512 sig from the sender's account.
2. Vertex production — every DAG vertex is FALCON-signed by its producer.
3. State-root attestations — committee members sign (wave_id, blake3_state_root, poseidon2_state_root) after each commit; ≥ 85 sigs constitute the HardFinalityCert.
4. Decryption share authentication — threshold partial decryptions are FALCON-signed by their producer.
5. PSS resharing contributions — contributors sign their shares.
6. P2P peer authentication — the FALCON handshake (crates/net/src/auth.rs).
7. VRF proofs — every VRF output is paired with a FALCON proof.
8. Slashing evidence — submitters sign their evidence transactions.

Batch verification

falcon_batch_verify checks an array of (pk, msg, sig) triples sequentially. The current implementation is not algebraically batched — it returns true only if every individual verification succeeds. Algebraic batch verification (sharing FFT operations across signatures) is on the post-mainnet hardening list; the sequential version is correct and meets the current per-block budget.

8.3 Kyber-768 / ML-KEM: Key Encapsulation

Kyber is Pyde's key encapsulation mechanism. NIST standardized it as ML-KEM under FIPS 203. Pyde uses the Kyber-768 parameter set, NIST Security Level 3.

What is a KEM?

A KEM lets two parties agree on a shared secret without the symmetric key ever crossing the wire. Alice runs encaps(pk) -> (ciphertext, shared_secret) and sends the ciphertext to Bob. Bob runs decaps(sk, ciphertext) -> shared_secret. They now share a 32-byte symmetric key, which Pyde uses as the AES-256-GCM key for the actual payload encryption.

Parameters

API

crates/crypto/src/kyber.rs:

#![allow(unused)]
fn main() {
pub fn kyber_keygen() -> (KyberPublicKey, KyberSecretKey);
pub fn kyber_encapsulate(pk: &KyberPublicKey) -> (KyberCiphertext, SharedSecret);
pub fn kyber_decapsulate(sk: &KyberSecretKey, ct: &KyberCiphertext) -> SharedSecret;
}

The dependency is ml_kem = "0.3.0-rc.0" — a release-candidate of the NIST final standard. Upgrading to the stable release once published is tracked as post-mainnet hardening (task 057 in the mainnet plan).

Where Kyber is used

1. P2P transport key exchange. When two nodes establish a libp2p connection, the QUIC handshake uses a hybrid Ed25519 + Kyber key exchange (Ed25519 for the libp2p PeerId, Kyber for forward-secure session keys). See Chapter 12.
2. Threshold encryption for the encrypted mempool. The committee's threshold public key is a Kyber-768 key whose secret has been Shamir-split across 128 validators. See §8.5.

8.4 Hashing: Blake3 + Poseidon2

Pyde uses two hash functions, each chosen for a class of paths:

Blake3

Blake3 is the BLAKE family successor — based on the BLAKE2 compression function arranged as a parallelizable Merkle tree, with hardware acceleration on every modern CPU. Pyde uses Blake3 in its default configuration (256-bit output) for every hash that lives entirely off-chain or inside a trusted committee-signed structure.

Key Pyde-specific uses:

• JMT internal nodes — blake3_pair(left, right) per Merkle level. At commodity CPU speed, an entire JMT update batch hashes in microseconds.
• Batch hashes referenced from vertices — the worker batches transactions and identifies each batch by its Blake3 hash.
• Vertex hashes in the DAG — every consensus vertex is identified by its Blake3 hash.
• Gossip message de-duplication — Gossipsub uses Blake3 to detect duplicate broadcasts.
• RocksDB cache keys — Blake3 fingerprint of (key, version) for the LRU value cache.

Poseidon2: ZK-Friendly Hashing

Poseidon2 is the algebraic hash function used on paths that may be exposed to a ZK circuit, plus a handful of legacy paths kept for compatibility.

Why not Keccak or SHA-256?

Inside an algebraic system (a STARK, an MPC protocol, a future ZK validity proof), bitwise hash functions like Keccak-256 are catastrophically expensive — roughly 150,000 algebraic constraints per Keccak hash compared to a few hundred for Poseidon2. Even though Pyde doesn't ship a STARK at mainnet, the threshold-encryption MAC and the lattice VRF both benefit from a hash that's cheap inside an algebraic field, and the JMT itself amortizes the per-Merkle work better when the hash is field-native.

Construction

Poseidon2 is a sponge construction over a prime field. Pyde uses the Goldilocks field (p = 2^64 − 2^32 + 1) because:

• Single field elements fit in a 64-bit register.
• Modular reduction is a shift-and-subtract.
• Hardware AES is independent of this field, so we can use both efficiently.

Parameters

(Verified in crates/crypto/src/poseidon2.rs test suite.)

API

#![allow(unused)]
fn main() {
pub fn poseidon2_hash(data: &[u8]) -> Hash256;
pub fn poseidon2_pair(left: Hash256, right: Hash256) -> Hash256;
pub fn poseidon2_many(hashes: &[Hash256]) -> Hash256;
}

Domain separation is built into the encoding: variable-length inputs are length-prefixed before sponge absorption, and field elements are packed 7 bytes at a time (avoiding values that exceed the Goldilocks modulus).

Where Poseidon2 is used

1. State root commitment — the dual-rooted state has a Poseidon2 root alongside the Blake3 root, signed by the committee.
2. Account address derivation — Poseidon2(falcon_pubkey).
3. CREATE / CREATE2 address derivation — Poseidon2(deployer || nonce) or Poseidon2(0xFF || deployer || salt || code_hash).
4. Storage key derivation — Poseidon2(contract, slot) for single fields, doubled for maps. Encoded as build-time constants by the otigen developer toolchain's state binding generator.
5. Transaction hashing — the canonical tx hash used for replay prevention and the wallet's signing target.
6. Threshold MAC — Poseidon2(0xFF...0xFF || secret || ciphertext).
7. VRF output — Poseidon2(domain || fingerprint || input).
8. Epoch randomness combination — Poseidon2_many(sorted_shares).
9. poseidon2 WASM host function — exposed to user-space contracts via the host-function ABI.

8.5 Threshold Encryption (Mempool MEV Protection)

Threshold encryption is what lets the encrypted mempool work: messages are encrypted such that no single validator (or coalition of < 85) can decrypt, but the active committee acting collectively can.

Construction

The scheme combines three pieces:

1. Shamir Secret Sharing over the Goldilocks field — splits a secret into 128 shares of which any 85 reconstruct.
2. Kyber-768 KEM — the underlying public-key primitive.
3. Poseidon2 as a counter-mode keystream and as the MAC.

Implementation: crates/crypto/src/threshold.rs.

Setup (per epoch)

1. Generate a Kyber-768 keypair: (pk, sk_seed)
2. Split sk_seed into 128 shares using Shamir SSS:
     - Random degree-(t-1) polynomial f over Goldilocks where t = 85
     - f(0) = sk_seed
     - share_i = (i, f(i)) for i in 1..=128
3. Distribute share_i to validator i
4. Publish pk as the committee's threshold public key

Encryption (user wallet)

(ciphertext, shared_secret) = Kyber.Encaps(pk)
keystream = Poseidon2_keystream(shared_secret, message_length)
encrypted_payload = message XOR keystream
mac = Poseidon2(0xFF...0xFF || shared_secret || ciphertext)
wire = (ciphertext, encrypted_payload, mac)

Decryption (committee)

For each ciphertext in the encrypted block:
    Each validator i computes a blinded share:
        blinded_i = raw_share_i + H(ct_hash || i || elem_idx)
    Validator broadcasts blinded share on the consensus channel.
    Combiner collects >= 85 shares, unblinds them by subtracting the
    same H() values, then Lagrange-interpolates at x=0 to recover the
    Kyber decapsulation seed.
    Kyber.Decaps(seed, ciphertext) -> shared_secret
    Verify MAC; on success, decrypt payload with the keystream.

Share blinding

Each share is blinded with a per-ciphertext, per-element mask (H(ct_hash || validator_idx || element_idx)) before transmission. This prevents a validator's share from ciphertext A from being reused against a different ciphertext B — even if a validator's share leaked, an attacker couldn't apply it to other blocks. The combiner has the ciphertext and can unblind during recovery.

Parameters

8.6 PSS — Proactive Secret Sharing and Resharing

The committee rotates each epoch; the threshold public key does not change. PSS is what makes that work — at every epoch boundary the shares are refreshed without anyone learning the underlying secret.

Why PSS

Without PSS, every committee rotation would require a fresh distributed key generation (DKG), which is O(n^2) interactive and slow. PSS achieves the same goal with a single round of asynchronous contributions per validator.

Same-committee refresh

Used for routine forward-security refresh:

Each member generates a degree-(t-1) polynomial f_i with f_i(0) = 0.
Each member sends f_i(j) to every other member j.
Each member j updates: new_share_j = old_share_j + Σ f_i(j)
Because every f_i(0) = 0, the underlying secret is unchanged.
But every share is now drawn from a fresh combined polynomial.

The verification check verify_refresh_contribution confirms the first t evaluations interpolate back to zero — catching contributors who tried to inject a non-zero free term.

Cross-committee resharing

Used at epoch boundaries when membership changes:

Each old member i with share s_i picks a fresh degree-(new_t - 1)
polynomial g_i with g_i(0) = s_i. They evaluate at the indices of
the new committee and ship the resulting sub-shares.

Each new member j collects threshold contributions, applies a
canonical-subset rule (lowest-from_old_index first), and aggregates:
    new_share_j = Σ (lambda_i × g_i(j))
where lambda_i are Lagrange coefficients at x=0 over the OLD indices.

Result: H(0) = original secret; H is the new polynomial; the new
committee sits on H.

The canonical-subset rule is critical. Different new members must deterministically agree on which t contributions to use, or they end up on different polynomials. The rule: sort contributions by from_old_index, take the first t. This is implemented as canonical_resharing_subset() in crates/crypto/src/threshold.rs.

The aggregation delay

Because the network delivers contributions asynchronously, every new member waits RESHARE_AGGREGATION_DELAY_ROUNDS = 5 rounds after entering the new epoch before aggregating. This guarantees that the same canonical set is visible to every new member when aggregation begins.

Known limitation: no VSS / KZG commitments

The current verify_refresh_contribution and verify_resharing_contribution detect polynomial inconsistency — if the sub-shares aren't all on the claimed polynomial, the check fails. They do not detect a malicious member who consistently presents a polynomial whose constant term is not their actual share s_i. This would silently cause the new committee to derive shares of a different secret, and threshold decryption would stop working at the start of the next epoch.

The mitigation requires Pedersen or KZG commitments on the shares — a substantial crypto upgrade. For mainnet, the assumption is "committee-member compromise is rare," and any such corruption surfaces as a hard decryption failure within the first block of the affected epoch (highly visible). The upgrade is tracked as post-mainnet research.

8.7 Lattice VRF

Pyde's VRF is built on FALCON-512. The construction:

Output (deterministic):
    fingerprint = Poseidon2("pyde-vrf-output-v1" || sk_bytes)
    output      = Poseidon2("pyde-vrf-output-v1" || fingerprint || input)

Proof:
    msg   = "pyde-vrf-proof-v1" || pk || input || output
    proof = falcon_sign(sk, msg)

Verify(pk, input, output, proof):
    msg  = "pyde-vrf-proof-v1" || pk || input || output
    return falcon_verify(pk, msg, proof)

Properties

Where the VRF is used

1. Anchor selection (indirect). Each round, the canonical anchor is computed as Hash(beacon, round, prev_state_root) mod 128 (see Chapter 6 §3). The beacon itself is the threshold-aggregated VRF output of the prior epoch's committee — so VRF underpins anchor selection one step removed, not per-round.
2. Epoch randomness contributions. Each member of the previous epoch's committee contributes a VRF share that, combined with 84 others, seeds the next epoch's beacon.
3. Committee selection scoring. At each epoch boundary, every registered validator gets a VRF score from epoch_randomness || "committee"; the uniform-random subset of eligible validators chosen by this score forms the next committee.

8.8 Symmetric Encryption: AES-256-GCM

All symmetric encryption uses AES-256-GCM:

1. Threshold-encrypted transaction payloads. Once the Kyber KEM gives the wallet a 32-byte shared secret, the payload is encrypted with AES-256-GCM under that secret.
2. P2P channel encryption (after the libp2p QUIC handshake — see Chapter 12).
3. Wallet keystore encryption (crates/pyde-rust-sdk/src/wallet.rs).

Properties

• 256-bit key (128-bit post-quantum security against Grover).
• AEAD — authenticated encryption with additional data; tampering is detected.
• AES-NI hardware acceleration on every modern CPU.

8.9 Key Derivation and Address Format

From keypair to address

Master seed (user-provided or random)
    -> SHAKE-256 (with domain separator) -> FALCON keygen seed
    -> FALCON-512 keygen
        |
        +-> Public key (897 bytes)
        |
        +-> Secret key (1281 bytes)

Address derivation:
    EOA address = Poseidon2(falcon_public_key)              // 32 bytes
    CREATE      = Poseidon2(deployer_address || nonce)
    CREATE2     = Poseidon2(0xFF || deployer || salt || code_hash)

Why 32-byte addresses

Pyde uses 32 bytes (the full Poseidon2 output) instead of Ethereum's 20-byte truncation. Three reasons:

1. Birthday-bound margin. A 20-byte address has 80-bit collision resistance. Marginal at chain scale; decisively safer at 128 bits.
2. Native output size. Poseidon2 naturally outputs 4 Goldilocks field elements (≈ 256 bits = 32 bytes). Using the full output avoids a truncation step.
3. Simpler key derivation. Every key derivation in the protocol produces 32 bytes; addresses match.

Wallet display

Addresses are stored and serialized as raw 32-byte values. Wallets render them in hex (0xabc...123) or in a Bech32m-style human-readable format with the pyde1... prefix for safety against typos. The choice of display format is a wallet-side concern; the protocol doesn't care.

8.10 The Stack at a Glance

   +----------------+     +----------------+
   | FALCON-512     |     | Kyber-768      |
   | sigs           |     | KEM            |
   +----------------+     +----------------+
        |                       |
        v                       v
   tx sigs               P2P session keys
   vertex sigs           threshold pubkey (mempool)
   state root attest         |
   PSS contributions          |
        |                       |
        +-> Lattice VRF (FALCON sign + Poseidon2 output)
              anchor seeding, epoch randomness, committee scoring

   +----------------+     +----------------+
   | Blake3         |     | Poseidon2      |
   | (high-volume)  |     | (Goldilocks)   |
   +----------------+     +----------------+
        |                       |
        v                       v
   JMT internals          state root commit,
   batch hashes           addresses, storage keys,
   vertex hashes          MAC, VRF output, RNG mix
   gossip dedup           poseidon2 host function

   +----------------+
   | AES-256-GCM    |
   +----------------+
   payload AEAD,
   wallet keystore

No elliptic curves anywhere. No trusted setup. Every primitive is either a NIST FIPS-standardized scheme (FALCON, ML-KEM, AES) or a widely-studied algebraic construction (Poseidon2, Shamir SSS, PSS).

8.11 Cryptographic Agility

Each primitive is accessed through a small, well-defined module (crates/crypto/src/falcon.rs, kyber.rs, poseidon2.rs, threshold.rs, vrf.rs). If a serious break is discovered in any one of them, the affected module can be replaced through a protocol upgrade without restructuring the rest of the system.

Because the address format is bound to a hash of the public key (not the key itself), a future migration to a different post-quantum signature scheme would change addresses — but the upgrade path is well-defined: a one-time key-rotation transaction signed by both old and new keys, with the address derivation domain-separated by scheme version.

That migration is not planned. NIST's FIPS standardization is the credible long-term anchor for FALCON and Kyber, and switching from them would only happen if a substantive cryptanalytic break appeared.

Summary

The next chapter walks through MEV protection end-to-end — how these primitives combine in the DAG commit pipeline to make front-running and sandwich attacks not "discouraged," but unexpressible.

Chapter 9: MEV Protection

Maximal Extractable Value is the single largest structural problem in production blockchain design. On Ethereum it transfers somewhere between $1B and $3B annually from ordinary users into the pockets of searchers, builders, and validators. On Solana the Jito stack is a tip auction by another name. Every "fix" attempted at the application layer ultimately relies on someone who can see your transaction before it lands.

Pyde does not mitigate MEV. It removes the mechanism by which it is expressible. This chapter walks through the four interlocking pieces that make front-running, sandwich attacks, JIT liquidity sniping, and ordering bribery infeasible at the protocol level — not in policy, in physics.

Post-pivot context. The earlier HotStuff design had a single proposer per slot, which was both the source of and the brake on MEV. After the 2026 pivot to Mysticeti DAG consensus, there is no single proposer to bribe or collude with — each round, every committee member produces a vertex independently, and the canonical order is derived from a deterministically-selected anchor + commit certificate. This makes the MEV story even stronger, but a few details (ordering commitment, mandatory inclusion) have moved from "proposer asserts" to "DAG structurally enforces."

Encryption is optional per-transaction. Users who don't care about front-running (e.g., simple transfers, public DAO votes) can submit plaintext for lower fees and ~0.5-2× higher TPS. Users who do care (swaps, liquidations, arbs) encrypt and pay the threshold-decryption overhead. The protocol supports both.

9.1 The MEV Problem

What MEV looks like

The simplest sandwich attack:

Without MEV protection (Ethereum, Solana):

  Mempool:
    Alice: Buy 10,000 TOKEN_X at market

  Searcher sees Alice's tx and bundles:
    Searcher: Buy 5,000 TOKEN_X    <- inserted BEFORE Alice
    Alice:    Buy 10,000 TOKEN_X   <- executes at higher price
    Searcher: Sell 5,000 TOKEN_X   <- inserted AFTER Alice, profits

  Result:
    Alice pays a worse price.
    Searcher pockets the slippage.
    Builder/validator extracts a cut via tip or block-bid.

Variants: front-running (just the "Buy before"), back-running (capture an arb the victim's swap creates), JIT liquidity (provide liquidity right before a large swap, withdraw immediately after), liquidation sniping (race other liquidators for a discount).

Why mitigation isn't enough

Every "mitigation" approach in production today shares one defect: at least one party — a builder, a relay, a private-mempool operator — can see your transaction before its position in the block is final.

As long as anyone can read your transaction before deciding where it goes, MEV extraction is possible.

Pyde's choice: make it information-theoretically impossible for anyone — the proposer, validators, observers — to know what a transaction does until after its position is irrevocably committed.

9.2 The Four Layers

Layer 1: OPTIONAL THRESHOLD-ENCRYPTED MEMPOOL
    - Tx payload encrypted with the committee's threshold pubkey (Kyber-768).
    - No single party can decrypt; 85 of 128 share-holders required.
    - Encryption is opt-in per tx — txs that don't need MEV protection
      can be submitted plaintext at lower cost.
    - Closes (for encrypted txs): front-running, sandwich, JIT,
      liquidation-sniping based on reading mempool contents.

Layer 2: COMMIT-BEFORE-REVEAL ORDERING
    - The DAG anchor at round R commits to a canonical subdag ordering
      of vertices (and therefore txs) BEFORE decryption shares for that
      wave are released.
    - The anchor is deterministic from epoch beacon + round; no single
      validator chooses it. Decryption shares are piggybacked on
      subsequent rounds' vertices and only combine once the subdag is
      committed.
    - Closes: post-decryption reordering. Because the order is fixed by
      the DAG structure before contents are readable, even a colluding
      85+ subset cannot rewrite the order after seeing contents.

Layer 3: STRUCTURAL INCLUSION (DAG)
    - Every vertex from round R includes references to >= 85 parent
      vertices from round R-1. A tx introduced into the DAG via any
      honest member's batch is committed once any committed anchor
      references the path containing it.
    - There is no "proposer" who can selectively omit. Censorship
      requires >= 44 validators (the equivocation threshold) to refuse
      to reference the tx — a structurally visible attack.
    - Closes: single-actor censorship of decryptable txs.

Layer 4: NO TIPS, NO PRIORITY FEES
    - The wire format has no field for a tip, priority fee, or out-of-band
      payment to any party.
    - The fee is exactly gas_used * base_fee.
    - Closes: bribery channels for ordering.

Each layer closes attacks the others alone could not. Removing any one re-opens a class of MEV.

9.3 Layer 1 — Threshold-Encrypted Mempool

The wire shape

Plaintext (visible from submission):
  from         32 B    (Poseidon2 of the FALCON pubkey)
  nonce        u64
  gas_limit    u64     (>= 21,000, <= 1.6B gas ceiling)
  access_list  Vec     (state slots the tx will touch)
  deadline     u64?    (wave height after which the tx is invalid)
  chain_id     u64
  signature    ~666 B  (FALCON-512 over the canonical hash of all fields)

Encrypted (Kyber ciphertext + AES-256-GCM payload):
  to           32 B
  value        u128
  calldata     Vec<u8>
  fee_payer    Sender | GasTank | Paymaster(addr)
  tx_type      Standard | Deploy | Batch | Stake* | Vote*

The committee's threshold public key is a Kyber-768 key whose secret has been Shamir-split across the 128 active validators (see Chapter 8). Any 85 share-holders combine to decrypt; any 84 learn nothing.

What's visible vs what's hidden

The access list reveals which state slots the transaction touches, but not what it does to them. An observer can see "this tx touches the DEX contract's reserve slots" but cannot tell whether it's a buy, a sell, a liquidity add, or a fee claim.

Access-list padding (optional)

If a contract's slot pattern is unusually distinctive (rare), the wallet can pad the access list with read-only decoy slots. The decoys cost a small amount of gas (one Sload per slot, ~100 gas each) but flatten the access profile. Most contracts use overlapping slots for many operations, so padding is not needed in practice.

What MEV searchers see in the mempool

Pyde encrypted mempool (what an observer scrapes):

  tx_hash | sender   | gas_limit | access_list        | encrypted
  --------+----------+-----------+--------------------+-----------
  0xabc...| Alice    | 300,000   | [(DEX, [s7, s12])] | 0x8f3a...
  0xdef...| Bob      | 100,000   | [(NFT, [s1])]      | 0x2c7b...
  0x123...| Carol    | 500,000   | [(DEX, [s7, s12])] | 0x91de...

The observer learns access patterns. They cannot construct an attack bundle because they don't know the swap direction, swap size, slippage tolerance, or token pair.

Anti-spam and per-sender rate limits

To stop a malicious user from flooding the mempool with garbage ciphertexts:

Each sender has a SenderQuota tracking timestamp deque + concurrent count; an add() past the limit returns MempoolError::RateLimited.

Ciphertext binding to FALCON pubkey

Each transaction's signature covers a hash that includes the ciphertext hash (Poseidon2 of the encrypted blob). A relay-inflation spammer who takes someone else's ciphertext and resubmits it under a different sender fails signature verification because the legitimate sender's signature binds the ciphertext to the original sender.

This is what makes per-sender rate limits work — every encrypted tx has exactly one valid sender it can attribute to.

9.4 Layer 2 — Commit-Before-Reveal Ordering (DAG)

In the post-pivot DAG architecture, ordering and decryption are structurally separated by the protocol — no proposer "commits" to an ordering, because there is no proposer. Instead:

1. Round R: every committee member produces one vertex with parent refs and batch refs. Encrypted transactions are referenced by batch hash; their plaintext is unknown to everyone (including the vertex producer, who cannot decrypt alone).

2. Round R+1 to R+3: later rounds reference round-R vertices as parents and accumulate Mysticeti's 3-stage support.

3. Anchor commit at round R+3: the deterministic anchor at round R+3 (selected by Hash(beacon, round, prev_state_root) mod 128) collects sufficient support, and a canonical subdag traversal emits a fixed ordered list of vertices, batches, and transactions.

4. Decryption shares released: committee members compute and broadcast decryption shares for the just-committed wave's encrypted transactions, piggybacked on round-R+4 vertices.

5. 85 shares combined: any honest node assembles 85 shares per ciphertext, decrypts, and executes in the canonical order.

Round R    : vertices produced (encrypted txs referenced by batch hash;
                                 nobody can read contents yet)
Round R+1  : referencing vertices (still encrypted)
Round R+2  : 2-stage support accumulates
Round R+3  : anchor commit fires -> canonical order LOCKED
Round R+4  : decryption shares released -> contents revealed

The critical property: between the moment the anchor commits and the moment shares combine, the ordering is fixed by the DAG structure. There is no actor with both the ability to read contents AND the ability to alter ordering — those capabilities exist in non-overlapping rounds.

Why this is stronger than commit-then-broadcast

Under a single-proposer commit-then-broadcast scheme, you have to trust that the proposer can't both compute shares early AND alter the commitment. Under the DAG, you don't trust anyone: the order is a deterministic function of vertices that were already in the DAG before contents could be read. No commitment signature is needed, because the commitment is the DAG itself.

Implementation

The canonical subdag traversal and ordering emission live in crates/consensus/src/subdag.rs. The deferred-decryption pipeline lives in crates/crypto/src/threshold.rs and crates/consensus/src/wave.rs.

9.5 Layer 3 — Structural Inclusion (DAG)

Under HotStuff, a single proposer could selectively omit txs, motivating the local-view mandatory-inclusion check. Under Mysticeti DAG, there is no single proposer — every committee member produces a vertex each round, each vertex references batches from any worker the producer gossiped with, and every committed wave traverses the entire subdag.

For a transaction to be censored, a coalition of ≥ 44 validators (equivocation threshold = n - 2f = 128 - 84 = 44) must all refuse to reference the batch containing it. Below that threshold, ≥ 85 honest vertices reference it and it lands in some committed subdag.

A tx submitted to ANY honest worker is gossiped to all 128 validators.
Each validator's primary produces a vertex referencing batches from
workers it received from. As long as 85+ committee members eventually
reference the batch (directly or transitively via the parent links),
the tx is committed in the next wave.

Censoring requires 44+ validators to coordinate omission — a structurally
visible attack with multiple independent forks of evidence.

Mempool-level mandatory inclusion (residual)

For tighter guarantees on a per-vertex basis, a validator can still skip or down-weight a vertex that omits txs visible in its local mempool view for >= grace_slots. This is defensive, not necessary for safety — the DAG already guarantees inclusion at the wave level. The check catches single-validator censorship attempts before they require coalition.

The audit logic lives in crates/mempool/src/inclusion.rs.

Cryptographic mempool commitments (post-mainnet)

Cryptographically aggregated mempool commitments (every committee member periodically gossips a hash-set of txs they've seen, then the DAG-level inclusion check is against the union) make censorship coalition-bounded even at the round level. This is tracked for post-mainnet hardening; not needed for safety at launch.

9.6 Layer 4 — No Tips, No Priority Fees

Pyde's gas model has no field anywhere in the wire format for a "priority fee" or "tip." Every transaction pays exactly:

fee = gas_used * base_fee

Where base_fee is algorithmically determined by EIP-1559 (target 400M gas, 4× elastic ceiling, ±12.5% per block adjustment). The only sender-controlled fee parameter is gas_limit, which is a cap (refunded if execution uses less).

Why this matters

Even if encryption + commitment + mandatory inclusion fully closed the direct ordering attacks, a tip would re-open the bribery channel. A searcher could pay a committee validator out-of-protocol to delay a tx, to position their own tx first, or to censor a competitor's tx. Tips create the economic incentive for all of those attacks; absent tips, no validator gains anything from any of them.

How ordering happens

Under the DAG, ordering is a deterministic function of the committed subdag — not a proposer choice. The subdag traversal at each commit emits transactions in a canonical order derived from vertex round, member id, and batch sequence. No actor — proposer, validator, observer — chooses positions.

For sequential nonce dependencies (a sender submitting txs n, n+1, n+2 in quick succession), the protocol uses the 16-slot bitmap nonce window (see Chapter 11) — the txs can be included in any order within the window; gaps are tolerated.

9.7 The End-to-End Walkthrough

A swap from Alice's wallet through the full pipeline:

Step 1 — WALLET (Alice)
  - Build tx: to=DEX, calldata=swap(USDC, PYDE, 1000, min_out=950)
  - Call pyde_estimateAccess(tx) -> returns gas + access_list
  - Encrypt (to, value, calldata, fee_payer, tx_type) with the committee's
    Kyber threshold pubkey: ciphertext + AES-256-GCM payload
  - Sign the canonical hash with Alice's FALCON-512 secret key
  - Submit via pyde_sendRawEncryptedTransaction

  Visible to anyone who scrapes the mempool:
    Alice sent a tx. It touches DEX slots [reserve_0, reserve_1, alice_bal].
    300,000 gas. 0xpyde1abc... signature.
  Hidden:
    Direction (buy or sell), size, target tokens, slippage tolerance.

Step 2 — INGRESS VALIDATION (any RPC node)
  - chain_id, FALCON sig, nonce window, gas-tank balance, gas ceiling,
    deadline, access-list dedup, tx size, calldata size -> all pass
  - Forward to a nearby worker; worker batches and gossips

Step 3 — DAG VERTEX PRODUCTION (round R)
  - Each committee primary produces ONE vertex this round, with:
      batch_refs: hashes of batches containing Alice's tx (and others)
      parent_vertex_refs: ≥ 85 prior-round vertex hashes
      state_root_sigs: attestations on recent commits
      decryption_shares: PARTIAL shares for previously-committed waves
      FALCON sig
  - Nobody can read Alice's tx contents yet — full ciphertext payload.

Step 4 — DAG ANCHOR COMMIT (round R+3, ~500 ms after submission)
  - Deterministic anchor at round R+3:
      anchor_member = Hash(beacon, R+3, prev_state_root) mod 128
  - Anchor collects Mysticeti 3-stage support -> commit fires
  - Canonical subdag traversal emits ordered tx list — including Alice's

Step 5 — THRESHOLD DECRYPTION (rounds R+4 to R+5)
  - Committee members compute decryption shares for txs in the just-
    committed wave, blinded with H(ct_hash || member_idx || elem_idx),
    and piggyback shares on their next vertices.
  - Any honest node collects ≥ 85 shares per ciphertext, interpolates,
    decrypts with AES-256-GCM. ~10-15 ms once 85th share arrives.

Step 6 — EXECUTION (Block-STM)
  - Prefetch the union of declared access lists in one batched
    state_cf.multi_get (PIP-3) into the dashmap (PIP-4). Lists are
    hints; they never partition the wave or affect correctness.
  - Run every decrypted tx in parallel via the Block-STM scheduler:
    optimistic execute through an MVCC layer + validate against
    canonical tx_index order + cascade-invalidate + re-incarnate on
    conflict + fixpoint. Full algorithm in
    companion/BLOCK_STM_EXECUTION.md.
  - Final state derived from the fixpoint: highest-tx_index's last
    write per slot. Execute against pre_state_root → new post_state_root.
  - Distribute fees: 70% burn, 20% to current epoch's reward pool, 10% treasury.
    (Layer 4: no tip is paid because no tip field exists in the wire format.)

Step 7 — STATE ROOT ATTESTATION
  - Each committee member FALCON-signs (wave_id, blake3_state_root, poseidon2_state_root).
  - Sigs piggyback on subsequent vertices.
  - ≥ 85 sigs -> finality. Typically ~500 ms median end-to-end.

Step 8 — RECEIPT
  - Receipt available via pyde_getTransactionReceipt:
      success, gas_used, logs, fee_paid, fee_payer, wave_id

At no point in this flow does any party know transaction contents AND have the ability to influence ordering. That conjunction is what MEV requires; the protocol structurally denies it.

9.8 What Each Attack Vector Requires (And Why It Fails)

Front-running Alice's swap requires:
  1. Know Alice's intent              <- blocked by encryption (Layer 1)
  2. Insert before Alice in this block <- blocked by ordering commitment (Layer 2)
  3. Get into the block at all         <- blocked by mandatory inclusion + sealed block
  4. Have economic motive              <- blocked by no-tip rule (Layer 4)

Sandwich attack requires:
  1. Know the swap direction          <- (1) above
  2. Insert before AND after          <- (2) and the sealed-block invariant
  3. Bribe for specific positioning   <- (4) above

Censoring a competitor's tx requires:
  - Selectively omitting it           <- blocked by mandatory inclusion (Layer 3)

Bribing a committee validator for ordering requires:
  - A protocol mechanism to pay them   <- doesn't exist (Layer 4)

Each attack requires a conjunction of capabilities. Pyde structurally denies at least one element of every conjunction.

9.9 Edge Cases

Insufficient decryption shares

If fewer than 85 valid shares arrive within ~2 rounds (~300 ms) of a commit, decryption fails for that wave. The DAG continues — subsequent waves are unaffected — but the affected txs remain encrypted and stuck in mempool until either enough shares arrive late OR the user resubmits. Non-responsive committee members are tracked toward the liveness slashing threshold (see Chapter 6).

Liveness assumption: as long as 85+ of 128 validators are honest and online, decryption succeeds. This is the same f < n/3 assumption that secures consensus.

Invalid decryption shares

A malicious validator could broadcast a fabricated share. The combiner verifies each share's blinding and the recovery's MAC; an invalid share doesn't poison the recovery (Lagrange interpolation over a sufficient honest subset still works). Detected bad shares are tracked toward slashing for "decryption withholding" (2% per offense).

Garbage ciphertexts

A user could submit a ciphertext that decodes but contains junk. After decryption, the AES-GCM authentication tag fails, the tx is invalid, and gas is consumed (sender pays). The mempool's per-sender rate limit (10 tx/s, 100 concurrent) caps the throughput an attacker can sustain.

Epoch boundary transitions

PSS resharing happens at every epoch boundary. The threshold public key is unchanged across boundaries — wallets continue encrypting against the same key. The 5-round aggregation delay (RESHARE_AGGREGATION_DELAY_ROUNDS) ensures every new committee member agrees on the same canonical contribution set before the new shares become live.

Committee-member compromise

If a coalition of 85+ validators colluded, they could decrypt early. Even then, the ordering commitment forces them to commit to ordering before decryption — they can't exploit the early read for sandwiching. They could in principle censor (omit txs from blocks they propose), but that fails the mandatory inclusion check on every honest validator's view. The cost of 85+ collusion is 850,000 PYDE at risk plus the slashing exposure of every participant; the gain is sharply bounded by the structural protections.

9.10 Performance Cost

The MEV protection adds latency primarily in the deferred-decryption path:

Encrypted txs reach finality + execution ~600-800 ms median (vs ~500 ms for plaintext). Plaintext-only chains pay zero of this overhead.

Throughput impact. Encrypted txs are ~3-5× slower end-to-end than plaintext because the decryption pipeline serializes (shares must be gathered before the wave can execute). Both the plaintext and encrypted v1 throughput targets are to be established by the multi-region performance harness; the encrypted regime lands well below the plaintext one because of this serialization.

The bandwidth cost is per-share data piggybacked on consensus vertices (~250 KB/validator/wave), well within the 500 Mbps committee NIC budget.

9.11 What's Visible vs Hidden — Recap

+-----------------------------+------+------+
| Field                       | Plain| Enc. |
+-----------------------------+------+------+
| sender                      |  Y   |      |
| nonce                       |  Y   |      |
| gas_limit                   |  Y   |      |
| access_list                 |  Y   |      |
| deadline                    |  Y   |      |
| chain_id                    |  Y   |      |
| signature                   |  Y   |      |
| to                          |      |  Y   |
| value                       |      |  Y   |
| calldata                    |      |  Y   |
| fee_payer                   |      |  Y   |
| tx_type                     |      |  Y   |
+-----------------------------+------+------+

You see who sends, how much gas they're willing to pay, which slots they touch. You don't see what they're doing.

9.12 What This Doesn't Solve

Honest about the limits:

• Information leakage from access lists. A sufficiently distinctive access pattern can leak operation type. The mitigation is at the contract-design level (DEXes already share the same slots for buys, sells, and liquidity ops in well-designed code) and the wallet level (optional access-list padding).

• Out-of-protocol coordination. If a user signs an off-chain message saying "I will swap soon," anyone with that information can act on it. The protocol can't prevent users from leaking their own intent.

• Long-run statistical profiling. A persistent attacker who watches Alice's access patterns over many transactions could infer her behavior. This is a privacy concern, not an MEV one — Alice's individual transactions are still safe from front-running.

• Searcher-on-searcher games at the DEX/contract level. If a contract has a built-in tip mechanism (priority gas auctions inside the contract itself), Pyde's protocol-level MEV protection doesn't reach into it.

For mainnet, the in-scope guarantees are: no front-running by any committee member, no sandwich attacks composable through the mempool, no censorship of decryptable txs, and no bribery channel for ordering.

Summary

Pyde's MEV protection is not a feature bolted on to an otherwise standard chain. It is a structural property of the protocol arising from the interaction of four mechanisms:

Each layer addresses an attack the others alone cannot stop. Together, MEV extraction is not "discouraged" — it is unexpressible in the protocol.

v1 scope. Local-view mandatory inclusion is implemented and safe (a defensive backstop on top of structural DAG inclusion). Cryptographically aggregated mempool commitments + on-chain censorship slashing are tracked as post-mainnet hardening.

The next chapter covers the gas and fee model that the no-tip rule sits on top of.

Chapter 16: Security

Security is the substrate on which every other property of Pyde rests. This chapter catalogs the realistic attack surface at mainnet, the concrete defense for each class, the invariants that make the BFT safety argument work, and the operational hygiene that keeps a post-launch network healthy.

The scope of this chapter is the shipped mainnet. Where a defense is on the post-mainnet hardening list rather than live, the chapter says so.

Note. This chapter is the narrative security reference. The canonical catalog — ~50 threats by ID, organized by layer, with mitigation cross-references and acknowledged residual risks — lives in companion/THREAT_MODEL.md. External auditors should start with the threat model and use this chapter for context; readers building intuition should start here and dip into the threat model when they want the full catalog.

16.1 Attack Surface

Each of these is covered in more detail below.

16.2 BFT Safety and Liveness

The guarantee

Safety (Mysticeti DAG): no two conflicting subdag commits or state roots ever achieve finality at the same wave, provided fewer than f = ⌊(n-1)/3⌋ = 42 committee members are Byzantine. At n = 128, this is f ≤ 42, threshold 2f + 1 = 85.

Liveness: the DAG advances and produces commits as long as 85 of 128 committee members are honest and online.

Why it holds

Each vertex carries ≥ 85 parent vertex references. An anchor commit at round R+3 requires Mysticeti 3-stage support — at least 85 round-(R+1) vertices that reference the anchor as a parent. Two conflicting commits of contradictory subdags at the same wave would each need 85+ signing vertices; the total exceeds n = 128, so at least 85 + 85 − 128 = 42 honest members would have had to equivocate (sign in both forks). Under the Byzantine bound, at most 42 are adversarial. Equivocation is slashable evidence at 100% of stake, so the cost is total. ∎

State-root divergence (two contradictory Blake3 state roots both signed by 85 members) is detected automatically and triggers a hard halt (Chapter 7 / companion/CHAIN_HALT.md).

What if more than 1/3 are Byzantine

The protocol cannot promise safety above the 1/3 threshold; that's a mathematical limit of BFT consensus. Defenses:

1. Raise the cost. 10M PYDE per committee validator × 43 = 430M PYDE at stake minimum for a safety violation, all slashable at 100%. Slashing evidence can be submitted with a 10% finder's fee, creating economic incentive for whistleblowers.
2. Weak-subjectivity checkpoints. If an adversary somehow accumulated ≥ 1/3 and started forking, nodes that sync from a recent checkpoint reject the fork outright (§16.3).
3. Hard halt on detected divergence. State root divergence (two signed contradictory roots) triggers an automatic chain halt; the network stops producing commits until the divergence is resolved (Chapter 7).
4. Social consensus. As with every BFT chain, the final backstop is human coordination: if the chain demonstrably goes off the rails, the honest majority forks away and the broken chain loses social legitimacy.

16.3 Long-Range Attacks and Weak Subjectivity

The attack

An attacker buys (or otherwise acquires) a majority of validator keys that were active at some point in the past. They create a long alternative chain starting from that point — completely different history, potentially different token holders. If a fresh node syncs without any reference point, it cannot distinguish the real chain from the alternative.

The defense: weak-subjectivity checkpoints

When a commit collects ≥ 85 FALCON state-root signatures, the validator writes a FinalityCheckpoint to the consensus store:

#![allow(unused)]
fn main() {
struct FinalityCheckpoint {
    wave_id:    u64,
    blake3_state_root:    Hash,
    poseidon2_state_root: Hash,
}
}

(Stored under FINALITY_CHECKPOINT_KEY in crates/node/src/consensus_store.rs.)

A node that's currently synced will refuse to reorg past the latest checkpoint. FinalityTracker::can_reorg(wave_id) returns false for any wave at or before the checkpoint's wave_id.

For a cold-syncing node, the protocol doesn't pick a checkpoint on its own — the node's operator provides a trusted recent block hash from a source they trust (the Foundation website, a public explorer, a known good peer). This is called "weak subjectivity" because new nodes must trust something outside pure protocol to anchor their sync.

The human-trust assumption is narrow: all you need is any one honest, recent observation of the chain. Once anchored, the node enforces its own local checkpoint going forward.

Bootstrap peers

The genesis block hash is built into the client binary — no external trust needed for it. The MAINNET_BOOTSTRAP and TESTNET_BOOTSTRAP lists (crates/net/src/discovery.rs) provide starting peers, which provide the current chain state. A new node combines:

1. Genesis block hash (hard-coded).
2. Recent weak-subjectivity checkpoint (operator-provided).
3. Current peer set (from bootstrap_peers).

—to pin down which chain is real without requiring a full replay from genesis.

16.4 Sybil Resistance

The attack

An adversary creates many validator identities to dominate consensus — bypassing the f < n/3 bound by simply being the majority of the active committee.

The defense: layered, not stake-driven

Pyde's Sybil resistance is intentionally not anchored to stake size. The chain's structural MEV resistance removes the primary attack incentive, which lets the stake floor sit at a modest 10,000 PYDE (single tier) and shifts the security burden onto a stack of qualitative defenses. Five layers:

1. Threshold encryption removes the attack incentive. The dominant reason adversaries attack BFT consensus on production chains is MEV extraction — front-running, sandwich attacks, transaction reordering. On Pyde, this attack value is structurally near-zero. Even a Byzantine 1/3 cannot:

• Decrypt encrypted-mempool ciphertexts (requires 85 of 128 shares — see Chapter 8 §8.5);
• Reorder transactions after the DAG anchor commits the canonical order (Chapter 9 §9.4);
• Profitably front-run any opt-in-encrypted transaction.

This collapses the attack-profit equation that drives Ethereum-scale stake floors (32 ETH → ~$80–120K). Pyde does not need to price stake against MEV profits because there are no MEV profits to be made.

2. Operator-identity cap (max 3 validators per operator). A Byzantine fork needs f + 1 = 43 of 128 committee slots. Under a 3-per-operator cap, that translates to ≥ 15 distinct KYC'd operator identities — much harder to manufacture than capital. Identity binding is enforced via the stake-account-to-operator mapping; high-stake operators face additional KYC verification at registration.

3. Slashing at 100% on safety violations. Equivocation and bad state-root signatures incur full-stake slashing plus permanent ban (see Chapter 14 §14.5 / companion/SLASHING.md). The 10% finder's fee creates an active whistleblower incentive — every honest node has a financial reason to surface attacker evidence within the 21-day freshness window.

4. Hard-halt detection on state-root divergence. Two contradictory signed state roots trigger an automatic chain halt (Chapter 7 §Part 2). Attackers cannot quietly corrupt state — safety violations are loud, visible, and immediately interrupt block production. The 1-epoch bounded rollback policy contains damage to a narrow window.

5. Minimum-stake credibility deposit. The 10K PYDE floor is a credible-commitment deposit, not the load-bearing economic defense. It ensures every validator has some skin in the game and gives the slashing mechanism something to slash. Combined with the operator cap, the lower bound on committed capital for a 43-Byzantine attack is ≥ 15 operators × 3 validators × 10K PYDE = 450K PYDE locked plus the legal and reputational exposure of 15 KYC'd entities. Modest in dollar terms; meaningful in coordination terms.

The honest framing

The single-number "you'd lose $N million in stake to attack" argument that other chains lead with does not apply here. Pyde's claim is different and stronger: the protocol is designed such that there is no profitable attack to fund. Stake economics back this up at the margin. Operator identity binding does the heavy lifting on Sybil specifically. The threshold-encryption property does the work of removing the attack value entirely.

This shifts the trust assumption from "stake is large enough to deter attack" to "operator-identity binding + slashing + structural MEV-resistance jointly make attack unprofitable and detectable." The second is a substantively different argument and worth being explicit about.

Genesis Sybil resistance

The initial 128-validator set is Foundation-curated at genesis (Phase 10 of the launch plan, recruited + validated across 3+ regions). This is a "trusted launch" assumption — not that the Foundation is trusted forever, but that the initial set is diverse and honest. After genesis, committee rotation and permissionless stake-based registration take over.

16.5 Eclipse Attacks

The attack

An adversary surrounds a single target validator with only-adversary peers. The target sees whatever the adversary wants them to see: fake proposals, faked votes, a fake chain. If the adversary can eclipse enough validators, they can force consensus on a fake state (though safety still holds under the 1/3 rule, liveness can be hurt).

The defense

1. Peer diversity. The peer manager (crates/net/src/peer.rs) caps connections per /24 subnet. An adversary would need to control IP addresses across many subnets, not just spin up lots of VMs on one provider.
2. Layered discovery (no DHT). Pyde explicitly chose not to use a Kademlia DHT (Chapter 12). Discovery is layered: hardcoded seeds, DNS, on-chain validator registry, PEX, local cache. This eliminates the DHT-poisoning eclipse vector — an attacker can't pollute a routing table that doesn't exist.
3. FALCON peer authentication (§12.4). After the libp2p connection, peers run a FALCON-signed attestation that binds PeerId to a post-quantum identity. An adversary can't clone a validator's PeerId without their FALCON secret key.
4. Sentry node pattern (Chapter 12). Committee validators are reachable only through trusted sentry proxies — their real IPs are not in the public peer set. Eclipsing a committee validator requires compromising the sentry layer, not just the public network.
5. Validator-channel filtering. The vertex channel only accepts messages from peers whose attested FALCON pubkey is in the current committee. A non-validator eclipse peer can inject garbage on gossip topics but cannot fake vertex signatures.

What isn't defended (yet)

The current peer-scoring system is deliberately simple (reputation = messages_received - 10 * invalid_messages). A more sophisticated gossipsub score with per-topic weights, decay parameters, and gray-listing is on the post-mainnet hardening list. The current model is enough for the DDoS-shaped threats at mainnet scale; more sophisticated Eclipse attacks against one specific validator would show up as anomalous peer behavior that operators could see in their metrics.

16.6 DDoS Resistance

Connection-level

#![allow(unused)]
fn main() {
DEFAULT_RATE_LIMIT_PER_IP = 5 conns/sec
DEFAULT_MAX_PEERS         = 50
DEFAULT_MAX_INBOUND       = 30
DEFAULT_MAX_OUTBOUND      = 20
}

Per-IP rate limiter throttles new connections; per-subnet limit prevents one network from hogging peer slots. An attacker flooding an RPC endpoint bumps against conn_rate_limit_per_ip and saturates at 5 new connections per second per source address.

Evidence-ingest rate limiting (task 014d)

A non-validator peer can submit evidence messages to validators that then verify them. Naive validators would FALCON-verify every evidence message at ~60 µs each — enough for a flood of invalid evidence to saturate CPU.

The fix: token-bucket rate limit on evidence messages, applied per-peer. Repeat offenders are dropped after the first failed verification instead of verifying indefinitely. Lives in crates/net/src/ddos.rs.

Per-channel message size limits

Each gossipsub channel has its own max message size:

Oversized messages are rejected and the sender takes a reputation hit.

RPC ingress validation (task P7a-3)

Invalid transactions never enter the mempool. The ingress validator (crates/node/src/rpc.rs::ingress_validate) checks chain_id, FALCON sig, nonce window, balance, gas bounds, deadline, access-list duplicates, tx size, calldata size — all before returning Ok or gossipping. Pollution is isolated to the single ingress node.

Mempool per-sender caps

DEFAULT_MAX_TX_PER_WINDOW_PER_SENDER = 10  (per 1-sec window)
DEFAULT_MAX_CONCURRENT_PER_SENDER    = 100 (concurrent txs in pool)

A single spammer cannot flood the mempool. If they try, their per-sender quota blocks further submissions until the window slides.

16.7 Front-Running and MEV

Covered in detail in Chapter 9. The short version:

• Optional threshold-encrypted mempool. Tx payload hidden from everyone until 85-of-128 Kyber shares combine. Users opt in per tx.
• Commit-before-reveal DAG ordering. The DAG anchor commit at round R+3 fixes the canonical order; decryption shares are released only at R+4. No actor has both "can read contents" and "can alter order" at any single round.
• Structural inclusion. No single proposer to censor; censoring a tx requires ≥ 44 colluding committee members.
• No tips. The wire format has no priority-fee field.

Each layer closes attacks the others cannot. Together, MEV is not discouraged — it is structurally unexpressible.

16.8 State Manipulation

The attack

A malicious vertex producer submits a wave-anchor candidate whose claimed post-state root doesn't actually match the result of executing the wave's transactions. Honest validators would incorrectly accept a bogus state.

The defense

Every honest validator executes each committed wave themselves and FALCON-signs (wave_id, blake3_state_root, poseidon2_state_root). A malicious vertex producer that claims a wrong root gets 0 honest state-root sigs; the network cannot reach the 85-sig finality bar.

Two conflicting state claims can't both reach finality (same BFT argument: > 1/3 would have to equivocate). State root divergence is hard-halt detectable (Chapter 7) — the network stops automatically once two contradictory signed roots appear.

JMT Merkle proofs

For light clients that do not execute the wave, the JMT batched proof + the signed blake3_state_root + the committee's FALCON signatures are the authentication path. A light client verifies:

1. HardFinalityCert for the wave is valid (≥ 85 FALCON sigs).
2. The JMT proof from blake3_state_root to the specific leaf is valid.
3. The leaf value is what the light client was querying.

The chain of authentication is end-to-end cryptographic. ZK light clients (post-mainnet) can use the parallel poseidon2_state_root for SNARK-based verification at much lower cost.

16.9 Quantum Attacks

Every primitive in the protocol is post-quantum:

• FALCON-512 signatures — NTRU lattice, not factoring.
• Kyber-768 / ML-KEM key exchange — lattice, not ECDH.
• Poseidon2 hashing — algebraic, not affected by quantum.
• Lattice VRF — inherits FALCON security.
• AES-256-GCM — symmetric, 128-bit post-quantum security under Grover's algorithm.

The weakest link is Poseidon2's 64-bit post-quantum collision resistance (Grover halves the exponent). 64-bit collision resistance requires 2^64 quantum hash evaluations, which is far beyond any realistic near- or mid-term quantum capability. If cryptanalytic advances tighten this, a hash migration is a standard-shape protocol upgrade.

Pyde has no elliptic-curve crypto anywhere in the protocol. No secp256k1, no ed25519, no BLS12-381. The libp2p transport layer uses ed25519 for PeerId routing only; application-level authentication uses FALCON.

16.10 Smart Contract Safety

The default-safe properties Otigen the language provided are preserved in the WASM era. Mechanism changed; guarantees did not. See Chapter 5 §5.6 for the full attribute surface.

• No reentrancy by default. Every function is guarded by the WASM execution layer; opt out with the reentrant attribute (language-native: #[pyde::reentrant] / @pyde.reentrant / //pyde:reentrant / PYDE_REENTRANT).
• Checked arithmetic. Encouraged by per-language SDK helper patterns; wrapping ops require explicit opt-in (e.g., Rust's wrapping_add is explicitly named).
• Typed storage. Declared in otigen.toml [state] schema; the build tool emits type-safe accessors and the runtime enforces slot-hash uniqueness.
• No tx.origin. The host function ABI exposes only caller() (direct caller). The Solidity-style phishing vector is absent.
• Access-list enforcement. Slot accesses against slots not declared in the contract's state schema fail at the host-function layer.

These defaults eliminate the most common smart-contract exploit classes at the toolchain + runtime level, not as library choices developers might forget.

The toolchain audit surface

The otigen developer toolchain — specifically its state binding generators and ABI extractor — is part of the audit surface. A codegen bug in a binding generator could emit accessor code that violates declared semantics. Mitigations:

• Unit tests per binding-generator output pattern. Each language target (Rust, AssemblyScript, Go, C/C++) has its own generator with its own test suite covering every accessor shape.
• Property tests for slot-hash determinism across languages — given the same otigen.toml, all four generators must produce identical runtime slot_hash values for identical inputs.
• External audit of the otigen toolchain before mainnet.
• Wasmtime as a trust-minimized dependency. The execution runtime itself is wasmtime, which inherits years of production fuzzing and Bytecode Alliance audit attention — we do not audit a VM we built ourselves.

16.11 WASM Execution Layer Safety

Pyde's execution layer is wasmtime (with Cranelift AOT). The trap surface is wasmtime's, augmented by host-function-specific traps Pyde injects through the ABI.

WASM-native traps

wasmtime traps when the executing module violates its sandbox or its fuel budget. The canonical trap conditions:

OutOfFuel              IntegerOverflow         IntegerDivisionByZero
MemoryOutOfBounds      StackOverflow           UndefinedElement
IndirectCallToNull     BadSignature            UnreachableCodeReached
TableOutOfBounds       Interrupt               (host-function traps)

Each trap is a clean revert: state writes roll back, gas is consumed up to the trap point (computed from fuel actually consumed), the transaction fails. There is no undefined behavior path. wasmtime's sandbox guarantees structural safety: no buffer overflows, no control-flow hijacks, no type confusion.

Pyde-specific traps via host functions

The host functions add another trap layer for Pyde-specific safety properties:

Determinism enforcement

wasmtime is configured to reject any module that uses non-deterministic features. The config enforces (at module instantiation and at deploy validation):

• cranelift_nan_canonicalization(true) — floating-point NaN bit patterns canonicalized identically across all validators
• wasm_threads(false) — no threading (non-deterministic by definition)
• wasm_simd(false), wasm_relaxed_simd(false) — SIMD disabled until a deterministic-only subset is vetted
• wasm_reference_types(false), wasm_gc(false), wasm_function_references(false) — complexity surface gated until needed
• wasm_multi_memory(false), wasm_memory64(false) — explicit memory layout
• No WASI imports

A deploy-time validator (crates/wasm-exec/src/validate.rs) re-checks the module's import section against the allowlist and rejects anything that would slip past wasmtime's instantiation check.

Trust-minimization of the runtime

We do not audit wasmtime itself — that work is done continuously by the Bytecode Alliance with years of production fuzzing under adversarial workloads. We pin a tagged wasmtime version per chain release, document the version in the protocol upgrade record, and require validators to upgrade in coordinated forks when we move it. This is a meaningfully smaller audit surface than maintaining a custom VM ourselves would have been (see The Pivot preface for the full reasoning).

16.12 Consensus-State Persistence

The risk. If a validator casts a vote, crashes before the vote is durable, and restarts with a different view, it can double-vote on restart — violating BFT safety.

The defense.

1. WriteOptions::set_sync(true) on every write to the consensus store (task 014a). A vote is not considered "cast" until fsync returns.
2. panic! + panic = "abort" on any persist failure (task 014b). The process terminates immediately. Continuing after a failed disk write is a BFT-unsafe operation; halting is the correct fail-safe.
3. Restart recovery reloads seen_proposals, seen_votes, pending_evidence from the consensus store (task 003, 014c).

Microbenchmark (task 014f) confirmed the per-vertex-sig fsync cost is ~25.5 µs on Apple Silicon NVMe — ~39K writes/sec headroom against the ~150 ms round cadence (≥ 1000× margin).

Gradeful drain-and-shutdown on persist failure is a post-mainnet operational polish, not a launch blocker.

16.13 Replay Protection

Cross-chain replay

Every transaction includes chain_id in the canonical hash. A transaction signed for mainnet cannot be replayed on a testnet; a testnet tx cannot be submitted to mainnet. Chain IDs:

The chain_id is always enforced; the dev_skip_signature flag only disables signature verification for chain_id 31337 (devnet), and only if the config explicitly allows it. On any chain_id other than 31337, signatures are always required.

Same-chain replay

Each transaction has a nonce that must fit the sender's 16-slot bitmap window (Chapter 11). Once used, the bitmap bit stays set until the window slides past it. A replayed tx hits the bitmap and is rejected.

Multisig replay

Treasury multisig spends include the current MULTISIG_NONCE in the signing bytes. After a spend, the nonce bumps, so the same signed bytes cannot be replayed.

Emergency replay

EmergencyPause and EmergencyResume include the current MULTISIG_NONCE in their signing context. A paused chain that auto- expires cannot be re-paused by replaying the same signed payload.

16.14 Treasury Security

See Chapter 15 for the governance model. The treasury's on-chain protections:

1. Multisig-only spend. No other transaction type drains the treasury account.
2. Audit trail. data_digest = hash(pip_file_contents) ties every spend to a published PIP.
3. Rotation. RotateMultisig can replace the signer set; no single signer is entrenched.
4. Writeback-clobber protection. spend.target != tx.from, tx.to == 0x00. Prevents the post-execution pipeline from accidentally overwriting the spend.
5. Nonce-bound signatures. Each spend bumps MULTISIG_NONCE; replays fail.

The multisig signer set is a trust assumption. The mitigation is scope: the signers can spend the treasury and rotate themselves; they cannot change consensus rules, supply, or fee distribution.

16.15 Operational Security

Aspects that are not cryptographic but matter at mainnet operation:

• Key management. Validator FALCON secret keys are kept in hardware-backed storage where possible. Key rotation transactions (key_nonce bump) exist for compromised-key recovery.
• Sentry nodes. Validators typically expose a sentry node for P2P traffic and keep the validator process unreachable directly. This is a deployment concern, not protocol-enforced.
• Monitoring. Every node exposes Prometheus metrics; operators run alerting on consensus participation rate, block inclusion rate, and peer churn.
• Bug bounty. A permanent bug bounty program is part of the community allocation (Chapter 14). The Phase 7 testnet tier has its own bounty; the mainnet tier will be funded at launch.
• Incident response. Phase 10 of the mainnet plan specifies on-call rotation and incident response SOPs. The emergency-pause mechanism gives operational response a real lever during a live exploit.

16.16 Hardening Work In-Flight

Pre-mainnet hardening work tracked in the launch plan (chapter 19):

The honest shape at mainnet: a small, audited, heavily-tested core with a well-scoped set of known future hardening items.

16.17 External Audits

The launch plan schedules five independent external audits before mainnet:

Note: wasmtime itself is not separately audited — it is a vetted production dependency from the Bytecode Alliance. The Pyde audit focuses on the integration surface (host functions, fuel mapping, validation gate, module cache) and on the toolchain that emits the WASM modules.

Critical + high findings are remediated before mainnet; audit remediations themselves are re-audited. Penetration testing (P2P flooding, RPC DoS, eclipse simulations) runs in parallel.

Summary

The next chapter covers developer tools: the otigen developer toolchain, the pyde node binary, the Rust and TypeScript SDKs, the WASM crypto bindings, and the JSON-RPC surface.

Chapter 10: Gas and Fee Model

Pyde meters every operation in gas. The economic model on top of gas is EIP-1559 with 4× elastic blocks, deterministic 70/20/10 fee distribution, and no priority fees. There is no tip field, no builder/proposer separation, no bidding war for inclusion order.

This chapter covers the full model: gas costs per opcode, the EIP-1559 base fee math, elastic block sizing, the 70/20/10 split, sponsored transactions through gas tanks, and the calldata/tx size limits.

10.1 Gas Accounting

Pyde uses wasmtime's fuel mechanism for gas metering. At node startup, the engine establishes a deterministic mapping from gas units (the chain-level metering unit) to wasmtime fuel units. Every WebAssembly instruction consumes a configurable amount of fuel; host function calls also consume fuel manually, charged by the host based on operation cost (sstore is heavier than add, for example).

When fuel reaches zero, wasmtime traps the execution with an out-of-fuel error. The transaction reverts; the sender pays gas for all the work done up to the trap point. There is no refund.

#![allow(unused)]
fn main() {
struct ExecContext {
    gas_limit: u64,    // set by the transaction
    gas_used:  u64,    // computed from fuel consumed during execution
}
}

Charging model: validate up front, deduct after execution

Step 1 — Ingress validation (at RPC):
  Check sender.balance ≥ gas_limit × base_fee + value_attached.
  If insufficient: REJECT before mempool admission.

Step 2 — Mempool admission + propagation:
  No balance changes. Tx flows through workers, batches, vertices.

Step 3 — Execution (at wave commit):
  Re-check balance (sender may have spent in prior txs of this wave).
  Execute via wasmtime, tracking consumed_fuel.
  On completion (success OR trap):
    gas_used   = fuel_to_gas(consumed_fuel)
    charge     = gas_used × base_fee
    sender.balance -= charge + (value_attached if execution succeeded)
    
Step 4 — Fee distribution (always 70/20/10):
    burn        += charge × 0.70
    reward_pool += charge × 0.20
    treasury    += charge × 0.10

No gas refunds in v1

Pyde v1 ships with zero gas refunds. gas_used is what the user pays, always. The sdelete host function is a regular metered operation; it has a lower gas cost than sstore (clearing a slot is less work than writing), but there is no refund applied on top.

The reasoning:

1. Ethereum had to roll back gas refunds via EIP-3529 after gas-token attacks (CHI, GST2) abused refunds to manipulate gas markets at scale. The refund mechanism turned out to be an attack surface, not a feature.

2. Pyde handles state cleanup at the engine layer via PIP-4's write-back cache + state pruning policy, not via user incentives. Storage doesn't accumulate unbounded regardless of whether users explicitly delete. The financial incentive is unnecessary.

3. Simpler accounting. No refund-capping rules, no two-step charge-then-refund logic, no edge cases. Receipts carry one number — gas_used — and that's the charge.

Why fuel, not opcode counting

Fuel is built into wasmtime's Cranelift backend. Every basic block is instrumented to decrement a fuel counter; when the counter goes negative, execution traps. The instrumentation is efficient enough not to dominate execution time.

Implementing custom opcode-counting on top of wasmtime would be slower and add maintenance burden for no functional gain. The chain-side gas table maps WASM instruction categories and individual host functions to fuel costs; the engine consumes that table at startup and configures wasmtime accordingly.

Why a single dimension

Earlier drafts of this book described a two-dimensional gas model (exec_cost + prove_cost) intended to price both CPU work and ZK proving work separately. With ZK proving deferred to post-mainnet, the proving-cost dimension does not exist at launch and the two-dimensional model collapses into a single number — the chain-level gas total derived from wasmtime fuel consumption.

Should ZK proving land later, the second dimension can be re-introduced as a separate counter without changing the wire format (transactions already carry only gas_limit).

10.2 EIP-1559 Base Fee

Pyde's base fee adjusts every block by up to 12.5% in either direction based on whether the previous block exceeded or fell below the gas target.

Constants (crates/tx/src/fee.rs)

Adjustment formula

#![allow(unused)]
fn main() {
fn adjust_base_fee(parent_base_fee: u128, parent_gas_used: u64) -> u128 {
    if parent_gas_used == GAS_TARGET {
        parent_base_fee
    } else if parent_gas_used > GAS_TARGET {
        let delta = parent_gas_used - GAS_TARGET;
        let bump  = parent_base_fee * delta as u128 / GAS_TARGET as u128 / 8;
        parent_base_fee + bump.max(1)
    } else {
        let delta = GAS_TARGET - parent_gas_used;
        let drop  = parent_base_fee * delta as u128 / GAS_TARGET as u128 / 8;
        (parent_base_fee.saturating_sub(drop)).max(MIN_BASE_FEE)
    }
}
}

Properties:

• Proportional adjustment. The change scales with how far the block deviated from target. A block at 75% target produces a smaller bump than one at 100% target.
• Capped at ±12.5% per block. No oracle, no governance vote.
• Bounded below by MIN_BASE_FEE. Cannot reach zero.
• Minimum increase of 1 quanta. Even at very low fees, a busy block bumps the fee at least one quanta.

Convergence at ~500 ms commits

Mysticeti DAG produces a commit every ~500 ms median (Chapter 6). Each commit is the unit at which the base fee is recomputed (block and commit are interchangeable here — Pyde collapses both concepts since the DAG commits at per-commit granularity).

Equilibrium under fluctuating demand sits around 50% of the gas target.

10.3 Elastic Blocks

Pyde blocks have two gas limits:

Block builders can pack up to 4 × GAS_TARGET = 1.6B gas into a single block. When they exceed the target, the base fee for the next block rises proportionally.

Gas usage during a congestion spike:

   4× ┤ ......................... hard ceiling
      │
   3× ┤            +-+
      │           /   \
   2× ┤      +---+     +---+
      │     /               \
target┤----+                 +---+----  target line
      │   /                       \
   1× ┤  /                         +-...
      │
      +---------------------------------------> blocks
                spike      decay
        base fee rises ~2x         then settles

Why 4× and not higher

• Validator memory. A 4× block has up to 4× more transactions to buffer, decrypt, and execute. The per-validator memory ceiling caps how high this can safely go on commodity hardware.
• Decryption + voting timing. Threshold decryption shares for a 4× block take longer to combine; the commit timing budget assumes the worst case fits.
• State growth. Larger blocks drive faster state growth. The 4× ceiling bounds worst-case growth by the same factor.

Gas-bound throughput ceiling

At 2 commits/sec (~500 ms commit), GAS_TARGET = 400M, GAS_CEILING = 1.6B:

Honest v1 numbers. The gas-bound ceiling above is a mechanical cap — block gas budget ÷ gas-per-tx — assuming committee hardware fully saturates execution. In practice, the v1 honest throughput target (to be established by the multi-region performance harness) is set on commodity committee hardware (500 Mbps NIC, 32-core, 64 GB). Higher numbers require larger NICs and more cores; see Chapter 19 for the launch-strategy capacity table.

Real numbers depend on workload composition. The performance harness (companion/PERFORMANCE_HARNESS.md) is the only valid source of TPS claims — publish only what the harness measures under sustained, production-realistic conditions, never lab extrapolations or microbenchmark peaks. The headline number is never the theoretical max.

10.4 No Tips, No Priority Fees

Pyde's transaction format has no priority-fee field. Every transaction pays exactly:

fee = gas_used * base_fee

There is no bidding, no auction, no out-of-protocol payment to any committee validator. The MEV-protection consequences are spelled out in Chapter 9; the gas-economics consequences are:

• Predictable fees. Wallets can quote a single number, not a range.
• No fee market gaming. No need for fee-estimation oracles or multi-priority queues.
• Simpler accounting. The fee distribution is a single division, not a base-vs-tip split.

How does ordering happen, then?

Under the Mysticeti DAG, ordering is a deterministic function of the committed subdag — vertices are produced independently each round, the anchor commit selects a canonical traversal, and transactions emerge in a fixed canonical order. No actor chooses positions; the order is structural (Chapters 6 and 9).

For sequential nonce dependencies, the protocol uses the 16-slot nonce bitmap window (Chapter 11) — a sender can submit txs n, n+1, n+2 out of order; gaps are tolerated up to the window size.

Legitimate urgency

Use cases that need fast inclusion (liquidations, bridges, time-sensitive trades) have two routes:

• Pre-fund a paymaster's gas tank (sponsored tx — see §10.7) so the user doesn't bottleneck on liquidity.
• Use the deadline field to expire stale txs that were not included quickly, freeing the nonce slot for a fresh attempt.

Neither route bribes anyone for ordering.

10.5 Fee Distribution: 70 / 20 / 10

Every fee splits deterministically:

Note: in the pre-pivot HotStuff design the 20% went directly to the slot proposer. Under the DAG there is no single proposer, so the validator share goes to an epoch reward pool indexed by stake and uptime. See Chapter 14 for the per-validator yield math.

Implemented as distribute_fee in crates/tx/src/execution.rs:

#![allow(unused)]
fn main() {
pub fn distribute_fee(effective_gas: u64, base_fee: u128) -> FeeDistribution {
    let total_fee  = effective_gas as u128 * base_fee;
    let burned     = total_fee * 70 / 100;
    let reward_pool = total_fee * 20 / 100;
    let treasury   = total_fee - burned - reward_pool;   // remainder catches rounding
    FeeDistribution { burned, reward_pool, treasury }
}
}

The remainder-to-treasury pattern catches rounding dust so no quanta are lost.

Why not 100% burn?

A 100% burn (Ethereum's EIP-1559 model for the base fee) means validators get nothing from fees and depend entirely on inflation rewards. This works when inflation is generous, but it makes the security budget brittle: as inflation decreases, validator economics become fully dependent on tip volume, which Pyde doesn't have.

The 20% reward-pool share compensates the full staked validator set (both active-committee and validators awaiting selection, per stake × uptime) and ties their compensation to network usage in addition to inflation. Under the DAG there is no single proposer to credit, so the share is pooled and distributed at epoch end. The 10% treasury share funds protocol work via PIP-driven multisig spends (Chapter 15).

Why no prover share?

Earlier drafts of this book had a 70 / 20 / 10 split where the 10% went to provers. Without provers at mainnet, that 10% goes to the treasury. The on-chain math is the same; only the recipient changed.

If ZK proving lands in a future hardfork, the split can be adjusted by governance (a PIP + on-chain multisig action). Until then the treasury gets the 10%.

10.6 Fee Calculation Examples

Simple transfer (21,000 gas)

At GENESIS_BASE_FEE = 50,000,000,000 quanta:
  fee = 21,000 * 50,000,000,000
      = 1,050,000,000,000,000 quanta
      = 1,050,000 micro-PYDE
      = 1.05 milli-PYDE
      = 0.00105 PYDE

Distribution:
  Burn:      735,000,000,000,000 quanta  (~0.000735 PYDE)
  Validator: 210,000,000,000,000 quanta  (~0.000210 PYDE)
  Treasury:  105,000,000,000,000 quanta  (~0.000105 PYDE)

High-congestion scenario

If sustained demand has driven the base fee 3.5× higher:

base_fee = 175,000,000,000 quanta
fee = 21,000 * 175,000,000,000 = 3,675,000,000,000,000 quanta = 0.003675 PYDE

Burn:      2,572,500 micro-PYDE
Validator:   735,000 micro-PYDE
Treasury:    367,500 micro-PYDE

Low-demand scenario

If sustained empty blocks have driven the base fee to half normal:

base_fee = 25,000,000,000 quanta
fee = 21,000 * 25,000,000,000 = 525,000,000,000,000 quanta = 0.000525 PYDE

The base fee keeps adjusting until the market clears — congestion makes it expensive to spam, low usage makes inclusion cheap.

10.7 Sponsored Transactions

A user with no PYDE balance can still transact if a contract or paymaster account pays the gas. Two mechanisms exist.

Gas tanks

Every account has a gas_tank: u128 field (see Chapter 4 / 11). It's a balance separate from the account's spendable balance, dedicated to paying gas on behalf of users.

Anyone can deposit to any account's gas tank:
  deposit_gas_tank(target, amount)

Only the account owner can withdraw:
  withdraw_gas_tank(target, amount, recipient)

To use a gas tank, a transaction sets:

tx.fee_payer = FeePayer::GasTank

The engine looks up the target contract's gas_tank, debits the fee from there, and credits the receiver as usual. If the gas tank is empty, the tx reverts (the sender did not pay).

Paymaster pattern

For more complex sponsorship (eligibility checks, per-user limits), a paymaster contract sits between the user and the target:

tx.fee_payer = FeePayer::Paymaster(paymaster_address)

The engine calls the paymaster's validate_sponsorship(user, target, calldata) -> bool function (gas-bounded — see below). If it returns true, gas is debited from the paymaster's gas tank.

+----------+      +------------------+     +-----------------+
|   User   |----->|   Paymaster      |---->|  Target         |
|  (no $)  |      |   - eligibility  |     |  Contract       |
+----------+      |   - rate limits  |     +-----------------+
                  |   - gas tank pays |
                  +------------------+

Validation gas limit

To stop a paymaster from running an expensive validation function as a DoS vector, the paymaster's validate_sponsorship has a hard gas cap of 100,000 gas. If validation exceeds that, the tx is rejected. This prevents an adversarial paymaster from making mempool inclusion expensive for relays.

Use cases

10.8 Gas Costs for Common Operations

The full WASM-instruction and host-function gas table is published in the Host Function ABI specification. The headline numbers for the operations that dominate real-world gas usage:

Storage

Crypto

Cross-contract

Events

WASM execution (per-instruction baseline)

The build-time state binding generator (see Chapter 5) emits efficient access patterns; for example, a single map lookup expands to one host-function call rather than multiple. The wasmtime-AOT pass then compiles the resulting WASM to native code for execution.

10.9 Validation Limits

The transaction validator (crates/tx/src/validation.rs) enforces these limits at RPC ingress:

MAX_CALLDATA is a separate cap from MAX_TX_SIZE (per the audit recommendation — task 055 in the mainnet plan). The split prevents an attacker from building a tx whose calldata fills the entire 128 KB tx budget and starves the rest of the encoded fields.

A transaction that fails any of these checks is rejected at the RPC node and never enters the mempool — pollution is constrained to that single ingress node.

10.10 Fee Estimation API

pyde_estimateGas runs the transaction in simulation against the current state and returns the predicted gas consumption.

> pyde_estimateGas
> {
>   "from":  "0xpyde1abc...",
>   "to":    "0xpyde1def...",
>   "data":  "0x...",
>   "value": "0x0"
> }
< {
<   "gas_estimate": 45200,
<   "base_fee":     "0x2D79883D2000",
<   "estimated_fee": "2260000000000000"
< }

Wallets typically multiply the estimate by ~1.10 to absorb state changes between estimation and inclusion. Because base fee can move at most ±12.5% per block, the inclusion-time fee is bounded relative to the estimation-time fee.

pyde_call runs read-only simulation without state mutation; pyde_createAccessList produces the access list that should accompany the transaction. Wallets typically chain these calls automatically: createAccessList → estimateGas → submit signed tx with the resulting access list.

10.11 Comparison

10.12 Implementation Notes

Integer arithmetic

All fee calculations use integer arithmetic to avoid floating-point non-determinism. Quanta are u128 (1 PYDE = 10^9 quanta — note this is not Ethereum's 10^18 wei scale).

Overflow protection

compute_fee() uses checked_mul to detect overflow. Realistic inputs (gas_used in millions, base_fee in billions of quanta) fit comfortably in u128 (max product ≈ 2^60 * 2^40 = 2^100, well below 2^128). The overflow check guards against pathological encodings.

Base fee in the commit header

Pyde's commit header is the equivalent of Ethereum's block header for fee-market purposes — each commit carries the base fee for transactions executed in that commit:

#![allow(unused)]
fn main() {
struct CommitHeader {
    // ...
    base_fee:    u128,     // base fee for txs in THIS commit
    gas_used:    u64,      // total gas consumed by this commit's txs
    gas_target:  u64,      // = GAS_TARGET (always 400M)
    gas_limit:   u64,      // = GAS_CEILING (always 1.6B)
}
}

(The web3-compatibility RPC methods pyde_getBlockByNumber / pyde_getBlockByHash return a representation of this header, since external tooling expects "block" terminology.)

The base fee for block N+1 is computed from block N's header by adjust_base_fee() — every honest node arrives at the same value.

Summary

The next chapter covers the account model the fee model sits on top of — addresses, the nonce window, multisig, and batch transactions.

Chapter 14: Tokenomics

PYDE is the network's native token. It pays for gas, secures consensus through validator staking, and funds protocol work via the treasury. This chapter covers the on-chain mechanics: supply, the inflation schedule, the fee distribution, validator economics, the vesting + airdrop machinery that ships at genesis, and the treasury that funds ongoing protocol work.

Numbers are taken from the actual code constants in crates/tx/src/fee.rs, crates/slashing/src/lib.rs, and crates/consensus/src/validator.rs — not from aspirational projections. Where a parameter is set at genesis (as opposed to hard-coded), the chapter says so.

14.1 Denomination

PYDE has 9 decimals: 1 PYDE = 1,000,000,000 quanta (10^9).

1 quanta        = 0.000000001 PYDE
1 micro-PYDE    = 1,000 quanta            (10^-6 PYDE)
1 milli-PYDE    = 1,000,000 quanta        (10^-3 PYDE)
1 PYDE          = 1,000,000,000 quanta    (10^9)
1 kilo-PYDE     = 10^12 quanta             (10^3 PYDE)
1 mega-PYDE     = 10^15 quanta             (10^6 PYDE)

All on-chain balances are stored as unsigned 128-bit integers in quanta. This easily covers the genesis supply of 1B PYDE (= 10^18 quanta) without overflow risk, and provides enough precision for micro-transactions.

(Note: Pyde's denomination is not Ethereum's 10^18 wei scale. SDKs expose the correct conversion automatically.)

14.2 Genesis Supply

Genesis total supply: 1,000,000,000 PYDE (1 billion).

#![allow(unused)]
fn main() {
pub const GENESIS_SUPPLY: u128 = 1_000_000_000 * 1_000_000_000;  // = 10^18 quanta
}

(crates/tx/src/fee.rs:84)

This is the entire on-chain PYDE in existence at block 0. From block 1 onward, new PYDE enters circulation only via the inflation schedule; no other minting path exists.

Distribution

The genesis allocation is set in the genesis configuration TOML; the on-chain machinery enforces:

• Per-bucket caps — the genesis builder rejects allocations that exceed the per-category caps to prevent oversupply.
• Vesting schedules — most non-validator allocations are subject to on-chain vesting (see §14.6).
• Validator subsidy stream — a portion of the genesis pool is reserved for validator subsidy that streams over a fixed window (§14.4).
• Airdrop pool — genesis seeds an airdrop account with the expected total; claims draw against it; the residual sweeps to the treasury after the deadline.

The exact percentages between buckets (treasury, team vesting, ecosystem, validator subsidy, airdrop) are governance-set parameters in the genesis file rather than protocol constants. The launch genesis is finalized by the Foundation in coordination with the validator set during the mainnet genesis ceremony (Phase 10 of the launch plan).

No supply cap

PYDE has no hard cap. The supply grows by a decreasing inflation rate and shrinks via the 70% fee burn. At target throughput the burn exceeds inflation and the network is net deflationary; at low throughput inflation dominates. The equilibrium depends on usage.

14.3 Inflation Schedule

The inflation rate decreases on a year-by-year schedule:

#![allow(unused)]
fn main() {
pub const INFLATION_BPS: [u16; 4] = [
    500,   // year 1: 5.0%
    300,   // year 2: 3.0%
    200,   // year 3: 2.0%
    100,   // year 4+: 1.0% (terminal)
];
}

(crates/tx/src/fee.rs:92-98, expressed in basis points.)

Year   Annual rate
----   -----------
1      5.0%
2      3.0%
3      2.0%
4+     1.0%   (terminal — never decreases further)

The 1% terminal floor exists so validators always have a baseline reward stream regardless of fee volume. At target throughput, fee burn easily exceeds 1% inflation; at lean throughput, inflation keeps validator economics viable.

Per-wave inflation reward

waves_per_year = 63_113_904         (2 commits/sec * 86400 s/day * 365.25 days)

reward_per_wave = GENESIS_SUPPLY * inflation_rate_bps / (10_000 * waves_per_year)

At year 1 (5%):

reward_per_wave = 10^18 quanta * 500 / (10_000 * 63_113_904)
               ≈ 792,202,572 quanta
               ≈ 0.792 PYDE per wave

At year 4+ (1%):

reward_per_wave ≈ 158,440,514 quanta ≈ 0.158 PYDE per wave

This per-wave reward credits the reward pool and the treasury at the shares specified by the on-chain reward distribution (see §14.4).

Why a decreasing schedule

• High initial inflation bootstraps validator participation before fee volume exists.
• Decreasing schedule rewards token holders as the network matures — early validators were taking risk that later operators don't.
• Terminal 1% stays low enough that ordinary fee burn at any meaningful usage produces net deflation.

14.4 Fee Distribution: 70 / 20 / 10

Every transaction fee splits deterministically (Chapter 10):

#![allow(unused)]
fn main() {
pub const FEE_BURN_PCT: u64           = 70;    // burned (deflationary)
pub const FEE_REWARD_POOL_PCT: u64    = 20;    // distributed to stakers
pub const FEE_TREASURY_PCT: u64       = 10;    // treasury account
}

(crates/tx/src/execution.rs:17-20)

The distribute_fee function:

#![allow(unused)]
fn main() {
pub fn distribute_fee(effective_gas: u64, base_fee: u128) -> FeeDistribution {
    let total_fee   = effective_gas as u128 * base_fee;
    let burned      = total_fee * 70 / 100;
    let reward_pool = total_fee * 20 / 100;
    let treasury    = total_fee - burned - reward_pool;   // remainder catches dust
    FeeDistribution { burned, reward_pool, treasury }
}
}

The remainder-to-treasury pattern means rounding dust never disappears.

Where each share goes

• Burn — increments the on-chain TOTAL_BURNED counter under discriminator 0x13. Permanently removes PYDE from circulation.
• Reward pool — credited to the epoch reward pool account, distributed at epoch end to all staked validators (committee + non-committee) proportional to stake × uptime. Under the DAG there is no single proposer to credit; the pool model spreads rewards across the entire staked validator set.
• Treasury — credited to the treasury account at Poseidon2("pyde-treasury"). Spent through MultisigTx (Chapter 15).

Why 70% burn

• High burn pressure. At sustained moderate usage with realistic fee loads, the annual burn exceeds the annual mint within a few years — net deflation.
• MEV resistance. A would-be MEV searcher who used Pyde for extraction would burn 70% of the captured value. Combined with the encrypted-mempool protections (Chapter 9), this further dis-incentivizes attempts.
• Validator share is meaningful but not dominant. 20% pool share is enough to reward staking without making validators primarily fee-driven.

Net inflation analysis

Net inflation = (mint per year) − (burn per year). Illustrative figures at a representative base-fee assumption:

At sustained moderate usage, the network is near-neutral to deflationary in year 1. At the 1% terminal inflation rate (year 4+), even very low TPS produces net deflation.

14.5 Validator Economics

Single-tier staking

#![allow(unused)]
fn main() {
pub const MIN_VALIDATOR_STAKE: u128 = 10_000_000_000_000;   // 10,000 PYDE
}

Single pool, no tiers. Every validator meeting the 10K PYDE minimum is in the same pool. At each epoch boundary, uniform-random selection picks 128 from the pool to form the active committee for that epoch (see Chapter 6 §7). There is no "committee tier" vs. "non-committee tier" — just one validator role, with committee duty rotating per epoch.

Equal voting in committee. All 128 committee members have equal vote weight regardless of stake. To get additional selection probability, a wealthy staker must register multiple distinct validators with separate FALCON keys and operator identities — and each faces independent slashing exposure plus the per-operator cap (see below).

Why 10K, not higher. Pyde's MEV-extraction attack value is structurally near-zero (threshold encryption + commit-before-reveal ordering eliminate the profit motive that drives Ethereum-scale stake floors). With the attack-incentive removed, stake serves as a credible-commitment deposit against slashable misbehavior rather than as the load-bearing economic defense. Pyde's Sybil resistance is layered (operator-identity cap + slashing + threshold encryption + state-root divergence detection) — see Chapter 16 §16.4 for the full security argument.

The 10K floor matches the spirit of Ethereum's "Lean Consensus" direction (reducing 32 ETH → 4 ETH as fast finality reduces reversibility-window risk) and keeps the modest-hardware-decentralization promise intact: at realistic launch valuations, the bond is accessible without being trivial.

Anti-Sybil: operator-identity cap. Maximum 3 validators per operator identity. An attacker pursuing a Byzantine fork needs 43 committee slots, which translates to ≥ 15 distinct KYC'd operator identities under the cap — meaningfully harder to manufacture than capital alone.

Income sources

A validator's gross income per year:

1. Inflation share. A portion of the per-block inflation reward, paid to the epoch reward pool. Distributed across staked validators (committee + non-committee) proportional to stake × uptime — discriminator 0x15 tracks the active stake-weighted total used as the denominator.
2. Fee revenue. 20% of every fee in every committed wave flows to the same epoch reward pool, distributed by the same stake × uptime rule (there is no single proposer in the DAG to credit).

Lazy reward accrual

Rewards do not get pushed to the validator on every block — that would mean N writes per block. Instead, a global per-stake accumulator (REWARDS_PER_STAKE_UNIT at discriminator 0x14) tracks the cumulative yield per unit of staked PYDE × uptime:

On each block:
  rewards_per_stake_unit += per_block_reward / total_active_stake_weighted_by_uptime

On ClaimReward (tx type 6):
  owed = (current_accumulator - validator.last_claimed_at) * validator.stake * validator.uptime_share
  pay owed
  validator.last_claimed_at = current_accumulator

ClaimReward is only valid for Active (status 0x00) and Unbonding (status 0x01) validators; Exited (status 0x02) validators are explicitly rejected to prevent post-exit accrual leakage.

Validator status lifecycle

#![allow(unused)]
fn main() {
enum Status {
    Active    = 0x00,
    Unbonding = 0x01,
    Exited    = 0x02,
}
}

Transitions:

register     ->  Active
StakeWithdraw ->  Unbonding (30-day countdown)
unbond expires -> Exited (stake returned, removed from pool)
slashed (forced) -> Exited (stake reduced or zero)

Unbonding period

#![allow(unused)]
fn main() {
pub const UNBONDING_PERIOD_DAYS: u64 = 30;   // wall-clock, independent of consensus cadence
}

(crates/consensus/src/validator.rs)

A validator who initiates StakeWithdraw (tx type 4) cannot reclaim their stake until 30 days have passed. The period must exceed the 21-day safety-evidence freshness window so attackers cannot withdraw before their offense becomes provable.

During the unbonding window:

• Status is Unbonding.
• Stake is locked.
• Validator no longer signs (removed from active committee).
• Pending rewards continue to accrue and can be claimed via ClaimReward.
• Slashing for past offenses still applies — the unbonding window exists precisely so post-exit evidence can still penalize.

After 30 days, an explicit follow-up sweeps the unbonded stake back to the validator's spendable balance and marks them Exited.

Slashing

Reused from Chapter 6 and companion/SLASHING.md. Penalties scale with stake (percentages of the offender's at-risk stake at the time of offense):

Of every slashed amount:

• 10% pays the evidence submitter (FINDER_FEE_PERCENT).
• 90% is burned.

This permissionless evidence-and-burn model means anyone who detects misbehavior is incentivized to submit it, and slashed PYDE is removed from circulation rather than redistributed (preventing perverse "slashing profit" incentives).

Indicative APY

APY = (annual_PYDE_rewards / staked_PYDE) × 100. Rewards distribute by stake × uptime, so per-token yield is uniform across all validators — only the absolute PYDE earned scales with stake. Committee participation adds an activity-weighted bonus, but the base yield is the same.

At year 1, assume 5,000 active validators averaging 100K PYDE staked each (~500M total staked, modest middle ground while supply distributes), 128 selected to the active committee, modest fee volume, 60% of mint flowing to the reward pool:

Inflation share to reward pool (assume 60% of mint):
  ~30M PYDE / 500M total staked  ≈ 6% APY on staked balance
Committee bonus (activity-weighted, 128 of 5000):
  marginal additional ~0.5-1% APY during the ~3 hr epoch a validator
  is on the committee (and 0 the rest of the time)
Average over a year: small uplift for active operators

Yields vary with how much total stake competes for the pool and where inflation sits on the taper:

Year 1 yields are high by design — bootstrap incentive while the validator set grows from genesis. As more validators come online, the per-token yield compresses naturally. The 1% terminal inflation rate plus the 20% fee-share keeps the steady-state validator economic viable without unbounded dilution.

The exact split between reward pool and treasury inside the inflation mint, and the trajectory of total validator count, are governance parameters; the numbers above are rough sketches, not commitments.

14.6 Vesting

Genesis allocations (team, ecosystem) are subject to on-chain vesting.

#![allow(unused)]
fn main() {
struct VestingSchedule {
    start_wave:     u64,
    cliff_waves:    u64,
    duration_waves: u64,
    total_amount:   u128,
}
}

(crates/tx/src/vesting.rs:29-34, wire format 40 bytes: start:8 || cliff:8 || duration:8 || total:16 LE)

Unlock curve

wave_id < start + cliff             -> unlocked = 0
wave_id >= start + duration         -> unlocked = total_amount
otherwise                            -> unlocked = total_amount * (wave_id - start) / duration

Cliff > duration safeguard

A genesis misconfiguration where cliff > duration would trap funds forever (the cliff fires before the duration ends, then the duration "ends" but the cliff still applies). The slice-5.1 audit fix prioritizes end-of-vesting over cliff:

#![allow(unused)]
fn main() {
if wave_id >= start + duration {
    return total_amount;          // FULL UNLOCK regardless of cliff
}
if wave_id < start + cliff {
    return 0;
}
// linear interpolation
}

Plus genesis validation rejects schedules where cliff > duration.

Validation integration

Every transaction validation reads the sender's vesting schedule and subtracts vesting.locked_at(current_wave_id) from the account's balance before checking that the sender can pay gas_limit * base_fee + value. A sender cannot transfer locked tokens — the protocol enforces it at ingress.

14.7 Airdrop

Genesis ships an airdrop pool with claims gated by Merkle proof.

State

The airdrop pool account lives at Poseidon2("pyde-airdrop-pool"). At genesis, the pool is funded with AIRDROP_EXPECTED_SUM (sanity check against drift between the off-chain Merkle builder and the genesis balance).

Merkle tree format

Leaf:     Poseidon2(0x00 || leaf_index_le8 || address || amount_le16)
Internal: poseidon2_pair(left, right)

Direction bit comes from the leaf_index (prevents sorted-pair attacks where
an attacker could swap left and right siblings to forge a proof).

Claim flow (tx type 7)

data = [leaf_index:8 LE][amount:16 LE][proof_len:1][sibling_0:32]...[sibling_N-1:32]

ClaimAirdrop handler:
  1. Check current_wave_id <= AIRDROP_DEADLINE.
  2. Check claim hasn't been redeemed (AIRDROP_CLAIMED bit unset).
  3. Verify Merkle path against AIRDROP_ROOT.
  4. Debit pool by amount; credit claimant.
  5. Set the claim bit.

Gas: 30,000 base + 5,000 per Merkle level. Early gas guard rejects if tx.gas_limit < required_gas before mutating any state — fixed in PR #212 to prevent under-paid claims from drifting state. Max proof length is 255 levels.

Sweep flow (tx type 8)

After the deadline, anyone can call SweepAirdrop:

SweepAirdrop handler (any sender):
  1. Check current_wave_id > AIRDROP_DEADLINE.
  2. Move pool's residual balance to the treasury account.

Gas: 40,000 flat. The sweep is permissionless because the funds belong to the protocol — anyone can submit it once the window closes. The early-gas guard pattern applies here too.

14.8 Treasury

The treasury is a system account at Poseidon2("pyde-treasury"). It accumulates value from three streams:

1. Genesis allocation — direct allocation in the genesis config.
2. Fee share — 10% of every transaction fee.
3. Inflation share — a configurable share of per-block mint.
4. Airdrop residual — whatever wasn't claimed by the deadline.

Treasury spending is always through the on-chain MultisigTx (tx type 9). There is no other path that drains the treasury account (enforced by the pipeline writeback-clobber protections — see §14.9).

MultisigTx payload

#![allow(unused)]
fn main() {
struct MultisigSpend {
    target:      Address,
    value:       u128,
    data_digest: [u8; 32],   // hash(pip_file_contents) — audit trail to PIP
}
}

The data_digest field is the on-chain link to the off-chain PIP (Pyde Improvement Proposal) document. Anyone auditing the chain can recover the PIP from its hash, verify the signers approved that exact spend, and trace the on-chain action back to a published proposal.

Multisig configuration

Max signers: 16 (MAX_MULTISIG_SIGNERS). Each spend bumps MULTISIG_NONCE so the same signed bytes cannot be replayed.

Wire format (MultisigPayload in crates/tx/src/multisig.rs):

[op_version: 1] [op_body: variable] [sig_count: 1]
[sig_entry_0] ... [sig_entry_N-1]

sig_entry = [signer_index: 1] [sig_len: 2 LE] [falcon_sig: sig_len]
op_version = 0x01 (MULTISIG_VERSION)

Gas: 50,000 base + 50,000 per signature.

Rotating the signer set

RotateMultisig (tx type 10):

#![allow(unused)]
fn main() {
struct MultisigRotate {
    new_signer_pks: Vec<Vec<u8>>,    // each is a 897-byte FALCON pk
    new_threshold:  u8,
}
}

Rotation requires the current signer set to authorize. Validation checks: at least one new signer, threshold ≤ new signer count.

Gas: 60,000 base + 50,000 per signature + 10,000 per new signer.

14.9 Emergency Pause

A multisig-authorized circuit breaker that halts all transactions except EmergencyResume.

Pause (tx type 11)

#![allow(unused)]
fn main() {
struct EmergencyPausePayload {
    duration_waves: u64,
    sigs:           Vec<SigEntry>,
}
}

• duration_waves ∈ [1, MAX_PAUSE_DURATION_WAVES] where the cap is 6,500,000 slots (≈ 30 days). Reject zero or excessive durations.
• Reject re-pause if the chain is already paused.
• Sets EMERGENCY_PAUSE_END_WAVE (discriminator 0x1F) = current_wave_id + duration_waves.
• Bumps multisig nonce.
• Gas: 40,000 base + 50,000 per signature.

Resume (tx type 12)

#![allow(unused)]
fn main() {
struct EmergencyResumePayload {
    sigs: Vec<SigEntry>,
}
}

• Requires the chain to be currently paused.
• Zeros EMERGENCY_PAUSE_END_WAVE.
• Bumps multisig nonce.
• Gas: 40,000 base + 50,000 per signature.

Pause-gate semantics

is_paused(state, current_wave_id) returns true if current_wave_id < EMERGENCY_PAUSE_END_WAVE. While paused, the pipeline rejects every transaction type except EmergencyResume before running validation or charging gas. This means a paused chain cannot be spammed into draining gas budgets.

The pause auto-expires (current_wave_id >= end_wave) without an explicit sweep — the gate just stops returning true. This means the worst case for a runaway pause is the 30-day cap, never indefinite.

Use cases

• Critical bug discovered after audit but before fix is deployed.
• Active exploit being mitigated; pause halts state mutation until a fix ships.
• Coordinated upgrade window (rare; voluntary upgrades are the normal path — see Chapter 18).

The signer set should be picked specifically for crisis response (likely core developers + security team multisig), not the same set that signs treasury spends. This is a configuration decision, not a protocol constraint.

14.10 Writeback Clobber Protection

A subtle pipeline interaction: every transaction's post-execution stage unconditionally writes the sender's and recipient's account state back to the JMT. If a MultisigTx handler credits a target that collides with either tx.from or tx.to, the writeback would overwrite the credit.

The fix:

• MultisigTx rejects if spend.target == tx.from (submitter).
• MultisigTx rejects if tx.to != Address::ZERO (must not collide with a regular tx target).

Same defenses are applied to RotateMultisig to prevent any signer collision from clobbering the signer-set update.

14.11 Active-Stake Divisor and Unified Parsing

The pool-share calculation divides by ACTIVE_STAKE_WEIGHTED_TOTAL (discriminator 0x15) — the sum of stake × uptime_share across every validator currently in Active status. This diverges from VALIDATOR_COUNT (the total registered count) once validators exit or are slashed, and from a flat-per-validator divisor once validators differ in stake or uptime (the common case across the two staking tiers).

Without this divisor, exited validators would dilute the pool share — even though they're not contributing security. Adjusted on:

• StakeWithdraw (validator transitions to Unbonding; their stake weight is removed from the total)
• Slash of an Active validator (stake weight decreases, or removed entirely on jail/exit)
• Each block where a validator's uptime_share changes (lazy, indexed by the same accumulator pattern as REWARDS_PER_STAKE_UNIT)

ValidatorEntry parsing is unified through ValidatorEntry::decode() — the same parser is used by every consensus and tx-handler call site. Length: 4 + 897 (FALCON pk) + 16 (stake u128) + 1 (status) + 16 (last_claimed_at u128) = 934 bytes.

(This unification fixed a genesis bug where an earlier per-call-site parser returned None on every genesis validator — surfaced and fixed in multi-node test #228.)

14.12 Long-Run Equilibrium

The model targets:

The 1% terminal inflation rate × GENESIS_SUPPLY is around 10M PYDE per year. Even modest sustained throughput (a few thousand TPS at typical fee levels) burns more than that. Net deflation is the long-run expected state.

Summary

The next chapter covers governance — how PIPs (Pyde Improvement Proposals) become on-chain MultisigTx actions, and what scope governance has versus what's hard-coded.

Chapter 15: Governance

Pyde's governance is deliberately minimal at the protocol level. There is no two-chamber voting machine, no plutocratic stake-weighted ballot, no on-chain referendum logic. The model is off-chain Pyde Improvement Proposals (PIPs) + an on-chain treasury multisig, with everything else either hard-coded or operationally driven.

This chapter describes the actual governance design: how proposals form, how rough consensus is reached, what authority the on-chain multisig has, and what falls outside governance entirely.

15.1 Why "Off-Chain PIPs + On-Chain Multisig"

A small number of governance models are well-explored in production blockchains, each with distinct failure modes:

Pyde's choice is closer to the Bitcoin BIP / Ethereum EIP model than to Cosmos-style on-chain governance:

1. Proposals are documents, not on-chain ballots. They live in a public pips repo (zarah-s/pips), open to any author, indexed and discussed in the open.
2. Adoption is via voluntary validator upgrade. When validators running a new client version reach a sufficient share of the active committee, the new behavior takes effect. Validators that don't upgrade continue running the old rules and either follow along (no consensus change) or fork off (consensus-breaking change).
3. The on-chain treasury multisig executes spends linked to PIPs. The MultisigTx payload carries data_digest = hash(pip_file_contents), so every treasury action is on-chain-linked to a published PIP.

The model's core property: no party can drain the treasury, halt the chain, or change the rules without a coordinated, public, auditable process. Drainage requires multisig signers; chain halt requires the emergency multisig; rule changes require validators choosing to run the new code.

15.2 The PIP Process

PIPs are governed by PIP-0001, the founding document that ratifies the PIP system itself. The process at a high level:

PIP lifecycle:

  1. Draft        Author writes a markdown document (problem, design,
                  rationale, security considerations).
                  Creates a PR against zarah-s/pips.

  2. Discussion   Open discussion on the PR, in forums, etc.
                  Author iterates.

  3. Review       PIP receives review from core devs, validators, the
                  security team. Concerns are addressed in discussion.

  4. Acceptance   PIP is merged into the pips repo with a final number.
                  An acceptance signal does not change protocol behavior
                  by itself — it is documentation of rough consensus.

  5. Implementation The PIP is implemented in a code change (PR against
                  the relevant Pyde repo). The PIP # is referenced.

  6. Deployment   The new node version ships. Validators choose to run
                  the new version. Once a sufficient validator share
                  upgrades, the change takes effect on-chain.

There is no on-chain "yes/no" vote on the PIP itself. The closest thing to a vote is validators choosing to run the new code — a softer but genuine signal.

What gets a PIP