btclib_wallet.ledger package

Submodules

btclib_wallet.ledger.ledger module

A set of descriptor wallets, their transactions and coins, kept current.

Ledger is what Bitcoin Core calls a wallet: a set of descriptors, which add_source grows as importdescriptors does, and every transaction that pays to or spends from their scripts. It answers what Core’s wallet RPCs answer of them – balances (getbalances, and getbalance’s trusted), utxos (listunspent), transaction and transactions (gettransaction, listtransactions) – and spends from them. It keeps labels on addresses, as the last paragraph says. It reads the chain only when its caller calls sync; nothing runs between calls.

What a source is. A DescriptorWallet, one descriptor per branch: branch 0 receives and branch 1, where there is one, takes change. The ledger watches each ranged branch from index 0 up to the next index it would hand out plus lookahead, that last one left out: with nothing handed out and a lookahead of 3, indexes 0, 1 and 2. LOOKAHEAD is Core’s DEFAULT_KEYPOOL_SIZE (src/wallet/scriptpubkeyman.h at bitcoin/bitcoin@f0de87f040, the v32.1 tag). An output paid to a position marks it handed out, as Core’s MarkUnusedAddresses does, which moves the window on. Ownership is computed from the scripts each time it is asked, so a source added later makes an output of a transaction already held the ledger’s with no read of the chain (test/functional/wallet_balance.py:283-307 at the same commit).

The sync. HistoryReader says how two answers are read together, and sync follows it. It asks again from the height of the tip it last synced to. Where the answer starts from that tip, its blocks extend what is held. Where it starts from another block, a reorganization replaced that tip: sync asks again from the height of each block it holds below it, highest first, until an answer starts from a block it holds. The blocks above that one are disconnected, and their transactions are what the new answer says they are. A source whose history has not been read yet is read from its birth height, and so is a position that a payment the sync finds brings into the window. A position that comes into the window between two syncs is read from the tip on, at the next sync: a payment to it in an earlier block is not found, as Core’s TopUpWithDB reads no earlier block either: it hands the new scripts to TopUpCallback, which only caches them (src/wallet/scriptpubkeyman.cpp:1109-1169 and src/wallet/wallet.cpp:4560-4571 at bitcoin/bitcoin@f0de87f040, the v32.1 tag).

The mempool part of the answers replaces the one the ledger held. A transaction that was in the mempool or in a block and is in neither now is kept as TxState.INACTIVE, not dropped: the mempool replaced it, refused it or evicted it (test/functional/wallet_balance.py:174-180 and 214-225). A coinbase (Abandon) and a transaction a block conflicts with (Conflicts) are the exceptions.

Conflicts. A transaction in a block that spends an input of a transaction in no block makes that one TxState.CONFLICTED with the block, and each of its descendants not in a block, as Core’s MarkConflicted does (src/wallet/wallet.cpp:1235-1252 and 1372-1400 at bitcoin/bitcoin@f0de87f040, the v32.1 tag). Where several blocks conflict with one transaction, the lowest is its block. Its confirmations are minus the depth of that block. A reorganization that disconnects the block makes it inactive again, as Core’s blockDisconnected does (:1599-1644). The ledger holds only what its HistoryReader answers, so a conflict is found only where the conflicting transaction touches the ledger’s scripts: a payment to the ledger whose input a block spends in a transaction paying elsewhere goes inactive, not conflicted.

Abandon. abandon marks an inactive transaction ABANDONED, and each inactive descendant, in the file, as Core’s AbandonTransaction does (:1342-1370). A sync that finds an abandoned transaction in the mempool or a block clears its own mark only, and a conflict replaces it. A coinbase a reorganization takes out of its block is abandoned, as Core’s blockDisconnected leaves it. An abandoned or conflicted transaction counts in no balance and gives no coin, and the coins it spends count and can be spent again.

Resubmission. resubmit broadcasts again each transaction in no block that is neither conflicted nor abandoned, as Core does on load and from time to time (:2147-2180). Here it runs only when its caller calls it: the ledger broadcasts nothing that spend or resubmit was not called for.

What is checked of an unconfirmed transaction (ISS btclib-org/btclib-wallet#642). A backend can report a mempool transaction that spends the ledger’s coins with a signature that does not verify, to have the user replace it. So each input of a transaction in no block that spends an output the ledger owns is verified with btclib’s script engine, against every output the transaction spends that the ledger holds. The check runs at the end of each sync, against the scripts the windows reach once that sync has moved them, and again whenever the scripts watched grow between two syncs. A transaction that fails leaves the ledger with its unconfirmed descendants, or is kept out. A taproot input commits to every output the transaction spends, so a spend of a taproot output of the ledger beside an output the ledger does not hold fails the check. What stays unverified: an incoming unconfirmed transaction spends no coin of the ledger, so nothing of it is checked; a spend of the ledger’s coin whose parent the backend has not reported, until it does; and a transaction a backend reports in a block, since a HistoryReader answers no proof that the block holds it (ISS btclib-org/btclib-wallet#737).

Balances. Core’s GetBalance and CachedTxIsTrusted (src/wallet/receive.cpp:205-295 at bitcoin/bitcoin@f0de87f040, the v32.1 tag), and its HowSpent (src/wallet/wallet.cpp:810-830). A transaction is trusted where it is confirmed, or in the mempool with every input spending a trusted output of the ledger. A coinbase is immature until 100 blocks are built on top of its own.

The spender. fund selects among the trusted, unlocked, unspent coins that are confirmed or in the mempool, with select_coins, and pays the change to source 0: to the next address of its branch 1 not handed out, or of its branch 0 where it has no branch 1, or to the one address of that branch where its descriptor is not ranged. The fee rate is the caller’s where given, refused below the node’s minimum relay rate; else the backend’s estimate, else fallback_fee_rate, raised to the node’s mempool minimum. A spend with no rate, no estimate and no fallback is refused, as Core’s is with -fallbackfee=0. spend funds, signs and records the transaction as inactive before it broadcasts it, so one the node refuses stays, and counts as nonmempool.

Labels. Core’s address book (src/wallet/wallet.h:238-278 at bitcoin/bitcoin@f0de87f040, the v32.1 tag). A label is kept by script, in the file, on an address of the ledger or of anybody else on its network. Its purpose is receive where the ledger watches the script when the label is set, and send otherwise, as setlabel sets it (src/wallet/rpc/addresses.cpp:146-150). Until one is set, an address of branch 0 has the label “” once it or a later index of its branch is handed out or paid to, or where its descriptor is not ranged, as Core labels each receiving address it hands out, imports, sees paid or skips below one paid (src/wallet/wallet.cpp:1275-1280 and 3849-3865, and src/wallet/scriptpubkeyman.cpp:1171-1197). new_address on a ranged branch 0 sets the label it is given, “” where it is given none, over any label the address had, with the purpose receive, as Core’s GetNewDestination does (src/wallet/wallet.cpp:2640-2654). An address of another branch has no label until one is set. Change is an output to the ledger’s script with no label, as Core’s ScriptIsChange reads it (src/wallet/receive.cpp:52-72), so a label makes a change address a receiving one. A script with no address, as pk() pays to, has no label, is change, and is in no answer about labels or groupings. The name * is refused, as LabelFromValue refuses it (src/wallet/rpc/util.cpp:101-110). What an address or a label received is Core’s GetReceived (src/wallet/rpc/coins.cpp:21-77): every output paying the ledger’s scripts, change included, in each transaction deep enough. address_groupings is GetAddressBalances and GetAddressGroupings (src/wallet/receive.cpp:297-416).

class btclib_wallet.ledger.ledger.Ledger(store: _Store, network: str, reader: HistoryReader, broadcaster: Broadcaster | None, fee_estimator: FeeEstimator | None, relay_fee_reader: RelayFeeReader | None, fallback_fee_rate: FeeRate | None)

Bases: object

A set of descriptor wallets, their transactions, and their file.

Made by create, load or restore, never directly. The reader is the backend sync reads the chain from. The broadcaster, the fee estimator and the relay fee reader are what fund and spend use, each where the backend has it.

abandon(txid: bytes) → None

Abandon an inactive transaction, and its inactive descendants.

Core’s abandontransaction: the coins they spend count, and can be spent, again. The mark is written to the file. A transaction confirmed, conflicted or in the mempool is refused, and an abandoned one is left as it is. txid is in display order.

add_source(wallet: DescriptorWallet, birth_height: int | None = 0, *, lookahead: int = 1000, label: str | None = None) → int

Add a wallet of descriptors, and return its source id.

Core’s importdescriptors. birth_height is where the next sync reads its history from, and None reads none before the tip the ledger holds, as Core’s timestamp: “now” does; fetch.start_height_for_time turns a birth time into a height. The wallet is written to the file whole, its private keys included, and load builds it again from its descriptors and keys. label is set on the one address of branch 0, where its script has one, and refused where that branch is ranged or missing, as Core refuses a label on a ranged descriptor (src/wallet/rpc/backup.cpp:213-216 at bitcoin/bitcoin@f0de87f040, the v32.1 tag).

property address_groupings: tuple[tuple[GroupedAddress, ...], ...]

The ledger’s addresses, grouped as spent together.

Core’s listaddressgroupings. Addresses whose outputs one transaction spends are in one group, with the change it pays; each address paid is in a group, alone where nothing joins it. A script with no address is left out. The groups and the addresses in each are sorted by address.

addresses_by_label(label: str) → dict[str, str]

Return the purpose of each address with the label.

Core’s getaddressesbylabel. A label no address has is refused.

backup(path: str | PathLike[str]) → None

Write a copy of the ledger’s file into a new file at path.

Core’s backupwallet. Anything at path is refused, the ledger’s own file included, and nothing is written there. store says what the copy holds; restore reads it.

balances(min_depth: int = 0, *, include_nonmempool: bool = True) → Balances

Return Core’s balance buckets, in satoshi.

getbalances is the defaults. getbalance with minconf is the trusted bucket of balances(minconf, include_nonmempool=False).

close() → None

Close the file; the ledger answers nothing after this.

classmethod create(path: str | PathLike[str], network: str, reader: HistoryReader, *, broadcaster: Broadcaster | None = None, fee_estimator: FeeEstimator | None = None, relay_fee_reader: RelayFeeReader | None = None, fallback_fee_rate: FeeRate | None = None) → Ledger

Return a new ledger, with no source, in a new file at path.

Core’s createwallet. A file already at path is refused.

fund(outputs: Sequence[TxOut], fee_rate: FeeRate | None = None) → FundedPsbt

Return the unsigned psbt paying outputs from the ledger’s coins.

Core’s fundrawtransaction. The coins, the rate and the change address are the module docstring’s; the change address is handed out only where the psbt pays to it. A ledger with no source 0 is refused.

label_of(address: str) → str | None

Return the label of an address, None where it has none.

The labels that Core’s getaddressinfo reports (src/wallet/rpc/addresses.cpp:550-555 at bitcoin/bitcoin@f0de87f040, the v32.1 tag).

labels(purpose: str | None = None) → tuple[str, ...]

Return each label in use, sorted, Core’s listlabels.

A purpose, receive or send, keeps the labels of the addresses of that purpose.

classmethod load(path: str | PathLike[str], network: str, reader: HistoryReader, *, broadcaster: Broadcaster | None = None, fee_estimator: FeeEstimator | None = None, relay_fee_reader: RelayFeeReader | None = None, fallback_fee_rate: FeeRate | None = None) → Ledger

Return the ledger the file at path holds, reading no backend.

Core’s loadwallet. store says which files are refused.

lock(outpoint: OutPoint) → None

Keep an output out of fund and spend, until unlock.

Core’s lockunspent, not persistent: a lock is not in the file.

property locked: frozenset[OutPoint]

The outputs locked, Core’s listlockunspent.

new_address(source: int = 0, branch: int = 0, *, label: str | None = None) → str

Hand out the next address of a branch, and remember it.

Core’s getnewaddress. The next index is one past the highest handed out or paid to. A branch whose descriptor is not ranged has one address, which is handed out every time. label is set on the address, replacing any it had. On a ranged branch 0, one not given is “”, as the module docstring says.

new_change_address(source: int = 0) → str

Hand out the next address of the change branch, branch 1.

Core’s getrawchangeaddress. A source with no branch 1 is refused.

position_of(script_pub_key: ScriptPubKey) → tuple[int, int, int] | None

Return the source, branch and index paying to a script, or None.

The answer is one of the positions the ledger watches.

received_by_address(address: str, min_depth: int = 1, *, include_immature_coinbase: bool = False) → int

Return what the address received, in satoshi.

Core’s getreceivedbyaddress, as the module docstring says. An address the ledger does not watch is refused.

received_by_label(label: str, min_depth: int = 1, *, include_immature_coinbase: bool = False) → int

Return what the ledger’s addresses with the label received.

Core’s getreceivedbylabel. A label no address has is refused, and so is one that only addresses of others have.

classmethod restore(backup: str | PathLike[str], path: str | PathLike[str], network: str, reader: HistoryReader, *, broadcaster: Broadcaster | None = None, fee_estimator: FeeEstimator | None = None, relay_fee_reader: RelayFeeReader | None = None, fallback_fee_rate: FeeRate | None = None) → Ledger

Copy the backup at backup into a new file at path, and load it.

Core’s restorewallet, which copies the backup and loads the copy (RestoreWallet, src/wallet/wallet.cpp:459-536 at bitcoin/bitcoin@f0de87f040, the v32.1 tag). A missing backup, a file already at path, and a backup that is no ledger file of network are refused, with nothing left at path. The ledger reads no backend here: its next sync reads from the tip the backup holds. On a node that pruned blocks from that tip up, BitcoinCoreFetcher fails that sync with a FetchError, where Core refuses the restore itself.

resubmit() → dict[bytes, FetchError]

Broadcast again what is in the mempool or inactive; return refusals.

Core’s ResubmitWalletTransactions, run only when the caller calls it: each transaction in the mempool or inactive, in the order it was recorded. One the broadcaster accepts is in the mempool, and hands out what it pays, as spend says. One it refuses stays as it was, and its refusal is returned under its id rather than raised, so that one refusal does not hold back the others.

set_label(address: str, label: str) → None

Set the label of an address, the ledger’s or anybody else’s.

Core’s setlabel. A label the address had is replaced.

sign(psbt: Psbt) → Psbt

Return the psbt with every signature the ledger’s keys can add.

Core’s signrawtransactionwithwallet, over a psbt: each input spending an output the ledger holds is updated with its source’s scripts and key origins first. A source signs with the extended private keys it was added with.

property sources: tuple[DescriptorWallet, ...]

The wallets of the ledger, in source id order.

spend(outputs: Sequence[TxOut], fee_rate: FeeRate | None = None) → Tx

Pay outputs from the ledger’s coins, and broadcast the payment.

Core’s send. The transaction is recorded as inactive before it is broadcast, and as in the mempool once the broadcaster accepts it. A refusal is raised as the broadcaster raises it, and leaves the transaction in the ledger as inactive. Each position of the ledger it pays is handed out once the broadcaster accepts it, as Core’s wallet marks the scripts a transaction pays used when the mempool reports it (src/wallet/wallet.cpp:1263-1280 at bitcoin/bitcoin@f0de87f040, the v32.1 tag): a refusal hands out nothing.

sync() → SyncResult

Read the chain from the tip the ledger holds, and record it.

The module docstring says how. A tip that moves between the reads of one sync starts it again, at most _SYNC_ATTEMPTS times in all, and then raises FetchError. A backend’s own FetchError is raised as it comes, and nothing is written. A ledger with no source is refused, having no script to ask about.

property tip: BlockRef | None

The block the ledger is synced to, None before any sync.

Core’s lastprocessedblock.

transaction(txid: bytes) → TxInfo

Return what gettransaction reports of a transaction held.

txid is in display order, as Tx.id returns it.

property transactions: tuple[TxInfo, ...]

Every transaction held, in the order it was recorded.

Core’s listtransactions, one TxInfo per transaction.

unlock(outpoint: OutPoint) → None

Let a locked output be spent again.

utxos(min_depth: int = 1, *, include_immature_coinbase: bool = False, include_locked: bool = False, include_unsafe: bool = True) → tuple[Utxo, ...]

Return the unspent outputs, as Core’s AvailableCoins filters them.

listunspent is the defaults. An output is left out where a transaction of the ledger that is neither abandoned nor conflicted spends it; where its own transaction is in no block and not in the mempool, a conflicted one included; where it is locked, unless include_locked; where it is an immature coinbase, unless include_immature_coinbase; and where its transaction is not trusted and include_unsafe is False.

btclib_wallet.ledger.records module

What a Ledger holds and answers, one frozen record each.

TxState is the state Bitcoin Core gives a wallet transaction (src/wallet/transaction.h:33-81 at bitcoin/bitcoin@f0de87f040, the v32.1 tag), with the abandoned flag of Core’s inactive state as a state of its own.

class btclib_wallet.ledger.records.Balances(trusted: int, untrusted_pending: int, immature: int, nonmempool: int)

Bases: object

Core’s balance buckets, in satoshi, as getbalances reports them.

nonmempool is negative: the coins counted in another bucket that a wallet transaction outside the mempool spends.

class btclib_wallet.ledger.records.GroupedAddress(address: str, amount: int, label: str | None)

Bases: object

One address of a group listaddressgroupings reports.

amount is what its unspent outputs hold, in satoshi, counted as Core’s GetAddressBalances counts it. label is None where the address has none, as change has none.

class btclib_wallet.ledger.records.SyncResult(tip: BlockRef, fork_height: int | None, changed: frozenset[bytes])

Bases: object

What one Ledger.sync did.

tip is the block the ledger is synced to. fork_height is the height of the last block the ledger held that is still on the chain where a reorganization replaced the blocks above it, and None where none did. It is -1 where no block the ledger held below its tip is still on the chain, as where the backend now follows another chain: the ledger then asked from height 0, and every block it held was disconnected. changed holds the id of every transaction that entered the ledger, left it, or changed state or block.

class btclib_wallet.ledger.records.TxDetail(category: str, vout: int, amount: int)

Bases: object

One line of gettransaction’s details.

category is Core’s: send for an output paid to someone else by a transaction spending the ledger’s coins, and for an output the ledger receives receive, or for a coinbase immature, generate or orphan. amount is negative for send.

class btclib_wallet.ledger.records.TxInfo(wallet_tx: WalletTx, amount: int, fee: int | None, confirmations: int, trusted: bool, details: tuple[TxDetail, ...], wallet_conflicts: frozenset[bytes])

Bases: object

What gettransaction reports of a wallet transaction, in satoshi.

amount is what the transaction adds to the ledger with its fee left out, as Core’s amount leaves it; a coinbase adds nothing until it matures, and an orphaned one, in no block, nothing at all. Its details still list what it pays. fee is what it pays, and None unless it spends one of the ledger’s coins. confirmations is 0 for a transaction in no block, and minus the depth of the conflicting block for a conflicted one. wallet_conflicts is Core’s walletconflicts: the ids of the other transactions of the ledger that spend one of its inputs, whatever their state.

class btclib_wallet.ledger.records.TxState(*values)

Bases: Enum

Where a wallet transaction is.

INACTIVE is a transaction neither in a block of the chain nor in the last mempool read: one the mempool replaced, refused or evicted, or one a reorganization took out of a block and the mempool did not take back. It is kept, not dropped. ABANDONED is an inactive transaction its caller abandoned, or a descendant of one (Ledger.abandon), or a coinbase a reorganization took out of its block. CONFLICTED is a transaction that a transaction in a block conflicts with, by spending one of its inputs or an input of one of its ancestors.

class btclib_wallet.ledger.records.Utxo(outpoint: OutPoint, tx_out: TxOut, confirmations: int, safe: bool, source: int, branch: int, index: int)

Bases: object

An unspent output of the ledger, as listunspent reports it.

safe is Core’s: the transaction is trusted. source, branch and index are the position of the source that pays to the output.

class btclib_wallet.ledger.records.WalletTx(tx: Tx, state: TxState, block: BlockRef | None, seq: int)

Bases: object

A transaction the ledger holds, its state, and its order.

block is the block that confirms it where state is CONFIRMED, the block that conflicts with it where state is CONFLICTED, and None otherwise. seq is the order the ledger first recorded it in.

btclib_wallet.ledger.store module

The file a Ledger lives in: SQLite, through the standard library.

Two integers in SQLite’s own header say what the file is, as Bitcoin Core’s wallet does (src/wallet/sqlite.cpp at bitcoin/bitcoin@f0de87f040, the v32.1 tag). PRAGMA application_id is APPLICATION_ID, the same in every file this package writes, so another program’s SQLite file is refused before any table is read. Core writes its network magic there instead, so a Core wallet file is refused too. PRAGMA user_version is the format version, FORMAT_VERSION for the files this release writes. A file of a newer version is refused. A file of an older version is migrated one version at a time, each step in its own SQLite transaction, by the steps _MIGRATIONS holds. The network is a row of the meta table, checked when the file is opened.

The file holds everything a load answers from: the sources, the positions handed out, every transaction with its state and block, the blocks synced through, the tip, and the labels. Each source’s private keys are written in plain text, as an unencrypted Core wallet writes its own: ISS btclib-org/btclib-wallet#717 encrypts them. SQLite’s rollback journal and its freed pages can keep old bytes after a write.

Every write a sync makes is one SQLite transaction, so a process killed mid-write leaves the file as the last whole sync left it.

A backup is a new file written through SQLite’s backup API, as Core’s SQLiteDatabase::Backup writes one (src/wallet/sqlite.cpp:356-381 at bitcoin/bitcoin@f0de87f040): a copy of every page of the file as one read sees it, freed pages included. So it holds what the file holds, private keys included, and the old bytes its freed pages keep.

Module contents

The ledger: descriptor wallets, their transactions and coins, and a file.

What wallet’s wallets leave out – the transactions, the coins, the balances, a spender and a file that outlives the process – is here, one layer above them and above fetch:

• ledger is Ledger, which holds a set of descriptor wallets, syncs them from a HistoryReader when its caller calls sync, answers Bitcoin Core’s wallet questions of them, and spends from them;

• records is what it answers in;

• store is its SQLite file and how the file says what it is.

class btclib_wallet.ledger.Balances(trusted: int, untrusted_pending: int, immature: int, nonmempool: int)

Bases: object

Core’s balance buckets, in satoshi, as getbalances reports them.

nonmempool is negative: the coins counted in another bucket that a wallet transaction outside the mempool spends.

class btclib_wallet.ledger.GroupedAddress(address: str, amount: int, label: str | None)

Bases: object

One address of a group listaddressgroupings reports.

amount is what its unspent outputs hold, in satoshi, counted as Core’s GetAddressBalances counts it. label is None where the address has none, as change has none.

class btclib_wallet.ledger.Ledger(store: _Store, network: str, reader: HistoryReader, broadcaster: Broadcaster | None, fee_estimator: FeeEstimator | None, relay_fee_reader: RelayFeeReader | None, fallback_fee_rate: FeeRate | None)

Bases: object

A set of descriptor wallets, their transactions, and their file.

Made by create, load or restore, never directly. The reader is the backend sync reads the chain from. The broadcaster, the fee estimator and the relay fee reader are what fund and spend use, each where the backend has it.

abandon(txid: bytes) → None

Abandon an inactive transaction, and its inactive descendants.

Core’s abandontransaction: the coins they spend count, and can be spent, again. The mark is written to the file. A transaction confirmed, conflicted or in the mempool is refused, and an abandoned one is left as it is. txid is in display order.

add_source(wallet: DescriptorWallet, birth_height: int | None = 0, *, lookahead: int = 1000, label: str | None = None) → int

Add a wallet of descriptors, and return its source id.

Core’s importdescriptors. birth_height is where the next sync reads its history from, and None reads none before the tip the ledger holds, as Core’s timestamp: “now” does; fetch.start_height_for_time turns a birth time into a height. The wallet is written to the file whole, its private keys included, and load builds it again from its descriptors and keys. label is set on the one address of branch 0, where its script has one, and refused where that branch is ranged or missing, as Core refuses a label on a ranged descriptor (src/wallet/rpc/backup.cpp:213-216 at bitcoin/bitcoin@f0de87f040, the v32.1 tag).

property address_groupings: tuple[tuple[GroupedAddress, ...], ...]

The ledger’s addresses, grouped as spent together.

Core’s listaddressgroupings. Addresses whose outputs one transaction spends are in one group, with the change it pays; each address paid is in a group, alone where nothing joins it. A script with no address is left out. The groups and the addresses in each are sorted by address.

addresses_by_label(label: str) → dict[str, str]

Return the purpose of each address with the label.

Core’s getaddressesbylabel. A label no address has is refused.

backup(path: str | PathLike[str]) → None

Write a copy of the ledger’s file into a new file at path.

Core’s backupwallet. Anything at path is refused, the ledger’s own file included, and nothing is written there. store says what the copy holds; restore reads it.

balances(min_depth: int = 0, *, include_nonmempool: bool = True) → Balances

Return Core’s balance buckets, in satoshi.

getbalances is the defaults. getbalance with minconf is the trusted bucket of balances(minconf, include_nonmempool=False).

close() → None

Close the file; the ledger answers nothing after this.

classmethod create(path: str | PathLike[str], network: str, reader: HistoryReader, *, broadcaster: Broadcaster | None = None, fee_estimator: FeeEstimator | None = None, relay_fee_reader: RelayFeeReader | None = None, fallback_fee_rate: FeeRate | None = None) → Ledger

Return a new ledger, with no source, in a new file at path.

Core’s createwallet. A file already at path is refused.

fund(outputs: Sequence[TxOut], fee_rate: FeeRate | None = None) → FundedPsbt

Return the unsigned psbt paying outputs from the ledger’s coins.

Core’s fundrawtransaction. The coins, the rate and the change address are the module docstring’s; the change address is handed out only where the psbt pays to it. A ledger with no source 0 is refused.

label_of(address: str) → str | None

Return the label of an address, None where it has none.

The labels that Core’s getaddressinfo reports (src/wallet/rpc/addresses.cpp:550-555 at bitcoin/bitcoin@f0de87f040, the v32.1 tag).

labels(purpose: str | None = None) → tuple[str, ...]

Return each label in use, sorted, Core’s listlabels.

A purpose, receive or send, keeps the labels of the addresses of that purpose.

classmethod load(path: str | PathLike[str], network: str, reader: HistoryReader, *, broadcaster: Broadcaster | None = None, fee_estimator: FeeEstimator | None = None, relay_fee_reader: RelayFeeReader | None = None, fallback_fee_rate: FeeRate | None = None) → Ledger

Return the ledger the file at path holds, reading no backend.

Core’s loadwallet. store says which files are refused.

lock(outpoint: OutPoint) → None

Keep an output out of fund and spend, until unlock.

Core’s lockunspent, not persistent: a lock is not in the file.

property locked: frozenset[OutPoint]

The outputs locked, Core’s listlockunspent.

new_address(source: int = 0, branch: int = 0, *, label: str | None = None) → str

Hand out the next address of a branch, and remember it.

Core’s getnewaddress. The next index is one past the highest handed out or paid to. A branch whose descriptor is not ranged has one address, which is handed out every time. label is set on the address, replacing any it had. On a ranged branch 0, one not given is “”, as the module docstring says.

new_change_address(source: int = 0) → str

Hand out the next address of the change branch, branch 1.

Core’s getrawchangeaddress. A source with no branch 1 is refused.

position_of(script_pub_key: ScriptPubKey) → tuple[int, int, int] | None

Return the source, branch and index paying to a script, or None.

The answer is one of the positions the ledger watches.

received_by_address(address: str, min_depth: int = 1, *, include_immature_coinbase: bool = False) → int

Return what the address received, in satoshi.

Core’s getreceivedbyaddress, as the module docstring says. An address the ledger does not watch is refused.

received_by_label(label: str, min_depth: int = 1, *, include_immature_coinbase: bool = False) → int

Return what the ledger’s addresses with the label received.

Core’s getreceivedbylabel. A label no address has is refused, and so is one that only addresses of others have.

classmethod restore(backup: str | PathLike[str], path: str | PathLike[str], network: str, reader: HistoryReader, *, broadcaster: Broadcaster | None = None, fee_estimator: FeeEstimator | None = None, relay_fee_reader: RelayFeeReader | None = None, fallback_fee_rate: FeeRate | None = None) → Ledger

Copy the backup at backup into a new file at path, and load it.

Core’s restorewallet, which copies the backup and loads the copy (RestoreWallet, src/wallet/wallet.cpp:459-536 at bitcoin/bitcoin@f0de87f040, the v32.1 tag). A missing backup, a file already at path, and a backup that is no ledger file of network are refused, with nothing left at path. The ledger reads no backend here: its next sync reads from the tip the backup holds. On a node that pruned blocks from that tip up, BitcoinCoreFetcher fails that sync with a FetchError, where Core refuses the restore itself.

resubmit() → dict[bytes, FetchError]

Broadcast again what is in the mempool or inactive; return refusals.

Core’s ResubmitWalletTransactions, run only when the caller calls it: each transaction in the mempool or inactive, in the order it was recorded. One the broadcaster accepts is in the mempool, and hands out what it pays, as spend says. One it refuses stays as it was, and its refusal is returned under its id rather than raised, so that one refusal does not hold back the others.

set_label(address: str, label: str) → None

Set the label of an address, the ledger’s or anybody else’s.

Core’s setlabel. A label the address had is replaced.

sign(psbt: Psbt) → Psbt

Return the psbt with every signature the ledger’s keys can add.

Core’s signrawtransactionwithwallet, over a psbt: each input spending an output the ledger holds is updated with its source’s scripts and key origins first. A source signs with the extended private keys it was added with.

property sources: tuple[DescriptorWallet, ...]

The wallets of the ledger, in source id order.

spend(outputs: Sequence[TxOut], fee_rate: FeeRate | None = None) → Tx

Pay outputs from the ledger’s coins, and broadcast the payment.

Core’s send. The transaction is recorded as inactive before it is broadcast, and as in the mempool once the broadcaster accepts it. A refusal is raised as the broadcaster raises it, and leaves the transaction in the ledger as inactive. Each position of the ledger it pays is handed out once the broadcaster accepts it, as Core’s wallet marks the scripts a transaction pays used when the mempool reports it (src/wallet/wallet.cpp:1263-1280 at bitcoin/bitcoin@f0de87f040, the v32.1 tag): a refusal hands out nothing.

sync() → SyncResult

Read the chain from the tip the ledger holds, and record it.

The module docstring says how. A tip that moves between the reads of one sync starts it again, at most _SYNC_ATTEMPTS times in all, and then raises FetchError. A backend’s own FetchError is raised as it comes, and nothing is written. A ledger with no source is refused, having no script to ask about.

property tip: BlockRef | None

The block the ledger is synced to, None before any sync.

Core’s lastprocessedblock.

transaction(txid: bytes) → TxInfo

Return what gettransaction reports of a transaction held.

txid is in display order, as Tx.id returns it.

property transactions: tuple[TxInfo, ...]

Every transaction held, in the order it was recorded.

Core’s listtransactions, one TxInfo per transaction.

unlock(outpoint: OutPoint) → None

Let a locked output be spent again.

utxos(min_depth: int = 1, *, include_immature_coinbase: bool = False, include_locked: bool = False, include_unsafe: bool = True) → tuple[Utxo, ...]

Return the unspent outputs, as Core’s AvailableCoins filters them.

listunspent is the defaults. An output is left out where a transaction of the ledger that is neither abandoned nor conflicted spends it; where its own transaction is in no block and not in the mempool, a conflicted one included; where it is locked, unless include_locked; where it is an immature coinbase, unless include_immature_coinbase; and where its transaction is not trusted and include_unsafe is False.

class btclib_wallet.ledger.SyncResult(tip: BlockRef, fork_height: int | None, changed: frozenset[bytes])

Bases: object

What one Ledger.sync did.

tip is the block the ledger is synced to. fork_height is the height of the last block the ledger held that is still on the chain where a reorganization replaced the blocks above it, and None where none did. It is -1 where no block the ledger held below its tip is still on the chain, as where the backend now follows another chain: the ledger then asked from height 0, and every block it held was disconnected. changed holds the id of every transaction that entered the ledger, left it, or changed state or block.

class btclib_wallet.ledger.TxDetail(category: str, vout: int, amount: int)

Bases: object

One line of gettransaction’s details.

category is Core’s: send for an output paid to someone else by a transaction spending the ledger’s coins, and for an output the ledger receives receive, or for a coinbase immature, generate or orphan. amount is negative for send.

class btclib_wallet.ledger.TxInfo(wallet_tx: WalletTx, amount: int, fee: int | None, confirmations: int, trusted: bool, details: tuple[TxDetail, ...], wallet_conflicts: frozenset[bytes])

Bases: object

What gettransaction reports of a wallet transaction, in satoshi.

amount is what the transaction adds to the ledger with its fee left out, as Core’s amount leaves it; a coinbase adds nothing until it matures, and an orphaned one, in no block, nothing at all. Its details still list what it pays. fee is what it pays, and None unless it spends one of the ledger’s coins. confirmations is 0 for a transaction in no block, and minus the depth of the conflicting block for a conflicted one. wallet_conflicts is Core’s walletconflicts: the ids of the other transactions of the ledger that spend one of its inputs, whatever their state.

class btclib_wallet.ledger.TxState(*values)

Bases: Enum

Where a wallet transaction is.

INACTIVE is a transaction neither in a block of the chain nor in the last mempool read: one the mempool replaced, refused or evicted, or one a reorganization took out of a block and the mempool did not take back. It is kept, not dropped. ABANDONED is an inactive transaction its caller abandoned, or a descendant of one (Ledger.abandon), or a coinbase a reorganization took out of its block. CONFLICTED is a transaction that a transaction in a block conflicts with, by spending one of its inputs or an input of one of its ancestors.

class btclib_wallet.ledger.Utxo(outpoint: OutPoint, tx_out: TxOut, confirmations: int, safe: bool, source: int, branch: int, index: int)

Bases: object

An unspent output of the ledger, as listunspent reports it.

safe is Core’s: the transaction is trusted. source, branch and index are the position of the source that pays to the output.

class btclib_wallet.ledger.WalletTx(tx: Tx, state: TxState, block: BlockRef | None, seq: int)

Bases: object

A transaction the ledger holds, its state, and its order.

block is the block that confirms it where state is CONFIRMED, the block that conflicts with it where state is CONFLICTED, and None otherwise. seq is the order the ledger first recorded it in.