Migration: v0.3 to v0.4

Breaking Changes

Wallet sync is now fail-fast

wallet.sync() raises WalletSyncError when the backend is unreachable. Previously it silently returned stale data. Callers should wrap sync in try/except.

Mock UTXOs removed from production path

Wallet.create() no longer seeds mock UTXOs. Test code should use:

from bitpilot.testing import seed_mock_utxos
seed_mock_utxos(wallet)

Broadcast failures are explicit

BroadcastRejectedError is raised when a backend explicitly rejects a transaction. There is no silent fallback to a stub txid.

PSBT validation enforced

PSBTError is raised on malformed BIP-174 payloads. Previously some invalid PSBTs were silently accepted.

Insufficient confirmed funds

InsufficientConfirmedFundsError is raised during approval when confirmed UTXOs cannot cover amount + fees.

Lightning constructors validate at init

LightningWallet.from_lnd() and from_cln() now validate credentials and verify connectivity. Invalid config raises LightningConfigError; auth failures raise LightningAuthError.

MCP server lifecycle

The MCP adapter uses the mcp server lifecycle instead of a demo stdin loop. Tool errors are structured with codes.

CLI changes

• New command: bitpilot sync
• balance and utxos fail clearly when sync cannot reach the backend
• status reports runtime-configured state (no placeholder defaults)

Website

• Docs navigation changed from #docs anchor to /docs/ route.
• GitHub links updated to https://github.com/dotdevn/neetbtc-toolkit.
• Version references updated to v0.4.

New Exports

Added to bitpilot.__all__:

• WalletSyncError
• InsufficientConfirmedFundsError
• BroadcastRejectedError
• PSBTError
• CircuitBreakerRule
• Watcher, WatcherError
• AuditLedger, AuditEntry, AuditEvent
• LightningWallet, L402Client (lazy import)