Ledger Rules Reference

This page catalogs all built-in validators and mutators in the Scalus Ledger Rules Framework. For architecture, composition, and customization patterns, see the Framework overview.

Validating and updating UTxO state (EraRule UTXOW)

The following diagram shows how Scalus validators and mutators map to the Conway-era UTXOW state transition in the Cardano ledger:

Validators

Input Validation

• AllInputsMustBeInUtxoValidator — Ensures all transaction inputs (spending, collateral, and reference inputs) exist in the UTxO set
• EmptyInputsValidator — Verifies that the transaction has at least one input
• InputsAndReferenceInputsDisjointValidator — Ensures regular inputs and reference inputs don’t overlap

Value and Balance Validation

• ValueNotConservedUTxOValidator — Validates that the total value consumed equals the total value produced (conservation of value)
• OutputsHaveNotEnoughCoinsValidator — Checks that all outputs meet the minimum ADA requirement
• OutputsHaveTooBigValueStorageSizeValidator — Validates that output values don’t exceed maximum storage size limits
• OutputBootAddrAttrsSizeValidator — Ensures bootstrap address attributes don’t exceed size limits

Fee and Collateral Validation

• FeesOkValidator — Comprehensive fee validation including minimum fee check, collateral requirements, and collateral input validation
• ExUnitsTooBigValidator — Validates that execution units (memory and CPU steps) don’t exceed protocol limits
• TooManyCollateralInputsValidator — Ensures the number of collateral inputs doesn’t exceed the maximum allowed

Script Validation

• NativeScriptsValidator — Validates native scripts in the transaction
• ScriptsWellFormedValidator — Ensures all scripts are properly formed and valid
• MissingOrExtraScriptHashesValidator — Verifies that all required script hashes are present and no extra ones exist
• MissingRequiredDatumsValidator — Checks that all required datums are provided in the transaction
• ExactSetOfRedeemersValidator — Validates that the set of redeemers matches exactly what’s needed

Witness Validation

• VerifiedSignaturesInWitnessesValidator — Verifies that all required cryptographic signatures are present and valid
• MissingKeyHashesValidator — Ensures all required key hashes for signing are provided

Network and Metadata Validation

• WrongNetworkValidator — Validates that transaction addresses match the expected network
• WrongNetworkWithdrawalValidator — Checks withdrawal addresses match the network
• WrongNetworkInTxBodyValidator — Validates network consistency in transaction body
• MetadataValidator — Validates transaction metadata format and size

Stake and Certificate Validation

• CertsValidator — Conway CERTS rule: validates certificate sequences in the transaction
• StakeCertificatesValidator — Conway DELEG rule: validates stake registration, deregistration, and delegation certificates
• StakePoolCertificatesValidator — Conway POOL rule: validates stake pool registration and retirement certificates

Protocol and Transaction Validation

• ProtocolParamsViewHashesMatchValidator — Ensures protocol parameter view hashes match expected values
• TransactionSizeValidator — Validates that transaction size doesn’t exceed maximum limits
• OutsideValidityIntervalValidator — Checks that the transaction is within its validity interval (time-to-live)
• OutsideForecastValidator — Validates forecast-related constraints for transaction validity

Mutators

Script Execution

• PlutusScriptsTransactionMutator — Evaluates Plutus scripts (V1/V2/V3), processes collateral on script failure, and updates the UTxO set (adds outputs, removes consumed inputs)

Stake Delegation

• StakeCertificatesMutator — Processes stake delegation certificates (registration, deregistration, delegation) and updates the delegation state

Composition

• CardanoMutator — Top-level orchestrator that runs all DefaultValidators.all then DefaultMutators.all in sequence

Conway Rule Mapping

The following table maps Cardano ledger rules (from cardano-ledger ) to their Scalus implementations:

See Also

• Ledger Rules Framework — Architecture, composition, and rule customization
• Emulator — In-memory node using these rules for fast testing
• Yaci DevKit — Docker-based devnet with real Cardano node
• Protocol Parameters — Network configuration used by validators