Apex Rust 客户端

apex-sender-client 是 Apex 的参考客户端。它为每个 Apex 端点保持一个持久 QUIC 连接，使用由您的 API 密钥派生的客户端证书进行身份验证，每个流发送一笔序列化后的交易，并在连接断开时以 0-RTT 重连。

安装

该 crate 即将发布到 crates.io，名称为 apex-sender-client。在发布之前，请从 OrbitFlare 的 GitHub 仓库安装：

[dependencies]
apex-sender-client = { git = "https://github.com/orbitflare/apex-sender-client", features = ["rpc"] }

发布到 crates.io 之后：

[dependencies]
apex-sender-client = { version = "0.1", features = ["rpc"] }

rpc 特性会添加 HTTP 辅助工具：getTipAccounts、JSON-RPC sendTransaction、二进制路由，以及适用于任意 Solana RPC 的 blockhash 和确认辅助工具。单独的 QUIC 路径没有 HTTP 依赖，因此如果您只需要 QUIC，请不要启用该特性。该 crate 需要 Rust 1.92 或更高版本。

快速开始

use std::time::Duration;

use apex_sender_client::rpc::{RpcClient, SolanaRpc};
use apex_sender_client::{tip, tip_instruction, ApexSenderClient, Region, MIN_TIP_LAMPORTS};
use solana_signer::Signer;
use solana_transaction::versioned::VersionedTransaction;
use solana_transaction::Transaction;

let client = ApexSenderClient::connect(Region::Frankfurt, &api_key).await?;
let tip_accounts = RpcClient::new(Region::Frankfurt, &api_key).get_tip_accounts().await?;
let tip_account = tip::pick_tip_account(&tip_accounts).ok_or("no tip accounts")?;

// Your instructions, plus the tip as a top-level instruction.
let instructions = [
    your_instruction,
    tip_instruction(&payer.pubkey(), &tip_account, MIN_TIP_LAMPORTS),
];
let solana = SolanaRpc::new(solana_rpc_url);
let blockhash = solana.latest_blockhash().await?;
let tx = VersionedTransaction::from(Transaction::new_signed_with_payer(
    &instructions,
    Some(&payer.pubkey()),
    &[&payer],
    blockhash,
));

let signature = client.send_transaction(&tx).await?; // microseconds, no acknowledgement
let slot = solana.confirm(&signature.to_string(), Duration::from_secs(30)).await?;

带有 Cargo.toml 的完整程序，参见快速入门的 Rust 标签页。

区域

Region 为每个 Apex 端点命名。Region::parse("fra") 和 Region::code() 用于与短代码相互转换，Region::ALL 列出全部区域。

变体	代码
`Region::Frankfurt`	`fra`
`Region::Amsterdam`	`ams`
`Region::London`	`lon`
`Region::NewYork`	`nyc`
`Region::SaltLakeCity`	`slc`
`Region::Singapore`	`sgp`
`Region::Tokyo`	`tyo`
`Region::Siauliai`	`sqq`
`Region::Global`（正在逐步上线）	`global`

region.quic_endpoint() 返回 <code>.apex.orbitflare.com:7001，region.rpc_url() 返回 http://<code>.apex.orbitflare.com。参见端点与区域。

传输方式

	QUIC 单向	QUIC 双向	HTTP 二进制	JSON-RPC
调用	`send_transaction`, `send_transaction_bytes`	`send_transaction_with_response`, `send_with_response`	`rpc::RpcClient::send_transaction_binary`, `send_batch`	`rpc::RpcClient::send_transaction`
返回	签名。不读取任何返回内容	已接受，或拒绝代码和消息	签名，或带标签的错误	签名，或 JSON-RPC 错误
每次发送的开销	预热连接上的一个流	一个流加一次往返	一个携带原始字节的 HTTP 请求	一个在 JSON 中携带 base64 的 HTTP 请求
最适合	使用持久连接的机器人	集成、调试，以及希望直接获得原因的工具	批量发送	直接替换 `sendTransaction` 代码

传输方式不会改变优先级或路由。起作用的是小费。

API

项	描述
`ApexSenderClient::connect(region, api_key)`	使用临时本地端口和默认选项连接
`ApexSenderClient::connect_with_options(opts, api_key)`	使用 `ClientOptions` 连接
`send_transaction(&tx)`	序列化（legacy、v0 或 v1）并在单向流上发送。返回第一个签名
`send_transaction_bytes(bytes)`	同上，但使用您已持有的字节。不会对其重新编码
`send_transaction_with_response(&tx)`	双向流。被拒绝时返回 `Err(Error::Rejected { code, message })`
`send_with_response(bytes)`	同上，但使用字节。返回原始的 `Admission`
`health()`, `reconnects_total()`, `zero_rtt_resumptions_total()`, `remote_addr()`	连接状态，用于您的指标
`reconnect()`, `close()`	生命周期
`tip_instruction(payer, tip_account, lamports)`	构建小费转账
`tip::pick_tip_account(&accounts)`	随机选择一个小费账户
`MIN_TIP_LAMPORTS`	标准等级下限：1,000,000 lamports
`rpc::RpcClient`	通过 HTTP 访问 Apex 端点：`get_tip_accounts`、`send_transaction` (JSON-RPC)、`send_transaction_binary`、`send_batch`、`ping`
`rpc::SolanaRpc`	任意 Solana RPC：`latest_blockhash`、`confirm(signature, timeout)`
`rpc::fetch_vaults(solana_rpc_url)`	直接从链上小费程序（`rpc::TIP_PROGRAM_ID`）读取小费账户，无需调用 Apex 端点
`client_pubkey(api_key)`	您的 API 密钥派生出的证书密钥，与控制台上显示的一致
`serialize_transaction(&tx)`	规范的线路字节。对 legacy 和 v0 与 bincode 相同，对 v1 也正确
`wire::encode_packet`, `wire::decode_admission`	QUIC 线路格式，可作为其他语言的参考

客户端的 Clone 开销很低，克隆出的副本共享同一个连接。创建一次，然后将克隆分发给您的各个任务。

该 crate 目前还没有捆绑包辅助工具。请通过 HTTP 使用 sendBundle 或 POST /send-bundle 发送捆绑包。

选项

ClientOptions 实现了 Default，因此只需设置您需要的字段：

字段	默认值	描述
`endpoint`	该区域的 QUIC 地址	QUIC 地址的 `host:port`。会覆盖区域设置
`mev_protect`	`false`	跳过 Shield 黑名单上的领导者。参见 MEV 保护
`max_retries`	`None`	每笔交易的重试预算。`None` 使用端点的默认值
`bind_addr`	临时端口	本地 UDP 绑定地址，用于防火墙白名单
`connect_timeout`	3 s	握手超时
`send_timeout`	2 s	单次发送的超时
`keep_alive`	1 s	QUIC PING 间隔。端点的空闲超时为 30 s
`auto_reconnect`	`true`	当发送因连接已断开而失败时，重新连接并再发送一次
`proactive_reconnect`	`true`	后台任务在发现断线后立即重新握手，这样下一次发送就不必为此付出代价

use std::time::Duration;

use apex_sender_client::{ApexSenderClient, ClientOptions, Region};

let client = ApexSenderClient::connect_with_options(
    ClientOptions {
        endpoint: Some(Region::NewYork.quic_endpoint()),
        bind_addr: Some("0.0.0.0:47001".parse()?),
        mev_protect: true,
        max_retries: Some(30),
        send_timeout: Duration::from_secs(1),
        ..Default::default()
    },
    &api_key,
)
.await?;

保活与重连

连接通过每秒一次的 QUIC PING 保持打开，而 Apex 端点的空闲超时为 30 秒。在预热的连接上，一次发送就是打开一个流并写入一次。如果连接断开：

后台任务会发现并立即重新握手（proactive_reconnect），因此下一次发送通常能找到一个可用的连接。
重连会使用缓存的会话票据，并在握手的首批数据包中发送等待中的交易（0-RTT）。如果端点拒绝早期数据，客户端会在握手完成后重新发送。
因连接已断开而失败的发送会重新连接并重试一次（auto_reconnect）。将其设为 false 可自行处理这种情况。

health()、reconnects_total() 和 zero_rtt_resumptions_total() 会显示发生了什么。请将它们导出到您的指标中。

错误

`Error` 变体	含义
`Rejected { code, message }`	端点在双向流上拒绝了交易。参见准入码
`TooLarge(bytes)`	超过 4096 字节。在发送任何内容之前于本地捕获
`Timeout`	连接或发送超时已到
`Resolve`, `Bind`, `Tls`, `Connect`, `Connection`, `Write`, `Read`	传输失败
`Serialize`, `BadAdmission`	编码问题
`Closed`	客户端已关闭

HTTP 辅助工具返回 rpc::RpcError：Http 表示传输失败，Rpc { code, message } 表示 JSON-RPC 或普通 HTTP 拒绝，另有 BadResponse。

仓库中的示例

所有示例都读取 APEX_API_KEY、KEYPAIR_PATH（默认 payer.json）、SOLANA_RPC_URL，以及可选的 APEX_REGION、APEX_QUIC、APEX_RPC、TIP_LAMPORTS 和 APEX_TX_VERSION（legacy 或 v1）。每个示例都会发送一笔带小费的 memo 交易，并报告其上链的 slot。

示例	展示内容
`quic_send`	单向流：最快的路径，然后通过 Solana RPC 确认
`quic_send_with_response`	双向流：已接受或被拒绝的应答，以及如何解读拒绝
`rpc_send`	通过 HTTP 使用 JSON-RPC `sendTransaction`，小费规则相同
`raw_bytes`	线路上的预序列化字节，以及供其他语言参考的精确数据包布局
`throughput`	一个预热连接，N 个并发发送，每次发送的 p50 和 p99，以及上链数量
`client_pubkey`	API 密钥派生出的证书密钥，用于与您的控制台进行比较
`typescript/send_rpc.ts`	使用 `@solana/web3.js` 的 JSON-RPC 路径，无需客户端库
`python/send.py`	在 Python 中使用 `solders` 调用二进制路由和 JSON-RPC

APEX_API_KEY=... KEYPAIR_PATH=payer.json SOLANA_RPC_URL=https://... \
  cargo run --release --example quic_send --features rpc

主网上的典型输出，来自一个紧邻 Apex 端点的客户端：

sent in 16 us
landed in slot 447831391 after 745 ms: 5gwAmfVM...

客户端不做的事

构建或签名交易，或为您选择优先费。
模拟或运行预检。在您和领导者之间，没有任何环节会这样做。

开始使用

产品

解决方案

数据获取

RPC

数据流

Apex

交易 API

安装

快速开始

区域

传输方式

API

选项

保活与重连

错误

仓库中的示例

客户端不做的事

​安装

​快速开始

​区域

​传输方式

​API

​选项

​保活与重连

​错误

​仓库中的示例

​客户端不做的事

安装

快速开始

区域

传输方式

API

选项

保活与重连

错误

仓库中的示例

客户端不做的事