chainsource

type BestHeightRequest struct {
	actor.BaseMessage
}

type BestHeightResponse struct {
	actor.BaseMessage

	// Height is the current best block height.
	Height int32

	// Hash is the current best block hash.
	Hash chainhash.Hash
}

type BlockEpoch struct {
	actor.BaseMessage

	// Height is the block height.
	Height int32

	// Hash is the block hash.
	Hash chainhash.Hash

	// Timestamp is the block timestamp from the header.
	Timestamp int64
}

type BlockEpochActor struct {
	// contains filtered or unexported fields
}

type BlockEpochConfig struct {
	// Backend is the blockchain backend used to monitor blocks.
	Backend ChainBackend

	// Log is an optional logger for this actor instance. If None, the actor
	// falls back to extracting a logger from context via LoggerFromContext,
	// or uses btclog.Disabled if no logger is found.
	Log fn.Option[btclog.Logger]

	// ReconnectBackoff is the initial delay before reconnecting a block
	// epoch subscription whose backend stream closed after the initial
	// registration succeeded. Zero uses defaultBlockEpochReconnectBackoff.
	ReconnectBackoff time.Duration

	// MaxReconnectBackoff caps the exponential reconnect delay. Zero uses
	// defaultBlockEpochMaxReconnectBackoff.
	MaxReconnectBackoff time.Duration
}

type BlockRegistration struct {
	// Epochs is a channel that sends an event for each new block connected
	// to the chain. The channel is buffered to handle bursts of blocks.
	Epochs <-chan *BlockEpoch

	// Cancel is a function that can be called to cancel this registration
	// and clean up resources.
	Cancel func()
}

type BroadcastTxRequest struct {
	actor.BaseMessage

	// Tx is the transaction to broadcast.
	Tx *wire.MsgTx

	// Label is an optional label for tracking this transaction in the
	// wallet. Can be empty.
	Label string
}

type BroadcastTxResponse struct {
	actor.BaseMessage

	// Txid is the transaction ID of the broadcast transaction.
	Txid chainhash.Hash
}

type ChainBackend interface {
	// EstimateFee returns the estimated fee rate in satoshis per vbyte for
	// a transaction to confirm within the target number of blocks. Returns
	// an error if fee estimation fails or is unavailable.
	EstimateFee(ctx context.Context,
		targetConf uint32) (btcutil.Amount, error)

	// BestBlock returns the current best known block height and hash from
	// the blockchain. This represents the tip of the longest valid chain
	// according to the backend's view.
	BestBlock(ctx context.Context) (int32, chainhash.Hash, error)

	// TestMempoolAccept tests whether one or more transactions would be
	// accepted by the mempool without actually broadcasting them. When
	// len(txs) > 1 the backend must evaluate the transactions as a
	// package (matching Bitcoin Core's testmempoolaccept JSON array
	// form); backends that can only validate individual transactions
	// must return ErrPackageMempoolAcceptUnsupported rather than
	// silently evaluating the first tx in isolation.
	//
	// The returned slice has one entry per input tx, in the same
	// order. Not all backends may support this operation at all; those
	// should return a non-nil error from the single-tx call so callers
	// can distinguish "rejected" from "not evaluated".
	TestMempoolAccept(ctx context.Context,
		txs ...*wire.MsgTx) ([]MempoolAcceptResult, error)

	// BroadcastTx broadcasts a transaction to the network. The label
	// parameter is optional and may be used for wallet tracking. Returns
	// an error if the broadcast fails.
	BroadcastTx(ctx context.Context, tx *wire.MsgTx, label string) error

	// RegisterConf registers for confirmation notifications of a
	// transaction. The registration returns a ConfRegistration that
	// provides channels for receiving confirmation events.
	//
	// Parameters:
	//   - ctx: Context for cancellation
	//   - txid: The transaction ID to monitor (can be nil to match by
	//     script)
	//   - pkScript: The public key script to watch for
	//   - numConfs: Target number of confirmations
	//   - heightHint: Earliest block containing the tx (0 if unknown)
	//   - includeBlock: If true, include the full block in the confirmation
	//     event for merkle proof construction
	//
	// The returned ConfRegistration must have buffered channels and a
	// Cancel function for cleanup.
	RegisterConf(ctx context.Context, txid *chainhash.Hash, pkScript []byte,
		numConfs uint32, heightHint uint32,
		includeBlock bool) (*ConfRegistration, error)

	// RegisterSpend registers for spend notifications of a transaction
	// output. The registration returns a SpendRegistration that provides
	// channels for receiving spend events.
	//
	// Parameters:
	//   - ctx: Context for cancellation
	//   - outpoint: The output to monitor (can be nil to match by script)
	//   - pkScript: The public key script to watch for
	//   - heightHint: Earliest block containing a spend (0 if unknown)
	//
	// The returned SpendRegistration must have buffered channels and a
	// Cancel function for cleanup.
	RegisterSpend(ctx context.Context, outpoint *wire.OutPoint,
		pkScript []byte, heightHint uint32) (*SpendRegistration, error)

	// RegisterBlocks registers for new block notifications. The
	// registration returns a BlockRegistration that provides a channel for
	// receiving block events.
	//
	// The returned BlockRegistration must have a buffered channel and a
	// Cancel function for cleanup. The backend may optionally backfill
	// missed blocks if the client provides a best known block.
	RegisterBlocks(ctx context.Context) (*BlockRegistration, error)

	// SubmitPackage atomically submits a parent+child transaction
	// package to the network. This is required for V3 package relay
	// where the child pays fees for otherwise non-relayable parents.
	SubmitPackage(ctx context.Context, parents []*wire.MsgTx,
		child *wire.MsgTx) error

	// Start initializes the backend and any background processes. This
	// must be called before using any other methods.
	Start() error

	// Stop shuts down the backend and cleans up all resources. All pending
	// registrations will be cancelled.
	Stop() error
}

type ChainSourceActor struct {
	// contains filtered or unexported fields
}

type ChainSourceConfig struct {
	// Backend is the blockchain backend used for all chain operations.
	Backend ChainBackend

	// System is the actor system for spawning sub-actors.
	System *actor.ActorSystem

	// Log is an optional logger for this actor instance. If None, the actor
	// falls back to extracting a logger from context via LoggerFromContext,
	// or uses btclog.Disabled if no logger is found.
	Log fn.Option[btclog.Logger]

	// FinalityDepth is forwarded to each spawned sub-actor as the
	// number of confirmations past the first observed positive event
	// that the actor uses to synthesize a Done signal when the backend
	// transport (notably lndclient over gRPC) cannot deliver one. Zero
	// disables height-based finality synthesis. See
	// ConfActorConfig.FinalityDepth / SpendActorConfig.FinalityDepth.
	FinalityDepth uint32
}

type ChainSourceMsg interface {
	actor.Message
	// contains filtered or unexported methods
}

type ChainSourceResp interface {
	actor.Message
	// contains filtered or unexported methods
}

type ConfActor struct {
	// contains filtered or unexported fields
}

type ConfActorConfig struct {
	// Backend is the blockchain backend used to monitor confirmations.
	Backend ChainBackend

	// Log is an optional logger for this actor instance. If None, the actor
	// falls back to extracting a logger from context via LoggerFromContext,
	// or uses btclog.Disabled if no logger is found.
	Log fn.Option[btclog.Logger]

	// FinalityDepth is the number of confirmations past the first
	// observed Confirmed event that the actor uses to synthesize a Done
	// signal when the backend cannot deliver one. Zero disables
	// height-based finality synthesis entirely; in that case the actor
	// only fires ConfDoneEvent when the backend's own Done channel
	// fires (e.g. an in-process lnd notifier). Non-zero values close
	// the lndclient transport gap, where the gRPC layer does not
	// surface lnd's internal "past reorg-safety depth" signal.
	//
	// The depth is counted inclusively (a tx confirmed at height H is
	// at depth 1; height-based finality fires once the actor observes
	// a block at H + FinalityDepth - 1). The conventional choice is 6.
	FinalityDepth uint32
}

type ConfDoneEvent struct {
	actor.BaseMessage

	// Txid is the transaction ID whose registration matured.
	Txid chainhash.Hash
}

type ConfMsg interface {
	actor.Message
	// contains filtered or unexported methods
}

type ConfRegistration struct {
	// Confirmed fires every time the transaction reaches the target
	// number of confirmations on the canonical chain. After a Reorged
	// event it may fire again when the transaction re-confirms. The
	// channel is buffered.
	Confirmed <-chan *TxConfirmation

	// Reorged fires when a previously delivered confirmation is reorged
	// out of the canonical chain. The payload is the backend forwarder's
	// monotonic sequence number (see TxConfirmation.Seq) rather than
	// reorg depth or block identity, which the lndclient gRPC transport
	// cannot preserve; the sequence lets the consumer order this signal
	// against confirmations sharing the same sequence space even though
	// they arrive on a different channel. Backends that cannot observe
	// reorgs leave this channel nil-equivalent (allocated but never
	// written to); reading from it is always safe.
	Reorged <-chan uint64

	// Done fires once when the confirmation watch is past the backend's
	// reorg-safety depth and will receive no further events. Callers
	// must still invoke Cancel to release client-side resources.
	// Backends that cannot synthesize a safety-depth signal leave this
	// channel nil-equivalent (allocated but never written to).
	Done <-chan struct{}

	// Cancel is a function that can be called to cancel this registration
	// and clean up resources. After calling Cancel, no more events will be
	// sent on any channels.
	Cancel func()
}

type ConfReorgedEvent struct {
	actor.BaseMessage

	// Txid is the transaction ID whose confirmation was reorged. This
	// matches the Txid carried on the originating ConfirmationEvent.
	Txid chainhash.Hash
}

type ConfResp interface {
	actor.Message
	// contains filtered or unexported methods
}

type ConfirmationEvent struct {
	actor.BaseMessage

	// Txid is the transaction ID.
	Txid chainhash.Hash

	// BlockHeight is the height of the block containing the transaction.
	BlockHeight int32

	// BlockHash is the hash of the block containing the transaction.
	BlockHash chainhash.Hash

	// NumConfs is the actual number of confirmations at the time of this
	// event.
	NumConfs uint32

	// Tx is the confirmed transaction. This allows consumers to inspect
	// transaction outputs without making additional chain queries.
	Tx *wire.MsgTx

	// Block is the full block containing the confirmed transaction. This
	// is only populated when the confirmation was registered with
	// IncludeBlock=true. Used for constructing merkle proofs.
	Block *wire.MsgBlock
}

type EpochMsg interface {
	actor.Message
	// contains filtered or unexported methods
}

type EpochResp interface {
	actor.Message
	// contains filtered or unexported methods
}

type FeeEstimateRequest struct {
	actor.BaseMessage

	// TargetConf is the desired number of blocks within which the
	// transaction should confirm.
	TargetConf uint32
}

type FeeEstimateResponse struct {
	actor.BaseMessage

	// SatPerVByte is the estimated fee rate in satoshis per virtual byte.
	SatPerVByte btcutil.Amount
}

type MempoolAcceptResult struct {
	// Txid is the transaction hash the result applies to.
	Txid chainhash.Hash

	// Accepted reports whether the backend would accept the
	// transaction into its mempool.
	Accepted bool

	// Reason carries the backend's human-readable rejection reason
	// when Accepted is false. Empty on acceptance.
	Reason string
}

type PositiveDoneOrder struct {
	// contains filtered or unexported fields
}

type RegisterConfRequest struct {
	actor.BaseMessage

	// CallerID is a unique identifier provided by the caller. This is used
	// to construct the service key for the dedicated actor, enabling
	// deterministic cancellation.
	CallerID string

	// Txid is the transaction ID to monitor. Can be nil to match by script
	// only.
	Txid *chainhash.Hash

	// PkScript is the public key script to monitor.
	PkScript []byte

	// TargetConfs is the number of confirmations to wait for.
	TargetConfs uint32

	// HeightHint is an optional height hint indicating the earliest block
	// that could contain the transaction. This is an optimization for
	// light clients. Set to 0 if unknown.
	HeightHint uint32

	// IncludeBlock indicates whether the confirmation event should include
	// the full block containing the transaction. This is needed for
	// constructing merkle proofs. When true, the ConfirmationEvent.Block
	// field will be populated.
	IncludeBlock bool

	// NotifyActor is an optional actor reference. If Some, confirmation
	// events will be sent to this actor asynchronously. If None, a Future
	// is returned in the response for blocking await.
	NotifyActor fn.Option[actor.TellOnlyRef[ConfirmationEvent]]

	// NotifyReorged is an optional actor reference for negative
	// confirmation events. It is only used in async actor mode.
	NotifyReorged fn.Option[actor.TellOnlyRef[ConfReorgedEvent]]

	// NotifyDone is an optional actor reference notified when the
	// confirmation watch is beyond the backend's reorg tracking horizon.
	// It is only used in async actor mode.
	NotifyDone fn.Option[actor.TellOnlyRef[ConfDoneEvent]]
}

type RegisterConfResponse struct {
	actor.BaseMessage

	// Future provides a blocking await interface for confirmation. Only
	// present if NotifyActor was None in the request.
	Future actor.Future[ConfirmationEvent]
}

type RegisterSpendRequest struct {
	actor.BaseMessage

	// CallerID is a unique identifier provided by the caller. This is used
	// to construct the service key for the dedicated actor, enabling
	// deterministic cancellation.
	CallerID string

	// Outpoint is the transaction output to monitor for spends. Can be nil
	// to match by script only.
	Outpoint *wire.OutPoint

	// PkScript is the public key script of the output to monitor.
	PkScript []byte

	// HeightHint is an optional height hint indicating the earliest block
	// that could contain a spending transaction. Set to 0 if unknown.
	HeightHint uint32

	// NotifyActor is an optional actor reference. If Some, spend events
	// will be sent to this actor asynchronously. If None, a Future is
	// returned for blocking await.
	NotifyActor fn.Option[actor.TellOnlyRef[SpendEvent]]

	// NotifyReorged is an optional actor reference for spend reorg events.
	// It is only used in async actor mode.
	NotifyReorged fn.Option[actor.TellOnlyRef[SpendReorgedEvent]]

	// NotifyDone is an optional actor reference notified when the spend
	// watch is beyond the backend's reorg tracking horizon. It is only used
	// in async actor mode.
	NotifyDone fn.Option[actor.TellOnlyRef[SpendDoneEvent]]
}

type RegisterSpendResponse struct {
	actor.BaseMessage

	// Future provides a blocking await interface for spend notification.
	// Only present if NotifyActor was None in the request.
	Future actor.Future[SpendEvent]
}

type SpendActor struct {
	// contains filtered or unexported fields
}

type SpendActorConfig struct {
	// Backend is the blockchain backend used to monitor spends.
	Backend ChainBackend

	// Log is an optional logger for this actor instance. If None, the actor
	// falls back to extracting a logger from context via LoggerFromContext,
	// or uses btclog.Disabled if no logger is found.
	Log fn.Option[btclog.Logger]

	// FinalityDepth is the number of confirmations past the first
	// observed Spend event that the actor uses to synthesize a Done
	// signal when the backend cannot deliver one. See the matching
	// field on ConfActorConfig for the rationale; the same constraint
	// applies on the spend watch — lnd's chainntnfs.SpendEvent.Done
	// does not survive the lndclient gRPC transport, so consumers
	// that gate eviction on Done would otherwise leak per-spend state.
	FinalityDepth uint32
}

type SpendDetail struct {
	// SpentOutPoint is the outpoint that was spent.
	SpentOutPoint *wire.OutPoint

	// SpenderTxHash is the hash of the spending transaction.
	SpenderTxHash *chainhash.Hash

	// SpendingTx is the full spending transaction.
	SpendingTx *wire.MsgTx

	// SpenderInputIndex is the input index in the spending transaction
	// that consumed the outpoint.
	SpenderInputIndex uint32

	// SpendingHeight is the block height where the spending transaction
	// was confirmed.
	SpendingHeight int32

	// Seq is a per-registration monotonic sequence number stamped by the
	// backend forwarder in the order it observed lifecycle events. Spend
	// and Reorged share one sequence space so the consumer can order them
	// even though they arrive on separate channels (a select over two
	// ready channels picks at random and cannot recover order). The
	// consumer applies an event only when its Seq exceeds the highest Seq
	// seen so far, discarding a stale event that lost a cross-channel
	// race. Zero means the backend does not stamp sequences (it never
	// reorgs, so ordering is moot); such events are always applied.
	Seq uint64
}

type SpendDoneEvent struct {
	actor.BaseMessage

	// Outpoint is the output whose spend registration matured.
	Outpoint wire.OutPoint
}

type SpendEvent struct {
	actor.BaseMessage

	// Outpoint is the output that was spent.
	Outpoint wire.OutPoint

	// SpendingTxid is the transaction ID of the spending transaction.
	SpendingTxid chainhash.Hash

	// SpendingTx is the full spending transaction.
	SpendingTx *wire.MsgTx

	// SpenderInputIndex is the input index within the spending transaction
	// that consumes the monitored outpoint.
	SpenderInputIndex uint32

	// SpendingHeight is the block height where the spending transaction
	// was confirmed.
	SpendingHeight int32
}

type SpendMsg interface {
	actor.Message
	// contains filtered or unexported methods
}

type SpendRegistration struct {
	// Spend fires every time the monitored outpoint is spent on the
	// canonical chain. After a Reorged event it may fire again when a
	// new spender confirms. The channel is buffered.
	Spend <-chan *SpendDetail

	// Reorged fires when a previously delivered spend is reorged out of
	// the canonical chain. The payload is the backend forwarder's
	// monotonic sequence number (see SpendDetail.Seq) rather than reorg
	// depth or block identity, which the lndclient gRPC transport cannot
	// preserve; the sequence lets the consumer order this signal against
	// spends sharing the same sequence space even though they arrive on a
	// different channel. Backends that cannot observe spend reorgs leave
	// this channel nil-equivalent (allocated but never written to);
	// reading from it is always safe.
	Reorged <-chan uint64

	// Done fires once when the spend watch is past the backend's
	// reorg-safety depth and will receive no further events. Callers
	// must still invoke Cancel to release client-side resources.
	// Backends that cannot synthesize a safety-depth signal leave this
	// channel nil-equivalent (allocated but never written to).
	Done <-chan struct{}

	// Cancel is a function that can be called to cancel this registration
	// and clean up resources.
	Cancel func()
}

type SpendReorgedEvent struct {
	actor.BaseMessage

	// Outpoint is the output whose spend was reorged.
	Outpoint wire.OutPoint
}

type SpendResp interface {
	actor.Message
	// contains filtered or unexported methods
}

type SubmitPackageRequest struct {
	actor.BaseMessage

	// Parents is the list of parent transactions in dependency order.
	Parents []*wire.MsgTx

	// Child is the fee-paying child transaction.
	Child *wire.MsgTx
}

type SubmitPackageResponse struct {
	actor.BaseMessage
}

type SubscribeBlocksRequest struct {
	actor.BaseMessage

	// CallerID is a unique identifier provided by the caller. This is used
	// to construct the service key for the dedicated actor, enabling
	// deterministic cancellation.
	CallerID string

	// NotifyActor is an optional actor reference. If Some, block events
	// will be sent to this actor asynchronously. If None, an iterator is
	// returned for use in range loops.
	NotifyActor fn.Option[actor.TellOnlyRef[BlockEpoch]]
}

type SubscribeBlocksResponse struct {
	actor.BaseMessage

	// Iterator provides an iterator for iterating over block epochs using
	// Go's range-over-function feature (Go 1.23+). Only present if
	// NotifyActor was None in the request.
	Iterator iter.Seq[BlockEpoch]

	// Cancel terminates the subscription and cleans up backend resources.
	// It is safe to call multiple times.
	Cancel func()
}

type TestMempoolAcceptRequest struct {
	actor.BaseMessage

	// Txs are the transactions to test for mempool acceptance. One
	// transaction performs a single-tx test; multiple transactions
	// request a package test.
	Txs []*wire.MsgTx
}

type TestMempoolAcceptResponse struct {
	actor.BaseMessage

	// Results has one entry per tx in the original request, in the
	// same order.
	Results []MempoolAcceptResult
}

type TxConfirmation struct {
	// BlockHash is the hash of the block containing the transaction.
	BlockHash *chainhash.Hash

	// BlockHeight is the height of the block containing the transaction.
	BlockHeight uint32

	// TxIndex is the position of the transaction within the block.
	TxIndex uint32

	// Tx is the confirmed transaction itself.
	Tx *wire.MsgTx

	// Block is the full block containing the transaction. Only populated
	// when the confirmation was registered with IncludeBlock=true. This
	// matches lnd's chainntnfs behavior.
	Block *wire.MsgBlock

	// Seq is a per-registration monotonic sequence number stamped by the
	// backend forwarder in the order it observed lifecycle events.
	// Confirmed and Reorged share one sequence space so the consumer can
	// order them even though they arrive on separate channels (a select
	// over two ready channels picks at random and cannot recover order).
	// The consumer applies an event only when its Seq exceeds the highest
	// Seq seen so far, discarding a stale event that lost a cross-channel
	// race. Zero means the backend does not stamp sequences (it never
	// reorgs, so ordering is moot); such events are always applied.
	Seq uint64
}

type UnregisterConfRequest struct {
	actor.BaseMessage

	// CallerID is the unique identifier provided in the original
	// RegisterConfRequest. Required to reconstruct the service key.
	CallerID string

	// Txid is the transaction ID being monitored. Can be nil to match by
	// script only (must match the original registration).
	Txid *chainhash.Hash

	// PkScript is the public key script being monitored. Required if Txid
	// is nil.
	PkScript []byte

	// TargetConfs is the number of confirmations from the original
	// request. Required to reconstruct the service key.
	TargetConfs uint32
}

type UnregisterConfResponse struct {
	actor.BaseMessage
}

type UnregisterSpendRequest struct {
	actor.BaseMessage

	// CallerID is the unique identifier provided in the original
	// RegisterSpendRequest. Required to reconstruct the service key.
	CallerID string

	// Outpoint is the transaction output being monitored. Can be nil to
	// match by script only (must match the original registration).
	Outpoint *wire.OutPoint

	// PkScript is the public key script being monitored. Required if
	// Outpoint is nil.
	PkScript []byte
}

type UnregisterSpendResponse struct {
	actor.BaseMessage
}

type UnsubscribeBlocksRequest struct {
	actor.BaseMessage

	// CallerID is the unique identifier provided in the original
	// SubscribeBlocksRequest. Required to reconstruct the service key.
	CallerID string
}

type UnsubscribeBlocksResponse struct {
	actor.BaseMessage
}