Documentation
¶
Overview ¶
Package utxorpc implements Dingo's UTxO RPC server, serving the utxorpc.v1alpha.cardano gRPC API defined by the UTxO RPC spec.
The Utxorpc type is a gRPC server that translates incoming requests into queries against the ledger and mempool packages and streams results back to clients. It is only started when the node runs in "api" storage mode and DINGO_UTXORPC_PORT is non-zero — "core" mode nodes do not index the data required to answer query requests.
Predicate evaluation ¶
SearchUtxos uses UtxoPredicate filters over live UTxOs; a nil SearchUtxos predicate scans all addresses. TxPredicate evaluation for transaction streams uses composite operators (not / all_of / any_of) around leaf predicates (address, policy, certificate, consumes, produces, …). That path is stricter: evalTxPredicateOutcome returns predNoMatch for a nil converted TxPredicate node.
Authentication ¶
This server does not authenticate clients. Authentication, rate limiting, and TLS termination are expected to be handled by a reverse proxy or API gateway in front of the node. Do not add auth middleware here — keep the node itself transport-neutral.
Index ¶
Constants ¶
const ( DefaultMaxBlockRefs = 100 DefaultMaxUtxoKeys = 1000 DefaultMaxHistoryItems = 10000 DefaultMaxDataKeys = 1000 DefaultServerTimeout = time.Hour )
Default request size limits to prevent denial-of-service via unbounded request arrays.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Utxorpc ¶
type Utxorpc struct {
// contains filtered or unexported fields
}
func NewUtxorpc ¶
func NewUtxorpc(cfg UtxorpcConfig) *Utxorpc
type UtxorpcConfig ¶
type UtxorpcConfig struct {
Logger *slog.Logger
EventBus UtxorpcEventBus
LedgerState UtxorpcLedgerState
Mempool UtxorpcMempool
TlsCertFilePath string
TlsKeyFilePath string
Host string
Port uint
// Request size limits (0 = use default)
MaxBlockRefs int
MaxUtxoKeys int
// MaxHistoryItems caps DumpHistory and SearchUtxos page size; omitted
// max_items uses this cap.
MaxHistoryItems int
MaxDataKeys int
// ServerTimeout bounds long-running UTxO RPC handlers server-side
// (0 = use default).
ServerTimeout time.Duration
// CORSAllowedOrigins configures Access-Control-Allow-Origin.
// Empty disables CORS.
CORSAllowedOrigins []string
}
type UtxorpcEventBus ¶ added in v0.55.0
type UtxorpcEventBus interface {
SubscribeFunc(eventType event.EventType, handlerFunc event.EventHandlerFunc) event.EventSubscriberId
Unsubscribe(eventType event.EventType, subId event.EventSubscriberId)
}
UtxorpcEventBus is the subset of event.EventBus needed by the UTxO RPC server.
type UtxorpcLedgerState ¶ added in v0.55.0
type UtxorpcLedgerState interface {
BlockByHash(hash []byte) (models.Block, error)
CardanoNodeConfig() *cardano.CardanoNodeConfig
Datum(hash []byte) (*models.Datum, error)
EvaluateTx(tx lcommon.Transaction) (uint64, lcommon.ExUnits, map[lcommon.RedeemerKey]lcommon.ExUnits, error)
GetBlock(point ocommon.Point) (models.Block, error)
GetChainFromPointContext(ctx context.Context, point ocommon.Point, inclusive bool) (*chain.ChainIterator, error)
GetCurrentPParams() lcommon.ProtocolParameters
GetEpochs() ([]models.Epoch, error)
GetIntersectPoint(points []ocommon.Point) (*ocommon.Point, error)
GetPParamsForEpoch(epoch uint64, era eras.EraDesc) (lcommon.ProtocolParameters, error)
SlotToTime(slot uint64) (time.Time, error)
SystemStart() (time.Time, error)
Tip() ochainsync.Tip
TransactionByHash(hash []byte) (*models.Transaction, error)
UtxoByRef(txId []byte, outputIdx uint32) (*models.Utxo, error)
UtxosByAddressWithOrdering(q *models.UtxoWithOrderingQuery) ([]models.UtxoWithOrdering, error)
}
UtxorpcLedgerState is the subset of ledger.LedgerState needed by the UTxO RPC server. Using this interface keeps the server and service handlers free of a direct *ledger.LedgerState dependency.
type UtxorpcMempool ¶ added in v0.55.0
type UtxorpcMempool interface {
AddTransaction(txType uint, txBytes []byte) error
Transactions() []mempool.MempoolTransaction
}
UtxorpcMempool is the subset of mempool.Mempool needed by the UTxO RPC server.
Source Files