Two use-cases: private key backup and threshold signatures.
This is a TypeScript implementation of the FROST threshold signature scheme as specified in RFC 9591.
FROST (Flexible Round-Optimized Schnorr Threshold signatures) is a threshold signature scheme that allows a group of participants to collectively generate signatures, requiring a minimum number of participants during the signing process.
The threshold signature reveals only that the threshold was met. It does not reveal who signed. It is cryptographically impossible to determine which participants signed.
A single private key gets split into multiple shards during setup. Each participant gets one shard of the key. The original private key can be discarded/lost at this point.
The participants use their individual key shards to collectively create signatures that are mathematically equivalent to what the original private key would have produced, but the original private key itself is never reconstructed.
Even after successful signing ceremonies, no single participant ever gains access to the complete private key. The threshold property is maintained permanently — you always need the minimum number of participants to create future signatures.
Featuring:
- Simple Key Backup: Split any Ed25519 key with
split(), recover withrecover() - Easy Signing: Sign with recovered keys using
sign()- no ceremony complexity - Flexible Input: Accepts CryptoKey, PKCS#8, or raw 32-byte keys
- Threshold Signatures: Configurable m-of-n threshold signing for advanced use cases
- RFC 9591 Compliant: See the doc
npm i -S @substrate-system/frostFROST can be used to backup an existing Ed25519 private key by splitting it into threshold shares. This is useful for creating secure key storage where you need multiple shares to recover the original key.
In Dark Crystal, for example, the intended use is to give the shards of your private key to several of your friends, using the social graph to securely backup your key. But this works just as well by distributing your key shards amongst multiple of your own devices, in case you lose one device.
Note
We do not create a CryptoKey in recover.
The value returned by recover() is a scalar
(the mathematical secret used in signing), not a seed. WebCrypto's importKey
expects a seed, which it then hashes with SHA-512 and bit-clamps to derive a
scalar. Since we can't reverse this one-way process, we can't convert our
recovered scalar back into a CryptoKey. Instead, use the sign() function,
which handles the FROST signing ceremony internally using the scalar
directly. Signatures from sign() will verify correctly with the
original public key.
import { webcrypto } from '@substrate-system/one-webcrypto'
import {
createFrostConfig,
split,
recover,
sign
} from '@substrate-system/frost'
// 1. Generate or use existing Ed25519 keypair
const keyPair = await webcrypto.subtle.generateKey(
{ name: 'Ed25519' },
true, // extractable so we can split the private key
['sign', 'verify']
)
// 2. Split into 3 shares (require 2 to recover)
const config = createFrostConfig(2, 3)
const { groupPublicKey, keyPackages } = await split(
keyPair.privateKey,
config
)
// 3. Distribute shares to different locations
// - Share 1: USB drive in safe
// - Share 2: Cloud backup (encrypted)
// - Share 3: Paper backup
// 4. Later, recover using any 2 of 3 shares
const availableShares = [keyPackages[0], keyPackages[2]]
const recoveredKey = recover(availableShares, config)
// 5. Use the recovered key to sign
const message = new TextEncoder().encode('Important message')
const signature = await sign(recoveredKey, message, config)
// 6. Verify the signature with the original public key
const isValid = await webcrypto.subtle.verify(
'Ed25519',
keyPair.publicKey,
signature,
message
)Note
splitaccepts CryptoKey, Uint8Array (PKCS#8), or Uint8Array (32-byte raw scalar)- The recovered key will produce the same public key as the original
- You need at least the threshold number of shares to recover
- Different combinations of shares all recover the same key
Collaboratively sign a message. The final signature reveals only that the threshold was met. It does not reveal who signed. It is cryptographically impossible to determine which participants signed.
import {
createFrostConfig,
generateKeys,
thresholdSign
} from '@substrate-system/frost'
// 1. Alice creates a 3-of-4 FROST setup
const config = createFrostConfig(3, 4) // Need 3 out of 4 to sign
const { groupPublicKey, keyPackages } = generateKeys(config)
// 2. Distribute key packages to participants
const [aliceKey, bobKey, carolKey, desmondKey] = keyPackages
// 3. Later, any 3 participants can create a signature
const message = new TextEncoder().encode('Hello, FROST!')
const signature = await thresholdSign(
[bobKey, carolKey, desmondKey], // Any 3 participants
message,
groupPublicKey,
config
)
// 4. Verify signature
const isValid = await crypto.subtle.verify(
'Ed25519',
new Uint8Array(groupPublicKey.point),
signature,
message
)Run the example locally.
npm run example:nodeThis will execute the complete example showing:
- Alice creating a 3-of-4 threshold keypair
- Getting key shares for Alice, Bob, Carol, and Desmond
- Using any 3 participants to create threshold signatures
- Verifying the signature is valid
Run the tests:
npm testStart the example:
npm startCreates a FROST configuration with Ed25519 cipher suite.
function createFrostConfig (
minSigners: number,
maxSigners: number
): FrostConfigconst config = createFrostConfig(2, 3) // 2-of-3 thresholdasync function split (
privateKey: CryptoKey | Uint8Array,
config: FrostConfig
): Promise<Signers>const { groupPublicKey, keyPackages } = await split(keyPair.privateKey, config)Recover the private key from threshold shares.
function recover (
keyPackages: KeyPackage[],
config: FrostConfig
): Uint8Arrayconst recoveredKey = recover(keyPackages.slice(0, 2), config)Sign a message with a recovered key.
async function sign (
recoveredKey:Uint8Array,
message:Uint8Array,
config:FrostConfig
):Promise<Uint8Array<ArrayBuffer>>const signature = await sign(recoveredKey, message, config)Create a threshold signature from multiple participants.
async function thresholdSign (
keyPackages:KeyPackage[],
message:Uint8Array,
groupPublicKey:GroupElement,
config:FrostConfig
):Promise<Uint8Array>const signature = await thresholdSign(
[aliceKey, bobKey, carolKey], // Participant key packages
message,
groupPublicKey,
config
)Generate keys for all participants.
function generateKeys (config:FrostConfig):Signersconst { groupPublicKey, keyPackages } = generateKeys(config)
// groupPublicKey: The collective public key
// keyPackages: Individual key packages for each participantVerifies that a key package is valid.
function verifyKeyPackage (
keyPackage:KeyPackage,
config:FrostConfig
):booleanconst isValid = verifyKeyPackage(keyPackage, config)This implementation follows:
- RFC 9591 - The Flexible Round-Optimized Schnorr Threshold (FROST) Protocol
- FROST RFC 9591
- Ed25519 Signature Scheme
- Improving Geographical Resilience For Distributed Open Source Teams with FREEON
- Threshold Cryptography
- soatok/frost — Go implementation
- Lose your device, but keep your keys — FROST in iroh
Represents an individual participant in the signing ceremony.
const signer = new FrostSigner(keyPackage, config)
// Round 1: Generate nonce commitments
const round1 = signer.sign_round1()
// Round 2: Generate signature share
const round2 = signer.sign_round2(signingPackage, round1.nonces)Manages the signing ceremony and aggregates signatures.
const coordinator = new FrostCoordinator(config)
// Create signing package
const signingPackage = coordinator.createSigningPackage(
message,
commitmentShares,
participantIds
)
// Aggregate signature shares
const signature = coordinator.aggregateSignatures(
signingPackage,
signatureShares
)
// Verify signature
const isValid = coordinator.verify(signature, message, groupPublicKey)The FROST protocol consists of the following phases:
// Generate keys for all participants
const { groupPublicKey, keyPackages } = generateKeys(config)
// Distribute key packages to participants securelyEach participant generates nonces and creates commitments:
const round1Results = signers.map(signer => signer.sign_round1())Participants receive the signing package and generate signature shares:
const signingPackage = coordinator.createSigningPackage(
message, commitmentShares, participantIds
)
const signatureShares = signers.map((signer, i) =>
signer.sign_round2(signingPackage, round1Results[i].nonces)
)The coordinator combines signature shares into a final signature:
const signature = coordinator.aggregateSignatures(
signingPackage,
signatureShares.map(r => r.signatureShare)
)Alice can create a threshold keypair and later create signatures with her trusted friends.
import {
createFrostConfig,
generateKeys,
FrostCoordinator,
FrostSigner
} from '@substrate-system/frost'
// Alice decides she wants a 3-of-4 threshold scheme
const config = createFrostConfig(3, 4) // Need 3 out of 4 to sign
const { groupPublicKey, keyPackages } = generateKeys(config)
// Distribute key shares to Alice, Bob, Carol, and Desmond
const [aliceKey, bobKey, carolKey, desmondKey] = keyPackagesLater, Alice wants to sign a message but needs help from 3 of her 4 trusted friends:
// Alice chooses Carol and Desmond to help (any 3 would work)
const participants = [aliceKey, carolKey, desmondKey]
const signers = participants.map(pkg => new FrostSigner(pkg, config))
const coordinator = new FrostCoordinator(config)This process creates a threshold signature:
const message = new TextEncoder().encode('Alice\'s important message')
// Round 1: Each participant generates commitments
const round1 = signers.map(s => s.sign_round1())
const commitmentShares = round1.map((r, i) => ({
participantId: participants[i].participantId,
commitment: r.commitment
}))
// Create the signing package
const participantIds = participants.map(p => p.participantId)
const signingPackage = await coordinator.createSigningPackage(
message,
commitmentShares,
participantIds
)
// Round 2: Generate signature shares
const signatureShares = []
for (let i = 0; i < signers.length; i++) {
const res = await signers[i].sign_round2(signingPackage, round1[i].nonces)
signatureShares.push(res.signatureShare)
}
// Combine into final signature
const finalSignature = coordinator.aggregateSignatures(
signingPackage,
signatureShares
)
// Verify it worked
const valid = await coordinator.verify(finalSignature, message, groupPublicKey)
console.log('Threshold signature valid:', valid) // Should be trueThe signature is mathematically equivalent to a single-key signature