feat(examples): confidential dark-pool batch-auction example

[clawdbot-glitch003]

What

A new flagship example: examples/dark-pool/ — a confidential exchange where orders are submitted encrypted, matched blind inside the TEE at a single uniform clearing price, and settled on-chain. Order side/price/quantity never exist in plaintext anywhere outside the enclave, including in the database that stores them.

This is the first example to use Lit's encryption primitive and to hold confidential state — the existing four are all compute + signing. It wires together encrypt + confidential-compute + sign in one flow.

Honest trust framing

Not "more private than an MPC dark pool" — a different trade: hardware privacy (the TEE sees the book but doesn't leak it) for radically less complexity, async batching, and confidential state on a hobby-tier Postgres. Pre-trade privacy (no front-running of resting orders); post-trade fills are public on-chain, like real dark pools. This is stated plainly in the README.

Design

• Sealed-bid batch auction, not a continuous order book — removes time-priority front-running and the stateless-sequencing problem; matches the whole batch in one atomic enclave run (the CoW/Penumbra approach).
• Storage: orders are ciphertext in Neon (queried over its SQL-over-HTTP endpoint, since a Lit Action can only fetch). The DB connection string is itself encrypted to the vault PKP and decrypted only inside the enclave.
• Settlement: DarkPoolSettlement pins the matchEpoch action's CID-derived address as matcher; edit the action by a byte and the contract stops trusting it.

Contents

• contracts/DarkPoolSettlement.sol + TestToken.sol — escrow, signed-fill settlement, per-epoch replay guard, conservation invariant, cross-pool/chain digest binding
• action/encryptOrder.js, action/matchEpoch.js — seal+store; decrypt-batch + uniform-price auction (conservation-safe rationing) + sign
• scripts/setup.js, submitOrder.js, runEpoch.js, deploy.js, lit.js
• README.md, schema.sql, and an examples/README.md row

Tests & live validation

• npx hardhat test → 12 passing (6 contract: happy path, wrong-signer, replay, under-collateralised, conservation, cross-pool replay; 6 auction: cross, rounding-dust conservation, no-cross, volume-max + tie-break, fuzz conservation, determinism)
• Validated live end-to-end (Lit API + Neon + Base Sepolia): orders sealed as ciphertext, matched in-enclave at clearing price 100, signature recovers to the pinned matcher, epoch settled on-chain with balances moving correctly. A cleartext scan of the stored rows for buy/sell/limitPrice returns 0.

Full build log: plans/dark-pool-example.md.

Notes for review

• Uses a wildcard action group (matching the sibling examples); the signing pin is contract-enforced regardless, and pinning the CIDs is documented as the first "going further" item.
• examples/dark-pool/node_modules, .env, and key files are gitignored.

🤖 Generated with Claude Code