BIP-0376: use PSBT vectors for signer tests

lucia-w · lucia-w · commit 2590fa36331b · 2026-04-26T21:05:21.000+12:00
diff --git a/bip-0376.mediawiki b/bip-0376.mediawiki
@@ -147,6 +147,7 @@ These are new fields added to the existing PSBT format. Because PSBT is designed
 == Reference implementation ==
 
 A Python reference implementation is provided in [[bip-0376/reference.py|<code>bip-0376/reference.py</code>]].
+It uses the vendored <code>bitcoin_test</code> PSBT components and <code>secp256k1lab</code> test-only secp256k1 implementation from BIP 375.
 
 It demonstrates the Signer behavior specified in this BIP:
 
@@ -161,7 +162,7 @@ Machine-readable test vectors are provided in [[bip-0376/test-vectors.json|<code
 
 The vector set includes:
 
-* Valid cases with and without key negation.
+* Valid signing cases with and without key negation.
 * Invalid cases for output-key mismatch, zero tweaked key, and out-of-range spend key.
 
 The reference implementation can be run against the vectors with:
diff --git a/bip-0376/psbt_bip376.py b/bip-0376/psbt_bip376.py
@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""BIP-376 PSBT helpers."""
+
+from io import BytesIO
+import struct
+from typing import Optional
+
+from deps.bitcoin_test.messages import CTransaction, CTxOut, deser_compact_size, from_binary
+from deps.bitcoin_test.psbt import (
+    PSBT,
+    PSBTMap,
+    PSBT_GLOBAL_INPUT_COUNT,
+    PSBT_GLOBAL_OUTPUT_COUNT,
+    PSBT_GLOBAL_UNSIGNED_TX,
+    PSBT_GLOBAL_VERSION,
+    PSBT_IN_TAP_KEY_SIG,
+    PSBT_IN_WITNESS_UTXO,
+)
+
+PSBT_IN_SP_SPEND_BIP32_DERIVATION = 0x1F
+PSBT_IN_SP_TWEAK = 0x20
+
+
+class BIP376PSBTMap(PSBTMap):
+    """PSBTMap with helpers for BIP-376 field access."""
+
+    def __getitem__(self, key):
+        return self.map[key]
+
+    def __contains__(self, key):
+        return key in self.map
+
+    def get(self, key, default=None):
+        return self.map.get(key, default)
+
+    def get_by_key(self, key_type: int, key_data: bytes = b"") -> Optional[bytes]:
+        if key_data == b"":
+            return self.map.get(key_type)
+        return self.map.get(bytes([key_type]) + key_data)
+
+    def set_by_key(self, key_type: int, value_data: bytes, key_data: bytes = b"") -> None:
+        if key_data == b"":
+            self.map[key_type] = value_data
+        else:
+            self.map[bytes([key_type]) + key_data] = value_data
+
+
+class BIP376PSBT(PSBT):
+    """PSBT that deserializes maps as BIP376PSBTMap instances."""
+
+    def deserialize(self, f):
+        assert f.read(5) == b"psbt\xff"
+        self.g = from_binary(BIP376PSBTMap, f)
+
+        self.version = 0
+        if PSBT_GLOBAL_VERSION in self.g.map:
+            assert PSBT_GLOBAL_INPUT_COUNT in self.g.map
+            assert PSBT_GLOBAL_OUTPUT_COUNT in self.g.map
+            self.version = struct.unpack("<I", self.g.map[PSBT_GLOBAL_VERSION])[0]
+            assert self.version in [0, 2]
+        if self.version == 2:
+            self.in_count = deser_compact_size(
+                BytesIO(self.g.map[PSBT_GLOBAL_INPUT_COUNT])
+            )
+            self.out_count = deser_compact_size(
+                BytesIO(self.g.map[PSBT_GLOBAL_OUTPUT_COUNT])
+            )
+        else:
+            assert PSBT_GLOBAL_UNSIGNED_TX in self.g.map
+            tx = from_binary(CTransaction, self.g.map[PSBT_GLOBAL_UNSIGNED_TX])
+            self.in_count = len(tx.vin)
+            self.out_count = len(tx.vout)
+
+        self.i = [from_binary(BIP376PSBTMap, f) for _ in range(self.in_count)]
+        self.o = [from_binary(BIP376PSBTMap, f) for _ in range(self.out_count)]
+        return self
+
+
+def get_p2tr_witness_utxo_output_key(input_map: BIP376PSBTMap) -> bytes:
+    witness_utxo = input_map.get(PSBT_IN_WITNESS_UTXO)
+    if witness_utxo is None:
+        raise ValueError("missing PSBT_IN_WITNESS_UTXO")
+
+    txout = from_binary(CTxOut, witness_utxo)
+    script_pubkey = txout.scriptPubKey
+    if len(script_pubkey) != 34 or script_pubkey[:2] != b"\x51\x20":
+        raise ValueError("PSBT_IN_WITNESS_UTXO is not a P2TR output")
+    return script_pubkey[2:]
+
+
+def get_sp_tweak(input_map: BIP376PSBTMap) -> bytes:
+    tweak = input_map.get(PSBT_IN_SP_TWEAK)
+    if tweak is None:
+        raise ValueError("missing PSBT_IN_SP_TWEAK")
+    if len(tweak) != 32:
+        raise ValueError("PSBT_IN_SP_TWEAK must be 32 bytes")
+    return tweak
+
+
+def set_tap_key_sig(input_map: BIP376PSBTMap, signature: bytes) -> None:
+    if len(signature) not in (64, 65):
+        raise ValueError("PSBT_IN_TAP_KEY_SIG must be 64 or 65 bytes")
+    input_map.set_by_key(PSBT_IN_TAP_KEY_SIG, signature)
diff --git a/bip-0376/reference.py b/bip-0376/reference.py
@@ -7,117 +7,25 @@
 
 import json
 import sys
-import hashlib
 from pathlib import Path
-from typing import Optional, Tuple
 
-p = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F
-n = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
-G = (
-    0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798,
-    0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8,
+BIP375_DIR = Path(__file__).resolve().parents[1] / "bip-0375"
+DEPS_DIR = BIP375_DIR / "deps"
+SECP256K1LAB_DIR = DEPS_DIR / "secp256k1lab/src"
+for dependency_path in (BIP375_DIR, DEPS_DIR, SECP256K1LAB_DIR):
+    sys.path.insert(0, str(dependency_path))
+
+from secp256k1lab.bip340 import schnorr_sign
+from secp256k1lab.secp256k1 import G, Scalar
+
+from psbt_bip376 import (
+    BIP376PSBT,
+    PSBT_IN_SP_TWEAK,
+    get_p2tr_witness_utxo_output_key,
+    get_sp_tweak,
+    set_tap_key_sig,
 )
 
-Point = Tuple[int, int]
-
-
-def tagged_hash(tag: str, msg: bytes) -> bytes:
-    tag_hash = hashlib.sha256(tag.encode("utf-8")).digest()
-    return hashlib.sha256(tag_hash + tag_hash + msg).digest()
-
-
-def int_from_bytes(data: bytes) -> int:
-    return int.from_bytes(data, byteorder="big")
-
-
-def bytes_from_int(x: int) -> bytes:
-    return x.to_bytes(32, byteorder="big")
-
-
-def has_even_y(P: Point) -> bool:
-    return (P[1] % 2) == 0
-
-
-def bytes_from_point(P: Point) -> bytes:
-    return bytes_from_int(P[0])
-
-
-def xor_bytes(a: bytes, b: bytes) -> bytes:
-    return bytes(x ^ y for (x, y) in zip(a, b))
-
-
-def lift_x(x_coord: int) -> Optional[Point]:
-    if x_coord >= p:
-        return None
-    y_sq = (pow(x_coord, 3, p) + 7) % p
-    y_coord = pow(y_sq, (p + 1) // 4, p)
-    if pow(y_coord, 2, p) != y_sq:
-        return None
-    return (x_coord, y_coord if (y_coord % 2) == 0 else p - y_coord)
-
-
-def point_add(P1: Optional[Point], P2: Optional[Point]) -> Optional[Point]:
-    if P1 is None:
-        return P2
-    if P2 is None:
-        return P1
-    if (P1[0] == P2[0]) and (P1[1] != P2[1]):
-        return None
-    if P1 == P2:
-        lam = (3 * P1[0] * P1[0] * pow(2 * P1[1], p - 2, p)) % p
-    else:
-        lam = ((P2[1] - P1[1]) * pow(P2[0] - P1[0], p - 2, p)) % p
-    x3 = (lam * lam - P1[0] - P2[0]) % p
-    y3 = (lam * (P1[0] - x3) - P1[1]) % p
-    return (x3, y3)
-
-
-def point_mul(P: Optional[Point], scalar: int) -> Optional[Point]:
-    R = None
-    for i in range(256):
-        if (scalar >> i) & 1:
-            R = point_add(R, P)
-        P = point_add(P, P)
-    return R
-
-
-def schnorr_verify(msg: bytes, pubkey: bytes, sig: bytes) -> bool:
-    if len(pubkey) != 32 or len(sig) != 64:
-        return False
-    P = lift_x(int_from_bytes(pubkey))
-    r = int_from_bytes(sig[0:32])
-    s = int_from_bytes(sig[32:64])
-    if P is None or r >= p or s >= n:
-        return False
-    e = int_from_bytes(tagged_hash("BIP0340/challenge", sig[0:32] + pubkey + msg)) % n
-    R = point_add(point_mul(G, s), point_mul(P, n - e))
-    if R is None:
-        return False
-    return has_even_y(R) and (R[0] == r)
-
-
-def schnorr_sign(msg: bytes, seckey: bytes, aux_rand: bytes) -> bytes:
-    d0 = int_from_bytes(seckey)
-    if not (1 <= d0 <= n - 1):
-        raise ValueError("The secret key must be in the range 1..n-1.")
-    if len(aux_rand) != 32:
-        raise ValueError("aux_rand must be 32 bytes.")
-    P = point_mul(G, d0)
-    assert P is not None
-    d = d0 if has_even_y(P) else n - d0
-    t = xor_bytes(bytes_from_int(d), tagged_hash("BIP0340/aux", aux_rand))
-    k0 = int_from_bytes(tagged_hash("BIP0340/nonce", t + bytes_from_point(P) + msg)) % n
-    if k0 == 0:
-        raise RuntimeError("Failure. This happens only with negligible probability.")
-    R = point_mul(G, k0)
-    assert R is not None
-    k = k0 if has_even_y(R) else n - k0
-    e = int_from_bytes(tagged_hash("BIP0340/challenge", bytes_from_point(R) + bytes_from_point(P) + msg)) % n
-    sig = bytes_from_point(R) + bytes_from_int((k + e * d) % n)
-    if not schnorr_verify(msg, bytes_from_point(P), sig):
-        raise RuntimeError("The created signature does not pass verification.")
-    return sig
-
 
 def parse_hex(data: str, expected_len: int, field_name: str) -> bytes:
     raw = bytes.fromhex(data)
@@ -126,29 +34,45 @@ def parse_hex(data: str, expected_len: int, field_name: str) -> bytes:
     return raw
 
 
-def derive_signing_key(spend_seckey: bytes, tweak: bytes, output_pubkey: bytes) -> Tuple[int, int, bool]:
-    b_spend = int_from_bytes(spend_seckey)
-    if not (1 <= b_spend <= n - 1):
+def derive_signing_key(
+    spend_seckey: bytes, tweak: bytes, output_pubkey: bytes
+) -> tuple[Scalar, Scalar, bool]:
+    try:
+        b_spend = Scalar.from_bytes_checked(spend_seckey)
+    except ValueError as exc:
+        raise ValueError("spend key out of range") from exc
+    if b_spend == 0:
         raise ValueError("spend key out of range")
 
-    tweak_int = int_from_bytes(tweak)
-    d_raw = (b_spend + tweak_int) % n
+    d_raw = b_spend + Scalar.from_bytes_wrapping(tweak)
     if d_raw == 0:
         raise ValueError("tweaked private key is zero")
 
-    Q = point_mul(G, d_raw)
-    assert Q is not None
-    negated = not has_even_y(Q)
-    d = d_raw if not negated else n - d_raw
+    Q = d_raw * G
+    assert not Q.infinity
+    negated = not Q.has_even_y()
+    d = d_raw if not negated else -d_raw
 
-    Q_even = point_mul(G, d)
-    assert Q_even is not None
-    if bytes_from_point(Q_even) != output_pubkey:
+    Q_even = d * G
+    assert not Q_even.infinity
+    if Q_even.to_bytes_xonly() != output_pubkey:
         raise ValueError("tweaked key does not match output key")
 
     return d_raw, d, negated
 
 
+def sign_psbt(psbt_data: str, spend_seckey: bytes, message: bytes, aux_rand: bytes) -> str:
+    psbt = BIP376PSBT.from_base64(psbt_data)
+    for input_map in psbt.i:
+        if input_map.get(PSBT_IN_SP_TWEAK) is None:
+            continue
+        tweak = get_sp_tweak(input_map)
+        output_pubkey = get_p2tr_witness_utxo_output_key(input_map)
+        _, d, _ = derive_signing_key(spend_seckey, tweak, output_pubkey)
+        set_tap_key_sig(input_map, schnorr_sign(message, d.to_bytes(), aux_rand))
+    return psbt.to_base64()
+
+
 def run_test_vectors(path: Path) -> bool:
     vectors = json.loads(path.read_text(encoding="utf-8"))
     all_passed = True
@@ -164,18 +88,18 @@ def run_test_vectors(path: Path) -> bool:
         print(f"- valid[{index}] {description}")
         try:
             spend_seckey = parse_hex(given["spend_seckey"], 32, "spend_seckey")
-            tweak = parse_hex(given["tweak"], 32, "tweak")
-            output_pubkey = parse_hex(given["output_pubkey"], 32, "output_pubkey")
             message = parse_hex(given["message"], 32, "message")
             aux_rand = parse_hex(given["aux_rand"], 32, "aux_rand")
 
-            d_raw, d, negated = derive_signing_key(spend_seckey, tweak, output_pubkey)
-            signature = schnorr_sign(message, bytes_from_int(d), aux_rand)
-
-            assert bytes_from_int(d_raw).hex() == expected["raw_tweaked_seckey"]
-            assert negated == expected["negated"]
-            assert bytes_from_int(d).hex() == expected["final_seckey"]
-            assert signature.hex() == expected["signature"]
+            if "psbt" in given:
+                signed_psbt = sign_psbt(given["psbt"], spend_seckey, message, aux_rand)
+                assert signed_psbt == expected["psbt"]
+            else:
+                tweak = parse_hex(given["tweak"], 32, "tweak")
+                output_pubkey = parse_hex(given["output_pubkey"], 32, "output_pubkey")
+                _, d, _ = derive_signing_key(spend_seckey, tweak, output_pubkey)
+                signature = schnorr_sign(message, d.to_bytes(), aux_rand)
+                assert signature.hex() == expected["signature"]
         except Exception as exc:
             all_passed = False
             print(f"  FAILED: {exc}")
diff --git a/bip-0376/test-vectors.json b/bip-0376/test-vectors.json
@@ -4,32 +4,24 @@
       "description": "No negation required; tweaked key directly matches output key",
       "given": {
         "spend_seckey": "26c6ca8d553ebf5633cad2f5becd608acb99bfade1005254aa59bc4fc372985a",
-        "tweak": "ac7b0d0420f0d4a567d9abcb8a52e02cfae21690fd8d2d5934370dcc5aaee221",
-        "output_pubkey": "528b75296fa646acecf3fcb7c7697f92f7645ea0e41e6ee8a66554739d2da028",
+        "psbt": "cHNidP8BAgQCAAAAAQQBAQEFAQEB+wQCAAAAAAEOIBERERERERERERERERERERERERERERERERERERERERERAQ8EAAAAAAEBK+gDAAAAAAAAIlEgUot1KW+mRqzs8/y3x2l/kvdkXqDkHm7opmVUc50toCgiHwKBLDacI8QYV1WBO0D07fDO3/vCSW94ApMlE+rXY/+u+AQAAAAAASAgrHsNBCDw1KVn2avLilLgLPriFpD9jS1ZNDcNzFqu4iEAAQMIhAMAAAAAAAABBAFqAA==",
         "message": "289e5175e02c788c2d442cfe81d6be0533d8c13e253ef763fda45d37accfe4d4",
         "aux_rand": "a617dfb275f834e26a6f0c94052dd88982c86297dba990fd96645026e7c69e10"
       },
       "expected": {
-        "raw_tweaked_seckey": "d341d791762f93fb9ba47ec1492040b7c67bd63ede8d7fadde90ca1c1e217a7b",
-        "negated": false,
-        "final_seckey": "d341d791762f93fb9ba47ec1492040b7c67bd63ede8d7fadde90ca1c1e217a7b",
-        "signature": "d0c4f5ee3768c03a8d8e1204b8e52c6a4ded1f456d0f1707e7841928945c5a45bc1c0bc671d79612ef1c67a54bd50d653ce3d33c1fd966ce9a91e053f9417778"
+        "psbt": "cHNidP8BAgQCAAAAAQQBAQEFAQEB+wQCAAAAAAEOIBERERERERERERERERERERERERERERERERERERERERERAQ8EAAAAAAEBK+gDAAAAAAAAIlEgUot1KW+mRqzs8/y3x2l/kvdkXqDkHm7opmVUc50toCgiHwKBLDacI8QYV1WBO0D07fDO3/vCSW94ApMlE+rXY/+u+AQAAAAAASAgrHsNBCDw1KVn2avLilLgLPriFpD9jS1ZNDcNzFqu4iEBE0DQxPXuN2jAOo2OEgS45SxqTe0fRW0PFwfnhBkolFxaRbwcC8Zx15YS7xxnpUvVDWU849M8H9lmzpqR4FP5QXd4AAEDCIQDAAAAAAAAAQQBagA="
       }
     },
     {
       "description": "Negation required because (b_spend + tweak)G has odd Y",
       "given": {
         "spend_seckey": "26c6ca8d553ebf5633cad2f5becd608acb99bfade1005254aa59bc4fc372985a",
-        "tweak": "58e2385eb96d1c906bbd807eafd1fddb80fb2f43026a16386a400e6832644cbc",
-        "output_pubkey": "db0edc417c73c567add118de8d138b2d0b64083f0a1bd8e876936415de7edc46",
+        "psbt": "cHNidP8BAgQCAAAAAQQBAQEFAQEB+wQCAAAAAAEOIBISEhISEhISEhISEhISEhISEhISEhISEhISEhISEhISAQ8EAAAAAAEBK+kDAAAAAAAAIlEg2w7cQXxzxWet0RjejROLLQtkCD8KG9jodpNkFd5+3EYiHwKBLDacI8QYV1WBO0D07fDO3/vCSW94ApMlE+rXY/+u+AQAAAAAASAgWOI4XrltHJBrvYB+r9H924D7L0MCahY4akAOaDJkTLwAAQMIhQMAAAAAAAABBAFqAA==",
         "message": "a78521e49048b6e0d368d3fba417fc20c7546272dafa78a8a173fcca6c81233b",
         "aux_rand": "6b31977a8ac73ede3f3653ea0d96bc3656242461e31d771985a0b17084d3cf91"
       },
       "expected": {
-        "raw_tweaked_seckey": "7fa902ec0eabdbe69f8853746e9f5e664c94eef0e36a688d1499cab7f5d6e516",
-        "negated": true,
-        "final_seckey": "8056fd13f15424196077ac8b9160a1986e19edf5cbde37aeab3893d4da5f5c2b",
-        "signature": "3df67213afd895a833bc046e9455c77a7e40165638ad489669a5c498d4d71ab565a9c54abda2e23e931f7a0f78a9f151bba07b8400b7b96d24f857c8ba65c022"
+        "psbt": "cHNidP8BAgQCAAAAAQQBAQEFAQEB+wQCAAAAAAEOIBISEhISEhISEhISEhISEhISEhISEhISEhISEhISEhISAQ8EAAAAAAEBK+kDAAAAAAAAIlEg2w7cQXxzxWet0RjejROLLQtkCD8KG9jodpNkFd5+3EYiHwKBLDacI8QYV1WBO0D07fDO3/vCSW94ApMlE+rXY/+u+AQAAAAAASAgWOI4XrltHJBrvYB+r9H924D7L0MCahY4akAOaDJkTLwBE0A99nITr9iVqDO8BG6UVcd6fkAWVjitSJZppcSY1NcatWWpxUq9ouI+kx96D3ip8VG7oHuEALe5bST4V8i6ZcAiAAEDCIUDAAAAAAAAAQQBagA="
       }
     }
   ],
