Getting started

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 (opens in a new tab);
• 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 (opens in a new tab) and explore tutorials, courses or projects that catch your attention;
• Explore the language-tour;
• Join the #aiken channel on Discord (opens in a new tab) and follow us (opens in a new tab) 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 (opens in a new tab) 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:

# [Optional - if 'members' is present]
#
# Project's name, as {organisation}/{repository}
name = "foo/bar"
 
# [Optional - if 'members' is present]
#
# 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]
#
# A list of folders to look for Aiken projects. See Workspaces below.
members = ["."]
 
# [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

Workspaces

Aiken has minimal support for workspaces (a.k.a. monorepos). This is enabled using the members configuration fields in an aiken.toml file at the root of a project.

members = ["pkgs/my_library", "pkgs/my_validators"]

Globs are supported so it is possible to do this:

members = ["pkgs/*"]

Note also that, other configuration fields are ignored when members is present.

Caveats

• This does not support referencing local dependencies by path (yet)
• Dependencies are not intelligently resolved and cached once. Each sub-project gets it's own build/ folder with dependencies redundantly fetched for now.
• The LSP is not yet aware of this configuration option and may behave strangely.

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 (opens in a new tab) 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 (opens in a new tab) and at the bottom of this website.