tachi

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 6, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package tachi is a Go client for the Tachi daemon HTTP RPC API (tachid).

It covers every route in the daemon's swagger spec: dashboard/stats, address & balance, blocks, transactions, epochs, VTXOs, vaults, validators & peers, node operations, the cooperative-refund signing ceremony, watchtower status/receipts, live websocket alerts, and the pass-through Bitcoin Core JSON-RPC proxy.

The Client follows the same shape as most official Go API clients (e.g. google/go-github): a root Client exposes one field per resource group, and each group's methods return (result, *Response, error). 

c, err := tachi.NewClient()
stats, _, err := c.Dashboard.Stats(ctx)
addr, _, err := c.Address.Get(ctx, "bcrt1p...")

See https://rpc-regtest.tachibtc.com/swagger/index.html for the reference spec this client was generated against.

Index

Constants

View Source 
const Version = "0.1.0"

Version is the SDK's semantic version, sent as part of the default User-Agent header.

Variables

This section is empty.

Functions

This section is empty.

Types

type AddressResponse 

type AddressResponse struct {
	// Pubkey is the normalized 32-byte x-only public key hex for the queried address.
	Pubkey string `json:"pubkey"`
	// BalanceSat is the total unspent balance in satoshis summed across the address's VTXOs.
	BalanceSat int64 `json:"balance_sat"`
	// Nonce is the last used transaction nonce for the address; the next tx should use Nonce+1.
	Nonce uint64 `json:"nonce"`
	// VTXOCount is the number of unspent VTXOs owned by the address.
	VTXOCount int `json:"vtxo_count"`
}

AddressResponse is returned by AddressService.Get.

type AddressService 

type AddressService service

AddressService groups account-scoped endpoints: balance, nonce, VTXOs, transaction history, and pending mempool activity for a public key or taproot address.

func (*AddressService) Balance 

func (s *AddressService) Balance(ctx context.Context, address string) (*BalanceResponse, *Response, error)

Balance returns the total unspent balance for address in satoshis.

func (*AddressService) Get 

func (s *AddressService) Get(ctx context.Context, address string) (*AddressResponse, *Response, error)

Get returns account detail (balance, nonce, VTXO count) for a public key or taproot address (bc1p/tb1p/bcrt1p, or 32/33-byte hex).

func (*AddressService) Mempool 

func (s *AddressService) Mempool(ctx context.Context, address string) (*MempoolByAddressResponse, *Response, error)

Mempool returns pending (unconfirmed) transactions crediting address or spending one of its currently-unspent VTXOs. Poll this once for current pending state, then use WSService.Subscribe for new arrivals instead of re-polling.

func (*AddressService) Nonce 

func (s *AddressService) Nonce(ctx context.Context, address string) (*NonceResponse, *Response, error)

Nonce returns the last used nonce for address; the next transaction should use NextNonce.

func (*AddressService) Transactions 

func (s *AddressService) Transactions(ctx context.Context, address string, opts *AddressTransactionsOptions) (*AddressTransactionsResponse, *Response, error)

Transactions returns transactions involving address in descending height order, height-cursor paginated (chain opts.BeforeHeight on the previous response's NextBeforeHeight). The scan is bounded by a server-side time budget rather than a block cap, so a sparse address can return zero transactions along with a cursor to keep walking older blocks.

func (*AddressService) VTXOs 

func (s *AddressService) VTXOs(ctx context.Context, address string, includeSpent bool) (*AddressVTXOsResponse, *Response, error)

VTXOs returns VTXOs owned by address. By default only unspent VTXOs are returned; pass includeSpent=true for full history.

type AddressTransactionsOptions 

type AddressTransactionsOptions struct {
	// BeforeHeight is the exclusive upper-bound block height; zero means
	// "start from the chain tip".
	BeforeHeight int64
	// PageSize is the max transactions to return (default 50, max 100).
	PageSize int
}

AddressTransactionsOptions configures AddressService.Transactions pagination.

type AddressTransactionsResponse 

type AddressTransactionsResponse struct {
	// Pubkey is the normalized 32-byte x-only public key hex the transactions are filtered by.
	Pubkey string `json:"pubkey"`
	// Transactions is the page of decoded transactions involving Pubkey, ordered newest-first.
	Transactions []ListTransactionItem `json:"transactions"`
	// PageSize is the maximum number of transactions the caller asked the scanner to collect.
	PageSize int `json:"page_size"`
	// ScannedFromHeight is the highest block height included in this scan (inclusive).
	ScannedFromHeight int64 `json:"scanned_from_height"`
	// ScannedToHeight is the lowest block height included in this scan (inclusive).
	ScannedToHeight int64 `json:"scanned_to_height"`
	// NextBeforeHeight is the cursor to pass as BeforeHeight on the next call; nil once genesis is reached.
	NextBeforeHeight *int64 `json:"next_before_height,omitempty"`
}

AddressTransactionsResponse is returned by AddressService.Transactions. Pagination is height-cursor based, same semantics as TxService.List's ListTransactionsResponse.

type AddressVTXOsResponse 

type AddressVTXOsResponse struct {
	// Pubkey is the normalized 32-byte x-only public key hex the VTXOs are owned by.
	Pubkey string `json:"pubkey"`
	// VTXOs is the list of matching VTXOs (unspent by default, all when includeSpent=true).
	VTXOs []VTXOItem `json:"vtxos"`
	// Count is the number of entries returned in VTXOs.
	Count int `json:"count"`
}

AddressVTXOsResponse is returned by AddressService.VTXOs.

type BalanceResponse 

type BalanceResponse struct {
	// Pubkey is the normalized 32-byte x-only public key hex whose balance is reported.
	Pubkey string `json:"pubkey"`
	// BalanceSat is the total unspent balance in satoshis owned by Pubkey.
	BalanceSat int64 `json:"balance_sat"`
}

BalanceResponse is returned by AddressService.Balance.

type BitcoinRPCError 

type BitcoinRPCError struct {
	// Code is the bitcoind JSON-RPC error code (negative integers per bitcoind convention).
	Code int `json:"code" example:"-8"`
	// Message is the human-readable error description from bitcoind.
	Message string `json:"message" example:"invalid parameter"`
}

BitcoinRPCError describes an error returned by bitcoind.

func (*BitcoinRPCError) Error 

func (e *BitcoinRPCError) Error() string

type BitcoinRPCResponse 

type BitcoinRPCResponse struct {
	// Result is the raw JSON result body from bitcoind; nil when an error occurred.
	Result json.RawMessage `json:"result" swaggertype:"object"`
	// Error carries the bitcoind error payload when the call failed; nil on success.
	Error *BitcoinRPCError `json:"error"`
	// ID echoes back the caller-supplied request identifier.
	ID string `json:"id" example:"1"`
}

BitcoinRPCResponse is the JSON-RPC 1.0 envelope returned by POST / (the bitcoind proxy).

type BitcoinService 

type BitcoinService service

BitcoinService wraps the daemon's pass-through Bitcoin Core JSON-RPC proxy (POST /).

func (*BitcoinService) RPC 

func (s *BitcoinService) RPC(ctx context.Context, method string, params interface{}) (json.RawMessage, *Response, error)

RPC forwards a JSON-RPC 1.0 request to the daemon's configured bitcoind (POST /). method is the bitcoind RPC method name (e.g. "getblockchaininfo"); params is marshalled as-is into the request's params array/object — pass nil for no parameters.

Common read-only methods (chain/mempool/tx-decoding queries) are forwarded with no authentication. Any other method (wallet, admin, network-mutation) requires the Client to have been created with WithAPIKey using the daemon's master BTC_RPC_API_KEY — a missing or non-matching key on a non-common method returns a 403 *ErrorResponse.

On a bitcoind-level error (non-nil BitcoinRPCResponse.Error), RPC returns that error wrapped so callers can still access the raw BitcoinRPCError via errors.As; on a transport/HTTP-level error it returns an *ErrorResponse as usual.

type BlockResponse 

type BlockResponse struct {
	// Height is the block height described by this response.
	Height int64 `json:"height"`
	// Hash is the hex-encoded CometBFT block hash.
	Hash string `json:"hash"`
	// Time is the unix-seconds timestamp of the block header; omitted if unknown.
	Time *int64 `json:"time,omitempty"`
	// Epoch is the epoch ID this block belongs to, derived from height and epochBlocks.
	Epoch uint32 `json:"epoch"`
	// TxCount is the number of decoded transactions contained in this block.
	TxCount int `json:"tx_count"`
	// Transactions is the list of decoded transactions in this block.
	Transactions []ListTransactionItem `json:"transactions"`
}

BlockResponse is returned by BlockService.Get, BlockService.ByHeight, and BlockService.ByHash.

type BlockService 

type BlockService service

BlockService groups block-lookup endpoints, including the Tachi-chain analogues of bitcoind's getblockhash/getblockheader/getblock.

func (*BlockService) ByHash 

func (s *BlockService) ByHash(ctx context.Context, hash string) (*BlockResponse, *Response, error)

ByHash returns full Tachi chain block detail (header + decoded transactions) for the block with the given hex hash.

func (*BlockService) ByHeight 

func (s *BlockService) ByHeight(ctx context.Context, height int64) (*BlockResponse, *Response, error)

ByHeight returns full Tachi chain block detail (header + decoded transactions) for height — the Tachi-chain analogue of bitcoind's getblock. Same response shape as Get.

func (*BlockService) Get 

func (s *BlockService) Get(ctx context.Context, height int64) (*BlockResponse, *Response, error)

Get returns block metadata and all decoded transactions at height.

func (*BlockService) Hash 

func (s *BlockService) Hash(ctx context.Context, height int64) (*GetBlockHashResponse, *Response, error)

Hash returns the Tachi chain's block hash at height — the Tachi-chain analogue of bitcoind's getblockhash (not a bitcoin RPC).

func (*BlockService) HeaderByHash 

func (s *BlockService) HeaderByHash(ctx context.Context, hash string) (*GetBlockHeaderResponse, *Response, error)

HeaderByHash returns Tachi chain block header metadata (no transaction list) for the block with the given hex hash.

func (*BlockService) HeaderByHeight 

func (s *BlockService) HeaderByHeight(ctx context.Context, height int64) (*GetBlockHeaderResponse, *Response, error)

HeaderByHeight returns Tachi chain block header metadata (no transaction list) for height — the Tachi-chain analogue of bitcoind's getblockheader.

func (*BlockService) List 

func (s *BlockService) List(ctx context.Context, page, pageSize int) (*ListBlocksResponse, *Response, error)

List returns a paginated list of blocks from latest to oldest with tx counts. page defaults to 1; pageSize defaults to 50 (max 100). Pass 0 for either to use the default.

type BlockSummary 

type BlockSummary struct {
	// Height is the block height of this summary entry.
	Height int64 `json:"height"`
	// Hash is the hex-encoded CometBFT block hash.
	Hash string `json:"hash"`
	// Time is the unix-seconds timestamp of the block header; omitted if unknown.
	Time *int64 `json:"time,omitempty"`
	// TxCount is the number of transactions contained in the block.
	TxCount int `json:"tx_count"`
	// Epoch is the epoch ID this block belongs to, derived from height and epochBlocks.
	Epoch uint32 `json:"epoch"`
}

BlockSummary is a lightweight block for the BlockService.List view.

type BreachReceipt 

type BreachReceipt struct {
	// VaultID is the vault whose funding outpoint was spent.
	VaultID string `json:"vault_id"`
	// BroadcastState is the state decoded from the spending tx's hint.
	BroadcastState uint64 `json:"broadcast_state"`
	// LatestState is the BFT-replicated latest state at detection.
	LatestState uint64 `json:"latest_state"`
	// Classification is "legitimate", "stale", or "anomalous".
	Classification string `json:"classification"`
	// SpendTxID is the displayed txid of the transaction that spent the funding outpoint.
	SpendTxID string `json:"spend_txid"`
	// SpendVout is the funding output index the spend consumed.
	SpendVout uint32 `json:"spend_vout"`
	// DetectedHeight is the L1 block height the spend was observed at.
	DetectedHeight int64 `json:"detected_height"`
	// DetectedAt is the node's wall-clock unix timestamp at detection.
	DetectedAt int64 `json:"detected_at"`
}

BreachReceipt is an entry (or single lookup result) from WatchtowerService.Receipts / Receipt.

type Client 

type Client struct {

	// BaseURL is the root of every request, e.g.
	// "https://rpc-regtest.tachibtc.com/" or "http://127.0.0.1:26670/".
	// Always has a trailing slash.
	BaseURL *url.URL

	// UserAgent is sent on every request. Defaults to
	// "tachi-sdk-go/<Version>".
	UserAgent string

	// Address groups account-scoped endpoints: balance, nonce, VTXOs, transaction history, and pending mempool activity.
	Address *AddressService
	// Block groups block-lookup endpoints, including the bitcoind-analogue getblockhash/getblockheader/getblock routes.
	Block *BlockService
	// Epoch groups epoch-lookup endpoints.
	Epoch *EpochService
	// Tx groups transaction endpoints: lookup, decode/validate, broadcast, mempool, and fee estimation.
	Tx *TxService
	// VTXO groups VTXO-lookup endpoints.
	VTXO *VTXOService
	// Vault groups vault-lookup endpoints.
	Vault *VaultService
	// Validators groups the bootstrap validator registry and this node's own peer info.
	Validators *ValidatorsService
	// Node groups liveness, node-info, and raw CometBFT-proxy endpoints.
	Node *NodeService
	// Dashboard groups network-overview endpoints: stats, supply, and search.
	Dashboard *DashboardService
	// Bitcoin wraps the daemon's pass-through Bitcoin Core JSON-RPC proxy (POST /).
	Bitcoin *BitcoinService
	// Sign wraps the cooperative-refund threshold-signing ceremony.
	Sign *SignService
	// Watchtower groups the vault watchtower's status and breach-receipt endpoints.
	Watchtower *WatchtowerService
	// WS opens live websocket subscriptions for chain alerts.
	WS *WSService
	// contains filtered or unexported fields
}

Client manages communication with the Tachi daemon RPC API. Create one with NewClient; the zero value is not usable. A Client is safe for concurrent use.

func NewClient 

func NewClient(opts ...ClientOption) (*Client, error)

NewClient creates a Client. With no options it targets the public Tachi regtest daemon; use WithBaseURL to target a local or private node.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, req *http.Request, v interface{}) (*Response, error)

Do sends req and, on a 2xx response, JSON-decodes the body into v (which may be nil to discard it). On a non-2xx response it returns an *ErrorResponse. Exposed alongside NewRequest for reaching not-yet-wrapped endpoints.

func (*Client) NewRequest 

func (c *Client) NewRequest(method, path string, query url.Values, body interface{}) (*http.Request, error)

NewRequest builds an API request against path (relative to c.BaseURL, no leading slash — e.g. "tachi_stats", not "/tachi_stats") with an optional query string and an optional JSON-encoded body. Exposed so callers can reach an endpoint the SDK hasn't wrapped yet; every generated service method is built on top of it.

type ClientOption 

type ClientOption func(*Client)

ClientOption configures a Client constructed by NewClient.

func WithAPIKey 

func WithAPIKey(key string) ClientOption

WithAPIKey attaches an X-Api-Key header to every request. Pass the daemon's master BTC_RPC_API_KEY to unlock privileged bitcoind methods, vault reconstruction parameters on Vault.List, and the vaults_by_user query path, or a client key registered with the relevant scope.

func WithBaseURL 

func WithBaseURL(rawURL string) ClientOption

WithBaseURL points the client at a different daemon, e.g. "http://127.0.0.1:26670/" for a local node. Defaults to the public regtest endpoint.

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) ClientOption

WithHTTPClient overrides the default http.Client (30s timeout). Pass a client wrapping a retry/backoff RoundTripper (e.g. hashicorp's go-retryablehttp) to add retry behavior — the SDK does not retry on its own, matching the convention of most official Go API clients.

func WithUserAgent 

func WithUserAgent(ua string) ClientOption

WithUserAgent overrides the default "tachi-sdk-go/<Version>" User-Agent.

type CometRPCResponse 

type CometRPCResponse struct {
	// JSONRPC is the JSON-RPC version reported by CometBFT, always "2.0".
	JSONRPC string `json:"jsonrpc" example:"2.0"`
	// ID is the request identifier echoed back by CometBFT.
	ID int `json:"id" example:"1"`
	// Result is the endpoint-specific result body forwarded verbatim from CometBFT.
	Result json.RawMessage `json:"result" swaggertype:"object"`
}

CometRPCResponse is the raw JSON-RPC 2.0 envelope CometBFT wraps every forwarded result in. Shape of Result varies by endpoint.

type DashboardService 

type DashboardService service

DashboardService groups network-overview endpoints.

func (*DashboardService) Search 

func (s *DashboardService) Search(ctx context.Context, q string) (*SearchResponse, *Response, error)

Search auto-detects whether q is a tx hash, block height, epoch ID, VTXO ID, or pubkey and returns the matching result. Inspect resp.Type ("block", "epoch", "tx", "vtxo", or "address") and json.Unmarshal resp.Result into the matching type.

func (*DashboardService) Stats 

func (s *DashboardService) Stats(ctx context.Context) (*StatsResponse, *Response, error)

Stats returns a single-call network dashboard overview: chain height, total transactions, accounts, current epoch, node count, and supply.

func (*DashboardService) Supply 

func (s *DashboardService) Supply(ctx context.Context) (*SupplyResponse, *Response, error)

Supply returns the total circulating supply (sum of all unspent VTXO amounts) and unspent VTXO count.

type EpochService 

type EpochService service

EpochService groups epoch-lookup endpoints.

func (*EpochService) ByHash 

func (s *EpochService) ByHash(ctx context.Context, hash string) (*GetEpochResponse, *Response, error)

ByHash returns a Tachi-decoded view of the epoch whose Verkle root matches the given 64-char hex hash.

func (*EpochService) Get 

func (s *EpochService) Get(ctx context.Context, id uint32) (*GetEpochResponse, *Response, error)

Get returns a Tachi-decoded view of the epoch with the given sequential EpochID.

func (*EpochService) List 

func (s *EpochService) List(ctx context.Context, page, pageSize int) (*ListEpochsResponse, *Response, error)

List returns a paginated list of all epochs from latest to oldest with full metadata. page defaults to 1; pageSize defaults to 50 (max 100). Pass 0 for either to use the default.

type ErrorResponse 

type ErrorResponse struct {
	// Response is the raw non-2xx HTTP response that triggered this error.
	Response *http.Response
	// Message is the daemon's plain-text error body (http.Error), trimmed of surrounding whitespace.
	Message string
}

ErrorResponse is returned when the daemon responds with a non-2xx status. The daemon's error bodies are plain text (http.Error), not JSON, so Message carries the raw response body.

func (*ErrorResponse) Error 

func (r *ErrorResponse) Error() string

type FeeEstimateResponse 

type FeeEstimateResponse struct {
	// MinFeeSat is the minimum acceptable fee in satoshis (currently a flat floor of 1).
	MinFeeSat int64 `json:"min_fee_sat"`
	// AvgFeeSat is the mean fee in satoshis across recently scanned blocks.
	AvgFeeSat int64 `json:"avg_fee_sat"`
	// RecommendedFeeSat is the suggested fee to use for a new transaction, derived from recent activity.
	RecommendedFeeSat int64 `json:"recommended_fee_sat"`
}

FeeEstimateResponse is returned by TxService.FeeEstimate.

type GetBlockHashResponse 

type GetBlockHashResponse struct {
	// Height is the height the hash was requested for.
	Height int64 `json:"height"`
	// Hash is the hex-encoded CometBFT block hash at Height.
	Hash string `json:"hash"`
}

GetBlockHashResponse is returned by BlockService.Hash.

type GetBlockHeaderResponse 

type GetBlockHeaderResponse struct {
	// Height is the block height.
	Height int64 `json:"height"`
	// Hash is the hex-encoded CometBFT block hash.
	Hash string `json:"hash"`
	// PrevHash is the hex-encoded hash of the preceding block ("" for the genesis block).
	PrevHash string `json:"prev_hash"`
	// Time is the unix-seconds timestamp of the block header.
	Time int64 `json:"time"`
	// Epoch is the epoch ID this block belongs to, derived from height and epochBlocks.
	Epoch uint32 `json:"epoch"`
}

GetBlockHeaderResponse is returned by BlockService.HeaderByHeight and BlockService.HeaderByHash.

type GetEpochResponse 

type GetEpochResponse struct {
	// Hash is the hex-encoded 32-byte Verkle root committed by this epoch.
	Hash string `json:"hash"`
	// Height is the sequential EpochID (uint32) of this epoch.
	Height uint32 `json:"height"`
	// BitcoinBlockHeight is nil until L1-settled or bitcoin client unavailable.
	BitcoinBlockHeight *int64 `json:"bitcoin_block_height"`
	// Status is "open" or "closed".
	Status string `json:"status"`
	// Timestamp is unix seconds at epoch close; nil for open epochs.
	Timestamp *int64 `json:"timestamp"`
	// TxCount is the number of transactions committed within this epoch.
	TxCount int `json:"tx_count"`
	// TxHashes is the list of 64-char hex transaction hashes included in this epoch.
	TxHashes []string `json:"tx_hashes"`
	// HATCount is the number of HAT (hash anchor tree) commitments recorded
	// in this epoch's Verkle tree.
	HATCount int `json:"hat_count"`
	// L1SettlementTxID is the hex-encoded Bitcoin L1 transaction that settled
	// this epoch's Verkle root; empty until the epoch is L1-settled.
	L1SettlementTxID string `json:"l1_settlement_txid,omitempty"`
}

GetEpochResponse is returned by EpochService.Get and EpochService.ByHash.

type GetRawTransactionResponse 

type GetRawTransactionResponse struct {
	// TxHash is the hex-encoded tmhash of the raw transaction bytes.
	TxHash string `json:"txHash"`
	// Hex is the hex-encoded raw transaction bytes.
	Hex string `json:"hex"`
}

GetRawTransactionResponse is returned by TxService.Raw.

type GetTransactionResponse 

type GetTransactionResponse struct {
	// TxHash is the hex-encoded tmhash of the raw transaction bytes
	// (witness-included).
	TxHash string `json:"txHash"`
	// TxID is the segwit-style transaction id (witness stripped).
	TxID string `json:"txid"`
	// Type is transfer/deposit/withdraw/lock/unlock/vault_open/
	// vault_state_advance/vault_close/vault_breach/unknown.
	Type string `json:"type"`
	// State is committed/pending/failed.
	State string `json:"state"`
	// Status is the raw ABCI {code, log} pair describing tx execution.
	Status TxStatus `json:"status"`
	// Epoch is the epoch ID the committing block belongs to; nil for mempool/pending txs.
	Epoch *uint32 `json:"epoch"`
	// Vin lists the VTXO inputs being spent by this transaction.
	Vin []TxVin `json:"vin"`
	// Vout lists the VTXO outputs produced by this transaction.
	Vout []TxVout `json:"vout"`
	// Size is the byte length of the raw transaction bytes.
	Size int `json:"size"`
	// IsSegwit reports whether any input carries witness data (a non-empty SigScript).
	IsSegwit bool `json:"is_segwit"`
	// Weight is the Bitcoin-style segwit weight: 3*baseSize + totalSize.
	Weight int `json:"weight"`
	// VSize is the Bitcoin-style virtual size: ceil(Weight/4).
	VSize int `json:"vsize"`
	// Version is the TachiTx protocol version byte.
	Version uint8 `json:"version"`
	// Hex is the hex-encoded raw transaction bytes.
	Hex string `json:"hex"`
	// BlockHash is the hex-encoded committing block hash; nil for mempool/pending txs.
	BlockHash *string `json:"blockhash"`
	// Time is the unix-seconds timestamp of the committing block; nil for mempool/pending txs.
	Time *int64 `json:"time"`
	// HAT is the HAT commitment for the VTXO spent by this tx's first input; populated only via TxOptions.HAT.
	HAT *HATProofResponse `json:"hat,omitempty"`
	// RIP is the raw JSON-encoded recursive inclusion proof; populated only
	// when requested via TxOptions.RIP. Decode with json.Unmarshal into a
	// caller-defined struct.
	RIP json.RawMessage `json:"rip,omitempty"`
}

GetTransactionResponse is returned by TxService.Get.

type HATProofResponse 

type HATProofResponse struct {
	// VTXOID is the hex-encoded 32-byte VTXO identifier the HAT commits to.
	VTXOID string `json:"vtxo_id"`
	// BTCTimestamp is the Bitcoin L1 block timestamp bound into the proof preimage.
	BTCTimestamp uint32 `json:"btc_timestamp"`
	// BTCHeight is the Bitcoin L1 block height bound into the proof preimage.
	BTCHeight uint32 `json:"btc_height"`
	// Proof is the hex-encoded SHA256d commitment over the raw finalized PSBT payload.
	Proof string `json:"proof"`
}

HATProofResponse is the hex-encoded view of a hat.HAT commitment.

type HealthResponse 

type HealthResponse struct {
	// Status is the liveness label; always "ok" when the daemon is serving requests.
	Status string `json:"status" example:"ok"`
	// Validators is the count of validators currently in the bootstrap registry.
	Validators int `json:"validators" example:"3"`
}

HealthResponse is returned by NodeService.Health.

type ListBlocksResponse 

type ListBlocksResponse struct {
	// Blocks is the page of block summaries, ordered newest-first.
	Blocks []BlockSummary `json:"blocks"`
	// Total is the latest block height, used as the total block count for pagination.
	Total int64 `json:"total"`
	// Page is the 1-based page number the caller requested.
	Page int `json:"page"`
	// PageSize is the maximum number of blocks returned per page (capped at 100).
	PageSize int `json:"page_size"`
	// TotalPages is the total number of pages available for the current PageSize.
	TotalPages int `json:"total_pages"`
}

ListBlocksResponse is returned by BlockService.List.

type ListEpochsResponse 

type ListEpochsResponse struct {
	// Epochs is the page of epochs returned, ordered latest-first by EpochID.
	Epochs []GetEpochResponse `json:"epochs"`
	// Total is the total number of epochs known to the chain (current_epoch + 1).
	Total int `json:"total"`
	// Page is the 1-based page number the caller requested.
	Page int `json:"page"`
	// PageSize is the maximum number of epochs returned per page (capped at 100).
	PageSize int `json:"page_size"`
	// TotalPages is the total number of pages available for the current PageSize.
	TotalPages int `json:"total_pages"`
}

ListEpochsResponse is returned by EpochService.List.

type ListTransactionItem 

type ListTransactionItem struct {
	// TxHash is the hex-encoded tmhash of the raw transaction bytes.
	TxHash string `json:"tx_hash"`
	// Type is transfer/deposit/withdraw/lock/unlock/vault_open/vault_state_advance/vault_close/vault_breach/unknown.
	Type string `json:"type"`
	// State is "committed" for confirmed txs, "pending" for mempool entries.
	State string `json:"state"`
	// Epoch is the epoch ID the committing block belongs to; nil for mempool/pending txs.
	Epoch *uint32 `json:"epoch,omitempty"`
	// Height is the committing block height, or 0 for mempool entries.
	Height int64 `json:"height"`
	// BlockHash is the hex-encoded committing block hash; empty for mempool entries.
	BlockHash string `json:"block_hash,omitempty"`
	// Time is the unix-seconds timestamp of the committing block; nil for mempool entries.
	Time *int64 `json:"time,omitempty"`
	// Size is the byte length of the raw transaction bytes.
	Size int `json:"size"`
	// IsSegwit reports whether any input carries witness data (a non-empty SigScript).
	IsSegwit bool `json:"is_segwit"`
	// Weight is the Bitcoin-style segwit weight: 3*baseSize + totalSize.
	Weight int `json:"weight"`
	// VSize is the Bitcoin-style virtual size: ceil(Weight/4).
	VSize int `json:"vsize"`
	// Fee is the fee paid by the transaction in satoshis.
	Fee int64 `json:"fee"`
	// Vin lists the VTXO inputs being spent by this transaction.
	Vin []TxVin `json:"vin"`
	// Vout lists the VTXO outputs produced by this transaction.
	Vout []TxVout `json:"vout"`
	// Direction is "sent" or "received", populated only by address-scoped
	// endpoints (AddressService.Transactions, AddressService.Mempool).
	Direction string `json:"direction,omitempty"`
	// HAT is the HAT commitment for the VTXO spent by this tx's first input; omitted when there is none or the proof fetch failed.
	HAT *HATProofResponse `json:"hat,omitempty"`
	// HasRIP reports whether a RIP inclusion proof is available for this tx's HAT without generating it.
	HasRIP bool `json:"has_rip"`
}

ListTransactionItem is a summary of a transaction in a list/block/address view — shared by TxService.List, BlockService.Get, AddressService. Transactions, and AddressService.Mempool.

type ListTransactionsOptions 

type ListTransactionsOptions struct {
	// BeforeHeight is the exclusive upper-bound block height; zero means
	// "start from the chain tip".
	BeforeHeight int64
	// PageSize is the max transactions to return (default 50, max 100).
	PageSize int
}

ListTransactionsOptions configures TxService.List pagination.

type ListTransactionsResponse 

type ListTransactionsResponse struct {
	// Transactions is the page of committed transactions, ordered newest-first by block height.
	Transactions []ListTransactionItem `json:"transactions"`
	// PageSize is the maximum number of transactions the caller asked the scanner to collect.
	PageSize int `json:"page_size"`
	// ScannedFromHeight is the highest block height included in this scan (inclusive).
	ScannedFromHeight int64 `json:"scanned_from_height"`
	// ScannedToHeight is the lowest block height included in this scan (inclusive).
	ScannedToHeight int64 `json:"scanned_to_height"`
	// NextBeforeHeight is the cursor to pass as BeforeHeight on the next call; nil once genesis is reached.
	NextBeforeHeight *int64 `json:"next_before_height,omitempty"`
}

ListTransactionsResponse is returned by TxService.List. Pagination is height-cursor based: pass NextBeforeHeight as the BeforeHeight of the next call; nil once genesis is reached.

type ListVTXOsResponse 

type ListVTXOsResponse struct {
	// VTXOs is the page of VTXOs returned, sorted by height descending.
	VTXOs []VTXOResponse `json:"vtxos"`
	// Total is the total number of VTXOs across all pages, as reported by the ABCI app.
	Total int `json:"total"`
	// Page is the 1-based page number the caller requested.
	Page int `json:"page"`
	// PageSize is the maximum number of VTXOs returned per page.
	PageSize int `json:"page_size"`
	// TotalPages is the total number of pages available for the current PageSize.
	TotalPages int `json:"total_pages"`
}

ListVTXOsResponse is returned by VTXOService.List.

type ListVaultsResponse 

type ListVaultsResponse struct {
	// User is the normalized 32-byte x-only pubkey (hex) the vaults are owned by.
	User string `json:"user"`
	// Vaults is the requested page of vaults owned by User.
	Vaults []VaultListItem `json:"vaults"`
	// Total is the total number of vaults User owns across all pages.
	Total int `json:"total"`
	// Page is the 1-based page number returned.
	Page int `json:"page"`
	// PageSize is the maximum entries per page.
	PageSize int `json:"page_size"`
	// TotalPages is the total number of pages available at the current PageSize.
	TotalPages int `json:"total_pages"`
}

ListVaultsResponse is returned by VaultService.List.

type LiveValidatorsResponse 

type LiveValidatorsResponse struct {
	// Validators is the subset of validators whose peers are currently connected via the overlay network.
	Validators []ValidatorInfo `json:"validators"`
	// Count is the number of live validators returned.
	Count int `json:"count" example:"2"`
	// TotalKnown is the total number of validators known to the node (live plus offline).
	TotalKnown int `json:"total_known" example:"3"`
}

LiveValidatorsResponse is returned by ValidatorsService.Live.

type LockedVTXOsResponse 

type LockedVTXOsResponse struct {
	// Vault is the vault address (bech32m or hex) the locked VTXOs are bound to.
	Vault string `json:"vault"`
	// VTXOs is the list of VTXOs locked to Vault.
	VTXOs []VTXOResponse `json:"vtxos"`
	// Count is the number of entries returned in VTXOs.
	Count int `json:"count"`
}

LockedVTXOsResponse is returned by VTXOService.Locked.

type MempoolByAddressResponse 

type MempoolByAddressResponse struct {
	// Pubkey is the normalized 32-byte x-only public key hex the mempool is filtered by.
	Pubkey string `json:"pubkey"`
	// Transactions is the list of matching pending transactions.
	Transactions []ListTransactionItem `json:"transactions"`
	// Count is the number of entries returned in Transactions.
	Count int `json:"count"`
}

MempoolByAddressResponse is returned by AddressService.Mempool.

type MempoolResponse 

type MempoolResponse struct {
	// Transactions is the list of decoded pending transactions currently in the CometBFT unconfirmed mempool.
	Transactions []ListTransactionItem `json:"transactions"`
	// Count is the number of pending transactions returned.
	Count int `json:"count"`
}

MempoolResponse is returned by TxService.Mempool.

type NodeInfoResponse 

type NodeInfoResponse struct {
	// Version is the CometBFT node software version reported by /status.
	Version string `json:"version"`
	// ChainID identifies the chain the node is participating in.
	ChainID string `json:"chain_id"`
	// NodeID is the CometBFT p2p node identifier.
	NodeID string `json:"node_id"`
	// Network is the network name advertised by the node (mirrors ChainID for CometBFT).
	Network string `json:"network"`
	// Moniker is the operator-chosen human-readable name for the node.
	Moniker string `json:"moniker"`
	// SyncStatus is "catching_up" when the node is replaying blocks, "synced" otherwise.
	SyncStatus string `json:"sync_status"`
	// LatestBlockHeight is the height of the most recently seen block.
	LatestBlockHeight int64 `json:"latest_block_height"`
	// LatestBlockTime is the Unix-seconds timestamp of the latest block, omitted if unknown.
	LatestBlockTime *int64 `json:"latest_block_time,omitempty"`
	// EpochBlocks is the configured number of blocks per Tachi epoch.
	EpochBlocks int64 `json:"epoch_blocks"`
	// Peers is the count of currently connected p2p peers.
	Peers int `json:"peers"`
}

NodeInfoResponse is returned by NodeService.Info.

type NodeService 

type NodeService service

NodeService groups liveness, node-info, and raw CometBFT-proxy endpoints.

func (*NodeService) ConsensusState 

func (s *NodeService) ConsensusState(ctx context.Context) (*CometRPCResponse, *Response, error)

ConsensusState forwards to CometBFT's consensus_state endpoint: current round, step, and proposer info.

func (*NodeService) Health 

func (s *NodeService) Health(ctx context.Context) (*HealthResponse, *Response, error)

Health is a liveness probe that returns the daemon status and validator count.

func (*NodeService) Info 

func (s *NodeService) Info(ctx context.Context) (*NodeInfoResponse, *Response, error)

Info returns extended node information: version, chain ID, sync status, epoch config, and peer count.

func (*NodeService) NetInfo 

func (s *NodeService) NetInfo(ctx context.Context) (*CometRPCResponse, *Response, error)

NetInfo forwards to CometBFT's net_info endpoint: listening addresses, connected peer count, and per-peer connection info.

func (*NodeService) Query 

func (s *NodeService) Query(ctx context.Context, path string, opts *QueryOptions) (*CometRPCResponse, *Response, error)

Query forwards a raw query to CometBFT's abci_query endpoint; the ABCI application interprets path and the optional data/height. See the daemon's RPC.md for the full set of supported query paths (height, nonce, supply, vtxo, utxos, all_vtxos, locked_vtxos, current_epoch, epoch_root, epoch, epochs, rip, vaults_by_user).

func (*NodeService) Status 

func (s *NodeService) Status(ctx context.Context) (*CometRPCResponse, *Response, error)

Status forwards to CometBFT's status endpoint: node info, sync status, and the latest block height.

func (*NodeService) ValidatorsPower 

func (s *NodeService) ValidatorsPower(ctx context.Context) (*CometRPCResponse, *Response, error)

ValidatorsPower forwards to CometBFT's validators endpoint: the current validator set with voting power.

type NonceResponse 

type NonceResponse struct {
	// Address is the normalized public key hex the nonce was looked up for.
	Address string `json:"address"`
	// Nonce is the last used transaction nonce for Address.
	Nonce uint64 `json:"nonce"`
	// NextNonce is the nonce the next transaction from Address should use (Nonce+1).
	NextNonce uint64 `json:"next_nonce"`
}

NonceResponse is returned by AddressService.Nonce.

type QueryOptions 

type QueryOptions struct {
	// DataHex is hex-encoded query data; its meaning depends on Path (see
	// the daemon's RPC.md "ABCI query paths" table, e.g. "vtxo", "utxos",
	// "epoch", "rip").
	DataHex string
	// Height is the block height to query at ("" or "0" for latest).
	Height string
}

QueryOptions configures NodeService.Query's optional parameters.

type ReadyResponse 

type ReadyResponse struct {
	// Ready is true once the registry has reached the expected validator count before the long-poll deadline.
	Ready bool `json:"ready" example:"true"`
	// Validators is the current bootstrap registry snapshot at the time the long-poll returned.
	Validators []ValidatorInfo `json:"validators"`
	// Count is the number of validators in Validators.
	Count int `json:"count" example:"2"`
}

ReadyResponse is returned by ValidatorsService.Ready.

type RefundInput 

type RefundInput struct {
	// Prevout is the funding outpoint being spent.
	Prevout RefundPrevout `json:"prevout"`
	// Sequence is nSequence (0 for a cooperative refund; no CSV).
	Sequence uint32 `json:"sequence"`
	// WitnessUtxo is the vault P2TR output this input commits to.
	WitnessUtxo RefundWitnessUtxo `json:"witnessUtxo"`
	// TapLeafScript holds exactly one entry: the vault cooperative leaf.
	TapLeafScript []RefundTapLeaf `json:"tapLeafScript"`
	// TapInternalKey is the x-only(32) hex internal key.
	TapInternalKey string `json:"tapInternalKey"`
	// SighashType must be SIGHASH_DEFAULT (0x00).
	SighashType uint32 `json:"sighashType"`
	// TapScriptSig is empty in; the collected quorum partials out.
	TapScriptSig []RefundTapSig `json:"tapScriptSig,omitempty"`
}

RefundInput is the single funding input spent via the vault cooperative leaf. TapScriptSig is empty on the way in and carries the collected quorum partials on the way out.

type RefundOutput 

type RefundOutput struct {
	// Value is the output amount in satoshis.
	Value int64 `json:"value"`
	// Script is the hex-encoded output locking script.
	Script string `json:"script"`
}

RefundOutput is a refund output. Outputs[0] must be the canonical to_local P2TR.

type RefundPrevout 

type RefundPrevout struct {
	// Hash is the display-order (big-endian) txid hex.
	Hash string `json:"hash"`
	// Index is the funding output index.
	Index uint32 `json:"index"`
}

RefundPrevout identifies the funding outpoint. Hash is the display/BE txid hex.

type RefundTapLeaf 

type RefundTapLeaf struct {
	// LeafVersion is the tapscript leaf version (0xc0 for the vault cooperative leaf).
	LeafVersion uint8 `json:"leafVersion"`
	// Script is the hex-encoded tapleaf script.
	Script string `json:"script"`
	// ControlBlock is the hex-encoded control block proving the leaf's inclusion in the taproot tree.
	ControlBlock string `json:"controlBlock"`
}

RefundTapLeaf is the tapscript spend path (the vault cooperative leaf).

type RefundTapSig 

type RefundTapSig struct {
	// Pubkey is the signer's x-only(32) hex public key.
	Pubkey string `json:"pubkey"`
	// LeafHash is the tapleaf hash hex the signature is bound to.
	LeafHash string `json:"leafHash"`
	// Signature is the 64-byte BIP-340 signature hex.
	Signature string `json:"signature"`
}

RefundTapSig is a PSBT tapscript partial signature.

type RefundTx 

type RefundTx struct {
	// Version is the tx version (2 for CSV-aware refunds).
	Version uint32 `json:"version"`
	// Locktime is nLockTime (0 for a cooperative refund).
	Locktime uint32 `json:"locktime"`
	// Inputs holds exactly one entry: the funding UTXO.
	Inputs []RefundInput `json:"inputs"`
	// Outputs holds the refund outputs; Outputs[0] is to_local, the rest are extras.
	Outputs []RefundOutput `json:"outputs"`
	// UserSig is the vault owner's 64-byte BIP-340 signature (hex) over the
	// cooperative-leaf sighash. Required.
	UserSig string `json:"userSig,omitempty"`
}

RefundTx is the PSBT-shaped refund transaction SignService.Transaction accepts and returns. Field naming mirrors the daemon's reference schema (camelCase).

type RefundWitnessUtxo 

type RefundWitnessUtxo struct {
	// Value is the prevout amount in satoshis.
	Value int64 `json:"value"`
	// Script is the hex-encoded prevout locking script.
	Script string `json:"script"`
}

RefundWitnessUtxo is the prevout the input sighash commits to (the vault P2TR output).

type Response 

type Response struct {
	// Response is the raw HTTP response the service method received.
	*http.Response
}

Response wraps the raw *http.Response returned by every service method, mirroring the shape used by most official Go API clients so callers can inspect status/headers alongside the decoded result.

type SearchResponse 

type SearchResponse struct {
	// Type is the kind of entity Result matched: one of "block", "epoch", "tx", "vtxo", or "address".
	Type string `json:"type"`
	// Result is the matching entity payload; its shape depends on Type.
	Result json.RawMessage `json:"result"`
}

SearchResponse is returned by DashboardService.Search. Type is one of "block", "epoch", "tx", "vtxo", or "address"; Result's shape depends on Type — the SDK leaves it as raw JSON since each type has a different schema. Use json.Unmarshal(resp.Result, &dst) with the appropriate target type (a map for "block"/"address", GetEpochResponse, GetTransactionResponse, etc).

type SignService 

type SignService service

SignService wraps the cooperative-refund threshold-signing ceremony.

func (*SignService) Transaction 

func (s *SignService) Transaction(ctx context.Context, tx *RefundTx) (*SignTransactionResponse, *Response, error)

Transaction fans a PSBT-shaped refund transaction (which must carry the owner's UserSig over the cooperative-leaf sighash) out to the vault's signing quorum and returns it with the collected tapScriptSig partials attached. The caller adds its own user signature and finalizes.

Returns a 503 *ErrorResponse if refund signing is disabled on the daemon, or a 504 *ErrorResponse if the signing threshold wasn't reached in time.

type SignTransactionResponse 

type SignTransactionResponse struct {
	// Refund is the refund transaction with the quorum partial signatures attached.
	Refund *RefundTx `json:"refund"`
	// Signatures is the number of quorum partial signatures collected.
	Signatures int `json:"signatures" example:"5"`
}

SignTransactionResponse is returned by SignService.Transaction.

type StatsResponse 

type StatsResponse struct {
	// Height is the latest committed block height reported by the ABCI app.
	Height int64 `json:"height"`
	// TotalTransactions is the cumulative count of transactions across all epoch commits.
	TotalTransactions int `json:"total_transactions"`
	// TotalAccounts is the number of distinct accounts; currently always 0 pending an ABCI owner-count path.
	TotalAccounts int `json:"total_accounts"`
	// CurrentEpoch is the currently open epoch ID.
	CurrentEpoch uint32 `json:"current_epoch"`
	// NodeCount is the number of validator nodes known via KDHT, plus self.
	NodeCount int `json:"node_count"`
	// ChainID identifies the chain (mirrors CometBFT's node_info.network).
	ChainID string `json:"chain_id"`
	// LatestBlockTime is the unix-seconds timestamp of the latest block; omitted when unknown.
	LatestBlockTime *int64 `json:"latest_block_time,omitempty"`
	// TotalSupplySat is the total circulating supply in satoshis (sum of unspent VTXO amounts).
	TotalSupplySat int64 `json:"total_supply_sat"`
	// VTXOCount is the total number of unspent VTXOs across the chain.
	VTXOCount int `json:"vtxo_count"`
}

StatsResponse is returned by DashboardService.Stats.

type SubscribeOptions 

type SubscribeOptions struct {
	// Address watches for incoming vouts to this taproot address or pubkey hex.
	Address string
	// Vault watches for incoming locks into this vault address.
	Vault string
	// VaultID watches for watchtower breach receipts on this vault (64-hex).
	VaultID string
	// Blocks subscribes to an alert for every durably-committed block.
	Blocks bool
	// Validators subscribes to an alert for every new validator registration.
	Validators bool
	// Txs subscribes to every transaction (pending, then committed),
	// unfiltered by Address/Vault.
	Txs bool
}

SubscribeOptions selects which alerts a websocket connection receives. At least one field must be set.

type SupplyResponse 

type SupplyResponse struct {
	// TotalSupplySat is the total circulating supply in satoshis (sum of all unspent VTXO amounts).
	TotalSupplySat int64 `json:"total_supply_sat"`
	// VTXOCount is the total number of unspent VTXOs across the chain.
	VTXOCount int `json:"vtxo_count"`
}

SupplyResponse is returned by DashboardService.Supply.

type TxDecodeResponse 

type TxDecodeResponse struct {
	// TxHash is the hex-encoded tmhash of the raw transaction bytes.
	TxHash string `json:"tx_hash"`
	// Type is transfer/deposit/withdraw/lock/unlock/vault_open/
	// vault_state_advance/vault_close/vault_breach/unknown.
	Type string `json:"type"`
	// Version is the TachiTx protocol version byte.
	Version uint8 `json:"version"`
	// Fee is the fee paid by the transaction in satoshis.
	Fee int64 `json:"fee"`
	// Nonce is the sender's transaction nonce as committed by the signer.
	Nonce uint64 `json:"nonce"`
	// Size is the byte length of the decoded raw transaction.
	Size int `json:"size"`
	// IsSegwit reports whether any input carries witness data (a non-empty SigScript).
	IsSegwit bool `json:"is_segwit"`
	// Weight is the Bitcoin-style segwit weight: 3*baseSize + totalSize.
	Weight int `json:"weight"`
	// VSize is the Bitcoin-style virtual size: ceil(Weight/4).
	VSize int `json:"vsize"`
	// Vin lists the VTXO inputs being spent by this transaction.
	Vin []TxVin `json:"vin"`
	// Vout lists the VTXO outputs produced by this transaction.
	Vout []TxVout `json:"vout"`
	// PubKey is the hex-encoded signer public key authorizing the transaction.
	PubKey string `json:"pubkey"`
}

TxDecodeResponse is returned by TxService.Decode.

type TxOptions 

type TxOptions struct {
	// HAT attaches the HAT commitment for the tx's first spent VTXO.
	HAT bool
	// RIP attaches a RIP inclusion proof; requires OriginEpoch and FinalEpoch.
	RIP bool
	// OriginEpoch is the epoch the HAT was inserted into (required when RIP is true).
	OriginEpoch uint32
	// FinalEpoch is the L1-settled epoch to chain the proof up to (required when RIP is true).
	FinalEpoch uint32
}

TxOptions configures TxService.Get's optional proof attachments.

type TxService 

type TxService service

TxService groups transaction endpoints: lookup, decode/validate, broadcast, mempool, and fee estimation.

func (*TxService) BroadcastAsync 

func (s *TxService) BroadcastAsync(ctx context.Context, hexTx string) (*CometRPCResponse, *Response, error)

BroadcastAsync forwards a hex-encoded transaction to CometBFT's broadcast_tx_async, returning immediately without waiting for CheckTx.

func (*TxService) BroadcastSync 

func (s *TxService) BroadcastSync(ctx context.Context, hexTx string) (*CometRPCResponse, *Response, error)

BroadcastSync forwards a hex-encoded transaction to CometBFT's broadcast_tx_sync, waiting for CheckTx to complete before returning.

func (*TxService) Decode 

func (s *TxService) Decode(ctx context.Context, hexTx string) (*TxDecodeResponse, *Response, error)

Decode decodes a raw hex-encoded Tachi transaction without broadcasting it.

func (*TxService) FeeEstimate 

func (s *TxService) FeeEstimate(ctx context.Context) (*FeeEstimateResponse, *Response, error)

FeeEstimate returns the minimum, average, and recommended transaction fee based on recent confirmed transactions.

func (*TxService) Get 

func (s *TxService) Get(ctx context.Context, hash string, opts *TxOptions) (*GetTransactionResponse, *Response, error)

Get returns a Tachi-decoded view of a transaction by its 40-char hex CometBFT hash. Looks up committed txs first, then falls back to the unconfirmed mempool.

func (*TxService) List 

func (s *TxService) List(ctx context.Context, opts *ListTransactionsOptions) (*ListTransactionsResponse, *Response, error)

List returns committed transactions in descending height order, height-cursor paginated. Pass the previous response's NextBeforeHeight as opts.BeforeHeight to fetch the next page; when NextBeforeHeight is nil the scan has reached genesis.

func (*TxService) Mempool 

func (s *TxService) Mempool(ctx context.Context) (*MempoolResponse, *Response, error)

Mempool returns decoded pending transactions from the CometBFT unconfirmed mempool.

func (*TxService) Raw 

func (s *TxService) Raw(ctx context.Context, hash string) (*GetRawTransactionResponse, *Response, error)

Raw returns just the raw hex-encoded bytes of a transaction by its 40-char hex CometBFT hash.

func (*TxService) Validate 

func (s *TxService) Validate(ctx context.Context, hexTx string) (*TxValidateResponse, *Response, error)

Validate validates a hex-encoded transaction against current chain state via CometBFT CheckTx, without broadcasting.

type TxStatus 

type TxStatus struct {
	// Code is the ABCI execution code; 0 means success, non-zero means failure.
	Code uint32 `json:"code"`
	// Log is the ABCI execution log message; "pending" for mempool txs.
	Log string `json:"log"`
}

TxStatus mirrors the ABCI tx_result {code, log} pair. For pending txs the daemon reports code=0, log="pending"; for committed txs the values come from FinalizeBlock's ExecTxResult.

type TxValidateResponse 

type TxValidateResponse struct {
	// Valid is true when CometBFT CheckTx returned code 0 (transaction is acceptable).
	Valid bool `json:"valid"`
	// Code is the raw ABCI CheckTx response code; non-zero indicates rejection.
	Code uint32 `json:"code"`
	// Log is the human-readable CheckTx log message explaining acceptance or rejection.
	Log string `json:"log"`
}

TxValidateResponse is returned by TxService.Validate.

type TxVin 

type TxVin struct {
	// VTXOID is the hex-encoded 32-byte identifier of the VTXO being spent.
	VTXOID string `json:"vtxo_id"` // 64-char hex
	// Txid is the hex-encoded 32-byte parent transaction hash that created the VTXO.
	Txid string `json:"txid"` // 64-char hex
	// Vout is the zero-based output index within the parent transaction.
	Vout uint32 `json:"vout"`
	// ValueSats is the satoshi value committed by the input from the spent VTXO.
	ValueSats int64 `json:"value_sats"`
	// SigScript is the hex-encoded signature script authorizing the spend.
	SigScript string `json:"sig_script"` // hex
}

TxVin is a hex-encoded view of a TachiTx VTXOInput.

type TxVout 

type TxVout struct {
	// Owner is the hex-encoded public key authorized to spend this output's VTXO.
	Owner string `json:"owner"` // hex pubkey
	// Amount is the value of this output in satoshis.
	Amount int64 `json:"amount"`
	// Script is the hex-encoded locking script attached to the output.
	Script string `json:"script"` // hex
}

TxVout is a hex-encoded view of a TachiTx VTXOOutput.

type VTXOItem 

type VTXOItem struct {
	// ID is the hex-encoded 32-byte VTXO identifier.
	ID string `json:"id"`
	// Owner is the hex-encoded owner public key authorized to spend this VTXO.
	Owner string `json:"owner"`
	// Amount is the VTXO value in satoshis.
	Amount int64 `json:"amount"`
	// Spent is true once this VTXO has been consumed by a confirmed transaction.
	Spent bool `json:"spent"`
	// Height is the block height at which this VTXO was created.
	Height int64 `json:"height"`
	// Script is the hex-encoded locking script associated with this VTXO.
	Script string `json:"script"`
	// Locked is true while this VTXO is bound to a vault and not freely spendable.
	Locked bool `json:"locked"`
	// VaultAddress is the bech32m P2TR vault address when Locked is true; empty otherwise.
	VaultAddress string `json:"vault_address,omitempty"`
	// BTCHeight is the Bitcoin L1 block height of the deposit that created
	// this VTXO; 0 when not a deposit or not yet populated.
	BTCHeight uint32 `json:"btc_height,omitempty"`
	// BTCTimestamp is the Bitcoin L1 block timestamp of the deposit that
	// created this VTXO; 0 when not a deposit or not yet populated.
	BTCTimestamp uint32 `json:"btc_timestamp,omitempty"`
}

VTXOItem is a single VTXO in an AddressService.VTXOs response.

type VTXOResponse 

type VTXOResponse struct {
	// ID is the hex-encoded 32-byte VTXO identifier.
	ID string `json:"id"`
	// Owner is the hex-encoded owner public key authorized to spend this VTXO.
	Owner string `json:"owner"`
	// Amount is the VTXO value in satoshis.
	Amount int64 `json:"amount"`
	// Spent is true once this VTXO has been consumed by a confirmed transaction.
	Spent bool `json:"spent"`
	// Height is the block height at which this VTXO was created.
	Height int64 `json:"height"`
	// Script is the hex-encoded locking script associated with this VTXO.
	Script string `json:"script"`
	// Locked is true while this VTXO is locked to a vault.
	Locked bool `json:"locked"`
	// VaultAddress is the bech32m P2TR vault address this VTXO is locked
	// to; empty when Locked is false.
	VaultAddress string `json:"vault_address,omitempty"`
	// BTCHeight is the Bitcoin L1 block height of the deposit that created
	// this VTXO; 0 when not a deposit or not yet populated.
	BTCHeight uint32 `json:"btc_height,omitempty"`
	// BTCTimestamp is the Bitcoin L1 block timestamp of the deposit that
	// created this VTXO; 0 when not a deposit or not yet populated.
	BTCTimestamp uint32 `json:"btc_timestamp,omitempty"`
}

VTXOResponse is returned by VTXOService.Get and appears in LockedVTXOsResponse and ListVTXOsResponse.

type VTXOService 

type VTXOService service

VTXOService groups VTXO-lookup endpoints.

func (*VTXOService) Get 

func (s *VTXOService) Get(ctx context.Context, id string) (*VTXOResponse, *Response, error)

Get returns a single VTXO by its 64-char hex ID.

func (*VTXOService) List 

func (s *VTXOService) List(ctx context.Context, page, pageSize int) (*ListVTXOsResponse, *Response, error)

List returns a paginated list of all VTXOs (unspent and spent), sorted by height descending. page defaults to 1; pageSize defaults to 50 (max 100). Pass 0 for either to use the default.

func (*VTXOService) Locked 

func (s *VTXOService) Locked(ctx context.Context, vault string) (*LockedVTXOsResponse, *Response, error)

Locked returns all VTXOs locked for the given vault address.

type ValidatorCountResponse 

type ValidatorCountResponse struct {
	// Count is the number of validators currently in the bootstrap registry.
	Count int `json:"count" example:"3"`
}

ValidatorCountResponse is returned by ValidatorsService.Count.

type ValidatorInfo 

type ValidatorInfo struct {
	// PeerID is the libp2p peer identifier used by the discovery overlay.
	PeerID string `json:"peer_id"`
	// PubKeyHex is the compressed secp256k1 validator public key hex used for signed registration.
	PubKeyHex string `json:"pub_key_hex"`
	// Host is the CometBFT P2P address "host:port" the validator listens on.
	Host string `json:"host,omitempty"`
	// P2PPort is the CometBFT P2P listening port advertised by the validator.
	P2PPort int `json:"p2p_port,omitempty"`
	// RPCAddr is the daemon RPC listen address ("host:port") this validator serves.
	RPCAddr string `json:"rpc_addr,omitempty"`
}

ValidatorInfo represents a registered validator, and is also the shape returned by ValidatorsService.PeerInfo for the local node.

type ValidatorsResponse 

type ValidatorsResponse struct {
	// Validators is the merged list of bootstrap-registered and KDHT-discovered validators.
	Validators []ValidatorInfo `json:"validators"`
	// Count is the total number of validators in the response.
	Count int `json:"count" example:"3"`
}

ValidatorsResponse is returned by ValidatorsService.List.

type ValidatorsService 

type ValidatorsService service

ValidatorsService groups the bootstrap validator registry and this node's own peer info.

func (*ValidatorsService) Count 

func (s *ValidatorsService) Count(ctx context.Context) (*ValidatorCountResponse, *Response, error)

Count returns the number of validators currently in the bootstrap registry.

func (*ValidatorsService) List 

func (s *ValidatorsService) List(ctx context.Context) (*ValidatorsResponse, *Response, error)

List returns the merged list of bootstrap-registered and KDHT-discovered validators.

func (*ValidatorsService) Live 

func (s *ValidatorsService) Live(ctx context.Context) (*LiveValidatorsResponse, *Response, error)

Live returns only validators whose peers are currently connected via the overlay network.

func (*ValidatorsService) PeerInfo 

func (s *ValidatorsService) PeerInfo(ctx context.Context) (*ValidatorInfo, *Response, error)

PeerInfo returns this node's PeerID, public key, and network addresses.

func (*ValidatorsService) Ready 

func (s *ValidatorsService) Ready(ctx context.Context, expected int) (*ReadyResponse, *Response, error)

Ready long-polls (up to 60s server-side) until expected validators have registered, then returns the current registry snapshot.

type VaultListItem 

type VaultListItem struct {
	// VaultID is the hex VaultID = H(funding_txid || vout).
	VaultID string `json:"vault_id"`
	// Name is the display label set at open. Not unique — key on VaultID.
	// Untrusted: chosen by the vault opener and may contain HTML
	// metacharacters. Escape it for the render context before displaying.
	Name string `json:"name,omitempty"`
	// State is the vault lifecycle label (always "open" today).
	State string `json:"state"`
	// LatestStateNum is the vault's latest state number (always 0 today).
	LatestStateNum uint64 `json:"latest_state_num"`
	// FundingTxid is the hex L1 funding transaction id.
	FundingTxid string `json:"funding_txid"`
	// FundingVout is the L1 funding output index.
	FundingVout uint32 `json:"funding_vout"`
	// Address is the bech32m P2TR vault address; the ?vault= websocket filter key.
	Address string `json:"address"`
	// CSVDelay, Threshold, QuorumKeyset, and UserKey are the vault's
	// reconstruction parameters. Only populated when the Client was
	// created with WithAPIKey using a valid master key or a client key
	// registered with the vault scope; omitted otherwise.
	CSVDelay uint32 `json:"csv_delay,omitempty"`
	// Threshold is the number of quorum signatures required to authorize a spend.
	Threshold int `json:"threshold,omitempty"`
	// QuorumKeyset is the list of quorum member public keys.
	QuorumKeyset []string `json:"quorum_keyset,omitempty"`
	// UserKey is the vault owner's public key.
	UserKey string `json:"user_key,omitempty"`
}

VaultListItem is a compact per-vault view returned by VaultService.List.

type VaultService 

type VaultService service

VaultService groups vault-lookup endpoints.

func (*VaultService) List 

func (s *VaultService) List(ctx context.Context, user string, page, pageSize int) (*ListVaultsResponse, *Response, error)

List returns a paginated list of vaults owned by user (a public key or taproot address). csv_delay/threshold/quorum_keyset/user_key are only populated when the Client was created with WithAPIKey using a valid master key or a vault-scoped client key. page defaults to 1; pageSize defaults to 50 (max 100). Pass 0 for either to use the default.

type WSBlockAlert 

type WSBlockAlert struct {
	// Height is the committed block height.
	Height int64 `json:"height"`
	// BlockHash is the hex-encoded committing block hash.
	BlockHash string `json:"block_hash"`
	// AppHash is the hex-encoded ABCI app hash for this block.
	AppHash string `json:"app_hash"`
	// TxCount is the number of transactions included in this block.
	TxCount int `json:"tx_count"`
	// EpochClosed is the epoch ID this block closed; omitted for blocks that didn't close an epoch.
	EpochClosed *uint32 `json:"epoch_closed,omitempty"`
}

WSBlockAlert is pushed to "blocks" subscribers for every durably-committed block.

type WSBreachAlert 

type WSBreachAlert struct {
	// VaultID is the hex VaultID whose funding outpoint was spent.
	VaultID string `json:"vault_id"`
	// BroadcastState is the state decoded from the spending tx's hint.
	BroadcastState uint64 `json:"broadcast_state"`
	// LatestState is the BFT-replicated latest state at detection.
	LatestState uint64 `json:"latest_state"`
	// Classification is "legitimate", "stale", or "anomalous".
	Classification string `json:"classification"`
	// SpendTxID is the L1 txid that spent the funding outpoint.
	SpendTxID string `json:"spend_txid"`
	// SpendVout is the funding output index that was consumed.
	SpendVout uint32 `json:"spend_vout"`
	// DetectedHeight is the L1 block height the spend was observed at.
	DetectedHeight int64 `json:"detected_height"`
	// DetectedAt is the node's wall-clock unix timestamp at detection.
	DetectedAt int64 `json:"detected_at"`
}

WSBreachAlert is pushed to "vaultId" subscribers when the watchtower observes an L1 spend of a vault's funding outpoint — every classification (legitimate/stale/anomalous) is delivered, same population as WatchtowerService.Receipts.

type WSConn 

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

WSConn is a live subscription opened by WSService.Subscribe. Events arrive on the channel returned by Events(); a transport error or server close terminates the read loop, closes the Events channel, and is reported once on Err(). Callers must call Close when done.

func (*WSConn) Close 

func (w *WSConn) Close() error

Close closes the underlying websocket connection. Safe to call multiple times.

func (*WSConn) Err 

func (w *WSConn) Err() <-chan error

Err returns a channel that receives at most one error when the read loop terminates abnormally (transport error, unexpected close). A clean close (via Close) delivers nothing.

func (*WSConn) Events 

func (w *WSConn) Events() <-chan WSEvent

Events returns the channel of incoming alerts. It is closed when the connection ends (see Err for the reason, if any).

type WSEvent 

type WSEvent struct {
	// Event is "tx", "block", "validator", or "breach".
	Event string `json:"event"`
	// Tx is set when Event == "tx".
	Tx *WSTxAlert `json:"tx,omitempty"`
	// Block is set when Event == "block".
	Block *WSBlockAlert `json:"block,omitempty"`
	// Validator is set when Event == "validator".
	Validator *WSValidatorAlert `json:"validator,omitempty"`
	// Breach is set when Event == "breach".
	Breach *WSBreachAlert `json:"breach,omitempty"`
}

WSEvent is the envelope delivered on WSConn.Events(). Event discriminates which of Tx/Block/Validator/Breach is populated, since one subscription can watch multiple filters at once.

type WSService 

type WSService service

WSService opens live websocket subscriptions for chain alerts.

func (*WSService) Subscribe 

func (s *WSService) Subscribe(ctx context.Context, opts SubscribeOptions) (*WSConn, error)

Subscribe upgrades to a websocket and streams tx, block, validator, and/or watchtower-breach alerts per opts. The connection is push-only — the server never expects client messages, and the SDK's read loop answers server pings transparently (handled by the underlying websocket.Conn).

type WSTxAlert 

type WSTxAlert struct {
	// TxHash is the hex-encoded hash of the matching transaction.
	TxHash string `json:"tx_hash"`
	// Type is transfer/deposit/withdraw/lock/unlock/vault_open/
	// vault_state_advance/vault_close/vault_breach/unknown.
	Type string `json:"type"`
	// State is "pending" (seen via CheckTx) or "committed".
	State string `json:"state"`
	// Height is the block height that committed the transaction; 0/omitted while State is "pending".
	Height int64 `json:"height,omitempty"`
	// VaultAddress is set only when the alert matched on a vault subscription.
	VaultAddress string `json:"vault_address,omitempty"`
	// Vout lists the transaction's outputs.
	Vout []TxVout `json:"vout"`
}

WSTxAlert is pushed when a tx (pending or committed) matches an address/vault subscription.

type WSValidatorAlert 

type WSValidatorAlert struct {
	// PubKeyHex is the compressed secp256k1 public key of the joining validator.
	PubKeyHex string `json:"pub_key_hex"`
	// PeerID is the joining validator's libp2p peer identifier.
	PeerID string `json:"peer_id,omitempty"`
	// Host is the joining validator's CometBFT P2P address "host:port".
	Host string `json:"host,omitempty"`
	// RPCAddr is the joining validator's daemon RPC listen address.
	RPCAddr string `json:"rpc_addr,omitempty"`
	// Total is the registry size immediately after this join.
	Total int `json:"total"`
}

WSValidatorAlert is pushed to "validators" subscribers when a new validator registers.

type WatchtowerService 

type WatchtowerService service

WatchtowerService groups the vault watchtower's status and breach-receipt endpoints.

func (*WatchtowerService) Receipt 

func (s *WatchtowerService) Receipt(ctx context.Context, vaultID string, state uint64) (*BreachReceipt, *Response, error)

Receipt returns a single breach receipt for vaultID at the given broadcast state number. Returns a 404 *ErrorResponse if no receipt exists at that state.

func (*WatchtowerService) Receipts 

func (s *WatchtowerService) Receipts(ctx context.Context, vaultID string) ([]BreachReceipt, *Response, error)

Receipts lists breach receipts, optionally filtered to one vault (pass "" for vaultID to list every receipt). Returns a 503 *ErrorResponse if the watchtower is disabled.

func (*WatchtowerService) Status 

func (s *WatchtowerService) Status(ctx context.Context) (*WatchtowerStatus, *Response, error)

Status returns the watchtower mode, last-scanned L1 height, and receipt count. Returns a 503 *ErrorResponse if the watchtower is disabled.

type WatchtowerStatus 

type WatchtowerStatus struct {
	// Mode is "detection" (watch + receipt only), "responder" (also co-signs
	// peers' sweeps), or "initiator" (also originates and broadcasts sweeps).
	Mode string `json:"mode"`
	// LastScannedHeight is the L1 height the subscriber has scanned through.
	LastScannedHeight int64 `json:"last_scanned_height"`
	// ReceiptCount is the number of breach receipts on record.
	ReceiptCount int `json:"receipt_count"`
	// SweepThreshold is the partial-signature threshold the collector requires.
	SweepThreshold int `json:"sweep_threshold"`
	// BountyConfigured reports whether a sweep-bounty payout script is set
	// (required to initiate sweeps).
	BountyConfigured bool `json:"bounty_configured"`
}

WatchtowerStatus is returned by WatchtowerService.Status.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.