Add spec references, a mapping of spec to implementation

[jtraglia]

PR Description

This PR adds a directory with specification references. These are used to map specification items (configs, presets, functions, etc) to client implementations (code in Teku). This is much less invasive than my original idea of adding spec tags all across the codebase. 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.

If there's a change (eg a file is moved or a function is renamed) the included CI check will alert developers that something needs to be fixed; fixing issues should be relatively infrequent and easy, probably just updating a filepath or search string. When updating the codebase to be compliant with the next spec version, developers will:

• Bump the version in specrefs/.ethspecify.yml.
• Run ethspecify process --path=specrefs.
  • This will update the code sections in the spec tags.
• Run git diff to see what changes were made.
  • Developers can then make the appropriate changes.
• Run ethspecify check --path=specrefs to check for new spec items.
  • For example, a new function is added and is missing from the spec references.
  • The developer will add it to the appropriate spec reference file.

This PR is marked as a draft because I have not completely mapped out all of the functions. This is taking longer than I expected. Opening this now so that I can collect feedback from the team.

PS: I got the idea for this from Lodestar!

• feat: integrate ethspecify updates and add docs and check script ChainSafe/lodestar#7861

Documentation

• I thought about documentation and added the doc-change-required label to this PR if updates are required.

Changelog

• I thought about adding a changelog entry, and added one if I deemed necessary.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[jtraglia]

I have read the CLA Document and I hereby sign the CLA

[rolfyone]

I like the idea, are there any examples of when this finds diffs that we could peek at?

[jtraglia]

I like the idea, are there any examples of when this finds diffs that we could peek at?

Sure, I can provide some examples. To be clear, the "diff spec <> implementation <> other implementations" part of this plan has not been developed yet. We need a consistent way to identify these functions first.

When the version in build.gradle changes but we forgot to update specrefs:

When there's a missing entry (eg there's a new spec item):

When a search condition fails (eg the function was renamed):

When there's an ambiguous search (eg an overloaded function was added):

When there's a missing file (eg the file was renamed):

[rolfyone]

nice, thats kinda cool...

[rolfyone]

LGTM lets give this a go.