diff --git a/README.md b/README.md index 9aa7359..f5d12a3 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,110 @@ +
+ Lombard + Solidity + Node.js + TypeScript + Hardhat + Ethers +
+ # 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. \ No newline at end of file