tx-engine 0.11.0__tar.gz → 0.11.2__tar.gz

{tx_engine-0.11.0 → tx_engine-0.11.2}/Cargo.lock

@@ -80,6 +80,12 @@ version = "0.22.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
+[[package]]
+name = "base64"
+version = "0.23.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
+
 [[package]]
 name = "base64ct"
 version = "1.8.3"
@@ -88,9 +94,9 @@ checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
 [[package]]
 name = "bitflags"
-version = "2.13.1"
+version = "2.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
 
 [[package]]
 name = "block-buffer"
@@ -130,9 +136,9 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "cc"
-version = "1.4.5"
+version = "1.4.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "005ec2760ca554fae18df7a11195552ec576cd665632a881bc011d5bb2fd4d80"
+checksum = "a3eb0f42d6c360dc3f8a821f6bf2fdea7f72bfd36b3076eb0e6d1e9e0752fff4"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
@@ -165,7 +171,7 @@ dependencies = [
 
 [[package]]
 name = "chain-gang"
-version = "0.11.0"
+version = "0.11.2"
 dependencies = [
  "async-lock",
  "async-trait",
@@ -251,6 +257,12 @@ version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
+[[package]]
+name = "core_detect"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f8f80099a98041a3d1622845c271458a2d73e688351bf3cb999266764b81d48"
+
 [[package]]
 name = "cpubits"
 version = "0.1.1"
@@ -391,11 +403,17 @@ dependencies = [
 
 [[package]]
 name = "encoding_rs"
-version = "0.8.35"
+version = "0.8.41"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3"
+checksum = "7b5ef0006ac9ab233c38522f5ae99cae3625151de8f706cacee1cba4b8e2832a"
 dependencies = [
  "cfg-if",
+ "core_detect",
+ "multiversion",
+ "multiversion_no_op",
+ "rustversion",
+ "scopeguard",
+ "simdutf8",
 ]
 
 [[package]]
@@ -625,9 +643,9 @@ checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
 
 [[package]]
 name = "hybrid-array"
-version = "0.4.14"
+version = "0.4.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "707114b52a152fa7bdb290cd7cd5912d9467273b6d74e21b8d81aca1f8533f6b"
+checksum = "27f864f10dfb56725ce5ce5472bc52252c8f93a4ab86327122cebf62c5f59a17"
 dependencies = [
  "subtle",
  "typenum",
@@ -676,7 +694,7 @@ version = "0.1.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "bytes",
  "futures-channel",
  "futures-util",
@@ -811,9 +829,9 @@ dependencies = [
 
 [[package]]
 name = "ipnet"
-version = "2.12.1"
+version = "2.12.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6a756c3fac73139e83f14c2d742155dd2b78d3ee56597b419a0579b7bdd6dd78"
+checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0"
 
 [[package]]
 name = "itoa"
@@ -932,9 +950,9 @@ checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
 
 [[package]]
 name = "lru-slab"
-version = "0.1.2"
+version = "0.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
+checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f"
 
 [[package]]
 name = "memchr"
@@ -959,6 +977,33 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "multiversion"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ca4bea16ffc3f443cf7d866912118196bfef4c6a1556ca00f9f9b00bb43f7c"
+dependencies = [
+ "multiversion-macros",
+]
+
+[[package]]
+name = "multiversion-macros"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d416831a7317ef4b08bee00b69cbbb9c8763da7959a7026244d6266869f9c83"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "rustversion",
+ "syn 3.0.5",
+]
+
+[[package]]
+name = "multiversion_no_op"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "743fb55ba31b18fb1ecef6bdc9aa2743314978ac084044301a7eee33fb99a20d"
+
 [[package]]
 name = "murmur3"
 version = "0.5.2"
@@ -1160,9 +1205,9 @@ dependencies = [
 
 [[package]]
 name = "quinn"
-version = "0.11.11"
+version = "0.11.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c1a41e437b6bbd489372cd4971de128e85c855f56c57f283d20ff016cf7c0a8"
+checksum = "4051e23e9185c255a7e33ef59cdbca87a22d359052eecd22fc6b901fb37d9d11"
 dependencies = [
  "bytes",
  "cfg_aliases",
@@ -1180,9 +1225,9 @@ dependencies = [
 
 [[package]]
 name = "quinn-proto"
-version = "0.11.17"
+version = "0.11.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "04759210543be93709136e28212294a659ef5001836ff4eab4d663e4529bba83"
+checksum = "a9746dbde176634f4f2f1faf2404e30a31b2bc1e9cafb5329c95d8177a18c9fc"
 dependencies = [
  "aws-lc-rs",
  "bytes",
@@ -1287,11 +1332,11 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "reqwest"
-version = "0.13.4"
+version = "0.13.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "219c5811de6525e5416c7d5d53bb656d3afdbc6c5af816e0802bcfa42dbdc1c3"
+checksum = "16a1cfa75cc186dd73d5818e510e042e40927bccc9c236b061cea97e1eb08029"
 dependencies = [
- "base64",
+ "base64 0.23.1",
  "bytes",
  "encoding_rs",
  "futures-core",
@@ -1375,9 +1420,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.43"
+version = "0.23.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0283386ce02abc0151e1761d08802dfe86c173b0b494af5cbc086574e453da06"
+checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
 dependencies = [
  "aws-lc-rs",
  "once_cell",
@@ -1472,6 +1517,12 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
 [[package]]
 name = "sec1"
 version = "0.8.1"
@@ -1630,9 +1681,9 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
 [[package]]
 name = "smallvec"
-version = "1.16.0"
+version = "1.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b9be42f50aa861c555654aa3a37f52f4b1074bacf4e48fe0ef7fa584e80f1f0f"
+checksum = "ba467056f1b547ed52077911161fc86985becbc60e8e1857c8a144dab0def891"
 
 [[package]]
 name = "socket2"
@@ -1699,13 +1750,13 @@ dependencies = [
 
 [[package]]
 name = "synstructure"
-version = "0.13.2"
+version = "0.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn 3.0.5",
 ]
 
 [[package]]
@@ -1767,18 +1818,9 @@ dependencies = [
 
 [[package]]
 name = "tinyvec"
-version = "1.13.2"
+version = "1.13.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4cf0ded5c4e56918d8f8a339e1bb67d038d3bc6d144ac407904015ba2e4cde9b"
-dependencies = [
- "tinyvec_macros",
-]
-
-[[package]]
-name = "tinyvec_macros"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee"
 
 [[package]]
 name = "tokio"
@@ -2190,13 +2232,13 @@ dependencies = [
 
 [[package]]
 name = "yoke-derive"
-version = "0.8.2"
+version = "0.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+checksum = "33811428bee40dbceb6d545e95754741d17a6aef9a4849f0fd62e2ba4f412a78"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn 3.0.5",
  "synstructure",
 ]
 
@@ -2211,13 +2253,13 @@ dependencies = [
 
 [[package]]
 name = "zerofrom-derive"
-version = "0.1.7"
+version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.119",
+ "syn 3.0.5",
  "synstructure",
 ]
 

{tx_engine-0.11.0 → tx_engine-0.11.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "chain-gang"
-version = "0.11.0"
+version = "0.11.2"
 description = "This is a library that enables monitoring of multiple blockchains (BTC, BCH, BSV)."
 repository = "https://github.com/nchain-innovation/chain-gang"
 homepage = "https://github.com/nchain-innovation/chain-gang"

{tx_engine-0.11.0 → tx_engine-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tx_engine
-Version: 0.11.0
+Version: 0.11.2
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11

{tx_engine-0.11.0 → tx_engine-0.11.2}/docs/README.md

@@ -36,6 +36,7 @@ Index for **chain-gang** (Rust library) and **tx-engine** (Python bindings).
 | [README-chain-gang.md](README-chain-gang.md) | Crate overview, feature flags, installation |
 | [BIP-32.md](BIP-32.md) | HD wallets — BIP-32/39/44, `HdWallet`, watch-only `xpub`, Rust + Python |
 | [Chronicle.md](Chronicle.md) | Same Chronicle spec; Rust examples use `chain_gang::chronicle` |
+| [Regtest.md](Regtest.md) | **Regtest guide** — running a node, `RpcInterface`, P2P, and the constants |
 | [docs.rs](https://docs.rs/chain-gang) | Generated Rust API (`chain_gang::chronicle`, `Tx::validate_at_height`, etc.) |
 
 ## Development and releases

tx_engine-0.11.2/docs/Regtest.md

@@ -0,0 +1,150 @@
+# Regtest
+
+Regtest is a private chain you run yourself: blocks are mined on demand at minimum
+difficulty, coins are worthless, and nothing leaves your machine. It is the natural
+place to test anything that spends, because the alternative is testnet coins,
+outbound network access, and waiting on a public chain.
+
+chain-gang reaches regtest through two independent paths:
+
+| | type | what it needs |
+|---|---|---|
+| **Chain queries** — balances, UTXOs, broadcast | [`RpcInterface`](https://docs.rs/chain-gang/latest/chain_gang/interface/rpc_interface/struct.RpcInterface.html) | the node's JSON-RPC port, and credentials |
+| **P2P** — messages, headers, blocks | [`Peer`](https://docs.rs/chain-gang/latest/chain_gang/peer/struct.Peer.html) with `Network::BSV_Regtest` | the node's P2P port |
+
+`WocInterface` cannot: WhatsOnChain is a public explorer, and a private chain has
+nothing for it to index. Asking it for regtest returns an error rather than
+guessing.
+
+## Starting a node
+
+```bash
+docker run -d --name regtest -p 18443:18443 -p 18444:18444 \
+  bitcoinsv/bitcoin-sv:latest \
+  bitcoind -regtest -server -listen=1 -bind=0.0.0.0:18444 \
+    -rpcbind=0.0.0.0 -rpcallowip=0.0.0.0/0 -rpcport=18443 \
+    -rpcuser=cguser -rpcpassword=cgpass \
+    -minminingtxfee=0.000005 -printtoconsole
+```
+
+Two of those are easy to get wrong:
+
+* **`-minminingtxfee` is mandatory.** Without it `bitcoind` refuses to start, with
+  `Mandatory policy parameter is not set`. The container exits and the only trace
+  is in `docker logs`.
+* **`-listen=1` is needed for P2P.** RPC on 18443 works without it; a `Peer`
+  connection to 18444 will not.
+
+Then mine enough blocks for a spendable coinbase — 101, since coinbase outputs
+mature after 100:
+
+```bash
+ADDR=$(bitcoin-cli -regtest getnewaddress)
+bitcoin-cli -regtest generatetoaddress 101 "$ADDR"
+```
+
+## Chain queries
+
+```rust
+use chain_gang::interface::{BlockchainInterface, RpcInterface};
+use chain_gang::network::Network;
+
+let node = RpcInterface::new("127.0.0.1:18443", "cguser", "cgpass", Network::BSV_Regtest);
+
+node.status().await?;                       // getblockchaininfo
+let balance = node.get_balance(&address).await?;
+let utxos = node.get_utxo(&address).await?;
+let txid = node.broadcast_tx(&tx).await?;   // sendrawtransaction
+```
+
+A bare `host:port` is treated as `http://`; pass a full URL for `https`. Credentials
+go to whatever host is configured, as HTTP basic auth on every call, so point this
+only at a node you control.
+
+### The node must be watching the address
+
+`get_balance` and `get_utxo` go through `listunspent`, which reports only what the
+node's own wallet tracks. **An address the node knows nothing about reads as zero,
+with no error** — the node is answering truthfully about a wallet that has never
+heard of it. The symptom is an empty balance from a node that is plainly reachable,
+which looks like a bug in your code.
+
+Either ask the node to watch it:
+
+```rust
+node.import_address(&address, false).await?;   // false: skip the rescan
+```
+
+or do the same from the command line:
+
+```bash
+bitcoin-cli -regtest importaddress "<address>" "" false
+```
+
+`rescan` asks the node to walk the chain for the address's history and blocks the
+RPC connection until it finishes. Pass `false` when the address has no history yet —
+which on a fresh chain is always — and `true` when importing an address that has
+already been paid.
+
+Nothing in `RpcInterface` imports for you. Doing so would mean the library managing
+the node's wallet and deciding when to rescan, which belongs to whoever runs the
+node.
+
+## P2P
+
+```rust
+use chain_gang::messages::{Version, NODE_BITCOIN_CASH, PROTOCOL_VERSION};
+use chain_gang::network::Network;
+use chain_gang::peer::{Peer, SVPeerFilter};
+use chain_gang::util::{rx::Observable, secs_since};
+
+let version = Version {
+    version: PROTOCOL_VERSION,
+    services: NODE_BITCOIN_CASH,
+    timestamp: secs_since(std::time::UNIX_EPOCH) as i64,
+    user_agent: "my-app".to_string(),
+    ..Default::default()
+};
+
+let peer = Peer::connect(ip, 18444, Network::BSV_Regtest, version, SVPeerFilter::new(0));
+peer.connected_event().poll_timeout(Duration::from_secs(15))?;
+```
+
+There are no DNS seeds on a private chain, so `Network::BSV_Regtest.seeds()` is
+empty by design: connect to an address you already know.
+
+**A node bans a peer that sends a bad message start.** If the magic bytes are wrong
+the first attempt is dropped and every later attempt is refused without being
+looked at, whatever it sends — so a wrong constant looks identical to a network
+problem. Clear it with `bitcoin-cli -regtest clearbanned`, or restart the node,
+before trying again.
+
+## What regtest is, in constants
+
+| | value | note |
+|---|---|---|
+| P2P port | 18444 | RPC is 18443 |
+| Magic bytes | `da b5 bf fa` | inherited from Bitcoin Cash, **not** Bitcoin Core's `fa bf b5 da` |
+| Genesis hash | `0f9188f1…466e2206` | differs from testnet in `bits` and `nonce`: regtest mines at minimum difficulty |
+| Address prefixes | `0x6f` / `0xc4` | the same as testnet |
+| Extended keys | `tpub` / `tprv` | the same as testnet |
+| WIF prefix | `0xef` | the same as testnet |
+| DNS seeds | none | a private chain has nothing to discover |
+| Chronicle activation | block 0 | as for STN, a private chain runs current rules from its first block |
+
+Because the address and key prefixes are testnet's, anything you already have on
+disk for testnet — addresses, WIFs, extended keys — works unchanged on regtest.
+
+## The tests in this repository
+
+`tests/regtest_p2p.rs` drives a real handshake against a node and is `#[ignore]`d,
+because CI has no node to talk to:
+
+```bash
+cargo test --test regtest_p2p -- --ignored --test-threads=1
+```
+
+It exists because a wrong `magic` value cannot be caught any other way: the magic
+bytes are not part of the genesis hash, so every offline test passes while no node
+will speak to you. That is not hypothetical — `BSV_Regtest` shipped with Bitcoin
+Core's magic until this test was written.

{tx_engine-0.11.0 → tx_engine-0.11.2}/docs/Releases.md

@@ -57,3 +57,5 @@
 * v0.10.0 - `Tx` and `Block` now implement `serde::Serialize`/`Deserialize`, encoding as their raw wire-format byte stream (matching `Serializable::write`/`read`); added a reusable `serde_bytes` helper in `util::serdes`
 * v0.10.1 - crates.io publication: added package metadata (`repository`, `homepage`, `documentation`), a CI job that publishes to crates.io on tagged releases, README/rustdoc improvements (docs.rs readme, working links, MIT license), and full public-API documentation guarded by `#![warn(missing_docs)]`
 * v0.11.0 - **Breaking.** Regtest support: `Network::BSV_Regtest` and a JSON-RPC `RpcInterface` for talking to a local node, verified against a bitcoin-sv regtest node. `Peer::id` is now `PeerId` rather than `snowflake::ProcessUniqueId`; `generate_wif` takes a `Network` instead of its name and returns `Result`, where an unrecognised name used to yield a mainnet key; `decode_base58_checksum`, `ExtendedKey::decode` and `WocInterface` return errors where they used to panic; unconfirmed UTXOs report `UNCONFIRMED_HEIGHT` (-1) through every interface, WhatsOnChain's own `height: 0` being translated on the way in; `Block::validate` enforces the Chronicle activation height it already had; `ChainGangError` no longer discards the message of `ResponseError`, `JSONParseError` and `InvalidOperation`. `serde` and `serde_json` are ordinary dependencies, so `--no-default-features` compiles. Dropped `typenum`, `lazy_static` and `snowflake`; moved `async-mutex` to `async-lock` and `base58` to `bs58`. CI gained clippy, a feature matrix and Python lint gates
+* v0.11.1 - `RpcInterface::import_address` asks the node to watch an address, opt-in because whether to touch the node's wallet is the caller's decision; a JSON-RPC method answering `"result": null`, as `importaddress` does, is now success rather than "returned neither a result nor an error"; documented that balance and UTXO queries see only what the node's wallet tracks, so an unwatched address reads as zero with no error, in both the Rust and Python clients; added [Regtest.md](Regtest.md), a guide to running against a private chain; cleared the rustdoc warnings
+* v0.11.2 - Two robustness fixes. Additive API only, so cargo treats this as a compatible upgrade: `util::read_exact_vec`, `util::bounded_capacity`, `util::MAX_PREALLOC_ELEMENTS` and `script::stack::pop_bigint_checked_minimal` are new, and nothing existing changes shape. Wire-format reads no longer size an allocation from a sender-controlled length prefix: 17 sites across `tx_in`/`tx_out`, `tx`, `block`, `merkle_block`, `filter_add`/`filter_load`, `protoconf`/`createstrm`, `version` and `reject` now grow a buffer as bytes arrive via `util::read_exact_vec`, or cap a speculative reserve with `util::bounded_capacity`, so a 27-byte transaction declaring a 2^48-byte script is an error rather than an allocation-failure `SIGABRT` that a consumer cannot catch. Script evaluation applies minimal *number* encoding only where a stack item is decoded as a number, not to every push: a 33-byte public key or a 20-byte hash ending `0x00` or `0x80` is ordinary data, and rejecting it as `Non-minimal push data` refused roughly 1 in 128 standard P2PKH spends. Minimal-*push* (BIP-62) is unchanged, and minimal-number enforcement now also covers the bigint arithmetic operands it previously missed

{tx_engine-0.11.0 → tx_engine-0.11.2}/python/src/tx_engine/interface/rpc_interface.py

@@ -7,6 +7,17 @@ network -> main/test mapping in sync across both when either changes.
 
 That includes the unconfirmed-UTXO height, reported as UNCONFIRMED_HEIGHT on
 both sides.
+
+The node must be watching the addresses you ask about. Balance and UTXO queries
+go through listunspent, which reports only what the node's own wallet tracks, so
+an address the node knows nothing about reads as zero with no error. On a fresh
+node, import each address once:
+
+    bitcoin-cli -regtest importaddress "<address>" "" false
+
+The false skips the rescan, which is what you want on a chain with no history.
+This client does not import for you: that would mean managing the node's wallet
+and deciding when to rescan, which belongs to whoever runs the node.
 """
 from typing import Dict, List, Any
 import logging
@@ -150,7 +161,11 @@ class RPCInterface(BlockchainInterface):
         return self._get_history(address)
 
     def get_utxo(self, address):
-        """Return ordered list of UTXOs for this address"""
+        """Return ordered list of UTXOs for this address
+
+        Empty for an address the node's wallet does not track; see the module
+        docstring.
+        """
         unspent_address = self.get_unspent(address)
         block_count = self.get_block_count()
 
@@ -167,7 +182,11 @@ class RPCInterface(BlockchainInterface):
         return response
 
     def get_balance(self, address, confirmations=6):
-        """Return the confirmed and unconfirmed balance associated with this address"""
+        """Return the confirmed and unconfirmed balance associated with this address
+
+        Reads zero for an address the node's wallet does not track; see the
+        module docstring.
+        """
         unspent_address = self.get_unspent(address)
         # Convert each amount before summing, so the total does not accumulate
         # the float error of the individual amounts