Kanari Network

Technical Whitepaper

Abstract

Kanari is a Rust-based network for programmable payments and application state transitions. The current design combines Mysticeti-style DAG ordering, a Move-based execution layer, and checkpoint persistence that advances only when real transactions exist.

This whitepaper documents the architecture as it exists today. It avoids fixed promises for throughput, latency, or finality because those values depend on hardware, validator topology, storage behavior, and workload shape.

1. Introduction

Kanari is designed around a small set of operational principles:

  • consensus metadata and blockchain state are different layers
  • checkpoints must correspond to executed transactions
  • idle networks should not manufacture empty chain progress
  • state divergence must be visible and debuggable

This approach is useful for payment systems, application backends, and asset workflows where developers care more about deterministic state progression than about synthetic block production.

The network is implemented primarily in Rust, uses Move for programmable execution, and keeps the state model explicit so operators can reason about persistence, replay, and recovery behavior.

2 Architecture & Mysticeti Consensus

2.1 DAG Ordering in Kanari

Kanari uses a Directed Acyclic Graph to exchange ordering metadata between authorities. DAG traffic helps validators agree on the order of work, but it does not directly define blockchain state.

That distinction is intentional:

  • DAG sync must not create synthetic checkpoints
  • network liveness must not inflate blockchain height
  • state roots must come from executed transaction effects

2.2 Mysticeti-Style Authority Flow

The current implementation follows a Mysticeti-oriented authority model.

At a high level:

  1. Authorities receive and propagate transactions.
  2. Validators exchange DAG vertices and dependency references.
  3. Ordered transaction batches move into execution.
  4. A checkpoint is finalized only if there are pending transactions to commit.

This keeps consensus progress and state progress aligned without forcing empty blocks during quiet periods.

2.3 Checkpoint Invariants

Kanari currently treats the following rules as architectural invariants:

  • no pending transactions means no new checkpoint
  • DAG metadata propagation alone must not advance chain height
  • nodes catching up from peers should replay committed work instead of inventing local progress
  • state roots at the same checkpoint height should converge across honest nodes

These rules make explorer output and operator debugging much easier to trust.

2.4 Security Model

Kanari assumes partial faults and Byzantine behavior are possible. Safety depends on deterministic execution and validator agreement on the ordered transaction set.

Operationally this means:

  • root mismatches at the same height are treated as real divergence signals
  • lagging nodes must resync from committed history
  • checkpoint persistence must reflect executed state, not transient consensus chatter

2.5 Component Overview

The main runtime components are:

  • kanari-core: execution orchestration, checkpoint production, persistence, DAG integration
  • kanari-node: runtime startup, networking, synchronization, RPC bootstrapping
  • kanari-rpc-api: public method surface and shared RPC types
  • kanari-rpc-server: JSON-RPC handlers and query endpoints
  • kanari-move-runtime-v1: Move execution and state application
  • crates/smt: sparse Merkle tree support for state-root maintenance

This separation lets Kanari optimize execution and storage without weakening the consensus model.

3. MoveVM Execution Layer

3.1 Why Move for Kanari

Kanari uses Move to express programmable state transitions with deterministic execution rules. This is useful for payment and asset workloads where ownership, balances, and module-level policy need to remain explicit.

3.2 Execution Model

The execution path is intentionally simple:

  1. signed transactions enter the mempool
  2. ordered batches are selected for execution
  3. Move applies state changes deterministically
  4. committed effects are persisted into checkpoint history

Execution does not define consensus by itself. It consumes ordered work and produces state changes that can be verified and replayed.

3.3 Transaction-Driven Progress

Kanari does not advance checkpoint height just because the network is alive. The Move layer participates only when there is real work to execute.

Benefits of this model:

  • no empty-checkpoint spam
  • clearer explorer semantics
  • state-root changes stay tied to actual transactions

3.4 Performance Notes

Observed performance depends on:

  • transaction mix
  • signer distribution
  • worker count
  • storage backend cost
  • state-root update strategy

For that reason, benchmark numbers should always be published together with the exact command, code revision, and hardware profile used.

3.5 Developer Workflow

Typical development flow:

# Create or update a Move package

# Build modules

# Run tests

# Publish through the Kanari toolchain

Developers should treat the runtime as deterministic infrastructure, not as a source of synthetic chain activity.

4. The Zero-Fee Payment Infrastructure

4.1 Fee Policy

Kanari is designed for low-friction application flows. In the current developer setup, many examples use zero-gas or operator-controlled fee policy so teams can test payment paths without exposing end users to chain UX complexity.

4.2 Why This Matters

For payment-oriented systems, fee predictability is often more important than speculative token mechanics. Kanari therefore emphasizes:

  • simple transfer flows
  • predictable application behavior
  • developer-controlled integration surfaces

4.3 Account and Asset Flows

Kanari supports programmable account and asset workflows through Move modules and RPC services. This allows teams to model balances, token logic, escrow, and application-specific rules without changing the consensus layer.

4.4 Economic Considerations

The cost model still exists even when user-facing gas is hidden:

  • operators pay for hardware, storage, and availability
  • validators pay for synchronization and persistence work
  • application design still determines system load

A low-friction UX is sustainable only when runtime and storage behavior stay efficient.

4.5 Payment Scenarios

Example use cases include:

  • consumer payment flows
  • in-game assets and marketplace settlement
  • creator payouts
  • service credits and prepaid balances
  • internal application accounting

The shared requirement across these cases is deterministic, observable state progression.

5. Infrastructure & Networking

5.1 Rust Runtime

Kanari's node and core services are written in Rust to keep concurrency, storage control, and networking behavior explicit.

5.2 Networking Model

A running node combines several responsibilities:

  • peer-to-peer communication between authorities
  • DAG metadata exchange
  • mempool transaction propagation
  • JSON-RPC access for clients and tooling

The network layer must allow validators to sync without turning synchronization into fake blockchain progress.

5.3 Storage Model

Storage efficiency is a major part of correctness and performance. The current direction emphasizes:

  • compact checkpoint metadata
  • incremental state-root maintenance where possible
  • separation between summary records and heavier transaction payloads

This reduces unnecessary recomputation and keeps persistence work closer to the actual transaction delta.

5.4 State Roots and Divergence Detection

State roots are not cosmetic metrics. They are how operators verify that nodes which claim the same checkpoint height also agree on the same committed state.

If two nodes report different roots at the same checkpoint height, that indicates divergence and should trigger investigation or resync.

5.5 Deployment Notes

Kanari supports single-node and multi-node developer setups. In multi-node environments, validators should be restarted from consistent binaries and data expectations so explorers and RPC queries are interpreting the same runtime behavior.

6. The Universal Payment Ecosystem

6.1 Developer Surfaces

Kanari exposes a set of tools for application teams:

  • node runtime and CLI workflows
  • JSON-RPC endpoints
  • Move packages and publish flows
  • explorer and monitoring surfaces

6.2 Integration Approach

A typical integration uses RPC for reads and transaction submission, while Move modules define application behavior.

Common patterns include:

  • balance and asset queries
  • transaction submission
  • module publishing
  • object and ownership inspection

6.3 Explorer Semantics

Explorer output should reflect committed history, not synthetic progress. If the explorer shows unexpected transaction count changes, the correct first step is to inspect checkpoint persistence, transaction indexing, and any retained historical data before assuming new user traffic exists.

6.4 Operational Guidance

For accurate multi-node behavior:

  • run the same node build on every authority
  • avoid mixing old and new persistence semantics
  • rebuild and restart when checkpoint logic changes
  • verify both height and state root during debugging

6.5 Application Direction

Kanari is suitable for teams building application-specific payment and asset systems where clear state semantics matter as much as raw execution speed.

7. Roadmap & Conclusion

7.1 Current Engineering Priorities

The most important optimization areas are:

  • incremental state-root maintenance
  • reducing transaction cloning between execution and checkpoint paths
  • keeping checkpoint persistence compact
  • preserving deterministic replay and divergence visibility

7.2 Operational Safety

Kanari should prefer explicit invariants over hidden automation. That means:

  • do not generate checkpoints without transactions
  • do not hide state-root mismatches
  • do not treat sync traffic as committed execution

These rules make debugging harder to ignore, but they keep the system honest.

7.3 Performance Scaling

Performance work should be measured, not assumed. Useful benchmark reports include:

  • exact command line
  • validator count
  • sender distribution
  • CPU and RAM profile
  • workload mode

Without that context, a TPS number is only anecdotal.

7.4 Long-Term Direction

The long-term goal is a payment-oriented programmable network with:

  • efficient execution
  • compact persistence
  • clear validator recovery behavior
  • observable state convergence

7.5 Conclusion

Kanari's current design is centered on one simple idea: blockchain state should move only when real user work is committed. Mysticeti-style ordering, Move execution, and explicit state-root comparison all serve that goal.

That makes the system easier to reason about, easier to benchmark honestly, and easier to operate in a multi-node environment.