Skip to content
Skills Library
Programming · Testing

local-development

/local-development

Use when developing or testing Scalus smart contracts with the local Emulator and TxBuilder. Covers how to create an Emulator provider, submit transactions, and test negative validator cases.

Repository
scalus ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when developing or testing Scalus smart contracts with the local Emulator and TxBuilder. Covers how to create an Emulator provider, submit transactions, and test negative validator cases.

Original author description

Use when developing or testing Scalus smart contracts with the local Emulator and TxBuilder. Covers how to create an Emulator provider, submit transactions, and test negative validator cases.

How it works

  1. Overview
  2. File structure for testing a validator
  3. Submitting a transaction
  4. Testing negative cases (validator expected to fail)
  5. Ledger rules the Emulator checks (Scalus 1.4.0 or newer)
Original SKILL.md headings · 147 lines, 569 words
SKILL.md preview
---
name: local-development
description: Use when developing or testing Scalus smart contracts with the local Emulator and TxBuilder. Covers how to create an Emulator provider, submit transactions, and test negative validator cases.
---

## Overview

When developing on-chain code, the Emulator is a local, single-node no-consensus implementation of
the Cardano ledger. It includes phase 1 & 2 validation.

## File structure for testing a validator

Four files are typically involved:

- **Validator** — the on-chain logic (e.g. `MyValidator.scala`)
- **Contract** — compiles the validator into a `PlutusV3` value (e.g. `MyContract.scala`)
- **Transactions** — uses `TxBuilder` to create validator-specific transactions (e.g. `MyTransactions.scala`)
- **Test** — wires everything together using the Emulator (e.g. `MyValidatorTest.scala`)

### Contract file

```scala
private given Options = Options.release
lazy val MyContract = PlutusV3.compile(MyValidator.validate)
```

For parameterized validators, apply the parameter after compilation:

```scala
val applied = MyContract.withErrorTraces(myParam)   // applies param + enables traces
val script  = Script.PlutusV3(applied.program.cborByteString)
val scriptAddress = applied.address(network)
```

### Transactions file

`CardanoInfo` (aliased as `env`) carries network/protocol config and is provided by `ScalusTest`
via `TestUtil.testEnvironment`. Spending transactions need an evaluator.
`evaluator = PlutusScriptEvaluator.constMaxBudget(env)` skips script evaluation while the builder
balances the transaction. The Emulator still runs the scripts when you submit.

```scala
case class MyTransactions(
    env: CardanoInfo,
    evaluator: PlutusScriptEvaluator,
    contract: PlutusV3[Data => Unit]  
) {
    def script: Script.PlutusV3 = contract.script
    val scriptAddress: Address  = contract.address(env.network)

    // Necessary to have funds locked behind the contract under test
    def sendToScript(utxos: Utxos, datum: MyDatum, sponsor: Address, signer: TransactionSigner): Transaction =
        TxBuilder(env)
            .spend(Utxo(utxos.head))
            .payTo(scriptAddress, Value.ada(10), datum) // or pass the ada amount in a parameter
            .complete(availableUtxos = utxos, sponsor = sponsor)
            .sign(signer)
            .transaction

    def spendFromScript(
        utxos: Utxos,
        scriptUtxo: Utxo,
        redeemer: MyRedeemer,
        signerPkh: AddrKeyHash,
        sponsor: Address,
        signer: TransactionSigner
    ): Transaction =
        TxBuilder(env, evaluator)
            .spend(scriptUtxo, redeemer, script)
            .spend(Utxo(utxos.head))
            .payTo(sponsor, scriptUtxo.output.value)
            .complete(availableUtxos = utxos, sponsor = sponsor)
            .sign(signer)
            .transaction
}
```

### Test file

```scala
// ScalusTest provides: PlutusVM, Alice/Bob/Eve/Charles/Dave parties (via Party.*),
//                       cardanoEnv, genesisHash, assertScriptFail, and ArbitraryInstances
class MyValidatorTest extends AnyFunSuite, ScalusTest {
    import MyValidatorTest.{*, given}

    test("valid redeemer succeeds") {
        val provider = createProvider()
        // ... build and submit transactions
    }
}

object MyValidatorTest extends ScalusTest {
    private given env: CardanoInfo = TestUtil.testEnvironment
    private val compiledContract   = MyContract.withErrorTraces
    private val scriptAddress      = compiledContract.address(env.network)

    private val txCreator = MyTransactions(
        env       = env,
        evaluator = PlutusScriptEvaluator.constMaxBudget(env),
        contract  = compiledContract
    )

    private def createProvider(): Emulator = {
        // genesisHash is a zero-hash sentinel used as the "genesis" input
        val initialUtxos = Map(
            Input(genesisHash, 0) -> Output(Alice.address, Value.ada(5000)),
            Input(genesisHash, 1) -> Output(Alice.address, Value.ada(5000)),
            Input(genesisHash, 2) -> Output(Bob.address,   Value.ada(5000)),
        )
        Emulator(initialUtxos = initialUtxos, initialContext = Context.testMainnet())
    }
}
```

## Submitting a transaction

```scala
provider.submit(tx).await() match {
    case Left(value) => fail(s"Transaction failed: $value")
    case Right(_)    => ()
}
```

## Testing negative cases (validator expected to fail)

Override `PlutusScriptEvaluator` so `TxBuilder` won't reject the transaction during construction:

```scala
val evaluator = PlutusScriptEvaluator.constMaxBudget(env)

TxBuilder(env, evaluator)
    .spend(scriptUtxo, badRedeemer, script, Set(signerPkh))
    ...
    .complete(...) // or `build`
    .sign(signer)
    .transaction
// Then submit to the Emulator and assert Left(SubmitError.ScriptFailure(...))
```

## Ledger rules the Emulator checks (Scalus 1.4.0 or newer)

The Emulator rejects what a node rejects. A test that sets up stake or governance state hits these:

- A withdrawal from a key-hash reward account needs a DRep delegation first, from protocol
  version 10: `TxBuilder.delegateVoteToDRep(stakeAddress, DRep.AlwaysAbstain)`. Script-hash
  accounts are exempt, so the withdraw-zero pattern needs no DRep.
- A delegation needs a registered pool or DRep. Register it in an earlier transaction first.
- A withdrawal subtracts from the balance; a drained account stays registered with balance 0.
- A UTxO added with `provider.addUtxo(input, output)` that holds only a datum hash: call
  `provider.addDatum(datum)` so the Emulator finds the datum.

Versions

The database has no other skills named local-development.

Database snapshot: 13.11.2026 · package version 1c3241c81935 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100contract-test
    Guide for testing Scalus smart contracts. Use when writing unit, property, budget, or Emulator tests for Cardano validators.
  • 100contract
    Guide for developing Scalus smart contracts. Use when writing or modifying Cardano validators in Scala 3 with Scalus.
  • 96start-emulator
    Start an Android emulator. Use when you need to launch an AVD for testing.
  • 100floci-dev-assistant
    Expert guide for developing with Floci — the Java/Quarkus-based open-source local AWS emulator. Use this skill whenever someone asks about adding a new AWS service to Floci, implementing AWS protocol-compatible handlers, writing integration or unit tests for Floci services,…
  • 96stop-emulator
    Stop a running Android emulator. Use when you need to shut down an AVD.
  • 100emulator
    Use to run and inspect the Blokada Android app on a Google Developer Device Platform emulator, with screenshots and UI dumps, from a Claude Code cloud session or a local machine without an Android emulator. Trigger when a change under common/ affects UI and should be checked on…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.