Glossary
Terminology and definitions used throughout Kaizen Core.
Core Concepts
| Term | Description |
|---|---|
| Box | Thesis type observing price range over entire time window. User wins if price stays within range. |
| Line | Thesis type checking price only at a specific point in time (future support). |
| RFQ | Request for Quote - the thesis flow where users request quotes from solvers. |
| Solver | Market maker that provides quotes and takes opposite positions to users. |
| Challenge Window | Time period after observation where settlement can occur. Settler service monitors and settles during this time. |
| Breach | State where price exits the specified range. |
| OI | Open Interest - total bet amount of open positions in a market. |
| Ring Buffer | Fixed-size circular buffer for oracle prices, overwrites oldest data. |
| JMT | Jellyfish Merkle Tree - efficient merkle tree implementation from Aptos. |
| STF | State Transition Function - pure function that transforms state given a block. |
| DA | Data Availability layer for submitting finalized blocks. |
| Checkpoint | Periodic operation (every 100ms) that commits state, updates oracle, and creates block. |
| Streaming Execution | Execution model where transactions execute immediately, not in batches. |
Thesis Lifecycle
| State | Description |
|---|---|
| Created | Thesis submitted, waiting for start time. |
| Active | Within observation period, monitoring for breaches. |
| InChallengeWindow | Observation ended, in settlement window. |
| SettledUserWin | User won - price stayed in range. |
| SettledSolverWin | Solver won - breach was proven. |
| Cancelled | Thesis cancelled before start. |
Node Types
| Type | Description |
|---|---|
| Write Node | Sequencer that produces blocks and executes transactions. Single instance. |
| Read Node | Replica that syncs from write node, serves queries. Horizontally scalable. |
| Oracle Service | External service that provides price feeds from exchanges. |
| Settler | External service that monitors theses and submits settlement transactions. |
Transaction Types
Account Operations
| Type | Description |
|---|---|
| Transfer | Move balance between accounts within Kaizen. |
| NominateApiWallet | Register a delegated API wallet for trading. |
| RevokeApiWallet | Remove an API wallet. |
Bridge Operations
| Type | Description |
|---|---|
| Deposit | Credit funds from external chain deposit (Relayer only). |
| Withdraw | Request withdrawal to external chain. |
| ProcessWithdrawal | Mark withdrawal as completed (Relayer only). |
RFQ Operations
| Type | Description |
|---|---|
| RfqSubmit | Create new prediction thesis with solver quote. |
| RfqSettle | Finalize thesis after settlement window. |
Oracle Operations
| Type | Description |
|---|---|
| OracleFeed | Submit price data (Feeder only, deprecated - now uses pull model). |
| OracleBackfill | Backfill historical price data (Admin only). |
| SystemSettle | Settlement transaction submitted by Settler service. Settles RFQ theses. |
Admin Operations
| Type | Description |
|---|---|
| MarketUpdate | Create or update market configuration. |
| SetUserLimits | Set per-user trading limits. |
| SetBlacklist | Add/remove address from blacklist. |
| SetSystemPause | Pause/unpause entire system. |
Permissions
| Role | Description | Allowed Operations |
|---|---|---|
| User | Normal user | Trade, transfer, API wallets |
| Relayer | Bridge relayer | Deposit, ProcessWithdrawal |
| Feeder | Oracle feeder | OracleFeed |
| Admin | Administrator | All admin operations |
Technical Terms
Cryptography
| Term | Description |
|---|---|
| EIP-712 | Ethereum typed structured data signing standard. |
| secp256k1 | Elliptic curve used for signatures (same as Ethereum). |
| keccak256 | Hash function used for addresses and signatures. |
| ECDSA | Elliptic Curve Digital Signature Algorithm. |
State Management
| Term | Description |
|---|---|
| State Root | Merkle root hash of entire state at a block height. |
| Version | Sequential number for state snapshots (same as block height). |
| Snapshot | Full state dump at a specific version for bootstrapping. |
| Pruning | Removing old state versions to save storage. |
| Event Sourcing | Architecture where events are the source of truth for queryable state. |
| WAL | Write-Ahead Log - durable append-only log for crash recovery. |
| Indexer | Service that stores events to PostgreSQL for fast queries. |
Blockchain
| Term | Description |
|---|---|
| Block Height | Sequential block number (1, 2, 3, ...). |
| Timestamp | Transaction timestamp used for replay protection (Hyperliquid-style). |
| Mempool | Pool of pending transactions (used in batch mode, not streaming). |
| Column Family | RocksDB logical data partition for different data types. |
Networking
| Term | Description |
|---|---|
| JSON-RPC | Remote procedure call protocol used for API. |
| WebSocket | Full-duplex connection for real-time subscriptions. |
| gRPC | High-performance RPC for block sync between nodes. |
Crate Architecture
| Crate | Purpose |
|---|---|
| kaizen-core | Core traits and abstractions (Payload, StateReader, etc.) |
| kaizen-types | Common type definitions (Address, Block, RfqThesis, etc.) |
| kaizen-tx | Transaction structures and EIP-712 encoding |
| kaizen-auth | Signature verification and API wallet authorization |
| kaizen-state | RocksDB + JMT state management |
| kaizen-engine | Business logic and modular STF executors |
| kaizen-app | Server, RPC, WebSocket, and node runtime |
| kaizen-metrics | Prometheus and Sentry integration |
| kaizen-macros | Derive macros for serialization |
Executor Modules
| Module | Responsibility |
|---|---|
| AccountExecutor | Transfer, API wallet management |
| BridgeExecutor | Deposit, withdrawal processing |
| RfqExecutor | Thesis submission, settlement |
| OracleExecutor | Price feed processing, backfill |
| AdminExecutor | System configuration, limits, pause |
Units and Constants
| Unit | Value | Description |
|---|---|---|
| USDC | 6 decimals | 1 USDC = 1,000,000 base units |
| Timestamp | Unix milliseconds | All timestamps in milliseconds |
| Block Interval | 100ms | Checkpoint frequency |
| Ring Buffer Size | 65,536 slots | ~1.8 hours of price history |
| Max Staleness | 3,000ms | Maximum oracle age for trading |
| Challenge Window | Configurable | Time period for auto-settlement |
Events
| Event | Description |
|---|---|
| Transfer | Balance transferred between accounts |
| Deposit | Funds deposited from external chain |
| WithdrawRequested | Withdrawal request created |
| WithdrawProcessed | Withdrawal completed |
| RfqSubmitted | New thesis created |
| RfqSettled | Thesis settled with winner |
| RfqCancelled | Thesis cancelled |
| OraclePriceUpdated | New price recorded |
| OracleBackfilled | Historical data added |
| SystemPaused | System paused by admin |
| SystemUnpaused | System resumed |
API Wallet
| Term | Description |
|---|---|
| Main Wallet | User's primary wallet that controls the account |
| API Wallet | Delegated wallet that can trade but not withdraw |
| Expiry | Timestamp when API wallet authorization ends |
| Nomination | Process of registering an API wallet |
| Revocation | Process of removing an API wallet |
Quote Structure
| Field | Description |
|---|---|
| bet_amount | Amount user is betting |
| payout | Total amount winner receives |
| solver_collateral | payout - bet_amount (solver's stake) |
| price_range | Lower and upper bounds for prediction |
| start_time | When observation period begins |
| end_time | When observation period ends |
| deadline | User must submit before this time |