Raiku Sim

Simulate how Raiku’s deterministic scheduling compares to vanilla Solana’s best-effort model, focusing on inclusion guarantees, slot utilization, MEV risk, and fairness.

---

✨ Features

• Deterministic transaction scheduling (Raiku model)
• Optional comparison against vanilla Solana
• Configurable network congestion simulation
• Fairness Index (predictability ratio)
• ASCII-based slot utilization heatmap
• JSON output for automation or analysis pipelines

---

📦 Installation

# Clone this repository
git clone https://github.com/starfrich/raiku-sim.git

# Go to raiku-sim directory
cd raiku-sim

# Install dependencies
pnpm install

# Build project
pnpm build

---

🚀 Usage

pnpm sim [options]

Or run directly without building:

pnpm start [options]

Options

Option	Alias	Description	Default
--tx-count <number>	-t	Number of transactions to simulate	10
--fee-bid <number>	-f	Fee bid per transaction (in SOL)	0.0005
--congested	-c	Simulate network congestion	false
--compare	-x	Compare with vanilla Solana behavior	false
--json	—	Output full JSON result for scripts	false

---

🧮 Example Runs

1. Simple Raiku Simulation

pnpm sim -t 50 -f 0.001

Output:

✅ Raiku Mode (Deterministic Scheduling):
   Slots Used         : 1
   Avg. Delay         : 0.4s
   Total Cost         : 0.05 SOL
   MEV Risk           : LOW

2. Compare with Vanilla Solana

pnpm sim -t 280 -f 0.001 -c -x

Output:

✅ Raiku Mode (Deterministic Scheduling):
   Slots Used         : 2
   Avg. Delay         : 0.4s
   Total Cost         : 0.28 SOL
   MEV Risk           : LOW
📊 Raiku Slot Utilization:
Slot 123456: ████████████████████ (200 tx)
Slot 123457: ████████████████     (80 tx)

⚠️  Vanilla Solana (Best-Effort):
   Slots Used         : 4
   Avg. Delay         : 1.6s
   MEV Risk           : HIGH
📊 Vanilla Slot Utilization:
Slot 123458: ████████████████████ (200 tx)
Slot 123459: ████████████████     (80 tx)
Slot 123460: ████████████████     (0 tx)

⚖️  Fairness Index (Raiku vs Solana): 4.00x more predictable

---

📊 JSON Output Example

pnpm sim -t 100 -f 0.0005 -x --json

{
  "raiku": {
    "summary": {
      "slotsUsed": 1,
      "averageDelaySeconds": 0.4,
      "totalCostSol": 0.05,
      "mevRisk": "LOW"
    },
    "transactions": [...]
  },
  "vanilla": {
    "summary": {
      "slotsUsed": 3,
      "averageDelaySeconds": 1.2,
      "totalCostSol": 0.05,
      "mevRisk": "HIGH"
    },
    "transactions": [...]
  },
  "fairnessIndex": 3.00
}

---

⚖️ Metrics Breakdown

Metric	Meaning
Slots Used	Number of unique Solana slots occupied
Average Delay	Mean inclusion delay (seconds)
Total Cost	Total SOL cost for all transactions
MEV Risk	Estimated front-running exposure
Fairness Index	Predictability improvement (Vanilla delay ÷ Raiku delay)

---

🧠 How It Works

Raiku Sim models Solana’s ~400ms slot cadence and compares deterministic Raiku scheduling versus best-effort queuing. Under congestion, Raiku maintains guaranteed inclusion while Solana experiences delay growth and higher MEV risk.

Raiku Advantage:

• Predictable confirmation timing
• Slot fairness under load
• Reduced MEV risk due to deterministic inclusion

%%{init: {"theme": "base", "themeVariables": {
  "primaryColor": "#4B9CE2",
  "primaryBorderColor": "#1E70BF",
  "primaryTextColor": "#ffffff",
  "secondaryColor": "#2F2F2F",
  "secondaryBorderColor": "#999999",
  "tertiaryColor": "#EFEFEF",
  "tertiaryBorderColor": "#CCCCCC",
  "lineColor": "#888888",
  "textColor": "#EAEAEA",
  "fontSize": "14px",
  "background": "transparent"
}}}%%

sequenceDiagram
    participant Dev as Developer
    participant Raiku as Raiku Scheduler
    participant Solana as Solana Validator

    Dev->>Raiku: Submit tx + fee bid for slot N
    Raiku-->>Dev: Pre-confirmation (guaranteed inclusion)
    Note over Raiku,Solana: At slot N
    Raiku->>Solana: Deliver tx deterministically
    Solana-->>Dev: Block N includes tx (0 MEV, 0 delay)

Loading

---

🧩 API Reference (for programmatic use)

import { simulate } from './simulator';

const result = simulate({
  txCount: 280,
  feeBidSol: 0.001,
  congested: true,
  compare: true,
});

console.log(result.fairnessIndex);

---

🧾 License

See LICENSE for more details