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

    Class Submit

    The Submit class provides methods for submitting transactions to the Supra network.

    Every submission in the SDK (the methods of this class, the submit methods of a built transaction, the coin and fungible asset transfers, publishPackage, the automation task helpers, the multisig helpers and the entry functions of Contract.fromABI) behaves as follows, controlled by enableTransactionWaitAndSimulationArgs:

    1. With enableTransactionSimulation, the transaction is simulated first. A simulated status other than Success throws SupraSimulationFailedError and nothing is submitted; a simulation refused because the gas unit price is below the node's minimum throws SupraGasUnitPriceBelowMinimumError instead (its cause is the SupraSimulationFailedError).
    2. The transaction's hash is derived from the signed transaction (as deriveTransactionHash does), and the transaction is submitted.
      • The node accepts it with a 2xx status. Its answer is the transaction's hash; an answer that is not a hash (a body that is not JSON, an empty body, or another value) is replaced by the derived hash. Steps 3 and 4 follow.

      • The node refuses it with a 4xx status or 503: SupraAPIError is thrown; the transaction was not accepted. A refusal because the gas unit price is below the node's minimum (a 400) throws SupraGasUnitPriceBelowMinimumError, which is not a SupraAPIError (its cause is the SupraAPIError). A v12 node whose transaction pool is full answers 503; the transaction can be submitted again later.

      • The node refuses it with a 400 because its pool already holds this transaction, for example when the same signed transaction was submitted before. For a transaction whose sequence number is the caller's (the methods of this class, the submit methods of a built transaction, and helper calls with sequenceNumber):

        • A v12 node names the transaction (transaction <hash> is already pending) after it has forwarded it again: the submission is handled as accepted, with the derived hash, and steps 3 and 4 follow.
        • A v11.7 node answers Already scheduled digest=<hash>, ..., also when its pool holds another transaction with the same sequence number at a gas unit price at least this one's, and does not forward the submission. The transaction is read by hash, once, within 5 seconds and without retries. Success or Fail: handled as accepted, as above. Pending (the node's pool holds it, and its earlier forward may have failed), another non-final status, or a failed read other than a 404: handled as an unknown outcome, as below (SupraSubmissionOutcomeUnknownError with the refusal as cause, or a wait for the derived hash with enableWaitForTransaction). A 404 or Invalid: the refusal is thrown as SupraAPIError. A 404 is taken to come from the node that refused the submission; several RPC nodes behind one URL can answer 404 for a transaction another of them holds.

        For a helper call whose number came from the client's counter, the transaction the node holds is another call's, since a helper does not deduplicate its calls: its number is kept as taken, and the helper sends its own transaction once more with the next number, as after a stale number. A repeated helper call, including one from a restarted process that builds the same transaction again, submits a new transaction.

      • The request times out, the connection fails before the node answers, or the node answers with a 5xx status other than 503: the node may have accepted the transaction, and SupraSubmissionOutcomeUnknownError is thrown with the derived hash, sender, sequenceNumber, expirationTimestampSecs and the error of the request (SupraTimeoutError, SupraNetworkError or SupraAPIError) as cause. Look the hash up or wait for it before sending the transaction again. A v11 node whose transaction pool is full answers 500, which is reported this way (see "HTTP status codes by node version" in the README). With enableWaitForTransaction, the call first waits for the derived hash as in step 3, and throws SupraSubmissionOutcomeUnknownError (with the wait's SupraTransactionTimeoutError as waitError) only when the wait ends without a final status.

      • Any other error of the request is thrown as it is.

    3. With enableWaitForTransaction, the call waits until the transaction has a final status, as waitForTransaction does:
      • Success: the transaction is returned.
      • Fail (executed and failed, for example a Move abort or Out of gas; the sequence number was incremented) or Invalid (discarded; the sequence number was not incremented): SupraTransactionFailedError is thrown with hash, status, vm_status, major_status, sub_status and transaction, unless checkSuccess is false.
      • Pending (not executed yet) and PendingAfterExecution (executed with a status that may change in a later execution) are not final; the call keeps reading the transaction, also while a read fails or returns 404. Without a final status within waitTimeoutMs (default SupraConfig.waitTimeoutMs, else 60000 ms) SupraTransactionTimeoutError is thrown with hash and lastStatus.
    4. Without enableWaitForTransaction, the transaction is read once and returned as the node reports it (usually Pending). When that read fails, the call returns { hash, status: "NotReadBack", readError } instead of throwing, because the node has accepted the transaction.

    Every error thrown after the node answered the submission with the transaction's hash carries that hash, and so does SupraSubmissionOutcomeUnknownError.

    Index
    • The constructor function takes a NetworkConfig object as a parameter and assigns it to the networkInformation property.

      Parameters

      • networkInformation: NetworkConfig

        A NetworkConfig object that contains information about the network on which the Supra client is running.

      Returns Submit

      import { SupraClient,Network } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });
    • Signs a raw transaction with the sender's key and submits it. The client checks the chain ID of its node before it signs; see SupraConfig.

      Parameters

      Returns Promise<SubmitTransactionResponse>

      SubmitTransactionResponse. The class description lists the statuses and errors of a submission.

      When the node refuses the submission or an enabled simulation because the gas unit price is below its minimum (this replaces SupraSimulationFailedError and SupraAPIError for that refusal).

      When the submission request times out, fails before the node answers or is answered with a 5xx status other than 503 (after the wait, with enableWaitForTransaction); carries the hash derived before the submission.

      Before signing, when the chain ID is not the node's.

      import { BCS, Network, SupraAccount, SupraClient } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });
      const account = new SupraAccount(); // an account that holds SUPRA

      async function runExample() {

      const supraCoinTransferRawTransaction = supra.transaction.build.rawTxnObject({
      senderAddress: account.address(),
      senderSequenceNumber: (await supra.account.getAccountInfo({ accountAddress: account.address() })).sequence_number,
      function: "0x1::supra_account::transfer",
      functionTypeArgs: [],
      functionArgs: [new SupraAccount().address().toUint8Array(), BCS.bcsSerializeUint64(10000n)],
      optionalTransactionPayloadArgs: { gasUnitPrice: await supra.getEstimatedGasUnitPrice() },
      });

      const txn = await supra.transaction.submit.submitRawTransaction({
      senderAccount: account,
      rawTransaction: supraCoinTransferRawTransaction,
      enableTransactionWaitAndSimulationArgs: {
      enableTransactionSimulation: true,
      enableWaitForTransaction: true
      }
      });

      console.log("Transaction submitted:", txn);
      }

      runExample().catch(console.error);
    • Signs a serialized raw transaction with the sender's key and submits it. The client checks the chain ID of its node before it signs; see SupraConfig.

      Parameters

      Returns Promise<SubmitTransactionResponse>

      SubmitTransactionResponse. The class description lists the statuses and errors of a submission.

      When the node refuses the submission or an enabled simulation because the gas unit price is below its minimum (this replaces SupraSimulationFailedError and SupraAPIError for that refusal).

      When the submission request times out, fails before the node answers or is answered with a 5xx status other than 503 (after the wait, with enableWaitForTransaction); carries the hash derived before the submission.

      Before signing, when the chain ID is not the node's.

      import { BCS, Network, SupraAccount, SupraClient } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });
      const account = new SupraAccount(); // an account that holds SUPRA

      async function runExample() {

      const supraCoinTransferRawTransaction = supra.transaction.build.rawTxnObject({
      senderAddress: account.address(),
      senderSequenceNumber: (await supra.account.getAccountInfo({ accountAddress: account.address() })).sequence_number,
      function: "0x1::supra_account::transfer",
      functionTypeArgs: [],
      functionArgs: [new SupraAccount().address().toUint8Array(), BCS.bcsSerializeUint64(10000n)],
      optionalTransactionPayloadArgs: { gasUnitPrice: await supra.getEstimatedGasUnitPrice() },
      });

      const supraCoinTransferRawTransactionSerializer = new BCS.Serializer();
      supraCoinTransferRawTransaction.serialize(
      supraCoinTransferRawTransactionSerializer
      );

      const txn = await supra.transaction.submit.submitSerializedRawTransaction({
      senderAccount: account,
      serializedRawTransaction: supraCoinTransferRawTransactionSerializer.getBytes(),
      enableTransactionWaitAndSimulationArgs: {
      enableTransactionSimulation: true,
      enableWaitForTransaction: true
      }
      });

      console.log("Transaction submitted:", txn);
      }

      runExample().catch(console.error);
    • Submits a serialized raw transaction with an ed25519 signature made elsewhere. No key is used and the chain ID is not checked; the node rejects a signature that does not match.

      Parameters

      Returns Promise<SubmitTransactionResponse>

      SubmitTransactionResponse. The class description lists the statuses and errors of a submission.

      When the node refuses the submission or an enabled simulation because the gas unit price is below its minimum (this replaces SupraSimulationFailedError and SupraAPIError for that refusal).

      When the submission request times out, fails before the node answers or is answered with a 5xx status other than 503 (after the wait, with enableWaitForTransaction); carries the hash derived before the submission.

      Before submitting, when senderPubkey or signature is not hex digits in pairs after its 0x prefix.

      import { BCS, Network, SupraAccount, SupraClient, TxnBuilderTypes } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });
      const account = new SupraAccount(); // an account that holds SUPRA

      async function runExample() {

      const supraCoinTransferRawTransaction = supra.transaction.build.rawTxnObject({
      senderAddress: account.address(),
      senderSequenceNumber: (await supra.account.getAccountInfo({ accountAddress: account.address() })).sequence_number,
      function: "0x1::supra_account::transfer",
      functionTypeArgs: [],
      functionArgs: [new SupraAccount().address().toUint8Array(), BCS.bcsSerializeUint64(10000n)],
      optionalTransactionPayloadArgs: { gasUnitPrice: await supra.getEstimatedGasUnitPrice() },
      });
      const supraCoinTransferSerializedRawTransaction = BCS.bcsToBytes(supraCoinTransferRawTransaction);

      const raw_txn = TxnBuilderTypes.RawTransaction.deserialize(
      new BCS.Deserializer(supraCoinTransferSerializedRawTransaction),
      );

      const signature = await supra.transaction.signTransaction({ senderAccount: account, rawTxn: raw_txn });

      const txn = await supra.transaction.submit.submitSerializedRawTransactionAndSignature({
      senderPubkey: account.pubKey(),
      signature,
      serializedRawTransaction: supraCoinTransferSerializedRawTransaction,
      enableTransactionWaitAndSimulationArgs: {
      enableTransactionSimulation: true,
      enableWaitForTransaction: true
      }
      });

      console.log("Transaction submitted:", txn);
      }

      runExample().catch(console.error);
    • Sends sponsor transaction. The authenticators are made with supra.transaction.signTransaction on a FeePayerRawTransaction, which checks the chain ID of the node before it signs; this method signs nothing.

      Parameters

      • args: {
            feePayerAddress: AccountAddressInput;
            secondarySignersAccountAddress: string[];
            rawTxn: RawTransaction;
            senderAuthenticator: AccountAuthenticatorEd25519;
            feePayerAuthenticator: AccountAuthenticatorEd25519;
            secondarySignersAuthenticator: AccountAuthenticatorEd25519[];
            enableTransactionWaitAndSimulationArgs?: EnableTransactionWaitAndSimulationArgs;
        }
        • feePayerAddress: AccountAddressInput

          Account address of tx fee payer

        • secondarySignersAccountAddress: string[]

          List of account address of tx secondary signers

        • rawTxn: RawTransaction

          The raw transaction to be submitted

        • senderAuthenticator: AccountAuthenticatorEd25519

          The sender account authenticator

        • feePayerAuthenticator: AccountAuthenticatorEd25519

          The fee payer account authenticator

        • secondarySignersAuthenticator: AccountAuthenticatorEd25519[]

          An optional array of the secondary signers account authenticator

        • OptionalenableTransactionWaitAndSimulationArgs?: EnableTransactionWaitAndSimulationArgs

          enable transaction wait and simulation arguments

      Returns Promise<SubmitTransactionResponse>

      SubmitTransactionResponse. The class description lists the statuses and errors of a submission.

      When the node refuses the submission or an enabled simulation because the gas unit price is below its minimum (this replaces SupraSimulationFailedError and SupraAPIError for that refusal).

      When the submission request times out, fails before the node answers or is answered with a 5xx status other than 503 (after the wait, with enableWaitForTransaction); carries the hash derived before the submission.

      Before submitting, when the fee payer address or a secondary signer address is not 1 to 64 hex digits after an optional 0x or 0X.

      A sender that has no Account resource sends its first transaction with sequence number 0. Check with supra.account.isAccountExists, which returns false for it on every node, and do not read the number with getAccountInfo, which throws for an absent account. The simulation with that number succeeds. A node from supra_node_v12.0.0 (Devnet) admits the submission and the transaction creates the account, so the sender's sequence number is 1 afterwards. A v11.7.x node (Mainnet, Testnet) refuses the submission with HTTP 400, "Transaction validation failed: Failed to read the AccountResource". rawTxnObject reads nothing from the node, so the number is the caller's. The fee payer pays the gas, but a new sender holds no SUPRA, so its payload must not spend from the sender's balance (a transfer from it aborts); create_account below spends nothing.

      import { Network, SupraAccount, SupraClient, TxnBuilderTypes } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });
      const account = new SupraAccount(); // the sender
      const feePayerAccount = new SupraAccount(); // an account that holds SUPRA and pays the fee

      async function runExample() {

      // 0 for a sender with no account, else the account's sequence number
      const accountAddress = account.address();
      const senderSequenceNumber = (await supra.account.isAccountExists({ accountAddress }))
      ? (await supra.account.getAccountInfo({ accountAddress })).sequence_number
      : 0n;

      const supraCoinTransferSponsoredRawTransaction = supra.transaction.build.rawTxnObject({
      senderAddress: accountAddress,
      senderSequenceNumber,
      function: "0x1::supra_account::create_account",
      functionTypeArgs: [],
      functionArgs: [new SupraAccount().address().toUint8Array()],
      optionalTransactionPayloadArgs: { gasUnitPrice: await supra.getEstimatedGasUnitPrice() },
      });

      const sponsorTransactionPayload = new TxnBuilderTypes.FeePayerRawTransaction(
      supraCoinTransferSponsoredRawTransaction,
      [],
      new TxnBuilderTypes.AccountAddress(feePayerAccount.address().toUint8Array())
      );

      const sponsorTxnSenderAuthenticator = await supra.transaction.signTransaction({
      senderAccount: account,
      rawTxn: sponsorTransactionPayload
      });

      const feePayerAuthenticator = await supra.transaction.signTransaction({
      senderAccount: feePayerAccount,
      rawTxn: sponsorTransactionPayload
      });

      const txn = await supra.transaction.submit.submitSponsorTransaction({
      feePayerAddress: feePayerAccount.address().toString(),
      secondarySignersAccountAddress: [],
      rawTxn: supraCoinTransferSponsoredRawTransaction,
      senderAuthenticator: sponsorTxnSenderAuthenticator,
      feePayerAuthenticator: feePayerAuthenticator,
      secondarySignersAuthenticator: [],
      enableTransactionWaitAndSimulationArgs: {
      enableTransactionSimulation: true,
      enableWaitForTransaction: true
      }
      });

      console.log("Transaction submitted:", txn);
      }

      runExample().catch(console.error);
    • Sends multi-agent transaction. The authenticators are made with supra.transaction.signTransaction on a MultiAgentRawTransaction, which checks the chain ID of the node before it signs; this method signs nothing.

      Parameters

      • args: {
            secondarySignersAccountAddress: string[];
            rawTxn: RawTransaction;
            senderAuthenticator: AccountAuthenticatorEd25519;
            secondarySignersAuthenticator: AccountAuthenticatorEd25519[];
            enableTransactionWaitAndSimulationArgs?: EnableTransactionWaitAndSimulationArgs;
        }
        • secondarySignersAccountAddress: string[]

          List of account address of tx secondary signers

        • rawTxn: RawTransaction

          The raw transaction to be submitted

        • senderAuthenticator: AccountAuthenticatorEd25519

          The sender account authenticator

        • secondarySignersAuthenticator: AccountAuthenticatorEd25519[]

          List of the secondary signers account authenticator

        • OptionalenableTransactionWaitAndSimulationArgs?: EnableTransactionWaitAndSimulationArgs

          enable transaction wait and simulation arguments

      Returns Promise<SubmitTransactionResponse>

      SubmitTransactionResponse. The class description lists the statuses and errors of a submission.

      When the node refuses the submission or an enabled simulation because the gas unit price is below its minimum (this replaces SupraSimulationFailedError and SupraAPIError for that refusal).

      When the submission request times out, fails before the node answers or is answered with a 5xx status other than 503 (after the wait, with enableWaitForTransaction); carries the hash derived before the submission.

      Before submitting, when a secondary signer address is not 1 to 64 hex digits after an optional 0x or 0X.

      import { Network, SupraAccount, SupraClient, TxnBuilderTypes } from "supra-ts-sdk";

      const supra = new SupraClient({ network: Network.TESTNET });
      const account = new SupraAccount(); // an account that holds SUPRA
      const secondarySignerAccount = new SupraAccount();

      async function runExample() {

      const multiAgentRawTransaction = supra.transaction.build.rawTxnObject({
      senderAddress: account.address(),
      senderSequenceNumber: (await supra.account.getAccountInfo({ accountAddress: account.address() })).sequence_number,
      function: "0x1234::wrapper::two_signers", // a function of a published module that takes two signers
      functionTypeArgs: [],
      functionArgs: [],
      optionalTransactionPayloadArgs: { gasUnitPrice: await supra.getEstimatedGasUnitPrice() },
      });

      // Creating Multi-Agent Transaction Payload
      const multiAgentTransactionPayload =
      new TxnBuilderTypes.MultiAgentRawTransaction(multiAgentRawTransaction, [
      new TxnBuilderTypes.AccountAddress(
      secondarySignerAccount.address().toUint8Array()
      ),
      ]);

      // Generating sender authenticator
      const multiAgentSenderAuthenticator = await supra.transaction.signTransaction({
      senderAccount: account,
      rawTxn: multiAgentTransactionPayload
      });

      // Generating Secondary Signer authenticator
      const secondarySignerAuthenticator = await supra.transaction.signTransaction({
      senderAccount: secondarySignerAccount,
      rawTxn: multiAgentTransactionPayload
      });

      // Sending Multi-Agent transaction
      const txn = await supra.transaction.submit.submitMultiAgentTransaction({
      secondarySignersAccountAddress: [secondarySignerAccount.address().toString()],
      rawTxn: multiAgentRawTransaction,
      senderAuthenticator: multiAgentSenderAuthenticator,
      secondarySignersAuthenticator: [secondarySignerAuthenticator],
      enableTransactionWaitAndSimulationArgs: {
      enableWaitForTransaction: true,
      enableTransactionSimulation: true,
      }
      });

      console.log("Transaction submitted:", txn);
      }
      runExample().catch(console.error);