evm-booking

EVM smart contract for ERC20 backed time slot booking
Info | Log | Files | Refs | README

README.md (4213B)

      1 # evm-booking
      2 
      3 # Overview
      4 
      5 This EVM smart contract allows exchanging ERC20 tokens for generic
      6 serial units.
      7 
      8 The primary use-case is time-slot booking.
      9 
     10 Unit ranges may also be reserved for collective use. In this case, token
     11 holders must pledge a proportional amount of their holdings towards the
     12 shared units.
     13 
     14 ## Example
     15 
     16 Alice and Bob hold ‘`TIME`’ vouchers.
     17 
     18 Each ‘`TIME`’ voucher unit represents one hour of time with a really
     19 comfortable hammock on the beach.
     20 
     21 Unfortunately, the beach is not accessible all the time, because local
     22 technocrat authorities have decided to close the beach for the public
     23 every day from 6pm to 6am on every weekday, to protect people from their
     24 own pleasure-seeking.
     25 
     26 Their trusted friend Trent publishes the ‘`evm-booking`’ contract, to
     27 manage hammock time for the coming month.
     28 
     29 The month has 30 days. The period starts on a wednesday (6am) and ends
     30 on a friday (6am).
     31 
     32 The period has 22 weekdays and 8 weekend days. This translates to
     33 $(22 * 12) + (8 * 24) = 264 + 192 = 456$ hours of available hammock
     34 time.
     35 
     36 456.00 ‘`TIME`’ vouchers are minted (two decimal places).
     37 
     38 Since Alice paid more for the hammock, she gets 60% of the time. Thus
     39 Alice has 273.6 and Bob has 182.4.
     40 
     41 ### Collective use
     42 
     43 Alice and Bob decide that they will rent the hammock out on weekends
     44 through Trent, and share in the proceeds. The rest of the time, they can
     45 reserve hammock time for themselves, or sell hammock time on to others.
     46 
     47 Trent reserves 192 hours in the contract for collective use, and Alice
     48 and Bob has to pledge $192 * 60% = 115.2$ and $192 * 0.4 = 76.8$
     49 vouchers respectively to cover that use.
     50 
     51 Trent will be selling hammock time for Generic Fiat Currency (GFC), and
     52 will get 30% off the top for the bother.
     53 
     54 ### Individual use
     55 
     56 Alice spends a total of 100 hours on the hammock. Her remaining 15.2
     57 hours are unused, during which time the hammock is very lonely.
     58 
     59 Bob sells 10 hours of hammock use to each Carol and Dave, and uses every
     60 bit of remaining time himself.
     61 
     62 Dave is too busy for hammocking. He spends 2 hours and sells 8 remaining
     63 hours to Frank.
     64 
     65 ### Fruits of use
     66 
     67 Trent was able to cash in a tidy 200 GFC for the time. He takes 60 GFC
     68 for himself. According to their shares, Alice gets 84 GFC and Bob gets
     69 56 GFC.
     70 
     71 # Smart contract
     72 
     73 When the smart contract is published, it is bound to:
     74 
     75 - The ERC20 token that will be used to spend serial units.
     76 
     77 - The amount of serial units.
     78 
     79 - Timestamp until when serial units can be reserved and spent.
     80 
     81 The supply of the ERC20 token will be read and stored, and used to
     82 calculate shares for collective use.
     83 
     84 **The supply of the ERC20 token must not change after binding it to the
     85 contract**.
     86 
     87 ## Interface
     88 
     89 The contract interface consists of three main methods.
     90 
     91 `consume`  
     92 Will spend serial units in the contract, and invoke `ERC20.transferFrom`
     93 to cover those units.
     94 
     95 `share`  
     96 Reserve serial units for collective use. Requires all token holders to
     97 collectively deposit a corresponding share of the total supply.
     98 
     99 `deposit(For)`  
    100 Manually synchronise deposits to cover the time currently reserved for
    101 collective use.
    102 
    103 ## Expiration
    104 
    105 After expiration, the shares of the collective use are considered
    106 finalized, and can be read out from the contract.
    107 
    108 ## Raw output
    109 
    110 The `raw` method returns the bit field representing the state of
    111 individual serial slots.
    112 
    113 ### Example
    114 
    115 Let the total of time slots be 50.
    116 
    117 Slots (inclusive, zero-indexed) 13-30 have been *spent* (`consume`) and
    118 249-255 have been *reserved* (`share`).
    119 
    120 Calling `raw(11, 257)` will yield a virtual bit field (lowest index
    121 left) as follows:
    122 
    123     00111111 11111111 11110000 00000000 (bytes 0-4)
    124     [...]
    125     00000000 00000011 11111000 00000000 (bytes 28-31)
    126     0 (bit 257)
    127 
    128 The ABI encoded return value will be, grouped by word:
    129 
    130     0000000000000000000000000000000000000000000000000000000000000020
    131     0000000000000000000000000000000000000000000000000000000000000021
    132     008f300000000000000000000000000000000000000000ffffffffffffffff3f
    133     0000000000000000000000000000000000000000000000000000000000000000
    134 
    135 The bit field is read word for word, then byte-for-byte from right to
    136 left.
    137 
    138 Note how it merges both the *spent* and *reserved* slots.