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

    Class Multisig

    The Multisig class provides methods for the lifecycle of a multisig account (0x1::multisig_account): creating the account, proposing a transaction, approving or rejecting it, executing it, and removing a rejected one.

    Each method that sends a transaction takes the sender's SupraAccount and optionalTransactionArgs and goes through the same path as the other helpers: the sequence number comes from the client's counter unless optionalTransactionPayloadArgs.sequenceNumber is set, the client submits its calls from one account one after another, the client checks the chain ID of its node before it signs (see SupraConfig), and without a maxGas the max gas is estimated (see OptionalTransactionPayloadArgs).

    Hierarchy (View Summary)

    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 Multisig

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

      const supra = new SupraClient({ network: Network.TESTNET });
    • Creates a multisig account (0x1::multisig_account::create_with_owners) owned by the sender and additionalOwners, and returns its address.

      The address is derived from the sender's address and the sequence number of the creating transaction, as the framework derives it (deriveMultisigAccountAddress); it is returned whether or not the call waits for the commit, and the account exists once the transaction has executed successfully. When the submission's outcome is unknown (SupraSubmissionOutcomeUnknownError) no address is returned; the error's sender and sequenceNumber give it. The account holds no SUPRA at first; send SUPRA to its address to fund transactions it executes.

      Parameters

      • args: {
            senderAccount: SupraAccount;
            additionalOwners?: AccountAddressInput[];
            signaturesRequired: number | bigint;
            timeoutDurationSecs?: number | bigint;
            optionalTransactionArgs?: OptionalTransactionArgs;
        }
        • senderAccount: SupraAccount

          The account that creates the multisig account and becomes one of its owners.

        • OptionaladditionalOwners?: AccountAddressInput[]

          The addresses of the other owners. The sender must not be in the list and the list must hold no duplicates.

        • signaturesRequired: number | bigint

          The number of approvals a proposal needs, from 1 to the number of owners (the sender included).

        • OptionaltimeoutDurationSecs?: number | bigint

          The time in seconds that a proposal can be executed after its creation, at least MIN_MULTISIG_TIMEOUT_DURATION_SECS (300). Default DEFAULT_MULTISIG_TIMEOUT_DURATION_SECS (seven days).

        • OptionaloptionalTransactionArgs?: OptionalTransactionArgs

          Optional transaction arguments (see OptionalTransactionArgs).

      Returns Promise<CreateMultisigAccountResponse>

      A Promise that resolves to the account's address and the SubmitTransactionResponse of the creating transaction. Submit describes the statuses and errors of a submission.

      When the estimating simulation or an enabled simulation does not succeed, for example when signaturesRequired exceeds the number of owners.

      When enableWaitForTransaction is set and the transaction fails.

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

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

      async function runExample() {
      const { multisigAddress } = await supra.multisig.createMultisigAccount({
      senderAccount: senderAccount,
      additionalOwners: [secondOwner],
      signaturesRequired: 2,
      optionalTransactionArgs: { enableTransactionWaitAndSimulationArgs: { enableWaitForTransaction: true } },
      });
      console.log(multisigAddress);
      }

      runExample().catch(console.error);
    • Proposes a transaction of a multisig account with its payload stored on chain (0x1::multisig_account::create_transaction). The proposal has the sender's approval. Any owner can execute it once it has enough approvals, with executeMultisigTransaction, which sends no payload for it.

      The proposal's number is the next of getMultisigSequenceNumbers before the call (when no other owner proposes at the same time).

      Parameters

      Returns Promise<SubmitTransactionResponse>

      A Promise that resolves to a SubmitTransactionResponse. Submit describes the statuses and errors of a submission.

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

      const supra = new SupraClient({ network: Network.TESTNET });
      const senderAccount = new SupraAccount(); // an owner of the multisig account, holding SUPRA
      const multisigAddress = "0x1234"; // replace with the address of the multisig account

      async function runExample() {
      const response = await supra.multisig.proposeMultisigTransaction({
      senderAccount: senderAccount,
      multisigAddress: multisigAddress,
      payload: { function: "0x1::supra_account::transfer", functionArgs: ["0x2", 1000n] },
      optionalTransactionArgs: { enableTransactionWaitAndSimulationArgs: { enableWaitForTransaction: true } },
      });
      console.log(response);
      }

      runExample().catch(console.error);
    • Proposes a transaction of a multisig account storing only the SHA3-256 hash of its payload on chain (0x1::multisig_account::create_transaction_with_hash). The executor provides the payload: executeMultisigTransaction with the same payload checks it against the stored hash and sends it.

      Parameters

      Returns Promise<SubmitTransactionResponse>

      A Promise that resolves to a SubmitTransactionResponse. Submit describes the statuses and errors of a submission.

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

      const supra = new SupraClient({ network: Network.TESTNET });
      const senderAccount = new SupraAccount(); // an owner of the multisig account, holding SUPRA
      const multisigAddress = "0x1234"; // replace with the address of the multisig account

      async function runExample() {
      const response = await supra.multisig.proposeMultisigTransactionWithHash({
      senderAccount: senderAccount,
      multisigAddress: multisigAddress,
      payload: { function: "0x1::supra_account::transfer", functionArgs: ["0x2", 1000n] },
      });
      console.log(response);
      }

      runExample().catch(console.error);
    • Approves a proposal of a multisig account (0x1::multisig_account::approve_transaction). An owner who has rejected the proposal changes the vote to an approval.

      Parameters

      Returns Promise<SubmitTransactionResponse>

      A Promise that resolves to a SubmitTransactionResponse. Submit describes the statuses and errors of a submission.

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

      const supra = new SupraClient({ network: Network.TESTNET });
      const senderAccount = new SupraAccount(); // an owner of the multisig account, holding SUPRA
      const multisigAddress = "0x1234"; // replace with the address of the multisig account

      async function runExample() {
      const response = await supra.multisig.approveMultisigTransaction({
      senderAccount: senderAccount,
      multisigAddress: multisigAddress,
      sequenceNumber: 1,
      });
      console.log(response);
      }

      runExample().catch(console.error);
    • Rejects a proposal of a multisig account (0x1::multisig_account::reject_transaction). An owner who has approved the proposal changes the vote to a rejection. With enough rejections, any owner can remove the proposal with executeRejectedMultisigTransaction.

      Parameters

      Returns Promise<SubmitTransactionResponse>

      A Promise that resolves to a SubmitTransactionResponse. Submit describes the statuses and errors of a submission.

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

      const supra = new SupraClient({ network: Network.TESTNET });
      const senderAccount = new SupraAccount(); // an owner of the multisig account, holding SUPRA
      const multisigAddress = "0x1234"; // replace with the address of the multisig account

      async function runExample() {
      const response = await supra.multisig.rejectMultisigTransaction({
      senderAccount: senderAccount,
      multisigAddress: multisigAddress,
      sequenceNumber: 1,
      });
      console.log(response);
      }

      runExample().catch(console.error);
    • Executes the next proposal of a multisig account, the one after the last executed or removed. The method reads the proposal first and sends the transaction that matches it:

      • A proposal that stores its payload (proposeMultisigTransaction) is executed without a payload when the call gives none; the node reads it from the proposal. When the call gives a payload, it must encode to the stored bytes, and it is sent, so that the node checks the match when it executes the transaction.
      • A proposal that stores only a hash (proposeMultisigTransactionWithHash) is executed with the call's payload, whose SHA3-256 hash must be the stored one.

      The sender pays the gas and the proposal runs as the multisig account. The node executes the proposal only when it has enough approvals (counting the sender's implicit approval) and has not timed out; otherwise it refuses the transaction. The proposal can change between the read and the submission (another owner executes it first). A call that gave a payload is then refused by the node, because the payload is not the next proposal's; a call without a payload runs the proposal that is next when the node executes it, or is refused when that is a proposal that stores only a hash. Give the payload when the queue is shared.

      The nodes of v11.7.0 and v12.0.0.rc6 do not simulate an execution without a payload (they report MISSING_DATA). The max gas estimate and enableTransactionSimulation therefore simulate the execution with the stored payload carried, and the sent transaction, its signature and its hash are those of the execution without a payload. A simulation skips the multisig checks of the node: it does not detect missing approvals, an expired proposal or a payload that is not the stored one, so enableTransactionSimulation does not tell whether the node will accept the execution.

      Parameters

      Returns Promise<SubmitTransactionResponse>

      A Promise that resolves to a SubmitTransactionResponse. Submit describes the statuses and errors of a submission. A final status of Success means the multisig transaction was executed; whether the proposal's own function succeeded is in the transaction's events.

      When the multisig account has no pending proposal.

      Before submitting, when the proposal stores only a hash and payload is missing or hashes to another value, when the proposal stores its payload and payload encodes to other bytes, or when the stored payload cannot be decoded and the call needs a simulation (it has no maxGas, or enables enableTransactionSimulation; give maxGas and leave the simulation off).

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

      const supra = new SupraClient({ network: Network.TESTNET });
      const senderAccount = new SupraAccount(); // an owner of the multisig account, holding SUPRA
      const multisigAddress = "0x1234"; // replace with the address of the multisig account

      async function runExample() {
      const response = await supra.multisig.executeMultisigTransaction({
      senderAccount: senderAccount,
      multisigAddress: multisigAddress,
      optionalTransactionArgs: { enableTransactionWaitAndSimulationArgs: { enableWaitForTransaction: true } },
      });
      console.log(response);
      }

      runExample().catch(console.error);
    • Removes the next proposal of a multisig account when it has enough rejections or has timed out (0x1::multisig_account::execute_rejected_transaction). The sender's own rejection is counted. Proposals are resolved in order, so a proposal that cannot be executed blocks the queue until it is removed this way.

      Parameters

      Returns Promise<SubmitTransactionResponse>

      A Promise that resolves to a SubmitTransactionResponse. Submit describes the statuses and errors of a submission.

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

      const supra = new SupraClient({ network: Network.TESTNET });
      const senderAccount = new SupraAccount(); // an owner of the multisig account, holding SUPRA
      const multisigAddress = "0x1234"; // replace with the address of the multisig account

      async function runExample() {
      const response = await supra.multisig.executeRejectedMultisigTransaction({
      senderAccount: senderAccount,
      multisigAddress: multisigAddress,
      });
      console.log(response);
      }

      runExample().catch(console.error);
    • Reads the positions in a multisig account's queue of proposals: the number of the last executed or removed proposal and the number the next new proposal gets. The two are read with two requests.

      Parameters

      Returns Promise<MultisigSequenceNumbers>

      A Promise that resolves to { lastResolved, next }; proposals lastResolved + 1 to next - 1 are pending.

      When the address is not a multisig account.

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

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const { lastResolved, next } = await supra.multisig.getMultisigSequenceNumbers({ multisigAddress: "0x1234" });
      console.log(lastResolved, next);
      }

      runExample().catch(console.error);
    • Reads a proposal of a multisig account with its votes (0x1::multisig_account::get_transaction).

      Parameters

      • args: { multisigAddress: AccountAddressInput; sequenceNumber: number | bigint }
        • multisigAddress: AccountAddressInput

          The address of the multisig account.

        • sequenceNumber: number | bigint

          The proposal's number, from 1.

      Returns Promise<MultisigProposal>

      A Promise that resolves to the MultisigProposal.

      When the address is not a multisig account or no proposal has that number.

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

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const proposal = await supra.multisig.getMultisigProposal({ multisigAddress: "0x1234", sequenceNumber: 1 });
      console.log(proposal.votes);
      }

      runExample().catch(console.error);
    • Reads the next proposal of a multisig account to execute or remove, with its votes.

      Parameters

      Returns Promise<MultisigProposal | undefined>

      A Promise that resolves to the MultisigProposal, or undefined when the queue is empty.

      When the address is not a multisig account.

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

      const supra = new SupraClient({ network: Network.TESTNET });

      async function runExample() {
      const proposal = await supra.multisig.getNextMultisigProposal({ multisigAddress: "0x1234" });
      console.log(proposal?.sequenceNumber);
      }

      runExample().catch(console.error);