Class BSV::Wallet::Client ¶

Inherits: Object Includes: BSV::Identity, BSV::Network, BSV::Transaction, BSV::Wallet::Client::Authentication, BSV::Wallet::Client::Crypto, BSV::Wallet::Interface::BRC100

BRC-100 wallet implementation.

All 28 BRC-100 methods are implemented directly — the 9 crypto operations are inlined here, with substrate delegation wired at the top of each method. No inheritance; behaviour is fully self-contained.

@example Create a simple transaction

client = BSV::Wallet::Client.new(private_key)
result = client.create_action({
  description: 'Pay invoice',
  outputs: [{ locking_script: '76a914...88ac', satoshis: 1000,
              output_description: 'Payment' }]
})

Attributes¶

broadcast_queue [R] ¶

• @return [BroadcastQueue] the broadcast queue used to dispatch transactions

broadcaster [R] ¶

• @return [#broadcast, nil] the optional broadcaster (responds to #broadcast(tx))

chain_data_source [R] ¶

• @return [#current_height, #get_block_header, #fetch_utxos, #fetch_transaction, nil] optional chain data source for SPV and block header lookups

key_deriver [R] ¶

• @return [KeyDeriver] the underlying key deriver

network [R] ¶

• @return [String] the network ('mainnet' or 'testnet')

proof_store [R] ¶

• @return [ProofStore] the merkle proof persistence store

storage [R] ¶

• @return [Store] the underlying persistence adapter

substrate [R] ¶

• @return [Interface, nil] the optional substrate for remote wallet delegation

Public Instance Methods¶

abort_action(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

acquire_certificate(args, originator: = nil) ¶

--- Identity and Certificate Management (codes 17-22) --- - @raise [UnsupportedActionError]

balance(basket: = nil) ¶

Returns the total spendable satoshis across all baskets (or a named basket). - @param basket [String, nil] the basket to total, or +nil+ for all baskets - @return [Integer] sum of all spendable output values

broadcast_enabled?() ¶

Returns true when broadcast is available. - @return [Boolean]

create_action(args, originator: = nil) ¶

--- Transaction Operations (codes 1-7) --- - @raise [UnsupportedActionError]

create_hmac(args, originator: = nil) ¶

Creates an HMAC-SHA256 using a derived symmetric key. - @option args - @option args - @option args - @option args - @param args [Hash] - @return [Hash] { hmac: Array }

create_signature(args, originator: = nil) ¶

Creates an ECDSA signature using a derived private key. - @option args - @option args - @option args - @option args - @option args - @param args [Hash] - @return [Hash] { signature: Array } DER-encoded signature as byte array

decrypt(args, originator: = nil) ¶

Decrypts ciphertext using AES-256-GCM with a derived symmetric key. - @option args - @option args - @option args - @option args - @param args [Hash] - @return [Hash] { plaintext: Array }

discover_by_attributes(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

discover_by_identity_key(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

encrypt(args, originator: = nil) ¶

Encrypts plaintext using AES-256-GCM with a derived symmetric key. - @option args - @option args - @option args - @option args - @param args [Hash] - @return [Hash] { ciphertext: Array }

get_header_for_height(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

get_height(args = {}, originator: = nil) ¶

--- Blockchain and Network Data (codes 25-28) --- - @raise [UnsupportedActionError]

get_network(args = {}, originator: = nil) ¶

• @raise [UnsupportedActionError]

get_public_key(args, originator: = nil) ¶

Returns a derived or identity public key. - @option args - @option args - @option args - @option args - @option args - @param args [Hash] - @return [Hash] { public_key: String } hex-encoded compressed public key

get_version(args = {}, originator: = nil) ¶

• @raise [UnsupportedActionError]

initialize(key, storage: = Store::File.new, network: = 'mainnet', proof_store: = nil, http_client: = nil, fee_estimator: = nil, coin_selector: = nil, change_generator: = nil, broadcaster: = nil, broadcast_queue: = nil, substrate: = nil, chain_data_source: = nil, allow_memory_store: = false) ¶

• @param key [BSV::Primitives::PrivateKey, String, KeyDeriver] signing key
• @param storage [Store] persistence adapter (default: Store::File.new)
• @param allow_memory_store [Boolean] set +true+ to suppress the MemoryStore safety guard
• @param network [String] 'mainnet' (default) or 'testnet'
• @param proof_store [ProofStore, nil] merkle proof store (default: LocalProofStore backed by storage)
• @param http_client [#request, nil] injectable HTTP client for certificate issuance
• @param fee_estimator [FeeEstimator, nil] optional fee estimator
• @param coin_selector [CoinSelector, nil] optional coin selector
• @param change_generator [ChangeGenerator, nil] optional change generator
• @param broadcaster [#broadcast, nil] optional broadcaster
• @param broadcast_queue [BroadcastQueue, nil] optional broadcast queue; defaults to BroadcastQueue::Inline
• @param substrate [Interface, nil] optional remote wallet substrate
• @param chain_data_source [#current_height, #get_block_header, #fetch_utxos, #fetch_transaction, nil] optional chain data source for SPV and block header lookups
• @return [Client] a new instance of Client

internalize_action(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

is_authenticated(args = {}, originator: = nil) ¶

Checks whether the user is authenticated. - @return [Hash] { authenticated: Boolean }

list_actions(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

list_certificates(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

list_outputs(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

prove_certificate(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

relinquish_certificate(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

relinquish_output(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

reveal_counterparty_key_linkage(args, originator: = nil) ¶

Reveals counterparty key linkage to a verifier (BRC-69 Method 1). - @option args - @option args - @param args [Hash] - @raise [InvalidParameterError] - @return [Hash] with :prover, :verifier, :counterparty, :revelation_time, :encrypted_linkage, :encrypted_linkage_proof

reveal_specific_key_linkage(args, originator: = nil) ¶

Reveals specific key linkage for a particular interaction (BRC-69 Method 2). - @option args - @option args - @option args - @option args - @param args [Hash] - @raise [InvalidParameterError] - @return [Hash] with :prover, :verifier, :counterparty, :protocol_id, :key_id, :encrypted_linkage, :encrypted_linkage_proof, :proof_type

set_wallet_change_params(count:, satoshis:) ¶

Configures the target UTXO pool parameters for change generation. - @param count [Integer] desired number of spendable UTXOs in 'default' basket - @param satoshis [Integer] desired average value per UTXO in satoshis - @raise [InvalidParameterError]

sign_action(args, originator: = nil) ¶

• @raise [UnsupportedActionError]

spendable_balance(basket: = nil) ¶

Returns the total satoshis of outputs the wallet can automatically spend. - @param basket [String, nil] restrict to a named basket, or +nil+ for all - @return [Integer] total auto-spendable satoshis

sync_utxos() ¶

Discovers UTXOs on-chain for the wallet's identity address and imports any that are not already in local storage.

Requires either a substrate or a chain_data_source. When both are present, the substrate takes priority. - @raise [UnsupportedActionError] when neither substrate nor chain_data_source is set - @raise [WalletError] when a fetched transaction has an out-of-bounds tx_pos - @return [Integer] number of UTXOs imported (0 if nothing new)

utxo_pool(name:, target_count: = 20, target_satoshis: = 10_000, low_water_mark: = 0.5) ¶

Creates a UTXO pool for high-frequency transaction pre-allocation. - @param name [String] pool identifier (basket will be +"pool:"+) - @param target_count [Integer] desired number of UTXOs (default 20) - @param target_satoshis [Integer] desired satoshis per UTXO (default 10_000) - @param low_water_mark [Float] replenishment trigger fraction (default 0.5) - @raise [WalletError] - @return [LocalPool]

verify_hmac(args, originator: = nil) ¶

Verifies an HMAC-SHA256 using a derived symmetric key. - @option args - @option args - @option args - @option args - @option args - @param args [Hash] - @raise [InvalidHmacError] if the HMAC does not match - @return [Hash] { valid: true }

verify_signature(args, originator: = nil) ¶

Verifies an ECDSA signature using a derived public key. - @option args - @option args - @option args - @option args - @option args - @option args - @option args - @param args [Hash] - @raise [InvalidSignatureError] if the signature does not verify - @return [Hash] { valid: true }

wait_for_authentication(args = {}, originator: = nil) ¶

Waits until the user is authenticated. - @return [Hash] { authenticated: true }