Skip to content

Fold return collateral dust into the total collateral#1267

Open
palas wants to merge 2 commits into
1261-fix2-return-collateral-min-utxofrom
1261-fix3-fold-collateral-dust
Open

Fold return collateral dust into the total collateral#1267
palas wants to merge 2 commits into
1261-fix2-return-collateral-min-utxofrom
1261-fix3-fold-collateral-dust

Conversation

@palas

@palas palas commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Context

This is the third of three stacked PRs fixing #1261: the balancing functions
(makeTransactionBodyAutoBalance and estimateBalancedTxBody, in both the traditional and the
experimental API) could build transactions that the ledger rejects at submission time because of
their collateral. Each PR contains a pair of commits — regression tests that fail, then the fix
that makes them pass — and each PR is based on the previous one, so every diff shows only its own
two commits.

🗺️ Map — you are here: 3️⃣

🚪 #1261 the issue: transaction build does not validate min UTxO value of the collateral return output
1️⃣ #1265 remove collateral from transactions without Plutus scripts
2️⃣ #1266 fail on invalid computed collateral instead of building a rejected transaction
3️⃣ (this PR) fold return collateral dust into the total collateral

This PR: after the previous PR, balancing fails when the ada left over for the return
collateral output is below its minimum UTxO value — even when the collateral is ada-only and a
valid transaction exists. calcReturnAndTotalCollateral (both copies) now folds that ada into
the total collateral and omits the return collateral output instead of failing; the extra ada is
only lost if a Plutus script fails on chain. estimateBalancedTxBody cannot see the content of
the collateral inputs, so it computes collateral under the assumption that they contain no native
tokens — now documented on its totalPotentialCollateral parameters. A transaction built under a
wrong assumption is rejected by the ledger, and tokens are never lost: a valid transaction must
always give the tokens back in the return collateral output. Fixes #1261.

How to trust this PR

  • The first commit adds four regression tests (one per balancing function) with an ada-only
    collateral input holding exactly its minimum UTxO value: balancing must succeed, with no return
    collateral output and the whole input as total collateral. On the base branch they fail with
    TxBodyErrorReturnCollateralMinUTxONotMet; the second commit makes them pass.
  • The fold only happens when the collateral value is ada-only (isZero on the non-ada part):
    token-carrying collateral keeps failing, and the tests from the previous PR still pass.
  • The pre-existing property test prop_calcReturnAndTotalCollateral needs no change: its
    computed-case assertions hold for folded results.

Checklist

  • Commit sequence broadly makes sense and commits have useful messages
  • New tests are added if needed and existing tests are updated. See Running tests for more details
  • Self-reviewed the diff
  • Changelog fragment added in .changes/

palas added 2 commits July 24, 2026 03:09
Add four tests, for makeTransactionBodyAutoBalance and
estimateBalancedTxBody in both the traditional and the experimental
API: balancing a transaction with a Plutus script and an ada-only
collateral input must succeed even when the ada left over after
covering the required collateral is below the minimum UTxO value of a
return collateral output. The whole collateral input must be used as
total collateral, with no return collateral output.

The tests currently fail because balancing rejects the transaction
with TxBodyErrorReturnCollateralMinUTxONotMet.

Related to #1261
When the collateral is ada-only and the ada left after covering the
required collateral is below the minimum UTxO value of a return
collateral output, calcReturnAndTotalCollateral (traditional and
experimental API) now uses the whole collateral as total collateral and
omits the return collateral output, instead of failing: the extra ada
is only lost if a Plutus script fails on chain.

estimateBalancedTxBody cannot see the content of the collateral inputs,
so it computes collateral under the assumption that they carry no
native tokens. A transaction built under a wrong assumption is rejected
by the ledger, but tokens are never lost: a valid transaction must
always give the tokens back in the return collateral output. Document
this on the totalPotentialCollateral parameters.

Add the changelog fragment.

Fixes #1261
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant