threshold-elgamal 1.0.9 → 2.0.0

package/dist/protocol/types.d.ts

@@ -1,12 +1,26 @@
+/**
+ * Public protocol payload and verification types.
+ *
+ * These types describe the signed board records that move through manifest
+ * publication, DKG, ballot casting, decryption-share publication, and final
+ * tally verification.
+ */
 import type { EncodedPoint } from '../core/types.js';
 import type { VerifiedDKGTranscript } from '../dkg/verification.js';
 import type { DecryptionShare } from '../threshold/types.js';
 import type { EncodedAuthPublicKey, EncodedTransportPrivateKey, EncodedTransportPublicKey } from '../transport/types.js';
-/** Canonical protocol payload type identifiers. */
+/**
+ * Canonical protocol payload type identifiers for the supported ceremony.
+ */
 export type ProtocolMessageType = 'manifest-publication' | 'registration' | 'manifest-acceptance' | 'phase-checkpoint' | 'pedersen-commitment' | 'encrypted-dual-share' | 'complaint' | 'complaint-resolution' | 'feldman-commitment' | 'key-derivation-confirmation' | 'ballot-submission' | 'ballot-close' | 'decryption-share' | 'tally-publication';
 /** Complaint reasons recognized by the protocol layer. */
 export type ComplaintReason = 'aes-gcm-failure' | 'malformed-plaintext' | 'pedersen-failure';
-/** Shared fields present on every unsigned protocol payload. */
+/**
+ * Shared fields present on every unsigned protocol payload.
+ *
+ * These fields bind each payload to one manifest, session, participant, and
+ * protocol phase.
+ */
 export type BaseProtocolPayload = {
     readonly protocolVersion: string;
     readonly sessionId: string;
@@ -34,14 +48,23 @@ export type EncodedDisjunctiveBranch = {
 export type EncodedDisjunctiveProof = {
     readonly branches: readonly EncodedDisjunctiveBranch[];
 };
-/** Registration payload carrying ceremony auth and transport keys. */
+/**
+ * Registration payload carrying ceremony auth and transport keys.
+ *
+ * This is the public source of truth for the accepted roster.
+ */
 export type RegistrationPayload = BaseProtocolPayload & {
     readonly messageType: 'registration';
     readonly rosterHash: string;
     readonly authPublicKey: EncodedAuthPublicKey;
     readonly transportPublicKey: EncodedTransportPublicKey;
 };
-/** Participant-signed manifest acceptance payload. */
+/**
+ * Participant-signed manifest acceptance payload.
+ *
+ * This records acceptance of the frozen manifest and roster hash for one
+ * assigned participant index.
+ */
 export type ManifestAcceptancePayload = BaseProtocolPayload & {
     readonly messageType: 'manifest-acceptance';
     readonly rosterHash: string;
@@ -55,12 +78,21 @@ export type PhaseCheckpointPayload = BaseProtocolPayload & {
     readonly checkpointTranscriptHash: string;
     readonly qualifiedParticipantIndices: readonly number[];
 };
-/** Broadcast payload carrying Pedersen coefficient commitments. */
+/**
+ * Broadcast payload carrying Pedersen coefficient commitments.
+ *
+ * This belongs to DKG phase 1.
+ */
 export type PedersenCommitmentPayload = BaseProtocolPayload & {
     readonly messageType: 'pedersen-commitment';
     readonly commitments: readonly string[];
 };
-/** Encrypted share-envelope payload for the share-distribution step. */
+/**
+ * Encrypted share-envelope payload for the share-distribution step.
+ *
+ * This publishes the sender-ephemeral envelope metadata for one dealer to one
+ * recipient in DKG phase 1.
+ */
 export type EncryptedDualSharePayload = BaseProtocolPayload & {
     readonly messageType: 'encrypted-dual-share';
     readonly recipientIndex: number;
@@ -89,7 +121,11 @@ export type ComplaintResolutionPayload = BaseProtocolPayload & {
     readonly suite: 'X25519';
     readonly revealedEphemeralPrivateKey: EncodedTransportPrivateKey;
 };
-/** Broadcast payload carrying Feldman commitments and coefficient proofs. */
+/**
+ * Broadcast payload carrying Feldman commitments and coefficient proofs.
+ *
+ * This belongs to DKG phase 3.
+ */
 export type FeldmanCommitmentPayload = BaseProtocolPayload & {
     readonly messageType: 'feldman-commitment';
     readonly commitments: readonly string[];
@@ -107,19 +143,32 @@ export type KeyDerivationConfirmation = BaseProtocolPayload & {
     readonly dkgTranscriptHash: string;
     readonly publicKey: EncodedPoint;
 };
-/** Signed manifest-publication payload anchoring the frozen manifest. */
+/**
+ * Signed manifest-publication payload anchoring the frozen manifest.
+ *
+ * This is the first public payload in the supported ceremony.
+ */
 export type ManifestPublicationPayload = BaseProtocolPayload & {
     readonly messageType: 'manifest-publication';
     readonly manifest: ElectionManifest;
 };
-/** Signed additive ballot payload for one participant and one option slot. */
+/**
+ * Signed additive ballot payload for one participant and one option slot.
+ *
+ * A complete voter ballot is represented as one such payload per option.
+ */
 export type BallotSubmissionPayload = BaseProtocolPayload & {
     readonly messageType: 'ballot-submission';
     readonly optionIndex: number;
     readonly ciphertext: EncodedCiphertext;
     readonly proof: EncodedDisjunctiveProof;
 };
-/** Signed organizer payload that freezes which participants are counted. */
+/**
+ * Signed organizer payload that freezes which participants are counted.
+ *
+ * This is the cutoff record that determines the accepted ballot set used for
+ * tallying.
+ */
 export type BallotClosePayload = BaseProtocolPayload & {
     readonly messageType: 'ballot-close';
     readonly countedParticipantIndices: readonly number[];
@@ -136,7 +185,12 @@ export type DecryptionSharePayload = BaseProtocolPayload & {
     readonly decryptionShare: EncodedPoint;
     readonly proof: EncodedCompactProof;
 };
-/** Signed tally-publication payload for the recovered additive tally. */
+/**
+ * Signed tally-publication payload for the recovered additive tally.
+ *
+ * This is the optional published record checked against the verifier's own
+ * recomputed tally.
+ */
 export type TallyPublicationPayload = BaseProtocolPayload & {
     readonly messageType: 'tally-publication';
     readonly optionIndex: number;
@@ -145,18 +199,42 @@ export type TallyPublicationPayload = BaseProtocolPayload & {
     readonly tally: string;
     readonly decryptionParticipantIndices: readonly number[];
 };
-/** Union of all unsigned protocol payload shapes. */
+/**
+ * Union of all unsigned protocol payload shapes that may appear on the board.
+ */
 export type ProtocolPayload = ManifestPublicationPayload | RegistrationPayload | ManifestAcceptancePayload | PhaseCheckpointPayload | PedersenCommitmentPayload | EncryptedDualSharePayload | ComplaintPayload | ComplaintResolutionPayload | FeldmanCommitmentPayload | KeyDerivationConfirmation | BallotSubmissionPayload | BallotClosePayload | DecryptionSharePayload | TallyPublicationPayload;
-/** Unsigned protocol payload paired with an authentication signature. */
+/**
+ * Unsigned protocol payload paired with an authentication signature.
+ *
+ * This is the canonical board record shape accepted by the audit and
+ * verification layers.
+ */
 export type SignedPayload<TPayload extends ProtocolPayload = ProtocolPayload> = {
     readonly payload: TPayload;
     /** Raw Ed25519 signature bytes encoded as lowercase hex. */
     readonly signature: string;
 };
-/** Canonical election-manifest shape bound into protocol transcripts. */
+/**
+ * Canonical election-manifest shape bound into protocol transcripts.
+ *
+ * The manifest is intentionally compact: it fixes the frozen roster hash,
+ * option list, and one explicit global score range, while participant count
+ * and threshold are derived later from the accepted registration roster.
+ */
+export type ScoreRange = {
+    readonly min: number;
+    readonly max: number;
+};
+/**
+ * Canonical election-manifest shape bound into protocol transcripts.
+ *
+ * The score range applies uniformly to every option slot in the supported
+ * workflow.
+ */
 export type ElectionManifest = {
     readonly rosterHash: string;
     readonly optionList: readonly string[];
+    readonly scoreRange: ScoreRange;
 };
 /**
  * Input bundle for verifying typed ballot payloads.
@@ -169,7 +247,12 @@ type VerifyBallotSubmissionPayloadsInput = {
 };
 /** Input bundle for verifying typed ballot payloads across all options. */
 export type VerifyBallotSubmissionPayloadsByOptionInput = VerifyBallotSubmissionPayloadsInput;
-/** Verified typed decryption-share payload. */
+/**
+ * Verified typed decryption-share payload.
+ *
+ * This pairs the original signed payload with the decoded low-level share used
+ * in final tally recomputation.
+ */
 export type VerifiedDecryptionSharePayload = {
     readonly payload: SignedPayload<DecryptionSharePayload>;
     readonly share: DecryptionShare;
@@ -192,7 +275,12 @@ export type VerifyDecryptionSharePayloadsByOptionInput = {
     readonly manifest: ElectionManifest;
     readonly sessionId: string;
 };
-/** Input bundle for full ceremony verification across all published options. */
+/**
+ * Input bundle for full ceremony verification across all published options.
+ *
+ * This is the top-level verifier input that an auditor or bulletin-board
+ * reader supplies when replaying a full ceremony.
+ */
 export type VerifyElectionCeremonyInput = {
     readonly manifest: ElectionManifest;
     readonly sessionId: string;
@@ -202,7 +290,12 @@ export type VerifyElectionCeremonyInput = {
     readonly decryptionSharePayloads: readonly SignedPayload<DecryptionSharePayload>[];
     readonly tallyPublications?: readonly SignedPayload<TallyPublicationPayload>[];
 };
-/** Verified published tally for one option slot. */
+/**
+ * Verified published tally for one option slot.
+ *
+ * The full ceremony verifier returns one of these per manifest option after
+ * replaying ballots, decryption shares, and optional tally publications.
+ */
 export type VerifiedPublishedOptionVotingResult = {
     readonly optionIndex: number;
     readonly ballots: import('./voting-ballot-aggregation.js').VerifiedOptionBallotAggregation;

package/dist/protocol/verification.d.ts

@@ -1,12 +1,21 @@
 import type { EncodedAuthPublicKey, EncodedTransportPublicKey } from '../transport/types.js';
 import type { RegistrationPayload, SignedPayload } from './types.js';
-/** Roster entry used for deterministic roster hashing. */
+/**
+ * Roster entry used for deterministic roster hashing.
+ *
+ * This is the minimal frozen identity view derived from accepted registrations.
+ */
 export type RosterEntry = {
     readonly participantIndex: number;
     readonly authPublicKey: EncodedAuthPublicKey;
     readonly transportPublicKey: EncodedTransportPublicKey;
 };
-/** Verified protocol-signature result with the frozen registration roster. */
+/**
+ * Verified protocol-signature result with the frozen registration roster.
+ *
+ * Downstream verifiers reuse this result instead of rebuilding the roster map
+ * for every phase.
+ */
 export type VerifiedProtocolSignatures = {
     readonly participantCount: number;
     readonly registrations: readonly SignedPayload<RegistrationPayload>[];
@@ -16,8 +25,7 @@ export type VerifiedProtocolSignatures = {
 /**
  * Hashes a deterministic roster view with SHA-256.
  *
- * @param rosterEntries Deterministic roster entries.
- * @returns Lowercase hexadecimal roster hash.
+ * Manifest creation and registration verification both depend on this digest.
  */
 export declare const hashRosterEntries: (rosterEntries: readonly RosterEntry[]) => Promise<string>;
 /**
@@ -28,8 +36,7 @@ export declare const hashRosterEntries: (rosterEntries: readonly RosterEntry[])
  * same registration payload. Every later payload is verified against the
  * registered auth key for its participant index.
  *
- * @param signedPayloads Signed protocol payloads.
- * @param participantCount Optional expected participant count.
- * @returns Verified registration roster and derived roster hash.
+ * This is the signature gate that stands between raw board data and every
+ * later semantic verifier.
  */
 export declare const verifySignedProtocolPayloads: (signedPayloads: readonly SignedPayload[], participantCount?: number) => Promise<VerifiedProtocolSignatures>;

package/dist/protocol/verification.js

@@ -1,3 +1,7 @@
+/**
+ * Registration-roster hashing and signature verification for published
+ * protocol payloads.
+ */
 import { bytesToHex } from '../core/bytes.js';
 import { InvalidPayloadError, assertValidParticipantIndex, sha256, utf8ToBytes, } from '../core/index.js';
 import { importAuthPublicKey, verifyPayloadSignature } from '../transport/auth.js';
@@ -51,8 +55,7 @@ const canonicalizeRosterEntries = (rosterEntries) => {
 /**
  * Hashes a deterministic roster view with SHA-256.
  *
- * @param rosterEntries Deterministic roster entries.
- * @returns Lowercase hexadecimal roster hash.
+ * Manifest creation and registration verification both depend on this digest.
  */
 export const hashRosterEntries = async (rosterEntries) => bytesToHex(await sha256(utf8ToBytes(canonicalizeRosterEntries(rosterEntries))));
 const assertUniqueParticipantIndices = (payloads, participantCount) => {
@@ -89,9 +92,8 @@ const registrationKey = (payload) => ({
  * same registration payload. Every later payload is verified against the
  * registered auth key for its participant index.
  *
- * @param signedPayloads Signed protocol payloads.
- * @param participantCount Optional expected participant count.
- * @returns Verified registration roster and derived roster hash.
+ * This is the signature gate that stands between raw board data and every
+ * later semantic verifier.
  */
 export const verifySignedProtocolPayloads = async (signedPayloads, participantCount) => {
     const registrations = signedPayloads.filter((payload) => payload.payload.messageType === 'registration');

package/dist/protocol/voting-ballot-aggregation.d.ts

@@ -9,13 +9,21 @@ export type BallotTranscriptEntry = {
     readonly ciphertext: ElGamalCiphertext;
     readonly proof: DisjunctiveProof;
 };
-/** Result of verifying and aggregating a ballot transcript. */
+/**
+ * Result of verifying and aggregating a ballot transcript.
+ *
+ * This is the bridge between ballot verification and threshold decryption.
+ */
 export type VerifiedBallotAggregation = {
     readonly aggregate: VerifiedAggregateCiphertext;
     readonly ballots: readonly BallotTranscriptEntry[];
     readonly transcriptHash: string;
 };
-/** Verified additive ballot aggregation for one manifest option slot. */
+/**
+ * Verified additive ballot aggregation for one manifest option slot.
+ *
+ * The full ceremony verifier works one option at a time at this stage.
+ */
 export type VerifiedOptionBallotAggregation = VerifiedBallotAggregation & {
     readonly optionIndex: number;
 };

package/dist/protocol/voting-ballot-aggregation.js

@@ -1,3 +1,9 @@
+/**
+ * Ballot transcript verification and additive aggregation helpers.
+ *
+ * This module turns verified ballot ciphertexts into per-option aggregates that
+ * the decryption and tally stages can consume.
+ */
 import { bytesToHex } from '../core/bytes.js';
 import { InvalidPayloadError, RISTRETTO_GROUP, assertInSubgroup, sha256, utf8ToBytes, } from '../core/index.js';
 import { encodePoint, RISTRETTO_ZERO } from '../core/ristretto.js';

package/dist/protocol/voting-ballots.d.ts

@@ -4,10 +4,8 @@ import { type VerifiedOptionBallotAggregation } from './voting-ballot-aggregatio
  * Verifies typed ballot-submission payloads and recomputes one aggregate tally
  * ciphertext per manifest option.
  *
- * Signatures are expected to have been checked already against the frozen
- * registration roster.
- *
- * @param input Typed ballot verification input.
- * @returns Ordered per-option additive ballot aggregations.
+ * This is the public entry point for applications that already have
+ * signature-checked ballot payloads and want the per-option verified
+ * ciphertext aggregates that feed threshold decryption.
  */
 export declare const verifyBallotSubmissionPayloadsByOption: (input: VerifyBallotSubmissionPayloadsByOptionInput) => Promise<readonly VerifiedOptionBallotAggregation[]>;

package/dist/protocol/voting-ballots.js

@@ -1,3 +1,6 @@
+/**
+ * Public ballot-verification entry point for the supported score-voting flow.
+ */
 import { InvalidPayloadError } from '../core/index.js';
 import { auditSignedPayloads } from './board-audit.js';
 import { verifyAndAggregateBallotsByOption, } from './voting-ballot-aggregation.js';
@@ -37,11 +40,9 @@ const verifyAuditedBallotSubmissionPayloadsByOption = async (input) => {
  * Verifies typed ballot-submission payloads and recomputes one aggregate tally
  * ciphertext per manifest option.
  *
- * Signatures are expected to have been checked already against the frozen
- * registration roster.
- *
- * @param input Typed ballot verification input.
- * @returns Ordered per-option additive ballot aggregations.
+ * This is the public entry point for applications that already have
+ * signature-checked ballot payloads and want the per-option verified
+ * ciphertext aggregates that feed threshold decryption.
  */
 export const verifyBallotSubmissionPayloadsByOption = async (input) => {
     const context = await buildVotingManifestContext(input.manifest, input.sessionId);

package/dist/protocol/voting-codecs.d.ts

@@ -1,6 +1,6 @@
 import type { ElGamalCiphertext } from '../elgamal/types.js';
 import type { DLEQProof, DisjunctiveProof } from '../proofs/types.js';
-import type { EncodedCiphertext, EncodedCompactProof, EncodedDisjunctiveProof } from './types.js';
+import type { EncodedCiphertext, EncodedCompactProof, EncodedDisjunctiveProof, ScoreRange } from './types.js';
 /**
  * Encodes an additive ciphertext into fixed-width protocol hex.
  *
@@ -47,6 +47,11 @@ export declare const encodeDisjunctiveProof: (proof: DisjunctiveProof) => Encode
  */
 export declare const decodeDisjunctiveProof: (proof: EncodedDisjunctiveProof) => DisjunctiveProof;
 /**
- * Returns the fixed shipped score-voting domain `1..10`.
+ * Expands one inclusive contiguous score range into its allowed plaintext
+ * domain.
+ *
+ * Ballot builders and verifiers pass the resulting values into the
+ * disjunctive-proof layer so each encrypted score can be proven to belong to
+ * the manifest-declared domain.
  */
-export declare const scoreVotingDomain: () => readonly bigint[];
+export declare const scoreRangeDomain: (scoreRange: ScoreRange) => readonly bigint[];

package/dist/protocol/voting-codecs.js

@@ -1,4 +1,9 @@
+/**
+ * Encode and decode helpers that bridge low-level cryptographic objects and
+ * their published protocol payload representations.
+ */
 import { decodePoint, decodeScalar, encodeScalar } from '../core/ristretto.js';
+import { validateSupportedScoreRange } from './score-range.js';
 /**
  * Encodes an additive ciphertext into fixed-width protocol hex.
  *
@@ -62,6 +67,17 @@ export const decodeDisjunctiveProof = (proof) => ({
     branches: proof.branches.map((branch) => decodeCompactProof(branch)),
 });
 /**
- * Returns the fixed shipped score-voting domain `1..10`.
+ * Expands one inclusive contiguous score range into its allowed plaintext
+ * domain.
+ *
+ * Ballot builders and verifiers pass the resulting values into the
+ * disjunctive-proof layer so each encrypted score can be proven to belong to
+ * the manifest-declared domain.
  */
-export const scoreVotingDomain = () => Object.freeze(Array.from({ length: 10 }, (_value, index) => BigInt(index + 1)));
+export const scoreRangeDomain = (scoreRange) => {
+    validateSupportedScoreRange(scoreRange, {
+        min: 'Score range min',
+        max: 'Score range max',
+    });
+    return Object.freeze(Array.from({ length: scoreRange.max - scoreRange.min + 1 }, (_value, index) => BigInt(scoreRange.min + index)));
+};

package/dist/protocol/voting-decryption.d.ts

@@ -3,10 +3,8 @@ import type { VerifiedOptionDecryptionShares, VerifyDecryptionSharePayloadsByOpt
  * Verifies typed decryption-share payloads against the DKG transcript-derived
  * trustee keys and one locally recomputed aggregate ciphertext per option slot.
  *
- * Signatures are expected to have been checked already against the frozen
- * registration roster.
- *
- * @param input Typed decryption-share verification input.
- * @returns Verified decryption shares grouped by option.
+ * This is the public entry point for applications that have already accepted a
+ * DKG transcript and verified ballot aggregates and now need to validate the
+ * published threshold shares.
  */
 export declare const verifyDecryptionSharePayloadsByOption: (input: VerifyDecryptionSharePayloadsByOptionInput) => Promise<readonly VerifiedOptionDecryptionShares[]>;

package/dist/protocol/voting-decryption.js

@@ -1,3 +1,7 @@
+/**
+ * Public decryption-share verification entry point for the supported voting
+ * workflow.
+ */
 import { InvalidPayloadError, RISTRETTO_GROUP, assertInSubgroupOrIdentity, } from '../core/index.js';
 import { deriveTranscriptVerificationKey } from '../dkg/verification.js';
 import { verifyDLEQProof } from '../proofs/dleq.js';
@@ -92,11 +96,9 @@ const verifyAuditedDecryptionSharePayloadsByOption = async (input) => {
  * Verifies typed decryption-share payloads against the DKG transcript-derived
  * trustee keys and one locally recomputed aggregate ciphertext per option slot.
  *
- * Signatures are expected to have been checked already against the frozen
- * registration roster.
- *
- * @param input Typed decryption-share verification input.
- * @returns Verified decryption shares grouped by option.
+ * This is the public entry point for applications that have already accepted a
+ * DKG transcript and verified ballot aggregates and now need to validate the
+ * published threshold shares.
  */
 export const verifyDecryptionSharePayloadsByOption = async (input) => {
     const context = await buildVotingManifestContext(input.manifest, input.sessionId);

package/dist/protocol/voting-shared.d.ts

@@ -1,5 +1,5 @@
 import type { ProofContext } from '../proofs/types.js';
-import type { DecryptionSharePayload, ElectionManifest, ProtocolPayload, RegistrationPayload, SignedPayload, OptionAggregateInput } from './types.js';
+import type { DecryptionSharePayload, ElectionManifest, RegistrationPayload, ProtocolPayload, SignedPayload, OptionAggregateInput } from './types.js';
 export declare const BALLOT_SUBMISSION_PHASE = 5;
 export declare const BALLOT_CLOSE_PHASE = 6;
 export declare const DECRYPTION_SHARE_PHASE = 7;
@@ -10,6 +10,7 @@ type VotingManifestContext = {
     readonly optionCount: number;
     readonly protocolVersion: string;
     readonly scoreDomainValues: readonly bigint[];
+    readonly scoreRangeMax: bigint;
     readonly sessionId: string;
 };
 export declare const assertPhase: (payload: ProtocolPayload, expectedPhase: number, label: string) => void;

package/dist/protocol/voting-shared.js

@@ -1,8 +1,14 @@
+/**
+ * Shared voting-workflow validation and context helpers.
+ *
+ * Ballot verification, decryption-share verification, tally verification, and
+ * the full ceremony verifier all reuse this layer.
+ */
 import { assertPositiveParticipantIndex, InvalidPayloadError, RISTRETTO_GROUP, } from '../core/index.js';
 import { importAuthPublicKey, verifyPayloadSignature } from '../transport/auth.js';
 import { hashElectionManifest, assertSupportedProtocolVersion, SHIPPED_PROTOCOL_VERSION, validateElectionManifest, } from './manifest.js';
 import { signedProtocolPayloadBytes } from './payloads.js';
-import { scoreVotingDomain } from './voting-codecs.js';
+import { scoreRangeDomain } from './voting-codecs.js';
 export const BALLOT_SUBMISSION_PHASE = 5;
 export const BALLOT_CLOSE_PHASE = 6;
 export const DECRYPTION_SHARE_PHASE = 7;
@@ -47,7 +53,8 @@ export const buildVotingManifestContext = async (manifest, sessionId) => {
         manifestHash: await hashElectionManifest(validatedManifest),
         optionCount: validatedManifest.optionList.length,
         protocolVersion: SHIPPED_PROTOCOL_VERSION,
-        scoreDomainValues: scoreVotingDomain(),
+        scoreDomainValues: scoreRangeDomain(validatedManifest.scoreRange),
+        scoreRangeMax: BigInt(validatedManifest.scoreRange.max),
         sessionId,
     };
 };

package/dist/protocol/voting-verification.d.ts

@@ -1,17 +1,31 @@
 import { type VerifiedDKGTranscript } from '../dkg/verification.js';
 import { type BoardAudit } from './board-audit.js';
 import type { BallotClosePayload, BallotSubmissionPayload, DecryptionSharePayload, ElectionManifest, VerifyElectionCeremonyInput, VerifiedPublishedOptionVotingResult, TallyPublicationPayload } from './types.js';
-/** Stable high-level failure codes for full ceremony verification. */
+/**
+ * Stable high-level failure codes for full ceremony verification.
+ *
+ * Applications can key off these codes instead of parsing free-form error
+ * strings.
+ */
 export type ElectionVerificationErrorCode = 'MANIFEST_INVALID' | 'BOARD_INVALID' | 'DKG_INVALID' | 'SIGNATURE_INVALID' | 'BALLOT_INVALID' | 'DECRYPTION_INVALID' | 'TALLY_INVALID';
-/** Named verification stage used by the high-level ceremony verifier. */
+/**
+ * Named verification stage used by the high-level ceremony verifier.
+ */
 export type ElectionVerificationStage = 'manifest' | 'board' | 'dkg' | 'signatures' | 'ballots' | 'decryption' | 'tally';
-/** Stable structured failure result returned by the non-throwing verifier. */
+/**
+ * Stable structured failure result returned by the non-throwing verifier.
+ */
 export type ElectionVerificationFailure = {
     readonly code: ElectionVerificationErrorCode;
     readonly stage: ElectionVerificationStage;
     readonly reason: string;
 };
-/** Detailed successful output from full ceremony verification. */
+/**
+ * Detailed successful output from full ceremony verification.
+ *
+ * This bundles the derived DKG material, accepted ballot set, per-option
+ * tallies, and deterministic board-audit output.
+ */
 export type VerifiedElectionCeremony = {
     readonly manifest: ElectionManifest;
     readonly manifestHash: string;
@@ -38,7 +52,11 @@ export type VerifiedElectionCeremony = {
     readonly dkg: VerifiedDKGTranscript;
     readonly options: readonly VerifiedPublishedOptionVotingResult[];
 };
-/** Non-throwing result shape for full ceremony verification. */
+/**
+ * Non-throwing result shape for full ceremony verification.
+ *
+ * Most application integrations should prefer this over exceptions.
+ */
 export type ElectionVerificationResult = {
     readonly ok: true;
     readonly verified: VerifiedElectionCeremony;
@@ -51,36 +69,15 @@ export type ElectionVerificationResult = {
  * DKG verification, ballot verification, decryption-share verification, and
  * per-option tally checks.
  *
- * @param input Full public ceremony input bundle.
- * @returns Detailed verified ceremony output.
- *
- * @example
- * ```ts
- * const verified = await verifyElectionCeremony(bundle);
- *
- * console.log(verified.boardAudit.overall.fingerprint);
- * console.log(verified.countedParticipantIndices);
- * console.log(verified.perOptionTallies);
- * ```
+ * This is the main verifier entry point for callers that want failures to
+ * abort immediately.
  */
 export declare const verifyElectionCeremony: (input: VerifyElectionCeremonyInput) => Promise<VerifiedElectionCeremony>;
 /**
  * Runs the full ceremony verifier and returns a structured success-or-failure
  * result without throwing.
  *
- * @param input Full public ceremony input bundle.
- * @returns Verified ceremony output or a stable structured failure.
- *
- * @example
- * ```ts
- * const result = await tryVerifyElectionCeremony(bundle);
- *
- * if (!result.ok) {
- *     console.error(result.error.stage, result.error.code, result.error.reason);
- *     return;
- * }
- *
- * console.log(result.verified.qualifiedParticipantIndices);
- * ```
+ * This is the preferred integration point for applications that want stable
+ * failure stages and codes instead of exception handling.
  */
 export declare const tryVerifyElectionCeremony: (input: VerifyElectionCeremonyInput) => Promise<ElectionVerificationResult>;