A condensed tour of how Nyx keeps order intent private without giving up on-chain auditability. Source-of-truth lives in docs/ARCHITECTURE.md ,this page is the visual map.
Anchor 0.32 vault program holds the depth-20 incremental Poseidon Merkle tree, 32-root ring buffer, TEE pubkey, and protocol-fee config. Withdrawals go through an on-chain Groth16 verifier (alt_bn128 syscall). The matching engine program owns the per-market PDAs.
vaultmatching_enginegroth16-solanaMagicBlock Ephemeral Rollup hosts the delegated PendingOrder PDAs. submit_order is signed by the user's seed-derived trading key and lives only in the rollup. run_batch executes uniform-clearing-price match with a Pyth circuit breaker and writes BatchResults.
PendingOrdersubmit_orderrun_batch@nyx/sdk hand-codes every Anchor instruction (no IDL parser at runtime). snarkjs runs in a Web Worker for VALID_WALLET_CREATE and VALID_SPEND. Key chain: Phantom signature → master seed → spending / viewing / trading keys.
@nyx/sdksnarkjsdarkpool-cryptoNyx hides individual order intent. Aggregate match data (clearing price, total matched volume, the two consumed note commitments) is public — that's by design, not an oversight.
| Object | L1 visible? | Notes |
|---|---|---|
| Order side / price / amount | Hidden | Stays in the ER until run_batch matches |
| Order's collateral note commitment | Hidden | Same — only inside the ER |
| User's trading-key signature on submit_order | Hidden | The whole submit tx lives in the ER |
| note_commitment of the deposit note | Public | Public on vault::deposit (always was) |
| Deposit amount / mint | Public | SPL transfer is on L1 |
| Match clearing price + matched volume | Public | Surfaces in BatchResults after commit |
| Settlement note commitments (note_c, note_d, note_fee) | Public | TEE appends them in tee_forced_settle |
| Withdrawal amount + recipient ATA | Public | SPL transfer-out is on L1 |
The hot-path tx for users is step 5 — submit_order on the ER. The other steps are mostly one-time per user / per market.
| # | Cluster | Instruction | Signer | Privacy property |
|---|---|---|---|---|
| 1 | L1 | vault::create_wallet (VALID_WALLET_CREATE) | user payer | links user_commitment to a Solana payer; identity-only |
| 2 | L1 | vault::deposit | user payer | reveals deposit amount + mint (SPL transfer) |
| 3a | L1 | matching_engine::init_pending_order_slot | user trading_key | empty PDA, zero order intent |
| 3b | L1 | matching_engine::delegate_pending_order | funder + user trading_key | hand slot to ER validator |
| 5 | ER | matching_engine::submit_order | user trading_key | HIDDEN — order intent never on L1 |
| 6 | ER | matching_engine::run_batch | TEE / operator | match all delegated slots in the rollup |
| 7 | ER | matching_engine::undelegate_market | TEE / operator | commits BatchResults back to L1 |
| 9a | L1 | vault::lock_note(note_a) + lock_note(note_b) | TEE | references commitments already public from deposit |
| 9b | L1 | Ed25519 precompile + vault::tee_forced_settle | TEE | atomic note_a/b consume + note_c/d/fee append |
| 10 | L1 | vault::withdraw (VALID_SPEND) | recipient | spends a note, reveals amount + mint + recipient ATA |
Standard, well-audited primitives only. The on-chain Groth16 verifier is groth16-solana v0.2.0; the Poseidon implementation is light-protocol's reference (BN254 Fr).
Connect a Phantom wallet on Solana devnet and run the full flow — identity derivation, shielded deposit, ER-private order, TEE settlement, and proof-backed withdraw. Every receipt is an explorer link.