Paying for Sui Transactions with Gas Coins

With Programmable Transactions, you can use the gas payment coin to construct coins with a set balance using splitCoin. This is useful for Sui payments, and avoids the need for up-front coin selection. You can use tx.gas to access the gas coin in a transaction, and it is valid as input for any arguments, as long as it is used by-reference (opens in a new tab). Practically speaking, this means you can also add to the gas coin with mergeCoins and borrow it for Move functions with moveCall.

You can also transfer the gas coin using transferObjects, in the event that you want to transfer all of your coin balance to another address.

Gas configuration

The new transaction builder comes with default behavior for all gas logic, including automatically setting the gas price, budget, and selecting coins to be used as gas. This behavior can be customized.

Gas price

By default, the gas price is set to the reference gas price of the network. You can also explicitly set the gas price of the transaction by calling setGasPrice on the transaction builder.

tx.setGasPrice(gasPrice);

Budget

By default, the gas budget is automatically derived by executing a dry-run of the transaction beforehand. The dry run gas consumption is then used to determine a balance for the transaction. You can override this behavior by explicitly setting a gas budget for the transaction, by calling setGasBudget on the transaction builder.

Note: The gas budget is represented in Sui, and should take the gas price of the transaction into account.

tx.setGasBudget(gasBudgetAmount);

Gas payment

By default, the gas payment is automatically determined by the SDK. The SDK selects all of the users coins that are not used as inputs in the transaction.

The list of coins used as gas payment will be merged down into a single gas coin before executing the transaction, and all but one of the gas objects will be deleted. The gas coin at the 0-index will be the coin that all others are merged into.

// you need to ensure that the coins do not overlap with any
// of the input objects for the transaction
tx.setGasPayment([coin1, coin2]);

Gas coins should be objects containing the coins objectId, version, and digest (ie { objectId: string, version: string | number, digest: string }).