feat(dkg): implement dkg/disk and dkg/share

AGENTS.md

@@ -145,6 +145,43 @@ Rules:
   - Prefer copying doc comments from Go and adapting to Rust conventions (avoid “Type is a …”).
   - Avoid leaving TODOs in merged code. If a short-lived internal note is necessary, use `// TODO:` and remove before PR merge.
 
+## Generalized Parameter Types
+
+Prefer generic parameters over concrete types when a function only needs the behavior of a trait. This mirrors the standard library's own conventions and makes functions callable with a wider range of inputs without extra allocations.
+
+| Instead of | Prefer | Accepts |
+| --- | --- | --- |
+| `&str` | `impl AsRef<str>` | `&str`, `String`, `&String`, … |
+| `&Path` | `impl AsRef<Path>` | `&str`, `String`, `PathBuf`, `&Path`, … |
+| `&[u8]` | `impl AsRef<[u8]>` | `&[u8]`, `Vec<u8>`, arrays, … |
+| `&Vec<T>` | `impl AsRef<[T]>` | `Vec<T>`, slices, arrays, … |
+| `String` (owned, read-only) | `impl Into<String>` | `&str`, `String`, … |
+
+Examples:
+
+```rust
+// accepts &str, String, PathBuf, &Path, …
+fn read_file(path: impl AsRef<std::path::Path>) -> std::io::Result<String> {
+    std::fs::read_to_string(path.as_ref())
+}
+
+// accepts &str, String, &String, …
+fn print_message(msg: impl AsRef<str>) {
+    println!(“{}”, msg.as_ref());
+}
+
+// accepts &[u8], Vec<u8>, arrays, …
+fn hash_bytes(data: impl AsRef<[u8]>) -> [u8; 32] {
+    sha256(data.as_ref())
+}
+```
+
+Rules:
+
+- Call `.as_ref()` once at the top of the function and bind it to a local variable when the value is used in multiple places.
+- Do not use `impl AsRef<T>` if the function immediately converts to an owned type anyway — use `impl Into<T>` (or just accept the owned type) in that case.
+- Applies to public and private functions alike; the gain is ergonomics, not just API surface.
+
 ## Testing
 
 - Translate Go tests to Rust where applicable; keep similar test names for cross-reference.

crates/cluster/Cargo.toml

@@ -19,7 +19,7 @@ pluto-core.workspace = true
 pluto-crypto.workspace = true
 pluto-eth2api.workspace = true
 thiserror.workspace = true
-rand_core.workspace = true
+rand.workspace = true
 libp2p.workspace = true
 pluto-p2p.workspace = true
 pluto-eth2util.workspace = true
@@ -28,16 +28,21 @@ pluto-k1util.workspace = true
 k256.workspace = true
 tokio.workspace = true
 reqwest = { workspace = true, features = ["json"] }
+# Workaround to use test code from different crate.
+# See: https://github.com/NethermindEth/pluto/pull/285
+pluto-testutil = { workspace = true, optional = true }
 
 [build-dependencies]
 prost-build.workspace = true
 
 [dev-dependencies]
 test-case.workspace = true
 pluto-testutil.workspace = true
-rand.workspace = true
 tempfile.workspace = true
 wiremock.workspace = true
 
 [lints]
 workspace = true
+
+[features]
+test-cluster = []

crates/cluster/src/definition.rs

@@ -933,10 +933,12 @@ pub struct DefinitionV1x2or3 {
     /// Config hash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// Definition hash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 
@@ -1047,10 +1049,12 @@ pub struct DefinitionV1x4 {
     /// Config hash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// Definition hash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 
@@ -1159,10 +1163,12 @@ pub struct DefinitionV1x5to7 {
     /// Config hash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// Definition hash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 
@@ -1260,10 +1266,12 @@ pub struct DefinitionV1x8 {
     /// ConfigHash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// DefinitionHash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 
@@ -1365,10 +1373,12 @@ pub struct DefinitionV1x9 {
     /// ConfigHash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// DefinitionHash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 
@@ -1477,10 +1487,12 @@ pub struct DefinitionV1x10 {
     /// Config hash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// Definition hash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "EthHex")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 

crates/cluster/src/helpers.rs

@@ -65,8 +65,10 @@ pub async fn fetch_definition(
 /// Creates a new directory for validator keys.
 /// If the directory "validator_keys" exists, it checks if the directory is
 /// empty.
-pub async fn create_validator_keys_dir(parent_dir: &std::path::Path) -> std::io::Result<PathBuf> {
-    let vk_dir = parent_dir.join("validator_keys");
+pub async fn create_validator_keys_dir(
+    parent_dir: impl AsRef<std::path::Path>,
+) -> std::io::Result<PathBuf> {
+    let vk_dir = parent_dir.as_ref().join("validator_keys");
 
     if let Err(e) = tokio::fs::create_dir(&vk_dir).await {
         if e.kind() != std::io::ErrorKind::AlreadyExists {

crates/cluster/src/lib.rs

@@ -4,32 +4,39 @@
 //! This crate handles the formation, management, and coordination of validator
 //! clusters in the Charon network.
 
-/// Cluster definition management and coordination.
+/// `Definition` type representing the intended cluster configuration
+/// (operators, validators, fork version) with EIP-712 hashing and verification.
 pub mod definition;
-/// Cluster deposit management and coordination.
+/// `DepositData` type for activating validators.
 pub mod deposit;
-/// Cluster distributed validator management and coordination.
+/// `DistValidator` type representing a distributed validator with its group
+/// public key, per-node public shares, and deposit data.
 pub mod distvalidator;
-/// Cluster EIP-712 signatures management and coordination.
+/// EIP-712 typed data construction and signing for cluster definition config
+/// hashes and operator ENR signatures.
 pub mod eip712sigs;
-/// Cluster helpers management and coordination.
+/// General helper utilities.
 pub mod helpers;
-/// Cluster lock management and coordination.
+/// `Lock` type representing the finalized cluster configuration, including
+/// distributed validators and node signatures.
 pub mod lock;
-/// Manifest
+/// Cluster manifest types, loading, mutation, and materialization.
 pub mod manifest;
-/// Manifest protocol buffers.
+/// Generated protobuf types for the cluster manifest (v1).
 pub mod manifestpb;
-/// Cluster operator management and coordination.
+/// `Operator` type representing a charon node operator with Ethereum address,
+/// ENR, and config/ENR signatures.
 pub mod operator;
-/// Cluster registration management and coordination.
+/// `BuilderRegistration` and `Registration` types for pre-generated signed
+/// validator registrations sent to the builder network.
 pub mod registration;
-/// Cluster SSZ management and coordination.
+/// SSZ serialization for various cluster types.
 pub mod ssz;
-/// Cluster SSZ hashing management and coordination.
+/// Core SSZ utilities.
 pub mod ssz_hasher;
-/// Cluster test cluster management and coordination.
-#[cfg(test)]
+/// Factory for constructing deterministic or random cluster locks for use in
+/// tests.
+#[cfg(any(test, feature = "test-cluster"))]
 pub mod test_cluster;
-/// Cluster version management and coordination.
+/// Supported cluster definition version constants and feature-flag helpers.
 pub mod version;

crates/cluster/src/test_cluster.rs

@@ -1,3 +1,5 @@
+#![allow(clippy::unwrap_used, reason = "test code")]
+
 use crate::{definition, distvalidator, helpers, lock, operator, registration, version};
 use chrono::{TimeZone, Utc};
 use pluto_crypto::tbls::Tbls;

crates/dkg/Cargo.toml

@@ -9,9 +9,25 @@ publish.workspace = true
 [dependencies]
 prost.workspace = true
 prost-types.workspace = true
+pluto-cluster.workspace = true
+pluto-crypto.workspace = true
+pluto-eth1wrap.workspace = true
+pluto-eth2util.workspace = true
+hex.workspace = true
+rand.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+tokio.workspace = true
+tracing.workspace = true
+url.workspace = true
 
 [build-dependencies]
 pluto-build-proto.workspace = true
 
+[dev-dependencies]
+pluto-cluster = { workspace = true, features = ["test-cluster"] }
+tempfile.workspace = true
+
 [lints]
 workspace = true