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

Code execution in the CVM, altering state, and gaining insights.

Central entities of this namespaces are contextes and they can be created using ctx.

All other functions revolve around them. 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), old context must be discarded and only 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 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 (eg. 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 a "fake" context. Ideal for testing and repl'ing around.

An optional map of options may be provided:

Key	Value	Default
:convex.cvm/address	Address of the executing account	Reserved address (an actor)
:convex.cvm/state	Genesis state	Initial state with Convex actors and libraries
`:convex.peer/key	Account key for the initial peer (see [[convex.cell/account-key]])	Fake key, all 0's

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 CVM symbol -> CVM value.

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, 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 a new 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 [[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? 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 object)

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 object)

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

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.

invoke clj

(invoke ctx f arg+)

Invokes the given CVM function using the given ctx.

arg+ is a Java array of CVM objects. 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 CVM vector of size 2 vectors containing a logging address and a logged value).

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.

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 CVM long) assigned to the state in the given ctx.

Also see [[timestamp-set]].

time-advance clj

(time-advance ctx millis)

Advances the timestamp in the state of ctx by millis milliseconds.

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 CVM symbol in sym+.