convex.cvm — world.convex/cvm.clj 0.0.0-alpha4

Code execution in the Convex Virtual Machine, altering its state, and gaining insights.

The central entity of this namespace is the execution context created by ctx. They embed a state and allow executing code to alter it.

All other functions revolve around contextes. While the design of a context is mostly immutable, whenever an altering function is applied (eg. juice-set) or code is handled in any way (eg. eval), the old context must be discarded and only the returned one should be used.

Cheap copies can be created using fork.

Actions involving code (eg. compile, exec, ...) return a new context which holds either a result or an exception. Those actions always consume juice.

Given that a "cell" is the term reserved for CVM data and objects, execution consists of the following steps:

Step	Function	Does
1	expand	cell -> canonical cell, applies macros
2	compile	canonical cell -> op, preparing executable code
3	exec	Executes compiled code

Any cell can be applied safely to those functions, worse that can happen is nothing (e.g. providing an already compiled cell to compile).

If fine-grained control is not needed and if source is not compiled anyways, a simpler alternative is to use eval which does all the job.

account clj

(account ctx)

(account ctx address)

Returns the account for the given address (or the address associated with ctx).

account-create clj

(account-create ctx)

(account-create ctx key)

Creates an new account, with a key (user) or without (actor).

See convex.cell/key.

Address is attached as a result in the returned context.

address clj

(address ctx)

Returns the executing address of the given ctx.

arg+* clj macro

(arg+* & arg+)

See invoke.

compile clj

(compile ctx)

(compile ctx canonical-cell)

Compiles the canonical-cell into executable code.

Fetched using result if not given.

Returns a new ctx with a result ready for exec or an exception in case of failure.

ctx clj

(ctx)

(ctx option+)

Creates an execution context.

An optional map of options may be provided:

Key	Value	Default
:convex.cvm/address	Address of the executing account	genesis-user
:convex.cvm/genesis-key+	Vector of keys for genesis users (at least one)	Vector with only fake-key for genesis-user
:convex.cvm/state	State (see state)	Initial state with Convex actors and libraries

More than one genesis key can be provided in order to create more users than genesis-user. However, it is important those public keys are different otherwise an exception is thrown.

See convex.cell/key about creating public keys.

def clj

(def ctx sym->value)

(def ctx addr sym->value)

Like calling (def sym value) in Convex Lisp, either in the current address of the given one.

Argument is a map of symbol cell -> cell.

deploy clj

(deploy ctx code)

Deploys the given code as an actor.

Returns a context that is either exceptional or has the address of the successfully created actor attached as a result.

env clj

(env ctx)

(env ctx address)

Returns the environment of the executing account attached to ctx.

eval clj

(eval ctx)

(eval ctx cell)

Evaluates the given cell after forking the ctx, going efficiently through expand, compile, and exec.

Works with any kind of cell and is sufficient when there is no need for fine-grained control.

An important difference with the aforementioned cycle is that the cell passes through *lang*, a function possibly set by the user for intercepting a cell (eg. modifying the cell and evaluating explicitley).

Returns the forked ctx with a result or an exception in case of failure.

exception clj

(exception ctx)

(exception code ctx)

The CVM enters in exceptional state in case of error or particular patterns such as halting or doing a rollback.

Returns the current exception or nil if ctx is not in such a state meaning that result can be safely used.

An exception code can be provided as a filter, meaning that even if an exception occured, this functions will return nil unless that exception has the given code.

Also see convex.cell/code-std* for easily retrieving an official error code. Note that in practice, unlike the CVM itself or any of the core function, a user Convex function can return anything as a code.

exception-clear clj

(exception-clear ctx)

Removes the currently attached exception from the given ctx.

exception-code clj

(exception-code exception)

Returns the code associated with the given exception.

Often a CVX keyword but could be any CVX value.

exception-message clj

(exception-message exception)

Returns the message associated with the given exception.

Often a CVX string but could be any CVX value.

exception? clj

(exception? ctx)

(exception? code ctx)

Returns true if the given ctx is in an exceptional state.

See exception.

exec clj

(exec ctx)

(exec ctx op)

Executes compiled code.

Usually run after compile.

Returns a new ctx with a result or an exception in case of failure.

expand clj

(expand ctx)

(expand ctx cell)

Expands cell into a canonical cell by applying macros.

Fetched using result if not given.

Returns a new ctx with a result ready for compile or an exception in case of failure.

expand-compile clj

(expand-compile ctx)

(expand-compile ctx cell)

Chains expand and compile in a slightly more efficient fashion than calling both separately.

fake-key clj

Fake key (all zeroes) meant for testing.

fork clj

(fork ctx)

Duplicates the given ctx (very cheap).

Any operation on the returned copy has no impact on the original context.

Attention, forking a ctx looses any attached result or exception.

fork-to clj

(fork-to ctx address)

Like fork but switches the executing account.

Note: CVM log is lost.

genesis-user clj

Address of the first genesis user when the CVM state is created in ctx. Might change in the future.

It receives half of the funds reserved for all users in the state.

invoke clj

(invoke ctx f arg+)

Invokes the given CVM function using the given ctx.

arg+ is a Java array of cells. See arg+* for easily and efficiently creating one.

Returns a new ctx with a result or an exception in case of failure.

juice clj

(juice ctx)

Returns the remaining amount of juice available for the executing account.

Also see juice-set.

juice-preserve clj

(juice-preserve ctx f)

Executes (f ctx), f being a function ctx -> ctx.

The returned ctx will have the same amount of juice as the original.

juice-refill clj

(juice-refill ctx)

Refills juice to maximum.

Also see juice-set.

juice-set clj

(juice-set ctx amount)

Sets the juice of the given ctx to the requested amount.

Also see juice, juice-refill.

key clj

(key ctx)

(key ctx address)

Returns the key of the given address (or the address associated with ctx).

key-set clj

(key-set ctx key)

Sets key on the address curently associated with ctx.

log clj

(log ctx)

Returns the log of ctx (a vector cell of size 2 vectors containing a logging address and a logged value).

look-up clj

(look-up ctx sym)

(look-up ctx address sym)

Returns the cell associated with the given sym in the environment of the given address (or the currently used one).

result clj

(result ctx)

Extracts the result (eg. after expansion, compilation, execution, ...) wrapped in a ctx.

Throws if the ctx is in an exceptional state. See exception.

result-set clj

(result-set ctx result)

Attaches the given result to ctx, as if it was the result of a transaction.

state clj

(state ctx)

Returns the whole CVM state associated with ctx.

It is a special type of cell behaving like a map cell. It notably holds all accounts and can be explored using convex.std map functions.

Also see state-set.

state-set clj

(state-set ctx state)

Replaces the CVM state in the ctx with the given one.

See state.

time clj

(time ctx)

Returns the current timestamp (Unix epoch in milliseconds as long cell) assigned to the state in the given ctx.

Also see [[time-set]].

time-advance clj

(time-advance ctx millis)

Advances the timestamp in the state of ctx by millis milliseconds. Scheduled transactions will be executed if necessary.

Does not do anything if millis is < 0.

See time.

undef clj

(undef ctx sym+)

(undef ctx addr sym+)

Like calling (undef sym) in Convex Lisp, either in the current account or the given one, repeatedly on any symbol cell in sym+.