Add helpers to spend taproot key path or script paths

We provide helpers for spending taproot output via the key path or any
script path, without dealing with low-level details such as signature
version, control blocks or script execution context.

It makes it easier and less error-prone to spend taproot outputs in
higher level applications.

Author: t-bast

src/commonMain/kotlin/fr/acinq/bitcoin/Crypto.kt

@@ -164,7 +164,7 @@ public object Crypto {
         public object NoTweak : SchnorrTweak()
     }
 
-    public sealed class TaprootTweak: SchnorrTweak() {
+    public sealed class TaprootTweak : SchnorrTweak() {
         /**
          * private key is tweaked with H_TapTweak(public key) (this is used for key path spending when no scripts are present)
          */
@@ -173,8 +173,11 @@ public object Crypto {
         /**
          * private key is tweaked with H_TapTweak(public key || merkle_root) (this is used for key path spending, with specific Merkle root of the script tree).
          */
-        public data class ScriptTweak(val merkleRoot: ByteVector32) : TaprootTweak()
+        public data class ScriptTweak(val merkleRoot: ByteVector32) : TaprootTweak() {
+            public constructor(scriptTree: ScriptTree) : this(scriptTree.hash())
+        }
     }
+
     /**
      * @param data data to sign (32 bytes)
      * @param privateKey private key
@@ -184,7 +187,7 @@ public object Crypto {
      */
     @JvmStatic
     public fun signSchnorr(data: ByteVector32, privateKey: PrivateKey, schnorrTweak: SchnorrTweak, auxrand32: ByteVector32? = null): ByteVector64 {
-        val priv = when(schnorrTweak)  {
+        val priv = when (schnorrTweak) {
             SchnorrTweak.NoTweak -> privateKey
             is TaprootTweak.NoScriptTweak -> privateKey.tweak(privateKey.xOnlyPublicKey().tweak(schnorrTweak))
             is TaprootTweak.ScriptTweak -> privateKey.tweak(privateKey.xOnlyPublicKey().tweak(schnorrTweak))
@@ -194,6 +197,24 @@ public object Crypto {
         return sig
     }
 
+    /** Produce a signature that will be included in the witness of a taproot key path spend. */
+    @JvmStatic
+    public fun signTaprootKeyPath(privateKey: PrivateKey, tx: Transaction, inputIndex: Int, inputs: List<TxOut>, sighashType: Int, scriptTree: ScriptTree?, annex: ByteVector? = null, auxrand32: ByteVector32? = null): ByteVector64 {
+        val data = Transaction.hashForSigningTaprootKeyPath(tx, inputIndex, inputs, sighashType, annex)
+        val tweak = when (scriptTree) {
+            null -> TaprootTweak.NoScriptTweak
+            else -> TaprootTweak.ScriptTweak(scriptTree.hash())
+        }
+        return signSchnorr(data, privateKey, tweak, auxrand32)
+    }
+
+    /** Produce a signature that will be included in the witness of a taproot script path spend. */
+    @JvmStatic
+    public fun signTaprootScriptPath(privateKey: PrivateKey, tx: Transaction, inputIndex: Int, inputs: List<TxOut>, sighashType: Int, tapleaf: ByteVector32, annex: ByteVector? = null, auxrand32: ByteVector32? = null): ByteVector64 {
+        val data = Transaction.hashForSigningTaprootScriptPath(tx, inputIndex, inputs, sighashType, tapleaf, annex)
+        return signSchnorr(data, privateKey, SchnorrTweak.NoTweak, auxrand32)
+    }
+
     @JvmStatic
     public fun verifySignatureSchnorr(data: ByteVector32, signature: ByteVector, publicKey: XonlyPublicKey): Boolean {
         return Secp256k1.verifySchnorr(signature.toByteArray(), data.toByteArray(), publicKey.value.toByteArray())

src/commonMain/kotlin/fr/acinq/bitcoin/Script.kt

@@ -386,6 +386,20 @@ public object Script {
     @JvmStatic
     public fun isPay2wsh(script: ByteArray): Boolean = isPay2wsh(parse(script))
 
+    @JvmStatic
+    public fun isPay2tr(script: List<ScriptElt>): Boolean {
+        return when {
+            script.size == 2 && script[0] == OP_1 && script[1].isPush(32) -> true
+            else -> false
+        }
+    }
+
+    @JvmStatic
+    public fun isPay2tr(script: ByteArray): Boolean = isPay2tr(parse(script))
+
+    @JvmStatic
+    public fun isPay2tr(script: ByteVector): Boolean = isPay2tr(script.toByteArray())
+
     /**
      * @param pubKeyHash public key hash
      * @return a pay-to-public-key-hash script
@@ -404,47 +418,41 @@ public object Script {
     public fun pay2pkh(pubKey: PublicKey): List<ScriptElt> = pay2pkh(pubKey.hash160())
 
     /**
-     *
      * @param script bitcoin script
      * @return a pay-to-script script
      */
     @JvmStatic
     public fun pay2sh(script: List<ScriptElt>): List<ScriptElt> = pay2sh(write(script))
 
     /**
-     *
      * @param script bitcoin script
      * @return a pay-to-script script
      */
     @JvmStatic
     public fun pay2sh(script: ByteArray): List<ScriptElt> = listOf(OP_HASH160, OP_PUSHDATA(Crypto.hash160(script)), OP_EQUAL)
 
     /**
-     *
      * @param script bitcoin script
      * @return a pay-to-witness-script script
      */
     @JvmStatic
     public fun pay2wsh(script: List<ScriptElt>): List<ScriptElt> = pay2wsh(write(script))
 
     /**
-     *
      * @param script bitcoin script
      * @return a pay-to-witness-script script
      */
     @JvmStatic
     public fun pay2wsh(script: ByteArray): List<ScriptElt> = listOf(OP_0, OP_PUSHDATA(Crypto.sha256(script)))
 
     /**
-     *
      * @param script bitcoin script
      * @return a pay-to-witness-script script
      */
     @JvmStatic
     public fun pay2wsh(script: ByteVector): List<ScriptElt> = pay2wsh(script.toByteArray())
 
     /**
-     *
      * @param pubKeyHash public key hash
      * @return a pay-to-witness-public-key-hash script
      */
@@ -455,20 +463,12 @@ public object Script {
     }
 
     /**
-     *
      * @param pubKey public key
      * @return a pay-to-witness-public-key-hash script
      */
     @JvmStatic
     public fun pay2wpkh(pubKey: PublicKey): List<ScriptElt> = pay2wpkh(pubKey.hash160())
 
-    /**
-     * @param pubkey x-only public key
-     * @return a pay-to-taproot script
-     */
-    @JvmStatic
-    public fun pay2tr(pubkey: XonlyPublicKey): List<ScriptElt> = listOf(OP_1, OP_PUSHDATA(pubkey.value))
-
     /**
      * @param pubKey public key
      * @param sig signature matching the public key
@@ -477,6 +477,47 @@ public object Script {
     @JvmStatic
     public fun witnessPay2wpkh(pubKey: PublicKey, sig: ByteVector): ScriptWitness = ScriptWitness(listOf(sig, pubKey.value))
 
+    /**
+     * @param outputKey public key exposed by the taproot script (tweaked based on the tapscripts).
+     * @return a pay-to-taproot script.
+     */
+    @JvmStatic
+    public fun pay2tr(outputKey: XonlyPublicKey): List<ScriptElt> = listOf(OP_1, OP_PUSHDATA(outputKey.value))
+
+    /**
+     * @param internalKey internal public key that will be tweaked with the [scripts] provided.
+     * @param scripts optional spending scripts that can be used instead of key-path spending.
+     * @return the script and the tweak that must be applied to the private key for [internalKey] when signing.
+     */
+    @JvmStatic
+    public fun pay2tr(internalKey: XonlyPublicKey, scripts: ScriptTree?): List<ScriptElt> {
+        val tweak = when (scripts) {
+            null -> Crypto.TaprootTweak.NoScriptTweak
+            else -> Crypto.TaprootTweak.ScriptTweak(scripts.hash())
+        }
+        val (publicKey, _) = internalKey.outputKey(tweak)
+        return pay2tr(publicKey)
+    }
+
+    /** NB: callers must ensure that they use the correct [Crypto.TaprootTweak] when generating their signature. */
+    @JvmStatic
+    public fun witnessKeyPathPay2tr(sig: ByteVector64, sighash: Int = SigHash.SIGHASH_DEFAULT): ScriptWitness = when (sighash) {
+        SigHash.SIGHASH_DEFAULT -> ScriptWitness(listOf(sig))
+        else -> ScriptWitness(listOf(sig.concat(sighash.toByte())))
+    }
+
+    /**
+     * @param internalKey taproot internal public key.
+     * @param script script that is spent (must exist in the [scriptTree]).
+     * @param witness witness for the spent [script].
+     * @param scriptTree tapscript tree.
+     */
+    @JvmStatic
+    public fun witnessScriptPathPay2tr(internalKey: XonlyPublicKey, script: ScriptTree.Leaf, witness: ScriptWitness, scriptTree: ScriptTree): ScriptWitness {
+        val controlBlock = ControlBlock.build(internalKey, scriptTree, script)
+        return ScriptWitness(witness.stack + script.script + controlBlock)
+    }
+
     public fun removeSignature(script: List<ScriptElt>, signature: ByteVector): List<ScriptElt> {
         val toRemove = OP_PUSHDATA(signature)
         return script.filterNot { it == toRemove }
@@ -622,7 +663,7 @@ public object Script {
          */
         @JvmStatic
         public fun build(internalPubKey: XonlyPublicKey, scriptTree: ScriptTree, spendingScript: ScriptTree.Leaf): ByteVector {
-            val (_, parity) = internalPubKey.outputKey(Crypto.TaprootTweak.ScriptTweak(scriptTree.hash()))
+            val (_, parity) = internalPubKey.outputKey(scriptTree)
             val controlByte = (spendingScript.leafVersion + (if (parity) 1 else 0)).toByte()
             // NB: the spending script is included in a separate witness element, so we remove it from the control block.
             val merkleProof = scriptTree.merkleProof(spendingScript.id).tail()
@@ -689,7 +730,16 @@ public object Script {
                 pubKey.size == 32 && sigBytes.isEmpty() -> false
                 pubKey.size == 32 -> {
                     val sighashType = sigHashType(sigBytes)
-                    val hash = Transaction.hashForSigningSchnorr(context.tx, context.inputIndex, context.prevouts, sighashType, signatureVersion, this.context.executionData)
+                    val hash = Transaction.hashForSigningSchnorr(
+                        context.tx,
+                        context.inputIndex,
+                        context.prevouts,
+                        sighashType,
+                        signatureVersion,
+                        context.executionData.tapleafHash,
+                        context.executionData.annex,
+                        context.executionData.codeSeparatorPos
+                    )
                     val result = Secp256k1.verifySchnorr(sigBytes.take(64).toByteArray(), hash.toByteArray(), pubKey)
                     require(result) { "Invalid Schnorr signature" }
                     result
@@ -1364,7 +1414,16 @@ public object Script {
                         val sig = stack.first()
                         val pub = XonlyPublicKey(program.byteVector32())
                         val hashType = sigHashType(sig)
-                        val hash = Transaction.hashForSigningSchnorr(context.tx, context.inputIndex, context.prevouts, hashType, SigVersion.SIGVERSION_TAPROOT, context.executionData)
+                        val hash = Transaction.hashForSigningSchnorr(
+                            context.tx,
+                            context.inputIndex,
+                            context.prevouts,
+                            hashType,
+                            SigVersion.SIGVERSION_TAPROOT,
+                            context.executionData.tapleafHash,
+                            context.executionData.annex,
+                            context.executionData.codeSeparatorPos
+                        )
                         require(Secp256k1.verifySchnorr(sig.take(64).toByteArray(), hash.toByteArray(), pub.value.toByteArray())) { " invalid Schnorr signature " }
                         return
                     } else {

src/commonMain/kotlin/fr/acinq/bitcoin/Transaction.kt

@@ -731,7 +731,8 @@ public data class Transaction(
          * @param inputs UTXOs spent by this transaction
          * @param sighashType signature hash type
          * @param sigVersion signature version
-         * @param executionData execution context of a transaction script
+         * @param tapleaf when spending a tapscript, the hash of the corresponding script leaf must be provided
+         * @param annex (optional) taproot annex
          */
         @JvmStatic
         public fun hashForSigningSchnorr(
@@ -740,7 +741,9 @@ public data class Transaction(
             inputs: List<TxOut>,
             sighashType: Int,
             sigVersion: Int,
-            executionData: Script.ExecutionData = Script.ExecutionData.empty
+            tapleaf: ByteVector32? = null,
+            annex: ByteVector? = null,
+            codeSeparatorPos: Long? = null,
         ): ByteVector32 {
             val out = ByteArrayOutput()
             out.write(0)
@@ -753,7 +756,7 @@ public data class Transaction(
                 SigVersion.SIGVERSION_TAPSCRIPT -> Pair(1, 0)
                 else -> Pair(0, 0)
             }
-            val spendType = 2 * extFlag + (if (executionData.annex != null) 1 else 0)
+            val spendType = 2 * extFlag + (if (annex != null) 1 else 0)
             out.write(spendType)
             val inputType = sighashType and SigHash.SIGHASH_INPUT_MASK
             if (inputType == SigHash.SIGHASH_ANYONECANPAY) {
@@ -763,9 +766,9 @@ public data class Transaction(
             } else {
                 writeUInt32(inputIndex.toUInt(), out)
             }
-            if (executionData.annex != null) {
+            if (annex != null) {
                 val buffer = ByteArrayOutput()
-                writeScript(executionData.annex, buffer)
+                writeScript(annex, buffer)
                 val annexHash = Crypto.sha256(buffer.toByteArray())
                 out.write(annexHash)
             }
@@ -774,15 +777,27 @@ public data class Transaction(
                 out.write(Crypto.sha256(TxOut.write(tx.txOut[inputIndex])))
             }
             if (sigVersion == SigVersion.SIGVERSION_TAPSCRIPT) {
-                require(executionData.tapleafHash != null) { "tapleaf hash is missing" }
-                out.write(executionData.tapleafHash.toByteArray())
+                require(tapleaf != null) { "tapleaf hash is missing" }
+                out.write(tapleaf.toByteArray())
                 out.write(keyVersion)
-                writeUInt32(executionData.codeSeparatorPos.toUInt(), out)
+                writeUInt32((codeSeparatorPos ?: 0xFFFFFFFFL).toUInt(), out)
             }
             val preimage = out.toByteArray()
             return Crypto.taggedHash(preimage, "TapSighash")
         }
 
+        /** Use this function when spending a taproot key path. */
+        @JvmStatic
+        public fun hashForSigningTaprootKeyPath(tx: Transaction, inputIndex: Int, inputs: List<TxOut>, sighashType: Int, annex: ByteVector? = null): ByteVector32 {
+            return hashForSigningSchnorr(tx, inputIndex, inputs, sighashType, SigVersion.SIGVERSION_TAPROOT, annex = annex)
+        }
+
+        /** Use this function when spending a taproot script path. */
+        @JvmStatic
+        public fun hashForSigningTaprootScriptPath(tx: Transaction, inputIndex: Int, inputs: List<TxOut>, sighashType: Int, tapleaf: ByteVector32, annex: ByteVector? = null): ByteVector32 {
+            return hashForSigningSchnorr(tx, inputIndex, inputs, sighashType, SigVersion.SIGVERSION_TAPSCRIPT, tapleaf, annex)
+        }
+
         @JvmStatic
         public fun correctlySpends(tx: Transaction, previousOutputs: Map<OutPoint, TxOut>, scriptFlags: Int) {
             val prevouts = tx.txIn.map { previousOutputs[it.outPoint]!! }

src/commonMain/kotlin/fr/acinq/bitcoin/XonlyPublicKey.kt

@@ -34,12 +34,16 @@ public data class XonlyPublicKey(@JvmField val value: ByteVector32) {
     }
 
     /**
-     * "tweaks" this key with an optional merkle root
+     * Tweak this key with an optional merkle root.
+     *
      * @param tapTweak taproot tweak
      * @return an (x-only pubkey, parity) pair
      */
     public fun outputKey(tapTweak: Crypto.TaprootTweak): Pair<XonlyPublicKey, Boolean> = this + PrivateKey(tweak(tapTweak)).publicKey()
 
+    /** Tweak this key with the merkle root of the given script tree. */
+    public fun outputKey(scriptTree: ScriptTree): Pair<XonlyPublicKey, Boolean> = outputKey(Crypto.TaprootTweak.ScriptTweak(scriptTree))
+
     /**
      * add a public key to this x-only key
      * @param that public key