YuBTC - put your money in your head.
Donations
=========
If YuBTC was useful, tips are welcome:
1KCp7GLkZpTBVCwrMfaAaWqyTWRAXYDpKq
A console BTC client. Downloads nothing, stores nothing on disk: private keys
are derived from a seed on each invocation.
Commands:
newseed Generate a new seed.
address Show the native (P2PKH) address.
balance Show the balance.
send Send BTC to an address.
dumpprivkey Show the private key in WIF format.
pushtx Broadcast a pre-signed raw transaction from stdin.
Network providers
=================
By default every command that talks to the network hits
blockchain.info. Switch providers with `--provider NAME`:
$ yubtc balance --provider blockstream
$ yubtc balance --provider mempool.space
Registered providers:
blockchain.info blockchain.info's public API (default)
blockstream blockstream.info's Esplora API
mempool.space mempool.space's Esplora API
The blockstream and mempool.space backends share the same JSON schema
(Esplora); only the base URL differs. Confirmations are computed
locally from each UTXO's block height and the chain tip, so a slow
provider can't break the gap scan.
An unknown `--provider` name is rejected by click before any network
work runs -- no silent fallback to the default.
Retries and automatic failover (v0.3)
-------------------------------------
Every HTTP request is retried up to `--retries N` times (default 3;
`0` = a single attempt) with a short capped exponential backoff
(0.5 s -> 1 s -> 2 s). Retried: connection errors, timeouts, server
faults (5xx), request timeouts (408) and rate limiting (429 -- a sane
`Retry-After` of up to 30 s is honoured). Not retried: every other 4xx
(bad address, rejected transaction, ...) and broken response bodies --
resending those would only duplicate the failure. After the retries
run out you see the same error a single attempt would have produced.
On top of that, `--provider auto` opts into failover across the three
registered providers -- they are tried in registry order
(blockchain.info -> blockstream -> mempool.space) per request, the
first one to answer wins and is remembered for the rest of the
command run (the wallet is stateless: nothing is stored between
runs). If every provider fails, the error lists what was tried:
yubtc: all backends failed: blockchain.info: ...; blockstream: ...; mempool.space: ...
The default provider stays `blockchain.info` -- `auto` and the retry
loop are opt-in resilience, not a change of data source.
Key derivation
==============
yuBTC supports two key derivation paths, gated on whether a passphrase
is set:
* **No passphrase** (the default): the legacy path. For each nonce the
32-byte secret is `sha256(keccak256(blake2b256(nonce ‖ seed)))`. Each
nonce is independent -- reusing a seed with the same passphrase at a
different nonce gives a different address, but two different seeds at
the same nonce are also independent. The wallet is compatible with
the original yubtc behaviour: an old wallet with no passphrase opens
to the same addresses as it always did.
* **With passphrase**: BIP-39 + BIP-32 + BIP-44. The mnemonic is
NFKD-normalised, stretched through PBKDF2-HMAC-SHA512 (2048 iter,
salt `b'mnemonic' + passphrase`, 64 bytes) to produce the BIP-39
seed. The BIP-32 master is derived from that seed, and the final
32-byte key is the leaf at the **main path**:
m/44'/0'/0'/0/<nonce>
(`purpose / coin_type / account / chain / address_index`).
Same mnemonic + passphrase + nonce yields the same address in Trezor,
Ledger, Electrum, etc. The wallet walks only the receiving chain
(`chain = 0`) and uses the next unused index of the same chain for
cashback -- a single-account, single-chain tree, in line with the
wallet's no-storage rescan-on-every-run model. A full BIP-44 walk
would be O(N×M) per scan with no upside for this use case.
Private key formats
===================
`dumpprivkey` returns a **WIF (Wallet Import Format)** string --
compressed, mainnet, base58check-encoded. Concretely, the bytes are:
0x80 || <32-byte secret> || 0x01
The trailing `0x01` is the compressed-pubkey flag; the prefix `0x80`
is the mainnet private-key prefix. The whole 34-byte payload is then
base58check-encoded so a typo in the WIF is detected by checksum, not
by silently signing for the wrong key.
Only compressed WIF is supported on import (`privwif2privkey`); an
uncompressed WIF (33-byte body, no trailing `0x01`) raises
`'uncompressed wif not supported'` rather than silently downgrading.
Inside the wallet the privkey is held as a 32-byte secret. yubtc does
not store anything, so the WIF is the only thing to keep between
sessions -- paste it into another BIP-39-aware wallet to recover.
Usage from a checkout (no installation needed):
$ pip install -r requirements.txt
$ ./yubtc newseed
The ./yubtc launcher runs the code straight from src/, so only the third-party
dependencies have to be installed, not YuBTC itself. Run the tests the same way:
$ pip install 'pytest>=7.0'
$ pytest
Alternatively, install it as a real package to get a yubtc command on PATH:
$ pip install .
Examples:
$ yubtc newseed
place fabric recall try between menu brush there around oil wing busy summer brush record
Address: 14bUA6ioEkUVCx8cU2zvjpK4KBVHxvEnt3
$ yubtc dumpprivkey
seed:
Address: 14bUA6ioEkUVCx8cU2zvjpK4KBVHxvEnt3
L25VQR3RxMNhAVgehEqGjMWXvNHDc4bdmPraiwoEoNQr4UVviz2n
$ yubtc balance
seed:
14bUA6ioEkUVCx8cU2zvjpK4KBVHxvEnt3: 0.99998552 BTC
$ yubtc send -c 0 -f 0.00001234 14bUA6ioEkUVCx8cU2zvjpK4KBVHxvEnt3 ALL
seed:
Address: 14bUA6ioEkUVCx8cU2zvjpK4KBVHxvEnt3
send 0.99997318 BTC to 14bUA6ioEkUVCx8cU2zvjpK4KBVHxvEnt3 (cashback=0.00000000, fee=0.00001234, txsize=192)? n