An architecture
of math, not
of trust.

The dominant payment networks of the last fifty years built their trust the same way: publish everything. Every cleared check, every interbank transfer, every stablecoin transaction sits in a ledger that anyone with credentials can read and that everyone with subpoena power eventually does. We treated this as the cost of having a working economy. It was not. It was the cost of not having a good enough cryptosystem.

Psy is what becomes possible when that cryptosystem finally arrives. Recursive zero-knowledge proofs over the Goldilocks field let us deliver a payment receipt that is simultaneously universally verifiable and completely private: an outsider can be sure your transfer was well-formed, that you had the balance, that the receiving user is registered, that the system invariants still hold — without learning who you are, who you paid, or how much.

The chain that runs underneath this promise has to be more than “Ethereum but private.” A private rollup that still pays for every block on a public host inherits the host's economics, latency, and censorship surface. Psy is an independent chain: its own validator set, its own consensus and execution layers, its own coordinator and realm processors. It bridges to Ethereum because Ethereum is where the world's liquidity sits — not because it needs Ethereum to be a chain.

We treat this as a literal restoration project: the right to transact privately is not a feature, it is a baseline that modern cryptography finally lets us put back where it belongs.

A Psy chain is composed of three classes of process, two bridge contracts on Ethereum, and one canonical configuration document distributed via a content-addressed page server. Each class has a single, sharply-scoped responsibility, and they communicate exclusively through three message buses: ScyllaDB for durable cold state, Redis for hot per-checkpoint state, and NATS JetStream for ordered job streams.

On the Ethereum side, two Ethereum contracts hold the chain's anchor: a Bridge that accepts Ethereum-side deposits and emits a Deposit event, and a StateManager that ingests recursive rollup proofs and emits a FinalizedBatch event when a new state-transition has been verified on-chain. Together they constitute the cryptographic settlement layer.

Off-chain, three Rust services co-operate per realm: a processor that sequences user requests into checkpoint-sized batches, an edge that serves JSON-RPC to wallets and indexers, and one or more workers that consume jobs off NATS and emit Plonky2 proofs. A single coordinator aggregates realm output and submits the rollup proof to Ethereum.

Every Psy chain is structured as three concentric layers: Coordinator, Realm, and Worker. Each layer has its own checkpoint clock, its own database namespace, and its own circuit manager. They are deliberately under-coupled: a misbehaving worker cannot freeze a realm, a stalled realm cannot freeze the coordinator, and the coordinator can produce empty checkpoints even when both realms have nothing to say.

The coordinator is the chain's clock. Its processor wakes on a 100 ms slot tick and, every sixtieth slot (i.e. every 6 s), opens a new checkpoint. It gathers whatever Global-User-Tree-Aggregate (GUTA) proofs, register- user proofs, and deploy-contract proofs the realms have delivered since the last checkpoint, recursively aggregates them into a single rollup state-transition proof, writes the new state root to durable storage, and prints a FinalizedBatch-ready bundle on the side.

Realms hold the per-user state. Every user is permanently assigned to exactly one realm by the high bits of their user_id. Realms run their own processor / edge / worker triad and produce state-transition proofs that the coordinator can absorb. The current production topology uses two realms (group_realm_height = 1); the protocol supports up to 128 (group_realm_height = 7).

Workers are stateless proving servers. They subscribe to NATS subjects for the realm or coordinator that hired them, pull jobs by queue_key, and stream completed proofs back. A worker holds its own copy of every circuit it might be asked to prove — typically several gigabytes of pre-built circuit data per process — and is horizontally scalable: add more workers, the chain proves faster.

Psy proves over Plonky2, Polygon Zero's FRI-based proof system, instantiated on the Goldilocks field (p = 2⁶⁴ − 2³² + 1) and the Poseidon hash with rate-8 / capacity-4 (12 field elements wide). The choice is not aesthetic. Goldilocks multiplies in two CPU cycles. Poseidon over Goldilocks gives ≈250 ns per permutation on commodity x86. Together they let a wallet on a laptop generate a privacy-preserving transaction proof in 600 ms–2 s, which is the only number that ever mattered.

Plonky2's killer feature is recursive verification at native speed. A circuit that verifies another Plonky2 proof is itself a Plonky2 circuit of bounded size — about 2¹⁶ gates — so the work to aggregate a thousand per-user-tx proofs into a single rollup proof is the same as the work to aggregate two. We exploit this aggressively. The proof a coordinator submits to Ethereum is a recursive tower:

1. per-user end-cap proofs (one per signing event)
2. per-realm GUTA aggregate (one per checkpoint per realm)
3. cross-realm coordinator aggregate (one per checkpoint)
4. checkpoint state-transition proof (one per checkpoint)
5. Ethereum-friendly Groth16 wrapper (one per submission)

The final Groth16 wrap is the only step that touches Ethereum. Verifying a Groth16 proof on Ethereum costs ≈250 k gas regardless of how many user transactions hid behind it. Today a checkpoint settles a few hundred user actions per wrap. Tomorrow it will settle a few hundred thousand. The gas line is flat.

Psy state is organised as a four-level tree-of-trees, where every level is a Poseidon-Goldilocks Merkle tree of fixed depth. The chain's entire global root is a single 32-byte digest. Any merkle path through the structure has a constant number of siblings, and every sibling is a single Goldilocks-quartet (32 bytes). This bounded shape is what lets a wallet prove inclusion in 30 ms on a phone.

• Global state root. The root of the global user tree. Height = 32. Each leaf is the realm-user-tree-cap of the realm that owns that user_id band.
• Realm user tree. Height = 20. Each leaf is a single user's “user-contract-tree” cap. Realms shard along the high bits of user_id.
• User contract tree. Per-user index of every contract that user has touched. Height = 32. Each leaf is the contract-state-tree root of that user under that contract.
• Contract state tree. Height = 32. Each leaf is a 32-byte slot. Contracts declare their state layout symbolically (sub_slot_index: 6 etc.); the compiler maps each symbolic slot to a leaf position.

In addition to the per-user state, the chain carries two global incremental Merkle trees (IMTs) anchored on Ethereum:

• Deposit tree. Append-only. Every Ethereum-side Deposit event becomes a leaf Poseidon(recipient, amount, l2_token_contract_id, shield_address, secret) . Psy users prove inclusion to claim.
• Withdrawal tree. Append-only. Each Psy-side withdrawal initiation appends a leaf; the coordinator submits the new tree root in the next FinalizedBatch, and the user redeems on Ethereum with a merkle proof against that root.

A Psy user is identified by a single u64: user_id. The number is not arbitrary — its bit layout encodes which realm owns the user and which sub-tree position the user occupies inside that realm. The layout is set by the chain's configured UserIdBitsStrategy, of which two are in production:

• Strategy 4 — 128-realm fan-out. group_realm_height = 7, users_per_realm = 2²⁰, total addressable users = 2²⁷ ≈ 134 M. Used by the earlier wide-fan-out deployment.
• Strategy 5 — 2-realm minimal. group_realm_height = 1, users_per_realm = 2²⁰, total addressable users = 2²¹ ≈ 2 M. Current production topology — gives much cheaper recursive aggregation while the network ramps. Strategy switches are forward-compatible: future hard-forks can promote to Strategy 4 without invalidating user_id space, only reassigning realms.

The realm a user belongs to is user_id / users_per_realm (integer division). The user's position inside the realm user tree is user_id mod users_per_realm. Both numbers are public — there is no privacy gain in hiding which realm a user lives in; the privacy is in what the user does there.

A crucial implication is that realm-side circuits are not interchangeable across strategies. A psy-sdk WASM built against Strategy 4 will produce proofs whose merkle-path arity disagrees with the Strategy 5 state tree, and the realm will reject them. Wallet builds are therefore strategy-tagged, and the bridge ships strategy-specific artifacts in psy-config-stg/config.json.

A Psy “block” is a tuple: (checkpoint id, rollup state-transition proof, aggregate realm caps). The coordinator's runner loop fires every 6 seconds and walks the pipeline. Below is the actual structure of coordinator/processor/core/process_block.rs:

1. get_results_from_gatherers() — pull each realm's submitted GUTA, register-user, and deploy-contract job IDs that landed since the last checkpoint.
2. get_root_job_ids() — if every job slot holds a dummy circuit type (GUTANoChange, DummyAppendUserRegistrationTreeAggregate, DummyBatchDeployContractsAggregate), return Ok(None); the chain is idle this tick.
3. publish_jobs(level=0) — write the per-realm proof jobs to NATS for workers to pick up.
4. plan_genesis_checkpoint_state_transition_proof()— only on checkpoint_id == 0.
5. plan_agg_guta_register_users_deploy_contracts_job()— schedule the recursive aggregation that will combine the per-realm proofs.
6. wait_for_jobs_completion() — block until the level-0 proofs are back.
7. publish_jobs(level=1..) — push the next recursion layer.
8. publish_and_wait_for_job_completion(agg_job)— finalise the cross-realm aggregate.
9. plan_checkpoint_state_transition() — fold the realm caps into a new global root + Plonky2 state- transition proof.
10. commit_state() — persist the new root and proof; print Committed new coordinator block with checkpoint_id = N.

The Psy bridge is a pair of one-way pipes: an ingress that pulls Ethereum ERC-20 balances into Psy as shielded notes, and an egress that returns Psy balances to Ethereum ERC-20s. Both directions are non-custodial in the cryptographic sense — the bridge contract holds custody of tokens but cannot move them without a valid Plonky2 proof of Psy-side intent. The two directions ride two independent Merkle trees.

Ingress — Ethereum → Psy.The user calls Bridge.deposit(token, amount, recipient_user_id, secret) on Ethereum. The contract pulls the ERC-20 via an approve+transferFrom, hashes Poseidon(recipient, amount, l2_token_contract_id, shield_address, secret) into a leaf, appends it to the deposit IMT, and emits a Deposit event. The off-chain indexer ingests the event, the the relayer folds the new deposit-tree-root into the next coordinator checkpoint, and from that checkpoint onward the recipient can run claim_deposit, proving inclusion of their leaf in the published root and crediting themselves the amount privately.

Egress — Psy → Ethereum.The user runs initiate_withdraw(token, amount, l1_recipient) on Psy. This burns the Psy-side balance and appends a leaf Poseidon(l1_recipient, amount, l2_token_contract_id, nonce) to the withdrawal IMT. The next coordinator checkpoint that lands on Ethereum carries the new withdrawal-tree-root. The user (or anyone, since the Ethereum-side transaction has no authority requirement beyond merkle inclusion) calls StateManager.completeWithdrawal(merkleProof, leaf), the contract verifies inclusion against the latest finalized root, and the ERC-20 is released to l1_recipient.

The whole thing has exactly one trust assumption: that the Ethereum's Groth16 verifier accepts only proofs corresponding to honestly-computed Psy state transitions. As soon as that proof verifies, all downstream tree roots are consensus-pinned, and there is no “optimistic challenge window.” Withdrawals are instant in the sense that there is no fraud-proof delay; the only delay is the proving time of the checkpoint that includes them, currently ≈90 s.

Privacy on Psy is layered. A user can choose to operate publicly (simple_transfer / simple_claim) at lowest proving cost, or to operate privately (private_transfer, claim_deposit with shield-address) at the cost of a slightly larger circuit. The same chain runs both. The same user can mix and match per-payment. Everything below is implemented in production today.

Shielded notes. A private balance is a set of notes, each note being a Poseidon commitment to (value, asset, owner_secret, nonce). The note tree is per-user. To spend a note, the sender publishes its nullifier — Poseidon(owner_secret, nonce) — and proves in zero-knowledge that the nullifier corresponds to a committed note inside the global note tree. The receiver receives one or more new notes whose commitments are appended to their own note tree.

Sign types. Authentication is plural. Psy ships five circuit families that authorize a tx, selectable per-key:

• ZKSign — Poseidon-Goldilocks Schnorr. Default for end-user wallets. Smallest circuit.
• SECP256K1Sign — for compatibility with Ethereum keys (think: log in with MetaMask, spend on Psy).
• SoftwareDefinedDPNSign, SoftwareDefinedPlonky2Sign — escape hatches for application-specific signing rules (multisig, social recovery, time-locks).
• SDKKeySign — “allow-method” delegated keys. The signing key is provably restricted to specific (contract_id, method_id) pairs and a per-key transaction count. The fingerprint baked into the circuit commits to those constraints. Used by the public faucet (No. 10).

The allow-method circuit. An SDK-key fingerprint is the Poseidon hash of the circuit that enforces this key can sign only these (contract, method) pairs and at most N times. The wallet locally re-builds that circuit (via register_sdk_key_circuit(contract_ids[], method_ids[], expected_tx_count)), gets the same fingerprint, and uses it to import its private key under the SDK-key sign type. This lets a backend hand out short-lived, narrowly-scoped signing keys without ever holding user funds.

The Psy testnet faucet is a small but instructive cryptosystem in its own right. It demonstrates two things at once: (1) that an in-browser WASM signer can drive arbitrary contract calls without a backend, and (2) that the SDK-key sign type can replace custodial key-management for a public throughput surface.

Topology. Ten operator wallets are bundled into the bridge frontend, each pre-funded with 1 000 000 PSY. All ten share the same circuit fingerprint — they were registered against one register_sdk_key_circuit([faucet_contract_id], [faucet_method_id], expected_tx_count=3) call — which means a single in-tab WASM session loads one circuit and uses it to sign for any of the ten.

Rotation. When a user clicks “Claim,” the bridge picks operator recipient_user_id mod 10. Same recipient always hits the same operator. This stable, per-recipient pinning is what makes the faucet contract's per-pair rate limit work: the contract tracks “PSY sent from operator i to recipient j in the last 120 checkpoints”, caps it at 1 000 PSY, and because each recipient maps to exactly one operator, the cap is enforced naturally.

Honest-client caveat. Because the ten private keys are bundled in the browser, a motivated user can extract them and call the faucet from all ten operators simultaneously, multiplying the cap 10×. Defence is contract-side: aggregate the cap on the recipient side rather than per-pair, or move the signing to a server that gates by recipient regardless of which operator key signed. For a testnet faucet this is acceptable; for any production economy it would not be.

Five user-facing surfaces sit on top of the chain. Each is independently deployable, each speaks the same JSON-RPC, and each ships its own copy of the Plonky2 WASM prover so it can construct proofs without round- tripping a server.

psy-walletChrome MV3 extension · in-tab prover · ZK + SDK-key

Holds user keys locally. Signs every tx with a Plonky2 proof generated inside the extension's background page via the bundled WASM. No private key ever leaves the extension; the dapp only sees signed payloads.

psy-sdkTypeScript + Rust → WASM · the lingua franca

The Rust crate psy-rust-sdk compiled to WASM, plus a TypeScript wrapper exposing createMemoryWalletProvider, register_sdk_key_circuit, deposit / withdraw helpers, and full local proving.

psy-bridge / privacy-bridge demoThe reference dapp

Lets a user deposit USDT or ETH from Ethereum and claim it as a shielded balance on Psy, send privately, withdraw back. Reference for every other dapp.

psy-explorerVite + React block explorer

Indexed entirely off Ethereum FinalizedBatch events plus realm RPC fan-out. Two views: per-checkpoint, per-user. Shows realm 0/1 lag, deposit / withdrawal queues, contract leaderboard.

psy-ideBrowser IDE for Psy-lang contracts

Edits, compiles (via the dargo WASM compiler), tests in a sandboxed devnet, and deploys to the connected network — all in the browser, no toolchain.

Psy is built for a world where the dominant payer is not a human. In ten years, the vast majority of micropayments originated on this planet will be issued by autonomous software acting on behalf of humans — agents purchasing inference, agents purchasing data, agents reconciling expenses with other agents. The defining property of that world is not throughput. It is privacy by default, because the alternative is a panopticon in which every model on Earth can watch every model on Earth spend money, and the strategic implications of that visibility are ruinous.

The architectural commitments below are what the next eighteen months of Psy look like, in order of landed:

• Cached identity proofs for idle blocks — let the coordinator re-use a pre-proved no-change proof across empty checkpoints instead of re-proving the same tautology each tick. Expected effect: idle-block cadence drops from the current ~90 s into the single- digit-second range.
• Realm fan-out to 128 via Strategy 4 promotion. Each realm runs an independent proving worker pool; aggregation at the coordinator remains O(log N) recursive. Throughput scales near-linearly with number of realms.
• Multi-coordinator BFT — today one coordinator owns the checkpoint clock. The next generation pushes coordinator election to a BFT committee, removing the single-operator censorship surface. Internally this is “coordinator becomes a contract.”
• Universal SDK-key marketplace. Today SDK-keys are used inside one product (the faucet); the primitive generalises to a public market of “agents holding allow-method keys for specific dapps.” A user can mint a key that lets an AI model spend up to ¥100 of stable on inference at a specific provider, for a week, and revoke it by burning the corresponding fingerprint nullifier.
• Compliance bridges. Public-input selective disclosure: a user can choose to reveal, under a specific regulatory key, the recipient or amount of a single transaction, without breaking privacy for any other transaction. Closes the “cannot satisfy a subpoena” objection without re-introducing surveillance by default.
• Sub-millisecond settlement on Ethereum. Migrate the Groth16 wrap to a verifier deployed on EthDA-class chains where the calldata cost is ≈10× lower. Final goal: a Psy checkpoint costs less to anchor than a single Ethereum transfer.

The closing claim of this treatise is the same as its opening: the right to transact privately is a baseline, not a feature. Math has finally made it cheap. Psy is the engineering vehicle that puts it back where it belongs.