Add ability to download nightly tests from a specific night (#16298)

**What type of PR is this?**

Feature

**What does this PR do? Why is it needed?**

This PR allows devs to test against a specific run of the nightly
reference test generator.

**Acknowledgements**

- [x] I have read
[CONTRIBUTING.md](https://github.com/prysmaticlabs/prysm/blob/develop/CONTRIBUTING.md).
- [x] I have included a uniquely named [changelog fragment
file](https://github.com/prysmaticlabs/prysm/blob/develop/CONTRIBUTING.md#maintaining-changelogmd).
- [x] I have added a description with sufficient context for reviewers
to understand this PR.
- [x] I have tested that my changes work as expected and I added a
testing plan to the PR description (if applicable).

changelog/jtraglia-add-specrefs-readme.md

@@ -0,0 +1,3 @@
+### Added
+
+- Added README for maintaining specrefs.

changelog/jtraglia-nightly-reftests-with-run-id.md

@@ -0,0 +1,3 @@
+### Added
+
+- The ability to download the nightly reference tests from a specific day.

specrefs/README.md

@@ -0,0 +1,35 @@
+# Specification References
+
+This directory contains specification reference tracking files managed by
+[ethspecify](https://github.com/jtraglia/ethspecify).
+
+## Installation
+
+Install `ethspecify` with the following command:
+
+```bash
+pipx install ethspecify
+```
+
+> [!NOTE]
+> You can run `ethspecify <cmd>` in the `specrefs` directory or
+> `ethspecify <cmd> --path=specrefs` from the project's root directory.
+
+## Maintenance
+
+When adding support for a new specification version, follow these steps:
+
+0. Change directory into the `specrefs` directory.
+1. Update the version in `.ethspecify.yml` configuration.
+2. Run `ethspecify process` to update/populate specrefs.
+3. Run `ethspecify check` to check specrefs.
+4. If there are errors, use the error message as a guide to fix the issue. If
+   there are new specrefs with empty sources, implement/locate each item and
+   update each specref source list. If you choose not to implement an item,
+   add an exception to the appropriate section the the `.ethspecify.yml`
+   configuration.
+5. Repeat steps 3 and 4 until `ethspecify check` passes.
+6. Run `git diff` to view updated specrefs. If an object/function/etc has
+   changed, make the necessary updates to the implementation.
+7. Lastly, in the project's root directory, run `act -j check-specrefs` to
+   ensure everything is correct.

testing/spectest/README.md

@@ -21,10 +21,14 @@ There are tests for mainnet and minimal config, so for each config we will add a
 
 ## Running nightly spectests
 
-Since [PR 15312](https://github.com/OffchainLabs/prysm/pull/15312), Prysm has support to download "nightly" spectests from github via a starlark rule configuration by environment variable. 
-Set `--repo_env=CONSENSUS_SPEC_TESTS_VERSION=nightly` when running spectest to download the "nightly" spectests. 
-Note: A GITHUB_TOKEN environment variable is required to be set. The github token must be a [fine grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).
+Since [PR 15312](https://github.com/OffchainLabs/prysm/pull/15312), Prysm has support to download "nightly" spectests from github via a starlark rule configuration by environment variable.
+Set `--repo_env=CONSENSUS_SPEC_TESTS_VERSION=nightly` or `--repo_env=CONSENSUS_SPEC_TESTS_VERSION=nightly-<run_id>` when running spectest to download the "nightly" spectests.
+Note: A GITHUB_TOKEN environment variable is required to be set. The github token does not need to be associated with your main account; it can be from a "burner account". And the token does not need to be a fine-grained token; it can be a classic token.
 
 ```
 bazel test //... --test_tag_filters=spectest --repo_env=CONSENSUS_SPEC_TESTS_VERSION=nightly
 ```
+
+```
+bazel test //... --test_tag_filters=spectest --repo_env=CONSENSUS_SPEC_TESTS_VERSION=nightly-21422848633
+```

tools/download_spectests.bzl

@@ -1,5 +1,6 @@
 # bazel build @consensus_spec_tests//:test_data
 # bazel build @consensus_spec_tests//:test_data --repo_env=CONSENSUS_SPEC_TESTS_VERSION=nightly
+# bazel build @consensus_spec_tests//:test_data --repo_env=CONSENSUS_SPEC_TESTS_VERSION=nightly-<run_id>
 
 def _get_redirected_url(repository_ctx, url, headers):
     if not repository_ctx.which("curl"):
@@ -24,7 +25,7 @@ def _impl(repository_ctx):
     version = repository_ctx.getenv("CONSENSUS_SPEC_TESTS_VERSION") or repository_ctx.attr.version
     token = repository_ctx.getenv("GITHUB_TOKEN") or ""
 
-    if version == "nightly":
+    if version == "nightly" or version.startswith("nightly-"):
         print("Downloading nightly tests")
         if not token:
             fail("Error GITHUB_TOKEN is not set")
@@ -34,16 +35,22 @@ def _impl(repository_ctx):
             "Accept": "application/vnd.github+json",
         }
 
-        repository_ctx.download(
-            "https://api.github.com/repos/%s/actions/workflows/%s/runs?branch=%s&status=success&per_page=1"
-                % (repository_ctx.attr.repo, repository_ctx.attr.workflow, repository_ctx.attr.branch),
-            headers = headers,
-            output = "runs.json"
-        )
+        if version.startswith("nightly-"):
+            run_id = version.split("nightly-", 1)[1]
+            if not run_id:
+                fail("Error invalid run id")
+        else:
+            repository_ctx.download(
+                "https://api.github.com/repos/%s/actions/workflows/%s/runs?branch=%s&status=success&per_page=1"
+                    % (repository_ctx.attr.repo, repository_ctx.attr.workflow, repository_ctx.attr.branch),
+                headers = headers,
+                output = "runs.json"
+            )
 
-        run_id = json.decode(repository_ctx.read("runs.json"))["workflow_runs"][0]["id"]
-        repository_ctx.delete("runs.json")
+            run_id = json.decode(repository_ctx.read("runs.json"))["workflow_runs"][0]["id"]
+            repository_ctx.delete("runs.json")
 
+        print("Run id:", run_id)
         repository_ctx.download(
             "https://api.github.com/repos/%s/actions/runs/%s/artifacts"
                 % (repository_ctx.attr.repo, run_id),
@@ -108,8 +115,8 @@ consensus_spec_tests = repository_rule(
         "version": attr.string(mandatory = True),
         "flavors": attr.string_dict(mandatory = True),
         "repo": attr.string(default = "ethereum/consensus-specs"),
-        "workflow": attr.string(default = "generate_vectors.yml"),
-        "branch": attr.string(default = "dev"),
+        "workflow": attr.string(default = "nightly-reftests.yml"),
+        "branch": attr.string(default = "master"),
         "release_url_template": attr.string(default = "https://github.com/ethereum/consensus-specs/releases/download/%s"),
     },
 )