zap_codec

proto/zap_codec — ZAP-native wire codec for proto/{p,x,block,warp}

This package is the single canonical construction site for the wire codecs consumed by proto/p, proto/x, proto/p/warp, proto/p/warp/payload, proto/p/warp/message, proto/p/block, and proto/x/block.

It exists so SDK consumers (sdk/wallet/chain/{p,x}) can wire up the parser dependencies of the proto packages without importing github.com/luxfi/codec at the wallet layer. The codec backend choice is bound EXACTLY ONCE — here.

Wire-format verdict — BREAK from legacy linearcodec

This codec emits little-endian wire bytes via github.com/luxfi/codec/zapcodec. The previous linearcodec-backed construction emitted big-endian wire bytes.

For every multi-byte field — uint16/uint32/uint64, length prefixes, interface type-id discriminators, codec version bytes, string length prefixes — the byte order is inverted vs the pre-Wave-2G wire layout.

This is a forward-only wire-format change aligned with LP-023 ZAP-native activation (proto/zap_native/codec_select.go: ZAPActivationUnix=0). There is no dual-mode emission, no fallback, no rollback path. Network validators expecting LE wire bytes will accept this codec's output; validators still on BE linearcodec will not.

Canonical hex dump comparison

Test struct:

type dummyTx struct {
    NetworkID uint32 `serialize:"true"`  // 0x01020304
    Nonce     uint64 `serialize:"true"`  // 0x0102030405060708
    Memo      []byte `serialize:"true"`  // "hi"
}

Marshalled at codec version 0:

ZAP-native (this codec):
  00 00                                          ← codec version 0 (LE uint16)
  04 03 02 01                                    ← NetworkID 0x01020304 (LE uint32)
  08 07 06 05 04 03 02 01                        ← Nonce 0x0102030405060708 (LE uint64)
  02 00 00 00                                    ← Memo length 2 (LE uint32)
  68 69                                          ← Memo "hi"

linearcodec (legacy, gone after Wave 2G):
  00 00                                          ← codec version 0 (BE uint16, same byte pattern at v=0)
  01 02 03 04                                    ← NetworkID 0x01020304 (BE uint32)
  01 02 03 04 05 06 07 08                        ← Nonce 0x0102030405060708 (BE uint64)
  00 00 00 02                                    ← Memo length 2 (BE uint32)
  68 69                                          ← Memo "hi" (byte body identical)

Both encodings carry the same fields in the same order — the delta is byte order alone.

The above ZAP-native dump is captured live by TestManager_WireFormat_ZAPNative_HexDump. To reproduce:

$ go test -v ./zap_codec/... -run TestManager_WireFormat_ZAPNative_HexDump
ZAP-native canonical dummyTx hex dump:
  0000040302010807060504030201020000006869

The legacy linearcodec bytes shown above are anchored against the linearcodec spec (luxfi/codec/linearcodec); they are historical and no longer produced by any in-tree code path.

Architecture

Following Rich Hickey decomplection:

• Value, not place — the wire codec choice is a value qualified by namespace (zap_codec.NewVersionedManager). It is bound in ONE place, not braided into every consumer's package init.
• Composition over inheritance — Manager wraps zapcodec.Codec with a thin version-prefix outer layer. The outer carries the codec version (uint16 LE, matching the inner byte order). The two layers are independently complete primitives.
• Orthogonal — this package neither imports proto/{p,x} nor knows about block/tx/warp types. Per-chain type registration happens at the caller site (sdk/wallet/chain/{p/pcodecs.go,x/constants.go, x/builder/constants.go}) which RegisterTypes onto the registries returned here.
• One canonical way — there is exactly ONE construction expression per chain primitive (NewPVMRuntime, NewPVMGenesis, NewXVMParser, NewWarp, NewPayload, NewMessage). Wallet, builder, signer, genesis builder all reach for the same constructor.

Surface

Each *Manager satisfies the local Codec interface from every proto/{p,x,block,warp,payload,message} package by shape (Marshal(version, source), Unmarshal(bytes, dest), Size(version, value)) and also acts as a Registry (RegisterType, SkipRegistrations).