Update Inputs/Outputs

[bgravenorst]

Updates the Zesu inputs and outputs.

Fixes #41

[Copilot]

🟡 Changes recommended

The docs currently hardcode a fixed 43-byte commitment and a 43-byte “all-zero” undecodable-input output, which conflicts with the linked Issue #41 requirement for a variable-length commitment and a canonical default-failure output.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates the Zesu documentation to reflect a revised stateless input/output contract, including introducing a schema-ID prefix for SSZ inputs and updating multiple pages that reference the public output commitment size and EIP-8025 links.

Changes:

• Updates the inputs/outputs contract doc to include a schema ID prefix and adjusts the documented public output layout.
• Revises CLI/install/architecture docs to reference the new fork-selection mechanism and updated commitment size.
• Switches EIP-8025 links to the canonical eips.ethereum.org location and simplifies the “draft” warning text.

File summaries

File	Description
docs/reference/cli-options.mdx	Updates fork override wording and changes the documented stdout commitment size reference.
docs/get-started/install-native.mdx	Updates the “next steps” reference to the documented commitment size.
docs/concepts/inputs-and-outputs.mdx	Substantial rewrite of the documented stateless input/output contract (schema ID prefix, new field breakdown, failure-output section).
docs/concepts/architecture.mdx	Updates commitment-size references and EIP-8025 link/warning text in the pipeline description.

Review details

Suppressed comments (5)

docs/concepts/inputs-and-outputs.mdx:121

• The docs hardcode a ProtocolFork numeric mapping (0x15 is Amsterdam), but the linked issue notes the enum was remapped; this is likely to go stale or be wrong unless you cite the authoritative spec section.

The `ProtocolFork` index is the stable fork enum the stateless schemas are keyed by, where
`0x15` is Amsterdam.
Zesu implements every fork in one binary, so it applies the rules the index names instead
of assuming a single fork.

docs/concepts/inputs-and-outputs.mdx:127

• This section asserts rejection behavior and a single supported schema revision as an implementation fact. If this is a spec requirement, it should be phrased as such (or backed by a Zesu/source link), otherwise it risks documenting behavior Zesu may not guarantee.

Zesu rejects an input whose fork index the enum doesn't define, and any revision other
than `0x01`.
A guest can't execute rules it doesn't have, and the container layout is pinned to the
revision.

docs/concepts/inputs-and-outputs.mdx:158

• This says the commitment is always 43 bytes, but Issue #41 explicitly notes the commitment length is now variable (and introduces a new canonical default-failure output). The text here should reflect the variable-length contract.

Zesu serializes this `StatelessValidationResult` as a 43-byte SSZ commitment.
Every field is fixed-size, so the commitment is always 43 bytes.

docs/concepts/inputs-and-outputs.mdx:191

• This describes undecodable-input output as 43 zero bytes, but Issue #41 states the spec introduced a new 73-byte canonical _default_failed_stateless_output / DEFAULT_FAILED_OUTPUT and that commitment length is variable. The docs should match that contract.

- **Undecodable input**: Zesu can't decode the SSZ input, so it has no request root or
  schema to report. It emits 43 zero bytes, the
  [`_default_failed_stateless_output`](https://eips.ethereum.org/EIPS/eip-8025#guest-validation)
  defined by EIP-8025. A rejected input must produce exactly these bytes to match the
  reference guest.

docs/concepts/architecture.mdx:139

• This bullet hardcodes the commitment size as 43 bytes, but Issue #41 notes the commitment length is variable (including a canonical default-failure output). This reference should avoid a fixed byte count.

- [Inputs and outputs](./inputs-and-outputs.mdx): the `StatelessInput` structure and the
  43-byte public commitment.
- [Witness retrieval](./witness-retrieval.mdx): how Zesu obtains the witness it needs to

• Files reviewed: 4/4 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The updated input/output shapes and commitment sizing appear to conflict with the linked issue/spec notes (notably variable commitment length and the 73-byte default-failure output), so the docs risk being materially incorrect.

Review details

Suppressed comments (10)

Previously missed (2) — in code that hasn't changed since the last review.

docs/concepts/inputs-and-outputs.mdx:116

• This section says the input has no fork name and that a 2-byte schema ID prefix encodes (ProtocolFork index, schema revision). In the spec update referenced by issue #41 / Zesu PR #77, the fork selection is encoded via chain_config (ProtocolFork index + activation data), and the schema-id prefix/meaning differs. As written, this would cause an incorrect wire-format description.
  docs/reference/cli-options.mdx:64
• The --fork flag is documented as overriding fork rules selected by the input's schema ID. Based on the spec update referenced in issue #41, fork selection is driven by the input's chain_config (including fork index/activation), so this description and link target are likely misleading.

docs/concepts/inputs-and-outputs.mdx:58

• The mermaid diagram hard-codes a 2-byte schema_id prefix and a 43-byte public output. The linked spec update (issue #41 / Zesu PR #77) indicates the input still carries chain_config (with activation fields and a ProtocolFork index) and the output commitment length can vary (including a canonical 73-byte default-failure output), so this diagram likely no longer reflects the actual I/O contract.

    subgraph input["`**Private input** (schema ID + StatelessInput)<br/>not visible to verifiers`"]
        direction TB
        F0["schema_id (2-byte prefix)"]
        F1[new_payload_request]
        F2[witness]
        F3[chain_id]
        F4[public_keys]
    end
    subgraph zkvm["`**zkVM**`"]
        Z["`**Zesu**<br/>(guest)`"]
    end
    subgraph pubout["`**Public output** (43 bytes)<br/>visible to verifiers`"]
        direction TB
        O1["new_payload_request_root (32 bytes)"]
        O2["successful_validation<br/>(1 byte)"]
        O3["chain_id (8 bytes)"]
        O4["schema_id (2 bytes)"]
    end

docs/concepts/inputs-and-outputs.mdx:85

• StatelessInput is documented here as { new_payload_request, witness, chain_id, public_keys }, but the referenced spec change for issue #41 calls out chain_config (with new activation-related fields) as the surface that changed. This looks like a contract mismatch: consumers following this doc will omit chain_config and fork/activation data.

```python
class StatelessInput:
    new_payload_request: NewPayloadRequest
    witness: ExecutionWitness
    chain_id: uint64
    public_keys: Tuple[Bytes, ...]

**docs/reference/cli-options.mdx:156**
* This line hard-codes the public output as a 43-byte SSZ commitment, but issue #41 notes the commitment length is variable (and includes a 73-byte default-failure output). Consider removing the byte count here to avoid going stale.

Zesu writes its public output (the 43-byte SSZ commitment, or the JSON summary

**docs/concepts/inputs-and-outputs.mdx:164**
* The validation-result commitment is described as a fixed 43-byte structure with `(chain_id, schema_id)` fields. Issue #41 / Zesu PR #77 instead describes the output as having variable length (because of the `chain_config` trailer) and introduces a canonical 73-byte DEFAULT_FAILED_OUTPUT for decode failures. The byte layout/table here likely needs to be updated to match the current commitment shape(s).

Zesu serializes this StatelessValidationResult as a 43-byte SSZ commitment.
Every field is fixed-size, so the commitment is always 43 bytes.

Bytes	Field	Description
[0..32]	new_payload_request_root	SSZ hash_tree_root of the NewPayloadRequest
[32]	successful_validation	0x01 for success, 0x00 for failure
[33..41]	chain_id	Chain ID as a little-endian uint64
[41..43]	schema_id	Input schema ID as a little-endian uint16

**docs/concepts/inputs-and-outputs.mdx:190**
* For undecodable inputs, the doc says Zesu emits 43 zero bytes. In the referenced spec update (issue #41 / Zesu PR #77), the canonical decode-failure output is a specific 73-byte `DEFAULT_FAILED_OUTPUT` (not a 43-byte all-zero buffer), and verifiers/fixtures require an exact byte match.

• Undecodable input: Zesu can't decode the SSZ input, so it has no request root or
  schema to report. It emits 43 zero bytes, the
  _default_failed_stateless_output
  defined by EIP-8025. A rejected input must produce exactly these bytes to match the
  reference guest.

**docs/get-started/install-native.mdx:103**
* This page now states the binary produces a 43-byte commitment, but issue #41 calls out that the commitment length is variable (and not a single fixed size). It would be safer to avoid a hard-coded byte count here and defer to the Inputs/Outputs page for the exact structure.

the binary accepts and the 43-byte commitment it produces.

**docs/concepts/architecture.mdx:39**
* This section hard-codes the public output as a 43-byte commitment. The spec update referenced by issue #41 indicates the commitment length is variable (including a 73-byte default-failure output), so this should not claim a fixed size.

the block against the witness, and emits a 43-byte public commitment via write_output.

**docs/concepts/architecture.mdx:138**
* This cross-reference describes the commitment as 43 bytes, but issue #41 indicates the commitment size is variable. Removing the hard-coded size here avoids propagating potentially incorrect details.

43-byte public commitment.

- **Files reviewed:** 4/4 changed files
- **Comments generated:** 0 new
- **Review effort level:** Lite
</details>