docs: clear up certificate verification (#1515)

**Motivation:**

We want more descriptive documentation for the `CertificateVerifier`
 
**Modifications:**

- Update natspec for `CertificateVerifier`, along with meaning of
`maxStalenessPeriod`
- Update docs for above

**Result:**

Clearer documentation

Author: ypatil12

docs/multichain/README.md

@@ -71,6 +71,17 @@ Transporter --> Generator: Gets Root
 Transporter --> OperatorTableUpdater: Confirms Root, Updates Tables
 OperatorTableUpdater --> CertificateVerifier: Updates table
 ```
+
+The protocol proceeds in the following process:
+
+1. AVS deploys `AVSRegistrar` , configures metadata in EL, and gets operator registration
+    1. AVS registers for generation/transport calling `CrossChainRegistry.makeGenerationReservation`
+    2. The AVS deploys an `OperatorTableCalculator` 
+2. At some cadence, the `Generator`` process gets all active generations from the `CrossChainRegistry` against the latest `finalizedBlock` 
+    1. It then creates and signs a `globalTableRoot` of all operator table commitments
+3. The transporter will generate a Certificate to validate that the Eigen Labs Operator signed off on the `globalTableRoot`. The root is then transported to ALL destination chains 
+4. Lastly, the transporter will update all Operator Tables with a certificate. The sidecar will generate the proof data to then update tables via the `OperatorTableUpdater`
+
 ---
 
 ### Source Chain

docs/multichain/destination/CertificateVerifier.md

@@ -26,7 +26,7 @@ The CertificateVerifier contracts are responsible for verifying certificates fro
 
 Both verifiers implement staleness checks based on a `maxStalenessPeriod` to ensure certificates are not verified against outdated operator information. 
 
-*Note: Setting a max staleness period to 0 enables certificates to be confirmed against any `referenceTimestamp`*. 
+**Note: Setting a max staleness period to 0 enables certificates to be confirmed against any `referenceTimestamp`. In addition, setting a `maxStalenessPeriod` that is greater than 0 and less than the frequency of table updates (daily on testnet, weekly on mainnet) can result in certificates be unable to be confirmed.** See the [staleness period](#staleness-period) in the appendix for some examples. 
 
 ---
 
@@ -60,7 +60,7 @@ struct ECDSAOperatorInfo {
  * @param referenceTimestamp the timestamp at which the operatorInfos were sourced
  * @param operatorInfos the operatorInfos to update the operator table with
  * @param operatorSetConfig the configuration of the operatorSet
- * @dev only callable by the operatorTableUpdater for the given operatorSet
+ * @dev Only callable by the `OperatorTableUpdater`
  * @dev The `referenceTimestamp` must be greater than the latest reference timestamp for the given operatorSet
  */
 function updateOperatorTable(
@@ -73,6 +73,8 @@ function updateOperatorTable(
 
 Updates the operator table with new `operatorInfos` and `operatorSetConfig`. All operators and weights are written to storage. 
 
+Note that updating operator tables for a `referenceTimestamp` that is less than the latest reference timestamp is not possible. Thus, operator tables cannot be updated retroactively. AVS developers should keep this in mind when building their off-chain signature aggregation logic. 
+
 *Effects*:
 * Stores the number of operators at `_numOperators[operatorSetKey][referenceTimestamp]`
 * Stores each operator info at `_operatorInfos[operatorSetKey][referenceTimestamp][index]`
@@ -97,7 +99,8 @@ The contract supports 3 verification patterns:
 ```solidity
 /**
  * @notice A ECDSA Certificate
- * @param referenceTimestamp the timestamp at which the certificate was created
+ * @param referenceTimestamp the timestamp at which the certificate was created, 
+ *        which corresponds to a reference timestamp of the operator table update
  * @param messageHash the hash of the message that was signed by operators
  * @param sig the concatenated signature of each signing operator
  */
@@ -282,8 +285,9 @@ struct BN254OperatorSetInfo {
  * @param referenceTimestamp the timestamp at which the operatorInfos were sourced
  * @param operatorSetInfo the operatorInfos to update the operator table with
  * @param operatorSetConfig the configuration of the operatorSet
- * @dev only callable by the operatorTableUpdater for the given operatorSet
- * @dev The `referenceTimestamp` must be greater than the latest reference timestamp for the given operatorSet
+ * @dev Only callable by the `OperatorTableUpdater`
+ * @dev The `referenceTimestamp` must correspond to a reference timestamp for a globalTableRoot stored in the `OperatorTableUpdater`. 
+ *     It must also be greater than the latest reference timestamp for the given operatorSet.
  */
 function updateOperatorTable(
     OperatorSet calldata operatorSet,
@@ -295,6 +299,8 @@ function updateOperatorTable(
 
 Updates the operator table with new `operatorSetInfo` and `operatorSetConfig`. 
 
+Note that updating operator tables for a `referenceTimestamp` that is less than the latest reference timestamp is not possible. Thus, operator tables cannot be updated retroactively. AVS developers should keep this in mind when building their off-chain signature aggregation logic. 
+
 *Effects*:
 * Stores `operatorSetInfo` at `_operatorSetInfos[operatorSetKey][referenceTimestamp]` containing:
   * `operatorInfoTreeRoot` - Merkle root of all operator information, each leaf is a `BN254OperatorInfo`
@@ -321,7 +327,8 @@ The contract supports 3 verification patterns:
 ```solidity
 /**
  * @notice A BN254 Certificate
- * @param referenceTimestamp the timestamp at which the certificate was created
+ * @param referenceTimestamp the timestamp at which the certificate was created,
+ *        which corresponds to the reference timestamp of the operator table update
  * @param messageHash the hash of the message that was signed by operators and used to verify the aggregated signature
  * @param signature the G1 signature of the message
  * @param apk the G2 aggregate public key
@@ -339,8 +346,8 @@ struct BN254Certificate {
  * @notice verifies a certificate
  * @param operatorSet the operatorSet that the certificate is for
  * @param cert a certificate
- * @return signedStakes amount of stake that signed the certificate for each stake
- * type. Each index corresponds to a stake type in the `totalWeights` array in the `BN254OperatorSetInfo`. 
+ * @return signedStakes amount of stake that signed the certificate for each stake type. Each index
+ *         corresponds to a stake type in the `totalWeights` array in the `BN254OperatorSetInfo`.
  */
 function verifyCertificate(
     OperatorSet memory operatorSet,
@@ -376,9 +383,9 @@ Verifies a BN254 certificate by checking the aggregated signature against the op
  * @param operatorSet the operatorSet that the certificate is for
  * @param cert a certificate
  * @param totalStakeNominalThresholds the nominal amount of stake that
- * the signed stake of the certificate should meet. Each index corresponds to 
- * a stake type in the `totalWeights` array in the `BN254OperatorSetInfo`. 
- * @return whether or not certificate is valid and meets thresholds
+ * the signed stake of the certificate should meet. Each index corresponds to
+ * a stake type in the `totalWeights` array in the `BN254OperatorSetInfo`.
+ * @return whether or not certificate is valid and meets nominal thresholds
  */
 function verifyCertificateNominal(
     OperatorSet memory operatorSet,
@@ -408,11 +415,11 @@ Verifies that a certificate meets specified nominal (absolute) stake thresholds
  * @notice verifies a certificate and makes sure that the signed stakes meet
  * provided portions of the total stake on the AVS
  * @param operatorSet the operatorSet that the certificate is for
- * @param cert a certificate
+ * @param cert the certificate
  * @param totalStakeProportionThresholds the proportion, in BPS,of total stake that
- * the signed stake of the certificate should meet. Each index corresponds to 
- * a stake type in the `totalWeights` array in the `BN254OperatorSetInfo`. 
- * @return whether or not certificate is valid and meets thresholds
+ * the signed stake of the certificate should meet. Each index corresponds to
+ * a stake type in the `totalWeights` array in the `BN254OperatorSetInfo`.
+ * @return whether or not certificate is valid and meets proportion thresholds
  */
 function verifyCertificateProportion(
     OperatorSet memory operatorSet,
@@ -440,10 +447,12 @@ Verifies that a certificate meets specified proportion thresholds as a percentag
 
 ```solidity
 /**
- * @notice A witness for an operator
+ * @notice A witness for an operator, used to identify the non-signers for a given certificate
  * @param operatorIndex the index of the nonsigner in the `BN254OperatorInfo` tree
- * @param operatorInfoProof merkle proofs of the nonsigner at the index. Empty if operator is in cache.
- * @param operatorInfo the `BN254OperatorInfo` for the operator. Empty if operator is in cache
+ * @param operatorInfoProofs merkle proof of the nonsigner at the index. Empty if the non-signing operator is already stored from a previous verification
+ * @param operatorInfo the `BN254OperatorInfo` for the operator. Empty if the non-signing operator is already stored from a previous verification
+ * @dev Non-signing operators are stored in the `BN254CertificateVerifier` upon the first successful certificate verification. This is done to avoid
+ *      the need for resupplying proofs of non-signing operators for each certificate verification.
  */
 struct BN254OperatorInfoWitness {
     uint32 operatorIndex;
@@ -464,3 +473,29 @@ flowchart TB
     N1 --> L2[[Leaf 2<br/>BN254OperatorInfo #2]]
     N1 --> L3[[Leaf 3<br/>BN254OperatorInfo #3]]
 ```
+
+---
+
+## Appendix
+
+### Staleness Period
+
+For the below examples, let's assume that the operator table is updated on Day 1
+
+#### Eg. 1: Normal Functioning
+Assume the the staleness period is 10 days and the `referenceTimestamp` of a certificate is Day 1. 
+
+1. Day 1: Table Updated
+2. Day 9: Certificate passes
+3. Day 10: Certificate passes
+4. Day 11: Certificate verification *fails*
+
+#### Eg. 2: Low staleness period
+The operator table is updated every 10 days. The staleness period is 5 days. The `referenceTimestamp` of a certificate is Day 1. 
+
+1. Day 1: Table updated
+2. Day 2: Certificate passes
+3. Day 6: Certifiacte verification *fails*
+4. Day 7: A certificate is re-generated. However, this will stale fail as the `referenceTimestamp` would still be day 1 given that was the latest table update
+
+Note that we cannot re-generate a certificate on Day 7. This is why we recommend that the `stalenessPeriod` is greater than or equal to the update cadence of operator tables. 

docs/multichain/destination/OperatorTableUpdater.md

@@ -31,7 +31,7 @@ The following values are set upon initialization:
     * `maxStalenessPeriod`: 0. Set to zero to confirm `globalTableRoots` without updating the `generator` operatorSet. See [`CertificateVerifier`](./CertificateVerifier.md#overview) for specifics`OperatorTableUpdater`. It is the same across all destination chains, even for destination chains that are supported after the initial deployment. 
     * `owner`: Unused parameter for `Generator`
 
-
+Operator tables are updated daily on testnet and weekly on mainnet. 
 ---
 
 ## Global Root Confirmation

docs/multichain/source/CrossChainRegistry.md

@@ -21,6 +21,10 @@ The `CrossChainRegistry` manages the registration/deregistration of operatorSets
  * @notice A per-operatorSet configuration struct that is transported from the CrossChainRegistry on L1.
  * @param owner the permissioned owner of the OperatorSet on L2 that can call the CertificateVerifier specific setters
  * @param maxStalenessPeriod the maximum staleness period of the operatorSet
+ * 
+ * @dev A staleness period of 0 allows for certificates to be verified against any timestamp in the past
+ * @dev Staleness periods should not be greater than 0 and less than the update cadence of the `OperatorTables`, since
+ *      certificates would be unable to be validated against. The update cadence is communicated off-chain
  */
 struct OperatorSetConfig {
     address owner;
@@ -150,6 +154,7 @@ Updates the `operatorTableCalculator` contract for a given `operatorSet`. The `o
  * @param config the config to set
  * @dev msg.sender must be UAM permissioned for operatorSet.avs
  * @dev operatorSet must have an active generation reservation
+ * @dev The max staleness period is NOT checkpointed and is applied globally regardless of the reference timestamp of a certificate
  */
 function setOperatorSetConfig(
     OperatorSet calldata operatorSet,