warp/SUBMISSION.md

Warp Cross-Chain Messaging — Submission Cover Sheet

This document is the Tier A cover sheet for Lux Warp, the cross-chain messaging protocol for the Lux Network. It is written for cryptographic reviewers and auditors and points at every artifact a reviewer needs.

The warp repository is the single canonical home for the protocol: Go reference implementation in the module root, wire- format specification in SPECIFICATION.md, KAT oracle in cmd/envelope_kat_oracle/, post-quantum profile registry in PQ_PROFILES.md, deployment runbook in DEPLOYMENT-RUNBOOK.md, patent grant in PATENTS.md. There is exactly one canonical implementation, exactly one canonical wire format, exactly one canonical posture registry.

The repository is active (not frozen). Reviewer feedback and post-submission patches land in this same repository so the artifact chain stays auditable.

Date stamp (this revision): 2026-05-18.

Maturity stamp: Tier A — production wire format, PQ-native posture default, BSD-3-Clause-Eco licensed. Not NIST submitted; not FIPS 140-3 validated; not ACVP-validated. Cryptographic primitives (BLS12-381, ML-DSA-65, R-LWE threshold) live in their own audited modules; warp is the wire envelope + posture gate.

At a glance

Field	Value
Protocol name	Lux Warp (PQ-native generation)
Owning organisation	Lux Industries, Inc.
Wire format	Envelope — ZAP canonical-TLV, "LWZP"‖0x01 magic + 0x02 kind byte
Beam lane	BLS12-381 aggregate over BeamSigningBytes(D)
Pulse lane	Pulsar / Corona R-LWE threshold signature over PulseSigningBytes(D)
MLDSACertSet lane	FIPS 204 ML-DSA-65 per-validator attestations over MLDSASigningBytes(D)
Default posture	PQ-native (signature.NewPQNativeRegistry) — ML-DSA-65 preferred, classical opt-in only
Repository	https://github.com/luxfi/warp
Module path	github.com/luxfi/warp
License	BSD-3-Clause-Eco — see LICENSE
Patent posture	Royalty-free grant — see PATENTS.md
Reference implementation	Go canonical in module root
Cross-language ports	Rust (lux_warp), TypeScript (@luxfi/warp) — pinned to KAT manifest
Spec	SPECIFICATION.md (wire format) + PQ_PROFILES.md (security profiles)
KAT vectors	scripts/kat/envelope_kat.json (generated by cmd/envelope_kat_oracle/)
Cryptographer sign-off	CRYPTOGRAPHER-SIGN-OFF.md

Headline claim

Every Warp envelope produced under the canonical PQ-native posture binds the source-chain's MLDSACertSet (FIPS 204 ML-DSA-65 per-validator attestations) and / or Pulse (R-LWE threshold signature) to the same digest D — and thus the same Message — that the classical BLS Beam attests to. Under strict-PQ mode (pq.ModeStrictPQ) the envelope verifier REFUSES any envelope lacking PQ evidence with the canonical sentinel pq.ErrClassicalAuthForbidden.

This is the PQ-native posture claim. A chain pinned strict-PQ cannot accept a classical-only cross-chain message even when the binary supports BLS verification — the posture gate runs BEFORE any signature verification work.

What is in scope

Warp's responsibility is the envelope wire format plus the posture gate. Specifically:

1. Envelope format stability. The Envelope ZAP canonical-TLV encoding is byte-stable across Go / Rust / TypeScript reference implementations. KAT vectors in scripts/kat/envelope_kat.json are byte-exact and cross-language conformance is the acceptance test.

2. Domain separation. Each lane signs the SAME digest D under its OWN per-lane tag: BeamSigningBytes(D) = "LUX-WARP-ZAP-BEAM-v1" ‖ D, PulseSigningBytes(D) = "LUX-WARP-ZAP-PULSE-v1" ‖ D, MLDSASigningBytes(D) = "LUX-WARP-ZAP-MLDSA-v1" ‖ D. The three tags are mutually distinct and distinct from any Pulsar consensus prefix ("QUASAR-PULSAR-BUNDLE-v1") — a signature in one lane cannot be replayed in another. (At the scheme layer the registry also binds the FIPS 204 §5.2 context string SignContextWarpV1 = "lux-warp-cross-chain-v1" into each per-validator ML-DSA-65 / SLH-DSA signature.)

3. Transcript binding. D is computed over the full Message c14n — NetworkID || SourceChainID || SourceNebulaRoot || SourceKeyEraID || SourceGeneration || HashSuiteID (length-prefixed) || Payload (length-prefixed). Folding the lineage into the signed subject means every lane that signs DST ‖ D inherits the full transcript binding — no separate transcript-construction step is required.

4. Posture gate. The pq.Mode value (one of classical, hybrid, strict-pq) gates whether the envelope is admitted. The gate is the SINGLE function pq.ValidateMode(mode, env, verify) — five lines, one place, one error sentinel (pq.ErrClassicalAuthForbidden).

5. Replay protection. Envelope.ID() == Message.ID() == D — the Message digest (recomputed from the struct, never sliced from the wire) is the destination-chain dedup key.

What is OUT of scope

Warp does NOT claim:

1. PQ hardness of the underlying primitives. ML-DSA-65 rests on Module-LWE / Module-SIS (NIST FIPS 204 analysis). R-LWE threshold rests on Ring-LWE (Pulsar / Corona analysis). BLS aggregate rests on the co-CDH assumption (LP-075 analysis). Warp inherits these assumptions; it does not prove them.

2. Bridge quorum security inheritance. The destination-chain verifier validates the source-chain's signature material under the source-chain's validator set + quorum. A compromised source-chain validator set produces valid-but-malicious envelopes that warp cannot detect. Bridge-level trust is the verifier's responsibility, not warp's.

3. Network-layer integrity / liveness. Warp produces signed envelopes; transport-layer integrity (encryption, replay- window, congestion control) is the responsibility of the transporter. Inter-node carriers in the Lux ecosystem use github.com/luxfi/zap for transport — see TRANSPORT.md.

4. Aggregation of ML-DSA attestations. FIPS 204 has no native aggregation primitive. Warp's MLDSACertSet is N independent per-validator attestations; future Z-Chain Groth16 rollup compresses verification cost but does NOT compress the verification work to "succinct PQ" — see pulsar/classification.go and the disclaimer in pulsar/groth16_classification_test.go.

PQ-native posture — the canonical default

The signature registry (crypto/signature.NewPQNativeRegistry) is PQ-native by construction:

r := signature.NewPQNativeRegistry()       // Config.LegacyClassicalEnabled = false
r.Register(signature.SchemeMLDSA65, ...)    // OK — PQ scheme
r.Register(signature.SchemeBLS, ...)        // → signature.ErrClassicalRequiresOptIn

Classical schemes (bls, ed25519, secp256k1) are admitted ONLY when the operator explicitly opts in:

r := signature.NewRegistryFromConfig(signature.Config{
    LegacyClassicalEnabled: true,
})
r.Register(signature.SchemeBLS, ...)        // OK with opt-in

The opt-in flag is documented in LEGACY-CLASSICAL.md alongside the deprecation timeline. Every chain config that wants classical fallback MUST write this flag down in its config — no implicit fallback exists.

The chain-level gate (pq.Mode) is independent: even with the registry opted in to classical, a chain pinned strict-pq still refuses classical envelopes at the verifier boundary. The two gates are decomplected (registry posture is about which schemes are installable; chain posture is about which schemes are trusted) — both must agree for a classical envelope to verify.

Wire-format determinism

KAT manifest at scripts/kat/envelope_kat.json is regenerated by:

cd ~/work/lux/warp && go run ./cmd/envelope_kat_oracle/

Output is byte-identical across hosts / OSes / Go versions. The test TestE2E_KAT_PQEnvelope_WireBytesStable (in cross_chain_envelope_e2e_test.go) recomputes the SHA-256 over the canonical PQ envelope's wire bytes and refuses any drift.

Cross-language ports (Rust lux_warp, TypeScript @luxfi/warp) consume the manifest and MUST reproduce envelope_wire_hex byte-for-byte. This is the protocol's wire-stability commitment.

Verification chain

Envelope wire bytes
  ParseEnvelope  (ZAP decoder; structural verify)
  ↓
Envelope struct (Message + optional PQ lanes)
  pq.ValidateMode(mode, env, verify)  (posture gate; one function)
  ↓
{ classical → BLS Beam verify } ∨
{ PQ-evidenced → ML-DSA cert-set verify } ∨
{ PQ-evidenced → Pulsar Pulse verify }
  ↓
nil   |   error

Each step is a single function in a single file:

Step	Function	File
Wire decode	ParseEnvelope	envelope.go
Structural verify	(*Envelope).Verify	envelope.go
Posture gate	pq.ValidateMode	github.com/luxfi/pq/gate.go
Lane router	LanesForMode	security_profile.go
BLS Beam verify	VerifyEnvelope	envelope.go
ML-DSA cert-set verify	MLDSACertSetVerifier.VerifyCertSet	caller-supplied
Pulsar Pulse verify	pulsar.KernelVerifier.VerifyPulse	pulsar/pulsar.go

How to audit this submission

1. Read this cover sheet for scope.
2. Read PROOF-CLAIMS.md for what's claimed and what's NOT.
3. Read TRUSTED-COMPUTING-BASE.md for the TCB inventory.
4. Read SPECIFICATION.md for the wire format.
5. Read PQ_PROFILES.md for the posture taxonomy.
6. Read LEGACY-CLASSICAL.md for the classical-opt-in policy.
7. Run GOWORK=off go test -count=1 -race -timeout 240s ./... from the module root (expect the root warp package + crypto/ signature package green; precompile package has a transitive geth/verkle issue out of scope here).
8. Regenerate the KAT manifest: go run ./cmd/envelope_kat_oracle/. Diff against committed scripts/kat/envelope_kat.json — MUST be byte-identical.
9. Read CRYPTOGRAPHER-SIGN-OFF.md for the verdict and gates.

References

• LP-021 — Warp classical Beam-only messaging (legacy lineage).
• LP-021v2 — Warp hybrid envelope (this spec).
• LP-073 — Pulsar lattice threshold kernel.
• LP-075 — BLS aggregate (Beam).
• LP-105 — Lux Stack Lexicon (Beam, Pulse, Prism, Horizon).
• NIST FIPS 204 — ML-DSA Module-Lattice-Based Digital Signature Standard.
• NIST FIPS 205 — SLH-DSA Stateless Hash-Based Digital Signature Standard.

---

Document metadata

• Name: SUBMISSION.md
• Version: v1.0 (Tier A)
• Date: 2026-05-18