Tutorial
Basic workflow
The basic workflow is to write a Scala program and then compile it to a Plutus script, similar to how PlutuxTx works.
You can store the Plutus script in a *.plutus
file and use it with the Cardano CLI.
Or use one of the Java/JavaScript libraries to construct transactions with the script.
This example shows how to use the cardano-client-lib to send transactions.
You write a script using a small subset of Scala,
which is then compiled to a Scalus Intermediate Representation (SIR) with compile
function.
The SIR can be pretty-printed and reviewed.
The SIR is then compiled to Untyped Plutus Core (UPLC) that can be executed on the Cardano blockchain.
Simple validator
import scalus.Compiler.compile
import scalus.*
import scalus.builtin.Data
import scalus.uplc.Program
// Compile Scala code to Scalus Intermediate Representation (SIR)
val validator = compile {
// A simple validator that always succeeds
(context: Data) => ()
}
// validator: SIR = LamAbs(name = "context", term = Const(const = Unit))
// pretty print the SIR
validator.show
// res0: String = "{λ context -> () }"
// convert the SIR to UPLC and pretty print it with colorized syntax highlighting
validator.toUplc().showHighlighted
// res1: String = """(lam context
// (con unit ()))"""
// get a double CBOR encoded optimized UPLC program as HEX formatted string
Program(version = (1, 1, 0), term = validator.toUplcOptimized()).doubleCborHex
// res2: String = "46450101002499"
Constans and primitives
Plutus supports the following primitive types: unit
, bool
, integer
, bytestring
, string
, data
, list
, pair
.
Those types are represented in Scalus as Unit
, Boolean
, BigInt
, ByteString
, String
, Data
, List
, Pair
respectively.
We use Scala native types to represent Unit
, Boolean
, BigInt
, and String
.
Here is an example of how to define constants and use built-in types.
import scalus.Compiler.compile
import scalus.*
import scalus.builtin.*
import scalus.builtin.ByteString.given
val constants = compile {
val unit = () // unit type
val bool = true || false // boolean type
val int = BigInt(123) // integer type
val bigint = BigInt("12345678901234567890") // large integer value
val implicitBigIng: BigInt = 123
val emptyByteString = ByteString.empty
val byteString = ByteString.fromHex("deadbeef")
val byteStringUtf8 = ByteString.fromString("hello") // from utf8 encoded string
val byteString2 = hex"deadbeef" // ByteString from hex string
val string = "Scalus Rocks!" // string type
val emptyList = List.empty[BigInt] // empty list
val list = List[BigInt](1, 2, 3) // list of integers
val pair = Pair(true, ()) // pair of boolean and unit
}
Builtin Functions
import scalus.builtin.*
import scalus.builtin.ByteString.given
import scalus.prelude.Prelude.{*, given}
compile {
// See scalus.builtin.Builtins for what is available
val data = Builtins.iData(123)
val eqData = data == Builtins.iData(123) || data != Builtins.iData(123)
val eq = Builtins.equalsByteString(hex"deadbeef", ByteString.empty)
val byteStringEq = hex"deadbeef" == ByteString.empty || hex"deadbeef" != ByteString.empty
val stringEq = "deadbeef" == "" || "deadbeef" != ""
val a = BigInt(1)
val sum = a + 1 - a * 3 / 4 // arithmetic operators
val intEquality = a == sum || a != sum
val bool = !true || (false == true) != false && true // boolean operators
val equals = a === sum // comparison operators
}
Data types
You can define your own data types using Scala case classes and enums.
import scalus.builtin.ByteString
import scalus.prelude.Prelude.{*, given}
case class Account(hash: ByteString, balance: BigInt)
enum State:
case Empty
case Active(account: Account)
import State.*
compile {
// Tuple2 literals are supported
val tuple = (true, BigInt(123))
val empty = State.Empty // simple constructor
// Use `new` to create an instance
val account = new Account(ByteString.empty, tuple._2) // access tuple fields
val active: State = new State.Active(account)
val hash = account.hash // access case class fields
// A simple pattern matching is supported
// no guards, no type ascriptions.
// Inner matches can be done only on single constructor case classes
// Wildcard patterns are supported
active match
case Empty => true
case Active(account @ Account(_, balance)) => balance == BigInt(123)
// all cases must be covered or there must be a default case
val isEmpty = active match
case Empty => true
case _ => false
}
Control flow
import scalus.prelude.Prelude.{*, given}
compile {
val a = BigInt(1)
// if-then-else
if a == BigInt(2) then ()
// throwing an exception compiles to Plutus ERROR,
// which aborts the evaluation of the script
// the exception message can be translated to a trace message
// using sir.toUplc(generateErrorTraces = true)
else throw new Exception("not 2")
}
Functions
compile {
val nonRecursiveLambda = (a: BigInt) => a + 1
def recursive(a: BigInt): BigInt =
if a == BigInt(0) then 0
else recursive(a - 1)
}
Modules and reusable code
You can define reusable code in a Scala object annotated with @Compile
.
Scalus will compile the code to *.sir files and include them in the jar file.
This way you can distribute your code as a library.
Use @Ignore
to exclude a definition from the compilation.
The compile
will link the modules together and compile them to a single script.
@Compile
object ReusableCode {
val constant = BigInt(1)
def usefulFunction(a: BigInt): BigInt = a + 1
@Ignore // this function is not compiled to UPLC
def shouldNotBeInUplc() = ???
}
val modules = compile {
ReusableCode.usefulFunction(ReusableCode.constant)
}
FromData
FromData type class is used to convert a Data value to a Scalus value.
import scalus.builtin.*, Builtins.*, Data.*
import scalus.builtin.FromDataInstances.given
case class Account(hash: ByteString, balance: BigInt)
enum State:
case Empty
case Active(account: Account)
val fromDataExample = compile {
// The `fromData` function is used to convert a `Data` value to a Scalus value.
val data = iData(123)
// fromData is a summoner method for the `FromData` type class
// there are instances for all built-in types
val a = fromData[BigInt](data)
// also you can use extension method `to` on Data
val b = data.to[BigInt]
// you can define your own `FromData` instances
{
given FromData[Account] = (d: Data) => {
val args = unConstrData(d).snd
new Account(args.head.to[ByteString], args.tail.head.to[BigInt])
}
val account = data.to[Account]
}
// or your can you a macro to derive the FromData instance
{
given FromData[Account] = FromData.deriveCaseClass
given FromData[State] = FromData.deriveEnum[State] {
case 0 => d => State.Empty
case 1 => FromData.deriveConstructor[State.Active]
}
}
}
Writing a validator
Here is a simple example of a PlutusV2 validator written in Scalus.
import scalus.ledger.api.v1.PubKeyHash
import scalus.ledger.api.v3.*
import scalus.ledger.api.v3.FromDataInstances.given
import scalus.builtin.ByteString.given
import scalus.prelude.List
// Use Scala 3 indentation syntax. Look ma, no braces! Like Python!
val pubKeyValidator = compile:
def validator(ctxData: Data) = {
val ctx = ctxData.to[ScriptContext]
List.findOrFail[PubKeyHash](ctx.txInfo.signatories): sig =>
sig.hash == hex"deadbeef"
}
Troubleshooting
Firstly, you can use a debugger and debug the Scala code.
You can use log
and trace
functions to log messages to the execution log.
And there is a ?
operator that can be used to log the value of a boolean expression when it is false.
import scalus.builtin.Builtins.trace
import scalus.prelude.*
import scalus.prelude.Prelude.log
val sir = compile {
val a = trace("a")(BigInt(1))
val b = BigInt(2)
log("Checking if a == b")
val areEqual = a == b
areEqual.? // logs "areEqual ? False"
}.toUplc().evalDebug.toString
// sir: String = """Success executing script:
// term: (con bool False)
// budget: { mem: 0.004298, cpu: 0.962976 }
// costs:
// Startup: 1 { mem: 0.000100, cpu: 0.000100 }
// Var: 3 { mem: 0.000300, cpu: 0.048000 }
// Force: 5 { mem: 0.000500, cpu: 0.080000 }
// Delay: 2 { mem: 0.000200, cpu: 0.032000 }
// Const: 7 { mem: 0.000700, cpu: 0.112000 }
// Apply: 15 { mem: 0.001500, cpu: 0.240000 }
// LamAbs: 4 { mem: 0.000400, cpu: 0.064000 }
// Builtin: 5 { mem: 0.000500, cpu: 0.080000 }
// EqualsInteger: 1 { mem: 0.000001, cpu: 0.052333 }
// IfThenElse: 1 { mem: 0.000001, cpu: 0.076049 }
// Trace: 3 { mem: 0.000096, cpu: 0.178494 }
// logs: a: { mem: 0.000932, cpu: 0.187598 }
// Checking if a == b: { mem: 0.002064, cpu: 0.423096 }
// areEqual ? False: { mem: 0.004298, cpu: 0.962976 }"""
Converting the Scalus code to Flat/CBOR encoded UPLC
The compile
function converts the Scalus code to a SIR
value, Scalus Intermediate Representation.
You then need to convert the SIR
value to a UPLC value and encode it to Flat and then to CBOR.
Many APIs require the HEX encoded string of double CBOR encoded Flat encoded UPLC program,
like Hex(CborEncode(CborEncode(FlatEncode(Program(version, uplc)))))
.
import scalus.*
import scalus.builtin.ByteString.given
import scalus.ledger.api.PlutusLedgerLanguage
import scalus.ledger.api.v1.PubKeyHash
import scalus.ledger.api.v3.*
import scalus.ledger.api.v3.FromDataInstances.given
import scalus.prelude.List
import scalus.uplc.Program
val serializeToDoubleCborHex = {
val pubKeyValidator = compile {
def validator(datum: Data, redeamder: Data, ctxData: Data) = {
val ctx = ctxData.to[ScriptContext]
List.findOrFail[PubKeyHash](ctx.txInfo.signatories)(sig => sig.hash == hex"deadbeef")
}
}
// convert to UPLC
// generateErrorTraces = true will add trace messages to the UPLC program
val uplc = pubKeyValidator.toUplc(generateErrorTraces = true)
val program = Program((1, 1, 0), uplc)
val flatEncoded = program.flatEncoded // if needed
val cbor = program.cborEncoded // if needed
val doubleEncoded = program.doubleCborEncoded // if needed
// in most cases you want to use the hex representation of the double CBOR encoded program
program.doubleCborHex
// also you can produce a pubKeyValidator.plutus file for use with cardano-cli
import scalus.utils.Utils
Utils.writePlutusFile("pubKeyValidator.plutus", program, PlutusLedgerLanguage.PlutusV2)
// or simply
program.writePlutusFile("pubKeyValidator.plutus", PlutusLedgerLanguage.PlutusV2)
}
Evaluating scripts
Scalus provides a high-level API to evaluate UPLC scripts.
compile(BigInt(2) + 2).toUplc().evalDebug.toString
// res11: String = """Success executing script:
// term: (con integer 4)
// budget: { mem: 0.000602, cpu: 0.181308 }
// costs:
// Startup: 1 { mem: 0.000100, cpu: 0.000100 }
// Apply: 2 { mem: 0.000200, cpu: 0.032000 }
// Builtin: 1 { mem: 0.000100, cpu: 0.016000 }
// Const: 2 { mem: 0.000200, cpu: 0.032000 }
// AddInteger: 1 { mem: 0.000002, cpu: 0.101208 }
// logs: """
You get a Result
object that contains the result of the evaluation, the execution budget, the execution costs, and the logs.
You can also use the low-level API to evaluate scripts.
import scalus.builtin.{*, given}
import scalus.ledger.api.*
import scalus.uplc.*, eval.*
def evaluation() = {
val sir = compile {
def usefulFunction(a: BigInt): BigInt = a + 1
usefulFunction(1)
}
val term = sir.toUplc()
// simply evaluate the term
VM.evaluateTerm(term).show // (con integer 2)
// get default MachineParams for PlutusV3 in Conway era
val defaultMachineParams = MachineParams.defaultPlutusV3Params
// or
term.eval.show // (con integer 2)
// evaluate a flat encoded script and calculate the execution budget and logs
val result =
VM.evaluateScriptCounting(defaultMachineParams, Program((1, 1, 0), term).flatEncoded)
println(s"Execution budget: ${result.budget}")
println(s"Evaluated term: ${result.term.show}")
println(s"Logs: ${result.logs.mkString("\n")}")
// you can get the actual execution costs from protocol parameters JSON from cardano-cli
lazy val machineParams = MachineParams.fromCardanoCliProtocolParamsJson(
"JSON with protocol parameters",
PlutusLedgerLanguage.PlutusV3
)
// or from blockfrost API
lazy val machineParams2 = MachineParams.fromBlockfrostProtocolParamsJson(
"JSON with protocol parameters",
PlutusLedgerLanguage.PlutusV3
)
// evaluate the term with debug information
// the `Result` type has a readable `toString` method
VM.evaluateDebug(term) match
case r @ Result.Success(evaled, budget, costs, logs) =>
println(r)
case r @ Result.Failure(exception, budget, costs, logs) =>
println(r)
// Low-level evaluation API:
// CountingBudgetSpender is a budget spender that counts the total cost of the evaluation
val countingBudgetSpender = CountingBudgetSpender()
// TallyingBudgetSpender is a budget spender that counts the costs of each operation
val tallyingBudgetSpender = TallyingBudgetSpender(countingBudgetSpender)
val logger = Log()
// use NoLogger to disable logging
val noopLogger = NoLogger
val cekMachine = CekMachine(
defaultMachineParams, // or use default params
tallyingBudgetSpender,
logger,
JVMPlatformSpecific // platform specific functions. Use JSPlatformSpecific for Scala.js
)
val debruijnedTerm = DeBruijn.deBruijnTerm(term)
try {
cekMachine.evaluateTerm(debruijnedTerm)
} catch {
case e: StackTraceMachineError =>
println(s"Error: ${e.getMessage}")
println(s"Stacktrace: ${e.getCekStack}")
println(s"Env: ${e.env}")
}
println(s"Execution budget: ${tallyingBudgetSpender.budgetSpender.getSpentBudget}")
println(s"Logs: ${logger.getLogs.mkString("\n")}")
println(
s"Execution stats:\n${tallyingBudgetSpender.costs.toArray.sortBy(_._1.toString()).map {
case (k, v) => s"$k: $v"
}.mkString("\n")}"
)
}