EVM SDK

一个 Rust 客户端，服务于 OrbitFlare 的各条 EVM 链——Polygon、BNB Smart Chain 与 Robinhood Chain——以及你自己定义的任意 EVM 链。全程构建于 alloy 类型之上（Address、U256、B256、Filter、TransactionRequest，以及类型化的区块、交易、收据与日志），并配备 OrbitFlare 自有的传输层：端点故障转移、带退避的重试与自愈的 WebSocket 订阅。客户端对链是泛型的（RpcClient<C>、WsClient<C>）；下文的别名是便捷简写。gRPC 目前仅支持 Polygon（Bor）。

支持的链

链	Chain ID	别名
Polygon	137	`PolygonRpcClient`、`PolygonWsClient`
BNB Smart Chain	56	`BnbRpcClient`、`BnbWsClient`
Robinhood Chain	4663	`RobinhoodRpcClient`、`RobinhoodWsClient`
你自己的链	任意	`RpcClient<C>`，其中 `impl Chain for C`

正从 orbitflare-robinhood-sdk 迁移？Robinhood Chain 现已在此通过 RobinhoodRpcClient / RobinhoodWsClient 覆盖。其 RPC 与 WebSocket 接口完全一致；独立 crate 已弃用。

安装

cargo add orbitflare-evm-sdk

默认仅启用 RPC 客户端。按需启用其他特性：

cargo add orbitflare-evm-sdk --features ws
cargo add orbitflare-evm-sdk --features grpc
cargo add orbitflare-evm-sdk --features all

RPC

let client = PolygonRpcClient::builder()
    .url("https://ams.poly.rpc.orbitflare.com")
    .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
    .build()?;

let block = client.get_block_number().await?;
let gas_price = client.get_gas_price().await?;

use orbitflare_evm_sdk::{primitives::address, PolygonRpcClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = PolygonRpcClient::builder()
        .url("https://ams.poly.rpc.orbitflare.com")
        .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
        .build()?;

    let block = client.get_block_number().await?;
    let gas_price = client.get_gas_price().await?;

    let wallet = address!("d8dA6BF26964aF9D7eEd9e03E53415D37aA96045");
    let balance = client.get_balance(wallet).await?;

    println!("block {block}, gas {gas_price} wei, balance {balance} wei");
    Ok(())
}

没有内置的默认端点：用 .url() 或环境变量设置 URL（参见端点），用 .api_key() 或 ORBITFLARE_LICENSE_KEY 设置 API 密钥。

构建器方法

.url(url) — 主端点。解析顺序：构建器上的 .url()，然后是环境变量 ORBITFLARE_RPC_URL。 .urls(&[...]) — 一次设置主端点与所有备用端点。第一个元素为主端点，其余为备用。 .fallback_url(url) / .fallback_urls(&[...]) — 添加故障转移端点。失败的端点会被隔离并进入指数冷却（10s、20s、40s，最大 60s），冷却结束后自动重试；健康端点始终优先。 .api_key(key) — 你的 OrbitFlare 许可证密钥。若未设置，SDK 会检查 ORBITFLARE_LICENSE_KEY。密钥在请求时以 ?api_key=<key> 附加到端点 URL。 .block_tag(tag) — 状态查询（get_balance、call、get_code 等）使用的默认区块标签。默认为 Latest。 .retry(policy) — 控制瞬时错误（5xx、429、连接重置、JSON-RPC 错误码 -32005）的重试，采用指数退避，之后故障转移到下一个端点。 .timeout(duration) — 单次 HTTP 请求超时。

可用方法

方法	返回值
`get_block_number()`	`u64`
`get_chain_id()`	`u64`
`get_balance(Address)`	`U256` wei
`get_transaction_count(Address)`	`u64` nonce
`get_gas_price()`	`u128` wei
`max_priority_fee_per_gas()`	`u128` wei
`get_block_by_number(impl Into<BlockNumberOrTag>, full_txs)`	`Option<Block>`
`get_block_by_hash(B256, full_txs)`	`Option<Block>`
`get_transaction_by_hash(B256)`	`Option<Transaction>`
`get_transaction_receipt(B256)`	`Option<TransactionReceipt>`
`get_logs(&Filter)`	`Vec<Log>`
`get_code(Address)`	`Bytes`
`get_storage_at(Address, B256)`	`B256`
`call(&TransactionRequest)`	`Bytes`
`estimate_gas(&TransactionRequest)`	`u64`
`send_raw_transaction(&[u8])`	`B256` 交易哈希
`fee_history(blocks, newest, percentiles)`	`FeeHistory`
`request(method, params)`	按名称调用任意 RPC 方法（`serde_json::Value`）
`request_raw(body)`	原始 JSON-RPC 请求体字符串

日志过滤器

get_logs 直接接受 alloy 的 Filter：

let filter = Filter::new()
    .from_block(60_000_000u64)
    .to_block(BlockNumberOrTag::Latest)
    .address(address!("0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270"))
    .event_signature(transfer_topic);

let logs = client.get_logs(&filter).await?;

use orbitflare_evm_sdk::{primitives::{address, b256}, BlockNumberOrTag, Filter, PolygonRpcClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = PolygonRpcClient::builder()
        .url("https://ams.poly.rpc.orbitflare.com")
        .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
        .build()?;

    let transfer_topic =
        b256!("ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef");

    let filter = Filter::new()
        .from_block(60_000_000u64)
        .to_block(BlockNumberOrTag::Latest)
        .address(address!("0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270"))
        .event_signature(transfer_topic);

    let logs = client.get_logs(&filter).await?;
    println!("{} logs", logs.len());
    Ok(())
}

合约调用与交易

call 与 estimate_gas 接受 alloy 的 TransactionRequest。要发送交易，先用 alloy（alloy-signer、alloy-network）构建并签名，再通过 SDK 广播：

let hash = client.send_raw_transaction(&signed_tx_rlp).await?;
let receipt = client.get_transaction_receipt(hash).await?;

任意方法

request 按名称调用任意 RPC 方法——SDK 构建 JSON-RPC 信封，处理重试与故障转移，并返回 result 字段。request_raw 发送原始 JSON-RPC 请求体字符串。

use serde_json::json;

let syncing = client.request("eth_syncing", json!([])).await?;

WebSocket

启用 ws 特性。.build() 为异步——在返回前会建立连接。

let client = PolygonWsClient::builder()
    .url("wss://ams.poly.rpc.orbitflare.com")
    .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
    .build()
    .await?;

let mut heads = client.new_heads_subscribe().await?;

use orbitflare_evm_sdk::{PolygonWsClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = PolygonWsClient::builder()
        .url("wss://ams.poly.rpc.orbitflare.com")
        .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
        .build()
        .await?;

    let mut heads = client.new_heads_subscribe().await?;

    while let Some(head) = heads.next().await {
        println!("block {} (gas used {})", head.number, head.gas_used);
    }
    Ok(())
}

构建器与 RPC 构建器共享 .urls()、.fallback_url(s)、.api_key() 与 .retry()；WebSocket 特有的选项为 .ping_interval_secs(n)（默认 10）与 .max_missed_pongs(n)（默认 3）。

方法	产出
`new_heads_subscribe()`	每个新区块一条 `Header`
`logs_subscribe(&Filter)`	匹配过滤器的 `Log`
`new_pending_transactions_subscribe()`	`B256` 交易哈希

重连

若连接断开，后台任务会以指数退避重连，并自动重新订阅所有活跃订阅。你的 .next() 调用会持续工作。失效连接通过主动 ping/pong 检测。

Polygon gRPC

Polygon 暴露了一个 Bor gRPC 接口，用于低开销地访问区块、区块头与收据。启用 grpc 特性。gRPC 运行于明文 HTTP/2；通过 .api_key() 用令牌认证（作为 x-token 发送），或使用 IP 白名单。

let client = PolygonGrpcClient::builder()
    .url("http://your-bor-grpc-endpoint:3131")
    .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
    .build()?;

let header = client.header_by_number(BlockNumber::Latest).await?;

use orbitflare_evm_sdk::grpc::{BlockNumber, PolygonGrpcClient};
use orbitflare_evm_sdk::Result;

#[tokio::main]
async fn main() -> Result<()> {
    let client = PolygonGrpcClient::builder()
        .url("http://your-bor-grpc-endpoint:3131")
        .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
        .build()?;

    let header = client.header_by_number(BlockNumber::Latest).await?;
    let author = client.author(header.number).await?;

    println!("block {} authored by {author}", header.number);
    Ok(())
}

方法	返回值
`header_by_number(impl Into<BlockNumber>)`	`Header`
`block_by_number(impl Into<BlockNumber>)`	`Block`
`transaction_receipt(B256)`	`Receipt`
`bor_block_receipt(B256)`	`Receipt`
`author(impl Into<BlockNumber>)`	`Address`
`td_by_hash(B256)` / `td_by_number(...)`	`u64` 总难度
`root_hash(start, end)`	`String`
`block_info_in_batch(start, end)`	`Vec<BlockInfo>`

H160/H256 值可通过 ToAlloy trait 转换为 alloy 的 Address/B256。

自定义链

任意 EVM 链都可使用：为一个标记类型实现 Chain，并让泛型 RpcClient<C> 指向其 URL。CHAIN_ID 是元数据（可通过 RpcClient::<C>::chain_id_const() 获取）；它不会限制请求。

struct Base;

impl Chain for Base {
    const CHAIN_ID: u64 = 8453;
}

let client = RpcClient::<Base>::builder()
    .url("https://mainnet.base.org")
    .build()?;

use orbitflare_evm_sdk::{Chain, RpcClient, Result};

struct Base;

impl Chain for Base {
    const CHAIN_ID: u64 = 8453;
}

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClient::<Base>::builder()
        .url("https://mainnet.base.org")
        .build()?;

    println!("chain id: {}", client.get_chain_id().await?);
    println!("block:    {}", client.get_block_number().await?);
    Ok(())
}

Arbitrum 与 Nitro 区块字段

Robinhood Chain 是 Arbitrum Nitro，因此其区块携带额外字段（l1BlockNumber、sendRoot、sendCount），而标准 EVM 区块类型会丢弃这些字段。SDK 会保留它们，并通过 NitroBlockExt 暴露类型化的访问器。其他任何非标准字段仍可在 block.other 上获取。

let block = client
    .get_block_by_number(client.block_tag(), false)
    .await?
    .expect("block");

let l1 = block.l1_block_number();
let send_root = block.send_root();

use orbitflare_evm_sdk::{NitroBlockExt, RobinhoodRpcClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = RobinhoodRpcClient::builder()
        .url("https://robinhood.rpc.orbitflare.com")
        .api_key("ORBIT-XXXXXX-NNNNNN-NNNNNN")
        .build()?;

    let block = client
        .get_block_by_number(client.block_tag(), false)
        .await?
        .expect("block");

    println!("l1 block:   {:?}", block.l1_block_number());
    println!("send root:  {:?}", block.send_root());
    println!("send count: {:?}", block.send_count());
    Ok(())
}

Arbitrum 预编译合约（ArbSys、ArbGasInfo 等）可像任何合约一样通过 call() 访问。

端点

没有默认端点。用 .url() 为每个客户端设置 URL，或通过环境变量设置。解析顺序：构建器上的 .url()，然后是环境变量。

链	RPC	WebSocket
Polygon	`https://ams.poly.rpc.orbitflare.com`	`wss://ams.poly.rpc.orbitflare.com`
BNB Smart Chain	`https://bsc.rpc.orbitflare.com`	`wss://bsc.rpc.orbitflare.com`
Robinhood Chain	`https://robinhood.rpc.orbitflare.com`	`wss://robinhood.rpc.orbitflare.com`

请使用你 OrbitFlare 控制台中的确切端点。

环境变量

变量	使用者	用途
`ORBITFLARE_LICENSE_KEY`	RPC、WebSocket、gRPC	附加到端点 URL 的 API 密钥（gRPC 用 `x-token`）
`ORBITFLARE_RPC_URL`	RPC	未调用 `.url()` 时使用的端点
`ORBITFLARE_WS_URL`	WebSocket	未调用 `.url()` 时使用的端点
`ORBITFLARE_GRPC_URL`	gRPC	未调用 `.url()` 时使用的端点

源码

SDK 为开源：github.com/orbitflare/orbitflare-evm-sdk-rs

开始使用

产品

解决方案

数据获取

RPC

数据流

Apex

交易 API

支持的链

安装

RPC

构建器方法

可用方法

日志过滤器

合约调用与交易

任意方法

WebSocket

订阅

重连

Polygon gRPC

自定义链

Arbitrum 与 Nitro 区块字段

端点

环境变量

源码

​支持的链

​安装

​RPC

​构建器方法

​可用方法

​日志过滤器

​合约调用与交易

​任意方法

​WebSocket

​订阅

​重连

​Polygon gRPC

​自定义链

​Arbitrum 与 Nitro 区块字段

​端点

​环境变量

​源码

支持的链

安装

RPC

构建器方法

可用方法

日志过滤器

合约调用与交易

任意方法

WebSocket

订阅

重连

Polygon gRPC

自定义链

Arbitrum 与 Nitro 区块字段

端点

环境变量

源码