Paying for IOTA 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 IOTA 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](../../../../developer/iota-101/transactions/ptb/simulating-refs.mdx. 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 IOTA, 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 }).