docs
API
Generated with
docs/scalus/scalus.cardano/scalus.cardano.node

scalus.cardano.node

package scalus.cardano.node

Members list

Packages

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 emulator slot at the time of application

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(initialUtxos: Utxos = ..., initialContext: Context = ..., val validators: Iterable[Validator] = ..., val mutators: Iterable[Mutator] = ..., initialCertState: CertState = ..., initialDatums: Map[DataHash, Data] = ..., initialAppliedTxLog: Vector[AppliedTx] = ...) 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
case class EmulatorInitialState(utxos: Utxos = ..., stakeRegistrations: Seq[EmulatorStakeRegistration] = ..., poolRegistrations: Seq[EmulatorPoolRegistration] = ..., drepRegistrations: Seq[EmulatorDRepRegistration] = ..., datums: Map[DataHash, Data] = ...)

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.

The entire mutable state of an EmulatorBase, as one immutable value.

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.

appliedTxIndex and appliedTxs are derived from appliedTxLog, kept for O(1) lookup. Nothing outside this class writes them: 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. Every hash in the log is in both derived views and vice versa; only the multiplicity differs.

Value parameters

appliedTxIndex

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

appliedTxLog

applied transactions in application order, oldest first — one entry per application

appliedTxs

derived: the distinct hashes in appliedTxLog

context

the validation context, carrying the current slot, protocol parameters and evaluator mode

datums

every datum this emulator has seen, by hash

ledger

the ledger state proper — the UTxO set and the certificate state

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