supra-ts-sdk - v2.0.0
    Preparing search index...

    Interface OptionalTransactionPayloadArgs

    Per-transaction settings. Each one that is set replaces the client's setting for this transaction. The SDK does not modify the object.

    • maxGas: max gas of the transaction, in gas units. When absent, the client's maxGas applies; when that is absent too, the max gas is estimated (see estimateMaxGas).
    • gasUnitPrice: gas unit price, in quants, used as given. Default the client's gasUnitPrice, else the node's estimate, max(median gas price, minimum gas price) of GET /rpc/v3/transactions/estimate_gas_price, read for each transaction. In the helpers that submit, the read starts when the call is made and is awaited in the call's turn for the sender's account (SUPRA fungible asset transfers check the sender's balances first, and the multisig propose and execute helpers read the ABI of the proposal's function or the next proposal first, before the account is requested, and for these the price read starts after those reads, not when the call is made); transaction.build.simple awaits it before it builds. The max gas estimate uses the same price. A price below the node's minimum is refused by the node with SupraGasUnitPriceBelowMinimumError (its cause is the original error); the SDK does not change it. A failed read of the estimate throws its error and nothing is submitted.
    • txExpiryTime: expiration time of the transaction, in seconds since the Unix epoch, used as given. Default the client's txExpirySecs (default DEFAULT_TX_EXPIRATION_DURATION, 60) seconds after the client's clock in whole seconds when the transaction is built, at most TX_EXPIRATION_MARGIN_SECS (5) seconds less than the node's maximum time to live (max_transaction_time_to_live_seconds, 600 on Mainnet, Testnet and Devnet). The builders that send requests read the maximum once per client and throw the error of a failed read; the builders that send none use the maximum the client has read, else ASSUMED_MAX_TX_EXPIRATION_DURATION (600), and throw a RangeError when txExpirySecs is more than it, naming the maximum and saying whether it was read or assumed (getTransactionParameters() reads it first). Signing throws a RangeError for an expiration time more than TX_EXPIRATION_MARGIN_SECS (5) seconds beyond the node's maximum after the later of the client's clock and the chain time it estimates from its reads of the latest block.
    • estimateMaxGas: when no maxGas is set, estimate it (true) or use DEFAULT_MAX_GAS_UNITS (false). Default the client's estimateMaxGas, else true.

    The node accepts a transaction only when the sender's balance pays for max gas × gas unit price; the sender is charged for the gas used. An estimate is made by the methods that build and submit a transaction with a signing account: the coin and fungible asset transfers, publishPackage, cancelAutomationTask, stopAutomationTasks, the multisig helpers and contract entry calls. They read the sender's SUPRA balance and simulate the transaction with a max gas of the largest number of gas units that balance pays for at the gas unit price, at most MAX_GAS_UNITS_PER_TRANSACTION. The max gas is then ceil(gas used × DEFAULT_MAX_GAS_ESTIMATE_MULTIPLIER) (or the client's maxGasEstimateMultiplier), at least MIN_ESTIMATED_MAX_GAS_UNITS, and at most the number of units the balance pays for.

    • When the simulation's status is not Success (an abort, OUT_OF_GAS, PendingAfterExecution, Invalid), SupraSimulationFailedError is thrown and nothing is submitted.
    • When the balance read fails, or the simulation fails for a reason that is not a simulation result (a request error, a response without gas_used), the max gas is DEFAULT_MAX_GAS_UNITS, at most the number of units the balance pays for when that is known.

    The simulation runs against committed state. When an earlier transaction of the sender has not committed, the simulation reports the sequence number as too new, and the account and the latest block are read. When every number from the sender's sequence number on the chain up to the transaction's has a record of a transaction this client submitted that can still commit (see SupraConfig), the transaction is simulated with the chain's number and submitted with its own. Otherwise a helper that took the number from the client's counter builds and signs the transaction again with the lowest number that has no record, without giving up its place in the order of the calls, and a call with an explicit sequenceNumber throws the SupraSimulationFailedError. A failed read of the account is thrown and nothing is submitted. A transaction that depends on an earlier one that has not committed (for example one that uses a resource the earlier one creates) fails its estimate and throws SupraSimulationFailedError; set maxGas for such a transaction.

    A helper call without maxGas holds the sender's account while its max gas is estimated, and the calls of the same client from that account wait; a call with maxGas waits only until the calls ahead of it have been submitted or have failed (see SupraConfig).

    transaction.build.simple has no signing account to simulate with: its max gas is DEFAULT_MAX_GAS_UNITS, at most the number of gas units the sender's balance pays for. The builders that make no request (rawTxnObject, scriptRawTxnObject, automationRegistrationRawTxnObject, multisigRawTxnObject and multisigProposalTxRawTxnObject) use DEFAULT_MAX_GAS_UNITS (20,000 units). The node requires the sender's SUPRA balance to cover max gas × gas unit price at validation: 20,000 units at a gas unit price of 100,000 quants need 20 SUPRA (2,000,000,000 quants). A sender with less must set maxGas.

    The gas unit price is not estimated by the builders that make no request: without a gasUnitPrice on the call or the client they throw a RangeError before building.

    interface OptionalTransactionPayloadArgs {
        maxGas?: bigint;
        gasUnitPrice?: bigint;
        txExpiryTime?: bigint;
        estimateMaxGas?: boolean;
        sequenceNumber?: number | bigint;
    }
    Index
    maxGas?: bigint
    gasUnitPrice?: bigint
    txExpiryTime?: bigint
    estimateMaxGas?: boolean
    sequenceNumber?: number | bigint

    The sequence number of the transaction. Used by the helpers that build and submit the transaction (transferSupraCoin, transferCoin, transferSupraFungibleAsset, transferFungibleAsset, migrateCoinToFungibleStore, publishPackage, cancelAutomationTask, stopAutomationTasks, the multisig helpers and the entry functions of Contract.fromABI). When it is set, the helper uses it as given and does not wait for the other calls of the account; the client's counter records the submitted transaction like its own and does not hand out its number while the transaction can commit. When it is absent, the helper takes the next number of the client's counter, and the call does not deduplicate: a repeated call, including one from a restarted process that builds the same transaction again, submits a new transaction, with the next number when the node already holds the same transaction. With this field set, a call that builds the same transaction as a pending one is handled as a submission of that transaction (see Submit). The builders of transaction.build take senderSequenceNumber and ignore this field.