Lending Plapp
=====

# Overview

This document describes an architcture desgin of lending plapps (plasma apps). I outlined the specification referring to [Dharma project](https://www.dharma.io/) functionalities. Special thanks to @ben_chain for review.

1. Collateralizer(Alice) and Lender(Bob) swap their tokens
* Alice makes her collateral state with token A and swap the collateral for Bob's token B.
* It means that Bob lent token B to Alice
2. Collateral(tokenA) is returned to Alice if the total repayment has been repaid within the grace period.

# Architecture

We defined 2 predicates, swap predicate and collateral predicate based on Plasma Group's specification.
You first use swap predicate to set up a collateral.
Then, lender will execute collateral predicate.

## Swap predicate

This is a setup phase of lending. The debtor makes a collateral state described in the next section and swap it for the loaned token.

It's basically the same design as swap predicate, but collateralizer wants to cancel collateral when a swap fails. Hence, requirements are
* When a swap succeeds, the new state is a collateral state
* When a swap fails, the new state is a simple ownership of collateralizer(Alice)

### `verifyTransaction`

* ensure `witness` is a signature by `preState.data.owner`
* If predicate can ensure inclusion of a counter state(loan)
* ensure inclusion of a counter state(loan)
* ensure `postState` is a collateral state
* If predicate can't ensure inclusion of a counter state
* ensure `postState` has the ownership of collateralizer

## Collateral predicate

### 1. State object specification

struct lendingStateData:
  collateralizer: address
  lender: address
  amount: uint256
  grace_period: uint256

### 2. Methods

There are 2 methods.

#### `refundCollateral` method

Refund collateral. Lender gets a refund on the collateral after debt enters default.

#### `returnCollateral` method

Collateral is returned to the original collateralizer of the debt agreement.
The collateralizer can get collateral in exchange for the "repayment".

### 3. `verifyTransaction`

Refund collateral.

* ensure `block.number` is bigger than `preState.data.grace_period`
* ensure `witness` is a signature by `preState.data.lender`
* ensure `block.number` is bigger than `preState.data.grace_period`
* ensure `postState.range` has the same amount as `transaction.range`
* ensure `postState` is a ownership state of `prestate.data.lender`
* ensure `block.number` is smaller than `preState.data.grace_period`
* ensure `witness` is a signature by `preState.data.collateralizer`(Alice)
* ensure "repayment" has valid history
* finalize exit of "repayment" on behalf of lender(Bob)
* or show deprecation of "repayment" by Bob
* ensure "repayment" has the same amount as `preState.data.amount`
* ensure `postState.range` has the same amount as `transaction.range`
* ensure `postState` has the ownership state of collateralizer

# Questions

### - Can Alice use tokenA after the repayment?

I think she can, as far as she proves that her "repayment" is valid. It means recievers of tokenA should verify tokenB's history. It requires addtional amount of history.

When operator withholds a block, Alice should be able to exit her collateral state. The grace period should be added for its upcoming challenge period.

### - Can Bob use tokenA after debt enters default?

Bob can keep using tokenA after its grace period. When Bob attempts to use tokenA maliciously, for example when he (and colluded operator) transfers tokenA to someone before the grace period ends, Alice should be able to exit tokenA as soon as possible.