Scalus
1.5.0
Generated with
Scalus/scalus/scalus.cardano/scalus.cardano.node

scalus.cardano.node

package scalus.cardano.node

Members list

Packages

package scalus.cardano.node.emulator
package scalus.cardano.node.stream

Type members

Classlikes

case class AppliedTx(tx: Transaction, slot: SlotNo, spent: Utxos)

A record of a transaction applied to the emulated ledger.

A record of a transaction applied to the emulated ledger.

Captures the parts of chain history that the live UTxO set no longer holds after application: the full transaction, the slot it was applied at, and the resolved inputs it consumed (which are removed from the UTxO set once the transaction is applied).

Value parameters

slot

the slot at which the ledger last validated tx, spec [TS-6]. It can be earlier than the slot of the block that holds tx.

spent

the UTxOs consumed by tx, resolved against the pre-application UTxO set

tx

the applied transaction

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
trait BlockchainProvider extends BlockchainProviderTF[Future], BlockchainReader

Provider for Cardano blockchain operations.

Provider for Cardano blockchain operations.

Provider is the cross-platform interface for interacting with Cardano nodes. All methods return Future values and work on both JVM and JavaScript platforms.

Extends BlockchainReader with transaction submission capability.

Implementations capture their ExecutionContext at construction time, so callers don't need to provide it for each method call.

Use scalus.utils.await extension for blocking operations on JVM when needed.

Attributes

Supertypes
trait BlockchainProviderTF[Future]
trait BlockchainReaderTF[Future]
class Object
trait Matchable
class Any
Show all
Known subtypes
trait EmulatorBase
class Emulator
trait BlockchainProviderTF[F[_]] extends BlockchainReaderTF[F]

Trait for blockchain providers with generic effect type. (TF is for "tagless final" style, often term used in FP literature).

Trait for blockchain providers with generic effect type. (TF is for "tagless final" style, often term used in FP literature).

Extends BlockchainReaderTF with transaction submission capability.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
trait EmulatorBase
class Emulator
Show all
trait BlockchainReader extends BlockchainReaderTF[Future]

Read-only provider for Cardano blockchain operations.

Read-only provider for Cardano blockchain operations.

BlockchainReader provides read-only access to blockchain state without the ability to submit transactions. This is useful for:

  • Snapshot-based testing where state should not be modified
  • Transaction building that only needs to query UTxOs
  • APIs that should not have submit capability

Use BlockchainProvider when you also need to submit transactions.

Implementations capture their ExecutionContext at construction time, so callers don't need to provide it for each method call.

Attributes

Supertypes
trait BlockchainReaderTF[Future]
class Object
trait Matchable
class Any
Known subtypes
trait EmulatorBase
class Emulator
Show all
trait BlockchainReaderTF[F[_]]

Read-only blockchain operations with generic effect type. (TF is for "tagless final" style, often term used in FP literature).

Read-only blockchain operations with generic effect type. (TF is for "tagless final" style, often term used in FP literature).

This trait provides read-only access to blockchain state. Use BlockchainProviderTF when you also need to submit transactions.

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
trait EmulatorBase
class Emulator
Show all
class BlockfrostProvider(apiKey: String, baseUrl: String, maxConcurrentRequests: Int, initialCardanoInfo: CardanoInfo)(using backend: Backend[Future], ec: ExecutionContext) extends BlockchainProvider

Blockfrost-based Provider for Cardano blockchain operations.

Blockfrost-based Provider for Cardano blockchain operations.

Use the async factory methods in the companion object to create instances: BlockfrostProvider.preview(apiKey), BlockfrostProvider.mainnet(apiKey), etc. These fetch protocol parameters during construction so that cardanoInfo is immediately available.

Value parameters

apiKey

Blockfrost API key

baseUrl

Blockfrost API base URL

initialCardanoInfo

CardanoInfo with protocol parameters (fetched during async construction)

maxConcurrentRequests

Maximum concurrent HTTP requests

Attributes

Companion
object
Supertypes
trait BlockchainProviderTF[Future]
trait BlockchainReaderTF[Future]
class Object
trait Matchable
class Any
Show all
object BlockfrostProvider

Companion object for BlockfrostProvider with factory methods and utilities.

Companion object for BlockfrostProvider with factory methods and utilities.

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
object BlockfrostProviderPlatform

JVM-specific platform support for BlockfrostProvider.

JVM-specific platform support for BlockfrostProvider.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
class ConcurrencyLimiter(maxConcurrent: Int)(using ec: ExecutionContext)

Limits the number of concurrent futures that can be executing. Cross-platform (JVM/JS) and non-blocking.

Limits the number of concurrent futures that can be executing. Cross-platform (JVM/JS) and non-blocking.

Value parameters

maxConcurrent

Maximum number of futures that can execute concurrently

Attributes

Supertypes
class Object
trait Matchable
class Any
case class DelegationInfo(poolId: Option[PoolKeyHash], rewards: Coin)

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object Emulator

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
Emulator.type
class Emulator extends EmulatorBase

An in-memory bare-bones node implementation (JVM version with thread-safe state).

An in-memory bare-bones node implementation (JVM version with thread-safe state).

Allows submitting transaction and querying UTxO state. Runs validators and mutators against all submitted transactions. The default validator and mutator lists reflect the Cardano Node UTxO related ledger rules.

The rules themselves live in EmulatorBase, shared with the JavaScript emulator; all this class adds is the state cell and the compare-and-set retry that makes concurrent submission safe.

Attributes

See also

scalus.cardano.ledger.rules for the ledger rules

Companion
object
Supertypes
trait InteropApi
trait EmulatorBase
trait BlockchainProviderTF[Future]
trait BlockchainReaderTF[Future]
class Object
trait Matchable
class Any
Show all
object EmulatorBase

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
trait EmulatorBase extends BlockchainProvider

Base trait for Emulator implementations containing the whole emulator state machine.

Base trait for Emulator implementations containing the whole emulator state machine.

Everything an emulator does to its state lives here, expressed against a single abstract cell holding one EmulatorState. The platform implementations supply only that cell: the JVM one an AtomicReference with a compare-and-set retry, the JavaScript one a plain var, since JavaScript is single-threaded. Neither carries a copy of the rules, so the two platforms cannot drift apart.

Attributes

Companion
object
Supertypes
trait BlockchainProviderTF[Future]
trait BlockchainReaderTF[Future]
class Object
trait Matchable
class Any
Show all
Known subtypes
class Emulator
object EmulatorDRepRegistration

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case class EmulatorDRepRegistration(credential: Credential, deposit: Coin, anchor: Option[Anchor] = ...)

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class EmulatorInitialState

What an emulator starts with, beyond its chain parameters.

What an emulator starts with, beyond its chain parameters.

The constructor is private, so a new field later adds a with method, not a break. Start from EmulatorInitialState.empty and set a field with its with method, or use the Java EmulatorInitialState.builder, D121.

Value parameters

committee

the constitutional committee at genesis; None, the default, is a gov state with no committee, spec [ES-13]

committeeHotKeys

the hot key each committee member has authorized at genesis, cold credential to hot credential. Every cold credential must be a member of committee, spec [ES-6a].

constitution

the constitution at genesis; None, the default, is one with an empty anchor and no guardrails script, spec [ES-14]

reserves

the reserves at genesis; the default is the mainnet reserves at epoch 665, spec [ES-7]. No UTxO holds them, spec [ES-7b].

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object EmulatorInitialState

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case class EmulatorPoolRegistration(params: PoolRegistration)

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object EmulatorStakeRegistration

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case class EmulatorStakeRegistration(credential: Credential, rewards: Coin = ..., delegatedTo: Option[PoolKeyHash] = ...)

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class EmulatorState

The entire mutable state of an EmulatorBase, as one immutable value: a chain of real blocks, a mempool, and the config, spec section 6.

The entire mutable state of an EmulatorBase, as one immutable value: a chain of real blocks, a mempool, and the config, spec section 6.

Aggregating it is what lets one state machine serve both platforms, and it is also what makes a transaction land atomically: the ledger state and the bookkeeping that describes it are swapped together, so no reader — and on the JVM no other submitting thread — can observe a UTxO set that has moved on while the applied-transaction log has not caught up. Every transition is a pure function from one state to the next, spec [ST-9].

The readers ledger, context and binaryDatums return the tip snapshot, spec [ST-8], ticked to the current slot, as the node's ticked ledger state, spec [NL-2]. The stored snapshots stay at the slot their ledger state was produced at, so a block forged on an older block, or after a rollback, sees the treasury and the donations of its own slot. The current slot is its own field: withSlot moves it, and it can be ahead of the tip block's slot.

appliedTxLog, appliedTxIndex and appliedTxs are derived, kept for O(1) lookup: the log is the imported log, then the txs of the selected-chain blocks above the log start, spec [TS-5]. The constructor is private, so EmulatorState.initial and the transitions below are the only way to build one, and no caller can hand back a state whose log and caches disagree (EmulatorStateInvariantTest pins it).

The log records one entry per application, while the two derived views are keyed by hash, so they are not always the same size. Applying one transaction twice needs the direct ledger edits (EmulatorBase.addUtxo) to put its inputs back — the ledger rules reject the second submission otherwise — but it is reachable, and then the log holds both applications while the index holds the later one and appliedTxs holds the hash once.

Value parameters

appliedTxIndex

derived: appliedTxLog keyed by transaction hash, holding the latest application of each

appliedTxLog

derived: the imported log, then the txs of the selected chain above logStart

appliedTxs

derived: the distinct hashes in appliedTxLog

blocks

the block tree, by block id

chain

the ids of the selected chain, oldest first. Genesis is not in it.

config

how this emulator behaves as a chain

currentSlot

the current slot, spec [VW-9]

genesisSnapshot

the snapshot of genesis, until it is deeper than k, spec [ST-4]

importedLog

the applied-tx log the state was built with, spec [TS-5]

logStart

the height above which the txs of the selected chain join the log, spec [DE-4]

mempool

the pending txs, oldest first

statuses

the status of each tx that left the mempool or the selected chain: Dropped by revalidation, spec [RV-3], or RolledBack under the Drop policy, spec [OR-4]. Kept, since the entry or the block is gone.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object EmulatorState

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
object NetworkSubmitError

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
sealed trait NetworkSubmitError extends SubmitError

Network-level errors that occur during communication with the node/provider.

Network-level errors that occur during communication with the node/provider.

These errors are typically transient and may be worth retrying.

Attributes

Companion
object
Supertypes
trait SubmitError
class Object
trait Matchable
class Any
Known subtypes
class Banned
class MempoolFull
class RateLimited
Show all
object NodeSubmitError

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
sealed trait NodeSubmitError extends SubmitError

Node validation errors that occur when the transaction is rejected by the ledger.

Node validation errors that occur when the transaction is rejected by the ledger.

These errors indicate the transaction is invalid and needs to be modified before resubmission.

Attributes

Companion
object
Supertypes
trait SubmitError
class Object
trait Matchable
class Any
Known subtypes
case class StakeDistributionEntry(credential: Credential, pool: Option[PoolKeyHash], stake: Coin, rewards: Coin)

One row of EmulatorBase.stakeDistribution.

One row of EmulatorBase.stakeDistribution.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
sealed trait SubmitError

Error returned when submitting a transaction fails.

Error returned when submitting a transaction fails.

Errors are organized into two categories:

  • NetworkSubmitError: Communication/operational errors (connection, auth, rate limits)
  • NodeSubmitError: Transaction validation errors (invalid inputs, expired, script failures)

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Banned
class MempoolFull
class RateLimited
Show all
object SubmitError

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
final class SubmitResult

Outcome of a transaction submission, usable from Java.

Outcome of a transaction submission, usable from Java.

A null-based view over Either[SubmitError, TransactionHash] so non-Scala callers can inspect results without pattern matching — and tests that expect a rejection can assert on getErrorOrNull without try/catch. Scala code should keep using the Either-returning submit/submitSync (or toEither).

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
object SubmitResult

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
enum TransactionStatus

Status of a transaction on the blockchain.

Status of a transaction on the blockchain.

Used by BlockchainReaderTF.checkTransaction and BlockchainProviderTF.pollForConfirmation.

Attributes

Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
sealed trait UtxoFilter

Filter specifies optional refinements to apply after fetching from source.

Filter specifies optional refinements to apply after fetching from source.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class And
class AtInputs
class HasAsset
class HasDatum
class HasDatumHash
class MinLovelace
class Not
class Or
Show all
object UtxoFilter

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
UtxoFilter.type
sealed trait UtxoQuery

A query for UTxOs. Can be a simple query with source/filter/pagination, or a combination of queries using Or.

A query for UTxOs. Can be a simple query with source/filter/pagination, or a combination of queries using Or.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Or
class Simple
object UtxoQuery

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
UtxoQuery.type
enum UtxoQueryError

Errors that can occur when executing a UTxO query

Errors that can occur when executing a UTxO query

Attributes

Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object UtxoQueryMacros

Macro utilities for building UtxoQuery from lambda expressions at compile time.

Macro utilities for building UtxoQuery from lambda expressions at compile time.

This provides a HOAS (Higher-Order Abstract Syntax) embedding that translates lambda expressions to the UtxoQuery ADT.

Example:

import scalus.cardano.node.UtxoQueryMacros.buildQuery

val query = buildQuery { u =>
 u.output.address == myAddress && u.output.value.hasAsset(policyId, assetName)
}
// Compiles to: UtxoQuery(FromAddress(myAddress)) && HasAsset(policyId, assetName)

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
case class UtxoQueryWithReaderTF[F[_]](reader: BlockchainReaderTF[F], query: UtxoQuery)

A query builder that combines a BlockchainReaderTF with a UtxoQuery. Effect-polymorphic — .execute() returns the reader's own F[Either[UtxoQueryError, Utxos]].

A query builder that combines a BlockchainReaderTF with a UtxoQuery. Effect-polymorphic — .execute() returns the reader's own F[Either[UtxoQueryError, Utxos]].

Value parameters

query

The query to execute

reader

The reader to execute the query against

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object UtxoSource

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
UtxoSource.type
sealed trait UtxoSource

Source specifies WHERE to look for UTxOs. This is required - a query must start from a source.

Source specifies WHERE to look for UTxOs. This is required - a query must start from a source.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class And
class FromAddress
class FromAsset
class FromInputs
class Or
Show all
Generated with