Quick Start

This guide walks through consuming an existing Tx3 protocol from your application. We’ll generate a typed client from a compiled .tii, bind parties and a signer, and drive the full resolve → sign → submit → wait lifecycle against a TRP server. Every code step is shown in TypeScript, Rust, Go, and Python — pick the tab that matches your stack and the narrative still applies.

We’re assuming you already have:

• A Tx3 project (a trix.toml plus a main.tx3) — for example the transfer protocol from the authoring quick-start.
• A TRP server reachable from your machine. The simplest setup is to run trix devnet locally; for testnet/mainnet, point at a hosted TRP endpoint (Demeter, Blockfrost-via-TRP, etc.).
• The toolchain for your target language installed (Node.js 18+, Rust 1.78+, Go 1.22+, or Python 3.10+).

Note

Make sure you have followed the installation steps before you attempt to follow this guide.

Configure codegen

Tx3 produces typed clients via trix codegen. Open your project’s trix.toml and add a [[bindings]] entry for your target language. The output path is where the generated client will be written; declare more than one entry if you want to target multiple languages from the same protocol.

TypeScript

[[bindings]]
plugin = "typescript"
output = "./generated/ts"

Rust

[[bindings]]
plugin = "rust"
output = "./generated/rust"

Go

[[bindings]]
plugin = "go"
output = "./generated/go"

Python

[[bindings]]
plugin = "python"
output = "./generated/python"

Generate the client

From the project root, run:

trix codegen

This produces:

• A .tii artifact describing the protocol’s interface (transactions, parties, profiles).
• A typed module under the output directory that exposes one builder method per tx declared in your .tx3 file.

Re-run trix codegen whenever you change main.tx3. The generated code is meant to be checked into source control alongside your application — treat it like a lockfile, not a build artifact.

Install the runtime SDK

In the application that will use the generated client, install the runtime SDK. It ships the Tx3Client, party bindings, signer abstractions, and the TRP transport layer; the generated module wraps these in a typed surface specific to your protocol.

TypeScript

npm install tx3-sdk

Rust

Cargo.toml

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

Go

go get github.com/tx3-lang/go-sdk/sdk

Python

pip install tx3-sdk

Load the protocol

The .tii artifact carries the protocol’s interface: every transaction template, the parties it expects you to bind, the profiles it was compiled for. Each SDK exposes a Protocol.fromFile-shaped entry point.

TypeScript

import { Protocol } from "tx3-sdk";

const protocol = await Protocol.fromFile("./generated/ts/transfer.tii");

Rust

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

Go

import tx3 "github.com/tx3-lang/go-sdk/sdk"

protocol, err := tx3.ProtocolFromFile("./generated/go/transfer.tii")
if err != nil { log.Fatal(err) }

Python

from tx3_sdk import Protocol

protocol = Protocol.from_file("./generated/python/transfer.tii")

Connect to a TRP server

TRP is the wire protocol the SDK uses to ask a backend “given this TIR and these arguments, produce a balanced transaction.” When you run trix devnet, a local TRP endpoint comes up automatically. For preprod/mainnet, point at a hosted TRP server.

TypeScript

import { TrpClient } from "tx3-sdk";

const trp = new TrpClient({ endpoint: "http://localhost:3000/rpc" });

Rust

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

let trp = Client::new(ClientOptions {
    endpoint: "http://localhost:3000/rpc".to_string(),
    headers: None,
});

Go

import "github.com/tx3-lang/go-sdk/sdk/trp"

trpClient := tx3.NewTRPClient(trp.ClientOptions{
    Endpoint: "http://localhost:3000",
})

Python

from tx3_sdk import TrpClient

trp = TrpClient(endpoint="http://localhost:3000/rpc")

Bind parties, signer, and profile

Every party declared in the .tx3 file needs a binding at runtime. Party.signer(...) ties a party to a key that can produce witnesses; Party.address(...) binds a read-only address. withProfile(...) selects which environment block (devnet/preview/preprod/mainnet) the SDK uses when it asks TRP to resolve.

Each SDK ships two signer kinds: a CardanoSigner that derives keys from a BIP39 mnemonic at the standard Cardano path, and a generic Ed25519Signer for raw key material. The snippets below show whichever flavour is most idiomatic per language.

TypeScript

import { Tx3Client, Party, Ed25519Signer } from "tx3-sdk";

const signer = Ed25519Signer.fromHex("addr_test1...", "deadbeef...");

const tx3 = new Tx3Client(protocol, trp)
  .withProfile("devnet")
  .withParty("sender", Party.signer(signer))
  .withParty("receiver", Party.address("addr_test1..."));

Rust

use tx3_sdk::{CardanoSigner, Party, Tx3Client};

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

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

Go

import "github.com/tx3-lang/go-sdk/sdk/signer"

mySigner, err := signer.CardanoSignerFromMnemonic(
    "addr_test1...",
    "word1 word2 ... word24",
)
if err != nil { log.Fatal(err) }

client := tx3.NewClient(protocol, trpClient).
    WithProfile("devnet").
    WithParty("sender", tx3.SignerParty(mySigner)).
    WithParty("receiver", tx3.AddressParty("addr_test1..."))

Python

from tx3_sdk import CardanoSigner, Party, Tx3Client

sender_signer = CardanoSigner.from_mnemonic(
    address="addr_test1...",
    phrase="word1 word2 ... word24",
)

client = (
    Tx3Client(protocol, trp)
    .with_profile("devnet")
    .with_party("sender", Party.signer(sender_signer))
    .with_party("receiver", Party.address("addr_test1..."))
)

Drive a transaction end-to-end

tx("name").arg(...) builds an invocation; the four-stage chain takes it from there. Each stage returns a typed handle for the next: ResolvedTx → SignedTx → SubmittedTx. waitForConfirmed polls the chain (via TRP) until the transaction reaches the requested stability level; waitForFinalized waits for stronger finality.

TypeScript

import { PollConfig } from "tx3-sdk";

const status = await tx3
  .tx("transfer")
  .arg("quantity", 10_000_000n)
  .resolve()
  .then((r) => r.sign())
  .then((s) => s.submit())
  .then((sub) => sub.waitForConfirmed(PollConfig.default()));

console.log(status.stage); // "confirmed"

Rust

use serde_json::json;
use tx3_sdk::PollConfig;

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

let signed = invocation.sign()?;
let submitted = signed.submit().await?;
let status = submitted
    .wait_for_confirmed(PollConfig::default())
    .await?;

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

Go

ctx := context.Background()

resolved, err := client.Tx("transfer").
    Arg("quantity", 10_000_000).
    Resolve(ctx)
if err != nil { log.Fatal(err) }

signed, err := resolved.Sign()
if err != nil { log.Fatal(err) }

submitted, err := signed.Submit(ctx)
if err != nil { log.Fatal(err) }

status, err := submitted.WaitForConfirmed(ctx, tx3.DefaultPollConfig())
if err != nil { log.Fatal(err) }

fmt.Printf("Confirmed at stage %s\n", status.Stage)

Python

from tx3_sdk import PollConfig

resolved = await client.tx("transfer").arg("quantity", 10_000_000).resolve()
signed = await resolved.sign()
submitted = await signed.submit()

status = await submitted.wait_for_confirmed(PollConfig.default())
print(f"Confirmed at stage: {status.stage}")

What’s next

• Find the canonical repository and package registry for each SDK on the SDKs page.
• Learn more about the codegen workflow — supported targets, output layout, and how to wire generated code into your build.
• Understand the protocols underneath (TII, TRP) if you want to know how the wire format works.