Skip to main content

Crate talus_sui_move_runtime

Crate talus_sui_move_runtime 

Source
Expand description

§talus-sui-move-runtime

Runtime layer for typed Move interactions on Sui.

It combines the other Talus Sui Move crates where needed:

  • talus-sui-move: Rust representations of Move types (MoveType, MoveStruct, abilities)
  • talus-sui-move-call: typed call descriptions (CallSpec) and ToCallArg
  • talus-sui-move-ptb: build a ProgrammableTransaction (PTB) from CallSpec
  • talus-sui-move-runtime (this crate): submit, simulate, or inspect PTBs and keep handles up to date

This crate solves one problem: provide an ergonomic Read → Tx → Commit boundary for typed Sui interactions while staying truthful to Sui’s versioned objects + effects model:

  • In Read you fetch objects and prepare call specs.
  • In Tx you build a PTB and can simulate, inspect, or commit it.
  • On commit, you always get a Receipt (digest + effects/status when available + finality info), and the runtime advances its local cursor by applying a patch derived from any available effects.

§Quickstart (complete)

use talus_sui_move_runtime::prelude::*;
use sui_sdk_types::{Address, PersonalMessage, Transaction, UserSignature};


fn touch_object(object: &impl ToCallArg, amount: u64) -> CallSpec {
    let package: Address = "0x1".parse().unwrap();
    let mut spec = CallSpec::new(package, "demo", "touch").unwrap();
    spec.push_arg(object).unwrap();
    spec.push_arg(&amount).unwrap();
    spec
}

async fn demo() -> Result<(), Error> {
    let client = GrpcClient::new(GrpcClient::TESTNET_FULLNODE).unwrap();
    let signer = DummySigner;
    let sender: Address = "0x123".parse().unwrap();
    let object_id: Address = "0x2".parse().unwrap();

    let mut rt = Runtime::new(client, signer);

    // Read: fetch a typed handle owned by the runtime.
    let object: Object<Demo> = rt.read().object::<Demo>(object_id).await?;

    // Tx: build and commit once with the `tx!` macro.
    let receipt = talus_sui_move_runtime::tx!(&mut rt, sender => {
        touch_object(&object, 10);
    })
    .await?;

    // Execution failures are recorded in the receipt (they are not transport errors).
    receipt.ensure_success()?;

    // Back in Read: `object`'s `ObjectReference` has been updated internally.
    let _latest_ref = object.reference();
    Ok(())
}

§Core API

  • Runtime views:
    • Runtime: owns gRPC client, signer, and the handle cursor
    • Read: read view (fetch typed handles)
    • Tx: transaction view (simulate/inspect/commit PTBs)
  • Ergonomic helper:
    • tx!: macro that builds a Tx, runs an action, and returns a future (.await)
  • Handles (all implement ToCallArg):
    • Object<T>: object handle owned by the runtime; picks the correct input mode on conversion (shared defaults to immutable)
    • SharedObject<T>: explicit shared input (Input::Shared)
    • ReceivingObject<T>: explicit receiving input (Input::Receiving)
  • Transaction actions:
    • commit: signs/submits and then updates handles (waits for checkpoint inclusion by default)
    • simulate: checks enabled, no mutation, no handle updates
    • inspect: checks disabled, returns command outputs, no handle updates

§Preflight and debugging (simulate / inspect)

If you want a single action, use the tx! macro variants:

use talus_sui_move_runtime::prelude::*;
use sui_sdk_types::Address;

let _sim = talus_sui_move_runtime::tx!(simulate, &mut rt, sender => {
    CallSpec::new("0x1".parse().unwrap(), "m", "f").unwrap();
})
.await?;

let _dbg = talus_sui_move_runtime::tx!(inspect, &mut rt, sender => {
    CallSpec::new("0x1".parse().unwrap(), "m", "f").unwrap();
})
.await?;

If you need to simulate/inspect the exact same PTB before committing it, build a Tx once:

use talus_sui_move_runtime::prelude::*;

let mut tx = rt.tx(sender);
tx.call(CallSpec::new("0x1".parse().unwrap(), "m", "f").unwrap())?;

let _sim = tx.simulate().await?;
let _dbg = tx.inspect().await?;
let receipt = tx.commit().await?;
receipt.ensure_success()?;

§Choosing the right handle kind

Sui has two related but distinct concepts:

  • Owner kinds from chain state (sui_sdk_types::Owner): what an object is right now.
  • Transaction input modes (sui_sdk_types::Input): how you pass an object this time.

This crate uses ownership from chain state (from Owner) to choose a safe default transaction input mode when converting an Object<T> into an argument.

Transaction input modes for objects have different wire shapes and are intentionally represented as distinct types:

  • Immutable/owned: Input::ImmutableOrOwned(ObjectReference)
  • Shared: Input::Shared(SharedInput) (uses initial_shared_version + mutability)
  • Receiving: Input::Receiving(ObjectReference) (transaction input mode for sui::transfer::Receiving<T>)

Note: receiving is not an owner kind recorded on chain. It is a temporary “receiving ticket” consumed by sui::transfer::receive/public_receive.

Note: Sui also has Owner::ConsensusAddress { start_version, owner } objects. They use the shared input shape (start_version plays the same role as initial_shared_version).

Note: child objects (Owner::Object(_)) cannot be used as direct transaction inputs. This crate rejects them early when you try to construct handles that would later become invalid inputs.

This crate mirrors those shapes:

  • Use Read::object::<T>(id) to get an Object<T> for owned, immutable, and shared input shapes.
    • Objects with a shared input shape default to immutable shared when used as an argument.
    • Derive explicit views when needed: obj.shared_immutable()?, obj.shared_mutable()?, obj.receiving()?.

§Explicit views from Object<T>

Object<T> chooses Input::ImmutableOrOwned vs Input::Shared based on the runtime’s latest known owner kind. When an object has a shared input shape, it defaults to immutable shared.

If you need a specific input mode, derive an explicit view at the moment it matters:

use talus_sui_move_runtime::prelude::*;

#[talus_sui_move::move_struct(address = "0x2", module = "object", abilities = "copy, drop, store")]
struct ID {
    bytes: Address,
}

#[talus_sui_move::move_struct(address = "0x2", module = "object", abilities = "store")]
struct UID {
    id: ID,
}

#[talus_sui_move::move_struct(address = "0x1", module = "demo", abilities = "key")]
struct Demo {
    id: UID,
}

fn views(obj: Object<Demo>) -> Result<(), talus_sui_move_call::CallArgError> {
    let _shared_mut: SharedObject<Demo> = obj.shared_mutable()?;
    let _receiving: ReceivingObject<Demo> = obj.receiving()?;
    Ok(())
}

§Transaction actions in detail

All transaction actions take a sender address and are methods on a transaction builder (Tx):

  • call / arg / input: build the PTB in place.
  • simulate: calls simulate_transaction with checks enabled. No signature is required and the chain is not mutated. Handles are not updated.
  • inspect: calls simulate_transaction with checks disabled and asks gRPC for command_outputs. This is meant for debugging and observability, not for guaranteeing that a real commit on chain will succeed.
  • commit: builds a full Transaction, signs it, and submits it.
    • By default it also waits for checkpoint inclusion (TxOptions::finality = Checkpointed).
    • When the caller requests execution finality (TxOptions::finality = Executed), the runtime returns as soon as the transaction is executed (effects produced).
    • In both cases it requests effects.bcs so the runtime can decode TransactionEffects and refresh handles.
    • If checkpoint waiting times out (or the checkpoint stream errors), commit still returns a Receipt with digest + any decoded effects, and marks the observed finality as Executed.

§Receipts, finality, and recovery

Tx::commit* returns a Receipt. The receipt preserves recovery information:

  • digest is always present once submission succeeds.
  • effects/status are present when returned by gRPC (this crate requests effects.bcs).
  • requested_finality is what the runtime asked for (defaults to checkpointed for commits).
  • observed_finality + checkpoint_wait describe what the runtime actually observed.

If checkpoint waiting times out, your transaction may still have executed. When effects are present in the receipt, the runtime already advanced its cursor before returning the receipt.

If a receipt does not contain effects (for example, because it was persisted without them), you can recover by digest and advance the cursor explicitly:

use talus_sui_move_runtime::prelude::*;

if receipt.effects.is_none() {
    let _effects = rt.sync_transaction(receipt.digest).await?;
}
Ok(())
use talus_sui_move_runtime::prelude::*;
use std::time::Duration;
use sui_sdk_types::Address;

	let client = GrpcClient::new(GrpcClient::TESTNET_FULLNODE).unwrap();
	let signer = DummySigner;
	let sender: Address = "0x123".parse().unwrap();

	let mut rt = Runtime::new(client, signer)
	    .with_wait_timeout(Duration::from_millis(1)); // deliberately tiny to illustrate timeouts

	let mut tx = rt.tx(sender);
	let package: Address = "0x1".parse().unwrap();
	tx.call(CallSpec::new(package, "m", "f").unwrap())?;

let receipt = tx.commit().await?;

match receipt.checkpoint_wait {
    CheckpointWaitOutcome::Ok => {}
    CheckpointWaitOutcome::Timeout | CheckpointWaitOutcome::StreamError { .. } => {
        // `receipt.digest` is known; `receipt.effects` may be present.
        // If effects are present, the cursor has already been advanced.
    }
    CheckpointWaitOutcome::NotRequested => {
        // This can happen when the commit only requests execution finality.
    }
}

receipt.ensure_success()?;

§Building PTBs directly (more complex flows)

If you need native PTB commands (coin ops, transfers, result wiring, etc), build the PTB explicitly using talus-sui-move-ptb and pass it to commit_ptb / simulate_ptb / inspect_ptb.

use talus_sui_move_runtime::prelude::*;
use sui_sdk_types::Address;

let package: Address = "0x1".parse().unwrap();
let spec = CallSpec::new(package, "m", "f").unwrap();

let ptb = ptb(|tx| {
    tx.call(spec)?;
    Ok(())
})
.unwrap();

assert_eq!(ptb.commands.len(), 1);

§Gas and sponsorship (commit only)

Tx::commit_with(TxOptions) and Tx::commit_ptb_with(ptb, TxOptions) let you control gas details:

  • TxOptions::sponsor: gas owner (defaults to sender)
  • TxOptions::gas: explicit gas object reference (otherwise the runtime selects one coin owned by the gas owner)
  • TxOptions::gas_price: defaults to the reference gas price from gRPC
  • TxOptions::gas_budget: defaults to Runtime::default_gas_budget
  • TxOptions::expiration: optional TTL
  • TxOptions::finality: Checkpointed (default) or Executed

simulate/inspect do not sign or submit, and do not currently model explicit gas payment configuration (they rely on the simulation gRPC).

§Typed reads with tag verification

In addition to constructing handles, Read can fetch and decode Move object contents:

  • Read::get::<T>(id) -> (Object<T>, T): tag check + decode and return both a handle and value.
  • Read::decode(&Object<T>) -> T: refresh the handle and decode the latest contents.
  • *_unchecked variants skip type tag verification (explicit escape hatch).

These helpers use talus-sui-move decoding with tag verification (MoveInstance<T>), so “type tag says X but BCS layout expects Y” becomes an explicit error instead of a silent footgun.

use talus_sui_move_runtime::prelude::*;
use sui_sdk_types::Address;

#[talus_sui_move::move_struct(address = "0x2", module = "object", abilities = "copy, drop, store")]
struct ID {
    bytes: Address,
}

#[talus_sui_move::move_struct(address = "0x2", module = "object", abilities = "store")]
struct UID {
    id: ID,
}

#[talus_sui_move::move_struct(address = "0x1", module = "demo", abilities = "key")]
struct Demo {
    id: UID,
    value: u64,
}

let object_id: Address = "0x2".parse().unwrap();

let (object, value): (Object<Demo>, Demo) = rt.read().get(object_id).await?;
let _latest: Demo = rt.read().decode(&object).await?;
let _unchecked: Demo = rt.read().decode_unchecked(&object).await?;

§Writing interface functions (important)

To keep your Move interface layer usable in every context (unit tests, pure PTB building, runtime), write interface functions against ToCallArg instead of concrete handle types:

use talus_sui_move_runtime::prelude::*;
use sui_sdk_types::Address;

fn transfer_any_object(obj: &impl ToCallArg, recipient: Address) -> CallSpec {
    let package: Address = "0x1".parse().unwrap();
    let mut spec = CallSpec::new(package, "demo", "transfer").unwrap();
    spec.push_arg(obj).unwrap();
    spec.push_arg(&recipient).unwrap();
    spec
}

This works with:

  • talus_sui_move_call::MoveObject<T> (a plain wrapper around ObjectReference), and
  • talus_sui_move_runtime::Object<T> (a handle owned by the runtime that updates on commit).

§How runtime handles work

On Sui, mutating an object changes its ObjectReference (version/digest). Updating these refs manually is annoying and tends to leak plumbing into user code.

This crate lets the runtime own handles:

  • Read::object/Read::receiving_object fetch the current ObjectReference and intern it in a cursor (your local frontier) keyed by object_id.
  • The returned Object<T> / ReceivingObject<T> is a small Clone handle backed by Arc<RwLock<...>>.
  • Tx::commit requests effects.bcs from gRPC, decodes TransactionEffects, extracts updated object information, derives a patch from those effects, and applies it to the cursor, updating any live handle cells that match those object ids.

Consequences:

  • Clones of the same handle stay in sync (they share the same cell).
  • Only commits performed through the same Runtime advance the cursor.
  • simulate/inspect never update handles (they do not mutate the chain).
  • If other transactions mutate an object you track, use Read::refresh(&obj) (or Read::refresh_id / Read::refresh_ids) to refetch the latest reference/owner and overwrite the cursor’s slot.

§Storing handles in Rust structs

The point of handles owned by the runtime is that you can store them in normal Rust state without threading &mut ObjectReference everywhere.

use talus_sui_move_runtime::prelude::*;

#[talus_sui_move::move_struct(address = "0x2", module = "object", abilities = "copy, drop, store")]
struct ID {
    bytes: Address,
}

#[talus_sui_move::move_struct(address = "0x2", module = "object", abilities = "store")]
struct UID {
    id: ID,
}

#[talus_sui_move::move_struct(address = "0x1", module = "demo", abilities = "key")]
struct Demo {
    id: UID,
}

#[derive(Clone)]
struct Wallet {
    object: Object<Demo>,
}

let wallet = Wallet {
    object: rt.read().object("0x2".parse().unwrap()).await?,
};

let ptb = talus_sui_move_ptb::ptb! {
    // any call that mutates `wallet.object` in chain state
    CallSpec::new("0x1".parse().unwrap(), "m", "f").unwrap();
}?;
rt.tx(sender).commit_ptb(ptb).await?;

// The `ObjectReference` is refreshed internally after commit.
let _latest = wallet.object.reference();

§Outputs from inspect / decoding BCS

Inspection returns outputs for each command as raw BCS blobs (BcsValue). This crate does not impose a new typing layer on top of those blobs, but you can decode them using sui_sdk_types::bcs:

use talus_sui_move_runtime::BcsValue;
use sui_sdk_types::bcs::{FromBcs, ToBcs};

let bytes = 10u64.to_bcs().unwrap();
let value = BcsValue {
    name: Some("u64".to_owned()),
    bytes,
};

let decoded = u64::from_bcs(&value.bytes).unwrap();
assert_eq!(decoded, 10);

§Configuration and escape hatches

  • Runtime::with_default_gas_budget and TxOptions::gas_budget configure gas budget for commits.
  • Runtime::with_wait_timeout controls how long commit* waits for checkpoint inclusion when checkpointed finality is requested.
  • TxOptions::sponsor lets you submit sponsored transactions (gas owner differs from sender).
  • TxOptions::finality chooses whether commits request Checkpointed or Executed finality.
  • Runtime::with_cursor_snapshot / Runtime::cursor_snapshot provide snapshot/restore for the cursor.
  • Runtime::sync_transaction fetches effects by digest and advances the cursor (recovery escape hatch).
  • Read::refresh_id / Read::refresh_ids refresh cursor state explicitly (external drift escape hatch).
  • Read::grpc_client_mut gives direct access to the underlying GrpcClient when needed.

§Out of scope

  • No code generation: interface functions are still handwritten or derived elsewhere.
  • No “live ORM”: decoding is explicit snapshot reads (Read::get / Read::decode), not a background synchronization cache.

Modules§

prelude
Common exports for downstream code.

Macros§

tx
Build and run a transaction in the Read → Tx → Commit mental model.

Structs§

BcsValue
A raw BCS value returned by simulation or inspection.
CommandOutputs
Outputs returned for each command during inspection.
CursorSnapshot
Serializable snapshot of a runtime cursor (your local frontier).
InspectOptions
Options for running a transaction in inspect mode (checks disabled).
InspectReceipt
Receipt for an inspected transaction, with checks disabled, including command outputs.
Object
Handle owned by the runtime for an on chain object used as a transaction input.
Read
Read view: read/fetch helpers and handle construction.
Receipt
Receipt for a submitted transaction.
ReceivingObject
Handle owned by the runtime for a receiving object input.
Runtime
Runtime that owns a Sui gRPC client, signer, and handle cursor.
SharedObject
Typed handle for a shared object input.
SimulateOptions
Options for running a transaction in simulation mode (checks enabled).
SimulationReceipt
Receipt for a simulated transaction.
Tx
Transaction builder: build, simulate/inspect, and commit a PTB.
TxOptions
Additional transaction options for submitting a PTB.

Enums§

CheckpointWaitOutcome
Outcome of waiting for checkpoint inclusion.
EnsureSuccessError
Error returned by Receipt::ensure_success.
Error
Errors produced by talus-sui-move-runtime.
Finality
Transaction finality requested by the caller.
ObservedFinality
Finality actually observed by the runtime.
TombstoneReason
Reason an object is considered not live in the local cursor.

Traits§

SuiSigner
Public alias for sui_crypto::SuiSigner used by Runtime and Tx.

Type Aliases§

GrpcClient
Sui gRPC client used by the runtime.