diff --git a/spec/_attachments/ic.did b/spec/_attachments/ic.did index e4c920f4..2c205f02 100644 --- a/spec/_attachments/ic.did +++ b/spec/_attachments/ic.did @@ -322,10 +322,17 @@ type schnorr_public_key_result = record { chain_code : blob; }; +type schnorr_aux = variant { + bip341: record { + merkle_root_hash: blob; + } +}; + type sign_with_schnorr_args = record { message : blob; derivation_path : vec blob; key_id : record { algorithm : schnorr_algorithm; name : text }; + aux: opt schnorr_aux; }; type sign_with_schnorr_result = record { diff --git a/spec/index.md b/spec/index.md index ee37e789..b7e486d5 100644 --- a/spec/index.md +++ b/spec/index.md @@ -2445,7 +2445,13 @@ The encoding of the signature depends on the key ID's `algorithm`: - For algorithm `ed25519`, the signature is encoded in 64 bytes according to [RFC8032, 5.1.6 Sign](https://datatracker.ietf.org/doc/html/rfc8032#section-5.1.6). -This call requires that a Schnorr key with ID `key_id` was generated by the IC and the signing functionality for that key was enabled. Otherwise, the call is is rejected. +This call requires that a Schnorr key with ID `key_id` was generated by the IC and the signing functionality for that key was enabled. Otherwise, the call is rejected. + +This call accepts an optional auxiliary parameter `aux`. The auxiliary parameter type `schnorr_aux` is a variant. The only currently supported variant is `bip341` which allows passing a Merkle tree root hash, which is required to implement Taproot signatures as defined in [BIP341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki). The `bip341` variant is only allowed for `bip340secp256k1` signatures, and if provided the `merkle_root_hash` must be generated in accordance with BIP341's specification for `taproot_output_script`. Specifically it should be either an empty bytestring (for the `script == None` case) or else 32 bytes generated using the procedure documented as `taproot_tree_helper`. If no auxiliary parameter is provided, then `bip340secp256k1` signatures are generated in accordance with BIP340. + +On the Internet Computer, the tuple of the requested master key, the calling canister, and derivation path determines which private key that is used to generate the signature, and which public key is returned by `schnorr_public_key`. + +When using BIP341 signatures, the actual signature that is created will be relative to the Schnorr signature derived as described in BIP341's `taproot_sign_script`. The key returned by `schnorr_public_key` is the value identified in BIP341 as `internal_pubkey`. Cycles to pay for the call must be explicitly transferred with the call, i.e., they are not automatically deducted from the caller's balance implicitly (e.g., as for inter-canister calls).