Expand description
§talus-sui-move-call
Typed building blocks for describing Move calls on Sui.
This crate builds on top of talus-sui-move and solves one problem:
describe a Move call in a typed way (object handles + type arguments + arguments) without
building or executing transactions.
§Relationship to the other crates
talus-sui-move-call uses MoveType and MoveStruct from talus-sui-move to build call
descriptions whose types are checked by Rust:
talus-sui-move-calldescribes what to call and how to encode arguments.talus-sui-move-ptbcan turn aCallSpecinto aProgrammableTransaction.talus-sui-move-runtimecan submit that transaction and update typed handles.
This crate can be used independently when an application only needs typed call descriptions. Transaction building and execution are intentionally out of scope.
§Core types
CallSpec:(package, module, function)+ type arguments + call argumentsCallArg: canonical call argument representation (a public alias forsui_sdk_types::Input)ToCallArg: convert values intoCallArgwithout consuming themToCallArgMut: convert values intoCallArgfor Move&mutparameters (shared inputs become mutable)ObjectArg<T>: typed object argument trait used by generated interfaces (accepts any object handle that can be encoded as both&and&mutin Move)MoveObject<T>: typed handle forInput::ImmutableOrOwned(ObjectReference)SharedMoveObject<T>: typed handle forInput::Shared(SharedInput)ReceivingMoveObject<T>: typed handle forInput::Receiving(ObjectReference)
Note: ToCallArg can fail even when BCS encoding is not involved (for example, higher layers can
refuse to convert tombstoned handles or invalid owner kinds into object inputs).
§Receiving is an input mode (not ownership)
Sui’s “receiving” is a distinct transaction input mode. It corresponds to the Move framework
type sui::transfer::Receiving<T>: an ephemeral “receiving ticket” consumed by
sui::transfer::receive/public_receive.
It is not an owner kind recorded on chain, and this crate does not attempt to prove that a given
reference is valid to receive. It only models the correct wire shape
(Input::Receiving(ObjectReference)).
§Argument mapping
This crate keeps its public API small and maps typed values into Sui transaction input kinds:
T: MoveType→CallArg::Pure(bcs(T))MoveObject<T>→CallArg::ImmutableOrOwned(..)SharedMoveObject<T>→CallArg::Shared(..)ReceivingMoveObject<T>→CallArg::Receiving(..)
For Move &mut parameters, use CallSpec::push_arg_mut (or implement ToCallArgMut on your own
handle type). This matters for shared objects: Sui’s shared input encodes mutability in the
transaction input itself.
These are intentionally separate wrapper types because their transaction input shapes differ:
shared objects are described by (id, initial_shared_version, mutability), while
immutable/owned and receiving inputs use full ObjectReferences.
If you need an input kind that doesn’t have a typed wrapper here (for example
CallArg::FundsWithdrawal(..)), use CallSpec::push_input.
§Example: a typed interface function
The typical pattern is to write small interface functions that produce a CallSpec:
use std::str::FromStr;
use talus_sui_move::prelude::*;
use talus_sui_move_call::{CallSpec, MoveObject};
use sui_sdk_types::{Address, Digest, ObjectReference, TypeTag};
#[talus_sui_move::move_struct(address = "0x2", module = "object", abilities = "copy, drop, store")]
pub struct ID {
pub bytes: Address,
}
#[talus_sui_move::move_struct(address = "0x2", module = "object", abilities = "store")]
pub struct UID {
pub id: ID,
}
#[talus_sui_move::move_struct(address = "0x1", module = "vault", abilities = "key")]
pub struct Vault {
pub id: UID,
}
pub fn withdraw(vault: &MoveObject<Vault>, amount: u64) -> CallSpec {
let mut spec = CallSpec::new(
Address::from_str("0x1").expect("address"),
"vault",
"withdraw",
)
.expect("valid identifiers");
spec.push_type_arg::<u64>();
spec.push_arg(vault).expect("arg");
spec.push_arg(&amount).expect("arg");
spec
}
fn main() {
let package = Address::from_str("0x1").unwrap();
let obj_ref = ObjectReference::new(package, 1, Digest::default());
let vault = MoveObject::<Vault>::new(obj_ref);
let spec = withdraw(&vault, 10);
assert_eq!(spec.module.to_string(), "vault");
assert_eq!(spec.function.to_string(), "withdraw");
assert_eq!(spec.type_arguments, vec![TypeTag::U64]);
assert_eq!(spec.arguments.len(), 2);
}§Example: shared and receiving arguments
use std::str::FromStr;
use talus_sui_move_call::{CallArg, CallSpec, ReceivingMoveObject, SharedMoveObject};
use sui_sdk_types::{Address, Digest, ObjectReference};
#[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 Thing {
id: UID,
}
let package = Address::from_str("0x1").unwrap();
let shared = SharedMoveObject::<Thing>::immutable(Address::from_str("0x2").unwrap(), 1);
let recv_ref = ObjectReference::new(Address::from_str("0x3").unwrap(), 1, Digest::default());
let receiving = ReceivingMoveObject::<Thing>::new(recv_ref);
let mut spec = CallSpec::new(package, "demo", "run").unwrap();
spec.push_arg(&shared).unwrap();
spec.push_arg(&receiving).unwrap();
assert!(matches!(spec.arguments[0], CallArg::Shared(_)));
assert!(matches!(spec.arguments[1], CallArg::Receiving(_)));§Out of scope
- No transaction building: this crate does not produce
ProgrammableTransaction. - No execution/runtime: this crate does not talk to a network client or submit transactions.
- No object fetching: object contents are not loaded or decoded here.
Modules§
- prelude
- Common exports for downstream code.
Structs§
- Call
Spec - A description of a Move function call.
- Call
Target - Move call target without encoded arguments.
- Move
Object - Typed object handle for Move structs that have the
keyability. - Receiving
Move Object - Typed handle for a “receiving” object argument.
- Shared
Move Object - Typed handle for a shared object argument.
Enums§
- CallArg
- Canonical Sui transaction input kind.
- Call
ArgError - Errors that can occur when converting values into
CallArg. - Call
Spec Error - Errors that can occur when constructing a
CallSpec.
Traits§
- Object
Arg - Typed object arguments.
- ToCall
Arg - Convert a value into a
CallArg. - ToCall
ArgMut - Convert a value into a
CallArg, forcing a “mutable object input” when applicable.