Calculating fees.

The Cardano.Api.Internal.Tx.Body documentation demonstrates how to create a TxBodyContent for a transaction that takes 12 ada and sends 10 ada to an address, and spends 2 ada for fees. If a UTXO with exactly 12 ada is available, this would be a valid transaction, because it is balanced, and has sufficient fees, as 2 ada is more than enough to cover the fees for such a simple transaction on mainnet at the time of writing.

A simple transaction that spends UTXOs is considered balanced if the value consumed equals the value produced. Simply put, a transaction that spends only lovelace must account for the total lovelace at the inputs, output(s), and transaction fee.

In other words:

inputs = outputs + fee

In this equation, the inputs would include the minted tokens, and the outputs would include the burned tokens.

However, we don't always want to spend all the ada from a UTXO. Balancing a transaction ensures that we send the desired amount, pay only the necessary fees, and calculate any extra currency to be sent back to a change address.

Since changes to the transaction body can affect the required, finding this balance can be challenging. Fortunately, there are functions available to help achieve this.

This module offers several methods for calculating transaction fees or fully balancing a draft transaction. Each method requires varying amounts of information and provides different levels of accuracy and automation.

Next, this module explores three examples of fee calculation methods. Other methods exist but they have similar requirements.

Examples below use the following qualified modules:

import qualified Cardano.Api as Api                -- the general `cardano-api` exports

This method requires minimal information and some manual work.

It calculates the transaction fees, but we need to balance the transaction manually.

We need to know:

1. The Shelley-based era witness for the current era, which can be obtained by using shelleyBasedEra.

let sbe :: Api.ShelleyBasedEra Api.ConwayEra = Api.shelleyBasedEra

2. The protocol parameters for the current era, which can be obtained using the QueryProtocolParameters query defined in Cardano.Api.Internal.Query. Let's assume they are stored in the exampleProtocolParams variable.
3. The draft transaction body, which can be created using createTransactionBody defined in Cardano.Api.Internal.Tx.Body:

let (Right txBody) = Api.createTransactionBody sbe txBodyContent

4. The number of Byron and Shelley key witnesses, which corresponds to the number of keys required to sign the transaction. We can estimate this by using estimateTransactionKeyWitnessCount. For a simple transaction with a single UTXO locked by a single modern Shelley key, there would be 0 Byron witnesses and 1 Shelley witness.
5. The size of any reference scripts in bytes (if any). For simple transactions, this would be 0.

With this in mind, it is possible to estimate the fees required by the transaction by calling evaluateTransactionFee as follows:

let fees = Api.evaluateTransactionFee sbe exampleProtocolParams txBody 0 1 0

Once we know the required fees, we can balance the transaction by subtracting fees from the total value of the UTXO being spent.

For example, if we have a UTXO with 12 ada, the fees are 0.2 ada, and we want to send 10 ada to an address, the transaction could look like this:

• 1 input of 12 ada (from the UTXO)
• 1 output of 10 ada (to the recipient address)
• 1 output of 1.8 ada (to the change address)
• 0.2 ada in fees (calculated fees, in this case, an overestimation).

We would then have to update the TxBodyContent accordingly and continue building the transaction as demonstrated in Cardano.Api.Internal.Experimental.Tx.

This method requires more information, but better automates the process, reducing the need for estimation. It also works with a TxBodyContent, rather than a full TxBody.

The following information is required:

1. The MaryEraOnwards witness for the current era. In this case, we use the one for the Conway era:

let meo = Api.MaryEraOnwardsConway

2. The draft TxBodyContent for the transaction we want to balance. See how to create one in Cardano.Api.Internal.Tx.Body. It is assumed to be stored in the txBodyContent variable.
3. The protocol parameters for the current era, which can be obtained using the QueryProtocolParameters query defined in Cardano.Api.Internal.Query. Let's assume they are stored in the exampleProtocolParams variable.

4. For stake pool and governance actions, we will also need:

   • The set of registered stake pools being unregistered in this transaction
   • The map of all deposits for stake credentials being unregistered in this transaction
   • The map of all deposits for DRep credentials that are unregistered in this transaction
   • Plutus script execution units for all script witnesses used in the transaction.

This example assumes we are only spending key-locked UTXOs. Therefore, we can ignore the above and use mempty.

5. The following amounts:

   • Collateral amount: required only for transactions involving Plutus scripts. Since this transaction does not include any, the collateral is 0.
   • Amount of Shelley key witnesses to be added: estimated using estimateTransactionKeyWitnessCount. For a simple transaction spending a single UTXO locked by a modern Shelley key, there is 1 Shelley witness.
   • Amount of Byron key witnesses to be added: assumed to be 0 for this transaction.
   • Size of all reference scripts (in bytes): since no reference scripts are used, this value is 0.
6. The address for sending the change. We can deserialize it from its bech32 representation using the deserialiseAddress function defined in Cardano.Api.Internal.Address:

let Just exampleChangeAddress =
           Api.deserialiseAddress
             (Api.AsAddressInEra eraAsType)
             "addr_test1vzpfxhjyjdlgk5c0xt8xw26avqxs52rtf69993j4tajehpcue4v2v"

Alternatively, we can get it from our signing key:

let exampleChangeAddress =
      Api.shelleyAddressInEra sbe $
        Api.makeShelleyAddress
          (Api.Testnet $ Api.NetworkMagic 2)    -- The magic for the network we are using
          (Api.PaymentCredentialByKey
             $ Api.verificationKeyHash
                 $ Api.getVerificationKey
                     signingKey)
          Api.NoStakeAddress                    -- Potentially, the stake credential if we want to use one

7. Finally, we need the total amount of ada (and other tokens) in the UTXOs being spent. In this example, the transaction spends 12 ada:

let totalUTxOValue = Api.lovelaceToValue 12_000_000

With all this information, a balanced transaction can be obtained by calling estimateBalancedTxBody as follows:

let (Right (Api.BalancedTxBody
              updatedTxBodyContent
              updatedTxBody
              changeOutput
              fees)) =
      Api.estimateBalancedTxBody
        meo
        txBodyContent
        exampleProtocolParams
        mempty
        mempty
        mempty
        mempty
        0
        1
        0
        0
        exampleChangeAddress

This will produce a balanced transaction body with calculated fees and a change output, but it still needs to be signed and submitted.

The previous example required manually providing various details, which was feasible for a simple transaction. However, for more complex transactions involving scripts or advanced functionalities such as governance actions, a more automated approach is available. This method performs most calculations in exchange for general ledger information.

The following details are required:

1. Shelley-based era witness for the current era, retrievable using shelleyBasedEra.

let sbe :: Api.ShelleyBasedEra Api.ConwayEra = Api.shelleyBasedEra

2. Network start time, obtainable using the QuerySystemStart query defined in Cardano.Api.Internal.Query. Assume we have it in the exampleSystemStart variable.
3. Ledger epoch information, derivable by applying toLedgerEpochInfo to the EraHistory, which can be retrieved using the QueryEraHistory query defined in Cardano.Api.Internal.Query. Assume this is stored in the exampleLedgerEpochInfo variable.
4. Protocol parameters for the current era, accessible through the QueryProtocolParameters query defined in Cardano.Api.Internal.Query. Assume this is stored in the exampleProtocolParams variable.

5. For stake pool and gov actions, additional data is requried:

   • The set of registered stake pools being unregistered in this transaction
   • The map of all deposits associated with stake credentials being unregistered in this transaction
   • The map of all deposits associated with DRep credentials being unregistered in this transaction.

For this example, no stake pool deregistration or governance actions are considered, so mempty is used for the corresponding parameters.

6. UTXO set being spent -- the full UTXO set can be obtained using the QueryUTxO query from Cardano.Api.Internal.Query. Assume this is stored in the utxoToUse variable.
7. Draft transaction body content -- the TxBodyContent for the transaction that requires balancing. The process for creating this structure is demonstrated in Cardano.Api.Internal.Tx.Body.
8. Change address -- the address where any remaining balance should be returned. This can be deserialized from its Bech32 representation using the deserialiseAddress function from Cardano.Api.Internal.Address:

let (Just exampleChangeAddress) =
            Api.deserialiseAddress
              (Api.AsAddressInEra eraAsType)
              "addr_test1vzpfxhjyjdlgk5c0xt8xw26avqxs52rtf69993j4tajehpcue4v2v"

Alternatively, it is possible to get it from the signing key:

let exampleChangeAddress =
      Api.shelleyAddressInEra sbe $
        Api.makeShelleyAddress
          (Api.Testnet $ Api.NetworkMagic 2)    -- The magic for the network we are using
          (Api.PaymentCredentialByKey
             $ Api.verificationKeyHash
                 $ Api.getVerificationKey
                     signingKey)
          Api.NoStakeAddress                    -- Potentially, the stake credential if we want to use one

9. Finally, the number of key witnesses required for the transaction can be manually specified. However, if set to Nothing, the function will automatically estimate the required number.

With all the necessary information available, a balanced transaction can be obtained by calling makeTransactionBodyAutoBalance as follows:

let Right (Api.BalancedTxBody
             updatedTxBodyContent
             updatedTxBody
             changeOutput
             fees) =
   Api.makeTransactionBodyAutoBalance
     sbe
     exampleSystemStart
     exampleLedgerEpochInfo
     (Api.LedgerProtocolParameters exampleProtocolParams)
     mempty
     mempty
     mempty
     utxoToUse
     txBodyContent
     exampleChangeAddress
     Nothing

This will give us a balanced transaction with the fees calculated and the change output included. The transaction can now be signed and submitted.