xBank - multi-currency money market on Starknet

xBank will serve primarily as the multi-currency money market on Starknet. The vision is to be the premier money market and facilitate the lending and borrowing for participants within the Starknet DeFi ecosystem, including but not limited to retail users, protocols, and institutions.

The contracts for xBank are currently being developed, and are expected to be completed by the end of Q3 2022.

Overview

At the start, there will be four primary types of participants in the xBank protocol.

1. Lender

• Alice, as one of the lenders, can deposit ERC20 tokens (e.g. USDC, wETH) to the protocol lending vaults, which in return provides “xToken” to the Lender. The “xToken” is an interest-bearing token that accrues interest over time and acts as a receipt for the Lenders’ deposited funds. To withdraw the funds, Lenders can convert the “xToken” back to the original ERC 20 tokens they deposited + the interest that has accrued over the deposit period.

2. Borrower

• To become a borrower, the user must first be a lender and put up their lending deposit as collateral. With their deposit collateralized, Bob, as one of the Borrowers, can take out loans in any assets from xBank’s lending vaults. The maximum borrowable amount for the Borrower is determined by the value of their collateral assets and the collateral factor of the borrowed assets. Note that just like AAVE and Compound, xBank loans are cross-margin loans.

3. Liquidator

• Charlie, as one of the Liquidators, plays a key role in helping xBank manage risks from bad debt, especially in a volatile market condition. They are in charge of liquidating positions whose health metrics fall below a predetermined threshold. To incentivize the Liquidator to take timely action, the Liquidator will be awarded a liquidation incentive for the liquidation they initiate. The liquidation incentive paid to the Liquidator is part of the liquidation fee charged on the position owners’ collateral asset.

4.Flash Loaner

• Each “xToken” contains a flash loan function, allowing the Flash Loaners to execute their desired strategy by taking out a flash loan from the xToken's asset in the lending vault in exchange for a protocol fee.

Contracts

xtoken

• The xtoken contract represents a self-contained interest-bearing token for users who deposit ERC20 tokens to xBank’s lending vaults. Each ERC20 has a distinct pair of “xToken” e.g. ETH-xETH, USDC-xUSDC which are always exchangeable. In addition, “xToken” can be considered as an entry point for xBank basic functionalities e.g. redeem, mint, borrow, and repay.

xcontroller

• The xcontroller contract acts as a mediator & approver for the “xToken”, checking whether a given action can be done safely under the current context and condition.

interest-model

• The interest-model contract represents a mathematical strategy to determine the most suitable interest rate for each asset based on the asset’s dynamic utilization rate, which is a function of the asset’s supply and market demand.

Getting Started

If you are not familiar with hardhat, read getting started with hardhat, and starknet hardhat plugin

Prerequisites

 # Install `asdf` to manage python tool version https://asdf-vm.com/
 # Make sure you also configure your shell to use it
 brew install asdf

 # Install python with `asdf`
 # See more: https://skeptric.com/asdf-python/
 asdf plugin add python

 brew install gmp

 # Install the `poetry` dependency manager for Python
 pip install poetry
 asdf reshim python

 # Set up the virtual env and install project dependencies
 env "CFLAGS=-I/opt/homebrew/include" poetry install

 # Make sure the virtual environment was correctly installed within the working directory
 ls .venv

 # Install the development/deployment dependencies
 yarn install

Compile contracts

• yarn compile

Run unit tests (Cairo, Starknet L2)

• We use pytest for testing cairo contract files (*.cairo)
• To run unit test
  • yarn test:py
• Note: If there is contract change and want to fresh re-run the tests
  • yarn test:clear_cache
  • yarn test:py
• ~~for hardhat~~ (deprecated)
  • yarn test:hardhat

Run unit & integration tests (Solidity, EVM)

• We use forge (foundry) for testing solidity contract files (*.sol)
• Prerequisites: install foundry https://book.getfoundry.sh/getting-started/installation.html
  • after installation, try forge test -vvv
  • magic happens ✨
• To run all available foundry tests
  • test:foundry
• To run only unit test
  • test:foundry:unit
• To run only integration test
  • test:foundry:integration
• Advance: we can regenerate test/integration/mock_merkle_proof.json by
  • yarn build:foundry-ffi will give you /compiled-foundry-ffi folder containing generated .js files
  • node compiled-foundry-ffi/integration/_utils/generate_merkle_proof_cli.js to create test/integration/{timestamp}_mock_merkle_proof.json

To see error messages

poetry run starknet tx_status --network alpha-goerli --hash "0x..." --contract starknet-artifacts/contracts/contract.cairo/contract.json --error_message

Updating Cairo

• poetry add cairo-lang@latest
• yarn upgrade @shardlabs/starknet-hardhat-plugin --latest