Merge pull request #1349 from keep-network/api

Client interfaces for random beacon and token staking

Author: nkuba

contracts/solidity/contracts/IRandomBeacon.sol

@@ -0,0 +1,69 @@
+
+pragma solidity ^0.5.4;
+
+/**
+ * @title Keep Random Beacon
+ *
+ * @notice Keep Random Beacon generates verifiable randomness that is resistant
+ * to bad actors both in the relay network and on the anchoring blockchain.
+ */
+interface IRandomBeacon {
+
+    /**
+     * @notice Provides the customer with an estimated entry fee in wei to use
+     * in the request. The fee estimate is only valid for the transaction it is
+     * called in, so the customer must make the request immediately after
+     * obtaining the estimate. Insufficient payment will lead to the request
+     * being rejected and the transaction reverted.
+     *
+     * The customer may decide to provide more ether for an entry fee than
+     * estimated by this function. This is especially heplful when callback gas
+     * cost fluctuates. Any surplus between the passed fee and the actual cost
+     * of producing an entry and executing a callback is returned back to the
+     * customer.
+     * @param callbackGas Gas required for the callback.
+     */
+    function entryFeeEstimate(uint256 callbackGas) external view returns (uint256);
+
+    /**
+     * @notice Submits a request to generate a new relay entry. Executes the
+     * provided callback with the generated entry and emits
+     * `RelayEntryGenerated(uint256 requestId, uint256 entry)` event.
+     *
+     * @dev Beacon does not support concurrent relay requests. No new requests
+     * should be made while the beacon is already processing another request.
+     * Requests made while the beacon is busy will be rejected and the
+     * transaction reverted.
+
+     * @param callbackContract Callback contract address. Callback is called
+     * once a new relay entry has been generated.
+     * @param callbackMethod Callback contract method signature. String
+     * representation of your method with a single
+     * uint256 input parameter i.e. "relayEntryCallback(uint256)".
+     * @param callbackGas Gas required for the callback.
+     * The customer needs to ensure they provide a sufficient callback gas
+     * to cover the gas fee of executing the callback. Any surplus is returned
+     * to the customer. If the callback gas amount turns to be not enough to
+     * execute the callback, callback execution is skipped.
+     * @return An uint256 representing uniquely generated relay request ID
+     */
+    function requestRelayEntry(
+        address callbackContract,
+        string calldata callbackMethod,
+        uint256 callbackGas
+    ) external payable returns (uint256);
+
+    /**
+     * @notice Submits a request to generate a new relay entry. Emits
+     * `RelayEntryGenerated(uint256 requestId, uint256 entry)` event for the
+     * generated entry.
+     *
+     * @dev Beacon does not support concurrent relay requests. No new requests
+     * should be made while the beacon is already processing another request.
+     * Requests made while the beacon is busy will be rejected and the
+     * transaction reverted.
+     *
+     * @return An uint256 representing uniquely generated relay request ID
+     */
+    function requestRelayEntry() external payable returns (uint256);
+}

contracts/solidity/contracts/ITokenStaking.sol

@@ -0,0 +1,33 @@
+pragma solidity ^0.5.4;
+
+/**
+ * @title Keep Network Token Staking
+ *
+ * @notice Provides an information about eligible stake of network operators.
+ * The Keep network uses staking of tokens to enforce correct behavior.
+ * Anyone with tokens can stake them, setting them aside as collateral for
+ * network operations. Staked tokens are delegated to an operator address who
+ * performs work for operator contracts. Operators can earn rewards from
+ * contributing to the network, but if they misbehave their collateral can be
+ * taken away (stake slashing) as punishment.
+ */
+interface ITokenStaking {
+
+    /**
+     * @dev Gets the eligible stake balance of the specified operator.
+     * An eligible stake is a stake that passed the initialization period
+     * and is not currently undelegating. Also, the operator had to approve
+     * the specified operator contract.
+     *
+     * Operator with a minimum required amount of eligible stake can join the
+     * network and participate in new work selection.
+     *
+     * @param _operator Address of stake operator.
+     * @param _operatorContract Address of operator contract.
+     * @return Eligible stake balance.
+     */
+    function eligibleStake(
+        address _operator,
+        address _operatorContract
+    ) external view returns (uint256 balance);
+}

contracts/solidity/contracts/KeepRandomBeaconServiceImplV1.sol

@@ -5,6 +5,7 @@ import "openzeppelin-solidity/contracts/utils/ReentrancyGuard.sol";
 import "./utils/AddressArrayUtils.sol";
 import "./DelayedWithdrawal.sol";
 import "./Registry.sol";
+import "./IRandomBeacon.sol";
 
 
 interface OperatorContract {
@@ -29,7 +30,7 @@ interface OperatorContract {
  * Warning: you can't set constants directly in the contract and must use initialize()
  * please see openzeppelin upgradeable contracts approach for more info.
  */
-contract KeepRandomBeaconServiceImplV1 is DelayedWithdrawal, ReentrancyGuard {
+contract KeepRandomBeaconServiceImplV1 is DelayedWithdrawal, ReentrancyGuard, IRandomBeacon {
     using SafeMath for uint256;
     using AddressArrayUtils for address[];
 

contracts/solidity/contracts/TokenStaking.sol

@@ -3,6 +3,7 @@ pragma solidity ^0.5.4;
 import "./StakeDelegatable.sol";
 import "./utils/UintArrayUtils.sol";
 import "./Registry.sol";
+import "./ITokenStaking.sol";
 
 
 /**
@@ -11,7 +12,7 @@ import "./Registry.sol";
  * A holder of the specified token can stake delegate its tokens to this contract
  * and recover the stake after undelegation period is over.
  */
-contract TokenStaking is StakeDelegatable {
+contract TokenStaking is StakeDelegatable, ITokenStaking {
 
     using UintArrayUtils for uint256[];