Add docstrings for new balancing interface; Address requested changes

Author: errfrom

CHANGELOG.md

@@ -112,9 +112,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Made adjustments to the [E2E testing documentation page](./doc/e2e-testing.md). Updated the [template](./templates/ctl-scaffold) to use the newly introduced `e2eConfigs` helper function that allows to define E2E configurations without unnecessary boilerplate. ([#1674](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1674))
 - The transaction balancing module used in CTL has been extracted to a separate package [purescript-cardano-transaction-balancer](https://github.com/mlabs-haskell/purescript-cardano-transaction-balancer) using module names in the format `Cardano.Transaction.Balancer.*` ([#1680](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1680))
 - Updated the `Contract.Transaction` interface to support pluggable transaction balancers. This enhancement should allow users to integrate custom balancers when the provided default solution does not satisfy specific domain requirements. ([#1680](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1680))
-  - The `balanceTx` and `balanceTxE` functions from `Contract.Transaction` have been deprecated. Users are now encouraged to use standalone transaction balancers directly (e.g. `defaultBalancer` and `defaultBalancerErr` respectively).
+  - The `balanceTx` and `balanceTxE` functions from `Contract.Transaction` have been deprecated. Users are now encouraged to use standalone transaction balancers directly (e.g. `defaultBalancer` and `defaultBalancerWithErr` respectively).
   - The `balanceTxs` function has been deprecated in favor of the new balancer-agnostic `balanceMultipleTxs`.
-  - `Contract.Transaction` now exports `defaultBalancer` and `defaultBalancerErr` variants, both implementing the new `TxBalancer` interface.
+  - `Contract.Transaction` now exports `defaultBalancer` and `defaultBalancerWithErr` variants, both implementing the new `TxBalancer` interface.
   - **[BREAKING CHANGE]** `withBalancedTx` and `withBalancedTxs` now accept a `TxBalancer` and its corresponding balancer context as arguments.
   - The `submitTxFromConstraints` and `submitTxFromBuildPlan` functions have been deprecated in favor of `submitTxFromBlueprint`. The new function accepts a `TxBlueprint` with the steps and context needed to construct and balance a transaction, and returns a `TxReceipt` containing the balanced, signed transaction along with its hash.
   - *Note that all mentioned deprecated functions are planned for removal in a future release.*

doc/balancing.md

@@ -16,7 +16,7 @@ Transaction balancing in Cardano is the process of finding a set of inputs and o
 
 ## Balancer constraints
 
-The default transaction balancer used in CTL (`defaultBalancer` / `defaultBalancerErr`) allows users to adjust its behavior by imposing various constraints:
+The default transaction balancer used in CTL (`defaultBalancer` / `defaultBalancerWithErr`) allows users to adjust its behavior by imposing various constraints:
 
 - Using arbitrary address as user's own (for transaction balancing): `mustUseUtxosAtAddresses` / `mustUseUtxosAtAddress`
 - Providing additional UTxOs to use: `mustUseAdditionalUtxos`

src/Contract/Transaction.purs

@@ -105,10 +105,10 @@ import Ctl.Internal.BalanceTx
   ( CtlBalancer
   , CtlBalancerContext
   , defaultBalancer
-  , defaultBalancerErr
+  , defaultBalancerWithErr
   , emptyBalancerCtx
   ) as X
-import Ctl.Internal.BalanceTx (defaultBalancerErr)
+import Ctl.Internal.BalanceTx (defaultBalancerWithErr)
 import Ctl.Internal.Contract.AwaitTxConfirmed
   ( awaitTxConfirmed
   , awaitTxConfirmedWithTimeout
@@ -274,14 +274,14 @@ withBalancedTx balancer tx balancerCtx =
 balanceTxE
   :: Warn
        ( Text
-           "Deprecated, use a standalone transaction balancer instead (see `defaultBalancerErr`)"
+           "Deprecated, use a standalone transaction balancer instead (see `defaultBalancerWithErr`)"
        )
   => Transaction
   -> UtxoMap
   -> BalancerConstraints
   -> Contract (Either BalanceTxError.BalanceTxError Transaction)
 balanceTxE tx utxos constraints =
-  defaultBalancerErr tx
+  defaultBalancerWithErr tx
     { balancerConstraints: constraints
     , extraUtxos: utxos
     }
@@ -326,6 +326,8 @@ balanceTxs unbalancedTxs =
       withUsedTxOuts <<< unlockTransactionInputs <<< _.transaction
     throwError e
 
+-- | Balances each transaction using the specified `TxBalancer` and locks the
+-- | used inputs so that they cannot be reused by subsequent transactions.
 balanceMultipleTxs
   :: forall (ctx :: Type)
    . TxBalancer Contract Error ctx
@@ -345,6 +347,8 @@ balanceMultipleTxs balancer unbalancedTxs =
         unbalancedTxs
       throwError err
 
+-- | Balances the transaction using the specified balancer constraints and locks
+-- | its inputs to prevent their reuse in subsequent transactions.
 balanceAndLock
   :: Warn (Text "Deprecated, use `balanceAndLockUtxos` instead")
   => { transaction :: Transaction
@@ -357,6 +361,8 @@ balanceAndLock { transaction, usedUtxos, balancerConstraints } = do
   void $ withUsedTxOuts $ lockTransactionInputs balancedTx
   pure balancedTx
 
+-- | Balances the transaction using the specified `TxBalancer` and locks its
+-- | inputs to prevent their reuse in subsequent transactions.
 balanceAndLockUtxos
   :: forall (ctx :: Type)
    . TxBalancer Contract Error ctx

src/Internal/BalanceTx/BalanceTx.purs

@@ -2,7 +2,7 @@ module Ctl.Internal.BalanceTx
   ( CtlBalancer
   , CtlBalancerContext
   , defaultBalancer
-  , defaultBalancerErr
+  , defaultBalancerWithErr
   , emptyBalancerCtx
   ) where
 
@@ -40,6 +40,15 @@ import Data.Newtype (unwrap)
 import Effect.Aff.Class (liftAff)
 import Effect.Exception (Error, error)
 
+-- | Additional context required by the default CTL balancer.
+-- |
+-- | `balancerConstraints`: A set of rules that guide or modify the behavior of
+-- | the balancer.
+-- |
+-- | `extraUtxos`: Extra (non-wallet) utxos to be considered during balancing,
+-- | typically used to resolve pre-specified inputs of the unbalanced
+-- | transaction. See `getInputVal` in `Cardano.Transaction.Balancer` for
+-- | further details.
 type CtlBalancerContext =
   { balancerConstraints :: BalancerConstraints
   , extraUtxos :: UtxoMap
@@ -56,12 +65,12 @@ type CtlBalancer (err :: Type) = TxBalancer Contract err CtlBalancerContext
 defaultBalancer :: CtlBalancer Error
 defaultBalancer transaction =
   map (lmap (error <<< explainBalanceTxError))
-    <<< defaultBalancerErr transaction
+    <<< defaultBalancerWithErr transaction
 
 -- | Balances an unbalanced transaction using the specified balancer
 -- | constraints.
-defaultBalancerErr :: CtlBalancer BalanceTxError
-defaultBalancerErr transaction ctx = do
+defaultBalancerWithErr :: CtlBalancer BalanceTxError
+defaultBalancerWithErr transaction ctx = do
   contractEnv <- ask
   isCip30Wallet <- Sync.isCip30Wallet
   ownAddresses <- Wallet.getWalletAddresses