Struct KeyAggCache

Source

pub struct KeyAggCache { /* private fields */ }

Expand description

Cached data related to a key aggregation.

Implementations§

Source §

impl KeyAggCache

Source

pub fn new(pubkeys: &[&PublicKey]) -> Self

Creates a new KeyAggCache by supplying a list of PublicKeys used in the session.

Computes a combined public key and the hash of the given public keys.

Different orders of pubkeys result in different agg_pks. The pubkeys can be sorted lexicographically before combining with which ensures the same resulting agg_pk for the same multiset of pubkeys. This is useful to do before aggregating pubkeys, such that the order of pubkeys does not affect the combined public key. To do this, call key::sort_pubkeys.

§Returns

A KeyAggCache the can be used KeyAggCache::nonce_gen and Session::new.

§Args:

secp - Secp256k1 context object initialized for verification
pubkeys - Input array of public keys to combine. The order is important; a different order will result in a different combined public key

Example:

let key_agg_cache = KeyAggCache::new(&[&pub_key1, &pub_key2]);
let _agg_pk = key_agg_cache.agg_pk();

§Panics

Panics if an empty slice of pubkeys is provided.

Source

pub fn agg_pk(&self) -> XOnlyPublicKey

Obtains the aggregate public key for this KeyAggCache

Source

pub fn agg_pk_full(&self) -> PublicKey

Obtains the aggregate public key for this KeyAggCache as a full PublicKey.

This is only useful if you need the non-xonly public key, in particular for plain (non-xonly) tweaking or batch-verifying multiple key aggregations (not supported yet).

Source

pub fn pubkey_ec_tweak_add( &mut self, tweak: &Scalar, ) -> Result<PublicKey, InvalidTweakErr>

Apply ordinary “EC” tweaking to a public key in a KeyAggCache.

This is done by adding the generator multiplied with tweak32 to it. Returns the tweaked PublicKey. This is useful for deriving child keys from an aggregate public key via BIP32. This function is required if you want to sign for a tweaked aggregate key.

§Arguments:

secp : Secp256k1 context object initialized for verification
tweak: tweak of type Scalar with which to tweak the aggregated key

§Errors:

If resulting public key would be invalid (only when the tweak is the negation of the corresponding secret key). For uniformly random 32-byte arrays(for example, in BIP 32 derivation) the chance of being invalid is negligible (around 1 in 2^128).

Example:

let mut key_agg_cache = KeyAggCache::new(&[&pub_key1, &pub_key2]);

let tweak: [u8; 32] = *b"this could be a BIP32 tweak....\0";
let tweak = Scalar::from_be_bytes(tweak).unwrap();
let tweaked_key = key_agg_cache.pubkey_ec_tweak_add(&tweak).unwrap();

Source

pub fn pubkey_xonly_tweak_add( &mut self, tweak: &Scalar, ) -> Result<PublicKey, InvalidTweakErr>

Apply “x-only” tweaking to a public key in a KeyAggCache.

This is done by adding the generator multiplied with tweak32 to it. Returns the tweaked XOnlyPublicKey. This is useful in creating taproot outputs. This function is required if you want to sign for a tweaked aggregate key.

§Arguments:

secp : Secp256k1 context object initialized for verification
tweak: tweak of type SecretKey with which to tweak the aggregated key

§Errors:

If resulting public key would be invalid (only when the tweak is the negation of the corresponding secret key). For uniformly random 32-byte arrays(for example, in BIP341 taproot tweaks) the chance of being invalid is negligible (around 1 in 2^128)

Example:


let mut key_agg_cache = KeyAggCache::new(&[&pub_key1, &pub_key2]);

let tweak = Scalar::from_be_bytes(*b"Insecure tweak, Don't use this!!").unwrap(); // tweak could be from tap
let _x_only_key_tweaked = key_agg_cache.pubkey_xonly_tweak_add(&tweak).unwrap();

Source

pub fn nonce_gen( &self, session_secrand: SessionSecretRand, pub_key: PublicKey, msg: &[u8; 32], extra_rand: Option<[u8; 32]>, ) -> (SecretNonce, PublicNonce)

Starts a signing session by generating a nonce

This function outputs a secret nonce that will be required for signing and a corresponding public nonce that is intended to be sent to other signers.

MuSig differs from regular Schnorr signing in that implementers must take special care to not reuse a nonce. If you cannot provide a sec_key, session_secrand UNIFORMLY RANDOM AND KEPT SECRET (even from other signers). Refer to libsecp256k1 documentation for additional considerations.

MuSig2 nonces can be precomputed without knowing the aggregate public key, the message to sign. See the new_nonce_pair method that allows generating SecretNonce and PublicNonce with only the session_secrand field.

If the aggregator lies, the resulting signature will simply be invalid.

Remember that nonce reuse will immediately leak the secret key!

§Returns:

A pair of (SecretNonce, PublicNonce) that can be later used signing and aggregation

§Arguments:

secp : Secp256k1 context object initialized for signing
session_secrand: SessionSecretRand Uniform random identifier for this session. Each call to this function must have a UNIQUE session_secrand.
pub_key: PublicKey of the signer creating the nonce.
msg: message that will be signed later on.
extra_rand: Additional randomness for mis-use resistance

Example:

let key_agg_cache = KeyAggCache::new(&[&pub_key1, &pub_key2]);
// The session id must be sampled at random. Read documentation for more details.
let session_secrand = SessionSecretRand::from_rng(&mut rand::rng());

// Provide the current time for mis-use resistance
let msg = b"Public message we want to sign!!";
let extra_rand : Option<[u8; 32]> = None;
let (_sec_nonce, _pub_nonce) = key_agg_cache.nonce_gen(session_secrand, pub_key1, msg, extra_rand);