-
Notifications
You must be signed in to change notification settings - Fork 393
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: overhaul README.md #1105
base: dev
Are you sure you want to change the base?
docs: overhaul README.md #1105
Conversation
dbeb2b0
to
2d28693
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some todos I need to get around to:
[](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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
TODO: Solidity version could be more explicit, should also link to solidity docs rather than our repo.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
minor: shall we just show how to get these from zeus?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
^ +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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
minor: users may not know what's m1 vs m2, prob just don't mention them?
### 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 | ||
|
||
 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Banner is way too big
# EigenLayer | ||
<a name="introduction"></a> | ||
|
||
# 🔄 EigenLayer |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What's this icon for?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mostly wanted to prompt the conversation, what emoji represents EL?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree, added as many as possible so we can pick and choose.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is outdated
@@ -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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.