eth-faucet

Gas token gifter with controls from time intervals, amounts and access
Info | Log | Files | Refs | README

README.md (2684B)

      1 # eth-faucet
      2 
      3 A faucet implementation for ETH gas tokens, implementing the [CIC Faucet](https://git.grassecon.net/cicnet/cic-contracts#faucet) interface.
      4 
      5 
      6 ## Setup
      7 
      8 Firstly, the faucet contract must be funded before use. It can be funded simply by sending gas tokens to it as a normal transaction.
      9 
     10 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.
     11 
     12 
     13 ## Usage
     14 
     15 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.
     16 
     17 
     18 ## Restricting accounts
     19 
     20 Usage of the faucet may be restricted by which addresses can request gas tokens from it.
     21 
     22 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.
     23 
     24 
     25 ## Restricting usage frequency
     26 
     27 Usage of the faucet may also be restricted by time delay. 
     28 
     29 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.
     30 
     31 
     32 ### Example usage frequency controller
     33 
     34 The `PeriodSimple` contract provided by this repository demonstrates an implementation of the usage frequency restriction.
     35 
     36 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.
     37 
     38 The number of seconds that must pass between each usage can be set using `setPeriod()`
     39 
     40 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).
     41 
     42 
     43 ## Sealing the contracts
     44 
     45 The faucet contract implements the [CIC Seal](https://git.grassecon.net/cicnet/cic-contracts#seal) interface to enable sealing the parameters defining its behavior.
     46 
     47 The parameters that can be sealed are:
     48 
     49 - *Registry*, blocking the use of the `setRegistry()` method.
     50 - *Period checker*, blocking the use of the `setPeriodChecker()` method.
     51 - *Value*, blocking the use of the `setAmount()` method.
     52 
     53 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.