chore: update "footgun" to "land mine" and add additional context and explanation

Author: yHSJ

src/ledger/ledger-rules/README.md

@@ -1,4 +1,8 @@
 # Ledger Rules
-This section details the ledger rules used in Cardano and, especially, some of the potential "foot guns" one could run into when implementing these rules. Those "foot guns" could be discrepencies between the specification and the ledger, some undefined behavior, or a bug that was fixed at some point, but is still relevant for syncing historical data.
 
-It is an ongoing work in progress, being updated periodically in paralel with the work happening to build Amaru.
+This section details the ledger rules used in Cardano and, especially, some of the potential "land mines" one could run into when implementing these rules.
+
+The ledger rules will be organized in a potentially unique way. Instead of grouping them based on inference rules defined in the [Cardano Ledger Specification](https://intersectmbo.github.io/formal-ledger-specifications/cardano-ledger.pdf) or some arbitrary implementation of said specification, they are grouped based on their responsibility throughout the validation process. For example, "Witness Validation" contains several rules related to validating the transaction witness set.
+
+## What is a "Land Mine"?
+In this context, a "Land Mine" is a part of the ledger rules that could cause confusion or are easy to get wrong. This could be a discrepency between the Haskell implementation and the formal specification (A bug or otherwise), some unintended behavior that resulted from an edge case that was not considered during initial implementation, or simply something that caused an issue for some alternative node implementors, and therefore should be documented for the future implementors.

src/ledger/ledger-rules/witness-validation.md

@@ -1,9 +1,33 @@
 # Witness Validation
 
-TODO: provide a description of the ledger rules relevant to this domain specific concept.
+### Key Definitions
+**`Witness`**: A witness is a piece of data that allows you to verify the authenticity of the transaction. There are many different witness types, depending on what the transaction requires, such as vkey witnesses, bootstrap witnesses, and script witnesses.
 
-## Footgun #1: Bootstrap Witnesses
-Alonzo introduced a [`bootstrap_witness`](https://github.com/IntersectMBO/cardano-ledger/blob/d71d7923a79cfcde8cac0b5db399a5427524d06a/eras/allegra/impl/cddl-files/allegra.cddl#L314-L319), which is a different structure for witnesses from a bootstrap address. One would, perhaps reasonably, assume that all witnesses from bootstrap addresses would be provided in this list. However, that is not an assumption that can be made.
+**`Vkey Witness`**: A vkey witness is a specific witness type. It is used to verify that the transaction has the authority to consume a UTxO(s) locked at the assosciated `pkh` address. It includes the signature and the vkey (instead of the key hash, which is encoded in the address).
+
+**`Bootstrap Witness`**: A bootstrap witness is a specific witness type. It is used to verify that the transaction has the authority to consume a UTxO(s) locked at the associated Byron-era address. It includes the assosciated public key, the signature, the 32 byte chain code, and a set of attributes encoded in the address.
+
+*TODO: script witnesses*
+
+### Process
+
+Witness validation is the process of validating that all witnesses are:
+1) Valid signatures given the tranasaction hash and the provided public key.
+2) Present if required by the transaction. There cannot be any missing witnesses.
+3) *TODO: script witness validation*
+
+The process of witness validation is described in section 12.2 of the [Cardano Ledger Specification](https://intersectmbo.github.io/formal-ledger-specifications/cardano-ledger.pdf), in the UTXOW inference rules.
+
+*TODO: provide links to the relevent sections of code in Amaru and Haskell node*
+
+
+## "Land Mine" #1: Bootstrap Witnesses
+
+### Context
+After Shelley introduced the [`bootstrap_witness`](https://github.com/IntersectMBO/cardano-ledger/blob/d71d7923a79cfcde8cac0b5db399a5427524d06a/eras/shelley/impl/cddl-files/shelley.cddl#L296-L301) field to the `transaction_witness_set`. One may reasonably assume that if a Byron-era address is present, the assosciated witness would be found in the `bootstrap_witness` field. However, it is possible to construct a valid transaction such that it includes a Byron-era address, but the `bootstrap_witness` field is an empty list.
+
+### Solution
+A node must consider the set of bootstrap root hashes and vkey hashes together when validating that there are no missing required witnesses, instead of isolating the handling of bootstrap addresses and `BootstrapWitness`es from shelley-era addresses and `VkeyWitness`es.
 
 ### Example: `0c22edee0ffd7c8f32d2fe4da1f144e9ef78dfb51e1678d5198493a83d6cf8ec`
 Consider the following [transaction](https://preprod.cexplorer.io/tx/0c22edee0ffd7c8f32d2fe4da1f144e9ef78dfb51e1678d5198493a83d6cf8ec) on Preprod. In JSON, it looks like this:
@@ -60,7 +84,7 @@ Consider the following [transaction](https://preprod.cexplorer.io/tx/0c22edee0ff
 }
 ```
 
-Notably, there is only one signature, and it is not in the form of a bootstrap witness. If we look at the logic that collects vkey hashes that must be present in the witness set ([`getShelleyWitsVkeyNeededNoGov`](https://github.com/IntersectMBO/cardano-ledger/blob/d71d7923a79cfcde8cac0b5db399a5427524d06a/eras/shelley/impl/src/Cardano/Ledger/Shelley/UTxO.hs#L226-L249)), we can understand why.
+Notably, there is only one signature, and it is a `VkeyWitness`. Examining the logic that collects required key hashes ([`getShelleyWitsVkeyNeededNoGov`](https://github.com/IntersectMBO/cardano-ledger/blob/d71d7923a79cfcde8cac0b5db399a5427524d06a/eras/shelley/impl/src/Cardano/Ledger/Shelley/UTxO.hs#L226-L249)), the reason becomes apparent:
 ```hs
 inputAuthors :: Set (KeyHash 'Witness)
 inputAuthors = foldr' accum Set.empty (txBody ^. spendableInputsTxBodyF)
@@ -76,6 +100,9 @@ inputAuthors = foldr' accum Set.empty (txBody ^. spendableInputsTxBodyF)
         Nothing -> ans
 ```
 
-Bootstrap witnesses and vkey witnesses are combined in the same set, since they are both just hash digests of the same size. That means, if one were to construct a bootstrap address with a payload containing only the keyhash, the validation would pass with a regular vkey witness, instead of a bootstrap witness.
+The Haskell node is inserting hashes from both `AddrBootstrap` and `Addr` into the same set, since they are both just hash digests of the same size. The hash digest inserted in the case of an `AddrBootstrap` is the bytes that are found at the first field of the `BYRON_ADDRESS_PAYLOAD`. In theory, this is the digest of the `blake2b_224(sha3_256(BYRON_ADDRESS_ROOT))` and that should never be the same digest as a `Addr` vkey hash digest, so there would be no complexity introduced here. However one could, and clearly did, manually construct a Byron-era address where the bytes that are suppose to be the digest of the `BYRON_ADDRESS_ROOT` are instead the digest of a vkey. In that case, a vkey witness present with the assosciated public key would satifsy the required witness, even though that requirement came from an Byron-era bootstrap address.
 
-The witnesses themselves are valdiated in isolation–just that they are valid signatures on the required data–so the presence of a boostrap address does not necessarily require the presence of a bootstrap witness.
+> [!TIP]
+>
+> The provided solution already handles this case, but it's worth noting that this could, theoretically, also apply the other direction. If one were to construct a shelley era address where the payment part is the digest of some `BYRON_ADDRESS_ROOT` instead of a verification key, they could have a `BootstrapWitness` present instead of a `VkeyWitness`.
+> Author's note: I only just thought of this case while writing up this information and haven't verified that it's true. But, off the top of my head, there is no reason this wouldn't be the case.