sui-framework

name	sui-framework
description	This skill should be used when the user asks about Sui Move standard library, Sui framework modules, core types like Coin, Balance, Object, or Sui system operations like staking. Covers 0x1 (Move stdlib), 0x2 (Sui framework), 0x3 (Sui system), and 0xb (Sui Bridge).

Sui Framework

Overview

The Sui Framework comprises the core on-chain packages that underpin the Sui blockchain. It includes the Move standard library (0x1), the Sui framework (0x2) with object model primitives, coin/balance types, and collections, the Sui system (0x3) for staking and validator management, and the Sui Bridge (0xb) for cross-chain bridging.

Package IDs

Package	Address	Version	Modules
Move Stdlib	0x1	22	22
Sui Framework	0x2	49	62
Sui System	0x3	28	11
Sui Bridge	0xb	7	8

Source Files

Decompiled source at:

• packages/mainnet_most_used/0x00/00000000000000000000000000000000000000000000000000000000000001/decompiled_modules/
• packages/mainnet_most_used/0x00/00000000000000000000000000000000000000000000000000000000000002/decompiled_modules/
• packages/mainnet_most_used/0x00/00000000000000000000000000000000000000000000000000000000000003/decompiled_modules/
• packages/mainnet_most_used/0x00/0000000000000000000000000000000000000000000000000000000000000b/decompiled_modules/

Key Modules

0x1 - Move Stdlib

Module	Purpose
vector	Native vector operations (empty, push_back, pop_back, borrow, length, etc.)
option	Option<T> type -- some, none, is_some, borrow, destroy_some
string	UTF-8 String type -- utf8, append, substring, length
ascii	ASCII string type
type_name	Runtime type introspection
bcs	Binary Canonical Serialization
hash	SHA2-256 and SHA3-256 hashing
fixed_point32	Fixed-point arithmetic

0x2 - Sui Framework

Module	Purpose
object	UID, ID types -- new, delete, id, id_address
tx_context	TxContext -- sender, epoch, epoch_timestamp_ms, fresh_object_address
transfer	Object transfer -- transfer, public_transfer, share_object, freeze_object, receive
coin	Coin<T>, TreasuryCap<T>, CoinMetadata<T> -- mint, burn, split, join, create_currency
balance	Balance<T>, Supply<T> -- zero, split, join, value, withdraw_all
sui	SUI coin type (9 decimals, total supply 10B)
clock	Clock shared object -- timestamp_ms
event	emit<T> for emitting events
dynamic_field	Heterogeneous dynamic fields on objects -- add, borrow, borrow_mut, remove, exists_
dynamic_object_field	Dynamic fields that store objects (preserving object ID)
package	Publisher, UpgradeCap -- claim, authorize_upgrade, make_immutable
display	Display<T> for on-chain display metadata -- new, add, update_version
token	Closed-loop Token<T> with policy-based rules
kiosk	Kiosk for NFT trading -- place, list, purchase, take
transfer_policy	TransferPolicy<T> -- enforces rules on kiosk purchases
table	Table<K, V> -- typed dynamic-field-based map
bag	Bag -- heterogeneous dynamic-field-based map
object_table	Like Table but values are objects
object_bag	Like Bag but values are objects
linked_table	Ordered linked-list table
vec_map	Vector-based map (small collections)
vec_set	Vector-based set (small collections)
pay	Payment utilities
borrow	Hot-potato borrow pattern
random	On-chain randomness
deny_list	Token deny-list for regulated coins
url	URL type

0x3 - Sui System

Module	Purpose
sui_system	SuiSystemState -- request_add_stake, request_withdraw_stake, validator management
staking_pool	StakingPool, StakedSui, FungibleStakedSui -- staking internals
validator	Validator metadata and staking pool access
validator_set	Active/pending validator set management
stake_subsidy	Epoch-based stake subsidies

0xb - Sui Bridge

Module	Purpose
bridge	Cross-chain bridge operations
treasury	Bridge token treasury
committee	Bridge committee management
message	Bridge message encoding

Common Patterns

Creating a new coin type

module my_package::my_coin {
    use sui::coin;
    use sui::url;

    public struct MY_COIN has drop {}

    fun init(witness: MY_COIN, ctx: &mut TxContext) {
        let (treasury_cap, metadata) = coin::create_currency(
            witness, 9, b"MYC", b"My Coin", b"Description",
            option::some(url::new_unsafe_from_bytes(b"https://...")), ctx
        );
        transfer::public_freeze_object(metadata);
        transfer::public_transfer(treasury_cap, ctx.sender());
    }
}

Transferring objects

// Objects with `store` ability -- use public_ variants
transfer::public_transfer(obj, recipient);
transfer::public_share_object(obj);
transfer::public_freeze_object(obj);

// Module-private transfers (objects without `store`)
transfer::transfer(obj, recipient);
transfer::share_object(obj);

Working with Coin and Balance

let coin_value: u64 = coin::value(&my_coin);
let balance: Balance<SUI> = coin::into_balance(my_coin);
let coin: Coin<SUI> = coin::from_balance(balance, ctx);
let split_coin = coin::split(&mut my_coin, amount, ctx);
coin::join(&mut my_coin, other_coin);
// Balance-level operations (no object overhead)
let bal_value = balance::value(&my_balance);
let split_bal = balance::split(&mut my_balance, amount);
balance::join(&mut my_balance, other_balance);

Using the Clock

use sui::clock::Clock;
public fun do_something(clock: &Clock) {
    let now_ms: u64 = clock::timestamp_ms(clock);
}

Dynamic fields

use sui::dynamic_field as df;
df::add(&mut obj.id, key, value);
let val_ref = df::borrow<KeyType, ValueType>(&obj.id, key);
let val = df::remove<KeyType, ValueType>(&mut obj.id, key);
let exists = df::exists_(&obj.id, key);

Staking SUI

// Entry function: stakes coin with a validator
sui_system::request_add_stake(system_state, coin, validator_address, ctx);
// Withdraw stake
sui_system::request_withdraw_stake(system_state, staked_sui, ctx);

Publisher and Display

// In init function with OTW
let publisher = package::claim(witness, ctx);
let display = display::new<MyType>(&publisher, ctx);
display::add(&mut display, string::utf8(b"name"), string::utf8(b"{name}"));
display::update_version(&mut display);
transfer::public_transfer(display, ctx.sender());

Important Constants

• SUI decimals: 9 (1 SUI = 1_000_000_000 MIST)
• Shared objects (well-known addresses): Clock (0x6), AuthenticatorState (0x7), Random (0x8), Bridge (0x9), SuiSystemState (0x5), DenyList (0x403)
• Minimum stake: 1_000_000_000 MIST (1 SUI)

Related Skills

• cetus -- Cetus DEX (uses Coin, Balance extensively)
• deepbook -- DeepBook orderbook (uses Coin, Balance, Clock)
• scallop / navi / suilend -- Lending protocols (use Coin, Balance, Clock)
• kiosk patterns are used by NFT marketplaces