Fuels-ts

Appearance

Transaction Request ​

A transaction request provides the foundations for submitting a transaction and interacting with the blockchain.

Within Fuel, we have the following transaction types:

  • Script
  • Create
  • Mint

The SDK provides class helpers for handling script and create transactions: ScriptTransactionRequest and CreateTransactionRequest, respectively.

Note: Mint transactions can only be created by the block producer and do not have any use outside of block creation. Therefore, the SDK only provides the ability to decode them.

Creating a Transaction Request ​

To create a transaction request, you must first instantiate either a ScriptTransactionRequest or CreateTransactionRequest.

A ScriptTransactionRequest is used for script transactions, which allows you to execute bytecode on chain to perform a task or chain of tasks. Within the SDK they can be created like so:

ts
import { ScriptTransactionRequest } from 'fuels';

// Instantiate the transaction request using a ScriptTransactionRequest
const transactionRequest = new ScriptTransactionRequest({ script: scriptBytecode });

// Set the script main function arguments (can also be passed in the class constructor)
transactionRequest.setData(scriptAbi, scriptMainFunctionArguments);
See code in context

A CreateTransactionRequest is used for create transactions, which are transactions that create a new contract on the blockchain.

ts
import { CreateTransactionRequest } from 'fuels';

// Instantiate the transaction request using a CreateTransactionRequest
const transactionRequest = new CreateTransactionRequest({ witnesses: [contractByteCode] });
See code in context

Note: We recommend you use the ContractFactory for contract deployment as this will shape the create transaction request for you. Information on this can be found in the contract deployment guide.

Modifying a Transaction Request ​

Once you have instantiated a transaction request, you can modify it by setting the transaction parameters and policies. This can either be done manually by directly altering the transaction request object, or through helper methods that are available on the above classes.

Adding Resources to a Transaction Request ​

Resources populate the inputs and outputs of a transaction request. This can take the form of coins, messages or contracts. The SDK provides a range of methods for dealing with resources. Below will detail how coins and messages can be added to a transaction request.

ts
import { ScriptTransactionRequest, BaseAssetId } from 'fuels';

// Instantiate the transaction request
const transactionRequest = new ScriptTransactionRequest({ script: scriptBytecode });

// Adding resources (coins or messages)
transactionRequest.addResources(resources);
transactionRequest.addResource(resource);

// Adding coin inputs and outputs (including transfer to recipient)
transactionRequest.addCoinInput(coin);
transactionRequest.addCoinOutput(recipientAddress, 1000, BaseAssetId);

// Adding message inputs
transactionRequest.addMessageInput(message);
See code in context

Adding a Contract to a Transaction Request ​

Scripts can perform multiple actions on chain, therefore you may want to chain contract calls. For this you will need to add a contract to the transaction request. This can be done like so:

ts
import { ScriptTransactionRequest } from 'fuels';

// Instantiate the transaction request
const transactionRequest = new ScriptTransactionRequest({ script: scriptBytecode });

// Add the contract input and output using the contract ID
transactionRequest.addContractInputAndOutput(contractId);
See code in context

Adding a Predicate to a Transaction Request ​

Predicates are used to define the conditions under which a transaction can be executed. Therefore you may want to add a predicate to a transaction request to unlock funds that are utilized by a script. This can be added like so:

ts
import { ScriptTransactionRequest, Predicate } from 'fuels';

// Instantiate the transaction request
const transactionRequest = new ScriptTransactionRequest({ script: scriptBytecode });

// Instantiate the predicate and pass valid input data to validate
// the predicate and unlock the funds
const predicate = new Predicate({
  bytecode: predicateBytecode,
  abi: predicateAbi,
  inputData: dataToValidatePredicate,
  provider,
});

// Add the predicate input and resources
transactionRequest.addPredicateResource(coin, predicate);
See code in context

Note: For more information on predicates, including information on configuring them, funding them and using them to unlock funds, please refer to the predicate guide.

Adding a Witness and Signing a Transaction Request ​

The SDK provides a way of either modifying the witnesses for a transaction request directly, or by passing accounts. This will then sign the transaction request with the account's private key. Below will detail how to add a witness to a transaction request:

ts
import type { Account } from 'fuels';
import { ScriptTransactionRequest, WalletUnlocked } from 'fuels';

// Instantiate the transaction request
const transactionRequest = new ScriptTransactionRequest({ script: scriptBytecode });

// Add a witness directly
transactionRequest.addWitness(witness);

// Add a witness using an account
const account: Account = WalletUnlocked.generate({ provider });
await transactionRequest.addAccountWitnesses(account);
See code in context

A more complex example of adding multiple witnesses to a transaction request can be seen in the multiple signers guide here, which validates the signatures inside the script itself.

Note: Once addAccountWitnesses has been called, any additional modifications to the transaction request will invalidate the signature as the transaction ID changes. Therefore, it is recommended to add witnesses last.

Getting the Transaction ID for a Transaction Request ​

The transaction ID is a SHA-256 hash of the entire transaction request. This can be useful for tracking the transaction on chain. To get the transaction ID, you can use the following method:

ts
import { ScriptTransactionRequest } from 'fuels';

// Instantiate the transaction request
const transactionRequest = new ScriptTransactionRequest({ script: scriptBytecode });

// Get the chain ID
const chainId = await provider.getChainId();

// Get the transaction ID using the Chain ID
const transactionId = transactionRequest.getTransactionId(chainId);
// TX ID: 0x55667d...
See code in context

Note: Any changes made to a transaction request will alter the transaction ID. Therefore, you should only get the transaction ID after all modifications have been made.