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) andToCallArgtalus-sui-move-ptb: build aProgrammableTransaction(PTB) fromCallSpectalus-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 cursorRead: read view (fetch typed handles)Tx: transaction view (simulate/inspect/commit PTBs)
- Ergonomic helper:
tx!: macro that builds aTx, 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 updatesinspect: 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)(usesinitial_shared_version+ mutability) - Receiving:
Input::Receiving(ObjectReference)(transaction input mode forsui::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 anObject<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: callssimulate_transactionwith checks enabled. No signature is required and the chain is not mutated. Handles are not updated.inspect: callssimulate_transactionwith checks disabled and asks gRPC forcommand_outputs. This is meant for debugging and observability, not for guaranteeing that a real commit on chain will succeed.commit: builds a fullTransaction, 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.bcsso the runtime can decodeTransactionEffectsand refresh handles. - If checkpoint waiting times out (or the checkpoint stream errors),
commitstill returns aReceiptwithdigest+ any decoded effects, and marks the observed finality asExecuted.
- By default it also waits for checkpoint inclusion (
§Receipts, finality, and recovery
Tx::commit* returns a Receipt. The receipt preserves recovery information:
digestis always present once submission succeeds.effects/statusare present when returned by gRPC (this crate requestseffects.bcs).requested_finalityis what the runtime asked for (defaults to checkpointed for commits).observed_finality+checkpoint_waitdescribe 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 gRPCTxOptions::gas_budget: defaults toRuntime::default_gas_budgetTxOptions::expiration: optional TTLTxOptions::finality:Checkpointed(default) orExecuted
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.*_uncheckedvariants 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 aroundObjectReference), andtalus_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_objectfetch the currentObjectReferenceand intern it in a cursor (your local frontier) keyed byobject_id.- The returned
Object<T>/ReceivingObject<T>is a smallClonehandle backed byArc<RwLock<...>>. Tx::commitrequestseffects.bcsfrom gRPC, decodesTransactionEffects, 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
Runtimeadvance the cursor. simulate/inspectnever update handles (they do not mutate the chain).- If other transactions mutate an object you track, use
Read::refresh(&obj)(orRead::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_budgetandTxOptions::gas_budgetconfigure gas budget for commits.Runtime::with_wait_timeoutcontrols how longcommit*waits for checkpoint inclusion when checkpointed finality is requested.TxOptions::sponsorlets you submit sponsored transactions (gas owner differs from sender).TxOptions::finalitychooses whether commits requestCheckpointedorExecutedfinality.Runtime::with_cursor_snapshot/Runtime::cursor_snapshotprovide snapshot/restore for the cursor.Runtime::sync_transactionfetches effects by digest and advances the cursor (recovery escape hatch).Read::refresh_id/Read::refresh_idsrefresh cursor state explicitly (external drift escape hatch).Read::grpc_client_mutgives direct access to the underlyingGrpcClientwhen 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.
- Command
Outputs - Outputs returned for each command during inspection.
- Cursor
Snapshot - Serializable snapshot of a runtime cursor (your local frontier).
- Inspect
Options - Options for running a transaction in inspect mode (checks disabled).
- Inspect
Receipt - 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.
- Receiving
Object - Handle owned by the runtime for a receiving object input.
- Runtime
- Runtime that owns a Sui gRPC client, signer, and handle cursor.
- Shared
Object - Typed handle for a shared object input.
- Simulate
Options - Options for running a transaction in simulation mode (checks enabled).
- Simulation
Receipt - Receipt for a simulated transaction.
- Tx
- Transaction builder: build, simulate/inspect, and commit a PTB.
- TxOptions
- Additional transaction options for submitting a PTB.
Enums§
- Checkpoint
Wait Outcome - Outcome of waiting for checkpoint inclusion.
- Ensure
Success Error - Error returned by
Receipt::ensure_success. - Error
- Errors produced by
talus-sui-move-runtime. - Finality
- Transaction finality requested by the caller.
- Observed
Finality - Finality actually observed by the runtime.
- Tombstone
Reason - Reason an object is considered not live in the local cursor.
Traits§
Type Aliases§
- Grpc
Client - Sui gRPC client used by the runtime.