TX3 Rust SDK

Ergonomic Rust SDK for interacting with UTxO-based blockchains using the Tx3 toolkit.

What is TX3?

TX3 is a domain-specific language (DSL) and protocol suite for defining and executing UTxO-based blockchain transactions in a declarative, type-safe manner. It abstracts the complexity of UTXO management and transaction construction while maintaining flexibility for complex DeFi and smart contract interactions.

Quick start

Add the SDK to your project:

[dependencies]
tx3-sdk = "0.9"
serde_json = "1"

Full lifecycle (recommended facade)

use serde_json::json;
use tx3_sdk::trp::{Client, ClientOptions};
use tx3_sdk::{CardanoSigner, Party, PollConfig, Tx3Client};

let signer = CardanoSigner::from_mnemonic(
    "addr_test1...",
    "word1 word2 ... word24",
)?;

let protocol = tx3_sdk::tii::Protocol::from_file("./examples/transfer.tii")?;

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

let tx3 = Tx3Client::new(protocol, trp)
    .with_profile("preprod")
    .with_party("sender", Party::signer(signer))
    .with_party("receiver", Party::address("addr_test1..."));

// this will call the TRP to compile the intent into
// a fully-defined transaction.
let invocation = tx3
    .tx("transfer")
    .arg("quantity", json!(10_000_000))
    .resolve()
    .await?;

// this will use the configured parties (those which are `signers`) to
// sign the transaction.
let signed = invocation.sign()?;

// this will submit the signed payload to the chain using the TRP server.
let submitted = signed.submit().await?;

// this will poll the submitted tx waiting for confirmation that is has
// reached the chain.
let status = submitted
    .wait_for_confirmed(PollConfig::default())
    .await?;

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

Concepts

Protocols

Protocols are defined in TII files and loaded via tii::Protocol.

let protocol = tx3_sdk::tii::Protocol::from_file("./examples/transfer.tii")?;

Parties

Parties are declared in the protocol and attached to the client:

• Party::address(...) for read-only parties (address only)
• Party::signer(...) for signing parties (address comes from signer)

Parties are injected into invocation args by name. You can still override any param explicitly with .arg(...) if needed.

Signers

Signers produce TRP witnesses from a tx hash.

• CardanoSigner is Cardano-specific and derives keys using the Cardano path m/1852'/1815'/0'/0/0.
• Ed25519Signer is a generic raw-key signer (address required at setup).

use tx3_sdk::CardanoSigner;

let signer = CardanoSigner::from_mnemonic(
    "addr_test1...",
    "word1 word2 ...",
)?;

Profiles

Profiles are set at the client level and applied to all invocations:

let tx3 = Tx3Client::new(protocol, trp).with_profile("preprod");

Waiting for status

There are two wait modes:

• wait_for_confirmed (default for most apps)
• wait_for_finalized (stronger finality)

let confirmed = submitted.wait_for_confirmed(PollConfig::default()).await?;
let finalized = submitted.wait_for_finalized(PollConfig::default()).await?;

Advanced: low-level TRP client

If you need full control, use the low-level TRP client 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(...)

Testing

• Unit tests are co-located with modules via #[cfg(test)].
• End-to-end (e2e) tests are 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