As an example, consider a LedgerState that contains a Ledger ledger state (such as the NewEpochState) and a UTxO set:

data instance LedgerState (Block era) mk = LedgerState {
    theLedgerLedgerState :: NewEpochState era
  , theTables            :: LedgerTables (Block era) mk
}

The Ledger ledger state contains a UTxO set as well, and with stowLedgerTables and unstowLedgerTables we move those between the Ledger ledger state and the LedgerTables, for example:

unstowLedgerTables (LedgerState {
                        theLedgerLedgerState = NewEpochState {
                            ...
                          , utxoSet = Map.fromList [('a', 100), ('b', 100), ...]
                        }
                      , theTables = EmptyMK
                    })
 ==
 LedgerState {
     theLedgerLedgerState = NewEpochState {
         ...
       , utxoSet = Map.empty
       }
   , theTables = ValuesMK (Map.fromList [('a', 100), ('b', 100), ...])
   })

stowLedgerTables (LedgerState {
                      theLedgerLedgerState = NewEpochState {
                          ...
                        , utxoSet = Map.empty
                      }
                    , theTables = ValuesMK (Map.fromList [('a', 100), ('b', 100), ...])
                  })
 ==
 LedgerState {
     theLedgerLedgerState = NewEpochState {
         ...
       , utxoSet = Map.fromList [('a', 100), ('b', 100), ...]
       }
   , theTables = EmptyMK
   })

Using these functions we can extract the data from the Ledger ledger state for us Consensus to manipulate, and we can then inject it back so that we provide the expected data to the ledger. Note that the Ledger rules for applying a block are defined in a way that it only needs the subset of the UTxO set that the block being applied will consume.

Now using calculateDifference, we can compare two (successive) LedgerStates to produce differences:

calculateDifference
  (LedgerState {
      ...
    , theTables = ValuesMK (Map.fromList [('a', 100), ('b', 100)])
    })
  (LedgerState {
      ...
    , theTables = ValuesMK (Map.fromList [('a', 100), ('c', 200)])
    })
==
 TrackingMK
   (Map.fromList [('a', 100),    ('c', 200)])
   (Map.fromList [('b', Delete), ('c', Insert 200)])

This operation provided a TrackingMK which is in fact just a ValuesMK and DiffMK put together.

We can then use those differences to forward a collection of values, so for example (taking the example above):

let tables1 = ValuesMK (Map.fromList [('a', 100), ('b', 100)])
    tables2 = ValuesMK (Map.fromList [('a', 100), ('c', 200)])
    diffs = rawForgetTrackingValues
          $ rawCalculateDifference tables1 tables2
in
  rawApplyDiffs tables1 diffs == tables2

Note: we usually don't call the raw* methods directly but instead call the corresponding function that operates on LedgerStates. See Ouroboros.Consensus.Ledger.Tables.Utils.

Also when applying a block that contains some transactions, we can produce LedgerTables of KeysMK, by gathering the txins required by the transactions:

getBlockKeySets (Block {..., txs = [Tx { input = ['a', 'b'], outputs = ['c', 'd'] }]})
 == KeysMK (Set.fromList ['a', 'b'])

We shall use those later on to read the txouts from some storage.

We call those types ending in "MK" mapkinds. They model the different types of collections and contained data in the tables. This example already covered most of the standard mapkinds, in particular:

EmptyMK

A nullary data constructor, an empty table.

ValuesMK

Contains a Data.Map from txin to txouts.

DiffMK

Contains a Data.Map from txin to a change on the value.

TrackingMK

Contains both a ValuesMK and DiffMK.

KeysMK

Contains a Data.Set of txins.

SeqDiffMK

A fingertree of DiffMKs.