lens

package module
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 16, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

README

Lens — Curve threshold kernel

Lux is not merely adding post-quantum signatures to a chain; it defines a hybrid finality architecture for DAG-native consensus, with protocol-agnostic threshold lifecycle, post-quantum threshold sealing, and cross-chain propagation of Horizon finality.

See LP-105 §Claims and evidence for the canonical claims/evidence table and the ten architectural commitments — single source of truth.

Lens is the curve-based threshold signing kernel for Lux. It is the classical sister to Pulsar (the lattice kernel at github.com/luxfi/pulsar).

Quick reference

Component Pulsar Lens
Math field Module-LWE / R_q Discrete log over a prime-order group
Sign math Ringtail Sign1/Sign2/Combine FROST 2-round (RFC 9591)
Pedersen commits A·NTT(s) + B·NTT(r) over R_q s·G + r·H over the curve
Genesis Trusted-dealer Bootstrap Trusted-dealer Bootstrap or FROST DKG
Per-epoch DKG Never — VSR via pulsar/reshare Never — VSR via lens/reshare
Lifecycle LSS-managed LSS-managed
LSS adapter threshold/protocols/lss/lss_pulsar.go threshold/protocols/lss/lss_lens.go

Curves shipped

  • Ed25519 — RFC 8032 / FIPS 186-5 EdDSA curve.
  • secp256k1 — SEC 2 / Bitcoin curve.
  • Ristretto255 — RFC 9496 prime-order group over Curve25519.

All three implement primitives.Curve. Per-curve secondary generators (H) are derived deterministically from a Lens-specific nothing-up-my-sleeve tag (lens.<curve>.h-base.v1); discrete log of H with respect to G is unknown to anyone, which is the only property Pedersen binding requires.

Package layout

primitives/  — curve abstraction, polynomial, Lagrange, Pedersen, Shamir, hash helpers
sign/        — FROST 2-round Schnorr threshold signing (RFC 9591)
threshold/   — GroupKey, KeyShare, Signer, Signature types
reshare/     — Refresh (HJKY97) + Reshare (Desmedt-Jajodia),
               Pedersen commits, complaints, transcript, pairwise KEX,
               activation cert
hash/        — HashSuite (Lens-SHA3 production / Lens-BLAKE3 legacy)
dkg/         — Distributed FROST key generation (proper distributed,
               no trusted dealer needed)
keyera/      — Bootstrap / Reshare / Reanchor lifecycle wrapper
cmd/         — KAT oracle binaries for cross-port byte-equal validation

Running

GOWORK=off go test ./...
GOWORK=off go run ./cmd/reshare_oracle -curve ed25519 -variant reshare -t_old 3 -t_new 3
GOWORK=off go run ./cmd/dkg_oracle -curve secp256k1 -n 5 -t 3

Lifecycle invariants

BLS lane:    each validator has its OWN keypair.
ML-DSA lane: each validator has its OWN keypair.
Lens lane:   each validator has a SHARE of one group key.
Pulsar lane: each validator has a SHARE of one group key.

Within a key era:

  • Master secret s is preserved across every Reshare.
  • Group public key X = s·G is byte-identical across resharing.
  • Only the share distribution rotates per epoch.

Across key eras (Reanchor): X and s are fresh.

References

  • Komlo, Goldberg 2020. FROST: Flexible Round-Optimized Schnorr Threshold Signatures. SAC 2020.
  • RFC 9591. The Flexible Round-Optimized Schnorr Threshold (FROST) Protocol for Two-Round Schnorr Signatures.
  • HJKY97. Proactive Secret Sharing or: How to Cope With Perpetual Leakage. CRYPTO.
  • Desmedt-Jajodia 1997. Redistributing Secret Shares to New Access Structures.
  • Wong-Wang-Wing 2002. Verifiable Secret Redistribution for Archive Systems.
  • Seesahai 2025. LSS MPC ECDSA: A Pragmatic Framework for Dynamic and Resilient Threshold Signatures. (LSS framework, paper-backed)
  • LP-103. Lens — Curve-Based Threshold Signatures with Dynamic Resharing. https://github.com/luxfi/lps/blob/main/LP-103-lens.md
  • LP-073. Pulsar — lattice threshold sister kernel.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package lens is the curve-based threshold signing kernel for Lux.

Lens is the classical sister to Pulsar (the lattice kernel at github.com/luxfi/pulsar). Both kernels share the same lifecycle shape — Bootstrap → Reshare* → Reanchor — and the same activation circuit-breaker contract; they differ only in the math field they operate over: 

Pulsar (PQ)        Lens (classical)
  Module-LWE         Discrete log over a prime-order group
  R_q                Curve scalar field
  Ringtail Sign      FROST 2-round Sign (RFC 9591)
  Lattice Pedersen   Curve Pedersen (g·s + h·r)

Layer separation 

github.com/luxfi/lens (this module)
  ├── primitives/    curve abstraction, polynomial, Lagrange,
  │                  Pedersen commit, Shamir
  ├── sign/          FROST 2-round signing math (RFC 9591)
  ├── threshold/     GroupKey, KeyShare, Signer types
  ├── reshare/       Refresh (HJKY97) + Reshare (Desmedt-Jajodia),
  │                  Pedersen commits, complaints, transcript,
  │                  pairwise KEX, activation cert
  ├── hash/          HashSuite (Lens-SHA3 production /
  │                  Lens-BLAKE3 legacy)
  ├── dkg/           Distributed FROST key generation
  ├── keyera/        Bootstrap / Reshare / Reanchor lifecycle
  └── cmd/*_oracle/  KAT vector generators for cross-port
                     byte-equal validation

github.com/luxfi/threshold/protocols/lss/lss_lens.go
  └── LSS adapter — wires Generation tracking, Rollback, and
      Bootstrap-Dealer / Signature-Coordinator role separation
      onto the Lens kernel.

Lifecycle invariants 

BLS lane:    each validator has its OWN keypair.
ML-DSA lane: each validator has its OWN keypair.
Lens lane:   each validator has a SHARE of one group key.
Pulsar lane: each validator has a SHARE of one group key.

Within a key era:

  • The hidden master secret s is preserved across every Reshare.
  • The group public key X = s·G is byte-identical across resharing.
  • Only the share distribution rotates per epoch.
  • The error term and dealer state from Bootstrap are erased.

Across key eras (Reanchor): X is fresh, s is fresh.

Three layers, one shipping path

  1. Bootstrap — trusted-dealer ceremony at chain genesis OR FROST DKG (proper distributed). Confined to one key era. Foundation MPC ceremony, observable, single one-time trust event.
  2. Reshare — preserves s and X; rotates share distribution. No trusted dealer. Triggered by every validator-set change.
  3. Reanchor — fresh GroupKey, new key era. Rare governance event; same trust shape as Bootstrap.

Domain separation

Every Lens-emitted message carries a distinct version-tagged prefix. No shared prefix between any two: 

QUASAR-LENS-BUNDLE-v1     — Lens threshold cert over a bundle
QUASAR-LENS-SIGN1-v1      — FROST Round 1
QUASAR-LENS-SIGN2-v1      — FROST Round 2
QUASAR-LENS-AGGREGATE-v1  — FROST aggregate
QUASAR-LENS-REFRESH-v1    — Refresh activation cert
QUASAR-LENS-RESHARE-v1    — Reshare activation cert
QUASAR-LENS-ACTIVATE-v1   — generic activation alias
QUASAR-LENS-REANCHOR-v1   — Reanchor authorization

Activation cert

After resharing finishes the math, the chain does NOT accept the new epoch on faith. The new committee threshold-signs an activation message under the UNCHANGED GroupKey using their freshly-derived shares; only when this signature verifies does the chain mark the new epoch live. See reshare/activation.go.

Cited works

  • Komlo, Goldberg 2020. "FROST: Flexible Round-Optimized Schnorr Threshold Signatures." SAC 2020.
  • RFC 9591. "The Flexible Round-Optimized Schnorr Threshold (FROST) Protocol for Two-Round Schnorr Signatures." 2024.
  • HJKY97. Herzberg-Jakobsson-Jarecki-Krawczyk-Yung. "Proactive Secret Sharing or: How to Cope With Perpetual Leakage."
  • Desmedt-Jajodia 1997. "Redistributing Secret Shares to New Access Structures."
  • Wong-Wang-Wing 2002. "Verifiable Secret Redistribution for Archive Systems."
  • Seesahai 2025. "LSS MPC ECDSA: A Pragmatic Framework for Dynamic and Resilient Threshold Signatures." (LSS framework)

Status

Production-grade. All packages have unit + integration test coverage. LSS adapter at threshold/protocols/lss/lss_lens.go.

Source Files

View all Source files

Directories

Path Synopsis
cmd
cross_runtime_oracle command
Command cross_runtime_oracle emits a deterministic Lens transcript covering DKG -> Sign -> Aggregate end-to-end, for cross-language byte-equality validation against the C++ port at luxcpp/crypto/lens/.
 Command cross_runtime_oracle emits a deterministic Lens transcript covering DKG -> Sign -> Aggregate end-to-end, for cross-language byte-equality validation against the C++ port at luxcpp/crypto/lens/.
cross_runtime_verify command
Command cross_runtime_verify loads a cross-runtime KAT JSON emitted by the C++ Lens kernel (luxcpp/crypto/lens/test/cpp/ cross_runtime_emit), drives the Go canonical with the same seed + message + salt, and asserts byte-equal across DKG / Sign / Aggregate.
 Command cross_runtime_verify loads a cross-runtime KAT JSON emitted by the C++ Lens kernel (luxcpp/crypto/lens/test/cpp/ cross_runtime_emit), drives the Go canonical with the same seed + message + salt, and asserts byte-equal across DKG / Sign / Aggregate.
dkg_oracle command
Command dkg_oracle emits a deterministic FROST DKG transcript for cross-language KAT validation.
 Command dkg_oracle emits a deterministic FROST DKG transcript for cross-language KAT validation.
reshare_oracle command
Command reshare_oracle emits Known-Answer-Test (KAT) vectors for the Lens reshare kernel.
 Command reshare_oracle emits Known-Answer-Test (KAT) vectors for the Lens reshare kernel.
Package dkg implements distributed FROST-style key generation over the curve.
 Package dkg implements distributed FROST-style key generation over the curve.
Package hash defines the canonical hashing profile used by every Lens reshare / activation / pairwise routine.
 Package hash defines the canonical hashing profile used by every Lens reshare / activation / pairwise routine.
Package keyera is the lifecycle wrapper for a Lens group lineage.
 Package keyera is the lifecycle wrapper for a Lens group lineage.
Package primitives provides the curve abstraction Lens uses for all elliptic-curve-based threshold operations.
 Package primitives provides the curve abstraction Lens uses for all elliptic-curve-based threshold operations.
Package reshare implements the two proactive secret-sharing primitives Lens needs to evolve a key era's share distribution without changing the persistent group public key.
 Package reshare implements the two proactive secret-sharing primitives Lens needs to evolve a key era's share distribution without changing the persistent group public key.
Package sign implements the FROST 2-round Schnorr threshold signing protocol (RFC 9591).
 Package sign implements the FROST 2-round Schnorr threshold signing protocol (RFC 9591).
Package threshold defines the public types Lens exposes for a threshold-signing group: GroupKey, KeyShare, Signer, Signature.
 Package threshold defines the public types Lens exposes for a threshold-signing group: GroupKey, KeyShare, Signer, Signature.
Package wire is lens's wire-format hardening boundary.
 Package wire is lens's wire-format hardening boundary.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.