# Mesmo
Rust bindings for [Cardano Client Lib](https://github.com/bloxbean/cardano-client-lib)
via the Mesmo native library.
> Part of the [Mesmo](https://github.com/bloxbean/mesmo) project. See the
> [top-level README](https://github.com/bloxbean/mesmo#readme) for the full API reference and
> [`docs/quicktx.md`](https://github.com/bloxbean/mesmo/blob/main/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
```bash
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](https://github.com/bloxbean/mesmo/blob/main/docs/adr/0012-native-lib-bundled-in-wrapper-packages.md).
## 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](https://github.com/bloxbean/mesmo/blob/main/wrappers/rust/BUILD_FROM_SOURCE.md).
The [`examples/`](https://github.com/bloxbean/mesmo/tree/main/wrappers/rust/examples) directory contains:
| [`account`](https://github.com/bloxbean/mesmo/blob/main/wrappers/rust/examples/account.rs) | Create an account, restore from mnemonic, derive keys and a DRep ID |
| [`primitives`](https://github.com/bloxbean/mesmo/blob/main/wrappers/rust/examples/primitives.rs) | Mnemonics, Blake2b hashing, Ed25519 signing, address parsing/validation |
| [`transaction`](https://github.com/bloxbean/mesmo/blob/main/wrappers/rust/examples/transaction.rs) | Build an unsigned payment **offline** (QuickTx) and sign it — no node/DevKit needed |
## Quick start
```rust
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](https://github.com/bloxbean/cardano-client-lib)
**YAML** document and built fully offline — you supply the UTXOs and protocol parameters
(as `serde_json::Value`):
```rust
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:
```toml
mesmo = { version = "0.1", features = ["providers"] }
```
```rust
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`):
```rust
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](https://github.com/bloxbean/mesmo/blob/main/docs/adr/0013-transaction-evaluators.md)), so remote evaluation
lives here in the wrapper (also behind the `providers` feature):
```rust
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`.