Crate stackmate

Stackmate

A set of composite functions that uses rust-bitcoin & bdk and exposes a simplified C interface to build descriptor based wallets.

Workflow

1. Use key functions generate_master/import_master and derive a parent key at a hardened path with a variable account number. Currently purpose is fixed at 84’ for Native-native only.
2. Use extended key format to create string policies. More on policies.
3. Use the compile function to get a general descriptor (keys ending in /*).
4. Use wallet functions by passing your descriptor and node_address as primary inputss.
5. Electrum over ssl is the recommended way to interact with the wallet with format of ‘ssl://electrum.blockstream.info:60002’.
6. “default” can be used as a string for the node_address which will use Blockstream servers. Recommened client to use tor with this setting.
7. Bitcoin-core RPC is supported but not advised unless on desktop where a node is connected to locally.
8. Core RPC (currently) requies node_address to follow the format of ‘https://address:port?auth=username:password’.
9. Outputs of each function are JSON stringified native structs specified as ‘FFI Outputs’ in under module documentation.
10. Use every function in combination with cstring_free to free their output pointers. This will keep things safe.

Building a transaction

1. Build a transaction with a default fixed fee of 1000 sats
2. Get weight of the transaction for a given descriptor
3. Use get absolute fee to get the fee needed to be paid for the transaction given variable fee rate and fixed weight.
4. Build transaction with the absolute fee chosen, sign & broadcast.

Tor controls are in BETA. Use with caution.

Modules

e

key

network

wallet

Functions

broadcast_tx^⚠

Broadcasts a signed transaction to a remote node.

build_tx^⚠

Builds a transaction for a given descriptor wallet. Supports sending to multiple outputs. TxOutputs have to be provided as a stringified JSON array.

check_xpub^⚠

Checks if an extended public key is valid. Do not use the key source while checking an xpub i.e. remove [fingerprint/derivation/path/values] and only provide the xpub/tpub.

compile^⚠

Compiles a policy into a descriptor of the specified script type. Use wpkh for a single signature Native native wallet (default). Use wsh for a scripted Native native wallet.

cstring_free^⚠

After using any other function, pass the output pointer into cstring_free(ptr: *mut c_char) to clear memory. ALWAYS use this in combination with any other function. Failure to do so can lead to memory bugs.

days_to_blocks^⚠

Convert days to bitcoin blocks as height. Does not consider the current block height. Add to get_height to get the expected block height after the given time in days.

decode_psbt^⚠

Decodes a PSBT and returns all outputs of the transaction and total size. “miner” is used in the ‘to’ field of an output to indicate fee.

derive_to_path^⚠

Derives child keys from a master xprv. Allows passing a custom derivation path string.

derive_wallet_account^⚠

Derives hardened child keys from a master xprv. Follows the BIP32 standard of m/purpose’/network’/account’. Network path is inferred from the master xprv.

estimate_network_fee^⚠

Gets the current network fee (in sats/vbyte) for a given confirmation target.

fee_absolute_to_rate^⚠

Converts a given absolute_fee (in sats) to fee rate (in sats/vbyte); given some transaction weight.

fee_rate_to_absolute^⚠

Converts a given fee_rate (in sats/vbyte) to absolute fee (in sats); given some transaction weight.

generate_master^⚠

Generates a mnemonic phrase of a given length. Defaults to 24 words. A master xprv is created from the mnemonic and passphrase.

get_address^⚠

Gets a new address for a descriptor wallet at a given index. Client must keep track of address indexes and ENSURE prevention of address reuse.

get_height^⚠

Gets the current block height.

get_weight^⚠

Gets the weight of a transaction built with a given descriptor.

import_master^⚠

Creates a master xprv given a mnemonic and passphrase.

policy_id^⚠

Gets the policy id from a given descriptor.

shared_secret^⚠

Computes a Diffie Hellman shared secret

sign_message^⚠

Signs a message using schnorr signature scheme

sign_tx^⚠

Signs a PSBT with a descriptor. Can only be used with descriptors containing private key(s).

sync_balance^⚠

Syncs to a remote node and fetches balance of a descriptor wallet.

sync_history^⚠

Syncs to a remote node and fetches history of a descriptor wallet.

tor_progress^⚠

Get bootstrap progress from tor daemon. Wait ~1s after calling tor_start() before calling this. BETA: Careful with this.

tor_start^⚠

Switch on tor daemon. BETA: Careful with this.

tor_stop^⚠

Shutdown tor daemon. BETA: Careful with this.

verify_signature^⚠

Signs a message using schnorr signature scheme Private key extracted from extended private key.

xprv_to_ec^⚠

Converts an xprv into EC keys with XOnlyPub..