Skip to content

Commit

Permalink
Add documentation comments for 'TxSkeleton' and related functions.
Browse files Browse the repository at this point in the history
  • Loading branch information
jonathanknowles committed Apr 29, 2021
1 parent d98beeb commit d7ff662
Showing 1 changed file with 24 additions and 3 deletions.
27 changes: 24 additions & 3 deletions lib/shelley/src/Cardano/Wallet/Shelley/Transaction.hs
Original file line number Diff line number Diff line change
Expand Up @@ -639,6 +639,15 @@ txConstraints protocolParams witnessTag = TxConstraints
nullByte :: Word8
nullByte = 0

-- | Includes just the parts of a transaction necessary to estimate its size.
--
-- In particular, this record type includes the minimal set of data needed for
-- the 'estimateTxCost' and 'estimateTxSize' functions to perform their
-- calculations, and nothing else.
--
-- The data included in 'TxSkeleton' is a subset of the data included in the
-- union of 'SelectionSkeleton' and 'TransactionCtx'.
--
data TxSkeleton = TxSkeleton
{ txMetadata :: !(Maybe TxMetadata)
, txDelegationAction :: !(Maybe DelegationAction)
Expand All @@ -650,6 +659,10 @@ data TxSkeleton = TxSkeleton
}
deriving (Eq, Show)

-- | Constructs an empty transaction skeleton.
--
-- This may be used to estimate the size and cost of an empty transaction.
--
emptyTxSkeleton :: TxWitnessTag -> TxSkeleton
emptyTxSkeleton txWitnessTag = TxSkeleton
{ txMetadata = Nothing
Expand All @@ -661,6 +674,11 @@ emptyTxSkeleton txWitnessTag = TxSkeleton
, txChange = []
}

-- | Constructs a transaction skeleton from wallet primitive types.
--
-- This function extracts a subset of the data included in 'SelectionSkeleton'
-- and 'TransactionCtx'.
--
mkTxSkeleton
:: TxWitnessTag
-> TransactionCtx
Expand All @@ -676,6 +694,8 @@ mkTxSkeleton witness context skeleton = TxSkeleton
, txChange = view #skeletonChange skeleton
}

-- | Estimates the final cost of a transaction based on its skeleton.
--
estimateTxCost :: ProtocolParameters -> TxSkeleton -> Coin
estimateTxCost pp args =
computeFee $ estimateTxSize args
Expand All @@ -686,12 +706,13 @@ estimateTxCost pp args =
computeFee (TxSize size) =
Coin $ ceiling (a + b * fromIntegral size)

-- Estimate the size of a final transaction by using upper boundaries for cbor
-- serialized objects according to:
-- | Estimates the final size of a transaction based on its skeleton.
--
-- This function uses the upper bounds of CBOR serialized objects as the basis
-- for many of its calculations. The following document is used as a reference:
--
-- https://github.com/input-output-hk/cardano-ledger-specs/blob/master/shelley/chain-and-ledger/shelley-spec-ledger-test/cddl-files/shelley.cddl
--
-- All sizes below are in bytes.
estimateTxSize :: TxSkeleton -> TxSize
estimateTxSize args =
TxSize $ fromIntegral sizeOf_Transaction
Expand Down

0 comments on commit d7ff662

Please sign in to comment.