ERPC SDK for Rust
Async Rust client for ERPC. The crate covers standard Solana, Ethereum, and Avalanche C/P/X-chain JSON-RPC, indexed asset and history RPC, leader and analytics RPC, WebSocket subscriptions, price REST and server-sent events, account usage, and scoped Cloud reads.
[]
= "0.8"
= "1"
= { = "1", = ["macros", "rt-multi-thread"] }
The minimum supported Rust version is 1.85.
For a fresh consumer on Rust 1.85, use Edition 2024, set
rust-version = "1.85", and configure Cargo resolver 3 in the root workspace
so dependency selection is MSRV-aware. See the Edition 2024 resolver
guide,
the resolver reference,
and the str implementation source.
For example, a fresh consumer root can declare:
[]
= "2024"
= "1.85"
[]
= "3"
Compatibility note (2026-09-17): upstream yoke-derive 0.8.3 has no
rust-version and uses str::from_utf8, which stabilized in Rust 1.87, so the
resolver cannot filter it. If a Rust 1.85 fresh resolution selects it, apply
the consumer-lock-only workaround
cargo +1.85.0 update -p yoke-derive@0.8.3 --precise 0.8.2, keep the
application's Cargo.lock, and verify with --locked (for example,
cargo +1.85.0 check --locked). The tested pair is yoke 0.8.3 with
yoke-derive 0.8.2; the historical published erpc-sdk 0.8.0 crate was verified on Rust
1.85 with this consumer lock. This guidance changes consumer
dependency selection only; an untouched fresh lock compiles on stable Rust
1.93. Do not copy the SDK lock, broadly downgrade
unrelated crates, or edit SDK dependencies.
Quick start
use ;
async
RPC helpers return an inert PendingRpcRequest. Network I/O starts when
send() is awaited. Positional methods accept any serializable tuple, array,
or vector; named indexed-asset methods accept serializable structs or JSON
objects. The wire method names remain unchanged.
Wallets and signing
ErpcClient and MayanSwiftV2BridgeClient do not load wallet keys or sign
locally. Their configuration has no wallet, private-key, or signer field.
sender, from, swapper_address, and fee_payer are public addresses and
do not grant signing authority. ERPC API keys, direct-RPC headers, and the
Mayan builder_api_key authenticate services; they are separate from wallet
private keys.
prepare_exact_input_swap and build_unsigned return unsigned transaction
data. The caller reviews the chain, target, amount, allowance, and expiry,
then selects the wallet or hardware signer, nonce and fee policy, and fresh
Solana blockhash as applicable. The external signer signs the reviewed bytes;
the caller can broadcast the serialized result through
erpc.ethereum.rpc.eth_send_raw_transaction(...).send() or
erpc.solana.rpc.send_transaction(...).send(). .send() performs the RPC
request and does not perform cryptographic signing. An eth_sign_transaction
call, when available, is an upstream RPC operation and does not prove that the
node manages a wallet. Confirmation and settlement remain separate caller
responsibilities.
See the shared wallets and signing guidance
and the TypeScript example
for an initialized external-signer flow. Browser and hardware-wallet
integrations keep keys inside the signer; the optional TypeScript ethers and
@solana/web3.js examples are consumer integrations, not Rust SDK
dependencies.
Direct RPC endpoints
Use RpcEndpointConfig when a chain should send JSON-RPC calls to a caller-owned
node. The caller supplies the final HTTP RPC URL as the complete request target,
including any path and query; the SDK does not add an eRPC route or API key and
does not follow HTTP redirects. for_rpc() allows a keyless client when at
least one direct endpoint is configured.
Direct RPC endpoint overrides were introduced in 0.8.0 and require that
package when installed from a registry. The published erpc-sdk 0.7.0 package
does not include them; check the package version badge and the latest GitHub
release for live
publication status.
# use ;
# async
Subscriptions require an explicit independent websocket_url when using a
direct endpoint. Endpoint-scoped HTTP headers apply to direct HTTP JSON-RPC
requests only and are not forwarded to the independent WebSocket connection.
# use ;
# async
For Solana transaction-version options and response handling, see the Solana v1 guide.
Namespaces
| Namespace | Purpose |
|---|---|
erpc.solana.rpc |
Standard Solana JSON-RPC |
erpc.solana.das |
Indexed assets and tokens |
erpc.solana.history |
Address transactions and transfers |
erpc.solana.leaders |
Leader slots and validator information |
erpc.solana.analytics |
Epoch, slot, program, and TPS analytics |
erpc.solana.subscriptions |
Enhanced WebSocket subscriptions |
erpc.ethereum.rpc |
Standard Ethereum JSON-RPC |
erpc.ethereum.subscriptions |
Ethereum WebSocket subscriptions |
erpc.avalanche.rpc |
Avalanche C-Chain EVM-compatible JSON-RPC |
erpc.avalanche.subscriptions |
Avalanche C-Chain WebSocket subscriptions |
erpc.avalanche.avax |
C-Chain AVAX atomic transaction API |
erpc.avalanche.x_chain |
X-Chain API |
erpc.avalanche.p_chain |
P-Chain API |
erpc.avalanche.proposer_vm |
P-Chain proposer VM API |
erpc.avalanche.info |
Network upgrade information |
erpc.avalanche.index |
C/P/X block and X transaction indexes |
erpc.price |
Price metadata, updates, and SSE streams |
erpc.account |
Token balance |
erpc.usage |
Masked monthly API-key usage |
Every JSON-RPC namespace also exposes request, raw, and batch for typed
results and forward-compatible methods. Avalanche uses the Ethereum-compatible
typed catalog and defaults to https://ava-rpc.erpc.global; the SDK uses its
/ava HTTP route and /ava-ws WebSocket route. Native namespaces provide
snake_case convenience methods with named parameters, while Index calls use
explicit chain/container paths. Override the base URL with
ErpcClientConfig::with_avalanche_endpoint when needed.
let p_height = erpc.avalanche.p_chain.get_height.send.await?;
let indexed_tx = erpc.avalanche.index.x_chain_transactions
.get_container_by_id?
.send
.await?;
Batch requests
# use ;
# async
The SDK sends one caller batch as one server batch, restores caller order when responses arrive out of order, accepts at most 256 calls, and rejects invalid mixed or unsupported batches locally. It never silently splits a batch.
Subscriptions
# use ErpcClient;
# async
Solana provides account_subscribe, transaction_subscribe, and
raw_subscribe. Dropping an HTTP request cancels its future; an explicit
CancellationToken can also be supplied through RequestOptions.
Cloud reads
# use ;
# async
Cloud configuration accepts HTTPS endpoints and local HTTP endpoints for testing. It retains only the access token supplied by the caller and does not implement interactive authorization or refresh-credential storage.
Non-streaming price reads and every Cloud read also provide a _with variant
that accepts an optional CancellationToken. The timeout configured with
ErpcClientConfig::with_timeout or ErpcCloudClientConfig::with_timeout
covers both response headers and the complete response body.
Offline token catalog
The crate ships a generated token catalog that needs no client, API key, or network request. Deployment aliases contain immutable deployment IDs, while the lookup functions return the complete canonical records and preserve every lifecycle status.
use ;
let usdc_id = USDC;
let usdc = get_token_deployment.expect;
assert_eq!;
let mixed_case = "0xa0B86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
let same_usdc = find_token_deployment_by_address;
assert_eq!;
Use find_token_deployments_by_symbol when a symbol has multiple deployments,
and list_token_deployments(Some(chain_id), Some("EUR")) for a chain and
stable-currency filter. See the canonical token registry
for the source records, evidence, and generation workflow.
Offline token rankings
The crate also exposes an immutable ranking snapshot through
list_token_rankings(chain_id). It is offline and returns an empty Vec for
an empty or unknown chain ID. Consult the bundled ranking metadata for its
current status, metric, as-of time, source IDs, and per-chain coverage;
coverage can be partial and unranked deployments remain explicit.
use ;
let ethereum_rankings = list_token_rankings;
Read the bundled ranking metadata for the current status, metric, as-of
time, source IDs, and per-chain coverage before presenting a result as current;
an empty result can reflect the requested chain or the metadata state. When
configured, the native metric is onchain-total-supply-value-native: values are
rational atomic native units and quote deployment IDs identify ETH, AVAX, or
SOL. A circulating market-cap estimate is not implied by this metric.
DEX catalog and exact-input quotes
The published 0.7.0 package includes the reviewed DEX and swap exports. The
offline DEX and pool catalog is available in that history baseline. Unsigned
EVM preparation and simulation below were introduced in 0.8.0 and require
that package. The six lookup functions
(get_dex_deployment, get_pool_definition,
find_pool_definition_by_address, find_pool_definitions_by_pair,
list_pool_definitions, and get_native_wrap_definition) never access an RPC
endpoint. Chain-qualified alias constants are available under dexes and
pools.
The configured client provides direct asynchronous exact-input quotes for the two currently reviewed EVM constant-product pools. The request uses decimal base-unit strings and optional block freshness limits; the result reports the block snapshot and decimal output. Quote eligibility is limited to the exact Ethereum Uniswap V2 USDC/WETH and Avalanche LFJ WAVAX/USDC capability tuples; newly discovered pools remain available for lookup, monitoring, and rankings until they receive a separate quote capability review.
use ;
async
Quotes read the selected pool through the configured Ethereum or Avalanche transport and use a single canonical block selector for the seven code and state reads. Solana Orca and Raydium records are lookup-only in this release; the quote API does not build, sign, simulate, or send transactions.
Unsigned EVM preparation and simulation (introduced in 0.8.0)
The two reviewed EVM pools also support local calldata construction and configured-RPC simulation. Preparation performs a new 11-call quote followed by five router preflight calls pinned to the quote block. Simulation performs that preparation, checks the ERC20 allowance, simulates the router call, and checks the final block freshness.
# use ;
# use ;
# async
prepared.transaction is a chain-bound SDK envelope. Convert or destructure
its chain_id, from, to, data, and value into the wallet library's
transaction type after applying that wallet's own nonce, fee, and signing
policy. The SDK does not sign, send, create approvals, or choose an unlimited
allowance policy; the caller's wallet controls allowance changes and
broadcasting.
Optional Mayan Swift v2 bridge (EURC in 0.8.1; USDC source addition unreleased)
MayanSwiftV2BridgeClient is a separate, explicit client. The published
erpc-sdk 0.8.1 package supports the two reviewed native issued EURC
directions: Ethereum (deployment-0011) and Solana (deployment-0013). This
source tree also contains the reviewed native USDC directions, Ethereum
(deployment-0008) and Solana (deployment-0010); that USDC addition is
unreleased and is not included in the published 0.8.1 package. The 0.8.1
Workers patch also does not include the native USDC or local-builder additions.
These are
external-provider intent routes, rather than Circle CCTP or RPC-only swap
routes.
EURC uses Mayan's hosted quote, source-swap, and transaction-builder services, plus its solver, relayer, Wormhole Guardian, and explorer dependencies. Direct USDC routes use the hosted quote and transaction-builder services, solvers, relayers, Wormhole Guardian, and explorer; they do not claim a Jupiter or hosted 0x dependency.
The bridge client owns a no-redirect HTTP client and sends only its
allowlisted accept, content-type, and build-only x-api-key headers. Its
configuration accepts provider endpoints, the optional builder key, the quote
validity margin, timeout, and unauthenticated-build opt-in; the defaults are
https://tx-builder.mayan.finance for quote/build and
https://explorer-api.mayan.finance/v3 for indexed status. Both endpoints are
customizable. The builder key is a separate Mayan build-only credential; quote
and status requests never receive it or an eRPC credential. The default SDK
policy requires a builder key for builds; with_allow_unauthenticated_build
is an explicit caller opt-in that permits a keyless HTTP attempt at any
configured endpoint, including the default endpoint; it does not guarantee
that the server will authorize the request. Official Mayan quote API key
documentation and
the pinned transaction-builder authentication
section
describe the provider key as optional for quote/build. A host recheck at
2026-09-17T11:27:34.223Z returned HTTP 200 for four EURC/USDC quotes without
keys; default builds made zero network requests, while explicit anonymous
builds reached /build and returned HTTP 401 UNAUTHORIZED. The deployed
provider revision is unknown, and no authenticated build or settlement
evidence was captured. The client does not accept arbitrary headers or a
prebuilt HTTP client.
# use ;
# async
The same request shape accepts the unreleased USDC tuple by using
deployment-0008 to deployment-0010 (or the reverse direction). For direct
USDC quotes, source_swap.required is false, input_token_deployment_id
and the intermediate token identify the native source USDC, and
router_kind/router_address are null. These JSON keys remain present.
Rust represents the nullable router fields as Option<String>, so consumers
whose source types currently use non-null strings must handle None before
using the unreleased USDC addition. Existing EURC router values remain
unchanged.
Local unsigned construction (source-tree addition)
The source tree also exposes prepare_source_swap and
build_local_unsigned for the reviewed four-route local construction path.
Pass a normalized quote, public source and destination addresses, and a fresh
16-byte public order_nonce to preparation, then pass the returned plan to the
local builder with an explicitly configured source-chain RPC:
# use ;
# async
The matching solana_rpc field is required for Solana-source routes. EURC
preparation makes one anonymous request to source_swap_endpoint; direct
USDC uses { kind: "none" } and makes no source-swap request. Local builds
perform bounded read-only source RPC checks and construct unsigned EVM or
Solana bytes locally. They never fall back to hosted /build, read service or
wallet keys, sign, approve, submit, broadcast, or claim settlement. The
returned public addresses identify the account that an external signer must
authorize; service API keys and RPC headers authenticate services and are not
signer keys. See the root wallets and signing guidance
and the TypeScript example for signer and broadcast responsibility.
Quotes preserve the provider's signed JSON object, including unknown fields and numeric lexemes, for the builder. Build output is structurally checked and marked as locally unverified for quote signatures, transaction semantics, and settlement. The bridge client never signs, approves, submits, broadcasts, or constructs refund transactions; wallet and provider policy remains with the caller.
Safety boundaries
- API keys and access tokens are redacted from configuration debug output, public endpoints, transport errors, and JSON-RPC error data.
- State-changing calls, including transaction submission, are never retried automatically.
- REST and JSON-RPC server boundaries remain explicit.
- Unknown methods remain available through
rawwithout pretending they are part of the typed compatibility catalog.
The crate uses Rustls and does not require a platform TLS library.