Respond to RFCs in PR #866

nucypher/blockchain/economics.py

@@ -29,9 +29,11 @@ LOG2 = Decimal(log(2))
 
 class TokenEconomics:
     """
-    Calculate parameters to use in token and escrow deployment
+    Calculate parameters to use in token and escrow blockchain deployments
     from high-level human-understandable parameters.
 
+    --------------------------
+
     Formula for staking in one period:
     (totalSupply - currentSupply) * (lockedValue / totalLockedValue) * (k1 + allLockedPeriods) / k2
 
@@ -45,6 +47,14 @@ class TokenEconomics:
 
     kappa = (small_stake_multiplier + (1 - small_stake_multiplier) * min(T, T1) / T1)
     where allLockedPeriods == min(T, T1)
+
+    --------------------------
+
+    Academic Reference:
+
+    NuCypher: Mining & Staking Economics - Michael Egorov, MacLane Wilkison, NuCypher
+    <https://github.com/nucypher/mining-paper/blob/master/mining-paper.pdf>
+
     """
 
     # Decimal
@@ -96,7 +106,7 @@ class TokenEconomics:
 
             initial_supply = Decimal(initial_supply)
 
-            # ERC20 Token parameter
+            # ERC20 Token parameter (See Equation 4 in Mining paper)
             total_supply = initial_supply * (1 + initial_inflation * halving_delay / LOG2)
 
             # Remaining / Reward Supply - Escrow Parameter

nucypher/blockchain/eth/actors.py

@@ -396,7 +396,7 @@ class Miner(NucypherTokenActor):
         """
         High-level staking looping call initialization, this function aims
         to be safely called at any time - For example, it is okay to call
-        this function multiple time within the same period.
+        this function multiple times within the same period.
         """
         # Get the last stake end period of all stakes
         terminal_period = max(stake.end_period for stake in self.stakes)
@@ -483,7 +483,7 @@ class Miner(NucypherTokenActor):
     def locked_tokens(self, periods: int = 0) -> NU:
         """Returns the amount of tokens this miner has locked for a given duration in periods."""
         raw_value = self.miner_agent.get_locked_tokens(miner_address=self.checksum_public_address, periods=periods)
-        value = NU(raw_value, 'NU')
+        value = NU.from_nunits(raw_value)
         return value
 
     @property
@@ -627,7 +627,7 @@ class Miner(NucypherTokenActor):
         return self.__read_stakes()
 
     @property
-    def stakes(self) -> Dict[int, Stake]:
+    def stakes(self) -> List[Stake]:
         """Return all cached stake instances from the blockchain."""
         return self.__stakes
 

nucypher/blockchain/eth/agents.py

@@ -478,7 +478,7 @@ class MiningAdjudicatorAgent(EthereumContractAgent):
                        cfrag_signature_by_miner: bytes,
                        requester_public_key: bytes,
                        miner_public_key: bytes,
-                       miner_piblc_key_signature: bytes,
+                       miner_public_key_signature: bytes,
                        precomputed_data: bytes):
         """
 

nucypher/blockchain/eth/deployers.py

@@ -170,7 +170,7 @@ class NucypherTokenDeployer(ContractDeployer):
 
         _contract, deployment_txhash = self.blockchain.interface.deploy_contract(
                                        self.contract_name,
-                                       self.__economics.erc20_total_supply)  # TODO: Is this the correct supply value (total vs inital economic parameter)?
+                                       self.__economics.erc20_total_supply)
 
         self._contract = _contract
         return {'txhash': deployment_txhash}
@@ -228,12 +228,12 @@ class MinerEscrowDeployer(ContractDeployer):
 
     def deploy(self) -> dict:
         """
-        Deploy and publish the NuCypher Token contract
+        Deploy and publish the MinersEscrow contract
         to the blockchain network specified in self.blockchain.network.
 
         Deployment can only ever be executed exactly once!
 
-        Emits the folowing blockchain network transactions:
+        Emits the following blockchain network transactions:
             - MinerEscrow contract deployment
             - MinerEscrow dispatcher deployment
             - Transfer reward tokens origin -> MinerEscrow contract

nucypher/blockchain/eth/interfaces.py

@@ -289,7 +289,7 @@ class BlockchainInterface:
                        factory=Contract) -> Contract:
         """
         Used for upgradeable contracts; Returns a new contract object assembled
-        with it's own address but the abi of the other.
+        with its own address but the abi of the other.
         """
 
         # Wrap the contract

nucypher/blockchain/eth/token.py

@@ -190,10 +190,7 @@ class Stake:
     @property
     def is_expired(self) -> bool:
         current_period = self.miner_agent.get_current_period()
-        if current_period >= self.end_period:
-            return True
-        else:
-            return False
+        return bool(current_period >= self.end_period)
 
     @property
     def is_active(self) -> bool:
@@ -307,7 +304,7 @@ class Stake:
 
         # Read from blockchain
         stake_info = self.miner_agent.get_substake_info(miner_address=self.owner_address,
-                                                        stake_index=self.index)  # < -- Read form blockchain
+                                                        stake_index=self.index)  # < -- Read from blockchain
 
         first_period, last_period, locked_value = stake_info
         if not self.start_period == first_period:

tests/blockchain/eth/entities/agents/test_user_escrow_agent.py

@@ -29,7 +29,7 @@ TEST_DURATION = 60*60
 TEST_ALLOCATION_REGISTRY = InMemoryAllocationRegistry()
 
 
-@pytest.fixture
+@pytest.fixture(scope='module')
 def allocation_value(token_economics):
     allocation = token_economics.minimum_allowed_locked * 10
     return allocation

tests/cli/ursula/test_blockchain_ursula.py

@@ -29,19 +29,19 @@ from nucypher.utilities.sandbox.ursula import start_pytest_ursula_services
 from web3 import Web3
 
 
-@pytest.fixture
+@pytest.fixture(scope='module')
 def stake_value(token_economics):
     value = NU(token_economics.minimum_allowed_locked * 2, 'NuNit')
     return value
 
 
-@pytest.fixture
+@pytest.fixture(scope='module')
 def policy_rate():
     rate = Web3.toWei(21, 'gwei')
     return rate
 
 
-@pytest.fixture
+@pytest.fixture(scope='module')
 def policy_value(token_economics, policy_rate):
     value = policy_rate * token_economics.minimum_locked_periods  # * len(ursula)
     return value