docs: overhaul README.md #1105
docs: overhaul README.md #1105
Conversation
0xClandestine
added
📖 Documentation
0xClandestine
force-pushed
the
docs/overhaul-readme
branch
from
dbeb2b0 to
2d28693
Compare
0xClandestine
requested review from
seanmcgary,
shrimalmadhur,
scotthconner,
bowenli86,
jbrower95,
nadir-akhtar,
stevennevins,
wadealexc,
0xrajath,
gpsanant,
8sunyuan,
ypatil12,
MinisculeTarantula and
eigenmikem
| [](https://github.com/Layr-Labs/eigenlayer-contracts/graphs/contributors) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts/commits/master) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts/releases) | ||
| [](https://coveralls.io/github/Layr-Labs/eigenlayer-contracts) |
There was a problem hiding this comment.
TODO: I need to get this to properly parse coverage.
| [](https://github.com/Layr-Labs/eigenlayer-contracts/commits/master) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts/releases) | ||
| [](https://coveralls.io/github/Layr-Labs/eigenlayer-contracts) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts) |
There was a problem hiding this comment.
TODO: Solidity version could be more explicit, should also link to solidity docs rather than our repo.
0xClandestine
force-pushed
the
docs/overhaul-readme
branch
from
9c7f8aa to
833fcae
Compare
|
|
||
| Additionally, to run all tests in a forked environment, [install yq](https://mikefarah.gitbook.io/yq/v/v3.x/). Then, set up your environment by running the following command. | ||
|
|
||
| `source bin/source-env.sh [goerli|local]` |
There was a problem hiding this comment.
there's only holesky, no goerli anymore
i had a PR which changed it, but it's never merged #764
|
|
||
| You can view the deployed contract addresses below, or check out the code itself on the [`testnet-holesky`](https://github.com/Layr-Labs/eigenlayer-contracts/tree/testnet-holesky) branch. | ||
|
|
||
| ###### Core |
There was a problem hiding this comment.
minor: shall we just show how to get these from zeus?
There was a problem hiding this comment.
I'd like these in the repo.
I'm not sure how I feel about moving them to separate files... what about this:
- Keep the mainnet deployment info in the top README. That's the most useful info by far and I know many of us / many customers value it being there.
- For testnet deployments, either move them to a separate file, or give instructions on how to fetch them from zeus.
There was a problem hiding this comment.
^ +1
It's always way too difficult finding contract addresses for a project. I'd prefer leaving both in top level README
There was a problem hiding this comment.
@8sunyuan Personally think it's a bit much, main readme feels bloated and you have to scroll quite a bit to find what you want. Think the main think is making links to addresses HIGHLY visible.
There was a problem hiding this comment.
I guess moving testnet is a happy compromise though
|
|
||
| ### Current Mainnet Deployment | ||
|
|
||
| The current mainnet deployment is our M2 release. You can view the deployed contract addresses below, or check out the code itself on the [`mainnet`](https://github.com/Layr-Labs/eigenlayer-contracts/tree/mainnet) branch. |
There was a problem hiding this comment.
minor: users may not know what's m1 vs m2, prob just don't mention them?
Should probably add a repo description as well. |
| ### Running Static Analysis | ||
|
|
||
| 1. Install [solhint](https://github.com/protofire/solhint), then run: | ||
|
|
||
| `solhint 'src/contracts/**/*.sol'` | ||
|
|
||
| 2. Install [slither](https://github.com/crytic/slither), then run: | ||
|
|
||
| `slither .` | ||
|
|
||
| ### Generate Inheritance and Control-Flow Graphs | ||
|
|
||
| 1. Install [surya](https://github.com/ConsenSys/surya/) and graphviz: | ||
|
|
||
| ``` | ||
| npm i -g surya | ||
|
|
||
| apt install graphviz | ||
| ``` | ||
|
|
||
| 2. Then, run: | ||
|
|
||
| ``` | ||
| surya inheritance ./src/contracts/**/*.sol | dot -Tpng > InheritanceGraph.png | ||
|
|
||
| surya mdreport surya_report.md ./src/contracts/**/*.sol | ||
| ``` |
There was a problem hiding this comment.
We should just remove this stuff. It's not helpful to anyone, and it's not specific to our repo. These sections are just "how to run various evm tools" -- not needed in our repo.
|
|
||
| # 🔄 EigenLayer | ||
|
|
||
|  |
| # EigenLayer | ||
| <a name="introduction"></a> | ||
|
|
||
| # 🔄 EigenLayer |
There was a problem hiding this comment.
Mostly wanted to prompt the conversation, what emoji represents EL?
There was a problem hiding this comment.
Ah I see you added emojis everywhere. I'm not sure about this one - but maybe the title itself needs to be changed too? This repo isn't EigenLayer, it's the EL core protocol contracts.
| [](https://github.com/Layr-Labs/eigenlayer-contracts/blob/master/LICENSE) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts/actions/workflows/foundry.yml) | ||
| [](https://twitter.com/eigenlayer) | ||
| [](https://docs.eigenlayer.xyz) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts/issues) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts/pulls) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts/graphs/contributors) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts/commits/master) | ||
| [](https://github.com/Layr-Labs/eigenlayer-contracts/releases) | ||
| [](https://coveralls.io/github/Layr-Labs/eigenlayer-contracts) |
There was a problem hiding this comment.
This is very cluttered. Let's keep the most important badges and nix the rest. Maybe these?
- License
- Tests
- Docs (note - this links to our user docs. not sure if that's misleading/unhelpful? we have more technical docs in the repo itself, and if you're in our repo you probably want the technical docs. maybe we can have a badge each for user docs/technical docs? idk)
- Release
- Solidity Version (?)
There was a problem hiding this comment.
Agree, added as many as possible so we can pick and choose.
There was a problem hiding this comment.
Agreed, lets keep the badges minimal. The docs should just point to /docs directory in this repo imo
| [](https://github.com/Layr-Labs/eigenlayer-contracts) | ||
| [](https://github.com/OpenZeppelin/openzeppelin-contracts/tree/v4.9.0) | ||
|
|
||
| ## 📚 Background | ||
|
|
||
| EigenLayer is a set of smart contracts deployed on Ethereum that enable restaking of assets to secure new services. This repo contains the EigenLayer core contracts, whose currently-supported assets include beacon chain ETH and several liquid staking tokens (LSTs). Users use these contracts to deposit and withdraw these assets, as well as delegate them to operators providing services to AVSs. |
There was a problem hiding this comment.
Outdated description, does not reflect longtail/slashing
|
|
||
| The following strategies differ significantly from the other strategies deployed/used above: | ||
| For an intuitive introduction to EigenLayer's core concepts, we recommend reading ["You Could've Invented EigenLayer"](https://www.blog.eigenlayer.xyz/ycie/), though note that some described features like the Slasher are still in development. If you're looking to get started using EigenLayer, we provide comprehensive guides for both users and operators. The [Restaking User Guide](https://docs.eigenlayer.xyz/eigenlayer/restaking-guides/overview) walks through the process of restaking assets, while the [Operator Guide](https://docs.eigenlayer.xyz/operator-guides/operator-introduction) provides instructions for running an EigenLayer operator node. |
| @@ -94,3 +94,72 @@ Use the following types for your commit messages: | |||
|
|
|||
| By following these guidelines, you help maintain the quality and readability of the EigenLayer codebase. We appreciate your contributions and look forward to collaborating with you! | |||
|
|
|||
| ## Building and Running Tests | |||
There was a problem hiding this comment.
I'm not sure if we have concrete PR/branching guidelines yet, but if/when we create those, we should include those guidelines in this file.
Motivation:
The previous README lacked organization and visual clarity, making it harder for users to quickly grasp the project's purpose and key details. Enhancing its structure and aesthetics improves accessibility and engagement.
Modifications:
Result:
A clearer, more structured, and visually engaging README that makes it easier for users and contributors to understand and navigate the project.
NOTE: Checkout the new README.