Introduce trait StakeTableScheme and migrate previous implementations

[alxiong]

Resolve #65.
(a follow-up of, and should be merged after, #64)

Major changes include:

• introduce trait StakeTableScheme
• rename SnapshotVersion from pending/frozen/active to head/epoch_start/last_epoch_start for better readability
• most old APIs are migrated under the trait impl, notable additions include: len(), contains_key(), deregister() (left unimplemented and future work); notable changes include: lookup() now returns (Amount, Proof) instead of just MerkleProof as before.
• replace struct StakeTableEntry<V> with generic API from trait StakeTableScheme
  • implement an Iterator for PersistentMerkleNode, implement IntoIterator for StakeTableScheme
  • Make current stake_table implementation generic over K instead of fixated on EncodedPublicKey

[alxiong]

Q: should we make struct StakeTable generic over <K, V>?

currently our stake table implementation uses concrete types (EncodedPublicKey, U256) for its key-value, where the encoded pk just contains the seralized bytes (of whatever actual pk being used)

This decision forces me to write:

/// Public parameters for [`BitVectorQC`].
/// generic over the stake table type `ST` and aggregated signature type `A`
#[derive(Serialize, Deserialize, PartialEq, Debug)]
pub struct QCParams<A: AggregateableSignatureSchemes, ST: StakeTableScheme> {
    // pub stake_entries: Vec<StakeTableEntry<V>>,
    pub stake_table: Arc<ST>,
    pub threshold: U256,
    pub agg_sig_pp: A::PublicParameter,
}

impl<A, ST> QuorumCertificate<A> for BitVectorQC<A, ST>
where
    A: AggregateableSignatureSchemes + Serialize + for<'a> Deserialize<'a>,
    ST: StakeTableScheme<Amount = U256>,
    ST::Key: From<A::VerificationKey>,
    A::VerificationKey: From<ST::Key>,

instead of

impl<A, ST> QuorumCertificate<A> for BitVectorQC<A, ST>
where
    A: AggregateableSignatureSchemes + Serialize + for<'a> Deserialize<'a>,
    ST: StakeTableScheme<Key = A::VerificationKey>,
    ST::Amount: Add<Output = Self>,

Apart from having cleaner trait bound, the main advantages of the latter (if we have generic struct StakeTable<K, V>) is avoiding lots of internal serde.
For example, insideQC::check(), we will be calling A::multi_sig_verify on the aggregated signature scheme which accepts list of public keys of type &[A::VerificationKey], which may not be of the same type as &[ST::Key] (which currently is concretized as struct EncodedPublicKey).
To deal with this, we would have to implement two-way conversion (thus the bound A::VerificationKey: From<ST::Key>), and this (arguably unnecessary) serde is being done each time people run QC::check().

In short, I would propose that we make turn our Stake Table generic struct StakeTable<K, V>, wdyt? @mrain
(if agreed, I would work on a separate PR that merge into this PR)

[mrain]

@alxiong Good idea on generalizing K. However doing this for V may introduce complicacy for other interfaces, e.g.

    pub fn update(
        &mut self,
        key: &EncodedPublicKey,
        delta: U256,
        negative: bool,
    ) -> Result<U256, StakeTableError>;

[alxiong]

right, all I need is to add trait bound related to Add, AddAssign, Sub, SubAssign to V, then the code should mostly work, correct?

[mrain]

Yep. Also that's the only place with all troubles.

[alxiong]

Here's a problem:

previously, we had this VerKey -> ark_bn254::Fq conversion:

hotshot-primitives/src/stake_table/mod.rs

Line 240 in e9bda5c

.map(|i| EncodedPublicKey(to_bytes!(&FieldType::from(i)).unwrap()))

but this code has the wrong assumption that bls_on_bn254::VerKey can be serialized into 32 bytes without any loss/truncation.

VerKey is of type G2Affine which has x, y coordinate where each is a quadratic extension field, thus at least even with compressed serialized bytes, we need 64 bytes.
And lossy conversion would result in failed deserialization back into the correct VerKey.

---

at the current stage of this PR, I introduce this IntoField<FieldType> trait bound, as a reflection of the old code (thus the wrong assumption that it can be converted to a FieldType w/o loss),

And I think I might be better refactoring it to IntoFields<[FieldType; const N]> and then change:

hotshot-primitives/src/stake_table/utils.rs

Lines 94 to 100 in e9bda5c

	let input = [
	FieldType::from(0),
	<FieldType as CanonicalDeserialize>::deserialize_compressed(&key.0[..])
	.unwrap(),
	u256_to_field(value),
	];
	let init = Digest::evaluate(input).map_err(|_| StakeTableError::RescueError)?[0];

and

hotshot-primitives/src/stake_table/config.rs

Lines 13 to 14 in e9bda5c

	/// Hash algorithm used in Merkle tree, using a RATE-3 rescue
	pub(crate) type Digest = FixedLengthRescueCRHF<FieldType, TREE_BRANCH, 1>;

into maybe type Digest<N> = FixedLengthRescueCRHF<FieldType, TREE_BRANCH + N-1, 1>,
I'm not sure if I could make the compiler happy, but this seems a necessary change.

---

There's another almost hacky way to avoid deserialization error. that is to define and manually implement serialization of struct StakeTable as the its commitment, meaning I don't serialize the whole tree (thus avoiding serializing the Key type), instead I only serialize the commitment.

^^ the problem with this approach is given a serialized QCparam, you can't just directly reconstruct the stake table. instead you can only check for consistency against another stake table you download from other means. <-- which also seem a little strange.

@mrain let's chat and see which one do we prefer and what to do next.

[alxiong]

After discussion with @mrain, we decide to go with: IntoFields<[FieldType; 2]>.
While we acknowledge that this looks hardcoded, we prefer it over using VariableLengthRescueCRHF which will automatically append an 1, and ends up costing 2 rescue hash instead of 1 for the Digest::evaluate().

[mrain]

Generally LGTM, with some minor comments