Class BSV::Wallet::Substrates::HTTPWalletJSON ¶

Inherits: Object Includes: BSV::Wallet::Interface::BRC100

JSON-RPC-style HTTP substrate implementing BRC-100.

Dispatches all 28 BRC-100 methods as JSON POST requests to {base_url}/v1/wallet/{methodNameInCamelCase}. Request bodies are deep-converted from snake_case to camelCase via {BSV::WireFormat.to_wire}; responses are deep-converted back via {BSV::WireFormat.from_wire}.

This substrate does NOT use the BRC-103 binary frame codec — it speaks plain JSON over HTTP, matching the Go SDK HTTPWalletJSON implementation.

@example

client = BSV::Wallet::Substrates::HTTPWalletJSON.new(
  base_url: 'https://wallet.example.com',
  headers: { 'Authorization' => 'Bearer token' }
)
client.get_network  # => { network: 'mainnet' }

Constants¶

WIRE_METHOD_NAMES ¶

Maps each BRC-100 Ruby method name to its camelCase wire name. authenticated? maps to isAuthenticated — the BRC-100 wire name uses the is_ prefix convention; the Ruby predicate suffix is dropped for the lookup.

Public Instance Methods¶

abort_action(reference:, originator: = nil) ¶

Aborts a transaction that has not yet been finalized. - @raise [NotImplementedError]

acquire_certificate(type:, certifier:, acquisition_protocol:, fields:, serial_number: = nil, revocation_outpoint: = nil, signature: = nil, certifier_url: = nil, keyring_revealer: = nil, keyring_for_subject: = nil, privileged: = false, privileged_reason: = nil, originator: = nil) ¶

Acquires an identity certificate from a certifier or by direct receipt. - @param acquisition_protocol [Symbol] :direct or :issuance - @param fields [Hash{String => String}] certificate field names to values - @raise [NotImplementedError]

authenticated?(originator: = nil) ¶

Checks whether the user is authenticated. - @raise [NotImplementedError] - @return [Boolean]

create_action(description:, input_beef: = nil, inputs: = nil, outputs: = nil, lock_time: = nil, version: = nil, labels: = nil, sign_and_process: = true, accept_delayed_broadcast: = true, trust_self: = nil, known_txids: = nil, return_txid_only: = false, no_send: = false, no_send_change: = nil, send_with: = nil, randomize_outputs: = true, originator: = nil) ¶

Creates a new Bitcoin transaction. - @param description [String] human-readable description (5-50 chars) - @param inputs [Array] optional inputs to consume - :outpoint [String] txid.index being consumed - :unlocking_script [String] hex unlocking script - :unlocking_script_length [Integer] length, if script provided later via {#sign_action} - :input_description [String] what this input consumes (5-50 chars) - :sequence_number [Integer] optional sequence number - @param outputs [Array] optional outputs to create - :locking_script [String] hex locking script - :satoshis [Integer] output value - :output_description [String] what this output represents (5-50 chars) - :basket [String] optional basket name for UTXO tracking - :custom_instructions [String] application-specific context - :tags [Array] output tags for filtering - @raise [NotImplementedError] - @return [Hash] BRC-100 spec-mandated keys: :txid (display-order hex), :tx, :no_send_change, :send_with_results, :signable_transaction

create_hmac(data:, protocol_id:, key_id:, privileged: = false, privileged_reason: = nil, counterparty: = nil, seek_permission: = true, originator: = nil) ¶

Creates an HMAC for the provided data. - @raise [NotImplementedError]

create_signature(protocol_id:, key_id:, data: = nil, hash_to_directly_sign: = nil, privileged: = false, privileged_reason: = nil, counterparty: = nil, seek_permission: = true, originator: = nil) ¶

Creates a digital signature (ECDSA) for data or a pre-computed hash. - @raise [NotImplementedError]

decrypt(ciphertext:, protocol_id:, key_id:, privileged: = false, privileged_reason: = nil, counterparty: = nil, seek_permission: = true, originator: = nil) ¶

Decrypts ciphertext using derived keys. - @raise [NotImplementedError]

discover_by_attributes(attributes:, limit: = 10, offset: = 0, seek_permission: = true, originator: = nil) ¶

Discovers certificates matching specific attribute values. - @param attributes [Hash{String => String}] field name/value pairs to match - @raise [NotImplementedError]

discover_by_identity_key(identity_key:, limit: = 10, offset: = 0, seek_permission: = true, originator: = nil) ¶

Discovers certificates issued to a given identity key. - @raise [NotImplementedError]

encrypt(plaintext:, protocol_id:, key_id:, privileged: = false, privileged_reason: = nil, counterparty: = nil, seek_permission: = true, originator: = nil) ¶

Encrypts plaintext using derived keys. - @raise [NotImplementedError]

get_header_for_height(height:, originator: = nil) ¶

Returns the 80-byte block header at the given height. - @raise [NotImplementedError]

get_height(originator: = nil) ¶

Returns the current blockchain height. - @raise [NotImplementedError]

get_network(originator: = nil) ¶

Returns the network (:mainnet or :testnet). - @raise [NotImplementedError]

get_public_key(identity_key: = false, protocol_id: = nil, key_id: = nil, privileged: = false, privileged_reason: = nil, counterparty: = nil, for_self: = false, seek_permission: = true, originator: = nil) ¶

Retrieves a derived or identity public key. - @param protocol_id [Array(Integer, String)] security level (0-2) and protocol string - @param counterparty [String] public key hex, 'self', or 'anyone' - @raise [NotImplementedError] - @return [Hash] :public_key

get_version(originator: = nil) ¶

Returns the wallet version string. - @raise [NotImplementedError]

initialize(base_url:, http_client: = nil, headers: = {}) ¶

• @param base_url [String] wallet base URL (e.g. 'https://wallet.example')
• @param http_client [#request, nil] injectable HTTP client for testing; must respond to +#request(uri, net_http_request)+. Defaults to +Net::HTTP+.
• @param headers [Hash] additional headers merged into every request
• @return [HTTPWalletJSON] a new instance of HTTPWalletJSON

internalize_action(tx:, outputs:, description:, labels: = nil, seek_permission: = true, originator: = nil) ¶

Internalizes a transaction — labels it, pays outputs to the wallet balance, inserts outputs into baskets, and/or tags them. - @param tx [Array] Atomic BEEF-formatted transaction (byte array) - @param outputs [Array] metadata per output - :output_index [Integer] index within the transaction - :protocol [Symbol] :wallet_payment or :basket_insertion - :payment_remittance [Hash] for payments: { derivation_prefix:, derivation_suffix:, sender_identity_key: } - :insertion_remittance [Hash] for insertions: { basket:, custom_instructions:, tags: } - @raise [NotImplementedError]

list_actions(labels:, label_query_mode: = :any, include_labels: = false, include_inputs: = false, include_input_source_locking_scripts: = false, include_input_unlocking_scripts: = false, include_outputs: = false, include_output_locking_scripts: = false, limit: = 10, offset: = 0, seek_permission: = true, originator: = nil) ¶

Lists transactions matching the specified labels. - @raise [NotImplementedError] - @return [Hash] :total_actions, :actions

list_certificates(certifiers:, types:, limit: = 10, offset: = 0, privileged: = false, privileged_reason: = nil, originator: = nil) ¶

Lists identity certificates filtered by certifier(s) and type(s). - @raise [NotImplementedError]

list_outputs(basket:, tags: = nil, tag_query_mode: = :any, include: = nil, include_custom_instructions: = false, include_tags: = false, include_labels: = false, limit: = 10, offset: = 0, seek_permission: = true, originator: = nil) ¶

Lists spendable outputs in a basket. - @param include [Symbol] nil, :locking_scripts, or :entire_transactions - @raise [NotImplementedError] - @return [Hash] :total_outputs, :beef, :outputs

prove_certificate(certificate:, fields_to_reveal:, verifier:, privileged: = false, privileged_reason: = nil, originator: = nil) ¶

Proves select fields of a certificate to a verifier. - @param certificate [Hash] the full certificate (type, subject, serial_number, certifier, revocation_outpoint, signature, fields) - @param fields_to_reveal [Array] field names to disclose - @raise [NotImplementedError]

relinquish_certificate(type:, serial_number:, certifier:, originator: = nil) ¶

Removes a certificate from the wallet. - @raise [NotImplementedError]

relinquish_output(basket:, output:, originator: = nil) ¶

Removes an output from a basket without spending it. - @raise [NotImplementedError]

reveal_counterparty_key_linkage(counterparty:, verifier:, privileged: = false, privileged_reason: = nil, originator: = nil) ¶

Reveals key linkage with a counterparty to a verifier, across all interactions. - @raise [NotImplementedError]

reveal_specific_key_linkage(counterparty:, verifier:, protocol_id:, key_id:, privileged: = false, privileged_reason: = nil, originator: = nil) ¶

Reveals key linkage for a specific protocol and key interaction. - @raise [NotImplementedError]

sign_action(spends:, reference:, accept_delayed_broadcast: = true, return_txid_only: = false, no_send: = false, send_with: = nil, originator: = nil) ¶

Signs a transaction previously created with {#create_action}. - @param spends [Hash{Integer => Hash}] input index => { unlocking_script:, sequence_number: } - @param reference [String] reference returned by {#create_action} - @raise [NotImplementedError]

verify_hmac(data:, hmac:, protocol_id:, key_id:, privileged: = false, privileged_reason: = nil, counterparty: = nil, seek_permission: = true, originator: = nil) ¶

Verifies an HMAC against the provided data. - @raise [NotImplementedError]

verify_signature(signature:, protocol_id:, key_id:, data: = nil, hash_to_directly_verify: = nil, privileged: = false, privileged_reason: = nil, counterparty: = nil, for_self: = false, seek_permission: = true, originator: = nil) ¶

Verifies a digital signature against data or a pre-computed hash. - @raise [NotImplementedError]

wait_for_authentication(originator: = nil) ¶

Blocks until the user is authenticated. - @raise [NotImplementedError]