From 6c82ebe9568dbab3b21dbbf88b562f97880e36c4 Mon Sep 17 00:00:00 2001 From: Greg Hysen Date: Fri, 28 Jun 2019 17:45:23 -0700 Subject: [PATCH] Added more documentation to interfaces --- .../staking/contracts/src/StakingProxy.sol | 19 ++++-- .../contracts/src/immutable/MixinStorage.sol | 4 +- .../contracts/src/interfaces/IStaking.sol | 61 ++----------------- .../src/interfaces/IStakingEvents.sol | 10 +++ .../src/interfaces/IStakingProxy.sol | 31 ++++++++-- .../contracts/src/interfaces/IStructs.sol | 29 ++++++--- .../src/stake/MixinDelegatedStake.sol | 2 +- 7 files changed, 80 insertions(+), 76 deletions(-) diff --git a/contracts/staking/contracts/src/StakingProxy.sol b/contracts/staking/contracts/src/StakingProxy.sol index d3ffd77eee..130025c2fc 100644 --- a/contracts/staking/contracts/src/StakingProxy.sol +++ b/contracts/staking/contracts/src/StakingProxy.sol @@ -20,16 +20,19 @@ pragma solidity ^0.5.5; import "./immutable/MixinStorage.sol"; import "./interfaces/IStakingProxy.sol"; +import "./sys/MixinOwnable.sol"; contract StakingProxy is IStakingProxy, MixinDeploymentConstants, MixinConstants, - MixinStorage + MixinStorage, + MixinOwnable { - address constant internal NIL_ADDRESS = 0x0000000000000000000000000000000000000000; + /// @dev Constructor. + /// @param _stakingContract Staking contract to delegate calls to. constructor(address _stakingContract) public { @@ -37,6 +40,7 @@ contract StakingProxy is stakingContract = _stakingContract; } + /// @dev Delegates calls to the staking contract, if it is set. // solhint-disable no-complex-fallback function () external @@ -82,17 +86,24 @@ contract StakingProxy is } } + /// @dev Attach a staking contract; future calls will be delegated to the staking contract. + /// Note that this is callable only by this contract's owner. + /// @param _stakingContract Address of staking contract. function attachStakingContract(address _stakingContract) external - //ownerOnly + onlyOwner { stakingContract = _stakingContract; + emit StakingContractAttachedToProxy(_stakingContract); } + /// @dev Detach the current staking contract. + /// Note that this is callable only by this contract's owner. function detachStakingContract() external - //ownerOnly + onlyOwner { stakingContract = NIL_ADDRESS; + emit StakingContractDetachedFromProxy(); } } \ No newline at end of file diff --git a/contracts/staking/contracts/src/immutable/MixinStorage.sol b/contracts/staking/contracts/src/immutable/MixinStorage.sol index bb16759cb3..c54d64c820 100644 --- a/contracts/staking/contracts/src/immutable/MixinStorage.sol +++ b/contracts/staking/contracts/src/immutable/MixinStorage.sol @@ -30,8 +30,6 @@ contract MixinStorage is MixinConstants { - // @TODO Add notes about which Mixin manages which state - // address of owner address internal owner; @@ -87,7 +85,7 @@ contract MixinStorage is // fees collected this epoch mapping (bytes32 => uint256) internal protocolFeesThisEpochByPool; - // + // pools that were active in the current epoch bytes32[] internal activePoolsThisEpoch; // mapping from POol Id to Shadow Rewards diff --git a/contracts/staking/contracts/src/interfaces/IStaking.sol b/contracts/staking/contracts/src/interfaces/IStaking.sol index d7713503d0..fedc54b16b 100644 --- a/contracts/staking/contracts/src/interfaces/IStaking.sol +++ b/contracts/staking/contracts/src/interfaces/IStaking.sol @@ -19,62 +19,9 @@ pragma solidity ^0.5.5; -/// THIS CONTRACT IS AUTO-GENERATED FROM INTERFACES IN `./core_interfaces` /// -contract IStaking { - - /// @dev Returns the current epoch. - function getCurrentEpoch() - public - view - returns (uint64); - - /// @dev Returns the current epoch period, measured in seconds. - /// Epoch period = [startTimeInSeconds..endTimeInSeconds) - function getEpochDurationInSeconds() - public - pure - returns (uint64); - - /// @dev Returns the start time in seconds of the current epoch. - /// Epoch period = [startTimeInSeconds..endTimeInSeconds) - function getCurrentEpochStartTimeInSeconds() - public - view - returns (uint64); - - /// @dev Returns the earliest end time in seconds of this epoch. - /// The next epoch can begin once this time is reached. - /// Epoch period = [startTimeInSeconds..endTimeInSeconds) - function getCurrentEpochEarliestEndTimeInSeconds() - public - view - returns (uint64); - - /// @dev Returns the current timelock period - function getCurrentTimelockPeriod() - public - view - returns (uint64); - - /// @dev Returns the length of a timelock period, measured in epochs. - /// Timelock period = [startEpoch..endEpoch) - function getTimelockDurationInEpochs() - public - pure - returns (uint64); - - /// @dev Returns the epoch that the current timelock period started at. - /// Timelock period = [startEpoch..endEpoch) - function getCurrentTimelockPeriodStartEpoch() - public - view - returns (uint64); - - /// @dev Returns the epoch that the current timelock period will end. - /// Timelock period = [startEpoch..endEpoch) - function getCurrentTimelockPeriodEndEpoch() - public - view - returns (uint64); +// solhint-disable no-empty-blocks +interface IStaking { + /// THIS INTERFACE IS LEFT INTENTIONALLY BLANK /// + /// @TODO Generate this file before deploying. } diff --git a/contracts/staking/contracts/src/interfaces/IStakingEvents.sol b/contracts/staking/contracts/src/interfaces/IStakingEvents.sol index 2e2c29b860..24a723eff3 100644 --- a/contracts/staking/contracts/src/interfaces/IStakingEvents.sol +++ b/contracts/staking/contracts/src/interfaces/IStakingEvents.sol @@ -3,20 +3,30 @@ pragma solidity ^0.5.5; interface IStakingEvents { + /// @dev Emitted by MixinStake when new Stake is minted. + /// @param owner of Stake. + /// @param amount of Stake minted. event StakeMinted( address owner, uint256 amount ); + /// @dev Emitted by MixinStake when Stake is burned. + /// @param owner of Stake. + /// @param amount of Stake burned. event StakeBurned( address owner, uint256 amount ); + /// @dev Emitted by MixinExchangeManager when an exchange is added. + /// @param exchangeAddress Address of new exchange. event ExchangeAdded( address exchangeAddress ); + /// @dev Emitted by MixinExchangeManager when an exchange is removed. + /// @param exchangeAddress Address of removed exchange. event ExchangeRemoved( address exchangeAddress ); diff --git a/contracts/staking/contracts/src/interfaces/IStakingProxy.sol b/contracts/staking/contracts/src/interfaces/IStakingProxy.sol index 6554fb2c41..26d52570f3 100644 --- a/contracts/staking/contracts/src/interfaces/IStakingProxy.sol +++ b/contracts/staking/contracts/src/interfaces/IStakingProxy.sol @@ -19,9 +19,32 @@ pragma solidity ^0.5.5; -interface IStakingProxy +interface IStakingProxy /* is IStaking */ { - /*function attachStakingContract(address stakingContract) external; - function detachStakingContract() external; - function () external payable;*/ + + /// @dev Emitted by StakingProxy when a staking contract is attached. + /// @param newStakingContractAddress Address of newly attached staking contract. + event StakingContractAttachedToProxy( + address newStakingContractAddress + ); + + /// @dev Emitted by StakingProxy when a staking contract is detached. + event StakingContractDetachedFromProxy(); + + /// @dev Delegates calls to the staking contract, if it is set. + // solhint-disable no-complex-fallback + function () + external + payable; + + /// @dev Attach a staking contract; future calls will be delegated to the staking contract. + /// Note that this is callable only by this contract's owner. + /// @param _stakingContract Address of staking contract. + function attachStakingContract(address _stakingContract) + external; + + /// @dev Detach the current staking contract. + /// Note that this is callable only by this contract's owner. + function detachStakingContract() + external; } diff --git a/contracts/staking/contracts/src/interfaces/IStructs.sol b/contracts/staking/contracts/src/interfaces/IStructs.sol index 02f4fc72b1..6f95c2a76b 100644 --- a/contracts/staking/contracts/src/interfaces/IStructs.sol +++ b/contracts/staking/contracts/src/interfaces/IStructs.sol @@ -21,7 +21,7 @@ pragma solidity ^0.5.5; interface IStructs { - // Allowed signature types. + /// @dev Allowed signature types. enum SignatureType { Illegal, // 0x00, default value Invalid, // 0x01 @@ -31,25 +31,40 @@ interface IStructs { NSignatureTypes // 0x05, number of signature types. Always leave at end. } + /// @dev Required fields for a maker to approve a staking pool. + /// @param poolId Unique Id of staking pool. + /// @param makerAddress Address of maker who has approved the pool. struct StakingPoolApproval { bytes32 poolId; address makerAddress; } - struct Timelock { - uint64 lockedAt; - uint96 total; - uint96 pending; - } - + /// @dev State for Staking Pools (see MixinStakingPool). + /// @param operatorAddress Address of pool operator. + /// @param operatorShare Portion of pool rewards owned by operator. struct Pool { address payable operatorAddress; uint8 operatorShare; } + /// @dev State for a pool that actively traded during the current epoch. + /// (see MixinExchangeFees). + /// @param poolId Unique Id of staking pool. + /// @param feesCollected Fees collected in ETH by this pool in the current epoch. + /// @param weightedStake Amount of weighted stake currently held by the pool. struct ActivePool { bytes32 poolId; uint256 feesCollected; uint256 weightedStake; } + + /// @dev Tracks timelocked stake (see MixinTimelockedStake). + /// @param lockedAt The Timelock Period that stake was most recently locked at. + /// @param total Amount of stake that is timelocked. + /// @param pending Stake pending to be un-timelocked next Timelock Period. + struct Timelock { + uint64 lockedAt; + uint96 total; + uint96 pending; + } } \ No newline at end of file diff --git a/contracts/staking/contracts/src/stake/MixinDelegatedStake.sol b/contracts/staking/contracts/src/stake/MixinDelegatedStake.sol index 405cf52e3e..4e02906ff3 100644 --- a/contracts/staking/contracts/src/stake/MixinDelegatedStake.sol +++ b/contracts/staking/contracts/src/stake/MixinDelegatedStake.sol @@ -155,7 +155,7 @@ contract MixinDelegatedStake is amount, _delegatedStakeToPoolByOwner, _delegatedStakeByPoolId - ); + ); // decrement how much stake the owner has delegated delegatedStakeByOwner[owner] = _delegatedStakeByOwner._sub(amount);