This README.md contains a set of checklists for our contest collaboration.
Your contest will use two repos:
- a contest repo (this one), which is used for scoping your contest and for providing information to contestants (wardens)
- a findings repo, where issues are submitted (shared with you after the contest)
Ultimately, when we launch the contest, this contest repo will be made public and will contain the smart contracts to be reviewed and all the information needed for contest participants. The findings repo will be made public after the contest report is published and your team has mitigated the identified issues.
Some of the checklists in this doc are for C4 (🐺) and some of them are for you as the contest sponsor (⭐️).
- Create a PR to this repo with the below changes:
- Provide a self-contained repository with working commands that will build (at least) all in-scope contracts, and commands that will run tests producing gas reports for the relevant contracts.
- Make sure your code is thoroughly commented using the NatSpec format.
- Please have final versions of contracts and documentation added/updated in this repo no less than 24 hours prior to contest start time.
- Be prepared for a 🚨code freeze🚨 for the duration of the contest — important because it establishes a level playing field. We want to ensure everyone's looking at the same code, no matter when they look during the contest. (Note: this includes your own repo, since a PR can leak alpha to our wardens!)
Under "SPONSORS ADD INFO HERE" heading below, include the following:
- Modify the bottom of this
README.mdfile to describe how your code is supposed to work with links to any relevent documentation and any other criteria/details that the C4 Wardens should keep in mind when reviewing. (Here's a well-constructed example.)- When linking, please provide all links as full absolute links versus relative links
- All information should be provided in markdown format (HTML does not render on Code4rena.com)
- Under the "Scope" heading, provide the name of each contract and:
- source lines of code (excluding blank lines and comments) in each
- external contracts called in each
- libraries used in each
- Describe any novel or unique curve logic or mathematical models implemented in the contracts
- Does the token conform to the ERC-20 standard? In what specific ways does it differ?
- Describe anything else that adds any special logic that makes your approach unique
- Identify any areas of specific concern in reviewing the code
- Optional / nice to have: pre-record a high-level overview of your protocol (not just specific smart contract functions). This saves wardens a lot of time wading through documentation.
- See also: this checklist in Notion
- Delete this checklist and all text above the line below when you're ready.
- Total Prize Pool: $90,500 USDC
- HM awards: $63,750 USDC
- QA report awards: $7,500 USDC
- Gas report awards: $3,750 USDC
- Bot race awards: $7,500 USDC
- Judge awards: $9,000 USDC
- Lookout awards: $6,000 USDC
- Scout awards: $500 USDC
- Join C4 Discord to register
- Submit findings using the C4 form
- Read our guidelines for more details
- Starts April 27, 2023 20:00 UTC
- Ends May 04, 2023 20:00 UTC
Automated findings output for the contest can be found [here](add link to report) within an hour of contest opening.
Note for C4 wardens: Anything included in the automated findings output is considered a publicly known issue and is ineligible for awards.
[ ⭐️ SPONSORS ADD INFO HERE ]
EigenLayer (formerly 'EigenLayr') is a set of smart contracts deployed on Ethereum that enable restaking of assets to secure new services. At present, this repository contains both the contracts for EigenLayer and a set of general "middleware" contracts, designed to be reuseable across different applications built on top of EigenLayer.
Note that the interactions between middleware and EigenLayer are not yet "set in stone", and may change somewhat prior to the platform being fully live on mainnet; in particular, payment architecture is likely to evolve. As such, the "middleware" contracts should not be treated as definitive, but merely as a helpful reference, at least until the architecture is more settled.
The EigenLayer whitepaper is available on our website, as well as introductory information and links to other documentation.
This repo contains our developer-oriented documentation; you can click the links in the Table of Contents below to access more specific documentation, or simply browse the /docs/ folder. We recommend starting with the EigenLayer Technical Specification to get a better overview before diving into any of the other docs.
Code4rena-specific note: The scope for this Code4rena contest is somewhat limited. We recommend reading through the contest scope section below before diving too deep into the specifics.
Design Docs
Flow Docs
- EigenLayer Withdrawal Flow
- EigenLayer Deposit Flow
- EigenLayer Delegation Flow
- Middleware Registration Flow for Operators
foundryup
This repository uses Foundry as a smart contract development toolchain.
See the Foundry Docs for more info on installation and usage.
You will notice that we also have hardhat installed in this repo. This is only used to generate natspec docgen. This is our workaround until foundry finishes implementing the forge doc command.
To generate the docs, run npx hardhat docgen (you may need to run npm install first). The output is located in docs/docgen
Prior to running tests, you should set up your environment. At present this repository contains fork tests against ETH mainnet; your environment will need an RPC_MAINNET key to run these tests. See the .env.example file for an example -- two simple options are to copy the LlamaNodes RPC url to your env or use your own infura API key in the provided format.
The main command to run tests is:
forge test -vv
solhint 'src/contracts/**/*.sol'
slither .
first install surya
then run
surya inheritance ./src/contracts/**/*.sol | dot -Tpng > InheritanceGraph.png
and/or
surya graph ./src/contracts/middleware/*.sol | dot -Tpng > MiddlewareControlFlowGraph.png
and/or
surya mdreport surya_report.md ./src/contracts/**/*.sol
List all files in scope in the table below (along with hyperlinks) -- and feel free to add notes here to emphasize areas of focus.
For line of code counts, we recommend using cloc.
| Contract | SLOC | Purpose | Libraries used |
|---|---|---|---|
| contracts/folder/sample.sol | 123 | This contract does XYZ | @openzeppelin/* |
List any files/contracts that are out of scope for this audit.
Describe any novel or unique curve logic or mathematical models implemented in the contracts
Sponsor, please confirm/edit the information below.
- If you have a public code repo, please share it here:
- How many contracts are in scope?: 25
- Total SLoC for these contracts?: 1560
- How many external imports are there?: 10
- How many separate interfaces and struct definitions are there for the contracts within scope?: ~11 interfaces, ~10 structs
- Does most of your code generally use composition or inheritance?: Inheritance
- How many external calls?: 6
- What is the overall line coverage percentage provided by your tests?: 95
- Is there a need to understand a separate part of the codebase / get context in order to audit this part of the protocol?: true
- Please describe required context: We will be excluding some parts of the protocol from scope, but understanding their interfaces / broad purposes may still be necessary. We are also doing proofs against Beacon Chain state, so understanding the details of the Beacon Chain / Execution Layer will be very helpful.
- Does it use an oracle?: Others; Part of it is designed to interface with an oracle, but the exact details of the oracle are still TBD, and the oracle itself is considered out-of-scope. It is a custom oracle for bringing Beacon Chain roots to the Execution Layer (for proving against Beacon Chain state).
- Does the token conform to the ERC20 standard?:
- Are there any novel or unique curve logic or mathematical models?: N/A
- Does it use a timelock function?:
- Is it an NFT?:
- Does it have an AMM?:
- Is it a fork of a popular project?: false
- Does it use rollups?:
- Is it multi-chain?:
- Does it use a side-chain?: false
- Describe any specific areas you would like addressed. E.g. Please try to break XYZ.": We are most concerned with a loss of user funds.
We’re aiming to launch with a very conservative design, in which all withdrawals from the system have a minimal enforced delay; we can respond to observations of any anomalous withdrawal behavior by pausing functionality and subsequently upgrading the contracts. The preliminary plan is to manually review user withdrawals until an automated solution is in place.
As such, any method to defeat these safeguards (i.e. to avoid the enforced minimum withdrawal delay) would also be of significant concern.
We’re also quite concerned with privilege escalation or the compromise of trusted roles; our docs will provide more details on trusted roles and the design philosophy we’ve taken here.
Another more specific concern we have is ensuring the correctness of the native restaking flow, i.e. “EigenPods” and their related functionality. This is a rather complicated system with a lot of moving parts, and ensuring that our code accurately reflects the design of the consensus layer is important.
Provide every step required to build the project from a fresh git clone, as well as steps to run the tests with a gas report.
Note: Many wardens run Slither as a first pass for testing. Please document any known errors with no workaround.