Protocol overview

Kasumi is an encrypted frequent batch auction. Trading is cut into epochs. During an epoch, clients submit orders that are signed and encrypted on their own machine. When the epoch closes, the set of ciphertexts is fixed by a Merkle root. Only after that can the orders be decrypted, matched at one clearing price per market, and settled.

The guarantee is pre-trade intent privacy: nobody, including the relay operator, can read an order before its epoch's decryption time. After settlement everything is public. See THREAT_MODEL.md for the exact limits.

This document describes what is implemented. Where something is designed but not built it says so.

	Sealed	Committed	Decrypted	Matched	Settled
Ciphertext and commitment	public	public	public	public	public
Number of orders in the batch	public	public	public	public	public
Merkle root onchain	hidden	public	public	public	public
Market, side, size, limit, wallet	hidden	hidden	public	public	public
Clearing price and fills	hidden	hidden	hidden	public	public
Token transfers	hidden	hidden	hidden	hidden	public

What is public at each state. Before decryption nothing about an order's content is readable by anyone. The relay additionally sees IP address and timing at submission.

1. Roles#

Role	What it does	Where
Client	Builds, signs and encrypts an order locally. Sends only the envelope. Verifies the receipt and inclusion.	`packages/sdk/src/client.ts`
Relay	Accepts envelopes, rate-limits, assigns a sequence, signs an inclusion receipt, builds the epoch Merkle tree, publishes the root. Cannot read or alter orders.	`apps/web/src/server/engine.ts`
Epoch manager	Epoch schedule, batch commitment, state machine.	`contracts/src/KasumiEpochManager.sol`
Matcher	Decrypts the committed batch, validates, runs the auction, proposes fills.	`packages/sdk/src/pipeline.ts`, `matcher/` (Rust), `packages/sdk/src/matcher.ts` (reference)
Settlement	Re-checks every user constraint from the signed order and moves tokens.	`contracts/src/KasumiSettlement.sol`
Oracle	Reference price used as a safety bound and as the clearing-price tie-break.	`contracts/src/KasumiChainlinkOracle.sol`

The matcher proposes. The settlement contract enforces. No user constraint relies on the matcher being honest.

The contracts are deployed on Robinhood Chain mainnet (deployments/robinhood-mainnet.json). The web relay in apps/web plays the relay role against those contracts and, by default, the matcher role as well: it uses packages/operator to send commit after the cutoff and postMatch and settleMarket after the drand round. The operator can also run as a separate process. DEPLOYMENT.md describes the deployment.

9. More than one relay#

KasumiEpochManager keeps a set of allowed relays (isRelay). Receipts name the relay that signed them, and verifyInclusion takes the expected relay as a parameter. In v1 a single commitment per epoch is accepted, from whichever allowed relay commits first. Aggregating commitments from several relays into one epoch is not implemented in v1.