Sign inGet started
Documentation index

Multi-Region

Slipstream regions are dynamic — they are discovered at runtime from the discovery service. Regions and workers change as infrastructure scales, so the SDK auto-discovers the best connection at connect time.

Discovery Service

The SDK queries https://discovery.allenhark.network/v1/discovery at connect time. This returns:

  • Regions — Available regions with display names and current leader RTT
  • Workers — Individual workers per region with IP, ports, health status, and version
  • Recommended region — The region with lowest leader RTT right now

The discovery endpoint is public and requires no authentication.

How Auto-Discovery Works

  1. SDK queries the discovery service for available regions and workers
  2. SDK probes latency to each healthy worker
  3. SDK connects to the worker with the lowest measured round trip, using the protocol fallback chain
  4. If the connection drops, SDK automatically reconnects to the next best worker

Querying Regions

Regions — Rust

Rust
// Get available regions (no auth required)
let regions = client.get_regions().await?;
for region in &regions {
    println!("{} ({})", region.display_name, region.region_id);
    if let Some(geo) = &region.geolocation {
        println!("  Location: {:.2}, {:.2}", geo.lat, geo.lon);
    }
}

Regions — TypeScript

TypeScript
const regions = await client.getRegions();
for (const region of regions) {
    console.log(`${region.displayName} (${region.regionId})`);
}

Regions — Python

Python
regions = await client.get_regions()
for region in regions:
    print(f"{region.display_name} ({region.region_id})")

Pinning to a Region

You can optionally pin to a specific region by passing its ID in the config. Use the region IDs returned by the discovery service.

Rust
let config = Config::builder()
    .api_key("sk_live_...")
    .region("us-east-2")   // Pin to a specific region
    .build()?;
TypeScript
const config = configBuilder()
    .apiKey("sk_live_...")
    .region("eu-central")
    .build();
Python
config = config_builder().api_key("sk_live_...").region("ap-southeast-1").build()

Direct Endpoint

To bypass discovery entirely and connect to a specific worker:

Rust
let config = Config::builder()
    .api_key("sk_live_...")
    .endpoint("84.32.34.7")  // Direct IP
    .build()?;
TypeScript
const config = configBuilder()
    .apiKey("sk_live_...")
    .endpoint("84.32.34.7")
    .wsEndpoint("ws://84.32.34.7:9000")
    .build();

Routing Recommendations

Get real-time routing recommendations based on the current leader.

Routing — Rust

Rust
let rec = client.get_routing_recommendation().await?;
println!("Best region: {}", rec.best_region);
println!("Leader: {}", rec.leader_pubkey);
println!("Slot: {}", rec.slot);
println!("Confidence: {}%", rec.confidence);
println!("Expected RTT: {:?}ms", rec.expected_rtt_ms);
println!("Fallback regions: {:?}", rec.fallback_regions);
println!("Fallback strategy: {:?}", rec.fallback_strategy);
println!("Valid for: {}ms", rec.valid_for_ms);

Routing — TypeScript

TypeScript
const rec = await client.getRoutingRecommendation();
console.log("Best region:", rec.bestRegion);
console.log("Leader:", rec.leaderPubkey);
console.log("Confidence:", rec.confidence, "%");
console.log("Fallback strategy:", rec.fallbackStrategy);

Routing — Python

Python
rec = await client.get_routing_recommendation()
print(f"Best region: {rec.best_region}")
print(f"Leader: {rec.leader_pubkey}")
print(f"Confidence: {rec.confidence}%")
print(f"Fallback strategy: {rec.fallback_strategy}")

Fallback Strategies

StrategyDescription
sequentialTry regions in order of latency
broadcastFan-out to every discovered region at once
retryRetry same region with backoff
noneNo fallback

Use broadcast_mode: true in SubmitOptions to fan-out a transaction to every discovered region.

Connection Info

Check which region and protocol you're connected to:

Connection — Rust

Rust
let info = client.connection_info();
println!("Region: {:?}", info.region);
println!("Protocol: {:?}", info.protocol);
println!("Session: {}", info.session_id);

Connection — TypeScript

TypeScript
const info = client.connectionInfo();
console.log("Region:", info.region);
console.log("Protocol:", info.protocol);

Latency & Time Sync

The SDK maintains latency measurements and clock synchronization via keep-alive pings.

Latency — Rust

Rust
// Median RTT/2 from keep-alive pings
if let Some(latency) = client.latency_ms() {
    println!("Latency: {}ms", latency);
}

// Client-server clock offset
if let Some(offset) = client.clock_offset_ms() {
    println!("Clock offset: {}ms", offset);
}

// Corrected server time
let server_time = client.server_time();

// Manual ping
let ping = client.ping().await?;
println!("RTT: {}ms, offset: {}ms", ping.rtt_ms, ping.clock_offset_ms);

Landing Rates by Region

Track landing rates per region to understand performance.

Landing Rates — Rust

Rust
let stats = client.get_landing_rates(None).await?;
println!("Overall: {:.1}% ({}/{})",
    stats.landing_rate * 100.0, stats.total_landed, stats.total_sent);
for region in &stats.by_region {
    println!("  {}: {:.1}% ({}/{})",
        region.region, region.landing_rate * 100.0,
        region.total_landed, region.total_sent);
}

Landing Rates — TypeScript

TypeScript
const stats = await client.getLandingRates();
console.log(`Overall: ${(stats.landingRate * 100).toFixed(1)}%`);
for (const region of stats.byRegion) {
    console.log(`  ${region.region}: ${(region.landingRate * 100).toFixed(1)}%`);
}

Next Steps