Last State Protocol (LEP)

Binary, versioned, transport-independent contract for firmware and hardware diagnostics between devices, gateways, and servers.

v2.0.0 — VERSION

When Latch, Relay, Trace, or third-party code disagree on bytes, this repo wins.

Relay and Trace keep local LEP codecs for deployment independence, but their CI runs test-vectors/ against those codecs (PROTOCOL_VECTORS / TestProtocolVectors). Prefer changing this repo first, then bumping consumer codecs.

Wire (summary)

Item	Value
Magic	LSTP (4C 53 54 50)
Endianness	little-endian
Header	24 bytes
CRC	CRC-32/IEEE
Payload	TLV u16 type + u16 length + value
Flags	AUTH, ENC, AEAD, TRUNCATED, COMPRESSED (bit 4)

Full layout: spec/lep-v1.md, spec/lep-v2.md

Repository

spec/                 Normative text (wire, framing, crypto, …)
registry/tlv-types.md All TLV byte layouts
test-vectors/         Golden hex
implementations/go/   Reference codec
conformance/runner/   Vector checker

Doc	Topic
spec/lep-v1.md	Header, flags, validation (v1)
spec/lep-v2.md	v2 wire format, version-bound crypto
spec/integrity.md	CRC
spec/identity.md	Device / build identity
spec/encryption.md	HMAC / XChaCha AEAD
spec/compression.md	Truncation vs zstd
spec/framing.md	Stream, COBS, LSAK, fragments
spec/transports.md	UART, TCP, HTTP, …
spec/architectures.md	Arch codes, CPU/FAULT
registry/tlv-types.md	All TLV byte layouts
spec/compatibility.md	Versioning
spec/limits.md	Size bounds

Try it

Validate the reference codec and golden vectors locally:

cd implementations/go && go vet ./... && go test ./...
python conformance/runner/run.py

To add a new golden vector or update the registry:

1. Edit registry/tlv-types.md first.
2. Add or update hex vectors under test-vectors/.
3. Run the conformance runner; fix the codec if a vector no longer passes.
4. Update the CHANGELOG.md with a one-line note.

Not in this repo

Product code: HardFault handlers, SQLite spool, Trace UI, Probe PCB, cloud billing. Those live in latch, relay, and the private Trace backend.

Community and security

• Contributing guide
• Security policy
• Code of conduct
• Support
• Roadmap and changelog

Maintainers preparing a visibility change should complete the publication checklist.

License

Apache-2.0 — LICENSE