Interface IArkadeWalletSigner

Namespace

NArk.Abstractions.Wallets

Assembly

NArk.Abstractions.dll

Wallet-side signer used during MuSig2 batch participation. The MuSig2 nonce flow is designed so the secret half never leaves the signer:

1. GenerateNonces(OutputDescriptor, MusigContext, string, CancellationToken) derives the secret nonce internally and returns only the public half.
2. The signer keeps the secret nonce indexed by the caller-supplied sessionId.
3. SignMusig(OutputDescriptor, MusigContext, string, CancellationToken) looks the secret nonce back up by the same sessionId, uses it, and consumes it.

The caller must pass a session-unique sessionId to both calls — typically a transaction identifier (e.g. a tree-node txid in batch participation), or any string the caller can correlate. AggregatePubKey on its own is not unique per signing operation: in a batch tree, multiple transactions can share the same cosigner set and taproot tweak, so their contexts have identical aggregate pubkeys but different sighashes. The sighash is buried inside MusigContext and cannot be observed by the signer, so disambiguation has to be caller-supplied.

public interface IArkadeWalletSigner

Methods

GenerateNonces(OutputDescriptor, MusigContext, string, CancellationToken)

Generates a fresh MuSig2 nonce pair for context, retains the secret half indexed by sessionId, and returns the public half. Calling twice with the same sessionId (without an intervening SignMusig(OutputDescriptor, MusigContext, string, CancellationToken) to consume the prior nonce) throws — generating a fresh nonce on top of an unused one would orphan secret material in the signer's store.

Task<MusigPubNonce> GenerateNonces(OutputDescriptor descriptor, MusigContext context, string sessionId, CancellationToken cancellationToken = default)

Parameters

descriptor OutputDescriptor

The descriptor identifying the signing key.

context MusigContext

The MuSig2 context the nonce is generated for.

sessionId string

A caller-supplied identifier unique to this signing operation. Must match the value later passed to SignMusig(OutputDescriptor, MusigContext, string, CancellationToken). Typically a transaction identifier (txid).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<MusigPubNonce>

GetPubKey(OutputDescriptor, CancellationToken)

Gets the compressed public key for the given descriptor, preserving parity.

Task<ECPubKey> GetPubKey(OutputDescriptor descriptor, CancellationToken cancellationToken = default)

Parameters

descriptor OutputDescriptor

cancellationToken CancellationToken

Returns

Task<ECPubKey>

Sign(OutputDescriptor, uint256, CancellationToken)

Produces a BIP-340 Schnorr signature over hash using the descriptor's private key, returning the x-only pubkey alongside the signature.

Task<(ECXOnlyPubKey, SecpSchnorrSignature)> Sign(OutputDescriptor descriptor, uint256 hash, CancellationToken cancellationToken = default)

Parameters

descriptor OutputDescriptor

hash uint256

cancellationToken CancellationToken

Returns

Task<(ECXOnlyPubKey, SecpSchnorrSignature)>

Remarks

The returned x-only pubkey must be the key named by descriptor (i.e. descriptor.ToXOnlyPubKey()) — not a derived, rotated, or otherwise substituted key. Signatures are stored in PSBTs keyed by this pubkey, and callers look them back up by the descriptor's key; pending-tx recovery in particular relies on that to check the wallet really signed a transaction before it signs the matching checkpoint. A signer returning a different key makes its own signatures unfindable and gets valid transactions rejected.

SignMusig(OutputDescriptor, MusigContext, string, CancellationToken)

Produces a MuSig2 partial signature for the given context using the descriptor's private key and the secret nonce generated under the same sessionId by a prior call to GenerateNonces(OutputDescriptor, MusigContext, string, CancellationToken). The secret nonce is consumed and cannot be reused for another SignMusig(OutputDescriptor, MusigContext, string, CancellationToken) call (MuSig2 nonce reuse leaks the private key).

Task<MusigPartialSignature> SignMusig(OutputDescriptor descriptor, MusigContext context, string sessionId, CancellationToken cancellationToken = default)

Parameters

descriptor OutputDescriptor

The descriptor identifying the signing key.

context MusigContext

The MuSig2 context (cosigner set + sighash) the nonce was generated for.

sessionId string

The same session identifier that was passed to the matching GenerateNonces(OutputDescriptor, MusigContext, string, CancellationToken) call. Typically a transaction identifier (txid) or any other string unique to this signing operation within the signer's scope.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<MusigPartialSignature>

Exceptions

InvalidOperationException

No secret nonce is stored for sessionId — GenerateNonces(OutputDescriptor, MusigContext, string, CancellationToken) was not called for this session on this signer, or the nonce was already consumed.