Skip to content
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

Open
wants to merge 2 commits into
base: dev
Choose a base branch
from
Open

docs: overhaul README.md #1105

wants to merge 2 commits into from

Conversation

0xClandestine
Copy link
Member

@0xClandestine 0xClandestine commented Feb 14, 2025

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:

  • Added badges for key project stats (e.g., build status, coverage, license).
  • Reorganized sections for better flow and readability.
  • Included a banner for a more professional and visually appealing look.

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.

Copy link
Member Author

@0xClandestine 0xClandestine left a 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:

[![Contributors](https://img.shields.io/github/contributors/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts/graphs/contributors)
[![Last Commit](https://img.shields.io/github/last-commit/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts/commits/master)
[![Release](https://img.shields.io/github/release/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts/releases)
[![Coverage Status](https://coveralls.io/repos/github/Layr-Labs/eigenlayer-contracts/badge.svg)](https://coveralls.io/github/Layr-Labs/eigenlayer-contracts)
Copy link
Member Author

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.

[![Last Commit](https://img.shields.io/github/last-commit/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts/commits/master)
[![Release](https://img.shields.io/github/release/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts/releases)
[![Coverage Status](https://coveralls.io/repos/github/Layr-Labs/eigenlayer-contracts/badge.svg)](https://coveralls.io/github/Layr-Labs/eigenlayer-contracts)
[![Solidity Version](https://img.shields.io/badge/solidity-%5E0.8.0-blue)](https://github.com/Layr-Labs/eigenlayer-contracts)
Copy link
Member Author

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.


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]`
Copy link
Member

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
Copy link
Member

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?

Copy link
Collaborator

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:

  1. 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.
  2. For testnet deployments, either move them to a separate file, or give instructions on how to fetch them from zeus.

Copy link
Collaborator

@8sunyuan 8sunyuan Mar 5, 2025

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

Copy link
Member Author

@0xClandestine 0xClandestine Mar 6, 2025

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.

Copy link
Member Author

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.
Copy link
Member

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?

@0xClandestine
Copy link
Member Author

image

Should probably add a repo description as well.

Comment on lines +133 to +159
### 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
```
Copy link
Collaborator

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

![EigenLayer Banner](docs/images/Banner.png)
Copy link
Collaborator

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
Copy link
Collaborator

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?

Copy link
Member Author

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?

Copy link
Collaborator

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.

Comment on lines +7 to +19
[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-yellow.svg)](https://github.com/Layr-Labs/eigenlayer-contracts/blob/master/LICENSE)
[![Tests](https://github.com/Layr-Labs/eigenlayer-contracts/actions/workflows/foundry.yml/badge.svg)](https://github.com/Layr-Labs/eigenlayer-contracts/actions/workflows/foundry.yml)
[![Twitter Follow](https://img.shields.io/twitter/follow/eigenlayer?style=social)](https://twitter.com/eigenlayer)
[![Documentation](https://img.shields.io/badge/docs-latest-blue)](https://docs.eigenlayer.xyz)
[![GitHub Issues](https://img.shields.io/github/issues/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts/issues)
[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts/pulls)
[![GitHub Stars](https://img.shields.io/github/stars/Layr-Labs/eigenlayer-contracts?style=social)](https://github.com/Layr-Labs/eigenlayer-contracts)
[![GitHub Forks](https://img.shields.io/github/forks/Layr-Labs/eigenlayer-contracts?style=social)](https://github.com/Layr-Labs/eigenlayer-contracts)
[![Code Size](https://img.shields.io/github/languages/code-size/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts)
[![Contributors](https://img.shields.io/github/contributors/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts/graphs/contributors)
[![Last Commit](https://img.shields.io/github/last-commit/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts/commits/master)
[![Release](https://img.shields.io/github/release/Layr-Labs/eigenlayer-contracts)](https://github.com/Layr-Labs/eigenlayer-contracts/releases)
[![Coverage Status](https://coveralls.io/repos/github/Layr-Labs/eigenlayer-contracts/badge.svg)](https://coveralls.io/github/Layr-Labs/eigenlayer-contracts)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image

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 (?)

Copy link
Member Author

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.

Copy link
Collaborator

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

[![Solidity Version](https://img.shields.io/badge/solidity-%5E0.8.0-blue)](https://github.com/Layr-Labs/eigenlayer-contracts)
[![OpenZeppelin Dependencies](https://img.shields.io/badge/OpenZeppelin-4.9.0-blue)](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.
Copy link
Collaborator

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.
Copy link
Collaborator

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
Copy link
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
📖 Documentation Improvements or additions to documentation.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants