Order Settler API

This documentation outlines the integration flow for Order Settlers using Bolt Liquidity with synchronous settlement on Sui.

Overview

As a Order Settler, you interact with the PrivateSettlementService to provide liquidity, settle orders created by Swap Aggregators, and manage your assets across pools.

Private API Interface

service PrivateSettlementService {
  rpc SwapExactIn(SwapExactInRequest) returns (SwapExactInResponse);
  rpc WithdrawQuotes(WithdrawQuotesRequest) returns (WithdrawQuotesResponse);
  rpc WithdrawAllQuotes(WithdrawAllQuotesRequest) returns (WithdrawAllQuotesResponse);
  rpc DepositBase(DepositBaseRequest) returns (DepositBaseResponse);
  rpc WithdrawBase(WithdrawBaseRequest) returns (WithdrawBaseResponse);
  rpc WithdrawAllBases(WithdrawAllBasesRequest) returns (WithdrawAllBasesResponse);
  rpc Info(InfoRequest) returns (InfoResponse);
}

Core Components

SwapExactIn

Main entry point for executing swaps with specific input amounts.

message SwapExactInRequest {
  string want_out = 1;                  // Base asset to receive
  Balance input = 2;                    // Quote asset and amount to swap in
  string min_base_out = 3;              // Minimum base to receive
  string receiver = 4;                  // Optional different recipient
}

message SwapExactInResponse {
  Balance base_out = 1;                 // Base asset received
  string spot_price = 2;                // Price used for swap
  Balance fee = 3;                      // Fee taken
  string trade_id = 5;                  // Unique trade identifier
}

Deposit/Withdraw

Methods for managing liquidity in pools.

message DepositBaseRequest {
  Balance amount = 1;                   // Base asset and amount to deposit
}

message WithdrawBaseRequest {
  string base_asset = 1;                // Base asset to withdraw
}

message WithdrawBaseResponse {
  Balance withdrawn = 1;                // Amount withdrawn
}

Implementation Flow

1. Account Setup and Verification

// Get your account info
let info = client.info(InfoRequest {}).await?;
println!("Connected to network: {}", info.network_id);
println!("Operating as: {}", info.whoami);

// Go
resp, err := client.Info(ctx, &pb.InfoRequest{})
if err != nil {
    log.Fatalf("Could not get info: %v", err)
}
log.Printf("Connected to network: %s as %s", resp.NetworkId, resp.Whoami)

2. Providing Liquidity

// Deposit base asset to a pool
let deposit_response = client.deposit_base(
    ctx_with_funds, // Context with ETH attached
    DepositBaseRequest {
        amount: Balance {
            asset: "ETH".to_string(),
            amount: "10.0".to_string()
        }
    }
).await?;

# Python
deposit_response = await client.deposit_base(
    DepositBaseRequest(
        amount=Balance(
            asset="ETH",
            amount="10.0"
        )
    ),
    metadata=attach_funds("ETH", 10.0)  # Implementation depends on your gRPC client
)

3. Settling Orders

Market Makers listen for new orders and settle them to earn fees.

// Monitor for new orders
async fn monitor_for_orders(client: &OrderMonitorClient) -> Result<()> {
    // Subscribe to NewOrderEvent
    let mut stream = client.subscribe_events("NewOrderEvent").await?;
    
    while let Some(event) = stream.next().await {
        let event = event?;
        let order_id = event.order_id;
        
        // Get order details
        let order = client.get_order(order_id).await?;
        
        if should_settle_order(&order) {
            // Calculate settlement amount based on order
            let settlement_amount = calculate_settlement_amount(&order);
            
            // Settle the order
            client.settle_order(
                ctx_with_settlement_funds, // Context with settlement funds
                order_id
            ).await?;
            
            println!("Settled order: {}", order_id);
        }
    }
    
    Ok(())
}

fn should_settle_order(order: &Order) -> bool {
    // Implement your strategy for selecting orders to settle
    // Consider:
    // - Profitability (price compared to your sources)
    // - Risk (asset volatility)
    // - Order expiry time
    // - Asset availability in your inventory
    true
}

// JavaScript/TypeScript
async function monitorForOrders(client) {
  const stream = await client.subscribeEvents("NewOrderEvent");
  
  for await (const event of stream) {
    const orderId = event.orderId;
    const order = await client.getOrder(orderId);
    
    if (shouldSettleOrder(order)) {
      const settlementAmount = calculateSettlementAmount(order);
      
      try {
        await client.settleOrder(
          orderId,
          {
            // Attach settlement funds
            funds: {
              denom: order.want,
              amount: settlementAmount
            }
          }
        );
        
        console.log(`Settled order: ${orderId}`);
      } catch (error) {
        console.error(`Settlement failed: ${error.message}`);
      }
    }
  }
}

4. Direct Swap Execution

For direct, immediate swaps without going through the order system:

// Execute a direct swap
let swap_response = client.swap_exact_in(
    ctx_with_funds, // Context with USDC attached
    SwapExactInRequest {
        want_out: "ETH".to_string(),
        input: Balance {
            asset: "USDC".to_string(),
            amount: "1000.0".to_string()
        },
        min_base_out: "0.5".to_string(),
        receiver: None // Send to self
    }
).await?;

println!("Received: {} ETH", swap_response.base_out.amount);
println!("At price: {}", swap_response.spot_price);
println!("Fee paid: {} {}", swap_response.fee.amount, swap_response.fee.denom);

5. Collecting Quote Assets

Periodically harvest quote assets that accumulate from settled trades.

// Withdraw quotes from a single pool
let withdraw_quotes_resp = client.withdraw_quotes(
    WithdrawQuotesRequest {
        base_asset: "ETH".to_string()
    }
).await?;

for quote in withdraw_quotes_resp.withdrawn {
    println!("Withdrawn: {} {}", quote.amount, quote.denom);
}

// Or withdraw from all pools at once
let withdraw_all_resp = client.withdraw_all_quotes(
    WithdrawAllQuotesRequest {}
).await?;

for quote in withdraw_all_resp.all_withdrawn {
    println!("Withdrawn: {} {}", quote.amount, quote.denom);
}

6. LP Token Management

Market Makers must manage LP tokens for tracking pool ownership and claiming rewards.

// Deposit liquidity and receive LP tokens
let deposit_liq_resp = client.deposit_liquidity(
    ctx_with_base_funds,
    DepositLiquidityRequest {
        receiver: None, // Self
        min_lp_out: 500 // Minimum LP tokens to receive
    }
).await?;

println!("Received {} LP tokens", deposit_liq_resp.lp_out);

// Withdraw liquidity by burning LP tokens
let withdraw_liq_resp = client.withdraw_liquidity(
    WithdrawLiquidityRequest {
        receiver: None, // Self
        lps_in: 250, // LP tokens to burn (half position)
        min_out: 475 // Minimum base asset to receive
    }
).await?;

println!("Received {} base asset", withdraw_liq_resp.liquidity_out);

// Claim accumulated rewards
client.claim_rewards(
    ClaimRewardsRequest {
        to: None // Self
    }
).await?;

Price Oracle Integration

Order Settlers interact with the price oracle to update and validate prices.

// Update price with cryptographic proof
client.update_price(
    UpdatePriceRequest {
        base: "ETH".to_string(),
        quote: "USDC".to_string(),
        price_with_proof: PriceWithProof {
            price: 1825.50,
            proof: encoded_proof // Proof from oracle network
        }
    }
).await?;

// Verify a price is within bounds
client.price_in_bound(
    PriceInBoundRequest {
        base: "ETH".to_string(),
        quote: "USDC".to_string(),
        price: 1825.50
    }
).await?;

Strategy Considerations

Optimal Order Selection

fn evaluate_order_profitability(order: &Order, current_price: f64) -> bool {
    // Get current market price from your sources
    // Compare to order's limit price
    if let Some(limit_price) = order.limit_price {
        // Calculate potential profit after fees
        let offered_amount = order.offered.amount;
        let potential_settlement = offered_amount / limit_price;
        let market_value = potential_settlement * current_price;
        
        // Account for protocol and settlement fees
        let fee_rate = 0.0002; // Example fee rate
        let net_value = market_value * (1.0 - fee_rate);
        
        // Determine if profitable
        return net_value > offered_amount;
    }
    
    // No limit price, use price oracle bounds
    true
}

Balanced Inventory Management

async fn rebalance_inventory(client: &PrivateClient) -> Result<()> {
    // Get current balances across all pools
    let pools = client.get_pools().await?;
    
    for pool in pools {
        // Check if base asset needs rebalancing
        if pool.base_amount < target_min_liquidity(pool.base_asset) {
            // Add more liquidity
            client.deposit_base(
                ctx_with_funds,
                DepositBaseRequest {
                    amount: Balance {
                        asset: pool.base_asset.clone(),
                        amount: liquidity_to_add(pool.base_asset).to_string()
                    }
                }
            ).await?;
        } else if pool.base_amount > target_max_liquidity(pool.base_asset) {
            // Withdraw excess liquidity
            client.withdraw_base(
                WithdrawBaseRequest {
                    base_asset: pool.base_asset.clone()
                }
            ).await?;
        }
        
        // Withdraw accumulated quote assets
        client.withdraw_quotes(
            WithdrawQuotesRequest {
                base_asset: pool.base_asset.clone()
            }
        ).await?;
    }
    
    Ok(())
}

Error Handling

match client.settle_order(ctx, order_id).await {
    Ok(response) => {
        // Order settled successfully
        log_settlement_success(order_id, &response.completion_data);
    },
    Err(e) if e.to_string().contains("order has expired") => {
        // Skip expired orders
        log::info!("Order {} has expired", order_id);
    },
    Err(e) if e.to_string().contains("did not match order limit price") => {
        // Price moved against us
        log::warn!("Price mismatch for order {}: {}", order_id, e);
    },
    Err(e) if e.to_string().contains("price out of bounds") => {
        // Oracle price check failed
        log::warn!("Price out of bounds for order {}: {}", order_id, e);
        
        // Consider updating oracle price if you have a valid source
        update_oracle_price().await?;
    },
    Err(e) => {
        // Handle other errors
        log::error!("Settlement failed: {}", e);
    }
}

Performance Optimization

Batch Processing

// Process multiple orders in parallel
async fn process_pending_orders(client: &PrivateClient, orders: Vec<String>) -> Result<()> {
    let mut futures = Vec::new();
    
    for order_id in orders {
        let client = client.clone();
        let future = tokio::spawn(async move {
            match client.settle_order(ctx_with_funds.clone(), order_id.clone()).await {
                Ok(_) => Ok(order_id),
                Err(e) => Err((order_id, e.to_string()))
            }
        });
        
        futures.push(future);
    }
    
    let results = futures::future::join_all(futures).await;
    
    // Process results
    for result in results {
        match result {
            Ok(Ok(order_id)) => {
                println!("Successfully settled order: {}", order_id);
            },
            Ok(Err((order_id, error))) => {
                println!("Failed to settle order {}: {}", order_id, error);
            },
            Err(e) => {
                println!("Task failed: {}", e);
            }
        }
    }
    
    Ok(())
}

Security Considerations

• Fund Security - Implement proper key management for settlement funds

• Pricing Reliability - Use Bolt's Oracle service to ensure proper aggregate CEX pricing

• Gas Management - Monitor and manage gas costs for settlement transactions

• Order Validation - Verify order parameters before attempting settlement

Monitoring

async fn monitor_pool_health(client: &PrivateClient) -> Result<()> {
    // Get all pools
    let pools = client.get_pools().await?;
    
    for pool in pools {
        // Monitor liquidity relative to trading volume
        let trades = client.get_recent_trades(&pool.base_asset).await?;
        let trading_volume = calculate_24h_volume(&trades);
        
        // Calculate liquidity ratio
        let liquidity_ratio = pool.base_amount / trading_volume;
        
        if liquidity_ratio < 0.2 {  // Less than 20% of daily volume
            alert("Low liquidity in pool: {}", pool.base_asset);
        }
        
        // Monitor fee accrual
        let accrued_fees = estimate_accrued_fees(&trades);
        println!("Pool {} accrued ~{} in fees", pool.base_asset, accrued_fees);
    }
    
    Ok(())
}