bip46 1.0.0__tar.gz

bip46-1.0.0/.github/workflows/mypy.yml

@@ -0,0 +1,27 @@
+name: mypy
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --locked --all-extras --dev
+      - name: Run mypy
+        run: make mypy

bip46-1.0.0/.github/workflows/release.yaml

@@ -0,0 +1,27 @@
+name: release
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Build the project
+        run: uv build
+      - name: Publish to pypi
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_KEY }}
+        run: uv publish
+      - name: Create github release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ github.ref_name }}
+        run: gh release create "$tag" --generate-notes

bip46-1.0.0/.github/workflows/ruff.yml

@@ -0,0 +1,12 @@
+name: Ruff
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v3

bip46-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,27 @@
+name: tests
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --locked --all-extras --dev
+      - name: Test with pytest
+        run: make test

bip46-1.0.0/.gitignore

@@ -0,0 +1,2 @@
+__pycache__
+.env

bip46-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

bip46-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dni ⚡
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bip46-1.0.0/Makefile

@@ -0,0 +1,19 @@
+all: ruff mypy test
+format: ruff
+lint: ruff mypy
+check: checkruff mypy test
+
+install:
+	uv sync
+
+ruff:
+	uv run ruff check . --fix
+
+checkruff:
+	uv run ruff check .
+
+mypy:
+	uv run mypy .
+
+test:
+	uv run pytest tests

bip46-1.0.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: bip46
+Version: 1.0.0
+Summary: A Python implementation of BIP46: Address Scheme for Timelocked Fidelity Bonds
+Author-email: dni <dni@lnbits.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: bech32<2.0.0,>=1.2.0
+Requires-Dist: click<9.0.0,>=8.1.7
+Requires-Dist: embit<0.9.0,>=0.8.0
+Requires-Dist: httpx<1.0.0,>=0.27.2
+Requires-Dist: secp256k1<0.15.0,>=0.14.0
+Description-Content-Type: text/markdown
+
+# BIP46 - Address Scheme for Timelocked Fidelity Bonds
+
+Python implementation of BIP46: Address Scheme for Timelocked Fidelity Bonds.
+
+## Example
+
+### Create a redeem script from a mnemonic
+
+```python
+from datetime import UTC, datetime
+
+from bip46 import (
+    create_redeemscript,
+    hdkey_derive,
+    hdkey_from_mnemonic,
+    hdkey_to_pubkey,
+    lockdate_to_derivation_path,
+    redeemscript_address,
+    redeemscript_pubkey,
+)
+
+network = "mainnet"
+lock_date = datetime(2042, 6, 1, tzinfo=UTC)
+lock_path = lockdate_to_derivation_path(lock_date, network=network)
+
+hdkey = hdkey_from_mnemonic(
+    "abandon abandon abandon abandon abandon abandon"
+    " abandon abandon abandon abandon abandon about",
+    network=network,
+)
+redeem_key = hdkey_derive(hdkey, lock_path)
+redeem_pub_key = hdkey_to_pubkey(redeem_key)
+redeem_script = create_redeemscript(lock_date, redeem_pub_key)
+script_pubkey = redeemscript_pubkey(redeem_script)
+script_address = redeemscript_address(script_pubkey, network=network)
+```
+
+### Create addresses from an xpub
+
+BIP46 paths include hardened account components: `m/84'/coin_type'/0'/2/index`.
+A public key cannot derive those hardened components, so pass an account-level xpub
+for `m/84'/coin_type'/0'`. The library will derive the public BIP46 suffix
+`2/index` from that account xpub.
+
+```python
+from datetime import UTC, datetime
+
+from bip46 import (
+    create_redeemscript,
+    hdkey_derive,
+    hdkey_from_xpub,
+    hdkey_to_pubkey,
+    lockdate_to_derivation_path,
+    redeemscript_address,
+    redeemscript_pubkey,
+)
+
+network = "mainnet"
+lock_date = datetime(2042, 6, 1, tzinfo=UTC)
+lock_path = lockdate_to_derivation_path(lock_date, network=network)
+
+hdkey = hdkey_from_xpub("xpub...")
+redeem_key = hdkey_derive(hdkey, lock_path)
+redeem_pub_key = hdkey_to_pubkey(redeem_key)
+redeem_script = create_redeemscript(lock_date, redeem_pub_key)
+script_pubkey = redeemscript_pubkey(redeem_script)
+script_address = redeemscript_address(script_pubkey, network=network)
+```
+
+The CLI also accepts an account xpub:
+
+```sh
+XPUB="xpub..." uv run bip46 create-timelock 2042 6 mainnet
+```

bip46-1.0.0/README.md

@@ -0,0 +1,74 @@
+# BIP46 - Address Scheme for Timelocked Fidelity Bonds
+
+Python implementation of BIP46: Address Scheme for Timelocked Fidelity Bonds.
+
+## Example
+
+### Create a redeem script from a mnemonic
+
+```python
+from datetime import UTC, datetime
+
+from bip46 import (
+    create_redeemscript,
+    hdkey_derive,
+    hdkey_from_mnemonic,
+    hdkey_to_pubkey,
+    lockdate_to_derivation_path,
+    redeemscript_address,
+    redeemscript_pubkey,
+)
+
+network = "mainnet"
+lock_date = datetime(2042, 6, 1, tzinfo=UTC)
+lock_path = lockdate_to_derivation_path(lock_date, network=network)
+
+hdkey = hdkey_from_mnemonic(
+    "abandon abandon abandon abandon abandon abandon"
+    " abandon abandon abandon abandon abandon about",
+    network=network,
+)
+redeem_key = hdkey_derive(hdkey, lock_path)
+redeem_pub_key = hdkey_to_pubkey(redeem_key)
+redeem_script = create_redeemscript(lock_date, redeem_pub_key)
+script_pubkey = redeemscript_pubkey(redeem_script)
+script_address = redeemscript_address(script_pubkey, network=network)
+```
+
+### Create addresses from an xpub
+
+BIP46 paths include hardened account components: `m/84'/coin_type'/0'/2/index`.
+A public key cannot derive those hardened components, so pass an account-level xpub
+for `m/84'/coin_type'/0'`. The library will derive the public BIP46 suffix
+`2/index` from that account xpub.
+
+```python
+from datetime import UTC, datetime
+
+from bip46 import (
+    create_redeemscript,
+    hdkey_derive,
+    hdkey_from_xpub,
+    hdkey_to_pubkey,
+    lockdate_to_derivation_path,
+    redeemscript_address,
+    redeemscript_pubkey,
+)
+
+network = "mainnet"
+lock_date = datetime(2042, 6, 1, tzinfo=UTC)
+lock_path = lockdate_to_derivation_path(lock_date, network=network)
+
+hdkey = hdkey_from_xpub("xpub...")
+redeem_key = hdkey_derive(hdkey, lock_path)
+redeem_pub_key = hdkey_to_pubkey(redeem_key)
+redeem_script = create_redeemscript(lock_date, redeem_pub_key)
+script_pubkey = redeemscript_pubkey(redeem_script)
+script_address = redeemscript_address(script_pubkey, network=network)
+```
+
+The CLI also accepts an account xpub:
+
+```sh
+XPUB="xpub..." uv run bip46 create-timelock 2042 6 mainnet
+```

bip46-1.0.0/bip46/__init__.py

@@ -0,0 +1,76 @@
+from embit.script import address_to_scriptpubkey
+from embit.transaction import Transaction, TransactionInput, TransactionOutput
+
+from .certificate import (
+    create_certificate_message,
+    recover_from_signature_and_message,
+    sign_certificate_message,
+)
+from .derivation import (
+    index_to_lockdate,
+    lockdate_to_derivation_path,
+    lockdate_to_index,
+    lockindex_to_derivation_path,
+)
+from .exceptions import (
+    Bip46Bech32Error,
+    Bip46IndexError,
+    Bip46PathError,
+    Bip46RecoverPubkeyError,
+    Bip46TimeError,
+)
+from .hdkey import (
+    hdkey_derive,
+    hdkey_from_mnemonic,
+    hdkey_from_seed,
+    hdkey_from_xpub,
+    hdkey_scan,
+    hdkey_scan_all,
+    hdkey_to_pubkey,
+)
+from .script import create_redeemscript, redeemscript_address, redeemscript_pubkey
+
+
+# WIP
+def create_redeem_transaction(
+    prevtxid: str,
+    vout: int,
+    redeemscript: bytes,
+    address: str,
+    fee_sats_vbyte: int = 10,
+    # network: str = DEFAULT_NETWORK,
+) -> str:
+    """Create a redeem transaction for a BIP46 timelock"""
+    tx_size = 100
+    amount = 100000 - fee_sats_vbyte * tx_size
+    receive_address = address_to_scriptpubkey(address)
+    txout = TransactionOutput(amount, receive_address)
+    txin = TransactionInput(prevtxid, vout, redeemscript)
+    tx = Transaction(2, [txin], [txout])
+    return tx.serialize().hex()
+
+
+__all__ = [
+    "Bip46Bech32Error",
+    "Bip46IndexError",
+    "Bip46PathError",
+    "Bip46RecoverPubkeyError",
+    "Bip46TimeError",
+    "create_certificate_message",
+    "create_redeemscript",
+    "hdkey_derive",
+    "hdkey_from_mnemonic",
+    "hdkey_from_seed",
+    "hdkey_from_xpub",
+    "hdkey_scan",
+    "hdkey_scan_all",
+    "hdkey_to_pubkey",
+    "index_to_lockdate",
+    "lockdate_to_derivation_path",
+    "lockdate_to_index",
+    "lockindex_to_derivation_path",
+    "recover_from_signature_and_message",
+    "redeemscript_address",
+    "redeemscript_pubkey",
+    "sign_certificate_message",
+]

bip46-1.0.0/bip46/certificate.py

@@ -0,0 +1,69 @@
+from base64 import b64decode
+from hashlib import sha256
+
+from secp256k1 import PrivateKey, PublicKey
+
+from .exceptions import Bip46RecoverPubkeyError
+
+
+def create_certificate_message(
+    pubkey: str,
+    message: str = "fidelity-bond-cert",
+    expiry: int = 375
+) -> str:
+    """Create a certificate message for a BIP46 timelock"""
+    return f"{message}|{pubkey}|{expiry}"
+
+
+def prepare_certificate_message(message: str) -> bytes:
+    """ message hash for signing """
+    msg = message.encode()
+    prefix = b"\x18Bitcoin Signed Message:\n"
+    data = prefix + bytes([len(msg)]) + msg
+    return sha256(sha256(data).digest()).digest()
+
+
+def sign_certificate_message(private_key: bytes, message: str) -> bytes:
+    """Sign a certificate message for a BIP46 timelock"""
+    message_hash = prepare_certificate_message(message)
+    key = PrivateKey(private_key)
+    raw_sig = key.ecdsa_sign_recoverable(message_hash, raw=True)
+    sig, recid = key.ecdsa_recoverable_serialize(raw_sig)
+    # 31 for p2pkh_address
+    return bytes([recid + 31]) + sig
+
+
+def convert_recoverable_message_signature(sig_base64: str) -> tuple[bytes, int, bool]:
+    """ Convert a recoverable signature to a normal signature """
+    sig = b64decode(sig_base64)
+    if len(sig) != 65:
+        raise Bip46RecoverPubkeyError("Invalid signature length")
+    header = int(sig[0])
+    if header < 27 or header > 42:
+        raise Bip46RecoverPubkeyError(f"Header out of range: {header}")
+    r = sig[1:33]
+    s = sig[33:]
+    compressed = False
+    if(header >= 39): # this is a bech32 signature
+        header -= 12
+        compressed = True
+    # this is a segwit p2sh signature
+    elif header >= 35:
+        header -= 8
+        compressed = True
+    # this is a compressed key signature
+    elif header >= 31:
+        compressed = True
+        header -= 4
+    rec_id = header - 27
+    return r + s, rec_id, compressed
+
+
+def recover_from_signature_and_message(sig_base64: str, message: str) -> bytes:
+    """Recover a pubkey from signature and message"""
+    message_hash = prepare_certificate_message(message)
+    sig, recid, _ = convert_recoverable_message_signature(sig_base64)
+    empty = PublicKey()
+    sig = empty.ecdsa_recoverable_deserialize(sig, recid)
+    pubkey = empty.ecdsa_recover(message_hash, sig, raw=True)
+    return PublicKey(pubkey).serialize()

bip46-1.0.0/bip46/cli.py

@@ -0,0 +1,135 @@
+""" bip46 CLI """
+
+
+import os
+import sys
+from datetime import UTC, datetime
+
+import click
+from embit.bip32 import HDKey
+
+from bip46 import (
+    create_redeemscript,
+    hdkey_derive,
+    hdkey_from_mnemonic,
+    hdkey_from_seed,
+    hdkey_from_xpub,
+    hdkey_scan,
+    hdkey_scan_all,
+    hdkey_to_pubkey,
+    index_to_lockdate,
+    lockdate_to_derivation_path,
+    redeemscript_address,
+    redeemscript_pubkey,
+)
+from bip46.consts import DEFAULT_NETWORK
+
+# disable tracebacks on exceptions
+sys.tracebacklimit = 0
+
+def _check_hdkey(network: str) -> HDKey:
+    """check if the environment is set"""
+    if "XPUB" in os.environ:
+        return hdkey_from_xpub(os.environ["XPUB"])
+    if "SEED" in os.environ:
+        return hdkey_from_seed(os.environ["SEED"].encode(), network)
+    if "MNEMONIC" in os.environ:
+        return hdkey_from_mnemonic(os.environ["MNEMONIC"], network)
+
+    click.echo("please set `XPUB`, `SEED` or `MNEMONIC` environment variable")
+    sys.exit(1)
+
+
+@click.group()
+def command_group():
+    """
+    Python CLI for bip46 timelocks\n
+    set `SEED` or `MNEMONIC` environment variable to set the seed
+    """
+
+
+@click.command()
+@click.argument("network", type=str, default=DEFAULT_NETWORK)
+def scan_all(network: str):
+    """
+    scan for all timelocks
+    """
+    key = _check_hdkey(network)
+    bonds = hdkey_scan_all(key, network)
+    print(f"Found {len(bonds)} timelocked bonds:")
+    for bond in bonds:
+        print(bond.index, bond.txid, bond.address)
+
+
+@click.command()
+@click.argument("index", type=int)
+@click.argument("network", type=str, default=DEFAULT_NETWORK)
+def scan(index: int, network: str):
+    """
+    scan for a timelock at a specific index
+    """
+    key = _check_hdkey(network)
+    bonds = hdkey_scan(index, key, network)
+    print(f"Found {len(bonds)} timelocked bonds")
+    for bond in bonds:
+        print(bond.index, bond.txid, bond.address)
+
+
+@click.command()
+@click.argument("year", type=int)
+@click.argument("month", type=int)
+@click.argument("network", type=str, default=DEFAULT_NETWORK)
+def create_timelock(year: int, month: int, network: str):
+    """
+    create a timelock address
+    """
+    key = _check_hdkey(network)
+    lock_date = datetime(year, month, 1, tzinfo=UTC)
+    lock_path = lockdate_to_derivation_path(lock_date, network)
+    redeem_child = hdkey_derive(key, lock_path)
+    redeem_pub_key = hdkey_to_pubkey(redeem_child)
+    redeem_script = create_redeemscript(lock_date, redeem_pub_key)
+    script_pubkey = redeemscript_pubkey(redeem_script)
+    script_address = redeemscript_address(script_pubkey, network=network)
+
+    print(f"network: {network}")
+    print(f"lock_date: {lock_date.isoformat()}")
+    print(f"lock_path: {lock_path}")
+    print(f"script address: {script_address}")
+
+
+@click.command()
+@click.argument("year", type=int)
+@click.argument("month", type=int)
+@click.argument("network", type=str, default=DEFAULT_NETWORK)
+def get_derivation_path(year: int, month: int, network: str):
+    """
+    create a timelock address
+    """
+    lock_date = datetime(year, month, 1, tzinfo=UTC)
+    lock_path = lockdate_to_derivation_path(lock_date, network)
+    print(lock_path)
+
+
+@click.command()
+@click.argument("index", type=int)
+def get_lockdate(index: int):
+    """
+    get the lock date from an index
+    """
+    lock_path = index_to_lockdate(index)
+    print(lock_path.isoformat())
+
+
+def main():
+    """main function"""
+    command_group.add_command(create_timelock)
+    command_group.add_command(scan)
+    command_group.add_command(scan_all)
+    command_group.add_command(get_derivation_path)
+    command_group.add_command(get_lockdate)
+    command_group()
+
+
+if __name__ == "__main__":
+    main()

bip46-1.0.0/bip46/consts.py

@@ -0,0 +1,25 @@
+ELECTRS_SERVER = "https://testnet-electrs.b1tco1n.org"
+MAX_INDEX = 959
+DEFAULT_NETWORK = "testnet"
+NETWORKS = {
+    "mainnet": {
+        "bech32": "bc",
+        "xprv": b"\x04\x88\xad\xe4",
+        "bip32": 0,  # coin type for bip32 derivation
+    },
+    "testnet": {
+        "bech32": "tb",
+        "xprv": b"\x04\x35\x83\x94",
+        "bip32": 1,
+    },
+    "regtest": {
+        "bech32": "bcrt",
+        "xprv": b"\x04\x35\x83\x94",
+        "bip32": 1,
+    },
+    "signet": {
+        "bech32": "tb",
+        "xprv": b"\x04\x35\x83\x94",
+        "bip32": 1,
+    },
+}

bip46-1.0.0/bip46/derivation.py

@@ -0,0 +1,37 @@
+from datetime import UTC, datetime
+
+from .consts import DEFAULT_NETWORK, NETWORKS
+from .exceptions import Bip46IndexError, Bip46TimeError
+
+
+def index_to_lockdate(index: int) -> datetime:
+    """Convert a BIP46 timelock index to a datetime"""
+    if index < 0 or index > 959:
+        raise Bip46IndexError("index must be between 0 and 959")
+    year = 2020 + index // 12
+    month = 1 + index % 12
+    day = 1
+    return datetime(year, month, day, tzinfo=UTC)
+
+
+def lockdate_to_index(lock_date: datetime) -> int:
+    """Convert a datetime to a BIP46 timelock index"""
+    if lock_date.year < 2020:
+        raise Bip46TimeError("lock_date must be after 2020")
+    if lock_date.year > 2099:
+        raise Bip46TimeError("lock_date must be before 2100")
+    return (lock_date.year - 2020) * 12 + lock_date.month - 1
+
+
+def lockdate_to_derivation_path(
+    lock_date: datetime, network: str = DEFAULT_NETWORK
+) -> str:
+    """Derive the path for a BIP46 timelock from a date"""
+    i = lockdate_to_index(lock_date)
+    return lockindex_to_derivation_path(i, network)
+
+
+def lockindex_to_derivation_path(index: int, network: str = DEFAULT_NETWORK) -> str:
+    """Derive the path for a BIP46 timelock from an index"""
+    bip32 = NETWORKS[network]["bip32"]
+    return f"m/84'/{bip32}'/0'/2/{index}"

bip46-1.0.0/bip46/electrs.py

@@ -0,0 +1,38 @@
+
+import httpx
+
+from .consts import ELECTRS_SERVER
+
+
+def request(url: str) -> dict:
+    with httpx.Client() as client:
+        resp = client.get(url)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def get_tx(txid: str, electrs_server: str = ELECTRS_SERVER) -> dict:
+    """Get a transaction from a block explorer"""
+    url = f"{electrs_server}/tx/{txid}"
+    return request(url)
+
+
+def get_txs_from_address(address: str, electrs_server: str = ELECTRS_SERVER) -> dict:
+    """Get a transaction from a block explorer"""
+    url = f"{electrs_server}/address/{address}/txs"
+    return request(url)
+
+
+def get_vout_from_tx(tx: dict, address: str) -> tuple[str, int, int] | None:
+    for i, out in enumerate(tx["vout"]):
+        if out["scriptpubkey_address"] == address:
+            return tx["txid"], i, out["value"]
+    return None
+
+
+def get_vout_from_txs(txs: dict, address: str) -> tuple[str, int, int] | None:
+    for tx in txs:
+        vout = get_vout_from_tx(tx, address)
+        if vout:
+            return vout
+    return None