@substrate-system/frost
    Preparing search index...

    @substrate-system/frost

    FROST

    tests types module semantic versioning Common Changelog install size gzip size license

    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.

    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 with recover()
    • 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

    Contents

     
    npm i -S @substrate-system/frost

    FROST 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 'crypto'
    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

    • split accepts 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:node

    This will execute the complete example showing:

    1. Alice creating a 3-of-4 threshold keypair
    2. Getting key shares for Alice, Bob, Carol, and Desmond
    3. Using any 3 participants to create threshold signatures
    4. Verifying the signature is valid

    Run the tests:

    npm test

    Start the example:

    npm start

    Creates a FROST configuration with Ed25519 cipher suite.

    function createFrostConfig (
      minSigners: number,
      maxSigners: number
    ): FrostConfig

    const config = createFrostConfig(2, 3)  // 2-of-3 threshold

    async 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
    ): Uint8Array

    const 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):Signers

    const { groupPublicKey, keyPackages } = generateKeys(config)
    // groupPublicKey: The collective public key
    // keyPackages: Individual key packages for each participant

    Verifies that a key package is valid.

    function verifyKeyPackage (
      keyPackage:KeyPackage,
      config:FrostConfig
    ):boolean

    const isValid = verifyKeyPackage(keyPackage, config)

    This implementation follows:

    • RFC 9591 - The Flexible Round-Optimized Schnorr Threshold (FROST) Protocol

    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 securely

    Each 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] = keyPackages

    Later, 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 true

    The signature is mathematically equivalent to a single-key signature

    Settings

    Member Visibility

    On This Page

    FROST