Merge branch 'master' of https://github.com/HardhatChad/ore

src/processor/mine.rs

@@ -98,6 +98,8 @@ pub fn process_mine<'a, 'info>(
     Ok(())
 }
 
+/// Validates the provided hash, ensursing it is equal to SHA3(current_hash, singer, nonce).
+/// Fails if the provided hash is valid but does not satisfy the required difficulty.
 pub(crate) fn validate_hash(
     current_hash: KeccakHash,
     hash: KeccakHash,

src/processor/update_admin.rs

@@ -11,6 +11,20 @@ use crate::{instruction::UpdateAdminArgs, loaders::*, state::Treasury, utils::Ac
 /// Safety requirements:
 /// - Can only succeed if the signer is the current program admin.
 /// - Can only succeed if the provided treasury is valid.
+///
+/// Discussion:
+/// - The admin authority has one lever of power: the ability to adjust the global 
+///   mining difficulty. If the difficulty is too easy, miners will find hashes very quickly
+///   and the bottleneck for mining will shift from local compute to Solana bandwidth. In essence,
+///   if the Ore token has value and difficulty is low, mining becomes an incentivized stress
+///   test for the Solana network. 
+/// - At the same time, if difficulty is too hard, miners will have to wait a very long period
+///   of time between finding valid hashes. This will bias rewards to well-resourced miners 
+///   with large compute operations. Keeping a low difficulty ensures casual miners can 
+///   consistently earn rewards and undercuts some of the advantage of larger players.
+/// - Ultimately admin authority should be delegated to a governance mechanism – either 
+///   democratic or futarchic – to ensure difficulty is kept at a value that represents the 
+///   values and interests of the whole ecosystem.
 pub fn process_update_admin<'a, 'info>(
     _program_id: &Pubkey,
     accounts: &'a [AccountInfo<'info>],

src/processor/update_difficulty.rs

@@ -13,6 +13,19 @@ use crate::{
 /// Safety requirements:
 /// - Can only succeed if the signer is the current program admin.
 /// - Can only succeed if the provided treasury is valid.
+///
+/// Discussion:
+/// - Ore subdivides into 1 billion indivisible atomic units. Therefore if global hashpower
+///   were to increase to the point where >1B valid hashes were submitted to the protocol for
+///   validation per epoch, the Ore inflation rate could be pushed above the 1 ORE / min target.
+/// - The strict limits on bus reward counters guarantee inflation can never exceed 2 ORE / min, 
+///   but it is the responsibility of the admin to adjust mining difficulty if needed to maintain
+///   the 1 ORE / min target average.
+/// - It is worth noting that Solana today processes well below 1 million real TPS or 
+///   (60 * 1,000,000) = 60,000,000 transactions per minute. Even if every transaction on Solana
+///   were a mine operation, this would still be two orders of magnitude below the boundary 
+///   condition where Ore inflation targets would be challenged. So in practice, Solana is likely 
+///   to reach its network saturation point long before Ore ever hits its theoretical limits. 
 pub fn process_update_difficulty<'a, 'info>(
     _program_id: &Pubkey,
     accounts: &'a [AccountInfo<'info>],