ChainSafe · jtraglia · Jan 23, 2026 · Jan 23, 2026 · Jan 23, 2026 · Jan 23, 2026
@@ -0,0 +1,52 @@
+name: Check Spec References
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches: [unstable, stable]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  check-specrefs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Check version consistency
+      run: |
+        SPEC_TEST_VERSION=$(grep 'specVersion:' packages/beacon-node/test/spec/specTestVersioning.ts | head -1 | sed 's/.*specVersion: "\(.*\)".*/\1/')
+        ETHSPECIFY_VERSION=$(grep '^version:' specrefs/.ethspecify.yml | sed 's/version: //')
+        if [ "$SPEC_TEST_VERSION" != "$ETHSPECIFY_VERSION" ]; then
+          echo "Version mismatch between specTestVersioning.ts and ethspecify"
+          echo "  packages/beacon-node/test/spec/specTestVersioning.ts: $SPEC_TEST_VERSION"
+          echo "  specrefs/.ethspecify.yml: $ETHSPECIFY_VERSION"
+          exit 1
+        else
+          echo "Versions match: $SPEC_TEST_VERSION"
+        fi
+
+    - name: Install ethspecify
+      run: python3 -mpip install ethspecify
+
+    - name: Update spec references
+      run: ethspecify process --path=specrefs
+
+    - name: Check for differences
+      run: |
+        if ! git diff --exit-code -- specrefs >/dev/null; then
+          echo "Spec references are out-of-date!"
+          echo ""
+          git --no-pager diff -- specrefs
+          exit 1
+        else
+          echo "Spec references are up-to-date!"
+        fi
+
+    - name: Check spec references
+      run: ethspecify check --path=specrefs
@@ -0,0 +1,279 @@
+version: v1.6.1
+style: full
+
+specrefs:
+  files:
+    - configs.yml
+    - constants.yml
+    - containers.yml
+    - dataclasses.yml
+    - functions.yml
+    - presets.yml
+    - types.yml
+
+exceptions:
+  constants:
+    # phase0
+    - ENDIANNESS#phase0
+    - ETH_TO_GWEI#phase0
+    - SAFETY_DECAY#phase0
+    - UINT64_MAX#phase0
+    - UINT64_MAX_SQRT#phase0
+
+    # deneb
+    - BLS_MODULUS#deneb
+    - BYTES_PER_COMMITMENT#deneb
+    - BYTES_PER_PROOF#deneb
+    - FIAT_SHAMIR_PROTOCOL_DOMAIN#deneb
+    - G1_POINT_AT_INFINITY#deneb
+    - KZG_ENDIANNESS#deneb
+    - KZG_SETUP_G2_LENGTH#deneb
+    - KZG_SETUP_G2_MONOMIAL#deneb
+    - PRIMITIVE_ROOT_OF_UNITY#deneb
+    - RANDOM_CHALLENGE_KZG_BATCH_DOMAIN#deneb
+
+    # fulu
+    - RANDOM_CHALLENGE_KZG_CELL_BATCH_DOMAIN#fulu
+    - UINT256_MAX#fulu
+
+    # gloas
+    - PAYLOAD_STATUS_EMPTY#gloas
+    - PAYLOAD_STATUS_FULL#gloas
+    - PAYLOAD_STATUS_PENDING#gloas
+
+  containers:
+    # gloas
+    - ForkChoiceNode#gloas
+
+  dataclasses:
+    # phase0
+    - LatestMessage#phase0
+
+    # bellatrix
+    - OptimisticStore#bellatrix
+
+    # gloas
+    - LatestMessage#gloas
+    - Store#gloas
+
+  functions:
+    # phase0
+    - bytes_to_uint64#phase0
+    - compute_fork_version#phase0
+    - get_aggregate_signature#phase0
+    - get_attestation_component_deltas#phase0
+    - get_attesting_balance#phase0
+    - get_base_reward#phase0
+    - get_checkpoint_block#phase0
+    - get_current_store_epoch#phase0
+    - get_eligible_validator_indices#phase0
+    - get_eth1_vote#phase0
+    - get_filtered_block_tree#phase0
+    - get_forkchoice_store#phase0
+    - get_head_deltas#phase0
+    - get_inactivity_penalty_deltas#phase0
+    - get_inclusion_delay_deltas#phase0
+    - get_matching_head_attestations#phase0
+    - get_matching_source_attestations#phase0
+    - get_matching_target_attestations#phase0
+    - get_proposer_reward#phase0
+    - get_proposer_score#phase0
+    - get_source_deltas#phase0
+    - get_target_deltas#phase0
+    - get_total_active_balance#phase0
+    - get_unslashed_attesting_indices#phase0
+    - get_voting_source#phase0
+    - get_weight#phase0
+    - is_candidate_block#phase0
+    - is_proposer#phase0
+    - max_compressed_len#phase0
+    - max_message_size#phase0
+    - saturating_sub#phase0
+    - seconds_to_milliseconds#phase0
+    - store_target_checkpoint_state#phase0
+    - validate_target_epoch_against_current_time#phase0
+    - voting_period_start_time#phase0
+
+    # altair
+    - add_flag#altair
+    - apply_light_client_update#altair
+    - compute_fork_version#altair
+    - compute_merkle_proof#altair
+    - compute_subnets_for_sync_committee#altair
+    - create_light_client_bootstrap#altair
+    - create_light_client_finality_update#altair
+    - create_light_client_optimistic_update#altair
+    - create_light_client_update#altair
+    - current_sync_committee_gindex_at_slot#altair
+    - eth_aggregate_pubkeys#altair
+    - eth_fast_aggregate_verify#altair
+    - finalized_root_gindex_at_slot#altair
+    - get_base_reward#altair
+    - get_subtree_index#altair
+    - get_sync_subcommittee_pubkeys#altair
+    - get_unslashed_participating_indices#altair
+    - is_assigned_to_sync_committee#altair
+    - is_next_sync_committee_known#altair
+    - is_valid_normalized_merkle_branch#altair
+    - next_sync_committee_gindex_at_slot#altair
+    - process_light_client_finality_update#altair
+    - process_light_client_optimistic_update#altair
+    - process_light_client_store_force_update#altair
+    - set_or_append_list#altair
+
+    # bellatrix
+    - compute_fork_version#bellatrix
+    - get_execution_payload#bellatrix
+    - get_pow_block_at_terminal_total_difficulty#bellatrix
+    - get_terminal_pow_block#bellatrix
+    - is_execution_block#bellatrix
+    - is_merge_transition_block#bellatrix
+    - is_optimistic#bellatrix
+    - is_optimistic_candidate_block#bellatrix
+    - is_valid_terminal_pow_block#bellatrix
+    - latest_verified_ancestor#bellatrix
+    - validate_merge_block#bellatrix
+
+    # capella
+    - compute_fork_version#capella
+    - get_lc_execution_root#capella
+    - is_fully_withdrawable_validator#capella
+    - is_partially_withdrawable_validator#capella
+
+    # deneb
+    - bit_reversal_permutation#deneb
+    - blob_to_kzg_commitment#deneb
+    - blob_to_polynomial#deneb
+    - bls_field_to_bytes#deneb
+    - bytes_to_bls_field#deneb
+    - bytes_to_kzg_commitment#deneb
+    - bytes_to_kzg_proof#deneb
+    - compute_blob_kzg_proof#deneb
+    - compute_challenge#deneb
+    - compute_fork_version#deneb
+    - compute_kzg_proof#deneb
+    - compute_kzg_proof_impl#deneb
+    - compute_powers#deneb
+    - compute_quotient_eval_within_domain#deneb
+    - compute_roots_of_unity#deneb
+    - evaluate_polynomial_in_evaluation_form#deneb
+    - g1_lincomb#deneb
+    - get_lc_execution_root#deneb
+    - hash_to_bls_field#deneb
+    - is_power_of_two#deneb
+    - multi_exp#deneb
+    - reverse_bits#deneb
+    - validate_kzg_g1#deneb
+    - verify_blob_kzg_proof#deneb
+    - verify_blob_kzg_proof_batch#deneb
+    - verify_kzg_proof#deneb
+    - verify_kzg_proof_batch#deneb
+    - verify_kzg_proof_impl#deneb
+
+    # electra
+    - compute_fork_version#electra
+    - compute_on_chain_aggregate#electra
+    - current_sync_committee_gindex_at_slot#electra
+    - finalized_root_gindex_at_slot#electra
+    - get_committee_indices#electra
+    - get_eth1_pending_deposit_count#electra
+    - get_eth1_vote#electra
+    - get_execution_requests#electra
+    - get_lc_execution_root#electra
+    - is_fully_withdrawable_validator#electra
+    - is_partially_withdrawable_validator#electra
+    - is_valid_switch_to_compounding_request#electra
+    - next_sync_committee_gindex_at_slot#electra
+
+    # fulu
+    - _fft_field#fulu
+    - add_polynomialcoeff#fulu
+    - cell_to_coset_evals#fulu
+    - compute_cells#fulu
+    - compute_cells_and_kzg_proofs#fulu
+    - compute_cells_and_kzg_proofs_polynomialcoeff#fulu
+    - compute_fork_version#fulu
+    - compute_kzg_proof_multi_impl#fulu
+    - compute_verify_cell_kzg_proof_batch_challenge#fulu
+    - construct_vanishing_polynomial#fulu
+    - coset_evals_to_cell#fulu
+    - coset_fft_field#fulu
+    - coset_for_cell#fulu
+    - coset_shift_for_cell#fulu
+    - divide_polynomialcoeff#fulu
+    - evaluate_polynomialcoeff#fulu
+    - fft_field#fulu
+    - get_beacon_proposer_indices#fulu
+    - interpolate_polynomialcoeff#fulu
+    - multiply_polynomialcoeff#fulu
+    - polynomial_eval_to_coeff#fulu
+    - recover_cells_and_kzg_proofs#fulu
+    - recover_polynomialcoeff#fulu
+    - vanishing_polynomialcoeff#fulu
+    - verify_cell_kzg_proof_batch#fulu
+    - verify_cell_kzg_proof_batch_impl#fulu
+
+    # gloas
+    - compute_balance_weighted_acceptance#gloas
+    - compute_balance_weighted_selection#gloas
+    - compute_fork_version#gloas
+    - compute_proposer_indices#gloas
+    - get_ancestor#gloas
+    - get_attestation_participation_flag_indices#gloas
+    - get_checkpoint_block#gloas
+    - get_data_column_sidecars#gloas
+    - get_data_column_sidecars_from_block#gloas
+    - get_data_column_sidecars_from_column_sidecar#gloas
+    - get_execution_payload_bid_signature#gloas
+    - get_execution_payload_envelope_signature#gloas
+    - get_expected_withdrawals#gloas
+    - get_forkchoice_store#gloas
+    - get_head#gloas
+    - get_next_sync_committee_indices#gloas
+    - get_node_children#gloas
+    - get_parent_payload_status#gloas
+    - get_payload_attestation_due_ms#gloas
+    - get_payload_attestation_message_signature#gloas
+    - get_payload_status_tiebreaker#gloas
+    - get_pending_balance_to_withdraw#gloas
+    - get_ptc_assignment#gloas
+    - get_weight#gloas
+    - has_compounding_withdrawal_credential#gloas
+    - is_parent_node_full#gloas
+    - is_payload_timely#gloas
+    - is_supporting_vote#gloas
+    - notify_ptc_messages#gloas
+    - on_block#gloas
+    - on_execution_payload#gloas
+    - on_payload_attestation_message#gloas
+    - prepare_execution_payload#gloas
+    - process_attestation#gloas
+    - process_block#gloas
+    - process_epoch#gloas
+    - process_execution_payload#gloas
+    - process_operations#gloas
+    - process_proposer_slashing#gloas
+    - process_slot#gloas
+    - process_withdrawals#gloas
+    - should_extend_payload#gloas
+    - update_latest_messages#gloas
+    - validate_merge_block#gloas
+    - validate_on_attestation#gloas
+    - verify_data_column_sidecar#gloas
+
+  custom_types:
+    # phase0
+    - Ether#phase0
+    - Hash32#phase0
+    - NodeID#phase0
+    - SubnetID#phase0
+
+    # bellatrix
+    - PayloadId#bellatrix
+
+    # fulu
+    - CellIndex#fulu
+    - CommitmentIndex#fulu
+
+    # gloas
+    - PayloadStatus#gloas
@@ -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 in 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.