threshold-elgamal 1.0.9 → 2.0.0

package/dist/proofs/disjunctive.d.ts

@@ -1,29 +1,24 @@
+/**
+ * CDS94-style disjunctive proofs for additive ElGamal plaintexts drawn from an
+ * explicit finite value set.
+ *
+ * Ballot payloads use this module to prove that a ciphertext encodes one value
+ * from the manifest-declared domain without revealing which value was chosen.
+ */
 import { type CryptoGroup, type RandomBytesSource } from '../core/index.js';
 import type { ElGamalCiphertext } from '../elgamal/types.js';
 import type { DisjunctiveProof, ProofContext } from './types.js';
 /**
  * Creates a CDS94-style disjunctive proof for additive ElGamal plaintexts.
  *
- * @param plaintext Actual plaintext encoded in the ciphertext.
- * @param randomness Encryption randomness used for the ciphertext.
- * @param ciphertext Fresh additive ciphertext.
- * @param publicKey Additive-mode public key.
- * @param validValues Ordered set of valid plaintext values.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @param randomSource Optional random source used for deterministic tests.
- * @returns Compact disjunctive proof with one branch per valid value.
+ * In the supported voting flow this is the proof attached to every
+ * `ballot-submission` payload.
  */
 export declare const createDisjunctiveProof: (plaintext: bigint, randomness: bigint, ciphertext: ElGamalCiphertext, publicKey: string, validValues: readonly bigint[], group: CryptoGroup, context: ProofContext, randomSource?: RandomBytesSource) => Promise<DisjunctiveProof>;
 /**
  * Verifies a CDS94-style disjunctive proof for additive ElGamal plaintexts.
  *
- * @param proof Compact disjunctive proof with one branch per valid value.
- * @param ciphertext Fresh additive ciphertext.
- * @param publicKey Additive-mode public key.
- * @param validValues Ordered set of valid plaintext values.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @returns `true` when the proof verifies.
+ * Ballot verification uses this to reject ciphertexts that do not encode one
+ * of the allowed manifest-domain values for the current option slot.
  */
 export declare const verifyDisjunctiveProof: (proof: DisjunctiveProof, ciphertext: ElGamalCiphertext, publicKey: string, validValues: readonly bigint[], group: CryptoGroup, context: ProofContext) => Promise<boolean>;

package/dist/proofs/disjunctive.js

@@ -1,3 +1,10 @@
+/**
+ * CDS94-style disjunctive proofs for additive ElGamal plaintexts drawn from an
+ * explicit finite value set.
+ *
+ * Ballot payloads use this module to prove that a ciphertext encodes one value
+ * from the manifest-declared domain without revealing which value was chosen.
+ */
 import { assertInSubgroup, assertInSubgroupOrIdentity, assertScalarInZq, InvalidProofError, modQ, randomScalarBelow, } from '../core/index.js';
 import { decodePoint, encodePoint, multiplyBase, pointMultiply, pointSubtract, } from '../core/ristretto.js';
 import { concatBytes, encodeForChallenge, encodeSequenceForChallenge, } from '../serialize/encoding.js';
@@ -5,19 +12,12 @@ import { assertProofContext, contextElements, fixedPoint, fixedScalar, hashChall
 import { hedgedNonce } from './nonces.js';
 const candidateEncoding = (ciphertext, candidateValue, group) => encodePoint(pointSubtract(decodePoint(ciphertext.c2, 'Ciphertext c2'), multiplyBase(modQ(candidateValue, group.q))));
 const commitmentSequence = (commitments) => encodeSequenceForChallenge(commitments.map((commitment) => concatBytes(encodeForChallenge(fixedPoint(commitment.a1)), encodeForChallenge(fixedPoint(commitment.a2)))));
-const challengePayload = (ciphertext, publicKey, validValues, commitments, group, context) => encodeForChallenge(...contextElements(context), fixedPoint(group.g), fixedPoint(publicKey), fixedPoint(ciphertext.c1), fixedPoint(ciphertext.c2), encodeSequenceForChallenge(validValues.map((value) => fixedScalar(modQ(value, group.q), group))), commitmentSequence(commitments));
+const challengePayload = (ciphertext, publicKey, validValues, commitments, group, context) => encodeForChallenge(...contextElements(context), fixedPoint(group.g), fixedPoint(publicKey), fixedPoint(ciphertext.c1), fixedPoint(ciphertext.c2), encodeSequenceForChallenge(validValues.map((value) => fixedScalar(modQ(value, group.q)))), commitmentSequence(commitments));
 /**
  * Creates a CDS94-style disjunctive proof for additive ElGamal plaintexts.
  *
- * @param plaintext Actual plaintext encoded in the ciphertext.
- * @param randomness Encryption randomness used for the ciphertext.
- * @param ciphertext Fresh additive ciphertext.
- * @param publicKey Additive-mode public key.
- * @param validValues Ordered set of valid plaintext values.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @param randomSource Optional random source used for deterministic tests.
- * @returns Compact disjunctive proof with one branch per valid value.
+ * In the supported voting flow this is the proof attached to every
+ * `ballot-submission` payload.
  */
 export const createDisjunctiveProof = async (plaintext, randomness, ciphertext, publicKey, validValues, group, context, randomSource) => {
     assertProofContext(context, group);
@@ -67,13 +67,8 @@ export const createDisjunctiveProof = async (plaintext, randomness, ciphertext,
 /**
  * Verifies a CDS94-style disjunctive proof for additive ElGamal plaintexts.
  *
- * @param proof Compact disjunctive proof with one branch per valid value.
- * @param ciphertext Fresh additive ciphertext.
- * @param publicKey Additive-mode public key.
- * @param validValues Ordered set of valid plaintext values.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @returns `true` when the proof verifies.
+ * Ballot verification uses this to reject ciphertexts that do not encode one
+ * of the allowed manifest-domain values for the current option slot.
  */
 export const verifyDisjunctiveProof = async (proof, ciphertext, publicKey, validValues, group, context) => {
     assertProofContext(context, group);

package/dist/proofs/dleq.d.ts

@@ -1,7 +1,16 @@
+/**
+ * Chaum-Pedersen equality-of-discrete-logs proofs used for threshold
+ * decryption-share publication and verification.
+ */
 import { type CryptoGroup, type RandomBytesSource } from '../core/index.js';
 import type { ElGamalCiphertext } from '../elgamal/types.js';
 import type { DLEQProof, ProofContext } from './types.js';
-/** Statement tuple for a Chaum-Pedersen equality-of-discrete-logs proof. */
+/**
+ * Statement tuple for a Chaum-Pedersen equality-of-discrete-logs proof.
+ *
+ * In the supported voting flow this statement ties a trustee's decryption
+ * share to both the joint public key and the accepted aggregate ciphertext.
+ */
 export type DLEQStatement = {
     /** Transcript-derived trustee verification key. */
     readonly publicKey: string;
@@ -13,21 +22,16 @@ export type DLEQStatement = {
 /**
  * Creates a compact additive-form Chaum-Pedersen proof of equal discrete logs.
  *
- * @param secret Witness scalar.
- * @param statement DLEQ statement over `(g, publicKey)` and `(c1, share)`.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @param randomSource Optional random source used for deterministic tests.
- * @returns Compact DLEQ proof `(challenge, response)`.
+ * This is the proof published alongside each threshold decryption share so
+ * observers can verify that the share came from the same secret exponent as the
+ * trustee's transcript-derived verification key.
  */
 export declare const createDLEQProof: (secret: bigint, statement: DLEQStatement, group: CryptoGroup, context: ProofContext, randomSource?: RandomBytesSource) => Promise<DLEQProof>;
 /**
- * Verifies a compact additive-form Chaum-Pedersen proof of equal discrete logs.
+ * Verifies a compact additive-form Chaum-Pedersen proof of equal discrete
+ * logs.
  *
- * @param proof Compact DLEQ proof `(challenge, response)`.
- * @param statement DLEQ statement over `(g, publicKey)` and `(c1, share)`.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @returns `true` when the proof verifies.
+ * Decryption-share verification routes through this helper after reconstructing
+ * the transcript-bound proof statement for one option slot.
  */
 export declare const verifyDLEQProof: (proof: DLEQProof, statement: DLEQStatement, group: CryptoGroup, context: ProofContext) => Promise<boolean>;

package/dist/proofs/dleq.js

@@ -1,3 +1,7 @@
+/**
+ * Chaum-Pedersen equality-of-discrete-logs proofs used for threshold
+ * decryption-share publication and verification.
+ */
 import { assertInSubgroup, assertInSubgroupOrIdentity, assertScalarInZq, modQ, } from '../core/index.js';
 import { decodePoint, encodePoint, multiplyBase, pointMultiply, pointSubtract, } from '../core/ristretto.js';
 import { encodeForChallenge } from '../serialize/encoding.js';
@@ -8,12 +12,9 @@ const challengePayload = (statement, a1, a2, group, context) => encodeForChallen
 /**
  * Creates a compact additive-form Chaum-Pedersen proof of equal discrete logs.
  *
- * @param secret Witness scalar.
- * @param statement DLEQ statement over `(g, publicKey)` and `(c1, share)`.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @param randomSource Optional random source used for deterministic tests.
- * @returns Compact DLEQ proof `(challenge, response)`.
+ * This is the proof published alongside each threshold decryption share so
+ * observers can verify that the share came from the same secret exponent as the
+ * trustee's transcript-derived verification key.
  */
 export const createDLEQProof = async (secret, statement, group, context, randomSource) => {
     assertProofContext(context, group);
@@ -32,13 +33,11 @@ export const createDLEQProof = async (secret, statement, group, context, randomS
     };
 };
 /**
- * Verifies a compact additive-form Chaum-Pedersen proof of equal discrete logs.
+ * Verifies a compact additive-form Chaum-Pedersen proof of equal discrete
+ * logs.
  *
- * @param proof Compact DLEQ proof `(challenge, response)`.
- * @param statement DLEQ statement over `(g, publicKey)` and `(c1, share)`.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @returns `true` when the proof verifies.
+ * Decryption-share verification routes through this helper after reconstructing
+ * the transcript-bound proof statement for one option slot.
  */
 export const verifyDLEQProof = async (proof, statement, group, context) => {
     assertProofContext(context, group);

package/dist/proofs/helpers.d.ts

@@ -3,6 +3,6 @@ import type { ProofContext } from './types.js';
 export declare const assertProofContext: (context: ProofContext, group: CryptoGroup) => void;
 export declare const contextElements: (context: ProofContext) => (bigint | string | Uint8Array)[];
 export declare const fixedPoint: (value: string) => Uint8Array;
-export declare const fixedScalar: (value: bigint, group: CryptoGroup) => Uint8Array;
+export declare const fixedScalar: (value: bigint) => Uint8Array;
 export declare const hashChallenge: (payload: Uint8Array, q: bigint) => Promise<bigint>;
 export declare const sumChallenges: (values: readonly bigint[], q: bigint) => bigint;

package/dist/proofs/helpers.js

@@ -1,3 +1,7 @@
+/**
+ * Shared Fiat-Shamir transcript helpers used by the Schnorr, DLEQ, and
+ * disjunctive proof implementations.
+ */
 import { hexToBytes } from '../core/bytes.js';
 import { assertCanonicalRistrettoGroup, InvalidProofError, modQ, } from '../core/index.js';
 import { encodeScalar, hashChallengeToScalar } from '../core/ristretto.js';
@@ -55,9 +59,6 @@ export const contextElements = (context) => {
     return fields;
 };
 export const fixedPoint = (value) => hexToBytes(value);
-export const fixedScalar = (value, group) => {
-    void group;
-    return hexToBytes(encodeScalar(value));
-};
+export const fixedScalar = (value) => hexToBytes(encodeScalar(value));
 export const hashChallenge = (payload, q) => Promise.resolve(modQ(hashChallengeToScalar(payload), q));
 export const sumChallenges = (values, q) => values.reduce((sum, value) => modQ(sum + value, q), 0n);

package/dist/proofs/nonces.js

@@ -1,3 +1,9 @@
+/**
+ * Hedged nonce derivation for proof generation.
+ *
+ * The proof systems use this module so they remain safe under poor randomness
+ * while still allowing deterministic tests and vector generation.
+ */
 import { bytesToBigInt } from '../core/bytes.js';
 import { modQ, randomBytes, sha256, } from '../core/index.js';
 import { bigintToFixedBytes, concatBytes, domainSeparator, } from '../serialize/encoding.js';

package/dist/proofs/public.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Proof-system helpers for Schnorr, DLEQ, and disjunctive ballot proofs.
+ *
+ * Use this module when you need to create or verify proof objects directly.
+ *
+ * @module threshold-elgamal/proofs
+ * @packageDocumentation
+ */
+export { createDisjunctiveProof, verifyDisjunctiveProof } from './disjunctive.js';
+export { createDLEQProof, type DLEQStatement, verifyDLEQProof } from './dleq.js';
+export { createSchnorrProof, verifySchnorrProof } from './schnorr.js';
+export type { DLEQProof, DisjunctiveProof, ProofContext, SchnorrProof, } from './types.js';

package/dist/proofs/public.js

@@ -0,0 +1,11 @@
+/**
+ * Proof-system helpers for Schnorr, DLEQ, and disjunctive ballot proofs.
+ *
+ * Use this module when you need to create or verify proof objects directly.
+ *
+ * @module threshold-elgamal/proofs
+ * @packageDocumentation
+ */
+export { createDisjunctiveProof, verifyDisjunctiveProof } from './disjunctive.js';
+export { createDLEQProof, verifyDLEQProof } from './dleq.js';
+export { createSchnorrProof, verifySchnorrProof } from './schnorr.js';

package/dist/proofs/schnorr.d.ts

@@ -1,23 +1,22 @@
+/**
+ * Schnorr proof helpers used for knowledge-of-discrete-log statements.
+ *
+ * In the supported workflow this is primarily used for Feldman coefficient
+ * proofs inside the DKG transcript.
+ */
 import { type CryptoGroup, type RandomBytesSource } from '../core/index.js';
 import type { ProofContext, SchnorrProof } from './types.js';
 /**
  * Creates a compact additive-form Schnorr proof of knowledge.
  *
- * @param secret Witness scalar.
- * @param statement Statement element `g^secret mod p`.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @param randomSource Optional random source used for deterministic tests.
- * @returns Compact Schnorr proof `(challenge, response)`.
+ * This is the proof format used when a trustee needs to show knowledge of a
+ * secret coefficient without revealing it.
  */
 export declare const createSchnorrProof: (secret: bigint, statement: string, group: CryptoGroup, context: ProofContext, randomSource?: RandomBytesSource) => Promise<SchnorrProof>;
 /**
  * Verifies a compact additive-form Schnorr proof.
  *
- * @param proof Compact Schnorr proof `(challenge, response)`.
- * @param statement Statement element `g^secret mod p`.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @returns `true` when the proof verifies.
+ * DKG transcript verification uses this to validate Feldman coefficient proofs
+ * before accepting the published commitment set.
  */
 export declare const verifySchnorrProof: (proof: SchnorrProof, statement: string, group: CryptoGroup, context: ProofContext) => Promise<boolean>;

package/dist/proofs/schnorr.js

@@ -1,3 +1,9 @@
+/**
+ * Schnorr proof helpers used for knowledge-of-discrete-log statements.
+ *
+ * In the supported workflow this is primarily used for Feldman coefficient
+ * proofs inside the DKG transcript.
+ */
 import { assertInSubgroup, assertScalarInZq, modQ, } from '../core/index.js';
 import { decodePoint, encodePoint, multiplyBase, pointMultiply, pointSubtract, } from '../core/ristretto.js';
 import { encodeForChallenge } from '../serialize/encoding.js';
@@ -8,12 +14,8 @@ const challengePayload = (statement, commitment, group, context) => encodeForCha
 /**
  * Creates a compact additive-form Schnorr proof of knowledge.
  *
- * @param secret Witness scalar.
- * @param statement Statement element `g^secret mod p`.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @param randomSource Optional random source used for deterministic tests.
- * @returns Compact Schnorr proof `(challenge, response)`.
+ * This is the proof format used when a trustee needs to show knowledge of a
+ * secret coefficient without revealing it.
  */
 export const createSchnorrProof = async (secret, statement, group, context, randomSource) => {
     assertProofContext(context, group);
@@ -30,11 +32,8 @@ export const createSchnorrProof = async (secret, statement, group, context, rand
 /**
  * Verifies a compact additive-form Schnorr proof.
  *
- * @param proof Compact Schnorr proof `(challenge, response)`.
- * @param statement Statement element `g^secret mod p`.
- * @param group Resolved group definition.
- * @param context Fiat-Shamir binding context.
- * @returns `true` when the proof verifies.
+ * DKG transcript verification uses this to validate Feldman coefficient proofs
+ * before accepting the published commitment set.
  */
 export const verifySchnorrProof = async (proof, statement, group, context) => {
     assertProofContext(context, group);

package/dist/proofs/types.d.ts

@@ -1,7 +1,19 @@
+/**
+ * Shared proof types and transcript context bindings.
+ *
+ * Every proof in the package binds itself to the same core ceremony context so
+ * proofs cannot be replayed across manifests, sessions, participants, or
+ * option slots.
+ */
 import type { GroupName } from '../core/types.js';
-/** Common Fiat-Shamir context fields used by the shipped proof systems. */
+/**
+ * Common Fiat-Shamir context fields used by the proof systems.
+ *
+ * Higher-level modules derive these fields from the manifest, transcript, and
+ * payload slot currently being proved or verified.
+ */
 export type ProofContext = {
-    /** Protocol version string bound into the transcript. */
+    /** Protocol namespace string bound into the transcript. */
     readonly protocolVersion: string;
     /** Group suite name bound into the transcript. */
     readonly suiteId: GroupName;
@@ -20,12 +32,20 @@ export type ProofContext = {
     /** Optional ballot option index so ballot proofs stay bound to one option slot. */
     readonly optionIndex?: number;
 };
-/** Compact Schnorr proof encoded as challenge and response only. */
+/**
+ * Compact Schnorr proof encoded as challenge and response only.
+ *
+ * Used primarily for Feldman coefficient proofs in the DKG flow.
+ */
 export type SchnorrProof = {
     readonly challenge: bigint;
     readonly response: bigint;
 };
-/** Compact Chaum-Pedersen proof encoded as challenge and response only. */
+/**
+ * Compact Chaum-Pedersen proof encoded as challenge and response only.
+ *
+ * Used for decryption-share correctness proofs.
+ */
 export type DLEQProof = {
     readonly challenge: bigint;
     readonly response: bigint;
@@ -35,7 +55,12 @@ export type DisjunctiveBranch = {
     readonly challenge: bigint;
     readonly response: bigint;
 };
-/** A disjunctive proof over an ordered set of valid plaintext values. */
+/**
+ * A disjunctive proof over an ordered set of valid plaintext values.
+ *
+ * Ballot payloads use this to prove that an encrypted value came from the
+ * allowed manifest domain without revealing which value was chosen.
+ */
 export type DisjunctiveProof = {
     readonly branches: readonly DisjunctiveBranch[];
 };

package/dist/protocol/board-audit.d.ts

@@ -13,7 +13,12 @@ type PhaseDigest = {
     readonly digest: string;
     readonly payloadCount: number;
 };
-/** Deterministic audit result for a set of signed protocol payloads. */
+/**
+ * Deterministic audit result for a set of signed protocol payloads.
+ *
+ * Higher-level verifiers consume this output instead of raw board logs so they
+ * can operate on one canonical accepted transcript.
+ */
 export type BoardAudit<TPayload extends ProtocolPayload = ProtocolPayload> = {
     readonly acceptedPayloads: readonly SignedPayload<TPayload>[];
     readonly ceremonyDigest: string;
@@ -25,8 +30,8 @@ export type BoardAudit<TPayload extends ProtocolPayload = ProtocolPayload> = {
  * Audits signed payloads by canonical slot, rejecting equivocation and
  * collapsing only exact signed retransmissions to one representative payload.
  *
- * @param signedPayloads Signed payloads to audit.
- * @returns Deterministic audit output with accepted payloads and digests.
+ * All transcript-level verifiers run this step before they interpret the
+ * semantic contents of the board.
  */
 export declare const auditSignedPayloads: <TPayload extends ProtocolPayload>(signedPayloads: readonly SignedPayload<TPayload>[]) => Promise<BoardAudit<TPayload>>;
 export {};

package/dist/protocol/board-audit.js

@@ -1,3 +1,9 @@
+/**
+ * Deterministic bulletin-board audit for signed protocol payloads.
+ *
+ * This is the layer that collapses exact retransmissions, rejects
+ * equivocation, and produces stable digests over the accepted transcript.
+ */
 import { InvalidPayloadError } from '../core/index.js';
 import { compareProtocolPayloads } from './ordering.js';
 import { classifySlotConflict, payloadSlotKey } from './payloads.js';
@@ -20,8 +26,8 @@ const acceptedUnsignedPayloads = (acceptedPayloads) => acceptedPayloads.map((pay
  * Audits signed payloads by canonical slot, rejecting equivocation and
  * collapsing only exact signed retransmissions to one representative payload.
  *
- * @param signedPayloads Signed payloads to audit.
- * @returns Deterministic audit output with accepted payloads and digests.
+ * All transcript-level verifiers run this step before they interpret the
+ * semantic contents of the board.
  */
 export const auditSignedPayloads = async (signedPayloads) => {
     const sortedPayloads = [...signedPayloads].sort(compareSignedPayloads);

package/dist/protocol/builders.d.ts

@@ -6,11 +6,21 @@ import type { BallotClosePayload, BallotSubmissionPayload, DecryptionSharePayloa
 type ProtocolPayloadByMessageType<TMessageType extends ProtocolMessageType> = Extract<ProtocolPayload, {
     readonly messageType: TMessageType;
 }>;
-/** Signs one canonical protocol payload with a participant auth key. */
+/**
+ * Signs one canonical protocol payload with a participant auth key.
+ *
+ * All specialized payload builders in this module eventually route through
+ * this helper after normalizing the payload shape.
+ */
 export declare const signProtocolPayload: <TMessageType extends ProtocolMessageType>(privateKey: CryptoKey, payload: ProtocolPayloadInput<ProtocolPayloadByMessageType<TMessageType>> & {
     readonly messageType: TMessageType;
 }) => Promise<SignedPayload<ProtocolPayloadByMessageType<TMessageType>>>;
-/** Creates a signed manifest-publication payload. */
+/**
+ * Creates a signed `manifest-publication` payload.
+ *
+ * This is the first public payload in the supported ceremony and anchors the
+ * explicit manifest on the board.
+ */
 export declare const createManifestPublicationPayload: (privateKey: CryptoKey, input: {
     readonly manifest: ElectionManifest;
     readonly manifestHash: string;
@@ -18,7 +28,12 @@ export declare const createManifestPublicationPayload: (privateKey: CryptoKey, i
     readonly protocolVersion?: string;
     readonly sessionId: string;
 }) => Promise<SignedPayload<ManifestPublicationPayload>>;
-/** Creates a signed registration payload for one participant. */
+/**
+ * Creates a signed `registration` payload for one participant.
+ *
+ * Registrations publish the participant's auth key and transport key and are
+ * the source of truth for the accepted roster.
+ */
 export declare const createRegistrationPayload: (privateKey: CryptoKey, input: {
     readonly authPublicKey: EncodedAuthPublicKey;
     readonly manifestHash: string;
@@ -28,7 +43,12 @@ export declare const createRegistrationPayload: (privateKey: CryptoKey, input: {
     readonly sessionId: string;
     readonly transportPublicKey: EncodedTransportPublicKey;
 }) => Promise<SignedPayload<RegistrationPayload>>;
-/** Creates a signed manifest-acceptance payload. */
+/**
+ * Creates a signed `manifest-acceptance` payload.
+ *
+ * This records that a participant accepted the frozen manifest and the roster
+ * hash under which they were assigned an index.
+ */
 export declare const createManifestAcceptancePayload: (privateKey: CryptoKey, input: {
     readonly accountIdHash?: string;
     readonly assignedParticipantIndex: number;
@@ -38,7 +58,12 @@ export declare const createManifestAcceptancePayload: (privateKey: CryptoKey, in
     readonly rosterHash: string;
     readonly sessionId: string;
 }) => Promise<SignedPayload<ManifestAcceptancePayload>>;
-/** Creates a signed phase-checkpoint payload over one DKG phase snapshot. */
+/**
+ * Creates a signed `phase-checkpoint` payload over one DKG phase snapshot.
+ *
+ * Checkpoints let observers replay the DKG in coarse-grained epochs while
+ * preserving deterministic transcript commitments.
+ */
 export declare const createPhaseCheckpointPayload: (privateKey: CryptoKey, input: {
     readonly checkpointPhase: 0 | 1 | 2 | 3;
     readonly manifestHash: string;
@@ -48,15 +73,27 @@ export declare const createPhaseCheckpointPayload: (privateKey: CryptoKey, input
     readonly sessionId: string;
     readonly transcript: readonly SignedPayload[];
 }) => Promise<SignedPayload<PhaseCheckpointPayload>>;
-/** Creates a signed Pedersen-commitment payload for DKG phase 1. */
+/**
+ * Creates a signed `pedersen-commitment` payload for DKG phase 1.
+ */
 export declare const createPedersenCommitmentPayload: (privateKey: CryptoKey, input: Omit<PedersenCommitmentPayload, "messageType" | "phase" | "protocolVersion"> & {
     readonly protocolVersion?: string;
 }) => Promise<SignedPayload<PedersenCommitmentPayload>>;
-/** Creates a signed encrypted dual-share payload for DKG phase 1. */
+/**
+ * Creates a signed `encrypted-dual-share` payload for DKG phase 1.
+ *
+ * The envelope contents are produced separately by the transport layer and are
+ * merely wrapped and signed here.
+ */
 export declare const createEncryptedDualSharePayload: (privateKey: CryptoKey, input: Omit<EncryptedDualSharePayload, "messageType" | "phase" | "protocolVersion"> & {
     readonly protocolVersion?: string;
 }) => Promise<SignedPayload<EncryptedDualSharePayload>>;
-/** Creates a signed Feldman-commitment payload for DKG phase 3. */
+/**
+ * Creates a signed `feldman-commitment` payload for DKG phase 3.
+ *
+ * This payload exposes the public Feldman commitments and their Schnorr proofs
+ * after the complaint phase has been resolved.
+ */
 export declare const createFeldmanCommitmentPayload: (privateKey: CryptoKey, input: Omit<FeldmanCommitmentPayload, "messageType" | "phase" | "proofs" | "protocolVersion"> & {
     readonly protocolVersion?: string;
     readonly proofs: FeldmanCommitmentPayload["proofs"] | readonly ({
@@ -67,26 +104,53 @@ export declare const createFeldmanCommitmentPayload: (privateKey: CryptoKey, inp
         readonly coefficientIndex: number;
     } & EncodedCompactProof))[];
 }) => Promise<SignedPayload<FeldmanCommitmentPayload>>;
-/** Creates a signed key-derivation-confirmation payload for DKG phase 4. */
+/**
+ * Creates a signed `key-derivation-confirmation` payload for DKG phase 4.
+ *
+ * Trustees use this to confirm the final derived joint key and transcript
+ * digest they believe the DKG produced.
+ */
 export declare const createKeyDerivationConfirmationPayload: (privateKey: CryptoKey, input: Omit<KeyDerivationConfirmation, "messageType" | "phase" | "protocolVersion"> & {
     readonly protocolVersion?: string;
 }) => Promise<SignedPayload<KeyDerivationConfirmation>>;
-/** Creates a signed ballot payload for one participant and one option slot. */
+/**
+ * Creates a signed `ballot-submission` payload for one participant and one
+ * option slot.
+ *
+ * Higher-level application code is expected to create the ciphertext and
+ * disjunctive proof first, then hand them to this builder for encoding and
+ * signing.
+ */
 export declare const createBallotSubmissionPayload: (privateKey: CryptoKey, input: Omit<BallotSubmissionPayload, "messageType" | "phase" | "ciphertext" | "proof" | "protocolVersion"> & {
     readonly protocolVersion?: string;
     readonly ciphertext: BallotSubmissionPayload["ciphertext"] | ElGamalCiphertext;
     readonly proof: BallotSubmissionPayload["proof"] | DisjunctiveProof;
 }) => Promise<SignedPayload<BallotSubmissionPayload>>;
-/** Creates the organizer-signed ballot cutoff payload. */
+/**
+ * Creates the organizer-signed `ballot-close` payload.
+ *
+ * This freezes which complete ballots are counted for the tally and therefore
+ * determines the accepted aggregate seen by every later decryption step.
+ */
 export declare const createBallotClosePayload: (privateKey: CryptoKey, input: Omit<BallotClosePayload, "messageType" | "phase" | "protocolVersion"> & {
     readonly protocolVersion?: string;
 }) => Promise<SignedPayload<BallotClosePayload>>;
-/** Creates a signed threshold decryption-share payload for one option slot. */
+/**
+ * Creates a signed `decryption-share` payload for one option slot.
+ *
+ * The caller is responsible for computing the share and DLEQ proof first; this
+ * helper encodes and signs the published object.
+ */
 export declare const createDecryptionSharePayload: (privateKey: CryptoKey, input: Omit<DecryptionSharePayload, "messageType" | "phase" | "proof" | "protocolVersion"> & {
     readonly protocolVersion?: string;
     readonly proof: DecryptionSharePayload["proof"] | DLEQProof;
 }) => Promise<SignedPayload<DecryptionSharePayload>>;
-/** Creates a signed tally-publication payload for one option slot. */
+/**
+ * Creates a signed `tally-publication` payload for one option slot.
+ *
+ * This is the final organizer-facing publication step after the accepted
+ * decryption shares have been combined into a bounded plaintext tally.
+ */
 export declare const createTallyPublicationPayload: (privateKey: CryptoKey, input: Omit<TallyPublicationPayload, "messageType" | "phase" | "tally" | "protocolVersion"> & {
     readonly protocolVersion?: string;
     readonly tally: TallyPublicationPayload["tally"] | bigint;