API.md

Table of contents

• convex.cell - Constructors for CVM cells.
  • * - Macro for translating Clojure types to Convex types.
  • IEquivalent - Translates Clojure types to equivalent Convex types.
  • address - Creates an address from a long.
  • any
  • bigint - Creates a big integer cell from the given Clojure or Java a big integer.
  • blob - Creates a blob from a byte array.
  • blob-map - Creates a blob map from a collection of [blob value].
  • blob<-hex - Creates a blob from a hex string.
  • boolean - Creates a boolean cell given a falsy or truthy value.
  • call - Creates a transaction for invoking a callable function.
  • char - Creates a character cell from a regular character.
  • code-std* - Given a Clojure keyword, returns the corresponding standard error code.
  • double - Creates a double cell.
  • encoding - Returns a blob representing the encoding of the given cell.
  • error - An error value as Convex data.
  • fake - Returns a proxy class which looks like a cell, wrapping x which can be any JVM value.
  • fake? - Returns true if cell has been produced by [[fake]].
  • hash - Returns the hash of the given cell.
  • hash<-blob - Converts a 32-byte blob to a hash.
  • hash<-hex - Creates a hash from a hex string.
  • invoke - Creates a transaction for invoking code (a cell).
  • key - Creates an account key from a 32-byte blob.
  • key-fake - Zeroed account key for testing purposes.
  • keyword - Creates a keyword cell from a string.
  • list - Creates a list cell from a collection of cells.
  • long - Creates a long cell.
  • map - Creates a map cell from a collection of [key value].
  • quoted - Wraps x in quote.
  • set - Creates a set cell from a collection of items cell.
  • string - Creates a string cell from a regular string.
  • symbol - Creates a symbol cell from a string.
  • syntax - Creates a syntax cell.
  • transfer - Creates a transaction for transferring Convex Coins.
  • vector - Creates a vector cell from a collection of items cell.
• convex.clj - Convert cells to Clojure types.
  • IClojuresque - Generic function for converting a cell to a Clojure representation.
  • address - Returns the given address as a JVM long.
  • any
  • bigint - Returns the given bigint cell as a Clojure BigInt.
  • blob - Returns the given blob as a byte array.
  • blob->hex - Returns the given blob as a hex string.
  • boolean - Returns the given boolean cell as a JVM boolean.
  • char - Returns the given char cell as a JVM char.
  • double - Returns the given double cell as a JVM double.
  • keyword - Returns the given keyword cell as a Clojure keyword.
  • list - Returns the given list cell as a Clojure list.
  • long - Returns the given long cell as a JVM long.
  • map - Returns the given map cell (hash map or blob map) as a Clojure map.
  • set - Returns the given set cell as a Clojure set.
  • string - Returns the given string cell as a JVM string.
  • symbol - Returns the given symbol cell as a Clojure symbol.
  • syntax - Returns the given syntax cell as a Clojure map.
  • vector - Returns the given vector cell as a Clojure vector.
• convex.cvm - Code execution in the Convex Virtual Machine Altering its state and gaining insights.
  • account - Returns the account for the given address (or the address associated with ctx).
  • account-create - Creates an new account, with a key (user) or without (actor).
  • actor? - Returns true if the given address point to an actor in ctx.
  • address - Returns the executing address of the given ctx.
  • arg+* - Prepares arguments for invokation.
  • compile - Compiles the canonical-cell into executable code.
  • ctx - Creates an execution context.
  • def - Like calling (def sym value) in Convex Lisp, either in the current address of the given one.
  • deploy - Deploys the given code as an actor.
  • env - Returns the environment of the executing account attached to ctx.
  • eval - Evaluates the given cell after forking the ctx.
  • exception - Returns the exception attached to the CVM (or nil).
  • exception-clear - Removes the currently attached exception from the given ctx.
  • exception-code - Returns the code associated with the given [[exception]].
  • exception-message - Returns the message associated with the given [[exception]].
  • exception-set - Returns a ctx set in an exceptional state.
  • exception-trace - Returns the trace associated with the given [[exception]] (CVX list of strings).
  • exception? - Returns true if the given ctx is in an exceptional state.
  • exec - Executes compiled code.
  • expand - Expands cell into a canonical cell by applying macros.
  • expand-compile - Expands and compiles in one go.
  • fork - Duplicates the given ctx (very cheap).
  • fork-to - Duplicates the given ctx and switches the executing account.
  • genesis-user - Address of the first genesis user.
  • invoke - Invokes the given CVM function using the given ctx.
  • juice - Returns the amount of juice consumed so far in the given context.
  • juice-available - Returns the amount of juice available for execution according to [[juice]] and [[juice-limit]].
  • juice-limit - Returns the maximum amount of juice that can be consumed.
  • juice-limit-set - Sets the value of [[juice-limit]] to the requested amount.
  • juice-preserve - Executes (f ctx), f being a function ctx -> ctx.
  • juice-refill - Resets the value of [[juice]] to 0.
  • juice-set - Sets the value of [[juice]] to the requested amount.
  • key - Returns the key of the given address.
  • key-set - Sets key on the address curently associated with ctx.
  • log - Returns the log of ctx.
  • look-up - Returns the cell associated with the given sym.
  • result - Extracts the result (eg.
  • result-set - Attaches the given result to ctx, as if it was the result of a transaction.
  • state - Returns the whole CVM state associated with ctx.
  • state-set - Replaces the CVM state in the ctx with the given one.
  • time - Returns the current timestamp assigned to the state in the given ctx.
  • time-advance - Advances the timestamp in the state of ctx by millis milliseconds.
  • transact - Executes the given transaction.
  • undef - Like calling (undef sym) in Convex Lisp.
• convex.db - Etch is a fast, immutable, embedded database tailored for cells.
  • close - Flushes and closes the thread-local instance.
  • current - Returns the thread-local instance (or nil).
  • current-set - Binds the given instance to the current thread.
  • flush - Flushes the thread-local instance, ensuring all changes are persisted to disk.
  • global-set - When an instance is used in more than one thread, it is a good idea using this function.
  • open - Opens an instance at the given path.
  • open-tmp - Opens an instance under a temporary file.
  • path - Returns the path of the thread-local instance.
  • read - Reads from the thread-local instance and returns the cell for the given hash (or nil if not found).
  • root-read - Returns the cell stored at the root of the thread-local instance.
  • root-write - Exactly like [[write]] but the cell is written to the root of the thread-local instance.
  • size - Returns the size in bytes of the thread-local instance.
  • write - Writes the given cell to the thread-local instance and returns a new "version" of that cell.
• convex.eval - Quick helpers for evaluating Convex Lisp code.
  • ctx - Evaluates the given cell and the resulting ctx.
  • exception - Evaluates the given cell and returns the resulting CVM exception.
  • exception-code - Evaluates the given cell and returns the resulting CVM exception code.
  • result - Evaluates the given cell and returns the result.
  • true? - Evaluates the given cell and returns JVM true if the result is CVM true.
• convex.read - Reading, parsing various kind of sources into CVX cells without any evaluation.
  • file - Reads all cells from the given filename and returns them in a CVX list.
  • line - Reads a line from the given java.io.BufferedReader and parses the result as a CVX list of cells.
  • resource - Reads one cell from resource located under path on the classpath.
  • stream - Reads all cells from the given java.io.Reader (parent class of text streams) and returns them in a CVX list.
  • string - Reads all cells from the given string and returns them in a CVX list.
• convex.std - Provides an API for cells with classic convex.core-like functions.
  • * - Like classic * but for numeric cells.
  • + - Like classic + but for numeric cells.
  • - - Like classic - but for numeric cells.
  • < - Like classic < but with numeric cells.
  • <= - Like classic <= but with numeric cells.
  • == - Like classic == but with numeric cells.
  • > - Like classic > but with numeric cells.
  • >= - Like classic >= but with numeric cells.
  • abs - Returns the absolute value of x.
  • account-key - Coerces the given cell to an account key or return nil.
  • address - Coerces the given cell to an address or return nil.
  • address? - Is x an address?.
  • assoc - Like classic assoc but for collection cells.
  • bigint? - Is x a bigint?.
  • blob - Coerces the given cell to a blob or return nil.
  • blob-map - Builds a blob map from key-values (keys must be blobs).
  • blob-map? - Is x a blob map?.
  • blob? - Is x a blob?.
  • boolean? - Is x a CVM boolean?.
  • ceil - Returns a double cell ceiling the value of number.
  • cell? - Is x a cell?.
  • char - Coerces the given cell to a char or return nil.
  • char? - Is x a char cell?.
  • coll? - Is x a collection cell?.
  • concat - Like classic concat but for collection cells.
  • conj - Akin to classic conj but for collection cells.
  • cons - Like classic cons but for collection cells.
  • contains? - Like classic contains? but for collection cells.
  • count - Returns a JVM long representing the number of itms in the given cell.
  • cvm-value? - Is x a CVM value? Returns false if x is not accessible to the CVM and meant to be used outside (eg.
  • dec - Like classic dec but for long cells.
  • difference - Like clojure.set/difference but for set cells.
  • dissoc - Like classic dissoc but for map cells.
  • div - Like classic / but for numeric cells.
  • double - Coerces the given cell to a double or return nil.
  • double? - Is x a double cell?.
  • empty - Like classic empty but for collection cells.
  • empty? - Is the given countable empty? See [[count]].
  • exp - Returns e raised to the power of the given numeric cell.
  • false? - Is x a false cell?.
  • find - Like classic find` but for map cells.
  • floor - Returns a double cell flooring the value of x.
  • fn? - Is x a CVM function?.
  • get - Like classic get but for collection cells.
  • hash-map - Builds a map from key-values.
  • hash-map? - Is x a hash map cell?.
  • hash-set - Builds a set from the given cells.
  • hash-set? - Is x a hash set cell? Currently at least, hast sets are the only kind of available sets.
  • hash? - Is x a hash?.
  • inc - Like classic inc but for long cells.
  • integer? - Is x an integer cell (either a bigint or a long)?.
  • intersection - Like clojure.set/intersection but for set cells.
  • into - Like classic into but to is a collection cell.
  • keys - Like classic keys but for map cells.
  • keyword - Coerces the given cell to a keyword or return nil.
  • keyword? - Is x a keyword cell?.
  • list - Buildsa list from the given cells.
  • list? - Is x a list cell?.
  • long - Coerces the given cell to a long or return nil.
  • long? - Is x a long cell?.
  • map? - Is x a map cell?.
  • memory-size - Returns the total memory size of cell (cannot be nil).
  • merge - Like classic merge but for hash map cells (not blob maps).
  • mod - Returns the integer modulus of a numerator divided by a divisor.
  • name - Like classic name but for keyword and symbol cells.
  • nan? - Is the given cell NaN?.
  • next - Like classic next but for collection cells.
  • nth - Like classic nth but for countables.
  • number? - Is x a numeric cell? Either a long or a double.
  • pow - Returns a CVM double, x raised to the power of y.
  • ref-stat - Given a cell (cannot be nil), returns a map: | Key | Value | |--------------|------------------------------------| | :direct | Number of direct refs | | :embedded | Number of embedded refs | | :persisted | Number of refs marked as persisted | | :soft | Number of soft refs | | :total | Total number of refs | This is for CVM developers familiar with the notion of cell references.
  • reverse - Like classic reverse but for sequential cells (list or vector cells).
  • set - Coerces the given cell to a set or return nil.
  • set? - Is x a set cell? Currently at least, hast sets are the only kind of available sets.
  • signed? - Is x signed data?.
  • signum - Returns the sign of the number.
  • sqrt - Returns a double cell, the square root of the given number cell.
  • state? - Is x a state cell?.
  • str - Stringifies the given cell(s) like Convex's str.
  • string? - Is x a string cell?.
  • subset? - Like clojure.set/subset? but for set cells.
  • symbol - Coerces the given cell to a symbol or return nil.
  • symbol? - Is x a symbol cell?.
  • syntax? - Is x a syntax cell?.
  • transaction? - Is x a transaction?.
  • true? - Is x a true cell?.
  • union - Like clojure.set/union but for set cells.
  • update - Akin to classic update but for collection cell.
  • vals - Like classic vals but for map cells.
  • vec - Coerces the given cell to a vector or return nil.
  • vector - Builds a vector from the given cells.
  • vector? - Is x a vector cell?.
  • zero? - Like classic zero? but for cells.
• convex.write - Writing CVX cells as UTF-8 text.
  • stream - Writes the given cell to the given java.io.Writer (parent class of text streams).
  • string - Prints the given cell as a string cell which can be read back with the [[convex.read]] namespace.

---

convex.cell

Constructors for CVM cells.

📄 *

(* x)

Macro.

Macro for translating Clojure types to Convex types.

Convex types can be inserted using ~, especially useful for inserting values dynamically or inserting types that have no equivalent in Clojure (eg. address).

Also understands ~@ (aka unquote splicing).

;; Cell for `(transfer #42 500000)`
;;
(* (transfer ~(address 42)
             500000))

📄 IEquivalent

Translates Clojure types to equivalent Convex types. Other objects remain as they are.

However, the * macro is usually preferred for performance.

(any {:a ['b]})

📄 address

(address long)

Creates an address from a long.

📄 any

(any data)

📄 bigint

(bigint n)

Creates a big integer cell from the given Clojure or Java a big integer.

📄 blob

(blob byte-array)

Creates a blob from a byte array.

📄 blob-map

(blob-map)
(blob-map kvs)

Creates a blob map from a collection of [blob value].

📄 blob<-hex

(blob<-hex hex-string)

Creates a blob from a hex string.

📄 boolean

(boolean x)

Creates a boolean cell given a falsy or truthy value.

📄 call

(call address sequence address-callable function-name arg+)
(call address sequence address-callable offer function-name arg+)

Creates a transaction for invoking a callable function.

📄 char

(char ch)

Creates a character cell from a regular character.

📄 code-std*

(code-std* kw)

Macro.

Given a Clojure keyword, returns the corresponding standard error code.

Those are errors codes used by the CVM itself:

• :ARGUMENT
• :ARITY
• :ASSERT
• :BOUNDS
• :CAST
• :COMPILE
• :DEPTH
• :EXCEPTION
• :EXPAND
• :FATAL
• :FUNDS
• :HALT
• :JUICE
• :MEMORY
• :NOBODY
• :RECUR
• :REDUCED
• :RETURN
• :ROLLBACK
• :SEQUENCE
• :SIGNATURE
• :STATE
• :TAILCALL
• :TODO
• :TRUST
• :UNDECLARED
• :UNEXPECTED

Throws if keyword does not match any of those.

Note that in user functions, codes can be anything, any type, using those codes is not at all mandatory.

📄 double

(double x)

Creates a double cell.

📄 encoding

(encoding cell)

Returns a blob representing the encoding of the given cell.

This encoding is meant for incremental updates.

📄 error

(error message)
(error code message)
(error code message trace)

An error value as Convex data.

 `code` is often a keyword cell (`:ASSERT` by default), `message` could be any cell (albeit often a human-readable
 string), and `trace` is an optional stacktrace (vector cell of string cells).

📄 fake

(fake x)

Returns a proxy class which looks like a cell, wrapping x which can be any JVM value.

For expert users only! Primarily useful for allowing actual cells to store any arbitrary JVM values.

deref will return x.

Prints as the keyword cell DEREF-ME but is not an actual symbol cell. Similarly, writing this fake cell to Etch writes the symbol cell DEREF-ME. Obviously, reading from Etch will return that actual symbol cell since only real cells can be serialized and deserialized (see convex.db).

📄 fake?

(fake? x)

Returns true if cell has been produced by fake.

📄 hash

(hash cell)

Returns the hash of the given cell.

A hash is a specialized 32-byte blob.

📄 hash<-blob

(hash<-blob blob)

Converts a 32-byte blob to a hash.

See hash.

📄 hash<-hex

(hash<-hex hex-string)

Creates a hash from a hex string.

See hash.

Returns nil if hex string is of wrong format.

📄 invoke

(invoke address sequence-id cell)

Creates a transaction for invoking code (a cell).

📄 key

(key blob)

Creates an account key from a 32-byte blob.

Returns nil if the given blob is of wrong size.

📄 key-fake

Zeroed account key for testing purposes.

See key.

📄 keyword

(keyword string)

Creates a keyword cell from a string.

📄 list

(list)
(list x)

Creates a list cell from a collection of cells.

📄 long

(long x)

Creates a long cell.

📄 map

(map)
(map kvs)

Creates a map cell from a collection of [key value].

📄 quoted

(quoted x)

Wraps x in quote.

📄 set

(set)
(set x)

Creates a set cell from a collection of items cell.

📄 string

(string string)

Creates a string cell from a regular string.

📄 symbol

(symbol string)

Creates a symbol cell from a string.

📄 syntax

(syntax cell)
(syntax cell metadata)

Creates a syntax cell.

It wraps the given cell and allow attaching a metadata map.

📄 transfer

(transfer address sequence address-receiver amount)

Creates a transaction for transferring Convex Coins.

📄 vector

(vector)
(vector x)

Creates a vector cell from a collection of items cell.

---

convex.clj

Convert cells to Clojure types.

Sometimes lossy since some cells do not have equivalents in Clojure. For instance, addresses are converted to long. Recursive when it comes to collection.

Mainly useful for a deeper Clojure integration.

📄 IClojuresque

Generic function for converting a cell to a Clojure representation.

Relies all other functions from this namespace.

(any (convex.cell/* {:a [:b]}))

📄 address

(address address)

Returns the given address as a JVM long.

📄 any

(any cell)

📄 bigint

(bigint bigint)

Returns the given bigint cell as a Clojure BigInt.

📄 blob

(blob blob)

Returns the given blob as a byte array.

📄 blob->hex

(blob->hex blob)

Returns the given blob as a hex string.

📄 boolean

(boolean boolean)

Returns the given boolean cell as a JVM boolean.

📄 char

(char char)

Returns the given char cell as a JVM char.

📄 double

(double double)

Returns the given double cell as a JVM double.

📄 keyword

(keyword keyword)

Returns the given keyword cell as a Clojure keyword.

📄 list

(list list)

Returns the given list cell as a Clojure list.

📄 long

(long long)

Returns the given long cell as a JVM long.

📄 map

(map map)

Returns the given map cell (hash map or blob map) as a Clojure map.

Attention, in Clojure maps, sequential types containg the same items are equivalent but not in Convex. Hence, a clash could happen in the rare case where different sequential types are used as keys. For instance, the following is possible in Convex but not in Clojure (would complain about duplicate keys:

{[:a]  :foo
 '(:a) :foo}

📄 set

(set set)

Returns the given set cell as a Clojure set.

Same comment about sequential types as in map applies here.

📄 string

(string string)

Returns the given string cell as a JVM string.

📄 symbol

(symbol symbol)

Returns the given symbol cell as a Clojure symbol.

📄 syntax

(syntax syntax)

Returns the given syntax cell as a Clojure map.

Such as:

Key	Value
:meta	Clojure map of metadata
:value	Value wrapped, converted as well

📄 vector

(vector vector)

Returns the given vector cell as a Clojure vector.

---

convex.cvm

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

(account ctx)
(account ctx address)

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

📄 account-create

(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.

📄 actor?

(actor? ctx address)

Returns true if the given address point to an actor in ctx.

An actor is an account without a public key.

📄 address

(address ctx)

Returns the executing address of the given ctx.

📄 arg+*

(arg+* & arg+)

Macro.

Prepares arguments for invokation.

See invoke.

📄 compile

(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

(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 public 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

When no state is provided, based on the provided public keys (which MUST be distinct):

• A special genesis user is created with 50% of available user funds, associated with the first public key
• For the address of that special genesis user, see genesis-user
• For each public key, an additional user is created, sharing the remaining user funds equally
• Each additional user becomes the controller of a declared peers (see the :peers key in the state)
• Each peer uses the same public key as its controller
• Each user stakes 1 / 3 of its balance on its peer

See convex.cell/key about creating public keys or the convex.key-pair namespace from :module/net.

📄 def

(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

(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

(env ctx)
(env ctx address)

Returns the environment of the executing account attached to ctx.

📄 eval

(eval ctx)
(eval ctx cell)

Evaluates the given cell after forking the ctx.

Goes 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 in an alternative way).

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

📄 exception

(exception ctx)
(exception code ctx)

Returns the exception attached to the CVM (or nil).

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

A nil result means result can be safely used on this context.

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

(exception-clear ctx)

Removes the currently attached exception from the given ctx.

📄 exception-code

(exception-code exception)

Returns the code associated with the given exception.

Often a CVX keyword but could be any CVX value.

📄 exception-message

(exception-message exception)

Returns the message associated with the given exception.

Often a CVX string but could be any CVX value.

📄 exception-set

(exception-set ctx exception)
(exception-set ctx code message)

Returns a ctx set in an exceptional state.

See exception.

📄 exception-trace

(exception-trace exception)

Returns the trace associated with the given exception (CVX list of strings).

📄 exception?

(exception? ctx)
(exception? code ctx)

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

See exception.

📄 exec

(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

(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

(expand-compile ctx)
(expand-compile ctx cell)

Expands and compiles in one go.

More efficient than chaining expand and compile yourself.

📄 fork

(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

(fork-to ctx address)

Duplicates the given ctx and switches the executing account.

Like fork but only state and juice are preservered. Everything else is lost: local bindings, CVM log. CVM depth, etc.

📄 genesis-user

Address of the first genesis user.

More precisely, when the CVM state is created in ctx. This behavior might change in the future.

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

📄 invoke

(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

(juice ctx)

Returns the amount of juice consumed so far in the given context.

Also see juice-set.

📄 juice-available

(juice-available ctx)

Returns the amount of juice available for execution according to juice and juice-limit.

📄 juice-limit

(juice-limit ctx)

Returns the maximum amount of juice that can be consumed.

📄 juice-limit-set

(juice-limit-set ctx amount)

Sets the value of juice-limit to the requested amount.

Returns an update context.

📄 juice-preserve

(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

(juice-refill ctx)

Resets the value of juice to 0.

Also see juice-set.

Returns an update context.

📄 juice-set

(juice-set ctx amount)

Sets the value of juice to the requested amount.

Also see juice, juice-refill.

Returns an update context.

📄 key

(key ctx)
(key ctx address)

Returns the key of the given address.

Or the address associated with ctx.

📄 key-set

(key-set ctx key)

Sets key on the address curently associated with ctx.

📄 log

(log ctx)

Returns the log of ctx.

A vector cell of size 2 vectors containing a logging address and a logged value.

📄 look-up

(look-up ctx sym)
(look-up ctx address sym)

Returns the cell associated with the given sym.

From the environment of the given address (or the currently used one).

📄 result

(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

(result-set ctx result)

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

📄 state

(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

(state-set ctx state)

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

Attention, will fail if the address does not exist in the new state.

See state.

📄 time

(time ctx)

Returns the current timestamp assigned to the state in the given ctx.

A timetamp is a Unix epoch in milliseconds (long cell);

Also see [[time-set]].

📄 time-advance

(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.

📄 transact

(transact ctx trx)

Executes the given transaction.

This is exactly what a peer does when executing a transation from a block, after validating its signature.

Similar to eval but:

• Temporarily switches to the account of the transaction
• Executes the code in that account
• Takes care of all the juice and memory accounting for that account

For creating transactions, see:

• convex.cell/call
• convex.cell/invoke
• convex.cell/transfer

Returns a new ctx with the result or exception attached.

📄 undef

(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+.

---

---

convex.db

Etch is a fast, immutable, embedded database tailored for cells.

It can be understood as a data store where keys are hashes of the cells they point to. Hence, the API is pretty simple. read takes the hash of a cell and returns the cell (if present). write takes a cell and returns a new version of that cell with some internals updated.

Most of the time, usage is made even simpler by using root-write and root-read to persist the state of a whole application at once (only new values are effectively written).

Data is retrieved semi-lazily. For instance, in the case of a large vector, only the the top structure of that vector is fetched. Elements are read from disk when actually accessed then cached using a clever system of soft references under the hood. This explains why data larger than memory can be retrieved and handled since the JVM can garbage-collect those soft references ; their value will be read from disk again if required. Nonetheless, users only deal with cells and all this process is completely transparent.

Attention, although this namespace is straightforward, one rule must be followed at all time: cells read from an instance can only be written back to that instance. In other words, one must never mix cells read from different instances with the intent of writing them anywhere. This will result in some of the data not being written. Everything, from cells to Etch, has been heavily optimized for Convex peers that only ever handle 1 instance at a time. It is fine using several stores in the same process as long as operations never cross-over.

Convex tooling, whenever an instance is needed, will always look for the instance associated with the current thread (if any). The typical workflow is to call current-set after open. If no instance is bound to the current thread explicitely, a temporary one is created whenever needed. See global-set for improving the workflow when an instance is needed in more than one thread.

When using a convex.cvm/ctx, its state is initially hold in memory. After opening an Etch instance and setting it as thread-local, this state can be retrieved at any point using convex.cvm/state and persisted to disk since it is a cell. This renders that state garbage-collecteable as exposed above. Of course, it is important not to close the instance before stopping all operations on that context and its state.

📄 close

(close)

Flushes and closes the thread-local instance. Also unbinds it from the current thread.

Note that all instances are also cleanly closed on JVM shutdown but it is more predictable doing it manually.

📄 current

(current)

Returns the thread-local instance (or nil). See current-set.

📄 current-set

(current-set instance)

Binds the given instance to the current thread. Returns the instance. See current.

📄 flush

(flush)

Flushes the thread-local instance, ensuring all changes are persisted to disk.

📄 global-set

(global-set instance)

When an instance is used in more than one thread, it is a good idea using this function. Convex tooling will then use the given instance in all thread automatically where no store has been initialized yet.

Setting a store global will not impact threads which already started handling an instance. Hence, this function is best used when one needs only one store throught the lifetime of the process, preferably setting it at the beginning.

📄 open

(open path)

Opens an instance at the given path. File is created if needed.

📄 open-tmp

(open-tmp)
(open-tmp prefix)

Opens an instance under a temporary file.

A prefix string may be provided for the filename.

📄 path

(path)

Returns the path of the thread-local instance.

📄 read

(read hash)

Reads from the thread-local instance and returns the cell for the given hash (or nil if not found).

📄 root-read

(root-read)

Returns the cell stored at the root of the thread-local instance.

The root is a place in the instance that can be read without providing a hash. It is commonly used for storing the whole state of an application or at least some sort of index containing hashes of other data in the instance. This makes Etch self-sufficient as no hash must be stored externally.

See [[write-root]].

📄 root-write

(root-write cell)

Exactly like write but the cell is written to the root of the thread-local instance.

See [[read-root]].

📄 size

(size)

Returns the size in bytes of the thread-local instance.

Etch always reserves some extra space in its instance file. The returned value is the size of the actual data, without any extra space.

📄 write

(write cell)

Writes the given cell to the thread-local instance and returns a new "version" of that cell.

If the cell is needed for more work, the old version should be discarded in favor of that new version. This allows for transparent garbage-collection (see namespace description) while acting as an optimization during subsequent writes (e.g. an already persisted cell is put in a collection that is in turn persisted).

Very basic cell types are not persisted because that would be inefficient and hardly ever happens. They are typically embedded in collections. Hence, this function will return nil for:

 - Address
 - Empty collections
 - Primitives (boolean, byte, double, long)
 - Symbolic (keywords and symbols)

---

convex.eval

Quick helpers for evaluating Convex Lisp code.

Systematically forks the used context before any operation so that it remains intact.

Notably useful when writing tests.

📄 ctx

(ctx ctx cell)

Evaluates the given cell and the resulting ctx.

📄 exception

(exception ctx cell)

Evaluates the given cell and returns the resulting CVM exception.

Or nil.

📄 exception-code

(exception-code ctx cell)

Evaluates the given cell and returns the resulting CVM exception code.

Or nil.

📄 result

(result ctx cell)

Evaluates the given cell and returns the result.

📄 true?

(true? ctx cell)

Evaluates the given cell and returns JVM true if the result is CVM true.

Notably useful for test assertions.

---

convex.read

Reading, parsing various kind of sources into CVX cells without any evaluation.

Attention, currently, functions that read only one cell fail when the input contains more than one. In the future, behavior should be improved. For instance, consuming cells one by one from a stream.

Also see the convex.write namespace for the opposite idea.

📄 file

(file filename)

Reads all cells from the given filename and returns them in a CVX list.

📄 line

(line buffered-reader)

Reads a line from the given java.io.BufferedReader and parses the result as a CVX list of cells.

📄 resource

(resource path)

Reads one cell from resource located under path on the classpath.

📄 stream

(stream reader)

Reads all cells from the given java.io.Reader (parent class of text streams) and returns them in a CVX list.

📄 string

(string string)

Reads all cells from the given string and returns them in a CVX list.

---

convex.std

Provides an API for cells with classic convex.core-like functions.

All clojure.core functions related to sequences usually understand Convex collections, making them easy to handle. Some of those (eg. cons, next) have counterparts in this namespace in case the return value must be a cell instead of a Clojure sequence.

Functions take and return cells unless specified otherwise. Predicates return JVM booleans.

Sometimes, it can be useful converting cells to Clojure data, such as unwrapping blob to byte arrays, which is the purpose of the convex.clj namespace.

Lastly, in the rare cases where all of this would not be enough, Java interop can be used;

📄 *

(* & xs)

Like classic * but for numeric cells.

📄 +

(+ & xs)

Like classic + but for numeric cells.

📄 -

(- & xs)

Like classic - but for numeric cells.

📄 <

(< & xs)

Like classic < but with numeric cells.

📄 <=

(<= & xs)

Like classic <= but with numeric cells.

📄 ==

(== & xs)

Like classic == but with numeric cells.

📄 >

(> & xs)

Like classic > but with numeric cells.

📄 >=

(>= & xs)

Like classic >= but with numeric cells.

📄 abs

(abs number)

Returns the absolute value of x.

Same type as x.

📄 account-key

(account-key cell)

Coerces the given cell to an account key or return nil.

Works with:

• 64-char hex-string cell
• 32-byte blob

📄 address

(address cell)

Coerces the given cell to an address or return nil.

Works with:

• Long cell
• 16-char hex-string cell
• 8-byte blob

📄 address?

(address? x)

Is x an address?

📄 assoc

(assoc coll k v)

Like classic assoc but for collection cells.

📄 bigint?

(bigint? x)

Is x a bigint?

📄 blob

(blob cell)

Coerces the given cell to a blob or return nil.

Works with:

• Any kind of blob (eg. hash)
• Long cell
• Hex-string cell

📄 blob-map

(blob-map & kvs)

Builds a blob map from key-values (keys must be blobs).

📄 blob-map?

(blob-map? x)

Is x a blob map?

📄 blob?

(blob? x)

Is x a blob?

📄 boolean?

(boolean? x)

Is x a CVM boolean?

📄 ceil

(ceil number)

Returns a double cell ceiling the value of number.

📄 cell?

(cell? x)

Is x a cell?

📄 char

(char cell)

Coerces the given cell to a char or return nil.

📄 char?

(char? x)

Is x a char cell?

📄 coll?

(coll? x)

Is x a collection cell?

📄 concat

(concat x y)

Like classic concat but for collection cells.

Return type is the same as x.

📄 conj

(conj)
(conj coll)
(conj coll v)

Akin to classic conj but for collection cells.

📄 cons

(cons x coll)

Like classic cons but for collection cells.

Returns a list cell.

📄 contains?

(contains? coll k)

Like classic contains? but for collection cells.

📄 count

(count countable)

Returns a JVM long representing the number of itms in the given cell.

A countable is either:

• Blob
• Blob map
• Map
• List
• Set
• String
• Vector

📄 cvm-value?

(cvm-value? x)

Is x a CVM value?

Returns false if x is not accessible to the CVM and meant to be used outside (eg. networking).

📄 dec

(dec long)

Like classic dec but for long cells.

📄 difference

(difference set-1 set-2)

Like clojure.set/difference but for set cells.

📄 dissoc

(dissoc map k)

Like classic dissoc but for map cells.

📄 div

(div & xs)

Like classic / but for numeric cells.

📄 double

(double cell)

Coerces the given cell to a double or return nil.

📄 double?

(double? x)

Is x a double cell?

📄 empty

(empty coll)

Like classic empty but for collection cells.

📄 empty?

(empty? countable)

Is the given countable empty?

See count.

📄 exp

(exp number)

Returns e raised to the power of the given numeric cell.

📄 false?

(false? x)

Is x a false cell?

📄 find

(find map k)

Like classic `find`` but for map cells.

📄 floor

(floor x)

Returns a double cell flooring the value of x.

📄 fn?

(fn? x)

Is x a CVM function?

📄 get

(get coll k)
(get coll k not-found)

Like classic get but for collection cells.

📄 hash-map

(hash-map & kvs)

Builds a map from key-values.

📄 hash-map?

(hash-map? x)

Is x a hash map cell?

📄 hash-set

(hash-set & cell+)

Builds a set from the given cells.

📄 hash-set?

(hash-set? x)

Is x a hash set cell?

Currently at least, hast sets are the only kind of available sets.

📄 hash?

(hash? x)

Is x a hash?

📄 inc

(inc long)

Like classic inc but for long cells.

📄 integer?

(integer? x)

Is x an integer cell (either a bigint or a long)?

📄 intersection

(intersection set-1 set-2)

Like clojure.set/intersection but for set cells.

📄 into

(into to from)
(into to xform from)

Like classic into but to is a collection cell.

📄 keys

(keys map)

Like classic keys but for map cells.

Returns an eager vector cell.

📄 keyword

(keyword cell)

Coerces the given cell to a keyword or return nil.

Works with:

• Max 64-char string cell
• Symbol

📄 keyword?

(keyword? x)

Is x a keyword cell?

📄 list

(list & cell+)

Buildsa list from the given cells.

📄 list?

(list? x)

Is x a list cell?

📄 long

(long cell)

Coerces the given cell to a long or return nil.

📄 long?

(long? x)

Is x a long cell?

📄 map?

(map? x)

Is x a map cell?

📄 memory-size

(memory-size cell)

Returns the total memory size of cell (cannot be nil).

In other words, the number of bytes accounting for the encoding of the cell as well as all its children (if any).

📄 merge

(merge map-1 map-2)

Like classic merge but for hash map cells (not blob maps).

📄 mod

(mod a b)

Returns the integer modulus of a numerator divided by a divisor.

Result will always be positive and consistent with Euclidean Divsion.

📄 name

(name symbolic)

Like classic name but for keyword and symbol cells.

Returns a string cell.

📄 nan?

(nan? cell)

Is the given cell NaN?

📄 next

(next coll)

Like classic next but for collection cells.

Return type is a list cell if coll is a list, a vector cell otherwise.

📄 nth

(nth countable index)

Like classic nth but for countables.

Index must be a JVM long.

See count.

📄 number?

(number? x)

Is x a numeric cell?

Either a long or a double.

📄 pow

(pow x y)

Returns a CVM double, x raised to the power of y.

📄 ref-stat

(ref-stat cell)

Given a cell (cannot be nil), returns a map:

Key	Value
:direct	Number of direct refs
:embedded	Number of embedded refs
:persisted	Number of refs marked as persisted
:soft	Number of soft refs
:total	Total number of refs

This is for CVM developers familiar with the notion of cell references.

📄 reverse

(reverse sq)

Like classic reverse but for sequential cells (list or vector cells).

📄 set

(set cell)

Coerces the given cell to a set or return nil.

Works with any collection.

📄 set?

(set? x)

Is x a set cell?

Currently at least, hast sets are the only kind of available sets.

📄 signed?

(signed? x)

Is x signed data?

📄 signum

(signum number)

Returns the sign of the number.

More precisely:

• -1 if negative
• 0 if 0
• 1 if positive

As a long cell if input is a long, double cell if it is a double.

📄 sqrt

(sqrt number)

Returns a double cell, the square root of the given number cell.

📄 state?

(state? x)

Is x a state cell?

📄 str

(str & cell+)

Stringifies the given cell(s) like Convex's str.

📄 string?

(string? x)

Is x a string cell?

📄 subset?

(subset? set-1 set-2)

Like clojure.set/subset? but for set cells.

📄 symbol

(symbol cell)

Coerces the given cell to a symbol or return nil.

Works with:

• Max 64-char string cell
• Symbol

📄 symbol?

(symbol? x)

Is x a symbol cell?

📄 syntax?

(syntax? x)

Is x a syntax cell?

📄 transaction?

(transaction? x)

Is x a transaction?

📄 true?

(true? x)

Is x a true cell?

📄 union

(union set-1 set-2)

Like clojure.set/union but for set cells.

📄 update

(update coll k f)

Akin to classic update but for collection cell.

📄 vals

(vals map)

Like classic vals but for map cells.

Returns an eager vector cell.

📄 vec

(vec cell)

Coerces the given cell to a vector or return nil.

Works with any countable (see count).

📄 vector

(vector & cell+)

Builds a vector from the given cells.

📄 vector?

(vector? x)

Is x a vector cell?

📄 zero?

(zero? x)

Like classic zero? but for cells.

---

convex.write

Writing CVX cells as UTF-8 text.

Also see convex.read for the opposite idea.

📄 stream

(stream writer cell)
(stream writer stringify cell)

Writes the given cell to the given java.io.Writer (parent class of text streams).

By default, standard str is used for stringifying cell. See string for implications.

📄 string

(string cell)
(string limit cell)

Prints the given cell as a string cell which can be read back with the convex.read namespace.

A default limit of 10000 bytes is applied relative to the output, beyond which "<>" is appended. Pass Long/MAX_VALUE for the maximum limit.