Better error messages for balanceTx and related functions

CHANGELOG.md

@@ -56,6 +56,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Added
 
+- `mkUnbalancedTxE`, as a 'throwing' version of `mkUnbalancedTx`. This version
+  throws an exception on failure, instead of returning in `Either`.
+- `balanceTxE` and `balanceTxWithConstraintsE`, as 'throwing' versions of
+  `balanceTx` and `balanceTxWithConstraints`. These throw exceptions on failure,
+  instead of returning in `Either`.
+- `explainMkUnbalancedTxError` and `explainBalanceTxError`, which prettyprint
+  `MkUnbalancedTxError` and `BalanceTxError` for a more human-readable output.
 - Added `extraSources` and `data` features to CTL's Nix build function ([#1516](https://github.com/Plutonomicon/cardano-transaction-lib/pull/1516))
 - Added several `Ring`-like numeric instances for `Coin` ([#1485](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1485))
 - Added `ToData` and `FromData` instances for `PoolPubKeyHash` ([#1483](https://github.com/Plutonomicon/cardano-transaction-lib/issues/1483))

src/Contract/Transaction.purs

@@ -3,8 +3,10 @@
 module Contract.Transaction
   ( BalancedSignedTransaction(BalancedSignedTransaction)
   , balanceTx
+  , balanceTxE
   , balanceTxM
   , balanceTxWithConstraints
+  , balanceTxWithConstraintsE
   , balanceTxs
   , balanceTxsWithConstraints
   , calculateMinFee
@@ -72,6 +74,7 @@ import Ctl.Internal.BalanceTx.Error
   , Expected(Expected)
   , ImpossibleError(Impossible)
   , InvalidInContext(InvalidInContext)
+  , explainBalanceTxError
   ) as BalanceTxError
 import Ctl.Internal.BalanceTx.UnattachedTx (UnindexedTx)
 import Ctl.Internal.Cardano.Types.NativeScript
@@ -238,7 +241,7 @@ import Ctl.Internal.Types.VRFKeyHash
 import Data.Array.NonEmpty as NonEmptyArray
 import Data.Bifunctor (lmap)
 import Data.BigInt (BigInt)
-import Data.Either (Either, hush)
+import Data.Either (Either(Left, Right), hush)
 import Data.Foldable (foldl, length)
 import Data.Generic.Rep (class Generic)
 import Data.Lens.Getter (view)
@@ -407,6 +410,9 @@ unUnbalancedTx
 
 -- | Attempts to balance an `UnbalancedTx` using the specified
 -- | balancer constraints.
+-- |
+-- | This is a 'non-throwing' variant of this functionality. Use this when
+-- | errors are expected, and graceful recovery is possible.
 balanceTxWithConstraints
   :: UnbalancedTx
   -> BalanceTxConstraintsBuilder
@@ -417,13 +423,40 @@ balanceTxWithConstraints tx =
   in
     BalanceTx.balanceTxWithConstraints tx' ix
 
+-- | 'Throwing' variant of `balanceTxWithConstraints`. Instead of returning in
+-- | `Either`, it throws an exception on failure. Use this when errors are not
+-- | expected, and graceful recovery is either impossible or wouldn't make
+-- | sense.
+balanceTxWithConstraintsE
+  :: UnbalancedTx
+  -> BalanceTxConstraintsBuilder
+  -> Contract FinalizedTransaction
+balanceTxWithConstraintsE tx bcb = do
+  result <- balanceTxWithConstraints tx bcb
+  case result of
+    Left err -> throwError $ error $ BalanceTxError.explainBalanceTxError err
+    Right ftx -> pure ftx
+
 -- | Same as `balanceTxWithConstraints`, but uses the default balancer
 -- | constraints.
+-- |
+-- | This is a 'non-throwing' variant of this functionality. Use this when
+-- | errors are expected, and graceful recovery is possible.
 balanceTx
   :: UnbalancedTx
   -> Contract (Either BalanceTxError.BalanceTxError FinalizedTransaction)
 balanceTx = flip balanceTxWithConstraints mempty
 
+-- | 'Throwing' variant of `balanceTx`. Instead of returning in `Either`, it
+-- | throws an exception on failure. Use this when errors are not expected, and
+-- | graceful recovery is either impossible or wouldn't make sense.
+balanceTxE :: UnbalancedTx -> Contract FinalizedTransaction
+balanceTxE utx = do
+  result <- balanceTx utx
+  case result of
+    Left err -> throwError $ error $ BalanceTxError.explainBalanceTxError err
+    Right ftx -> pure ftx
+
 -- | Balances each transaction using specified balancer constraint sets and
 -- | locks the used inputs so that they cannot be reused by subsequent
 -- | transactions.

src/Internal/BalanceTx/Error.purs

@@ -21,6 +21,7 @@ module Ctl.Internal.BalanceTx.Error
   , Expected(Expected)
   , ImpossibleError(Impossible)
   , printTxEvaluationFailure
+  , explainBalanceTxError
   ) where
 
 import Prelude
@@ -89,6 +90,37 @@ instance Show BalanceTxError where
     "ExUnitsEvaluationFailed: " <> printTxEvaluationFailure tx failure
   show e = genericShow e
 
+explainBalanceTxError :: BalanceTxError -> String
+explainBalanceTxError = case _ of
+  BalanceInsufficientError expected actual ctx ->
+    "Insufficient balance. Expected: " <> show expected
+      <> ", actual: "
+      <> show actual
+      <> ". Context: "
+      <> show ctx
+  CouldNotConvertScriptOutputToTxInput ->
+    "Could not convert script output to transaction input."
+  CouldNotGetChangeAddress ->
+    "Could not get change address."
+  CouldNotGetCollateral -> "Could not get collateral."
+  CouldNotGetUtxos -> "Could not get UTxOs."
+  CollateralReturnError err ->
+    "Collateral return error: " <> show err
+  CollateralReturnMinAdaValueCalcError ->
+    "Could not calculate minimum Ada for collateral return."
+  ExUnitsEvaluationFailed tx txEvalErr ->
+    "Script evaluation failure. Transaction: " <> show tx
+      <> "Error: "
+      <> show txEvalErr
+  InsufficientUtxoBalanceToCoverAsset _ asset ->
+    "Insufficient UTxO balance to cover asset " <> show asset
+  ReindexRedeemersError uir ->
+    "Could not reindex redeemer " <> show uir
+  UtxoLookupFailedFor ti ->
+    "Could not look up UTxO for " <> show ti
+  UtxoMinAdaValueCalculationFailed ->
+    "Could not calculate min ADA for UTxO."
+
 newtype Actual = Actual Value
 
 derive instance Generic Actual _