Willow’25
Status: Proposal (as of 05.17.2025)
The various Willow specifications leave open some parameter choices, primarily around cryptographic primitives. Willow’25 is a set of recommended parameters that should work in a variety of settings. It provides parameter choices for the Willow data model, the Meadowcap capability system, Willow Confidential Sync, and the drop_format.
The parameters are applicable to a large variety of use cases. By using Willow’25, you sidestep the daunting task of defining your own parameter choices, and you open up interoperability to all other Willow deployments which also conform to Willow’25.
Cryptographic Primitives
Willow’25 uses cryptographically secure parameters. We intend to not release another set of recommended parameters until one of the cryptographic primitives of Willow’25 is broken.
We use Ed25519 (defined here) as the signature scheme. We write Ed25519Pk for the type of Ed25519 public keys (the 32 byte encodings, not the actual curve points).
We are still debating whether to go with Blake3 instead of William3. This is a Proposal document after all.We use WILLIAM3 as the go-to hash function, which is defined as part of the Bab specification. We write William3Digest for the type of digests, which is simply the type of 32-byte arrays.
Data Model Parameters
Willow’25 instantiates the Willow data model with the following parameters:
The type NamespaceId is the type of Ed25519Pks.
The type SubspaceId is the type of Ed25519Pks.
The max_component_length is 4096, the max_component_count is 4096, and the max_path_length is 4096.
The hash_payload function is WILLIAM3.
The type PayloadDigest is William3Digest, the total order we use is the numeric one.
The type AuthorisationToken is MeadowcapAuthorisationToken and the is_authorised_write function is meadowcap_is_authorised_write, with the Meadowcap parameter instantiation described in the next section.
Meadowcap Parameters
Willow’25 instantiates Meadowcap with the following parameters:
The namespace_signature_scheme is Ed25519.
The encode_namespace_pk function is the identity function (the public keys are bytestrings already).
The encode_namespace_sig function is the identity function (the signatures are bytestrings already).
The user_signature_scheme is Ed25519.
The encode_user_pk function is the identity function (the public keys are bytestrings already).
The encode_user_sig function is the identity function (the signatures are bytestrings already).
The is_communal function maps an Ed25519Pk to true if and only if its least significant bit is 0.
The choices for the Meadowcap max_component_length, max_component_count, and max_path_length are the same as those for the data model max_component_length, max_component_count, and max_path_length (i.e., 4096 each).
These choices of parameters make the Meadowcap instantiation compatible with the data model instantiation.
Confidential Sync Parameters
Willow’25 instantiates Confidential Sync with the following parameters:
Handshake and Transport Encryption
The SecretKey of the handshake are the secret keys of Ed25519. The PublicKey are the encoded Ed25519Pks, i.e., the 32 byte integers.
The dh function is Ed25519 scalar multiplication. encode_pk is the identify function (public keys are already byte strings).
For encryption, we use AEAD_CHACHA20_POLY1305. Unlike Noise, we use a nonce_length of 12 bytes. The keys are of type [U8; 32].
The hash function for the handshake is WILLIAM3, which has a hashlen of 32 bytes, and a blocklen of 128 bytes. The digest_to_aeadkey function is the identity function (both digests and encryption keys are 32 byte integers).
The protocol_name is the ASCII encoding of Nose_XX_ED25519_ChaChaPoly_WILLIAM3:78, 111, 115, 101, 95, 88, 88, 95, 69, 68, 50, 53, 53, 49, 57, 95, 67, 104, 97, 67, 104, 97, 80, 111, 108, 121, 95, 87, 73, 76, 76, 73, 65, 77, 51 (decimal).
General Parameters
The ReadCapabilities are the McCapabilities — as instantiated above — with a access mode of read. Consequently, the type Receiver is Ed25519Pk. The type EnumerationCapability is the type of McEnumerationCapabilities for our instantiation of Meadowcap.
The interest_hash_length is 32. The hash_interests function operates by applying WILLIAM3 to the concatenation of the following bytes:
| Bits | Big-Endian Bitfield |
|---|---|
| 0 | 1 iff the subspace_id of the PrivateInterest is any |
| 1 – 7 | The bitstring 0000000. |
| The raw bytes of the salt. | |
| The raw bytes of the namespace_id of the PrivateInterest. | |
| |
| The code in encode_path for path of the PrivateInterest. | |
For set reconciliation, the hash_lengthy_authorised_entries function is defined as follows:
- hash_lengthy_authorised_entries maps the empty set to the 32 byte array of all zeros.
- hash_lengthy_authorised_entries maps sets containing exactly one LengthyAuthorisedEntry entry to the WILLIAM3digest of the concatenation of
entry.available as a big-endian unsigned 8 byte integer. The code in encode_mc_capability for AuthorisationToken of the entry.entry. The code in encode_entry for Entry of the entry.entry. - hash_lengthy_authorised_entries hashes sets of multiple LengthyAuthorisedEntries by first hashing each singleton set as described above, and then adding the hashes modulo (i.e., discarding all overflows).
The transform_payload function maps each Payload to the corresponding Bab light verifiable stream without the leading length indicator.
The default_namespace_id is This is an Ed25519Pk we generated randomly, the corresponding secret key is [94, 20, 172, 228, 210, 200, 2, 143, 200, 154, 143, 4, 118, 91, 25, 210, 205, 117, 45, 145, 187, 55, 60, 12, 158, 212, 118, 39, 107, 92, 69, 65].[147, 78, 96, 33, 51, 158, 31, 1, 59, 169, 73, 0, 237, 194, 93, 141, 116, 192, 180, 229, 115, 118, 137, 16, 174, 15, 80, 125, 140, 129, 115, 24]. This is a communal namespace.
The default_subspace_id is equal to the default_namespace_id.
The default_payload_digest is This is the WILLIAM3 digest of the empty string.[59, 99, 143, 200, 242, 251, 104, 65, 131, 37, 163, 107, 71, 24, 255, 176, 125, 228, 87, 172, 48, 19, 147, 168, 69, 70, 106, 121, 238, 163, 40, 107].
The default_authorisation_token is the MeadowcapAuthorisationToken whose capability is the CommunalCapability with an
- access_mode of write,
- namespace_key of default_namespace_id,
- user_key of default_subspace_id, and
- empty delegations,
and whose signature is the correct signature for default_entry(default_namespace_id, default_subspace_id).
Encoding Parameters
The EncodeReadCapability encoding relation is EncodeMcCapabilityRelativePrivateInterest.
The EncodeEnumerationCapability encoding relation is EncodeMcEnumerationCapabilityRelativePrivateInterest.
The encoding function for SubspaceId is — like encode_user_pk — the identity function. The total order on SubspaceId is the numeric order on Ed25519Pk (interpreted as big-endian, unsigned integers).
The EncodeFingerprint encoding relation is the identity function (WILLIAM3 digests are bytestrings already).
The EncodeAuthorisationToken encoding relation is EncodeMeadowcapAuthorisationTokenRelative.
