Skip to content

Commit

Permalink
update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@hashxtree
hashxtree committed Dec 19, 2024
1 parent b42aa19 commit bb6fb5f
Showing 1 changed file with 79 additions and 60 deletions.
139 changes: 79 additions & 60 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,91 +1,110 @@
<div>
<img alt="Lombard" src="https://img.shields.io/badge/v2-version?label=Lombard&labelColor=62C9B9&color=white"/>
<img alt="Solidity" src="https://img.shields.io/badge/0.8.24-solidity-purple">
<img alt="Node.js" src="https://img.shields.io/badge/>=18-node.js-green">
<img alt="TypeScript" src="https://img.shields.io/badge/>=4.5.0-typescript-green">
<img alt="Hardhat" src="https://img.shields.io/badge/^2.22.12-hardhat-yellow">
<img alt="Ethers" src="https://img.shields.io/badge/^6.4.0-ethers-darkblue">
</div>

# Lombard Finance EVM smart-contracts
[Website](https://www.lombard.finance/) | [Docs](https://docs.lombard.finance/)

## Content
1. [Overview](https://github.com/lombard-finance/evm-smart-contracts?tab=readme-ov-file#overview)
2. [One-time setup](https://github.com/lombard-finance/evm-smart-contracts?tab=readme-ov-file#one-time-setup)
3. [Deployment](https://github.com/lombard-finance/evm-smart-contracts?tab=readme-ov-file#deployment)
4. [Audit](https://github.com/lombard-finance/evm-smart-contracts?tab=readme-ov-file#audit)
5. [Misc](https://github.com/lombard-finance/evm-smart-contracts?tab=readme-ov-file#misc)

## Overview
LBTC is liquid Bitcoin; it's yield-bearing, cross-chain, and 1:1 backed by BTC. LBTC enables yield-bearing BTC to move cross-chain without fragmenting liquidity, and is designed to seamlessly integrate Bitcoin into the decentralized finance (DeFi) ecosystem while maintaining the security and integrity of the underlying asset.

| Smart contract | Description |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| Bascule | Bascule drawbridge designed to prevent bridge hacks before they hit the chain. |
| Consortium | The contract utilizes notary consortium multi-signature verification. |
| LombardTimelock | Safeguard helps to perform delayed transactions (e.g. implementation upgrade). |
| LBTC | ERC20 token to interact with protocol. |
| GnosisSafeProxy | Lombard governance, pauser and treasury wallets. |
| Bridge | Lombard multi-factor bridge. Supports different adapters (like [CCIP](https://docs.chain.link/ccip) as second factor to bridge `LBTC`. |
| OFTAdapters | LayerZero adapters for `LBTC` with different strategies. |
| ProxyFactory | CREATE3 factory allows to deploy proxies with same address. |
| FBTCPartnerVault | Allows to stake `FBTC` token. |
| PMMs | Swap pools to accept wrapped BTC ERC20 tokens (like `cbBTC` and `BTCb`). |
| PoR | Bitcoin addresses storage with the ownership proof system. |
| StakeAndBake | Convenience contract for users who wish to stake their `BTC` and deposit `LBTC` in a vault in the same transaction. |


### BTC deposit flow
Graph below represents BTC to LBTC flow

```mermaid
graph TD
users1(Users) -- mint(data,proofSignature) --> lbtc1{{LBTC}}
lbtc1 -- isValidSignature(hash,signature) --> consortium1{{consortium}}
lbtc1 -- validateWithdrawal(depositID,withdrawalAmount) --> bascule{{bascule}}
users2(Users) -- redeem(scriptPubkey,amount) --> lbtc2{{LBTC}}
users3(Users) -- depositToBridge(toChain,toAddress,amount) -->lbtc3A{{LBTC, chain A}}
users3 -- withdrawFromBridge(data,proofSignature) --> lbtc3B{{LBTC, chain B}}
lbtc3B -- isValidSignature(hash,signature) --> consortium3{{consortium}}
user_btc_wallet(User BTC wallet) -.-> btc{{BTC}}
btc -- deposit --> btc_wallet(Lombard controlled BTC address)
btc_wallet -. notarization request .-> consortium[Notary Consortium]
consortium -. notarization result .-> sc[Smart Contracts]
sc -- mint --> lbtc{{LBTC}}
lbtc -.-> user_evm_wallet(User EVM wallet)
```

### Addresses
#### Ethereum

| Smart contract | Description | Address | ProxyAdmin |
|-------------------|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| Bascule | Bascule drawbridge designed to prevent bridge hacks before they hit the chain. | [0xc750eCAC7250E0D18ecE2C7a5F130E3A765dc260](https://etherscan.io/address/0xc750eCAC7250E0D18ecE2C7a5F130E3A765dc260) | - |
| LombardConsortium | Stores consortium threshold key and verify signatures | [0xed6d647e2f81e5262101aff72c4a7bcdcfd780e0](https://etherscan.io/address/0xed6d647e2f81e5262101aff72c4a7bcdcfd780e0) | [0xa212Db18f8aEC6eF2F08cE42D7B447f9a405CD24](https://etherscan.io/address/0xa212Db18f8aEC6eF2F08cE42D7B447f9a405CD24) |
| LombardTimelock | Safeguard helps to perform delayed transactions (implementation upgrade) | [0x055E84e7FE8955E2781010B866f10Ef6E1E77e59](https://etherscan.io/address/0x055E84e7FE8955E2781010B866f10Ef6E1E77e59) | - |
| LBTC | ERC20 token to interact with protocol | [0x8236a87084f8B84306f72007F36F2618A5634494](https://etherscan.io/address/0x8236a87084f8B84306f72007F36F2618A5634494) | [0xbae061C73876952aa2C5e483B74DfA785425f879](https://etherscan.io/address/0xbae061C73876952aa2C5e483B74DfA785425f879) |
| GnosisSafeProxy | Lombard governance and treasury wallet | [0x251a604E8E8f6906d60f8dedC5aAeb8CD38F4892](https://etherscan.io/address/0x251a604E8E8f6906d60f8dedC5aAeb8CD38F4892) | - |
### BTC redeem flow
Graph below represents LBTC to BTC flow
```mermaid
graph TD
user_evm_wallet(User EVM wallet) -.-> lbtc{{LBTC}}
lbtc -- redeem --> sc[Smart Contracts]
sc -. notarization request .-> consortium[Notary Consortium]
consortium -. notarization result .-> custody[Custody approvers]
custody -.-> btc{{BTC}}
btc --> user_btc_wallet(User BTC wallet)
```

## One-time setup

## Installation
Install [nodejs](https://nodejs.org/en/download/package-manager). Run node -v to check your installation.

### Prerequisites
* Node: v18+
Support Node.js 18.x and higher.

### Tasks
#### Compilation
### 1. Clone this repo:
```bash
yarn hardhat compile
git clone https://github.com/lombard-finance/evm-smart-contracts.git
```
#### Tests
### 2. Install dependencies
```bash
yarn hardhat test
yarn
```

### Deployment
Compile contracts before deployment
### 3. Compile smart contracts

```bash
yarn hardhat compile
```
#### Proxy factory
Deploy proxy factory from zero nonce account
```bash
yarn hardhat deploy-proxy-factory --network '$NETWORK'
```

#### Core contracts
Deploy consortium
```bash
yarn hardhat deploy-consortium --network '$NETWORK'
```
### 4. Run tests

Deploy LBTC
```bash
yarn hardhat deploy-lbtc --consortium '$CONSORTIUM' --burn-commission 10000 --network '$NETWORK'
yarn hardhat test
```

Configure smart-contracts:
*TBD*
## Deployment

##### Bridge
Deploy adapter (e.g. Chain Link)
[Find router](https://docs.chain.link/ccip/supported-networks)
```bash
yarn hardhat deploy-chainlink-adapter --router '$ROUTER_ADDR' --lbtc '$LBTC_ADDR' --network '$NETWORK'
```
Deploy bridge
```bash
yarn hardhat deploy-bridge --lbtc '$LBTC_ADDR' --treasury '$TREASURY_ADDR' --adapter '$ADAPTER_ADDR' --set-bridge --network '$NETWORK'
```
Deploy token pool
Learn available scripts:
```bash
yarn hardhat deploy-ccip-token-pool --router '$ROUTER_ADDR' --lbtc '$LBTC_ADDR' --adapter '$ADAPTER_ADDR' --rmn '$RMN_ADDR' --network '$NETWORK'
yarn hardhat
```
Configure smart-contracts:
1. Add destinations using `addDestinations` of **Bridge** smart-contract.
2. *Claim the ownership of the token pool / register it in Chainlink*
3. *Connect token pools from different chains with addChainUpdates*
4. *TBD*

* `deploy-*` - scripts to deploy smart-contracts.
* `setup-*` - scripts to setup or change configuration of smart-contracts.
* `upgrade-proxy` - script to upgrade existing proxy with new implementation.

## Audit

Find the latest audit reports in [docs/audit](https://github.com/lombard-finance/evm-smart-contracts/tree/main/docs/audit)

## Misc

Follow [docs](https://github.com/lombard-finance/evm-smart-contracts/tree/main/docs) in more in-depth study of contracts.

1.

0 comments on commit bb6fb5f

Please sign in to comment.