tx3-sdk (Rust)

The official Rust SDK for Tx3 — a DSL and protocol suite for defining and executing UTxO-based blockchain transactions declaratively. Load a compiled .tii protocol, bind parties and signers, and drive the full transaction lifecycle (resolve, sign, submit, confirm) via the Transaction Resolve Protocol (TRP).

This repository is organized as a monorepo. The publishable crate lives in sdk/.

What is Tx3

Tx3 is a domain-specific language and protocol suite for declarative, type-safe UTxO transactions. Authors write .tx3 files describing parties, environment, and transactions; the toolchain compiles them to .tii artifacts that this SDK loads at runtime to drive the resolve → sign → submit → wait lifecycle through a TRP server. See the Tx3 docs for project context.

Installation

cargo add tx3-sdk

Or in Cargo.toml:

[dependencies]
tx3-sdk = "0.12"
serde_json = "1"
tokio = { version = "1", features = ["full"] }

Quick start

use serde_json::json;
use tx3_sdk::{CardanoSigner, Party, PollConfig};

#[tokio::main]
async fn main() -> Result<(), tx3_sdk::Error> {
    let signer = CardanoSigner::from_mnemonic(
        "addr_test1...",
        "word1 word2 ... word24",
    )?;

    // 1. Load a compiled .tii protocol and assemble the client through the builder.
    let tx3 = tx3_sdk::tii::Protocol::from_file("./examples/transfer.tii")?
        .client()
        .trp_endpoint("https://trp.example.com")
        .with_profile("preprod")
        .with_party("sender", Party::signer(signer))
        .with_party("receiver", Party::address("addr_test1..."))
        .build()?;

    // 2. Build, resolve, sign, submit, and wait for confirmation
    let status = tx3
        .tx("transfer")?
        .arg("quantity", json!(10_000_000))
        .resolve()
        .await?
        .sign()?
        .submit()
        .await?
        .wait_for_confirmed(PollConfig::default())
        .await?;

    println!("Confirmed at stage: {:?}", status.stage);
    Ok(())
}

All fallible validation — TRP endpoint present, profile declared, every bound party declared — happens inside build(), which returns Error::MissingTrpEndpoint, Error::UnknownProfile, or Error::UnknownParty. Optional setters never return Result, so chains stay fluent up to build(). Profile selection is builder-only: there is no profile-switching method on the built client. Switching profiles requires a new builder.

Concepts

Advanced usage

Skipping the runtime .tii (codegen flow)

If you've run trix codegen to generate typed bindings, your generated Client embeds the per-transaction TIR envelopes and per-profile data at codegen time — no .tii artifact at runtime. Under the hood it seeds the same builder via Tx3ClientBuilder::from_parts(transactions, profiles, known_parties) and routes typed per-party setters through with_party_unchecked. You can also call from_parts directly from hand-written code:

use std::collections::{HashMap, HashSet};
use tx3_sdk::{Party, Tx3ClientBuilder};

let tx3 = Tx3ClientBuilder::from_parts(transactions, profiles, HashSet::new())
    .trp_endpoint("https://trp.example.com")
    .with_party_unchecked("sender", Party::signer(signer))
    .build()?;

Adding TRP headers

with_header(key, value) attaches a header to every TRP request. Combine with trp_endpoint (or trp(ClientOptions { ... })) — with_header does not supply an endpoint on its own.

let tx3 = protocol
    .client()
    .trp_endpoint("https://trp.example.com")
    .with_header("dmtr-api-key", api_key)
    .with_profile("preprod")
    .with_party("sender", Party::signer(signer))
    .build()?;

One-off environment overrides

with_env_value(key, value) overlays a single environment value on top of the selected profile's environment, merged at resolve time (override wins). Useful for adjusting a network selector or other env without forking a new profile.

let tx3 = protocol
    .client()
    .trp_endpoint("https://trp.example.com")
    .with_profile("preprod")
    .with_env_value("tax", json!(2_500_000))
    .with_party("sender", Party::signer(signer))
    .build()?;

Low-level TRP client

If you don't want the facade, drive TRP directly:

use tx3_sdk::trp::{Client, ClientOptions, ResolveParams};

let client = Client::new(ClientOptions {
    endpoint: "https://trp.example.com".to_string(),
    headers: None,
});

// build ResolveParams and call client.resolve(...).await

Custom Signer

Implement the Signer trait. sign receives a SignRequest carrying both the tx hash and the full tx CBOR; hash-based signers read tx_hash_hex, tx-based signers (e.g. wallet bridges) read tx_cbor_hex.

use tx3_sdk::{SignRequest, Signer};
use tx3_sdk::trp::TxWitness;

struct MySigner { /* ... */ }

impl Signer for MySigner {
    fn address(&self) -> &str { "addr_test1..." }

    fn sign(
        &self,
        request: &SignRequest,
    ) -> Result<TxWitness, Box<dyn std::error::Error + Send + Sync>> {
        // sign request.tx_hash_hex with your key
        unimplemented!()
    }
}

Manual witness attachment

When a witness is produced outside any registered Signer — for example by an external wallet app or a remote signing service — resolve the transaction first, hand the resolved hash (or full tx CBOR) to the wallet, then attach the returned witness before sign():

let resolved = tx3
    .tx("transfer")?
    .arg("quantity", json!(10_000_000))
    .resolve()
    .await?;

// Hand `resolved.hash` (or `resolved.tx_hex`) to the external wallet
// and get back a witness. The wallet needs the resolved tx to sign.
let witness: tx3_sdk::trp::TxWitness = /* sign resolved.hash with external wallet */;

let status = resolved
    .add_witness(witness)
    .sign()?
    .submit()
    .await?
    .wait_for_confirmed(PollConfig::default())
    .await?;

add_witness may be called any number of times; manual witnesses are appended after registered-signer witnesses in attach order.

Tx3 protocol compatibility

• TRP protocol version: v1beta0
• TII schema version: v1beta0

Testing

• Unit tests are co-located with modules via #[cfg(test)].
• End-to-end (e2e) tests live under sdk/tests/ and run as Cargo test targets.

# from rust-sdk/sdk
cargo test --lib
cargo test --test smoke --test codegen --test error_cases --test happy_path

License

Apache-2.0