diff --git a/api/types.go b/api/types.go index 84c98ae3..a126eb67 100644 --- a/api/types.go +++ b/api/types.go @@ -42,8 +42,8 @@ var ErrUnsupportedXpub = errors.New("XPUB not supported") // APIError extends error by information if the error details should be returned to the end user type APIError struct { - Text string - Public bool + Text string `ts_doc:"Human-readable error message describing the issue."` + Public bool `ts_doc:"Whether the error message can safely be shown to the end user."` } func (e *APIError) Error() string { @@ -58,16 +58,16 @@ func NewAPIError(s string, public bool) error { } } -// Amount is datatype holding amounts +// Amount is a datatype holding amounts type Amount big.Int -// IsZeroBigInt if big int has zero value +// IsZeroBigInt checks if big int has zero value func IsZeroBigInt(b *big.Int) bool { return len(b.Bits()) == 0 } // Compare returns an integer comparing two Amounts. The result will be 0 if a == b, -1 if a < b, and +1 if a > b. -// Nil Amount is always less then non nil amount, two nil Amounts are equal +// Nil Amount is always less then non-nil amount, two nil Amounts are equal func (a *Amount) Compare(b *Amount) int { if b == nil { if a == nil { @@ -136,41 +136,41 @@ func (a *Amount) AsInt64() int64 { // Vin contains information about single transaction input type Vin struct { - Txid string `json:"txid,omitempty"` - Vout uint32 `json:"vout,omitempty"` - Sequence int64 `json:"sequence,omitempty"` - N int `json:"n"` - AddrDesc bchain.AddressDescriptor `json:"-"` - Addresses []string `json:"addresses,omitempty"` - IsAddress bool `json:"isAddress"` - IsOwn bool `json:"isOwn,omitempty"` - ValueSat *Amount `json:"value,omitempty"` - Hex string `json:"hex,omitempty"` - Asm string `json:"asm,omitempty"` - Coinbase string `json:"coinbase,omitempty"` + Txid string `json:"txid,omitempty" ts_doc:"ID/hash of the originating transaction (where the UTXO comes from)."` + Vout uint32 `json:"vout,omitempty" ts_doc:"Index of the output in the referenced transaction."` + Sequence int64 `json:"sequence,omitempty" ts_doc:"Sequence number for this input (e.g. 4294967293)."` + N int `json:"n" ts_doc:"Relative index of this input within the transaction."` + AddrDesc bchain.AddressDescriptor `json:"-" ts_doc:"Internal address descriptor for backend usage (not exposed via JSON)."` + Addresses []string `json:"addresses,omitempty" ts_doc:"List of addresses associated with this input."` + IsAddress bool `json:"isAddress" ts_doc:"Indicates if this input is from a known address."` + IsOwn bool `json:"isOwn,omitempty" ts_doc:"Indicates if this input belongs to the wallet in context."` + ValueSat *Amount `json:"value,omitempty" ts_doc:"Amount (in satoshi or base units) of the input."` + Hex string `json:"hex,omitempty" ts_doc:"Raw script hex data for this input."` + Asm string `json:"asm,omitempty" ts_doc:"Disassembled script for this input."` + Coinbase string `json:"coinbase,omitempty" ts_doc:"Data for coinbase inputs (when mining)."` } // Vout contains information about single transaction output type Vout struct { - ValueSat *Amount `json:"value,omitempty"` - N int `json:"n"` - Spent bool `json:"spent,omitempty"` - SpentTxID string `json:"spentTxId,omitempty"` - SpentIndex int `json:"spentIndex,omitempty"` - SpentHeight int `json:"spentHeight,omitempty"` - Hex string `json:"hex,omitempty"` - Asm string `json:"asm,omitempty"` - AddrDesc bchain.AddressDescriptor `json:"-"` - Addresses []string `json:"addresses"` - IsAddress bool `json:"isAddress"` - IsOwn bool `json:"isOwn,omitempty"` - Type string `json:"type,omitempty"` + ValueSat *Amount `json:"value,omitempty" ts_doc:"Amount (in satoshi or base units) of the output."` + N int `json:"n" ts_doc:"Relative index of this output within the transaction."` + Spent bool `json:"spent,omitempty" ts_doc:"Indicates whether this output has been spent."` + SpentTxID string `json:"spentTxId,omitempty" ts_doc:"Transaction ID in which this output was spent."` + SpentIndex int `json:"spentIndex,omitempty" ts_doc:"Index of the input that spent this output."` + SpentHeight int `json:"spentHeight,omitempty" ts_doc:"Block height at which this output was spent."` + Hex string `json:"hex,omitempty" ts_doc:"Raw script hex data for this output - aka ScriptPubKey."` + Asm string `json:"asm,omitempty" ts_doc:"Disassembled script for this output."` + AddrDesc bchain.AddressDescriptor `json:"-" ts_doc:"Internal address descriptor for backend usage (not exposed via JSON)."` + Addresses []string `json:"addresses" ts_doc:"List of addresses associated with this output."` + IsAddress bool `json:"isAddress" ts_doc:"Indicates whether this output is owned by valid address."` + IsOwn bool `json:"isOwn,omitempty" ts_doc:"Indicates if this output belongs to the wallet in context."` + Type string `json:"type,omitempty" ts_doc:"Output script type (e.g., 'P2PKH', 'P2SH')."` } -// MultiTokenValue contains values for contract with id and value (like ERC1155) +// MultiTokenValue contains values for contracts with multiple token IDs type MultiTokenValue struct { - Id *Amount `json:"id,omitempty"` - Value *Amount `json:"value,omitempty"` + Id *Amount `json:"id,omitempty" ts_doc:"Token ID (for ERC1155)."` + Value *Amount `json:"value,omitempty" ts_doc:"Amount of that specific token ID."` } // Token contains info about tokens held by an address @@ -178,19 +178,19 @@ type Token struct { // Deprecated: Use Standard instead. Type bchain.TokenStandardName `json:"type" ts_type:"'' | 'XPUBAddress' | 'ERC20' | 'ERC721' | 'ERC1155' | 'BEP20' | 'BEP721' | 'BEP1155'" ts_doc:"@deprecated: Use standard instead."` Standard bchain.TokenStandardName `json:"standard" ts_type:"'' | 'XPUBAddress' | 'ERC20' | 'ERC721' | 'ERC1155' | 'BEP20' | 'BEP721' | 'BEP1155'"` - Name string `json:"name"` - Path string `json:"path,omitempty"` - Contract string `json:"contract,omitempty"` - Transfers int `json:"transfers"` - Symbol string `json:"symbol,omitempty"` - Decimals int `json:"decimals"` - BalanceSat *Amount `json:"balance,omitempty"` - BaseValue float64 `json:"baseValue,omitempty"` // value in the base currency (ETH for Ethereum) - SecondaryValue float64 `json:"secondaryValue,omitempty"` // value in secondary (fiat) currency, if specified - Ids []Amount `json:"ids,omitempty"` // multiple ERC721 tokens - MultiTokenValues []MultiTokenValue `json:"multiTokenValues,omitempty"` // multiple ERC1155 tokens - TotalReceivedSat *Amount `json:"totalReceived,omitempty"` - TotalSentSat *Amount `json:"totalSent,omitempty"` + Name string `json:"name" ts_doc:"Readable name of the token."` + Path string `json:"path,omitempty" ts_doc:"Derivation path if this token is derived from an XPUB-based address."` + Contract string `json:"contract,omitempty" ts_doc:"Contract address on-chain."` + Transfers int `json:"transfers" ts_doc:"Total number of token transfers for this address."` + Symbol string `json:"symbol,omitempty" ts_doc:"Symbol for the token (e.g., 'ETH', 'USDT')."` + Decimals int `json:"decimals,omitempty" ts_doc:"Number of decimals for this token."` + BalanceSat *Amount `json:"balance,omitempty" ts_doc:"Current token balance (in minimal base units)."` + BaseValue float64 `json:"baseValue,omitempty" ts_doc:"Value in the base currency (e.g. ETH for ERC20 tokens)."` + SecondaryValue float64 `json:"secondaryValue,omitempty" ts_doc:"Value in a secondary currency (e.g. fiat), if available."` + Ids []Amount `json:"ids,omitempty" ts_doc:"List of token IDs (for ERC721, each ID is a unique collectible)."` + MultiTokenValues []MultiTokenValue `json:"multiTokenValues,omitempty" ts_doc:"Multiple ERC1155 token balances (id + value)."` + TotalReceivedSat *Amount `json:"totalReceived,omitempty" ts_doc:"Total amount of tokens received."` + TotalSentSat *Amount `json:"totalSent,omitempty" ts_doc:"Total amount of tokens sent."` ContractIndex string `json:"-"` } @@ -226,90 +226,94 @@ type TokenTransfer struct { // Deprecated: Use Standard instead. Type bchain.TokenStandardName `json:"type" ts_type:"'' | 'XPUBAddress' | 'ERC20' | 'ERC721' | 'ERC1155' | 'BEP20' | 'BEP721' | 'BEP1155'" ts_doc:"@deprecated: Use standard instead."` Standard bchain.TokenStandardName `json:"standard" ts_type:"'' | 'XPUBAddress' | 'ERC20' | 'ERC721' | 'ERC1155' | 'BEP20' | 'BEP721' | 'BEP1155'"` - From string `json:"from"` - To string `json:"to"` - Contract string `json:"contract"` - Name string `json:"name,omitempty"` - Symbol string `json:"symbol,omitempty"` - Decimals int `json:"decimals"` - Value *Amount `json:"value,omitempty"` - MultiTokenValues []MultiTokenValue `json:"multiTokenValues,omitempty"` + From string `json:"from" ts_doc:"Source address of the token transfer."` + To string `json:"to" ts_doc:"Destination address of the token transfer."` + Contract string `json:"contract" ts_doc:"Contract address of the token."` + Name string `json:"name,omitempty" ts_doc:"Token name."` + Symbol string `json:"symbol,omitempty" ts_doc:"Token symbol."` + Decimals int `json:"decimals,omitempty" ts_doc:"Number of decimals for this token (if applicable)."` + Value *Amount `json:"value,omitempty" ts_doc:"Amount (in base units) of tokens transferred."` + MultiTokenValues []MultiTokenValue `json:"multiTokenValues,omitempty" ts_doc:"List of multiple ID-value pairs for ERC1155 transfers."` } +// EthereumInternalTransfer represents internal transaction data in Ethereum-like blockchains type EthereumInternalTransfer struct { - Type bchain.EthereumInternalTransactionType `json:"type"` - From string `json:"from"` - To string `json:"to"` - Value *Amount `json:"value"` + Type bchain.EthereumInternalTransactionType `json:"type" ts_doc:"Type of internal transfer (CALL, CREATE, etc.)."` + From string `json:"from" ts_doc:"Address from which the transfer originated."` + To string `json:"to" ts_doc:"Address to which the transfer was sent."` + Value *Amount `json:"value" ts_doc:"Value transferred internally (in Wei or base units)."` } -// EthereumSpecific contains ethereum specific transaction data +// EthereumSpecific contains ethereum-specific transaction data type EthereumSpecific struct { - Type bchain.EthereumInternalTransactionType `json:"type,omitempty"` - CreatedContract string `json:"createdContract,omitempty"` - Status eth.TxStatus `json:"status"` // 1 OK, 0 Fail, -1 pending - Error string `json:"error,omitempty"` - Nonce uint64 `json:"nonce"` - GasLimit *big.Int `json:"gasLimit"` - GasUsed *big.Int `json:"gasUsed,omitempty"` - GasPrice *Amount `json:"gasPrice,omitempty"` + Type bchain.EthereumInternalTransactionType `json:"type,omitempty" ts_doc:"High-level type of the Ethereum tx (e.g., 'call', 'create')."` + CreatedContract string `json:"createdContract,omitempty" ts_doc:"Address of contract created by this transaction, if any."` + Status eth.TxStatus `json:"status" ts_doc:"Execution status of the transaction (1: success, 0: fail, -1: pending)."` + Error string `json:"error,omitempty" ts_doc:"Error encountered during execution, if any."` + Nonce uint64 `json:"nonce" ts_doc:"Transaction nonce (sequential number from the sender)."` + GasLimit *big.Int `json:"gasLimit" ts_doc:"Maximum gas allowed by the sender for this transaction."` + GasUsed *big.Int `json:"gasUsed,omitempty" ts_doc:"Actual gas consumed by the transaction execution."` + GasPrice *Amount `json:"gasPrice,omitempty" ts_doc:"Price (in Wei or base units) per gas unit."` MaxPriorityFeePerGas *Amount `json:"maxPriorityFeePerGas,omitempty"` MaxFeePerGas *Amount `json:"maxFeePerGas,omitempty"` BaseFeePerGas *Amount `json:"baseFeePerGas,omitempty"` - L1Fee *big.Int `json:"l1Fee,omitempty"` - L1FeeScalar string `json:"l1FeeScalar,omitempty"` - L1GasPrice *Amount `json:"l1GasPrice,omitempty"` - L1GasUsed *big.Int `json:"l1GasUsed,omitempty"` - Data string `json:"data,omitempty"` - ParsedData *bchain.EthereumParsedInputData `json:"parsedData,omitempty"` - InternalTransfers []EthereumInternalTransfer `json:"internalTransfers,omitempty"` + L1Fee *big.Int `json:"l1Fee,omitempty" ts_doc:"Fee used for L1 part in rollups (e.g. Optimism)."` + L1FeeScalar string `json:"l1FeeScalar,omitempty" ts_doc:"Scaling factor for L1 fees in certain Layer 2 solutions."` + L1GasPrice *Amount `json:"l1GasPrice,omitempty" ts_doc:"Gas price for L1 component, if applicable."` + L1GasUsed *big.Int `json:"l1GasUsed,omitempty" ts_doc:"Amount of gas used in L1 for this tx, if applicable."` + Data string `json:"data,omitempty" ts_doc:"Hex-encoded input data for the transaction."` + ParsedData *bchain.EthereumParsedInputData `json:"parsedData,omitempty" ts_doc:"Decoded transaction data (function name, params, etc.)."` + InternalTransfers []EthereumInternalTransfer `json:"internalTransfers,omitempty" ts_doc:"List of internal (sub-call) transfers."` } +// AddressAlias holds a specialized alias for an address type AddressAlias struct { - Type string - Alias string + Type string `ts_doc:"Type of alias, e.g., user-defined name or contract name."` + Alias string `ts_doc:"Alias string for the address."` } + +// AddressAliasesMap is a map of address strings to their alias definitions type AddressAliasesMap map[string]AddressAlias // Tx holds information about a transaction type Tx struct { - Txid string `json:"txid"` - Version int32 `json:"version,omitempty"` - Locktime uint32 `json:"lockTime,omitempty"` - Vin []Vin `json:"vin"` - Vout []Vout `json:"vout"` - Blockhash string `json:"blockHash,omitempty"` - Blockheight int `json:"blockHeight"` - Confirmations uint32 `json:"confirmations"` - ConfirmationETABlocks uint32 `json:"confirmationETABlocks,omitempty"` - ConfirmationETASeconds int64 `json:"confirmationETASeconds,omitempty"` - Blocktime int64 `json:"blockTime"` - Size int `json:"size,omitempty"` - VSize int `json:"vsize,omitempty"` - ValueOutSat *Amount `json:"value"` - ValueInSat *Amount `json:"valueIn,omitempty"` - FeesSat *Amount `json:"fees,omitempty"` - Hex string `json:"hex,omitempty"` - Rbf bool `json:"rbf,omitempty"` - CoinSpecificData json.RawMessage `json:"coinSpecificData,omitempty" ts_type:"any"` - TokenTransfers []TokenTransfer `json:"tokenTransfers,omitempty"` - EthereumSpecific *EthereumSpecific `json:"ethereumSpecific,omitempty"` - AddressAliases AddressAliasesMap `json:"addressAliases,omitempty"` + Txid string `json:"txid" ts_doc:"Transaction ID (hash)."` + Version int32 `json:"version,omitempty" ts_doc:"Version of the transaction (if applicable)."` + Locktime uint32 `json:"lockTime,omitempty" ts_doc:"Locktime indicating earliest time/height transaction can be mined."` + Vin []Vin `json:"vin" ts_doc:"Array of inputs for this transaction."` + Vout []Vout `json:"vout" ts_doc:"Array of outputs for this transaction."` + Blockhash string `json:"blockHash,omitempty" ts_doc:"Hash of the block containing this transaction."` + Blockheight int `json:"blockHeight" ts_doc:"Block height in which this transaction was included."` + Confirmations uint32 `json:"confirmations" ts_doc:"Number of confirmations (blocks mined after this tx's block)."` + ConfirmationETABlocks uint32 `json:"confirmationETABlocks,omitempty" ts_doc:"Estimated blocks remaining until confirmation (if unconfirmed)."` + ConfirmationETASeconds int64 `json:"confirmationETASeconds,omitempty" ts_doc:"Estimated seconds remaining until confirmation (if unconfirmed)."` + Blocktime int64 `json:"blockTime" ts_doc:"Unix timestamp of the block in which this transaction was included. 0 if unconfirmed."` + Size int `json:"size,omitempty" ts_doc:"Transaction size in bytes."` + VSize int `json:"vsize,omitempty" ts_doc:"Virtual size in bytes, for SegWit-enabled chains."` + ValueOutSat *Amount `json:"value" ts_doc:"Total value of all outputs (in satoshi or base units)."` + ValueInSat *Amount `json:"valueIn,omitempty" ts_doc:"Total value of all inputs (in satoshi or base units)."` + FeesSat *Amount `json:"fees,omitempty" ts_doc:"Transaction fee (inputs - outputs)."` + Hex string `json:"hex,omitempty" ts_doc:"Raw hex-encoded transaction data."` + Rbf bool `json:"rbf,omitempty" ts_doc:"Indicates if this transaction is replace-by-fee (RBF) enabled."` + CoinSpecificData json.RawMessage `json:"coinSpecificData,omitempty" ts_type:"any" ts_doc:"Blockchain-specific extended data."` + TokenTransfers []TokenTransfer `json:"tokenTransfers,omitempty" ts_doc:"List of token transfers that occurred in this transaction."` + EthereumSpecific *EthereumSpecific `json:"ethereumSpecific,omitempty" ts_doc:"Ethereum-like blockchain specific data (if applicable)."` + AddressAliases AddressAliasesMap `json:"addressAliases,omitempty" ts_doc:"Aliases for addresses involved in this transaction."` } // FeeStats contains detailed block fee statistics type FeeStats struct { - TxCount int `json:"txCount"` - TotalFeesSat *Amount `json:"totalFeesSat"` - AverageFeePerKb int64 `json:"averageFeePerKb"` - DecilesFeePerKb [11]int64 `json:"decilesFeePerKb"` + TxCount int `json:"txCount" ts_doc:"Number of transactions in the given block."` + TotalFeesSat *Amount `json:"totalFeesSat" ts_doc:"Sum of all fees in satoshi or base units."` + AverageFeePerKb int64 `json:"averageFeePerKb" ts_doc:"Average fee per kilobyte in satoshi or base units."` + DecilesFeePerKb [11]int64 `json:"decilesFeePerKb" ts_doc:"Fee distribution deciles (0%..100%) in satoshi or base units per kB."` } // Paging contains information about paging for address, blocks and block type Paging struct { - Page int `json:"page,omitempty"` - TotalPages int `json:"totalPages,omitempty"` - ItemsOnPage int `json:"itemsOnPage,omitempty"` + Page int `json:"page,omitempty" ts_doc:"Current page index."` + TotalPages int `json:"totalPages,omitempty" ts_doc:"Total number of pages available."` + ItemsOnPage int `json:"itemsOnPage,omitempty" ts_doc:"Number of items returned on this page."` } // TokensToReturn specifies what tokens are returned by GetAddress and GetXpubAddress @@ -335,74 +339,74 @@ const ( // AddressFilter is used to filter data returned from GetAddress api method type AddressFilter struct { - Vout int - Contract string - FromHeight uint32 - ToHeight uint32 - TokensToReturn TokensToReturn + Vout int `ts_doc:"Specifies which output index we are interested in filtering (or use the special constants)."` + Contract string `ts_doc:"Contract address to filter by, if applicable."` + FromHeight uint32 `ts_doc:"Starting block height for filtering transactions."` + ToHeight uint32 `ts_doc:"Ending block height for filtering transactions."` + TokensToReturn TokensToReturn `ts_doc:"Which tokens to include in the result set."` // OnlyConfirmed set to true will ignore mempool transactions; mempool is also ignored if FromHeight/ToHeight filter is specified - OnlyConfirmed bool + OnlyConfirmed bool `ts_doc:"If true, ignores mempool (unconfirmed) transactions."` } // StakingPool holds data about address participation in a staking pool contract type StakingPool struct { - Contract string `json:"contract"` - Name string `json:"name"` - PendingBalance *Amount `json:"pendingBalance"` - PendingDepositedBalance *Amount `json:"pendingDepositedBalance"` - DepositedBalance *Amount `json:"depositedBalance"` - WithdrawTotalAmount *Amount `json:"withdrawTotalAmount"` - ClaimableAmount *Amount `json:"claimableAmount"` - RestakedReward *Amount `json:"restakedReward"` - AutocompoundBalance *Amount `json:"autocompoundBalance"` + Contract string `json:"contract" ts_doc:"Staking pool contract address on-chain."` + Name string `json:"name" ts_doc:"Name of the staking pool contract."` + PendingBalance *Amount `json:"pendingBalance" ts_doc:"Balance pending deposit or withdrawal, if any."` + PendingDepositedBalance *Amount `json:"pendingDepositedBalance" ts_doc:"Any pending deposit that is not yet finalized."` + DepositedBalance *Amount `json:"depositedBalance" ts_doc:"Currently deposited/staked balance."` + WithdrawTotalAmount *Amount `json:"withdrawTotalAmount" ts_doc:"Total amount withdrawn from this pool by the address."` + ClaimableAmount *Amount `json:"claimableAmount" ts_doc:"Rewards or principal currently claimable by the address."` + RestakedReward *Amount `json:"restakedReward" ts_doc:"Total rewards that have been restaked automatically."` + AutocompoundBalance *Amount `json:"autocompoundBalance" ts_doc:"Any balance automatically reinvested into the pool."` } -// Address holds information about address and its transactions +// Address holds information about an address and its transactions type Address struct { Paging - AddrStr string `json:"address"` - BalanceSat *Amount `json:"balance"` - TotalReceivedSat *Amount `json:"totalReceived,omitempty"` - TotalSentSat *Amount `json:"totalSent,omitempty"` - UnconfirmedBalanceSat *Amount `json:"unconfirmedBalance"` - UnconfirmedTxs int `json:"unconfirmedTxs"` - UnconfirmedSending *Amount `json:"unconfirmedSending,omitempty"` - UnconfirmedReceiving *Amount `json:"unconfirmedReceiving,omitempty"` - Txs int `json:"txs"` - AddrTxCount int `json:"addrTxCount,omitempty"` - NonTokenTxs int `json:"nonTokenTxs,omitempty"` - InternalTxs int `json:"internalTxs,omitempty"` - Transactions []*Tx `json:"transactions,omitempty"` - Txids []string `json:"txids,omitempty"` - Nonce string `json:"nonce,omitempty"` - UsedTokens int `json:"usedTokens,omitempty"` - Tokens Tokens `json:"tokens,omitempty"` - SecondaryValue float64 `json:"secondaryValue,omitempty"` // address value in secondary currency - TokensBaseValue float64 `json:"tokensBaseValue,omitempty"` - TokensSecondaryValue float64 `json:"tokensSecondaryValue,omitempty"` - TotalBaseValue float64 `json:"totalBaseValue,omitempty"` // value including tokens in base currency - TotalSecondaryValue float64 `json:"totalSecondaryValue,omitempty"` // value including tokens in secondary currency - ContractInfo *bchain.ContractInfo `json:"contractInfo,omitempty"` + AddrStr string `json:"address" ts_doc:"The address string in standard format."` + BalanceSat *Amount `json:"balance" ts_doc:"Current confirmed balance (in satoshi or base units)."` + TotalReceivedSat *Amount `json:"totalReceived,omitempty" ts_doc:"Total amount ever received by this address."` + TotalSentSat *Amount `json:"totalSent,omitempty" ts_doc:"Total amount ever sent by this address."` + UnconfirmedBalanceSat *Amount `json:"unconfirmedBalance" ts_doc:"Unconfirmed balance for this address."` + UnconfirmedTxs int `json:"unconfirmedTxs" ts_doc:"Number of unconfirmed transactions for this address."` + UnconfirmedSending *Amount `json:"unconfirmedSending,omitempty" ts_doc:"Unconfirmed outgoing balance for this address."` + UnconfirmedReceiving *Amount `json:"unconfirmedReceiving,omitempty" ts_doc:"Unconfirmed incoming balance for this address."` + Txs int `json:"txs" ts_doc:"Number of transactions for this address (including confirmed)."` + AddrTxCount int `json:"addrTxCount,omitempty" ts_doc:"Historical total count of transactions, if known."` + NonTokenTxs int `json:"nonTokenTxs,omitempty" ts_doc:"Number of transactions not involving tokens (pure coin transfers)."` + InternalTxs int `json:"internalTxs,omitempty" ts_doc:"Number of internal transactions (e.g., Ethereum calls)."` + Transactions []*Tx `json:"transactions,omitempty" ts_doc:"List of transaction details (if requested)."` + Txids []string `json:"txids,omitempty" ts_doc:"List of transaction IDs (if detailed data is not requested)."` + Nonce string `json:"nonce,omitempty" ts_doc:"Current transaction nonce for Ethereum-like addresses."` + UsedTokens int `json:"usedTokens,omitempty" ts_doc:"Number of tokens with any historical usage at this address."` + Tokens Tokens `json:"tokens,omitempty" ts_doc:"List of tokens associated with this address."` + SecondaryValue float64 `json:"secondaryValue,omitempty" ts_doc:"Total value of the address in secondary currency (e.g. fiat)."` + TokensBaseValue float64 `json:"tokensBaseValue,omitempty" ts_doc:"Sum of token values in base currency."` + TokensSecondaryValue float64 `json:"tokensSecondaryValue,omitempty" ts_doc:"Sum of token values in secondary currency (fiat)."` + TotalBaseValue float64 `json:"totalBaseValue,omitempty" ts_doc:"Address's entire value in base currency, including tokens."` + TotalSecondaryValue float64 `json:"totalSecondaryValue,omitempty" ts_doc:"Address's entire value in secondary currency, including tokens."` + ContractInfo *bchain.ContractInfo `json:"contractInfo,omitempty" ts_doc:"Extra info if the address is a contract (ABI, type)."` // Deprecated: replaced by ContractInfo Erc20Contract *bchain.ContractInfo `json:"erc20Contract,omitempty" ts_doc:"@deprecated: replaced by contractInfo"` - AddressAliases AddressAliasesMap `json:"addressAliases,omitempty"` - StakingPools []StakingPool `json:"stakingPools,omitempty"` + AddressAliases AddressAliasesMap `json:"addressAliases,omitempty" ts_doc:"Aliases assigned to this address."` + StakingPools []StakingPool `json:"stakingPools,omitempty" ts_doc:"List of staking pool data if address interacts with staking."` // helpers for explorer - Filter string `json:"-"` - XPubAddresses map[string]struct{} `json:"-"` + Filter string `json:"-" ts_doc:"Filter used internally for data retrieval."` + XPubAddresses map[string]struct{} `json:"-" ts_doc:"Set of derived XPUB addresses (internal usage)."` } // Utxo is one unspent transaction output type Utxo struct { - Txid string `json:"txid"` - Vout int32 `json:"vout"` - AmountSat *Amount `json:"value"` - Height int `json:"height,omitempty"` - Confirmations int `json:"confirmations"` - Address string `json:"address,omitempty"` - Path string `json:"path,omitempty"` - Locktime uint32 `json:"lockTime,omitempty"` - Coinbase bool `json:"coinbase,omitempty"` + Txid string `json:"txid" ts_doc:"Transaction ID in which this UTXO was created."` + Vout int32 `json:"vout" ts_doc:"Index of the output in that transaction."` + AmountSat *Amount `json:"value" ts_doc:"Value of this UTXO (in satoshi or base units)."` + Height int `json:"height,omitempty" ts_doc:"Block height in which the UTXO was confirmed."` + Confirmations int `json:"confirmations" ts_doc:"Number of confirmations for this UTXO."` + Address string `json:"address,omitempty" ts_doc:"Address to which this UTXO belongs."` + Path string `json:"path,omitempty" ts_doc:"Derivation path for XPUB-based wallets, if applicable."` + Locktime uint32 `json:"lockTime,omitempty" ts_doc:"If non-zero, locktime required before spending this UTXO."` + Coinbase bool `json:"coinbase,omitempty" ts_doc:"Indicates if this UTXO originated from a coinbase transaction."` } // Utxos is array of Utxo @@ -425,13 +429,13 @@ func (a Utxos) Less(i, j int) bool { // BalanceHistory contains info about one point in time of balance history type BalanceHistory struct { - Time uint32 `json:"time"` - Txs uint32 `json:"txs"` - ReceivedSat *Amount `json:"received"` - SentSat *Amount `json:"sent"` - SentToSelfSat *Amount `json:"sentToSelf"` - FiatRates map[string]float32 `json:"rates,omitempty"` - Txid string `json:"txid,omitempty"` + Time uint32 `json:"time" ts_doc:"Unix timestamp for this point in the balance history."` + Txs uint32 `json:"txs" ts_doc:"Number of transactions in this interval."` + ReceivedSat *Amount `json:"received" ts_doc:"Amount received in this interval (in satoshi or base units)."` + SentSat *Amount `json:"sent" ts_doc:"Amount sent in this interval (in satoshi or base units)."` + SentToSelfSat *Amount `json:"sentToSelf" ts_doc:"Amount sent to the same address (self-transfer)."` + FiatRates map[string]float32 `json:"rates,omitempty" ts_doc:"Exchange rates at this point in time, if available."` + Txid string `json:"txid,omitempty" ts_doc:"Transaction ID if the time corresponds to a specific tx."` } // BalanceHistories is array of BalanceHistory @@ -493,105 +497,105 @@ func (a BalanceHistories) SortAndAggregate(groupByTime uint32) BalanceHistories // Blocks is list of blocks with paging information type Blocks struct { Paging - Blocks []db.BlockInfo `json:"blocks"` + Blocks []db.BlockInfo `json:"blocks" ts_doc:"List of blocks."` } // BlockInfo contains extended block header data and a list of block txids type BlockInfo struct { - Hash string `json:"hash"` - Prev string `json:"previousBlockHash,omitempty"` - Next string `json:"nextBlockHash,omitempty"` - Height uint32 `json:"height"` - Confirmations int `json:"confirmations"` - Size int `json:"size"` - Time int64 `json:"time,omitempty"` - Version common.JSONNumber `json:"version"` - MerkleRoot string `json:"merkleRoot"` - Nonce string `json:"nonce"` - Bits string `json:"bits"` - Difficulty string `json:"difficulty"` - Txids []string `json:"tx,omitempty"` + Hash string `json:"hash" ts_doc:"Block hash."` + Prev string `json:"previousBlockHash,omitempty" ts_doc:"Hash of the previous block in the chain."` + Next string `json:"nextBlockHash,omitempty" ts_doc:"Hash of the next block, if known."` + Height uint32 `json:"height" ts_doc:"Block height (0-based index in the chain)."` + Confirmations int `json:"confirmations" ts_doc:"Number of confirmations of this block (distance from best chain tip)."` + Size int `json:"size" ts_doc:"Size of the block in bytes."` + Time int64 `json:"time,omitempty" ts_doc:"Timestamp of when this block was mined."` + Version common.JSONNumber `json:"version" ts_doc:"Block version (chain-specific meaning)."` + MerkleRoot string `json:"merkleRoot" ts_doc:"Merkle root of the block's transactions."` + Nonce string `json:"nonce" ts_doc:"Nonce used in the mining process."` + Bits string `json:"bits" ts_doc:"Compact representation of the target threshold."` + Difficulty string `json:"difficulty" ts_doc:"Difficulty target for mining this block."` + Txids []string `json:"tx,omitempty" ts_doc:"List of transaction IDs included in this block."` } // Block contains information about block type Block struct { Paging BlockInfo - TxCount int `json:"txCount"` - Transactions []*Tx `json:"txs,omitempty"` - AddressAliases AddressAliasesMap `json:"addressAliases,omitempty"` + TxCount int `json:"txCount" ts_doc:"Total count of transactions in this block."` + Transactions []*Tx `json:"txs,omitempty" ts_doc:"List of full transaction details (if requested)."` + AddressAliases AddressAliasesMap `json:"addressAliases,omitempty" ts_doc:"Optional aliases for addresses found in this block."` } // BlockRaw contains raw block in hex type BlockRaw struct { - Hex string `json:"hex"` + Hex string `json:"hex" ts_doc:"Hex-encoded block data."` } // BlockbookInfo contains information about the running blockbook instance type BlockbookInfo struct { - Coin string `json:"coin"` - Network string `json:"network"` - Host string `json:"host"` - Version string `json:"version"` - GitCommit string `json:"gitCommit"` - BuildTime string `json:"buildTime"` - SyncMode bool `json:"syncMode"` - InitialSync bool `json:"initialSync"` - InSync bool `json:"inSync"` - BestHeight uint32 `json:"bestHeight"` - LastBlockTime time.Time `json:"lastBlockTime"` - InSyncMempool bool `json:"inSyncMempool"` - LastMempoolTime time.Time `json:"lastMempoolTime"` - MempoolSize int `json:"mempoolSize"` - Decimals int `json:"decimals"` - DbSize int64 `json:"dbSize"` - HasFiatRates bool `json:"hasFiatRates,omitempty"` - HasTokenFiatRates bool `json:"hasTokenFiatRates,omitempty"` - CurrentFiatRatesTime *time.Time `json:"currentFiatRatesTime,omitempty"` - HistoricalFiatRatesTime *time.Time `json:"historicalFiatRatesTime,omitempty"` - HistoricalTokenFiatRatesTime *time.Time `json:"historicalTokenFiatRatesTime,omitempty"` - SupportedStakingPools []string `json:"supportedStakingPools,omitempty"` - DbSizeFromColumns int64 `json:"dbSizeFromColumns,omitempty"` - DbColumns []common.InternalStateColumn `json:"dbColumns,omitempty"` - About string `json:"about"` + Coin string `json:"coin" ts_doc:"Coin name, e.g. 'Bitcoin'."` + Network string `json:"network" ts_doc:"Network shortcut, e.g. 'BTC'."` + Host string `json:"host" ts_doc:"Hostname of the blockbook instance, e.g. 'backend5'."` + Version string `json:"version" ts_doc:"Running blockbook version, e.g. '0.4.0'."` + GitCommit string `json:"gitCommit" ts_doc:"Git commit hash of the running blockbook, e.g. 'a0960c8e'."` + BuildTime string `json:"buildTime" ts_doc:"Build time of running blockbook, e.g. '2024-08-08T12:32:50+00:00'."` + SyncMode bool `json:"syncMode" ts_doc:"If true, blockbook is syncing from scratch or in a special sync mode."` + InitialSync bool `json:"initialSync" ts_doc:"Indicates if blockbook is in its initial sync phase."` + InSync bool `json:"inSync" ts_doc:"Indicates if the backend is fully synced with the blockchain."` + BestHeight uint32 `json:"bestHeight" ts_doc:"Best (latest) block height according to this instance."` + LastBlockTime time.Time `json:"lastBlockTime" ts_doc:"Timestamp of the latest block in the chain."` + InSyncMempool bool `json:"inSyncMempool" ts_doc:"Indicates if mempool info is synced as well."` + LastMempoolTime time.Time `json:"lastMempoolTime" ts_doc:"Timestamp of the last mempool update."` + MempoolSize int `json:"mempoolSize" ts_doc:"Number of unconfirmed transactions in the mempool."` + Decimals int `json:"decimals" ts_doc:"Number of decimals for this coin's base unit."` + DbSize int64 `json:"dbSize" ts_doc:"Size of the underlying database in bytes."` + HasFiatRates bool `json:"hasFiatRates,omitempty" ts_doc:"Whether this instance provides fiat exchange rates."` + HasTokenFiatRates bool `json:"hasTokenFiatRates,omitempty" ts_doc:"Whether this instance provides fiat exchange rates for tokens."` + CurrentFiatRatesTime *time.Time `json:"currentFiatRatesTime,omitempty" ts_doc:"Timestamp of the latest fiat rates update."` + HistoricalFiatRatesTime *time.Time `json:"historicalFiatRatesTime,omitempty" ts_doc:"Timestamp of the latest historical fiat rates update."` + HistoricalTokenFiatRatesTime *time.Time `json:"historicalTokenFiatRatesTime,omitempty" ts_doc:"Timestamp of the latest historical token fiat rates update."` + SupportedStakingPools []string `json:"supportedStakingPools,omitempty" ts_doc:"List of contract addresses supported for staking."` + DbSizeFromColumns int64 `json:"dbSizeFromColumns,omitempty" ts_doc:"Optional calculated DB size from columns."` + DbColumns []common.InternalStateColumn `json:"dbColumns,omitempty" ts_doc:"List of columns/tables in the DB for internal state."` + About string `json:"about" ts_doc:"Additional human-readable info about this blockbook instance."` } // SystemInfo contains information about the running blockbook and backend instance type SystemInfo struct { - Blockbook *BlockbookInfo `json:"blockbook"` - Backend *common.BackendInfo `json:"backend"` + Blockbook *BlockbookInfo `json:"blockbook" ts_doc:"Blockbook instance information."` + Backend *common.BackendInfo `json:"backend" ts_doc:"Information about the connected backend node."` } // MempoolTxid contains information about a transaction in mempool type MempoolTxid struct { - Time int64 `json:"time"` - Txid string `json:"txid"` + Time int64 `json:"time" ts_doc:"Timestamp when the transaction was received in the mempool."` + Txid string `json:"txid" ts_doc:"Transaction hash for this mempool entry."` } // MempoolTxids contains a list of mempool txids with paging information type MempoolTxids struct { Paging - Mempool []MempoolTxid `json:"mempool"` - MempoolSize int `json:"mempoolSize"` + Mempool []MempoolTxid `json:"mempool" ts_doc:"List of transactions currently in the mempool."` + MempoolSize int `json:"mempoolSize" ts_doc:"Number of unconfirmed transactions in the mempool."` } // FiatTicker contains formatted CurrencyRatesTicker data type FiatTicker struct { - Timestamp int64 `json:"ts,omitempty"` - Rates map[string]float32 `json:"rates"` - Error string `json:"error,omitempty"` + Timestamp int64 `json:"ts,omitempty" ts_doc:"Unix timestamp for these fiat rates."` + Rates map[string]float32 `json:"rates" ts_doc:"Map of currency codes to their exchange rate."` + Error string `json:"error,omitempty" ts_doc:"Any error message encountered while fetching rates."` } // FiatTickers contains a formatted CurrencyRatesTicker list type FiatTickers struct { - Tickers []FiatTicker `json:"tickers"` + Tickers []FiatTicker `json:"tickers" ts_doc:"List of fiat tickers with timestamps and rates."` } // AvailableVsCurrencies contains formatted data about available versus currencies for exchange rates type AvailableVsCurrencies struct { - Timestamp int64 `json:"ts,omitempty"` - Tickers []string `json:"available_currencies"` - Error string `json:"error,omitempty"` + Timestamp int64 `json:"ts,omitempty" ts_doc:"Timestamp for the available currency list."` + Tickers []string `json:"available_currencies" ts_doc:"List of currency codes (e.g., USD, EUR) supported by the rates."` + Error string `json:"error,omitempty" ts_doc:"Error message, if any, when fetching the available currencies."` } // Eip1559Fee diff --git a/bchain/types.go b/bchain/types.go index 04c87e73..40e54d6e 100644 --- a/bchain/types.go +++ b/bchain/types.go @@ -39,81 +39,81 @@ var ( // Outpoint is txid together with output (or input) index type Outpoint struct { - Txid string - Vout int32 + Txid string `ts_doc:"Transaction ID of the referenced outpoint."` + Vout int32 `ts_doc:"Index of the specific output in the transaction."` } // ScriptSig contains data about input script type ScriptSig struct { // Asm string `json:"asm"` - Hex string `json:"hex"` + Hex string `json:"hex" ts_doc:"Hex-encoded representation of the scriptSig."` } // Vin contains data about tx input type Vin struct { - Coinbase string `json:"coinbase"` - Txid string `json:"txid"` - Vout uint32 `json:"vout"` - ScriptSig ScriptSig `json:"scriptSig"` - Sequence uint32 `json:"sequence"` - Addresses []string `json:"addresses"` - Witness [][]byte `json:"-"` + Coinbase string `json:"coinbase" ts_doc:"Coinbase data if this is a coinbase input."` + Txid string `json:"txid" ts_doc:"Transaction ID of the input being spent."` + Vout uint32 `json:"vout" ts_doc:"Output index in the referenced transaction."` + ScriptSig ScriptSig `json:"scriptSig" ts_doc:"scriptSig object containing the spending script data."` + Sequence uint32 `json:"sequence" ts_doc:"Sequence number for the input."` + Addresses []string `json:"addresses" ts_doc:"Addresses derived from this input's script (if known)."` + Witness [][]byte `json:"-" ts_doc:"Witness data for SegWit inputs (not exposed via JSON)."` } // ScriptPubKey contains data about output script type ScriptPubKey struct { // Asm string `json:"asm"` - Hex string `json:"hex,omitempty"` + Hex string `json:"hex,omitempty" ts_doc:"Hex-encoded representation of the scriptPubKey."` // Type string `json:"type"` - Addresses []string `json:"addresses"` + Addresses []string `json:"addresses" ts_doc:"Addresses derived from this output's script (if known)."` } // Vout contains data about tx output type Vout struct { - ValueSat big.Int - JsonValue common.JSONNumber `json:"value"` - N uint32 `json:"n"` - ScriptPubKey ScriptPubKey `json:"scriptPubKey"` + ValueSat big.Int `ts_doc:"Amount (in satoshi or base unit) for this output."` + JsonValue common.JSONNumber `json:"value" ts_doc:"String-based amount for JSON usage."` + N uint32 `json:"n" ts_doc:"Index of this output in the transaction."` + ScriptPubKey ScriptPubKey `json:"scriptPubKey" ts_doc:"scriptPubKey object containing the output script data."` } // Tx is blockchain transaction // unnecessary fields are commented out to avoid overhead type Tx struct { - Hex string `json:"hex"` - Txid string `json:"txid"` - Version int32 `json:"version"` - LockTime uint32 `json:"locktime"` - VSize int64 `json:"vsize,omitempty"` - Vin []Vin `json:"vin"` - Vout []Vout `json:"vout"` - BlockHeight uint32 `json:"blockHeight,omitempty"` + Hex string `json:"hex" ts_doc:"Hex-encoded transaction data."` + Txid string `json:"txid" ts_doc:"Transaction ID (hash)."` + Version int32 `json:"version" ts_doc:"Transaction version number."` + LockTime uint32 `json:"locktime" ts_doc:"Locktime specifying earliest time/block a tx can be mined."` + VSize int64 `json:"vsize,omitempty" ts_doc:"Virtual size of the transaction (for SegWit-based networks)."` + Vin []Vin `json:"vin" ts_doc:"List of inputs."` + Vout []Vout `json:"vout" ts_doc:"List of outputs."` + BlockHeight uint32 `json:"blockHeight,omitempty" ts_doc:"Block height in which this transaction was included."` // BlockHash string `json:"blockhash,omitempty"` - Confirmations uint32 `json:"confirmations,omitempty"` - Time int64 `json:"time,omitempty"` - Blocktime int64 `json:"blocktime,omitempty"` - CoinSpecificData interface{} `json:"-"` + Confirmations uint32 `json:"confirmations,omitempty" ts_doc:"Number of confirmations the transaction has."` + Time int64 `json:"time,omitempty" ts_doc:"Timestamp when the transaction was broadcast or included in a block."` + Blocktime int64 `json:"blocktime,omitempty" ts_doc:"Timestamp of the block in which the transaction was mined."` + CoinSpecificData interface{} `json:"-" ts_doc:"Additional chain-specific data (not exposed via JSON)."` } -// MempoolVin contains data about tx input +// MempoolVin contains data about tx input specifically in mempool type MempoolVin struct { Vin - AddrDesc AddressDescriptor `json:"-"` - ValueSat big.Int + AddrDesc AddressDescriptor `json:"-" ts_doc:"Internal descriptor for the input address (not exposed)."` + ValueSat big.Int `ts_doc:"Amount (in satoshi or base unit) of the input."` } // MempoolTx is blockchain transaction in mempool // optimized for onNewTx notification type MempoolTx struct { - Hex string `json:"hex"` - Txid string `json:"txid"` - Version int32 `json:"version"` - LockTime uint32 `json:"locktime"` - VSize int64 `json:"vsize,omitempty"` - Vin []MempoolVin `json:"vin"` - Vout []Vout `json:"vout"` - Blocktime int64 `json:"blocktime,omitempty"` - TokenTransfers TokenTransfers `json:"-"` - CoinSpecificData interface{} `json:"-"` + Hex string `json:"hex" ts_doc:"Hex-encoded transaction data."` + Txid string `json:"txid" ts_doc:"Transaction ID (hash)."` + Version int32 `json:"version" ts_doc:"Transaction version number."` + LockTime uint32 `json:"locktime" ts_doc:"Locktime specifying earliest time/block a tx can be mined."` + VSize int64 `json:"vsize,omitempty" ts_doc:"Virtual size of the transaction (if applicable)."` + Vin []MempoolVin `json:"vin" ts_doc:"List of inputs in this mempool transaction."` + Vout []Vout `json:"vout" ts_doc:"List of outputs in this mempool transaction."` + Blocktime int64 `json:"blocktime,omitempty" ts_doc:"Timestamp for the block in which tx might eventually be mined, if known."` + TokenTransfers TokenTransfers `json:"-" ts_doc:"Token transfers discovered in this mempool transaction (not exposed by default)."` + CoinSpecificData interface{} `json:"-" ts_doc:"Additional chain-specific data (not exposed via JSON)."` } // TokenStandard - standard of token @@ -150,71 +150,71 @@ func (a TokenTransfers) Less(i, j int) bool { // Block is block header and list of transactions type Block struct { BlockHeader - Txs []Tx `json:"tx"` - CoinSpecificData interface{} `json:"-"` + Txs []Tx `json:"tx" ts_doc:"List of full transactions included in this block."` + CoinSpecificData interface{} `json:"-" ts_doc:"Additional chain-specific data (not exposed via JSON)."` } // BlockHeader contains limited data (as needed for indexing) from backend block header type BlockHeader struct { - Hash string `json:"hash"` - Prev string `json:"previousblockhash"` - Next string `json:"nextblockhash"` - Height uint32 `json:"height"` - Confirmations int `json:"confirmations"` - Size int `json:"size"` - Time int64 `json:"time,omitempty"` + Hash string `json:"hash" ts_doc:"Block hash."` + Prev string `json:"previousblockhash" ts_doc:"Hash of the previous block in the chain."` + Next string `json:"nextblockhash" ts_doc:"Hash of the next block, if known."` + Height uint32 `json:"height" ts_doc:"Block height (0-based index in the chain)."` + Confirmations int `json:"confirmations" ts_doc:"Number of confirmations (distance from best chain tip)."` + Size int `json:"size" ts_doc:"Block size in bytes."` + Time int64 `json:"time,omitempty" ts_doc:"Timestamp of when this block was mined."` } // BlockInfo contains extended block header data and a list of block txids type BlockInfo struct { BlockHeader - Version common.JSONNumber `json:"version"` - MerkleRoot string `json:"merkleroot"` - Nonce common.JSONNumber `json:"nonce"` - Bits string `json:"bits"` - Difficulty common.JSONNumber `json:"difficulty"` - Txids []string `json:"tx,omitempty"` + Version common.JSONNumber `json:"version" ts_doc:"Block version (chain-specific meaning)."` + MerkleRoot string `json:"merkleroot" ts_doc:"Merkle root of the block's transactions."` + Nonce common.JSONNumber `json:"nonce" ts_doc:"Nonce used in the mining process."` + Bits string `json:"bits" ts_doc:"Compact representation of the target threshold."` + Difficulty common.JSONNumber `json:"difficulty" ts_doc:"Difficulty target for mining this block."` + Txids []string `json:"tx,omitempty" ts_doc:"List of transaction IDs included in this block."` } // MempoolEntry is used to get data about mempool entry type MempoolEntry struct { - Size uint32 `json:"size"` - FeeSat big.Int - Fee common.JSONNumber `json:"fee"` - ModifiedFeeSat big.Int - ModifiedFee common.JSONNumber `json:"modifiedfee"` - Time uint64 `json:"time"` - Height uint32 `json:"height"` - DescendantCount uint32 `json:"descendantcount"` - DescendantSize uint32 `json:"descendantsize"` - DescendantFees uint32 `json:"descendantfees"` - AncestorCount uint32 `json:"ancestorcount"` - AncestorSize uint32 `json:"ancestorsize"` - AncestorFees uint32 `json:"ancestorfees"` - Depends []string `json:"depends"` + Size uint32 `json:"size" ts_doc:"Size of the transaction in bytes, as stored in mempool."` + FeeSat big.Int `ts_doc:"Transaction fee in satoshi/base units."` + Fee common.JSONNumber `json:"fee" ts_doc:"String-based fee for JSON usage."` + ModifiedFeeSat big.Int `ts_doc:"Modified fee in satoshi/base units after priority adjustments."` + ModifiedFee common.JSONNumber `json:"modifiedfee" ts_doc:"String-based modified fee for JSON usage."` + Time uint64 `json:"time" ts_doc:"Unix timestamp when the tx entered the mempool."` + Height uint32 `json:"height" ts_doc:"Block height when the tx entered the mempool."` + DescendantCount uint32 `json:"descendantcount" ts_doc:"Number of descendant transactions in mempool."` + DescendantSize uint32 `json:"descendantsize" ts_doc:"Total size of all descendant transactions in bytes."` + DescendantFees uint32 `json:"descendantfees" ts_doc:"Combined fees of all descendant transactions."` + AncestorCount uint32 `json:"ancestorcount" ts_doc:"Number of ancestor transactions in mempool."` + AncestorSize uint32 `json:"ancestorsize" ts_doc:"Total size of all ancestor transactions in bytes."` + AncestorFees uint32 `json:"ancestorfees" ts_doc:"Combined fees of all ancestor transactions."` + Depends []string `json:"depends" ts_doc:"List of txids this transaction depends on."` } // ChainInfo is used to get information about blockchain type ChainInfo struct { - Chain string `json:"chain"` - Blocks int `json:"blocks"` - Headers int `json:"headers"` - Bestblockhash string `json:"bestblockhash"` - Difficulty string `json:"difficulty"` - SizeOnDisk int64 `json:"size_on_disk"` - Version string `json:"version"` - Subversion string `json:"subversion"` - ProtocolVersion string `json:"protocolversion"` - Timeoffset float64 `json:"timeoffset"` - Warnings string `json:"warnings"` - ConsensusVersion string `json:"consensus_version,omitempty"` - Consensus interface{} `json:"consensus,omitempty"` + Chain string `json:"chain" ts_doc:"Name of the chain (e.g. 'main')."` + Blocks int `json:"blocks" ts_doc:"Number of fully verified blocks in the chain."` + Headers int `json:"headers" ts_doc:"Number of block headers in the chain (can be ahead of full blocks)."` + Bestblockhash string `json:"bestblockhash" ts_doc:"Hash of the best (latest) block."` + Difficulty string `json:"difficulty" ts_doc:"Current difficulty of the network."` + SizeOnDisk int64 `json:"size_on_disk" ts_doc:"Size of the blockchain data on disk in bytes."` + Version string `json:"version" ts_doc:"Version of the blockchain backend."` + Subversion string `json:"subversion" ts_doc:"Subversion string of the blockchain backend."` + ProtocolVersion string `json:"protocolversion" ts_doc:"Protocol version for this chain node."` + Timeoffset float64 `json:"timeoffset" ts_doc:"Time offset (in seconds) reported by the node."` + Warnings string `json:"warnings" ts_doc:"Any warnings generated by the node regarding the chain state."` + ConsensusVersion string `json:"consensus_version,omitempty" ts_doc:"Version of the chain's consensus protocol, if available."` + Consensus interface{} `json:"consensus,omitempty" ts_doc:"Additional consensus details, structure depends on chain."` } // RPCError defines rpc error returned by backend type RPCError struct { - Code int `json:"code"` - Message string `json:"message"` + Code int `json:"code" ts_doc:"Error code returned by the backend RPC."` + Message string `json:"message" ts_doc:"Human-readable error message."` } func (e *RPCError) Error() string { @@ -245,8 +245,8 @@ func AddressDescriptorFromString(s string) (AddressDescriptor, error) { // MempoolTxidEntry contains mempool txid with first seen time type MempoolTxidEntry struct { - Txid string - Time uint32 + Txid string `ts_doc:"Transaction ID (hash) of the mempool entry."` + Time uint32 `ts_doc:"Unix timestamp when the transaction was first seen in the mempool."` } // ScriptType - type of output script parsed from xpub (descriptor) @@ -263,12 +263,12 @@ const ( // XpubDescriptor contains parsed data from xpub descriptor type XpubDescriptor struct { - XpubDescriptor string // The whole descriptor - Xpub string // Xpub part of the descriptor - Type ScriptType - Bip string - ChangeIndexes []uint32 - ExtKey interface{} // extended key parsed from xpub, usually of type *hdkeychain.ExtendedKey + XpubDescriptor string `ts_doc:"Full descriptor string including xpub and script type."` + Xpub string `ts_doc:"The xpub part itself extracted from the descriptor."` + Type ScriptType `ts_doc:"Parsed script type (P2PKH, P2WPKH, etc.)."` + Bip string `ts_doc:"BIP standard (e.g. BIP44) inferred from the descriptor."` + ChangeIndexes []uint32 `ts_doc:"Indexes designated as change addresses."` + ExtKey interface{} `ts_doc:"Extended key object parsed from xpub (implementation-specific)."` } // MempoolTxidEntries is array of MempoolTxidEntry @@ -277,8 +277,8 @@ type MempoolTxidEntries []MempoolTxidEntry // MempoolTxidFilterEntries is a map of txids to mempool golomb filters // Also contains a flag whether constant zeroed key was used when calculating the filters type MempoolTxidFilterEntries struct { - Entries map[string]string `json:"entries,omitempty"` - UsedZeroedKey bool `json:"usedZeroedKey,omitempty"` + Entries map[string]string `json:"entries,omitempty" ts_doc:"Map of txid to filter data (hex-encoded)."` + UsedZeroedKey bool `json:"usedZeroedKey,omitempty" ts_doc:"Indicates if a zeroed key was used in filter calculation."` } // OnNewBlockFunc is used to send notification about a new block diff --git a/bchain/types_ethereum_type.go b/bchain/types_ethereum_type.go index f29602eb..b93632ec 100644 --- a/bchain/types_ethereum_type.go +++ b/bchain/types_ethereum_type.go @@ -8,35 +8,35 @@ import ( // EthereumInternalTransfer contains data about internal transfer type EthereumInternalTransfer struct { - Type EthereumInternalTransactionType `json:"type"` - From string `json:"from"` - To string `json:"to"` - Value big.Int `json:"value"` + Type EthereumInternalTransactionType `json:"type" ts_doc:"The type of internal transaction (CALL, CREATE, SELFDESTRUCT)."` + From string `json:"from" ts_doc:"Sender address of this internal transfer."` + To string `json:"to" ts_doc:"Recipient address of this internal transfer."` + Value big.Int `json:"value" ts_doc:"Amount (in Wei) transferred internally."` } -// FourByteSignature contains data about about a contract function signature +// FourByteSignature contains data about a contract function signature type FourByteSignature struct { // stored in DB - Name string - Parameters []string + Name string `ts_doc:"Original function name as stored in the database."` + Parameters []string `ts_doc:"Raw parameter type definitions (e.g. ['uint256','address'])."` // processed from DB data and stored only in cache - DecamelName string - Function string - ParsedParameters []abi.Type + DecamelName string `ts_doc:"A decamelized version of the function name for readability."` + Function string `ts_doc:"Reconstructed function definition string (e.g. 'transfer(address,uint256)')."` + ParsedParameters []abi.Type `ts_doc:"ABI-parsed parameter types (cached for efficiency)."` } // EthereumParsedInputParam contains data about a contract function parameter type EthereumParsedInputParam struct { - Type string `json:"type"` - Values []string `json:"values,omitempty"` + Type string `json:"type" ts_doc:"Parameter type (e.g. 'uint256')."` + Values []string `json:"values,omitempty" ts_doc:"List of stringified parameter values."` } // EthereumParsedInputData contains the parsed data for an input data hex payload type EthereumParsedInputData struct { - MethodId string `json:"methodId"` - Name string `json:"name"` - Function string `json:"function,omitempty"` - Params []EthereumParsedInputParam `json:"params,omitempty"` + MethodId string `json:"methodId" ts_doc:"First 4 bytes of the input data (method signature ID)."` + Name string `json:"name" ts_doc:"Parsed function name if recognized."` + Function string `json:"function,omitempty" ts_doc:"Full function signature (including parameter types)."` + Params []EthereumParsedInputParam `json:"params,omitempty" ts_doc:"List of parsed parameters for this function call."` } // EthereumInternalTransactionType - type of ethereum transaction from internal data @@ -49,12 +49,12 @@ const ( SELFDESTRUCT ) -// EthereumInternalTransaction contains internal transfers +// EthereumInternalData contains internal transfers type EthereumInternalData struct { - Type EthereumInternalTransactionType `json:"type"` - Contract string `json:"contract,omitempty"` - Transfers []EthereumInternalTransfer `json:"transfers,omitempty"` - Error string + Type EthereumInternalTransactionType `json:"type" ts_doc:"High-level type of the internal transaction (CALL, CREATE, etc.)."` + Contract string `json:"contract,omitempty" ts_doc:"Address of the contract involved, if any."` + Transfers []EthereumInternalTransfer `json:"transfers,omitempty" ts_doc:"List of internal transfers associated with this data."` + Error string `ts_doc:"Error message if something went wrong while processing."` } // ContractInfo contains info about a contract @@ -62,12 +62,12 @@ type ContractInfo struct { // Deprecated: Use Standard instead. Type TokenStandardName `json:"type" ts_type:"'' | 'XPUBAddress' | 'ERC20' | 'ERC721' | 'ERC1155' | 'BEP20' | 'BEP721' | 'BEP1155'" ts_doc:"@deprecated: Use standard instead."` Standard TokenStandardName `json:"standard" ts_type:"'' | 'XPUBAddress' | 'ERC20' | 'ERC721' | 'ERC1155' | 'BEP20' | 'BEP721' | 'BEP1155'"` - Contract string `json:"contract"` - Name string `json:"name"` - Symbol string `json:"symbol"` - Decimals int `json:"decimals"` - CreatedInBlock uint32 `json:"createdInBlock,omitempty"` - DestructedInBlock uint32 `json:"destructedInBlock,omitempty"` + Contract string `json:"contract" ts_doc:"Smart contract address."` + Name string `json:"name" ts_doc:"Readable name of the contract."` + Symbol string `json:"symbol" ts_doc:"Symbol for tokens under this contract, if applicable."` + Decimals int `json:"decimals" ts_doc:"Number of decimal places, if applicable."` + CreatedInBlock uint32 `json:"createdInBlock,omitempty" ts_doc:"Block height where contract was first created."` + DestructedInBlock uint32 `json:"destructedInBlock,omitempty" ts_doc:"Block height where contract was destroyed (if any)."` } // Ethereum token standard names @@ -81,37 +81,38 @@ const ( // the map must match all bchain.TokenStandard to avoid index out of range panic var EthereumTokenStandardMap = []TokenStandardName{ERC20TokenStandard, ERC771TokenStandard, ERC1155TokenStandard} +// MultiTokenValue holds one ID-value pair for multi-token standards like ERC1155 type MultiTokenValue struct { - Id big.Int - Value big.Int + Id big.Int `ts_doc:"Token ID for this multi-token entry."` + Value big.Int `ts_doc:"Amount of the token ID transferred or owned."` } // TokenTransfer contains a single token transfer type TokenTransfer struct { - Standard TokenStandard - Contract string - From string - To string - Value big.Int - MultiTokenValues []MultiTokenValue + Standard TokenStandard `ts_doc:"Integer value od the token standard."` + Contract string `ts_doc:"Smart contract address for the token."` + From string `ts_doc:"Sender address of the token transfer."` + To string `ts_doc:"Recipient address of the token transfer."` + Value big.Int `ts_doc:"Amount of tokens transferred (for fungible tokens)."` + MultiTokenValues []MultiTokenValue `ts_doc:"List of ID-value pairs for multi-token transfers (e.g., ERC1155)."` } // RpcTransaction is returned by eth_getTransactionByHash type RpcTransaction struct { - AccountNonce string `json:"nonce"` - GasPrice string `json:"gasPrice"` + AccountNonce string `json:"nonce" ts_doc:"Transaction nonce from the sender's account."` + GasPrice string `json:"gasPrice" ts_doc:"Gas price bid by the sender in Wei."` MaxPriorityFeePerGas string `json:"maxPriorityFeePerGas,omitempty"` MaxFeePerGas string `json:"maxFeePerGas,omitempty"` BaseFeePerGas string `json:"baseFeePerGas,omitempty"` - GasLimit string `json:"gas"` - To string `json:"to"` // nil means contract creation - Value string `json:"value"` - Payload string `json:"input"` - Hash string `json:"hash"` - BlockNumber string `json:"blockNumber"` - BlockHash string `json:"blockHash,omitempty"` - From string `json:"from"` - TransactionIndex string `json:"transactionIndex"` + GasLimit string `json:"gas" ts_doc:"Maximum gas allowed for this transaction."` + To string `json:"to" ts_doc:"Recipient address if not a contract creation. Empty if it's contract creation."` + Value string `json:"value" ts_doc:"Amount of Ether (in Wei) sent in this transaction."` + Payload string `json:"input" ts_doc:"Hex-encoded input data for contract calls."` + Hash string `json:"hash" ts_doc:"Transaction hash."` + BlockNumber string `json:"blockNumber" ts_doc:"Block number where this transaction was included, if mined."` + BlockHash string `json:"blockHash,omitempty" ts_doc:"Hash of the block in which this transaction was included, if mined."` + From string `json:"from" ts_doc:"Sender's address derived by the backend."` + TransactionIndex string `json:"transactionIndex" ts_doc:"Index of the transaction within the block, if mined."` // Signature values - ignored // V string `json:"v"` // R string `json:"r"` @@ -120,53 +121,53 @@ type RpcTransaction struct { // RpcLog is returned by eth_getLogs type RpcLog struct { - Address string `json:"address"` - Topics []string `json:"topics"` - Data string `json:"data"` + Address string `json:"address" ts_doc:"Contract or address from which this log originated."` + Topics []string `json:"topics" ts_doc:"Indexed event signatures and parameters."` + Data string `json:"data" ts_doc:"Unindexed event data in hex form."` } -// RpcLog is returned by eth_getTransactionReceipt +// RpcReceipt is returned by eth_getTransactionReceipt type RpcReceipt struct { - GasUsed string `json:"gasUsed"` - Status string `json:"status"` - Logs []*RpcLog `json:"logs"` - L1Fee string `json:"l1Fee,omitempty"` - L1FeeScalar string `json:"l1FeeScalar,omitempty"` - L1GasPrice string `json:"l1GasPrice,omitempty"` - L1GasUsed string `json:"l1GasUsed,omitempty"` + GasUsed string `json:"gasUsed" ts_doc:"Amount of gas actually used by the transaction."` + Status string `json:"status" ts_doc:"Transaction execution status (0x0 = fail, 0x1 = success)."` + Logs []*RpcLog `json:"logs" ts_doc:"Array of log entries generated by this transaction."` + L1Fee string `json:"l1Fee,omitempty" ts_doc:"Additional Layer 1 fee, if on a rollup network."` + L1FeeScalar string `json:"l1FeeScalar,omitempty" ts_doc:"Fee scaling factor for L1 fees on some L2s."` + L1GasPrice string `json:"l1GasPrice,omitempty" ts_doc:"Gas price used on L1 for the rollup network."` + L1GasUsed string `json:"l1GasUsed,omitempty" ts_doc:"Amount of L1 gas used by the transaction, if any."` } // EthereumSpecificData contains data specific to Ethereum transactions type EthereumSpecificData struct { - Tx *RpcTransaction `json:"tx"` - InternalData *EthereumInternalData `json:"internalData,omitempty"` - Receipt *RpcReceipt `json:"receipt,omitempty"` + Tx *RpcTransaction `json:"tx" ts_doc:"Raw transaction details from the blockchain node."` + InternalData *EthereumInternalData `json:"internalData,omitempty" ts_doc:"Summary of internal calls/transfers, if any."` + Receipt *RpcReceipt `json:"receipt,omitempty" ts_doc:"Transaction receipt info, including logs and gas usage."` } // AddressAliasRecord maps address to ENS name type AddressAliasRecord struct { - Address string - Name string + Address string `ts_doc:"Address whose alias is being stored."` + Name string `ts_doc:"The resolved name/alias (e.g. ENS domain)."` } // EthereumBlockSpecificData contain data specific for Ethereum block type EthereumBlockSpecificData struct { - InternalDataError string - AddressAliasRecords []AddressAliasRecord - Contracts []ContractInfo + InternalDataError string `ts_doc:"Error message for processing block internal data, if any."` + AddressAliasRecords []AddressAliasRecord `ts_doc:"List of address-to-alias mappings discovered in this block."` + Contracts []ContractInfo `ts_doc:"List of contracts created or updated in this block."` } -// StakingPool holds data about address participation in a staking pool contract +// StakingPoolData holds data about address participation in a staking pool contract type StakingPoolData struct { - Contract string `json:"contract"` - Name string `json:"name"` - PendingBalance big.Int `json:"pendingBalance"` // pendingBalanceOf method - PendingDepositedBalance big.Int `json:"pendingDepositedBalance"` // pendingDepositedBalanceOf method - DepositedBalance big.Int `json:"depositedBalance"` // depositedBalanceOf method - WithdrawTotalAmount big.Int `json:"withdrawTotalAmount"` // withdrawRequest method, return value [0] - ClaimableAmount big.Int `json:"claimableAmount"` // withdrawRequest method, return value [1] - RestakedReward big.Int `json:"restakedReward"` // restakedRewardOf method - AutocompoundBalance big.Int `json:"autocompoundBalance"` // autocompoundBalanceOf method + Contract string `json:"contract" ts_doc:"Address of the staking pool contract."` + Name string `json:"name" ts_doc:"Human-readable name of the staking pool."` + PendingBalance big.Int `json:"pendingBalance" ts_doc:"Amount not yet finalized in the pool (pendingBalanceOf)."` + PendingDepositedBalance big.Int `json:"pendingDepositedBalance" ts_doc:"Amount pending deposit (pendingDepositedBalanceOf)."` + DepositedBalance big.Int `json:"depositedBalance" ts_doc:"Total amount currently deposited (depositedBalanceOf)."` + WithdrawTotalAmount big.Int `json:"withdrawTotalAmount" ts_doc:"Total amount requested for withdrawal (withdrawRequest[0])."` + ClaimableAmount big.Int `json:"claimableAmount" ts_doc:"Amount that can be claimed (withdrawRequest[1])."` + RestakedReward big.Int `json:"restakedReward" ts_doc:"Total reward that has been restaked (restakedRewardOf)."` + AutocompoundBalance big.Int `json:"autocompoundBalance" ts_doc:"Auto-compounded balance (autocompoundBalanceOf)."` } // Eip1559Fee diff --git a/common/internalstate.go b/common/internalstate.go index 9e452ce7..2122c178 100644 --- a/common/internalstate.go +++ b/common/internalstate.go @@ -23,85 +23,85 @@ var inShutdown int32 // InternalStateColumn contains the data of a db column type InternalStateColumn struct { - Name string `json:"name"` - Version uint32 `json:"version"` - Rows int64 `json:"rows"` - KeyBytes int64 `json:"keyBytes"` - ValueBytes int64 `json:"valueBytes"` - Updated time.Time `json:"updated"` + Name string `json:"name" ts_doc:"Name of the database column."` + Version uint32 `json:"version" ts_doc:"Version or schema version of the column."` + Rows int64 `json:"rows" ts_doc:"Number of rows stored in this column."` + KeyBytes int64 `json:"keyBytes" ts_doc:"Total size (in bytes) of keys stored in this column."` + ValueBytes int64 `json:"valueBytes" ts_doc:"Total size (in bytes) of values stored in this column."` + Updated time.Time `json:"updated" ts_doc:"Timestamp of the last update to this column."` } // BackendInfo is used to get information about blockchain type BackendInfo struct { - BackendError string `json:"error,omitempty"` - Chain string `json:"chain,omitempty"` - Blocks int `json:"blocks,omitempty"` - Headers int `json:"headers,omitempty"` - BestBlockHash string `json:"bestBlockHash,omitempty"` - Difficulty string `json:"difficulty,omitempty"` - SizeOnDisk int64 `json:"sizeOnDisk,omitempty"` - Version string `json:"version,omitempty"` - Subversion string `json:"subversion,omitempty"` - ProtocolVersion string `json:"protocolVersion,omitempty"` - Timeoffset float64 `json:"timeOffset,omitempty"` - Warnings string `json:"warnings,omitempty"` - ConsensusVersion string `json:"consensus_version,omitempty"` - Consensus interface{} `json:"consensus,omitempty"` + BackendError string `json:"error,omitempty" ts_doc:"Error message if something went wrong in the backend."` + Chain string `json:"chain,omitempty" ts_doc:"Name of the chain - e.g. 'main'."` + Blocks int `json:"blocks,omitempty" ts_doc:"Number of fully verified blocks in the chain."` + Headers int `json:"headers,omitempty" ts_doc:"Number of block headers in the chain."` + BestBlockHash string `json:"bestBlockHash,omitempty" ts_doc:"Hash of the best block in hex."` + Difficulty string `json:"difficulty,omitempty" ts_doc:"Current difficulty of the network."` + SizeOnDisk int64 `json:"sizeOnDisk,omitempty" ts_doc:"Size of the blockchain data on disk in bytes."` + Version string `json:"version,omitempty" ts_doc:"Version of the blockchain backend - e.g. '280000'."` + Subversion string `json:"subversion,omitempty" ts_doc:"Subversion of the blockchain backend - e.g. '/Satoshi:28.0.0/'."` + ProtocolVersion string `json:"protocolVersion,omitempty" ts_doc:"Protocol version of the blockchain backend - e.g. '70016'."` + Timeoffset float64 `json:"timeOffset,omitempty" ts_doc:"Time offset (in seconds) reported by the backend."` + Warnings string `json:"warnings,omitempty" ts_doc:"Any warnings given by the backend regarding the chain state."` + ConsensusVersion string `json:"consensus_version,omitempty" ts_doc:"Version or details of the consensus protocol in use."` + Consensus interface{} `json:"consensus,omitempty" ts_doc:"Additional chain-specific consensus data."` } // InternalState contains the data of the internal state type InternalState struct { - mux sync.Mutex + mux sync.Mutex `ts_doc:"Mutex for synchronized access to the internal state."` - Coin string `json:"coin"` - CoinShortcut string `json:"coinShortcut"` - CoinLabel string `json:"coinLabel"` - Host string `json:"host"` - Network string `json:"network,omitempty"` + Coin string `json:"coin" ts_doc:"Coin name (e.g. 'Bitcoin')."` + CoinShortcut string `json:"coinShortcut" ts_doc:"Short code for the coin (e.g. 'BTC')."` + CoinLabel string `json:"coinLabel" ts_doc:"Human-readable label for the coin (e.g. 'Bitcoin main')."` + Host string `json:"host" ts_doc:"Hostname of the node or backend."` + Network string `json:"network,omitempty" ts_doc:"Network name if different from CoinShortcut (e.g. 'testnet')."` - DbState uint32 `json:"dbState"` - ExtendedIndex bool `json:"extendedIndex"` + DbState uint32 `json:"dbState" ts_doc:"State of the database (closed=0, open=1, inconsistent=2)."` + ExtendedIndex bool `json:"extendedIndex" ts_doc:"Indicates if an extended indexing strategy is used."` - LastStore time.Time `json:"lastStore"` + LastStore time.Time `json:"lastStore" ts_doc:"Time when the internal state was last stored/persisted."` // true if application is with flag --sync - SyncMode bool `json:"syncMode"` + SyncMode bool `json:"syncMode" ts_doc:"Flag indicating if the node is in sync mode."` - InitialSync bool `json:"initialSync"` - IsSynchronized bool `json:"isSynchronized"` - BestHeight uint32 `json:"bestHeight"` - StartSync time.Time `json:"-"` - LastSync time.Time `json:"lastSync"` - BlockTimes []uint32 `json:"-"` - AvgBlockPeriod uint32 `json:"-"` + InitialSync bool `json:"initialSync" ts_doc:"If true, the system is in the initial sync phase."` + IsSynchronized bool `json:"isSynchronized" ts_doc:"If true, the main index is fully synced to BestHeight."` + BestHeight uint32 `json:"bestHeight" ts_doc:"Current best block height known to the indexer."` + StartSync time.Time `json:"-" ts_doc:"Timestamp when sync started (not exposed via JSON)."` + LastSync time.Time `json:"lastSync" ts_doc:"Timestamp of the last successful sync."` + BlockTimes []uint32 `json:"-" ts_doc:"List of block timestamps (per height) for calculating historical stats (not exposed via JSON)."` + AvgBlockPeriod uint32 `json:"-" ts_doc:"Average time (in seconds) per block for the last 100 blocks (not exposed via JSON)."` - IsMempoolSynchronized bool `json:"isMempoolSynchronized"` - MempoolSize int `json:"mempoolSize"` - LastMempoolSync time.Time `json:"lastMempoolSync"` + IsMempoolSynchronized bool `json:"isMempoolSynchronized" ts_doc:"If true, mempool data is in sync."` + MempoolSize int `json:"mempoolSize" ts_doc:"Number of transactions in the current mempool."` + LastMempoolSync time.Time `json:"lastMempoolSync" ts_doc:"Timestamp of the last mempool sync."` - DbColumns []InternalStateColumn `json:"dbColumns"` + DbColumns []InternalStateColumn `json:"dbColumns" ts_doc:"List of database column statistics."` - HasFiatRates bool `json:"-"` - HasTokenFiatRates bool `json:"-"` - HistoricalFiatRatesTime time.Time `json:"historicalFiatRatesTime"` - HistoricalTokenFiatRatesTime time.Time `json:"historicalTokenFiatRatesTime"` + HasFiatRates bool `json:"-" ts_doc:"True if fiat rates are supported (not exposed via JSON)."` + HasTokenFiatRates bool `json:"-" ts_doc:"True if token fiat rates are supported (not exposed via JSON)."` + HistoricalFiatRatesTime time.Time `json:"historicalFiatRatesTime" ts_doc:"Timestamp of the last historical fiat rates update."` + HistoricalTokenFiatRatesTime time.Time `json:"historicalTokenFiatRatesTime" ts_doc:"Timestamp of the last historical token fiat rates update."` - EnableSubNewTx bool `json:"-"` + EnableSubNewTx bool `json:"-" ts_doc:"Internal flag controlling subscription to new transactions (not exposed)."` - BackendInfo BackendInfo `json:"-"` + BackendInfo BackendInfo `json:"-" ts_doc:"Information about the connected blockchain backend (not exposed in JSON)."` // database migrations - UtxoChecked bool `json:"utxoChecked"` - SortedAddressContracts bool `json:"sortedAddressContracts"` + UtxoChecked bool `json:"utxoChecked" ts_doc:"Indicates if UTXO consistency checks have been performed."` + SortedAddressContracts bool `json:"sortedAddressContracts" ts_doc:"Indicates if address/contract sorting has been completed."` // golomb filter settings - BlockGolombFilterP uint8 `json:"block_golomb_filter_p"` - BlockFilterScripts string `json:"block_filter_scripts"` - BlockFilterUseZeroedKey bool `json:"block_filter_use_zeroed_key"` + BlockGolombFilterP uint8 `json:"block_golomb_filter_p" ts_doc:"Parameter P for building Golomb-Rice filters for blocks."` + BlockFilterScripts string `json:"block_filter_scripts" ts_doc:"Scripts included in block filters (e.g., 'p2pkh,p2sh')."` + BlockFilterUseZeroedKey bool `json:"block_filter_use_zeroed_key" ts_doc:"If true, uses a zeroed key for building block filters."` // allowed number of fetched accounts over websocket - WsGetAccountInfoLimit int `json:"-"` - WsLimitExceedingIPs map[string]int `json:"-"` + WsGetAccountInfoLimit int `json:"-" ts_doc:"Limit of how many getAccountInfo calls can be made via WS (not exposed)."` + WsLimitExceedingIPs map[string]int `json:"-" ts_doc:"Tracks IP addresses exceeding the WS limit (not exposed)."` } // StartedSync signals start of synchronization diff --git a/server/ws_types.go b/server/ws_types.go index 111b698e..6732b4ea 100644 --- a/server/ws_types.go +++ b/server/ws_types.go @@ -6,150 +6,176 @@ import ( "github.com/trezor/blockbook/api" ) +// WsReq represents a generic WebSocket request with an ID, method, and raw parameters. type WsReq struct { - ID string `json:"id"` - Method string `json:"method" ts_type:"'getAccountInfo' | 'getInfo' | 'getBlockHash'| 'getBlock' | 'getAccountUtxo' | 'getBalanceHistory' | 'getTransaction' | 'getTransactionSpecific' | 'estimateFee' | 'sendTransaction' | 'subscribeNewBlock' | 'unsubscribeNewBlock' | 'subscribeNewTransaction' | 'unsubscribeNewTransaction' | 'subscribeAddresses' | 'unsubscribeAddresses' | 'subscribeFiatRates' | 'unsubscribeFiatRates' | 'ping' | 'getCurrentFiatRates' | 'getFiatRatesForTimestamps' | 'getFiatRatesTickersList' | 'getMempoolFilters'"` - Params json.RawMessage `json:"params" ts_type:"any"` + ID string `json:"id" ts_doc:"Unique request identifier."` + Method string `json:"method" ts_type:"'getAccountInfo' | 'getInfo' | 'getBlockHash'| 'getBlock' | 'getAccountUtxo' | 'getBalanceHistory' | 'getTransaction' | 'getTransactionSpecific' | 'estimateFee' | 'sendTransaction' | 'subscribeNewBlock' | 'unsubscribeNewBlock' | 'subscribeNewTransaction' | 'unsubscribeNewTransaction' | 'subscribeAddresses' | 'unsubscribeAddresses' | 'subscribeFiatRates' | 'unsubscribeFiatRates' | 'ping' | 'getCurrentFiatRates' | 'getFiatRatesForTimestamps' | 'getFiatRatesTickersList' | 'getMempoolFilters'" ts_doc:"Requested method name."` + Params json.RawMessage `json:"params" ts_type:"any" ts_doc:"Parameters for the requested method in raw JSON format."` } +// WsRes represents a generic WebSocket response with an ID and arbitrary data. type WsRes struct { - ID string `json:"id"` - Data interface{} `json:"data"` + ID string `json:"id" ts_doc:"Corresponding request identifier."` + Data interface{} `json:"data" ts_doc:"Payload of the response, structure depends on the request."` } +// WsAccountInfoReq carries parameters for the 'getAccountInfo' method. type WsAccountInfoReq struct { - Descriptor string `json:"descriptor"` - Details string `json:"details,omitempty" ts_type:"'basic' | 'tokens' | 'tokenBalances' | 'txids' | 'txslight' | 'txs'"` - Tokens string `json:"tokens,omitempty" ts_type:"'derived' | 'used' | 'nonzero'"` - PageSize int `json:"pageSize,omitempty"` - Page int `json:"page,omitempty"` - FromHeight int `json:"from,omitempty"` - ToHeight int `json:"to,omitempty"` - ContractFilter string `json:"contractFilter,omitempty"` - SecondaryCurrency string `json:"secondaryCurrency,omitempty"` - Gap int `json:"gap,omitempty"` + Descriptor string `json:"descriptor" ts_doc:"Address or XPUB descriptor to query."` + Details string `json:"details,omitempty" ts_type:"'basic' | 'tokens' | 'tokenBalances' | 'txids' | 'txslight' | 'txs'" ts_doc:"Level of detail to retrieve about the account."` + Tokens string `json:"tokens,omitempty" ts_type:"'derived' | 'used' | 'nonzero'" ts_doc:"Which tokens to include in the account info."` + PageSize int `json:"pageSize,omitempty" ts_doc:"Number of items per page, if paging is used."` + Page int `json:"page,omitempty" ts_doc:"Requested page index, if paging is used."` + FromHeight int `json:"from,omitempty" ts_doc:"Starting block height for transaction filtering."` + ToHeight int `json:"to,omitempty" ts_doc:"Ending block height for transaction filtering."` + ContractFilter string `json:"contractFilter,omitempty" ts_doc:"Filter by specific contract address (for token data)."` + SecondaryCurrency string `json:"secondaryCurrency,omitempty" ts_doc:"Currency code to convert values into (e.g. 'USD')."` + Gap int `json:"gap,omitempty" ts_doc:"Gap limit for XPUB scanning, if relevant."` } +// WsBackendInfo holds extended info about the connected backend node. type WsBackendInfo struct { - Version string `json:"version,omitempty"` - Subversion string `json:"subversion,omitempty"` - ConsensusVersion string `json:"consensus_version,omitempty"` - Consensus interface{} `json:"consensus,omitempty"` + Version string `json:"version,omitempty" ts_doc:"Backend version string."` + Subversion string `json:"subversion,omitempty" ts_doc:"Backend sub-version string."` + ConsensusVersion string `json:"consensus_version,omitempty" ts_doc:"Consensus protocol version in use."` + Consensus interface{} `json:"consensus,omitempty" ts_doc:"Additional consensus details, structure depends on blockchain."` } +// WsInfoRes is returned by 'getInfo' requests, containing basic blockchain info. type WsInfoRes struct { - Name string `json:"name"` - Shortcut string `json:"shortcut"` - Network string `json:"network"` - Decimals int `json:"decimals"` - Version string `json:"version"` - BestHeight int `json:"bestHeight"` - BestHash string `json:"bestHash"` - Block0Hash string `json:"block0Hash"` - Testnet bool `json:"testnet"` - Backend WsBackendInfo `json:"backend"` + Name string `json:"name" ts_doc:"Human-readable blockchain name."` + Shortcut string `json:"shortcut" ts_doc:"Short code for the blockchain (e.g. BTC, ETH)."` + Network string `json:"network" ts_doc:"Network identifier (e.g. mainnet, testnet)."` + Decimals int `json:"decimals" ts_doc:"Number of decimals in the base unit of the coin."` + Version string `json:"version" ts_doc:"Version of the blockbook or backend service."` + BestHeight int `json:"bestHeight" ts_doc:"Current best chain height according to the backend."` + BestHash string `json:"bestHash" ts_doc:"Block hash of the best (latest) block."` + Block0Hash string `json:"block0Hash" ts_doc:"Genesis block hash or identifier."` + Testnet bool `json:"testnet" ts_doc:"Indicates if this is a test network."` + Backend WsBackendInfo `json:"backend" ts_doc:"Additional backend-related information."` } +// WsBlockHashReq holds a single integer for querying the block hash at that height. type WsBlockHashReq struct { - Height int `json:"height"` + Height int `json:"height" ts_doc:"Block height for which the hash is requested."` } +// WsBlockHashRes returns the block hash for a requested height. type WsBlockHashRes struct { - Hash string `json:"hash"` + Hash string `json:"hash" ts_doc:"Block hash at the requested height."` } +// WsBlockReq is used to request details of a block (by ID) with paging options. type WsBlockReq struct { - Id string `json:"id"` - PageSize int `json:"pageSize,omitempty"` - Page int `json:"page,omitempty"` + Id string `json:"id" ts_doc:"Block identifier (hash)."` + PageSize int `json:"pageSize,omitempty" ts_doc:"Number of transactions per page in the block."` + Page int `json:"page,omitempty" ts_doc:"Page index to retrieve if multiple pages of transactions are available."` } +// WsAccountUtxoReq is used to request unspent transaction outputs (UTXOs) for a given xpub/address. type WsAccountUtxoReq struct { - Descriptor string `json:"descriptor"` + Descriptor string `json:"descriptor" ts_doc:"Address or XPUB descriptor to retrieve UTXOs for."` } +// WsBalanceHistoryReq is used to retrieve a historical balance chart or intervals for an account. type WsBalanceHistoryReq struct { - Descriptor string `json:"descriptor"` - From int64 `json:"from,omitempty"` - To int64 `json:"to,omitempty"` - Currencies []string `json:"currencies,omitempty"` - Gap int `json:"gap,omitempty"` - GroupBy uint32 `json:"groupBy,omitempty"` + Descriptor string `json:"descriptor" ts_doc:"Address or XPUB descriptor to query history for."` + From int64 `json:"from,omitempty" ts_doc:"Unix timestamp from which to start the history."` + To int64 `json:"to,omitempty" ts_doc:"Unix timestamp at which to end the history."` + Currencies []string `json:"currencies,omitempty" ts_doc:"List of currency codes for which to fetch exchange rates at each interval."` + Gap int `json:"gap,omitempty" ts_doc:"Gap limit for XPUB scanning, if relevant."` + GroupBy uint32 `json:"groupBy,omitempty" ts_doc:"Size of each aggregated time window in seconds."` } +// WsTransactionReq requests details for a specific transaction by its txid. type WsTransactionReq struct { - Txid string `json:"txid"` + Txid string `json:"txid" ts_doc:"Transaction ID to retrieve details for."` } +// WsMempoolFiltersReq requests mempool filters for scripts of a specific type, after a given timestamp. type WsMempoolFiltersReq struct { - ScriptType string `json:"scriptType"` - FromTimestamp uint32 `json:"fromTimestamp"` - ParamM uint64 `json:"M,omitempty"` + ScriptType string `json:"scriptType" ts_doc:"Type of script we are filtering for (e.g., P2PKH, P2SH)."` + FromTimestamp uint32 `json:"fromTimestamp" ts_doc:"Only retrieve filters for mempool txs after this timestamp."` + ParamM uint64 `json:"M,omitempty" ts_doc:"Optional parameter for certain filter logic (e.g., n-bloom)."` } +// WsBlockFilterReq requests a filter for a given block hash and script type. type WsBlockFilterReq struct { - ScriptType string `json:"scriptType"` - BlockHash string `json:"blockHash"` - ParamM uint64 `json:"M,omitempty"` + ScriptType string `json:"scriptType" ts_doc:"Type of script filter (e.g., P2PKH, P2SH)."` + BlockHash string `json:"blockHash" ts_doc:"Block hash for which we want the filter."` + ParamM uint64 `json:"M,omitempty" ts_doc:"Optional parameter for certain filter logic."` } +// WsBlockFiltersBatchReq is used to request batch filters for consecutive blocks. type WsBlockFiltersBatchReq struct { - ScriptType string `json:"scriptType"` - BlockHash string `json:"bestKnownBlockHash"` - PageSize int `json:"pageSize,omitempty"` - ParamM uint64 `json:"M,omitempty"` + ScriptType string `json:"scriptType" ts_doc:"Type of script filter (e.g., P2PKH, P2SH)."` + BlockHash string `json:"bestKnownBlockHash" ts_doc:"Hash of the latest known block. Filters will be retrieved backward from here."` + PageSize int `json:"pageSize,omitempty" ts_doc:"Number of block filters per request."` + ParamM uint64 `json:"M,omitempty" ts_doc:"Optional parameter for certain filter logic."` } +// WsTransactionSpecificReq requests blockchain-specific transaction info that might go beyond standard fields. type WsTransactionSpecificReq struct { - Txid string `json:"txid"` + Txid string `json:"txid" ts_doc:"Transaction ID for the detailed blockchain-specific data."` } +// WsEstimateFeeReq requests an estimation of transaction fees for a set of blocks or with specific parameters. type WsEstimateFeeReq struct { - Blocks []int `json:"blocks,omitempty"` - Specific map[string]interface{} `json:"specific,omitempty" ts_type:"{conservative?: boolean;txsize?: number;from?: string;to?: string;data?: string;value?: string;}"` + Blocks []int `json:"blocks,omitempty" ts_doc:"Block confirmations targets for which fees should be estimated."` + Specific map[string]interface{} `json:"specific,omitempty" ts_type:"{conservative?: boolean; txsize?: number; from?: string; to?: string; data?: string; value?: string;}" ts_doc:"Additional chain-specific parameters (e.g. for Ethereum)."` } +// WsEstimateFeeRes is returned in response to a fee estimation request. type WsEstimateFeeRes struct { - FeePerTx string `json:"feePerTx,omitempty"` - FeePerUnit string `json:"feePerUnit,omitempty"` - FeeLimit string `json:"feeLimit,omitempty"` + FeePerTx string `json:"feePerTx,omitempty" ts_doc:"Estimated total fee per transaction, if relevant."` + FeePerUnit string `json:"feePerUnit,omitempty" ts_doc:"Estimated fee per unit (sat/byte, Wei/gas, etc.)."` + FeeLimit string `json:"feeLimit,omitempty" ts_doc:"Max fee limit for blockchains like Ethereum."` Eip1559 *api.Eip1559Fees `json:"eip1559,omitempty"` } +// WsSendTransactionReq is used to broadcast a transaction to the network. type WsSendTransactionReq struct { - Hex string `json:"hex"` + Hex string `json:"hex" ts_doc:"Hex-encoded transaction data to broadcast."` } +// WsSubscribeAddressesReq is used to subscribe to updates on a list of addresses. type WsSubscribeAddressesReq struct { - Addresses []string `json:"addresses"` + Addresses []string `json:"addresses" ts_doc:"List of addresses to subscribe for updates (e.g., new transactions)."` } + +// WsSubscribeFiatRatesReq subscribes to updates of fiat rates for a specific currency or set of tokens. type WsSubscribeFiatRatesReq struct { - Currency string `json:"currency,omitempty"` - Tokens []string `json:"tokens,omitempty"` + Currency string `json:"currency,omitempty" ts_doc:"Fiat currency code (e.g. 'USD')."` + Tokens []string `json:"tokens,omitempty" ts_doc:"List of token symbols or IDs to get fiat rates for."` } +// WsCurrentFiatRatesReq requests the current fiat rates for specified currencies (and optionally a token). type WsCurrentFiatRatesReq struct { - Currencies []string `json:"currencies,omitempty"` - Token string `json:"token,omitempty"` + Currencies []string `json:"currencies,omitempty" ts_doc:"List of fiat currencies, e.g. ['USD','EUR']."` + Token string `json:"token,omitempty" ts_doc:"Token symbol or ID if asking for token fiat rates (e.g. 'ETH')."` } +// WsFiatRatesForTimestampsReq requests historical fiat rates for given timestamps. type WsFiatRatesForTimestampsReq struct { - Timestamps []int64 `json:"timestamps"` - Currencies []string `json:"currencies,omitempty"` - Token string `json:"token,omitempty"` + Timestamps []int64 `json:"timestamps" ts_doc:"List of Unix timestamps for which to retrieve fiat rates."` + Currencies []string `json:"currencies,omitempty" ts_doc:"List of fiat currencies, e.g. ['USD','EUR']."` + Token string `json:"token,omitempty" ts_doc:"Token symbol or ID if asking for token fiat rates."` } +// WsFiatRatesTickersListReq requests a list of tickers for a given timestamp (and possibly a token). type WsFiatRatesTickersListReq struct { - Timestamp int64 `json:"timestamp,omitempty"` - Token string `json:"token,omitempty"` + Timestamp int64 `json:"timestamp,omitempty" ts_doc:"Timestamp for which the list of available tickers is needed."` + Token string `json:"token,omitempty" ts_doc:"Token symbol or ID if asking for token-specific fiat rates."` } +// WsRpcCallReq is used for raw RPC calls (for example, on an Ethereum-like backend). type WsRpcCallReq struct { - From string `json:"from,omitempty"` - To string `json:"to"` - Data string `json:"data"` + From string `json:"from,omitempty" ts_doc:"Address from which the RPC call is originated (if relevant)."` + To string `json:"to" ts_doc:"Contract or address to which the RPC call is made."` + Data string `json:"data" ts_doc:"Hex-encoded call data (function signature + parameters)."` } +// WsRpcCallRes returns the result of an RPC call in hex form. type WsRpcCallRes struct { - Data string `json:"data"` + Data string `json:"data" ts_doc:"Hex-encoded return data from the call."` }