Cardano Emulator for JavaScript and TypeScript
The Scalus Emulator – an in-memory Cardano node with full transaction validation and Plutus script execution – is also available as an npm package for JavaScript and TypeScript.
What It Validates
Scalus implements a ledger framework that emulates an in-memory node without consensus. Transactions are validated as if submitted to a real node:
| Validation | Description |
|---|---|
| UTxO Rules | Input existence, double-spend prevention, value conservation |
| Plutus Scripts | V1, V2, V3 script execution with cost model evaluation |
| Staking | Stake registration, delegation, reward withdrawals |
| Native Scripts | Multisig and timelock validation |
| Fees & Collateral | Fee calculation, collateral handling on script failure |
| Signatures | Witness verification for required signers |
The emulator runs the same ledger rules as the JVM version – Phase 1 (transaction structure) and Phase 2 (script execution) validation.
Installation
npm install scalusQuick Start
import { CardanoInfo, Emulator, Utxo, Value } from "scalus";
const alice = "addr_test1vzpwq95z3xyum8vqndgdd9mdnmafh3djcxnc6jemlgdmswcve6tkw";
// A network is a slot configuration and a set of protocol parameters together,
// so the emulator cannot validate against one network's parameters while doing
// slot arithmetic for another.
const emulator = Emulator.create(CardanoInfo.preview(), {
utxos: [new Utxo("00".repeat(32), 0, alice, Value.ada(1000n))],
});
// Build the transaction with whatever builder you already use, then submit the
// bytes it produced.
const result = emulator.submitTx(txCborBytes);
if (result.isSuccess) {
console.log(`accepted: ${result.txHash}`);
} else {
console.log(`rejected by ${result.errorRule}: ${result.error}`);
console.log(result.logs.join("\n")); // empty unless a Plutus script traced
}
// Queries return objects, not CBOR.
const [utxo] = emulator.getUtxos({ address: alice });
console.log(utxo.value.coin); // 1000000000nCreating an Emulator
Emulator.create takes a CardanoInfo – the network, its slot configuration and its protocol
parameters as one coherent triple – and, optionally, the state to start from.
CardanoInfo.mainnet() // mainnet parameters and slot configuration
CardanoInfo.preprod() // preprod testnet
CardanoInfo.preview() // preview testnet
// Yaci DevKit, a private testnet, or anything else with its own timing:
const devnet = CardanoInfo.custom(
"testnet",
new SlotConfig(zeroTime, zeroSlot, slotLength, epochLength, zeroEpoch),
params,
);Every field of the options object is optional:
const emulator = Emulator.create(CardanoInfo.preview(), {
utxos: [new Utxo(txHash, 0, alice, Value.ada(1000n))],
slot: 1_000_000, // defaults to the slot containing Date.now()
stakeRegistrations: [
{ credentialType: "key", credentialHash: keyHashHex, rewards: 0n },
],
poolRegistrations: [{ params: poolRegistrationCertificateCbor }],
drepRegistrations: [
{ credentialType: "script", credentialHash: scriptHashHex, deposit: 500_000_000n },
],
datums: [{ hash: datumHashHex, datum: datumCborHex }],
});new Emulator(utxosCbor, slotConfig) is deprecated since 1.2.0, and 1.4.0 removes
Emulator.withState and Emulator.withAddresses. They take protocol parameters from the slot
configuration alone, so a SlotConfig.preview emulator validated transactions against
mainnet’s parameters. Emulator.create is the fix.
Querying UTxOs
getUtxos() returns every UTxO; getUtxos(filter) narrows it. Filtering happens inside the
ledger, so no object is built for a row the filter drops.
emulator.getUtxos(); // everything
emulator.getUtxos({ address: alice }); // one address
emulator.getUtxos({ paymentCredential: keyHashHex }); // any address with this payment part
emulator.getUtxos({ unit: policyId + assetNameHex }); // holders of one asset
emulator.getUtxos({ minLovelace: 5_000_000n, limit: 10 });
emulator.getUtxos({ outRefs: [{ txHash, outputIndex: 0 }] });Every field given is ANDed together. outRefs is the exception: it matches any of the references
given, which is what a “resolve these inputs” query needs.
A field the filter does not declare throws. TypeScript rejects { adress: alice } at compile time;
in plain JavaScript it used to be ignored, and a filter with nothing recognised in it matches
everything, so a misspelt key handed back the whole ledger as though it were one wallet’s.
A returned Utxo carries the ledger’s own input and output, so it can be handed straight back to
evaluateTx or addUtxo with no encoding step:
const [utxo] = emulator.getUtxos({ address: alice });
utxo.txHash; // hex
utxo.outputIndex; // number
utxo.address; // bech32
utxo.value.coin; // bigint lovelace
utxo.value.assets; // Asset[], each with policyId, assetName, quantity and unit
utxo.datumHash; // string | undefined
utxo.inlineDatum; // Uint8Array | undefined
utxo.scriptRef; // Uint8Array | undefinedUtxo, Value, Asset, ProtocolParams and CardanoInfo expose their fields through
accessors, which live on the prototype. JSON.stringify, object spread and expect(...).toEqual
therefore all see an empty object. Call toObject() and assert on that instead.
Values and assets
Value.ada(10n); // 10 ada, as lovelace
new Value(2_000_000n, [asset]); // lovelace plus native assets
value.plus(other); // neither operand is modified
const asset = new Asset(policyIdHex, assetNameHex, 5n);
asset.unit; // policyIdHex + assetNameHex, the form lucid and MeshJS both call a "unit"Protocol parameters
const params = emulator.getProtocolParameters();
params.txFeePerByte; // number
params.utxoCostPerByte; // bigint
params.maxTxExecutionSteps; // bigint
params.costModels.PlutusV3; // number[], by language rather than by position
// For an adapter that already parses Blockfrost's shape:
const json = params.toBlockfrostJson();
const roundTripped = ProtocolParams.fromBlockfrostJson(json);Quantities that can exceed Number.MAX_SAFE_INTEGER – every deposit, utxoCostPerByte and the
execution-unit maxima – are bigint. Fee rates, sizes, percentages and counts are number, and
so are slots.
Evaluating scripts against the ledger
evaluateTx runs every Plutus script a transaction triggers, resolving its inputs against this
emulator’s UTxO set, slot config, cost models and protocol version. Nothing has to be passed in,
so nothing can be passed in wrongly.
for (const redeemer of emulator.evaluateTx(txCborBytes)) {
console.log(`${redeemer.tag}[${redeemer.index}]:`,
redeemer.budget.memory, "mem,", redeemer.budget.steps, "steps");
}
// Inputs the emulator does not hold yet - the outputs of a transaction you have
// not submitted, typically - go in the second argument.
emulator.evaluateTx(txCborBytes, [new Utxo(txHash, 0, scriptAddress, Value.ada(5n))]);A failing script throws PlutusScriptEvaluationError, which extends Error and carries the
script’s trace logs:
try {
emulator.evaluateTx(txCborBytes);
} catch (e) {
if (e instanceof PlutusScriptEvaluationError) {
console.log(e.message, e.logs);
}
}Time
emulator.getSlot(); // current slot
emulator.setSlot(1000); // jump to an absolute slot, forwards or backwards
emulator.tick(10); // advance by 10 slots
emulator.getTime(); // POSIX ms at which the current slot starts
emulator.setTime(Date.now());
SlotConfig.mainnet;
SlotConfig.preview;
SlotConfig.preprod;
const custom = new SlotConfig(zeroTime, zeroSlot, slotLength);No blocks are produced between two slots: validity intervals and time-aware scripts see the difference. Crossing an epoch boundary runs the epoch rules: pool retirement, proposal expiry and refunds, rewards and enactment.
Blocks, mempool and forks
The emulator behaves like a small Cardano node: a submitted transaction waits in a mempool, a
block makes it visible, and a fork can roll it back. blockProduction picks the preset:
// The default: every submitTx forges a block at once, so every example above still holds.
const instant = Emulator.create(CardanoInfo.preview(), { utxos });
// Only produceBlock() or awaitTx forges a block; a submitted transaction waits in the mempool.
const manual = Emulator.create(CardanoInfo.preview(), { utxos, blockProduction: "manual" });awaitTx ("produceBlock", the default, or "waitOnly"), orphanTxs ("returnToMempool", the
default, or "drop") and securityParam (k, default 2160) are options of the same call.
The delay case
With blockProduction: "manual", a query keeps showing the old state until produceBlock() (or
awaitTx) makes the submitted transaction’s outputs real:
const result = manual.submitTx(txCborBytes);
manual.getUtxos({ address: bob }); // []: still pending
manual.getTransactionStatus(result.txHash!); // "Pending"
manual.produceBlock();
manual.getUtxos({ address: bob }); // the payment is there
manual.getTransactionStatus(result.txHash!); // "Confirmed"A Lucid Evolution provider’s awaitTx forges for you, the way this adapter’s does:
async awaitTx(txHash: string): Promise<boolean> {
return this.emulator.awaitTx(txHash); // forges blocks while pending, then reports confirmed
}Tx status
getTxStatus(hash) returns { status, depth?, point?, reason?, error? }, where status is one
of "Pending" | "Confirmed" | "Dropped" | "RolledBack" | "NotFound". getTransactionStatus(hash)
is just the status field.
Views
getUtxos(filter, view) reads something other than the tip – the selected chain’s last block,
what a real provider shows:
manual.getUtxos({ address: bob }, "tip"); // the chain; same as getUtxos({ address: bob })
manual.getUtxos({ address: bob }, "mempool"); // the chain plus the pending transactions
manual.getUtxos({ address: bob }, { stable: 2 }); // the block two deep; the tip is depth 1An unrecognised view throws TypeError. A stable depth below 1, above the tip height plus 1
(genesis), or deeper than the securityParam + 1 blocks the emulator keeps throws RangeError.
A rival double spend and rollback
const p1 = manual.produceBlock();
manual.submitTx(txACbor);
manual.submitTx(txBCbor);
const p2 = manual.produceBlock(); // A and B are confirmed in p2
// A rival that double-spends B's input, forged on the branch at p1 instead of the tip.
const r2 = manual.produceBlockOn(p1, [rivalTxCbor]);
manual.getTip().height; // still 2: the rival branch (height 2) only ties p2's height
const r3 = manual.produceBlockOn(r2.point!, []); // the rival branch is now longer
manual.getTip().height; // 3: the emulator switched
manual.rollback(1); // removes the last block; its transactions follow orphanTxs
manual.rollback(0); // { isSuccess: false, errorKind: "NotPositive", ... }produceBlockOn and rollback return { isSuccess, point? } on success, or { isSuccess: false, error, errorKind } otherwise, where errorKind is the stable name to branch on and error is a
sentence for a person, such as "rollback(0): n must be at least 1".
With blockProduction: "instant" and the default orphanTxs: "returnToMempool", rollback(1) at
an unchanged slot changes nothing you can see: the removed block’s transactions return to the
mempool, and the emulator forges them at once into the same block, with the same hash. To see a
rollback, use blockProduction: "manual", use orphanTxs: "drop", or move the slot first:
const instant = Emulator.create(CardanoInfo.preview(), { utxos });
instant.submitTx(txCborBytes);
instant.rollback(1); // the same block again, at the same point
instant.tick(1);
instant.rollback(1); // a new block, one slot later, with the same transactionshasTx(hash) is true only for a confirmed transaction, one in a block on the chain. A pending
transaction reads false; use getTxStatus to tell it from an unknown one.
Documented deviations from a real node
- With
blockProduction: "instant", two blocks can share a slot: severalsubmitTxcalls at the same slot each get their own block. - With
blockProduction: "instant", moving the slot backward withsetSlotbefore an epoch boundary no block has crossed restores the donations that boundary moved into the treasury – the boundary never happened on the stored chain. - A forged block carries fixed placeholder bytes for the consensus fields a node checks; nothing in the emulator verifies them.
- When several branches are longer than the current chain, chain selection picks the tallest, then the lowest block hash, where a real node breaks the tie by VRF.
Editing the ledger directly
emulator.addUtxo(utxo); // seed a UTxO, skipping validation
emulator.removeUtxo({ txHash, outputIndex: 0 }); // take one away
const checkpoint = emulator.snapshot(); // an independent copy of everythingsnapshot copies the UTxOs, registrations and rewards, the datum store, the accepted
transactions and the current slot, so one expensive setup can branch into several scenarios.
Stake and governance state
Stake queries take a bech32 reward address, so a key credential and a script credential are told apart by the address itself:
emulator.getStakeReward("stake_test1..."); // bigint | undefined
emulator.getDelegation("stake_test1..."); // { poolId?, rewards }
emulator.getStakeDistribution(); // live stake per registered credentialUsing the emulator as a transaction-builder backend
Both MeshJS and lucid-evolution take a provider object. The emulator answers what either of them asks, so the adapter is field renaming: no CBOR codec, no protocol-parameter table and no cost model of its own.
lucid-evolution
import {
Lucid,
type Credential,
type Delegation,
type EvalRedeemer,
type OutRef,
type ProtocolParameters,
type Provider,
type RedeemerTag,
type UTxO,
} from "@lucid-evolution/lucid";
import type { Emulator, Utxo } from "scalus";
// The mechanical conversions the adapter carries. `__tests__/lucid-provider.ts` has all four in
// full; each is field renaming, and the two UTxO ones refuse the shapes the two sides do not
// share rather than dropping a datum or a reference script in silence.
declare function hexToBytes(hex: string): Uint8Array;
declare function bytesToHex(bytes: Uint8Array): string;
declare function toLucidUtxo(utxo: Utxo): UTxO;
declare function fromLucidUtxo(utxo: UTxO): Utxo;
// `{ Spend: "spend", Mint: "mint", Cert: "publish", Reward: "withdraw", ... }`
declare const LUCID_TAG: Record<string, RedeemerTag>;
class EmulatorProvider implements Provider {
constructor(readonly emulator: Emulator) {}
async getProtocolParameters(): Promise<ProtocolParameters> {
const p = this.emulator.getProtocolParameters();
return {
protocolMajorVersion: p.protocolMajorVersion,
minFeeA: p.txFeePerByte,
minFeeB: p.txFeeFixed,
maxTxSize: p.maxTxSize,
maxValSize: p.maxValueSize,
keyDeposit: p.stakeAddressDeposit,
poolDeposit: p.stakePoolDeposit,
drepDeposit: p.dRepDeposit,
govActionDeposit: p.govActionDeposit,
priceMem: p.priceMemory,
priceStep: p.priceSteps,
maxTxExMem: p.maxTxExecutionMemory,
maxTxExSteps: p.maxTxExecutionSteps,
coinsPerUtxoByte: p.utxoCostPerByte,
collateralPercentage: p.collateralPercentage,
maxCollateralInputs: p.maxCollateralInputs,
minFeeRefScriptCostPerByte: p.minFeeRefScriptCostPerByte,
costModels: p.costModels,
};
}
async getUtxos(addressOrCredential: string | Credential): Promise<UTxO[]> {
const filter = typeof addressOrCredential === "string"
? { address: addressOrCredential }
: { paymentCredential: addressOrCredential.hash };
return this.emulator.getUtxos(filter).map(toLucidUtxo);
}
async submitTx(txHex: string): Promise<string> {
const result = this.emulator.submitTx(hexToBytes(txHex));
if (!result.isSuccess) throw new Error(`${result.errorRule}: ${result.error}`);
return result.txHash!; // `txHash` is present exactly when `isSuccess` is true
}
// The rest is one emulator call each.
async getUtxosWithUnit(
addressOrCredential: string | Credential,
unit: string,
): Promise<UTxO[]> {
const filter = typeof addressOrCredential === "string"
? { address: addressOrCredential, unit }
: { paymentCredential: addressOrCredential.hash, unit };
return this.emulator.getUtxos(filter).map(toLucidUtxo);
}
async getUtxoByUnit(unit: string): Promise<UTxO> {
const found = this.emulator.getUtxos({ unit, limit: 2 });
if (found.length !== 1) throw new Error(`${found.length} UTxOs hold ${unit}, expected 1`);
return toLucidUtxo(found[0]!);
}
async getUtxosByOutRef(outRefs: OutRef[]): Promise<UTxO[]> {
return this.emulator.getUtxos({ outRefs }).map(toLucidUtxo);
}
async getDelegation(rewardAddress: string): Promise<Delegation> {
const d = this.emulator.getDelegation(rewardAddress);
return { poolId: d.poolId ?? null, rewards: d.rewards };
}
async getDatum(datumHash: string): Promise<string> {
const datum = this.emulator.getDatum(datumHash);
if (datum === undefined) throw new Error(`no datum for hash ${datumHash}`);
return bytesToHex(datum);
}
async awaitTx(txHash: string): Promise<boolean> {
// Forges blocks for a pending transaction under `blockProduction: "manual"`; with the
// default `"instant"` it only confirms what is already there.
return this.emulator.awaitTx(txHash);
}
async evaluateTx(txHex: string, additionalUTxOs: UTxO[] = []): Promise<EvalRedeemer[]> {
return this.emulator
.evaluateTx(hexToBytes(txHex), additionalUTxOs.map(fromLucidUtxo))
.map((r) => ({
redeemer_tag: LUCID_TAG[r.tag]!,
redeemer_index: r.index,
ex_units: { mem: Number(r.budget.memory), steps: Number(r.budget.steps) },
}));
}
}
const lucid = await Lucid(new EmulatorProvider(emulator), "Preview");
lucid.selectWallet.fromSeed(seed);
const tx = await lucid.newTx().pay.ToAddress(bob, { lovelace: 25_000_000n }).complete();
const txHash = await (await tx.sign.withWallet().complete()).submit();
emulator.getUtxos({ address: bob }); // the payment is on the ledgerMeshJS
IFetcher, ISubmitter and IEvaluator map just as directly. castProtocol fills in the
parameters a transaction build never reads:
import { MeshTxBuilder, MeshWallet, castProtocol } from "@meshsdk/core";
// Two methods from the body of a class EmulatorProvider
// implements IFetcher, ISubmitter, IEvaluator:
async fetchAddressUTxOs(address: string, asset?: string) {
const filter = asset === undefined ? { address } : { address, unit: asset };
return this.emulator.getUtxos(filter).map(toMeshUtxo);
}
async evaluateTx(txHex: string, additionalUtxos = []) {
return this.emulator
.evaluateTx(hexToBytes(txHex), additionalUtxos.map(fromMeshUtxo))
.map((r) => ({
tag: MESH_TAG[r.tag],
index: r.index,
budget: { mem: Number(r.budget.memory), steps: Number(r.budget.steps) },
}));
}The complete, runnable lucid-evolution adapter lives at __tests__/lucid-provider.ts; the Mesh
one is inline in __tests__/provider-mesh.test.ts. __tests__/provider-lucid.test.ts and
__tests__/emulator-chain.test.ts drive the lucid-evolution adapter, each one building, signing
and submitting a real transaction against the emulator, the second one through a "manual"
emulator with awaitTx.
Script evaluation without an emulator
evalPlutusScripts evaluates a transaction’s scripts with everything passed in explicitly. Prefer
emulator.evaluateTx when you have an emulator: it takes the UTxOs, slot config, cost models and
protocol version from the ledger the transaction is going to.
import { evalPlutusScripts, SlotConfig } from "scalus";
const redeemers = evalPlutusScripts(
txCborBytes,
utxoCborBytes,
SlotConfig.preview,
costModels, // [v1CostModel, v2CostModel, v3CostModel]
);Evaluating one script
evaluator.evaluateScript(script, args, options) applies CBOR-encoded Data arguments to a
script, runs it and returns an EvaluationResult. It builds the machine from options on every
call. To evaluate many scripts, build a PlutusVM once. To evaluate one script many times, also
decode it once with uplc.decodeProgram:
import { EvaluationOptions, PlutusVM, uplc } from "scalus";
const vm = new PlutusVM(EvaluationOptions.mainnet("PlutusV3")); // the machine, built once
const program = uplc.decodeProgram(scriptHex); // the script, decoded once
for (const [datum, redeemer, context] of cases) {
const result = vm.evaluateScript(program, [datum, redeemer, context]);
console.log(result.isSuccess, result.budget.steps, result.budget.memory);
}vm.evaluateScript also takes the script as hex or bytes, as evaluator.evaluateScript does. A
maxBudget in the options applies to every call of that PlutusVM.
Profiling a script
evaluateScript(doubleCborHex) runs a single fully-applied script (for example the output of applyDataArgToScript) and returns an EvaluationResult with isSuccess, budget, and logs. evaluateScriptProfile(doubleCborHex) does the same but also collects CEK machine profiling data, exposed on the result as profileJson – per-source-location and per-builtin cost plus the transition edges. It is undefined for the plain evaluateScript (which has zero profiling overhead).
import { evaluateScriptProfile } from "scalus";
// `applied` is a fully-applied script, e.g. from applyDataArgToScript(...)
const result = evaluateScriptProfile(applied);
console.log(`success=${result.isSuccess}, cpu=${result.budget.steps}, mem=${result.budget.memory}`);
if (result.profileJson) {
const profile = JSON.parse(result.profileJson);
console.log(`total cpu: ${profile.totalBudget.cpu}`);
// profile.bySourceLocation / profile.byFunction / profile.transitions
}Only the profiling data is available from JavaScript. The interactive HTML report (sortable
tables, hot paths/edges, annotated source) is rendered by the Scala/JVM
ProfileFormatter – it is deliberately kept out of
scalus.js so the transaction-builder bundle stays small. Feed profileJson into your own tooling,
or run the profiler on the JVM to get the HTML.
Conformance
Scalus’s JavaScript build runs the Plutus conformance suite in CI, with the corpus of the plutus-core version that the latest production cardano-node runs: every UPLC evaluation case, in both its textual and flat-encoded form, none skipped. For each program the reference evaluates successfully, both the resulting term and the exact CPU and memory budget are asserted against the reference implementation. For the programs the reference rejects – it fails to evaluate, parse or decode them – the corpus records no term or budget, so the assertion there is that Scalus rejects them the same way.
The evaluator that prices your transaction here is the same code the emulator runs in phase 2, so
evaluateTx and submitTx cannot disagree about cost – which is not true of a setup that pairs a
separate wasm evaluator with a hand-written emulator.
See Also
- Emulator (JVM) – Full Scala API documentation
- Multiplatform – Platform support overview
scalusnpm package – Full JavaScript/TypeScript API