Skip to content

Architecture

System components

Component Binary Purpose
chaind packages/node Chain node: consensus, block production, transaction execution, RPC API
admissiond packages/admission Admission service: receives Wasm uploads, validates, compiles, votes on code activation
chainctl packages/cli Developer and operator CLI

Nodes run chaind alongside admissiond. The admission service handles the computationally expensive Wasm compilation off the consensus hot path.

Consensus

Wasichain uses Commonware's simplex consensus protocol -- a threshold-based BFT protocol with BLS aggregate signatures. Validators participate in round-robin block proposal with a target block time of 1 second (configurable via target_block_time_ms in genesis).

The chain supports two operational modes:

  • Dev mode -- single-validator, no P2P networking, no consensus protocol. For local development.
  • Consensus mode -- multi-validator with simplex consensus and authenticated P2P networking.

Contract lifecycle

Code goes through distinct phases before contracts can be instantiated from it:

Upload (blob to admissiond)
  -> Announce (UploadCodeManifest tx)
    -> Pending (validators download blob)
      -> Admitted (quorum of PreparedCodeVote txs)
        -> Activated (code ready for instantiation)
  1. Upload -- raw .wasm bytes are sent to an admission endpoint (POST /v1/code).
  2. Announce -- the uploader submits an UploadCodeManifest transaction containing the code hash, blob size, and VM version string.
  3. Pending -- validators download the blob and begin compilation.
  4. Admitted -- each validator that successfully compiles the code submits a PreparedCodeVote. Once a quorum is reached, the code is admitted.
  5. Activated -- the code receives a sequential code_id and can be used to instantiate contracts.

Storage model

Each contract has an isolated KV namespace. All reads and writes during execution go through a transactional KvOverlay. On success the overlay is committed to chain state; on failure it is discarded.

For cross-contract calls, an OverlayStack provides nested frames -- each sub-message gets its own frame. On sub-message success the frame merges into its parent; on failure it is discarded.

Fee model

Fees are defined in genesis (fees.toml):

Fee type Description
intrinsic_tx_fee Base fee for every transaction
fuel_price Cost per unit of Wasmtime fuel consumed
base_upload_fee + upload_byte_price Upload costs
base_compile_fee + compile_byte_price Compilation costs (with size-class surcharges)
event_byte_price Cost per byte of emitted event data

Execution is metered via Wasmtime fuel. The maximum fuel per transaction is capped by max_fuel_per_tx (default: 10 billion units).