CurrencyNetwork Protocol

[ice09]

The CurrencyNetwork Protocol contract provides the main functionality of the Trustlines network. It stores all Trustlines between users and implements multi-hop transfers, which allow for transfers rippling through the Trustlines network between users not knowing each other (but through a path of friends).

The CurrencyNetwork in its final state will be upgradeable, so that inevitable bugs can be fixed. The storage has to stay though all updates in the lifecycle of the CurrencyNetwork.

API

.init
.transfer(to, value,    via_obj)
.transferFrom(from, to, value, via_obj)         
.approve(spender, value)        
.allowance(owner, spender)                  
.updateCreditLine(receiver, creditlimit, interestrate, governance_address)          
.acceptCreditLine(hash)                     
.cashCheque(signed_message, via_obj)                    
.prepareTransfer(from, to, amount or via_obj)   

via_obj:    [max_fee, [hops, ]]

Events

event Approval(address _owner, address _spender, uint256 _value);
event Transfer(address _from, address _to, uint _value);
event CreditlineUpdateRequest(address _creditor, address _debtor, uint32 _value);
event CreditlineUpdate(address _creditor, address _debtor, uint32 _value); 
event PathPrepared(address _sender, address _receiver, uint32 _value);
// must be deactivated due to gas costs
event BalanceUpdate(address _from, address _to, int256 _value);

functions

prepare

Prepare a path between two UserAccounts, msg.sender and _to. This path is valid one day after preparation. The path is calculated by a system of federated relay servers off-chain.

• Parameters

  • _to - address of receiver
  • _value - value of transfer
  • _maxFee - maximum fee which sender accepts to pay
  • _path - array of addresses of Trustlines which have been calculated by the relay server

• Result on success

  Events

  PathPrepared(address _sender, address _receiver, uint32 _value)

prepareFrom

NOTE: check if necessary to support this function

Prepare a path between two UserAccounts, _from and _to. This path is valid one day after preparation. The path is calculated by a system of federated relay servers off-chain.

• Parameters

  • _from - address of sender
  • _to - address of receiver
  • _value - value of transfer
  • _maxFee - maximum fee which sender accepts to pay
  • _path - array of addresses of Trustlines which have been calculated by the relay server

• Result on success

  Events

  PathPrepared(address _from, address _receiver, uint32 _value)

cashCheque

Create a Cheque which is signed by UserAccount _from and can be redeemed by _to. The Cheque has an expiry date which is set in _expiresOn. These values are hashed and must be signed by _from.

• Parameters

  • _from - address of the account able to transfer the tokens
  • _to - address of the recipient
  • _value - value of transfer
  • _expiresOn - amount of token to be transferred
  • _signature - the values _from, _to, _value and _expiresOn signed by _from

• Result on success

  Events

  Transfer events according to mediatedTransfer(...)

transfer (with prepared Path)

Transfer amount value of CurrencyNetwork currency to recipient _to. This transfer is not a direct transfer of msg.sender to _to, but uses the a prepared path which exists from msg.sender to recipient _to in the CurrencyNetwork.

NOTE: A Path has to be prepared before this method can be used.

• Parameters

  • _to - address of the recipient
  • _value - value of transfer

• Result on success

  Events

  Transfer events according to mediatedTransfer(...)

transfer (including pre-calculated path)

Transfer amount value of CurrencyNetwork currency to recipient _to, with maxFee maximum fees and using the submitted pre-calulated path.

NOTE: A Path has to be prepared before this method can be used.

function logic

• Create sha3(_from, _to, value) and load stored path. if path.expiresOn == 0 => exit

• Check if path is not already expired (path.expiresOn < currentBlockTime)

• Check if last element of path is recipient. if not => exit

• On first hop: apply network fee to feesOutstandingA

• For each path-element: call _transfer(sender, _to, value, account)

• Parameters

  • _from - address of sender
  • _to - address of the recipient
  • _value - value of transfer
  • _maxFee - value of maximum fee the sender wants to pay
  • _path - array of addresses which represent the path between msg.sender and _to

• Result on success

  Events

  Transfer events according to mediatedTransfer(...)

internal function _transfer

Internal function which does the actual transfer of the currency value for 1 hop (from _sender to _receiver).

NOTE: A Trustline must exist between the two addresses.

function logic

• Check if (value + balanceAB) <= creditlineAB (this also happens if there is no Trustline between A and B). if not => exit

• Apply interest for elapsed time between last usage of this Trustline to balanceAB

• Substract capacity fees and imbalance fees from _value

• Update balance with new value: balanceAB + _value

• Store account for (_receiver, sender)

• Parameters

  • _from - address of the sender
  • _to - address of the receiver
  • _value - value of transfer
  • _account - already loaded account, ie. the Trustline between _from and _to

• Result on success

  Events

  Transfer events according to mediatedTransfer(...)

transferFrom (with prepared Path)

Transfer amount value of CurrencyNetwork currency from sender _from to recipient _to. This transfer is not a direct transfer of msg.sender to _to, but uses the a prepared path which exists from msg.sender to recipient _to in the CurrencyNetwork.

NOTE: A Path has to be prepared before this method can be used.

• Parameters

  • _from - address of the sender
  • _to - address of the recipient
  • _value - value of transfer

• Result on success

  Events

  Transfer events according to mediatedTransfer(...)

updateCreditline

with modifier: notSender(_debtor): no self update possible

The msg.sender (the creditor) wants to update the Creditline with the debtor. This function only stores the request for the Creditline update. The key for the request proposal is msg.sender, debtor, value. For this (sha3) value the current date is stored. The debtor has to accept the Creditline update by calling acceptCreditline.

• Parameters

  • _to - address of the recipient
  • _value - value of transfer
  • _maxFee - value of maximum fee the sender wants to pay
  • _path - array of addresses which represent the path between msg.sender and _to

• Result on success

  Events

  Transfer events according to mediatedTransfer(...)

acceptCreditline

The msg.sender (the debtor) wants to accept the Creditline update request by _creditor.

function logic

• Load the Trustline between creditor and debtor (seen from creditor)

• Does the requests exists for sha3(creditor, debtor, value), ie. is the associated value > 0? if not => exit

• Is the balance of creditor to debtor below the Creditline update value? if not => exit

• Update the creditlineAB to the new value

• Store the Trustline between creditor and debtor

• Parameters

  • _to - address of the recipient
  • _value - value of transfer
  • _maxFee - value of maximum fee the sender wants to pay
  • _path - array of addresses which represent the path between msg.sender and _to

• Result on success

  Events

  Transfer events according to mediatedTransfer(...)

Subtask

• [x] setup new repo for contracts, integrate latest version and Sohan's PR
• [x] update version of Python tests and Populus to Python 3(.6)
• [x] examine/validate tests for new contract tl_token_business.sol
• [ ] get OpenZeppelin to run with current populus 2.0.0a4 (ERC20-Basecontract)
• [ ] define upgrade concept for contract
• [ ] remove users and friends (iteration) - move to relay?
• [x] help Piper find the problem of deployment in unit tests
• [x] integrate existing trustlines.sol and ERC20-Base, incl. interface changes
• [x] merge tl_token_business.sol and trustlines.sol (proposed name CurrencyNetwork.sol)
• [x] adapt tests to new CurrencyNetwork.sol
• [ ] add integration test & deploy script for local node (using parity --dev)

[ice09]

moved to description.

[berndbohmeier]

outdated, closed and new issues are pen for the missing features