clvm.org

clvm

Introduction

Cryptocurrency depends upon digital signatures corresponding to public keys. But what exactly do the digital signatures sign?

In bitcoin, coins are grouped into a “utxo”, which are protected by a “puzzle program” (known in bitcoin as “pubkey script”). This puzzle program generally lists one or more public keys, and to spend the coins in the utxo, these keys must sign a hash of a message derived from the spending transaction. Exactly how the message is derived can be chosen from several options depending on which parts of the spending transaction are relevant to the signer, and it’s very complicated and frankly kind of a mess, but the message essentially says “this signature blesses the spending of these coins as long as the spending transactions includes this set of inputs and that set of outputs”.

Chia makes these messages explicit. Although clvm (“contract language virtual machine”) is a general purpose language, typically a signature signs a program written in clvm which is then executed to produce a list of “conditions” which explicitly list out what restrictions the transaction or block which spends the coins must meet. These conditions include things like “the input being signed must be X”, “this output Y must be included”, “the signature is only valid in a block created after time Z”. So the restrictions place upon inputs, outputs and spending time can be much more complicated than in bitcoin.

clvm

The acronym clvm stands for Contract Language Virtual Machine, or Chia Lisp Virtual Machine depending upon whether we are referring to the trademarked version or generic version. Both puzzles and solutions are written in this language.

Compilers

The clvm is intended to be like an assembly-language level of programming, and is intentionally missing such operators such as list which are in most LISP-like languages. This makes writing programs more difficult, so compilation tools that transform programs from a higher-level LISP to the clvm will be made available.

Opcodes

The language is small, and similar to lisp, except most operators are one letter. To keep the implementation small, the operator set is minimal.

list operators

c

cons (c A B) takes exactly two operands and returns the cons box with the two objects in it (in the obvious order)

f

first (f X) takes exactly one operand which must be a cons box, and returns the left half

r

rest (r X) takes exactly one operand which must be a cons box, and returns the right half

l

listp (l X) takes exactly one operand and returns () if it’s an atom or 1 if it’s a list

control flow

i

if (i A B C) takes exactly three operands A, B, C. If A is () (which means “false), return C. Otherwise, return B

x

raise (x X Y...) takes an arbitrary number of arguments (even zero). Immediately fail, with the argument list passed up into the (python) exception

=

equal (= A B) returns 1 if A and B are both atoms and both equal. Otherwise ()

>

greater than (> A B) returns 1 if A and B are both atoms and A is greater than B, interpreting both as signed ints. Otherwise ()

>s

greater than bytes (>s A B) returns 1 if A and B are both atoms and A is greater than B, interpreting both as bytes. Otherwise ()

constants

q

quote (q X) takes exactly one operand which is not evaluated and returns it

integer operators

+

(+ a0 a1...) takes an arbitrary number of integer operands and sums them

-

(- a0 a1...) takes an arbitrary number of integer operands and adds a0 to the negative of the rest

*

(* a0 a1...) takes an arbitrary number of integer operands and returns the product

divmod

(divmod A B) takes two integers and returns a list of the floored quotient and the mod

streaming operators

sha256

(sha256 A) returns the sha256 hash (as a 32-byte blob) of the bytes A

ecdsa operators

point_add

(point_add a0 a1 ...) takes an arbitrary number of bls12_381 points and adds them

pubkey_for_exp

(pubkey_for_exp A) turns the integer A into a bls12_381 point