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 fastest worker using the protocol fallback chain
  4. If the connection drops, SDK automatically reconnects to the next best worker

Querying Regions

Regions — Rust

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

Regions — TypeScript

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

Regions — Python

1regions = await client.get_regions()
2for region in regions:
3    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.

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

Direct Endpoint

To bypass discovery entirely and connect to a specific worker:

1let config = Config::builder()
2    .api_key("sk_live_...")
3    .endpoint("84.32.34.7")  // Direct IP
4    .build()?;
1const config = configBuilder()
2    .apiKey("sk_live_...")
3    .endpoint("84.32.34.7")
4    .wsEndpoint("ws://84.32.34.7:9000")
5    .build();

Routing Recommendations

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

Routing — Rust

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

Routing — TypeScript

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

Routing — Python

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

Fallback Strategies

StrategyDescription
sequentialTry regions in order of latency
broadcastFan-out to all regions simultaneously
retryRetry same region with backoff
noneNo fallback

Use broadcast_mode: true in SubmitOptions to fan-out a transaction to all regions.

Connection Info

Check which region and protocol you're connected to:

Connection — Rust

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

Connection — TypeScript

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

Latency & Time Sync

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

Latency — Rust

1// Median RTT/2 from keep-alive pings
2if let Some(latency) = client.latency_ms() {
3    println!("Latency: {}ms", latency);
4}
5
6// Client-server clock offset
7if let Some(offset) = client.clock_offset_ms() {
8    println!("Clock offset: {}ms", offset);
9}
10
11// Corrected server time
12let server_time = client.server_time();
13
14// Manual ping
15let ping = client.ping().await?;
16println!("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

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

Landing Rates — TypeScript

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

Next Steps

PreviousReal-Time StreamsNextBilling & Tokens