From 390d6a9a2cde391e0b9f8ea63df58869ddb229b1 Mon Sep 17 00:00:00 2001 From: Pablo Lamela Date: Wed, 8 Jan 2025 14:53:44 +0100 Subject: [PATCH] Clarify balancing overview explanation and simplify references --- .../internal/Cardano/Api/Experimental/Tx.hs | 14 ++++++------ cardano-api/internal/Cardano/Api/Fees.hs | 22 +++++++++++++------ cardano-api/internal/Cardano/Api/Tx/Body.hs | 14 ++++++------ 3 files changed, 29 insertions(+), 21 deletions(-) diff --git a/cardano-api/internal/Cardano/Api/Experimental/Tx.hs b/cardano-api/internal/Cardano/Api/Experimental/Tx.hs index b705884a5e..4a57e749ff 100644 --- a/cardano-api/internal/Cardano/Api/Experimental/Tx.hs +++ b/cardano-api/internal/Cardano/Api/Experimental/Tx.hs @@ -49,14 +49,14 @@ module Cardano.Api.Experimental.Tx -- | -- If we have a UTxO with exactly 12 ADA, we could just construct the transaction like in the - -- previous section directly, and it would be a valid transaction. + -- previous section directly, and it would be a valid transaction, but: -- - -- That is because the requirement is that the sum of inputs of the transactions is equal to - -- the sum of the outputs, and that the fees specified are enough, and 2 ADA is more than enough - -- for fees of such a simple transaction on mainnet at the time of writing. But still, even if we - -- have exactly 12 ADA, it is unlikely that the fees required are exactly 2 ADA, so we are likely - -- wasting ADA on fees. Also, we may not always want to send all the ADA in the UTxO. So that is - -- were transaction balancing comes in. + -- * We are likely wasting ADA + -- * We may not have exactly one UTxO of 12 ADA + -- * Our transaciton may not be this simple + -- + -- For these reasons, it is recommended that we balance the transaction before proceeding with + -- signing and submitting. -- -- You can see how to balance a transaction in the documentation of the "Cardano.Api.Fees" module. diff --git a/cardano-api/internal/Cardano/Api/Fees.hs b/cardano-api/internal/Cardano/Api/Fees.hs index bc1cf03739..07536efbda 100644 --- a/cardano-api/internal/Cardano/Api/Fees.hs +++ b/cardano-api/internal/Cardano/Api/Fees.hs @@ -14,17 +14,25 @@ module Cardano.Api.Fees ( -- * Introduction - -- - -- | -- The documentation of the "Cardano.Api.Tx.Body" module shows how to create a 'TxBodyContent' for a -- transaction that takes 12 ADA and sends 10 ADA to an address, and spends 2 ADA on fees. If we have a - -- UTxO with exactly 12 ADA, this would be a valid transaction. + -- UTxO with exactly 12 ADA, this would be a valid transaction, because it is balanced, and it has + -- enough fees, since 2 ADA is more than enough for fees of such a simple transaction on mainnet + -- at the time of writing. + -- + -- A transaction is considered balanced if the value consumed is equivalent to the value produced. + -- In the simplest terms, a transaction that simply spends lovelace needs to be concerned with the + -- total lovelace that exists at the inputs, the output(s) and the transaction fee. + -- + -- In other words: + -- + -- @ + -- inputs = outputs + fee + -- @ -- - -- The requirement is that the sum of inputs of the transactions is equal to the sum of the outputs, - -- and that the fees specified are enough, and 2 ADA is more than enough for fees of such a simple - -- transaction on mainnet at the time of writing. But still, even if we have exactly 12 ADA, it is - -- unlikely that the fees required are exactly 2 ADA, so we are likely wasting ADA on fees. + -- In this equation, the inputs would include the minted tokens, and the outputs would include the + -- destroyed tokens. -- -- On the other hand, we don't always want to spend all the ADA from a UTxO. Balancing a transaction allows -- us to send the amount we want to send, pay only the necessary fees (or little more), and it diff --git a/cardano-api/internal/Cardano/Api/Tx/Body.hs b/cardano-api/internal/Cardano/Api/Tx/Body.hs index 2cc36ba5ac..8ca1ac9608 100644 --- a/cardano-api/internal/Cardano/Api/Tx/Body.hs +++ b/cardano-api/internal/Cardano/Api/Tx/Body.hs @@ -131,14 +131,14 @@ module Cardano.Api.Tx.Body -- | -- If we have a UTxO with exactly 12 ADA, we could just construct the transaction like in the - -- previous section directly, and it would be a valid transaction. + -- previous section directly, and it would be a valid transaction, but: -- - -- That is because the requirement is that the sum of inputs of the transactions is equal to - -- the sum of the outputs, and that the fees specified are enough, and 2 ADA is more than enough - -- for fees of such a simple transaction on mainnet at the time of writing. But still, even if we - -- have exactly 12 ADA, it is unlikely that the fees required are exactly 2 ADA, so we are likely - -- wasting ADA on fees. Also, we may not always want to send all the ADA in the UTxO. So that is - -- were transaction balancing comes in. + -- * We are likely wasting ADA + -- * We may not have exactly one UTxO of 12 ADA + -- * Our transaciton may not be this simple + -- + -- For these reasons, it is recommended that we balance the transaction before proceeding with + -- signing and submitting. -- -- You can see how to balance a transaction in the documentation of the "Cardano.Api.Fees" module.