update yaml format, add readme

genesis/README.md

@@ -0,0 +1,75 @@
+# Genesis
+
+## There are a few ways to bake validator accounts and staked into genesis:
+### 1) Through bootstrap validator cli args:
+```
+--bootstrap-validator <IDENTITY_PUBKEY> <VOTE_PUBKEY> <STAKE_PUBKEY>
+--bootstrap-validator-lamports <LAMPORTS>
+--bootstrap-validator-stake-lamports <LAMPORTS>
+```
+Note: you can pass in `--bootstrap-validator ...` multiple times but the lamports associated with `--bootstrap-validator-lamports` and `--bootstrap-validator-stake-lamports` will apply to all `--bootstrap-validator` arguments.
+For example:
+```
+cargo run --bin solana-genesis --
+    --bootstrap-validator <IDENTITY_PUBKEY_0> <VOTE_PUBKEY_0> <STAKE_PUBKEY_0>
+    --bootstrap-validator <IDENTITY_PUBKEY_1> <VOTE_PUBKEY_1> <STAKE_PUBKEY_1>
+    ...
+    --bootstrap-validator <IDENTITY_PUBKEY_N> <VOTE_PUBKEY_N> <STAKE_PUBKEY_N>
+    --bootstrap-validator-stake-lamports 10000000000
+    --bootstrap-validator 100000000000
+```
+All validator accounts will receive the same number of stake and account lamports
+
+### 2) Through the primordial accounts file flag:
+```
+--primordial-accounts-file <PATH_TO_PRIMORDIAL_ACCOUNTS_YAML>
+```
+The primordial accounts file has the following format:
+```
+---
+<IDENTITY_PUBKEY_0>:
+  balance: <LAMPORTS_0>
+  owner: <OWNER_PUBKEY_0>
+  data: <BAS64_ENCODED_DATA_0>
+  executable: false
+<IDENTITY_PUBKEY_1>:
+  balance: <LAMPORTS_1>
+  owner: <OWNER_PUBKEY_1>
+  data: <BAS64_ENCODED_DATA_1>
+  executable: true
+...
+<IDENTITY_PUBKEY_N>:
+  balance: <LAMPORTS_N>
+  owner: <OWNER_PUBKEY_N>
+  data: <BAS64_ENCODED_DATA_N>
+  executable: true
+```
+The `data` portion of the yaml file holds BASE64 encoded data about the account. `data` can include both vote and stake account information.
+
+### 3) Through the validator accounts file flag:
+The validator accounts file is an alternative to the primordial accounts file. The main goal with the validator accounts file is to:
+- Bake validator stakes into genesis with different stake and acount distributions
+- Remove the overhead of forcing the user to serialize and deserialize validator stake and vote account state if they want varying stake distributions - as required by (2)
+```
+--validator-accounts-file <PATH_TO_VALIDATOR_ACCOUNTS_YAML>
+```
+The validator accounts file has the following format:
+```
+validator_accounts:
+- balance_lamports: <balance-lamports-0>
+  stake_lamports: <stake-lamports-0>
+  identity_account: <identity-pubkey-0>
+  vote_account: <vote-pubkey-0>
+  stake_account: <stake-pubkey-0>
+- balance_lamports: <balance-lamports-1>
+  stake_lamports: <stake-lamports-1>
+  identity_account: <identity-pubkey-1>
+  vote_account: <vote-pubkey-1>
+  stake_account: <stake-pubkey-1>
+...
+- balance_lamports: <balance-lamports-N>
+  stake_lamports: <stake-lamports-N>
+  identity_account: <identity-pubkey-N>
+  vote_account: <vote-pubkey-N>
+  stake_account: <stake-pubkey-N>
+```

genesis/src/lib.rs

@@ -15,6 +15,11 @@ pub struct Base64Account {
     pub executable: bool,
 }
 
+#[derive(Serialize, Deserialize, Debug)]
+pub struct ValidatorAccountsFile {
+    pub validator_accounts: Vec<Base64ValidatorAccount>,
+}
+
 /// A validator account where the data is encoded as a Base64 string.
 /// Includes the vote account and stake account.
 #[derive(Serialize, Deserialize, Debug)]

genesis/src/main.rs

@@ -18,6 +18,7 @@ use {
     solana_entry::poh::compute_hashes_per_tick,
     solana_genesis::{
         genesis_accounts::add_genesis_accounts, Base64Account, Base64ValidatorAccount,
+        ValidatorAccountsFile,
     },
     solana_ledger::{blockstore::create_new_ledger, blockstore_options::LedgerColumnOptions},
     solana_rpc_client::rpc_client::RpcClient,
@@ -123,8 +124,9 @@ pub fn load_validator_accounts(
 ) -> io::Result<()> {
     let accounts_file = File::open(file)?;
     let validator_genesis_accounts: Vec<Base64ValidatorAccount> =
-        serde_yaml::from_reader(accounts_file)
-            .map_err(|err| io::Error::new(io::ErrorKind::Other, format!("{err:?}")))?;
+        serde_yaml::from_reader::<_, ValidatorAccountsFile>(accounts_file)
+            .map_err(|err| io::Error::new(io::ErrorKind::Other, format!("{err:?}")))?
+            .validator_accounts;
 
     for account_details in validator_genesis_accounts {
         let pubkeys = [
@@ -549,7 +551,7 @@ fn main() -> Result<(), Box<dyn error::Error>> {
                 .value_name("FILENAME")
                 .takes_value(true)
                 .multiple(true)
-                .help("The location of identity, vote, and stake pubkeys and balances for validator accounts"),
+                .help("The location of identity, vote, and stake pubkeys and balances for validator accounts to bake into genesis")
         )
         .arg(
             Arg::with_name("cluster_type")
@@ -1284,7 +1286,7 @@ mod tests {
         // write accounts to file
         let path = Path::new("test_append_validator_accounts_to_genesis.yml");
         let mut file = File::create(path).unwrap();
-        file.write_all(b"---\n").unwrap();
+        file.write_all(b"validator_accounts:\n").unwrap();
         file.write_all(serialized.as_bytes()).unwrap();
 
         load_validator_accounts(