Documentation
¶
Overview ¶
Package utxorpc implements Dingo's UTxO RPC server, serving the utxorpc.v1alpha and utxorpc.v1beta gRPC APIs 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_PLUGINS_API_UTXORPC_CONFIG_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. Exact addresses are compared by complete output address bytes, while payment/delegation parts are credential-scoped; 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 // DefaultShutdownTimeout bounds Stop's graceful http.Server.Shutdown // before it escalates to a hard Close, matching midnight/server's // identical ShutdownTimeout/defaultShutdownTimeout pattern. DefaultShutdownTimeout = 30 * time.Second )
Default request size limits to prevent denial-of-service via unbounded request arrays.
Variables ¶
This section is empty.
Functions ¶
func RegisterProvider ¶ added in v0.68.0
Types ¶
type ProviderConfig ¶ added in v0.68.0
type ProviderConfig struct {
Port uint `yaml:"port"`
}
type ProviderDependencies ¶ added in v0.68.0
type ProviderDependencies struct {
Logger *slog.Logger
EventBus UtxorpcEventBus
LedgerState UtxorpcLedgerState
Mempool UtxorpcMempool
Host string
TLSCertFilePath string
TLSKeyFilePath string
CORSAllowedOrigins []string
}
type Utxorpc ¶
type Utxorpc struct {
// contains filtered or unexported fields
}
func NewUtxorpc ¶
func NewUtxorpc(cfg UtxorpcConfig) *Utxorpc
func (*Utxorpc) Stop ¶
Stop shuts down the server, escalating to a hard Close if it does not complete within u.config.ShutdownTimeout (or the caller ctx's own deadline, if sooner), and also escalates immediately if ctx is cancelled (even when ctx carries no deadline at all), so a caller that wants to give up early is never stuck waiting out the full ShutdownTimeout. WatchTx/WatchMempool are unbounded streaming RPCs, so a connected client can otherwise keep http.Server.Shutdown blocked indefinitely, hanging any live database restore/truncate quiesce that waits on Stop -- matching midnight/server's identical Stop/gracefulStop pattern for a grpc.Server.
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
// ShutdownTimeout bounds Stop's graceful http.Server.Shutdown before it
// escalates to a hard Close (0 = use default). Watch* RPCs are
// unbounded streams, so a connected client can otherwise keep
// Shutdown blocked indefinitely.
ShutdownTimeout 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