utxorpc

type ProviderConfig struct {
	Port uint                `yaml:"port"`
	Host string              `yaml:"host"`
	TLS  apiconfig.TLSPolicy `yaml:"tls"`
}

type ProviderDependencies struct {
	Logger             *slog.Logger
	EventBus           UtxorpcEventBus
	LedgerState        UtxorpcLedgerState
	Mempool            UtxorpcMempool
	Host               string
	CORSAllowedOrigins []string
}

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

type UtxorpcConfig struct {
	Logger      *slog.Logger
	EventBus    UtxorpcEventBus
	LedgerState UtxorpcLedgerState
	Mempool     UtxorpcMempool
	TLS         apiconfig.EffectiveTLS
	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
	// HistoryPageItems is the DumpHistory page size used when max_items is
	// omitted (0 = use default, capped at MaxHistoryItems).
	HistoryPageItems int
	// MaxHistoryBytes caps the serialized block bytes in one DumpHistory
	// response; a longer page is cut short and continues from next_token
	// (0 = use default).
	MaxHistoryBytes int
	MaxDataKeys     int
	// MaxTxRefs caps the transaction references in one WaitForTx
	// request (0 = use default).
	MaxTxRefs int
	// MaxStreams caps concurrent FollowTip, WatchTx, WatchMempool and WaitForTx streams
	// across all clients; MaxStreamsPerClient caps them per client, an IPv4
	// address or IPv6 /64 (0 = use default).
	MaxStreams          int
	MaxStreamsPerClient int
	// MaxPredicateNodes caps the total nodes of a watch predicate
	// (0 = use default).
	MaxPredicateNodes int
	// MaxReplayBlocks caps how far behind the tip a WatchTx intersect may
	// start, in blocks (0 = use default).
	MaxReplayBlocks int
	// MaxWatchHistoryBytes caps the bytes one WatchTx stream retains for
	// rollback; older blocks are evicted and rebuilt from persisted blocks if
	// a rollback needs them (0 = use default).
	MaxWatchHistoryBytes int64
	// MaxWatchHistoryBytesTotal caps the bytes all WatchTx streams retain
	// for rollback together (0 = use default).
	MaxWatchHistoryBytesTotal int64
	// MaxConcurrentReplays caps FollowTip streams that are serving blocks
	// behind the tip at once, across all clients; a further replay is refused
	// with ResourceExhausted (0 = use default).
	MaxConcurrentReplays int
	// MaxReplaysPerClient caps the FollowTip streams one client may have
	// serving blocks behind the tip at once, so one client cannot hold every
	// MaxConcurrentReplays slot (0 = use default).
	MaxReplaysPerClient int
	// ReplayBlocksPerSecond paces the historical blocks FollowTip serves to
	// one client across all its streams; replay slows down, it does not stop
	// (0 = use default).
	ReplayBlocksPerSecond int
	// MaxReplayBlocksPerClient caps the historical blocks FollowTip serves to
	// one client per ReplayBudgetWindow; a replay that spends it ends with
	// ResourceExhausted (0 = use default).
	MaxReplayBlocksPerClient int64
	// ReplayBudgetWindow is the period MaxReplayBlocksPerClient covers
	// (0 = use default).
	ReplayBudgetWindow time.Duration
	// MaxPoolFilter caps ReadState's pool_keyhashes filter length.
	MaxPoolFilter int
	// MaxMempoolItems caps ReadMempool's result size (0 = use default).
	MaxMempoolItems int
	// MaxResponseBytes caps the payload bytes one bulk read response may
	// retain (0 = use default).
	MaxResponseBytes int64
	// MaxConcurrentBulkRequests caps concurrently running bulk read handlers
	// (0 = use default).
	MaxConcurrentBulkRequests int
	// MaxConcurrentEvalRequests caps EvalTx handlers before transaction
	// decoding; MaxEvalRequestsPerClient applies the same bound per client.
	MaxConcurrentEvalRequests int
	MaxEvalRequestsPerClient  int
	// BulkResponseWriteTimeout bounds delivery of a bulk unary response
	// (0 = use default).
	BulkResponseWriteTimeout time.Duration
	// 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 interface {
	SubscribeFunc(
		eventType event.EventType,
		handlerFunc event.EventHandlerFunc,
	) event.EventSubscriberId
	Unsubscribe(eventType event.EventType, subId event.EventSubscriberId)
	UnsubscribeAndWait(eventType event.EventType, subId event.EventSubscriberId)
}

type UtxorpcLedgerState interface {
	BlockTransactions(ctx context.Context, block models.Block) ([]lcommon.Transaction, error)
	BlockByHash(ctx context.Context, hash []byte) (models.Block, error)
	// BlockByHashIncludingRolledBack also finds blocks a primary-chain
	// rollback has already removed from the database.
	BlockByHashIncludingRolledBack(
		ctx context.Context,
		hash []byte,
	) (models.Block, error)
	CardanoNodeConfig() *cardano.CardanoNodeConfig
	// OldestRetainedSlot returns the slot of the oldest block whose body is
	// still stored, with ok=false when that is not known. It does no I/O.
	OldestRetainedSlot() (slot uint64, ok bool)
	Datums(ctx context.Context, hashes [][]byte) ([]*models.Datum, error)
	EvaluateTxContext(
		ctx context.Context,
		tx lcommon.Transaction,
	) (uint64, lcommon.ExUnits, map[lcommon.RedeemerKey]lcommon.ExUnits, error)
	ExistingTransactionHashes(
		ctx context.Context,
		hashes [][]byte,
	) ([][]byte, error)
	GetBlock(point ocommon.Point) (models.Block, error)
	// GetBlockContext is GetBlock under the caller's context.
	GetBlockContext(
		ctx context.Context,
		point ocommon.Point,
	) (models.Block, error)
	GetChainFromPointContext(
		ctx context.Context,
		point ocommon.Point,
		inclusive bool,
	) (*chain.ChainIterator, error)
	GetCurrentPParams() lcommon.ProtocolParameters
	GetCurrentPParamsForReporting() lcommon.ProtocolParameters
	GetEpochs() ([]models.Epoch, error)
	GetIntersectPoint(
		ctx context.Context,
		points []ocommon.Point,
	) (*ocommon.Point, error)
	GetPParamsForEpoch(
		epoch uint64,
		era eras.EraDesc,
	) (lcommon.ProtocolParameters, error)
	// PoolStakeDistributionBounded reports the active stake distribution
	// across at most maxPools block-producing pools. A nil filter asks for
	// every pool; see the method on ledger.LedgerState for why an empty non-nil
	// filter differs. at is the zero value and txn is nil here -- this RPC
	// handler always answers live, never pinned.
	PoolStakeDistributionBounded(
		ctx context.Context,
		poolFilter []lcommon.PoolKeyHash,
		at ledger.QueryPoint,
		txn *database.Txn,
		maxPools int,
	) (*ledger.PoolStakeDistribution, error)
	// PrimaryChainTip is the tip of the chain FollowTip's iterator reads. It
	// can be ahead of Tip while the ledger is still applying blocks.
	PrimaryChainTip() ochainsync.Tip
	// SecurityParam is the configured security parameter k, the deepest
	// rollback a chain follower can be asked to undo.
	SecurityParam() int
	SlotToTime(slot uint64) (time.Time, error)
	SystemStart() (time.Time, error)
	Tip() ochainsync.Tip
	TransactionByHash(ctx context.Context, hash []byte) (*models.Transaction, error)
	UtxoByRef(txId []byte, outputIdx uint32) (*models.Utxo, error)
	UtxosByRefsBounded(
		ctx context.Context,
		refs []models.UtxoId,
		maxBytes int64,
	) ([]models.Utxo, error)
	UtxosByAddressBoundedPage(
		ctx context.Context,
		q *models.UtxoWithOrderingQuery,
		maxCandidates int,
		maxBytes int64,
	) (models.UtxoAddressPage, error)
}

type UtxorpcMempool interface {
	AddTransaction(ctx context.Context, txType uint, txBytes []byte) error
	// TransactionsBounded returns a prefix of the pool in its snapshot
	// order holding at most maxItems transactions whose CBOR totals at most
	// maxBytes, together with the pool's total transaction count. A bound of
	// zero or less is not applied. The first transaction is returned even
	// when it alone exceeds maxBytes, so a non-empty pool never yields an
	// empty result.
	TransactionsBounded(
		maxItems int,
		maxBytes int64,
	) ([]mempool.MempoolTransaction, int)
}