Module: BSV::Wallet::Interface

Included in:
ProtoWallet, Substrates::HTTPWalletJSON, Substrates::WalletWireTransceiver
Defined in:
lib/bsv/wallet_interface/interface.rb

Overview

BRC-100 Wallet Interface

Defines the 28 methods of the standard BSV wallet-to-application interface. Include this module and override the methods your implementation supports. Unimplemented methods raise UnsupportedActionError.

Instance Method Summary collapse

Instance Method Details

#abort_action(args, originator: nil) ⇒ Hash

Aborts an incomplete transaction.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :reference (String) —

    base64 reference to abort

Returns:

  • (Hash) —

    { aborted: true }

Raises:



50
51
52
 
# File 'lib/bsv/wallet_interface/interface.rb', line 50

def abort_action(args, originator: nil)
  raise UnsupportedActionError, 'abort_action'
end

#acquire_certificate(args, originator: nil) ⇒ Hash

Acquires an identity certificate.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :type (String) —

    certificate type (base64)

  • :certifier (String) —

    certifier public key hex

  • :acquisition_protocol (String) —

    ‘direct’ or ‘issuance’

  • :fields (Hash) —

    certificate fields

Returns:

  • (Hash) —

    certificate data

Raises:



257
258
259
 
# File 'lib/bsv/wallet_interface/interface.rb', line 257

def acquire_certificate(args, originator: nil)
  raise UnsupportedActionError, 'acquire_certificate'
end

#create_action(args, originator: nil) ⇒ Hash

Creates a new Bitcoin transaction with metadata and labels.

Parameters:

  • args (Hash) —

    transaction parameters

  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :description (String) — default: required —

    5-50 char description

  • :input_beef (Array<Integer>) —

    BEEF data for inputs

  • :inputs (Array<Hash>) —

    input objects with :outpoint, :unlocking_script, :input_description

  • :outputs (Array<Hash>) —

    output objects with :locking_script, :satoshis, :output_description

  • :lock_time (Integer) —

    optional lock time

  • :version (Integer) —

    optional transaction version

  • :labels (Array<String>) —

    optional transaction labels

  • :options (Hash) —

    optional processing options

Returns:

  • (Hash) —

    with :txid, :tx, :no_send_change, :send_with_results, :signable_transaction

Raises:



28
29
30
 
# File 'lib/bsv/wallet_interface/interface.rb', line 28

def create_action(args, originator: nil)
  raise UnsupportedActionError, 'create_action'
end

#create_hmac(args, originator: nil) ⇒ Hash

Creates an HMAC using a derived symmetric key.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :data (Array<Integer>) —

    byte array

  • :protocol_id (Array) —
    security_level, protocol_name
  • :key_id (String) —

    key identifier

  • :counterparty (String) —

    public key hex, ‘self’, or ‘anyone’

  • :privileged (Boolean) —

    privileged mode

Returns:

  • (Hash) —

    { hmac: Array<Integer> }

Raises:



195
196
197
 
# File 'lib/bsv/wallet_interface/interface.rb', line 195

def create_hmac(args, originator: nil)
  raise UnsupportedActionError, 'create_hmac'
end

#create_signature(args, originator: nil) ⇒ Hash

Creates a digital signature using a derived private key.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :data (Array<Integer>) —

    data to sign

  • :hash_to_directly_sign (Array<Integer>) —

    pre-hashed data to sign

  • :protocol_id (Array) —
    security_level, protocol_name
  • :key_id (String) —

    key identifier

  • :counterparty (String) —

    public key hex, ‘self’, or ‘anyone’

  • :privileged (Boolean) —

    privileged mode

Returns:

  • (Hash) —

    { signature: Array<Integer> }

Raises:



225
226
227
 
# File 'lib/bsv/wallet_interface/interface.rb', line 225

def create_signature(args, originator: nil)
  raise UnsupportedActionError, 'create_signature'
end

#decrypt(args, originator: nil) ⇒ Hash

Decrypts data using a derived symmetric key.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :ciphertext (Array<Integer>) —

    byte array to decrypt

  • :protocol_id (Array) —
    security_level, protocol_name
  • :key_id (String) —

    key identifier

  • :counterparty (String) —

    public key hex, ‘self’, or ‘anyone’

  • :privileged (Boolean) —

    privileged mode

Returns:

  • (Hash) —

    { plaintext: Array<Integer> }

Raises:



181
182
183
 
# File 'lib/bsv/wallet_interface/interface.rb', line 181

def decrypt(args, originator: nil)
  raise UnsupportedActionError, 'decrypt'
end

#discover_by_attributes(args, originator: nil) ⇒ Hash

Discovers certificates by attributes.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :attributes (Hash) —

    attribute name/value pairs to match

  • :limit (Integer) —

    max results

  • :offset (Integer) —

    number to skip

Returns:

  • (Hash) —

    with :total_certificates, :certificates

Raises:



318
319
320
 
# File 'lib/bsv/wallet_interface/interface.rb', line 318

def discover_by_attributes(args, originator: nil)
  raise UnsupportedActionError, 'discover_by_attributes'
end

#discover_by_identity_key(args, originator: nil) ⇒ Hash

Discovers certificates by identity key.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :identity_key (String) —

    public key hex to search

  • :limit (Integer) —

    max results

  • :offset (Integer) —

    number to skip

Returns:

  • (Hash) —

    with :total_certificates, :certificates

Raises:



306
307
308
 
# File 'lib/bsv/wallet_interface/interface.rb', line 306

def discover_by_identity_key(args, originator: nil)
  raise UnsupportedActionError, 'discover_by_identity_key'
end

#encrypt(args, originator: nil) ⇒ Hash

Encrypts data using a derived symmetric key.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :plaintext (Array<Integer>) —

    byte array to encrypt

  • :protocol_id (Array) —
    security_level, protocol_name
  • :key_id (String) —

    key identifier

  • :counterparty (String) —

    public key hex, ‘self’, or ‘anyone’

  • :privileged (Boolean) —

    privileged mode

Returns:

  • (Hash) —

    { ciphertext: Array<Integer> }

Raises:



167
168
169
 
# File 'lib/bsv/wallet_interface/interface.rb', line 167

def encrypt(args, originator: nil)
  raise UnsupportedActionError, 'encrypt'
end

#get_header_for_height(args, originator: nil) ⇒ Hash

Returns the block header at a given height.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :height (Integer) —

    block height

Returns:

  • (Hash) —

    { header: String }

Raises:



339
340
341
 
# File 'lib/bsv/wallet_interface/interface.rb', line 339

def get_header_for_height(args, originator: nil)
  raise UnsupportedActionError, 'get_header_for_height'
end

#get_height(args = {}, originator: nil) ⇒ Hash

Returns the current blockchain height.

Parameters:

  • args (Hash) (defaults to: {}) —

    empty hash

  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Returns:

  • (Hash) —

    { height: Integer }

Raises:



329
330
331
 
# File 'lib/bsv/wallet_interface/interface.rb', line 329

def get_height(args = {}, originator: nil)
  raise UnsupportedActionError, 'get_height'
end

#get_network(args = {}, originator: nil) ⇒ Hash

Returns the network (mainnet or testnet).

Parameters:

  • args (Hash) (defaults to: {}) —

    empty hash

  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Returns:

  • (Hash) —

    { network: String }

Raises:



348
349
350
 
# File 'lib/bsv/wallet_interface/interface.rb', line 348

def get_network(args = {}, originator: nil)
  raise UnsupportedActionError, 'get_network'
end

#get_public_key(args, originator: nil) ⇒ Hash

Retrieves a derived or identity public key.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :identity_key (Boolean) —

    if true, return the identity key

  • :protocol_id (Array) —
    security_level, protocol_name
  • :key_id (String) —

    key identifier

  • :counterparty (String) —

    public key hex, ‘self’, or ‘anyone’

  • :for_self (Boolean) —

    derive from own identity

  • :privileged (Boolean) —

    privileged mode

  • :privileged_reason (String) —

    reason for privileged access

Returns:

  • (Hash) —

    { public_key: String }

Raises:



123
124
125
 
# File 'lib/bsv/wallet_interface/interface.rb', line 123

def get_public_key(args, originator: nil)
  raise UnsupportedActionError, 'get_public_key'
end

#get_version(args = {}, originator: nil) ⇒ Hash

Returns the wallet version string.

Parameters:

  • args (Hash) (defaults to: {}) —

    empty hash

  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Returns:

  • (Hash) —

    { version: String }

Raises:



357
358
359
 
# File 'lib/bsv/wallet_interface/interface.rb', line 357

def get_version(args = {}, originator: nil)
  raise UnsupportedActionError, 'get_version'
end

#internalize_action(args, originator: nil) ⇒ Hash

Accepts an incoming transaction for internalization.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :tx (Array<Integer>) —

    Atomic BEEF-formatted transaction

  • :outputs (Array<Hash>) —

    metadata about outputs

  • :description (String) —

    5-50 char description

  • :labels (Array<String>) —

    optional labels

Returns:

  • (Hash) —

    { accepted: true }

Raises:



79
80
81
 
# File 'lib/bsv/wallet_interface/interface.rb', line 79

def internalize_action(args, originator: nil)
  raise UnsupportedActionError, 'internalize_action'
end

#is_authenticated(args = {}, originator: nil) ⇒ Hash

Checks if the user is authenticated.

Parameters:

  • args (Hash) (defaults to: {}) —

    empty hash

  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Returns:

  • (Hash) —

    { authenticated: Boolean }

Raises:



368
369
370
 
# File 'lib/bsv/wallet_interface/interface.rb', line 368

def is_authenticated(args = {}, originator: nil)
  raise UnsupportedActionError, 'is_authenticated'
end

#list_actions(args, originator: nil) ⇒ Hash

Lists transactions matching the specified labels.

Parameters:

  • args (Hash) —

    query parameters

  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :labels (Array<String>) — default: required —

    labels to filter by

  • :label_query_mode (String) —

    ‘any’ or ‘all’

  • :include_labels (Boolean) —

    include labels in results

  • :include_inputs (Boolean) —

    include input details

  • :include_outputs (Boolean) —

    include output details

  • :limit (Integer) —

    max results (default 10, max 10000)

  • :offset (Integer) —

    number to skip

Returns:

  • (Hash) —

    with :total_actions, :actions

Raises:



66
67
68
 
# File 'lib/bsv/wallet_interface/interface.rb', line 66

def list_actions(args, originator: nil)
  raise UnsupportedActionError, 'list_actions'
end

#list_certificates(args, originator: nil) ⇒ Hash

Lists identity certificates.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :certifiers (Array<String>) —

    certifier public keys

  • :types (Array<String>) —

    certificate types

  • :limit (Integer) —

    max results

  • :offset (Integer) —

    number to skip

Returns:

  • (Hash) —

    with :total_certificates, :certificates

Raises:



270
271
272
 
# File 'lib/bsv/wallet_interface/interface.rb', line 270

def list_certificates(args, originator: nil)
  raise UnsupportedActionError, 'list_certificates'
end

#list_outputs(args, originator: nil) ⇒ Hash

Lists spendable outputs in a basket.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :basket (String) — default: required —

    basket name

  • :tags (Array<String>) —

    optional tag filter

  • :tag_query_mode (String) —

    ‘any’ or ‘all’

  • :include (String) —

    ‘locking scripts’ or ‘entire transactions’

  • :limit (Integer) —

    max results

  • :offset (Integer) —

    number to skip

Returns:

  • (Hash) —

    with :total_outputs, :outputs

Raises:



94
95
96
 
# File 'lib/bsv/wallet_interface/interface.rb', line 94

def list_outputs(args, originator: nil)
  raise UnsupportedActionError, 'list_outputs'
end

#prove_certificate(args, originator: nil) ⇒ Hash

Proves select fields of a certificate to a verifier.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :certificate (Hash) —

    the certificate to prove

  • :fields_to_reveal (Array<String>) —

    field names to reveal

  • :verifier (String) —

    verifier public key hex

Returns:

  • (Hash) —

    { keyring_for_verifier: Hash }

Raises:



282
283
284
 
# File 'lib/bsv/wallet_interface/interface.rb', line 282

def prove_certificate(args, originator: nil)
  raise UnsupportedActionError, 'prove_certificate'
end

#relinquish_certificate(args, originator: nil) ⇒ Hash

Removes a certificate from the wallet.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :type (String) —

    certificate type

  • :serial_number (String) —

    certificate serial number

  • :certifier (String) —

    certifier public key hex

Returns:

  • (Hash) —

    { relinquished: true }

Raises:



294
295
296
 
# File 'lib/bsv/wallet_interface/interface.rb', line 294

def relinquish_certificate(args, originator: nil)
  raise UnsupportedActionError, 'relinquish_certificate'
end

#relinquish_output(args, originator: nil) ⇒ Hash

Releases an output from basket tracking.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :basket (String) —

    basket name

  • :output (String) —

    outpoint string

Returns:

  • (Hash) —

    { relinquished: true }

Raises:



105
106
107
 
# File 'lib/bsv/wallet_interface/interface.rb', line 105

def relinquish_output(args, originator: nil)
  raise UnsupportedActionError, 'relinquish_output'
end

#reveal_counterparty_key_linkage(args, originator: nil) ⇒ Hash

Reveals key linkage between self and a counterparty to a verifier.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :counterparty (String) —

    counterparty public key hex

  • :verifier (String) —

    verifier public key hex

  • :privileged (Boolean) —

    privileged mode

  • :privileged_reason (String) —

    reason for privileged access

Returns:

  • (Hash) —

    with :prover, :verifier, :counterparty, :revelation_time, :encrypted_linkage, :encrypted_linkage_proof

Raises:



136
137
138
 
# File 'lib/bsv/wallet_interface/interface.rb', line 136

def reveal_counterparty_key_linkage(args, originator: nil)
  raise UnsupportedActionError, 'reveal_counterparty_key_linkage'
end

#reveal_specific_key_linkage(args, originator: nil) ⇒ Hash

Reveals specific key linkage for a particular interaction.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :counterparty (String) —

    counterparty public key hex

  • :verifier (String) —

    verifier public key hex

  • :protocol_id (Array) —
    security_level, protocol_name
  • :key_id (String) —

    key identifier

  • :privileged (Boolean) —

    privileged mode

  • :privileged_reason (String) —

    reason for privileged access

Returns:

  • (Hash) —

    with :prover, :verifier, :counterparty, :protocol_id, :key_id, :encrypted_linkage, :encrypted_linkage_proof, :proof_type

Raises:



151
152
153
 
# File 'lib/bsv/wallet_interface/interface.rb', line 151

def reveal_specific_key_linkage(args, originator: nil)
  raise UnsupportedActionError, 'reveal_specific_key_linkage'
end

#sign_action(args, originator: nil) ⇒ Hash

Signs a previously created transaction.

Parameters:

  • args (Hash) —

    signing parameters

  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :spends (Hash) —

    map of input indexes to unlocking scripts

  • :reference (String) —

    base64 reference from create_action

  • :options (Hash) —

    optional processing options

Returns:

  • (Hash) —

    with :txid, :tx, :send_with_results

Raises:



40
41
42
 
# File 'lib/bsv/wallet_interface/interface.rb', line 40

def sign_action(args, originator: nil)
  raise UnsupportedActionError, 'sign_action'
end

#verify_hmac(args, originator: nil) ⇒ Hash

Verifies an HMAC using a derived symmetric key.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :data (Array<Integer>) —

    byte array

  • :hmac (Array<Integer>) —

    HMAC to verify

  • :protocol_id (Array) —
    security_level, protocol_name
  • :key_id (String) —

    key identifier

  • :counterparty (String) —

    public key hex, ‘self’, or ‘anyone’

  • :privileged (Boolean) —

    privileged mode

Returns:

  • (Hash) —

    { valid: true }

Raises:



210
211
212
 
# File 'lib/bsv/wallet_interface/interface.rb', line 210

def verify_hmac(args, originator: nil)
  raise UnsupportedActionError, 'verify_hmac'
end

#verify_signature(args, originator: nil) ⇒ Hash

Verifies a digital signature using a derived public key.

Parameters:

  • args (Hash)
  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Options Hash (args):

  • :data (Array<Integer>) —

    original data

  • :hash_to_directly_verify (Array<Integer>) —

    pre-hashed data

  • :signature (Array<Integer>) —

    DER-encoded signature

  • :protocol_id (Array) —
    security_level, protocol_name
  • :key_id (String) —

    key identifier

  • :counterparty (String) —

    public key hex, ‘self’, or ‘anyone’

  • :for_self (Boolean) —

    verify own signature

  • :privileged (Boolean) —

    privileged mode

Returns:

  • (Hash) —

    { valid: true }

Raises:



242
243
244
 
# File 'lib/bsv/wallet_interface/interface.rb', line 242

def verify_signature(args, originator: nil)
  raise UnsupportedActionError, 'verify_signature'
end

#wait_for_authentication(args = {}, originator: nil) ⇒ Hash

Waits until the user is authenticated.

Parameters:

  • args (Hash) (defaults to: {}) —

    empty hash

  • originator (String, nil) (defaults to: nil) —

    FQDN of the originating application

Returns:

  • (Hash) —

    { authenticated: true }

Raises:



377
378
379
 
# File 'lib/bsv/wallet_interface/interface.rb', line 377

def wait_for_authentication(args = {}, originator: nil)
  raise UnsupportedActionError, 'wait_for_authentication'
end