mirror of git://holbrook.no/eth-faucet
54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
|
# 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.
|