ourdash 0.1.0__py3-none-any.whl

ourdash/__init__.py

@@ -0,0 +1,65 @@
+"""ourdash — Modern Python SDK for Dash (Dash crypto from dash.org, not Plotly Dash).
+
+Top-level re-exports of the stable v0.1 surface (reads + offline payments +
+proof verdicts). Import here for the common case::
+
+    from ourdash import DashRPC, Wallet, validate_address
+
+Deeper models and facades stay importable from their owning modules
+(``ourdash.core.*``, ``ourdash.platform.*``).
+"""
+
+from ourdash.core.addresses import AddressInfo as AddressInfo
+from ourdash.core.addresses import validate_address as validate_address
+from ourdash.core.rpc import DashRPC as DashRPC
+from ourdash.core.rpc import DashRPCConfig as DashRPCConfig
+from ourdash.core.transactions import ConfirmationStatus as ConfirmationStatus
+from ourdash.core.transactions import SignedTx as SignedTx
+from ourdash.core.transactions import UnsignedTx as UnsignedTx
+from ourdash.core.wallet import Wallet as Wallet
+from ourdash.errors import AddressError as AddressError
+from ourdash.errors import ConfigError as ConfigError
+from ourdash.errors import DAPIError as DAPIError
+from ourdash.errors import OurdashError as OurdashError
+from ourdash.errors import PaymentError as PaymentError
+from ourdash.errors import ProofError as ProofError
+from ourdash.errors import ProofUnavailableError as ProofUnavailableError
+from ourdash.errors import RpcAuthError as RpcAuthError
+from ourdash.errors import RpcConnectionError as RpcConnectionError
+from ourdash.errors import RpcError as RpcError
+from ourdash.errors import RpcTimeoutError as RpcTimeoutError
+from ourdash.errors import WalletError as WalletError
+from ourdash.platform.dapi import DAPIClient as DAPIClient
+from ourdash.platform.dapi import DAPIConfig as DAPIConfig
+from ourdash.platform.models import ProofVerdict as ProofVerdict
+from ourdash.platform.models import ProvenResult as ProvenResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "DashRPC",
+    "DashRPCConfig",
+    "DAPIClient",
+    "DAPIConfig",
+    "AddressInfo",
+    "validate_address",
+    "Wallet",
+    "UnsignedTx",
+    "SignedTx",
+    "ConfirmationStatus",
+    "ProofVerdict",
+    "ProvenResult",
+    "OurdashError",
+    "RpcError",
+    "RpcAuthError",
+    "RpcConnectionError",
+    "RpcTimeoutError",
+    "ConfigError",
+    "AddressError",
+    "WalletError",
+    "PaymentError",
+    "DAPIError",
+    "ProofError",
+    "ProofUnavailableError",
+]

ourdash/core/__init__.py

@@ -0,0 +1,8 @@
+"""Dash Core modules: RPC client, addresses, transactions, wallet, network.
+
+Research entrypoints:
+- dashd JSON-RPC via `dash-cli help` / docs.dash.org Core API
+- X11 + ChainLocks + InstantSend specifics vs Bitcoin Core fork
+"""
+
+from __future__ import annotations

ourdash/core/addresses.py

@@ -0,0 +1,126 @@
+"""Dash address validation (Dash crypto from dash.org — not Plotly Dash).
+
+Pure-offline Base58Check validation reporting validity, network, and kind
+before any funds move. Version bytes are fixed per Dash Core v23.1.8
+``src/chainparams.cpp`` ``base58Prefixes[PUBKEY_ADDRESS]`` /
+``[SCRIPT_ADDRESS]``: mainnet P2PKH ``0x4c`` (76, addresses start with
+``'X'``), mainnet P2SH ``0x10`` (16, start with ``'7'``), testnet P2PKH
+``0x8c`` (140, start with ``'y'``), testnet P2SH ``0x13`` (19, start with
+``'8'``/``'9'``). Regtest and devnet reuse the testnet prefixes.
+
+Only P2PKH/P2SH Base58Check is handled here (v0.1 scope). Checksum rule:
+4-byte double-SHA-256 checksum over a 21-byte payload (1 version byte +
+20-byte hash).
+"""
+
+from __future__ import annotations
+
+from typing import Literal, cast
+
+from pydantic import BaseModel
+
+from ourdash.errors import AddressError
+from ourdash.redact import redact
+from ourdash.utils import b58check_decode, b58check_encode
+
+Network = Literal["mainnet", "testnet", "regtest", "devnet"]
+AddressKind = Literal["p2pkh", "p2sh"]
+AddressReason = Literal[
+    "ok", "bad_charset", "bad_length", "bad_checksum", "wrong_network", "unknown_prefix"
+]
+
+_NETWORKS: tuple[str, ...] = ("mainnet", "testnet", "regtest", "devnet")
+
+# Version byte -> (family, kind). regtest/devnet reuse the testnet prefixes.
+_VERSION_TABLE: dict[int, tuple[str, AddressKind]] = {
+    0x4C: ("mainnet", "p2pkh"),
+    0x10: ("mainnet", "p2sh"),
+    0x8C: ("testnet", "p2pkh"),
+    0x13: ("testnet", "p2sh"),
+}
+
+# Network -> P2PKH version byte (single source of version-byte truth).
+_P2PKH_VERSION: dict[str, int] = {
+    "mainnet": 0x4C,
+    "testnet": 0x8C,
+    "regtest": 0x8C,
+    "devnet": 0x8C,
+}
+
+MAINNET_P2PKH_VERSION = 0x4C
+MAINNET_P2SH_VERSION = 0x10
+TESTNET_P2PKH_VERSION = 0x8C
+TESTNET_P2SH_VERSION = 0x13
+
+_PAYLOAD_LEN = 21  # 1 version byte + 20-byte hash
+
+
+class AddressInfo(BaseModel):
+    """Validation verdict for one Dash address input."""
+
+    valid: bool
+    network: Network | None = None
+    kind: AddressKind | None = None
+    reason: AddressReason = "ok"
+
+
+def _family_of(network: str) -> str:
+    """Map a network to its prefix family (``mainnet`` vs ``testnet``)."""
+    if network == "mainnet":
+        return "mainnet"
+    return "testnet"  # testnet, regtest, devnet share prefixes
+
+
+def validate_address(addr: str, expected_network: str | None = None) -> AddressInfo:
+    """Validate a Dash address, reporting network and kind.
+
+    Without ``expected_network``, a testnet-family prefix reports the
+    ``testnet`` family label. With ``expected_network="regtest"`` (or
+    ``"devnet"``), the prefix is validated against that network and the
+    specific network is reported. A prefix from the other family returns
+    ``valid=False, reason="wrong_network"`` — never raised.
+
+    Raises :class:`ourdash.errors.AddressError` only for non-string or
+    empty input (and for an unknown ``expected_network`` value).
+    """
+    if not isinstance(addr, str) or not addr:
+        raise AddressError(f"invalid address input {redact(addr)!r}")
+    if expected_network is not None and expected_network not in _NETWORKS:
+        raise AddressError(f"unknown network {redact(expected_network)!r}")
+
+    try:
+        payload = b58check_decode(addr)
+    except AddressError as exc:
+        message = str(exc)
+        if "bad charset" in message:
+            return AddressInfo(valid=False, reason="bad_charset")
+        if "bad length" in message:
+            return AddressInfo(valid=False, reason="bad_length")
+        return AddressInfo(valid=False, reason="bad_checksum")
+    if len(payload) != _PAYLOAD_LEN:
+        return AddressInfo(valid=False, reason="bad_length")
+
+    entry = _VERSION_TABLE.get(payload[0])
+    if entry is None:
+        return AddressInfo(valid=False, reason="unknown_prefix")
+    family, kind = entry
+
+    if expected_network is None:
+        return AddressInfo(valid=True, network=cast(Network, family), kind=kind)
+    if _family_of(expected_network) != family:
+        return AddressInfo(
+            valid=False,
+            network=cast(Network, family),
+            kind=kind,
+            reason="wrong_network",
+        )
+    return AddressInfo(valid=True, network=cast(Network, expected_network), kind=kind)
+
+
+def derive_p2pkh(pubkey_hash20: bytes, network: str = "mainnet") -> str:
+    """Build the P2PKH address for a 20-byte hash on ``network``."""
+    if not isinstance(pubkey_hash20, bytes) or len(pubkey_hash20) != 20:
+        raise AddressError("pubkey hash must be exactly 20 bytes")
+    if network not in _P2PKH_VERSION:
+        raise AddressError(f"unknown network {redact(network)!r}")
+    return b58check_encode(bytes([_P2PKH_VERSION[network]]) + pubkey_hash20)

ourdash/core/chain.py

@@ -0,0 +1,303 @@
+"""Typed Core read facade: chain info, blocks, transactions, balances, addresses.
+
+Dash here is Dash crypto from dash.org — not Plotly Dash.
+
+One typed read surface over the developer's own node. Every function takes a
+:class:`ourdash.core.rpc.DashRPC` and returns a pydantic model with a
+:meth:`to_dict` plain-object view (stdlib types only) for analysts' own
+tooling. Node error objects propagate as the Phase 1 taxonomy
+(:class:`ourdash.errors.RpcError` with the node code preserved); malformed
+node payloads raise :class:`ourdash.errors.RpcError` chained from the
+validation failure. Unknown extras in node responses are ignored; the
+documented fields below are required.
+
+Wallet selection: every wallet-aware function (``get_transaction``,
+``get_balance``, ``get_new_address``) accepts ``wallet: str | None``. When
+set, the call runs against a client bound to that wallet's ``-rpcwallet``
+endpoint, built internally from the passed client's config — the caller's
+client is never mutated. An unknown wallet surfaces the node's error as
+:class:`ourdash.errors.RpcError` with its code preserved.
+
+Method allowlist (Dash Core v23.1.8 ``dash-cli help``, retrieved 2026-09-05):
+``getblockchaininfo``, ``getblockhash``, ``getblock``, ``getrawtransaction``,
+``gettransaction``, ``getbalances``, ``getbalance``,
+``getunconfirmedbalance``, ``getnewaddress``, ``getchaintips``,
+``masternode list``, ``getbestchainlock``, ``getblockcount``. No
+``dashd``/``dash-cli`` binary exists in this environment, so the allowlist is
+pinned from the v23.1.8 sources/docs rather than a live ``dash-cli help``
+dump; only the methods above are called, and only the documented fields are
+asserted.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import replace
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from ourdash.core.addresses import validate_address
+from ourdash.core.rpc import DashRPC
+from ourdash.errors import RpcError
+from ourdash.redact import RedactionFilter
+
+logger = logging.getLogger(__name__)
+logger.addFilter(RedactionFilter())
+
+
+def _bound(rpc: DashRPC, wallet: str | None) -> DashRPC:
+    """Return ``rpc`` or a copy bound to ``wallet``'s ``-rpcwallet`` endpoint."""
+    if wallet is None:
+        return rpc
+    return DashRPC(replace(rpc.config, wallet=wallet))
+
+
+def _mapping(value: Any, method: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise RpcError(f"{method} returned a malformed response")
+    return value
+
+
+class BlockchainInfo(BaseModel):
+    """Chain state: name, height, sync progress, difficulty."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    chain: str
+    blocks: int
+    headers: int
+    bestblockhash: str
+    difficulty: float
+    verificationprogress: float
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain-object view (stdlib types only)."""
+        return self.model_dump(mode="python")
+
+
+class BlockInfo(BaseModel):
+    """One block: hash, height, time, transaction list/count, ChainLock flag."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    hash: str
+    height: int
+    time: int
+    txids: list[str]
+    tx_count: int
+    chainlock: bool | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain-object view (stdlib types only)."""
+        return self.model_dump(mode="python")
+
+
+class TransactionInfo(BaseModel):
+    """One transaction: confirmations, amounts, InstantSend flag."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    txid: str
+    confirmations: int = 0
+    amount: float | None = None
+    fee: float | None = None
+    instantlock: bool = False
+    blockhash: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain-object view (stdlib types only)."""
+        return self.model_dump(mode="python")
+
+
+class Balance(BaseModel):
+    """Wallet balance split: confirmed vs unconfirmed (plus immature mining)."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    confirmed: float
+    unconfirmed: float = 0.0
+    immature: float | None = None
+    wallet: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain-object view (stdlib types only)."""
+        return self.model_dump(mode="python")
+
+
+def get_blockchain_info(rpc: DashRPC) -> BlockchainInfo:
+    """Read chain state (height, chain name, progress, difficulty)."""
+    data = _mapping(rpc.call("getblockchaininfo"), "getblockchaininfo")
+    try:
+        return BlockchainInfo(
+            chain=data["chain"],
+            blocks=int(data["blocks"]),
+            headers=int(data["headers"]),
+            bestblockhash=data["bestblockhash"],
+            difficulty=float(data["difficulty"]),
+            verificationprogress=float(data["verificationprogress"]),
+        )
+    except (KeyError, TypeError, ValueError, ValidationError) as exc:
+        raise RpcError(f"getblockchaininfo returned a malformed response: {exc}") from exc
+
+
+def get_block(rpc: DashRPC, hash_or_height: str | int, verbosity: int = 1) -> BlockInfo:
+    """Read one block by hash (64-hex) or by height (int or decimal string).
+
+    Heights resolve via ``getblockhash`` first. ``verbosity`` 1 returns txids;
+    2 returns full tx objects (reduced to their txids here). Verbosity 0
+    (raw hex) is refused pre-network — use verbosity 1 or 2.
+    """
+    if isinstance(hash_or_height, bool):
+        raise RpcError("block selector must be a hash string or a height int")
+    if verbosity not in (1, 2):
+        raise RpcError("get_block needs verbosity 1 or 2 (0 returns raw hex)")
+    block_hash: str
+    if isinstance(hash_or_height, int):
+        resolved: Any = rpc.call("getblockhash", hash_or_height)
+        if not isinstance(resolved, str) or not resolved:
+            raise RpcError("getblockhash returned a malformed response")
+        block_hash = resolved
+    elif isinstance(hash_or_height, str) and hash_or_height.isdigit():
+        # Decimal-string height (a 64-char all-digit hash is ~impossible).
+        resolved = rpc.call("getblockhash", int(hash_or_height))
+        if not isinstance(resolved, str) or not resolved:
+            raise RpcError("getblockhash returned a malformed response")
+        block_hash = resolved
+    elif isinstance(hash_or_height, str) and hash_or_height:
+        block_hash = hash_or_height
+    else:
+        raise RpcError("block selector must be a hash string or a height int")
+    data = _mapping(rpc.call("getblock", block_hash, verbosity), "getblock")
+    raw_tx = data.get("tx", [])
+    if not isinstance(raw_tx, list):
+        raise RpcError("getblock returned a malformed response")
+    txids: list[str] = []
+    for entry in raw_tx:
+        txid: Any = entry.get("txid", entry.get("hash")) if isinstance(entry, Mapping) else entry
+        if not isinstance(txid, str) or not txid:
+            raise RpcError("getblock returned a malformed response")
+        txids.append(txid)
+    raw_count = data.get("nTx")
+    tx_count = int(raw_count) if isinstance(raw_count, int) else len(txids)
+    lock_raw = data.get("chainlock", data.get("chainLock"))
+    chainlock = bool(lock_raw) if lock_raw is not None else None
+    try:
+        return BlockInfo(
+            hash=data["hash"],
+            height=int(data["height"]),
+            time=int(data["time"]),
+            txids=txids,
+            tx_count=tx_count,
+            chainlock=chainlock,
+        )
+    except (KeyError, TypeError, ValueError, ValidationError) as exc:
+        raise RpcError(f"getblock returned a malformed response: {exc}") from exc
+
+
+def _transaction_from_mapping(txid: str, data: Mapping[str, Any]) -> TransactionInfo:
+    """Build a :class:`TransactionInfo` from either verbose shape.
+
+    Accepts the ``getrawtransaction``-verbose shape and the wallet
+    ``gettransaction`` shape (``instantlock`` / ``instantlock_internal``).
+    """
+    raw_confirmations = data.get("confirmations", 0)
+    raw_amount = data.get("amount")
+    raw_fee = data.get("fee")
+    raw_blockhash = data.get("blockhash")
+    try:
+        return TransactionInfo(
+            txid=str(data.get("txid", txid)),
+            confirmations=int(raw_confirmations),
+            amount=float(raw_amount) if raw_amount is not None else None,
+            fee=float(raw_fee) if raw_fee is not None else None,
+            instantlock=bool(data.get("instantlock", False))
+            or bool(data.get("instantlock_internal", False)),
+            blockhash=str(raw_blockhash) if raw_blockhash is not None else None,
+        )
+    except (TypeError, ValueError, ValidationError) as exc:
+        raise RpcError(f"transaction payload is malformed: {exc}") from exc
+
+
+def get_transaction(rpc: DashRPC, txid: str, wallet: str | None = None) -> TransactionInfo:
+    """Read one transaction (amounts, fee, confirmations, InstantSend flag).
+
+    With ``wallet`` set, reads the wallet ``gettransaction`` view on that
+    wallet's endpoint. Without ``wallet``, tries verbose
+    ``getrawtransaction`` (needs txindex for confirmed txs) and falls back to
+    the default-wallet ``gettransaction`` view.
+    """
+    if not isinstance(txid, str) or len(txid) != 64:
+        raise RpcError("txid must be 64 hex chars")
+    try:
+        bytes.fromhex(txid)
+    except ValueError:
+        raise RpcError("txid must be 64 hex chars") from None
+    target = _bound(rpc, wallet)
+    if wallet is not None:
+        return _transaction_from_mapping(
+            txid, _mapping(target.call("gettransaction", txid), "gettransaction")
+        )
+    try:
+        raw: Any = target.call("getrawtransaction", txid, True)
+    except RpcError as first:
+        try:
+            raw = target.call("gettransaction", txid)
+        except RpcError:
+            raise first from None
+    return _transaction_from_mapping(txid, _mapping(raw, "getrawtransaction"))
+
+
+def get_balance(rpc: DashRPC, wallet: str | None = None) -> Balance:
+    """Read a wallet balance split (confirmed / unconfirmed / immature).
+
+    Uses ``getbalances`` when the node offers it; older nodes fall back to
+    ``getbalance`` plus ``getunconfirmedbalance``. Unbound (``wallet=None``)
+    reads the node's default wallet view.
+    """
+    target = _bound(rpc, wallet)
+    try:
+        data = _mapping(target.call("getbalances"), "getbalances")
+        mine = _mapping(data.get("mine"), "getbalances")
+        try:
+            return Balance(
+                confirmed=float(mine["trusted"]),
+                unconfirmed=float(mine.get("untrusted_pending", 0.0)),
+                immature=float(mine["immature"]) if mine.get("immature") is not None else None,
+                wallet=wallet,
+            )
+        except (TypeError, ValueError, ValidationError) as exc:
+            raise RpcError(f"getbalances returned a malformed response: {exc}") from exc
+    except RpcError as first:
+        if first.message and "malformed" in first.message:
+            raise
+        try:
+            confirmed: Any = target.call("getbalance")
+        except RpcError as second:
+            raise second from first
+        try:
+            unconfirmed_raw: Any = target.call("getunconfirmedbalance")
+        except RpcError:
+            unconfirmed_raw = 0.0
+        try:
+            return Balance(
+                confirmed=float(confirmed),
+                unconfirmed=float(unconfirmed_raw),
+                wallet=wallet,
+            )
+        except (TypeError, ValueError, ValidationError) as exc:
+            raise RpcError(f"getbalance returned a malformed response: {exc}") from exc
+
+
+def get_new_address(rpc: DashRPC, label: str | None = None, wallet: str | None = None) -> str:
+    """Request a fresh receiving address (Phase-2-validated before return)."""
+    target = _bound(rpc, wallet)
+    result: Any = target.call("getnewaddress", label) if label else target.call("getnewaddress")
+    if not isinstance(result, str) or not result:
+        raise RpcError("getnewaddress returned a malformed response")
+    info = validate_address(result)
+    if not info.valid:
+        raise RpcError(f"node returned an invalid address (reason={info.reason})")
+    logger.debug("new address issued wallet=%s", wallet)
+    return result

ourdash/core/network.py

@@ -0,0 +1,186 @@
+"""Network health reads over JSON-RPC: chain tips, masternode-list diffs, ChainLock tip.
+
+Dash here is Dash crypto from dash.org — not Plotly Dash.
+
+REST-vs-ZMQ split (hard v0.1 boundary): Dash Core's read-only HTTP REST
+mechanism and its real-time ZMQ push-feed mechanism are two SEPARATE opt-in
+mechanisms; both are trusted-network-only features — whether served from the
+same port or a separate port (same-port-or-separate-port trusted-network-only
+deployments) — and both carry user-visible warnings. v0.1 implements NEITHER
+as a transport: there is no REST client and no ZMQ subscriber in this module
+(and no new dependencies for either). This module exposes JSON-RPC helpers
+only. Any future REST or ZMQ addition requires an explicit opt-in constructor
+plus a trusted-network warning; removing this boundary wording breaks
+``tests/test_network.py::test_rest_zmq_boundary_docstring``.
+
+This module owns the ONLY global ChainLock-tip reader
+(:func:`chainlock_tip_status`). Per-transaction finality
+(:func:`ourdash.core.transactions.confirm_status`) is owned by Phase 3 and is
+not modified here.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from ourdash.core.rpc import DashRPC
+from ourdash.errors import RpcError
+from ourdash.redact import RedactionFilter
+
+logger = logging.getLogger(__name__)
+logger.addFilter(RedactionFilter())
+
+
+def _mapping(value: Any, method: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise RpcError(f"{method} returned a malformed response")
+    return value
+
+
+class ChainTip(BaseModel):
+    """One chain tip: height, hash, branch length, sync status."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    height: int
+    hash: str
+    branchlen: int
+    status: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain-object view (stdlib types only)."""
+        return self.model_dump(mode="python")
+
+
+class MasternodeDiff(BaseModel):
+    """Masternode-list change between two snapshots (proTxHash identifiers)."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    added: list[str]
+    removed: list[str]
+    changed: list[str]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain-object view (stdlib types only)."""
+        return self.model_dump(mode="python")
+
+
+class ChainLockStatus(BaseModel):
+    """Global ChainLock tip: locked height/hash plus lag behind the node tip."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    height: int
+    blockhash: str
+    behind_by: int
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain-object view (stdlib types only)."""
+        return self.model_dump(mode="python")
+
+
+def get_chain_tips(rpc: DashRPC) -> list[ChainTip]:
+    """Read ``getchaintips`` (each tip: height, hash, branch length, status)."""
+    raw: Any = rpc.call("getchaintips")
+    if not isinstance(raw, list):
+        raise RpcError("getchaintips returned a malformed response")
+    tips: list[ChainTip] = []
+    for entry in raw:
+        data = _mapping(entry, "getchaintips")
+        try:
+            tips.append(
+                ChainTip(
+                    height=int(data["height"]),
+                    hash=data["hash"],
+                    branchlen=int(data["branchlen"]),
+                    status=data["status"],
+                )
+            )
+        except (KeyError, TypeError, ValueError, ValidationError) as exc:
+            raise RpcError(f"getchaintips returned a malformed response: {exc}") from exc
+    logger.debug("chain tips read count=%d", len(tips))
+    return tips
+
+
+def get_masternode_list(rpc: DashRPC) -> dict[str, Any]:
+    """Read the full ``masternode list json`` snapshot keyed by proTxHash."""
+    try:
+        raw: Any = rpc.call("masternode", "list", "json")
+    except RpcError as first:
+        if first.code == -32601:  # pre-0.13 alias for the same snapshot
+            raw = rpc.call("masternodelist", "json")
+        else:
+            raise
+    data = _mapping(raw, "masternode list")
+    return dict(data)
+
+
+def diff_masternode_lists(before: Mapping[str, Any], after: Mapping[str, Any]) -> MasternodeDiff:
+    """Diff two ``masternode list`` snapshots (e.g. taken at different heights).
+
+    Identifiers are the deterministic proTxHash keys: ``added`` holds keys
+    only in ``after``, ``removed`` keys only in ``before``, ``changed`` keys
+    in both whose quorum-relevant entry differs. All three lists are sorted.
+    """
+    if not isinstance(before, Mapping) or not isinstance(after, Mapping):
+        raise RpcError("masternode snapshots must be mappings keyed by proTxHash")
+    before_keys = set(before.keys())
+    after_keys = set(after.keys())
+    added = sorted(str(key) for key in after_keys - before_keys)
+    removed = sorted(str(key) for key in before_keys - after_keys)
+    changed = sorted(str(key) for key in before_keys & after_keys if before[key] != after[key])
+    return MasternodeDiff(added=added, removed=removed, changed=changed)
+
+
+def masternode_list_diff(
+    rpc: DashRPC, base_snapshot: Mapping[str, Any] | None = None
+) -> MasternodeDiff:
+    """Diff the live masternode list against ``base_snapshot`` (or empty).
+
+    Capture ``base_snapshot`` via :func:`get_masternode_list` at a base
+    height, mine/wait, then call again: the result reports which masternodes
+    appeared, vanished, or changed entries between the two snapshots.
+    """
+    current = get_masternode_list(rpc)
+    base: Mapping[str, Any] = base_snapshot if base_snapshot is not None else {}
+    result = diff_masternode_lists(base, current)
+    logger.debug(
+        "masternode diff added=%d removed=%d changed=%d",
+        len(result.added),
+        len(result.removed),
+        len(result.changed),
+    )
+    return result
+
+
+def chainlock_tip_status(rpc: DashRPC) -> ChainLockStatus:
+    """Read the global ChainLock tip (locked height/hash + lag behind tip)."""
+    lock = _mapping(rpc.call("getbestchainlock"), "getbestchainlock")
+    try:
+        node_height_raw: Any = rpc.call("getblockcount")
+        if not isinstance(node_height_raw, int) or isinstance(node_height_raw, bool):
+            raise RpcError("getblockcount returned a malformed response")
+        node_height = int(node_height_raw)
+    except RpcError as exc:
+        if "malformed" in str(exc):
+            raise
+        info = _mapping(rpc.call("getblockchaininfo"), "getblockchaininfo")
+        try:
+            node_height = int(info["blocks"])
+        except (KeyError, TypeError, ValueError) as nested:
+            raise RpcError(f"getblockchaininfo returned a malformed response: {nested}") from nested
+    try:
+        status = ChainLockStatus(
+            height=int(lock["height"]),
+            blockhash=lock["blockhash"],
+            behind_by=node_height - int(lock["height"]),
+        )
+    except (KeyError, TypeError, ValueError, ValidationError) as exc:
+        raise RpcError(f"getbestchainlock returned a malformed response: {exc}") from exc
+    logger.debug("chainlock tip height=%d behind_by=%d", status.height, status.behind_by)
+    return status