A bilingual, deeply technical specification of Psy Protocol — realms, coordinators, state machine, runtime, networking, SDK, AI-native infrastructure, and the civilization-scale coordination layer that emerges from them. Less marketing, more architecture; less RFC-than-thou, more readable.
A protocol used to be a way for two computers to agree on a packet format. The protocols of the next decade are something larger: shared state, programmable memory, persistent identity, and autonomous coordination among humans and machines. Psy is one such substrate — not "a blockchain," not "a crypto network," but a coordination layer that future internet civilizations could plausibly run on. This specification documents how it works, end to end.
A user signs a transaction in the wallet. Eight components later, that transaction is a piece of provably-shared state visible to every other participant. Each component is replaceable; the boundaries between them are the spec. Click any block to read it.
A realm is the protocol's unit of locality. Every account, contract, and balance lives inside exactly one realm; cross-realm communication is explicit and settled at the bridge. Realms isolate failures, parallelise execution, and let the protocol scale without forcing every account into the same global queue.
// realm message envelope (simplified) struct RealmMessage { src_realm: u32, // e.g. 0 dst_realm: u32, // e.g. 1 seq: u64, payload: bytes, commitment: poseidon256, // inclusion-provable }
The coordinator service (default port 5174) accepts signed transactions from clients, orders them, batches them into blocks, hands them to the realm engine for execution, and forwards the resulting state-root commitment to the validator set. It is not the only honest party in the system — but it is the most latency-sensitive one.
Psy state is a Merkle tree of accounts and contract storage, hashed with Poseidon (Goldilocks field). A block is a list of signed transactions; applying a block deterministically rewrites a subtree of state. Validators do not re-execute the block — they verify a Plonky2 proof that the new state root follows from the old one under the protocol's transition function.
Psy contracts are not EVM bytecode. Both the language semantics and the runtime are co-designed with the proving system: every primitive must be cheap to enforce as a Plonky2 constraint, and storage is laid out for efficient Merkle proofs. The trade-off: smaller surface area, larger throughput per proof, and no on-chain Solidity. The table below names where Psy diverges from a typical EVM-like chain.
Psy nodes form a libp2p-flavoured peer fabric carrying four classes of message: tx, block, vote, and proof. The protocol does not assume any node is honest; it does assume that some bounded fraction is, and that the fabric routes messages within a few hops. Below: the four message types, with their headers and propagation rules.
The full RPC surface is hundreds of methods; the eight below are the ones a developer reads first. Pick any to see the shape of the request, the response, and a synthetic trial run. The "send" button is local-only — it does not contact any server; it constructs a deterministic response from a small in-browser stub so you can see the format without authentication.
When agents transact and remember on each other's behalf, the protocol underneath them stops being optional infrastructure and starts being the constitution. Psy's primitives — persistent identity, shared state, low-latency settlement, decentralised memory — are designed to be useful to autonomous agents specifically, not just to humans pretending to be agents.
Headline figures from the v0.9 reference implementation under the standard benchmark workload. The numbers are illustrative and will change with realm count and prover hardware, but the relative shape is informative.
A protocol is a piece of social engineering wearing technical clothing. Below: six classes of institution that look feasible if a substrate like Psy reaches civilization scale. None is inevitable; each is an open construction project.
Pick a value for each of six dimensions — workload, realm count, prover capacity, network latency, validator participation, and AI-agent share. The modeler pattern-matches your selection against an internal table and writes a short outlook on the protocol's expected behaviour. It is local-only, deterministic, and not a real benchmark.