codegen

ZAP v2 schema declarations

This directory holds JSON schema declarations consumed by the zapgen-all bulk emitter (see ../cmd/zapgen-all/). One file per LP family.

Format

Each .json file is a single bundle:

{
  "lp": "lp-201",
  "description": "ZAP P2P transport ...",
  "schemas": [
    {
      "wire_name": "ConsensusVote",
      "go_name":   "ConsensusVoteSchema",
      "kind":      "0xD0",
      "size":      53,
      "package":   "p2pwire",
      "out":       "lp-201/consensus_vote_zap.go",
      "fields": [
        { "name": "Round",   "type": "uint64",  "offset": 1 },
        { "name": "BlockID", "type": "bytes32", "offset": 9 }
      ]
    }
  ]
}

Field types

Two field-type families are supported:

1. Scalar fields. Type names: bool, int8/int16/int32/int64, uint8/uint16/uint32/uint64, float32/float64. Read/write via zapv2.Read / zapv2.Write with the Field[S, T] handle declared in <GoName>Fields.

2. Fixed-width byte-array fields. Type names: bytes<N> where N is a positive integer (e.g., bytes20 for NodeID/Address, bytes32 for hashes, bytes16 for session IDs, bytes96 for PQ-signature digests). Emitted as standalone typed accessor functions <WireName><FieldName>(view) [N]byte; NOT in the <GoName>Fields struct because [N]byte is not a zapv2.FieldKind member.

Variable-length tails (lists, bytes, sub-objects) are NOT declared here. They live outside the fixed payload. Convention in this dir: a field named *Off is a uint32 offset pointer into the variable- length tail; the actual tail read/write code is hand-written using zapv2.ListAt, Object.Bytes, or similar helpers.

Bundles in this directory

Total: 77 schemas declared and ready for bulk emission.

Variable-length tail convention (LP-182 + LP-186)

Each variable-length byte tail (bytes field per LP-182 §"Wire schemas" / LP-186 §"Variable-length fields") occupies an 8-byte slot in the fixed section, matching what zap.ObjectBuilder.SetBytes actually writes: {relOff uint32, length uint32} little-endian. In the JSON schema this is modeled as two uint32 fields: <Name>Off and <Name>Len. The underlying ZAP wire is unchanged — this is purely how the codegen declares the fixed-section byte layout.

LP-201 / LP-214 schemas (declared earlier) use a single *Off uint32 convention without an explicit *Len companion; their generated code remains wire-compatible because the codegen does not synthesise SetBytes calls for Off fields (callers invoke SetBytes themselves when filling tails). The LP-182 + LP-186 Off+Len convention is the preferred form going forward — it faithfully models the 8-byte slot.

Schemas out of scope (deferred)

The following schemas / kinds are declared in their LP but DO NOT yet have a fixed-section byte layout in the canonical source-of-truth file. They are flagged as "deferred pending spec amendment" rather than guessed.

LP-182 — Consensus wire (5 deferred)

Path forward for deferred LP-182 schemas: once ~/work/lux/consensus/pkg/wire/zap/*.go lands the byte-by-byte layout for each deferred kind, append the JSON schema entry to lp-182-consensus.json with the offsets matched to the source file.

LP-186 — Chains-VM wire (~12 kinds deferred)

The LP-186 §Schema table enumerates kinds that DO NOT yet have a matching wire-layout file in ~/work/lux/chains/<vm>/wire/. The kind constant exists in kind.go, but no per-kind .go file declares its fixed-section byte layout:

Path forward for deferred LP-186 schemas: once each VM's wire/ directory ships the missing per-kind .go file with a fixed-section layout comment, append the JSON schema entry to lp-186-vms.json and re-run zapgen-all.

Running the emitter

cd ~/work/lux/zap
GOWORK=off go run ./v2/codegen/cmd/zapgen-all \
  -schemas ./v2/codegen/schemas \
  -out /tmp/zap-emit

The output /tmp/zap-emit/ will contain one *_zap.go per declared schema under the out path each schema specifies. The bulk emitter prints emit <lp>/<schema> -> <path> per file plus a final summary line.

Schema-ID allocation map (canonical)

Per /tmp/SESSION-HANDOFF.md §"Schema ID Allocation":

The LP-218 file lists 0xE0..0xEF; this collides with LP-208 + LP-211. The session handoff resolves this in favour of LP-208 + LP-211; LP-218 rollups should track at their kind bytes (0x40..0x43) within a yet- to-allocate schema-ID range — likely 0xC0-bucket extensions or a dedicated 0xC bucket once chains-VM finalises. Until that resolves, the lp-218-rollup.json bundle emits at kind bytes 0x40..0x43 and is parked in its own rollupwire package; the schema-ID byte is not load-bearing for these schemas because they live in a unique package namespace.