mirror of
https://github.com/luxfi/warp.git
synced 2026-10-30 15:13:04 +00:00
zeekay
948ee85a9c
Implements the LP-021v2 / LP-105 §"Warp evolution" cross-chain envelope
that carries the Warp 1.x BLS Beam intact alongside transcript-binding
fields and two optional PQ lanes (Pulsar Pulse, ML-DSA cert set).
Wire format: leading 0x02 version byte + RLP-encoded EnvelopeV2 record
binding SourceNebulaRoot, SourceKeyEraID, SourceGeneration, HashSuiteID
(default "Pulsar-SHA3"), plus optional PulsarPulse and MLDSACertSet
lanes. Forward compatibility: ParseEnvelope decodes Warp 1.x bytes into
a v2 envelope with PQ lanes empty. Backward compatibility: v1 receivers
reject v2 bytes (the 0x02 leading byte is not a valid RLP-list prefix);
senders that need to reach v1-only verifiers emit Warp 1.x bytes on the
v1 channel. Replay protection is uniform: EnvelopeV2.ID() returns the
embedded Message.ID().
Verification: VerifyV2 checks structural invariants, hash-suite
consistency, BLS Beam (against the source-chain validator set), then
the optional ML-DSA cert-set and Pulsar Pulse lanes. VerifyPQLanes is
the standalone entrypoint for callers that already verified the Beam
through a separate code path.
Subpackage warp/pulsar holds the Pulse path:
- KernelVerifier consumes a GroupKeyResolver (the destination chain's
source-chain key registry) to fetch the source-chain GroupKey for
a given (KeyEraID, Generation) and verifies the Pulse via the
luxfi/pulsar kernel.
- BuildSigningBytes produces the canonical transcript bytes under the
WARP-PULSAR-ENVELOPE-v1 domain prefix (distinct from any Pulsar
consensus-side prefix to prevent cross-domain replay).
- HorizonFromEnvelope lifts a verified envelope into the LP-105
HorizonCertificate shape consumed by destination consensus / bridge
code.
Pulse byte format wraps the kernel Signature's C / Z / Delta components
in three little-endian length-prefixed frames so DeserializePulse can
dispatch each component into a fresh slice-backed lattigo buffer
(the recommended path for slice-backed reads).
Tests:
- envelope_test.go: roundtrip, optional-field defaulting, forward /
backward / unknown-version dispatch, ID stability, PQ-lane
verifier dispatch (Pulse, CertSet, required-but-absent flags).
- pulsar/pulsar_test.go: real t-of-n Pulsar ceremony, serialize /
deserialize roundtrip, KernelVerifier accept / reject paths
(transcript-tampering rejection, resolver failure, suite mismatch),
BuildSigningBytes binds every transcript field, Horizon assembly.
Module wiring: adds github.com/luxfi/pulsar (replace ../pulsar) and
github.com/luxfi/lattice/v7 to warp/go.mod. Restores the pinned
luxfi/precompile h1: hash so go test ./... resolves cleanly.
Documentation: README.md and SPECIFICATION.md rewritten to describe the
shipping v1.x + v2.0 + v2-Private versions, the dispatch flow, and the
Pulse transcript-binding rules.
LP refs: LP-021 (Warp 1.x), LP-021v2 (this work), LP-073 (Pulsar
kernel), LP-075 (BLS aggregate), LP-105 §"Warp evolution".
All warp tests pass: GOWORK=off go test ./...
61 lines
1.9 KiB
Bash
Executable File
61 lines
1.9 KiB
Bash
Executable File
#!/usr/bin/env bash
|
||
# regen-kats.sh — deterministic regeneration + verification of every
|
||
# Warp 2.0 envelope KAT consumed by cross-language ports.
|
||
#
|
||
# Outputs:
|
||
# scripts/kat/envelope_kat.json — RLP-framed EnvelopeV2 vectors
|
||
# (4 entries spanning Pulse/Cert
|
||
# presence × signer-set sizes)
|
||
#
|
||
# Also runs the in-tree envelope tests so a ports change that breaks
|
||
# the v1↔v2 round-trip surfaces in the same script the manifest does.
|
||
|
||
set -euo pipefail
|
||
|
||
WARP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||
KAT_DIR="${WARP_DIR}/scripts/kat"
|
||
MANIFEST="${WARP_DIR}/scripts/regen-kats.manifest.sha256"
|
||
|
||
VERIFY=0
|
||
if [[ "${1:-}" == "--verify" ]]; then
|
||
VERIFY=1
|
||
fi
|
||
|
||
cd "${WARP_DIR}"
|
||
mkdir -p "${KAT_DIR}"
|
||
|
||
echo "[1/3] envelope_kat_oracle → ${KAT_DIR}/envelope_kat.json"
|
||
WARP_ENVELOPE_KAT_PATH="${KAT_DIR}/envelope_kat.json" \
|
||
go run ./cmd/envelope_kat_oracle >/dev/null
|
||
|
||
echo "[2/3] in-tree envelope round-trip tests"
|
||
go test -count=1 -run "TestEnvelopeV2" ./ >/dev/null
|
||
|
||
echo "[3/3] in-tree warp/pulsar threshold tests"
|
||
go test -count=1 ./pulsar >/dev/null
|
||
|
||
# Build sha256 manifest deterministically.
|
||
TMP_MANIFEST="$(mktemp)"
|
||
trap 'rm -f "${TMP_MANIFEST}"' EXIT
|
||
|
||
find "${KAT_DIR}" -maxdepth 1 -name "*.json" -type f | sort | while read -r f; do
|
||
rel="${f#${WARP_DIR}/}"
|
||
shasum -a 256 "$f" | awk -v p="${rel}" '{print $1" "p}'
|
||
done > "${TMP_MANIFEST}"
|
||
|
||
if [[ "${VERIFY}" == "1" ]]; then
|
||
if [[ ! -f "${MANIFEST}" ]]; then
|
||
echo "ERROR: --verify requested but no prior manifest at ${MANIFEST}"
|
||
exit 2
|
||
fi
|
||
if ! diff -u "${MANIFEST}" "${TMP_MANIFEST}"; then
|
||
echo "FAIL: manifest mismatch — Warp KAT regeneration is non-deterministic" >&2
|
||
exit 3
|
||
fi
|
||
echo "OK: Warp KAT regeneration is byte-equal across runs ($(wc -l < "${MANIFEST}") files)"
|
||
else
|
||
cp "${TMP_MANIFEST}" "${MANIFEST}"
|
||
echo "wrote manifest: ${MANIFEST}"
|
||
cat "${MANIFEST}"
|
||
fi
|