Astralane-quic-client-go

Go client library for sending Solana transactions to Astralane's QUIC TPU endpoint.

How It Works

The client authenticates using a self-signed TLS certificate with your API key as the Common Name (CN). On connect, the server extracts the CN from the certificate to identify your account. Transactions are sent as fire-and-forget over QUIC unidirectional streams - one stream per transaction.

Installation

go get github.com/astralane/astralane-quic-client-go

Quick Start

package main

import (
    astralane "github.com/astralane/astralane-quic-client-go"
    "log"
)

func main() {
    // Connect (certificate is generated automatically from your API key)
    client, err := astralane.Connect("lim.gateway.astralane.io:7000", "your-api-key-uuid")
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Build your transaction
    // txBytes := ... your bincode-serialized VersionedTransaction ...

    // Send (fire-and-forget)
    if err := client.SendTransaction(txBytes); err != nil {
        log.Fatal(err)
    }
}

API

astralane.Connect(serverAddr, apiKey)

Connects to the QUIC server. Accepts both IP:port ("1.2.3.4:7000") and hostname:port ("lim.gateway.astralane.io:7000") formats.

Internally generates an EC P-256 self-signed certificate with apiKey as the CN, configures ALPN as astralane-tpu, and establishes a single QUIC connection with 25s keep-alive. Each client instance holds exactly one connection - all SendTransaction calls are multiplexed as separate streams over it. Create multiple client instances if you need more concurrent connections (up to the server's per-API-key connection limit).

client.SendTransaction(txBytes)

Sends a bincode-serialized VersionedTransaction (max 1232 bytes). Opens a unidirectional QUIC stream, writes the bytes, and finishes the stream. Fire-and-forget - returns nil once written, with no server response.

Automatic reconnection: If the connection is dead (idle timeout, server restart, etc.), SendTransaction will transparently reconnect before sending. No manual intervention needed.

client.Reconnect()

Manually reconnects if the connection was closed. Typically not needed since SendTransaction reconnects automatically.

client.IsConnected()

Returns true if the connection is still alive.

client.Close()

Gracefully closes the connection.

Important: Close() sends a QUIC CONNECTION_CLOSE frame that immediately terminates all open streams. If you've just sent transactions, add a short delay before closing to let the server finish reading in-flight streams:

time.Sleep(100 * time.Millisecond)
client.Close()

Current Server Limits

Parameter	Value
Max connections per API key	10
Max streams per connection	64
Stream timeout	750 ms
Max transaction size	1232 bytes
Idle timeout	30 s

Error Codes

The server may close your connection with these application-level error codes:

Code	Name	Meaning
0	OK	Normal closure
1	UNKNOWN_API_KEY	API key not recognized
2	CONNECTION_LIMIT	Too many connections for this key

Use astralane.DescribeErrorCode(code) to get a human-readable description.

Rate limiting: When the rate limit is exceeded, the server silently drops excess transactions. The connection stays alive - no error is returned to the client.

Stream limits: When the concurrent stream limit is reached, OpenUniStream() blocks (backpressure) until a stream slot frees up. The server does not close the connection - SendTransaction will simply take longer to return.

Error Handling

if err := client.SendTransaction(txBytes); err != nil {
    log.Printf("Error: %v", err)
    // Reconnection is automatic on the next SendTransaction call.
    // Only fatal errors (e.g., UNKNOWN_API_KEY after 3 retries) require manual intervention.
}

Running the Example

Builds a signed transaction with compute budget instructions and a 0.0001 SOL tip transfer, then sends it via QUIC.

Variable	Required	Description	Default
API_KEY	Yes	Your Astralane API key
KEYPAIR_PATH	Yes	Path to Solana keypair JSON file
TIP_ADDRESS	Yes	Tip recipient pubkey (Astralane tip account)
SERVER_ADDR	Yes	QUIC server address
RPC_URL	No	Solana RPC URL (for fetching recent blockhash)	https://api.mainnet-beta.solana.com

API_KEY=your-api-key-uuid \
  KEYPAIR_PATH=~/.config/solana/id.json \
  TIP_ADDRESS=astrazznxsGUhWShqgNtAdfrzP2G83DzcWVJDxwV9bF \
  RPC_URL=https://api.mainnet-beta.solana.com \
  SERVER_ADDR=lim.gateway.astralane.io:7000 \
  go run ./examples/send_transaction

What the Example Transaction Contains

1. SetComputeUnitLimit - 20,000 CUs
2. SetComputeUnitPrice - 10,000 micro-lamports per CU
3. SystemProgram::Transfer - 0.0001 SOL (100,000 lamports) to the tip address