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)

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

segfault-magnet · 2025-05-02T14:28:42Z

It seems that we're not passing the sdk cached coins to the exclude filter of the assemble tx, so the node doesn't know that we already plan to use a UTXO and that it shouldn't be a candidate when filling required balances.

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

hal3e · 2025-05-06T12:08:46Z

It seems that we're not passing the sdk cached coins to the exclude filter of the assemble tx, so the node doesn't know that we already plan to use a UTXO and that it shouldn't be a candidate when filling required balances.

d1a83ec

AurelienFT

LGTM

packages/fuels-accounts/src/coin_cache.rs

segfault-magnet · 2025-05-08T12:28:32Z

packages/fuels-accounts/src/provider.rs

+        let exclude = match exclude {
+            Some((mut utxos, mut nonces)) => {
+                utxos.extend(cache_utxos);
+                nonces.extend(cache_nonces);
+
+                Some((utxos, nonces))
+            }
+            None => Some((cache_utxos, cache_nonces)),
+        };


If the provider is used concurrently then the cache can have entries unrelated to the owners mentioned here. Technically the minimum we can send here is just the cached utxos and nonces of the owners mentioned in require balances.

If the user clones the provider a lot (like they should do if they want to reuse the underlying connection pool) and if they use it to send concurrent transactions then we could end up having this request be bigger than it needs to be.

Not sure that's necessarily a huge deal, but just pointing it out.

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

Co-authored-by: Ahmed Sagdati <[email protected]>

MitchTurner · 2025-05-26T21:11:30Z

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

-If your contract method is calling other contracts you will have to add the appropriate `Inputs` and `Outputs` to your transaction. For your convenience, the `CallHandler` provides methods that prepare those inputs and outputs for you. You have two methods that you can use: `with_contracts(&[&contract_instance, ...])` and `with_contract_ids(&[&contract_id, ...])`.
-
-`with_contracts(&[&contract_instance, ...])` requires contract instances that were created using the `abigen` macro. When setting the external contracts with this method, logs and require revert errors originating from the external contract can be propagated and decoded by the calling contract.
+If your contract method is calling other contracts you will have to add the appropriate `Inputs` and `Outputs` to your transaction. For your convenience, the `CallHandler` will fill in all missing `Inputs`/`Outputs` before sending the transaction.


I'm not super familiar with the bounds of this "fill in all missing Inputs/Outputs". How much of this is communicated back to the sender before they click "send"?

MitchTurner · 2025-05-26T21:18:18Z

docs/src/custom-transactions/assemble_tx.md

@@ -0,0 +1,35 @@
+# Assemble Transactions
+
+Assemble transactions makes it possible to create a minimal `TransactionBuilder` and let the fuel node fill in the missing details. The node will add missing inputs, outputs, set transactions limits etc. Below is an example how the assemble strategy can be used to create a transfer.


Along the lines of previous question, when is the tx signed?

I see in the snippet code:

tb.add_signer(wallet.signer().clone())?;

I assume this happens on the client side.

The transaction is signed at the end after receiving the assembled tx. This happens in the TransactionBuilder's build method.

MitchTurner · 2025-05-26T21:31:24Z

e2e/tests/contracts.rs

@@ -291,21 +288,20 @@ async fn test_contract_call_fee_estimation() -> Result<()> {
        ),
    );

-    let gas_limit = 800;
+    let gas_limit = 3800;


Why did this need to increase so much? I assume it's somewhat arbitrary, but I wouldn't expect assemble-tx to significantly increase costs.

I had to increase the scipt gas limit here as the old value would have no effect. As it is lower then the script gas estimated by assemble tx it would have been overwritten by the higher value.

MitchTurner · 2025-05-26T21:40:47Z

e2e/tests/logs.rs

@@ -390,13 +390,13 @@ async fn multi_call_contract_with_contract_logs() -> Result<()> {

    let call_handler_1 = contract_caller_instance
        .methods()
-        .logs_from_external_contract(contract_instance.id())
-        .with_contracts(&[&contract_instance]);
+        .logs_from_external_contract(contract_instance.contract_id())


(With my limited context) I think I kinda prefer the id() syntax more. What was the thought process of changing that?

The id() method was part of a removed ContractDependency trait. I wanted the method to be clearer on what id it returns :). we can, of course, change it to id if it is clear enough.

MitchTurner · 2025-05-27T16:17:43Z

e2e/tests/providers.rs

@@ -835,6 +810,43 @@ async fn transactions_with_the_same_utxo() -> Result<()> {
    Ok(())
 }

+#[cfg(feature = "coin-cache")]
+#[tokio::test]
+async fn transfers_at_same_time_with_cache() -> Result<()> {


Maybe we could name it something like

Suggested change

async fn transfers_at_same_time_with_cache() -> Result<()> {

async fn transfer__assemble_tx_can_remove_used_coins() -> Result<()> {

Also can we add given/when/then?

MitchTurner · 2025-05-27T16:19:44Z

e2e/tests/providers.rs

@@ -1453,3 +1465,51 @@ async fn is_account_query_test() -> Result<()> {

    Ok(())
 }
+
+#[tokio::test]
+async fn assemble_tx_transfer() -> Result<()> {


I guess this test exists for the purpose of documentation. I think we should mark it as such, maybe in the name? What do you think?

MitchTurner · 2025-05-27T16:35:16Z

e2e/tests/wallets.rs

@@ -123,6 +123,27 @@ async fn adjust_fee_empty_transaction() -> Result<()> {
    Ok(())
 }

+#[tokio::test]
+async fn adjust_for_fee_error() -> Result<()> {


Can we add more clarity here. G/W/T and a more informative name?

MitchTurner · 2025-05-27T17:15:24Z

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

+        Ok(script_transaction)
+    }
+
+    async fn assemble_tx(


Do we have tests for each implementation of assemble_tx, for all the tx types?

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 and others added 2 commits April 25, 2025 11:37

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

dc841ea

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

Merge branch 'master' into feat/assemble-tx

6e2d9e0

hal3e and others added 8 commits May 6, 2025 10:52

Update packages/fuels-accounts/src/provider.rs

b85f8e2

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

update docstring

0d52722

update max_fee handling

cd6c12b

fix typo

ed99330

add docstring

e2096da

update docs

c364488

pr comment

26d45d4

add coin cache exclude

d1a83ec

hal3e requested review from segfault-magnet, AurelienFT and netrome May 6, 2025 13:33

AurelienFT previously approved these changes May 7, 2025

View reviewed changes

segfault-magnet reviewed May 8, 2025

View reviewed changes

Update packages/fuels-accounts/src/coin_cache.rs

56f379f

Co-authored-by: Ahmed Sagdati <[email protected]>

hal3e dismissed AurelienFT’s stale review via 56f379f May 9, 2025 09:30

hal3e and others added 7 commits May 9, 2025 11:30

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

08e8ee8

Co-authored-by: Ahmed Sagdati <[email protected]>

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

d5c0aac

Co-authored-by: Ahmed Sagdati <[email protected]>

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

323da72

Co-authored-by: Ahmed Sagdati <[email protected]>

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

8186383

Co-authored-by: Ahmed Sagdati <[email protected]>

coin-cache assemble-tx

95a80d2

un-delete cfg flag

5cdc2f4

check tx after building

cbcfad9

hal3e requested a review from segfault-magnet May 12, 2025 13:51

hal3e added 2 commits May 13, 2025 13:25

merge master

7cccd9b

Merge branch 'master' into feat/assemble-tx

18caac7

MitchTurner reviewed May 27, 2025

View reviewed changes

		@@ -0,0 +1,35 @@
		# Assemble Transactions

		Assemble transactions makes it possible to create a minimal `TransactionBuilder` and let the fuel node fill in the missing details. The node will add missing inputs, outputs, set transactions limits etc. Below is an example how the assemble strategy can be used to create a transfer.

	async fn transfers_at_same_time_with_cache() -> Result<()> {
	async fn transfer__assemble_tx_can_remove_used_coins() -> Result<()> {

feat!: add support for assemble tx #1634

Are you sure you want to change the base?

feat!: add support for assemble tx #1634

Uh oh!

Conversation

hal3e commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Release notes

Summary

Breaking Changes

Checklist

Uh oh!

segfault-magnet commented May 2, 2025

Uh oh!

hal3e commented May 6, 2025

Uh oh!

AurelienFT left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hal3e May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hal3e commented Apr 2, 2025 •

edited

Loading

hal3e May 28, 2025 •

edited

Loading