Fold return collateral dust into the total collateral#1267
Open
palas wants to merge 2 commits into
Open
Conversation
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
palas
requested review from
CarlosLopezDeLara,
Jimbo4350,
carbolymer,
disassembler and
erikd
as code owners
July 24, 2026 02:46
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
This is the third of three stacked PRs fixing #1261: the balancing functions
(
makeTransactionBodyAutoBalanceandestimateBalancedTxBody, in both the traditional and theexperimental 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️⃣
transaction builddoes not validate min UTxO value of the collateral return outputThis 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 intothe total collateral and omits the return collateral output instead of failing; the extra ada is
only lost if a Plutus script fails on chain.
estimateBalancedTxBodycannot see the content ofthe collateral inputs, so it computes collateral under the assumption that they contain no native
tokens — now documented on its
totalPotentialCollateralparameters. A transaction built under awrong 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
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.isZeroon the non-ada part):token-carrying collateral keeps failing, and the tests from the previous PR still pass.
prop_calcReturnAndTotalCollateralneeds no change: itscomputed-case assertions hold for folded results.
Checklist
.changes/