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

README.md

@@ -5,18 +5,18 @@
 
 ## How it works
 
-The primary innovation of Ore is to offer mining rewards that are non-exclusive. In traditional proof-of-work systems such as Bitcoin, mining rewards are exclusive. That is, only one miner can win every ~10 minutes, and that miner takes home all the tokens for the round. This has had the longterm effect of starving out casual miners who are simply unable to keep up in the arms race against much larger and well-resourced professional mining firms.
+The primary innovation of Ore is to offer non-exclusive mining rewards. This means if one miner wins rewards, it doesn't prevent another miner from also winning. In traditional proof-of-work systems such as Bitcoin, mining rewards are exclusive. That is, only one Bitcoin miner can win every ~10 minutes, and that miner takes home all the tokens for the round. This has had the longterm effect of starving out casual miners who are simply unable to keep up in the arms race against much larger and well-resourced professional mining firms.
 
-The primary reason Bitcoin is designed this way is that its proof-of-work system serves two roles. It's responsible not only for distributing tokens, but also for coordinating network consensus. This makes sense as the tokens are intended to be rewards for those who dedicate resources to securing the Bitcoin network. However due starvation problems outlined above, it has the unintended consequence of excluding major portions of the global population (>99%) from ever being able to mine. This ultimately limits the number of people who can reasonably acquire the token, and thus contributes to further consolidating the supply. Ore takes a different approach.
+The primary reason Bitcoin is designed this way is that its proof-of-work system serves two roles. It's responsible not only for distributing tokens, but also for coordinating network consensus. This makes sense as the tokens are intended to be a reward for those who dedicate resources to securing the Bitcoin network. However due starvation problems outlined above, it has had the unintended consequence of excluding major portions of the global population (>99%) from ever being able to mine. This ultimately limits the number of people who can reasonably acquire the token, and thus contributes to further consolidating the supply. Ore takes a different approach.
 
-Ore builds upon the consensus layer provided by Solana and uses it to reimagine proof-of-work purely as a token distribution mechanism. So rather than setting up every miner in a winner-take-all competition against one another, Ore gives each miner their own individual computational challenge. As long as a miner provides a valid solution to their personal challenge, the protocol guarantees they will earn a piece of the supply. Since no miner can be censored from the network and valid solutions are non-exclusive, starvation is avoided.
+Ore builds upon the consensus layer provided by Solana and uses it to reimagine proof-of-work purely as a token distribution mechanism. Rather than setting up every miner in a winner-take-all competition against one another, Ore gives each miner their own individual computational challenge. As long as a miner provides a valid solution to their personal challenge, the protocol guarantees they will earn a piece of the supply. Since no miner can be censored from the network and valid solutions are non-exclusive, starvation is avoided.
 
 
 ## Supply
 
-Ore provides strong protection and guarantees against runaway supply inflation. The supply growth rate is bounded strictly to a range of 0 ≤ R ≤ 2 ORE / min. In other words, linear. The reward rate – amount paid out to miners per valid hash – is dynamically recalculated every epoch (60 seconds) to maintain a target average supply growth rate of 1 ORE / min. This effectively means if global hashpower dedicated to mining Ore is increasing, the reward rate paid out per hash will decrease, and vice versa. 
+Ore provides strong guarantees and protection against runaway supply inflation. The supply growth rate is strictly bounded to a range of `0 ≤ R ≤ 2 ORE/min`. In other words, linear. The reward rate – amount paid out to miners per valid hash – is dynamically adjusted every 60 seconds to maintain a target average supply growth rate of `1 ORE/min`. This effectively means if the global hashpower dedicated to Ore mining increases, the reward rate paid out per hash will decrease, and vice versa. 
 
-A linear supply growth was chosen for its simplicity and straightforward predictability, a quality that can only be guaranteed by cryptocurrency. Ore aims to strike a balance between the unpredictable runaway inflation of fiat currencies on one hand and the feudal deflationary systems of alternative cryptocurrencies on the other. Ore holders simultaneously have incentive to loan and spend while also being protected against longterm exponential inflation.
+A linear supply growth was chosen for its simplicity and straightforward predictability. Ore aims to strike a balance between the unpredictable runaway inflation of fiat currencies on one hand and the feudal deflationary supply schedules of alternative cryptocurrencies on the other. Ore holders are simultaneously incentivized to loan and spend while also being protected against longterm exponential inflation.
 
 
 ## Program
@@ -28,9 +28,9 @@ A linear supply growth was chosen for its simplicity and straightforward predict
 
 ## Instructions
 - [`Initialize`](src/processor/initialize.rs) – Initializes the Ore program, creating the bus, mint, and treasury accounts.
-- [`Reset`](src/processor/reset.rs) – Resets the program for a new epoch, resetting the bus accounts and topping up the treasury.
+- [`Reset`](src/processor/reset.rs) – Resets the program for a new epoch.
 - [`Register`](src/processor/register.rs) – Creates a new proof account for a prospective miner.
-- [`Mine`](src/processor/mine.rs) – Verifies hashes provided by miners and issues claimable rewards.
+- [`Mine`](src/processor/mine.rs) – Verifies a hash provided by a miner and issues claimable rewards.
 - [`Claim`](src/processor/claim.rs) – Distributes claimable rewards as tokens from the treasury to a miner.
 - [`UpdateAdmin`](src/processor/update_admin.rs) – Updates the admin authority.
 - [`UpdateDifficulty`](src/processor/update_difficulty.rs) - Updates the hashing difficulty.
@@ -38,5 +38,5 @@ A linear supply growth was chosen for its simplicity and straightforward predict
 ## State
  - [`Bus`](src/state/bus.rs) - An account (8 total) which tracks and limits the amount mined rewards each epoch.
  - [`Proof`](src/state/proof.rs) - An account (1 per miner) which tracks a miner's current hash, claimable rewards, and lifetime stats.
- - [`Treasury`](src/state/treasury.rs) – A singleton account which manages program-wide variables and is the mint authority over the Ore token. 
+ - [`Treasury`](src/state/treasury.rs) – A singleton account which manages program-wide variables and authorities.
 

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>],