Correct throttle interface code implementation

Signed-off-by: lash <dev@holbrook.no>

.gitignore

@@ -4,4 +4,5 @@ build/
 dist/
 solidity/*.json
 solidity/*.bin
-.venv
+*.egg-info
+.venv

README.md

@@ -0,0 +1,53 @@
+# eth-faucet
+
+A faucet implementation for ETH gas tokens, implementing the [CIC Faucet](https://git.grassecon.net/cicnet/cic-contracts#faucet) interface.
+
+
+## Setup
+
+Firstly, the faucet contract must be funded before use. It can be funded simply by sending gas tokens to it as a normal transaction.
+
+Secondly, the amount of gas tokens to emit must be changed using the `setAmount()` method. Only the contract "owner" or a "writer" (see below) may change the amount. The amount can be changed again at any time, until sealed.
+
+
+## Usage
+
+To receive gas tokens from the faucet, the method `giveTo(address)` or `gimme()` is used. The latter will send gas tokens to the address that signed the transaction.
+
+
+## Restricting accounts
+
+Usage of the faucet may be restricted by which addresses can request gas tokens from it.
+
+The list must be provided by a contract implementing the [CIC ACL](https://git.grassecon.net/cicnet/cic-contracts#acl) interface. The contract to use is defined using the `setRegistry()` method.
+
+
+## Restricting usage frequency
+
+Usage of the faucet may also be restricted by time delay. 
+
+The usage control must be provided by a smart contract implementing the [CIC Throttle](https://git.grassecon.net/cicnet/cic-contracts#throttle) interface. The contract to use is defined using the `setPeriodChecker()` method.
+
+
+### Example usage frequency controller
+
+The `PeriodSimple` contract provided by this repository demonstrates an implementation of the usage frequency restriction.
+
+Only a single address has access to call the `poke(address)` method. This address is typically the contract providing the resource, and is defined by calling the `setPoker(address)` method.
+
+The number of seconds that must pass between each usage can be set using `setPeriod()`
+
+Using `setBalanceThreshold()` a maximum balance can be defined, to disallow use for addresses holding higher balances. (Note that this does not provide any real protection against agents, for example non-custioal wallets, that can forward the gas tokens at will).
+
+
+## Sealing the contracts
+
+The faucet contract implements the [CIC Seal](https://git.grassecon.net/cicnet/cic-contracts#seal) interface to enable sealing the parameters defining its behavior.
+
+The parameters that can be sealed are:
+
+- *Registry*, blocking the use of the `setRegistry()` method.
+- *Period checker*, blocking the use of the `setPeriodChecker()` method.
+- *Value*, blocking the use of the `setAmount()` method.
+
+The PeriodSimple contract does not implement the seal, but may discard ownedship through the [EIP173](https://eips.ethereum.org/EIPS/eip-173) interface, after which no parameters changing behavior can be modified.

python/eth_faucet/data/EthFaucet.json

@@ -1 +1 @@
-[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_amount","type":"uint256"}],"name":"FaucetAmountChange","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"_recipient","type":"address"},{"indexed":true,"internalType":"address","name":"_token","type":"address"},{"indexed":false,"internalType":"uint256","name":"_amount","type":"uint256"}],"name":"Give","type":"event"},{"anonymous":false,"inputs":[],"name":"ImNotGassy","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint256","name":"_sealState","type":"uint256"},{"indexed":false,"internalType":"address","name":"_registry","type":"address"},{"indexed":false,"internalType":"address","name":"_periodChecker","type":"address"}],"name":"SealStateChange","type":"event"},{"inputs":[{"internalType":"address","name":"_recipient","type":"address"}],"name":"check","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"gimme","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_recipient","type":"address"}],"name":"giveTo","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"maxSealState","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"nextTime","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"periodChecker","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"registry","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_state","type":"uint256"}],"name":"seal","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"sealState","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_v","type":"uint256"}],"name":"setAmount","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_checker","type":"address"}],"name":"setPeriodChecker","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_registry","type":"address"}],"name":"setRegistry","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"token","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"pure","type":"function"},{"inputs":[],"name":"tokenAmount","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"stateMutability":"payable","type":"receive"}]
+[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_amount","type":"uint256"}],"name":"FaucetAmountChange","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"_recipient","type":"address"},{"indexed":true,"internalType":"address","name":"_token","type":"address"},{"indexed":false,"internalType":"uint256","name":"_amount","type":"uint256"}],"name":"Give","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint256","name":"_sealState","type":"uint256"},{"indexed":false,"internalType":"address","name":"_registry","type":"address"},{"indexed":false,"internalType":"address","name":"_periodChecker","type":"address"}],"name":"SealStateChange","type":"event"},{"inputs":[{"internalType":"address","name":"_recipient","type":"address"}],"name":"check","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"gimme","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_recipient","type":"address"}],"name":"giveTo","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"maxSealState","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"nextBalance","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"nextTime","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"periodChecker","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"registry","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_state","type":"uint256"}],"name":"seal","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"sealState","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_v","type":"uint256"}],"name":"setAmount","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_checker","type":"address"}],"name":"setPeriodChecker","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_registry","type":"address"}],"name":"setRegistry","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"bytes4","name":"_sum","type":"bytes4"}],"name":"supportsInterface","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"pure","type":"function"},{"inputs":[],"name":"token","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"tokenAmount","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"stateMutability":"payable","type":"receive"}]

python/eth_faucet/data/EthFaucet.metadata.json

@@ -1 +1 @@
-{"compiler":{"version":"0.8.18+commit.87f61d96"},"language":"Solidity","output":{"abi":[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_amount","type":"uint256"}],"name":"FaucetAmountChange","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"_recipient","type":"address"},{"indexed":true,"internalType":"address","name":"_token","type":"address"},{"indexed":false,"internalType":"uint256","name":"_amount","type":"uint256"}],"name":"Give","type":"event"},{"anonymous":false,"inputs":[],"name":"ImNotGassy","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint256","name":"_sealState","type":"uint256"},{"indexed":false,"internalType":"address","name":"_registry","type":"address"},{"indexed":false,"internalType":"address","name":"_periodChecker","type":"address"}],"name":"SealStateChange","type":"event"},{"inputs":[{"internalType":"address","name":"_recipient","type":"address"}],"name":"check","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"gimme","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_recipient","type":"address"}],"name":"giveTo","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"maxSealState","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"nextTime","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"periodChecker","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"registry","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_state","type":"uint256"}],"name":"seal","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"sealState","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_v","type":"uint256"}],"name":"setAmount","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_checker","type":"address"}],"name":"setPeriodChecker","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_registry","type":"address"}],"name":"setRegistry","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"token","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"pure","type":"function"},{"inputs":[],"name":"tokenAmount","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"stateMutability":"payable","type":"receive"}],"devdoc":{"kind":"dev","methods":{},"version":1},"userdoc":{"kind":"user","methods":{},"version":1}},"settings":{"compilationTarget":{"EthFaucet.sol":"EthFacuet"},"evmVersion":"byzantium","libraries":{},"metadata":{"bytecodeHash":"ipfs"},"optimizer":{"enabled":false,"runs":200},"remappings":[]},"sources":{"EthFaucet.sol":{"keccak256":"0x914fa90608a36d5d6082a1bdba168c849a3ea34d70d3dd6e1fef143554840f19","license":"GPL-3.0-or-later","urls":["bzz-raw://b4efbed22465930f683933bd5b4f74a74d1f53c0c34a1231fbedcff92a3eeba2","dweb:/ipfs/QmT6szY5nAEs1megXscAsYkM9rke8M8VLj3MrQEP5hTekn"]}},"version":1}
+{"compiler":{"version":"0.8.19+commit.7dd6d404"},"language":"Solidity","output":{"abi":[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_amount","type":"uint256"}],"name":"FaucetAmountChange","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"_recipient","type":"address"},{"indexed":true,"internalType":"address","name":"_token","type":"address"},{"indexed":false,"internalType":"uint256","name":"_amount","type":"uint256"}],"name":"Give","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"uint256","name":"_sealState","type":"uint256"},{"indexed":false,"internalType":"address","name":"_registry","type":"address"},{"indexed":false,"internalType":"address","name":"_periodChecker","type":"address"}],"name":"SealStateChange","type":"event"},{"inputs":[{"internalType":"address","name":"_recipient","type":"address"}],"name":"check","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"gimme","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_recipient","type":"address"}],"name":"giveTo","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"maxSealState","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"nextBalance","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"nextTime","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"periodChecker","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"registry","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_state","type":"uint256"}],"name":"seal","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"sealState","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_v","type":"uint256"}],"name":"setAmount","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_checker","type":"address"}],"name":"setPeriodChecker","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_registry","type":"address"}],"name":"setRegistry","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"bytes4","name":"_sum","type":"bytes4"}],"name":"supportsInterface","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"pure","type":"function"},{"inputs":[],"name":"token","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"tokenAmount","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"stateMutability":"payable","type":"receive"}],"devdoc":{"kind":"dev","methods":{},"version":1},"userdoc":{"kind":"user","methods":{},"version":1}},"settings":{"compilationTarget":{"EthFaucet.sol":"EthFaucet"},"evmVersion":"byzantium","libraries":{},"metadata":{"bytecodeHash":"ipfs"},"optimizer":{"enabled":false,"runs":200},"remappings":[]},"sources":{"EthFaucet.sol":{"keccak256":"0x7775eaa388b81feca34dfb765dc6ccdf8216148c90e686689bd1340547e8ee88","license":"AGPL-3.0-or-later","urls":["bzz-raw://acb652ac132bcf3b63819e7311e07ad65f982c4d470f322ef91f147d462e4559","dweb:/ipfs/QmPNUaLd4c23K1RcHYWqPSfw8ix8ZbK3PdgFXD8iDMo2Fg"]}},"version":1}

python/eth_faucet/data/PeriodSimple.json

@@ -1 +1 @@
-[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_value","type":"uint256"}],"name":"BalanceThresholdChange","type":"event"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_value","type":"uint256"}],"name":"PeriodChange","type":"event"},{"inputs":[],"name":"balanceThreshold","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"check","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"","type":"address"}],"name":"lastUsed","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"next","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"period","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"poke","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"poker","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_threshold","type":"uint256"}],"name":"setBalanceThreshold","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint256","name":"_period","type":"uint256"}],"name":"setPeriod","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_poker","type":"address"}],"name":"setPoker","outputs":[],"stateMutability":"nonpayable","type":"function"}]
+[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_value","type":"uint256"}],"name":"BalanceThresholdChange","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"previousOwner","type":"address"},{"indexed":true,"internalType":"address","name":"newOwner","type":"address"}],"name":"OwnershipTransferred","type":"event"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_value","type":"uint256"}],"name":"PeriodChange","type":"event"},{"inputs":[],"name":"balanceThreshold","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"have","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"","type":"address"}],"name":"lastUsed","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"next","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"period","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"poke","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"poker","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_threshold","type":"uint256"}],"name":"setBalanceThreshold","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint256","name":"_period","type":"uint256"}],"name":"setPeriod","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_poker","type":"address"}],"name":"setPoker","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"bytes4","name":"_sum","type":"bytes4"}],"name":"supportsInterface","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"pure","type":"function"},{"inputs":[{"internalType":"address","name":"_newOwner","type":"address"}],"name":"transferOwnership","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"}]

python/eth_faucet/data/PeriodSimple.metadata.json

@@ -1 +1 @@
-{"compiler":{"version":"0.8.18+commit.87f61d96"},"language":"Solidity","output":{"abi":[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_value","type":"uint256"}],"name":"BalanceThresholdChange","type":"event"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_value","type":"uint256"}],"name":"PeriodChange","type":"event"},{"inputs":[],"name":"balanceThreshold","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"check","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"","type":"address"}],"name":"lastUsed","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"next","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"period","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"poke","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"poker","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_threshold","type":"uint256"}],"name":"setBalanceThreshold","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint256","name":"_period","type":"uint256"}],"name":"setPeriod","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_poker","type":"address"}],"name":"setPoker","outputs":[],"stateMutability":"nonpayable","type":"function"}],"devdoc":{"kind":"dev","methods":{},"version":1},"userdoc":{"kind":"user","methods":{},"version":1}},"settings":{"compilationTarget":{"PeriodSimple.sol":"PeriodSimple"},"evmVersion":"byzantium","libraries":{},"metadata":{"bytecodeHash":"ipfs"},"optimizer":{"enabled":false,"runs":200},"remappings":[]},"sources":{"PeriodSimple.sol":{"keccak256":"0x45faa9b0307c14cd87913aa6719092b693d47962285f659d1d01680ee9820527","license":"GPL-3.0-or-later","urls":["bzz-raw://29186cc92b9f6324e2043abe9ac74787866992c00ffeb0e3fc81d345d8c04ed1","dweb:/ipfs/QmXJaGaWBBFbdyQWaAicjXN6aC2w5Yvr97kXVVimHWAN7i"]}},"version":1}
+{"compiler":{"version":"0.8.19+commit.7dd6d404"},"language":"Solidity","output":{"abi":[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_value","type":"uint256"}],"name":"BalanceThresholdChange","type":"event"},{"anonymous":false,"inputs":[{"indexed":true,"internalType":"address","name":"previousOwner","type":"address"},{"indexed":true,"internalType":"address","name":"newOwner","type":"address"}],"name":"OwnershipTransferred","type":"event"},{"anonymous":false,"inputs":[{"indexed":false,"internalType":"uint256","name":"_value","type":"uint256"}],"name":"PeriodChange","type":"event"},{"inputs":[],"name":"balanceThreshold","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"have","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"","type":"address"}],"name":"lastUsed","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"next","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"owner","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[],"name":"period","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"address","name":"_subject","type":"address"}],"name":"poke","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"poker","outputs":[{"internalType":"address","name":"","type":"address"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"_threshold","type":"uint256"}],"name":"setBalanceThreshold","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint256","name":"_period","type":"uint256"}],"name":"setPeriod","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"address","name":"_poker","type":"address"}],"name":"setPoker","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"bytes4","name":"_sum","type":"bytes4"}],"name":"supportsInterface","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"pure","type":"function"},{"inputs":[{"internalType":"address","name":"_newOwner","type":"address"}],"name":"transferOwnership","outputs":[{"internalType":"bool","name":"","type":"bool"}],"stateMutability":"nonpayable","type":"function"}],"devdoc":{"kind":"dev","methods":{},"version":1},"userdoc":{"kind":"user","methods":{},"version":1}},"settings":{"compilationTarget":{"PeriodSimple.sol":"PeriodSimple"},"evmVersion":"byzantium","libraries":{},"metadata":{"bytecodeHash":"ipfs"},"optimizer":{"enabled":false,"runs":200},"remappings":[]},"sources":{"PeriodSimple.sol":{"keccak256":"0xdfc13eb19d32a0b20d1b73bde4d1ba7e36ed8a7b7cd1aee27f82204346acb31a","license":"AGPL-3.0-or-later","urls":["bzz-raw://72df3d89a4d080e1b4a4ac791bc3d330e496be2d5175360ca7c73ce1fab40337","dweb:/ipfs/QmNiRd5nS1uaKGThu9va6Zvm6AzSo4CW3vTN4gDZgfJL2z"]}},"version":1}

python/eth_faucet/faucet.py

@@ -104,4 +104,3 @@ class EthFaucet(Faucet):
         o['params'].append('latest')
         o = j.finalize(o)
         return o
-

python/requirements.txt

@@ -1,3 +1,3 @@
 chainlib-eth~=0.4.17
 chainlib~=0.4.12
-erc20-faucet~=0.7.0
+erc20-faucet~=0.8.0

python/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = eth-faucet
-version = 0.3.2
+version = 0.4.1
 description = Gas token gifter with controls from time intervals, amounts and access.
 author = Louis Holbrook
 author_email = dev@holbrook.no
@@ -23,7 +23,7 @@ licence_files =
 
 [options]
 include_package_data = True
-python_requires = >= 3.6
+python_requires = >= 3.8
 packages = 
 	eth_faucet
 	eth_faucet.runnable

solidity/EthFaucet.sol

@@ -1,29 +1,42 @@
-pragma solidity >0.8.0;
+pragma solidity >=0.8.0;
 
-// SPDX-License-Identifier: GPL-3.0-or-later
+// SPDX-License-Identifier: AGPL-3.0-or-later
 
-contract EthFacuet {
+contract EthFaucet {
 
+	// Implements ERC173
 	address public owner;
 	address public registry;
 	address public periodChecker;
+
+	// Implements Faucet
+	address constant public token = address(0);
+
+	// Implements Seal
 	uint256 public sealState;
+
 	uint256 amount;
 
 	uint8 constant REGISTRY_STATE = 1;
 	uint8 constant PERIODCHECKER_STATE = 2;
 	uint8 constant VALUE_STATE = 4;
+	// Implements Seal
 	uint256 constant public maxSealState = 7;
 
+	// Implements Faucet
 	event Give(address indexed _recipient, address indexed _token, uint256 _amount);
+	// Implements Faucet
 	event FaucetAmountChange(uint256 _amount);
+
+	// Implements Seal
 	event SealStateChange(uint256 indexed _sealState, address _registry, address _periodChecker);
-	event ImNotGassy();
 
 	constructor() {
 		owner = msg.sender;
 	}
 
+	// Set the given seal bits.
+	// Reverts if any bits are already set, if bit value is out of bounds.
 	function seal(uint256 _state) public returns(uint256) {
 		require(_state < 8, 'ERR_INVALID_STATE');
 		require(_state & sealState == 0, 'ERR_ALREADY_LOCKED');
@@ -32,6 +45,8 @@ contract EthFacuet {
 		return uint256(sealState);
 	}
 
+	// Change faucet amount.
+	// Reverts if VALUE_STATE seal is set.
 	function setAmount(uint256 _v) public returns(uint256) {
 		require(msg.sender == owner, 'ERR_NOT_OWNER');
 		require(sealState & VALUE_STATE == 0, 'ERR_SEALED');
@@ -40,6 +55,8 @@ contract EthFacuet {
 		return amount;
 	}
 
+	// Set period checker contract backend.
+	// Reverts if PERIODCHECKER_STATE seal is set
 	function setPeriodChecker(address _checker) public {
 		require(msg.sender == owner, 'ERR_NOT_OWNER');
 		require(sealState & PERIODCHECKER_STATE == 0, 'ERR_SEALED');
@@ -47,6 +64,8 @@ contract EthFacuet {
 		emit SealStateChange(sealState, registry, periodChecker);
 	}
 
+	// Set accounts index (Access Control List - ACL) backend.
+	// Reverts if REGISTRY_STATE seal is set
 	function setRegistry(address _registry) public {
 		require(msg.sender == owner, 'ERR_NOT_OWNER');
 		require(sealState & REGISTRY_STATE == 0, 'ERR_SEALED');
@@ -54,6 +73,8 @@ contract EthFacuet {
 		emit SealStateChange(sealState, registry, periodChecker);
 	}
 
+	// Return true if period checker backend allows usage of the faucet.
+	// Will always return true if period checker contract address has not been set.
 	function checkPeriod(address _recipient) private returns(bool) {
 		bool _ok;
 		bytes memory _result;
@@ -62,13 +83,15 @@ contract EthFacuet {
 			return true;
 		}
 
-		(_ok, _result) = periodChecker.call(abi.encodeWithSignature("check(address)", _recipient));
+		(_ok, _result) = periodChecker.call(abi.encodeWithSignature("have(address)", _recipient));
 		if (!_ok) {
 			revert('ERR_PERIOD_BACKEND');
 		}
 		return _result[31] == 0x01;
 	}
 
+	// Return true if recipient has been added to the ACL.
+	// Will always return true if ACL contract address has not been set.
 	function checkRegistry(address _recipient) private returns(bool) {
 		bool _ok;
 		bytes memory _result;
@@ -84,10 +107,13 @@ contract EthFacuet {
 		return _result[31] == 0x01;
 	}
 
+	// Return false if contract does not have sufficient gas token balance to cover a single use.
+	// Used as backend for check.
 	function checkBalance() private view returns(bool) {
 		return amount <= address(this).balance;
 	}
 
+	// Check if a faucet usage attempt would succeed for the given recipient in the current contract state.
 	function check(address _recipient) public returns(bool) {
 		if (!checkPeriod(_recipient)) {
 			return false;
@@ -97,7 +123,8 @@ contract EthFacuet {
 		}
 		return checkBalance();
 	}
-	
+
+	// Execute a single faucet usage for recipient.
 	function checkAndPoke(address _recipient) private returns(bool){
 		bool _ok;
 		bytes memory _result;
@@ -124,6 +151,7 @@ contract EthFacuet {
 		return true;
 	}
 
+	// Implements Faucet
 	function gimme() public returns(uint256) {
 		require(checkAndPoke(msg.sender));
 		payable(msg.sender).transfer(amount);
@@ -131,6 +159,7 @@ contract EthFacuet {
 		return amount;
 	}
 
+	// Implements Faucet
 	function giveTo(address _recipient) public returns(uint256) {
 		require(checkAndPoke(_recipient));
 		payable(_recipient).transfer(amount);
@@ -138,6 +167,7 @@ contract EthFacuet {
 		return amount;
 	}
 
+	// Implements Faucet
 	function nextTime(address _subject) public returns(uint256) {
 		bool _ok;
 		bytes memory _result;
@@ -149,14 +179,41 @@ contract EthFacuet {
 		return uint256(bytes32(_result));
 	}
 
+	// Implements Faucet
+	function nextBalance(address _subject) public returns(uint256) {
+		bool _ok;
+		bytes memory _result;
+
+		(_ok, _result) = periodChecker.call(abi.encodeWithSignature("balanceThreshold()", _subject));
+		if (!_ok) {
+			revert('ERR_PERIOD_BACKEND_ERROR');
+		}
+		return uint256(bytes32(_result));
+
+	}
+
+	// Implements Faucet
 	function tokenAmount() public view returns(uint256) {
 		return amount;
 	}
 
-	function token() public pure returns(address) {
-		return address(0);
-	}
-
 	receive () payable external {
 	}
+
+	// Implements ERC165
+	function supportsInterface(bytes4 _sum) public pure returns (bool) {
+		if (_sum == 0x01ffc9a7) { // ERC165
+			return true;
+		}
+		if (_sum == 0x9493f8b2) { // ERC173
+			return true;
+		}
+		if (_sum == 0x1a3ac634) { // Faucet
+			return true;
+		}
+		if (_sum == 0x0d7491f8) { // Seal
+			return true;
+		}
+		return false;
+	}
 }

solidity/PeriodSimple.sol

@@ -1,6 +1,6 @@
-pragma solidity >0.8.0;
+pragma solidity >=0.8.0;
 
-// SPDX-License-Identifier: GPL-3.0-or-later
+// SPDX-License-Identifier: AGPL-3.0-or-later
 
 contract PeriodSimple {
 
@@ -12,6 +12,10 @@ contract PeriodSimple {
 
 	event PeriodChange(uint256 _value);
 	event BalanceThresholdChange(uint256 _value);
+
+	// Implements ERC173
+	event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); // EIP173
+
 	constructor() {
 		owner = msg.sender;
 		poker = owner;
@@ -38,7 +42,8 @@ contract PeriodSimple {
 		return lastUsed[_subject] + period;
 	}
 	
-	function check(address _subject) external view returns(bool) {
+	//function check(address _subject) external view returns(bool) {
+	function have(address _subject) external view returns(bool) {
 		if (balanceThreshold > 0 && _subject.balance >= balanceThreshold) {
 			return false;
 		}
@@ -50,10 +55,39 @@ contract PeriodSimple {
 
 	function poke(address _subject) external returns(bool) {
 		require(msg.sender == owner || msg.sender == poker, 'ERR_ACCESS');
-		if (!this.check(_subject)) {
+		if (!this.have(_subject)) {
 			return false;
 		}
 		lastUsed[_subject] = block.timestamp;
 		return true;
 	}
+
+	// Implements EIP173
+	function transferOwnership(address _newOwner) public returns (bool) {
+		address oldOwner;
+		require(msg.sender == owner, 'ERR_AXX');
+
+		oldOwner = owner;
+		owner = _newOwner;
+
+		emit OwnershipTransferred(oldOwner, owner);
+		return true;
+	}
+
+	// Implements ERC165
+	function supportsInterface(bytes4 _sum) public pure returns (bool) {
+		if (_sum == 0x01ffc9a7) { // ERC165
+			return true;
+		}
+		if (_sum == 0x9493f8b2) { // ERC173
+			return true;
+		}
+		if (_sum == 0x3ef25013) { // ACL
+			return true;
+		}
+		if (_sum == 0x242824a9) { // Throttle
+			return true;
+		}
+		return false;
+	}
 }