corona/INTEGRATION.md

Quasar Consensus Integration: Resharing Replaces Per-Epoch DKG

This document describes how ~/work/lux/consensus/protocol/quasar/epoch.go should be modified to call pulsar/reshare at validator-set rotations instead of running a fresh trusted-dealer GenerateKeys every time.

Status

• Resharing primitive: complete (pulsar/reshare/reshare.go)
• Refresh primitive: complete (same-committee proactive update)
• KAT oracle: complete (16 entries, byte-equal Go↔C++)
• C++ port: complete (luxcpp/crypto/pulsar/cpp/reshare.{hpp,cpp})
• Integration test: complete (signature with new committee verifies under unchanged public key b̃)
• Wire integration into Quasar consensus: PENDING
• Verifiable Secret Resharing layer (commitments, complaints, activation certs): PENDING (depends on pulsar/dkg2/, parallel track)

Current state of epoch.go

// EpochManager.generateEpochKeysWithThreshold (line 336)
func (em *EpochManager) generateEpochKeysWithThreshold(
    epoch uint64, validators []string, threshold int,
) (*EpochKeys, error) {
    // ... Generate Corona threshold keys ...
    shares, groupKey, err := coronaThreshold.GenerateKeys(threshold, n, nil)
    // ...
}

GenerateKeys runs trusted-dealer Gen internally. Whoever runs generateEpochKeysWithThreshold learns the master secret s and the new public key b is unrelated to the previous epoch's. This is the defect the resharing primitive fixes.

Target state

// genesis only — runs once, before any epoch rotation
func (em *EpochManager) InitializeGenesis(validators []string) (*EpochKeys, error) {
    // First time only: run trusted-dealer Gen (or the eventual MPC
    // ceremony in pulsar/dkg2/). Result: shares + groupKey + master
    // public key b̃. Persist b̃ to chain genesis state — it is a
    // permanent, public, never-rotating value.
    shares, groupKey, err := coronaThreshold.GenerateKeys(
        em.threshold, len(validators), nil)
    // ...
}

// epoch rotation — runs every time the validator set changes
func (em *EpochManager) RotateEpochViaReshare(
    newValidators []string,
) (*EpochKeys, error) {
    // 1. Build the input to pulsar/reshare.Reshare from the OUTGOING
    //    epoch's shares.
    oldEpoch := em.currentKeys
    oldShares := convertToReshareInput(oldEpoch)

    // 2. Compute new committee party IDs (1-indexed).
    newSet := buildPartyIDs(newValidators)

    // 3. Run reshare. The randSource MUST be mixed by the consensus
    //    layer from a per-epoch entropy beacon (e.g. the previous
    //    block's hash + an honest-validator BLS contribution). Each
    //    PARTICIPATING outgoing validator runs Reshare LOCALLY with
    //    its OWN share + its OWN local randomness, then ships
    //    g_i(j) to each new validator. The function below is what
    //    one outgoing validator runs.
    newShares, err := reshare.Reshare(
        ringParams.R,
        oldShares,
        oldEpoch.Threshold,
        newSet,
        em.threshold,
        per_party_rng_source(epoch),
    )

    // 4. Wrap the new shares into Corona KeyShare instances.
    //    GroupKey is INHERITED from the old epoch — same A, same b̃.
    newKeyShares := wrapAsCoronaShares(
        newShares, oldEpoch.GroupKey,
        recomputeLagrangeCoefficients(newValidators, em.threshold),
    )

    // 5. Activation certificate: the new committee threshold-signs
    //    the transcript of the resharing under the SAME group key.
    //    Chain accepts the new epoch only when this cert verifies.
    activationSig, err := signActivationCert(
        newKeyShares, oldEpoch.GroupKey,
        transcriptHash(epoch, oldValidators, newValidators, em.threshold),
    )

    // 6. Build new EpochKeys with the inherited group key.
    return &EpochKeys{
        Epoch:        epoch + 1,
        ValidatorSet: newValidators,
        Threshold:    em.threshold,
        GroupKey:     oldEpoch.GroupKey,  // unchanged!
        Shares:       newKeyShares,
        // ...
    }, nil
}

Critical design points

1. GroupKey inheritance. The GroupKey (which contains A and bTilde) is set at genesis and persists for the lifetime of the group. Every epoch's EpochKeys.GroupKey points to the same underlying object. This is what makes VerifySignatureForEpoch work across epochs without separate per-epoch verification keys and what eliminates the need for "verification key history".

2. Lagrange coefficients are recomputed per epoch. In the old sign.Gen flow, each party's Lambda is baked into its share. Reshare produces shares in the standard polynomial-evaluation form, so each party computes its Lambda on the fly using primitives.ComputeLagrangeCoefficients over the active signing set. This is a tiny computation (one Lagrange basis evaluation per signer per signing session) and avoids the need for any committee- specific share preprocessing.

3. Pairwise channels. Reshare outputs the kernel — the function computes one party's shares from its own old share + fresh randomness, but assumes a magic transport. In the wire integration:

   • Each outgoing party i independently:

     • Computes g_i(X) (one polynomial of degree t_new - 1).
     • Evaluates at every j ∈ new_set.
     • Encrypts g_i(j) for party j under their pairwise key (X25519 + ML-KEM hybrid).
     • Broadcasts the ciphertexts on a chain-anchored bulletin board.

   • Each incoming party j independently:

     • Decrypts the t_old (or fewer, if some i ∈ Q are unavailable) envelopes addressed to it.
     • Sums the decrypted g_i(j) values.
     • Result is s'_j.

4. VSR layer (out of scope here). The kernel above is correct under honest-but-curious dealers. For full Byzantine resilience the following are required, in pulsar/dkg2/ (parallel track):

   • Pedersen-style polynomial commitments to g_i.
   • Complaint protocol for inconsistent dealings.
   • Deterministic disqualification + re-quorum.

5. Activation certificate. The chain MUST NOT accept a new epoch unless the new committee can produce a valid threshold signature under the inherited GroupKey. This proves liveness of the new committee. The activation message is the transcript hash of the resharing.

6. Genesis is special. The initial s must come from somewhere:

   • Foundation MPC ceremony (recommended): N geographically distinct parties run a verifiable DKG once, ship transcripts; chain genesis pins bTilde.
   • Trusted-dealer (acceptable for testnets only): one party runs Gen, publishes bTilde, deletes s.

   After genesis, no party ever re-derives s.

7. Refresh between rotations. Within a stable validator set, the pulsar/reshare.Refresh primitive runs the HJKY97 zero-polynomial update. Recommended cadence: every MaxEpochDuration (1 hour by default) even when validator set unchanged. This defeats a mobile adversary that compromises < t parties per epoch and tries to accumulate share material over time.

Migration path

Phase 1 (this PR): land the kernel + KAT + C++ port. No consensus changes yet. Resharing is callable from tests but not from production.

Phase 2: add RotateEpochViaReshare to epoch.go behind a feature flag. Existing RotateEpoch (which calls GenerateKeys) remains the default. New method is exercised on devnet only.

Phase 3: wire VSR layer (commitments, complaints, activation) on top of RotateEpochViaReshare. Continue devnet exercise; harden against adversarial validators.

Phase 4: switch testnet default to resharing. Run for at least one month with mixed honest/byzantine drills. Continue to allow GenerateKeys as escape hatch via governance proposal.

Phase 5: switch mainnet default. GenerateKeys removed from epoch code path; only callable for testnet bootstrap.

Proof of public-key invariance (test)

// pulsar/reshare/integration_test.go: TestResharePreservesPublicKey
//
// Demonstrates the load-bearing claim:
//
// 1. Sample s, A, e at genesis. Compute b = A·s + e, b̃ = round(b, ξ).
// 2. Standard-Shamir-share s across 3 parties with threshold 2.
// 3. Run the existing 2-round Sign protocol with the OLD committee.
//    Verify the resulting signature against b̃. Pass.
// 4. Reshare onto a 5-party committee with threshold 3, FRESH PARTY
//    IDs (no overlap with old committee).
// 5. Run Sign again with the NEW committee. Verify against the SAME
//    b̃ from step 1. Pass.
//
// Test status: PASSING.

Test output (current run):

=== RUN   TestResharePreservesPublicKey
    integration_test.go:131: OLD: signature verified
    integration_test.go:213: NEW: signature verified
    integration_test.go:217: PASS: NEW-committee signature verifies against
                                   UNCHANGED public key b̃
--- PASS: TestResharePreservesPublicKey (0.53s)