Crate mina_archive_sdk

Expand description

Rust SDK for Mina Protocol’s Archive Node GraphQL endpoint defined by o1-labs/Archive-Node-API.

Companion to the daemon-targeting mina-sdk crate. This crate targets the separate archive endpoint — events, actions, blocks, network state.

§Quick start

Archive-Node-API serves GraphQL at the root path /, not /graphql. Pass the base URL as-is — the SDK never appends a path, so a URL ending in /graphql returns 404.

use mina_archive_sdk::{ArchiveClient, BlockStatusFilter, EventFilterOptionsInput};

let client = ArchiveClient::new("https://archive.example/");
let events = client.get_events(
    EventFilterOptionsInput::for_address("B62q...")
        .status(BlockStatusFilter::Canonical)
        .from(100)
        .to(200),
).await?;

for group in events {
    let height = group.block_info.map(|b| b.height).unwrap_or(-1);
    let count = group.event_data.map(|d| d.len()).unwrap_or(0);
    println!("block {height}: {count} event(s)");
}

§Runtime requirements

This crate requires a Tokio runtime with the time driver enabled. reqwest’s per-request timeout needs it, so on a runtime built without enable_time() every query panics with “A Tokio 1.x context was found, but timers are disabled”. #[tokio::main] and #[tokio::test] enable it; a hand-built Builder::new_current_thread() does not unless you say so.

let runtime = tokio::runtime::Builder::new_current_thread()
    .enable_time()
    .enable_io()
    .build()
    .unwrap();

§Currency

Coinbase / fee / user-command amounts are returned as nanomina decimal strings. Use Currency for safe parsing and arithmetic:

use mina_archive_sdk::Currency;

let coinbase = Currency::from_graphql("720000000000").unwrap();
assert_eq!(coinbase.mina(), "720.000000000");

let fee = Currency::from_mina("0.01").unwrap();
let total = coinbase + fee;

§Error handling

All fallible operations return Result<T>, which uses Error. Match on variants:

use mina_archive_sdk::{ArchiveClient, EventFilterOptionsInput, Error};

let client = ArchiveClient::new("https://archive.example/");
match client.get_events(EventFilterOptionsInput::for_address("B62q...")).await {
    Ok(events) => println!("got {} groups", events.len()),
    Err(Error::Graphql { messages, .. }) => eprintln!("server rejected the query: {messages}"),
    Err(Error::Connection { attempts, .. }) => eprintln!("archive unreachable after {attempts} tries"),
    Err(e) => eprintln!("error: {e}"),
}

Re-exports§

pub use error::codes;
pub use error::Error;
pub use error::GraphqlErrorEntry;
pub use error::Result;

Modules§

error
queries: Hand-written GraphQL query strings. Each maps 1:1 to a method on ArchiveClient. For narrower selections, send a custom query through ArchiveClient::query.

Structs§

ActionData
ActionFilterOptionsInput: Filter actions from a specific account.
ActionOutput
ActionStates
ArchiveClient: Client for querying a Mina Archive Node GraphQL endpoint.
Block
BlockInfo
BlockQueryInput: Filter blocks by height, date, or canonical status.
BlockTransactions: Transactions attached to a block.
ClientConfig: Configuration for the Archive Node client.
Currency: A Mina currency amount stored as nanomina (the atomic unit).
EventData
EventFilterOptionsInput: Filter events from a specific account.
EventOutput
FeeTransfer
GetBlocksOptions: Options for ArchiveClient::get_blocks. All fields are optional.
MaxBlockHeightInfo
NetworkStateOutput
QueryBuilder: Builder returned by ArchiveClient::query.
Response: The result of one GraphQL call, keeping data and errors together.
TransactionInfo
UserCommand
VerificationKeyUpdate: An applied account update that set a verification key.
VerificationKeyUpdateFilterInput: Filter for verificationKeyUpdates.
ZkAppCommand

Enums§

BlockSortBy: Sort direction for block queries.
BlockStatusFilter: Filter for the consensus status of a block.

Constants§

SCHEMA_VERSION: The Archive-Node-API schema version (MAJOR.MINOR) this crate speaks.