Apex Rust 客户端

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

安装

该 crate 已以 orbitflare-apex 的名称发布到 crates.io；源码托管在 GitHub：

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

rpc 特性会添加 HTTP 辅助工具：getTipAccounts、JSON-RPC sendTransaction、二进制路由，以及适用于任意 Solana RPC 的 blockhash 和确认辅助工具。单独的 QUIC 路径没有 HTTP 依赖，因此如果您只需要 QUIC，请不要启用该特性。这就是构建并发送一笔交易所需的唯一依赖。该 crate 通过 orbitflare_apex::prelude 重新导出了这些 Solana 类型，并固定在端点所使用的版本上，因此您无需自行添加或版本匹配任何 solana-* crate。该 crate 需要 Rust 1.92 或更高版本。

快速开始

use std::time::Duration;

use orbitflare_apex::prelude::*;
use orbitflare_apex::rpc::{RpcClient, SolanaRpc};
use orbitflare_apex::tip;

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::Dublin`	`dub`
`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`、`send_bundle`、`bundle_statuses`、`ping`
`rpc::SolanaRpc`	任意 Solana RPC：`latest_blockhash`、`confirm(signature, timeout)`
`rpc::fetch_vaults(solana_rpc_url)`	从链上读取小费程序的金库账户（`rpc::TIP_PROGRAM_ID`）。这不是小费列表：它包含端点会拒绝的未发布金库。请使用 `get_tip_accounts` 获取可供打小费的账户，而此方法仅用于检查某个账户是否为真实的金库
`client_pubkey(api_key)`	您的 API 密钥派生出的证书密钥，与控制台上显示的一致
`serialize_transaction(&tx)`	规范的线路字节。对 legacy 和 v0 与 bincode 相同，对 v1 也正确
`wire::encode_packet`, `wire::decode_admission`	QUIC 线路格式，可作为其他语言的参考

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

使用 rpc::RpcClient::send_bundle(&[&[u8]]) 发送捆绑包，它返回一个 BundleAccepted（bundle_id 和 signatures）。轮询 bundle_statuses(&[&str]) 以获取 BundleStatus（state、landed_slot）。最多 MAX_BUNDLE（4）个成员，且恰好一个带小费。

Prelude

use orbitflare_apex::prelude::*; 会引入构建、签名和发送一笔带小费交易所需的一切，因此使用该客户端的程序不必直接依赖任何 solana-* crate。每个类型都以端点所使用的版本重新导出，从而免去了那些原本会破坏构建的版本匹配（Solana 各 crate 在不同小版本之间混用了 wincode 0.5 和 0.6）。

分组	重新导出的内容
客户端	`ApexSenderClient`, `ClientOptions`, `Region`, `MIN_TIP_LAMPORTS`, `tip_instruction`
交易	`VersionedTransaction`, `Transaction`, `Message`, `VersionedMessage`, `v1`
指令	`Instruction`, `AccountMeta`, `ComputeBudgetInstruction`
密钥与类型	`Keypair`, `read_keypair_file`, `Pubkey`, `Signature`, `Signer`, `Hash`

公开 API 类型（VersionedTransaction、Instruction、Keypair、Pubkey、Signature、Hash）在 crate 根路径下也同样可用。如果您更愿意用自己的 Solana crate 构建交易，请自行序列化并通过 send_transaction_bytes 发送这些字节，它与客户端的依赖图完全不相干。

选项

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 orbitflare_apex::{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 可自行处理这种情况。
每次重连都会重新解析主机名，因此使用 Region::Global 的客户端在自己所连的端点宕机时，会跟随负载均衡器切换到下一个最近的端点，无需重启。解析发生在后台重连中，而不是在发送时；如果解析失败或耗时超过两秒，客户端会保留原有地址。IP 地址形式的端点永远不会被解析。

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）、APEX_MEMO_BYTES 和 APEX_CU_LIMIT。每个示例都会发送一笔带小费的 memo 交易，并报告其上链的 slot。

示例	展示内容
`quic_send`	单向流：最快的路径，然后通过 Solana RPC 确认
`quic_send_with_response`	双向流：已接受或被拒绝的应答，以及如何解读拒绝
`rpc_send`	通过 HTTP 使用 JSON-RPC `sendTransaction`，小费规则相同
`raw_bytes`	线路上的预序列化字节，以及供其他语言参考的精确数据包布局
`throughput`	一个预热连接，N 个并发发送，每次发送的 p50 和 p99，以及上链数量
`bundle`	由两笔交易组成的原子捆绑包（其中一笔带小费），以及它上链前的状态
`client_pubkey`	API 密钥派生出的证书密钥，用于与您的控制台进行比较
`typescript/send_rpc.ts`	使用 `@solana/web3.js` 的 JSON-RPC 路径，无需客户端库
`python/send.py`	在 Python 中使用 `solders` 调用二进制路由和 JSON-RPC
`javascript/send.mjs`	纯 Node：二进制路由和批量发送，无需构建步骤
`curl/README.md`	仅用 cURL 调用每一条路由，包括批量和捆绑包的帧格式

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

Prelude

选项

保活与重连

错误

仓库中的示例

客户端不做的事

​安装

​快速开始

​区域

​传输方式

​API

​Prelude

​选项

​保活与重连

​错误

​仓库中的示例

​客户端不做的事

安装

快速开始

区域

传输方式

API

Prelude

选项

保活与重连

错误

仓库中的示例

客户端不做的事