feat(iota-genesis-builder): Add configurable delegator to genesis CLI

crates/iota-config/src/genesis.rs

@@ -516,12 +516,7 @@ impl TokenDistributionSchedule {
     /// Helper to read a TokenDistributionSchedule from a csv file.
     ///
     /// The file is encoded such that the final entry in the CSV file is used to
-    /// denote the allocation to the stake subsidy fund. It must be in the
-    /// following format:
-    /// `0x0000000000000000000000000000000000000000000000000000000000000000,
-    /// <pre>minted supply</pre>,`
-    ///
-    /// All entries in a token distribution schedule must add up to 10B Iota.
+    /// denote the allocation to the stake subsidy fund.
     pub fn from_csv<R: std::io::Read>(reader: R) -> Result<Self> {
         let mut reader = csv::Reader::from_reader(reader);
         let mut allocations: Vec<TokenAllocation> =
@@ -568,7 +563,17 @@ impl TokenDistributionSchedule {
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "kebab-case")]
 pub struct TokenAllocation {
+    /// Indicates the address that owns the tokens. It means that this
+    /// `TokenAllocation` can serve to stake some funds to the
+    /// `staked_with_validator` during genesis, but it's the `recipient_address`
+    /// which will receive the associated StakedIota (or TimelockedStakedIota)
+    /// object.
     pub recipient_address: IotaAddress,
+    /// Indicates an amount of nanos that is:
+    /// - minted for the `recipient_address` and staked to a validator, only in
+    ///   the case `staked_with_validator` is Some
+    /// - minted for the `recipient_address` and transferred that address,
+    ///   otherwise.
     pub amount_nanos: u64,
 
     /// Indicates if this allocation should be staked at genesis and with which
@@ -628,3 +633,110 @@ impl TokenDistributionScheduleBuilder {
         schedule
     }
 }
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub struct ValidatorAllocation {
+    /// The validator address receiving the stake and/or gas payment
+    pub address: IotaAddress,
+    // The amount of nanos to stake to the validator
+    pub amount_nanos_to_stake: u64,
+    /// The amount of nanos to transfer as gas payment to the validator
+    pub amount_nanos_to_pay_gas: u64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub struct DelegatorDistribution {
+    /// The address from which take the nanos for staking/gas
+    pub delegator: IotaAddress,
+    /// The allocation to a validator receiving a stake and/or a gas payment
+    pub validator_allocation: ValidatorAllocation,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub struct DelegatorMap {
+    // Maps a delegator address to a tuple containing the address of a validator (1nd element of
+    // the tuple) that will receive an amount of nanos to stake (2nd element) and an amount as gas
+    // payment (3rd element).
+    pub allocations: HashMap<IotaAddress, Vec<ValidatorAllocation>>,
+}
+
+impl DelegatorMap {
+    pub fn new_for_validators_with_default_allocation<I: IntoIterator<Item = IotaAddress>>(
+        validators: I,
+        delegator: IotaAddress,
+    ) -> Self {
+        let default_allocation = iota_types::governance::MIN_VALIDATOR_JOINING_STAKE_NANOS;
+
+        let allocations = validators.into_iter().fold(
+            HashMap::new(),
+            |mut allocations: HashMap<IotaAddress, Vec<_>>, address| {
+                allocations
+                    .entry(delegator)
+                    .or_default()
+                    .push(ValidatorAllocation {
+                        address,
+                        amount_nanos_to_stake: default_allocation,
+                        amount_nanos_to_pay_gas: 0,
+                    });
+                allocations
+            },
+        );
+
+        Self { allocations }
+    }
+
+    /// Helper to read a DelegatorMap from a csv file.
+    ///
+    /// The file is encoded such that the final entry in the CSV file is used to
+    /// denote the allocation coming from a delegator. It must be in the
+    /// following format:
+    /// `delegator,validator,amount-nanos-to-stake,amount-nanos-to-pay-gas
+    /// <delegator1-address>,<validator-1-address>,2000000000000000,5000000000
+    /// <delegator1-address>,<validator-2-address>,3000000000000000,5000000000
+    /// <delegator2-address>,<validator-3-address>,4500000000000000,5000000000`
+    pub fn from_csv<R: std::io::Read>(reader: R) -> Result<Self> {
+        let mut reader = csv::Reader::from_reader(reader);
+
+        let allocations = reader
+            .deserialize::<DelegatorDistribution>()
+            .collect::<Result<Vec<_>, _>>()?
+            .into_iter()
+            .fold(
+                HashMap::new(),
+                |mut allocations: HashMap<IotaAddress, Vec<_>>, allocation| {
+                    allocations
+                        .entry(allocation.delegator)
+                        .or_default()
+                        .push(allocation.validator_allocation);
+                    allocations
+                },
+            );
+
+        Ok(Self { allocations })
+    }
+
+    /// Helper to write a DelegatorMap into a csv file.
+    ///
+    /// It writes in the following format:
+    /// `delegator,validator,amount-nanos-to-stake,amount-nanos-to-pay-gas
+    /// <delegator1-address>,<validator-1-address>,2000000000000000,5000000000
+    /// <delegator1-address>,<validator-2-address>,3000000000000000,5000000000
+    /// <delegator2-address>,<validator-3-address>,4500000000000000,5000000000`
+    pub fn to_csv<W: std::io::Write>(&self, writer: W) -> Result<()> {
+        let mut writer = csv::Writer::from_writer(writer);
+
+        for (&delegator, validators_allocations) in &self.allocations {
+            for &validator_allocation in validators_allocations {
+                writer.serialize(DelegatorDistribution {
+                    delegator,
+                    validator_allocation,
+                })?;
+            }
+        }
+
+        Ok(())
+    }
+}

crates/iota-genesis-builder/examples/snapshot_only_test_outputs.rs

@@ -7,12 +7,9 @@
 use std::{fs::File, path::Path};
 
 use clap::{Parser, Subcommand};
-use iota_genesis_builder::{
-    IF_STARDUST_ADDRESS,
-    stardust::{
-        parse::HornetSnapshotParser,
-        test_outputs::{add_snapshot_test_outputs, to_nanos},
-    },
+use iota_genesis_builder::stardust::{
+    parse::HornetSnapshotParser,
+    test_outputs::{add_snapshot_test_outputs, to_nanos},
 };
 use iota_sdk::types::block::address::Address;
 use iota_types::{gas_coin::STARDUST_TOTAL_SUPPLY_IOTA, stardust::coin_type::CoinType};
@@ -32,6 +29,8 @@ enum Snapshot {
     Iota {
         #[clap(long, help = "Path to the Iota Hornet full-snapshot file")]
         snapshot_path: String,
+        #[clap(long, help = "Specify the delegator address")]
+        delegator: String,
     },
 }
 
@@ -62,8 +61,11 @@ fn parse_snapshot<const VERIFY: bool>(
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
     let cli = Cli::parse();
-    let (current_path, coin_type) = match cli.snapshot {
-        Snapshot::Iota { snapshot_path } => (snapshot_path, CoinType::Iota),
+    let (current_path, delegator, coin_type) = match cli.snapshot {
+        Snapshot::Iota {
+            snapshot_path,
+            delegator,
+        } => (snapshot_path, delegator, CoinType::Iota),
     };
     let mut new_path = String::from("test-");
     // prepend "test-" before the file name
@@ -80,7 +82,7 @@ async fn main() -> anyhow::Result<()> {
     let (randomness_seed, delegator_address) = match coin_type {
         CoinType::Iota => {
             // IOTA coin type values
-            (0, IF_STARDUST_ADDRESS)
+            (0, delegator)
         }
     };