Skip to main content

Gas Smashing

info

If you are using the address balances feature, then you do not need to use gas smashing. Address balance gas payment removes the need to select or merge gas coins entirely.

Every transaction on Sui has a gas fee that must be paid for successful execution. Gas smashing lets you pay this fee using multiple coins instead of a single one. This is useful when you have many smaller denomination coins or want to reduce the number of coins in your account. Gas smashing is most powerful when paired with the GasCoin programmable transaction block (PTB) argument.

Gas smashing happens automatically in a transaction if you provide multiple coins to pay for the gas fee. When Sui executes the transaction, the network combines, or smashes, all of the provided coins into a single coin. Smashing occurs regardless of coin amounts or the gas budget provided with the transaction, as long as it is within the minimum and maximum gas budgets. Sui deducts the gas fee from the single coin regardless of the execution status of the transaction. This means that even if the transaction fails to execute for some reason, such as an execution error, the provided gas coins remain smashed after the transaction's execution.

This design makes gas smashing a practical way to both manage coins and pay gas in the same transaction, as you can combine many small coins while simultaneously executing unrelated operations in one PTB.

You can smash at most 256 coins in a single PTB. Transactions with more than 256 gas coins fail.

Gas smashing and address balance gas payment​

In the basic case, gas smashing merges the real Coin<SUI> objects that you supply as gas payment. When you provide multiple Coin<SUI> objects, the network merges them into a single coin and deducts the gas fee from that coin.

Address balance gas payment is different. When you pay gas from an address balance, you do not select or provide any coin objects. The network resolves the gas fee as a withdrawal from your reserved address balance funds, so there is no gas coin selection or merge workflow, and gas smashing is not needed.

The compatibility layer can present compatibility coin reservations to older clients. A compatibility coin reservation is a synthetic object reference that reserves address balance funds, not a persisted Coin<SUI> object. These reservations still participate in gas smashing, and the outcome depends on which gas payment you list first:

  • If the first payment is a real Coin<SUI>, the network smashes every payment into that coin. Any coin reservation is fully withdrawn from the address balance into the resulting coin.
  • If the first payment is a coin reservation, the network smashes all of the real coins and sends the combined balance to your address balance.

You can also use a coin reservation deliberately, even when you do not need the compatibility layer. If you pay gas from an address balance but want extra SUI available within the PTB, you have two options:

  • Add additional fund withdrawals as input arguments.
  • Use a coin reservation larger than the gas budget. The excess amount is available through the GasCoin argument in the PTB, just as it is with Coin-based gas payments. This is helpful for PTB templates and similar cases.

To pay gas from an address balance, see Paying for gas from address balances. For details on the compatibility layer, see Compatibility coin reservations for legacy clients.

Rebates​

All but the first coin are deleted, often generating a storage rebate. Rebates cannot be applied to pay for gas in the same transaction. Instead, the rebate and the remaining balance after gas deduction are credited to the first coin once execution completes.

Running out of gas with a refund​

Because smashing always occurs, storage rebates can lead to unusual outcomes where a transaction both runs out of gas and still produces a net refund.

Consider the following scenario:

  • Transaction T has a gas budget of 5000.

  • You provide 5 coins with the balances: C1 = 1000, C2 = 2000, C3 = 3000, C4 = 4000, C5 = 5000.

  • The storage rebate per coin is 2000.

  • If the gas cost exceeds the 5000 budget, T fails with OutOfGas.

However, after smashing and rebates:

Final balance in C1 =
  (1000 + 2000 + 3000 + 4000 + 5000)   // all coin balances
  - 5000                               // gas cost
  + (2000 * 4)                         // rebates for deleted coins
= 15000 - 5000 + 8000
= 18000

In this case, T fails but you still receive a net refund of 3000.