wallet: add Signer interface

[yyforyongyu]

This PR fixes #1037 - the old design has evolved here, detailed below.

Initial State: A Powerful but Risky Interface

The initial design, outlined in #1037, proposed a single, powerful Signer interface. It combined routine cryptographic operations (signing transactions, deriving public keys) with highly sensitive, security-critical functions (exporting raw private keys).

While functional, this design presented several significant issues:

1. High Security Risk: Mixing "safe" and "unsafe" methods in a single interface makes it too easy for a consumer of the API to accidentally call a dangerous method like GetPrivKeyForAddress when they intended to use a safer alternative. Security relied solely on a DANGER comment, which is insufficient for preventing misuse.
2. Lack of Extensibility: The methods used primitive arguments (e.g., *wire.MsgTx, *input.SignDescriptor). This made the method signatures rigid and hard to extend. Adding a new feature, like support for Taproot signing, would likely require a breaking API change.
3. Inflexible SignMessage: The message signing function was basic, only supporting ECDSA. It lacked the flexibility to support different signature schemes (like Schnorr) or formats (like compact, recoverable signatures) required by modern applications.

The Design Evolution: Security, Clarity, and Extensibility

The final API was shaped by a strong focus on creating a safer, more expressive, and future-proof interface for cryptographic operations.

Insight 1: Security Through Interface Segregation

The most critical design decision was to split the original Signer into two distinct interfaces:

• Signer: This interface contains only the "safe" methods that do not export raw private key material. It is intended for the majority of use cases.
• UnsafeSigner: This interface embeds the Signer interface and adds the two dangerous methods: DerivePrivKey and GetPrivKeyForAddress.

This separation forces developers to make a conscious, explicit decision to use the UnsafeSigner, dramatically reducing the risk of accidental private key exposure. It is a compile-time safeguard that makes the API inherently safer.

Insight 2: Clarity and Extensibility with Parameter Objects

Instead of passing long, complex lists of arguments, the new design uses dedicated parameter objects for its primary methods:

• ComputeUnlockingScript uses UnlockingScriptParams.
• ComputeRawSig uses RawSigParams.
• SignMessage uses SignMessageIntent.

This approach has two major benefits:

1. Clarity: It makes the code self-documenting. The parameters for each operation are grouped into a single, coherent structure.
2. Extensibility: It allows for non-breaking API changes. New options can be added to the parameter structs without changing the method signatures, making the API much more adaptable to future protocol changes.

Insight 3: Explicit Support for Spend Types via the Strategy Pattern

To handle the complexity of signing different types of inputs (Legacy, SegWit v0, Taproot), the RawSigParams struct includes a SpendDetails field. This is a sealed interface with concrete implementations for each spend type (LegacySpendDetails, SegwitV0SpendDetails, TaprootSpendDetails).

This is an application of the Strategy Pattern. It cleanly separates the signing logic for each input type, making the code easier to understand, test, and extend. Adding support for a new input type in the future would simply require a new SpendDetails implementation, with no changes to the core Signer interface.

The Final API: Safe, Expressive, and Future-Proof

The final design provides a robust and secure foundation for all cryptographic operations in the wallet.

// Signer provides an interface for common, safe cryptographic operations.
type Signer interface {
	DerivePubKey(ctx context.Context, path BIP32Path) (*btcec.PublicKey, error)
	ECDH(ctx context.Context, path BIP32Path, pub *btcec.PublicKey) ([32]byte, error)
	SignMessage(ctx context.Context, path BIP32Path, intent *SignMessageIntent) (Signature, error)
	ComputeUnlockingScript(ctx context.Context, params *UnlockingScriptParams) (*UnlockingScript, error)
	ComputeRawSig(ctx context.Context, params *RawSigParams) (RawSignature, error)
}

// UnsafeSigner provides an interface for security-sensitive cryptographic
// operations that export raw private key material.
type UnsafeSigner interface {
	Signer
	DerivePrivKey(ctx context.Context, path BIP32Path) (*btcec.PrivateKey, error)
	GetPrivKeyForAddress(ctx context.Context, a btcutil.Address) (*btcec.PrivateKey, error)
}

Why This Design is Superior:

1. Inherently Safer: The separation of Signer and UnsafeSigner is a powerful, compile-time security feature that prevents the accidental exposure of private keys.
2. More Extensible: The use of parameter objects and the strategy pattern (SpendDetails) makes the API highly adaptable to future changes in the Bitcoin protocol.
3. More Expressive and Clear: The API is more self-documenting. The intent of the caller is made explicit through the use of structs like SignMessageIntent and RawSigParams.
4. More Powerful: The new SignMessage and ComputeRawSig methods provide the flexibility needed to support advanced, multi-party protocols like those used in Lightning.

[GustavoStingelin]

Is it already supposed to be reviewed?

[GustavoStingelin]

Left some comments about the hashing functions.

[GustavoStingelin]

If this flag is false, then Hash160 is being used, which is very different from a single SHA or a double SHA. Maybe we can add an enum so the caller can choose between double SHA and RIPEMD160 in a clear way. That would make the behavior easier to read.

That said, I do not know any situation in Bitcoin where we sign a digest produced with RIPEMD160. As far as I know, signatures are always made over a double SHA digest. If there is a real reason to support RIPEMD160 here, it would be great to explain that context.

[mohamedawnallah]

If this flag is false, then Hash160 is being used, which is very different from a single SHA or a double SHA. Maybe we can add an enum so the caller can choose between double SHA and RIPEMD160 in a clear way. That would make the behavior easier to read.

Good point. I have pending review comment which something along those lines. Why aren't we mirroring the LND one (HashB returns 32 bytes when doubleHash is false)?
https://github.com/lightningnetwork/lnd/blob/8c8662c86ae5dfa371941086bb828b0af060f7fd/lnwallet/btcwallet/signer.go#L416-L421

[GustavoStingelin]

The Schnorr signer only accepts digests that are exactly 32 bytes. RIPEMD160 returns a 20 byte value, so this will fail right away. I am trying to understand the reason for using this hash here. Is there any case where we need this shorter digest for signing?

I also do not see why we cannot sign with Schnorr without a tag. This seems a bit tied to the way Taproot builds its tagged hashing, but Schnorr itself does not require that. This could be an opportunity to improve this design.