Mesmo

Rust bindings for Cardano Client Lib via the Mesmo native library.

Part of the Mesmo project. See the top-level README for the full API reference and docs/quicktx.md for transaction building.

Requirements

• Rust (stable, 2021 edition).

The native library is fetched automatically at build time — no separate download and no MESMO_LIB_PATH / DYLD_LIBRARY_PATH / LD_LIBRARY_PATH needed.

Installing

cargo add mesmo

build.rs sources libmesmo.* for your target — in priority order: MESMO_LIB_PATH (a dir), the in-tree monorepo build, or downloaded from the GitHub release — then stages it and sets an rpath, so both linking and runtime "just work" with no environment variables.

• Override the release tag it fetches from with MESMO_LIB_VERSION.
• crates.io can't host the ~50 MB binary, so the crate carries only source + build.rs; the lib is pulled at build time (needs network on the first build). See ADR-0012.

Examples

From a checkout, cargo run --example account — no env vars required.

Building against a locally built libmesmo from a checkout: see BUILD_FROM_SOURCE.md.

The examples/ directory contains:

Quick start

use mesmo::{Mesmo, Network};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let lib = Mesmo::new()?; // loads libmesmo, starts a GraalVM isolate

    // Managed account handle (ADR-0016): info is public data only.
    let account = lib.accounts().create(Network::Testnet)?;
    println!("{}", account.info()?["base_address"]); // addr_test1...
    println!("{}", account.export_recovery_phrase()?); // 24-word phrase — one-shot
    Ok(())
} // Mesmo's Drop tears down the isolate

API surface

A Mesmo exposes namespaced accessors (all offline operations): lib.accounts(), .address(), .crypto(), .tx(), .plutus(), .script(), .quicktx().

Most methods return Result<String> where the String is JSON — parse it with serde_json.

Transactions are defined as a TxPlan YAML document and built fully offline — you supply the UTXOs and protocol parameters (as serde_json::Value):

let result = lib.quicktx().build(&yaml, &utxos, &protocol_params)?; // -> TxResult { tx_cbor, tx_hash, fee }

Methods that need a network take the Network enum — Network::Mainnet or Network::Testnet — so a transposed argument is a compile error rather than a key silently derived on the wrong network. Errors are mesmo::MesmoError.

Network is not Cardano's on-chain network id. Its discriminants are CCL's own enum ordinals (Mainnet = 0, Testnet = 1). Cardano's on-chain network id is the other way round — mainnet = 1, testnet = 0 — so an account created with Network::Mainnet has an address whose network_id is 1. The network_id field returned by lib.address().info() is that genuine on-chain value, not an ordinal from this enum.

Chain-data providers (optional)

build is offline — you supply the UTXOs and protocol parameters. Enable the providers feature for optional HTTP helpers (via ureq) that fetch those for you, keeping the native library offline and provider-free:

mesmo = { version = "0.1", features = ["providers"] }

use mesmo::providers::BlockfrostProvider; // or YaciProvider

let provider = BlockfrostProvider::new("proj_id", "preprod")?; // or YaciProvider::default()
let result = lib.quicktx().build_with(&yaml, &provider, &[sender], 0, None)?;

Plug in any backend (Koios, Ogmios, …) by implementing the ChainDataProvider trait (utxos, protocol_params). UTXO selection is handled inside Mesmo — a provider only returns all UTXOs at the address.

Transaction evaluators (optional)

A Plutus build needs each redeemer's execution units. Mesmo computes them offline with Scalus when you supply none — so a script build just works, no evaluation step (pass None):

let result = lib.quicktx().build_with(&yaml, &provider, &[sender], 0, None)?; // Scalus computes the units

To use a remote evaluator instead (e.g. an authoritative fallback), pass a TransactionEvaluator; build_with runs a two-pass (draft → evaluate → rebuild). libmesmo never makes HTTP calls (ADR-0013), so remote evaluation lives here in the wrapper (also behind the providers feature):

use mesmo::providers::BlockfrostEvaluator;

let evaluator = BlockfrostEvaluator::new("proj_id", "preprod")?;
let result = lib.quicktx().build_with(&yaml, &provider, &[sender], 0, Some(&evaluator))?;

Plug in any evaluator (Ogmios, …) by implementing the TransactionEvaluator trait (evaluate). To supply units you computed yourself, call build directly. See examples/evaluator.rs.