Skip to content

Transaction options

For every transaction it is possible to provide an options object with one or multiple of the following attributes to the respective function that builds and broadcasts the transaction. Some of these are common and can be provided for each transaction type. Others are transaction specific and only relevant for a specific tx-type.

The options object can be optionally passed to the respective function behind the last parameter, example:

const sender = 'ak_...';
const recipient = 'ak_...';
const options = { onAccount: sender, denomination: 'ae' }; // optional options object
// aeSdk is an instance of the AeSdk class
await aeSdk.spend(1, recipient, options); // amount, recipient and (optional) options

Note:

  • Without the options object the sender would be some other account selected in the instance of AeSdk and the recipient would receive 1 aetto instead of 1 AE.
  • buildTxAsync doesn't write the values it prepared (nonce, ttl, fee, gasPrice, …) back into the object it was given: pass the same object to two builds and the second prepares them again, instead of reusing values priced for the first. Read a prepared value off the built transaction with unpackTx. Only direct callers are affected — spend and the other high-level methods copy the options object before building.

Common options

These options are common and can be provided to every tx-type:

  • onAccount (default: the first account defined in the account array of the SDK instance)
  • You can specify the account that should be used to sign a transaction.
  • Note:
    • The account needs to be provided to the SDK instance in order to be used for signing.
  • nonce (default: obtain nonce of the account via node API)
  • The default behavior might cause problems if you perform many transactions in a short period of time.
  • You might want to implement your own nonce management and provide the nonce "manually".
  • 2 different strategies to use in order to determine the next nonce, See option strategy to learn more.
  • strategy (default: max)
  • The strategy to obtain next nonce for an account via node API
  • If set to max, then the greatest nonce seen in the account or currently in the transaction pool is incremented with 1 and returned. If the strategy is set to continuity, then transactions in the mempool are checked if there are gaps - missing nonces that prevent transactions with greater nonces to get included
  • ttl (default: 0 if buildTx used, current height + 3 otherwise)
  • Should be set if you want the transaction to be only valid until a certain block height is reached.
  • fee (default: calculated for each tx-type, based on network demand)
  • The minimum fee is dependent on the tx-type.
  • You can provide a higher fee to additionally reward the miners.
  • The default is also raised to the minimum gas price the miner of the connected node accepts, so that the node the transaction is submitted to is willing to mine it.
  • The minimum is counted at that same price, and so is the smallest fee accepted here. Node refuses a transaction priced below it with too_low_gas_price_for_miner.

  • protocolParameters (default: requested from node)

  • Consensus parameters the minimum fee and the maximum gas limit are calculated from. Accepted by every tx-type that has a fee or a gasLimit.

  • Requested by buildTxAsync at /v3/protocol-parameters and /v3/node-settings, so that a network running other parameters than the SDK release doesn't get underpriced transactions. Not requested if the transaction provides every value they would price (fee, gasPrice, gasLimit) and nests no transaction that still has to be built — such a build needs no node, as it didn't before. Those values are then checked against defaultProtocolParameters instead, so on a network running a lower minimum gas price provide this option (or leave one of the priced values out) to have the parameters of node applied.
  • Falls back to defaultProtocolParameters — the values as they were at the moment of the SDK release — for a node that doesn't provide the endpoints, can't be reached, or answers something this SDK release can't read. The two responses are taken as a set, and a single value node doesn't report falls back on its own, so that a node omitting a transaction type doesn't make that type unbuildable.
  • Provide this option to build a transaction offline for a node running other parameters. It is used for the nested transaction of a PayingForTx/GaMetaTx as well, unless that transaction is already built, and by buildAuthTxHash, which prices the same gasPrice.
  • The minimum fee is counted at the higher of minGasPrice and minMinerGasPrice, see getFloorGasPrice. To build for a network accepting a lower gas price lower both: { ...defaultProtocolParameters, minGasPrice } alone keeps the miner minimum of the SDK release.
  • Parameters that would raise the minimum transaction fee, or the cost of a contract transaction (gasPrice * gasLimit), more than 1000 times above the one of the SDK release are rejected, so that a node can't make the SDK build a transaction with an extreme fee. Each limit is on what the parameters produce together. Provide this option to build against such parameters anyway.
  • Within that limit, the values the SDK picks itself are lowered by the factor node raised them by, so each product stays within the one of the SDK release: the gas price ceiling the fee/gasPrice default is based on (the transaction may then be priced below the current demand and take longer to be mined — provide gasPrice/fee to pay more), and the gasLimit a transaction defaults to (provide gasLimit, or gasMax, to choose the amount at risk yourself).
  • The parameters provided in this option are used as they are — the limits above are exactly what this option is the way out of — beyond a check that they can price a transaction at all. They are as trusted as fee and gasLimit are, and like them must not be taken from input the application doesn't control: they decide what those very values are checked against.
  • A transaction that already exists is never re-checked against them, nor against the other consensus limits of the SDK release (the AENS name fee, the name TTL, the pointer count). Use rebuildUnpackedTx instead of buildTx to serialize the result of an unpackTx back, so that a transaction built for another network keeps working — plain buildTx prices it as if it were new, and rejects a fee or a gas price below the minimum this process builds against.

  • Only the parameters the fee and the gas limit are counted from are requested from node. The AENS name fees, the name TTL maximum, the pointer count maximum, and the vm/abi versions a contract may use are still the ones of the SDK release, even though node reports them too.

  • innerTx (default: false)

  • Should be used for signing an inner transaction that will be wrapped in a PayingForTx.
  • verify (default: false)
  • If set to true the transaction will be verified prior to broadcasting it.
  • waitMined (default: true)
  • Wait for transactions to be mined.
  • You can get the tx object that contains the tx-hash immediately by setting to false and should implement your own logic to watch for mined transactions.

Tx-type specific options

The following options are sepcific for each tx-type.

ContractCreateTx & ContractCallTx

  • amount (default: 0)
  • To be used for providing aettos (or AE with respective denomination) to a contract related transaction.
  • denomination (default: aettos)
  • You can specify the denomination of the amount that will be provided to the contract related transaction.
  • gasLimit
  • Maximum amount of gas to be consumed by the transaction. Learn more on How to estimate gas?
  • gasPrice (default: based on network demand, minimum: the higher of the consensus and the miner minimum gas price reported by node, 1e9 if not reported or not requested — see protocolParameters)
  • To increase chances to get your transaction included quickly you can use a higher gasPrice.
  • Node prices a contract transaction by the lower of gasPrice and the fee over its gas, so both are held to that minimum. Provide protocolParameters to build for another node.

NameClaimTx

  • nameFee (default: calculated based on the length of the name)
  • The fee in aettos that will be payed to claim the name.
  • For bids in an auction you need to explicitely calculate the required nameFee based on the last bid

NameUpdateTx

  • clientTtl (default: 3600, one hour)
  • This option is an indicator for indexing tools to know how long (in seconds) they could or should cache the name information.
  • nameTtl (default: 180000)
  • This option tells the protocol the relative TTL based on the current block height.
  • 180000 is the maximum possible value

OracleRegisterTx

  • queryFee (default: 0)
  • The fee in aettos that the oracle requests in order to provide a response.
  • oracleTtlValue (default: 500)
  • The TTL of the oracle that defines its expiration.
  • oracleTtlType (default: ORACLE_TTL_TYPES.delta)
  • ORACLE_TTL_TYPES.delta: TTL value treated relative to a current block height
  • ORACLE_TTL_TYPES.block: TTL value treated as absolute block height

OracleQueryTx

  • queryFee (default: 0)
  • The fee in aettos that will be payed to the oracle.
  • queryTtlValue (default: 10)
  • The TTL of the query that defines its expiration. The oracle needs to respond before the queryTtl expires.
  • queryTtlType (default: ORACLE_TTL_TYPES.delta)
  • ORACLE_TTL_TYPES.delta: TTL value treated relative to a current block height
  • ORACLE_TTL_TYPES.block: TTL value treated as absolute block height
  • responseTtlValue (default 10)
  • The TTL of the response that defines its expiration. The response of the oracle will be garbage collected after its expiration.
  • responseTtlType (default ORACLE_TTL_TYPES.delta)
  • ORACLE_TTL_TYPES.delta: TTL value treated relative to a current block height
  • ORACLE_TTL_TYPES.block: TTL value treated as absolute block height

SpendTx

  • denomination (default: aettos)
  • You can specify the denomination of the amount that will be provided to the contract related transaction.

How to estimate gas?

  • As æpp developer, it is reasonable to estimate the gas consumption for a contract call using the dry-run feature of the node once and provide a specific offset (e.g. multiplied by 1.5 or 2) as default in the æpp to ensure that contract calls are mined. Depending on the logic of the contract the gas consumption of a specific contract call can vary and therefore you should monitor the gas consumption and increase the default for the respective contract call accordingly over time.
  • By default, SDK estimates gasLimit using dry-run endpoint. This means an extra request that makes contract iterations slower, but it is more developer friendly (support of heavy requests without adjustments, and verbose error messages).