Skip to main content

Crate talus_sui_move_call

Crate talus_sui_move_call 

Source
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-call describes what to call and how to encode arguments.
  • talus-sui-move-ptb can turn a CallSpec into a ProgrammableTransaction.
  • talus-sui-move-runtime can 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 arguments
  • CallArg: canonical call argument representation (a public alias for sui_sdk_types::Input)
  • ToCallArg: convert values into CallArg without consuming them
  • ToCallArgMut: convert values into CallArg for Move &mut parameters (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 &mut in Move)
  • MoveObject<T>: typed handle for Input::ImmutableOrOwned(ObjectReference)
  • SharedMoveObject<T>: typed handle for Input::Shared(SharedInput)
  • ReceivingMoveObject<T>: typed handle for Input::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§

CallSpec
A description of a Move function call.
CallTarget
Move call target without encoded arguments.
MoveObject
Typed object handle for Move structs that have the key ability.
ReceivingMoveObject
Typed handle for a “receiving” object argument.
SharedMoveObject
Typed handle for a shared object argument.

Enums§

CallArg
Canonical Sui transaction input kind.
CallArgError
Errors that can occur when converting values into CallArg.
CallSpecError
Errors that can occur when constructing a CallSpec.

Traits§

ObjectArg
Typed object arguments.
ToCallArg
Convert a value into a CallArg.
ToCallArgMut
Convert a value into a CallArg, forcing a “mutable object input” when applicable.