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

* Initial `dkg/disk` module

- Add `load_definition`

* Add `write_to_keymanager`

- Requires `shares`

* Add `write_keys_to_disk`

- Adjust some pending TODOs.

* Add `write_lock`

* Add `check_clear_data_dir`

* Add `check_writes`

* Test `clear_data_dir_does_not_exist`

* Test `clear_data_dir_is_file`

* Test `clear_data_dir_contains_validator_keys_file`

* Test `clear_data_dir_contains_validator_keys_dir`

* Test `clear_data_dir_contains_validator_keys_dir`

* Test `clear_data_dir_contains_cluster_lock`

* Test `clear_data_dir_contains_deposit_data`

* Test `clear_data_dir_missing_private_key`

* Test `clear_data_dir_contains_private_key`

- Fix required file name

* Formatting

* Fix clippy lints

* Test `load_definition_file_does_not_exist`

* Test `load_definition_invalid_file`

- Fix `load_definition_file_does_not_exist` error

* Add `Generalized Parameter Types` rule

* Replace `todo!` with actual calls

* Make `test_cluster` non test-only

- Workaround to be used by dkg

* Update module docs

* Test `load_definition_valid`

* Use defaults when key is missing

* Test `load_definition_invalid_definition_no_verify`

* Test `load_definition_invalid_definition_verify`

* Add `ShareMsg`

- Impl `From<&Share> for ShareMsg`

* Update `Cargo.lock`

* Allow unwrap in test code

* Adjust visibility and docs

- Make everything public
- Add docs to all exposed symbols

* Fix clippy lints

* Use `File::create` instead of `File::open`

- We need to create the file first.

* Persist readonly permissions

* Resolve TODOs in module docs

* Prefer `AsRef<Path>`

* Fix typo

* Reduce visibility of utility

* Use `PathBuf` for the data_dir

* Simplify error handling

* Add `Debug` and `Clone` to `Share` and `ShareMsg`

* Fix typo & formatting

* feat: make test-cluster be feature based

* feat: update dkg Cargo.toml to split testing and release versions of cluster

* Remove inlined definitions

* Use default argument

* Include payload in error messages

* Inline function

* Use `Zeroizing`

* Add error unused payload lint

---------

Co-authored-by: Bohdan Ohorodnii <35969035+varex83@users.noreply.github.com>

Author: emlautarom1

AGENTS.md

@@ -132,6 +132,7 @@ pub type Result<T> = std::result::Result<T, ModuleError>;
 Rules:
 
 - `errors.New("msg")` → enum variant with `#[error("msg")]` (match strings exactly).
+- Every field/payload in an error variant **must** appear in its `#[error("...")]` format string. If a field is not surfaced in the error message, either include it or remove it from the variant. Dead payload (captured but never displayed) is not allowed.
 - `errors.Wrap(err, "...")` → `#[from]` / `#[source]` where appropriate.
 - Always propagate with `?`; avoid silent `filter_map(|x| x.ok())` patterns in production code.
 
@@ -145,6 +146,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.

Cargo.lock

@@ -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
@@ -29,16 +29,21 @@ pluto-ssz.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 = ["dep:pluto-testutil"]

crates/cluster/Cargo.toml

@@ -934,10 +934,12 @@ pub struct DefinitionV1x2or3 {
     /// Config hash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// Definition hash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 
@@ -1048,10 +1050,12 @@ pub struct DefinitionV1x4 {
     /// Config hash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// Definition hash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 
@@ -1160,10 +1164,12 @@ pub struct DefinitionV1x5to7 {
     /// Config hash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// Definition hash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 
@@ -1261,10 +1267,12 @@ pub struct DefinitionV1x8 {
     /// ConfigHash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// DefinitionHash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 
@@ -1366,10 +1374,12 @@ pub struct DefinitionV1x9 {
     /// ConfigHash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// DefinitionHash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 
@@ -1478,10 +1488,12 @@ pub struct DefinitionV1x10 {
     /// Config hash uniquely identifies a cluster definition excluding operator
     /// ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub config_hash: Vec<u8>,
     /// Definition hash uniquely identifies a cluster definition including
     /// operator ENRs and signatures.
     #[serde_as(as = "Hex0x")]
+    #[serde(default)]
     pub definition_hash: Vec<u8>,
 }
 

crates/cluster/src/definition.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/helpers.rs

@@ -4,30 +4,37 @@
 //! 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 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/lib.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/cluster/src/test_cluster.rs

@@ -9,9 +9,26 @@ 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
+zeroize.workspace = true
 
 [build-dependencies]
 pluto-build-proto.workspace = true
 
+[dev-dependencies]
+pluto-cluster = { workspace = true, features = ["test-cluster"] }
+tempfile.workspace = true
+
 [lints]
 workspace = true