A SafeHash is a hash of something that is safe to hash. Such types store their own serialisation bytes. The prime example is (MemoBytes t), but other examples are things that consist of only ByteStrings (i.e. they are their own serialization) or for some other reason store their original bytes.

We do NOT export the constructor SafeHash, but instead export other functions such as 'hashWithCrypto, hashAnnotated and extractHash which have constraints that limit their application to types which preserve their original serialization bytes.

Only Types that preserve their serialisation bytes are members of the class SafeToHash. There are only a limited number of primitive direct instances of SafeToHash, all but two of them are present in this file. Instead of making explicit instances, we almost always use a newtype (around a type S) where their is already an instance (SafeToHash S). In that case the newtype has its SafeToHash instance derived using newtype deriving. The prime example of s is MemoBytes. The only exceptions are the legacy Shelley types: Metadata and ShelleyTx, that preserve their serialization bytes using a different mechanism than the use of MemoBytes. SafeToHash is a superclass requirement of the classes HashAnnotated and HashWithCrypto (below) which provide more convenient ways to construct SafeHashes than using makeHashWithExplicitProxys.

Types that are SafeToHash, AND have both of the following two invariants, are made members of the HashAnnotated class. The preconditions are:

1. The type uniquely determines the index type tag of (SafeHash crypto index)
2. The type uniquely determines the crypto type of (SafeHash crytop index)

The SafeToHash and the HashAnnotated classes are designed so that their instances can be easily derived (because their methods have default methods when the type is a newtype around a type that is SafeToHash). For example,

  newtype T era = T S
     deriving Eq
     deriving newtype SafeToHash -- Uses {-# LANGUAGE DerivingStrategies #-}

  instance HashAnnotated (T era) Index (Crypto era)

After these declarations. One specialization of hashAnnotated is (hashAnnotated :: Era e => T e -> SafeHash (Crypto e) Index)

Create a (SafeHash i crypto), given (Hash.HashAlgorithm (HASH crypto)) and (HashAnnotated x i crypto) instances.

Create (SafeHash index crypto) values, used when the type being hashed: x determines the index tag but not the crypto tag of x

Don't use this except in Testing to make Arbitrary instances, etc. Defined here, only because the Constructor is in scope here.

To change the index parameter of SafeHash (which is a phantom type) use castSafeHash

Extract the hash out of a SafeHash

Sometimes one wants to hash multiple things, simply by concatenating all the bytes. This abstraction allows one to do that safely.