Skip to main content

Transaction Builder

By default, all transactions initiated using the SDK perform every step of the process for a transaction; From preparing and building the transaction all the way to waiting until it has been mined and the data is available to be read from the blockchain.

To gain more granular control over the transaction process, all transactions come with a prepare method that gives you full control over each step of this transaction journey.

Usage​

// Prepare a transaction, but DON'T send it
const quantity = 1;
const tx = await contract.erc721.claim.prepare(quantity);

// Some example use cases for the transaction
const gasCost = await tx.estimateGasCost(); // Estimate the gas cost
const simulatedTx = await tx.simulate(); // Simulate the transaction
const signedTx = await tx.sign(); // Sign the transaction for later use

Examples​

Sending a transaction without waiting for confirmations, and show a "view on block explorer" UI instead:

// Prepare an ERC20 transfer
const tx = await contract.erc20.transfer.prepare(receiver, amount);

// Submit the tx, but don't wait for confirmations
const sentTx = await tx.send();
const txHash = sentTx.hash;
// ... show a "view on block explorer" UI with the hash

Encoding two transactions to multicall them into a single transaction:

// Prepare an ERC721 burn and a erc721 mint to be executed in one tx
const tx1 = await contract.erc721.burn.prepare(tokenId);
const tx2 = await contract.erc721.mint.prepare(nftMetadata);

// Encode both transactions and execute them via multicall
// this will only prompt the user for 1 transaction to sign instead of 2
await contract.call("multicall", [tx1.encode(), tx2.encode()]);

Simulating a deploy transaction to get the deployed contract address before it's deployed:

// Prepare an deploy transaction
const tx = await sdk.deployer.deployNFTCollection.prepare(contractMetadata);

// Simulate the transaction to get the address without deploying it
const predictedAddress = await tx.simulate();

encode​

Encode the function data for this transaction.

const encodedTx = tx.encode();
Configuration

Return Value​

Returns a string containing the encoded function data.

string;

estimateGasCost​

Estimate the gas cost for a transaction.

const gasCost = await tx.estimateGasCost();
Configuration

Return Value​

Returns the gas cost for this transaction in both ether and wei.

{
  ether: string;
  wei: BigNumber;
}

estimateGasLimit​

Estimate the gas limit for a transaction.

const gasLimit = await tx.estimateGasLimit();
Configuration

Return Value​

Returns the gas limit for this transaction.

BigNumber;

execute​

Send the transaction and wait for it to be mined.

const txReceipt = await tx.execute();
Configuration

Return Value​

Some transactions return specific data about the mined transaction.

For example when minting a new NFT, the data returned will contain information about the NFT.

In most cases however, the transaction will return the transaction receipt.

TransactionResult;

getArgs​

Get the arguments for this transaction.

const args = tx.getArgs();
Configuration

Return Value​

Returns an array of arguments.

any[];

getGasPrice​

Calculates the gas price for transactions (adding a 10% tip buffer)

const gasPrice = await tx.getGasPrice();
Configuration

Return Value​

Returns the gas price for this transaction.

BigNumber;

getGaslessOptions​

Get the gasless transaction options for this transaction.

This reads from either the gasless option of the ThirdwebSDK, or the value set by setGaslessOptions.

const gaslessOptions = tx.getGaslessOptions();
Configuration

Return Value​

Returns undefined if no gasless options are set.

Otherwise, returns the openzeppelin or biconomy gasless configuration.

{
    openzeppelin: {
        relayerForwarderAddress?: string | undefined;
        relayerUrl: string;
        useEOAForwarder: boolean;
    };
    experimentalChainlessSupport: boolean;
} | {
    biconomy: {
        apiId: string;
        apiKey: string;
        deadlineSeconds: number;
    };
} | undefined

getMethod​

Get the method name for this transaction.

const method = tx.getMethod();
Configuration

Return Value​

Returns the method name for this transaction.

string;

getOverrides​

Get the CallOverrides for this transaction.

const overrides = tx.getOverrides();
Configuration

Return Value​

{
    blockTag?: BlockTag | Promise<BlockTag>;
    from?: string | Promise<string>;
}

getValue​

Get the value for this transaction.

const value = await tx.getValue();
Configuration

Return Value​

Returns the value for this transaction.

BigNumber;

send​

Send the transaction without waiting for it to be mined.

This is useful for when you want the transaction to be executed, but don’t need the data returned.

const sentTransaction = await tx.send(); // Send the transaction
Configuration

Return Value​

Returns a ContractTransaction object.

{
    hash: string;
    blockNumber?: number,
    blockHash?: string,
    timestamp?: number,
    confirmations: number,
    from: string;
    raw?: string,
    // This function waits until the transaction has been mined
    wait(confirmations?: number): Promise<ContractReceipt>;
};

setAccessList​

The AccessList to include; only available for EIP-2930 and EIP-1559 transactions.

Provide an array of objects containing address and storageKey values that the transaction plans to access.

tx.setAccessList([
  {
    address: "0x...",
    storageKeys: ["0x..."],
  },
]);

setArgs​

Set the arguments for this transaction.

Provide an array of arguments that will be passed to the transaction.

tx.setArgs(["arg1", "arg2"]);

setCcipReadEnabled​

Learn more about use of CCIP read for transactions.

tx.setCcipReadEnabled(true);

setCustomData​

Provide custom data to be included in the transaction.

tx.setCustomData({
  hello: "world",
});

setGasLimit​

Set the gas limit for this transaction.

Value provided must be a string, number, or BigNumber.

tx.setGasLimit(1000000);

setGasPrice​

Set the gas price for this transaction.

Value provided must be a string, number, or BigNumber.

tx.setGasPrice(1000000000);

setGaslessOptions​

Provide a gasless configuration for this transaction, using either openzeppelin or biconomy.

tx.setGaslessOptions({
  // Use Biconomy: https://blog.thirdweb.com/guides/biconomy-gasless-guide/
  biconomy: {
    apiId: "xxx",
    apiKey: "xxx",
    deadlineSeconds: 60,
  },

  // Use OpenZeppelin: https://blog.thirdweb.com/guides/setup-gasless-transactions/
  openzeppelin: {
    relayerUrl: "xxx",
    useEOAForwarder: true,
    relayerForwarderAddress: "0x...",
  },

  // Experimental (beta)
  experimentalChainlessSupport: true,
});

setMaxFeePerGas​

Set the maximum price (in wei) per unit of gas this transaction will pay.

Value provided must be a string, number, or BigNumber.

tx.setMaxFeePerGas(1000000000);

setMaxPriorityFeePerGas​

Set the price (in wei) per unit of gas this transaction will allow in addition to the block's base fee.

Value provided must be a string, number, or BigNumber.

tx.setMaxPriorityFeePerGas(1000000000);

setNonce​

Set the nonce for this transaction.

Value provided must be a string, number, or BigNumber.

tx.setNonce(0);

setOverrides​

Set the CallOverrides for this transaction.

tx.setOverrides({
  accessList: [], // The AccessList to include; only available for EIP-2930 and EIP-1559 transactions.
  blockTag: "latest", // A BlockTag specifies a specific block location in the Blockchain.
  ccipReadEnabled: false, // https://eips.ethereum.org/EIPS/eip-3668#use-of-ccip-read-for-transactions
  customData: {}, // The transaction data.
  from: "0x...", // The address this transaction is from.
  gasLimit: 100000, // The maximum amount of gas this transaction is permitted to use.
  gasPrice: 100000, // The price (in wei) per unit of gas this transaction will pay.
  maxFeePerGas: 100000, // The maximum price (in wei) per unit of gas this transaction will pay
  maxPriorityFeePerGas: 0, // The price (in wei) per unit of gas this transaction will allow in addition to the block's base fee
  nonce: 0, // The nonce used as part of the proof-of-work to mine this block.
  type: 0, // The EIP-2718 type of this transaction envelope, or undefined for to use the network default
  value: ethers.utils.parseEther("0.1"), // send 0.1 ether with the contract call
});

setType​

Set the EIP-2718 type of this transaction envelope, or undefined for to use the network default.

tx.setType(undefined);

sign​

Sign a transaction from the connected wallet, and return a string containing the signature.

const signedTx = await tx.sign();

simulate​

Simulate a transaction’s execution.

const simulatedTx = await tx.simulate();

updateOverrides​

Update the CallOverrides for this transaction.

tx.updateOverrides({
  accessList: [], // The AccessList to include; only available for EIP-2930 and EIP-1559 transactions.
  blockTag: "latest", // A BlockTag specifies a specific block location in the Blockchain.
  ccipReadEnabled: false, // https://eips.ethereum.org/EIPS/eip-3668#use-of-ccip-read-for-transactions
  customData: {}, // The transaction data.
  from: "0x...", // The address this transaction is from.
  gasLimit: 100000, // The maximum amount of gas this transaction is permitted to use.
  gasPrice: 100000, // The price (in wei) per unit of gas this transaction will pay.
  maxFeePerGas: 100000, // The maximum price (in wei) per unit of gas this transaction will pay
  maxPriorityFeePerGas: 0, // The price (in wei) per unit of gas this transaction will allow in addition to the block's base fee
  nonce: 0, // The nonce used as part of the proof-of-work to mine this block.
  type: 0, // The EIP-2718 type of this transaction envelope, or undefined for to use the network default
  value: ethers.utils.parseEther("0.1"), // send 0.1 ether with the contract call
});