How Layrs works

Layrs is a private prediction-market protocol. Trading happens inside an attested Trusted Execution Environment (TEE) — a secure enclave — so that individual orders, balances, and the order book stay confidential. Only netted, signed results reach the blockchain. This page walks through the end-to-end lifecycle, from attesting the enclave to final payout, and draws the line between what happens inside the enclave and what happens outside it.

The core idea: match privately, settle publicly

A traditional central limit order book (CLOB) exposes every resting order and every fill. Layrs runs the matching engine — private_core and the layrs-enclave binary — inside an attested secure enclave. The matching logic, per-user balances, and the full order book live behind that boundary. The host machine that runs the enclave never sees plaintext orders; it only transports ciphertext and stores encrypted artifacts.

What the public chain and public API see is deliberately narrow: an aggregated view of depth, published receipts, and a periodic netted batch settlement. Per-user orders never reach the chain — only the netted batch does.

The inside / outside boundary

Layrs draws a hard boundary between the private core running in the enclave and the host process that surrounds it.

Inside the enclave (private):

• Opaque private-user identities and signed sessions
• available, held, collateral, fee, and position balances
• Deterministic price-time matching with self-trade prevention
• Complete-set mint/burn and one-to-one market collateral
• Fee accounting: 0 bps maker, 20 bps taker, plus a 5% positive winning-profit fee computed on a per-position cost basis
• Signed Pyth-based resolution
• An encrypted, hash-chained journal, deterministic receipts, and AEAD-encrypted snapshots

Outside the enclave (public / host):

• Authentication and compliance eligibility
• Chain and Pyth connectivity
• VSOCK ciphertext transport — the host never sees plaintext
• Encrypted journal and snapshot storage
• Aggregate depth and public receipt publication (never the per-user book)

Two control facts anchor this boundary:

• The parent / host process cannot submit an admin operation without the Ed25519 operator key compiled into the EIF (the enclave image).
• A user cannot execute an order without all of: a registered enclave session, a valid signature, an unexpired request, and a strictly increasing sequence number.

The order lifecycle, end to end

At a high level, an order travels through the following stages. The critical property is that the client verifies the enclave before trusting it with anything.

1. Attest      client verifies the enclave's PCR0 measurement (fresh, unexpired)
2. Session     client opens a private, signed session
3. Seal        client seals a signed order to the enclave's transport public key
4. Match       deterministic price-time matching runs privately inside the TEE
5. Settle      only the netted batch reaches chain via batchSettle
6. Resolve     signed Pyth samples decide UP / DOWN / PUSH at the boundary
7. Payout      winnings are settled to the private ledger

1. Attest the enclave

Before submitting anything, the client verifies attestation first. The enclave is measured by PCR0 (SHA-384) — the environment binding is LAYRSV2_ENCLAVE_PCR0_SHA384. Verification uses expectedPcrs: { pcr0 } with allowExpired: false, so an expired attestation document is rejected.

The attestation flow is anti-replay by design. The public endpoint is:

GET /v1/attestation?nonce=<fresh-nonce>

A nonce query parameter is required — calling /v1/attestation without one returns ATTESTATION_NONCE_REQUIRED. The attestation document carries back a requestNonce (proving freshness) and a transportPublicKey (the key the client will seal orders to). Each market also advertises the measurement it is bound to: GET /v1/markets/{marketId} returns hiddenBook: true, an aggregateBucketMs value, and attestedPcr0Sha384 — the enclave measurement tied to that market.

Only if attestation verifies does the client proceed. This is the trust anchor for everything that follows: the client confirms it is talking to exactly the code it expects, running in a genuine enclave, before it shares any order.

2. Open a private session

The client opens a private session:

POST /v1/private/sessions

Sessions are signed and registered inside the enclave. Combined with the per-request rules — unexpired request, strictly increasing sequence number, valid signature — the session prevents replay and out-of-order execution.

3. Seal and submit the order

With a verified enclave and a session in hand, the client seals a signed order to the enclave's transportPublicKey (obtained from the attestation document) and submits it through the ciphertext-only relay:

POST /v1/private/relay

This relay is ciphertext-only. Plaintext order data never reaches an API container, a database, or a log. The host transports the sealed payload to the enclave over VSOCK, still encrypted.

4. Match privately inside the TEE

Inside the enclave, the matching engine runs deterministic price-time matching with self-trade prevention. Markets are binary — UP / DOWN / PUSH on a price boundary — and the engine handles complete-set mint/burn against one-to-one market collateral. Fees are applied as accounting inside the enclave: 0 bps for makers, 20 bps for takers. Every state transition is recorded in an encrypted, hash-chained journal that produces deterministic receipts.

Outwardly, the market exposes only aggregate depth (bucketed by aggregateBucketMs) and public receipts. The per-user order book stays hidden (hiddenBook: true).

5. Settle the netted batch on chain

Fills are settled to the chain in batches, not one order at a time. Settlement happens through batchSettle on the MatchSettlement contract, using the EIP-712 domain:

{ "name": "LayrsMatchSettlement", "version": "1", "chainId": 26514 }

A batch is a list of fills — each (marketId, buyer, seller, quantity, price, fee, nonce) — plus a deadline, signed by the enclave. What reaches the chain is the netted batch, not per-user orders. The chainId 26514 is Horizen Mainnet, where the production ZEN path currently runs.

6. Resolve with signed Pyth data

Markets resolve against a signed Pyth Pro feed. For each of the two boundaries — the opening boundary and the closing boundary — the oracle adapter collects exactly 25 authenticated samples at 200 ms spacing across the 5 seconds ending at the boundary, i.e. the window (T-5s, T]. Each sample must report at least 3 publishers and retains its signed EVM payload.

From the 25 samples at each boundary, the adapter computes the 13th sorted E8 price — the median of 25. The rule is straightforward:

Comparison	Outcome
closing median greater than opening median	UP
closing median less than opening median	DOWN
exact equality	PUSH

Resolution has no recovery deadline and no alternate source. If a valid Pyth window is missing, resolution pauses indefinitely rather than falling back to another feed. Binance is intentionally not a launch fallback. Resolved outcomes are readable at GET /v1/resolutions/{marketId}.

7. Payout

Once a market resolves, winnings are settled inside the enclave's private ledger. The 5% positive winning-profit fee is applied on a per-position cost basis — it is charged only on positive profit, not on principal.

Withdrawals follow the funding path: a credited balance produces an enclave-signed withdrawal authorization, which passes coordinator screening before the pool pays out. Withdrawal destinations are envelope-encrypted (KMS) as destination_ciphertext, so the destination address is never exposed in the clear.

Where funds live

Deposits and withdrawals are handled outside the matching path but still gated by the private ledger:

• Deposit: a user sends to a generated one-time deposit address; the backend sweeps it into the LayrsPool; the private ledger is credited only after pool-side finality — never on mere arrival at an externally owned account.
• Withdrawal: a credited balance yields an enclave-signed authorization, then coordinator screening, then a pool payout by the dedicated ledger signer.

Supported assets are USDC (Base, 6 decimals) and ZEN (Base 18 decimals / Horizen OFT 18 decimals). ZEN moves between Base and Horizen via Stargate / LayerZero OFT; ZEN is native on Base and an OFT on Horizen.

Durability: journal, snapshots, and rollback defense

The enclave's integrity does not depend on trusting the host with plaintext. State is protected by:

• An encrypted, hash-chained journal and deterministic receipts, so any tampering is detectable.
• AEAD-encrypted snapshots that capture the journal sequence / head and the state root. The enclave exports only these encrypted snapshots.
• Rollback defense: restore rejects corruption and rejects any snapshot older than an independently anchored minimum sequence. Receipts and journal records are archived to Object Lock storage, and checkpoints are anchored to a public audit rail before the accepted recovery floor advances.

The test suite exercises atomic ledger failure, price-time ordering, self-trade prevention, FOK behavior, journal tamper detection, collateralized trading, resolution fees, snapshot restore, and rollback rejection.

Putting it together

The end-to-end guarantee is: a client cryptographically verifies the enclave (PCR0 / /v1/attestation), opens a signed private session, and seals each order so only the attested code can read it. Matching, balances, and the book stay private inside the TEE. The chain receives only signed, netted batchSettle results, and markets resolve deterministically from signed Pyth medians. Privacy and verifiability come from the enclave boundary — not from trusting the operator or the host.