Quick reference on best practices for Sui Network developers.
- Read about package upgrades and write upgrade-friendly code:
- Packages are immutable, so buggy package code can be called forever. Add protections at the object level instead.
- If you upgrade a package
P', other packages and clients that depend on
Pwill continue using
P, not auto-update to
P'. Both dependent packages and client code must be explicitly updated to point at
- Packages that expect to be extended by dependent packages can avoid breaking their extensions with each upgrade by providing a standard (unchanging) interface that all versions conform to. See this example for message sending across a bridge from Wormhole. Extension packages that produce messages to send can use
prepare_messagefrom any version of the Wormhole package to produce a
MessageTicketwhile client code to send the message must pass that
publish_messagein the latest version of the package.
publicfunction signatures cannot be deleted or changed, but
public(friend)functions can. Use
public(friend)or private visibility liberally unless you are exposing library functions that will live forever.
- It is not possible to delete
structtypes, add new fields (though you can add dynamic fields), or add new abilities via an upgrade. Introduce new types carefully—they will live forever!
vector-backed collections (
PriorityQueue) with a known maximum size of ≤ 1000 items.
- Use dynamic field-backed collections (
LinkedTable) for any collection that allows third-party addition, larger collections, and collections of unknown size.
- Move objects have a maximum size of 250KB—any attempt to create a larger object leads to an aborted transaction. Ensure that your objects do not have an ever-growing
- Use dynamic field-backed collections (
- If your function
fneeds a payment in (e.g.) SUI from the caller, use
fun f(payment: Coin<SUI>)not
fun f(payment: &mut Coin<SUI>, amount: u64). This is safer for callers—they know exactly how much they are paying, and do not need to trust
fto extract the right amount.
- Don't micro-optimize gas usage. Sui computation costs are rounded up to the closest bucket, so only very drastic changes will make a difference. In particular, if your transaction is already in the lowest cost bucket, it can't get any cheaper.
- Follow the Move coding conventions for consistent style.
- Use the
displaystandard to customize how your objects show up in wallets, apps, and explorers
- Avoid “self-transfers”—whenever possible, instead of writing
transfer::transfer(obj, tx_context::sender(ctx)), return
objfrom the current function. This allows a caller or programmable transaction block to use
sui::test_scenarioto mimic multi-transaction, multi-sender test scenarios.
- Use the
sui::test_utilsmodule for better test error messages via
assert_eq, debug printing via
sui move test --coverageto compute code coverage information for your tests, and
sui move coverage source --module <name>to see uncovered lines highlighted in red. Push coverage all the way to 100% if feasible.
- For optimal performance and data consistency, apps should submit writes and reads for the same full node. In the TS SDK, this means that apps should use the wallet's
signTransactionBlockAPI, then submit the transaction via a call to
execute_transactionBlockon the app's full node, not use the wallet's
signAndExecuteTransactionBlockAPI. This ensures read-after-write-consistency--reads from the app's full node will reflect writes from the transaction right away instead of waiting for a checkpoint.
- For lower latency, use
"showEvents": falseif your app needs to know that a transaction was confirmed, but does not immediately need to see the transaction effects or read the objects/events written by the transaction.
- Apps should implement a local cache for frequently read data rather than over-fetching from the full node.
- Whenever possible, use programmable transaction blocks to compose existing on-chain functionality rather than publishing new smart contract code. Programmable transaction blocks allow large-scale batching and heterogenous composition, driving already-low gas fees down even further.
- Apps should leave gas budget, gas price, and coin selection to the wallet. This gives wallets more flexibility, and it's the wallet's responsibility to dry run a transaction to ensure it doesn't fail.
- Never sign two concurrent transactions that are touching the same owned object. Either use independent owned objects, or wait for one transaction to conclude before sending the next one. Violating this rule might lead to client equivocation, which locks up the owned objects involved in the two transactions until the end of the current epoch.
sui clientcommand that crafts a transaction (e.g.,
sui client publish,
sui client call) can accept the
--serialize-outputflag to output a base64 transaction to be signed.
- Sui supports several signature schemes for transaction signing, including native multisig.