comments

src/lib.rs

@@ -14,8 +14,6 @@ use solana_program::{
     program_error::ProgramError, pubkey::Pubkey,
 };
 
-// TODO Is downgrade necessary?
-
 declare_id!("mineRHF5r6S7HyD9SppBfVMXMavDkJsxwGesEvxZr2A");
 
 #[cfg(not(feature = "no-entrypoint"))]

src/processor/claim.rs

@@ -8,14 +8,14 @@ use crate::{
     MINT_ADDRESS, TREASURY, TREASURY_BUMP,
 };
 
-/// Claim distributes owed token rewards from the treasury to the miner. Its responsibilies include:
-/// 1. Decrement the miner's claimable rewards counter.
+/// Claim distributes Ore from the treasury to a miner. Its responsibilies include:
+/// 1. Decrement the miner's claimable balance.
 /// 2. Transfer tokens from the treasury to the miner.
 ///
 /// Safety requirements:
-/// - Claim is a permissionless instruction and can be called by any miner.
+/// - Claim is a permissionless instruction and can be called by any user.
 /// - Can only succeed if the claimed amount is less than or equal to the miner's claimable rewards.
-/// - The provided beneficiary token account, treasury, treasury token account, and token program must be valid.
+/// - The provided beneficiary, token account, treasury, treasury token account, and token program must be valid.
 pub fn process_claim<'a, 'info>(
     _program_id: &Pubkey,
     accounts: &'a [AccountInfo<'info>],

src/processor/deregister.rs

@@ -5,6 +5,15 @@ use solana_program::{
 
 use crate::{loaders::*, state::Proof, utils::AccountDeserialize, PROOF};
 
+/// Deregister closes a proof account and returns the rent to the owner. Its responsibilities include:
+/// 1. Realloc proof account size to 0.
+/// 2. Transfer lamports to the owner.
+/// 3. Reassign the account owner back to the system program.
+///
+/// Safety requirements:
+/// - Deregister is a permissionless instruction and can be invoked by any singer.
+/// - Can only succeed if the provided proof acount PDA is valid (associated with the signer).
+/// - The provided system program must be valid.
 pub fn process_deregister<'a, 'info>(
     _program_id: &Pubkey,
     accounts: &'a [AccountInfo<'info>],

src/processor/pause.rs

@@ -5,6 +5,16 @@ use solana_program::{
 
 use crate::{instruction::PauseArgs, loaders::*, state::Config, utils::AccountDeserialize};
 
+/// Pause updates the program's pause flag. Its responsibilities include:
+/// 1. Update the pause flag.
+///
+/// Safety requirements:
+/// - Can only succeed if the signer is the program admin.
+/// - Can only succeed if the provided config is valid.
+///
+/// Discussion:
+/// - This should only be used to address critical contract risks and force migration to a new
+///   verison (hardfork).
 pub fn process_pause<'a, 'info>(
     _program_id: &Pubkey,
     accounts: &'a [AccountInfo<'info>],

src/processor/register.rs

@@ -21,7 +21,7 @@ use crate::{
 /// Safety requirements:
 /// - Register is a permissionless instruction and can be invoked by any singer.
 /// - Can only succeed if the provided proof acount PDA is valid (associated with the signer).
-/// - Can only succeed once per signer.
+/// - Can only succeed if the user does not already have a proof account.
 /// - The provided system program must be valid.
 pub fn process_register<'a, 'info>(
     _program_id: &Pubkey,

src/processor/stake.rs

@@ -8,6 +8,14 @@ use crate::{
     TREASURY_ADDRESS,
 };
 
+/// Stake deposits Ore into a miner's proof account to earn multiplier. Its responsibilies include:
+/// 1. Transfer tokens from the miner to the treasury account.
+/// 2. Increment the miner's claimable balance.
+///
+/// Safety requirements:
+/// - Stake is a permissionless instruction and can be called by any user.
+/// - Can only succeed if the amount is less than or equal to the miner's transferable tokens.
+/// - The provided beneficiary, proof, sender, treasury token account, and token program must be valid.
 pub fn process_stake<'a, 'info>(
     _program_id: &Pubkey,
     accounts: &'a [AccountInfo<'info>],

src/processor/update_tolerance.rs

@@ -8,6 +8,14 @@ use crate::{
     utils::AccountDeserialize, ONE_MINUTE,
 };
 
+/// UpdateTolerance updates the program's tolerance settings. Its responsibilities include:
+/// 1. Update the liveness tolerance.
+/// 2. Update the spam tolerance.
+///
+/// Safety requirements:
+/// - Can only succeed if the signer is the program admin.
+/// - Can only succeed if the provided config is valid.
+/// - Can only succeed if the tolerances pass sanity tests.
 pub fn process_update_tolerance<'a, 'info>(
     _program_id: &Pubkey,
     accounts: &'a [AccountInfo<'info>],

src/processor/upgrade.rs

@@ -7,6 +7,13 @@ use crate::{
     instruction::StakeArgs, loaders::*, MINT_ADDRESS, MINT_V1_ADDRESS, TREASURY, TREASURY_BUMP,
 };
 
+/// Upgrade allows a user to migrate a v1 token to a v2 token one-for-one. Its responsibilies include:
+/// 1. Burns the v1 tokens.
+/// 2. Mints an equivalent number of v2 tokens to the user.
+///
+/// Safety requirements:
+/// - Upgrade is a permissionless instruction and can be called by any user.
+/// - The provided beneficiary, mint, mint v1, sender, and token program must be valid.
 pub fn process_upgrade<'a, 'info>(
     _program_id: &Pubkey,
     accounts: &'a [AccountInfo<'info>],