fhe/pkg/threshold/doc.go

// Copyright (C) 2025-2026, Lux Industries Inc. All rights reserved.
// SPDX-License-Identifier: BSD-3-Clause

// Package threshold is the ONE threshold-FHE implementation for Lux — the
// F-Chain confidential-decrypt lane. It is held to the trustless-by-default law:
// no trusted dealer (dealerless key generation) and no reconstruction of the FHE
// secret key at decrypt time, the same standard Corona / Pulsar / Magnetar meet.
//
// There is exactly one way to do each thing here. The canonical trustless flow:
//
//	pub, shares := DealerlessKeyGen(params, t, n, crsSeed)   // dealerless keygen
//	ct           := encrypt(pub, m)                          // collective public key
//	d_j          := PartialDecryptLWE(shares[j], ct, …)      // per-party, no s formed
//	m            := CombineLWE(ct, {d_j}_{|S|≥t}, …)         // s masked behind c_1, never recovered
//
// File map (decomplected — each file is one concern, no overlap):
//
//   - dealerless_dkg.go — THE production key generation. Dealerless (GJKR/Pedersen
//     DKG composed with the audited Lattigo multiparty CKG): each committee
//     member samples only its own contribution s_j, the collective secret
//     s = Σ s_j is NEVER formed, and the output is the collective LWE public key
//     plus one t-of-n LWEShare per party.
//
//   - partial_decrypt.go — THE threshold decryption (AJL+12 noise-flooding with
//     Bendlin-Damgård denominator clearing). PartialDecryptLWE / CombineLWE are
//     no-reconstruct: the secret s appears only as the coefficient of the public
//     c_1 inside the masked aggregate and is never materialised. ShareLWESecretKey
//     in this file is a TRUSTED-DEALER split of a whole key — retained only as a
//     test/KAT oracle for the same LWEShare type; production uses DealerlessKeyGen.
//
//   - lsss.go + keygen.go — a SEPARATE primitive: large-prime Shamir VSS with
//     Feldman commitments, and GenerateSharedKey, which shares the SHA-256 *hash*
//     of a serialized key. This is a key-COMMITMENT / verifiable-secret-sharing
//     facility (audit, dealer-equivocation checks). Its KeyShare values are shares
//     of a hash and are NOT usable for threshold DECRYPTION — do not mistake
//     GenerateSharedKey for the threshold-FHE keygen; that is DealerlessKeyGen.
//
// Scope and residual. This package realises the trustless confidential-DECRYPT
// lane completely: dealerless generation of the encryption key + t-of-n shares,
// and no-reconstruct threshold decryption. It deliberately does NOT generate the
// FHEW blind-rotation / bootstrap (evaluation) key, which homomorphic COMPUTE on
// committee ciphertexts requires. Dealerless bootstrap-key generation is a
// distinct multiparty-FHEW protocol (collaborative RGSW key generation) and is
// the documented residual — it is not faked here. Until it lands, the committee
// can trustlessly ENCRYPT (collective public key) and trustlessly threshold-
// DECRYPT (the launch-critical confidentiality property); homomorphic compute on
// the committee's own ciphertexts still depends on a bootstrap key generated by a
// dealer and is therefore out of the strict trustless lane.
//
// Decomplecting boundary (F ⊥ M). This package is FHE only (confidential
// decrypt). It shares nothing with threshold MPC SIGNING (M-Chain: CGGMP21 /
// FROST for bridge custody), which lives in github.com/luxfi/threshold. The two
// are orthogonal primitives — different math, different purpose — and must never
// be conflated.
package threshold