# Module BSV::Wallet <a id="module-BSV-Wallet"></a>

Wallet interface for transaction creation, signing, encryption, decryption,
certificate management, and identity verification per the BRC standards.

All methods return hashes. Nested structures (inputs, outputs, certificates)
are arrays of hashes — documented inline with @option tags where the shape is
non-obvious.

## Constants
### `EVENT_LOG_FORMATTER` <a id="constant-EVENT_LOG_FORMATTER"></a> <a id="EVENT_LOG_FORMATTER-constant"></a>
Canonical formatter for the event_log sink. Produces lines that tail/grep
cleanly without the standard Logger date/severity/PID prefix.

### `VERIFIER_VERSION` <a id="constant-VERIFIER_VERSION"></a> <a id="VERIFIER_VERSION-constant"></a>
Semantic version of the wallet's verify path. Bump when +Tx#verify+ semantics
change — script interpreter, BIP-143 preimage, +MerklePath#verify+, or FORKID
sighash rules. Do NOT bump for logging, metrics, error-message wording, or
performance-only refactors.

Written to <code>tx_proofs.verifier_version</code> on every successful
+Store#mark_verified+; rows with lower version are cache misses. Boot refuses
if +MAX(tx_proofs.verifier_version)+ exceeds this value —a downgraded binary
must not honour hits it can no longer reproduce. See ADR-033 and
<code>docs/reference/verification-cache.md</code>.

### `VERSION` <a id="constant-VERSION"></a> <a id="VERSION-constant"></a>
Not documented.

## Attributes
### `event_log` [RW] <a id="attribute-c-event_log"></a> <a id="event_log-class_method"></a>
Opt-in per-event log sink. When set, emit writes the canonical +[event] name
key=value …+ line here AND to <code>BSV.logger</code> (if set). The setter
auto-applies {EVENT_LOG_FORMATTER} so the sink's lines are always
tail/grep-friendly regardless of the caller's <code>Logger.new</code>
defaults.
**@example wire a per-run logfile from a harness**
```ruby
require 'logger'
BSV::Wallet.event_log = Logger.new('tmp/e2e.log')
```

## Public Class Methods
### `config()` <a id="method-c-config"></a> <a id="config-class_method"></a>
Singleton Config instance. Lazy: first access instantiates.
- **@return** [Config]

### `configure()` <a id="method-c-configure"></a> <a id="configure-class_method"></a>
User-facing configuration block. Yields the singleton Config so the user's
+~/.bsv-wallet/config.rb+ can override any setting.

    BSV::Wallet.configure do |c|
      c.limp_threshold = 100_000
      c.hints_socket   = '/tmp/bsv-wallet-hints.sock'
    end
- **@return** [Config] the populated singleton
- **@yield** [Config]

### `emit(name, **payload)` <a id="method-c-emit"></a> <a id="emit-class_method"></a>
Not documented.

### `event_observer_count()` <a id="method-c-event_observer_count"></a> <a id="event_observer_count-class_method"></a>
Snapshot of registered observers (testing).

### `format_field(key, value)` <a id="method-c-format_field"></a> <a id="format_field-class_method"></a>
Format a single key=value pair for structured log output.

Returns nil for nil values (caller uses .compact to skip them). Quotes values
containing whitespace; escapes embedded double quotes.

### `load_config_file!(path = nil)` <a id="method-c-load_config_file-21"></a> <a id="load_config_file!-class_method"></a>
Load the user's configuration file if present.

Resolution: explicit `path` argument > `BSV_WALLET_CONFIG` env var >
+~/.bsv-wallet/config.rb+ default. Absent file is a clean no-op (operator
without a config file falls back to Config's ENV-reading defaults). Errors
propagate — bad config = loud boot failure, not a silent swallow.
- **@param** `path` [String, nil]
- **@return** [String, nil] the path that was loaded, or +nil+

### `off_event(handle)` <a id="method-c-off_event"></a> <a id="off_event-class_method"></a>
Deregister a previously-registered observer.
- **@param** `handle` [Proc] the proc returned by {.on_event}
- **@return** [Proc, nil] the removed observer, or nil if not found

### `on_event(&block)` <a id="method-c-on_event"></a> <a id="on_event-class_method"></a>
Register an observer for every subsequent `emit` call.
- **@raise** [ArgumentError]
- **@return** [Proc] the registered observer (use as +handle+ for {.off_event})
- **@yieldparam** `name` [String] event name (e.g. +'task.dispatched'+)
- **@yieldparam** `payload` [Hash] the keyword payload passed to +emit+

### `random_derivation()` <a id="method-c-random_derivation"></a> <a id="random_derivation-class_method"></a>
Generate a random BRC-42 derivation value (base64-encoded 8 random bytes).
Matches reference wallet format: 12-character base64 string.

### `reset_config!()` <a id="method-c-reset_config-21"></a> <a id="reset_config!-class_method"></a>
Reset the singleton — drops the current Config so the next `config` access
instantiates fresh. Primarily a test helper for examples that mutate ENV and
need a clean Config rebuild.

### `reset_event_observers!()` <a id="method-c-reset_event_observers-21"></a> <a id="reset_event_observers!-class_method"></a>
Clear the process-wide observer registry. Test helper — do not call from
production code. Specs that boot a Scheduler / Daemon without a matching
shutdown leak observers across examples; the spec_helper hook uses this to
keep examples isolated.