feat: add spec references, a mapping of spec to implementation#8778
feat: add spec references, a mapping of spec to implementation#8778ensi321 merged 4 commits intoChainSafe:unstablefrom
Conversation
Summary of ChangesHello @jtraglia, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a robust system for tracking and verifying the client's adherence to Ethereum specifications. By creating a dedicated 'specrefs' directory and leveraging the 'ethspecify' tool, the project aims to improve development efficiency in managing specification changes and enhance the auditability of client implementations against the official Ethereum protocols. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Ignored Files
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
jtraglia
changed the title
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new specrefs directory to map specification items to their implementations in the codebase, using the ethspecify tool. This is a great initiative for improving spec compliance and maintainability. The new configuration files are well-structured, and the process is documented in a new README. I've found a small typo in the README and suggested an improvement to make the search patterns in the configuration more robust. Overall, this is a valuable addition to the repository.
| - name: AGGREGATE_DUE_BPS | ||
| sources: | ||
| - file: packages/config/src/chainConfig/configs/mainnet.ts | ||
| search: "AGGREGATE_DUE_BPS:" |
There was a problem hiding this comment.
The search pattern "AGGREGATE_DUE_BPS:" is a bit weak and could potentially match unintended lines, such as in comments. For better robustness, I suggest using a more specific regex that anchors the search to the start of the line and accounts for leading whitespace. This improvement should be applied to other similar simple string searches in this file for consistency and maintainability.
search: '^\s+AGGREGATE_DUE_BPS:'
regex: trueThere was a problem hiding this comment.
Nah, if it also matches a comment, ethspecify will throw an ambiguous search error:
For example:
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Nico Flaig <nflaig@protonmail.com>
|
this should be closing #7477 once merged |
ensi321
left a comment
ensi321
left a comment
There was a problem hiding this comment.
I think this is great. Minor maintenance effort from our side. And we can be monitor the exception list to see if Lodestar is missing something from the spec.
| sources: [] | ||
| spec: | | ||
| <spec fn="_fft_field" fork="fulu" hash="d9de8aaf"> | ||
| def _fft_field( |
There was a problem hiding this comment.
Hmmm, I don't see the point of having content of each function here. It could be a good reference but generally something like link should be enough? Same with containers and data classes.
There was a problem hiding this comment.
As it is right now, the link style is broken. It tries to link to the specs GitHub repo and not everything has a link. I should update ethspecify to use https://ethspec.tools/#specs/ links. That way everything has a well defined link. I'll add this to my todo list too.
Personally, I think full is the best style here because it's instantly clear what changed when bumping versions. With a link, all you'd see is that the hash changed but it wouldn't be very easy to tell what exactly changed. I will leave this up to y'all though; happy to do whatever you think is best.
There was a problem hiding this comment.
Hey again @ensi321. I have added this functionality to ethspecify v0.3.6. If you wanted to use the link style in some places, that's an option now. It would look something like:
| @@ -0,0 +1,11986 @@ | |||
| - name: _fft_field | |||
| sources: [] | |||
There was a problem hiding this comment.
For those that are under exceptions, is it possible to not generate them here?
There was a problem hiding this comment.
That's a good idea. I would need to publish a new version of ethspecify with an option for this though. I will add that to my todo list for Monday.
Note: There is a auto_add_missing_entries setting which defaults to true. We could simple disable that but it wouldn't populate new spec items when bumping the version. Also, I think there is some benefit in keeping functions which aren't mappable (because of implementation differences) but stuff like KZG functions really could be deleted without any harm.
ensi321
left a comment
ensi321
left a comment
There was a problem hiding this comment.
lgtm. Can always make improvement on this later on.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## unstable #8778 +/- ##
=========================================
Coverage 52.04% 52.04%
=========================================
Files 848 848
Lines 64584 64584
Branches 4762 4762
=========================================
Hits 33612 33612
Misses 30903 30903
Partials 69 69 🚀 New features to boost your workflow:
|
|
we already broke the spec ref CI on unstable branch 😁 should have rebased this branch before merging |
**Motivation** This PR is follow up from: * #8778 **Description** This PR enables a few optional features: * `auto_add_missing_entries`: Add missing spec items to the relevant mapping files. It _will not_ add missing spec items if there's an exception for that spec item. * `auto_standardize_names`: Automatically add `#fork` tags to specref names, for explicitness. * `require_exceptions_have_fork`: Require exceptions include a `#fork` tag. It also removes the KZG functions (which clients do not implement) from the `functions.yml` file. @ensi321 could you give me a list of other items we want to remove? And it also [fixes](da91b29) the search query for `get_committee_assignment` which was moved before the first PR was merged. **AI Assistance Disclosure** - [x] External Contributors: I have read the [contributor guidelines](https://github.com/ChainSafe/lodestar/blob/unstable/CONTRIBUTING.md#ai-assistance-notice) and disclosed my usage of AI below. I used AI to remove the KZG functions.
|
🎉 This PR is included in v1.40.0 🎉 |
4 participants
Motivation
This PR adds a directory with specification references. These are used to map specification items (configs, presets, functions, etc) to client implementations (code in Lodestar). These specification references are meant to (1) help developers keep track of specification changes and (2) make it easier for third-parties (eg EF Protocol Security) to verify clients adhere to the specifications.
Our team is working to do this for all clients.
Note: The function mappings are the only weak-spot. It's quite difficult to map some of these because of implementation differences & the fact that not everything is implemented (eg Gloas functions). The specref functions will most likely require some additional work, but this PR does identify most functions.
AI Assistance Disclosure
Yes, I used Claude Code to identify/map most of these.
Fixes: #7477