CLVM is the compiled, minimal version of ChiaLisp that is used by the Chia network. The full set of operators is documented here
This guide will cover the basics of the language and act as an introduction to the structure of programs. You should be able to follow along by running a version of clvm_tools.
In ChiaLisp everything is either a list or an atom. Lists take the form of parentheses and each entry in the list is single spaced.
Atoms are either literal binary blobs or variables. A program is actually just a list in polish notation.
There is no distinguishing of variable types in ChiaLisp.
This means that
(100 0x65 0x68656c6c6f) and
(0x64 101 'hello') are equivalent lists.
Internally however the blobs can be interpreted in a number of different ways, which we will cover later.
There are no support for floating point numbers in ChiaLisp, only integers. Internally integers are interpreted as 256 bit signed integers.
The math operators are
You may have noticed that the multiplication example above takes more than two parameters in the list.
This is because many operators can take a variable number of parameters.
* are commutative so the order of parameters does not matter.
For non-commutative operations,
(- (q 100) (q 30) (q 20) (q 5)) is equivalent to
(- (q 100) (+ (q 30) (q 20) (q 5))).
(/ 120 5 4 2) is equivalent to
(/ 120 (* 5 4 2)).
There is also support for negative values.
To use hexadecimal numbers, simply prefix them with
The final mathematical operator is equal which acts similarly to == in other languages.
As you can see above this language interprets some data as boolean values.
In this language an empty list
() evaluate to
Any other value evaluates to
True, though internally
True is represented with
The exception to this rule is
0 is exactly the same as
i operator takes the form
(i A B C) and acts as an if-statement that
A is True and
Note that both
C are evaluated eagerly, just like all subexpressions.
To defer evaluation until after the condition,
C must be quoted (with
q), and then evaluated with double parentheses, e.g.
Now seems like a good time to clarify further about lists and programs.
A list is any space-separated, ordered group of one or more elements inside brackets.
(70 80 90 100),
(0xf00dbabe 48 "hello"), and
(90) are all valid lists.
Lists can even contain other lists, such as
("list" "list" ("sublist" "sublist" ("sub-sublist")) "list").
Programs are a subset of lists which can be evaluated using CLVM.
In order for a list to be a valid program:
- 1. The first item in the list must be a valid operator
- 2. Every item after the first must be a valid program
This is why literal values and non-program lists must be quoted using
Note: There is a special case where the first item in a program is also a program, which we will cover in more detail later.
Programs can contain non-program lists, but they also must be quoted, for example:
And now that we know we can have programs inside programs we can create programs such as:
Programs in ChiaLisp tend to get built in this fashion. Smaller programs are assembled together to create a larger program. It is recommended that you create your programs in an editor with brackets matching!
f returns the first element in a passed list.
r returns every element in a list except for the first.
c prepends an element to a list
And we can use combinations of these to access or replace any element we want from a list:
Up until now our programs have not had any input or variables, however ChiaLisp does have support for a kind of variable which is passed in through a solution.
It's important to remember that the context for ChiaLisp is for use in locking up coins with a puzzle program. This means that we need to be able to pass some information to the puzzle.
A solution is a list of values passed to the puzzle.
In the higher level language the solution can be referenced with
Note the use of
And remember lists can be nested too.
These environment variables can be used in combination with all other operators.
This program checks that the second variable is equal to the square of the first variable.
In the above examples we were using
run, calling the higher level language, instead of
brun for the lower level language.
This is because for the sake of minimalism in the lower level CLVM language, we address the solution with evaluated integers.
1 accesses the root of the tree and returns the entire solution list.
After that, you can imagine a binary tree of
r, where each node is numbered.
And this is designed to work when there are lists inside lists too.
And so on.
This marks the end of this section of the guide. In this section we have covered many of the basics of using ChiaLisp. It is recommended you play with using the information presented here for a bit before moving on.
This guide has not covered all of the operators available in ChiaLisp - try using some of the other ones listed here.