Architecture¶

System components¶

Nodes run chaind alongside admissiond. Public clients typically talk to gatewayd on the gateway port rather than directly to the internal services.

At the application layer, Wasichain is designed for two execution roles:

• deterministic contracts for durable on-chain state
• network-connected services for workflows that cannot live inside the deterministic VM

Both are packaged as WASI components.

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 through genesis.

The chain supports two operational modes:

• Dev mode -- single-validator, no P2P networking, no consensus protocol. Useful 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 (raw blob)
  -> Announce (UploadCodeManifest tx)
    -> Pending (code_id assigned on-chain)
      -> Admitted (first valid PreparedCodeVote seen)
        -> Activated (quorum reached, activation certificate stored)

1. Upload -- raw .wasm bytes are sent to the code upload endpoint. The blob is identified by its SHA-256 hash.
2. Announce -- the uploader submits an UploadCodeManifest transaction containing the code hash, blob size, and VM version string.
3. Pending -- the chain allocates a new sequential code_id and binds it to that exact code_hash.
4. Admitted -- validators prepare the blob locally and submit PreparedCodeVote attestations.
5. Activated -- once a quorum is reached, the chain marks the code Activated and stores an activation certificate.

How operators agree on the code behind a code_id¶

The on-chain code record stores both:

• a sequential code_id
• the SHA-256 code_hash of the raw uploaded Wasm bytes

Execution resolves code_id -> code_hash, then loads the locally cached compiled artifact for that hash and VM version.

Two details make this stable:

• duplicate code hashes are rejected on upload, so a code_id maps 1:1 to a unique raw Wasm blob
• activation requires quorum on PreparedCodeVote attestations for that code hash and VM version

Consensus cares about the raw Wasm hash, VM version, and activation fact, not about machine-specific native compiled bytes.

Contract addresses¶

Contract addresses are deterministic:

SHA-256(creator_address || code_id_be_bytes || SHA-256(label))

The label hash acts as a salt so the same account can instantiate the same activated code more than once. Because duplicate code hashes are rejected, using code_id does not create multiple identities for identical uploaded binaries.

Storage model¶

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

For cross-contract calls, nested overlays provide savepoints per sub-message. A successful sub-message merges into its parent frame; a failed one is discarded.

Runtime model¶

Wasichain executes contracts in Wasmtime with a restricted host surface. Contracts are plain WASI Preview 2 components, but they only receive:

• the Wasichain WIT host ABI
• capability-denied WASI shims needed to satisfy the component model

Services are the complementary execution model: WASI components for network-connected and nondeterministic workflows that still feed accepted results back into ordinary contract execution.

See:

• Security for sandboxing, determinism, and attack resistance
• Fees & Fuel for metering, pricing, and validator fee distribution