Sui Developer Cheat Sheet

Quick reference on best practices for Sui Network developers.

Move

General

• Read the Code Quality Checklist for best practices in Move development.
• Follow the Move conventions for consistent naming and coding style.
• Use vector-backed collections (vector, VecSet, VecMap, PriorityQueue) with a known maximum size of ≤ 1000 items.
  • Use dynamic field-backed collections (Table, Bag, ObjectBag, ObjectTable, 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 vector-backed collection.
• If your function f needs a payment in, for example, 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 f to extract the right amount.

Composability

• Use the Sui Object Display to customize how your objects show up in wallets, apps, and explorers.
• Avoid “self-transfers." When possible, return the object from the current function, so it can be used in a different command in a programmable transaction block.

Package upgrades

• Read about package upgrades before publishing your package.
• Packages are immutable, so any published package can be called forever. Use object versioning to prevent older versions from being called.
• If you upgrade a package P1 to P2, other packages and clients that depend on P1 will continue using P1. They do not auto-update to P2. Both dependent packages and client code must be explicitly updated to point at P2.
• 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 the message sending across a bridge example from Wormhole. Extension packages that produce outbound messages can use prepare_message from any version of the Wormhole package to produce a MessageTicket while client code that sends the message must pass that MessageTicket into publish_message in the latest version of the package.
  • public function 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 struct types, change their definition or add new abilities via an upgrade. Introduce new types carefully as they will live forever.

Testing

• Use the sui::test_scenario module to mimic multi-transaction, multi-sender test scenarios.
• Use the std::unit_test module for assert_eq! and assert_ref_eq! macros for better test error messages.
• Use the sui::test_utils module for black-hole function destroy.
• Use the std::debug module for debug printing via print.
• Use sui move test --coverage to 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.

Apps

• 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 signTransactionBlock API, then submit the transaction via a call to execute_transactionBlock on the app's full node, not use the wallet's signAndExecuteTransactionBlock API. 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.
• 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 heterogeneous 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.

Signing

• 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.
• Any sui client command that crafts a transaction (e.g., sui client publish, sui client call) can accept the --serialize-output flag to output a base64 transaction to be signed.
• Sui supports several signature schemes for transaction signing, including native multisig.

zkLogin

• Call the proving service as sparingly as possible. Design your app flows such that you call the proving service only when the user is about to perform a real transaction.
• Beware of how you cache the ephemeral private key. Treat the private key akin to a piece of highly sensitive data, e.g., password. If an (unexpired) ephemeral private key and its corresponding ZK proof are leaked, then an attacker can steal user's assets.