Sign and Submit Transactions

mkdir supra-sign && cd supra-sign
npm init -y
npm install supra-ts-sdk@devnet
npm install --save-dev tsx

const signature = await supra.transaction.signTransaction({ senderAccount, rawTxn })

import { createHash, generateKeyPairSync, sign } from 'node:crypto'
import { BCS, HexString, Network, SupraAccount, SupraClient } from 'supra-ts-sdk'
 
// Stands in for a wallet or a remote signer: it holds the key and returns the public key and signatures.
const { publicKey, privateKey } = generateKeyPairSync('ed25519')
const publicKeyBytes = publicKey.export({ format: 'der', type: 'spki' }).subarray(-32)
// The address of an Ed25519 account is the SHA3-256 hash of its public key followed by the scheme byte 0.
const address = `0x${createHash('sha3-256')
  .update(Buffer.concat([publicKeyBytes, Buffer.from([0])]))
  .digest('hex')}`
const signWithExternalKey = (message: Uint8Array) => new HexString(sign(null, message, privateKey).toString('hex'))
 
async function main() {
  const supra = new SupraClient({ network: Network.DEVNET })
 
  // Nothing below checks the chain ID, so check it once: this throws SupraChainIdMismatchError when the node's chain ID
  // is not the configured one.
  await supra.validateChainId()
 
  // Fund the account from the faucet. The account exists on the chain once the funding transaction has committed.
  const faucet = await supra.faucet.fundAccountWithFaucet({ accountAddress: address })
  await supra.transaction.waitForTransaction({ transactionHash: faucet.hash })
  const { sequence_number } = await supra.account.getAccountInfo({ accountAddress: address })
 
  // Build the transaction. `rawTxnObject` makes no request.
  const receiver = new SupraAccount().address()
  const rawTxn = supra.transaction.build.rawTxnObject({
    senderAddress: address,
    senderSequenceNumber: sequence_number,
    function: '0x1::supra_account::transfer',
    functionTypeArgs: [],
    functionArgs: [receiver.toUint8Array(), BCS.bcsSerializeUint64(1_000n)],
    optionalTransactionPayloadArgs: { maxGas: 5_000n, gasUnitPrice: await supra.getEstimatedGasUnitPrice() },
  })
 
  // The bytes to sign: the SHA3-256 hash of the domain separator `SUPRA::RawTransaction`, then the BCS bytes of the
  // transaction. The external signer signs them as they are.
  const message = supra.transaction.getTransactionSignatureMessage({ rawTxn })
  const signature = signWithExternalKey(message)
 
  const transaction = await supra.transaction.submit.submitSerializedRawTransactionAndSignature({
    senderPubkey: new HexString(publicKeyBytes.toString('hex')),
    signature,
    serializedRawTransaction: BCS.bcsToBytes(rawTxn),
    enableTransactionWaitAndSimulationArgs: { enableTransactionSimulation: true, enableWaitForTransaction: true },
  })
  console.log(transaction.status, transaction.hash)
}
 
main()

npx tsx external_signing.ts

import { BCS, Network, SupraAccount, SupraClient, TxnBuilderTypes } from 'supra-ts-sdk'
 
async function main() {
  const supra = new SupraClient({ network: Network.DEVNET })
  const sender = new SupraAccount()
  const feePayer = new SupraAccount()
  const receiver = new SupraAccount().address()
 
  // Both accounts get SUPRA from the faucet.
  for (const account of [sender, feePayer]) {
    const faucet = await supra.faucet.fundAccountWithFaucet({ accountAddress: account.address() })
    await supra.transaction.waitForTransaction({ transactionHash: faucet.hash })
  }
 
  // The transaction is the sender's: its sender, sequence number and payload are the sender's.
  const { sequence_number } = await supra.account.getAccountInfo({ accountAddress: sender.address() })
  const rawTxn = supra.transaction.build.rawTxnObject({
    senderAddress: sender.address(),
    senderSequenceNumber: sequence_number,
    function: '0x1::supra_account::transfer',
    functionTypeArgs: [],
    functionArgs: [receiver.toUint8Array(), BCS.bcsSerializeUint64(1_000n)],
    optionalTransactionPayloadArgs: { maxGas: 5_000n, gasUnitPrice: await supra.getEstimatedGasUnitPrice() },
  })
 
  // The sender and the fee payer sign the same fee payer transaction.
  const feePayerTxn = new TxnBuilderTypes.FeePayerRawTransaction(
    rawTxn,
    [],
    new TxnBuilderTypes.AccountAddress(feePayer.address().toUint8Array()),
  )
  const senderAuthenticator = await supra.transaction.signTransaction({ senderAccount: sender, rawTxn: feePayerTxn })
  const feePayerAuthenticator = await supra.transaction.signTransaction({
    senderAccount: feePayer,
    rawTxn: feePayerTxn,
  })
 
  const before = {
    sender: await supra.account.getAccountSupraCoinBalance({ accountAddress: sender.address() }),
    feePayer: await supra.account.getAccountSupraCoinBalance({ accountAddress: feePayer.address() }),
  }
  const transaction = await supra.transaction.submit.submitSponsorTransaction({
    feePayerAddress: feePayer.address().toString(),
    secondarySignersAccountAddress: [],
    rawTxn,
    senderAuthenticator,
    feePayerAuthenticator,
    secondarySignersAuthenticator: [],
    enableTransactionWaitAndSimulationArgs: { enableTransactionSimulation: true, enableWaitForTransaction: true },
  })
  console.log(transaction.status, transaction.hash)
 
  // The sender's balance falls by the transferred amount; the fee payer's falls by the gas.
  const after = {
    sender: await supra.account.getAccountSupraCoinBalance({ accountAddress: sender.address() }),
    feePayer: await supra.account.getAccountSupraCoinBalance({ accountAddress: feePayer.address() }),
  }
  console.log('sender paid', before.sender - after.sender, 'quants')
  console.log('fee payer paid', before.feePayer - after.feePayer, 'quants')
}
 
main()

npx tsx sponsored_transaction.ts

import { Network, SupraAccount, SupraClient, TxnBuilderTypes } from 'supra-ts-sdk'
 
async function main() {
  const supra = new SupraClient({ network: Network.DEVNET })
  const sender = new SupraAccount() // has no account on the chain
  const feePayer = new SupraAccount()
 
  const faucet = await supra.faucet.fundAccountWithFaucet({ accountAddress: feePayer.address() })
  await supra.transaction.waitForTransaction({ transactionHash: faucet.hash })
 
  // An account that does not exist yet has sequence number 0. `getAccountInfo` throws for it.
  const accountAddress = sender.address()
  const senderSequenceNumber = (await supra.account.isAccountExists({ accountAddress }))
    ? (await supra.account.getAccountInfo({ accountAddress })).sequence_number
    : 0n
 
  // `create_account` spends nothing from the sender, which holds no SUPRA.
  const rawTxn = supra.transaction.build.rawTxnObject({
    senderAddress: accountAddress,
    senderSequenceNumber,
    function: '0x1::supra_account::create_account',
    functionTypeArgs: [],
    functionArgs: [new SupraAccount().address().toUint8Array()],
    optionalTransactionPayloadArgs: { maxGas: 5_000n, gasUnitPrice: await supra.getEstimatedGasUnitPrice() },
  })
 
  const feePayerTxn = new TxnBuilderTypes.FeePayerRawTransaction(
    rawTxn,
    [],
    new TxnBuilderTypes.AccountAddress(feePayer.address().toUint8Array()),
  )
  const senderAuthenticator = await supra.transaction.signTransaction({ senderAccount: sender, rawTxn: feePayerTxn })
  const feePayerAuthenticator = await supra.transaction.signTransaction({
    senderAccount: feePayer,
    rawTxn: feePayerTxn,
  })
 
  const transaction = await supra.transaction.submit.submitSponsorTransaction({
    feePayerAddress: feePayer.address().toString(),
    secondarySignersAccountAddress: [],
    rawTxn,
    senderAuthenticator,
    feePayerAuthenticator,
    secondarySignersAuthenticator: [],
    enableTransactionWaitAndSimulationArgs: { enableTransactionSimulation: true, enableWaitForTransaction: true },
  })
  console.log(transaction.status, transaction.hash)
 
  // The transaction created the sender's account, and its sequence number is now 1.
  const info = await supra.account.getAccountInfo({ accountAddress })
  console.log('sequence number', info.sequence_number)
}
 
main()

npx tsx sponsored_new_sender.ts

module pairing_addr::pairing {
    use std::signer;
 
    struct Pair has key {
        partner: address,
    }
 
    /// Records each signer as the partner of the other. Both signers must sign the transaction.
    public entry fun pair(first: &signer, second: &signer) {
        move_to(first, Pair { partner: signer::address_of(second) });
        move_to(second, Pair { partner: signer::address_of(first) });
    }
 
    #[view]
    public fun partner(addr: address): address acquires Pair {
        borrow_global<Pair>(addr).partner
    }
}

import { Network, SupraAccount, SupraClient, TxnBuilderTypes } from 'supra-ts-sdk'
 
async function main() {
  const supra = new SupraClient({ network: Network.DEVNET })
  // The address that the `pairing` module is published at.
  const moduleAddress = process.env.MODULE_ADDRESS!
 
  const first = new SupraAccount() // the sender
  const second = new SupraAccount() // the secondary signer
  for (const account of [first, second]) {
    const faucet = await supra.faucet.fundAccountWithFaucet({ accountAddress: account.address() })
    await supra.transaction.waitForTransaction({ transactionHash: faucet.hash })
  }
 
  // `pair(first: &signer, second: &signer)` takes no arguments besides its two signers.
  const { sequence_number } = await supra.account.getAccountInfo({ accountAddress: first.address() })
  const rawTxn = supra.transaction.build.rawTxnObject({
    senderAddress: first.address(),
    senderSequenceNumber: sequence_number,
    function: `${moduleAddress}::pairing::pair`,
    functionTypeArgs: [],
    functionArgs: [],
    optionalTransactionPayloadArgs: { maxGas: 5_000n, gasUnitPrice: await supra.getEstimatedGasUnitPrice() },
  })
 
  // The secondary signers are listed in the order of the signer parameters after the sender's.
  const multiAgentTxn = new TxnBuilderTypes.MultiAgentRawTransaction(rawTxn, [
    new TxnBuilderTypes.AccountAddress(second.address().toUint8Array()),
  ])
  const senderAuthenticator = await supra.transaction.signTransaction({ senderAccount: first, rawTxn: multiAgentTxn })
  const secondAuthenticator = await supra.transaction.signTransaction({ senderAccount: second, rawTxn: multiAgentTxn })
 
  const transaction = await supra.transaction.submit.submitMultiAgentTransaction({
    secondarySignersAccountAddress: [second.address().toString()],
    rawTxn,
    senderAuthenticator,
    secondarySignersAuthenticator: [secondAuthenticator],
    enableTransactionWaitAndSimulationArgs: { enableTransactionSimulation: true, enableWaitForTransaction: true },
  })
  console.log(transaction.status, transaction.hash)
 
  // Each account now holds a `Pair` that names the other.
  const [partnerOfFirst] = await supra.methods.view({
    function: `${moduleAddress}::pairing::partner`,
    typeArguments: [],
    functionArguments: [first.address().toString()],
  })
  console.log(partnerOfFirst === second.address().toString() ? 'paired' : 'not paired')
}
 
main()

MODULE_ADDRESS=<MODULE_ADDRESS> npx tsx multi_agent.ts

import { Network, SupraAccount, SupraClient, SupraSubmissionOutcomeUnknownError } from 'supra-ts-sdk'
 
async function main() {
  const supra = new SupraClient({ network: Network.DEVNET })
  const sender = new SupraAccount()
  const receiver = new SupraAccount().address()
 
  const faucet = await supra.faucet.fundAccountWithFaucet({ accountAddress: sender.address() })
  await supra.transaction.waitForTransaction({ transactionHash: faucet.hash })
 
  const send = () =>
    supra.coin.transferSupraCoin({
      senderAccount: sender,
      receiverAccountAddress: receiver,
      amount: 1_000n,
      optionalTransactionArgs: { enableTransactionWaitAndSimulationArgs: { enableWaitForTransaction: true } },
    })
 
  // Five transfers from one account, sent without waiting for each other. The client gives them consecutive numbers.
  const transfers = await Promise.all(Array.from({ length: 5 }, send))
  console.log(transfers.map((transfer) => ('header' in transfer ? transfer.header.sequence_number : undefined)))
 
  // A submission whose outcome is unknown: the request failed or timed out, and the node may have accepted it.
  try {
    await send()
  } catch (error) {
    if (!(error instanceof SupraSubmissionOutcomeUnknownError)) {
      throw error
    }
    console.log(`Outcome unknown: ${error.hash}, sequence number ${error.sequenceNumber}`)
    console.log(`It can commit until ${new Date(Number(error.expirationTimestampSecs) * 1000).toISOString()}`)
 
    // The client holds that sequence number until the transaction expires. Read the transaction by its hash
    // before sending anything for the same purpose again.
    const transaction = await supra.transaction
      .getTransactionByHash({ transactionHash: error.hash })
      .catch(() => undefined)
    console.log(transaction?.status ?? 'The node has not seen the transaction')
  }
}
 
main()

npx tsx sequence_numbers.ts