Mirrors/blockbook
2
0
Fork 0
mirror of https://github.com/trezor/blockbook.git synced 2026-02-20 00:51:39 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: document public API structs

Browse Source
This commit is contained in:
grdddj
2025-02-10 14:21:19 +01:00
committed by Martin
parent 91bdb8c948
commit d328ed9e00
5 changed files with 548 additions and 517 deletions
Download Patch File Download Diff File Expand all files Collapse all files

444
api/types.go
View File

@@ -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

190
bchain/types.go
View File

@@ -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

151
bchain/types_ethereum_type.go
View File

@@ -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

108
common/internalstate.go
View File

@@ -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

172
server/ws_types.go
View File

@@ -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."`
}