From 184431b35ee8a127aae96effedcd0201b77fdb35 Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Thu, 22 Aug 2019 16:22:26 -0500 Subject: [PATCH 01/11] Adding some updated comments --- .../access_control/AuthorizedAddresses.sol | 20 +-- .../contracts/base/Authorizable.sol | 6 +- .../contracts/event/EventEmitter.sol | 14 +- .../contracts/external/OrderGateway.sol | 38 ++--- .../contracts/lib/KosuToken.sol | 55 +++--- .../contracts/treasury/Treasury.sol | 161 ++++++++++-------- .../contracts/voting/Voting.sol | 10 +- 7 files changed, 155 insertions(+), 149 deletions(-) diff --git a/packages/kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol b/packages/kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol index f56c8187..c956c819 100644 --- a/packages/kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol +++ b/packages/kosu-system-contracts/contracts/access_control/AuthorizedAddresses.sol @@ -4,22 +4,22 @@ import "openzeppelin-solidity/contracts/ownership/Ownable.sol"; /** @title AuthorizedAddresses @author Freydal - @dev Common registry of system contract addresses authrorized to access internal methods. + @dev Common registry of system contract addresses authorized to access internal methods. */ contract AuthorizedAddresses is Ownable { // Mapping storing address permissions mapping(address => bool) private authorizedAddresses; - /** @dev Constructor initializes with the creator permission set to true. - @notice Constructor initializes with the creator permission set to true. + /** @dev Initializes contract with the creators permissions set to true. + @notice Initializes contract with the creators permissions set to true. */ constructor() Ownable() public { authorizedAddresses[owner()] = true; } /** @dev Authorizes the address by setting the mapping value to true. - @notice Authorizes the address by setting the mapping value to true + @notice Authorizes the address by setting the mapping value to true. @param a Address to authorize */ function authorizeAddress(address a) public { @@ -27,8 +27,8 @@ contract AuthorizedAddresses is Ownable { authorizedAddresses[a] = true; } - /** @dev Unauthorizes the address by setting the mapping value to false. - @notice Unauthorizes the address by setting the mapping value to false + /** @dev Disables the address previous authorization by setting the mapping value to false. + @notice Disables the address previous authorization by setting the mapping value to false @param a Address to unauthorize */ function unauthorizeAddress(address a) public { @@ -36,10 +36,10 @@ contract AuthorizedAddresses is Ownable { authorizedAddresses[a] = false; } - /** @dev Verify if address is authorized by reading contract mapping - @notice Verify if address is authorized by reading contract mapping - @param a Address to get authorized value. - @return True if the address is authorized, false otherwise. + /** @dev Verify address authorization. + @notice Verify address authorization. + @param a Address to authorize. + @return Address authorization */ function isAddressAuthorized(address a) public view returns (bool) { return authorizedAddresses[a]; diff --git a/packages/kosu-system-contracts/contracts/base/Authorizable.sol b/packages/kosu-system-contracts/contracts/base/Authorizable.sol index f02e2a17..5c5c69c4 100644 --- a/packages/kosu-system-contracts/contracts/base/Authorizable.sol +++ b/packages/kosu-system-contracts/contracts/base/Authorizable.sol @@ -4,7 +4,7 @@ import "../access_control/AuthorizedAddresses.sol"; /** @title Authorizable @author Freydal - @dev Implements a modifier to restrict function access based on the state of the AuthorizedAddresses registry. + @dev Implements a modifier to verify authorization with the AuthorizedAddresses contract */ contract Authorizable { @@ -19,8 +19,8 @@ contract Authorizable { authorizedAddress = AuthorizedAddresses(authorizedAddressesAddress); } - /** @dev Ensures msg.sender is from an address enabled for system level access. - @notice Ensures msg.sender is from an address enabled for system level access. + /** @dev Ensures msg.sender is authorized within the AuthorizedAddresses contract + @notice Ensures msg.sender is authorized within the AuthorizedAddresses contract */ modifier isAuthorized() { require(authorizedAddress.isAddressAuthorized(msg.sender)); diff --git a/packages/kosu-system-contracts/contracts/event/EventEmitter.sol b/packages/kosu-system-contracts/contracts/event/EventEmitter.sol index ae85519d..412cae00 100644 --- a/packages/kosu-system-contracts/contracts/event/EventEmitter.sol +++ b/packages/kosu-system-contracts/contracts/event/EventEmitter.sol @@ -4,11 +4,11 @@ import "../base/Authorizable.sol"; /** @title EventEmitter @author Freydal - @dev A shared contract for all Kosu system contracts to trigger event logs through. + @dev A central event emitting contract supporting the Kosu contract system. */ contract EventEmitter is Authorizable { - /// Generic event which can be decoded in Javascript via internal library. + // Generic Kosu Event event KosuEvent(string eventType, bytes32[] data, string stringData); /** @dev Event emitter instantiated with Authorizable. @@ -18,11 +18,11 @@ contract EventEmitter is Authorizable { constructor(address auth) Authorizable(auth) public { } - /** @dev Emit generic events which can have decoding exposed though javascript library. - @notice Emit generic events which can have decoding exposed though javascript library. - @param eventType String name/type of event - @param data Bytes32 encoded data to be emitted from a centralized location - @param stringData String containing optional additonal information + /** @dev Emits a standard event from the Kosu contract system. The events can be decoded though the javascript library. + @notice Emits a standard event from the Kosu contract system. The events can be decoded though the javascript library. + @param eventType String name/type of event. + @param data Bytes32 encoded data to be emitted. + @param stringData String containing optional additional information. */ function emitEvent(string calldata eventType, bytes32[] calldata data, string calldata stringData) external isAuthorized { emit KosuEvent(eventType, data, stringData); diff --git a/packages/kosu-system-contracts/contracts/external/OrderGateway.sol b/packages/kosu-system-contracts/contracts/external/OrderGateway.sol index a84fa8b5..4f1b8c93 100644 --- a/packages/kosu-system-contracts/contracts/external/OrderGateway.sol +++ b/packages/kosu-system-contracts/contracts/external/OrderGateway.sol @@ -4,50 +4,44 @@ import "@kosu/subcontract-sdk/contracts/SubContract.sol"; /** @title OrderGateway @author Freydal - @dev Access SubContract implementation's methods to participate in trades and check order status. + @dev Serves as a message router for SubContract implementations. Passing SubContract method calls through the gateway allows for a single watch point for incoming participate transactions. */ contract OrderGateway { - /** @dev Creates a new OrderGateway - @notice Creates a new OrderGateway - */ - constructor() public { - } - - /** @dev Calls participate on the provided subContract. - @notice Calls participate on the provided subContract. + /** @dev Forwards function calls of participate to the provided subContract address. + @notice Forwards function calls of participate to the provided subContract address. @param subContract Address of contract implementing the SubContract interface. - @param data Encoded maker values for Order encoded based on the arguments. - @return Boolean representing success of transaction. + @param data Encoded values for Order encoded in accordance to the arguments exposed by the provided subContract. + @return Boolean representing result of transaction. */ function participate(address subContract, bytes memory data) public returns (bool) { return SubContract(subContract).participate(data); } - /** @dev Calls isValid on provided subContract. - @notice Calls isValid on provided subContract. + /** @dev Forwards function calls of isValid to the provided subContract address. + @notice Forwards function calls of isValid to the provided subContract address. @param subContract Address of contract implementing the SubContract interface. - @param data Encoded maker values for Order encoded based on the makerArguments. - @return Boolean representing the validity of makerData. + @param data Encoded values for Order encoded in accordance to the arguments exposed by the provided subContract. + @return Boolean representing the validity of data. */ function isValid(address subContract, bytes memory data) public view returns (bool) { return SubContract(subContract).isValid(data); } - /** @dev Calls amountRemaining on provided subContract. - @notice Calls amountRemaining on provided subContract. + /** @dev Forwards function calls of amountRemaining to the provided subContract address. + @notice Forwards function calls of amountRemaining to the provided subContract address. @param subContract Address of contract implementing the SubContract interface. - @param data Encoded maker values for Order encoded based on the makerArguments. - @return Quantity of available asset for Order encoded in makerData. + @param data Encoded values for Order encoded in accordance to the arguments exposed by the provided subContract. + @return Quantity of available asset for Order encoded in data. */ function amountRemaining(address subContract, bytes memory data) public view returns (uint) { return SubContract(subContract).amountRemaining(data); } - /** @dev Calls arguments on provided subContract. - @notice Calls arguments on provided subContract. + /** @dev Forwards function calls of arguments to the provided subContract address. + @notice Forwards function calls of arguments to the provided subContract address. @param subContract Address of contract implementing the SubContract interface. - @return String encoded JSON representation of subContract maker arguments. + @return JSON string providing expected structure of subContract input data. */ function arguments(address subContract) public view returns (string memory) { return SubContract(subContract).arguments(); diff --git a/packages/kosu-system-contracts/contracts/lib/KosuToken.sol b/packages/kosu-system-contracts/contracts/lib/KosuToken.sol index 614af287..014ee5dc 100644 --- a/packages/kosu-system-contracts/contracts/lib/KosuToken.sol +++ b/packages/kosu-system-contracts/contracts/lib/KosuToken.sol @@ -6,7 +6,7 @@ import "./Formula.sol"; /** @title KosuToken @author Freydal - @dev KosuToken (KOSU) is an implentation of the ERC-20 interface and supporting bonding curve for mints and burns. + @dev KosuToken (KOSU) is an implementation of the ERC-20 interface and supporting bonding curve for mints and burns. */ contract KosuToken is ERC20, Authorizable { @@ -16,21 +16,21 @@ contract KosuToken is ERC20, Authorizable { uint private _weiPaid = 0; uint32 constant private r = 850000; // ppm - /** @dev Deploy a new ERC20 Token - @notice Deploy a new ERC20 Token + /** @dev Initializes KosuToken with the authorizedAddresses shared permission contract to protect functions. + @notice Initializes KosuToken with the authorizedAddresses shared permission contract to protect functions. */ constructor(address _auth) Authorizable(_auth) public { } - /** @dev Fallback payable method to allow contract to accept ether being sent directly to the address. - @notice Fallback payable method to allow contract to accept ether being sent directly to the address. + /** @dev Fallback payable function to allow the contract address to directly accept ether to be forwarded to the bonding function. + @notice Fallback payable function to allow the contract address to directly accept ether to be forwarded to the bonding function. */ function () external payable { bondTokens(0); } - /** @dev Uses the ether paid to calculate and mint tokens. - @notice Uses the ether paid to calculate and mint tokens. + /** @dev Receives ether as a backing currency to be used against the bonding curve to mint tokens. + @notice Receives ether as a backing currency to be used against the bonding curve to mint tokens. @param minPayout The minimum number of tokens to mint otherwise the transaction is reverted. This should prevent a front runner modifying the output. */ function bondTokens(uint minPayout) payable public returns (uint) { @@ -45,9 +45,9 @@ contract KosuToken is ERC20, Authorizable { return tokensToMint; } - /** @dev Burns the input amount of tokens returning the calculated amount of ether. - @notice Burns the input amount of tokens returning the calculated amount of ether. - @param tokensToBurn The number of tokens to burn + /** @dev Burns the input tokens and releases the calculated amount of ether backing the tokens destroyed. + @notice Burns the input tokens and releases the calculated amount of ether backing the tokens destroyed. + @param tokensToBurn The number of the users tokens to burn. */ function releaseTokens(uint tokensToBurn) public { if (tokensToBurn == 0) return; @@ -59,27 +59,27 @@ contract KosuToken is ERC20, Authorizable { _weiPaid = _weiPaid.sub(etherToRelease); } - /** @dev Estimates the number of tokens to generate with the input ether at the current state. - @notice Estimates the number of tokens to generate with the input ether at the current state. - @param input The amount of ether to contribute - @return Number of tokens that would be generated + /** @dev Estimates the number of tokens that would be minted with the input ether at the current ether and token balances. + @notice Estimates the number of tokens that would be minted with the input ether at the current ether and token balances. + @param input The amount of ether to contribute. + @return Number of tokens that would be minted. */ function estimateEtherToToken(uint input) public view returns (uint) { return calculateEtherToToken(input); } - /** @dev Estimates the amount of ether to return with the input number of tokens to burn. - @notice Estimates the amount of ether to return with the input number of tokens to burn. - @param input The number of tokens to burn - @return Amount of ether to receive + /** @dev Estimates the amount of ether to be released with the input number of tokens to burn. + @notice Estimates the amount of ether to be released with the input number of tokens to burn. + @param input The number of tokens to burn. + @return Amount of ether to release. */ function estimateTokenToEther(uint input) public view returns (uint) { return calculateTokenToEther(input); } - /** @dev Burn tokens - @notice Burn tokens - @param amount Number of tokens to destroy + /** @dev Voluntarily burn tokens. + @notice Voluntarily burn tokens. + @param amount Number of tokens to burn. */ function burn(uint amount) public isAuthorized { _burn(msg.sender, amount); @@ -92,17 +92,16 @@ contract KosuToken is ERC20, Authorizable { function mint(uint amount) public isAuthorized { _mint(msg.sender, amount); } - - /** @dev Mint tokens to specified address - @notice Mint tokens to specified address - @param _address Address to receive tokens - @param amount Number of tokens to create. + /** @dev Authorized addresses (mostly contract systems) may manually mint new tokens to desired addresses. + @notice Authorized addresses (mostly contract systems) may manually mint new tokens to desired addresses. + @param _address Address to mint tokens to. + @param amount Number of tokens to mint. */ function mintTo(address _address, uint amount) public isAuthorized { _mint(_address, amount); } - /** @dev Uses a modified BancorFormula to calculate the number of tokens to generate input parameters. + /** @dev Uses a modified BancorFormula to calculate the number of tokens to mint for input ether value. */ function calculateEtherToToken(uint etherValue) internal view returns (uint) { if (_weiPaid == 0 && totalSupply() == 0) { @@ -113,7 +112,7 @@ contract KosuToken is ERC20, Authorizable { } } - /** @dev Uses a modified BancorFormula to calculate the amount of ether to release with input parameters. + /** @dev Uses a modified BancorFormula to calculate the amount of ether to release for input token value. */ function calculateTokenToEther(uint numberOfTokens) internal view returns (uint) { return Formula.calculateSaleReturn(totalSupply(), _weiPaid, r, numberOfTokens); diff --git a/packages/kosu-system-contracts/contracts/treasury/Treasury.sol b/packages/kosu-system-contracts/contracts/treasury/Treasury.sol index 18c30971..51b9406b 100644 --- a/packages/kosu-system-contracts/contracts/treasury/Treasury.sol +++ b/packages/kosu-system-contracts/contracts/treasury/Treasury.sol @@ -4,8 +4,8 @@ import "../base/Authorizable.sol"; import "../lib/KosuToken.sol"; /** @title Treasury - @author Freydal\ - @dev The Kosu Treasury is the central balance management contract with the Kosu system. + @author Freydal + @dev The Kosu Treasury manages KosuToken balances to allow tokens in use within the contract system to be available for voting operations. */ contract Treasury is Authorizable { using SafeMath for uint; @@ -21,42 +21,42 @@ contract Treasury is Authorizable { mapping(address => uint) private systemBalances; mapping(address => PollLock[]) private userVotes; - /** @dev Creates a new Treasury. - @notice Creates a new Treasury. - @param kosuTokenAddress The deployed KosuToken contract address + /** @dev Initializes the treasury with the kosuToken and authorizedAddresses contracts. + @notice Initializes the treasury with the kosuToken and authorizedAddresses contracts. + @param kosuTokenAddress The deployed KosuToken contract address. @param auth AuthorizedAddresses deployed address. */ constructor(address payable kosuTokenAddress, address auth) Authorizable(auth) public { kosuToken = KosuToken(kosuTokenAddress); } - /** @dev Fallback payable function to allow for direct deposit of funds into the Treasury. - @notice Fallback payable function to allow for direct deposit of funds into the Treasury. + /** @dev Fallback payable function to allow ether but be bonded and directly deposit tokens into the Treasury. + @notice Fallback payable function to allow ether but be bonded and directly deposit tokens into the Treasury. */ function () external payable { _bond(msg.sender); } + /** @dev Allows Kosu contracts to bond ether on on the accounts behalf. + @notice Allows Kosu contracts to bond ether on on the accounts behalf. + @param account The address the calling contract is acting on behalf of. + */ + function contractBond(address account) isAuthorized payable public returns (uint) { + return _bond(account); + } + /** @dev Deposits tokens into the treasury. @notice Deposits tokens into the treasury. - @param amount Number of tokens to deposit + @param amount Number of tokens to deposit. */ function deposit(uint amount) public { _deposit(msg.sender, amount); } - /** @dev Allows Kosu contracts to bond for the user. - @notice Allows Kosu contracts to bond for the user. - @param user The user the calling contract is acting on behalf of. - */ - function contractBond(address user) isAuthorized payable public returns (uint) { - return _bond(user); - } - - /** @dev Allows contracts to deposit. - @notice Allows contracts to deposit. - @param account User to deposit tokens for - @param amount Number of tokens to deposit + /** @dev Allows contracts to deposit tokens from an accounts balance. + @notice Allows contracts to deposit tokens from an accounts balance. + @param account Account address the tokens will be deposited from. + @param amount Number of tokens to deposit. */ function contractDeposit(address account, uint amount) isAuthorized public { _deposit(account, amount); @@ -64,25 +64,25 @@ contract Treasury is Authorizable { /** @dev Withdraw tokens from the treasury. @notice Withdraw tokens from the treasury. - @param amount Number of tokens to withdraw + @param amount Number of tokens to withdraw. */ function withdraw(uint amount) public { _withdraw(msg.sender, amount); } - /** @dev Allows contracts to withdraw. - @notice Allows contracts to withdraw. - @param account User to withdraw tokens for - @param amount Number of tokens to withdraw + /** @dev Allows contracts to withdraw tokens back to an account address. + @notice Allows contracts to withdraw tokens back to an account address. + @param account Address to withdraw tokens for. + @param amount Number of tokens to withdraw. */ function contractWithdraw(address account, uint amount) isAuthorized public { _withdraw(account, amount); } - /** @dev Allows contracts to claim tokens. - @notice Allows contracts to claim tokens. - @param account User to claim tokens from - @param amount Number of tokens to claim + /** @dev Allows contracts to claim tokens. Claimed tokens are not available for other system contract and leave the treasury under control of the calling contract. These tokens are still available for voting. + @notice Allows contracts to claim tokens. Claimed tokens are not available for other system contract and leave the treasury under control of the calling contract. These tokens are still available for voting. + @param account Account to claim tokens from. + @param amount Number of tokens to claim. */ function claimTokens(address account, uint amount) isAuthorized public { //Attempt to get more balance if balance is insufficient @@ -95,10 +95,10 @@ contract Treasury is Authorizable { setCurrentBalance(account, getCurrentBalance(account).sub(amount)); } - /** @dev Allows contracts to release tokens. - @notice Allows contracts to release tokens. - @param account User to release tokens to - @param amount Number of tokens to release + /** @dev Allows contracts to release claimed tokens. Allowing them to be used elsewhere by the user again. + @notice Allows contracts to release claimed tokens. Allowing them to be used elsewhere by the user again. + @param account Account to release tokens to. + @param amount Number of tokens to release. */ function releaseTokens(address account, uint amount) isAuthorized public { //Transfer from requesting contract and update balance held in contract @@ -106,10 +106,10 @@ contract Treasury is Authorizable { setCurrentBalance(account, getCurrentBalance(account).add(amount)); } - /** @dev Allows contracts to confiscate tokens the user has lost access to. - @notice Allows contracts to confiscate tokens the user has lost access to. - @param account User to confiscate tokens from - @param amount Number of tokens to confiscate + /** @dev Allows contracts to confiscate tokens the account has lost access to. These previously claimed tokens are no longer owned by the account. + @notice Allows contracts to confiscate tokens the account has lost access to. These previously claimed tokens are no longer owned by the account. + @param account Account to confiscate tokens from. + @param amount Number of tokens to confiscate. */ function confiscate(address account, uint amount) isAuthorized public { //Remove the system balance @@ -118,17 +118,17 @@ contract Treasury is Authorizable { require(getSystemBalance(account) >= getCurrentBalance(account)); } - /** @dev Allows contracts to be rewarded with new tokens. - @notice Allows contracts to be rewarded with new tokens. - @param account User to award tokens to - @param amount Number of tokens to award + /** @dev Allows accounts to be rewarded with tokens. These tokens were previously obtained by the calling contract and are now being redistributed to the provided account. + @notice Allows accounts to be rewarded with tokens. These tokens were previously obtained by the calling contract and are now being redistributed to the provided account. + @param account Account to award tokens to. + @param amount Number of tokens to award. */ function award(address account, uint amount) isAuthorized public { //Transfer from requesting contract and update balance held in contract require(kosuToken.transferFrom(msg.sender, address(this), amount)); //Increase current balance setCurrentBalance(account, getCurrentBalance(account).add(amount)); - //Increase systemBalance these tokens are new to the user + //Increase systemBalance these tokens are new to the account setSystemBalance(account, getSystemBalance(account).add(amount)); } @@ -162,24 +162,23 @@ contract Treasury is Authorizable { _deposit(account, uint(amount)); } } - - /** @dev Allows contracts to burn tokens. - @notice Allows contracts to burn tokens. - @param account User to modify tokens for by burning - @param amount Number of tokens to burn + /** @dev Allows contracts to burn an accounts held tokens. + @notice Allows contracts to burn an accounts held tokens. + @param account Account to burn tokens for. + @param amount Number of tokens to burn. */ function burnFrom(address account, uint amount) isAuthorized public { require(getCurrentBalance(account) >= amount); - kosuToken.burn(amount); + kosuToken.burn(amount); //TODO: Consider event? setCurrentBalance(account, getCurrentBalance(account).sub(amount)); setSystemBalance(account, getSystemBalance(account).sub(amount)); } - /** @dev Allows voting contract to register a poll to ensure tokens aren't removed - @notice Allows voting contract to register a poll to ensure tokens aren't removed - @param account The user voting - @param pollId The poll the user is voting on - @param amount Number of tokens contributed + /** @dev Allows voting contract to register a poll to ensure tokens aren't removed. + @notice Allows voting contract to register a poll to ensure tokens aren't removed. + @param account The account voting. + @param pollId The poll the account is voting on. + @param amount Number of tokens contributed. */ function registerVote(address account, uint pollId, uint amount) isAuthorized public returns (bool) { if(systemBalances[account] < amount) { @@ -191,10 +190,10 @@ contract Treasury is Authorizable { return true; } - /** @dev Allows voting contract to release lock for selected poll - @notice Allows voting contract to release lock for selected poll - @param account The user voting - @param pollId The poll the user is voting on + /** @dev Releases lock on tokens for account after vote is revealed. No longer tracks the revealed poll. + @notice Releases lock on tokens for account after vote is revealed. No longer tracks the revealed poll. + @param account The account voting. + @param pollId The poll the account is voting on. */ function completeVote(address account, uint pollId) isAuthorized public returns (bool) { for(uint i = 0; i < userVotes[account].length; i++) { @@ -218,58 +217,68 @@ contract Treasury is Authorizable { return false; } - /** @dev Reports the balance within the contract system for a user. - @notice Reports the balance within the contract system for a user. - @param account Account to report balance on - @return The number of tokens within the total contract system. + /** @dev Reports the total balance within the entire contract system for an account. + @notice Reports the total balance within the entire contract system for an account. + @param account Account to report balance on. + @return The number of tokens within the entire contract system. */ function systemBalance(address account) public view returns (uint) { return getSystemBalance(account); } - /** @dev Reports the balance held within the contract for a user. - @notice Reports the balance held within the contract for a user. - @param account Account to report balance on - @return Number of tokens this contract holds for the user. + /** @dev Reports the available balance held within the treasury for an account. + @notice Reports the available balance held within the treasury for an account. + @param account Account to report balance on. + @return Number of available tokens the treasury holds for the account. */ function currentBalance(address account) public view returns (uint) { return getCurrentBalance(account); } // INTERNAL - function _bond(address user) internal returns (uint) { + /** @dev Bonds tokens by passing the transaction value to the bonding functions of the KosuToken then provides the added balance to the provided account address. + */ + function _bond(address account) internal returns (uint) { uint initialBalance = kosuToken.balanceOf(address(this)); uint minted = kosuToken.bondTokens.value(msg.value)(0); require(initialBalance+minted == kosuToken.balanceOf(address(this))); - setSystemBalance(user, getSystemBalance(user).add(minted)); - setCurrentBalance(user, getCurrentBalance(user).add(minted)); + setSystemBalance(account, getSystemBalance(account).add(minted)); + setCurrentBalance(account, getCurrentBalance(account).add(minted)); return minted; } + /** @dev Transfers tokens from the account address to the treasury. Increases the available and total system balance by the added amount. + */ function _deposit(address account, uint amount) internal { - //Pulls token from the user and increases both internal ans system balances by the value. + //Pulls token from the account and increases both internal ans system balances by the value. require(kosuToken.transferFrom(account, address(this), amount)); setSystemBalance(account, getSystemBalance(account).add(amount)); setCurrentBalance(account, getCurrentBalance(account).add(amount)); } + /** @dev Transfers tokens held within the treasury to the provided account address and removes the amount from the accounts available and system balances. + */ function _withdraw(address account, uint amount) internal { - //Sends tokens to the user reduce the values of internal and system balances by the value. + //Sends tokens to the account reduce the values of internal and system balances by the value. require(getCurrentBalance(account) >= amount); require(kosuToken.transfer(account, amount)); setSystemBalance(account, getSystemBalance(account).sub(amount)); setCurrentBalance(account, getCurrentBalance(account).sub(amount)); } + /** @dev Reads the account addresses system balance. + */ function getSystemBalance(address account) internal view returns (uint) { - //Reports the systemBalance for the user + //Reports the systemBalance for the account return systemBalances[account]; } + /** @dev Sets the accounts system balance. + */ function setSystemBalance(address account, uint amount) internal { - //Updates the systemBalance for the user + //Updates the systemBalance for the account if (systemBalances[account] > amount) { for(uint i = 0; i < userVotes[account].length; i++) { if(userVotes[account][i].value > amount) { @@ -281,13 +290,17 @@ contract Treasury is Authorizable { systemBalances[account] = amount; } + /** @dev Reads the accounts current balance. + */ function getCurrentBalance(address account) internal view returns (uint) { - //Reports the held balance for the user + //Reports the held balance for the account return currentBalances[account]; } + /** @dev Sets the accounts current balance. + */ function setCurrentBalance(address account, uint amount) internal { - //Updates the held balance for the user + //Updates the held balance for the account currentBalances[account] = amount; } } diff --git a/packages/kosu-system-contracts/contracts/voting/Voting.sol b/packages/kosu-system-contracts/contracts/voting/Voting.sol index 4f457a67..4f41bda8 100644 --- a/packages/kosu-system-contracts/contracts/voting/Voting.sol +++ b/packages/kosu-system-contracts/contracts/voting/Voting.sol @@ -6,7 +6,7 @@ import "openzeppelin-solidity/contracts/math/SafeMath.sol"; /** @title Voting @author Freydal - @dev Voting manages polls and votes on governance matters within the Kosu system. + @dev Voting manages polls and votes on governance matters within the Kosu system. Poll resolution logic will be the responsibility of the contract utilizing this service. */ contract Voting { using SafeMath for uint; @@ -37,10 +37,10 @@ contract Voting { uint voteOption; } - /** @dev Create a new voting engine - @notice Create a new voting engine - @param treasuryAddress Deployed Treasury address - @param _emitterAddress Deployed EventEmitter address + /** @dev Initializes the voting contract with the shared event emitter and treasury contracts. + @notice Initializes the voting contract with the shared event emitter and treasury contracts. + @param treasuryAddress Deployed Treasury address. + @param _emitterAddress Deployed EventEmitter address. */ constructor(address payable treasuryAddress, address _emitterAddress) public { emitter = EventEmitter(_emitterAddress); From dc33946be3eccfa8770c7595098ed66476c688ba Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Thu, 22 Aug 2019 16:22:50 -0500 Subject: [PATCH 02/11] Removing unused function --- .../contracts/treasury/Treasury.sol | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/packages/kosu-system-contracts/contracts/treasury/Treasury.sol b/packages/kosu-system-contracts/contracts/treasury/Treasury.sol index 51b9406b..84066238 100644 --- a/packages/kosu-system-contracts/contracts/treasury/Treasury.sol +++ b/packages/kosu-system-contracts/contracts/treasury/Treasury.sol @@ -149,19 +149,6 @@ contract Treasury is Authorizable { } } - /** @dev Allows contracts to change balance. - @notice Allows contracts to change balance. - @param account User to modify tokens for - @param amount Change to token balance - */ - function adjustBalance(address account, int amount) isAuthorized public { - //Changes balance by the provided amount - if(amount < 0) { - _withdraw(account, uint(amount * -1)); - } else if (amount > 0) { - _deposit(account, uint(amount)); - } - } /** @dev Allows contracts to burn an accounts held tokens. @notice Allows contracts to burn an accounts held tokens. @param account Account to burn tokens for. From 265d89e282ae7f1214d5b61c8820fe3ba48388ea Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Thu, 22 Aug 2019 16:23:08 -0500 Subject: [PATCH 03/11] Refactoring partially used function. --- .../contracts/treasury/Treasury.sol | 21 +++---------------- 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/packages/kosu-system-contracts/contracts/treasury/Treasury.sol b/packages/kosu-system-contracts/contracts/treasury/Treasury.sol index 84066238..895a3119 100644 --- a/packages/kosu-system-contracts/contracts/treasury/Treasury.sol +++ b/packages/kosu-system-contracts/contracts/treasury/Treasury.sol @@ -87,7 +87,9 @@ contract Treasury is Authorizable { function claimTokens(address account, uint amount) isAuthorized public { //Attempt to get more balance if balance is insufficient if(getCurrentBalance(account) < amount) { - updateBalance(account, amount); + uint currentBalance = getCurrentBalance(account); + uint amountToDeposit = amount.sub(currentBalance); + _deposit(account, amountToDeposit); } //Transfer to requesting contract and update balance held in contract @@ -132,23 +134,6 @@ contract Treasury is Authorizable { setSystemBalance(account, getSystemBalance(account).add(amount)); } - /** @dev Allows contracts to set balance. - @notice Allows contracts to set balance. - @param account User to modify tokens for - @param amount Number of tokens to set to current balance - */ - function updateBalance(address account, uint amount) isAuthorized public { - //Adjust balance to requested value. Increase or decrease based on current balance - uint currentBalance = getCurrentBalance(account); - if(currentBalance > amount) { - uint amountToWithdraw = currentBalance.sub(amount); - _withdraw(account, amountToWithdraw); - } else if (currentBalance < amount) { - uint amountToDeposit = amount.sub(currentBalance); - _deposit(account, amountToDeposit); - } - } - /** @dev Allows contracts to burn an accounts held tokens. @notice Allows contracts to burn an accounts held tokens. @param account Account to burn tokens for. From f1bb439d1148dcc7b26ef71aeb1dd14e069d7c0b Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Thu, 22 Aug 2019 16:23:25 -0500 Subject: [PATCH 04/11] Removing no longer needed manual mint function. --- packages/kosu-system-contracts/contracts/lib/KosuToken.sol | 7 ------- 1 file changed, 7 deletions(-) diff --git a/packages/kosu-system-contracts/contracts/lib/KosuToken.sol b/packages/kosu-system-contracts/contracts/lib/KosuToken.sol index 014ee5dc..d4536980 100644 --- a/packages/kosu-system-contracts/contracts/lib/KosuToken.sol +++ b/packages/kosu-system-contracts/contracts/lib/KosuToken.sol @@ -85,13 +85,6 @@ contract KosuToken is ERC20, Authorizable { _burn(msg.sender, amount); } - /** @dev Mint tokens - @notice Mint tokens - @param amount Number of tokens to create - */ - function mint(uint amount) public isAuthorized { - _mint(msg.sender, amount); - } /** @dev Authorized addresses (mostly contract systems) may manually mint new tokens to desired addresses. @notice Authorized addresses (mostly contract systems) may manually mint new tokens to desired addresses. @param _address Address to mint tokens to. From 1957c317b61bc6e7957c81dd9919aa51231a2c6e Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Thu, 22 Aug 2019 16:23:31 -0500 Subject: [PATCH 05/11] Removing tests. --- .../kosu-system-contracts/test/treasury.ts | 128 ------------------ 1 file changed, 128 deletions(-) diff --git a/packages/kosu-system-contracts/test/treasury.ts b/packages/kosu-system-contracts/test/treasury.ts index 99240ff4..35c6687c 100644 --- a/packages/kosu-system-contracts/test/treasury.ts +++ b/packages/kosu-system-contracts/test/treasury.ts @@ -346,134 +346,6 @@ describe("Treasury", async () => { }); }); - describe("updateBalance", () => { - it("should make required changes for balance to end at desired value.", async () => { - await kosuToken.approve.awaitTransactionSuccessAsync(treasury.address, new BigNumber("100000"), { - from: accounts[3], - }); - await treasury.contractDeposit.awaitTransactionSuccessAsync(accounts[3], TestValues.oneHundredWei, { - from: accounts[5], - }); - - await treasury.currentBalance - .callAsync(accounts[3]) - .then(x => x.toString()) - .should.eventually.eq(TestValues.oneHundredWei.toString()); - - await treasury.updateBalance.awaitTransactionSuccessAsync(accounts[3], new BigNumber("73"), { - from: accounts[5], - }); - - await treasury.currentBalance - .callAsync(accounts[3]) - .then(x => x.toString()) - .should.eventually.eq("73"); - - await treasury.updateBalance.awaitTransactionSuccessAsync(accounts[3], new BigNumber("80"), { - from: accounts[5], - }); - - await treasury.currentBalance - .callAsync(accounts[3]) - .then(x => x.toString()) - .should.eventually.eq("80"); - - await kosuToken.balanceOf - .callAsync(accounts[3]) - .then(x => x.toString()) - .should.eventually.eq("20"); - }); - - it("should fail on insufficient token approval.", async () => { - await treasury.updateBalance.awaitTransactionSuccessAsync(accounts[1], new BigNumber("51"), { - from: accounts[5], - }).should.eventually.be.rejected; - }); - - it("should fail on insufficient token balance.", async () => { - await kosuToken.approve.awaitTransactionSuccessAsync(treasury.address, new BigNumber("100000"), { - from: accounts[1], - }); - - await treasury.updateBalance.awaitTransactionSuccessAsync(accounts[1], new BigNumber("101"), { - from: accounts[5], - }).should.eventually.be.rejected; - }); - }); - - describe("adjustBalance", () => { - it("should change the balance by the provided value", async () => { - await kosuToken.approve.awaitTransactionSuccessAsync(treasury.address, new BigNumber("100000"), { - from: accounts[3], - }); - await treasury.contractDeposit.awaitTransactionSuccessAsync(accounts[3], TestValues.oneHundredWei, { - from: accounts[5], - }); - await treasury.currentBalance - .callAsync(accounts[3]) - .then(x => x.toString()) - .should.eventually.eq(TestValues.oneHundredWei.toString()); - - // should handle negative change - await treasury.adjustBalance.awaitTransactionSuccessAsync(accounts[3], new BigNumber("-27"), { - from: accounts[5], - }); - await treasury.currentBalance - .callAsync(accounts[3]) - .then(x => x.toString()) - .should.eventually.eq("73"); - - // should handle 0 - await treasury.adjustBalance.awaitTransactionSuccessAsync(accounts[3], new BigNumber("0"), { - from: accounts[5], - }); - await treasury.currentBalance - .callAsync(accounts[3]) - .then(x => x.toString()) - .should.eventually.eq("73"); - - // should handle positive change - await treasury.adjustBalance.awaitTransactionSuccessAsync(accounts[3], new BigNumber("7"), { - from: accounts[5], - }); - await treasury.currentBalance - .callAsync(accounts[3]) - .then(x => x.toString()) - .should.eventually.eq("80"); - - await kosuToken.balanceOf - .callAsync(accounts[3]) - .then(x => x.toString()) - .should.eventually.eq("20"); - }); - - it("should fail on over withdraw.", async () => { - await treasury.adjustBalance.awaitTransactionSuccessAsync(accounts[3], new BigNumber("-101"), { - from: accounts[5], - }).should.eventually.be.rejected; - }); - - it("should fail on insufficient token approval.", async () => { - await kosuToken.approve.awaitTransactionSuccessAsync(treasury.address, new BigNumber("0"), { - from: accounts[3], - }); - - await treasury.adjustBalance.awaitTransactionSuccessAsync(accounts[3], new BigNumber("1"), { - from: accounts[5], - }).should.eventually.be.rejected; - }); - - it("should fail on insufficient token balance.", async () => { - await kosuToken.approve.awaitTransactionSuccessAsync(treasury.address, new BigNumber("100000"), { - from: accounts[3], - }); - - await treasury.adjustBalance.awaitTransactionSuccessAsync(accounts[3], new BigNumber("101"), { - from: accounts[5], - }).should.eventually.be.rejected; - }); - }); - describe("confiscate", () => { let expectedValue; let from; From 7f452e0e1ab5cc2541ee3256e36a5daa08e20ba6 Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Sun, 25 Aug 2019 23:35:46 -0500 Subject: [PATCH 06/11] Updating additional comments and make a few naming changes. --- .../contracts/poster/PosterRegistry.sol | 92 +++----- .../sub-contracts/ZeroExV2SubContract.sol | 32 +-- .../contracts/validator/ValidatorRegistry.sol | 204 +++++++++--------- .../contracts/voting/Voting.sol | 52 ++--- .../test/poster_registry.ts | 4 +- 5 files changed, 179 insertions(+), 205 deletions(-) diff --git a/packages/kosu-system-contracts/contracts/poster/PosterRegistry.sol b/packages/kosu-system-contracts/contracts/poster/PosterRegistry.sol index 70266157..63e9cfe9 100644 --- a/packages/kosu-system-contracts/contracts/poster/PosterRegistry.sol +++ b/packages/kosu-system-contracts/contracts/poster/PosterRegistry.sol @@ -6,108 +6,84 @@ import "../event/EventEmitter.sol"; /** @title PosterRegistry @author Freydal - @dev Implementation contract for the PosterRegistry, allowing users to bond and un-bond tokens. + @dev The PosterRegistry allows accounts to manage tokens registered rewarding permission to post orders to the kosu network. */ contract PosterRegistry { using SafeMath for uint; mapping(address => uint) private _balances; - uint private _tokensContributed = 0; - KosuToken private _kosuToken; - Treasury private _treasury; + uint public tokensContributed = 0; + KosuToken public kosuToken; + Treasury public treasury; EventEmitter private e; - /** @dev Creates a new PosterRegistry - @notice Creates a new PosterRegistry - @param _treasuryAddress Deployed Treasury contract address - @param _events Deployed Events contract address + /** @dev Initializes the PosterRegistry with the treasury and EventEmitter addresses. + @notice Initializes the PosterRegistry with the treasury and EventEmitter addresses. + @param _treasuryAddress Treasury contract address. + @param _events Deployed Events contract address. */ constructor(address payable _treasuryAddress, address _events) public { - _treasury = Treasury(_treasuryAddress); - _kosuToken = _treasury.kosuToken(); + treasury = Treasury(_treasuryAddress); + kosuToken = treasury.kosuToken(); e = EventEmitter(_events); } - /** @dev Fallback payable function to allow for direct deposit of ether to generate and claim tokens for Posting to Kosu network - @notice Fallback payable function to allow for direct deposit of ether to generate and claim tokens for Posting to Kosu network + /** @dev Fallback payable function allows for direct deposit of ether to generate tokens to be registered for Posting to Kosu network. + @notice Fallback payable function allows for direct deposit of ether to generate tokens to be registered for Posting to Kosu network. */ function () external payable { - uint amount = _treasury.contractBond.value(msg.value)(msg.sender); - _treasury.claimTokens(msg.sender, amount); - _tokensContributed = _tokensContributed.add(amount); + uint amount = treasury.contractBond.value(msg.value)(msg.sender); + treasury.claimTokens(msg.sender, amount); + tokensContributed = tokensContributed.add(amount); _balances[msg.sender] = _balances[msg.sender].add(amount); - emitEvent(msg.sender); + _emitEvent(msg.sender); } - /** @dev The number of tokens that have been contributed to the contract - @notice The number of tokens that have been contributed to the contract - @return Total number of tokens contributed. - */ - function tokensContributed() external view returns (uint) { - return _tokensContributed; - } - - /** @dev The token address. - @notice The token address. - @return KosuToken address. - */ - function token() external view returns (address) { - return address(_kosuToken); - } - - /** @dev The Treasury address. - @notice The Treasury address. - @return Deployed Treasury address. - */ - function treasury() external view returns (address) { - return address(_treasury); - } - - /** @dev Tokens registered for a user. - @notice Tokens registered for a user. - @param a Address to get value for + /** @dev Tokens registered for an account. + @notice Tokens registered for an account. + @param a Address to get value for. @return Tokens registered for address. */ function tokensRegisteredFor(address a) external view returns (uint) { - return tokensFor(a); + return _tokensFor(a); } - /** @dev Register tokens. - @notice Register tokens. - @param amount Number of tokens to register + /** @dev Register tokens for posting permissions. + @notice Register tokens for posting permissions. + @param amount Number of tokens to register. */ function registerTokens(uint amount) external { //Claim tokens from the treasury, delivering them to this contract and accounting for the balances locally. - _treasury.claimTokens(msg.sender, amount); - _tokensContributed = _tokensContributed.add(amount); + treasury.claimTokens(msg.sender, amount); + tokensContributed = tokensContributed.add(amount); _balances[msg.sender] = _balances[msg.sender].add(amount); - emitEvent(msg.sender); + _emitEvent(msg.sender); } /** @dev Release tokens from the registry. @notice Release tokens from the registry. - @param amount Number of tokens to release + @param amount Number of tokens to release. */ function releaseTokens(uint amount) external { //Approve treasury to take tokens from this contract, treasury takes tokens and updates accounting. - _kosuToken.approve(address(_treasury), amount); - _treasury.releaseTokens(msg.sender, amount); + kosuToken.approve(address(treasury), amount); + treasury.releaseTokens(msg.sender, amount); _balances[msg.sender] = _balances[msg.sender].sub(amount); - _tokensContributed = _tokensContributed.sub(amount); - emitEvent(msg.sender); + tokensContributed = tokensContributed.sub(amount); + _emitEvent(msg.sender); } // Internal - function emitEvent(address a) internal { + function _emitEvent(address a) internal { //Emits an event for the address that made a change and the new current balance. bytes32[] memory data = new bytes32[](2); data[0] = bytes32(uint(a)); - data[1] = bytes32(tokensFor(a)); + data[1] = bytes32(_tokensFor(a)); e.emitEvent("PosterRegistryUpdate", data, ""); } - function tokensFor(address a) internal view returns (uint) { + function _tokensFor(address a) internal view returns (uint) { return _balances[a]; } } diff --git a/packages/kosu-system-contracts/contracts/sub-contracts/ZeroExV2SubContract.sol b/packages/kosu-system-contracts/contracts/sub-contracts/ZeroExV2SubContract.sol index 0b2112e7..897d74a6 100644 --- a/packages/kosu-system-contracts/contracts/sub-contracts/ZeroExV2SubContract.sol +++ b/packages/kosu-system-contracts/contracts/sub-contracts/ZeroExV2SubContract.sol @@ -10,7 +10,7 @@ import "@0x/contracts-exchange-libs/contracts/src/LibOrder.sol"; /** @title ZeroExV2SubContract @author Freydal - @dev Implementation of a sub contract that forwards a 0x - kosu order to the zero ex contract system + @dev Implementation of a SubContract that forwards kosu orders with 0x resolution to the 0x exchange contract. */ contract ZeroExV2SubContract is SubContract { using BytesDecoder for bytes; @@ -21,8 +21,8 @@ contract ZeroExV2SubContract is SubContract { string private _arguments; bytes4 private ERC20bytes = bytes4(keccak256("ERC20Token(address)")); - /** @dev Constructor - @notice Constructor + /** @dev Initialize subContract with arguments json 0x Exchange address and the 0x erc20 proxy address. + @notice Initialize subContract with arguments json 0x Exchange address and the 0x erc20 proxy address. @param args The arguments json string. @param exchangeAddress The 0x deployed exchange address. @param proxyAddress The 0x deployed erc20 proxy address. @@ -33,8 +33,8 @@ contract ZeroExV2SubContract is SubContract { _proxy = proxyAddress; } - /** @dev The arguments used to serialize kosu orders. - @notice The arguments used to serialize kosu orders. + /** @dev The arguments used to serialize kosu orders into values to generate the 0x exchange transaction. + @notice The arguments used to serialize kosu orders into values to generate the 0x exchange transaction. @return String encoded JSON object used to encode contract input. */ function arguments() external view returns (string memory) { @@ -47,7 +47,7 @@ contract ZeroExV2SubContract is SubContract { @return Validity of order. */ function isValid(bytes calldata data) external view returns (bool) { - LibOrder.Order memory order = getOrder(data); + LibOrder.Order memory order = _getOrder(data); LibOrder.OrderInfo memory info = _exchange.getOrderInfo(order); return info.orderStatus == uint8(LibOrder.OrderStatus.FILLABLE); } @@ -58,26 +58,26 @@ contract ZeroExV2SubContract is SubContract { @return Tokens remaining to fill. */ function amountRemaining(bytes calldata data) external view returns (uint) { - LibOrder.Order memory order = getOrder(data); + LibOrder.Order memory order = _getOrder(data); LibOrder.OrderInfo memory info = _exchange.getOrderInfo(order); return order.takerAssetAmount - info.orderTakerAssetFilledAmount; } - /** @dev De-serializes ksou order data to 0x order and submits to the 0x exchange. - @notice De-serializes ksou order data to 0x order and submits to the 0x exchange. + /** @dev De-serializes ksou order data to 0x order and submits to the 0x exchange for final resolution. Finalizes by forwarding along any successfully exchanged tokens. + @notice De-serializes ksou order data to 0x order and submits to the 0x exchange for final resolution. Finalizes by forwarding along any successfully exchanged tokens. @param data Kosu order data serialized with arguments. @return Fill success. */ function participate(bytes calldata data) external returns (bool) { - LibOrder.Order memory order = getOrder(data); + LibOrder.Order memory order = _getOrder(data); address taker = data.getAddress(410); uint takeAmount = data.getUint(430); require(taker == tx.origin, "The taker should send the transaction"); // TODO May want to use a different method since 0x started doing something different for gas reasons. - require(getTokenAssetCode(order.makerAssetData.getBytes(0, 4)) == ERC20bytes, "Maker token asset isn't ERC20"); - require(getTokenAssetCode(order.takerAssetData.getBytes(0, 4)) == ERC20bytes, "Taker token asset isn't ERC20"); + require(_getTokenAssetCode(order.makerAssetData.getBytes(0, 4)) == ERC20bytes, "Maker token asset isn't ERC20"); + require(_getTokenAssetCode(order.takerAssetData.getBytes(0, 4)) == ERC20bytes, "Taker token asset isn't ERC20"); IERC20 makerToken = IERC20(order.makerAssetData.getAddress(16)); IERC20 takerToken = IERC20(order.takerAssetData.getAddress(16)); @@ -85,7 +85,7 @@ contract ZeroExV2SubContract is SubContract { takerToken.transferFrom(taker, address(this), takeAmount); takerToken.approve(_proxy, takeAmount); - LibFillResults.FillResults memory fillResult = _exchange.fillOrder(order, takeAmount, getSignature(data)); + LibFillResults.FillResults memory fillResult = _exchange.fillOrder(order, takeAmount, _getSignature(data)); if (fillResult.makerAssetFilledAmount > 0) { require(makerToken.transfer(taker, fillResult.makerAssetFilledAmount), "Didn't successfully forward exchanged tokens. Reverting."); @@ -100,7 +100,7 @@ contract ZeroExV2SubContract is SubContract { /** @dev Internal function to deserialize the Order data from the input bytes. */ - function getOrder(bytes memory data) internal pure returns (LibOrder.Order memory) { + function _getOrder(bytes memory data) internal pure returns (LibOrder.Order memory) { return LibOrder.Order( data.getAddress(0), data.getAddress(20), @@ -119,13 +119,13 @@ contract ZeroExV2SubContract is SubContract { /** @dev Internal function to deserialize the 0x signature from the input bytes. */ - function getSignature(bytes memory data) internal returns (bytes memory) { + function _getSignature(bytes memory data) internal returns (bytes memory) { return data.getBytes(344, 66); // Special 0x signature with a trailing code representing the signature type. } /** @dev Internal function to read the token asset code */ - function getTokenAssetCode(bytes memory data) internal pure returns (bytes4 outBytes4) { + function _getTokenAssetCode(bytes memory data) internal pure returns (bytes4 outBytes4) { if (data.length == 0) { return 0x0; } diff --git a/packages/kosu-system-contracts/contracts/validator/ValidatorRegistry.sol b/packages/kosu-system-contracts/contracts/validator/ValidatorRegistry.sol index 0d9f91bf..8e5695b9 100644 --- a/packages/kosu-system-contracts/contracts/validator/ValidatorRegistry.sol +++ b/packages/kosu-system-contracts/contracts/validator/ValidatorRegistry.sol @@ -78,16 +78,16 @@ contract ValidatorRegistry is Ownable { bytes32 _maxGenerator; mapping(bytes32 => MaxList)_generators; - /** @dev Create a new ValidatorRegistry - @notice Create a new ValidatorRegistry - @param _treasuryAddress Deployed Treasury address - @param _votingAddress Deployed Voting address - @param _events Deployed EventEmitter address - @param _applicationPeriod Initial application period (in blocks) for pending listings - @param _commitPeriod Number of blocks after challenge initiated in which votes can be committed - @param _challengePeriod Number of blocks a challenge lasts before being finalized - @param _exitPeriod Number of blocks exiting listings must wait before claiming stake - @param _rewardPeriod The frequency (in blocks) with which validator rewards may be issued + /** @dev Initializes the ValidatorRegistry with chain based configuration for pacing and deployed addresses. + @notice Initializes the ValidatorRegistry with chain based configuration for pacing and deployed addresses. + @param _treasuryAddress Deployed Treasury address. + @param _votingAddress Deployed Voting address. + @param _events Deployed EventEmitter address. + @param _applicationPeriod Initial application period (in blocks) for pending listings. + @param _commitPeriod Number of blocks after challenge initiated in which votes can be committed. + @param _challengePeriod Number of blocks a challenge lasts before being finalized. + @param _exitPeriod Number of blocks exiting listings must wait before claiming stake. + @param _rewardPeriod The frequency (in blocks) with which validator rewards may be issued. */ constructor(address payable _treasuryAddress, address _votingAddress, address _events, uint _applicationPeriod, uint _commitPeriod, uint _challengePeriod, uint _exitPeriod, uint _rewardPeriod) public Ownable() { treasury = Treasury(_treasuryAddress); @@ -139,7 +139,7 @@ contract ValidatorRegistry is Ownable { /** @dev Expose several listings provided multiple public keys. @notice Expose several listings provided multiple public keys. - @param pubKeys Hex encoded Tendermint public keys to retreive + @param pubKeys Hex encoded Tendermint public keys to retrieve @return The array of listing structures corresponding to the provided keys. */ function getListings(bytes32[] memory pubKeys) public view returns (Listing[] memory) { @@ -164,7 +164,7 @@ contract ValidatorRegistry is Ownable { /** @dev Expose challenge data for a given ID. @notice Expose challenge data for a given ID. - @param challengeId The ID to retreive challenge data for + @param challengeId The ID to retrieve challenge data for @return The challenge indicated by the provided ID. */ function getChallenge(uint challengeId) public view returns (Challenge memory) { @@ -172,9 +172,10 @@ contract ValidatorRegistry is Ownable { } - /** @dev Expose challenge data - @notice Expose challenge data - @param challengeIds challenge id + /** @dev Expose multiple challenges by is + @notice Expose multiple challenges by is + @param challengeIds challenge ids to read + @return Array of requested challenges */ function getChallenges(uint[] memory challengeIds) public view returns (Challenge[] memory) { Challenge[] memory challenges = new Challenge[](challengeIds.length); @@ -186,6 +187,7 @@ contract ValidatorRegistry is Ownable { /** @dev Expose all challenges @notice Expose all challenges + @return Array of all challenges */ function getAllChallenges() public view returns (Challenge[] memory) { uint challengeCount = nextChallenge - 1; @@ -196,12 +198,12 @@ contract ValidatorRegistry is Ownable { return challenges; } - /** @dev Register a listing - @notice Register a listing - @param tendermintPublicKey Hex encoded tendermint public key - @param tokensToStake The number of tokes at stake if the order is challenged - @param rewardRate The rate tokens are minted or destroyed over the active listings reward periods - @param details A string value to represent support for claim (commonly an external link) + /** @dev Register a listing. The listing will require the deposit of the at least the minimum stake balance. The tokens will now be vulnerable to be challenged but are not providing any valdator power. + @notice Register a listing. The listing will require the deposit of the at least the minimum stake balance. The tokens will now be vulnerable to be challenged but are not providing any valdator power. + @param tendermintPublicKey Hex encoded tendermint public key. + @param tokensToStake The number of tokes at stake if the order is challenged. + @param rewardRate The rate tokens are minted or destroyed over the active listings reward periods (ether/rewardPeriod). + @param details A string value to represent support for claim (commonly an external link). */ function registerListing(bytes32 tendermintPublicKey, uint tokensToStake, int rewardRate, string calldata details) external { //tokensToStake must be greater than or equal to _minimumBalance @@ -232,13 +234,13 @@ contract ValidatorRegistry is Ownable { _listingKeys.push(tendermintPublicKey); //Emit event - emitValidatorRegistered(listing.applicationBlock, listing.tendermintPublicKey, listing.owner, rewardRate, listing.details); + _emitValidatorRegistered(listing.applicationBlock, listing.tendermintPublicKey, listing.owner, rewardRate, listing.details); } - /** @dev Challenge a registered listing - @notice Challenge a registered listing - @param tendermintPublicKey Hex encoded tendermint public key - @param details A string value to represent support for claim (commonly an external link) + /** @dev Challenge a registered listing. Stakes a balance of tokens matching the validator being challenged. Creates a poll through the voting contract of tokens holders to determine a winner. + @notice Challenge a registered listing. Stakes a balance of tokens matching the validator being challenged. Creates a poll through the voting contract of tokens holders to determine a winner. + @param tendermintPublicKey Hex encoded tendermint public key. + @param details A string value to represent support for claim (commonly an external link). */ function challengeListing(bytes32 tendermintPublicKey, string memory details) public { //Load listing @@ -248,14 +250,9 @@ contract ValidatorRegistry is Ownable { require(listing.status == Status.PENDING || listing.status == Status.ACCEPTED || listing.status == Status.EXITING); //Ensure earns and burns are up to date return if a touch and remove was executed - processRewards(listing); + _processRewards(listing); if (listing.status == Status.NULL) return; - if (listing.stakedBalance < minimumBalance) { - touchAndRemoveListing(listing); - return; - } - //Create challenge Challenge storage challenge = _challenges[nextChallenge]; @@ -279,16 +276,16 @@ contract ValidatorRegistry is Ownable { nextChallenge++; //Emit challenged event - emitValidatorChallenged(listing.tendermintPublicKey, listing.owner, challenge.challenger, listing.currentChallenge, challenge.pollId, challenge.details); + _emitValidatorChallenged(listing.tendermintPublicKey, listing.owner, challenge.challenger, listing.currentChallenge, challenge.pollId, challenge.details); } - /** @dev Resolve a challenge - @notice Resolve a challenge - @param pubKey Hex encoded tendermint public key + /** @dev Resolve a challenge. Pays out tokens to the winning staked party. Captures information to facilitate voter payout. + @notice Resolve a challenge. Pays out tokens to the winning staked party. Captures information to facilitate voter payout. + @param tendermintPublicKey Hex encoded tendermint public key. */ - function resolveChallenge(bytes32 pubKey) public { + function resolveChallenge(bytes32 tendermintPublicKey) public { //Load listing - Listing storage listing = _listings[pubKey]; + Listing storage listing = _listings[tendermintPublicKey]; Challenge storage challenge = _challenges[listing.currentChallenge]; //Must be currently challenged and after the end block but not finalized @@ -321,9 +318,9 @@ contract ValidatorRegistry is Ownable { challenge.balance = challenge.balance.sub(holderCut); //Emit event removing power - emitValidatorRegistryUpdate(listing.tendermintPublicKey, listing.owner, 0); + _emitValidatorRegistryUpdate(listing.tendermintPublicKey, listing.owner, 0); - removeListing(listing); + _removeListing(listing); } else { challenge.passed = false; challenge.finalized = true; @@ -350,15 +347,15 @@ contract ValidatorRegistry is Ownable { treasury.releaseTokens(listing.owner, listing.stakedBalance); //Clear listing data and remove from tracking array - removeListing(listing); + _removeListing(listing); } else if (listing.confirmationBlock > 0) {//Confirmed challenge is returned to accepted listing.status = Status.ACCEPTED; listing.currentChallenge = 0; - emitValidatorChallengeResolved(listing); + _emitValidatorChallengeResolved(listing); } else {//Pending challege returned to pending listing.status = Status.PENDING; listing.currentChallenge = 0; - emitValidatorChallengeResolved(listing); + _emitValidatorChallengeResolved(listing); } //ensure the ending state is correct @@ -366,8 +363,8 @@ contract ValidatorRegistry is Ownable { } } - /** @dev Claims winnings from a challenge - @notice Claims winnings from a challenge + /** @dev Claims winnings from a challenge that has been completed. Accounts are rewarded for voting in support of the winning resolution proportionally to their vote contribution. + @notice Claims winnings from a challenge that has been completed. Accounts are rewarded for voting in support of the winning resolution proportionally to their vote contribution. @param challengeId Challenge id to claim rewards from. */ function claimWinnings(uint challengeId) public { @@ -395,21 +392,21 @@ contract ValidatorRegistry is Ownable { treasury.award(msg.sender, voterCut); } - /** @dev Claims rewards for a listing - @notice Claims rewards for a listing - @param pubKey Public key for the listing to have rewards claimed + /** @dev Claims rewards for a listing. Positive reward rate will have new tokens minted. Negative reward rates will burn tokens and have risk of being removed immediately through a TouchAndRemove when insufficient tokens are available. + @notice Claims rewards for a listing. Positive reward rate will have new tokens minted. Negative reward rates will burn tokens and have risk of being removed immediately through a TouchAndRemove when insufficient tokens are available. + @param tendermintPublicKey Public key for the listing to have rewards claimed. */ - function claimRewards(bytes32 pubKey) public { + function claimRewards(bytes32 tendermintPublicKey) public { //Load listing - Listing storage listing = _listings[pubKey]; + Listing storage listing = _listings[tendermintPublicKey]; //Call process rewards with loaded listing - processRewards(listing); + _processRewards(listing); } - /** @dev Confirm a listing registration - @notice Confirm a listing registration - @param tendermintPublicKey Hex encoded tendermint public key + /** @dev Confirm a listing registration after the confirmation period. Perform initial token burn for a burning listing. + @notice Confirm a listing registration after the confirmation period. Perform initial token burn for a burning listing. + @param tendermintPublicKey Hex encoded tendermint public key. */ function confirmListing(bytes32 tendermintPublicKey) public { //Load listing @@ -426,23 +423,23 @@ contract ValidatorRegistry is Ownable { listing.lastRewardBlock = block.number - rewardPeriod; } else { if (listing.rewardRate > 0) { - addGeneratorToList(listing.rewardRate, listing.tendermintPublicKey); + _addGeneratorToList(listing.rewardRate, listing.tendermintPublicKey); } listing.lastRewardBlock = block.number; } - processRewards(listing); + _processRewards(listing); if (listing.status != Status.NULL) { //Emit update event if listing wasn't removed - emitValidatorConfirmed(listing); - emitValidatorRegistryUpdate(listing.tendermintPublicKey, listing.owner, listing.stakedBalance); + _emitValidatorConfirmed(listing); + _emitValidatorRegistryUpdate(listing.tendermintPublicKey, listing.owner, listing.stakedBalance); } } - /** @dev Initiate a listing exit - @notice Initiate a listing exit - @param tendermintPublicKey Hex encoded tendermint public key + /** @dev Initiate a listing exit. Immediately exit a pending listing or start the exit delay and remove validator power of the listing. + @notice Initiate a listing exit. Immediately exit a pending listing or start the exit delay and remove validator power of the listing. + @param tendermintPublicKey Hex encoded tendermint public key. */ function initExit(bytes32 tendermintPublicKey) public { //Load the listing @@ -458,7 +455,7 @@ contract ValidatorRegistry is Ownable { treasury.releaseTokens(msg.sender, listing.stakedBalance); //Clear listing data and remove from tracking array - removeListing(listing); + _removeListing(listing); return; } @@ -470,12 +467,12 @@ contract ValidatorRegistry is Ownable { listing.exitBlock = block.number + exitPeriod; //Emit event - emitValidatorRegistryUpdate(listing.tendermintPublicKey, listing.owner, 0); + _emitValidatorRegistryUpdate(listing.tendermintPublicKey, listing.owner, 0); } - /** @dev Complete a listing exit - @notice Complete a listing exit - @param tendermintPublicKey Hex encoded tendermint public key + /** @dev Finalize a listings exit. Allowing the account to safely remove the staked tokens and nullify the listing. + @notice Finalize a listings exit. Allowing the account to safely remove the staked tokens and nullify the listing. + @param tendermintPublicKey Hex encoded tendermint public key. */ function finalizeExit(bytes32 tendermintPublicKey) public { //Load the listing @@ -493,9 +490,14 @@ contract ValidatorRegistry is Ownable { treasury.releaseTokens(msg.sender, listing.stakedBalance); //Clear listing data and remove from tracking array - removeListing(listing); + _removeListing(listing); } + /** @dev Reduces the generating reward rate of a listing. This prevents the listing from needing to reapply when they amount of tokens they are generating is to high. + @notice Reduces the generating reward rate of a listing. This prevents the listing from needing to reapply when they amount of tokens they are generating is to high. + @param tendermintPublicKey Hex encoded tendermint public key. + @param newRate New reward rate in the units of ether/period. + */ function reduceReward(bytes32 tendermintPublicKey, int newRate) public { //Load the listing Listing storage listing = _listings[tendermintPublicKey]; @@ -511,12 +513,17 @@ contract ValidatorRegistry is Ownable { //Listing must be active and in good standing. require(listing.status == Status.ACCEPTED); - processRewards(listing); + _processRewards(listing); listing.rewardRate = newRate; - emitValidatorReducedReward(listing); + _emitValidatorReducedReward(listing); } + /** @dev Updates the contract configuration. + @notice Updates the contract configuration. + @param index The index of the parameter you wish to update. + @param value The new value for the parameter. + */ function updateConfigValue(uint index, uint value) public onlyOwner { if (index == 0) { applicationPeriod = value; @@ -544,12 +551,12 @@ contract ValidatorRegistry is Ownable { } //INTERNAL - function hasRewardPending(Listing storage l) internal view returns (bool) { + function _hasRewardPending(Listing storage l) internal view returns (bool) { return (l.status == Status.ACCEPTED && l.rewardRate != 0 && l.lastRewardBlock + rewardPeriod <= block.number); } - function processRewards(Listing storage l) internal { - if (hasRewardPending(l)) { + function _processRewards(Listing storage l) internal { + if (_hasRewardPending(l)) { uint rewardPeriods = block.number.sub(l.lastRewardBlock).div(rewardPeriod); if (l.rewardRate > 0) { //Converting reward rate from ether to tokens to mint @@ -578,7 +585,7 @@ contract ValidatorRegistry is Ownable { uint totalTokensToBurn = userTreasuryBalance.add(tokensRemaining); treasury.burnFrom(l.owner, totalTokensToBurn); - touchAndRemoveListing(l); + _touchAndRemoveListing(l); } else { treasury.burnFrom(l.owner, tokensToBurn); } @@ -587,20 +594,20 @@ contract ValidatorRegistry is Ownable { } } - function touchAndRemoveListing(Listing storage l) internal { + function _touchAndRemoveListing(Listing storage l) internal { //Emit events to signal listing was to and removed, and voting power has been lost - emitValidatorTouchedAndRemoved(l); - emitValidatorRegistryUpdate(l.tendermintPublicKey, l.owner, 0); + _emitValidatorTouchedAndRemoved(l); + _emitValidatorRegistryUpdate(l.tendermintPublicKey, l.owner, 0); //Approve and release tokens to treasury kosuToken.approve(address(treasury), l.stakedBalance); treasury.releaseTokens(l.owner, l.stakedBalance); //Clear listing data and remove from tracking array - removeListing(l); + _removeListing(l); } - function removeListingKey(bytes32 key) internal { + function _removeListingKey(bytes32 key) internal { //Removes the listing by key and shortens the array for (uint i = 0; i < _listingKeys.length; i++) { if (_listingKeys[i] == key) { @@ -611,29 +618,20 @@ contract ValidatorRegistry is Ownable { } } - function sqrt(uint x) internal pure returns (uint y) { - uint z = (x + 1) / 2; - y = x; - while (z < y) { - y = z; - z = (x / z + z) / 2; - } - } - - function removeListing(Listing storage l) internal { + function _removeListing(Listing storage l) internal { if (l.rewardRate > 0 && l.confirmationBlock > 0) { - removeEntryFromList(l.tendermintPublicKey); + _removeEntryFromList(l.tendermintPublicKey); } bytes32[] memory data = new bytes32[](1); data[0] = l.tendermintPublicKey; eventEmitter.emitEvent("ValidatorRemoved", data, ""); - removeListingKey(l.tendermintPublicKey); + _removeListingKey(l.tendermintPublicKey); delete _listings[l.tendermintPublicKey]; } - function emitValidatorRegistryUpdate(bytes32 tendermintPublicKey, address owner, uint stake) internal { + function _emitValidatorRegistryUpdate(bytes32 tendermintPublicKey, address owner, uint stake) internal { bytes32[] memory data = new bytes32[](3); data[0] = tendermintPublicKey; data[1] = bytes32(uint(owner)); @@ -641,7 +639,7 @@ contract ValidatorRegistry is Ownable { eventEmitter.emitEvent("ValidatorRegistryUpdate", data, ""); } - function emitValidatorRegistered(uint applicationBlock, bytes32 tendermintPublicKey, address owner, int rewardRate, string storage details) internal { + function _emitValidatorRegistered(uint applicationBlock, bytes32 tendermintPublicKey, address owner, int rewardRate, string storage details) internal { bytes32[] memory data = new bytes32[](4); data[0] = tendermintPublicKey; data[1] = bytes32(applicationBlock); @@ -650,20 +648,20 @@ contract ValidatorRegistry is Ownable { eventEmitter.emitEvent("ValidatorRegistered", data, details); } - function emitValidatorConfirmed(Listing storage l) internal { + function _emitValidatorConfirmed(Listing storage l) internal { bytes32[] memory data = new bytes32[](1); data[0] = l.tendermintPublicKey; eventEmitter.emitEvent("ValidatorConfirmed", data, ""); } - function emitValidatorTouchedAndRemoved(Listing storage l) internal { + function _emitValidatorTouchedAndRemoved(Listing storage l) internal { bytes32[] memory data = new bytes32[](2); data[0] = l.tendermintPublicKey; data[1] = bytes32(uint(l.owner)); eventEmitter.emitEvent("ValidatorTouchedAndRemoved", data, ""); } - function emitValidatorReducedReward(Listing storage l) internal { + function _emitValidatorReducedReward(Listing storage l) internal { bytes32[] memory data = new bytes32[](3); data[0] = l.tendermintPublicKey; data[1] = bytes32(uint(l.owner)); @@ -671,7 +669,7 @@ contract ValidatorRegistry is Ownable { eventEmitter.emitEvent("ValidatorReducedReward", data, ""); } - function emitValidatorChallenged(bytes32 tendermintPublicKey, address owner, address challenger, uint challengeId, uint pollId, string storage details) internal { + function _emitValidatorChallenged(bytes32 tendermintPublicKey, address owner, address challenger, uint challengeId, uint pollId, string storage details) internal { bytes32[] memory data = new bytes32[](5); data[0] = tendermintPublicKey; data[1] = bytes32(uint(owner)); @@ -681,13 +679,13 @@ contract ValidatorRegistry is Ownable { eventEmitter.emitEvent("ValidatorChallenged", data, details); } - function emitValidatorChallengeResolved(Listing storage l) internal { + function _emitValidatorChallengeResolved(Listing storage l) internal { bytes32[] memory data = new bytes32[](1); data[0] = l.tendermintPublicKey; eventEmitter.emitEvent("ValidatorChallengeResolved", data, ""); } - function findGeneratorPlaceInList(int value) internal view returns (bytes32 previous, bytes32 next) { + function _findGeneratorPlaceInList(int value) internal view returns (bytes32 previous, bytes32 next) { if (_maxGenerator == 0x0) { return (0x0, 0x0); } @@ -709,12 +707,12 @@ contract ValidatorRegistry is Ownable { } } - function addGeneratorToList(int rewardRate, bytes32 pubKey) internal { - MaxList storage newGenerator = _generators[pubKey]; + function _addGeneratorToList(int rewardRate, bytes32 tendermintPublicKey) internal { + MaxList storage newGenerator = _generators[tendermintPublicKey]; newGenerator.value = rewardRate; - newGenerator.self = pubKey; + newGenerator.self = tendermintPublicKey; - (bytes32 previous, bytes32 next) = findGeneratorPlaceInList(newGenerator.value); + (bytes32 previous, bytes32 next) = _findGeneratorPlaceInList(newGenerator.value); if (previous == 0x0 && next == 0x0) { _maxGenerator = newGenerator.self; @@ -736,7 +734,7 @@ contract ValidatorRegistry is Ownable { } } - function removeEntryFromList(bytes32 entryKey) internal { + function _removeEntryFromList(bytes32 entryKey) internal { if (_maxGenerator == 0x0) { return; } diff --git a/packages/kosu-system-contracts/contracts/voting/Voting.sol b/packages/kosu-system-contracts/contracts/voting/Voting.sol index 4f41bda8..44558b7e 100644 --- a/packages/kosu-system-contracts/contracts/voting/Voting.sol +++ b/packages/kosu-system-contracts/contracts/voting/Voting.sol @@ -47,13 +47,13 @@ contract Voting { treasury = Treasury(treasuryAddress); } - /** @dev Create a new poll to accept votes based on the configuration - @notice Create a new poll to accept votes based on the configuration - @param _commitEndBlock Block number when commit phase ends - @param _revealEndBlock Block number when reveal phase ends + /** @dev Create a new poll. The commit and reveal periods must be provided. The creation of the poll is notified with an event from the shared EventEmitter. + @notice Create a new poll. The commit and reveal periods must be provided. The creation of the poll is notified with an event from the shared EventEmitter. + @param _commitEndBlock Block number when commit phase ends. + @param _revealEndBlock Block number when reveal phase ends. @return Poll index number. Will be used as the key for interacting with a vote. */ - function createPoll(uint _commitEndBlock, uint _revealEndBlock) public returns (uint) { + function createPoll(uint _commitEndBlock, uint _revealEndBlock) public returns (uint) {//TODO is it a concern that polls could be created by anyone freely? // Reveal end after commit require(_commitEndBlock < _revealEndBlock); @@ -79,11 +79,11 @@ contract Voting { return p.id; } - /** @dev Commit a vote in a poll to be later revealed - @notice Commit a vote in a poll to be later revealed - @param _pollId Poll index to act upon - @param _vote Hash encoded vote - @param _tokensToCommit Number of tokens to commit to vote + /** @dev Commit a vote in a poll to be later revealed. The salt and option must be retained for a successful reveal. + @notice Commit a vote in a poll to be later revealed. The salt and option must be retained for a successful reveal. + @param _pollId Poll id to commit vote to. + @param _vote Hash encoded vote option with salt. + @param _tokensToCommit Number of tokens to commit to vote. */ function commitVote(uint _pollId, bytes32 _vote, uint _tokensToCommit) public { //load Poll and Vote @@ -104,11 +104,11 @@ contract Voting { p.didCommit[msg.sender] = true; } - /** @dev Reveal a previously committed vote - @notice Reveal a previously committed vote - @param _pollId Poll index to act upon - @param _voteOption User vote option - @param _voteSalt Salt used to in hash to obfuscate vote option + /** @dev Reveal a previously committed vote by providing the vote option and salt used to generate the vote hash. + @notice Reveal a previously committed vote by providing the vote option and salt used to generate the vote hash. + @param _pollId Poll id to commit vote to. + @param _voteOption Vote option used to generate vote hash. + @param _voteSalt Salt used to generate vote hash. */ function revealVote(uint _pollId, uint _voteOption, uint _voteSalt) public { Poll storage p = polls[_pollId]; @@ -140,9 +140,9 @@ contract Voting { p.leadingTokens = p.voteValues[p.currentLeadingOption]; } - /** @dev Retreive the winning outcome for a finalized poll. - @param _pollId Poll index to check winning option for - @return The uint value of the winning outcome + /** @dev Retrieve the winning option for a finalized poll. + @param _pollId Poll index to check winning option for. + @return The winning option. */ function winningOption(uint _pollId) public view returns (uint) { Poll memory p = polls[_pollId]; @@ -150,9 +150,9 @@ contract Voting { return p.currentLeadingOption; } - /** @dev Retreive the total number of tokens that voted on the winning side of a finalized poll. - @param _pollId Poll index to check winning tokens for - @return The uint number of tokens revealed for the winning option. + /** @dev Retrieve the total number of tokens that supported the winning option of a finalized poll. + @param _pollId Poll index to check winning tokens for. + @return The uint number of tokens supporting the winning option. */ function totalWinningTokens(uint _pollId) public view returns (uint) { Poll memory p = polls[_pollId]; @@ -160,9 +160,9 @@ contract Voting { return p.leadingTokens; } - /** @dev Retreive the total number of tokens revealed for a finalized poll. - @param _pollId Poll index to check total revealed tokens for - @return The total number of tokens reveled in the poll. + /** @dev Retrieve the total number of tokens revealed for a finalized poll. + @param _pollId Poll index to check total revealed tokens for. + @return The total number of tokens revealed in the poll. */ function totalRevealedTokens(uint _pollId) public view returns (uint) { Poll memory p = polls[_pollId]; @@ -170,8 +170,8 @@ contract Voting { return p.totalRevealedTokens; } - /** @dev Retreive the number of tokens committed by a user for the winning option. - @param _pollId Poll index to check winning tokens for + /** @dev Retrieve the number of tokens committed by a user for the winning option. + @param _pollId Poll index to check winning tokens for. @param _user Address of user to check winning tokens. */ function userWinningTokens(uint _pollId, address _user) public view returns (uint tokens) { diff --git a/packages/kosu-system-contracts/test/poster_registry.ts b/packages/kosu-system-contracts/test/poster_registry.ts index e96522ba..89223b9d 100644 --- a/packages/kosu-system-contracts/test/poster_registry.ts +++ b/packages/kosu-system-contracts/test/poster_registry.ts @@ -164,9 +164,9 @@ describe("PosterRegistry", () => { }); }); - describe("token", () => { + describe("kosuToken", () => { it("should have a token token configured", async () => { - posterRegistry.token.callAsync().should.eventually.eq(token.address); + posterRegistry.kosuToken.callAsync().should.eventually.eq(token.address); }); }); From eed67b7c45de136949f24cf5f2086c80b06e0f0d Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Sun, 25 Aug 2019 23:45:58 -0500 Subject: [PATCH 07/11] Regenerating the documents. --- .../docs/AuthorizedAddresses.md | 14 +- .../docs/EventEmitter.md | 14 +- .../kosu-system-contracts/docs/KosuToken.md | 67 +++---- .../docs/OrderGateway.md | 42 ++-- .../docs/PosterRegistry.md | 34 ++-- .../kosu-system-contracts/docs/Treasury.md | 183 +++++++++--------- .../docs/ValidatorRegistry.md | 164 ++++++++++------ packages/kosu-system-contracts/docs/Voting.md | 80 ++++---- .../docs/ZeroExV2SubContract.md | 6 +- 9 files changed, 322 insertions(+), 282 deletions(-) diff --git a/packages/kosu-system-contracts/docs/AuthorizedAddresses.md b/packages/kosu-system-contracts/docs/AuthorizedAddresses.md index af09f599..0560b414 100644 --- a/packages/kosu-system-contracts/docs/AuthorizedAddresses.md +++ b/packages/kosu-system-contracts/docs/AuthorizedAddresses.md @@ -1,6 +1,6 @@ # AuthorizedAddresses -Common registry of system contract addresses authrorized to access internal methods. +Common registry of system contract addresses authorized to access internal methods. ## Contents @@ -30,7 +30,7 @@ function authorizeAddress(a address) public ### isAddressAuthorized -Verify if address is authorized by reading contract mapping +Verify address authorization. #### Signature @@ -40,13 +40,13 @@ function isAddressAuthorized(a address) public view (bool) #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | -------------------------------- | -| `a` | `address` | Address to get authorized value. | +| Parameter | Type | Description | +| --------- | --------- | --------------------- | +| `a` | `address` | Address to authorize. | #### Returns: -True if the address is authorized, false otherwise. +Address authorization ### transferOwnership @@ -66,7 +66,7 @@ function transferOwnership(newOwner address) public ### unauthorizeAddress -Unauthorizes the address by setting the mapping value to false. +Disables the address previous authorization by setting the mapping value to false. #### Signature diff --git a/packages/kosu-system-contracts/docs/EventEmitter.md b/packages/kosu-system-contracts/docs/EventEmitter.md index 863854e1..161436ad 100644 --- a/packages/kosu-system-contracts/docs/EventEmitter.md +++ b/packages/kosu-system-contracts/docs/EventEmitter.md @@ -1,6 +1,6 @@ # EventEmitter -A shared contract for all Kosu system contracts to trigger event logs through. +A central event emitting contract supporting the Kosu contract system. ## Contents @@ -28,7 +28,7 @@ constructor(auth address) public ### emitEvent -Emit generic events which can have decoding exposed though javascript library. +Emits a standard event from the Kosu contract system. The events can be decoded though the javascript library. #### Signature @@ -38,8 +38,8 @@ function emitEvent(eventType string, data bytes32[], stringData string) public #### Parameters: -| Parameter | Type | Description | -| ------------ | ----------- | -------------------------------------------------------------- | -| `eventType` | `string` | String name/type of event | -| `data` | `bytes32[]` | Bytes32 encoded data to be emitted from a centralized location | -| `stringData` | `string` | String containing optional additonal information | +| Parameter | Type | Description | +| ------------ | ----------- | -------------------------------------------------- | +| `eventType` | `string` | String name/type of event. | +| `data` | `bytes32[]` | Bytes32 encoded data to be emitted. | +| `stringData` | `string` | String containing optional additional information. | diff --git a/packages/kosu-system-contracts/docs/KosuToken.md b/packages/kosu-system-contracts/docs/KosuToken.md index 92c1808a..6b4f42f4 100644 --- a/packages/kosu-system-contracts/docs/KosuToken.md +++ b/packages/kosu-system-contracts/docs/KosuToken.md @@ -1,6 +1,6 @@ # KosuToken -KosuToken (KOSU) is an implentation of the ERC-20 interface and supporting bonding curve for mints and burns. +KosuToken (KOSU) is an implementation of the ERC-20 interface and supporting bonding curve for mints and burns. ## Contents @@ -14,7 +14,6 @@ KosuToken (KOSU) is an implentation of the ERC-20 interface and supporting bondi - [estimateEtherToToken](#estimateethertotoken) - [estimateTokenToEther](#estimatetokentoether) - [increaseAllowance](#increaseallowance) - - [mint](#mint) - [mintTo](#mintto) - [releaseTokens](#releasetokens) - [transfer](#transfer) @@ -82,7 +81,7 @@ An uint256 representing the amount owned by the passed address. ### bondTokens -Uses the ether paid to calculate and mint tokens. +Receives ether as a backing currency to be used against the bonding curve to mint tokens. #### Signature @@ -98,7 +97,7 @@ function bondTokens(minPayout uint256) public (uint256) ### burn -Burn tokens +Voluntarily burn tokens. #### Signature @@ -108,9 +107,9 @@ function burn(amount uint256) public #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | --------------------------- | -| `amount` | `uint256` | Number of tokens to destroy | +| Parameter | Type | Description | +| --------- | --------- | ------------------------- | +| `amount` | `uint256` | Number of tokens to burn. | ### decreaseAllowance @@ -131,7 +130,7 @@ function decreaseAllowance(spender address, subtractedValue uint256) public (boo ### estimateEtherToToken -Estimates the number of tokens to generate with the input ether at the current state. +Estimates the number of tokens that would be minted with the input ether at the current ether and token balances. #### Signature @@ -141,17 +140,17 @@ function estimateEtherToToken(input uint256) public view (uint256) #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | --------------------------------- | -| `input` | `uint256` | The amount of ether to contribute | +| Parameter | Type | Description | +| --------- | --------- | ---------------------------------- | +| `input` | `uint256` | The amount of ether to contribute. | #### Returns: -Number of tokens that would be generated +Number of tokens that would be minted. ### estimateTokenToEther -Estimates the amount of ether to return with the input number of tokens to burn. +Estimates the amount of ether to be released with the input number of tokens to burn. #### Signature @@ -161,13 +160,13 @@ function estimateTokenToEther(input uint256) public view (uint256) #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ---------------------------- | -| `input` | `uint256` | The number of tokens to burn | +| Parameter | Type | Description | +| --------- | --------- | ----------------------------- | +| `input` | `uint256` | The number of tokens to burn. | #### Returns: -Amount of ether to receive +Amount of ether to release. ### increaseAllowance @@ -186,25 +185,9 @@ function increaseAllowance(spender address, addedValue uint256) public (bool) | `spender` | `address` | The address which will spend the funds. | | `addedValue` | `uint256` | The amount of tokens to increase the allowance by. | -### mint - -Mint tokens - -#### Signature - -```solidity -function mint(amount uint256) public -``` - -#### Parameters: - -| Parameter | Type | Description | -| --------- | --------- | -------------------------- | -| `amount` | `uint256` | Number of tokens to create | - ### mintTo -Mint tokens to specified address +Authorized addresses (mostly contract systems) may manually mint new tokens to desired addresses. #### Signature @@ -214,14 +197,14 @@ function mintTo(_address address, amount uint256) public #### Parameters: -| Parameter | Type | Description | -| ---------- | --------- | --------------------------- | -| `_address` | `address` | Address to receive tokens | -| `amount` | `uint256` | Number of tokens to create. | +| Parameter | Type | Description | +| ---------- | --------- | -------------------------- | +| `_address` | `address` | Address to mint tokens to. | +| `amount` | `uint256` | Number of tokens to mint. | ### releaseTokens -Burns the input amount of tokens returning the calculated amount of ether. +Burns the input tokens and releases the calculated amount of ether backing the tokens destroyed. #### Signature @@ -231,9 +214,9 @@ function releaseTokens(tokensToBurn uint256) public #### Parameters: -| Parameter | Type | Description | -| -------------- | --------- | ---------------------------- | -| `tokensToBurn` | `uint256` | The number of tokens to burn | +| Parameter | Type | Description | +| -------------- | --------- | --------------------------------------- | +| `tokensToBurn` | `uint256` | The number of the users tokens to burn. | ### transfer diff --git a/packages/kosu-system-contracts/docs/OrderGateway.md b/packages/kosu-system-contracts/docs/OrderGateway.md index 6fe3c120..2d7e62ae 100644 --- a/packages/kosu-system-contracts/docs/OrderGateway.md +++ b/packages/kosu-system-contracts/docs/OrderGateway.md @@ -1,6 +1,6 @@ # OrderGateway -Access SubContract implementation's methods to participate in trades and check order status. +Serves as a message router for SubContract implementations. Passing SubContract method calls through the gateway allows for a single watch point for incoming participate transactions. ## Contents @@ -14,7 +14,7 @@ Access SubContract implementation's methods to participate in trades and check o ### amountRemaining -Calls amountRemaining on provided subContract. +Forwards function calls of amountRemaining to the provided subContract address. #### Signature @@ -24,18 +24,18 @@ function amountRemaining(subContract address, data bytes) public view (uint256) #### Parameters: -| Parameter | Type | Description | -| ------------- | --------- | ------------------------------------------------------------------- | -| `subContract` | `address` | Address of contract implementing the SubContract interface. | -| `data` | `bytes` | Encoded maker values for Order encoded based on the makerArguments. | +| Parameter | Type | Description | +| ------------- | --------- | ---------------------------------------------------------------------------------------------------- | +| `subContract` | `address` | Address of contract implementing the SubContract interface. | +| `data` | `bytes` | Encoded values for Order encoded in accordance to the arguments exposed by the provided subContract. | #### Returns: -Quantity of available asset for Order encoded in makerData. +Quantity of available asset for Order encoded in data. ### arguments -Calls arguments on provided subContract. +Forwards function calls of arguments to the provided subContract address. #### Signature @@ -51,11 +51,11 @@ function arguments(subContract address) public view (string) #### Returns: -String encoded JSON representation of subContract maker arguments. +JSON string providing expected structure of subContract input data. ### isValid -Calls isValid on provided subContract. +Forwards function calls of isValid to the provided subContract address. #### Signature @@ -65,18 +65,18 @@ function isValid(subContract address, data bytes) public view (bool) #### Parameters: -| Parameter | Type | Description | -| ------------- | --------- | ------------------------------------------------------------------- | -| `subContract` | `address` | Address of contract implementing the SubContract interface. | -| `data` | `bytes` | Encoded maker values for Order encoded based on the makerArguments. | +| Parameter | Type | Description | +| ------------- | --------- | ---------------------------------------------------------------------------------------------------- | +| `subContract` | `address` | Address of contract implementing the SubContract interface. | +| `data` | `bytes` | Encoded values for Order encoded in accordance to the arguments exposed by the provided subContract. | #### Returns: -Boolean representing the validity of makerData. +Boolean representing the validity of data. ### participate -Calls participate on the provided subContract. +Forwards function calls of participate to the provided subContract address. #### Signature @@ -86,11 +86,11 @@ function participate(subContract address, data bytes) public (bool) #### Parameters: -| Parameter | Type | Description | -| ------------- | --------- | -------------------------------------------------------------- | -| `subContract` | `address` | Address of contract implementing the SubContract interface. | -| `data` | `bytes` | Encoded maker values for Order encoded based on the arguments. | +| Parameter | Type | Description | +| ------------- | --------- | ---------------------------------------------------------------------------------------------------- | +| `subContract` | `address` | Address of contract implementing the SubContract interface. | +| `data` | `bytes` | Encoded values for Order encoded in accordance to the arguments exposed by the provided subContract. | #### Returns: -Boolean representing success of transaction. +Boolean representing result of transaction. diff --git a/packages/kosu-system-contracts/docs/PosterRegistry.md b/packages/kosu-system-contracts/docs/PosterRegistry.md index 5da45bf1..4c24e130 100644 --- a/packages/kosu-system-contracts/docs/PosterRegistry.md +++ b/packages/kosu-system-contracts/docs/PosterRegistry.md @@ -1,6 +1,6 @@ # PosterRegistry -Implementation contract for the PosterRegistry, allowing users to bond and un-bond tokens. +The PosterRegistry allows accounts to manage tokens registered rewarding permission to post orders to the kosu network. ## Contents @@ -14,7 +14,7 @@ Implementation contract for the PosterRegistry, allowing users to bond and un-bo ### constructor -Creates a new PosterRegistry +Initializes the PosterRegistry with the treasury and EventEmitter addresses. #### Signature @@ -24,14 +24,14 @@ constructor(_treasuryAddress address, _events address) public #### Parameters: -| Parameter | Type | Description | -| ------------------ | --------- | ---------------------------------- | -| `_treasuryAddress` | `address` | Deployed Treasury contract address | -| `_events` | `address` | Deployed Events contract address | +| Parameter | Type | Description | +| ------------------ | --------- | --------------------------------- | +| `_treasuryAddress` | `address` | Treasury contract address. | +| `_events` | `address` | Deployed Events contract address. | ### registerTokens -Register tokens. +Register tokens for posting permissions. #### Signature @@ -41,9 +41,9 @@ function registerTokens(amount uint256) public #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ---------------------------- | -| `amount` | `uint256` | Number of tokens to register | +| Parameter | Type | Description | +| --------- | --------- | ----------------------------- | +| `amount` | `uint256` | Number of tokens to register. | ### releaseTokens @@ -57,13 +57,13 @@ function releaseTokens(amount uint256) public #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | --------------------------- | -| `amount` | `uint256` | Number of tokens to release | +| Parameter | Type | Description | +| --------- | --------- | ---------------------------- | +| `amount` | `uint256` | Number of tokens to release. | ### tokensRegisteredFor -Tokens registered for a user. +Tokens registered for an account. #### Signature @@ -73,9 +73,9 @@ function tokensRegisteredFor(a address) public view (uint256) #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ------------------------ | -| `a` | `address` | Address to get value for | +| Parameter | Type | Description | +| --------- | --------- | ------------------------- | +| `a` | `address` | Address to get value for. | #### Returns: diff --git a/packages/kosu-system-contracts/docs/Treasury.md b/packages/kosu-system-contracts/docs/Treasury.md index 3fe09f9b..2b854c06 100644 --- a/packages/kosu-system-contracts/docs/Treasury.md +++ b/packages/kosu-system-contracts/docs/Treasury.md @@ -1,14 +1,14 @@ # Treasury -The Kosu Treasury is the central balance management contract with the Kosu system. +The Kosu Treasury manages KosuToken balances to allow tokens in use within the contract system to be available for voting operations. ## Contents - [Methods](undefined) - - [adjustBalance](#adjustbalance) - [award](#award) - [burnFrom](#burnfrom) - [claimTokens](#claimtokens) + - [completeVote](#completevote) - [confiscate](#confiscate) - [constructor](#constructor) - [contractBond](#contractbond) @@ -16,84 +16,84 @@ The Kosu Treasury is the central balance management contract with the Kosu syste - [contractWithdraw](#contractwithdraw) - [currentBalance](#currentbalance) - [deposit](#deposit) + - [registerVote](#registervote) - [releaseTokens](#releasetokens) - [systemBalance](#systembalance) - - [updateBalance](#updatebalance) - [withdraw](#withdraw) ## Methods -### adjustBalance +### award -Allows contracts to change balance. +Allows accounts to be rewarded with tokens. These tokens were previously obtained by the calling contract and are now being redistributed to the provided account. #### Signature ```solidity -function adjustBalance(account address, amount int256) public +function award(account address, amount uint256) public ``` #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ------------------------- | -| `account` | `address` | User to modify tokens for | -| `amount` | `int256` | Change to token balance | +| Parameter | Type | Description | +| --------- | --------- | --------------------------- | +| `account` | `address` | Account to award tokens to. | +| `amount` | `uint256` | Number of tokens to award. | -### award +### burnFrom -Allows contracts to be rewarded with new tokens. +Allows contracts to burn an accounts held tokens. #### Signature ```solidity -function award(account address, amount uint256) public +function burnFrom(account address, amount uint256) public ``` #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ------------------------- | -| `account` | `address` | User to award tokens to | -| `amount` | `uint256` | Number of tokens to award | +| Parameter | Type | Description | +| --------- | --------- | --------------------------- | +| `account` | `address` | Account to burn tokens for. | +| `amount` | `uint256` | Number of tokens to burn. | -### burnFrom +### claimTokens -Allows contracts to burn tokens. +Allows contracts to claim tokens. Claimed tokens are not available for other system contract and leave the treasury under control of the calling contract. These tokens are still available for voting. #### Signature ```solidity -function burnFrom(account address, amount uint256) public +function claimTokens(account address, amount uint256) public ``` #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ------------------------------------ | -| `account` | `address` | User to modify tokens for by burning | -| `amount` | `uint256` | Number of tokens to burn | +| Parameter | Type | Description | +| --------- | --------- | ----------------------------- | +| `account` | `address` | Account to claim tokens from. | +| `amount` | `uint256` | Number of tokens to claim. | -### claimTokens +### completeVote -Allows contracts to claim tokens. +Releases lock on tokens for account after vote is revealed. No longer tracks the revealed poll. #### Signature ```solidity -function claimTokens(account address, amount uint256) public +function completeVote(account address, pollId uint256) public (bool) ``` #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ------------------------- | -| `account` | `address` | User to claim tokens from | -| `amount` | `uint256` | Number of tokens to claim | +| Parameter | Type | Description | +| --------- | --------- | ---------------------------------- | +| `account` | `address` | The account voting. | +| `pollId` | `uint256` | The poll the account is voting on. | ### confiscate -Allows contracts to confiscate tokens the user has lost access to. +Allows contracts to confiscate tokens the account has lost access to. These previously claimed tokens are no longer owned by the account. #### Signature @@ -103,14 +103,14 @@ function confiscate(account address, amount uint256) public #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ------------------------------ | -| `account` | `address` | User to confiscate tokens from | -| `amount` | `uint256` | Number of tokens to confiscate | +| Parameter | Type | Description | +| --------- | --------- | ---------------------------------- | +| `account` | `address` | Account to confiscate tokens from. | +| `amount` | `uint256` | Number of tokens to confiscate. | ### constructor -Creates a new Treasury. +Initializes the treasury with the kosuToken and authorizedAddresses contracts. #### Signature @@ -120,30 +120,30 @@ constructor(kosuTokenAddress address, auth address) public #### Parameters: -| Parameter | Type | Description | -| ------------------ | --------- | --------------------------------------- | -| `kosuTokenAddress` | `address` | The deployed KosuToken contract address | -| `auth` | `address` | AuthorizedAddresses deployed address. | +| Parameter | Type | Description | +| ------------------ | --------- | ---------------------------------------- | +| `kosuTokenAddress` | `address` | The deployed KosuToken contract address. | +| `auth` | `address` | AuthorizedAddresses deployed address. | ### contractBond -Allows Kosu contracts to bond for the user. +Allows Kosu contracts to bond ether on on the accounts behalf. #### Signature ```solidity -function contractBond(user address) public (uint256) +function contractBond(account address) public (uint256) ``` #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ----------------------------------------------------- | -| `user` | `address` | The user the calling contract is acting on behalf of. | +| Parameter | Type | Description | +| --------- | --------- | -------------------------------------------------------- | +| `account` | `address` | The address the calling contract is acting on behalf of. | ### contractDeposit -Allows contracts to deposit. +Allows contracts to deposit tokens from an accounts balance. #### Signature @@ -153,14 +153,14 @@ function contractDeposit(account address, amount uint256) public #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | --------------------------- | -| `account` | `address` | User to deposit tokens for | -| `amount` | `uint256` | Number of tokens to deposit | +| Parameter | Type | Description | +| --------- | --------- | -------------------------------------------------- | +| `account` | `address` | Account address the tokens will be deposited from. | +| `amount` | `uint256` | Number of tokens to deposit. | ### contractWithdraw -Allows contracts to withdraw. +Allows contracts to withdraw tokens back to an account address. #### Signature @@ -170,14 +170,14 @@ function contractWithdraw(account address, amount uint256) public #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ---------------------------- | -| `account` | `address` | User to withdraw tokens for | -| `amount` | `uint256` | Number of tokens to withdraw | +| Parameter | Type | Description | +| --------- | --------- | ------------------------------- | +| `account` | `address` | Address to withdraw tokens for. | +| `amount` | `uint256` | Number of tokens to withdraw. | ### currentBalance -Reports the balance held within the contract for a user. +Reports the available balance held within the treasury for an account. #### Signature @@ -187,13 +187,13 @@ function currentBalance(account address) public view (uint256) #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ---------------------------- | -| `account` | `address` | Account to report balance on | +| Parameter | Type | Description | +| --------- | --------- | ----------------------------- | +| `account` | `address` | Account to report balance on. | #### Returns: -Number of tokens this contract holds for the user. +Number of available tokens the treasury holds for the account. ### deposit @@ -207,63 +207,64 @@ function deposit(amount uint256) public #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | --------------------------- | -| `amount` | `uint256` | Number of tokens to deposit | +| Parameter | Type | Description | +| --------- | --------- | ---------------------------- | +| `amount` | `uint256` | Number of tokens to deposit. | -### releaseTokens +### registerVote -Allows contracts to release tokens. +Allows voting contract to register a poll to ensure tokens aren't removed. #### Signature ```solidity -function releaseTokens(account address, amount uint256) public +function registerVote(account address, pollId uint256, amount uint256) public (bool) ``` #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | --------------------------- | -| `account` | `address` | User to release tokens to | -| `amount` | `uint256` | Number of tokens to release | +| Parameter | Type | Description | +| --------- | --------- | ---------------------------------- | +| `account` | `address` | The account voting. | +| `pollId` | `uint256` | The poll the account is voting on. | +| `amount` | `uint256` | Number of tokens contributed. | -### systemBalance +### releaseTokens -Reports the balance within the contract system for a user. +Allows contracts to release claimed tokens. Allowing them to be used elsewhere by the user again. #### Signature ```solidity -function systemBalance(account address) public view (uint256) +function releaseTokens(account address, amount uint256) public ``` #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ---------------------------- | -| `account` | `address` | Account to report balance on | - -#### Returns: +| Parameter | Type | Description | +| --------- | --------- | ----------------------------- | +| `account` | `address` | Account to release tokens to. | +| `amount` | `uint256` | Number of tokens to release. | -The number of tokens within the total contract system. - -### updateBalance +### systemBalance -Allows contracts to set balance. +Reports the total balance within the entire contract system for an account. #### Signature ```solidity -function updateBalance(account address, amount uint256) public +function systemBalance(account address) public view (uint256) ``` #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ------------------------------------------ | -| `account` | `address` | User to modify tokens for | -| `amount` | `uint256` | Number of tokens to set to current balance | +| Parameter | Type | Description | +| --------- | --------- | ----------------------------- | +| `account` | `address` | Account to report balance on. | + +#### Returns: + +The number of tokens within the entire contract system. ### withdraw @@ -277,6 +278,6 @@ function withdraw(amount uint256) public #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | ---------------------------- | -| `amount` | `uint256` | Number of tokens to withdraw | +| Parameter | Type | Description | +| --------- | --------- | ----------------------------- | +| `amount` | `uint256` | Number of tokens to withdraw. | diff --git a/packages/kosu-system-contracts/docs/ValidatorRegistry.md b/packages/kosu-system-contracts/docs/ValidatorRegistry.md index 04e100a2..20e0cc39 100644 --- a/packages/kosu-system-contracts/docs/ValidatorRegistry.md +++ b/packages/kosu-system-contracts/docs/ValidatorRegistry.md @@ -16,14 +16,17 @@ Stores registry of validator listings and provides functionality to curate throu - [getListing](#getlisting) - [getListings](#getlistings) - [initExit](#initexit) + - [reduceReward](#reducereward) - [registerListing](#registerlisting) - [resolveChallenge](#resolvechallenge) + - [transferOwnership](#transferownership) + - [updateConfigValue](#updateconfigvalue) ## Methods ### challengeListing -Challenge a registered listing +Challenge a registered listing. Stakes a balance of tokens matching the validator being challenged. Creates a poll through the voting contract of tokens holders to determine a winner. #### Signature @@ -33,30 +36,30 @@ function challengeListing(tendermintPublicKey bytes32, details string) public #### Parameters: -| Parameter | Type | Description | -| --------------------- | --------- | ------------------------------------------------------------------------- | -| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key | -| `details` | `string` | A string value to represent support for claim (commonly an external link) | +| Parameter | Type | Description | +| --------------------- | --------- | -------------------------------------------------------------------------- | +| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key. | +| `details` | `string` | A string value to represent support for claim (commonly an external link). | ### claimRewards -Claims rewards for a listing +Claims rewards for a listing. Positive reward rate will have new tokens minted. Negative reward rates will burn tokens and have risk of being removed immediately through a TouchAndRemove when insufficient tokens are available. #### Signature ```solidity -function claimRewards(pubKey bytes32) public +function claimRewards(tendermintPublicKey bytes32) public ``` #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | -------------------------------------------------- | -| `pubKey` | `bytes32` | Public key for the listing to have rewards claimed | +| Parameter | Type | Description | +| --------------------- | --------- | --------------------------------------------------- | +| `tendermintPublicKey` | `bytes32` | Public key for the listing to have rewards claimed. | ### claimWinnings -Claims winnings from a challenge +Claims winnings from a challenge that has been completed. Accounts are rewarded for voting in support of the winning resolution proportionally to their vote contribution. #### Signature @@ -72,7 +75,7 @@ function claimWinnings(challengeId uint256) public ### confirmListing -Confirm a listing registration +Confirm a listing registration after the confirmation period. Perform initial token burn for a burning listing. #### Signature @@ -82,37 +85,36 @@ function confirmListing(tendermintPublicKey bytes32) public #### Parameters: -| Parameter | Type | Description | -| --------------------- | --------- | --------------------------------- | -| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key | +| Parameter | Type | Description | +| --------------------- | --------- | ---------------------------------- | +| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key. | ### constructor -Create a new ValidatorRegistry implementation +Initializes the ValidatorRegistry with chain based configuration for pacing and deployed addresses. #### Signature ```solidity -constructor(_treasuryAddress address, _votingAddress address, auth address, _events address, _applicationPeriod uint256, _commitPeriod uint256, _challengePeriod uint256, _exitPeriod uint256, _rewardPeriod uint256) public +constructor(_treasuryAddress address, _votingAddress address, _events address, _applicationPeriod uint256, _commitPeriod uint256, _challengePeriod uint256, _exitPeriod uint256, _rewardPeriod uint256) public ``` #### Parameters: -| Parameter | Type | Description | -| -------------------- | --------- | -------------------------------------------------------------------------- | -| `_treasuryAddress` | `address` | Deployed Treasury address | -| `_votingAddress` | `address` | Deployed Voting address | -| `auth` | `address` | AuthorizedAddresses deployed address | -| `_events` | `address` | Deployed EventEmitter address | -| `_applicationPeriod` | `uint256` | Initial application period (in blocks) for pending listings | -| `_commitPeriod` | `uint256` | Number of blocks after challenge initiated in which votes can be committed | -| `_challengePeriod` | `uint256` | Number of blocks a challenge lasts before being finalized | -| `_exitPeriod` | `uint256` | Number of blocks exiting listings must wait before claiming stake | -| `_rewardPeriod` | `uint256` | The frequency (in blocks) with which validator rewards may be issued | +| Parameter | Type | Description | +| -------------------- | --------- | --------------------------------------------------------------------------- | +| `_treasuryAddress` | `address` | Deployed Treasury address. | +| `_votingAddress` | `address` | Deployed Voting address. | +| `_events` | `address` | Deployed EventEmitter address. | +| `_applicationPeriod` | `uint256` | Initial application period (in blocks) for pending listings. | +| `_commitPeriod` | `uint256` | Number of blocks after challenge initiated in which votes can be committed. | +| `_challengePeriod` | `uint256` | Number of blocks a challenge lasts before being finalized. | +| `_exitPeriod` | `uint256` | Number of blocks exiting listings must wait before claiming stake. | +| `_rewardPeriod` | `uint256` | The frequency (in blocks) with which validator rewards may be issued. | ### finalizeExit -Complete a listing exit +Finalize a listings exit. Allowing the account to safely remove the staked tokens and nullify the listing. #### Signature @@ -122,9 +124,9 @@ function finalizeExit(tendermintPublicKey bytes32) public #### Parameters: -| Parameter | Type | Description | -| --------------------- | --------- | --------------------------------- | -| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key | +| Parameter | Type | Description | +| --------------------- | --------- | ---------------------------------- | +| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key. | ### getChallenge @@ -140,7 +142,7 @@ function getChallenge(challengeId uint256) public view (tuple) | Parameter | Type | Description | | ------------- | --------- | ------------------------------------- | -| `challengeId` | `uint256` | The ID to retreive challenge data for | +| `challengeId` | `uint256` | The ID to retrieve challenge data for | #### Returns: @@ -148,7 +150,7 @@ The challenge indicated by the provided ID. ### getChallenges -Expose challenge data +Expose multiple challenges by is #### Signature @@ -158,9 +160,13 @@ function getChallenges(challengeIds uint256[]) public view (tuple[]) #### Parameters: -| Parameter | Type | Description | -| -------------- | ----------- | ------------ | -| `challengeIds` | `uint256[]` | challenge id | +| Parameter | Type | Description | +| -------------- | ----------- | --------------------- | +| `challengeIds` | `uint256[]` | challenge ids to read | + +#### Returns: + +Array of requested challenges ### getListing @@ -196,7 +202,7 @@ function getListings(pubKeys bytes32[]) public view (tuple[]) | Parameter | Type | Description | | --------- | ----------- | ---------------------------------------------- | -| `pubKeys` | `bytes32[]` | Hex encoded Tendermint public keys to retreive | +| `pubKeys` | `bytes32[]` | Hex encoded Tendermint public keys to retrieve | #### Returns: @@ -204,7 +210,7 @@ The array of listing structures corresponding to the provided keys. ### initExit -Initiate a listing exit +Initiate a listing exit. Immediately exit a pending listing or start the exit delay and remove validator power of the listing. #### Signature @@ -214,13 +220,30 @@ function initExit(tendermintPublicKey bytes32) public #### Parameters: -| Parameter | Type | Description | -| --------------------- | --------- | --------------------------------- | -| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key | +| Parameter | Type | Description | +| --------------------- | --------- | ---------------------------------- | +| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key. | + +### reduceReward + +Reduces the generating reward rate of a listing. This prevents the listing from needing to reapply when they amount of tokens they are generating is to high. + +#### Signature + +```solidity +function reduceReward(tendermintPublicKey bytes32, newRate int256) public +``` + +#### Parameters: + +| Parameter | Type | Description | +| --------------------- | --------- | --------------------------------------------- | +| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key. | +| `newRate` | `int256` | New reward rate in the units of ether/period. | ### registerListing -Register a listing +Register a listing. The listing will require the deposit of the at least the minimum stake balance. The tokens will now be vulnerable to be challenged but are not providing any valdator power. #### Signature @@ -230,25 +253,58 @@ function registerListing(tendermintPublicKey bytes32, tokensToStake uint256, rew #### Parameters: -| Parameter | Type | Description | -| --------------------- | --------- | ------------------------------------------------------------------------------- | -| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key | -| `tokensToStake` | `uint256` | The number of tokes at stake if the order is challenged | -| `rewardRate` | `int256` | The rate tokens are minted or destroyed over the active listings reward periods | -| `details` | `string` | A string value to represent support for claim (commonly an external link) | +| Parameter | Type | Description | +| --------------------- | --------- | ----------------------------------------------------------------------------------------------------- | +| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key. | +| `tokensToStake` | `uint256` | The number of tokes at stake if the order is challenged. | +| `rewardRate` | `int256` | The rate tokens are minted or destroyed over the active listings reward periods (ether/rewardPeriod). | +| `details` | `string` | A string value to represent support for claim (commonly an external link). | ### resolveChallenge -Resolve a challenge +Resolve a challenge. Pays out tokens to the winning staked party. Captures information to facilitate voter payout. #### Signature ```solidity -function resolveChallenge(pubKey bytes32) public +function resolveChallenge(tendermintPublicKey bytes32) public ``` #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | --------------------------------- | -| `pubKey` | `bytes32` | Hex encoded tendermint public key | +| Parameter | Type | Description | +| --------------------- | --------- | ---------------------------------- | +| `tendermintPublicKey` | `bytes32` | Hex encoded tendermint public key. | + +### transferOwnership + +Allows the current owner to transfer control of the contract to a newOwner. + +#### Signature + +```solidity +function transferOwnership(newOwner address) public +``` + +#### Parameters: + +| Parameter | Type | Description | +| ---------- | --------- | ------------------------------------- | +| `newOwner` | `address` | The address to transfer ownership to. | + +### updateConfigValue + +Updates the contract configuration. + +#### Signature + +```solidity +function updateConfigValue(index uint256, value uint256) public +``` + +#### Parameters: + +| Parameter | Type | Description | +| --------- | --------- | ---------------------------------------------- | +| `index` | `uint256` | The index of the parameter you wish to update. | +| `value` | `uint256` | The new value for the parameter. | diff --git a/packages/kosu-system-contracts/docs/Voting.md b/packages/kosu-system-contracts/docs/Voting.md index b4de66d5..5600f0a5 100644 --- a/packages/kosu-system-contracts/docs/Voting.md +++ b/packages/kosu-system-contracts/docs/Voting.md @@ -1,6 +1,6 @@ # Voting -Voting manages polls and votes on governance matters within the Kosu system. +Voting manages polls and votes on governance matters within the Kosu system. Poll resolution logic will be the responsibility of the contract utilizing this service. ## Contents @@ -18,7 +18,7 @@ Voting manages polls and votes on governance matters within the Kosu system. ### commitVote -Commit a vote in a poll to be later revealed +Commit a vote in a poll to be later revealed. The salt and option must be retained for a successful reveal. #### Signature @@ -28,15 +28,15 @@ function commitVote(_pollId uint256, _vote bytes32, _tokensToCommit uint256) pub #### Parameters: -| Parameter | Type | Description | -| ----------------- | --------- | ---------------------------------- | -| `_pollId` | `uint256` | Poll index to act upon | -| `_vote` | `bytes32` | Hash encoded vote | -| `_tokensToCommit` | `uint256` | Number of tokens to commit to vote | +| Parameter | Type | Description | +| ----------------- | --------- | ----------------------------------- | +| `_pollId` | `uint256` | Poll id to commit vote to. | +| `_vote` | `bytes32` | Hash encoded vote option with salt. | +| `_tokensToCommit` | `uint256` | Number of tokens to commit to vote. | ### constructor -Create a new voting engine +Initializes the voting contract with the shared event emitter and treasury contracts. #### Signature @@ -46,14 +46,14 @@ constructor(treasuryAddress address, _emitterAddress address) public #### Parameters: -| Parameter | Type | Description | -| ----------------- | --------- | ----------------------------- | -| `treasuryAddress` | `address` | Deployed Treasury address | -| `_emitterAddress` | `address` | Deployed EventEmitter address | +| Parameter | Type | Description | +| ----------------- | --------- | ------------------------------ | +| `treasuryAddress` | `address` | Deployed Treasury address. | +| `_emitterAddress` | `address` | Deployed EventEmitter address. | ### createPoll -Create a new poll to accept votes based on the configuration +Create a new poll. The commit and reveal periods must be provided. The creation of the poll is notified with an event from the shared EventEmitter. #### Signature @@ -63,10 +63,10 @@ function createPoll(_commitEndBlock uint256, _revealEndBlock uint256) public (ui #### Parameters: -| Parameter | Type | Description | -| ----------------- | --------- | ----------------------------------- | -| `_commitEndBlock` | `uint256` | Block number when commit phase ends | -| `_revealEndBlock` | `uint256` | Block number when reveal phase ends | +| Parameter | Type | Description | +| ----------------- | --------- | ------------------------------------ | +| `_commitEndBlock` | `uint256` | Block number when commit phase ends. | +| `_revealEndBlock` | `uint256` | Block number when reveal phase ends. | #### Returns: @@ -74,7 +74,7 @@ Poll index number. Will be used as the key for interacting with a vote. ### revealVote -Reveal a previously committed vote +Reveal a previously committed vote by providing the vote option and salt used to generate the vote hash. #### Signature @@ -84,15 +84,15 @@ function revealVote(_pollId uint256, _voteOption uint256, _voteSalt uint256) pub #### Parameters: -| Parameter | Type | Description | -| ------------- | --------- | --------------------------------------------- | -| `_pollId` | `uint256` | Poll index to act upon | -| `_voteOption` | `uint256` | User vote option | -| `_voteSalt` | `uint256` | Salt used to in hash to obfuscate vote option | +| Parameter | Type | Description | +| ------------- | --------- | --------------------------------------- | +| `_pollId` | `uint256` | Poll id to commit vote to. | +| `_voteOption` | `uint256` | Vote option used to generate vote hash. | +| `_voteSalt` | `uint256` | Salt used to generate vote hash. | ### totalRevealedTokens -Retreive the total number of tokens revealed for a finalized poll. +Retrieve the total number of tokens revealed for a finalized poll. #### Signature @@ -102,17 +102,17 @@ function totalRevealedTokens(_pollId uint256) public view (uint256) #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | --------------------------------------------- | -| `_pollId` | `uint256` | Poll index to check total revealed tokens for | +| Parameter | Type | Description | +| --------- | --------- | ---------------------------------------------- | +| `_pollId` | `uint256` | Poll index to check total revealed tokens for. | #### Returns: -The total number of tokens reveled in the poll. +The total number of tokens revealed in the poll. ### totalWinningTokens -Retreive the total number of tokens that voted on the winning side of a finalized poll. +Retrieve the total number of tokens that supported the winning option of a finalized poll. #### Signature @@ -122,17 +122,17 @@ function totalWinningTokens(_pollId uint256) public view (uint256) #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | -------------------------------------- | -| `_pollId` | `uint256` | Poll index to check winning tokens for | +| Parameter | Type | Description | +| --------- | --------- | --------------------------------------- | +| `_pollId` | `uint256` | Poll index to check winning tokens for. | #### Returns: -The uint number of tokens revealed for the winning option. +The uint number of tokens supporting the winning option. ### userWinningTokens -Retreive the number of tokens committed by a user for the winning option. +Retrieve the number of tokens committed by a user for the winning option. #### Signature @@ -144,12 +144,12 @@ function userWinningTokens(_pollId uint256, _user address) public view (uint256) | Parameter | Type | Description | | --------- | --------- | ---------------------------------------- | -| `_pollId` | `uint256` | Poll index to check winning tokens for | +| `_pollId` | `uint256` | Poll index to check winning tokens for. | | `_user` | `address` | Address of user to check winning tokens. | ### winningOption -Retreive the winning outcome for a finalized poll. +Retrieve the winning option for a finalized poll. #### Signature @@ -159,10 +159,10 @@ function winningOption(_pollId uint256) public view (uint256) #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | -------------------------------------- | -| `_pollId` | `uint256` | Poll index to check winning option for | +| Parameter | Type | Description | +| --------- | --------- | --------------------------------------- | +| `_pollId` | `uint256` | Poll index to check winning option for. | #### Returns: -The uint value of the winning outcome +The winning option. diff --git a/packages/kosu-system-contracts/docs/ZeroExV2SubContract.md b/packages/kosu-system-contracts/docs/ZeroExV2SubContract.md index 044d3d17..26d3621e 100644 --- a/packages/kosu-system-contracts/docs/ZeroExV2SubContract.md +++ b/packages/kosu-system-contracts/docs/ZeroExV2SubContract.md @@ -1,6 +1,6 @@ # ZeroExV2SubContract -Implementation of a sub contract that forwards a 0x - kosu order to the zero ex contract system +Implementation of a SubContract that forwards kosu orders with 0x resolution to the 0x exchange contract. ## Contents @@ -34,7 +34,7 @@ Tokens remaining to fill. ### constructor -Constructor +Initialize subContract with arguments json 0x Exchange address and the 0x erc20 proxy address. #### Signature @@ -72,7 +72,7 @@ Validity of order. ### participate -De-serializes ksou order data to 0x order and submits to the 0x exchange. +De-serializes ksou order data to 0x order and submits to the 0x exchange for final resolution. Finalizes by forwarding along any successfully exchanged tokens. #### Signature From d18f514ad90fd6d180be7c438f495e85bd390644 Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Sun, 25 Aug 2019 23:48:14 -0500 Subject: [PATCH 08/11] Adding readme with new test net. --- packages/kosu-system-contracts/README.md | 17 +++++++++++++++++ .../scripts/generateReadme.js | 4 ++++ 2 files changed, 21 insertions(+) diff --git a/packages/kosu-system-contracts/README.md b/packages/kosu-system-contracts/README.md index a0786fd0..086f9c69 100644 --- a/packages/kosu-system-contracts/README.md +++ b/packages/kosu-system-contracts/README.md @@ -43,3 +43,20 @@ Below are the deployed addresses for the core Kosu protocol contract system on t | [PosterRegistry](./contracts/poster/PosterRegistry.sol) | 08/19/19 | 0x7e6534b8205713246e91a14b462d2dbcac3ede17 | | [ValidatorRegistry](./contracts/validator/ValidatorRegistry.sol) | 08/19/19 | 0x301bb008f2a8a3cae9918743fe43428551392773 | | [ZeroExV2SubContract](./contracts/sub-contracts/ZeroExV2SubContract.sol) | 08/19/19 | 0x0265e7d1b094787cb13174e18a1cefc41279a6c9 | + +### Kosu CI Test + +- **Network ID:** 6175 +- **ETHNET URL:** `http://kosu-geth:8545` + +| Contract Name | Last Deploy Date | Deployed Address | +| ------------------------------------------------------------------------- | ---------------- | ------------------------------------------ | +| [OrderGateway](./contracts/external/OrderGateway.sol) | 08/20/19 | 0xb8fda6341f80cbae987ab5cd00dce502097e3152 | +| [AuthorizedAddresses](./contracts/access_control/AuthorizedAddresses.sol) | 08/20/19 | 0xe473109cb41c773fd2fe01e83c6e51356f9585d6 | +| [EventEmitter](./contracts/event/EventEmitter.sol) | 08/20/19 | 0x2f3afeff0914f33769cdfbf3fcf870c33b26c311 | +| [KosuToken](./contracts/lib/KosuToken.sol) | 08/20/19 | 0xcc868306d6188b2b12757a7c3926042b4d3c4e29 | +| [Treasury](./contracts/treasury/Treasury.sol) | 08/20/19 | 0x46572f9082dd2429c2c138fa9483a67d4f29d423 | +| [Voting](./contracts/voting/Voting.sol) | 08/20/19 | 0x5d60c93d8b48682cd387c8be7e9461b67ecfbea1 | +| [PosterRegistry](./contracts/poster/PosterRegistry.sol) | 08/20/19 | 0x7e6534b8205713246e91a14b462d2dbcac3ede17 | +| [ValidatorRegistry](./contracts/validator/ValidatorRegistry.sol) | 08/20/19 | 0x301bb008f2a8a3cae9918743fe43428551392773 | +| [ZeroExV2SubContract](./contracts/sub-contracts/ZeroExV2SubContract.sol) | 08/20/19 | 0x0265e7d1b094787cb13174e18a1cefc41279a6c9 | diff --git a/packages/kosu-system-contracts/scripts/generateReadme.js b/packages/kosu-system-contracts/scripts/generateReadme.js index ce77326b..8e513521 100644 --- a/packages/kosu-system-contracts/scripts/generateReadme.js +++ b/packages/kosu-system-contracts/scripts/generateReadme.js @@ -17,6 +17,10 @@ const NETWORKS = { name: "Kosu Dev PoA", endpoint: "https://ethnet.zaidan.io/kosu", }, + "6175": { + name: "Kosu CI Test", + endpoint: "http://kosu-geth:8545", + }, }; const PATHS = { From e43691735ebfc1f3522d3e5f53e5dc0846fbaf4d Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Mon, 26 Aug 2019 11:59:11 -0500 Subject: [PATCH 09/11] Fixing some typos. --- .../contracts/validator/ValidatorRegistry.sol | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/kosu-system-contracts/contracts/validator/ValidatorRegistry.sol b/packages/kosu-system-contracts/contracts/validator/ValidatorRegistry.sol index 8e5695b9..1abdcf53 100644 --- a/packages/kosu-system-contracts/contracts/validator/ValidatorRegistry.sol +++ b/packages/kosu-system-contracts/contracts/validator/ValidatorRegistry.sol @@ -129,7 +129,7 @@ contract ValidatorRegistry is Ownable { /** @dev Expose listing data for given public key. @notice Expose listing data for given public key. - @param pubKey Hex encoded tendermint public key + @param pubKey Hex encoded tendermint public key. @return The listing structure corresponding to the provided key. */ function getListing(bytes32 pubKey) public view returns (Listing memory) { @@ -139,7 +139,7 @@ contract ValidatorRegistry is Ownable { /** @dev Expose several listings provided multiple public keys. @notice Expose several listings provided multiple public keys. - @param pubKeys Hex encoded Tendermint public keys to retrieve + @param pubKeys Hex encoded Tendermint public keys to retrieve. @return The array of listing structures corresponding to the provided keys. */ function getListings(bytes32[] memory pubKeys) public view returns (Listing[] memory) { @@ -164,7 +164,7 @@ contract ValidatorRegistry is Ownable { /** @dev Expose challenge data for a given ID. @notice Expose challenge data for a given ID. - @param challengeId The ID to retrieve challenge data for + @param challengeId The ID to retrieve challenge data for. @return The challenge indicated by the provided ID. */ function getChallenge(uint challengeId) public view returns (Challenge memory) { @@ -172,9 +172,9 @@ contract ValidatorRegistry is Ownable { } - /** @dev Expose multiple challenges by is - @notice Expose multiple challenges by is - @param challengeIds challenge ids to read + /** @dev Expose multiple challenges by ids. + @notice Expose multiple challenges by ids. + @param challengeIds challenge ids to read. @return Array of requested challenges */ function getChallenges(uint[] memory challengeIds) public view returns (Challenge[] memory) { From d3dee22bb89c07eb123f6e7fa3962ecee3aa2202 Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Mon, 26 Aug 2019 12:14:16 -0500 Subject: [PATCH 10/11] Fixing a wording thing. --- .../kosu-system-contracts/contracts/event/EventEmitter.sol | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/kosu-system-contracts/contracts/event/EventEmitter.sol b/packages/kosu-system-contracts/contracts/event/EventEmitter.sol index 412cae00..6fd1d00b 100644 --- a/packages/kosu-system-contracts/contracts/event/EventEmitter.sol +++ b/packages/kosu-system-contracts/contracts/event/EventEmitter.sol @@ -18,8 +18,8 @@ contract EventEmitter is Authorizable { constructor(address auth) Authorizable(auth) public { } - /** @dev Emits a standard event from the Kosu contract system. The events can be decoded though the javascript library. - @notice Emits a standard event from the Kosu contract system. The events can be decoded though the javascript library. + /** @dev Emits a standard event from the Kosu contract system. The events can be decoded though the Kosu.js library. + @notice Emits a standard event from the Kosu contract system. The events can be decoded though the Kosu.js library. @param eventType String name/type of event. @param data Bytes32 encoded data to be emitted. @param stringData String containing optional additional information. From 34c21198170802d5a182f2c6eef29d93cea2fee8 Mon Sep 17 00:00:00 2001 From: Nick Freyaldenhoven Date: Mon, 26 Aug 2019 14:38:08 -0500 Subject: [PATCH 11/11] Regenerating documentation. --- .../docs/EventEmitter.md | 2 +- .../docs/ValidatorRegistry.md | 26 +++++++++---------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/packages/kosu-system-contracts/docs/EventEmitter.md b/packages/kosu-system-contracts/docs/EventEmitter.md index 161436ad..af08ba2d 100644 --- a/packages/kosu-system-contracts/docs/EventEmitter.md +++ b/packages/kosu-system-contracts/docs/EventEmitter.md @@ -28,7 +28,7 @@ constructor(auth address) public ### emitEvent -Emits a standard event from the Kosu contract system. The events can be decoded though the javascript library. +Emits a standard event from the Kosu contract system. The events can be decoded though the Kosu.js library. #### Signature diff --git a/packages/kosu-system-contracts/docs/ValidatorRegistry.md b/packages/kosu-system-contracts/docs/ValidatorRegistry.md index 20e0cc39..ac46553e 100644 --- a/packages/kosu-system-contracts/docs/ValidatorRegistry.md +++ b/packages/kosu-system-contracts/docs/ValidatorRegistry.md @@ -140,9 +140,9 @@ function getChallenge(challengeId uint256) public view (tuple) #### Parameters: -| Parameter | Type | Description | -| ------------- | --------- | ------------------------------------- | -| `challengeId` | `uint256` | The ID to retrieve challenge data for | +| Parameter | Type | Description | +| ------------- | --------- | -------------------------------------- | +| `challengeId` | `uint256` | The ID to retrieve challenge data for. | #### Returns: @@ -150,7 +150,7 @@ The challenge indicated by the provided ID. ### getChallenges -Expose multiple challenges by is +Expose multiple challenges by ids. #### Signature @@ -160,9 +160,9 @@ function getChallenges(challengeIds uint256[]) public view (tuple[]) #### Parameters: -| Parameter | Type | Description | -| -------------- | ----------- | --------------------- | -| `challengeIds` | `uint256[]` | challenge ids to read | +| Parameter | Type | Description | +| -------------- | ----------- | ---------------------- | +| `challengeIds` | `uint256[]` | challenge ids to read. | #### Returns: @@ -180,9 +180,9 @@ function getListing(pubKey bytes32) public view (tuple) #### Parameters: -| Parameter | Type | Description | -| --------- | --------- | --------------------------------- | -| `pubKey` | `bytes32` | Hex encoded tendermint public key | +| Parameter | Type | Description | +| --------- | --------- | ---------------------------------- | +| `pubKey` | `bytes32` | Hex encoded tendermint public key. | #### Returns: @@ -200,9 +200,9 @@ function getListings(pubKeys bytes32[]) public view (tuple[]) #### Parameters: -| Parameter | Type | Description | -| --------- | ----------- | ---------------------------------------------- | -| `pubKeys` | `bytes32[]` | Hex encoded Tendermint public keys to retrieve | +| Parameter | Type | Description | +| --------- | ----------- | ----------------------------------------------- | +| `pubKeys` | `bytes32[]` | Hex encoded Tendermint public keys to retrieve. | #### Returns: