Concepts

Transactions

Each transaction is an atomic state update containing several contract calls organized in a tree.

A contract call is the call data and function ID that calls a specific contract function. Additionally associated with each call are proofs and signatures that can be verified in any order.

/// A Transaction contains an arbitrary number of `ContractCall` objects,
/// along with corresponding ZK proofs and Schnorr signatures. `DarkLeaf`
/// is used to map relations between contract calls in the transaciton.
#[derive(Clone, Default, Eq, PartialEq, SerialEncodable, SerialDecodable)]
pub struct Transaction {
    /// Calls executed in this transaction
    pub calls: Vec<DarkLeaf<ContractCall>>,
    /// Attached ZK proofs
    pub proofs: Vec<Vec<Proof>>,
    /// Attached Schnorr signatures
    pub signatures: Vec<Vec<Signature>>,
}
/// A ContractCall is the part of a transaction that executes a certain
/// `contract_id` with `data` as the call's payload.
#[derive(Clone, Eq, PartialEq, SerialEncodable, SerialDecodable)]
pub struct ContractCall {
    /// ID of the contract invoked
    pub contract_id: ContractId,
    /// Call data passed to the contract
    pub data: Vec<u8>,
}

The tree of structure for contract calls corresponds to invocation semantics, but with the entire callgraph unrolled ahead of time.

WASM VM

Host refers to the context which loads and calls the WASM contract code.

Contracts are compiled WASM binary code. The WASM engine is a sandboxed environment with limited access to the host.

WASM exports are functions exported from WASM and callable by the WASM engine.

Contract Sections

Contract operation is defined by sections. Each contract section is only allowed to call certain host functions.

Example: exec() may call db_get() but not db_set(), while update() cannot call db_get(), but may call db_set().

#[derive(Clone, Copy, PartialEq)]
pub enum ContractSection {
    /// Setup function of a contract
    Deploy,
    /// Entrypoint function of a contract
    Exec,
    /// Apply function of a contract
    Update,
    /// Metadata
    Metadata,
    /// Placeholder state before any initialization
    Null,
}

For a list of permissions given to host functions, see the section Host Functions.

Contract Function IDs

Let be defined as in the section Pallas and Vesta.

Functions can be specified using a tuple .

Host Functions

Host functions give access to the executing node context external to the local WASM scope.

The current list of functions are:

Host functionPermissionDescription
db_initDeployCreate a new database
db_lookupDeploy, Exec, Metadata, UpdateLookup a database handle by name
db_setDeploy, UpdateSet a value
db_delDeploy, UpdateRemove a key
db_getDeploy, Exec, MetadataRead a value from a key
db_contains_keyDeploy, Exec, Metadata, UpdateCheck if a given key exists
zkas_db_setDeployInsert a new ZK circuit
merkle_addUpdateAdd a leaf to a merkle tree
set_return_dataExec, MetadataUsed for returning data to the host
get_verifying_block_heightDeploy, Exec, Metadata, UpdateRuntime verifying block height
get_verifying_block_height_epochDeploy, Exec, Metadata, UpdateRuntime verifying block height epoch
get_blockchain_timeDeploy, Exec, Metadata, UpdateCurrent blockchain (last block's) timestamp
get_last_block_infoExecLast block's info, used in VRF proofs