Reenable staging in client fund

[jijordre]

Description

The client fund does not allow funds to be explicitly staged. Thus at present the only way that a wallet can withdraw funds from the client fund is if its active balance is for deals and settlements increment the wallet's staged balance.

The new concepts for the client fund was exemplified in Slack message from @jijordre to @markbkk.

--

First, let’s rename client fund 1 balance and introduce 1 more balance. The active balance in the current spec we rename to deposited balance. The concept of staged balance is unchanged. We then introduce the concept of settled balance. (In name this matches what L&B suggested, although semantically it may be different.:smile:). This means that a wallet will have 3 balances (i.e. balance values) per currency.

Also we (re)introduce function Stage() in the client fund. Details about its implementation are below.

Then, we look at some actions.

1. Wallet a makes an initial deposit of 10 ETH. This increments his deposited balance of ETH.

2. Wallet a places a payment of 2 ETH to wallet b.

3. Wallet a then wants to withdraw its ETH. It is successful in running the deal settlement challenge for the payment deal.

4. Wallet a settles the payment deal on-chain by calling exchange contract’s SettleDeal() (Let’s assume immediate settlement is requested and/or discarding the reserve fund for now.) According to the net transfer of the payment it increments wallet b’s settled balance of ETH by an amount of 2 and decrements wallet a’s settled balance of ETH by the same amount of 2.

5. Wallet a continues towards withdrawal by calling client fund contract’s Stage(). The increment to its staged balance of ETH is the sum of deposited balance (10) and settled balance (-2) of ETH, with the total value of 8 ETH. This action also zeros out the deposited balance and settled balance of wallet a.

6. Wallet b then wants to withdraw its ETH and starts off by calling client fund’s Stage(). The increment to its staged balance of ETH is the sum of deposited balance (0) and settled balance (+2) of ETH, with the total value of 2 ETH. This action also zeros out the deposited balance and settled balance of wallet b.

7. Wallet a choses to not withdraw after all but rather wants to reengage with orders and payments. It calls Unstage() which increments the deposited balance of ETH to 8 and zeros out the staged balance of ETH.

8. Wallet b choses to withdraw by calling Withdraw() and zeros the staged balance of ETH.

I believe this scenario can be easily extended to trades as well. In addition we should bake into it the possibility of partial withdrawal and partial unstage. Partial stage may or may not make sense. I can’t quite decide yet.

Definition of done

• Active balance has been renamed to deposited balance in client fund.
• Settled balance has been implemented in client fund.
• Function Stage() has been implemented in client fund.
• Client fund function TransferFromActiveToStagedBalance() has been renamed to TransferFromDepositedToSettledBalance() and implementation updated to deal with updated balances.
• Client fund function WithdrawFromActiveBalance() has been renamed to WithdrawFromDepositedBalance() and implementation updated to deal with deposited balance instead of active balance.
• Client fund function DepositEtherToStagedBalance() has been renamed to DepositEtherToSettledBalance() and implementation updated to deal with settled balance instead of staged balance.
• Client fund function DepositTokenToStagedBalance() has been renamed to DepositTokenToSettledBalance() and implementation updated to deal with settled balance instead of staged balance.
• Unit tests are implemented/updated.

Details & Questions

This implementation is not included in the Omphalos specification.

Depends on