pqthreshold — How to run, test, and understand the library
Status: operator guide (v1.0.0)
Audience: developers evaluating or integrating the library
Prerequisites: Dart SDK ^3.12, sibling pqforge ^0.4.4 for local dev (see §2)
Related: TOOLING.md, CEREMONIES.md, API.md, INTEGRATION.md
pqthreshold implements threshold cryptography in pure Dart: no single party ever holds the full private key after a proper ceremony.
You choose t-of-n (for example 2-of-3):
- Any t honest participants can threshold-sign.
- t − 1 shares are cryptographically useless for signing.
- The joint public key is a normal 32-byte Ed25519 key verifiable via pqforge.
| Ceremony | Name | What it achieves |
|---|---|---|
| C1 | Root DKG | Create a threshold root with no trusted dealer |
| C2 | Dealer VSS | Split an existing secret (Feldman VSS) |
| C3 | Threshold signing | Produce a 64-byte Ed25519 signature with FROST |
| C5 | Rotation | New threshold key + continuity proof from the old quorum |
Runtime dependencies: pqforge (crypto) + swissarmyknife (state machines, validation). See SCHEMES.md and adr/002-runtime-dependencies.md.
Clone or open the repository:
cd /path/to/pqthreshold
dart pub getpqforge 0.4.4+ is required (PqBytes.sha512 for FROST profile hashes). For local development alongside the sibling repo:
# pubspec.yaml (already present in this monorepo layout)
dependency_overrides:
pqforge:
path: ../pqforgeBefore publishing or CI without a path override, publish pqforge 0.4.4 to pub.dev and remove dependency_overrides.
dart run tool/verify.dart fullRuns: pub get → dart analyze --fatal-infos → all tests → required documentation manifest → phase test directories.
dart pub get
dart analyze
dart test
dart run tool/verify.dart quick # same as CIdart test test/sharing/ # Feldman VSS (Phase 2)
dart test test/dkg/ # DKG simulation (Phase 3)
dart test test/signing/ # FROST signing (Phase 4)
dart test test/ceremony/ # Rotation + continuity (Phase 5)
dart test test/serialization/ # PQTH round-trips (Phase 6)
dart test test/cli/ # CLI smoke testsAcceptance vectors live under test/vectors/; see TEST_VECTORS.md.
Regenerate vectors (deterministic test RNG):
dart run tool/generate_dkg_vectors.dart
dart run tool/generate_frost_vectors.dart
dart run tool/generate_rotation_vectors.dartThe bundled example uses Tier 2 simulators (all parties in one process):
dart run example/pqthreshold_example.dartOn success you should see stepped output ending with Example OK:
dart run example/pqthreshold_example.dart
# or
dart run example/pqthreshold_example.dart && echo "Example OK"Do not set PqRandom.generator = PqBytes.randomBytes — that aliases the generator to itself and causes a stack overflow. Use the default platform CSPRNG, or assign a real function (as tests do with a deterministic helper).
Automated check: dart test test/example/pqthreshold_example_test.dart
Source: example/pqthreshold_example.dart — DKG root → threshold-sign a credential → rotate with continuity proof → sign under the new key.
The pqthreshold executable covers params, inspect, VSS, in-process DKG/signing, and ceremony workflows. Multi-party dir-transport (dkg participant) is deferred to v2 — use the library (CeremonySession) or packages/crypto_shared relay for production C1.
| Command | What it does |
|---|---|
pqthreshold --help |
Grouped help (styled like pqforge) |
pqthreshold version |
Package version |
pqthreshold params validate --t 2 --n 3 |
Check t/n limits (PARAMS.md) |
pqthreshold params export --t 2 --n 3 --out params.pqth |
Write 16-byte PQTH ThresholdParams file |
pqthreshold params validate --in params.pqth |
Validate an on-disk params file |
pqthreshold inspect --in <file> |
Describe PQTH objects, 16-byte ceremony.id, or wrapped-share JSON without decrypting |
pqthreshold vss split|verify|reconstruct |
C2 dealer ceremony (CEREMONIES.md) |
pqthreshold dkg simulate --t 2 --n 3 --out-dir ./dkg |
In-process C1 DKG + PQTH artifacts (CI/operator) |
pqthreshold sign run --share … --message … --out sig.bin |
Threshold-sign from ≥ t share files (primary C3 path) |
pqthreshold sign verify --public-key … --message … --signature … |
Ed25519 verify exit code |
pqthreshold ceremony run --flow c1|c3|c5|full |
Orchestrated in-process ceremonies |
Examples:
dart run pqthreshold --help
dart run pqthreshold params validate --t 2 --n 3
dart run pqthreshold dkg simulate --t 2 --n 3 --out-dir ./dkg-out
dart run pqthreshold sign run \
--share ./dkg-out/share-1.participant-1.pqth \
--share ./dkg-out/share-2.participant-2.pqth \
--message ./credential.bin --out ./credential.sig
dart run pqthreshold ceremony run --flow full
dart run pqthreshold inspect --in params.pqth| Deferred (v2 or app layer) | Library / package today |
|---|---|
pqthreshold dkg participant … (dir transport) |
CeremonySession + packages/crypto_shared relay |
sign partial → sign combine from disk (FROST round 2) |
sign run (in-process) or DistributedSigningCoordinator |
Wrapped share CLI (*.share.wrapped.json) |
packages/crypto_shared share_wrapping.dart |
Real-world ceremonies require you to:
- Move
DkgMessagebytes between participants (files, Serverpod RPC, WebSocket, etc.). - Store each officer's
Sharein secure storage (not on a shared server). - Call
ThresholdSignerfrom each signing device when a quorum is available.
Pair pqforge CLI for single-party device keys (keygen, encrypt, sign). See TERMINAL.md §3 for the unified lifecycle vision.
| Tier | Import | Use |
|---|---|---|
| Tier 1 | package:pqthreshold/pqthreshold.dart |
Production: sessions, sign, verify, PQTH codecs |
| Tier 2 | package:pqthreshold/testing.dart |
Tests, examples, docs: in-process simulators |
Tier 2 must not be used as a production transport replacement. It runs every participant in one process for convenience.
Tier 2 exports:
DkgSimulator— full C1 in one callSigningSimulator— full C3 in one callRotationSimulator— full C5 in one call
See API.md §2 for the formal split.
ThresholdParams (e.g. 2-of-3)
│
▼
C1 DKG ──► PublicKey (publish) + one Share per participant
│
▼
C3 Sign ──► any t shares + message ──► 64-byte Ed25519 signature
│
▼
C5 Rotate ──► new DKG + ContinuityProof (old quorum authorizes new key)
flowchart LR
subgraph C1["C1 Root DKG"]
P1[Participant 1]
P2[Participant 2]
P3[Participant 3]
P1 --> PK[Joint PublicKey]
P2 --> PK
P3 --> PK
P1 --> S1[Share 1]
P2 --> S2[Share 2]
P3 --> S3[Share 3]
end
subgraph C3["C3 Threshold sign"]
S1 --> SIG[Ed25519 signature]
S2 --> SIG
PK --> SIG
end
subgraph C5["C5 Rotation"]
S1 --> CP[ContinuityProof]
S2 --> CP
PK --> CP
CP --> NPK[New PublicKey + new shares]
end
Goal: A joint public key and one private share per participant. The full secret never exists in one place.
Production: Each party runs CeremonySession (or RootCeremony.startSession) and exchanges wire messages over your authenticated transport. Messages: PROTOCOL_MESSAGES.md §3.
Testing / learning:
import 'package:pqthreshold/testing.dart';
final params = ThresholdParams.tOfN(t: 2, n: 3);
final root = DkgSimulator.run(params: params);
// root.publicKey — 32-byte Ed25519 joint key (publish to directory / chain)
// root.shares — length n; each participant stores exactly ONE share
// root.transcripts — per-party audit logs (hash chain of public messages)Internal rounds:
- Round 1 — Each participant generates a random polynomial and broadcasts Feldman commitments.
- Round 2 — Each sends private shares to every other participant; receivers verify against commitments.
- Finalize — Each derives a final share; all parties compute the same joint public key.
Implementation: lib/src/dkg/ceremony_session.dart, lib/src/scheme/dkg/.
Goal: A standard 64-byte Ed25519 signature that verifies with pqforge (PqClassical.provider.ed25519Verify).
import 'dart:typed_data';
import 'package:pqthreshold/pqthreshold.dart';
import 'package:pqthreshold/testing.dart';
final message = Uint8List.fromList('membership-v1'.codeUnits);
// Simulator: first t shares sign in-process
final signature = await SigningSimulator.run(
shares: root.shares,
message: message,
);
final ok = await ThresholdSigner.verify(
publicKey: root.publicKey,
message: message,
signature: signature,
);Production pattern (coordinator optional):
- Each of t signers:
ThresholdSigner.signPartial(share:, message:). - Coordinator (or last signer):
ThresholdSigner.combine(partials:, publicKey:, message:). - Verifiers:
ThresholdSigner.verify(...).
Internal FROST rounds:
- Round 1 — Nonce commitments (hiding + binding).
- Round 2 — Partial signature scalars; binding factors and group commitment.
- Combine — Lagrange-weighted aggregation → Ed25519
(R, s).
Profile: FROST_PROFILE.md. Challenge hash (H2) uses RFC 8032 shape so pqforge Ed25519 verify succeeds.
Security: signPartial holds ephemeral nonces in memory until combine. Do not persist or transmit partials before combine in production; use wire rounds in PROTOCOL_MESSAGES.md §5.
Goal: A new threshold key plus evidence that the old quorum authorized the change.
final rotation = await RotationSimulator.run(
oldShares: root.shares,
oldPublicKey: root.publicKey,
);
await rotation.continuityProof.verify(oldPublicKey: root.publicKey);
rotation.newPublicKey; // publish as successor root
rotation.newShares; // distribute to participants
rotation.continuityProof.toBytes(); // store / publish PQTH kind 0x06Internal steps:
- Run a fresh DKG → new
PublicKey+ newShares (new ceremony ID). - Build continuity payload (PROTOCOL_MESSAGES.md §6): old/new public keys, ceremony IDs, timestamp.
- Old quorum threshold-signs the payload.
- Package as
ContinuityProof; verifiers check signature under old public key.
When a trusted dealer already holds a secret (legacy import):
import 'package:pqthreshold/pqthreshold.dart';
final outcome = VerifiableSecretSharing.split(
params: params,
ceremonyId: ceremonyId,
secret: existingSecret32Bytes,
);
// outcome.shares, outcome.publicKey, outcome.verificationDataThe dealer knows the secret at split time. Prefer C1 DKG for new organizational roots (CEREMONIES.md §5).
Durable objects use canonical PQTH bytes (ver=0x01, frozen at 1.0):
| Kind | Object | Typical use |
|---|---|---|
0x01 |
ThresholdParams |
t, n, scheme |
0x02 |
Share |
Participant private share (+ verification blob) |
0x03 |
PublicKey |
Joint Ed25519 public key |
0x04 |
PartialSignature |
Archival public FROST round material |
0x05 |
Transcript |
Ceremony audit hash chain |
0x06 |
ContinuityProof |
Rotation authorization |
Serialize / deserialize:
final bytes = share.toBytes();
final restored = Share.fromBytes(bytes);Full layout: SERIALIZATION.md.
| Concern | Package |
|---|---|
| Ed25519 verify, SHA-256/512, random bytes, classical crypto | pqforge |
| Feldman VSS, Gennaro DKG, FROST combine, ceremonies, PQTH | pqthreshold |
| State machines for DKG rounds | swissarmyknife (internal to pqthreshold) |
Typical application stack:
- Daily crypto (device keys, hybrid PQC envelopes) → pqforge / pqcrypto
- Organizational root (create, sign policy, rotate) → pqthreshold
- Transport, auth, secure storage → your application
See INTEGRATION.md §11 for a minimal integration sketch.
cd /path/to/pqthreshold
dart pub get
dart run example/pqthreshold_example.dart && echo "Example OK"
dart run tool/verify.dart fullExpected: 77 tests pass in main package, 6 in crypto_shared, analyze clean, verify: OK.
Before high-assurance production deployment:
- Complete REVIEW_CHECKLIST.md (independent cryptographic review).
- Publish pqforge 0.4.4+ and drop local
dependency_overridesif used. - Never store all shares on one server or one device.
Yes — as a library embedded in your app, not as a turnkey terminal product yet.
| Ready today | You still build |
|---|---|
DKG protocol (CeremonySession) |
Authenticated transport between officers |
| FROST threshold sign / verify | Quorum coordination UI or service |
| PQTH serialize shares, keys, transcripts | Secure share storage per device |
| Continuity proofs for rotation | Policy / directory for published public keys |
| Tier 2 simulators for tests | Production wiring (never ship simulators to users) |
Anti-patterns (see INTEGRATION.md §12):
- Storing all shares on one Serverpod server → destroys threshold guarantee
- Making the server a share-holder for the org root → server compromise = root compromise
- Using
DkgSimulator/SigningSimulatorin production app code - Threshold-signing every message → use pqforge for daily traffic; threshold only for high-value actions
Typical pattern: each officer runs a Flutter app on their own device; the app holds one share and talks to a coordination service that never sees share secrets.
┌─────────────────┐ round messages ┌──────────────────┐
│ Officer Flutter │ ◄──────────────────────►│ Coordinator │
│ app │ (DkgMessage bytes) │ (Serverpod / API)│
│ │ │ stores public │
│ flutter_secure_ │ │ material only │
│ storage: Share │ └──────────────────┘
└─────────────────┘
# pubspec.yaml (Flutter officer app or shared package)
dependencies:
pqthreshold: ^1.0.0
pqforge: ^0.4.4 # verify, wrap shares (optional)
flutter_secure_storage: ^9.0.0import 'dart:typed_data';
import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'package:pqthreshold/pqthreshold.dart';
Future<void> runDkgRound({
required ThresholdParams params,
required Uint8List ceremonyId,
required String participantId,
required int participantIndex,
required List<DkgMessage> inbox,
}) async {
final session = RootCeremony.startSession(
params: params,
ceremonyId: ceremonyId,
participantId: participantId,
participantIndex: participantIndex,
);
final outbox = session.processInbox(inbox);
// Send each DkgMessage in outbox to coordinator → other participants
// await api.postRoundMessages(outbox.map((m) => m.wireBytes).toList());
if (session.isComplete) {
final result = session.finalize();
const storage = FlutterSecureStorage();
await storage.write(
key: 'threshold_share',
value: String.fromCharCodes(result.share.toBytes()),
);
// Publish result.publicKey + result.transcript to directory (public bytes only)
}
}Your coordinator collects DkgMessage.wireBytes and routes them; it must not persist raw share scalars.
import 'package:pqthreshold/pqthreshold.dart';
Future<PartialSignature> officerSignPartial({
required Share share,
required Uint8List message,
}) async {
return ThresholdSigner.signPartial(share: share, message: message);
}
// Coordinator (or last signer) after collecting ≥ t partials:
Uint8List combineSignature({
required List<PartialSignature> partials,
required PublicKey publicKey,
required Uint8List message,
}) {
return ThresholdSigner.combine(
partials: partials,
publicKey: publicKey,
message: message,
);
}Partials contain sensitive nonce material until combine — treat as ephemeral; see API.md §4.3.
Member device keys (hybrid PQC seal/sign) stay on pqforge / pqcrypto. The threshold root only attests membership or signs policy — not every chat message.
The Serverpod server should coordinate, not custody.
| Server may store | Server must not store |
|---|---|
PublicKey, Transcript, ContinuityProof |
Share secret scalars |
| DKG round message relay | All officers' shares in one DB row |
| Published joint public key | Wrapped share passphrases |
A full example lives in example/serverpod_integration/:
| File | Purpose |
|---|---|
README.md |
Wiring steps |
threshold_ceremony_endpoint.dart.example |
Serverpod Endpoint delegating to ThresholdCeremonyService |
The endpoint relays DKG wire bytes, stores public PublicKey / Transcript, and coordinates C3 partial collection — never share scalars.
Add authentication (officer identity) and authorization (participant list) on every RPC — pqthreshold does not provide this.
Monorepo helper package (sketch, publish_to: none):
packages/crypto_shared/
lib/crypto_shared.dart # re-exports pqthreshold + pqforge
lib/src/hex_codec.dart # ceremony id / PQTH hex for JSON APIs
lib/src/ceremony_relay.dart # CeremonyMessageRelay + InMemoryCeremonyRelay
lib/src/officer_dkg_client.dart
lib/src/distributed_dkg.dart # DistributedDkgCoordinator
lib/src/signing_job_coordinator.dart
lib/src/threshold_ceremony_service.dart
Run tests:
cd packages/crypto_shared && dart pub get && dart testYour app monorepo typically adds:
officer_app/ # Flutter — holds Share, runs OfficerDkgClient
serverpod_server/ # ThresholdCeremonyEndpoint + DB relay
serverpod_client/ # generated + ceremony API wrappers
Combined signatures are standard Ed25519. Any tier can verify:
import 'package:pqthreshold/pqthreshold.dart';
final ok = await ThresholdSigner.verify(
publicKey: orgRootPublicKey,
message: credentialBytes,
signature: combinedSig,
);Same result as pqforge PqClassical.provider.ed25519Verify on the joint key bytes.
- Officers on separate devices; share in
flutter_secure_storageor HSM - Coordinator/server relays public protocol messages only
- Joint
PublicKey+Transcriptpublished to directory after C1 - Threshold sign only credentials / policy / high-value actions (C3)
- Rotation publishes
ContinuityProof(C5); verifiers check before trusting new key - Complete REVIEW_CHECKLIST.md before high-assurance deployment
| Question | Document |
|---|---|
| Public Dart types | API.md |
| Multi-party operational flows | CEREMONIES.md |
| Byte-level wire messages | PROTOCOL_MESSAGES.md |
| FROST ciphersuite details | FROST_PROFILE.md |
| Threat model | SECURITY.md |
| App integration patterns | INTEGRATION.md |
| Terminal vision (future CLI) | TERMINAL.md |
| Full doc index | INDEX.md |
| Version | Change |
|---|---|
| 2026-08-13 | Initial getting started guide (run, test, ceremony flows) |
| 2026-08-13 | CLI reality table; Flutter/Serverpod integration; fix example PqRandom note |
| 2026-08-13 | v1.0.0 CLI table; 77+6 tests; operator commands documented |