Class BSV::Overlay::Historian ¶

Inherits: Object

Builds a chronological history (oldest → newest) of typed values by traversing a transaction's input ancestry and interpreting each output with a provided interpreter.

The interpreter contract is: +interpreter.call(tx, output_index, ctx)+, returning the typed value or nil. Any callable responding to :call is accepted (lambda, proc, method, or object).

Traversal follows input.source_transaction references recursively. Callers must supply transactions whose inputs have source_transaction populated.

Cycle safety¶

Each transaction is visited at most once, tracked by its wtxid (wire-order binary).

Value semantics¶

Only nil is excluded. Falsy non-nil values (false, +""+, 0) are valid history entries and are included in the result.

Caching¶

An optional history_cache (any []/[]= responder) caches complete history results. Cache keys have the form: "#{interpreter_version}|#{dtxid_hex}|#{ctx_key}". Cached arrays are stored frozen; each retrieval returns a dup to protect the cache.

Note¶

The Ruby Historian is synchronous. There is no async/await semantics.

Public Instance Methods¶

build_history(start_transaction, context = nil) ¶

Traverses input ancestry from start_transaction and returns all interpreted values in chronological order (oldest first). - @param start_transaction [Transaction::Tx] - @param context [Object, nil] forwarded verbatim to the interpreter - @return [Array] interpreted values, oldest first

initialize(interpreter, debug: = false, history_cache: = nil, interpreter_version: = 'v1', ctx_key_fn: = nil) ¶

• @param interpreter [#call] callable: +call(tx, output_index, ctx) → value|nil+
• @param debug [Boolean] enable debug logging via +BSV.logger+
• @param history_cache [Hash, nil] optional cache store (+[]/[]=+ responder)
• @param interpreter_version [String] version tag for cache key invalidation
• @param ctx_key_fn [#call, nil] serialises context to a string cache key
• @return [Historian] a new instance of Historian