Worlds and Universes

Worlds and Universes are the containers and orchestrators for simulations in Starkbiter Engine.

Worlds

A World represents a single simulation environment where agents interact with a shared blockchain state.

Creating a World

#![allow(unused)]
fn main() {
use starkbiter_core::environment::Environment;
use starkbiter_engine::World;

let env = Environment::builder().build().await?;
let world = World::new(env);
}

Adding Agents

#![allow(unused)]
fn main() {
world.add_agent(Agent::new("trader", TradingBehavior));
world.add_agent(Agent::new("liquidator", LiquidatorBehavior));
world.add_agent(Agent::new("oracle", OracleBehavior));
}

Running Simulations

#![allow(unused)]
fn main() {
// Run until completion
world.run().await?;

// Run for specific number of blocks
world.run_for_blocks(1000).await?;

// Run until condition met
world.run_until(|w| w.condition_met()).await?;
}

Universes

A Universe manages multiple parallel worlds, enabling complex multi-world simulations and comparisons.

Creating a Universe

#![allow(unused)]
fn main() {
use starkbiter_engine::Universe;

let universe = Universe::new();
}

Adding Worlds

#![allow(unused)]
fn main() {
// Create worlds with different configurations
let world1 = create_conservative_world().await?;
let world2 = create_aggressive_world().await?;

universe.add_world("conservative", world1);
universe.add_world("aggressive", world2);
}

Running Multiple Worlds

#![allow(unused)]
fn main() {
// Run all worlds in parallel
universe.run_all().await?;

// Compare results
let results = universe.compare_results();
}

World API

State Queries

#![allow(unused)]
fn main() {
// Get current block
let block = world.get_block_number().await?;

// Get world state
let state = world.get_state();

// Get metrics
let metrics = world.get_metrics();
}

Agent Management

#![allow(unused)]
fn main() {
// Get agent by ID
let agent = world.get_agent("trader")?;

// List all agents
let agents = world.list_agents();

// Remove agent
world.remove_agent("trader")?;
}

Messaging

#![allow(unused)]
fn main() {
// Send message to agent
world.send_message("receiver", Message::Data(value)).await?;

// Broadcast to all agents
world.broadcast(Message::Alert("Important".to_string())).await?;
}

Use Cases

Scenario Testing

#![allow(unused)]
fn main() {
// Test different scenarios in separate worlds
let bear_market = create_world_with_params(MarketCondition::Bear).await?;
let bull_market = create_world_with_params(MarketCondition::Bull).await?;

universe.add_world("bear", bear_market);
universe.add_world("bull", bull_market);

universe.run_all().await?;
}

Parameter Sweeps

#![allow(unused)]
fn main() {
// Test multiple parameter combinations
for gas_price in [10, 50, 100, 500] {
    let world = create_world_with_gas(gas_price).await?;
    universe.add_world(&format!("gas-{}", gas_price), world);
}

universe.run_all().await?;
let optimal = universe.find_optimal_parameters();
}

A/B Testing

#![allow(unused)]
fn main() {
// Compare strategy variations
let strategy_a = World::new(env1);
strategy_a.add_agent(Agent::new("trader", StrategyA));

let strategy_b = World::new(env2);
strategy_b.add_agent(Agent::new("trader", StrategyB));

universe.add_world("A", strategy_a);
universe.add_world("B", strategy_b);

universe.run_all().await?;
universe.compare_performance();
}

Next Steps

• Agents - Creating agents
• Behaviors - Defining behaviors
• Configuration - Configuration files