First, install aikup: a basic cross-platform utility tool to download and manage Aiken's across multiple versions and for seamless upgrades. Once installed, simply run:

aikup

aikup alone installs the latest version available. You can install specific versions by specifying a version number. For usage instructions, see aikup --help.

From a package manager
npm
npm install -g @aiken-lang/aikup

Homebrew
brew install aiken-lang/tap/aikup

From url (Linux & MacOS)
curl --proto '=https' --tlsv1.2 -LsSf https://install.aiken-lang.org | sh

From url (Windows)
powershell -c "irm https://windows.aiken-lang.org | iex"

You can also find an MSI here.

Language Server
The aiken command-line comes with a built-in language server. If needed, configure your language client with the following configuration (refer to your language client's instructions):

command: aiken lsp (the command is hidden from the command-line help usage)
root pattern: aiken.toml
filetype: aiken (.ak)
The language server supports a variety of capabilities (but not all). For more details, please refer to the supported capabilities on the main repository.

Auto-completion
The command-line comes with few auto-completion scripts for bash, zsh and fish users. The scripts can be obtained using the aiken completion <shell> command. You can install completions on their standard/default locations as follows:

aiken completion bash --install
 
# or, manually
 
aiken completion bash > /usr/local/share/bash-completion/completions/aiken
source /usr/local/share/bash-completion/completions/aiken
 

Editor integrations
The following plugins provide syntax highlighting and indentation rules for Aiken.

Editor	Plugin
VSCode	aiken-lang/vscode-aiken
Vim/Neovim	aiken-lang/editor-integration-nvim
Emacs	aiken-lang/aiken-mode


Installation Via aikup

From a package manager
npm
npm install -g @aiken-lang/aiken

Homebrew
brew install aiken-lang/tap/aiken

From sources (All platform)
cargo install aiken --version 1.0.29-alpha
From Nix flakes (Linux & MacOS only)
nix build github:aiken-lang/aiken#aiken

Language Server
The aiken command-line comes with a built-in language server. If needed, configure your language client with the following configuration (refer to your language client's instructions):

command: aiken lsp (the command is hidden from the command-line help usage)
root pattern: aiken.toml
filetype: aiken (.ak)
The language server supports a variety of capabilities (but not all). For more details, please refer to the supported capabilities on the main repository.

Auto-completion
The command-line comes with few auto-completion scripts for bash, zsh and fish users. The scripts can be obtained using the aiken completion <shell> command. You can install completions on their standard/default locations as follows:

aiken completion bash --install
 
# or, manually
 
aiken completion bash > /usr/local/share/bash-completion/completions/aiken
source /usr/local/share/bash-completion/completions/aiken
 

Editor integrations
The following plugins provide syntax highlighting and indentation rules for Aiken.

Editor	Plugin
VSCode	aiken-lang/vscode-aiken
Vim/Neovim	aiken-lang/editor-integration-nvim
Emacs	aiken-lang/aiken-mode

Installation Manually

Installation Instructions

Checklist

Here's a little checklist to get started with Aiken. Use it if you don't know where to start.


 Install aikup and aiken following the installation instructions;
 Create your first project as indicated below;
 Have a look at the standard library;
 Complete the first steps of the "Hello, World!" tutorial;
 If you're not familiar with the eUTxO model (datums, redeemers, etc.), read the eUTxO Crash Course;
 Complete the end-to-end part of the "Hello, World!" tutorial using your favorite frontend library;
 Have a look at Aiken's Awesome List and explore tutorials, courses or projects that catch your attention;
 Explore the language-tour;
 Join the #aiken channel on Discord and follow us on Twitter!
Want more?


 Try more complex examples like The Gift Card;
 Experiment with property-based testing;
 Read about what we wish we knew when we started with Cardano;
 Learn about design patterns in the eUTxO model;
Creating a new project
Use aiken new foo/bar to create a scaffold a new project and follow instructions from the generated README.md at the root of your project. On success, your project should look roughly as follows:

.
├── README.md
├── aiken.toml
├── lib
│   └── bar
└── validators

Compiling a project
Use aiken build to compile a project, and aiken check to only type-check a project and run tests.

If you're writing a library aiken docs is a powerful utility to generate HTML documentation from types, type annotations and comments. Abuse it!

Finally, once compiled, you may look at the aiken blueprint command group to generate addresses, apply parameters and convert the build output to various formats.

Project structure
Folder organisation
Aiken projects divide their source code in two categories: library code, and application code. Library code must be located in a lib folder, and application code (i.e. on-chain validators) located in a validators folder.

After compilation, the compiler will generate a Plutus blueprint (plutus.json), which is an interoperable document that summarizes your project. The blueprint also contains compiled code for each validator of your project and their corresponding hash digests to be used in addresses.

Configuration
A project has a top-level aiken.toml file at its root containing metadata about the projects, as well as dependencies required by it. Here's a sample of (documented) project configuration:

aiken.toml
# Project's name, as {organisation}/{repository}
name = "foo/bar"
 
# Project's version, we recommend semantic versioning for libraries. However,
# any UTF-8 string is accepted.
version = "1.0.0"
 
# [Optional]
#
# A license name. We recommend Apache-2.0 or MPL-2.0 for open source projects.
licence = "Apache-2.0"
 
# [Optional]
#
# An informative albeit short description of the project.
description = "A next-level DeFi platform"
 
# [Optional]
#
# Structured information on a project to show in generated documentation.
[repository]
platform = "github"   # Platform type, only `github` for now.
user = "aiken-lang"   # Username or organisation on that platform
project = "stdlib"    # Repository or project on that platform
 
# [Optional]
#
# A list of dependencies. Avoid editing by hand, use `aiken packages` to manage
# them.
[[dependencies]]
source = "github"            # Platform type, only `github` for now.
name = "aiken-lang/stdlib"   # The github project, in the form of {organisation}/{repository}.
version = "main"             # Version, as a git tag, branch name or git commit hash

Well-known packages & modules
Aiken's prelude
The prelude contains a minimum set of functions, constructors and modules available by default to all Aiken projects. You can find it on aiken-lang/prelude and at the bottom of this website.

Aiken's standard library
The standard library (or stdlib in short) gathers useful functions and data-structures that might come in handy in your Aiken programming journey. It's also a good reference of well-written and well-tested Aiken code if you need some examples to get started with. You can find it on aiken-lang/stdlib and at the bottom of this website.

GETTING STARTED 

EUTxO CRASH COURSE 

This documentation is a collection of tips and secret knowledge that may be useful in your Cardano journey. Some may never be useful to you or only useful in the distant future. Yet, we hope that if we can save someone a few hours of debugging and hunting down rabbits in bottomless holes, we have accomplished our mission.

CBOR / CDDL
Pretty much everything in Cardano that requires serialization is done using a a structured binary format called CBOR. Think of it as JSON but for binary data. You don't have to be an expert in CBOR to work on Cardano, but being familiar with the notation can be useful especially for troubleshooting low-level stuff.

There are two specific areas worth knowing:

CDDL, which is a specification meta-language for CBOR. It's used to describe how some data is encoded into bytes. In particular, the Cardano ledger maintains a CDDL specification of all the Cardano objects that have to be serialized on-chain. Transaction serialization, for example, is entirely specified in this document. This specification is generally the source of truth for many other tools.

CBOR diagnostic provides a more human-readable, JSON-like syntax that is handy for debugging. We explain CBOR diagnostic in more detail in the Troubleshooting section.

A well-known tool for debugging CBOR is cbor.me; there are also numerous command-line utilities in various languages.

Byron Addresses
Cardano has two kinds of addresses, which are called by different names depending on who you ask. Prior to the introduction of the Shelley era, addresses looked vastly different than what they look like today.

For example: Ae2tdPwUPEYz6ExfbWubiXPB6daUuhJxikMEb4eXRp5oKZBKZwrbJ2k7EZe.

We call these addresses "Bootstrap addresses" or simply "Byron addresses"; in contrast to other addresses that are either called "addresses" or "Shelley addresses" when there's a possible ambiguity. Byron addresses are considered deprecated today and are likely not something you want to use ever. But, you might come across them, for some legacy systems still use them.

Outputs locked by a Byron address or inputs corresponding to such outputs are forbidden in transactions that have Plutus scripts! This means that on-chain validators should never encounter Byron addresses in a validation context. This used to be different in the early days of the Alonzo era but was later changed to avoid hazardous situations.

Validity Intervals
You probably know already that Cardano smart-contract execution is fully deterministic.

This, however, raises an interesting question: How to deal with time?

Asking for the current time usually breaks determinism because asking the same question at different moments may lead to different answers and, thus, different execution paths. So how to introduce time in scripts validating transactions?

Cardano decouples transaction validations in two phases, and we typically refer to them as "phase-1 validations" and "phase-2 validations". Phase-1 validations are structural checks on a transaction performed by the ledger. For example, this is when the ledger verifies that inputs referenced in a transaction are valid, that minimum amounts for fees and outputs are met, etc...

Among the available features of a transaction are "validity intervals" that define a period after which and until the ledger can consider the transaction valid. The validity interval is made of a lower bound (optional) and an upper bound (optional), and it is verified during phase-1 validations. That is if a transaction is said to be valid only after the 5th January 2030, it can only be submitted and considered valid by the ledger after that date. Similarly, if the validity interval defines an upper bound, then the transaction will sit in mempools until then. It is pruned if it doesn't make it into a block by the specified date.

Thereby, one can introduce a notion of time in validators through the means of validity intervals. Since they are checked during phase-1, a validator can assume that the transaction it validates is within the specified validity interval. Hence, should you ensure that an action happens only after a specific date, you can record that date as a datum and check that the transaction's lower bound is greater than the specified date.

The validity interval can be as narrow as one second, allowing scripts to run at very thin precisions. However, a narrow interval means getting the transaction in a block may be more difficult. As a reminder, there's one block every 20 seconds on average minted on the Cardano blockchain. Blocks are usually propagated fast, but it can take a few minutes under moments of heavy load.

Serialization strategies
There's no canonical serialization of objects on Cardano. While there is indeed a CDDL specification for core objectssee below, as mentioned earlier, there are still multiple possible interpretations possible of the specification. For example, a CDDL specification is unable to express in what order should keys in a map be serialized, or whether optional fields with default values (e.g. an optional list of elements) should be omitted entirely or specified with an empty default value.

While there are attempts, such as CIP-0021 to agree on a canonical serialization; the current Cardano ledger does not provide any such guarantee. Consequently, the recommended strategy when dealing with deserialized objects that need to be reserialized is to always preserve the original bytes and not attempt to reserialize anything. At the same time, parsers should not assume one way over another and be ready to deserialize any possible representation that is compliant with the CDDL specification.

This means, amongst other things, that there are multiple possible serializations of a transaction, and it may lead to surprising situations when trying to recalculate the hash of an object.

CDDL files
Era	CDDL Specification
Byron	byron.cddl
Shelley	shelley.cddl
Allegra	allegra.cddl
Mary	mary.cddl
Alonzo	alonzo.cddl
Babbage	babbage.cddl
Conway	conway.cddl
Hash digests
Cardano uses mostly only blake2b as a hashing algorithm throughout the chain. Saying "mostly" because we can find some examples of SHA-256 in some parts of the Byron era, but let's not dwell on that.

Many things called id are hash digests of some serialized objects. For example, a stake pool id is a hash digest of the pool public cold key. A transaction id is a hash digest value of the serialized transaction body. And so forth.

Hashes are generally 32-byte long on Cardano (or 256 bits), except for credentials (i.e. keys or scripts) which are 28-byte long (or 224 bits). This is why a policy id is only 28 bytes long: a policy id is the hash digest of a tagged script, and scripts can be used as credentials (i.e. part of an address). The same goes for any hash digest of a verification key.

Policy Id and language tags
A policy id is a hash digest of a tagged script. Tagged is the keyword here. Should you try to calculate the policy id by simply hashing a serialized script, you may find yourself with a wrong hash without knowing why.

Raw scripts aren't exact pre-image of their hash digest. Before hashing, scripts are prefixed with a certain discriminator byte depending on the language. For instance, any native script is prefixed with a 0x00 (0b0000_0000) byte before hashing.

Here's a table summarizing all discriminators:

Language	Discriminator Byte
Native	0x00
Plutus V1	0x01
Plutus V2	0x02
Plutus V3	0x03
The subsequent versions of Plutus may likely follow the pattern.

Rewards & Withdrawals
Ouroboros, the consensus algorithm used by Cardano, defines an incentive mechanism for stakeholders to participate in the consensus through rewards. Of course, you probably know that by now. Rewards are paid every epoch to delegators that delegate their stake (i.e. ADA tokens) to a stake pool of the network producing blocks on their behalf. Those rewards are, however, not paid directly to stakeholders; this would cause the network at every epoch boundary to pay out all rewards.

Instead, Cardano has introduced a restricted concept of account, similar to what exists on account-based ledgers. This account is, however, singular in many ways:

It is defined by some stake credentials and owned by them;
It can only receive rewards from the protocol but not from a user-defined transaction;
It is automatically delegated;
It is possible to withdraw funds from the account by issuing a withdrawal (which takes the form of a specific field in a transaction). A withdrawal sets the balance of an account to 0 and provides a virtual pot of the account value to the transaction carrying it as if it was an input of that same value. That value can then be dispatched in one or more UTxO, as typically done with any input.

The stake credentials associated with the account protect withdrawals as well. Who owns the stake credentials owns the right to withdraw from the account. This means that reward withdrawals can be commanded by a script (and thus an Aiken program).

Native Scripts
Before full-blown Plutus scripts, Cardano had a minimalistic scripting language usually referred to as "Native Script" or "Phase-1 scripts". It still exists and provides simple, albeit useful, programmability features to Cardano. Native scripts come in the form of a little domain-specific language with 6 constructors: key, all-of, any-of, n-of-m, after and before.

In particular, they are quite handy in defining multisig addresses owned by multiple tenants. You can find more about native scripts in CIP-1854 and in the Formal Ledger Specification, Figure 4: Multi-signature via Native Scripts.

The 'clean' trick: avoid replaying blocks
Sometimes, the Cardano node will perform a complete re-validation of the chain as an integrity check. It does so by scanning through its local files, and replaying blocks onto each other. On Mainnet, this procedure can take multiple hours and is caused, in principle, by mainly two things:

A restart after a non-clean shutdown of the node (e.g. a SIGKILL, or power outage);
A critical change in the ledger version.
The detection of the first scenario is sometimes a bit clunky, and the unlucky ones amongst us have likely already experienced (sometimes several times) the infamous:

Replayed block: slot 3844799 out of 112665654. Progress: 3.41%
Replayed block: slot 3844783 out of 112665654. Progress: 3.42%
...

It turns out that there exists a way to skip re-validations of the first kind. Indeed, on start-up, the node will look for an empty file named clean at the root of its database folder.

node.db/
├── clean              <------------ this fellow
├── immutable
├── ledger
├── lock
├── protocolMagicId
└── volatile

When present, the node will not replay blocks, unless it detects a critical change in the ledger (second scenario) which happens fairly rarely. So it suffices to create such a file (e.g. touch node.db/clean to avoid replaying blocks unecessarily. This is a useful trick to use when developing with a local node, but totally unsound in a production setting (especially for SPO).

Transaction latency vs finality
In a distributed system like Cardano, the notion of latency and finality are often misunderstood (or swapped). Yet, it is crucial to get them right especially when it comes to transactions.

Latency is the time it takes for a transaction to appear on the blockchain, in a block. Finality is the time it takes for a transaction to become immutable and permanent. Why is that different? Because the system is distributed! And that means the information is only eventually true. How long is enough depends on the interested parties and the type of transaction.

It is hard to give a definite answer because finality directly depends on the proportion of adversarial stake in the system. And unfortunately, adversaries don't walk the street waving their hands about the fact they are, in fact, adversaries. If we call ε the proportion of adversaries ([0;0.5]), and consider g their grinding power we find that under Ouroboros Praos (current Cardano consensus algorithm), the probability of settlement errors in terms of the number of blocks (x) is given by the following equation:


Now, what are good values for ε and g is hard to say. Regarding the grinding power, values in the range of 10^9..10^10 are quite conservative values. The entire Bitcoin network has a grinding power of about 10^12. So unless the entire Bitcoin network is attacking Cardano, g is likely smaller than 10^12. For the adversary proportion, as a rule of thumb, it's good to look at the total stake of the largest stake pools to get an idea of how much power can a single entity gather.


A good recommendation for sensitive transactions is thus to wait around 100-150 blocks (30-50 min) whereas a few blocks is usually sufficient for small payments. If you want to play with the equation, feel free to look at this interactive calculator.

Developer Portal
There exists plenty of resources available on Cardano. Though there are a bit hard to find sometimes. As a rule of thumb (and unfortunately): avoid http://docs.cardano.org as it is often inaccurate, plain wrong or missing crucial elements.

On the other hand, the Cardano Developer Portal is a good entry point to many of the ecosystem tooling and resources. The "Builder Tools" section is particularly furnished. It is community-maintained, curated and under constant evolution. Feel free to contribute and ask questions there as well!



TIPS ON EXPLORING CARDANO

Fundamental 

Aiken has 6 primitive types that are built in the language and can be typed as literals: booleans, integers, strings, byte arrays, data and void. The language also includes 2 base building blocks for associating types together: lists and tuples.

Worry not, we'll see later in this manual how to create your own custom types.

Inline comments are denoted via //. We'll use them to illustrate the value of some expressions in examples given all across this guide.

Bool
A Bool is a boolean value that can be either True or False.

Aiken defines a handful of operators that work with booleans. No doubts that they'll look quite familiar.

Operator	Description	Precedence
==	Equality	4
&&	Logical conjunction (a.k.a 'AND')	3
||	Logical disjunction (a.k.a. 'OR')	2
!	Logical negatation (a.k.a 'NOT')	1
?	Trace if false (see also Troubleshooting)	1
Like most languages, && and || are right-associative, which means they don't evaluate their second operand if the first one gives the answer (i.e. short-circuit).

and/or keywords
You'll soon come to realize that long chains of logical operators are quite common when building validators.

True && False && True || False

In this example one could derive the final boolean after thinking for a little but it also requires that you carefully consider how precedence affects the expression grouping. Although this specific example may be simple, in practice those True and False literals would actually be expressions of type Bool. Considering that these kinds of boolean checks are a huge corner stone of validator logic, we've introduced keywords that increase the readability of these so called logical operator chains.

and {
  True,
  False,
  or {
    True,
    False,
  }
}

With these keywords, the grouping becomes immediately obvious at a glance resulting in more readable and maintainable logical operator chains. This shines especially when composing large numbers of logical operators (i.e. four or more) but is less impactful when there are one or two logical operators.

Int
Aiken's only number type is an arbitrary sized integer. This means there is no underflow or overflow.

42
14
1337

Literals can also be written with _ as separators to enhance readability:

1_000_000

Aiken also supports writing integer literals in other bases than decimals. Binary, octal, and hexadecimal integers begin with 0b, 0o, and 0x respectively.

0b00001111 == 15
0o17 == 15
0xF == 15

Aiken has several binary arithmetic operators that work with integers.

Operator	Description	Precedence
+	Arithmetic sum	6
-	Arithmetic difference	6
/	Whole division	7
*	Arithmetic multiplication	7
%	Remainder by whole division	7
Integers are also of course comparable, so they work with a variety of binary logical operators too:

Operator	Description	Precedence
==	Equality	4
>	Greater than	4
<	Smaller than	4
>=	Greater or equal	4
<=	Smaller or equal	4
Any serialisable type is comparable through == in Aiken. A serialisable type represents any of the primitive type in this guide with the exception of Fuzzer and MillerLoopResult, as well as any user-defined custom data-type made of serialisable types.

Said differently, you can compare bytestrings, booleans, integers, lists, tuples, etc. using the == operator.

ByteArray
A ByteArray is exactly what it seems, an array of bytes. Aiken supports three notations to declare ByteArray literals.

1 - As an array of bytes
First, as list of integers ranging from 0 to 255 (a.k.a. bytes):

#[10, 255]
#[1, 256] // results in a parse error because 256 is bigger than 1 byte

Syntax rules for literal integers also apply to byte arrays. Thus, the following is a perfectly valid syntax:

#[0xff, 0x42]

2 - As a byte string
Second, as a UTF-8 encoded byte string. This is generally how common text strings are represented under the hood. In Aiken, simply use double-quotes for that:

"foo" == #[0x66, 0x6f, 0x6f] == #[102, 111, 111]

3 - As a hex-encoded byte string
Because it is quite common to manipulate base16-encoded byte strings in a blockchain context (e.g. transaction id, policy id, etc..); Aiken also supports a shorthand syntax for declaring bytearrays as an hexadecimal string.

Behind the scene, Aiken decodes the encoded string for you and stores only the raw bytes as a ByteArray. This is achieved by prefixing a double-quotes byte string with a #, like so:

#"666f6f" == #[0x66, 0x6f, 0x6f] == #[102, 111, 111] == "foo"

Note how this is different from:

"666f6f" == #[0x36, 0x36, 0x36, 0x66, 0x36, 0x66] == #[54, 54, 54, 102, 54, 54]

Tuples
Aiken has tuples which can be useful for grouping values. Each element in a tuple can have a different type.

(10, "hello") // Type is (Int, ByteArray)
(1, 4, [0]) // Type is (Int, Int, List<Int>)

Long tuples (i.e. more than 3 elements) are usually discouraged. Indeed, tuples are anonymous constructors, and while they are quick and easy to use, they often impede readability. When types become more complex, one should use records instead (as we'll see later).

Elements of a tuple can be accessed using the dot, followed by the index of the element (ordinal). So for example:

let point = (14, 42, 1337, 0)
let a = point.1st
let b = point.2nd
let c = point.3rd
let d = point.4th
(c, d, b, a) // (1337, 0, 42, 14)

List
Lists are ordered collections of values. They're one of the most common data structures in Aiken.

Unlike tuples, all the elements of a List must be of the same type. Attempting to make a list using multiple different types will result in a type error.

[1, 2, 3, 4]  // List<Int>
 
["text", 3, 4]  // Type error!

Inserting at the front of a list is very fast, and is the preferred way to add new values.

[1, ..[2, 3]] // [1, 2, 3]

Note that all data structures in Aiken are immutable so prepending to a list does not change the original list. Instead it efficiently creates a new list with the new additional element.

let x = [2, 3]
let y = [1, ..x]
 
x // [2, 3]
y // [1, 2, 3]

Void
Void is a type representing the nullary constructor, or put simply, the absence of value. It is denoted Void as a type and constructor. Fundamentally, if you think in terms of tuples, Void is a tuple with no element in it.

Void is useful in certain situations, but because in Aiken everything is a typed expression (there's no "statement"), you'll rarely end up in a situation where you need it.

Data
A Data is an opaque compound type that can represent any possible user-defined type in Aiken. We'll see more about Data when we cover custom types. In the meantime, think of Data as a kind of wildcard that can possibly represent any serialisable value.

This is useful when you need to use values from different types in an homogeneous structure. Any user-defined type can be cast to a Data, and you can try converting from a Data to any custom type in a safe manner. Besides, several language builtins only work with Data as a way to deal with polymorphism.

String
In Aiken text strings can be written as text surrounded by double quotes, prefixed with @.

@"Hello, Aiken!"

They can span multiple lines.

@"Hello
Aiken!"

Under the hood text strings are UTF-8 encoded binaries and can contain any valid unicode.

@"🌘 アルバイト Aiken 🌒"

Beware the use case for strings is extremely narrow in Aiken and on-chain code. They are only used for tracing, a bit like labels attached to specific execution paths of your program. You can't find them in the interface exposed by your validator, for example. So most of the time, you probably want to use a ByteArray instead and only resort to String for debugging.

Advanced
If you're just getting started with Aiken, you can probably skip the following section as it describes some more advanced types and behaviors. Feel free to come back to it in due time.

Pair
Aiken has a specific type for representing a pair of values of two not-necessarily equal types. Thus a Pair<a, b> is akin to a 2-tuple (a, b). Like for tuples, you can access elements of a pair using the ordinal syntax:

let foo = Pair(14, "aiken")
 
foo.1st == 14
 
foo.2nd == "aiken"

So why have another type specifically for pairs? The answer is two folds:

This is a specific kind of term that also exists on the underlying Plutus Virtual Machine. Hence, given Aiken's proximity to that machine's representation, it is useful, if not simply necessary, to have ways to represent those when needed.

There's an ambiguity at the contract's boundary regarding how to serialise lists of pairs in CBOR. One way is to use a CBOR array of arrays (of two elements). And the other is to use a CBOR map. While the former is more intuitive, it is in fact the latter that end up being used by the ledger for many internal types. In the first versions of Aiken, the compiler would implicitly treat list of pairs as CBOR map in serialisation functions to mimic the ledger. This has proven inconvenient and confusing in many scenarios involving user-defined data-types, hence the introduction of pairs.

So as a rule of thumb, unless you specifically want to serialize external types (in datums and redeemers) as CBOR maps, you probably never want to use a Pair<a, b> and can stick to a 2-tuple (a, b).

Pairs (former AList)
An associative list (a.k.a Pairs) is a mere type alias such that: type Pairs<a, b> = List<Pair<a, b>>. It exists as a convenience since pairs are mainly present in validator's script contexts under this form. In addition to functions for List which are also all usable on Pairs, the stdlib also provides a dedicated module of helpers specifically crafted for associative lists.

PRNG & Fuzzer
Aiken has an integrated property-based testing framework. Yes, you read that right. Property-based test is a first-class citizen here. If you want to read more about this, we strongly recommend looking at our guide about property-based test; it should teach you everything you need to get started with the framework.

To support this framework, the prelude comes with two pre-defined types. PRNG stands for Pseudo-Random Number Generator. Its definition is opaque and matters only to the internals of the test framework. If you're still interested about the details, head towards the aiken-lang/fuzz!

Similarly, the Fuzzer is an interface for building random generators. It offers a base set of primitives for a variety of types, and compose nicely with one another.

G1Element, G2Element & MillerLoopResult
Specific to the use of BLS12-381 cryptographic primitives, the G1Element, G2Element and MillerLoopResult capture the types of various operands and return values of some builtin functions. Their usage is agnostic to Aiken itself and described in more details in CIP-0381: Plutus support for Pairings over BLS12-381.

Primitive Types

Variables / let-bindings
Aiken has let-bindings for declaring variables. A value can be given a name using the keyword let. Names can be reused by later let-bindings.

Values assigned to let-bindings are immutable, however new bindings can shadow previous bindings.

let x = 1
let y = x
let x = 2
 
y + x == 3

Expect
You can also introduce new bindings through the expect keyword.

expect Some(foo) = my_optional_value

We will see more about the expect keyword when talking about custom types. For now, it is sufficient to know that it exists.

Module constants
Let-bindings aren't allowed in a top-level Aiken module. Yet, Aiken provides module constants as a way to use certain fixed values in multiple places of a Aiken project.

const start_year = 2101
const end_year = 2111

Like all values in Aiken, module constants are immutable. They cannot be used as global mutable state. When a constant is referenced, its value is inlined by the compiler so they can be used in any place where you'd have written a literal to begin with (e.g. when-expression guards, if clauses ...). We'll see some example of that when dealing with control flows.

Note that you can only declare module constants for the following Aiken types: Int, ByteArray and String.

Type annotations
Variables and constants can be given type annotations. These annotations serve as documentation or can be used to provide a more specific type than the compiler would otherwise infer.

const name: ByteArray = "Aiken"
const size: Int = 100
 
let result: Bool = 14 > 42

Variables & Constants

Named functions
Named functions in Aiken are defined using the fn keyword. Functions can have (typed) arguments, and always have a return type. Because in Aiken, pretty much everything is an expression, functions do not have an explicit return keyword. Instead, they implicitly return whatever they evaluate to.

fn add(x: Int, y: Int) -> Int {
  x + y
}
 
fn multiply(x: Int, y: Int) -> Int {
  x * y
}

Functions are first class values and so can be assigned to variables, passed to other functions, or anything else you might do with any other data type.

/// This function takes a function as an argument
fn twice(f: fn(t) -> t, x: t) -> t {
  f(f(x))
}
 
fn add_one(x: Int) -> Int {
  x + 1
}
 
fn add_two(x: Int) -> Int {
  twice(add_one, x)
}

Anonymous functions
Anonymous functions can be defined with a similar syntax.

fn run() {
  let add = fn(x, y) { x + y }
 
  add(1, 2)
}

Labeled arguments
When functions take several arguments it can be difficult for the user to remember what the arguments are, and what order they are expected in.

To help with this Aiken supports labeled arguments, where function arguments are given by labels instead of position.

Take this function that replaces sections of a string:

fn replace(self: String, pattern: String, replacement: String) {
  // ...
}

When calling the function, it is possible to use the defined labels to pass the arguments:

replace(self: "A,B,C", pattern: ",", replacement: " ")
 
// Labeled arguments can be given in any order
replace(pattern: ",", replacement: " ", self: "A,B,C")
 
// Positional arguments and labels can be mixed
replace("A,B,C", pattern: ",", replacement: " ")

The use of argument labels can allow a function to be called in an expressive, sentence-like manner, while still providing a function body that is readable and clear in intent.

Overriding default labels
Note that, when defining a function, it is possible to override the default label to use different names (e.g. a shorter name) in the function body. For example:

fn insert(self: List<(String, Int)>, key k: String, value v: Int) {
  // ... do something with `k` and `v`
}

Externally, the function can still be called using key and value as labelled, but in the function body, they are named k and v for conciseness.

Validators
In Aiken, you can promote some functions to validators using the keyword validator.

validator {
  fn foo(redeemer: Data, script_context: Data) {
    ..
  }
 
  fn bar(datum: Data, redeemer: Data, script_context: Data) {
    ..
  }
}

Functions present in a validator block must abide by the following rules:

 They must have exactly 2 or 3 arguments.
 They must be named
 There may be one or two functions, in a single block, but no more.
Parameters
Validators themselves can take parameters, which represent configuration elements that must be provided to create an instance of the validator. Once provided, parameters are embedded within the compiled validator and part of the generated code. Hence they must be provided before any address can be calculated for the corresponding validator.

validator(utxo_ref: ByteArray) {
  fn foo(redeemer: Data, script_context: Data) {
    ..
  }
}

We see more examples of validators in the examples presented later in this user manual.

Pipe Operator
Operator	Precedence
|>	0
Aiken provides syntax for passing the result of one function to the arguments of another function, the pipe operator (|>). This is similar in functionality to the same operator in Elixir or F#.

The pipe operator allows you to chain function calls without using a lot of parenthesis and nesting. For a simple example, consider the following implementation of an imaginary string.reverse in Aiken:

string_builder.to_string(string_builder.reverse(string_builder.from_string(string)))

This can be expressed more naturally using the pipe operator, eliminating the need to track parenthesis closure.

string
|> string_builder.from_string
|> string_builder.reverse
|> string_builder.to_string

Each line of this expression applies the function to the result of the previous line. This works easily because each of these functions takes only one argument. Syntax is available to substitute specific arguments of functions that take more than one argument; for more, look below in the section "Function capturing".

Function capturing
There is a shorthand syntax for creating anonymous functions that take one argument and call another function. The _ is used to indicate where the argument should be passed.

fn add(x, y) {
  x + y
}
 
fn run() {
  let add_one = add(1, _)
 
  add_one(2)
}

The function capture syntax is often used with the pipe operator to create a series of transformations on some data.

fn add(x: Int , y: Int ) -> Int {
  x + y
}
 
fn run() {
  // This is the same as add(add(add(1, 3), 6), 9)
  1
  |> add(_, 3)
  |> add(_, 6)
  |> add(_, 9)
}

In fact, this usage is so common that there is a special shorthand for it.

fn run() {
  // This is the same as the example above
  1
  |> add(3)
  |> add(6)
  |> add(9)
}

The pipe operator will first check to see if the left hand value could be used as the first argument to the call, e.g. a |> b(1, 2) would become b(a, 1, 2).

If not it falls back to calling the result of the right hand side as a function , e.g. b(1, 2)(a).

Backpassing ←
Functions that take a continuation (i.e. callback with a single argument) can be invoked using the backpassing syntax:

let x <- foo()
 
// which is equivalent to writing:
 
foo(fn(x) {
 
})

This is particularly well suited for functions that operate over abstractions such as Option or Fuzzer and that provide an API of primitives to manipulate them. For example, let's consider the following small API over a Fuzzer:

fn constant(a) -> Fuzzer<a>
fn bool() -> Fuzzer<Bool>
fn map(Fuzzer<a>, fn(a) -> b) -> Fuzzer<b>
fn and_then(Fuzzer<a>, fn(a) -> Fuzzer<b>) -> Fuzzer<b>

And let's look at an excerpt constructing a pipeline using those primitives without backpassing. Something along the lines of:

pub fn option(fuzz_a: Fuzzer<a>) -> Fuzzer<Option<a>> {
  bool()
    |> and_then(
         fn(predicate) {
           if predicate {
             fuzz_a |> map(Some)
           } else {
             constant(None)
           }
         },
       )
}

A bit involved. Here, we can see how and_then is used to step through the bool's Fuzzer. This can be re-written more simply with backpassing as:

pub fn option(fuzz_a: Fuzzer<a>) -> Fuzzer<Option<a>> {
  let predicate <- and_then(bool())
  if predicate {
   fuzz_a |> map(Some)
  } else {
    constant(None)
  }
}

Which reads a lot better! In fact, this technique becomes even more helpful when there are a lot of nested callbacks as it flattens them into a sequence of backpassed let-bindings.

Generic functions
At times you may wish to write functions that are generic over multiple types. For example, consider a function that consumes any value and returns a list containing two of the value that was passed in. This can be expressed in Aiken like this:

fn list_of_two(my_value: a) -> List<a> {
  [my_value, my_value]
}

Here the type variable a is used to represent any possible type.

You can use any number of different type variables in the same function. This function declares type variables a and b.

fn multi_result(x: a, y: b, condition: Bool) -> Result<a, b> {
  when condition is {
    True -> Ok(x)
    False -> Error(y)
  }
}

Type variables can be named anything and may contain underscores (_), but the names must be lowercase. Like other type annotations, they are completely optional, but using them may make it easier to understand the code.

Type annotations
Function arguments are normally annotated with their type, and the compiler will check these annotations and ensure they are correct.

fn identity(x: some_type) -> some_type {
  x
}
 
fn inferred_identity(x) {
  x
}

The Aiken compiler can infer all the types of Aiken code without annotations and both annotated and unannotated code is equally safe. It's considered a best practice to always write type annotations for your functions as they provide useful documentation, and they encourage thinking about types as code is being written.

Documentation
You may add user facing documentation in front of function definitions with a documentation comment /// per line. Markdown is supported and this text will be included with the module's entry in generated HTML documentation.

/// Always true.
///
fn always_true(_a) -> Bool {
  True
}

Functions

Aiken's custom types are named collections of keys and/or values. They are similar to objects in object oriented languages, though they don't have methods.

Custom types are defined with the type keyword.

type Datum {
  Datum { signer: ByteArray, count: Int }
}

Here we have defined a custom type called Datum. Its constructor is called Datum and it has two fields: A signer field which is a ByteArray, and a count field which is an Int.

Once defined the custom type can be used in functions:

fn datums() {
  // Fields can be given in any order
  let datum1 = Datum { signer: #[0xAA, 0xBB], count: 2001 }
  let datum2 = Datum { count: 1805, signer: #[0xAA, 0xCC] }
 
  [datum1, datum1]
}

Shorthand notation
Because single constructors are quite common, there exists a special shorthand notation when the type and the constructor have the same name. So instead of the above, one can write:

type Datum {
  signer: ByteArray,
  count: Int
}

These two notations are synonym. With the shorthand, we implicitly indicate that there's a single constructor named Datum which can be used for constructing values of type Datum, or can also be used when destructuring (see below).

Multiple constructors
Custom types in Aiken can be defined with multiple constructors, making them a way of modeling data that can be one of a few different variants.

We've already seen a custom type with multiple constructors in the Language Tour - Bool.

Aiken's built-in Bool type is defined like this:

/// A Bool is a value that is either `True` or `False`
type Bool {
  True
  False
}

It's a simple custom type with constructors that takes no arguments at all! Use it to answer yes/no questions and to indicate whether something is True or False.

The records created by different constructors for a custom type can contain different values. For example a User custom type could have a LoggedIn constructor that creates records with a name, and a Guest constructor which creates records without any contained values.

type User {
  LoggedIn { count: Int }  // A logged in user
  Guest                    // A guest user with no details
}

let user1 = LoggedIn { count: 4 }
let user2 = LoggedIn { count: 2 }
let visitor = Guest

Option
We define Option as a generic type like so:

type Option<a> {
  None
  Some(a)
}

Then, functions which fail may safely return an optional value.

fn get_head(a: List<a>) -> Option<a> {
  when a is {
    [a, ..] -> Some(a)
    [] -> None
  }
}

The Option type is readily available in Aiken; it is part of the default types and values available by default. Don't hesitate to use it!

Destructuring
When given a custom type record we can pattern match on it to determine which record constructor matches, and to assign names to any contained values.

fn get_name(user) {
  when user is {
    LoggedIn { count } -> count
    Guest -> "Guest user"
  }
}

Custom types can also be destructured with a let binding.

type Score {
  Points(Int)
}
 
let score = Points(50)
let Points(p) = score // This brings a let-binding `p` in scope.
 
p // 50

During destructuring you may also use discards (_) or spreads (..).

type Dog {
  Dog { name: ByteArray, cuteness: Int, age: Int }
}
 
let dog = Dog { name: #"436173686577", cuteness: 9001, age: 3 }

You will need to specify all args for a pattern match, or alternatively use the spread operator.

// All fields present
let Dog { name: name, cuteness: _, age: _ } = dog
builtin.decode_utf8(name) // "Cashew"
 
// Other fields ignored by spreading.
// Field punning is supported. Hence `age` is a shorthand for `age: age`.
let Dog { age, .. } = dog
age // 3

Named accessors
If a custom type has only one variant and named fields they can be accessed using .field_name.

For example using the Dog type defined earlier.

let dog = Dog { name: #[82, 105, 110], cuteness: 2001 }
dog.cuteness // This returns 2001

Generics
Custom types can be be parameterised with other types, making their contents variable.

For example, this Box type is a simple record that holds a single value.

type Box<inner_type> {
  Box(inner: inner_type)
}

The type of the field inner is inner_type, which is a parameter of the Box type. If it holds an int the box's type is Box<Int>, if it holds a string the box's type is Box<String>.

fn foo() {
  let a = Box(420) // type is Box<Int>
  let b = Box("That's my ninja way!") // type is Box<String>
}

Record updates
Aiken provides a dedicated syntax for updating some of the fields of a custom type record.

type Person {
  name: ByteArray,
  shoe_size: Int,
  age: Int,
  is_happy: Bool,
}
 
fn have_birthday(person) {
  // It's this person's birthday, so increment their age and
  // make them happy
  Person { ..person, age: person.age + 1, is_happy: True }
}

The update syntax created a new record with the values of the initial record. It replaces the given binding with their new values.

Type aliases
A type alias lets you create a name which is identical to another type, without any additional information.

type MyNumber = Integer

They are most useful for simplifying type signatures.

type Person = (String, Integer)
 
fn create_person(name: String, age: Integer) -> Person {
  (name, age)
}

Data
At runtime custom types become an opaque Plutus' Data. In Aiken's type system Data matches with any user-defined type (but with none of the primitive types).

Thus, it's also possible to cast any custom type into Data. Extracting from Data however requires the use of expect

fn to_datum(datum: Data) -> Datum {
    expect d: Datum = datum
    d
}

Note that this conversion will fail if the given Data isn't actually a valid representation of the target type. The primary use-case here is for instantiating script contexts, datums and redeemers provided to scripts in an opaque fashion.

It's also useful for interacting with builtins that operate on raw Data. In this case, the conversation happens implicitly. Simply expect any function that accepts Data to automatically work on any custom type.

type Datum {
  count: Int,
}
 
let datum = Datum { count: 1 }
 
// fn(Data) -> ByteArray
builtin.serialise_data(datum) // some bytearray

expect
expect is a special keyword which works like let, but allows to perform some potentially unsafe conversions. There are two main use cases for it:

Non-exhaustive pattern matching
In cases where you have a value of a type that has multiple constructor variants, but are only truly interested in one of the possible variants as outcomes (i.e. any other outcomes invalidate the program), then expect is the perfect tool. Consider the Option type from above in the following example:

let x = Some(42)
 
// As a pattern-match
let y = when x is {
  None -> ???
  Some(y) -> y
}
 
// Using expect
expect Some(y) = x

Casting from Data into a custom type
Another crucial use of expect is to turn some opaque Data into a concrete representation. In the context of a Cardano smart-contract, we can encounter Data in various places although in general it's most likely when dealing with the datums attached to outputs.

Often, we do expect a specific structure for some given datum, and so being able to safely relay those assumptions in the validators comes in handy.

The syntax is identical to the other use case, but it requires an explicit type annotation.

type MyDatum {
  foo: Int,
  bar: ByteArray,
}
 
fn to_my_datum(data: Data) -> MyDatum {
  expect my_datum: MyDatum = data
  my_datum
}

Custom types

Blocks
Every block in Aiken is an expression. All expressions in the block are executed, and the result of the last expression is returned.

let value: Bool = {
    "Hello"
    42 + 12
    False
}
 
value == False

Expression blocks can be used instead of parenthesis to change the precedence of operations.

let celsius = { fahrenheit - 32 } * 5 / 9

Matching
The when *expr* is expression is the most common kind of flow control in Aiken code. It allows us to say "if the data has this shape then do that", which we call pattern matching.

Here we match on an Int and return a specific string for the values 0, 1, and 2. The final pattern n matches any other value that did not match any of the previous patterns.

when some_number is {
  0 -> "Zero"
  1 -> "One"
  2 -> "Two"
  n -> "Some other number" // This matches anything
}

Aiken's when *expr* is is an expression, meaning it returns a value and can be used anywhere we would use a value. For example, we can name the value evaluated from a when expression with a let binding.

type Answer {
  Yes
  No
}
 
let answer = Yes
 
let description =
  when answer is {
    Yes -> "It's true!"
    No -> "It's not yes."
  }
 
description == "It's true!"

If-Else
Pattern matching on a Bool value is discouraged and if / else expressions should be use instead.

let some_bool = True
 
if some_bool {
  "It's true!"
} else {
  "It's not true."
}

Note that, while it may look like an imperative instruction: if this then do that or else do that, it is in fact one single expression. This means, in particular, that the return types of both branches have to match.

Incidentally, you can have as many conditional else/if branches as you need:

fn fibonnaci(n: Int) -> Int {
  if n == 0 {
    0
  } else if n == 1 {
    1
  } else {
    fibonnaci(n-2) + fibonnaci(n-1)
  }
}

Destructuring
A when *expr* is expression can be used to destructure values that contain other values, such as tuples and lists.

when xs is {
  [] -> "This list is empty"
  [a] -> "This list has 1 element"
  [a, b] -> "This list has 2 elements"
  _other -> "This list has more than 2 elements"
}

It's not just the top level data structure that can be pattern matched, contained values can also be matched. This gives when the ability to concisely express flow control that might be verbose without pattern matching.

when xs is {
  [[]] -> "The only element is an empty list"
  [[], ..] -> "The 1st element is an empty list"
  [[4], ..] -> "The 1st element is a list of the number 4"
  other -> "Something else"
}

Matching single-variant constructors
Aiken lets you pattern match on values from types that have a single constructor using a let-binding directly. This is the case for any Tuple , for example, or any custom type with a single constructor.

type Foo {
  foo: Int
}
 
let (a, b, c) = (1, 2, 3)
let Foo { foo } = Foo { foo: 42 }

Assigning names to sub-patterns
Sometimes when pattern matching we want to assign a name to a value while specifying its shape at the same time. We can do this using the as keyword.

when xs is {
  [[_, ..] as inner_list] -> inner_list
  _other -> []
}

Error & Todo
Sometimes, you need to halt the evaluation of your program because you've reached a case that is considered invalid or simply because you haven't yet finished developing some logic. Aiken provides two convenient keywords for that: fail and todo.

When encountered, both will halt the evaluation of your program which will be considered failed. They differ in their semantic i.e. how the compiler behaves towards them.

In fact, todo will trigger warnings at compilation to remind you of those unfinished parts. fail will not, as it is assumed to be a desired break point. Note that the warning also includes the expected type of the expression that needs to replace the todo. This can be a useful way of asking the compiler what type is needed if you are ever unsure.

Let's see an example for both to grasp the difference:

fn favourite_number() -> Int {
  // The type annotations says this returns an Int, but we don't need
  // to implement it yet.
  todo
}
 
fn expect_some_value(opt: Option<a>) -> a {
  when opt is {
    Some(a) -> a
    None -> fail // We want this to fail when we encounter 'None'.
  }
}

When this code is built Aiken will type check and compile the code to ensure it is valid, and the todo or fail will be replaced with code that crashes the program if that function is run.

Giving a reason
A String message can be given as a form of documentation. The message will be traced when the todo or fail code is evaluated. Note that this is likely the only place where you will encounter the type String and this is because the message needs to be printable -- unlike most ByteArray which are often plain gibberish.

fn favourite_number() -> Int {
  todo @"Believe in the you that believes in yourself!"
}
 
fn expect_some_value(opt: Option<a>) -> a {
  when opt is {
    Some(a) -> a
    None -> fail @"Option has no value"
  }
}

Control flow

Aiken programs are made up of bundles of functions and types called modules. Each module has its own namespace and can export types and values to be used by other modules in the program.

// inside module lib/straw_hats/sunny.ak
 
fn count_down() {
  "3... 2... 1..."
}
 
fn blast_off() {
  "BOOM!"
}
 
pub fn set_sail() {
  [
    count_down(),
    blast_off(),
  ]
}

Here we can see a module named straw_hats/sunny, the name determined by the filename lib/straw_hats/sunny.ak. Typically all the modules for one project would live within a directory with the name of the project, such as straw_hats in this example.

The pub keyword makes this type usable from other modules.

For the functions count_down and blast_off we have omitted the pub keyword, so these functions are private module functions. They can only be called by other functions within the same module.

Functions, type-aliases and constants can all be exported from a module using the pub keyword.

Import
To use functions or types from another module we need to import them using the use keyword.

// inside module src/straw_hats/laugh_tale.ak
 
use straw_hats/sunny
 
pub fn find_the_one_piece() {
  sunny.set_sail()
}

The definition use straw_hats/sunny creates a new variable with the name sunny and the value of the sunny module.

In the find_the_one_piece function we call the imported module's public set_sail function using the . operator. If we had attempted to call count_down it would result in a compile time error as this function is private to the sunny module.

Named import
It is also possible to give a module a custom name when importing it using the as keyword.

use unix/dog
use animal/dog as kitty

This may be useful to differentiate between multiple modules that would have the same default name when imported.

Unqualified import
Values and types can also be imported in an unqualified fashion.

use animal/dog.{Dog, stroke}
 
pub fn foo() {
  let puppy = Dog { name: "Zeus" }
  stroke(puppy)
}

This may be useful for values that are used frequently in a module, but generally qualified imports are preferred as it makes it clearer where the value is defined.

You may also combine unqualified imports with custom names as such:

use animal/dog.{Dog, stroke} as kitty

Opaque types
At times it may be useful to create a type and make the constructors and fields private so that users of this type can only use the type through publicly exported functions.

For example we can create a Counter type which holds an int which can be incremented. We don't want the user to alter the Int value other than by incrementing it, so we can make the type opaque to prevent them from being able to do this.

// The type is defined with the opaque keyword
pub opaque type Counter {
  Counter(value: Int)
}
 
pub fn new() {
  Counter(0)
}
 
pub fn increment(counter: Counter) {
  Counter(counter.value + 1)
}

Because the Counter type has been marked as opaque it is not possible for code in other modules to construct or pattern match on counter values or access the value field. Instead other modules have to manipulate the opaque type using the exported functions from the module, in this case new and increment.

The prelude module
There are two modules that are built into the language, the first is the aiken prelude module. By default its types and values are automatically imported into every module you write, but you can still chose to import it the regular way. This may be useful if you have created a type or value with the same name as an item from the prelude.

use aiken
 
/// This definition locally overrides the `Option` type
/// and the `Some` constructor.
pub type Option {
  Some
}
 
/// The original `Option` and `Some` can still be used
pub fn go() -> aiken.Option<Int> {
  aiken.Some(1)
}

The content of the Prelude module is documented in aiken-lang/prelude

The builtin module
The second module that comes with the language is for exposing useful builtin functions from Plutus core. Most underlying platform functions are available here using a "snake_case" name. Much of Aiken's syntax ends up compiling to combinations of certain bultins but many aren't "exposed" through the syntax and need to be used directly. The standard library wraps these in a more Aiken-friendly interface so you'll probably never need to use these directly unless you're making your own standard library.

use aiken/builtin
 
fn eq(a, b) {
    builtin.equals_integer(a, b)
}
 
// is implicitly used when doing:
 
a == b

Documentation
You may add user-facing documentation at the head of modules with a module documentation comment //// (quadruple slash!) per line. Markdown is supported and this text block will be included with the module's entry in generated HTML documentation.

Modules

Aiken has first-class support for unit tests and property-based tests. This means that you can write tests in Aiken directly and execute them on the fly. Hence, the toolkit (aiken check) can parse tests, collect them, run them, and display a report with (hopefully) helpful details.

Unit tests
Writing unit tests
To write a unit test, use the test keyword:

test foo() {
  1 + 1 == 2
}

A unit test is a named function that takes no arguments and returns a boolean. More specifically, a test is considered valid (i.e. it passes) if it returns True.

You can write tests anywhere in an Aiken module, and they can make calls to functions and use constants the same way. One exciting thing about tests is that they use the same virtual machine as the one for executing contracts on-chain. Said differently, they are snippets of on-chain code you can run and reason about in the same context as your production code.

Unit test reports
Let's write a simple function with some unit tests as an example.

lib/example.ak
fn add_one(n: Int) -> Int {
  n + 1
}
 
test add_one_1() {
  add_one(0) == 1
}
 
test add_one_2() {
  add_one(-42) == -41
}

Running aiken check on our project gives us the following report:



As you can see, the report groups tests by module and gives you the memory and CPU execution units needed for each test. That means tests can also be used as benchmarks if you need to experiment with different approaches and compare their execution costs.

Tests can be arbitrarily complex; unlike on-chain scripts, they do not have any execution limit -- or, more specifically, their limit is sufficiently large.

Automatic diffing
Aiken's test runner is (trying to be) intelligent and helpful, especially on test failures. If a test fails, the test runner will do its best to provide information about what went wrong. This is particularly efficient if you write your tests as assertions using binary operators (==, >=, != etc..).

For example, let's add a failing test to our example above:

lib/example.ak
// ... rest of the file is unchanged
test add_one_3() {
  add_one(1) == 1
}



Brilliant! We get to see what both operands are evaluated to, and the test runner points us to the problem.

Property-based test
Short introduction
One of Aiken's unique selling points is its property-based testing framework with integrated shrinking. Property-based testing is the art of generating test cases by exploring the realm of possible inputs and looking for general behaviours rather than specific cases.

For example, if you consider a function list.reverse that reverses the order of elements in a list, it has an excellent property: calling it twice puts the list back in its original order. You can approach testing that function by generating random list samples and checking that they satisfy the property.

If a counterexample to the property is found, the framework tries to simplify it to a minimal counterexample so that it is easier to digest and reason about. This is a crucial step since exploring an input domain randomly can lead to arbitrarily large sample values that may obfuscate the real problem. Imagine a function that operates on a list of integers and fails for negative integer values. In this example the list [12, 441, 0, 7863, -2, 1213] is a valid counterexample but [-1] is arguably a much better one. It allows for the precise pinning down of the issue more directly.

In classic property-based testing frameworks, finding a smaller counterexample can be tedious and is referred to as shrinking. Developers writing properties must define how to get to smaller counterexamples from an initial value. In Aiken, the framework integrates and automatically manages this process.

Writing properties
A property-based test is a test with a single argument that specifies a Fuzzer. A fuzzer, or generator, is an abstraction that specifies how to generate (pseudo-) random values from a source of randomness.

We provide -- and strongly recommend using -- a core library for fuzzers: aiken/fuzz. This library contains valuable primitives that go through the hassle of abstracting the management of the pseudo-randomness on your behalf so that writing fuzzers becomes bliss. Use it without moderation!

use aiken/fuzz
 
test prop_is_non_negative(n: Int via fuzz.int()) {
  n >= 0
}

A Fuzzer is introduced as a special annotation for the argument using the via keyword and must be of type Fuzzer<a> (although a must be instantiated to a concrete type!). In the example above, it is of type Fuzzer<Int>. There's thus a direct relation between the type of an argument and the type carried by its fuzzer! Therefore, the type annotation for the argument is entirely optional since it is redundant with the fuzzer.

Composing fuzzers
Fuzzers can be composed directly inline after the via keyword:

use aiken/fuzz
 
test prop_list(xs: List<Int> via fuzz.list(fuzz.int())) {
  todo
}

They can also be defined into separate functions and called by names:

use aiken/fuzz
 
fn my_fuzzer() -> Fuzzer<List<Int>> {
  fuzz.list(fuzz.int())
}
 
test prop_list(xs: List<Int> via my_fuzzer()) {
  todo
}

Property test reports
Akin to unit tests, properties are executed using the aiken check command. They provide a report highlighting the number of random samples checked and a simplified counterexample in case of failure. For example, if we run our prop_is_non_negative above operating on int, we get the following:



As you can see, the property is invalidated by negative values generated by the int() fuzzer. The counterexample is shown directly in the test report, along with the number of tests that ran until a counterexample was found.

Labelling
Often, one wants to assess that specific paths are being explored in a random walk. This is particularly true of complex generators that explore a large domain space. The aiken/fuzz library provides labels for that purpose that are automatically gathered by the framework. Upon success, their distribution across all test runs is shown in the report. Labelling can also be useful to assess a fuzzer's correctness, and we strongly recommend testing your fuzzers! A common pitfall of property-based testing is properties that do not actually test anything due to wrongly defined fuzzers. For example, let's inspect the bool() fuzzer from the aiken/fuzz library:

test prop_bool_distribution(predicate via fuzz.bool()) {
  fuzz.label(
    if predicate {
      @"True"
    } else {
      @"False"
    },
  )
 
  True
}

As we can see, the generator is mostly uniform between True and False (phew!). Note that it isn't necessarily exactly 50% due to the random nature of the sample, but it asymptotically converges towards that.



Note that we have passed the extra option --max-success=1000 to the check command here to increase the number of tests run and get a better view of the random sample.

Testing failures
Sometimes, you need to assert that a particular execution path can fail. This is also known as an "expected failure" and is a valid way of asserting the behaviour of a program. Fortunately, you can do this with Aiken, too, by adding fail after the test name. So, for example:

lib/example.ak
use aiken/math
 
test must_fail() fail {
  expect Some(result) = math.sqrt(-42)
  result == -1
}

The fail keyword here works for both unit and property tests, with a subtle difference for property tests. Indeed, a property that is expected to fail will still run multiple times and only be considered successful if ALL the execution of the property failed. This is useful to write non-properties, especially if they rely on fail or expect for checking pre-conditions under the hood. Said differently, a property test flagged as fail will stop at the first successful evaluation and be marked as failed.

For properties, it's also possible to indicate fail once in order to run a property until it fails or until it reaches the maximum number of tries (default to 100). If the test runner finds 100 tests that satisfy a property expected to fail once, the entire test is considered a failure. Said differently, a property test flagged as fail once will stop at the first failed evaluation and be marked as a success. If none of the evaluation fails, it is marked as failed.

Running specific tests
aiken check supports flags that allow you to run subsets of all tests in your project.

Examples
aiken check -m "aiken/list"

This only runs tests inside the module named aiken/list.

aiken check -m "aiken/option.{flatten}"

This only runs tests within the aiken/option module that contains the word flatten in their name.

aiken check -e -m "aiken/option.{flatten_1}"

You can force an exact match with -e.

aiken check -e -m map_1

This only runs tests in the whole project that exactly match the name map_1.

Tests

On-chain programming can be a bit tedious and shares a lot of commonalities with embedded programming. Because the execution environment is so constrained, programs have to be optimized and usually leave little room for troubleshooting errors.

Aiken tries its best to provide developers with extra tools and debugging capabilities. Let's explore them.

Traces
Your first ally in this journey are traces. Think of a trace as a log message, that is captured by the virtual machine at specific moment. You can add traces to top-level expressions in Aiken using the trace keyword.

For example:

fn is_even(n: Int) -> Bool {
  trace "is_even"
  n % 2 == 0
}
 
fn is_odd(n: Int) -> Bool {
  trace "is_odd"
  n % 2 != 0
}

Traces can be a little hard to grasp initially since Plutus -- and therefore Aiken -- is a purely functional execution engine. There's therefore no statements in a compiled program. There's only expressions. A trace will be collected if it is evaluated by the virtual machine. There are two common ways to capture traces in Aiken: when running tests via aiken check or when simulating a transaction using aiken tx simulate. In both cases, traces captured during evaluation will be printed on screen.

For example, in the following program:

let n = 10
is_even(n) || is_odd(n)

Only the trace is_even will be captured, because is_odd is in fact never evaluated (there's no need because the left-hand side already returns True).

Note that traces are:

Removed by default when building your project with aiken build. They can be preserved using --trace-level verbose;
Kept by default when checking your project with aiken check. They can be left out using --trace-level silent.
This is because tracing makes compiled code bigger and can add an extra overhead which is often undesired for final production-ready validators. Yet, they are useful for development and when testing. The command-line is thus geared towards those use-cases. Beware that while enabling or disabling traces doesn't change the semantic of your program, it effectively changes its hash value, and thus its associated addresses.

? operator
On-chain programs are fundamentally nothing more than predicates. Said differently, they are functions that return True or False. Hence, it is common practice to structure on-chain programs as conjunctions and disjunctions of booleans expressions.

This can be a little hard to reason about however because booleans are "blind". That is, you lose information about the original context as you evaluate complex boolean expressions.

Take for example the following simple expression:

let must_be_after = True
let must_spend_token = False
 
must_be_after && must_spend_token

It evaluates to False. From just False, you can't really tell which branch was actually False in the original expression. Yet it is often useful to reason about even larger expressions to troubleshoot an issue.

This is why Aiken provides the ? operator (reads as "trace-if-false operator"). This postfix operator can be appended to any boolean expression and will trace the expression only if it evaluates to False. This is useful to trace an entire evaluation path that led to a final expression being False. In the example above, we could have written:

must_be_after? && must_spend_token?

Which would have generated the trace "must_spend_token ? False".

Handy, right?

Incidentally, the ? operator works like trace and is therefore affected by the --keep-traces and --no-traces options. When compiling for production, it has therefore no effect on the program and behaves as if it wasn't there at all.

CBOR diagnostic
This is all great but sometimes, you need more. Sometimes, you need to inspect the value of some specific object at runtime. This is harder than it seems because a compiled Aiken program has erased any context and any notion of types. Even functions and variable names are replaced by compact indices which makes it relatively hard to inspect programs and values at runtime. For example, this is what a compiled function may look like in UPLC:

(lam i_31
  (lam i_32
    (lam i_33
      (force
        [ [ [ i_2 i_32 ] (delay (con unit ())) ]
          (delay
            [ [ i_4 [ i_33 [ i_1 i_32 ] ] ]
              [ [ [ i_31 i_31 ] [ i_0 i_32 ] ] i_33
              ]
            ]
          )
        ]
      )
    )
  )
)

Note quite easy to read, huh? But there's hope! Aiken's standard library provides a convenient method to inspect any value at runtime and obtain a String representation of them. The syntax used for this representation is called a CBOR diagnostic. Think of it as a high-level syntax that resembles JSON and that can represent binary data.

aiken/cbor
pub fn diagnostic(data: Data) -> String

Why use CBOR diagnostics you may ask?

Well, because it is what most faithfully captures the representation of objects present at runtime and in the interface of on-chain validators. Getting familiar with CBOR diagnostics requires a bit of practice but can be a useful skill to master when working with Cardano in general. CBOR is everywhere in Cardano, including in on-chain validators. Datum and redeemers are, for example, provided as CBOR objects to the validator by the ledger. Transactions are also themselves encoded as CBOR when serialized and propagated to the network.

A CBOR diagnostic is merely a slightly more human-friendly way to visualize a binary object. For example, a serialized list of integers such as 83010203 is represented as [1, 2, 3] in diagnostic notation.

In addition, most tools and libraries that deal with CBOR make it easy to go back-and-forth between the raw encoding and the diagnostic notation. This is the case of cbor.me or cbor-diag for instance.

Here's a little cheatsheet to help you decipher CBOR diagnostics:

Type	Examples
Int	1, -14, 42
ByteArray	h'FF00', h'666f6f'
List	[], [1, 2, 3], [_ 1, 2, 3]
Map	{}, { 1: h'FF', 2: 14 }, {_ 1: "AA" }
Tag	42(1), 10(h'ABCD'), 1280([1, 2])
While most are pretty transparent, the use-case for Tag may not strike many as obvious. In fact, Tag is used to encode custom types on-chain, starting from tag 121 for the first constructor of a data-type, 122 for the next, and so forth. What is tagged corresponds to the fields of the constructors, as a list of objects.

Let's see some more examples of diagnostics from real Aiken values.

use aiken/cbor
 
 
// An Int becomes a CBOR int
cbor.diagnostic(42) == @"42"
 
// A ByteArray becomes a CBOR bytestring
cbor.diagnostic("foo") == @"h'666F6F'"
 
// A List becomes a CBOR array
cbor.diagnostic([1, 2, 3]) == @"[_ 1, 2, 3]"
 
// A Tuple becomes a CBOR array
cbor.diagnostic((1, 2)) == @"[_ 1, 2]"
 
// A List of 2-tuples becomes a CBOR map
cbor.diagnostic([(1, #"ff")]) == @"{ 1: h'FF' }"
 
// 'Some' is the first constructor of Option → tagged as 121
cbor.diagnostic(Some(42)) == @"121([_ 42])"
 
// 'None' is the second constructor of Option → tagged as 122
cbor.diagnostic(None) == @"122([])"

Diagnostics are meant to be used only in development or for testing; in combination with trace for example. Incidentally, they also make for a convenient way to double-check the binary representation of some instance of your datum or redeemer through tests. Imagine the following type:

type MyDatum {
  foo: Int,
  bar: ByteArray
}

Eventually, you will need to construct compatible values for building an associated transaction. Aiken provides blueprints as build outputs to help with that. Yet you may also control some chosen values directly using cbor.diagnostic and a test:

use aiken/cbor
 
test my_datum_1() {
  let datum = MyDatum { foo: 42, bar: "Hello, World!" }
  cbor.diagnostic(datum) == @"121([42, h'48656c6c6f2c20576f726c6421'])"
}

You can turn this diagnostic into raw CBOR using tools such as cbor.me.

Troubleshooting

Language Tour 

Let's write and execute a smart contract on Cardano in 10 minutes. Yes, you read that right.

You can find code supporting this tutorial on Aiken's main repository.

Covered in this tutorial

 Writing a basic Aiken validator;
 Writing & running tests with Aiken;
 Troubleshooting smart contracts.
When encountering an unfamiliar syntax or concept, do not hesitate to refer to the language-tour for details and extra examples.

Pre-requisites
We'll use Aiken to write the script so make the command-line installed already or else, look at the installation instructions.

Scaffolding
First, let's create a new Aiken project:

aiken new aiken-lang/hello-world
cd hello-world

This command scaffolds an Aiken project. In particular, it creates a lib and validators folders in which you can put Aiken source files.

./hello-world
│
├── README.md
├── aiken.toml
├── lib
│   └── hello-world
└── validators

Using the standard library
We'll use the standard library for writing our validator. Fortunately, aiken new did automatically add the standard library to our aiken.toml for us. It should look roughly like that:

aiken.toml
name = "aiken-lang/hello-world"
version = "0.0.0"
license  = "Apache-2.0"
description = "Aiken contracts for project 'aiken-lang/hello-world'"
 
[repository]
user = 'aiken-lang'
project = 'hello-world'
platform = 'github'
 
[[dependencies]]
name = "aiken-lang/stdlib"
version = "1.9.0"
source = "github"

Now, running aiken check, we should see dependencies being downloaded. That shouldn't take long.

❯ aiken check
    Resolving versions
  Downloading packages
   Downloaded 1 package in 0.91s
    Compiling aiken-lang/stdlib 1.9.0 (/Users/aiken/Documents/aiken-lang/hello-world/build/packages/aiken-lang-stdlib)
    Compiling aiken-lang/hello-world 0.0.0 (/Users/aiken/Documents/aiken-lang/hello-world)
Summary
    0 error, 0 warning(s)

Our first validator
Let's write our first validator as validators/hello-world.ak:

validators/hello-world.ak
use aiken/hash.{Blake2b_224, Hash}
use aiken/list
use aiken/transaction.{ScriptContext}
use aiken/transaction/credential.{VerificationKey}
 
type Datum {
  owner: Hash<Blake2b_224, VerificationKey>,
}
 
type Redeemer {
  msg: ByteArray,
}
 
validator {
  fn hello_world(datum: Datum, redeemer: Redeemer, context: ScriptContext) -> Bool {
    let must_say_hello =
      redeemer.msg == "Hello, World!"
 
    let must_be_signed =
      list.has(context.transaction.extra_signatories, datum.owner)
 
    must_say_hello && must_be_signed
  }
}

Our first validator is rudimentary, yet there's already a lot to say about it.

It looks for a verification key hash (owner) in the datum and a message (msg) in the redeemer. Remember that, in the eUTxO model, the datum is set when locking funds in the contract and can be therefore seen as configuration. Here, we'll indicate the owner of contract and require a signature from them to unlock funds—very much like it already works on a typical non-script address.

Moreover, because there's no "Hello, World!" without a proper "Hello, World!" our little contract also demands this very message, as a UTF-8-encoded byte array, to be passed as redeemer (i.e. when spending from the contract).

It's now time to build our first contract!

aiken build

This command generate a CIP-0057 Plutus blueprint as plutus.json at the root of your project. This blueprint describes your on-chain contract and its binary interface. In particular, it contains the generated on-chain code that will be executed by the ledger, and a hash of your validator(s) that can be used to construct addresses.

This format is framework-agnostic and is meant to facilitate interoperability between tools. The blueprint is fully integrated into Aiken, which can automatically generate it based on your type definitions and comments.

Let's see the validator in action!

Adding traces
In a way, validators are nothing more than predicates. A predicate is a function that returns a boolean. It indicates whether the operation is permitted or not. Here, we are writing a spend validator which controls who is allowed to spend funds locked by it. Troubleshooting validators can rapidly become difficult as the only real output they give is yes or no. To cope with that, you can add traces to a validator. Traces are special commands which tells the ledger—or whomever is executing the validator—to collect messages when encountered. On failure, it spits out the messages encountered, thus giving a trace of the program execution.

So let's add a few traces.

validators/hello-world.ak
use aiken/hash.{Blake2b_224, Hash}
use aiken/list
use aiken/string
use aiken/transaction.{ScriptContext}
use aiken/transaction/credential.{VerificationKey}
 
type Datum {
  owner: Hash<Blake2b_224, VerificationKey>,
}
 
type Redeemer {
  msg: ByteArray,
}
 
validator {
  fn hello_world(datum: Datum, redeemer: Redeemer, context: ScriptContext) -> Bool {
    trace string.from_bytearray(redeemer.msg)
 
    let must_say_hello =
      redeemer.msg == "Hello, World!"
 
    let must_be_signed =
      list.has(context.transaction.extra_signatories, datum.owner)
 
    must_say_hello? && must_be_signed?
  }
}

Here we have done two changes:

We've added a manual message using the trace keyword. The message is the one passed as redeemer. With this, we can check that the value seen by the validator is the expected one.

Notice how we also added a question mark ? at the end of each expression must_say_hello and must_be_signed. This is what we call the trace-if-false operator, and is pretty handy to debug things. This operator will trace the expression it is attached to only if it evaluates to False. This encourages an approach where validators are built as a conjunction or disjunction of requirements. On unsuccessful executions, all the invalidated requirements will leave a trace!

In order to see those traces, we'll need to write a short test.

Writing a test
Aiken has support for tests built-in! As you'll see shortly, tests can also serve as benchmarks since they display the exact memory and steps execution units required to run them. They also collect traces for us. Let's write a simple test which runs our validator. Tests are functions without arguments which return boolean. Yet unlike functions, they are denoted with the keyword test. We will need a datum, a redeemer and a script context as well as a few more imports:

validators/hello-world.ak
use aiken/transaction.{OutputReference, ScriptContext, Spend, TransactionId}
 
// ... rest of the code is unchanged
 
test hello_world_example() {
  let datum =
    Datum { owner: #"00000000000000000000000000000000000000000000000000000000" }
 
  let redeemer =
    Redeemer { msg: "Aiken Rocks!" }
 
  let placeholder_utxo =
    OutputReference { transaction_id: TransactionId(""), output_index: 0 }
 
  let context =
    ScriptContext {
      purpose: Spend(placeholder_utxo),
      transaction: transaction.placeholder(),
    }
 
  hello_world(datum, redeemer, context)
}

Here, we have a test! A failing test, but we'll get it to pass, no worries. But first, let's execute it. Simply run aiken check:

❯ aiken check
        
  ┍━ hello_world ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  │ FAIL [mem: 22531, cpu: 8042312] hello_world_example
  │ ↳ Aiken Rocks!
  │ ↳ must_say_hello ? False
  ┕━━━━━━━━━━━━━━━━━━━━━━ 1 tests | 0 passed | 1 failed

This output is already pretty useful. We can see the trace that we added in our validator which spits back the msg in the redeemer. Then, we see the ? operator at play. It shows a trace since the predicate must_say_hello returned False. Note that the other predicate must_be_signed isn't shown here because Aiken ensures that the conditions are checked one after the other. Since the first one already failed, the entire expression shortcircuits to False.

Let's fix this and ensure that we say Hello, World! instead.

validators/hello-world.ak
test hello_world_example() {
  let datum =
    Datum { owner: #"00000000000000000000000000000000000000000000000000000000" }
 
  let redeemer =
    Redeemer { msg: "Hello, World!" }
 
  let placeholder_utxo =
    OutputReference { transaction_id: TransactionId(""), output_index: 0 }
 
  let context =
    ScriptContext {
      purpose: Spend(placeholder_utxo),
      transaction: transaction.placeholder(),
    }
 
  hello_world(datum, redeemer, context)
}

Now, we can run aiken check again:

❯ aiken check
        
  ┍━ hello_world ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  │ FAIL [mem: 23332, cpu: 8306868] hello_world_example
  │ ↳ Hello, World!
  │ ↳ must_be_signed ? False
  ┕━━━━━━━━━━━━━━━━━━━━━━ 1 tests | 0 passed | 1 failed

It fails again, as expected, but we got further. Notice how the the mem and cpu execution units are slightly higher than on the first execution. Now, we have moved to evaluating the second part of the validator requirements: must_be_signed. To satisfy this second requirement, we'll need to add our test owner to the transaction's extra signatories. As such:

validators/hello-world.ak
use aiken/transaction.{
  OutputReference, ScriptContext, Spend, Transaction, TransactionId,
}
 
// ...rest of the code is unchanged
 
test hello_world_example() {
  let datum =
    Datum { owner: #"00000000000000000000000000000000000000000000000000000000" }
 
  let redeemer =
    Redeemer { msg: "Hello, World!" }
 
  let placeholder_utxo =
    OutputReference { transaction_id: TransactionId(""), output_index: 0 }
 
  let context =
    ScriptContext {
      purpose: Spend(placeholder_utxo),
      transaction: transaction.placeholder()
        |> fn(transaction) {
             Transaction { ..transaction, extra_signatories: [datum.owner] }
           }
    }
 
  hello_world(datum, redeemer, context)
}

This should do the trick. Note that, at this point, we do not provide any signature of any kind. This is because we are not performing any of the ledger phase-1 validations. Yet, prior to executing smart contracts, the ledger will verify that the content of the transaction is valid. In particular, it will verify that any extra_signatories has a corresponding valid signature in the transaction. Here, we can just go with our placeholder verification key!

❯ aiken check
        
  ┍━ hello_world ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  │ PASS [mem: 37686, cpu: 13337425] hello_world_example
  │ ↳ Hello, World!
  ┕━━━━━━━━━━━━━━━━━━━━━━━ 1 tests | 1 passed | 0 failed

And, it works! We are left with our Hello, World! trace and no failure 🎉! Congratulations, you've made it. Of course, this particular test isn't really interesting. Yet, in practice, validators are more complex and layered. We encourage you to split validators into smaller functions that do one thing at a time, and test those functions independently.

Traces can add some overhead to a validator's execution. This is why Aiken erases all traces by default when you build validators. To keep them in the final validators, use the --trace-level verbose option when building. Conversely, the check command preserves traces by default since most of the time, this is what you want. If you need to benchmark an execution without traces, you can always pass the --trace-level silent flag when running tests to remove all traces.

You are now ready to move on to the next steps and look into performing this end-to-end, with a real transaction! Exciting, isn't it?

Hello, World!

Covered in this tutorial

 Interact with a validator on the Preview network;
 Using Lucid through Blockfrost;
 Getting test funds from the Cardano Faucet;
 Using web explorers such as CardanoScan.
Pre-requisites
We assume that you have followed the Hello, World!'s First steps and thus, have Aiken installed an ready-to-use. We will also use Lucid, so make sure you have your dev environment ready for some TypeScript★.

★ For TypeScript and the rest of this tutorial, we recommend installing deno

Getting funds
For this tutorial, we will use the validator we built in First steps. Yet, before moving on, we'll need some funds, and a public/private key pair to hold them. We can generate a private key and an address using Lucid.

Let's write our first script as generate-credentials.ts:

generate-credentials.ts
import { Lucid } from "https://deno.land/x/lucid@0.8.3/mod.ts";
 
const lucid = await Lucid.new(undefined, "Preview");
 
const privateKey = lucid.utils.generatePrivateKey();
await Deno.writeTextFile("me.sk", privateKey);
 
const address = await lucid
  .selectWalletFromPrivateKey(privateKey)
  .wallet.address();
await Deno.writeTextFile("me.addr", address);

You can run the instructions above using Deno via:

deno run --allow-net --allow-write generate-credentials.ts

Now, we can head to the Cardano faucet to get some funds on the preview network to our newly created address (inside me.addr).


👉 Make sure to select "Preview Testnet" as network.

Using CardanoScan we can watch for the faucet sending some ADA our way. This should be pretty fast (a couple of seconds).

Using the contract
Now that we have some funds, we can lock them in our newly created contract. We'll use Lucid to construct and submit our transaction through Blockfrost.

This is only one example of possible setup using tools we love. For more tools, make sure to check out the Cardano Developer Portal!

Setup
First, we setup Lucid with Blockfrost as a provider. This will allow us to let Lucid handle transaction building for us, which includes managing changes. It also gives us a direct way to submit the transaction later on.

Create a file named hello-world-lock.ts in the root of your project and add the following code:

hello-world-lock.ts
import {
  Blockfrost,
  C,
  Constr,
  Data,
  Lucid,
  SpendingValidator,
  TxHash,
  fromHex,
  toHex,
  utf8ToHex,
} from "https://deno.land/x/lucid@0.8.3/mod.ts";
import * as cbor from "https://deno.land/x/cbor@v1.4.1/index.js";
 
const lucid = await Lucid.new(
  new Blockfrost(
    "https://cardano-preview.blockfrost.io/api/v0",
    Deno.env.get("BLOCKFROST_PROJECT_ID")
  ),
  "Preview"
);

Note that the highlighted line above looks for an environment variable named BLOCKFROST_PROJECT_ID which its value must be set to your Blockfrost project id. You can define a new environment variable in your terminal by running (in the same session you're also executing the script!):

export BLOCKFROST_PROJECT_ID=preview...

Replace preview... with your actual project id.

Next, we'll need to read the validator from the blueprint (plutus.json) we generated earlier. We'll also need to convert it to a format that Lucid understands. This is done by serializing the validator and then converting it to a hexadecimal text string as shown below:

hello-world-lock.ts
lucid.selectWalletFromPrivateKey(await Deno.readTextFile("./me.sk"));
 
const validator = await readValidator();
 
// --- Supporting functions
 
async function readValidator(): Promise<SpendingValidator> {
  const validator = JSON.parse(await Deno.readTextFile("plutus.json")).validators[0];
  return {
    type: "PlutusV2",
    script: toHex(cbor.encode(fromHex(validator.compiledCode))),
  };
}

Locking funds into the contract
Now that we can read our validator, we can make our first transaction to lock funds into the contract. The datum must match the representation expected by the validator (and as specified in the blueprint), so this is a constructor with a single field that is a byte array.

As value for that byte array, we provide a hash digest of our public key (from the wallet created with our me.sk) . This will be needed to unlock the funds.

hello-world-lock.ts
const publicKeyHash = lucid.utils.getAddressDetails(
  await lucid.wallet.address()
).paymentCredential?.hash;
 
const datum = Data.to(new Constr(0, [publicKeyHash]));
 
const txHash = await lock(1000000n, { into: validator, owner: datum });
 
await lucid.awaitTx(txHash);
 
console.log(`1 tADA locked into the contract at:
    Tx ID: ${txHash}
    Datum: ${datum}
`);
 
// --- Supporting functions
 
async function lock(
  lovelace: bigint,
  { into, owner }: { into: SpendingValidator; owner: string }
): Promise<TxHash> {
  const contractAddress = lucid.utils.validatorToAddress(into);
 
  const tx = await lucid
    .newTx()
    .payToContract(contractAddress, { inline: owner }, { lovelace })
    .complete();
 
  const signedTx = await tx.sign().complete();
 
  return signedTx.submit();
}

You can run the excerpt above by executing:

deno run --allow-net --allow-read --allow-env hello-world-lock.ts

The above code requires you to:

have a BLOCKFROST_PROJECT_ID environment variable set. You can get one by signing up for a Blockfrost account.

have the file hello-world-lock.ts placed at the root of your hello-world folder.

At this stage, your folder should look roughly like this:

./hello-world
│
├── README.md
├── aiken.toml
├── plutus.json
├── generate-credentials.ts
├── hello-world-lock.ts
├── me.addr
├── me.sk
├── lib
│   └── ...
└── validators
    └── hello-world.ak

If everything went well, you should see something like this:

1 tADA locked into the contract at:
    Tx ID: 8559f57234407204d8e9a6bf57ef6943c65ec7119eb1c2ca6224f8bad8e71c1e
    Datum: d8799f581c10073fd2997d2f7dc6dadcf24966bd06b01930e5210e5de7aebf792dff

Inspecting the transaction
Now is a good moment to pause and have a look at CardanoScan. Here's an example of a Hello World transaction that we generated using this tutorial.

If you notice the small icon next to the contract output address, we can even inspect the datum:

d8799f581c10073fd2997d2f7dc6dadcf24966bd06b01930e5210e5de7aebf792dff
{
  "constructor": 0,
  "fields": [
    {
      "bytes": "10073fd2997d2f7dc6dadcf24966bd06b01930e5210e5de7aebf792d"
    }
  ]
}

Unlocking funds from the contract
Finally, as a last step: we now want to spend the UTxO that is locked by our hello-world contract.

To be valid, our transaction must meet two conditions:

it must provide "Hello, World!" as a redeemer; and
it must be signed by the key referenced as datum (i.e. the owner).
Let's make a new file hello-world-unlock.ts and copy over some of the boilerplate from the first one.

hello-world-unlock.ts
import {
  Blockfrost,
  C,
  Constr,
  Data,
  Lucid,
  SpendingValidator,
  TxHash,
  fromHex,
  toHex,
  utf8ToHex,
} from "https://deno.land/x/lucid@0.8.3/mod.ts";
import * as cbor from "https://deno.land/x/cbor@v1.4.1/index.js";
 
const lucid = await Lucid.new(
  new Blockfrost(
    "https://cardano-preview.blockfrost.io/api/v0",
    Deno.env.get("BLOCKFROST_PROJECT_ID")
  ),
  "Preview"
);
 
lucid.selectWalletFromPrivateKey(await Deno.readTextFile("./me.sk"));
 
const validator = await readValidator();
 
// --- Supporting functions
 
async function readValidator(): Promise<SpendingValidator> {
  const validator = JSON.parse(await Deno.readTextFile("plutus.json"))
    .validators[0];
  return {
    type: "PlutusV2",
    script: toHex(cbor.encode(fromHex(validator.compiledCode))),
  };
}

Now, let's add the bits to unlock the funds in the contract. We'll need the transaction identifier (i.e. Tx ID) obtained when you ran the previous script (hello-world-lock.ts)

That transaction identifier (a.k.a. transaction hash), and the corresponding output index (here, 0) uniquely identify the UTxO (Unspent Transaction Output) in which the funds are currently locked. And that's the one we're about to unlock.

Note that we need to explicitly add a signer using .addSigner so that it gets added to the extra_signatories of our transaction—and becomes accessible for our script.

hello-world-unlock.ts
const utxo: OutRef = { txHash: Deno.args[0], outputIndex: 0 };
 
const redeemer = Data.to(new Constr(0, [utf8ToHex("Hello, World!")]));
 
const txHash = await unlock(utxo, {
  from: validator,
  using: redeemer,
});
 
await lucid.awaitTx(txHash);
 
console.log(`1 tADA unlocked from the contract
    Tx ID:    ${txHash}
    Redeemer: ${redeemer}
`);
 
// --- Supporting functions
 
async function unlock(
  ref: OutRef,
  { from, using }: { from: SpendingValidator; using: Redeemer }
): Promise<TxHash> {
  const [utxo] = await lucid.utxosByOutRef([ref]);
 
  const tx = await lucid
    .newTx()
    .collectFrom([utxo], using)
    .addSigner(await lucid.wallet.address())
    .attachSpendingValidator(from)
    .complete();
 
  const signedTx = await tx
    .sign()
    .complete();
 
  return signedTx.submit();
}

Run this script as usual, but this time, also passing the transaction id obtained from the previous command locking the funds. For example:

deno run --allow-net --allow-read --allow-env hello-world-unlock.ts 8559f57234407204d8e9a6bf57ef6943c65ec7119eb1c2ca6224f8bad8e71c1e

If everything worked as planned you should see something resembling the following output:

1 tADA unlocked from the contract
    Tx ID:    d3d5e828a3989691b0960d22a265c8c9ae4723134b52aa05ec0fb7d40f060392
    Redeemer: d8799f4d48656c6c6f2c20576f726c6421ff

And, tada 🎉!

We can inspect our redeeming transaction on CardanoScan and see that it successfully executed our Hello World contract.

Hello, World! - with Lucid

Covered in this tutorial

 Interact with a validator on the Preview network;
 Using PyCardano through Blockfrost;
 Getting test funds from the Cardano Faucet;
 Using web explorers such as CardanoScan.
Pre-requisites
We assume that you have followed the Hello, World!'s First steps and thus, have Aiken installed an ready-to-use. We will also use PyCardano, so make sure you have your dev environment ready for somePython (3).

You setup a new Python environment for PyCardano as follows:

python3 -m venv ./venv
source venv/bin/activate
pip install pycardano

Getting funds
For this tutorial, we will use the validator we built in First steps. Yet, before moving one, we'll need some funds, and a public/private key pair to hold them. We can generate a private key and an address using PyCardano.

Let's write our first script as generate-credentials.py:

generate-credentials.py
from pycardano import Address, Network, PaymentSigningKey, PaymentVerificationKey
 
signing_key = PaymentSigningKey.generate()
signing_key.save("me.sk")
 
verification_key = PaymentVerificationKey.from_signing_key(signing_key)
 
address = Address(payment_part=verification_key.hash(), network=Network.TESTNET)
with open("me.addr", "w") as f:
    f.write(str(address))

You can run the instructions above using:

python generate-credentials.py

Now, we can head to the Cardano faucet to get some funds on the preview network to our newly created address (inside me.addr).


👉 Make sure to select "Preview Testnet" as network.

Using CardanoScan we can watch for the faucet sending some ADA our way. This should be pretty fast (a couple of seconds).

Using the contract
Now that we have some funds, we can lock them in our newly created contract. We'll use PyCardano to construct and submit our transaction through Blockfrost.

This is only one example of possible setup using tools we love. For more tools, make sure to check out the Cardano Developer Portal!

Setup
First, we setup PyCardano with Blockfrost as a provider. This will allow us to let PyCardano handle transaction building for us, which includes managing changes. It also gives us a direct way to submit the transaction later on.

Create a file named hello-world-lock.py in the root of your project and add the following code:

hello-world-lock.py
from pycardano import (
    BlockFrostChainContext,
)
import os
 
context = BlockFrostChainContext(
    project_id=os.environ["BLOCKFROST_PROJECT_ID"],
    base_url="https://cardano-preview.blockfrost.io/api/",
)

Note that the highlighted line above looks for an environment variable named BLOCKFROST_PROJECT_ID which value must be set to your Blockfrost project id. You can define a new environment variable in your terminal by running (in the same session you're also executing the script!):

export BLOCKFROST_PROJECT_ID=preview...

Replace preview... with your actual project id.

Next, we'll need to read the validator from the blueprint (plutus.json) we generated earlier. We'll also need to convert it to a format that PyCardano understands. This is done by serializing the validator and then converting it to an hexadecimal text string as shown below:

hello-world-lock.py
from pycardano import (
    BlockFrostChainContext,
    PaymentSigningKey,
)
import json
import os
 
def read_validator() -> dict:
    with open("plutus.json", "r") as f:
        validator = json.load(f)
    script_bytes = PlutusV2Script(
        bytes.fromhex(validator["validators"][0]["compiledCode"])
    )
    script_hash = ScriptHash(bytes.fromhex(validator["validators"][0]["hash"]))
    return {
        "type": "PlutusV2",
        "script_bytes": script_bytes,
        "script_hash": script_hash,
    }
 
context = BlockFrostChainContext(
    project_id=os.environ["BLOCKFROST_PROJECT_ID"],
    base_url="https://cardano-preview.blockfrost.io/api/",
)
 
signing_key = PaymentSigningKey.load("me.sk")
 
validator = read_validator()

Locking funds into the contract
Now that we can read our validator, we can make our first transaction to lock funds into the contract. The datum must match the representation expected by the validator (and as specified in the blueprint), so this is a constructor with a single field that is a byte array.

As value for that byte array, we provide a hash digest of our public me. This will be needed to unlock the funds.

hello-world-lock.py
from dataclasses import dataclass
from pycardano import (
    Address,
    BlockFrostChainContext,
    Network,
    PaymentSigningKey,
    PaymentVerificationKey,
    PlutusData,
    PlutusV2Script,
    TransactionBuilder,
    TransactionOutput,
)
from pycardano.hash import (
    VerificationKeyHash,
    TransactionId,
    ScriptHash,
)
import json
import os
 
def read_validator() -> dict:
    with open("plutus.json", "r") as f:
        validator = json.load(f)
    script_bytes = PlutusV2Script(
        bytes.fromhex(validator["validators"][0]["compiledCode"])
    )
    script_hash = ScriptHash(bytes.fromhex(validator["validators"][0]["hash"]))
    return {
        "type": "PlutusV2",
        "script_bytes": script_bytes,
        "script_hash": script_hash,
    }
 
def lock(
    amount: int,
    into: ScriptHash,
    datum: PlutusData,
    signing_key: PaymentSigningKey,
    context: BlockFrostChainContext,
) -> TransactionId:
    # read addresses
    with open("me.addr", "r") as f:
        input_address = Address.from_primitive(f.read())
    contract_address = Address(
        payment_part = into,
        network=Network.TESTNET,
    )
 
    # build transaction
    builder = TransactionBuilder(context=context)
    builder.add_input_address(input_address)
    builder.add_output(
        TransactionOutput(
            address=contract_address,
            amount=amount,
            datum=datum,
        )
    )
    signed_tx = builder.build_and_sign(
        signing_keys=[signing_key],
        change_address=input_address,
    )
 
    # submit transaction
    return context.submit_tx(signed_tx)
 
@dataclass
class HelloWorldDatum(PlutusData):
    CONSTR_ID = 0
    owner: bytes
 
context = BlockFrostChainContext(
    project_id=os.environ["BLOCKFROST_PROJECT_ID"],
    base_url="https://cardano-preview.blockfrost.io/api/",
)
 
signing_key = PaymentSigningKey.load("me.sk")
 
validator = read_validator()
 
owner = PaymentVerificationKey.from_signing_key(signing_key).hash()
 
datum = HelloWorldDatum(owner=owner.to_primitive())
 
tx_hash = lock(
    amount=2_000_000,
    into=validator["script_hash"],
    datum=datum,
    signing_key=signing_key,
    context=context,
)
 
print(
    f"2 tADA locked into the contract\n\tTx ID: {tx_hash}\n\tDatum: {datum.to_cbor_hex()}"
)

You can run the excerpt above by executing:

python hello-world-lock.py

The above code requires you to:

have a BLOCKFROST_PROJECT_ID environment variable set. You can get one by signing up for a Blockfrost account.

have the file hello-world-lock.py placed at the root of your hello-world folder.

At this stage, your folder should looks roughly like this:

./hello_world
│
├── README.md
├── aiken.toml
├── plutus.json
├── generate-credentials.py
├── hello-world-lock.py
├── me.addr
├── me.sk
├── lib
│   └── ...
└── validators
    └── hello-world.ak

If everything went well, you should see something like this:

2 tADA locked into the contract
    Tx ID: 2ea959e4b51b2b6046931fab80957b39e534f1c954d326e506814d3ca47726c6
    Datum: d8799f581c1defd7502e25b312e48dc57712c434d317ea16a57728cd3c31828ea1ff

Inspecting the transaction
Now is a good moment to pause and have a look at CardanoScan. Here's an example of an Hello World transaction that we generated using this tutorial.

If you notice the small icon next to the contract output address, we can even inspect the datum:

d8799f581c10073fd2997d2f7dc6dadcf24966bd06b01930e5210e5de7aebf792dff
{
  "constructor": 0,
  "fields": [
    {
      "bytes": "1defd7502e25b312e48dc57712c434d317ea16a57728cd3c31828ea1"
    }
  ]
}

Unlocking funds from the contract
Finally, as a last step: we now want to spend the UTxO that is locked by our hello-world contract.

To be valid, our transaction must meet two conditions:

it must provide "Hello, World!" as a redeemer; and
it must be signed by the key referenced as datum (i.e the owner).
Let's make a new file hello-world-unlock.py and copy over some of the boilerplate from the first one.

hello-world-unlock.py
from pycardano import (
    BlockFrostChainContext,
    PaymentSigningKey,
)
import json
import os
 
def read_validator() -> dict:
    with open("plutus.json", "r") as f:
        validator = json.load(f)
    script_bytes = PlutusV2Script(
        bytes.fromhex(validator["validators"][0]["compiledCode"])
    )
    script_hash = ScriptHash(bytes.fromhex(validator["validators"][0]["hash"]))
    return {
        "type": "PlutusV2",
        "script_bytes": script_bytes,
        "script_hash": script_hash,
    }
 
context = BlockFrostChainContext(
    project_id=os.environ["BLOCKFROST_PROJECT_ID"],
    base_url="https://cardano-preview.blockfrost.io/api/",
)
 
signing_key = PaymentSigningKey.load("me.sk")
 
validator = read_validator()

Now, let's add the bits to unlock the funds in the contract. We'll need the transaction identifier (i.e. Tx ID) obtained when you ran the previous script (hello-world-lock.py)

That transaction identifier (a.k.a. transaction hash), and the corresponding output index (here, 0) uniquely identify the UTxO (Unspent Transaction Output) in which the funds are currently locked. And that's the one we're about to unlock. Since we know we have created a single UTxO, we'll take a little shortcut and simply look for the transaction id.

hello-world-unlock.py
from pycardano import (
    Address,
    BlockFrostChainContext,
    Network,
    PaymentSigningKey,
    UTxO,
)
import json
import os
import sys
 
def read_validator() -> dict:
    with open("plutus.json", "r") as f:
        validator = json.load(f)
    script_bytes = PlutusV2Script(
        bytes.fromhex(validator["validators"][0]["compiledCode"])
    )
    script_hash = ScriptHash(bytes.fromhex(validator["validators"][0]["hash"]))
    return {
        "type": "PlutusV2",
        "script_bytes": script_bytes,
        "script_hash": script_hash,
    }
 
def get_utxo_from_str(tx_id: str, contract_address: Address) -> UTxO:
    for utxo in context.utxos(str(contract_address)):
        if str(utxo.input.transaction_id) == tx_id:
            return utxo
    raise Exception(f"UTxO not found for transaction {tx_id}")
 
context = BlockFrostChainContext(
    project_id=os.environ["BLOCKFROST_PROJECT_ID"],
    base_url="https://cardano-preview.blockfrost.io/api/",
)
 
signing_key = PaymentSigningKey.load("me.sk")
 
validator = read_validator()
 
# get utxo to spend
utxo = get_utxo_from_str(sys.argv[1], Address(
    payment_part = validator["script_hash"],
    network=Network.TESTNET,
))

Finally, we can add the rest of the code and build a transaction that unlock the funds we previously locked. We'll need to construct a redeemer this time.

Note that we need to explicitly add a signer using .addSigner so that it gets added to the extra_signatories of our transaction -- and becomes accessible for our script.

Furthermore, .add_input_address is necessary to ensure the transaction builder adds inputs to cover for fees and collateral.

hello-world-unlock.py
from dataclasses import dataclass
from pycardano import (
    Address,
    BlockFrostChainContext,
    Network,
    PaymentSigningKey,
    PaymentVerificationKey,
    PlutusData,
    PlutusV2Script,
    Redeemer,
    TransactionBuilder,
    TransactionOutput,
    UTxO,
)
from pycardano.hash import (
    VerificationKeyHash,
    TransactionId,
    ScriptHash,
)
import json
import os
import sys
 
def read_validator() -> dict:
    with open("plutus.json", "r") as f:
        validator = json.load(f)
    script_bytes = PlutusV2Script(
        bytes.fromhex(validator["validators"][0]["compiledCode"])
    )
    script_hash = ScriptHash(bytes.fromhex(validator["validators"][0]["hash"]))
    return {
        "type": "PlutusV2",
        "script_bytes": script_bytes,
        "script_hash": script_hash,
    }
 
def unlock(
    utxo: UTxO,
    from_script: PlutusV2Script,
    redeemer: Redeemer,
    signing_key: PaymentSigningKey,
    owner: VerificationKeyHash,
    context: BlockFrostChainContext,
) -> TransactionId:
    # read addresses
    with open("me.addr", "r") as f:
        input_address = Address.from_primitive(f.read())
 
    # build transaction
    builder = TransactionBuilder(context=context)
    builder.add_script_input(
        utxo=utxo,
        script=from_script,
        redeemer=redeemer,
    )
    builder.add_input_address(input_address)
    builder.add_output(
        TransactionOutput(
            address=input_address,
            amount=utxo.output.amount.coin,
        )
    )
    builder.required_signers = [owner]
    signed_tx = builder.build_and_sign(
        signing_keys=[signing_key],
        change_address=input_address,
    )
 
    # submit transaction
    return context.submit_tx(signed_tx)
 
def get_utxo_from_str(tx_id: str, contract_address: Address) -> UTxO:
    for utxo in context.utxos(str(contract_address)):
        if str(utxo.input.transaction_id) == tx_id:
            return utxo
    raise Exception(f"UTxO not found for transaction {tx_id}")
 
@dataclass
class HelloWorldRedeemer(PlutusData):
    CONSTR_ID = 0
    msg: bytes
 
context = BlockFrostChainContext(
    project_id=os.environ["BLOCKFROST_PROJECT_ID"],
    base_url="https://cardano-preview.blockfrost.io/api/",
)
 
signing_key = PaymentSigningKey.load("me.sk")
 
validator = read_validator()
 
# get utxo to spend
utxo = get_utxo_from_str(sys.argv[1], Address(
    payment_part = validator["script_hash"],
    network=Network.TESTNET,
))
 
# build redeemer
redeemer = Redeemer(data=HelloWorldRedeemer(msg=b"Hello, World!"))
 
# execute transaction
tx_hash = unlock(
    utxo=utxo,
    from_script=validator["script_bytes"],
    redeemer=redeemer,
    signing_key=signing_key,
    owner=PaymentVerificationKey.from_signing_key(signing_key).hash(),
    context=context,
)
 
print(
    f"2 tADA unlocked from the contract\n\tTx ID: {tx_hash}\n\tRedeemer: {redeemer.to_cbor_hex()}"
)

Run this script as usual, but this time, also passing the transaction id obtained from the previous command locking the funds. For example:

python hello-world-unlock.py 2ea959e4b51b2b6046931fab80957b39e534f1c954d326e506814d3ca47726c6

If everything worked as planned you should see something resembling the following output:

2 tADA unlocked from the contract
    Tx ID:    d3d5e828a3989691b0960d22a265c8c9ae4723134b52aa05ec0fb7d40f060392
    Redeemer: 840000d8799f4d48656c6c6f2c20576f726c6421ff82198ee61a00bd3334

And, tada 🎉!

We can inspect our redeeming transaction on CardanoScan and see that it successfully executed our Hello World contract.

Hello, World! - with PyCardano

Armed with our recently acquired knowledge from the Hello, World! contract, let's increase the difficulty and write a slightly more challenging one.

A vesting contract is a common type of contract that allows to lock funds for a period of time, only to unlock them later -- once a specified time has passed. Usually, vesting contract defines a beneficiary who can be different from the original owner.

Covered in this tutorial

 Writing non-trivial Aiken validators, with complex datums.
 Using more advanced Aiken features (type-aliases, pattern-matches)
 Writing unit tests using Aiken's built-in test framework
 Managing time on-chain through transaction validity ranges
When encountering an unfamiliar syntax or concept, do not hesitate to refer to the language-tour for details and extra examples.

Setup
In a similar fashion to what we did for the Hello, World! contract, we'll need some credentials (and funds) to play around with. Here, we define an extra key for the beneficiary. Again, use the Cardano faucet to receive test funds. Refer to Hello, World! :: Getting Funds in case you have any doubts on the procedure.

generate-credentials.ts
import { Lucid } from "https://deno.land/x/lucid@0.8.3/mod.ts";
 
const lucid = await Lucid.new(undefined, "Preview");
 
const ownerPrivateKey = lucid.utils.generatePrivateKey();
await Deno.writeTextFile("owner.sk", ownerPrivateKey);
 
const ownerAddress = await lucid
  .selectWalletFromPrivateKey(ownerPrivateKey)
  .wallet.address();
await Deno.writeTextFile("owner.addr", ownerAddress);
 
const beneficiaryPrivateKey = lucid.utils.generatePrivateKey();
await Deno.writeTextFile("beneficiary.sk", beneficiaryPrivateKey);
 
const beneficiaryAddress = await lucid
  .selectWalletFromPrivateKey(beneficiaryPrivateKey)
  .wallet.address();
await Deno.writeTextFile("beneficiary.addr", beneficiaryAddress);

You can run the instructions above using Deno via:

deno run --allow-net --allow-write generate-credentials.ts

On-Chain code
Let's write our time lock validator as validators/vesting.ak, starting with the definition of its interface (i.e. its datum's shape).

validators/vesting.ak
use aiken/hash.{Blake2b_224, Hash}
use aiken/transaction/credential.{VerificationKey}
 
type Datum {
  /// POSIX time in second, e.g. 1672843961000
  lock_until: POSIXTime,
  /// Owner's credentials
  owner: VerificationKeyHash,
  /// Beneficiary's credentials
  beneficiary: VerificationKeyHash,
}
 
type VerificationKeyHash =
  Hash<Blake2b_224, VerificationKey>
 
type POSIXTime =
  Int

As we can see the script's datum serves as configuration and contains the different parameters of our vesting operation. Remember that these elements are set when locking funds in the contract; combined with the script they define the conditions by which the funds can be released.

From there, lets define the spend validator itself.

validators/vesting.ak
use aiken/interval.{Finite}
use aiken/list
use aiken/transaction.{Transaction, ScriptContext, Spend, ValidityRange}
 
validator {
  fn vesting(datum: Datum, _redeemer: Void, ctx: ScriptContext) {
    // In principle, scripts can be used for different purpose (e.g. minting
    // assets). Here we make sure it's only used when 'spending' from a eUTxO
    when ctx.purpose is {
      Spend(_) ->
        or {
          must_be_signed_by(ctx.transaction, datum.owner),
          and {
            must_be_signed_by(ctx.transaction, datum.beneficiary),
            must_start_after(ctx.transaction.validity_range, datum.lock_until),
          },
        }
      _ -> False
    }
  }
}
 
fn must_be_signed_by(transaction: Transaction, vk: VerificationKeyHash) {
  list.has(transaction.extra_signatories, vk)
}
 
fn must_start_after(range: ValidityRange, lock_expiration_time: POSIXTime) {
  when range.lower_bound.bound_type is {
    Finite(tx_earliest_time) -> lock_expiration_time <= tx_earliest_time
    _ -> False
  }
}

The novelty here mostly lies in the check against a time period. In fact, transactions can have validity intervals that define from when and until when the transaction is considered valid. Validity bounds are checked by the ledger prior to executing a script and only does so if the bounds are legit.

This is meant to give scripts a notion of time, while preserving determinism from within the context of a script. For example, in this scenario, given a lower bound A on the transaction, we can deduce that the current time is at least A.

Note that because we don't control the upper-bound, it could very much be that this transaction is executed 30 years after the vesting delay. Yet, from the perspective of the vesting script, this is perfectly okay.

See also how we annotate the redeemer to Void to indicate that it isn't used. We could also leave it unannotated but it's generally good to signal your intent explicitly. Void captures that pretty well.

Testing
Okay, now before deploying our contract in the wild and risking collapsing the economy with some unforeseen bug, let's write a few tests. Aiken has builtin support for tests, which are very much like functions that takes no argument and must return a Bool.

Tests can use any function, constant or types defines in our module but beware, they cannot reference other tests!

validators/vesting.ak
use aiken/interval.{Finite, Interval, IntervalBound, PositiveInfinity}
 
test must_start_after_succeed_when_lower_bound_is_after() {
  must_start_after(interval.after(2), 1)
}
 
test must_start_after_succeed_when_lower_bound_is_equal() {
  must_start_after(interval.after(2), 2)
}
 
test must_start_after_fail_when_lower_bound_is_before() {
  !must_start_after(interval.after(2), 3)
}

You can run tests with aiken check; Aiken will collect and run all tests found in your modules, and give you some statistics about the execution units (CPU and memory) required by the test.

Building
It's now time to build our on-chain contract! Simply do:

aiken build

This generate a CIP-0057 Plutus blueprint as plutus.json at the root of your project. This blueprint describes your on-chain contract and its binary interface. In particular, it contains the generated on-chain code that will be executed by the ledger, and a hash of your validator(s) that can be used to construct addresses.

Let's see the validator in action!

Off-Chain code
As a starter, we need to lock funds in our newly created contract. We'll use Lucid to construct and submit our transaction through Blockfrost.

This is only one example of possible setup using tools we love. For more tools, make sure to check out the Cardano Developer Portal!

Setup
First, we setup Lucid with Blockfrost as a provider. You know the drill from the Hello, World! example already.

vesting_lock.ts
import {
  Blockfrost,
  C,
  Data,
  Lucid,
  SpendingValidator,
  TxHash,
  fromHex,
  toHex,
} from "https://deno.land/x/lucid@0.8.3/mod.ts";
import * as cbor from "https://deno.land/x/cbor@v1.4.1/index.js";
 
const lucid = await Lucid.new(
  new Blockfrost(
    "https://cardano-preview.blockfrost.io/api/v0",
    Deno.env.get("BLOCKFROST_API_KEY"),
  ),
  "Preview",
);
 
lucid.selectWalletFromPrivateKey(await Deno.readTextFile("./owner.sk"));
 
const validator = await readValidator();
 
// --- Supporting functions
 
async function readValidator(): Promise<SpendingValidator> {
  const validator = JSON.parse(await Deno.readTextFile("plutus.json")).validators[0];
  return {
    type: "PlutusV2",
    script: toHex(cbor.encode(fromHex(validator.compiledCode))),
  };
}

If you've installed deno, you can run the except above by executing:

deno run --allow-net --allow-read --allow-env vesting_lock.ts

It assumes that this file (vesting_lock.ts) is placed at the root of your vesting folder. At this stage, your folder should looks roughly like this:

./vesting
│
├── README.md
├── aiken.toml
├── plutus.json
├── vesting_lock.ts
├── owner.addr
├── owner.sk
├── beneficiary.addr
├── beneficiary.sk
├── lib
│   └── ...
└── validators
    └── vesting.ak

Locking funds into the contract
Here, we make our first transaction to lock funds into the contract. The datum must match the representation expected by the script, constructor is an object expecting 3 fields.

vesting_lock.ts
const ownerPublicKeyHash = lucid.utils.getAddressDetails(
  await lucid.wallet.address()
).paymentCredential.hash;
 
const beneficiaryPublicKeyHash =
  lucid.utils.getAddressDetails(await Deno.readTextFile("beneficiary.addr"))
    .paymentCredential.hash;
 
const Datum = Data.Object({
  lock_until: Data.BigInt, // this is POSIX time, you can check and set it here: https://www.unixtimestamp.com
  owner: Data.String, // we can pass owner's verification key hash as byte array but also as a string
  beneficiary: Data.String, // we can beneficiary's hash as byte array but also as a string
});
 
type Datum = Data.Static<typeof Datum>;
 
const datum = Data.to<Datum>(
  {
    lock_until: 1672843961000n, // Wed Jan 04 2023 14:52:41 GMT+0000
    owner: ownerPublicKeyHash, // our own wallet verification key hash
    beneficiary: beneficiaryPublicKeyHash,
  },
  Datum
);
 
const txLock = await lock(1000000, { into: validator, datum: datum });
 
await lucid.awaitTx(txLock);
 
console.log(`1 tADA locked into the contract
    Tx ID: ${txLock}
    Datum: ${datum}
`);
 
// --- Supporting functions
 
async function lock(lovelace, { into, datum }): Promise<TxHash> {
  const contractAddress = lucid.utils.validatorToAddress(into);
 
  const tx = await lucid
    .newTx()
    .payToContract(contractAddress, { inline: datum }, { lovelace })
    .complete();
 
  const signedTx = await tx.sign().complete();
 
  return signedTx.submit();
}

Unlocking funds from the contract
Now we can use another wallet (beneficiary.sk). This wallet will be beneficiary wallet had been added into datum in the previous step (locking) as well.

Finally, as a last step: we now want to spend the UTxO that is locked by our vesting contract.

To be valid, our transaction must meet one of two conditions:

it must be signed by the owner referenced as "owner" in the datum; or
it must be signed by the beneficiary referenced as "beneficiary" in the datum AND time has to pass beyond the threshold we fixed -- that is it needs to be later than 'Wed Jan 04 2023 14:52:41 GMT+0000'.
Like for the Hello, World! example, we need to explicitly add a signer using .addSigner so that it gets added to the extra_signatories of our transaction and becomes accessible for our script.

In addition we need to specify .validFrom as a POSIX timestamp from where transaction is considered valid (should be by the time we submit it). We can optionally defined an upper validity bound using .validTo as a TTL (Time-To-Live).

Let's make a new file vesting_unlock.ts and copy over some of the boilerplate from the first one.

vesting_unlock.ts
import {
  Blockfrost,
  C,
  Data,
  Lucid,
  SpendingValidator,
  TxHash,
  fromHex,
  toHex,
} from "https://deno.land/x/lucid@0.8.3/mod.ts";
import * as cbor from "https://deno.land/x/cbor@v1.4.1/index.js";
 
const lucid = await Lucid.new(
  new Blockfrost(
    "https://cardano-preview.blockfrost.io/api/v0",
    Deno.env.get("BLOCKFROST_API_KEY"),
  ),
  "Preview",
);
 
lucid.selectWalletFromPrivateKey(await Deno.readTextFile("./beneficiary.sk"));
 
const beneficiaryPublicKeyHash = lucid.utils.getAddressDetails(
  await lucid.wallet.address()
).paymentCredential.hash;
 
const validator = await readValidator();
 
// --- Supporting functions
 
async function readValidator(): Promise<SpendingValidator> {
  const validator = JSON.parse(await Deno.readTextFile("plutus.json")).validators[0];
  return {
    type: "PlutusV2",
    script: toHex(cbor.encode(fromHex(validator.compiledCode))),
  };
}

Now, let's add the bits to unlock the funds in the contract. We'll need the transaction identifier obtained when you ran the previous script (vesting_lock.ts)

That transaction identifier, and the corresponding output index (here, 0) uniquely identifies the UTxO (Unspent Transaction Output) in which the funds are currently locked. And that's the one we're about to unlock.

As we stated above, we need to make sure to only submit our transaction after the vesting delay has passed without what the node will simply reject the transaction (without charging any fee) and kindly ask us to re-submit the transaction at a later time.

vesting_unlock.ts
// ^^^ Code above is unchanged. ^^^
 
const scriptAddress = lucid.utils.validatorToAddress(validator);
 
// we get all the UTXOs sitting at the script address
const scriptUtxos = await lucid.utxosAt(scriptAddress);
 
const Datum = Data.Object({
  lock_until: Data.BigInt, // this is POSIX time, you can check and set it here: https://www.unixtimestamp.com
  owner: Data.String, // we can pass owner's verification key hash as byte array but also as a string
  beneficiary: Data.String, // we can beneficiary's hash as byte array but also as a string
});
 
type Datum = Data.Static<typeof Datum>;
 
const currentTime = new Date().getTime();
 
// we filter out all the UTXOs by beneficiary and lock_until
const utxos = scriptUtxos.filter((utxo) => {
    let datum = Data.from<Datum>(
      utxo.datum,
      Datum,
    );
 
    return datum.beneficiary === beneficiaryPublicKeyHash &&
      datum.lock_until <= currentTime;
});
 
if (utxos.length === 0) {
  console.log("No redeemable utxo found. You need to wait a little longer...");
  Deno.exit(1);
}
 
// we don't have any redeemer in our contract but it needs to be empty
const redeemer = Data.empty();
 
const txUnlock = await unlock(utxos, currentTime, { from: validator, using: redeemer });
 
await lucid.awaitTx(txUnlock);
 
console.log(`1 tADA recovered from the contract
    Tx ID: ${txUnlock}
    Redeemer: ${redeemer}
`);
 
// --- Supporting functions
 
async function unlock(utxos, currentTime, { from, using }): Promise<TxHash> {
  const laterTime = new Date(currentTime + 2 * 60 * 60 * 1000).getTime(); // add two hours (TTL: time to live)
 
  const tx = await lucid
    .newTx()
    .collectFrom(utxos, using)
    .addSigner(await lucid.wallet.address()) // this should be beneficiary address
    .validFrom(currentTime)
    .validTo(laterTime)
    .attachSpendingValidator(from)
    .complete();
 
  const signedTx = await tx
    .sign()
    .complete();
 
  return signedTx.submit();
}

As you imagine, we can run this script with the following incantation:

deno run --allow-net --allow-read --allow-env vesting_unlock.ts

Assuming everything went well... congratulations 🎉!

Vesting

Gift Card

Examples : Hello, World!

One key feature of Aiken is how it helps you manipulate Untyped Plutus Core (abbrev. UPLC in short). UPLC is ultimately the format whereby codes gets executed on-chain. This is pretty-much as low-level as you can get when it comes to Cardano smart contracts. Note however that on-chain, UPLC code is encoded in a binary encoding for conciseness.

Understanding how UPLC works, and having the right tools to troubleshoot UPLC programs can be handy when developing contracts on Cardano. Fortunately, this is something Aiken can help you with.

Aiken <-> Plutus compileation pipeline diagram
While UPLC has erased any explicit notion of types; functions, variables and constants are still implicitly typed and, an interpreter will raise errors when encountering a type mismatch.

For the sake of simplicity, we might speak about the type-signature of builtin functions such as addInteger which, in principle, only has a concrete meaning in Typed Plutus Core. Hence, even though they are untyped, we often think of UPLC programs has having implicit types, as if they were originally typed programs whose types had simply been erased (in fact, that's exactly what they are).

Untyped Plutus Core

Let's start with a little reminder about the syntax. The complete syntax for Untyped Plutus Core comes from the original Formal Specification of the Plutus Core Language.

Primitive Types
Plutus Core has 7 primitive types (a.k.a. constants): unit, bool, integer, bytestring, string, pair and list. One can construct constants using the con keyword, followed by the name of the primitive type and its value.

Unit is denoted ();
Bool are True or False;
Bytestrings are denoted with a leading # followed by an hexadecimal sequence;
Strings are UTF-8 text strings, between double quotes " ";
Pair and lists are encapsulated between brackets [ and ].
Note that each constant is named after its type. For pairs and lists -- which are compound types --, the type of their elements is specified between chevrons < and >.

Primitive Type	Example
unit	con unit ()
bool	con bool True
integer	con integer 42
bytestring	con bytestring #41696b656e
string	con string "Aiken"
pair	con pair<bool, integer> [True, 42]
list	con list<bytestring> [#00, #aa]
Functions
A function (or simply, lambda) is constructed with the keyword lam followed by a variable name, and a term (i.e. a constant, another function, etc..). One can apply variables to a function using squared brackets [ ].

For example: [ (lam x x) (con integer 42) ].

This little excerpt constructs a function that takes an argument x and returns it; to which we immediately apply the constant 42. If we were to evaluate this program, it would simply output: 42.

Builtins
Plutus Core comes with a set of builtins functions which comes in handy to define certain operations. Incidentally, there's no operator even for basic arithmetic operations, everything comes as a builtin.

You'll notice also that some builtins are very domain specific and tailored to operations you'd expect a smart contract to perform on a blockchain. Hence, new builtins may be added in the future to address specific use cases that emerge.

Builtins are called with the keyword builtin followed by their names. They may take one, two, three or really any number of arguments. Here is the complete list of builtin functions.

Delay & Force
Plutus Core has the notion of type abstractions and type instantiations. That is, like lambdas are functions over term values, abstractions are functions over types. These abstractions allow to represent polymorphic types (such as, a list of elements, or an option type). UPLC has gotten rid of the types, but introduces two new keywords in order to preserve the abstractions in some form.

force can be used on a polymorphic function to instantiate one type-parameter. For example, the branches of a builtin ifThenElse can be of any type -- though they have to be the same for both branches. In fact, ifThenElse has one type parameter. To be called, it must therefore be forced once: [ [ [ (force (builtin ifThenElse)) p ] x ] y ]

Similarly, delay can be used to defer the evaluation of a certain term; this allows to artificially construct or preserve type abstractions, but also, to introduce a certain level of laziness in parts of the program.

Data
In addition to primitive types, Plutus Core also has a more generalized data data-type which is meant to represent any possible data-type in a program.

TODO: Give additional detail about how the serialization is done and how to construct a Data.

In particular, revisit after #34 since the introduction of "list" and "pair" keywords may come in handy.

Programs
Finally, UPLC programs are wraps in a program declaration, which indicates the version (e.g. 1.0.0) of Plutus Core that this programs uses. You don't have to worry about that too much. Aiken supports the latest Plutus version (2.0.0).

Syntax

Evaluation
Let's consider the following basic program:

program_1.uplc

(program
  1.0.0
  [ [ (builtin addInteger) (con integer 16) ] (con integer 26) ]
)

We can evaluate this program using Aiken's cli via:

aiken uplc eval program_1.uplc

{
  "result": "(con integer 42)",
  "cpu": 321577,
  "mem": 602
}

The output indicates the result of the evaluation (42) as well as the execution cost of that program, both in terms of CPU and memory usage.

Note that the command also accepts arguments. So, for example, if we modify our program into a function that accepts an argument as follows:

program_2.uplc

(program
  1.0.0
  (lam x [ [ (builtin addInteger) (con integer 16) ] x ])
)

You can then instrument Aiken to provide arguments upon calling the program by simply appending them to the eval command:

aiken uplc eval program_2.uplc "(con integer 26)"

{
  "result": "(con integer 42)",
  "cpu": 390577,
  "mem": 902
}

Formatting
Because writing UPLC by hand can be a tedious task, Aiken provides a quick way to automatically format a UPLC program via the fmt command. By default, the command override the file given as input, but you can also simply prints the result to stdout using --print. For example:

aiken uplc fmt program_2.uplc --print

(program
  1.0.0
  (lam x [ [ (builtin addInteger) (con integer 16) ] x ])
)

Converting to/from binary encoding
So far, we've been representing UPLC programs using a high-level syntax. In practice, however, UPLC programs are encoded into compact binary strings when submitted on-chain (using flat).

Aiken provides utilities to convert a high-level UPLC program into a low-level flat encoding − and vice-versa, via the encode and decode commands. For example:

aiken uplc encode program_1.uplc --hex

01000023370090100009

The encode command prints everything on stdout and --hex turns the bytes into a hex encoded string so that we can read it.

aiken uplc encode program_1.uplc > program_1.flat

sends the raw "flat" bytes to a file named program_1.flat

From there, one can recover a UPLC high-level syntax from a flat program using unflat as such:

aiken uplc decode program_1.flat

(program
  1.0.0
  [ [ (builtin addInteger) (con integer 16) ] (con integer 26) ]
)

COMMAND-LINE UTILITIES 

Builtins	Type Args	Term Args	Result
ifThenElse1	(α)	(bool, (α), (α))	α
addInteger	-	(integer, integer)	integer
subtractInteger	-	(integer, integer)	integer
multiplyInteger	-	(integer, integer)	integer
divideInteger	-	(integer, integer)	integer
modInteger	-	(integer, integer)	integer
quotientInteger	-	(integer, integer)	integer
remainderInteger	-	(integer, integer)	integer
equalsInteger	-	(integer, integer)	bool
lessThanInteger	-	(integer, integer)	bool
lessThanEqualsInteger	-	(integer, integer)	bool
appendString	-	(string, string)	string
equalsString	-	(string, string)	bool
encodeUtf8	-	(string)	bytestring
appendByteString	-	(bytestring, bytestring)	bytestring
consByteString	-	(integer, bytestring)	bytestring
indexByteString	-	(bytestring, integer)	integer
sliceByteString	-	(integer, integer, bytestring)	bytestring
lengthOfByteString	-	(bytestring)	integer
equalsByteString	-	(bytestring, bytestring)	bool
lessThanByteString	-	(bytestring, bytestring)	bool
lessThanEqualsByteString	-	(bytestring, bytestring)	bool
decodeUtf8	-	(bytestring)	string
chooseData2	(α)	(data, (α), (α), (α), (α), (α))	α
constrData	-	(integer, list data)	data
unConstrData	-	data	(integer, list data)
iData	-	(integer)	data
unIData	-	(data)	integer
bData	-	(bytestring)	data
unBData	-	(data)	bytestring
mapData	-	(list (pair data data))	data
unMapData	-	(data)	list (pair data data)
listData	-	(list data)	data
unListData	-	(data)	list data
equalsData	-	(data, data)	bool
serialiseData	-	(data)	bytestring
chooseList3	(α, β)	(list (α), (β), (β))	β
mkNilData	-	(unit)	list (data)
mkNilPairData	-	(unit)	list (pair data data)
mkCons	(α)	((α), list (α))	list (α)
headList	(α)	(list (α))	α
tailList	(α)	(list (α))	list (α)
nullList	(α)	(list (α))	bool
mkPairData	-	(data, data)	pair (data) (data)
fstPair	(α, β)	pair (α) (β)	α
sndPair	(α, β)	pair (α) (β)	β
sha2_256	-	(bytestring)	bytestring
sha3_256	-	(bytestring)	bytestring
blake2b_256	-	(bytestring)	bytestring
verifyEd25519Signature4	-	(bytestring, bytestring, bytestring)	bool
verifyEcdsaSecp256k1Signature4	-	(bytestring, bytestring, bytestring)	bool
verifySchnorrSecp256k1Signature4	-	(bytestring, bytestring, bytestring)	bool
trace	(α)	(string, (α))	α
Footnotes
Returns the second argument when the predicate is True, and the third argument when False. ↩

Each argument corresponds to each of the constructors of a builtin data (in this order): constr, map, list, integer and bytestring. The evaluation will continue with whatever branch actually corresponds to the given term value. ↩

Returns the second argument when the list is empty, and the third argument otherwise. ↩

Arguments are respectively: the public key, the message and the signature ↩ ↩2 ↩3

Builtins

Advanced

Within the Cardano community there has been a flourishing ecosystem of alternative languages for writing smart contracts. So naturally, one might ask about the differences between these and which they should use for their use case. There is also a big misconception about how writing smart contracts actually works on Cardano. In this document, we'll list some of the main alternatives along with their differences and similarities. Before we get into this though, let's discuss the misconception first so everyone is on the same page.

The Misconception
Cardano uses Haskell for smart contracts

This is not entirely true.

The main Cardano node implementation does indeed happen to be written in Haskell. The virtual machine for executing smart contracts that comes baked into the node is then of course also implemented in Haskell. But that does not mean that it is Haskell itself which is executed by the smart contract virtual machine. Aiken actually has a fully working version of this virtual machine written in Rust.

So what's going on here? What is actually being executed?

Well, there is something called Untyped Plutus Core which is the lowest level representation of a smart contract and it is this low level representation that actually gets executed by the virtual machine. So contrary to popular knowledge, there isn't actually a coupling to Haskell. Armed with this knowledge one may now ask another question:

So what am I writing when I write Plutus?

In the wild, Plutus tends to refer to one of three things:

Plutus Core, the low-level interpreted code that is executed by the Cardano virtual machine.
PlutusTx, a Haskell framework that compiles to Plutus Core through the means of a GHC plugin.
The Plutus Platform, which more broadly includes Plutus Core, PlutusTx and most of the tools developed around Plutus Core.
Most of the time, when people say Plutus, they mean PlutusTx, which has led to a popular belief that Plutus is in fact Haskell.

PlutusTx being built as a GHC plugin means that you even use Haskell tooling like cabal for it. Even so, you are technically not writing Haskell. Code that one writes using PlutusTx is consumed by the plugin and then transformed into Untyped Plutus Core. Essentially, it takes the intermediate representation of Haskell, GHC Core, and turns that into Untyped Plutus Core. This results in not needing to write a new parser and type checker. What you end up with is a kind of embedded language that looks and feels like Haskell but the target runtime is not GHC.

The Alternatives
Now that this misconception is out of the way it should be possible to see how other new languages can be created that ultimately compile to Untyped Plutus Core. The current alternatives range from full blown new languages to embedded Domain Specific Languages (abbrev. eDSLs.) Here is a list of the main ones:

Aiken
opshin
Helios
Plutarch
plu-ts
Scalus
The creators of each of these projects all know each other and are in open communication with each other.

Aiken
Aiken is a brand new language with it's own syntax and compiler. It is not Rust. The compiler happens to be written in Rust but it is not Rust. Not only is Aiken a compiler for a new language but we've also developed everything in such a way that all the libraries we created in Rust are re-usable by people interested in doing more low-level things. One example of this is Lucid, which uses Aiken's uplc crate to evaluate transactions before submission to calculate exact redeemer ExUnits without using a node, ogmios, or blockfrost.

As a language, Aiken is purely functional with static typing and type inference. This means most of the time the compiler is smart enough to know what the type of something is without you annotating it. It also let's you make custom types that are similar to records and enums. It does not have higher-kinded types or typeclasses because Aiken aims for simplicity. Writing smart contracts can be tedious, and we therefore believe that a language should remain simple to avoid silly mistakes.

On-chain scripts are typically small in size and scope (relatively, compared to other kind of applications being written nowadays) and, therefore, do not require as much features as general-purpose languages that have to solve much harder problems.

That being said Aiken may introduce more elaborate language features (such as type classes/traits) at a later time if it's found that they are extremely useful to developers.

OpShin
OpShin allows you to write Smart Contracts in 100% valid but restricted Python3. Since it uses normal Python, you have all the features that come with developing on Python, including widespread editor support, language servers, linters, testing frameworks and verification tools. It implements it's own type system and at compile time checks the types to be correct.

As part of its development, python packages for uplc and pluto have been externalized and are available for anyone that wants to build UPLC tooling in Python (such as optimizers).

Helios
Helios is also a brand new language. One notable implementation difference is that it's compiler is written in a single javascript file without dependencies. According to the creator, the intention of that was to make the compiler implementation easier to audit.

As a language, Helios is also purely functional but has limited type inference. It also supports custom types similar to records and enums.

Another interesting thing is that because the compiler is a single javascript file it's pretty easy to use Helios from within a javascript project.

Plutarch
Plutarch is not a new language. You can consider it an eDSL for creating smart contracts with Haskell. In some ways, Plutarch is what PlutusTx should have been. There is no Template Haskell involved.

Since Plutarch is just Haskell, you have everything available to you. Type inference, typeclasses, higher-kinded types, etc.

plu-ts
plu-ts is not a new language. You can consider it an eDSL for creating smart contracts with Typescript. Because of this it's a bit closer to Plutarch conceptually than Aiken or Helios.

It implements it's own type system and at compile time (js runtime) checks the types to be correct.

Scalus
A Scala implementation of Plutus.

Scalus is a set of libraries to work with Cardano Untyped Plutus Core that works on both JVM and JavaScript. This includes:

Untyped Plutus Core (UPLC) data types and functions
Flat, CBOR, JSON serialization
CEK UPLC evaluation machine including execution cost calculation
UPLC parser and pretty printer
Type safe UPLC expression builder, think of Plutarch
Macros to generate UPLC code from Scala code, think of PlutusTx but simpler
Which should you use?
Only you can decide for yourself which of these fits your needs the best. Each has made some different decisions around design and implementation. Aiken and Helios are on the new language end of the spectrum while Plutarch and plu-ts are on the eDSL end. Plutarch has the most expressive type system while Aiken's types are in between Plutarch and Helios.

Embedded DSLs are nice because they integrate seamlessly with off-chain code and usually allow to reuse existing tools that already work on the host language.

New languages are nice because they include bespoke checks and functionality specifically for Cardano smart contracts directly in their compilers. While they demand a lot of the tooling to be created anew, they also give the opportunity to address shortcomings of existing tooling in various languages.

Which best serves your use case is for you to say. Being the maintainers behind Aiken, we can't be fully partial in providing an unbiaised answer. We encourage you to review the documentation, design decisions and overall project to make an informed decision.

Ecosystem Overview

Exploring Cardano
Cardano Foundation's education course
The Developer Portal
The Cardano Ledger (specs & CDDLs)
Aiken for Amateurs
Hello World with Mesh
Software Development Kit
Language	Link
C#	CardanoSharp
Haskell	Cardano API
Java/Scala	Bloxbean
JavaScript	Mesh.js
Python	PyCardano
Rust	Pallas, naumachia
TypeScript	Lucid, Mesh
Infrastructure
Demeter (cloud-based infrastructure for Cardano)
Maestro
Blockfrost (API query layer)
Koios (API query layer)
TangoCrypto (API query layer)
Building & Maintaining Aiken
Below is a list of links to resources we used while building Aiken.

The Gleam's compiler
The Official Plutus documentation
The source code about encoding/Decoding UPLC
The source code about core types
The original (albeit outdated) Plutus Core specification

AIKEN

Course Details

Level

Ratings

Modules

Lessons

Holder $WORK Price

Contact Us

Documentation

Navigation