The ZF FROST Book

This is a guide-level reference for the ZF FROST library.

Getting Started

If you're not familiar with FROST, first read Understanding FROST.

Then read the Tutorial, and use the Rust docs as reference.

Understanding FROST

This explains the main concepts and flows of FROST in a generic manner. These are important to understand how to use the library, but rest assured that the Tutorial will have more concrete information.

FROST is a threshold signature scheme. It allows splitting a Schnorr signing key into n shares for a threshold t, such that t (or more) participants can together generate a signature that can be validated by the corresponding verifying key. One important aspect is that the resulting signature is indistinguishable from a non-threshold signature from the point of view of signature verifiers.

Key Generation

There are two options for generating FROST key shares. In both cases, after the key generation procedure, each participant will get:

• a secret share;
• a verifying share (which can be used by other participants to verify the signature shares the participant produces);
• a group verifying key, which is the public key matching the private key that was split into shares; it is used to verify the final signature generated with FROST.

Trusted Dealer Generation

An existing key (which can be freshly generated) is split into shares. It's the simplest approach, but it has the downside of requiring the entire key to exist in memory at some point in time, which may not be desired in high security applications. However, it is much simpler to set up. It requires an authenticated and confidential communication channel to distribute each share to their respective participants.

Learn how to do Trusted Dealer Generation with the ZF FROST library.

Distributed Key Generation

A two-round protocol after which each participant will have their share of the secret, without the secret being ever present in its entirety in any participant's memory. Its downside is that it requires a broadcast channel as well as an authenticated and confidential communication channel between each pair of participants, which may be difficult to deploy in practice.

Learn how to do Distributed Key Generation with the ZF FROST library.

Signing

Signing with FROST starts with a Coordinator (which can be one of the share holders, or not) which selects the message to be signed and the participants that will generate the signature.

Each participant sends fresh nonce commitments to the Coordinator, which then consolidates them and sends them to each participant. Each one will then produce a signature share, which is sent to the Coordinator who finally aggregates them and produces the final signature.

Verifying Signatures

Signature verification is carried out as normal with single-party signatures, along with the signed message and the group verifying key as inputs.

Repairing Shares

Repairing shares allow participants to help another participant recover their share if they have lost it, or also issue a new share to a new participant (while keeping the same threshold).

The repair share functionality requires a threshold of participants to work. For example, in a 2-of-3 scenario, two participants can help the third recover their share, or they could issue a new share to move to a 2-of-4 group.

The functionality works in such a way that each participant running the repair share function is not able to obtain the share that is being recovered or issued.

Refreshing Shares

Refreshing shares allow participants (or a subset of them) to update their shares in a way that maintains the same group public key. Some applications are:

• Make it harder for attackers to compromise the shares. For example, in a 2-of-3 threshold scenario, if an attacker steals one participant's device and all participants refresh their shares, the attacker will need to start over and steal two shares instead of just one more.
• Remove a participant from the group. For example, in a 2-of-3 threshold scenario, if two participants decide to remove the third they can both refresh their shares and the third participant would no longer be able to participate in signing sessions with the others. (They can also then use the repair share functionality to issue a new share and move from 2-of-2 back to 2-of-3.)

Ciphersuites

FROST is a generic protocol that works with any adequate prime-order group, which in practice are constructed from elliptic curves. The spec specifies five ciphersuites with the Ristretto255, Ed25519, Ed448, P-256 and secp256k1 groups. It's possible (though not recommended) to use your own ciphersuite.

Network Topologies

FROST supports different network topologies for both signing and DKG (Distributed Key Generation) processes. Understanding these topologies is crucial for implementing FROST in a way that best suits your application's needs.

Signing Topologies

1. Centralized Coordinator

           Coordinator
           /    |    \
          /     |     \
         /      |      \
    Signer1  Signer2  Signer3

This is the default topology where:

• A single coordinator (which may or may not be a signer) manages the signing process
• Signers only communicate with the coordinator
• Pros: Simple to implement, clear communication flow
• Cons: Single point of failure, potential bottleneck

2. Distributed Coordination

    Signer1 -------- Signer2
        \           /
         \         /
          \       /
           Signer3

In this topology:

• Each signer acts as their own coordinator
• All signers communicate directly with each other
• Pros: No single point of failure
• Cons: More complex implementation, requires full mesh networking

DKG Topologies

1. Full Mesh (Recommended)

    Node1 --------- Node2
      | \         / |
      |  \       /  |
      |   \     /   |
      |    \   /    |
      |     \ /     |
    Node4 --- Node3

For DKG:

• All participants need to communicate directly with each other
• Requires authenticated and confidential channels between all pairs
• Requires a broadcast channel for public values
• Most secure but requires more complex networking setup

2. Star with Broadcast Hub

           Hub
         / | \
        /  |  \
    Node1  |  Node3
           |
         Node2

Alternative DKG setup:

• A central hub relays messages between participants
• Simpler networking requirements
• Hub must be trusted for message delivery (but cannot learn secrets)
• May be suitable for controlled environments

Tutorial

The ZF FROST suite consists of multiple crates. frost-core contains a generic implementation of the protocol, which can't be used directly without a concrete instantiation.

The ciphersuite crates (frost-ristretto255, frost-ed25519, frost-ed448, frost-p256, frost-secp256k1 and frost-secp256k1-tr) provide ciphersuites to use with frost-core, but also re-expose the frost-core functions without generics. If you will only use a single ciphersuite, then we recommend using those functions, and this tutorial will follow this approach. If you need to support multiple ciphersuites then feel free to use frost-core along with the ciphersuite types.

This tutorial will use the frost-ristretto255 crate, but changing to another ciphersuite should be a matter of simply changing the import.

Importing and General Information

Including frost-ristretto255

Add to your Cargo.toml file:

[dependencies]
frost-ristretto255 = "2.1.0"

Handling errors

Most crate functions mentioned below return Results with Errors. All errors should be considered fatal and should lead to aborting the key generation or signing procedure.

Serializing structures

FROST is a distributed protocol and thus it requires sending messages between participants. While the ZF FROST library does not handle communication, it can help with serialization in the following ways:

Default byte-oriented serialization

With the serialization feature, which is enabled by default, all structs that need to be communicated will have serialize() and deserialize() methods. The serialization format is described in Serialization Format.

serde

Alternatively, if you would like to use another format such as JSON, you can enable the serde feature (which is not enabled by default). When it is enabled, you can use serde to serialize any structure that needs to be transmitted. The importing would look like:

[dependencies]
frost-ristretto255 = { version = "2.1.0", features = ["serde"] }

Note that serde usage is optional. Applications can use different encodings, and to support that, all structures that need to be transmitted have public getters and new() methods allowing the application to encode and decode them as it wishes. (Note that fields like Scalar and Element do have standard byte string encodings; the application can encode those byte strings as it wishes, as well the structure themselves and things like maps and lists.)

Trusted Dealer Key Generation

The diagram below shows the trusted dealer key generation process. Dashed lines represent data being sent through an authenticated and confidential communication channel.

To generate the key shares, the dealer calls generate_with_dealer(). It returns a BTreeMap mapping the (automatically generated) Identifiers to their respective SecretShares, and a PublicKeyPackage which contains the VerifyingShare for each participant and the group public key (VerifyingKey).

use frost_ristretto255 as frost;
use std::collections::BTreeMap;

let mut rng = rand::rngs::OsRng;
let max_signers = 5;
let min_signers = 3;
let (shares, pubkey_package) = frost::keys::generate_with_dealer(
    max_signers,
    min_signers,
    frost::keys::IdentifierList::Default,
    &mut rng,
)?;

Each SecretShare must then be sent via an authenticated and confidential channel for each participant, who must verify the package to obtain a KeyPackage which contains their signing share, verifying share and group verifying key. This is done with KeyPackage::try_from():

    let key_package = frost::keys::KeyPackage::try_from(secret_share)?;

Signing

The diagram below shows the signing process. Dashed lines represent data being sent through an authenticated communication channel.

Coordinator, Round 1

To sign, the Coordinator must select which participants are going to generate the signature, and must signal to start the process. This needs to be implemented by users of the ZF FROST library and will depend on the communication channel being used.

Participants, Round 1

Each selected participant will then generate the nonces (a SigningNonces) and their commitments (a SigningCommitments) by calling round1::commit():

    let (nonces, commitments) = frost::round1::commit(
        key_package.signing_share(),
        &mut rng,
    );

The SigningNonces must be kept by the participant to use in Round 2, while the SigningCommitments must be sent to the Coordinator using an authenticated channel.

Coordinator, Round 2

The Coordinator will get all SigningCommitments from the participants and the message to be signed, and then build a SigningPackage by calling SigningPackage::new().

let message = "message to sign".as_bytes();
// In practice, the SigningPackage must be sent to all participants
// involved in the current signing (at least min_signers participants),
// using an authenticate channel (and confidential if the message is secret).
let signing_package = frost::SigningPackage::new(commitments_map, message);

The SigningPackage must then be sent to all the participants using an authenticated channel. (Of course, if the message is confidential, then the channel must also be confidential.)

Participants, Round 2

Upon receiving the SigningPackage, each participant will then produce their signature share using their KeyPackage from the key generation process and their SigningNonces from Round 1, by calling round2::sign():

    let signature_share = frost::round2::sign(&signing_package, nonces, key_package)?;

The resulting SignatureShare must then be sent back to the Coordinator using an authenticated channel.

Coordinator, Aggregate

Upon receiving the SignatureShares from the participants, the Coordinator can finally produce the final signature by calling aggregate() with the same SigningPackage sent to the participants and the PublicKeyPackage from the key generation (which is used to validate each SignatureShare).

let group_signature = frost::aggregate(&signing_package, &signature_shares, &pubkey_package)?;

The returned signature, a Signature, will be a valid signature for the message in the SigningPackage in Round 2 for the group verifying key in the PublicKeyPackage.

Verifying signatures

The Coordinator could verify the signature with:

let is_signature_valid = pubkey_package
    .verifying_key()
    .verify(message, &group_signature)
    .is_ok();

(There is no need for the Coordinator to verify the signature since that already happens inside aggregate(). This just shows how the signature can be verified.)

Distributed Key Generation

The diagram below shows the distributed key generation process. Dashed lines represent data being sent through an authenticated and confidential communication channel. Note that the first dashed line requires a broadcast channel

Part 1

To start the DKG, each participant calls dkg::part1() passing its identifier, the desired threshold and total number of participants. (Thus, they need to agree on those parameters via some mechanism which is up to the application.) It returns a round1::SecretPackage and a round1::Package:

use std::collections::BTreeMap;

use frost_ristretto255 as frost;

let mut rng = rand::rngs::OsRng;

let max_signers = 5;
let min_signers = 3;

    // Ask the user which identifier they would like to use. You can create
    // an identifier from a non-zero u16 or derive from an arbitrary string.
    // Some fixed examples follow (each participant must choose a different identifier)
    let participant_identifier = Identifier::try_from(7u16)?;
    let participant_identifier = Identifier::derive("alice@example.com".as_bytes())?;

    let (round1_secret_package, round1_package) = frost::keys::dkg::part1(
        participant_identifier,
        max_signers,
        min_signers,
        &mut rng,
    )?;

The round1::SecretPackage must be kept in memory to use in the next round. The round1::Package must be sent to all other participants using a broadcast channel to ensure that all participants receive the same value.

Part 2

Upon receiving the other participants' round1::Packages, each participant then calls dkg::part2() passing their own previously created round1::SecretPackage and a map of the received round1::Packages, keyed by the Identifiers of the participant that sent each one of them. (These identifiers must come from whatever mapping the coordinator has between communication channels and participants, i.e. they must have assurance that the round1::Package came from the participant with that identifier.) It returns a round2::SecretPackage and a BTreeMap mapping other participants's Identifiers to round2::Packages:

    let (round2_secret_package, round2_packages) =
        frost::keys::dkg::part2(round1_secret_package, round1_packages)?;

The round2::SecretPackage must be kept in memory for the next part; the round1::SecretPackage is consumed and is not required anymore.

The round2::Packages must be sent to their respective participants with the given Identifiers, using an authenticated and confidential communication channel.

Part 3

Finally, upon receiving the other participant's round2::Package, the DKG is concluded by calling dkg::part3() passing the same round1::Packages received in Part 2, the round2::Packages just received (again keyed by the Identifier of the participant that sent each one of them), and the previously stored round2::SecretPackage for the participant. It returns a KeyPackage, with the participant's secret share, and a PublicKeyPackage containing the group verifying key:

    let (key_package, pubkey_package) = frost::keys::dkg::part3(
        round2_secret_package,
        round1_packages,
        round2_packages,
    )?;

Refreshing Shares using a Trusted Dealer

The diagram below shows the refresh share process. Dashed lines represent data being sent through an authenticated and confidential communication channel.

The Trusted Dealer needs to first run compute_refreshing_shares() which returns SecretShares (the "refreshing shares") and a PublicKeyPackage. Each SecretShare must then be sent along with the PublicKeyPackage via an authenticated and confidential channel for each participant.

Each Participant then runs refresh_share() to generate a new KeyPackage which will replace their old KeyPackage; they must also replace their old PublicKeyPackage with the one sent by the Trusted Dealer.

User Documentation

• frost-core
• frost-rerandomized
• frost-ed25519
• frost-ed448
• frost-p256
• frost-ristretto255
• frost-secp256k1
• frost-secp256k1-tr

Serialization Format

With the serialization feature, which is enabled by default, all structs that need to communicated will have serialize() and deserialize() methods.

The format is basically the serde encoding of the structs using the postcard crate. But since this is an implementation detail, we describe the format as follows:

• Integers are encoded in varint format
• Fixed-size byte arrays are encoded as-is (e.g. scalars, elements)
  • Note that the encoding of scalars and elements are defined by the ciphersuites.
• Variable-size byte arrays are encoded with a length prefix (varint-encoded) and the array as-is (e.g. the message)
• Maps are encoded as the varint-encoded item count, followed by concatenated item encodings.
• Structs are encoded as the concatenation of the encodings of its items, with a Header struct as the first item, which contains the format version (a u8) and the ciphersuite ID.
  • The format currently described is identified by the constant 0.
  • Ciphersuite IDs are encoded as the 4-byte CRC-32 of the ID string (the constant Ciphersuite::ID, which for default ciphersuites is the contextString of the ciphersuite, per the FROST spec).

For example, the following Signing Package:

• Header (map):
  • Version (u8): 0
  • Ciphersuite ID (4 bytes): CRC-32 of FROST-RISTRETTO255-SHA512-v1
• Commitments (map):
  • Identifier (byte array): 2a00000000000000000000000000000000000000000000000000000000000000
  • Signing Commitments:
    • Hiding (byte array): e2f2ae0a6abc4e71a884a961c500515f58e30b6aa582dd8db6a65945e08d2d76
    • Bindng (byte array): 6a493210f7499cd17fecb510ae0cea23a110e8d5b901f8acadd3095c73a3b919
    • Ciphersuite ID (4 bytes): CRC-32 of FROST-RISTRETTO255-SHA512-v1
• Message (variable size byte array): 68656c6c6f20776f726c64 ("hello world" in UTF-8)

Is encoded as

00d76ecff5012a00000000000000000000000000000000000000000000000000
00000000000000d76ecff5e2f2ae0a6abc4e71a884a961c500515f58e30b6aa5
82dd8db6a65945e08d2d766a493210f7499cd17fecb510ae0cea23a110e8d5b9
01f8acadd3095c73a3b9190b68656c6c6f20776f726c64

• 00: the version of the format
• d76ecff5: the ciphersuite ID of the SigningPackage; CRC-32 of FROST-RISTRETTO255-SHA512-v1
• 01: the length of the map
• 2a00000000000000000000000000000000000000000000000000000000000000: the identifier
• d76ecff5: the ciphersuite ID of the SigningCommitments; CRC-32 of FROST-RISTRETTO255-SHA512-v1
• e2f2ae0a6abc4e71a884a961c500515f58e30b6aa582dd8db6a65945e08d2d76: the hinding commitment
• 6a493210f7499cd17fecb510ae0cea23a110e8d5b901f8acadd3095c73a3b919: the binding commitment
• 0b: the length of the message
• 68656c6c6f20776f726c64: the message

Test Vectors

Check the snapshots files in each ciphersuite crate for test vectors.

FROST with Zcash

FROST can be used with the Zcash cryptocurrency, allowing the creation of a wallet shared between multiple participants where multiple participants must authorize a transaction before it can go through.

In a regular Zcash wallet, the spending key (commonly derived from a seed phrase) allows freely spending from the wallet. If the key is lost or gets hacked, then the wallet owner will lose access to their funds forever.

With FROST, only shares of the related spend authorization key will exist, between multiple participants. During wallet creation, a threshold is set, and only that number of participants (or more) can jointly create a transaction that spends funds from the wallet.

Some possible applications are:

• Creating a wallet that is shared between members of a organization that manages certain funds. For example, a 3-of-5 wallet can be created which will require 3 members to authorize spending the funds.
• Shared custody services can be created so that users can have their own wallet and can spend their funds with the help of the service, and will not lose access to the funds in case they lose the device with their key share. For example, a 2-of-3 wallet where the user keeps one share, the service keeps another, and the third share is backed up in the user's cloud.

FROST thus helps addressing one of the biggest challenges in cryptocurrencies, which is the protecting the wallet key from either being accidentally lost or being hacked. Before, users needed to choose to either manage their own funds will puts a huge amount of responsibility on them and is well known to work greatly in practice, or to leave their funds to be managed by some custody service which is also known to be a risk. With FROST, users can share the responsibility between multiple entities or persons (or even multiple devices they own).

This section describes in more details how FROST can be used with Zcash.

Technical Details

FROST only works with Schnorr signatures. Zcash transparent transactions use ECDSA, therefore FROST does not work with Zcash transparent addresses. (This could change if the Taproot upgrade from Bitcoin is ported to Zcash, but it seems unlikely.)

Zcash supports three shielded pools: Sprout, Sapling and Orchard. Sprout is being deprecated so we only need to care about Sapling and Orchard.

Sapling and Orchard keys are commonly derived from a single spending key (which in turn is commonly derived from a seed phrase). This is shown in the figure below, taken from the Zcash protocol:

To use FROST with Zcash, the key that needs to be split is the Spend Authorizing Key or ask. This is the key that signs transactions and allow them to go through.

Key Derivation and DKG Support

As shown in the figure, the ask is commonly derived from the Spending Key sk. At first, this could indicate that it is impossible to use Distributed Key Generation (DKG) in this scenario, since the key it creates is unpredictable.

However, the protocol does not require ask to be derived from sk. This would allow creating key shares using DKG, which will also output ak (which is simply the public key matching ask). Thus:

• With Sapling, the rest of the keys can be derived from that ak and either:
  • An sk which is used to derive only nsk and ovk;
  • Or generating nsk and ovk by themselves (or generating them from a random sk which is thrown away).
• With Orchard, the rest of the keys can be derived from that ak and either:
  • An sk which is used to derive only nk and rivk;
  • Or generating nk and rivk by themselves (or generating them from a random sk which is thrown away).

Arguably this should be done even if Trusted Dealer Key Generation is used: the goal of FROST is requiring multiple entities to authorize a transaction, not having a seed phrase that allows recreating the ask ensures that property.

Backing Up Key Shares

Zcash users are familiar with the concept of seed phrases and with how they can always recover their wallet with it.

However, FROST wallets need more information to be restored:

• FROST-related:
  • Key share
  • Verifying shares of all participants
  • Public keys and identifiers of all participants if online communication is being used
• Zcash-related:
  • Sapling: sk, or both Proof authorizing key (ak and nsk) and Outgoing viewing key (ovk)
  • Orchard: sk, or Full viewing key (ak, nk, rivk). The upside of using the Full viewing key is that there is already a format for encoding it.

Thus, even if a sk derived from a seed phrase is used, that is not enough to restore a FROST wallet. In fact it would be probably confusing to use a seed phrase since users wouldn't be able to tell if it's a regular Zcash seed phrase or a FROST seed phrase which needs additional information to be restored.

For this reason it seems impossible to easily encode a FROST wallet, so using something like a JSON file with all this information is advisable.

Of course, unlike regular Zcash wallets, a user losing their FROST wallet is not catastrophic. Users can recover their key share with the help of other participants, and would only need to remember their identifier (and other participants can probably help with that).

Communications

The biggest challenge in using FROST with Zcash is allowing participants to communicate securely with each other, which is required to run the FROST protocol. Since wallets don't currently need to communicate with each other, a whole new mechanism will need to be implemented.

For this to happen, two things are required:

• Allowing wallets to actually communicate with each other (regardless of security). This is challenging because users are usually behind NATs and firewalls, so they can't simply open TCP connections with each other. So, some kind of signaling server may be needed.
• Making the communication secure. This is actually fairly solvable while not trivial and we're planning on working on a library to address it. It needs to provide authentication and confidentiality, for example using the Noise protocol. Also needs to provide a broadcast channel on top of it.
• Managing public keys. Another challenging part. Users need to be able to create a key pair of keys used for the secure communication, and exporting public keys to each other. This is similar to contact management that some wallets have, so a possibility is to expand on that (instead of storing just name and address, also store identifier and public key).

One long-term idea is to extend the Zcash protocol to allow P2P messaging.
This has been discussed in the context of sending encrypted notes via the network
instead of publishing them on the blockchain.

Another idea is to extend lightwalletd servers to support messaging, since
wallets are all already connected to a server (not the same one, so inter-server
communications would be also needed)

Ywallet Demo Tutorial

This tutorial explaining how to run the FROST demo using Ywallet that was presented during Zcon4 (though it has been updated and it differs from what was presented).

Ywallet supports offline signing, which allows having a view-only account that can generate a transaction plan, which can be signed by an offline wallet also running Ywallet. The demo uses this mechanism but signs the transaction plan with a command line tool, using FROST.

This tutorial assumes familiarity with the command line.

Setting up

Install cargo and git.

Install Ywallet.

Install the frost-client tool:

cargo install --git https://github.com/ZcashFoundation/frost-zcash-demo.git --locked frost-client

Install the zcash-sign tool:

cargo install --git https://github.com/ZcashFoundation/frost-zcash-demo.git --locked zcash-sign

Switch to an empty folder which will store the files generated in the demo. For example:

mkdir frost-demo
cd frost-demo/

Running the server

This demo uses the ZF FROST server (frostd) to help participants communicate. While in practice users would use an existing online server, for the demo you can run a local server by following these instructions (the "Compiling, Running and Deploying" and "Local Testing" sections).

The rest of the tutorial assumes the server is up and running.

Initializing the users

Run the following command to initialize three users (in practice, each user would run a similar command, but for demo purposes we're assuming you will simulate all of them in the same machine, so run these commands in your machine):

frost-client init -c alice.toml
frost-client init -c bob.toml
frost-client init -c eve.toml

This will create a config file for three users; Alice, Bob and Eve.

Generating FROST key shares

First we will generate the FROST key shares. For simplicity we'll use trusted dealer; if you want to use Distributed Key Generation, skip to the next section.

In a new terminal (in case the previous terminal is running the server), run the following:

frost-client trusted-dealer -d "Alice, Bob and Eve's group" --names Alice,Bob,Eve -c alice.toml -c bob.toml -c eve.toml -C redpallas

This will by default generate a 2-of-3 key shares. The key shares will be written into each participant's config file. You can change the threhsold, number of shares and file names using the command line; append -h to the commend above for the command line help.

Generating FROST key shares using DKG

For real-word usage we commend generating key shares using Distributed Key Generation. If you did the previous section, skip to "Generating the Full Viewing Key for the wallet".

Initializing config files

If they haven't yet, each participant should run:

frost-client init

Sharing contacts

Each participant must now generate a contact string that they will need to share with the other participants. This contact string will include a name, which they can choose when exporting and will be shown to whoever they send the contact to.

Run the following, substituting the name accordingly:

frost-client export --name 'Alice'

The command will print an encoded contact string such as zffrost1qyqq2stvd93k2g84hudcr98zp67a9rnx9v00euw9e5424hjathvre7ymy344fynjdvxmwxfg. Send it to the other participants using some trusted communication channel (instant messaging, etc.).

The other participants will send you their contacts. Import them by running the following command for each contact (replace <contact-string> with the contact string accordingly):

frost-client import <contact-string>

Generating shares

Finally, to generate the shares, one of the participants will need to initiate the process. They will need to public key of each participant, so they need to first list them with the following command:

frost-client contacts

Then run the following command, replacing the <pubkey1> and <pubkey2> hex strings with the public keys of the contacts which will participate (along with the user running the command):

frost-client dkg -d "Alice, Bob and Eve's group" -s localhost:2744 -S <pubkey1>,<pubkey2> -t 2 -C redpallas -c alice.toml

The user should then notify the others that a signing session has started (e.g. via instant messaging again), and also share the threshold number that was used. They should then run the following, replacing the name of the group if they wish and the threshold number with the one given by the first participant.

frost-client dkg -d "Alice, Bob and Eve's group" -s localhost:2744 -t 2 -C redpallas

Generating the Full Viewing Key for the wallet

Next, we will need to generate a Zcash Full Viewing Key from the FROST group material we have just generated; this address will then be imported into a wallet so that we'll be able to create Zcash transactions for it.

Run the following command:

frost-client groups

It will list all groups you're in - at this point it should list the only one you have just created. Copy the Public Key it shows (it will look like e.g. 79d6bcee79c88ad9ba259067772b97f5de12f1435b474d03bc98f255be08a610)

The run the following command, replacing <ak> with the value you copied.

zcash-sign generate --ak <ak> --danger-dummy-sapling

It will print an Orchard address, and a Unified Full Viewing Key. Copy and paste both somewhere to use them later.

Importing the Full Viewing Key into Ywallet

Open Ywallet and click "New account". Check "Restore an account" and paste the Unified Full Viewing Key created in the previous step. Click "Import".

Funding the wallet

Now you will need to fund this wallet with some ZEC. Use the Orchard address printed by the signer (see warning below). Send ZEC to that address using another account (or try ZecFaucet).

Creating the transaction

Now you will create the transaction that you wish to sign with FROST. Click the arrow button and paste the destination address (send it to yourself if you don't know where to send it). Type the amount you want to send and click the arrow button.

The wallet will show the transaction plan. Click the snowflake button. It will show a QR code, but we want that information as a file, so click the floppy disk button and save the file somewhere (e.g. tx-plan.json).

Signing the transaction

Now you will need to simulate two participants and a Coordinator to sign the transaction, and you should still have the FROST server running which will handle communications between them. It's probably easier to open three new terminals.

Go back to the signer terminal and run the following, replacing <tx_plan_path> with the path to the file you saved in the previous step, <ufvk> with the UFVK hex string printed previously, and <tx_signed_path> with the path where you want to write the signed transaction (e.g. tx-signed.raw).

zcash-sign sign --tx-plan <tx_plan_path> --ufvk <ufvk> -o <tx_signed_path>

The program will print a SIGHASH and a Randomizer, and will prompt for a signature. This is what you will get after running FROST, so let's do that; leave the prompt there without typing anything.

Coordinator

In the second terminal, the Coordinator, run (in the same folder where you initialized the users and ran the key generation) the following:

frost-client groups -c alice.toml

This will list the groups Alice is in; it should only list the one you created earlier. You will need to copy some values in the command. Run the following, replacing the value after <group> with the "Public key" listed for the group; replacing <pubkey1> and <pubkey2> with the public keys of Alice and Bob (the hexadecimal values printed next to their names; Alice's name will be empty to indicate it's her own).

frost-client coordinator -c alice.toml --server-url localhost:2744 --group <group> -S <pubkey1>,<pubkey2> -m - -r -

It will prompt you for a message. Paste the SIGHASH generated with the zcash-sign tool and press enter. It will then prompt for a randomizer. Paste the one generated with the zcash-sign tool and press enter.

The tool will connect to the server and wait for the other participants.

Participant 1 (Alice)

In the third terminal, Participant 1, run the following (replacing <group> with the same group public key used in the previous command):

frost-client participant -c alice.toml --server-url localhost:2744 --group <group>

(We are using "Alice" again. There's nothing stopping a Coordinator from being a Partcipant too!)

Participant 2 (Bob)

In the fourth terminal, for Participant 2, run the following (replacing <group> again):

frost-client participant -c bob.toml --server-url localhost:2744 --group <group>

Coordinator

Go back to the Coordinator CLI. The protocol should run and complete successfully. It will print the final FROST-generated signature. Hurrah! Copy it (just the hex value).

Go back to the signer and paste the signature. It will write the raw signed transaction to the file you specified.

Broadcasting the transaction

Go back to Ywallet and return to its main screen. In the menu, select "More" and "Broadcast". Click the upper-right box-with-an-arrow icon and select the raw signed transaction file you have just generated (tx-signed.raw if you followed the suggestion).

That's it! You just sent a FROST-signed Zcash transaction.

ZF FROST Server (frostd)

One challenge for using FROST is allowing participants to communicate securely with one another. Devices are usually behind firewalls and NATs, which make direct connections hard.

To mitigate this issue and to make it easier to use FROST, the ZF FROST Server (frostd) was created. It is a JSON-HTTP server with a small API to allow participants to create signing sessions and to communicate with one another.

It works like this:

• Clients (coordinator or participants) authenticate to the server using a key pair, which will likely be the same key pair they use to end-to-end encrypt messages.
• The Coordinator creates a session, specifying the public keys of the participants.
• Participants list sessions they're participating in, and choose the proceed with the signing session.
• Coordinator and Participants run the FROST protocol, end-to-end encrypting messages and sending them to the server.
• The Coordinator closes the session.

Note that the server doesn't really care about the particular key pair being used; it is only used to enforce who can send messages to who.

Compiling, Running and Deploying

You will need to have Rust and Cargo installed. Run:

cargo install --git https://github.com/ZcashFoundation/frost-zcash-demo.git --locked frostd

The frostd binary will be installed per cargo config and it will likely be in your $PATH, so you can run by simply running frostd.

To deploy the FROST Server, you need TLS/HTTPS certificates. We strongly recommend using a reverse proxy such as nginx to handle TLS and to also add denial of service protections. In that case, use the --no-tls-very-insecure flag in frostd and make nginx connect to it (see example config below).

If you want to expose frostd directly, use the --tls-cert and --tls-key to specify the paths of the PEM-encoded certificate and key. You can use Let's Encrypt to get a free certificate.

Local Testing

For local testing, you can use the mkcert tool. Install it and run:

mkcert -install
mkcert localhost 127.0.0.1 ::1

Then start the server with:

frostd  --tls-cert localhost+2.pem --tls-key localhost+2-key.pem

Sample nginx Config

This is a sample nginx config file tested in a Ubuntu deployment (i.e. it assumes it's in a http block and it's included by /etc/nginx/nginx.conf); copy it to /etc/nginx/sites-enabled/frostd and run sudo service nginx restart.

The config assumes the certificates were copied to /etc/ssl.

limit_req_zone $binary_remote_addr zone=challenge:10m rate=30r/m;
limit_req_zone $binary_remote_addr zone=create:10m rate=10r/m;
limit_req_zone $binary_remote_addr zone=other:10m rate=240r/m;
limit_conn_zone $binary_remote_addr zone=addr:10m;

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    ssl_certificate /etc/ssl/localhost+2.pem;
    ssl_certificate_key /etc/ssl/localhost+2-key.pem;
    ssl_protocols TLSv1.3;
    ssl_ecdh_curve X25519:prime256v1:secp384r1;
    ssl_prefer_server_ciphers off;

    server_name localhost;

    client_body_timeout 5s;
    client_header_timeout 5s;

    location / {
        proxy_pass http://127.0.0.1:2744;
        limit_req zone=other burst=5;
        limit_conn addr 10;
    }
    location /challenge {
        proxy_pass http://127.0.0.1:2744/challenge;
        limit_req zone=challenge burst=3;
        limit_conn addr 10;
    }
    location /create_new_session {
        proxy_pass http://127.0.0.1:2744/create_new_session;
        limit_req zone=create burst=3;
        limit_conn addr 10;
    }
}

API

The API uses JSON/HTTP. All requests should have Content-Type: application/json. Errors are returned with status code 500 and the content body will have a JSON such as:

{ code: 1, msg: "error message" }

The codes are:

pub const INVALID_ARGUMENT: usize = 1;
pub const UNAUTHORIZED: usize = 2;
pub const SESSION_NOT_FOUND: usize = 3;
pub const NOT_COORDINATOR: usize = 4;

Usage flow

For the Coordinator:

• Log in with /challenge and /login
• Create a new signing session with /create_new_session
• Wait for round 1 messages by repeatedly polling /receive each 2 seconds or longer
• Send round 2 messages by using /send
• Wait for round 2 message by repeatedly polling /receive each 2 seconds or longer
• Close the session with /close_session

For Participants:

• Log in with /challenge and /login
• Wait for signing sessions with /list_sessions, either by the user's request or by repeatedly polling each 10 seconds or longer
• Get the session information with /get_session_info
• Show the user the session information (who the participants are) to select which session (if more than one)
• Send round 1 message by using /send
• Wait for round 2 message by repeatedly polling /receive each 2 seconds or longer
• Send round 2 message by using /send

/challenge

Input: empty

Sample output:

{"challenge":"2c5cdb6d-a7db-470e-9e6f-2a7062532825"}

Returns a challenge that the client will need to sign in order to authenticate.

/login

To call /login, you will need to sign the challenge with XEdDSA, see example. Sign the challenge UUID, converted to bytes.

Input sample:

{
  "challenge":"b771757e-085a-4a88-ab8f-28bd4ba67f3a",
  "pubkey":"f5bf1b8194e20ebdd28e662b1efcf1c5cd2aaade5d5dd83cf89b246b5492726b",
  "signature":"bba398d0963ab88e28134ad41c127eeee816a219838db01dd7bcd9d7fcd975f082330c134e6f7238580ba8434652aa116891495452d9048f5615e07f4ad6b204"
}

Output sample:

{"access_token":"061a18ba-2c3c-4685-a79e-2c0c93000af5"}

The returned access token must be included as a bearer token in an Authorization header; e.g. Authorization: Bearer 061a18ba-2c3c-4685-a79e-2c0c93000af5.

Access tokens are currently valid for 1 hour. It's recommended to login at the beginning of each FROST session; log in again if it needs to take longer.

/logout

Input: empty (it will logout the authenticated user)

Output: empty

Logs out, invalidating the access token. Note that access tokens expire after 1 hour anyway.

/create_new_session

Input sample:

{
  "pubkeys": [
    "3c9f4a3b2ae28c8e11fbc90b693a9712c181275fb4b554a140c68dc13cdd9b4c",
    "edbd661dec0a9d0468b4a166a4afa80560d769f6bcb152fb8f4224059329a518"
  ],
  message_count: 1,
}

Output sample:

{"session_id": "2c5cdb6d-a7db-470e-9e6f-2a7062532825"}

Creates a new session. The requesting user will be the Coordinator, and the users with the hex-encoded public keys given in pubkeys will be the participants (which might or might not include the Coordinator itself).

The message_count parameter allows signing more than one message in the same signing session, which will save roundtrips. This does not impacts the server itself and is used to signal the participants (via /get_session_info).

/list_sessions

Input: empty (it will list for the authenticated user)

Output sample:

{"session_ids": ["2c5cdb6d-a7db-470e-9e6f-2a7062532825"]}

List the sessions IDs of the session a participant is in.

/get_session_info

Input sample:

{"session_id": "2c5cdb6d-a7db-470e-9e6f-2a7062532825"}

Output sample:

{
  "message_count": 1,
  "pubkeys": [
    "3c9f4a3b2ae28c8e11fbc90b693a9712c181275fb4b554a140c68dc13cdd9b4c",
    "edbd661dec0a9d0468b4a166a4afa80560d769f6bcb152fb8f4224059329a518"
  ],
  "coordinator_pubkey": "3c9f4a3b2ae28c8e11fbc90b693a9712c181275fb4b554a140c68dc13cdd9b4c",
}

Returns information about the given session.

/send

Input sample:

{
  "session_id": "2c5cdb6d-a7db-470e-9e6f-2a7062532825",
  "recipients": ["3c9f4a3b2ae28c8e11fbc90b693a9712c181275fb4b554a140c68dc13cdd9b4c"],
  "msg": "000102",
}

Output: empty

Sends a (hex-encoded) message to one or more participants. To send to the Coordinator, pass an empty list in recipients (do not use the Coordinator's public key, because that might be ambiguous if they're also a Participant).

/receive

Input sample:

{
  "session_id": "2c5cdb6d-a7db-470e-9e6f-2a7062532825",
  "as_coordinator": false,
}

Output sample:

{
  "msgs":[
    {
      "sender": "3c9f4a3b2ae28c8e11fbc90b693a9712c181275fb4b554a140c68dc13cdd9b4c",
      "msg": "000102",
    }
  ]
}

Receives messages sent to the requesting user. Note that if a user is both a Coordinator and a Participant, it is not possible to distinguish if a message received from them was sent as Coordinator or as a Participant. This does not matter in FROST since this ambiguity never arises (Participants always receive messages from the Coordinator, and vice-versa, except during DKG where there is no Coordinator anyway).

/close_session

Input sample:

{"session_id": "2c5cdb6d-a7db-470e-9e6f-2a7062532825"}

Output: empty

Closes the given session. Only the Coordinator who created the session can close it. Sessions also expire by default after 24 hours.

Terminology

Broadcast channel

A secure broadcast channel in the context of multi-party computation protocols such as FROST has the following properties:

1. Consistent. Each participant has the same view of the message sent over the channel.
2. Authenticated. Players know that the message was in fact sent by the claimed sender. In practice, this requirement is often fulfilled by a PKI.
3. Reliable Delivery. Player i knows that the message it sent was in fact received by the intended participants.
4. Unordered. The channel does not guarantee ordering of messages.

Possible deployment options:

• Echo-broadcast (Goldwasser-Lindell)
• Posting commitments to an authenticated centralized server that is trusted to provide a single view to all participants (also known as 'public bulletin board')

Identifier

An identifier is a non-zero scalar (i.e. a number in a range specific to the ciphersuite) which identifies a specific party. There are no restrictions to them other than being unique for each participant and being in the valid range.

In the ZF FROST library, they are either automatically generated incrementally during key generation or converted from a u16 using a TryFrom<u16>.

ZF FROST also allows deriving identifiers from arbitrary byte strings with Identifier::derive(). This allows deriving identifiers from usernames or emails, for example.

Peer to peer channel

Peer-to-peer channels are authenticated, reliable, and unordered, per the definitions above. Additionally, peer-to-peer channels are confidential; i.e., only participants i and j are allowed to know the contents of a message msg_i,j.

Possible deployment options:

• Mutually authenticated TLS
• Wireguard

Threshold secret sharing

Threshold secret sharing does not require a broadcast channel because the dealer is fully trusted.

Verifiable secret sharing

Verifiable secret sharing requires a broadcast channel because the dealer is not fully trusted: keygen participants verify the VSS commitment which is transmitted over the broadcast channel before accepting the shares distributed from the dealer, to ensure all participants have the same view of the commitment.

Developer Documentation

This section contains information only relevant to ZF FROST developers or contributors.

FROST dependencies

This is a list of production Rust code that is in scope and out of scope for FROSTs second audit.

--

Full Audit

FROST Crates

ZF Dependencies

Partial Audit

The following ed448-goldilocks modules are used by frost-ed448:

• src/field/scalar.rs
• src/curve/edwards/extended.rs (converting to/from TwistedExtendedPoint, MontgomeryPoint and AffinePoint are out of scope)
• src/field/mod.rs
• src/curve/scalar_mul/variable_base.rs

Out of Scope

The following crates and dependencies are out of scope for the audit.

FROST Crates

frost-core Dependencies

frost-ed25519 Dependencies

frost-ed448 Dependencies

frost-p256 Dependencies

frost-rerandomized Dependencies

frost-ristretto255 Dependencies

None

frost-secp256k1 Dependencies

Release Checklist

One-time gh setup

Install the GitHub command line tool to make releases easier.

One-time crates.io setup

• Follow the steps in https://doc.rust-lang.org/cargo/reference/publishing.html#before-your-first-publish (you can create a token scoped to publish-update).
• To get permissions to publish you’ll need to be in the owners group. If you aren’t in there, ask someone in that group to add you

Communication

• Post in #frost slack channel and tag the Frost team that you’re going to be doing a release to freeze PR approvals until it’s done. E.g “@frost-core I’m doing a release of <version> of Frost. Please do not merge any more PRs until I’m finished. Thanks.”

Checks

• Currently all crates share the same version number, in the root Cargo.toml file. Take note of that version. (If we ever decide to have specific versions, update those separately as required.)

• Decide which version to tag the release with (e.g. v0.3.0), considering SemVer.

• Create new issue. E.g. Release v0.4.0

Make changes

• Bump the version of the crates in the root Cargo.toml file. (If they ever get out of sync, you will need to bump in each crate Cargo.toml file.)

• Run cargo semver-checks to check if there are no API changes that break SemVer compatibility. (Installation instructions) Fix issues if any (i.e. change the version, or revert/adapt the API change).

• Bump the version used in the tutorial (importing.md)

• Check if the changelog is up to date and update if required (we’re only keeping the one in frost-core for now). Double check using FROST releases which will have a list of all the PRs that have been closed since the last release. Things to include in the changelog will be anything that impacts production code and big documentation changes. I.e. script and test changes should not be included. NOTE: Please add to the changelog whenever you make changes to the library as this will make things simpler for the person in charge of the release.

  • Move version in changelog to Released
  • Create a new version in “unreleased” in changelog

• Update the version number for frost-core and frost-rerandomized in the root Cargo.toml file, e.g. in frost-core = { path = "frost-core", version = "0.4.0", default-features = false }

• Create a PR with subject Release \<version number> containing all these changes

• You’ll need someone to review and approve it

• Wait for it to pass CI checks

Publish

• Checkout main branch, in the commit of the previously merged PR (in case other stuff got merged after that)

• Run cargo publish -p frost-core --dry-run to check if it’s ready to publish. Fix issues if any.

• Draft and publish a new release for frost-core.

  • In “Choose a tag” type <crate>/<version> e.g. “frost-core/v0.2.0” and click “Create new tag”
  • In “Target” select “main” as long as other PRs haven’t been merged after the version bump PR. Otherwise, select the commit matching the PR that was merged above.
  • In “Release title” use <crate> <version> e.g. “frost-core v0.2.0”
  • Paste the (raw Markdown) changelog for this version into the description box.
  • Leave “Set as pre-release” unchecked (we should have checked it in earlier versions but the ship has sailed. It doesn’t matter much)
  • Check “Set as the latest release”

• Publish it with cargo publish -p frost-core

• Check if frost-rerandomized is ready to be published: cargo publish -p frost-rerandomized --dry-run. Fix any errors if needed.

• Draft and publish a frost-rerandomized release:

  • Run gh release create "frost-rerandomized/v2.1.0" -n '' -t "frost-rerandomized v2.1.0" --latest=false (replace both instances of the version)

• Publish it with cargo publish -p frost-rerandomized

• Check if other crates are ready to be published: for cs in ristretto255 ed25519 secp256k1 secp256k1-tr p256 ed448; do cargo publish -p frost-$cs --dry-run; done. Fix any issues if needed.

  • If you get an error like this:

    “error: failed to verify package tarball Caused by: failed to select a version for the requirement frost-core = "^0.3.0" candidate versions found which didn't match: 0.2.0, 0.1.0 location searched: crates.io index required by package frost-ed25519 v0.3.0 (frost/target/package/frost-ed25519-0.3.0)”

    This is because the ciphersuite crates aren’t pointing at the new frost-core package. This is because you need to publish frost-core before you can publish the others otherwise they will not have the expected version to point to.

• Draft and publish releases for each of those crates:

  • Run for cs in ristretto255 ed25519 secp256k1 secp256k1-tr p256 ed448; do gh release create "frost-$cs/v2.1.0" -n '' -t "frost-$cs v2.1.0" --latest=false; done (replace both instances of the version)

• Publish those crates: for cs in ristretto255 ed25519 secp256k1 secp256k1-tr p256 ed448; do cargo publish -p frost-$cs; done

Confirm

• Check versions in the crates to confirm everything worked:

  • Frost core
  • Frost ed25519
  • Frost ed448
  • Frost p256
  • Frost ristretto255
  • Frost secp256k1
  • Frost secp256k1 tr
  • Frost rerandomized

• Let the team know in the #frost slack channel that the release is complete and successful

In the case of an unsuccessful release

If something was wrongly tagged, you can just retag it. If something was wrongly pushed to crates.io, you will need to make a new fixed release and yank the wrong release.

Developer Guide

Pre-commit checks

1. Run tests cargo test
2. Run formatter cargo fmt
3. Check linter cargo clippy --all-features --all-targets -- -D warnings and if you want to automatically fix then run cargo clippy --fix

Coverage

Test coverage checks are performed in the pipeline. This is configured here: .github/workflows/coverage.yaml To run these locally:

1. Install coverage tool by running cargo install cargo-llvm-cov
2. Run cargo llvm-cov --ignore-filename-regex '.*(tests).*|benches.rs|gencode|helpers.rs' (you may be asked if you want to install llvm-tools, if so type Y)