Skip to content

README.md

Latest commit

 

History

History
179 lines (141 loc) · 4.39 KB

README.md

File metadata and controls

179 lines (141 loc) · 4.39 KB
Raw

router-api-server

Off-chain API server for stellar-router providing transaction simulation and real-time status tracking via WebSocket.

Features

Transaction Simulation Endpoint (/simulate)

Allows developers to preview transaction outcomes before execution.

Request:

POST /simulate
{
  "target": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4",
  "function": "transfer",
  "route_details": {
    "name": "swap_route",
    "version": 1,
    "expected_outputs": ["1000000"]
  }
}

Response:

{
  "success": true,
  "estimated_fees": {
    "base_fee": 100,
    "resource_fee": 1000,
    "total_fee": 1100,
    "surge_multiplier": 100,
    "high_load": false
  },
  "expected_outputs": ["1000000"],
  "route_breakdown": {
    "route_name": "swap_route",
    "version": 1,
    "target_contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4",
    "function": "transfer"
  },
  "message": "Simulation successful"
}

WebSocket Transaction Status Tracking (/ws)

Real-time transaction status updates via WebSocket.

Subscribe to transaction:

{
  "action": "subscribe",
  "tx_id": "tx_12345"
}

Status events:

{
  "msg_type": "status_update",
  "data": {
    "tx_id": "tx_12345",
    "status": "PENDING",
    "timestamp": "2026-04-28T02:38:56Z",
    "message": "Transaction queued"
  }
}

Supported statuses:

  • PENDING - Transaction is pending
  • SUBMITTED - Transaction submitted to network
  • CONFIRMED - Transaction confirmed on-chain
  • FAILED - Transaction failed

Unsubscribe from transaction:

{
  "action": "unsubscribe",
  "tx_id": "tx_12345"
}

Running

Prerequisites

  • Rust 1.78+
  • Soroban RPC endpoint URL
  • Router execution contract ID

Environment Variables

export LISTEN_ADDR="127.0.0.1:8080"
export SOROBAN_RPC_URL="https://soroban-testnet.stellar.org"
export ROUTER_EXECUTION_CONTRACT_ID="CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4"
export ROUTER_API_MAX_REQUESTS="60"
export ROUTER_API_RATE_WINDOW_SECS="60"

ROUTER_API_MAX_REQUESTS and ROUTER_API_RATE_WINDOW_SECS control the token-bucket limiter for protected API routes. Requests are limited by X-API-Key when present, otherwise by remote IP address.

Fee Estimation

The heuristic fee-estimation model is tunable without code changes. Each variable falls back to the default shown below when unset, unparseable, or not strictly positive:

Variable Default Description
ROUTER_BASE_FEE 100 Flat base fee, in stroops.
ROUTER_RESOURCE_FEE_FLOOR 100 Lower bound for the derived resource fee.
ROUTER_RESOURCE_FEE_DIVISOR 1000 Divisor scaling amount into a resource fee.
ROUTER_SURGE_LOAD_THRESHOLD_BPS 8000 Network load (bps) at/above which surge pricing applies.
ROUTER_SURGE_MULTIPLIER 200 Multiplier (percent) applied under surge.
ROUTER_NORMAL_MULTIPLIER 100 Multiplier (percent) applied under normal load.

Start Server

cargo run --release -p router-api-server

Docker

docker build -t router-api-server -f Dockerfile.api .
docker run -p 8080:8080 \
  -e SOROBAN_RPC_URL="https://soroban-testnet.stellar.org" \
  -e ROUTER_EXECUTION_CONTRACT_ID="CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4" \
  router-api-server

API Endpoints

Endpoint Method Description
/health GET Health check
/simulate POST Simulate transaction
/routes GET List registered route names
/routes/:name GET Fetch route details
/ws GET WebSocket connection for status tracking

Reconnection Handling

The WebSocket client should implement automatic reconnection with exponential backoff:

  1. Initial connection attempt
  2. On disconnect, wait 1 second before retry
  3. Double wait time on each subsequent failure (max 30 seconds)
  4. Re-subscribe to previous transaction IDs after reconnection

Error Handling

Simulation Errors

  • 400 Bad Request - Missing or invalid parameters
  • 500 Internal Server Error - RPC or contract call failure

WebSocket Errors

  • Invalid JSON in message
  • Unknown action type
  • Connection timeout (server-side: 5 minutes of inactivity)

Development

Run tests:

cargo test -p router-api-server

Build release:

cargo build --release -p router-api-server