|
1 | 1 | <p align="center"> |
2 | | - <img src="logo.png" width="240" alt="CSM Logo"/> |
| 2 | + <img src="logo.png" width="240" alt="Staking Modules Logo"/> |
3 | 3 | </p> |
4 | | -<h1 align="center"> Lido Community Staking Module </h1> |
| 4 | +<h1 align="center">Lido Staking Modules</h1> |
5 | 5 |
|
6 | 6 | ## Intro |
7 | 7 |
|
8 | | -Lido Community Staking Module (CSM) is a permissionless module allowing community stakers to operate Ethereum validators with lower entry costs. Stakers provide stETH bonds, serving as security collateral, and receive rewards in the form of bond rebase and staking rewards (including execution layer rewards), which are socialized across Lido’s staking modules. |
| 8 | +Smart contracts for the staking modules of the [Lido](https://lido.fi) protocol. Three modules ship from this repository and share a common code base: |
9 | 9 |
|
10 | | -More on CSM in the [docs](https://docs.lido.fi/staking-modules/csm/intro). |
| 10 | +- **Community Staking Module (CSM)** — permissionless module for community stakers. See more in [CSM docs](https://docs.lido.fi/staking-modules/csm/intro). |
| 11 | +- **CSM 0x02** — CSM dedicated to validators with the `0x02` withdrawal credentials prefix. |
| 12 | +- **Curated Module v2 (CMv2)** — next iteration of Lido's curated module. Reuses CSM components to introduce bond-based security, flexible operator classification, improved incentive alignment, and lower governance friction compared to the legacy curated module. |
11 | 13 |
|
12 | | -## Contributing |
| 14 | +## Repository layout |
13 | 15 |
|
14 | | -We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md). |
| 16 | +- `src/` — Solidity sources |
| 17 | +- `script/` — deploy and helper scripts |
| 18 | +- `test/` — [Foundry](https://github.com/foundry-rs/foundry) tests |
| 19 | +- `artifacts/` — per-chain deployment artifacts (`mainnet/`, `hoodi/`, plus `latest/` and `local/` working dirs) |
15 | 20 |
|
16 | 21 | ## Getting Started |
17 | 22 |
|
18 | | -- Install [Foundry tools](https://book.getfoundry.sh/getting-started/installation) (version 1.2.3, see `.foundryref`) |
19 | | - |
20 | | -- Install [Just](https://github.com/casey/just) (version 1.24.0 or later) |
21 | | - |
22 | | -- Install [jq](https://jqlang.org/download/) (version 1.6 or later) |
| 23 | +Prerequisites: |
23 | 24 |
|
24 | | -> Some Linux distributions (like Arch Linux) might require additional install of [netcat (nc)](https://en.wikipedia.org/wiki/Netcat). The preferred version is OpenBSD. |
| 25 | +- [Foundry](https://book.getfoundry.sh/getting-started/installation) — version pinned in `.foundryref`. |
| 26 | +- [Just](https://github.com/casey/just) 1.24.0 or later. |
| 27 | +- [Yarn](https://classic.yarnpkg.com/) — 4.1 or later. |
| 28 | +- [jq](https://jqlang.org/download/) 1.6 or later. |
| 29 | +- OpenBSD-flavored `nc` (netcat) on some Linux distributions (e.g. Arch) for local fork recipes. |
25 | 30 |
|
26 | | -- Install project dependencies |
| 31 | +Bootstrap |
27 | 32 |
|
28 | 33 | ```bash |
29 | 34 | just deps |
30 | 35 | ``` |
31 | 36 |
|
32 | | -- Config environment variables |
33 | | - |
34 | | -```bash |
35 | | -cp .env.sample .env |
36 | | -``` |
37 | | - |
38 | | -Fill vars in the `.env` file with your own values |
39 | | - |
40 | | -- Build and test contracts |
41 | | - |
42 | | -```bash |
43 | | -just |
44 | | -``` |
45 | | - |
46 | | -## Run tests |
47 | | - |
48 | | -Run unit tests only |
| 37 | +Build and run unit tests |
49 | 38 |
|
50 | 39 | ```bash |
| 40 | +just build |
51 | 41 | just test-unit |
52 | 42 | ``` |
53 | 43 |
|
54 | | -For the following tests, make sure that the following variables are set in the `.env` file: |
55 | | - |
56 | | -```bash |
57 | | -export CHAIN=hoodi |
58 | | -export RPC_URL=<PUT_YOUR_URL_HERE> |
59 | | -``` |
60 | | - |
61 | | -Deploy CSM to the fork and run `deployment` and `integration` tests over it |
62 | | - |
63 | | -```bash |
64 | | -just test-local |
65 | | -``` |
66 | | - |
67 | | -Run all tests in one (`unit`, `deployment`, `integration`) |
68 | | - |
69 | | -```bash |
70 | | -just test-all |
71 | | -``` |
72 | | - |
73 | | -## Make a gas report |
74 | | - |
75 | | -It requires all unit tests to be green |
76 | | - |
77 | | -```bash |
78 | | -just gas-report |
79 | | -``` |
80 | | - |
81 | | -## Add new dependencies |
82 | | - |
83 | | -Dependencies are managed using yarn. To install new dependencies, run: |
84 | | - |
85 | | -```bash |
86 | | -yarn add <package-name> |
87 | | -``` |
88 | | - |
89 | | -Whenever you install new libraries using yarn, make sure to update your |
90 | | -`remappings.txt`. |
91 | | - |
92 | | -## Advanced testing scenarios using local fork |
93 | | - |
94 | | -Deploy contracts to the local fork |
95 | | - |
96 | | -```bash |
97 | | -just deploy-local |
98 | | -``` |
99 | | - |
100 | | -Set up environment for the local fork |
101 | | -Further test commands require the following environment variables to be set: |
102 | | - |
103 | | -```bash |
104 | | -export RPC_URL=http://127.0.0.1:8545 |
105 | | -export DEPLOY_CONFIG=./artifacts/local/deploy-hoodi.json |
106 | | -# Optional: utility deployment config for `test-utils` |
107 | | -export UTILS_DEPLOY_CONFIG=./artifacts/local/utils/TwoPhaseFrameConfigUpdate/deploy-hoodi.json |
108 | | -``` |
| 44 | +Run `just --list` to see all available recipes. |
109 | 45 |
|
110 | | -The result of deployment is `./artifacts/local/deploy-hoodi.json` deployment config, which is required for integration testing |
| 46 | +## Utility contracts |
111 | 47 |
|
112 | | -Verify deploy by running `deployment` tests. |
113 | | -Note that these are meant to be run only right after deployment, so they don't supposed to be green after any actions in the contracts |
| 48 | +The repository also ships a few utilities used for the modules: |
114 | 49 |
|
115 | | -```bash |
116 | | -just test-deployment |
117 | | -``` |
| 50 | +- **`TwoPhaseFrameConfigUpdate`** — shifts the Oracle report window by reconfiguring the `HashConsensus` in a safe manner |
| 51 | +- **`OneShotCurveSetup`** — atomically adds a new bond curve and applies its parameter overrides |
118 | 52 |
|
119 | | -Integration tests should pass either before a vote, or after at any state of contracts |
| 53 | +## ICS Assessment |
120 | 54 |
|
121 | | -```bash |
122 | | -just test-integration |
123 | | -``` |
124 | | - |
125 | | -There also fork helper scripts to prepare a fork state for e.g. UI testing purposes, |
126 | | -see [fork.just](./fork.just) to get all available commands |
127 | | - |
128 | | -```bash |
129 | | -just vote-upgrade |
130 | | -``` |
131 | | - |
132 | | -After a vote, you can test the contracts in the new state. It includes both `integration` and `vote-upgrade` tests |
133 | | - |
134 | | -```bash |
135 | | -just test-post-upgrade |
136 | | -``` |
| 55 | +Python utilities for assessing Identified Community Stakers (ICS) eligibility across engagement, experience, and humanity categories live in [`ics_assessment/`](./ics_assessment/). Methodology and scoring are described in the [Research Forum post](https://research.lido.fi/t/community-staking-module/5917/141); see [`ics_assessment/README.md`](./ics_assessment/README.md) for usage. |
137 | 56 |
|
138 | | -Kill fork after testing |
139 | | - |
140 | | -```bash |
141 | | -just kill-fork |
142 | | -``` |
143 | | - |
144 | | -## Deploy on a chain |
145 | | - |
146 | | -The following commands are related to the deployment process: |
147 | | - |
148 | | -- Dry run of deploy script to be sure it works as expected |
149 | | - |
150 | | -```bash |
151 | | -just deploy-live-dry |
152 | | -``` |
153 | | - |
154 | | -- Broadcast transactions |
155 | | - |
156 | | -> Note: pass `--legacy` arg in case of the following error: `Failed to get EIP-1559 fees` |
157 | | -
|
158 | | -```bash |
159 | | -just deploy-live |
160 | | -``` |
161 | | - |
162 | | -After that there should be artifacts in the `./artifacts/latest` directory, |
163 | | -which is might be moved to the particular directory and committed |
| 57 | +## Contributing |
164 | 58 |
|
165 | | -```bash |
166 | | -mv ./artifacts/latest ./artifacts/$CHAIN |
167 | | -``` |
| 59 | +See the [Contributing Guide](CONTRIBUTING.md) and repository conventions in `AGENTS.md`. |
0 commit comments