When building on the Sui blockchain, a fundamental concept is the ownership object. Objects owned by an address are critical for highly parallelizable transactions. They also logically map to assets or resources that are exclusively owned by someone. Tokens are a classic use case for ownership objects, with cash serving as a real-world analogy.
However, the paradigm of ownership objects—particularly concerning tokens—diverges somewhat from the balance concept seen in other blockchains. In other systems, especially those based on accounts, tokens reside in a single location (or field), much like a balance in a bank account.
Since Sui uses ownership objects instead of balances, it's common to own multiple tokens, sometimes even a significant number. Certain scenarios require merging some or all of these tokens into a single object. In some cases, merging tokens becomes necessary because the amount required to execute a transaction exceeds the value of any single token owned by the sender, making consolidation an unavoidable step.
Using the SDK
Sui's SDKs—available in TypeScript and Rust—handle token management on your behalf, eliminating the need for manual intervention. These SDKs attempt to merge tokens when possible and assume that transactions are executed sequentially. This is a reasonable assumption, especially for wallet-based transactions and common scenarios in general. Sui recommends relying on this functionality when large-scale parallel or concurrent execution isn't required.
Gas Smashing
When executing a transaction, Sui allows you to provide multiple tokens as payment. In other words, payment can be a vector of tokens, not just a single token. This feature, known as gas smashing, automatically performs token consolidation. It provides your Programmable Transaction Block (PTB) with a single gas token that can be used for purposes other than just gas.
Essentially, you can provide as many tokens as allowed (within the maximum limit defined by the protocol configuration), and they are all merged ("smashed") into the first token provided. This token, after deducting the gas budget, can then be used within the transaction for any command. If the token isn't used, it is returned to the user.
Gas smashing is a crucial feature—and a key concept to understand—for optimal token management. For more details, refer to the official documentation on Gas Smashing.
Generic Tokens
Gas smashing works effectively for Coin objects, which are the only type of token that can be used to pay for gas.
Any other token type requires explicit management by the user. PTBs provide a mergeCoins command that you can use to combine multiple tokens into a single one. There's also a complementary splitCoins operation to break them apart.
From a cost perspective, these are very inexpensive transactions. However, they require users to be aware of their token distribution and their specific needs.
👉 Explore advanced token management strategies
Concurrency Considerations
In scenarios requiring heavy or high concurrency, merging tokens—especially Coin objects—into a single token or a very small number of tokens can sometimes cause issues.
If all Coin objects are merged into a single token, each transaction must be submitted sequentially. Because a token is an ownership object, you must provide its version when signing a transaction. After executing a transaction that locks it, the system marks it as locked, making it unavailable for use in other transactions. Furthermore, attempting to sign multiple transactions with the same token can lead to ambiguity, rendering the token unusable and locked until the epoch ends.
Therefore, when high concurrency is needed, you should first split a token into as many tokens as the number of transactions you intend to execute concurrently. Alternatively, you can provide multiple distinct tokens for different transactions (using gas smashing). It is crucial that the sets of tokens used in different transactions have no overlap whatsoever.
Many potential issues can arise when dealing with heavy concurrency. Concurrency in transaction execution isn't the only performance bottleneck. When creating and submitting transactions, several rounds of communication with a full node may be required to discover and fetch the correct objects and handle transaction interference. These round trips can significantly impact performance.
Concurrency is a complex topic that extends beyond the scope of this document. When managing tokens in concurrent situations, you must exercise extreme caution. The correct strategy is often highly dependent on the specific scenario rather than being universally applicable.
Frequently Asked Questions
What is an ownership object in Sui?
An ownership object is a fundamental building block in Sui that represents an asset or resource exclusively owned by an address. It enables highly parallelizable transactions and differs from the balance-based model used in some other blockchains.
Why would I need to merge tokens on Sui?
Merging tokens is necessary when a transaction requires a greater amount than any single token you possess. Consolidating multiple tokens into one allows you to meet the minimum value required for the transaction to proceed.
Does gas smashing work for all token types?
No, gas smashing is specifically designed for Coin objects, which are the only type used for gas payments. Other token types require manual management using commands like mergeCoins and splitCoins.
How does concurrency affect token management?
High concurrency requires careful token distribution. Using a single token for multiple concurrent transactions can cause locking and failures. It is better to split tokens beforehand or use distinct sets of tokens for different transactions.
Are merge and split operations expensive on Sui?
No, both mergeCoins and splitCoins are very low-cost transactions. However, users must still be mindful of their token distribution strategies to avoid unnecessary operations.
What should I do if a token becomes locked?
If a token is locked due to ambiguous transaction attempts, it typically becomes available again at the end of the epoch. To avoid this, ensure you do not use the same token for multiple simultaneous transactions.