[docs] refresh dev cheat sheet #24063
Open
+15
−11
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
damirka
temporarily deployed
to
sui-typescript-aws-kms-test-env
GitHub Actions
Inactive
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
bot
added
the
Type: Documentation
damirka
commented
Oct 23, 2025
| - 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 (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 `f` to 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. |
There was a problem hiding this comment.
This is simply not true. We don't have buckets.
jessiemongeon1
approved these changes
Oct 24, 2025
| - `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, add new fields (though you can add dynamic fields), or add new [abilities](https://move-language.github.io/move/abilities.html) via an upgrade. Introduce new types carefully—they will live forever! | ||
| - Read the [Code Quality Checklist](https://move-book.com/guides/code-quality-checklist/) for best practices in Move development. | ||
| - Follow the [Move conventions](../../concepts/sui-move-concepts/conventions.mdx) for consistent naming and coding style. |
There was a problem hiding this comment.
Suggested change
| - Follow the [Move conventions](../../concepts/sui-move-concepts/conventions.mdx) for consistent naming and coding style. | |
| - Follow the [Move conventions](/concepts/sui-move-concepts/conventions.mdx) for consistent naming and coding style. |
| - It is not possible to delete `struct` types, add new fields (though you can add dynamic fields), or add new [abilities](https://move-language.github.io/move/abilities.html) via an upgrade. Introduce new types carefully—they will live forever! | ||
| - Read the [Code Quality Checklist](https://move-book.com/guides/code-quality-checklist/) for best practices in Move development. | ||
| - Follow the [Move conventions](../../concepts/sui-move-concepts/conventions.mdx) for consistent naming and coding style. | ||
| - Use `vector`-backed collections (`vector`, `VecSet`, `VecMap`, `PriorityQueue`) with a **known** maximum size of ≤ 1000 items. |
There was a problem hiding this comment.
Suggested change
| - Use `vector`-backed collections (`vector`, `VecSet`, `VecMap`, `PriorityQueue`) with a **known** maximum size of ≤ 1000 items. | |
| - Use `vector`-backed collections (`vector`, `VecSet`, `VecMap`, `PriorityQueue`) with a known maximum size of ≤ 1000 items. |
| - Follow the [Move conventions](../../concepts/sui-move-concepts/conventions.mdx) 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. |
There was a problem hiding this comment.
Suggested change
| - 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. | |
| - 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. |
| - 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 (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 `f` to extract the right amount. |
There was a problem hiding this comment.
Suggested change
| - If your function `f` needs 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 `f` to extract the right amount. | |
| - 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. |
| - Use the `display` standard 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 `obj` from the current function. This allows a caller or programmable transaction block to use `obj`. | ||
| - Use the [Sui Object Display](https://move-book.com/programmability/display) to customize how your objects show up in wallets, apps, and explorers. | ||
| - Avoid “self-transfers”—whenever possible, return the object from the current function, so it can be used in a different command in a [Programmable Transaction Block](./sui-101/working-with-ptbs.mdx). |
There was a problem hiding this comment.
Suggested change
| - Avoid “self-transfers”—whenever possible, return the object from the current function, so it can be used in a different command in a [Programmable Transaction Block](./sui-101/working-with-ptbs.mdx). | |
| - 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](/guides/developer/sui-101/working-with-ptbs.mdx). |
| - Use the [Sui Object Display](https://move-book.com/programmability/display) to customize how your objects show up in wallets, apps, and explorers. | ||
| - Avoid “self-transfers”—whenever possible, return the object from the current function, so it can be used in a different command in a [Programmable Transaction Block](./sui-101/working-with-ptbs.mdx). | ||
|
|
||
| ### Package Upgrades |
There was a problem hiding this comment.
Suggested change
| ### Package Upgrades | |
| ### Package upgrades |
| ### Package Upgrades | ||
|
|
||
| - Read about [package upgrades](../../concepts/sui-move-concepts/packages/upgrade.mdx) before publishing your package. | ||
| - Packages are immutable, so any published package can be called forever. Use [object versioning](../../concepts/sui-move-concepts/packages/upgrade.mdx#versioned-shared-objects) to prevent older versions from being called. |
There was a problem hiding this comment.
Suggested change
| - Packages are immutable, so any published package can be called forever. Use [object versioning](../../concepts/sui-move-concepts/packages/upgrade.mdx#versioned-shared-objects) to prevent older versions from being called. | |
| - Packages are immutable, so any published package can be called forever. Use [object versioning](/concepts/sui-move-concepts/packages/upgrade.mdx#versioned-shared-objects) to prevent older versions from being called. |
|
|
||
| - Read about [package upgrades](../../concepts/sui-move-concepts/packages/upgrade.mdx) before publishing your package. | ||
| - Packages are immutable, so any published package can be called forever. Use [object versioning](../../concepts/sui-move-concepts/packages/upgrade.mdx#versioned-shared-objects) to prevent older versions from being called. | ||
| - If you upgrade a package `P` to `P'`, other packages and clients that depend on `P` will continue using `P`, not auto-update to `P'`. Both dependent packages and client code must be explicitly updated to point at `P'`. |
There was a problem hiding this comment.
Suggested change
| - If you upgrade a package `P` to `P'`, other packages and clients that depend on `P` will continue using `P`, not auto-update to `P'`. Both dependent packages and client code must be explicitly updated to point at `P'`. | |
| - 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`. |
| - Read about [package upgrades](../../concepts/sui-move-concepts/packages/upgrade.mdx) before publishing your package. | ||
| - Packages are immutable, so any published package can be called forever. Use [object versioning](../../concepts/sui-move-concepts/packages/upgrade.mdx#versioned-shared-objects) to prevent older versions from being called. | ||
| - If you upgrade a package `P` to `P'`, other packages and clients that depend on `P` will continue using `P`, not auto-update to `P'`. Both dependent packages and client code must be explicitly updated to point at `P'`. | ||
| - 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](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move) across a bridge from Wormhole. Extension packages that produce messages to send can use [`prepare_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L68-L90) from any version of the Wormhole package to produce a [`MessageTicket`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L52-L66) while client code to send the message must pass that `MessageTicket` into [`publish_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L92-L152) in the latest version of the package. |
There was a problem hiding this comment.
Suggested change
| - 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](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move) across a bridge from Wormhole. Extension packages that produce messages to send can use [`prepare_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L68-L90) from any version of the Wormhole package to produce a [`MessageTicket`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L52-L66) while client code to send the message must pass that `MessageTicket` into [`publish_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L92-L152) in the latest version of the package. | |
| - 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](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move) across a bridge example from Wormhole. Extension packages that produce outbound messages can use [`prepare_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L68-L90) from any version of the Wormhole package to produce a [`MessageTicket`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L52-L66) while client code that sends the message must pass that `MessageTicket` into [`publish_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L92-L152) in the latest version of the package. |
| - If you upgrade a package `P` to `P'`, other packages and clients that depend on `P` will continue using `P`, not auto-update to `P'`. Both dependent packages and client code must be explicitly updated to point at `P'`. | ||
| - 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](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move) across a bridge from Wormhole. Extension packages that produce messages to send can use [`prepare_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L68-L90) from any version of the Wormhole package to produce a [`MessageTicket`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L52-L66) while client code to send the message must pass that `MessageTicket` into [`publish_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L92-L152) 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, add new fields (though you can add dynamic fields), or add new [abilities](https://move-book.com/reference/abilities) via an upgrade. Introduce new types carefully—they will live forever! |
There was a problem hiding this comment.
Suggested change
| - It is not possible to delete `struct` types, add new fields (though you can add dynamic fields), or add new [abilities](https://move-book.com/reference/abilities) via an upgrade. Introduce new types carefully—they will live forever! | |
| - It is not possible to delete `struct` types. Add new fields (though you can add dynamic fields), or add new [abilities](https://move-book.com/reference/abilities) via an upgrade. Introduce new types carefully as they will live forever. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Describe the changes or additions included in this PR.
Test plan
How did you test the new or updated feature?
Release notes
Check each box that your changes affect. If none of the boxes relate to your changes, release notes aren't required.
For each box you select, include information after the relevant heading that describes the impact of your changes that a user might notice and any actions they must take to implement updates.