wallet: Privatize Core descriptor records

The package-level core_descriptors adapter exposes import-record construction that runtime callers no longer need. Bitcoin Core already owns public derivation, while private descriptor construction is only an implementation detail of the Core adapter.

Remove the unused public-deriver protocol and branch, keep the record builder private, and make installed/public-API checks enforce that boundary. Internal tests and verification tools continue to exercise the same fixed descriptor templates and arbitrary account handling.

Fixes #63

Author: BenWestgate

docs/developer/api.md

@@ -100,7 +100,7 @@ generic parse-length failure.
   hidden state.
 
 Private Python names are convention rather than access control. The supported
-surface is the 25-name package `__all__`; direct use of private helpers is
+surface is the 23-name package `__all__`; direct use of private helpers is
 unsupported but remains in the review scope.
 
 ### Size budget
@@ -580,27 +580,24 @@ Public wallet operations accept only a validated `MasterSeed`. `wallet.py` is
 stateless and never accepts shares, Core Lightning secrets, BIP39 migration
 artifacts, or raw bytes.
 
-The public adapter has two functions:
-
-- `master_xprv(secret, testnet=False)` returns the BIP32 root extended private
-  key.
-- `core_descriptors(...)` returns fixed BIP44, BIP49, BIP84, and BIP86 Bitcoin
-  Core `importdescriptors` records. Private records use stdlib-only root xprv
-  serialization; public records require an explicit wallet integration and the
-  Core wallet whose imported root key will perform hardened derivation.
+The supported package surface exposes one wallet primitive:
+`master_xprv(secret, testnet=False)`, which returns the BIP32 root extended
+private key. Bitcoin Core descriptor-record construction is an internal
+test/reference detail rather than a supported package API.
 
 No installed Python dependency performs secp256k1 operations. The private
 Bitcoin Core adapter gives Core the root xprv over stdin and asks Core to
-create the four standard account-0 descriptor types. Public descriptor
-derivation remains available through the explicit integration API.
+create the four standard account-0 descriptor types. Descriptor normalization
+and public derivation stay behind that private Core boundary.
 
 Public descriptors contain account xpubs. Private descriptors intentionally
 follow Bitcoin Core's root-key form: they contain the root xprv followed by the
 complete derivation path. They therefore grant authority over the entire root,
 not only the selected account. The CLI warns before printing them.
 
-Account, private/public mode, network serialization, and timestamp are explicit
-API inputs. The `ms32 wallet` CLI takes `--account 0` and `--timestamp`; the
+Account and timestamp remain explicit at the Core boundary, while network
+serialization is explicit for `master_xprv`. The `ms32 wallet` CLI takes
+`--account 0` and `--timestamp`; the
 selected Bitcoin Core chain is authoritative and there is no wallet
 `--testnet` flag. `ms32 xprv --testnet` remains explicit because it directly
 selects xprv versus tprv serialization. The timestamp defaults to `0` so

src/codex32/__init__.py

@@ -27,7 +27,7 @@
 from .profiles.bip39 import Bip39Secret
 from .profiles.cl32 import CoreLightningSecret
 from .profiles.ms32 import MasterSeed
-from .wallet import core_descriptors, master_xprv
+from .wallet import master_xprv
 
 __all__ = [
     "Bip39Secret",
@@ -45,7 +45,6 @@
     "Secret",
     "Share",
     "WorksheetCorrection",
-    "core_descriptors",
     "correct",
     "correct_worksheet_residue",
     "derive_share",

src/codex32/wallet.py

@@ -1,6 +1,6 @@
 """Bitcoin wallet interoperability for validated master seeds."""
 
-from typing import Literal, Protocol
+from typing import Literal
 
 from codex32._bip32 import _master_xprv_from_seed
 from codex32.bech32 import _u5_to_chars
@@ -18,21 +18,6 @@
 )
 
 
-class WalletPublicDeriver(Protocol):
-    """Out-of-process provider for EC-dependent BIP32 public derivation."""
-
-    def fingerprint(self, secret: MasterSeed) -> bytes: ...
-
-    def public_descriptors(
-        self,
-        secret: MasterSeed,
-        *,
-        wallet: str,
-        account: int = 0,
-        timestamp: int | Literal["now"] = 0,
-    ) -> tuple[dict[str, object], ...]: ...
-
-
 def _master(secret: MasterSeed) -> MasterSeed:
     if not isinstance(secret, MasterSeed):
         raise TypeError("wallet operations accept only MasterSeed")
@@ -86,42 +71,22 @@ def master_xprv(secret: MasterSeed, *, testnet: bool = False) -> str:
     return _master_xprv_from_seed(_master(secret).seed_bytes, testnet=testnet)
 
 
-def core_descriptors(
+def _core_descriptors(
     secret: MasterSeed,
     *,
-    integration: WalletPublicDeriver | None = None,
-    wallet: str | None = None,
     account: int = 0,
     testnet: bool = False,
-    private: bool = False,
     timestamp: int | Literal["now"] = 0,
 ) -> tuple[dict[str, object], ...]:
-    """Return fixed Bitcoin Core records.
-
-    Private records are constructed with stdlib-only root xprv serialization.
-    Public records require an explicit out-of-process integration provider.
-    """
+    """Return fixed private descriptor records for verification tooling."""
     _master(secret)
     account = _account(account)
     if not isinstance(testnet, bool):
         raise TypeError("testnet must be bool")
-    if not isinstance(private, bool):
-        raise TypeError("private must be bool")
     if timestamp != "now" and (
         isinstance(timestamp, bool) or not isinstance(timestamp, int) or timestamp < 0
     ):
         raise ValueError("timestamp must be a nonnegative integer or 'now'")
-    if not private:
-        if integration is None:
-            raise TypeError("public descriptors require a wallet integration")
-        if wallet is None:
-            raise TypeError("public descriptors require a Bitcoin Core wallet name")
-        return integration.public_descriptors(
-            secret,
-            wallet=wallet,
-            account=account,
-            timestamp=timestamp,
-        )
     coin_type = int(testnet)
     xprv = master_xprv(secret, testnet=testnet)
     keys = []

tests/test_public_api.py

@@ -59,6 +59,11 @@ def test_checksum_completion_is_not_public_api() -> None:
     assert not hasattr(codex32, "complete_checksum")
 
 
+def test_bitcoin_core_descriptor_records_are_not_public_api() -> None:
+    assert "core_descriptors" not in codex32.__all__
+    assert not hasattr(codex32, "core_descriptors")
+
+
 def test_share_has_symbols_but_no_byte_or_padding_api() -> None:
     share = parse_codex32(VECTOR_2["share_A"])
     assert isinstance(share, Share)

tests/test_wallet.py

@@ -4,57 +4,8 @@
 from data.bip93_vectors import VECTOR_1, VECTOR_2, VECTOR_3, VECTOR_4, VECTOR_5
 from data.sharing_vectors import SHARING_VECTORS
 
-from codex32 import (
-    MasterSeed,
-    core_descriptors,
-    master_xprv,
-    parse_codex32,
-)
-from codex32.wallet import _with_checksum
-
-_MAIN_DESCRIPTORS = (
-    (
-        "pkh([3f3521a6/44h/0h/0h]"
-        "xpub6CeZ5XxHp6rXSwi2GCi7UT25rswWQtoPvj36MbzRBr3QEoEmBFNGgnMy329ZMk"
-        "fjRKBZHtKKpYfpkrPWohTjHZZn7y1NR9EHnojaGLKdMAR/<0;1>/*)#smv8ra2a"
-    ),
-    (
-        "sh(wpkh([3f3521a6/49h/0h/0h]"
-        "xpub6D9YUddFXuNKQvNrT9RQh8ueiTvHwF3RzdgU6uTEri73WTnBpKaDCGhTUiPBTy"
-        "VJxtR5u2atDmCHE7tw369ahXddCNqJBxFpseud3j7pjX8/<0;1>/*))#gylcnnd3"
-    ),
-    (
-        "wpkh([3f3521a6/84h/0h/0h]"
-        "xpub6CNhWVRpA49Bz3LSaBibGqfBV4qa5NH1CStbQfsxWKScwrws5jioMunWKj2uM2"
-        "rrfdJSroNuJBNDUmmdYXQw5LwVro39pH5nqEgAqrzTPyc/<0;1>/*)#zy06y40v"
-    ),
-    (
-        "tr([3f3521a6/86h/0h/0h]"
-        "xpub6C5pT77VWNhWvrB3TqSEbpm7NCpMYEzbJreYbB68RCUoAMkT7rdhafinmdKL4M5"
-        "275TyDqNAWCnssYnDNaPoXMiAg3sWvCgAiYqY8dHk1k4/<0;1>/*)#r8r04qrm"
-    ),
-)
-
-
-class _FakePublicDeriver:
-    def fingerprint(self, secret: MasterSeed) -> bytes:
-        del secret
-        return bytes.fromhex("3f3521a6")
-
-    def public_descriptors(
-        self,
-        secret: MasterSeed,
-        *,
-        wallet: str,
-        account: int = 0,
-        timestamp: int | str = 0,
-    ) -> tuple[dict[str, object], ...]:
-        del secret
-        if wallet != "signer":
-            raise AssertionError("unexpected wallet")
-        if account != 0:
-            raise AssertionError("unexpected frozen descriptor request")
-        return tuple({"desc": desc, "active": True, "timestamp": timestamp} for desc in _MAIN_DESCRIPTORS)
+from codex32 import MasterSeed, master_xprv, parse_codex32
+from codex32.wallet import _core_descriptors, _with_checksum
 
 
 def _master() -> MasterSeed:
@@ -71,29 +22,8 @@ def test_master_xprv_matches_bip93_vectors(vector: dict[str, str]) -> None:
     assert master_xprv(secret) == vector["xprv"]
 
 
-def test_public_core_descriptors_are_fixed_and_private_free() -> None:
-    records = core_descriptors(_master(), integration=_FakePublicDeriver(), wallet="signer")
-
-    assert len(records) == 4
-    assert [record["desc"].split("(", 1)[0] for record in records] == [
-        "pkh",
-        "sh",
-        "wpkh",
-        "tr",
-    ]
-    assert all(record["active"] is True for record in records)
-    assert all(record["timestamp"] == 0 for record in records)
-    assert all("xpub" in str(record["desc"]) for record in records)
-    assert all("xprv" not in str(record["desc"]) for record in records)
-    assert records[0]["desc"] == (
-        "pkh([3f3521a6/44h/0h/0h]"
-        "xpub6CeZ5XxHp6rXSwi2GCi7UT25rswWQtoPvj36MbzRBr3QEoEmBFNGgnMy329ZMk"
-        "fjRKBZHtKKpYfpkrPWohTjHZZn7y1NR9EHnojaGLKdMAR/<0;1>/*)#smv8ra2a"
-    )
-
-
 def test_private_core_descriptors_use_root_xprv_and_explicit_inputs() -> None:
-    records = core_descriptors(_master(), account=3, testnet=True, private=True, timestamp=123)
+    records = _core_descriptors(_master(), account=3, testnet=True, timestamp=123)
 
     assert all(record["timestamp"] == 123 for record in records)
     for purpose, record in zip((44, 49, 84, 86), records, strict=True):
@@ -103,12 +33,7 @@ def test_private_core_descriptors_use_root_xprv_and_explicit_inputs() -> None:
 
 
 def test_core_descriptors_accept_bitcoin_core_now_timestamp() -> None:
-    assert all(
-        record["timestamp"] == "now"
-        for record in core_descriptors(
-            _master(), timestamp="now", integration=_FakePublicDeriver(), wallet="signer"
-        )
-    )
+    assert all(record["timestamp"] == "now" for record in _core_descriptors(_master(), timestamp="now"))
 
 
 def test_descriptor_checksum_matches_published_example() -> None:
@@ -125,18 +50,18 @@ def test_descriptor_checksum_matches_published_example() -> None:
     ),
 )
 def test_wallet_boundary_rejects_every_non_master_seed(invalid: object) -> None:
-    for function in (master_xprv, core_descriptors):
+    for function in (master_xprv, _core_descriptors):
         with pytest.raises(TypeError, match="only MasterSeed"):
             function(invalid)  # type: ignore[arg-type]
 
 
 @pytest.mark.parametrize("account", (-1, 2**31, True, "0"))
 def test_account_is_explicitly_bounded(account: object) -> None:
     with pytest.raises((TypeError, ValueError)):
-        core_descriptors(_master(), account=account, integration=_FakePublicDeriver(), wallet="signer")  # type: ignore[arg-type]
+        _core_descriptors(_master(), account=account)  # type: ignore[arg-type]
 
 
 @pytest.mark.parametrize("timestamp", (-1, True, "yesterday"))
 def test_timestamp_is_a_supported_core_value(timestamp: object) -> None:
     with pytest.raises((TypeError, ValueError)):
-        core_descriptors(_master(), timestamp=timestamp)  # type: ignore[arg-type]
+        _core_descriptors(_master(), timestamp=timestamp)  # type: ignore[arg-type]

tools/bitcoin_core_regtest.py

@@ -18,7 +18,7 @@
 from codex32._bitcoin_core import BitcoinCore
 from codex32.bip93 import parse_codex32
 from codex32.profiles.ms32 import MasterSeed
-from codex32.wallet import core_descriptors
+from codex32.wallet import _core_descriptors
 
 # Frozen public BIP93 vector material; it has never controlled a funded wallet.
 _SEED = "ms10testsxxxxxxxxxxxxxxxxxxxxxxxxxx4nzvca9cmczlw"
@@ -225,8 +225,8 @@ def rpc(*rpc_arguments: str, wallet: str | None = None, stdin: str | None = None
             if rpc("gettransaction", spend, wallet="restore")["confirmations"] < 1:
                 raise RuntimeError("recovered wallet did not sign and broadcast")
 
-            main_private = core_descriptors(secret, private=True, timestamp=0)
-            test_private = core_descriptors(secret, testnet=True, private=True, timestamp=0)
+            main_private = _core_descriptors(secret, timestamp=0)
+            test_private = _core_descriptors(secret, testnet=True, timestamp=0)
             if "xprv" not in json.dumps(main_private) or "tprv" not in json.dumps(test_private):
                 raise RuntimeError("mainnet/test-network root serialization was not separated")
 

tools/verify_installed_wheel.py

@@ -5,12 +5,12 @@
 import importlib.util
 import sys
 
+import codex32
 from codex32 import (
     CorrectionContext,
     CreationCeremony,
     MasterSeed,
     Profile,
-    core_descriptors,
     correct,
     derive_share,
     master_xprv,
@@ -45,9 +45,8 @@ def main() -> None:
     secret = parse_codex32(_SECRET)
     assert isinstance(secret, MasterSeed)
     assert master_xprv(secret) == _XPRV
-    private = core_descriptors(secret, private=True)
-    assert len(private) == 4
-    assert all("xprv" in record["desc"] for record in private)
+    assert "core_descriptors" not in codex32.__all__
+    assert not hasattr(codex32, "core_descriptors")
     assert "bip32" not in sys.modules
     assert "coincurve" not in sys.modules