Skip to content
Docs / Architecture

Inside Ordeo

The parts of Ordeo and how they work together

Ordeo is a public ERC-20, a handful of fixed contracts that hold it behind encrypted notes, and a few off-chain helpers that anyone can replace. This page lists each part and walks through the main flows.

On this page

Components

Five contracts and four libraries make up the on-chain side. None of them is deployed yet; the descriptions below are of the code in contracts/src. No contract has an owner, an admin key, a pause switch or an upgrade path. Every parameter is set once in a constructor.

PartKindRun byCapabilities
OrdeoShroudContractNobody (no owner)Holds ORDEO and ETH behind notes. Accepts shields and spends that carry a valid proof. Keeps the vault that makes ORDEO notes earn.
OrdeoAttestorContract + 2 librariesNobodySays yes or no to a proof for the ten public inputs the pool hands it. Generated from the circuit; cannot be swapped.
OrdeoSponge2Library (with OrdeoSponge3)NobodyPoseidon hashing for the tree and for note commitments.
OrdeoKeyLedgerContractNobody; each address edits only its own entryMaps an ordinary 0x address to the note keys it published, so others can pay it privately.
OrdeoYieldSplitContractNobody; two fixed payout addressesReceives the Pons creator fee and the pool's ETH fees, splits them 50/50 between the team and the holders' harvester.
OrdeoTradeDeskContractNobodyBuys ORDEO on its Pons market straight into a note or into the vault, and lands private sales.
Browser appOff-chain, on your deviceYouDerives your note keys, finds your notes, builds and proves spends. Your keys stay inside the page.
Leaf indexOff-chain, site serverThe site operatorServes the public list of commitments and encrypted notes. Cannot forge one, because the app compares the root it rebuilds with the pool's.
BundlerOff-chain serviceAnyone; the site lists the ones it knowsSubmits a proof that names it, for a flat fee taken from your notes. Can submit or refuse, nothing else.
HarvesterOff-chain serviceThe holder of the splitter's holders keySweeps fees, spends the holders' half on ORDEO as a donation to the vault, tops up bundler gas.
Pons curve, v4 pool, meme hookThird-party contractsPonsThe market for ORDEO. Takes a fee on each trade and records the creator share in the splitter's favour.

Flow: buying in the app

Buying in the app takes one transaction and leaves you with a fresh private note.

  1. 01

    Prepare the note

    The app picks a random blinding, computes ownerHash = Poseidon(pk, blinding) for your key, and encrypts the blinding to your viewing key.

  2. 02

    Call the router

    Your wallet calls buy(ownerHash, minTokensOut, encryptedNote) on OrdeoTradeDesk with the ETH you are spending. The minimum output is required; a buy without one reverts.

  3. 03

    Trade on Pons

    Until graduation the router buys from the curve on Pons; afterwards it buys in the Pons-hooked Uniswap v4 pool. Any ETH the curve could not use comes back to you within that transaction.

  4. 04

    Shield

    The router passes everything it bought to OrdeoShroud.shield. The pool takes the shield fee, mints vault shares and computes the commitment itself from the amount it received.

  5. 05

    Find the note

    The ciphertext carries value 0, because only the pool knows the share count. Your app reads the value from the Shielded event that the same transaction emits.

Visible on chain: your wallet, the ETH paid, the ORDEO bought, and that it went into a new note. See Buy for the user side.

Flow: a private send through a bundler

  1. 01

    Ask for a quote

    The app reads GET /info from a bundler: its address and the flat fee it charges right now.

  2. 02

    Build the spend

    The app picks one or two of your notes and builds exactly two outputs: the payment to the recipient’s key and the change back to you. A missing input or output is a zero-value filler. The bundler’s fee is the exit value; the recipient field is empty.

  3. 03

    Prove

    A web worker proves the spend in your browser. The proof binds the bundler’s address, its fee and both ciphertexts.

  4. 04

    Relay

    The app posts the calldata to POST /relay. The bundler checks it, dry-runs it and sends transact from its own wallet.

  5. 05

    Settle

    The pool verifies the proof, marks two nullifiers spent, appends two commitments and pays the exit value to the bundler. Only the bundler named in the proof may send it.

Flow: a private sale through the router

  1. 01

    Write the terms

    The app encodes the payout address, the minimum ETH, a deadline, the bundler that may submit it and the bundler’s ORDEO fee. These terms take the place of the second encrypted output.

  2. 02

    Prove an unshield to the router

    The proof is an ordinary unshield whose recipient and relayer are both the router, so the pool accepts it only through OrdeoTradeDesk.sell.

  3. 03

    Submit

    The bundler calls sell. The router unshields to itself, pays the bundler its fee, sells the rest on the live Pons venue and pays the resulting ETH to the payout address.

  4. 04

    Or revert

    If the price moved and the ETH out is below the minimum, the whole transaction reverts and the notes stay unspent.

Flow: the harvest

About every four hours, at a time shifted at random by up to 40%, the harvester runs one round:

  1. sweepEthFees() on the pool when ETH fees are waiting, which sends them to the splitter.
  2. distribute() on the splitter: claim the Pons creator fees held in escrow by Pons, split 50/50, pay both sides.
  3. Top up the bundler’s wallet to 0.02 ETH when it is below 0.005 ETH.
  4. Buy ORDEO with the rest through buyAndDonate, in batches of at most 0.02 ETH, which donates every token to the vault.

The details, and why this is an operated service and not an open function, are on The vault and Threat model.

No bundler required

The bundler is a convenience for privacy, never a requirement for your funds. Each of these works from your own wallet:

  • Shielding public ORDEO or ETH, and buying through the router. Neither needs a proof.
  • Registering your note keys in the key registry.
  • Any spend with no relayer fee. A transact with zero exit value, or an unshield with zero relayer fee, can be sent by any address. Your wallet pays gas in ETH and shows up as the sender.
  • A sale whose terms name no submitter (anyone may land it) or name your own address.
  • Every fee step: sweepEthFees, collect, split, release, distribute and sweepPons are open to any caller, and anyone may call buyAndDonate with their own ETH.