ethspecify

A tool for referencing the Ethereum specifications in clients. This will:

• Help developers keep track of specification changes.
• Help auditors find important functions in client implementations.

Table of contents

• Getting Started
  • Install
  • Initialize
• Inline References
• Centralized References
  • Configure
  • Update
  • Map
  • Check
  • Exceptions
• Style Options
  • hash
  • full
  • link
  • diff

Getting Started

Install

pipx install ethspecify

Initialize

Create a .ethspecify.yml config file:

$ ethspecify init v1.6.0-beta.0
Successfully created .ethspecify.yml

To also generate a specrefs/ directory with a YAML file for each specification category, use the --specrefs flag:

$ ethspecify init v1.6.0-beta.0 --specrefs
Initializing specrefs directory: v1.6.0-beta.0
Successfully created .ethspecify.yml and specrefs/ directory

Inline References

Add <spec> tags anywhere in the codebase to reference specification items. For example:

<spec fn="is_active_validator" fork="phase0" />

Then run ethspecify to populate the tag body with the corresponding specification content:

<spec fn="is_active_validator" fork="phase0" hash="5765e850">
def is_active_validator(validator: Validator, epoch: Epoch) -> bool:
    """
    Check if ``validator`` is active.
    """
    return validator.activation_epoch <= epoch < validator.exit_epoch
</spec>

Centralized References

Specification references (specrefs) are YAML files that map specification items (constants, functions, containers, etc.) to their corresponding source file locations.

Configure

The following options can be set in the specrefs section of .ethspecify.yml:

Update

To update to a newer specification version, change the version field in .ethspecify.yml and run:

$ ethspecify

This updates the specification content in the YAML files to match the new version.

Map

Edit the YAML files to add sources for where each specification item is implemented.

If it is the entire file:

- name: BlobParameters
  sources:
    - file: ethereum/spec/src/main/java/tech/pegasys/teku/spec/logic/versions/fulu/helpers/BlobParameters.java
  spec: |
    <spec dataclass="BlobParameters" fork="fulu" hash="a4575aa8">
    class BlobParameters:
        epoch: Epoch
        max_blobs_per_block: uint64
    </spec>

If it is multiple entire files:

- name: BlobsBundleDeneb
  sources:
    - file: ethereum/spec/src/main/java/tech/pegasys/teku/spec/datastructures/execution/BlobsBundle.java
    - file: ethereum/spec/src/main/java/tech/pegasys/teku/spec/datastructures/builder/BlobsBundleSchema.java
    - file: ethereum/spec/src/main/java/tech/pegasys/teku/spec/datastructures/builder/versions/deneb/BlobsBundleDeneb.java
    - file: ethereum/spec/src/main/java/tech/pegasys/teku/spec/datastructures/builder/versions/deneb/BlobsBundleSchemaDeneb.java
  spec: |
    <spec dataclass="BlobsBundle" fork="deneb" hash="8d6e7be6">
    class BlobsBundle(object):
        commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK]
        proofs: List[KZGProof, MAX_BLOB_COMMITMENTS_PER_BLOCK]
        blobs: List[Blob, MAX_BLOB_COMMITMENTS_PER_BLOCK]
    </spec>

If it is a specific part of a file:

- name: EFFECTIVE_BALANCE_INCREMENT
  sources:
    - file: ethereum/spec/src/main/resources/tech/pegasys/teku/spec/config/presets/mainnet/phase0.yaml
      search: "EFFECTIVE_BALANCE_INCREMENT:"
  spec: |
    <spec preset_var="EFFECTIVE_BALANCE_INCREMENT" fork="phase0" hash="23dfe52c">
    EFFECTIVE_BALANCE_INCREMENT: Gwei = 1000000000
    </spec>

Regex is also supported in searches:

- name: ATTESTATION_DUE_BPS
  sources:
    - file: ethereum/spec/src/main/resources/tech/pegasys/teku/spec/config/configs/mainnet.yaml
      search: "^ATTESTATION_DUE_BPS:"
      regex: true
  spec: |
    <spec config_var="ATTESTATION_DUE_BPS" fork="phase0" hash="929dd1c9">
    ATTESTATION_DUE_BPS: uint64 = 3333
    </spec>

Check

Run the check command in CI to verify all specification items are properly mapped:

$ ethspecify check
MISSING: constants.BLS_MODULUS#deneb

Exceptions

Some specification items may not have a corresponding implementation. Add them to the exceptions list in .ethspecify.yml:

specrefs:
  exceptions:
    containers:
      # Not defined, unnecessary
      - Eth1Block

    functions:
      # No light client support
      - is_valid_light_client_header
      - process_light_client_update

Style Options

This attribute can be used to change how the specification content is shown.

hash

This style adds a hash of the specification content to the <spec> tag, without showing the content.

<spec fn="apply_deposit" fork="electra" hash="c723ce7b" />

full

This style displays the whole content of this specification item, including comments.

<spec fn="is_fully_withdrawable_validator" fork="deneb" style="full">
def is_fully_withdrawable_validator(validator: Validator, balance: Gwei, epoch: Epoch) -> bool:
    """
    Check if ``validator`` is fully withdrawable.
    """
    return (
        has_eth1_withdrawal_credential(validator)
        and validator.withdrawable_epoch <= epoch
        and balance > 0
    )
</spec>

link

This style displays a link to the specification item's source on GitHub. For a tagged version, the link uses the tag as the ref:

<spec ssz_object="BeaconState" fork="gloas" version="v1.7.0-alpha.11" style="link">
https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/gloas/beacon-chain.md?plain=1#L411-L468
</spec>

For nightly, the link uses a commit permalink instead of the tag:

<spec fn="apply_pending_deposit" fork="electra" style="link">
https://github.com/ethereum/consensus-specs/blob/99cc40f9317a15ea185690cee6095297fc571dda/specs/electra/beacon-chain.md?plain=1#L960-L975
</spec>

diff

This style displays a diff with the previous fork's version of the specification.

<spec ssz_object="BeaconState" fork="electra" style="diff">
--- deneb
+++ electra
@@ -27,3 +27,12 @@
     next_withdrawal_index: WithdrawalIndex
     next_withdrawal_validator_index: ValidatorIndex
     historical_summaries: List[HistoricalSummary, HISTORICAL_ROOTS_LIMIT]
+    deposit_requests_start_index: uint64
+    deposit_balance_to_consume: Gwei
+    exit_balance_to_consume: Gwei
+    earliest_exit_epoch: Epoch
+    consolidation_balance_to_consume: Gwei
+    earliest_consolidation_epoch: Epoch
+    pending_deposits: List[PendingDeposit, PENDING_DEPOSITS_LIMIT]
+    pending_partial_withdrawals: List[PendingPartialWithdrawal, PENDING_PARTIAL_WITHDRAWALS_LIMIT]
+    pending_consolidations: List[PendingConsolidation, PENDING_CONSOLIDATIONS_LIMIT]
</spec>

This can be used with any specification item, like functions too:

<spec fn="is_eligible_for_activation_queue" fork="electra" style="diff">
--- phase0
+++ electra
@@ -4,5 +4,5 @@
     """
     return (
         validator.activation_eligibility_epoch == FAR_FUTURE_EPOCH
-        and validator.effective_balance == MAX_EFFECTIVE_BALANCE
+        and validator.effective_balance >= MIN_ACTIVATION_BALANCE
     )
</spec>