feat: integrate with new AssembleTx GQL end-point

[Torres-ssf]

• Closes Integrate with new AssembleTx GQL end-point #3737

Release notes

In this release, we:

• Implemented provider.assembleTx

Summary

Introducing assembleTx a more robust and optimal way to estimate and fund transactions.

Parameters

The AssembleTxParams interface includes the following parameters:

export type AssembleTxParams<T extends TransactionRequest = TransactionRequest> = {
  // The transaction request to assemble
  request: T;
  // Block horizon for gas price estimation (default: 10)
  blockHorizon?: number;
  // Coin quantities required for the transaction
  accountCoinQuantities: AccountCoinQuantity[];
  // Account that will pay for the transaction fees
  feePayerAccount: Account;
  // Resources to exclude from the transaction
  excludeInput?: ExcludeResourcesOption;
  // Whether to estimate predicates (default: true)
  estimatePredicates?: boolean;
  // Amount of gas to reserve (optional)
  reserveGas?: number;
};

Return Value

The method returns an object containing:

• assembledRequest: The fully assembled transaction request with all necessary inputs, outputs, and policies
• gasPrice: The estimated gas price for the transaction
• receipts: The transaction receipts from the dry run

Usage Example

const request = new ScriptTransactionRequest();

request.addCoinOutput(accountB.address, transferAmount, baseAssetId);

const accountCoinQuantities: AccountCoinQuantity[] = [
  {
    amount: transferAmount,
    assetId: baseAssetId, // Asset ID
    account: accountA,
    changeOutputAccount: accountA, // Optional
  },
];

// Assemble the transaction
const { assembledRequest, gasPrice, receipts } = await provider.assembleTx({
  request,
  accountCoinQuantities,
  feePayerAccount: accountA,
  blockHorizon: 10,
});

// The assembledRequest is now ready to be signed and sent
const submit = await accountA.sendTransaction(assembledRequest);
await submit.waitForResult();

Best Practices

1. Always provide the correct feePayerAccount that has sufficient funds for the transaction fees
2. Pay special attention to change outputs when dealing with multiple accounts and the same asset ID:
   • In Fuel, only one change output is allowed per asset ID
   • If a transaction includes resources from the same asset ID for multiple accounts, only one account will receive the change from all spent resources
   • Make sure to coordinate with all parties involved to determine which account should receive the change output

Notes

• The method automatically handles base asset requirements for fees
• It performs a dry run to validate the transaction before returning
• The assembled transaction will include all necessary inputs and outputs based on the provided coin quantities
• Gas and fee estimation is performed using the specified block horizon

Checklist

• All changes are covered by tests (or not applicable)
• All changes are documented (or not applicable)
• I reviewed the entire PR myself (preferably, on GH UI)
• I described all Breaking Changes (or there's none)

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
fuels-template	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 28, 2025 4:36pm
ts-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 28, 2025 4:36pm
ts-docs-api	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Mar 28, 2025 4:36pm

[Torres-ssf]

Revert this change after using a released fuel-core version

[github-actions]

Temporary PR

This PR is published in AWS CodeArtifact with version: pr-3747

Install using the below commands — create-fuels variations are commented out.

PNPM

pnpm config set registry https://npm-packages.fuel.network/ --global
pnpm install fuels@pr-3747
# pnpm create fuels@pr-3747

NPM

npm --registry=https://npm-packages.fuel.network/ install fuels@pr-3747
# npm --registry=https://npm-packages.fuel.network/ create fuels@pr-3747

Bun

npm_config_registry=https://npm-packages.fuel.network/ bun install fuels@pr-3747
# npm_config_registry=https://npm-packages.fuel.network/ bun create fuels@pr-3747