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

    Type Alias SupraConfig

    SupraConfig:
        | {
            network: MAINNET
            | TESTNET
            | DEVNET;
            maxGas?: bigint;
            gasUnitPrice?: bigint;
            estimateMaxGas?: boolean;
            maxGasEstimateMultiplier?: number;
            timeoutMs?: number;
            retry?: RetryConfig;
            waitTimeoutMs?: number;
            txExpirySecs?: number;
            verifyChainId?: boolean;
        }
        | {
            network?: CUSTOM;
            rpcUrl: string;
            chainId: number;
            maxGas?: bigint;
            gasUnitPrice?: bigint;
            estimateMaxGas?: boolean;
            maxGasEstimateMultiplier?: number;
            timeoutMs?: number;
            retry?: RetryConfig;
            waitTimeoutMs?: number;
            txExpirySecs?: number;
            verifyChainId?: boolean;
        }

    The SupraConfig interface is used to configure the SupraClient class. maxGas sets the max gas of every transaction that sets none; without it the max gas is estimated (see OptionalTransactionPayloadArgs). gasUnitPrice sets the gas unit price of every transaction that sets none, used as given and in quants; without it each transaction that sets none carries the node's estimate, max(median gas price, minimum gas price) of GET /rpc/v3/transactions/estimate_gas_price, read for each transaction (getEstimatedGasUnitPrice()). The builders that make no request need a price on the call or here (see OptionalTransactionPayloadArgs). estimateMaxGas: false turns the estimate off: a transaction without maxGas then has DEFAULT_MAX_GAS_UNITS. A simulation whose status is not Success throws SupraSimulationFailedError and nothing is submitted; the simulation runs against committed state, so a transaction that depends on an earlier one that has not committed fails its estimate, and needs maxGas. maxGasEstimateMultiplier replaces DEFAULT_MAX_GAS_ESTIMATE_MULTIPLIER, the factor applied to the simulated gas used; it must be a finite number of at least 1.

    Sequence numbers: the client keeps a sequence-number counter for each account its helpers send from (the coin and fungible asset transfers, migrateCoinToFungibleStore, publishPackage, cancelAutomationTask, stopAutomationTasks, the multisig helpers and the entry functions of Contract.fromABI), and submits the calls of one account one after another. A call holds the account from taking its number until the node answers its submission (accepted, refused, or the request fails); the wait for the final status comes after that. A call without maxGas (here or on the call) holds the account while its max gas is estimated; a call with maxGas waits only until the calls ahead of it have been submitted or have failed. To submit faster from one account, set maxGas; to submit in parallel, send from several accounts. A call with an explicit sequenceNumber does not take part in this order. Calls request the account in the order they are made, except that SUPRA fungible asset transfers (balance checks) and the multisig propose and execute helpers (the ABI of the proposal's function, the next proposal) await reads before they request it. A helper call that takes its number from the counter 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.

    The counter records every transaction of the account that the client submitted (accepted, or whose submission request failed without an answer, explicit sequenceNumbers included) with its expiration time and hash (for a request without an answer, the hash derived from the signed transaction before the submission), and hands out the lowest number at or above the account's sequence number on the chain that has no record. A submission whose request failed without an answer holds its number until the transaction's expiration time or resetSequenceNumber, including when its expiration time was beyond what a node accepts. A record is dropped when the chain's number passes it, when the timestamp of a latest block the client reads (GET /rpc/v3/block) has reached its expiration time, or when a read of the transaction returns Invalid; an HTTP 404 does not drop it. The first use of an account reads the account and the latest block; so does the next call after a refusal for a stale number or a full queue (SupraAccountQueueFullError), and every call while the estimated chain time (the newest latest block's timestamp read plus the time elapsed since that read on a monotonic clock, never decreasing) has passed the expiration time of a record by two seconds and no latest block read has reached it.

    txExpirySecs sets the expiration time of every transaction built without txExpiryTime: that many seconds after the client's clock in whole seconds, at most TX_EXPIRATION_MARGIN_SECS (5) seconds less than the node's maximum time to live, so that a node whose clock is up to 5 seconds behind the client's accepts it. A positive integer; default DEFAULT_TX_EXPIRATION_DURATION (60). The constructor throws a RangeError otherwise. The node's maximum (max_transaction_time_to_live_seconds of GET /rpc/v3/transactions/parameters, 600 on Mainnet, Testnet and Devnet) is read once per client by the first builder or signature that needs it, and getTransactionParameters() reads it again. A builder that sends requests throws a RangeError when txExpirySecs is more than the maximum, and throws the error of a failed read of it, with no fallback. Signing throws a RangeError before signing when a transaction's expiration time, whoever set it, is more than the maximum after the later of the client's clock and the chain time it estimates from its reads of the latest block; with verifyChainId: false signing sends no request and does not check it. The builders that send no request (transaction.build.rawTxnObject and the like) use the maximum the client has read, else ASSUMED_MAX_TX_EXPIRATION_DURATION (600), and throw a RangeError when txExpirySecs is more than it. Every RangeError of these checks names the maximum and says whether it was read from GET /rpc/v3/transactions/parameters or assumed because it had not been read; for an assumed one it names getTransactionParameters() as the way to read it first. The signing check allows TX_EXPIRATION_MARGIN_SECS (5) seconds beyond the maximum, because the client's estimate of the node's clock can trail it; the node refuses what it does not accept. The node refuses a transaction whose expiration time is not after its clock, or more than its maximum after it, so a client whose clock is far from the node's has its transactions refused.

    timeoutMs sets the timeout of each request (default 30000 ms; an integer up to 2147483647); a request that exceeds it throws SupraTimeoutError, and a submission request that exceeds it makes the submit helper throw SupraSubmissionOutcomeUnknownError; with enableWaitForTransaction, the helper first waits for the transaction's hash and throws it only when that wait ends without a final status. retry turns on retries of GET requests; it is off by default. waitTimeoutMs sets how long a wait for a transaction's final status lasts (waitForTransaction and submissions with enableWaitForTransaction) when the call sets no timeout (default 60000 ms); a wait that exceeds it throws SupraTransactionTimeoutError.

    Every setting belongs to the client it is passed to: network, rpcUrl, chainId, maxGas, gasUnitPrice, estimateMaxGas, maxGasEstimateMultiplier, timeoutMs, retry, waitTimeoutMs, txExpirySecs and verifyChainId. The client copies the configuration, so later changes to the object passed in do not reach it, and two clients never share settings, including two clients of the same predefined network. rpcUrl must be an absolute http: or https: URL, with or without trailing slashes and with or without a path prefix; the constructor throws a TypeError otherwise. chainId must be an integer from 0 to 255; the constructor throws a RangeError otherwise.

    Chain ID check: before its first signature the client reads the node's chain ID, from the x-supra-chain-id header of an earlier response or with GET /rpc/v3/transactions/chain_id, and keeps it for the client's lifetime. Every signature (signTransaction, the signedTransaction, sendTxnPayload, signTransaction, simulate and submitTransaction methods of a built transaction, the submit helpers that take a senderAccount, the coin and fungible asset transfers, publishPackage, the automation task helpers, the multisig helpers and the entry functions of Contract.fromABI) throws SupraChainIdMismatchError before signing when the configured chain ID or the chain ID of the transaction differs from the node's. verifyChainId: false turns the check off: the configured chain ID is used and signing sends no request, which allows signing offline.

    Type Declaration

    • {
          network: MAINNET | TESTNET | DEVNET;
          maxGas?: bigint;
          gasUnitPrice?: bigint;
          estimateMaxGas?: boolean;
          maxGasEstimateMultiplier?: number;
          timeoutMs?: number;
          retry?: RetryConfig;
          waitTimeoutMs?: number;
          txExpirySecs?: number;
          verifyChainId?: boolean;
      }
      • network: MAINNET | TESTNET | DEVNET
      • OptionalmaxGas?: bigint
      • OptionalgasUnitPrice?: bigint
      • OptionalestimateMaxGas?: boolean
      • OptionalmaxGasEstimateMultiplier?: number
      • OptionaltimeoutMs?: number
      • Optionalretry?: RetryConfig
      • OptionalwaitTimeoutMs?: number
      • OptionaltxExpirySecs?: number
      • OptionalverifyChainId?: boolean

        false signs with the network's chain ID without reading the node's. Default true.

    • {
          network?: CUSTOM;
          rpcUrl: string;
          chainId: number;
          maxGas?: bigint;
          gasUnitPrice?: bigint;
          estimateMaxGas?: boolean;
          maxGasEstimateMultiplier?: number;
          timeoutMs?: number;
          retry?: RetryConfig;
          waitTimeoutMs?: number;
          txExpirySecs?: number;
          verifyChainId?: boolean;
      }
      • Optionalnetwork?: CUSTOM
      • rpcUrl: string
      • chainId: number
      • OptionalmaxGas?: bigint
      • OptionalgasUnitPrice?: bigint
      • OptionalestimateMaxGas?: boolean
      • OptionalmaxGasEstimateMultiplier?: number
      • OptionaltimeoutMs?: number
      • Optionalretry?: RetryConfig
      • OptionalwaitTimeoutMs?: number
      • OptionaltxExpirySecs?: number
      • OptionalverifyChainId?: boolean

        false signs with chainId without reading the node's chain ID. Default true.