API.md

Table of contents

• convex.client - Interacting with a peer server via the binary protocol.
  • close - Closes the given client.
  • connect - Connects to a peer server as a client using the binary protocol.
  • connect-local - Connects to an in-process peer server.
  • connected? - Returns true if the given client is still connected.
  • peer-status - Advanced feature.
  • query - Performs a query, cell representing code to execute.
  • resolve - Sends the given hash to the peer to resolve it as a cell using its Etch instance.
  • result->error-code - Given a result de-referenced from a future, returns the error code.
  • result->trace - Given a result de-referenced from a future, returns the stacktrace.
  • result->value - Given a result de-referenced from a future, returns its value.
  • sequence-id - Retrieves the next sequence ID required for a transaction.
  • state - Requests the currrent network state from the peer.
  • transact - Performs a transaction.
• convex.key-pair - Signing cells using public key cryptography, most notably transactions.
  • account-key - Returns the account key of the given key-pair.
  • ed25519 - Creates an Ed25519 key pair.
  • hex-string - Returns the public key of the given key-pair as a hex-string.
  • key-private - Returns the java.security.PrivateKey of the given key-pair.
  • key-public - Returns the java.security.PublicKey of the given key-pair.
  • seed - Returns the seed of the given key-pair.
  • sign - Returns the given cell as data signed by key-pair.
  • sign-hash - Signs the given hash with the given key-pair.
  • signed->account-key - Given signed data, returns the account key of the signer.
  • signed->cell - Given signed data, returns the cell that was signed.
  • signed->signature - Given signed data, returns the signature as a blob cell.
  • verify - Returns true if the given cell has indeed been signed by the given [[account-key]].
  • verify-hash - Verifies that the given signature is indeed the given hash signed by the given account key.
• convex.pfx - Creating and managing a key store for storing key pairs in a file.
  • create - Creates a new key store in the file under path.
  • key-pair-get - Retrieves a key pair from the given key-store.
  • key-pair-set - Adds the given key-pair to the key-store, protected by a mandatory passphrase.
  • load - Loads a key store from the file under path.
  • save - Saves the given key-store to the file under path.
• convex.server - Running a peer server.
  • controller - Returns the controller associated with server.
  • create - Returns a new peer server.
  • db - Returns the Etch instance used by the server.
  • host - Returns bind address used by the server as a string.
  • peer - Returns the peer object wrapped by the server.
  • persist - Persists peer data at the root of the server's Etch instance.
  • port - Returns the port used by the server.
  • start - Starts server.
  • stop - Stops server.

---

convex.client

Interacting with a peer server via the binary protocol.

After creating a client with connect, main interactions are query and transact.

All IO functions return a future which ultimately resolves to a result received from the peer. Information from result can be extracted using:

• result->error-code
• result->trace
• result->value

Clients need an access to Etch. See convex.db from :module/cvm.

📄 close

(close connection)

Closes the given client.

See connect.

📄 connect

(connect)
(connect option+)

Connects to a peer server as a client using the binary protocol.

Will use the Etch instance found with convex.db/current. It important keeping the client on a thread that has always access to the very same instance.

A map of options may be provided:

Key	Value	Default
:convex.server/host	Peer IP address	"localhost"
:convex.server/port	Peer port	18888

📄 connect-local

(connect-local server)

Connects to an in-process peer server.

If an application embeds a peer server, using a "local" client for interacting with it will be a lot more efficient.

It is important the client is always on a thread that has the same store being returned on convex.db/current (from :module/cvm) as the store used by the server.

See convex.server.

📄 connected?

(connected? client)

Returns true if the given client is still connected.

Attention. Currently, does not detect severed connections (eg. server shutting down).

See close.

📄 peer-status

(peer-status client)

Advanced feature. The peer status is a vector of blobs which are hashes to data about the peer. For instance, blob 4 is the hash of the state. That is how state works, retrieving the hash from the peer status and then using resolve.

📄 query

(query client address cell)

Performs a query, cell representing code to execute.

Queries are a dry run: executed only by the peer, without consensus, and any state change is discarded. They do not incur fees.

Returns a future resolving to a result.

📄 resolve

(resolve client hash)

Sends the given hash to the peer to resolve it as a cell using its Etch instance.

See convex.db from :module/cvm for more about hashes and values in the context of Etch.

Returns a future resolving to a result.

📄 result->error-code

(result->error-code result)

Given a result de-referenced from a future, returns the error code.

Could be any cell but typically a CVX keyword.

Returns nil if the result is not an error.

📄 result->trace

(result->trace result)

Given a result de-referenced from a future, returns the stacktrace.

A CVX vector of strings.

Returns nil if the result is not an error.

📄 result->value

(result->value result)

Given a result de-referenced from a future, returns its value.

Could be any cell.

In case of error, this will be the error message (often a CVX string but can be any value).

📄 sequence-id

(sequence-id client address)

Retrieves the next sequence ID required for a transaction.

Uses query.

Each account has a sequence ID, a number being incremented on each successful transaction to prevent replay attacks. Providing a transaction (eg. convex.cell/invoke from :module/cvm) with a wrong sequence ID number will fail.

📄 state

(state client)

Requests the currrent network state from the peer.

Returns a future resolving to a result.

📄 transact

(transact client signed-transaction)
(transact client key-pair transaction)

Performs a transaction.

3 types of transactions exists in module/cvm:

• convex.cell/call for an actor call
• convex.cell/invoke for executing code
• convex.cell/transfer for executing a transfer of Convex Coins

Transaction must be either pre-signed beforehand or a key pair must be provided to sign it. See the convex.key-pair namespace to learn more about key pairs.

It is important that transactions are created for the account matching the key pair and that the right sequence ID is used. See sequence-id.

---

convex.key-pair

Signing cells using public key cryptography, most notably transactions.

More precisely, is signed the hash of the encoding of the cell, producing a signed data cell.

Uses Ed25519.

📄 account-key

(account-key key-pair)

Returns the account key of the given key-pair.

An account key is a specialized cell behaving like a blob and representing the public key of an account.

📄 ed25519

(ed25519)
(ed25519 seed)
(ed25519 key-public key-private)

Creates an Ed25519 key pair.

It is generated from a seed, a 32-byte blob. If not given, one is generated randomly.

Alternatively, a key-public and a key-private retrieved from an existing key pair can be provided.

📄 hex-string

(hex-string key-pair)

Returns the public key of the given key-pair as a hex-string.

64-char string where each pair of chars represents a byte in hexadecimal.

📄 key-private

(key-private key-pair)

Returns the java.security.PrivateKey of the given key-pair.

📄 key-public

(key-public key-pair)

Returns the java.security.PublicKey of the given key-pair.

📄 seed

(seed key-pair)

Returns the seed of the given key-pair.

Attention, this is very sensitive information since it allows rebuilding the key-pair using ed25519.

📄 sign

(sign key-pair cell)

Returns the given cell as data signed by key-pair. That value is a cell itself and can be stored in Etch if required (see the convex.db namespace from :module/cvm).

signed->... functions allows for extracting information from signed data.

Most useful for signing transactions. See convex.client/transact.

📄 sign-hash

(sign-hash key-pair hash)

Signs the given hash with the given key-pair. Returns the signature as a blob.

See convex.cell/hash from :module/cvm.

📄 signed->account-key

(signed->account-key signed)

Given signed data, returns the account key of the signer.

See account-key, sign.

📄 signed->cell

(signed->cell signed)

Given signed data, returns the cell that was signed.

See sign.

📄 signed->signature

(signed->signature signed)

Given signed data, returns the signature as a blob cell.

See sign.

📄 verify

(verify account-key signature cell)

Returns true if the given cell has indeed been signed by the given account-key.

signature is the signature to verify as a blob cell.

📄 verify-hash

(verify-hash account-key signature hash)

Verifies that the given signature is indeed the given hash signed by the given account key.

See account-key, sign-hash.

---

---

convex.pfx

Creating and managing a key store for storing key pairs in a file.

See convex.key-pair about key pairs.

📄 create

(create path)
(create path passphrase)

Creates a new key store in the file under path.

An optional passphrase protecting the store may be provided.

📄 key-pair-get

(key-pair-get key-store alias-or-account-key passphrase)

Retrieves a key pair from the given key-store.

See key-pair-set.

📄 key-pair-set

(key-pair-set key-store key-pair passphrase)
(key-pair-set key-store alias key-pair passphrase)

Adds the given key-pair to the key-store, protected by a mandatory passphrase.

Public key is used as alias if none is provided.

See key-pair-set.

📄 load

(load path)
(load path passphrase)

Loads a key store from the file under path.

Passphrase must be provided if the store is protected by one.

📄 save

(save key-store path)
(save key-store path passphrase)

Saves the given key-store to the file under path.

An optional passphrase protecting the store may be provided.

---

convex.server

Running a peer server.

Can either:

• Run alone for dev and test
• Run locally, synced with other local peers
• Run locally but synced with the test network on convex.world

See README.

📄 controller

(controller server)

Returns the controller associated with server.

It was either explicitly specified in create or retrieved from the state.

📄 create

(create keypair)
(create keypair option+)

Returns a new peer server.

Can be started using start when required.

A key pair is mandatory. See the convex.key-pair.

An map of options may be provided:

Key	Value	Default
:convex.server/bind	Bind address (string)	"localhost"
:convex.server/state	See below	[:genesis]
:convex.server/controller	Controller account address	Retrieved from state
:convex.server/db	Database (see :module/cvm)	Default temp instance created automatically
:convex.server/n-peer	Maximum number of other peers this one should broadcast to	20
`:convex.server/persist-at-stop?	True if peer data should be persisted in DB when stopped	true
:convex.server/port	Port	18888
`:convex.server/url	URL of this peer (string) that will be registered on chain	/

The URL, if given, is stored on-chain so that other peers can use it to broadcast beliefs and state updates. It is typically different from :convex.server/bind and :convex.server/port. For instance, convex.world has registered URL convex.world:18888 in on-chain peer data, it is publicly accessible to all peers which wants to broadcast data to it.

A peer needs initial state optionally specified in :convex.server/state which is a vector. Either:

Item 0	Item 1	Does
:genesis	/	Creates new genesis state from scratch
:db	/	Restores state from :convex.server/db
:sync	Option map	Performs peer syncing (see below)
:use	State cell	Advanced. Uses given convex.core.State cell

Peer syncing retrieves state from the given peer and connection will automatically be formed to that other peer at start, forming a network. The option map may specify:

Key	Value	Default
:convex.server/host	Address of the remote peer	"localhost"
:convex.server/port	Port of the remote peer	18888

📄 db

(db server)

Returns the Etch instance used by the server.

📄 host

(host server)

Returns bind address used by the server as a string.

📄 peer

(peer server)

Returns the peer object wrapped by the server.

For advanced users only.

📄 persist

(persist server)

Persists peer data at the root of the server's Etch instance.

Persisted data can be recovered when creating a server with the same Etch instance (see :convex.server/state option in create).

Done automatically at stop is :convex.server/persist-at-stop? as set to true at create.

However, the database is not flushed. See convex.db/flush from :module/cvm.

Returns the server.

📄 port

(port server)

Returns the port used by the server.

📄 start

(start server)

Starts server.

See create first.

If peer syncing was configured in create, also connects to remote peer.

Returns the server.

📄 stop

(stop server)

Stops server.

Previously started with start.

Does not close the Etch instance optionally provided when starting.