Skip to content

Add how-to for debugging blocks with the native zesu binary #21

Description

@bgravenorst

Summary

The native zesu binary is the practical reference for two debugging workflows:

  • zkVM integrators validating their wiring by comparing their guest's 41-byte commitment to the native binary's commitment for the same input.
  • Operators reproducing a failing block locally during incident response, without involving any zkVM.

The docs don't currently cover either workflow. This issue asks for a how-to that does.

Suggested scope

  • How to obtain a block bundle to test against: capture one from an execution client, use one of the canonical fixtures, or generate one with the available tooling.
  • Running the native zesu binary against that input.
  • Comparing the 41-byte commitment against an expected value, or against the commitment a zkVM integration produces for the same input.
  • Interpreting a divergence — what it does and doesn't tell you about where the bug lives.

Out of scope

  • How to capture witnesses from a specific execution client. Witness production is covered in docs/concepts/witness-retrieval.mdx; this page should reference it rather than duplicate it.
  • The full zkVM integration flow. That belongs in the integrator content elsewhere.
  • Architecture of the native binary internals. Zesu is currently alpha and a fast-moving target — documentation should stay focused on user-facing usage rather than implementation details.

Notes

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions