pyrxd.btc_wallet — BTC-side wallet

Bitcoin wallet tooling for the Gravity Taker.

Public API

BtcKeypair — keypair with all 4 address formats BtcUtxo — UTXO descriptor BtcPaymentTx — signed transaction result generate_keypair — generate a fresh keypair from CSPRNG keypair_from_wif — load keypair from WIF (testing/recovery) build_payment_tx — build+sign a 1-input segwit-v0 payment tx validate_btc_address — validate a mainnet Bitcoin address string validate_satoshis — validate a satoshi amount

class pyrxd.btc_wallet.BtcKeypair[source]

Bases: object

A Bitcoin keypair with addresses in all 4 Gravity-supported formats.

Private key is stored as PrivateKeyMaterial (never logs/repr leaks).

network

bech32 HRP ("bc" mainnet, "tb" testnet/signet, "bcrt" regtest, or any custom HRP). Defaults to "bc".

Type:

str

__init__(_privkey, pubkey_bytes, p2pkh_address, p2wpkh_address, p2sh_p2wpkh_address, p2tr_address, pkh, p2sh_hash, p2tr_output_key, network='bc')
Parameters:
Return type:

None

network: str = 'bc'
unsafe_wif()[source]

Export WIF. Named ‘unsafe’ to be visible in code review.

Uses the WIF version byte for self.network (0x80 for mainnet, 0xEF for testnet/signet/regtest).

Return type:

str

pubkey_bytes: bytes
p2pkh_address: str
p2wpkh_address: str
p2sh_p2wpkh_address: str
p2tr_address: str
pkh: bytes
p2sh_hash: bytes
p2tr_output_key: bytes
class pyrxd.btc_wallet.BtcPaymentTx[source]

Bases: object

Result of build_payment_tx.

__init__(tx_hex, txid, fee_sats, change_sats, input_type, output_type)
Parameters:

  • tx_hex (str)

  • txid (str)

  • fee_sats (int)

  • change_sats (int)

  • input_type (str)

  • output_type (str)

Return type:

None

tx_hex: str
txid: str
fee_sats: int
change_sats: int
input_type: str
output_type: str
class pyrxd.btc_wallet.BtcUtxo[source]

Bases: object

A Bitcoin UTXO to spend.

__init__(txid, vout, value)
Parameters:
Return type:

None

txid: str
vout: int
value: int
pyrxd.btc_wallet.build_payment_tx(keypair, utxo, to_hash, to_type, amount_sats, fee_sats, input_type='p2wpkh', change_address=None)[source]

Build and sign a 1-input Bitcoin payment transaction for the Gravity Taker.

Exactly 1 input is required — this is a covenant structural constraint. input_type controls whether the input is native segwit (empty scriptSig) or wrapped segwit (23-byte scriptSig with P2WPKH redeem push).

Parameters:
Return type:

BtcPaymentTx

pyrxd.btc_wallet.generate_keypair(network='bc')[source]

Generate a fresh Bitcoin keypair using CSPRNG.

Uses secure_scalar_mod_n() for the private key — explicit range check, rejection sampling, never Math.random(). Matches JS btc_wallet.js::generateKeypair() audit-hardened version.

Parameters:

network (str) – bech32 HRP for address serialization. "bc" (default) for mainnet, "tb" for testnet/signet, "bcrt" for regtest, or any custom HRP.

Return type:

BtcKeypair

pyrxd.btc_wallet.keypair_from_wif(wif, network='bc')[source]

Load keypair from WIF string (for testing/recovery).

Parameters:

  • wif (str) – WIF-encoded private key.

  • network (str) – bech32 HRP for address serialization (see generate_keypair). Note: this controls OUTPUT address/WIF encoding only; the input WIF is decoded regardless of its version byte.

Return type:

BtcKeypair

pyrxd.btc_wallet.validate_btc_address(address)[source]

Validate a mainnet Bitcoin address.

Rejects path traversal, query injection, and anything outside the two recognized mainnet address shapes (Base58Check P2PKH/P2SH and bech32/bech32m).

Raises:

ValidationError – if the address is not a recognized mainnet format.

Parameters:

address (str)

Return type:

None

pyrxd.btc_wallet.validate_satoshis(value, name='value')[source]

Validate a satoshi amount.

Rules:

  • Must be a plain int (not bool, not float).

  • Must be > 0.

  • Must not exceed max BTC supply (21M BTC = 2.1e15 sats).

Raises:

ValidationError – on any violation.

Parameters:
Return type:

None