feat!: add support for assemble tx #1634

hal3e · 2025-04-02T12:11:55Z

closes: #1641

Release notes

In this release, we:

Added support for assemble transactions

Summary

We added support for assemble transactions and made it the default build strategy for all CallHandlers and transfers.

Breaking Changes

Contract dependencies → automatic & log decoding
The old with_contracts/with_contract_ids APIs are gone—contract inputs are now set using assemble tx, and if you need to decode logs/reverts you pass in the external contract’s decoder:

// old
my_contract
  .methods()
  .foo(arg)
  .with_contracts(&[&external_instance])
  .call()
  .await?;

// new
my_contract
  .methods()
  .foo(arg)
  .add_log_decoder(external_instance.log_decoder())
  .call()
  .await?;

Dependency & output estimation → fully automatic
You no longer need to chain on with_variable_output_policy(...) or call determine_missing_contracts(): the SDK will auto-estimate both missing contracts and variable outputs.
```
// old
call_handler
  .with_variable_output_policy(VariableOutputPolicy::EstimateMinimum)
  .determine_missing_contracts()
  .call()
  .await?;

// new
call_handler
  .call()
  .await?;
```

Script gas limit & TxPolicies → dedicated handler method
TxPolicies does not hold the script_gas_limit anymore. Use .with_script_gas_limit(n) directly on your call handler.

// old
let policies = TxPolicies::default().with_script_gas_limit(1_000_000);
my_contract
  .methods()
  .bar()
  .with_tx_policies(policies)
  .call()
  .await?;

// new
my_contract
  .methods()
  .bar()
  .with_script_gas_limit(1_000_000)
  .call()
  .await?;

Transaction submission → submit
send_transaction is renamed to submit

// old
let tx_id = provider.send_transaction(tx).await?;
let status = provider.tx_status(&tx_id).await?;

// new
let tx_id = provider.submit(tx).await?;
let status = provider.tx_status(&tx_id).await?;

Manual fee/inputs adjustment → “assemble” strategy
You do not have to use wallet.adjust_for_fee(&mut tb, …).await? if you use the new assemble strategy.

// old
wallet.adjust_for_fee(&mut tb, used_base_amount).await?;
let tx = tb.build(&provider).await?;

// new
let tx = tb.build(&provider).await?; // using ScriptBuildStrategy::AssembleTx under the hood

Removed the ContractDependency trait

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)

netrome

Some nits and style opinions but otherwise LGTM.

docs/src/calling-contracts/other-contracts.md

docs/src/calling-contracts/variable-outputs.md

netrome · 2025-04-24T08:09:59Z

packages/fuels-accounts/src/provider.rs

+    #[allow(clippy::too_many_arguments)]
+    pub async fn assemble_tx(
+        &self,
+        transaction: impl Transaction,


Nit: I think we can reduce this requirement since we only use .into(). Unless you believe we'll call more of the Transaction trait methods in the future.

Suggested change

transaction: impl Transaction,

transaction: impl Into<FuelTransaction>,

netrome · 2025-04-24T08:19:18Z

packages/fuels-core/src/types/transaction_builders.rs

+async fn update_witnesses<T: UniqueIdentifier + Witnesses + Inputs>(
+    tx: &mut T,
+    unresolved_signers: &[Arc<dyn Signer + Send + Sync>],
+    chain_id: &ChainId,
+) -> Result<()> {
+    let id = tx.id(chain_id);


Since we're already using generics here, it's unnecessarily restrictive to enforce the use of trait objects for unresolved_signers. I'd instead prefer something like:

Suggested change

async fn update_witnesses<T: UniqueIdentifier + Witnesses + Inputs>(

tx: &mut T,

unresolved_signers: &[Arc<dyn Signer + Send + Sync>],

chain_id: &ChainId,

) -> Result<()> {

let id = tx.id(chain_id);

async fn update_witnesses<T: UniqueIdentifier + Witnesses + Inputs, S: Signer>(

tx: &mut T,

unresolved_signers: &[S],

chain_id: &ChainId,

) -> Result<()> {

let id = tx.id(chain_id);

Signers might be of different types, ie you cannot have a slice of &[AwsSigner, PrivateKeySigner, LedgerSigner].

S is only going to resolve to one type at at time making the unresolved signers a slice of that particular signer type.

The builder has a add_signer(&mut self,... that accepts a dyn Signer so that is where the unresolved_signers come from.

TLDR,
we chose type erasure for the tx builder so that we don't end up with ScriptTxBuilder<NextSigner<PrivateKeySigner, NextSigner<AwsSigner, LedgerSigner>>> or something like that.

AurelienFT

It simplify so much things that's soooo cool. Nice one !

AurelienFT · 2025-04-24T09:39:35Z

packages/fuels-accounts/src/account.rs

@@ -170,6 +173,21 @@ pub trait Account: ViewOnlyAccount {
        Ok(())
    }

+    fn required_balance(


Can we add document such as the other methods of this trait

AurelienFT · 2025-04-24T09:47:45Z

packages/fuels-core/src/types/transaction_builders.rs

+                let mut policies = Policies::default();
+
+                policies.set(PolicyType::WitnessLimit, self.tx_policies.witness_limit());
+                policies.set(PolicyType::MaxFee, self.tx_policies.tip());


Suggested change

policies.set(PolicyType::MaxFee, self.tx_policies.tip());

policies.set(PolicyType::MaxFee, self.tx_policies.max_fee());

packages/fuels-core/src/types/transaction_builders.rs

AurelienFT · 2025-04-24T09:55:24Z

packages/fuels-core/src/types/transaction_builders.rs

+        //if user set `script_gas_limit` we will use it's value only
+        //if it is higher then the one estimated by assemble_tx
+        if let Some(script_gas_limit) = self.script_gas_limit {
+            if script_gas_limit > *tx.script_gas_limit() {


I don't really see a use case for that, the gas consumption doesn't fluctuate. If assemble_tx estimated an amount of gas I don't see a usecase where we should submit more. Maybe I'm missing something

E.g. users can consult the current block height and base their behavior off of that.

Or other transactions get included before this and change the contract state impacting script gas usage, etc.

If you assemble now, and don't get included in the next block then the script gas limit is no longer guaranteed to be correct.

not sure to what the node sets it to but if it is exactly what the dry run gave at that moment then we'll probably see users fallback to manually setting high values here just so they don't get flaky execution.

AurelienFT · 2025-04-24T09:56:09Z

packages/fuels-core/src/types/transaction_builders.rs

+            if script_gas_limit > *tx.script_gas_limit() {
+                *tx.script_gas_limit_mut() = script_gas_limit;
+
+                Self::set_max_fee_policy(


This line shouldn't be in the condition after of max_fee and not on this one on script_gas_limit ?

AurelienFT · 2025-04-24T09:59:42Z

packages/fuels-core/src/types/transaction_builders.rs

+            _ => {
+                return Err(error_transaction!(
+                    Builder,
+                    "`asseble_tx` did not return the right transactio type. Expected `create`"


Same for the other transaction type:

Suggested change

"`asseble_tx` did not return the right transactio type. Expected `create`"

"`assemble_tx` did not return the right transaction type. Expected `create`"

AurelienFT · 2025-04-24T10:02:44Z

packages/fuels-core/src/types/transaction_builders.rs

+            self.witnesses.clone(),
+        );
+
+        if let Some(max_fee) = self.tx_policies.max_fee() {


Same for others transaction type also : Is it necessary to set the max_fee here because we try to edit it again after estimation can we change the current behavior : set -> override with assemble_tx -> maybe set again to set with_assemble_tx -> maybe set again and remove this

AurelienFT · 2025-04-24T10:06:51Z

packages/fuels-programs/src/calls/call_handler.rs

-        for c in contracts {
-            self.log_decoder.merge(c.log_decoder());
-        }
+    pub fn add_log_decoder(mut self, log_decoder: LogDecoder) -> Self {


Can we document on that. What is a LogDecoder could be interesting also because I don't see what is it.

segfault-magnet

nice :)) you managed to keep it very minimal

docs/src/custom-transactions/assemble_tx.md

segfault-magnet · 2025-04-24T11:49:17Z

e2e/tests/predicates.rs

+    // As we have changed the witnesses and the predicate code depends on them we need
+    // to estimate the predicates again before sending the tx.
+    tx.estimate_predicates(&provider).await?;


seems like something we should document somewhere -- that changing malleable fields requires re-estimation of the predicate if the predicate uses them in some way.

segfault-magnet · 2025-04-24T12:12:51Z

packages/fuels-core/src/types/transaction_builders.rs

@@ -78,6 +83,11 @@ pub enum ScriptBuildStrategy {
    /// are present. Meant only for transactions that are to be dry-run with validations off.
    /// Useful for reading state with unfunded accounts.
    StateReadOnly,
+    /// Transaction is estimated using `assemble_tx` and signatures are automatically added.


I'm thinking about Strategy::Complete vs Strategy::AssembleTx.

Although assemble_tx is a nice identifier internally between the devs (maybe even a label on the gql endpoints), I feel that we should have a better name.

All transactions are assembled in some way, only here we delegate the work to the node itself. Seeing as that is the key difference maybe:

LocalEstimation vs RemoteEstimation but that is also misleading since local is scarcely more than just querying N methods and then filling in the fields of the transaction. The decisions around what UTXOs to spend are still not owned by the SDK.

Having written the above I'm thinking: have we considered removing the SDKs ability to do the estimation automatically?

Leave in all the various helpers but have the strategy be called SignOnly or something like that -- ie the user does the gas, contract, variable output and whatever else they want manually (potentially using sdk helpers), calling build will just add the signatures over whatever is currently set in the builder?

segfault-magnet · 2025-04-24T12:42:48Z

packages/fuels-core/src/types/transaction_builders.rs

+async fn update_witnesses<T: UniqueIdentifier + Witnesses + Inputs>(
+    tx: &mut T,
+    unresolved_signers: &[Arc<dyn Signer + Send + Sync>],
+    chain_id: &ChainId,
+) -> Result<()> {
+    let id = tx.id(chain_id);


Signers might be of different types, ie you cannot have a slice of &[AwsSigner, PrivateKeySigner, LedgerSigner].

S is only going to resolve to one type at at time making the unresolved signers a slice of that particular signer type.

The builder has a add_signer(&mut self,... that accepts a dyn Signer so that is where the unresolved_signers come from.

TLDR,
we chose type erasure for the tx builder so that we don't end up with ScriptTxBuilder<NextSigner<PrivateKeySigner, NextSigner<AwsSigner, LedgerSigner>>> or something like that.

segfault-magnet · 2025-04-24T12:50:22Z

packages/fuels-core/src/types/transaction_builders.rs

+        //if user set `script_gas_limit` we will use it's value only
+        //if it is higher then the one estimated by assemble_tx
+        if let Some(script_gas_limit) = self.script_gas_limit {
+            if script_gas_limit > *tx.script_gas_limit() {


E.g. users can consult the current block height and base their behavior off of that.

Or other transactions get included before this and change the contract state impacting script gas usage, etc.

If you assemble now, and don't get included in the next block then the script gas limit is no longer guaranteed to be correct.

not sure to what the node sets it to but if it is exactly what the dry run gave at that moment then we'll probably see users fallback to manually setting high values here just so they don't get flaky execution.

segfault-magnet · 2025-04-24T12:53:44Z

packages/fuels-core/src/types/transaction_builders.rs

+        if let Some(max_fee) = self.tx_policies.max_fee() {
+            if max_fee > tx.max_fee_limit() {
+                tx.policies_mut().set(PolicyType::MaxFee, Some(max_fee));
+            }
+        }


Now that I think about it I'm leaning towards "if the user set something, then that is how it's going to be".

I could see it being a surprise if the user says spend at most 100 and we bump it to 100M because that is the way it was estimated.

If the user wants to add a bit of leeway to the estimations of assemble tx then that is maybe best done via separate tolerance args like we have for the max fee.

segfault-magnet · 2025-04-24T13:01:40Z

packages/fuels-programs/src/calls/utils.rs

        })
-        .collect()
+        .enable_burn(true); // assemble tx will add missing change outputs


Hm. At what point do we check for burning? Ie if the assemble tx really adds missing change outputs, then can we do the check after the tx is assembled?

I don't doubt that it will add them but just that, IIUC, whenever users want to use assemble tx as the build strategy they have to say enable_burn which sounds scary.

Co-authored-by: Mårten Blankfors <[email protected]> Co-authored-by: Ahmed Sagdati <[email protected]>

Co-authored-by: AurelienFT <[email protected]>

hal3e added 7 commits February 28, 2025 15:35

feat: support for assemble tx

5a8cba6

Merge branch 'master' into feat/assemble-tx

723eb55

initial impl

93eaebe

merge master

648d5ff

fix merge

658a928

merge master

b3d1c7f

remove dbg

2069cdb

hal3e self-assigned this Apr 2, 2025

hal3e added 19 commits April 2, 2025 14:18

cargo fmt

d179a2a

remove fcore-client dep

b5bdbc6

Merge branch 'master' into feat/assemble-tx

dba5782

remove variable output and missing contracts estimation

342dd59

remove anchor, fix docs later

b6c4be2

merge master

8a82538

Merge branch 'master' into feat/assemble-tx

72b010d

work in progress

4c16920

refactor

3a1d523

merge master

ca880ac

refactor

d971704

remove test

c6bd94e

merge master

494ac3a

fix todo

6b0cc1c

remove unused lines

2478f48

create sdk version of AssembleTXResult struct and expose rest

f0e32f6

update docs

aa289f0

docs

575af13

Merge branch 'master' into feat/assemble-tx

f45e499

hal3e changed the title ~~feat: support for assemble tx~~ feat!: add support for assemble tx Apr 23, 2025

hal3e added 2 commits April 23, 2025 23:51

Merge branch 'master' into feat/assemble-tx

30ab40a

add asseble tx docs

b2bc3ea

hal3e added 2 commits April 23, 2025 23:59

tests

43a8079

fix docs

c30fb8a

hal3e marked this pull request as ready for review April 23, 2025 22:16

hal3e requested a review from a team as a code owner April 23, 2025 22:16

Merge branch 'master' into feat/assemble-tx

81b557e

netrome previously approved these changes Apr 24, 2025

View reviewed changes

netrome requested a review from a team April 24, 2025 08:24

AurelienFT requested changes Apr 24, 2025

View reviewed changes

segfault-magnet reviewed Apr 24, 2025

View reviewed changes

docs related suggestions

8d4af88

Co-authored-by: Mårten Blankfors <[email protected]> Co-authored-by: Ahmed Sagdati <[email protected]>

hal3e dismissed netrome’s stale review via 8d4af88 April 25, 2025 09:35

Update packages/fuels-core/src/types/transaction_builders.rs

dc841ea

Co-authored-by: AurelienFT <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat!: add support for assemble tx #1634

feat!: add support for assemble tx #1634

hal3e commented Apr 2, 2025 •

edited

Loading

netrome left a comment •

edited

Loading

netrome Apr 24, 2025

netrome Apr 24, 2025

segfault-magnet Apr 24, 2025

AurelienFT left a comment

AurelienFT Apr 24, 2025

AurelienFT Apr 24, 2025

AurelienFT Apr 24, 2025

segfault-magnet Apr 24, 2025

AurelienFT Apr 24, 2025

AurelienFT Apr 24, 2025

AurelienFT Apr 24, 2025

AurelienFT Apr 24, 2025

segfault-magnet left a comment

segfault-magnet Apr 24, 2025

segfault-magnet Apr 24, 2025

segfault-magnet Apr 24, 2025

segfault-magnet Apr 24, 2025

segfault-magnet Apr 24, 2025

segfault-magnet Apr 24, 2025

	transaction: impl Transaction,
	transaction: impl Into<FuelTransaction>,

	policies.set(PolicyType::MaxFee, self.tx_policies.tip());
	policies.set(PolicyType::MaxFee, self.tx_policies.max_fee());

	"`asseble_tx` did not return the right transactio type. Expected `create`"
	"`assemble_tx` did not return the right transaction type. Expected `create`"

feat!: add support for assemble tx #1634

Are you sure you want to change the base?

feat!: add support for assemble tx #1634

Conversation

hal3e commented Apr 2, 2025 • edited Loading

Release notes

Summary

Breaking Changes

Checklist

netrome left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AurelienFT left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

segfault-magnet left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hal3e commented Apr 2, 2025 •

edited

Loading

netrome left a comment •

edited

Loading