walletclient

type BlockTimestamp struct {
	Height uint32
	Time   int64
}

type Explorer interface {
	// GetTxHex retrieves the raw transaction hex for a given transaction ID.
	GetTxHex(txid string) (string, error)

	// Broadcast broadcasts one or more raw transactions to the network.
	// Returns the transaction ID of the first transaction on success.
	Broadcast(txs ...string) (string, error)

	// GetTxs retrieves all transactions associated with a given address.
	GetTxs(addr string) ([]tx, error)

	// GetTxOutspends returns the spent status of all outputs for a given transaction.
	GetTxOutspends(tx string) ([]spentStatus, error)

	// GetUtxos retrieves all unspent transaction outputs (UTXOs) for a given address.
	GetUtxos(addr string) ([]Utxo, error)

	// GetRedeemedVtxosBalance calculates the redeemed virtual UTXO balance for an address
	// considering the unilateral exit delay.
	GetRedeemedVtxosBalance(
		addr string, unilateralExitDelay arklib.RelativeLocktime,
	) (uint64, map[int64]uint64, error)

	// GetTxBlockTime returns whether a transaction is confirmed and its block time.
	GetTxBlockTime(
		txid string,
	) (confirmed bool, blocktime int64, err error)

	// BaseUrl returns the base URL of the explorer service.
	BaseUrl() string

	// GetFeeRate retrieves the current recommended fee rate in sat/vB.
	GetFeeRate() (float64, error)

	// GetAddressesEvents returns a channel that receives onchain address events
	// (new UTXOs, spent UTXOs, confirmed UTXOs) for all subscribed addresses.
	GetAddressesEvents() <-chan types.OnchainAddressEvent

	// SubscribeForAddresses subscribes to address updates via WebSocket connections.
	// Addresses are automatically distributed across multiple connections using hash-based routing.
	// Subscriptions are batched to prevent overwhelming individual connections.
	// Duplicate subscriptions are automatically prevented via instance-scoped deduplication.
	SubscribeForAddresses(addresses []string) error

	// UnsubscribeForAddresses removes address subscriptions and updates the WebSocket connections.
	UnsubscribeForAddresses(addresses []string) error

	// Stop gracefully shuts down the explorer, closing all WebSocket connections and channels.
	Stop()
}

type Outpoint struct {
	Txid string
	VOut uint32
}

type RBFTxn struct {
	TxId       string
	ReplacedBy string
}

type RbfTxId struct {
	TxId string `json:"txid"`
}

type TxInput interface {
	GetTxid() string
	GetIndex() uint32
	GetScript() string
	GetValue() uint64
}

type Utxo struct {
	Txid   string `json:"txid"`
	Vout   uint32 `json:"vout"`
	Amount uint64 `json:"value"`
	Asset  string `json:"asset,omitempty"`
	Status struct {
		Confirmed bool  `json:"confirmed"`
		BlockTime int64 `json:"block_time"`
	} `json:"status"`
	Script string
}

type VtxoWithValue struct {
	Outpoint Outpoint
	Value    uint64
}

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

type WalletStatus interface {
	IsInitialized() bool
	IsUnlocked() bool
	IsSynced() bool
}