Kanari Network

Technical Whitepaper

Version 2.0 — 12 August 2026

Abstract

Kanari is an object-centric programmable payment network implemented in Rust and Move. It combines Mysticeti-style DAG consensus, deterministic Move execution, explicit object ownership, incremental Sparse Merkle Tree roots, RocksDB persistence, and cryptographic agility including post-quantum and hybrid signatures.

This whitepaper documents the implemented design and measured engineering behavior. Performance is workload-dependent; no TPS, latency, or finality number is a protocol guarantee.

Principles

1. Consensus metadata and committed state are separate layers.
2. Checkpoints advance only for real committed work.
3. State roots and native supply must converge after recovery.
4. Runtime policy and Move contract authorization are separate controls.
5. Security and performance claims require reproducible tests and metrics.

1.1 Scope and terminology

In this paper, submitted means accepted by an API, executed means evaluated by Move, and committed means that effects passed validation and were durably applied to canonical state and a checkpoint. Only committed state is externally final. A valid signature therefore does not guarantee execution success.

Kanari is not presented as a permissionless deployment by default. Validator membership, genesis material, peer identity, upgrade policy, and key custody remain deployment decisions. The implementation provides audit points for those decisions; it does not remove operational risk.

1.2 Design trade-offs

Object parallelism helps independent transactions but hot shared objects create a dependency lane. Post-quantum signatures improve long-term cryptographic posture at the cost of larger keys, signatures, CPU, and bandwidth. Persistent durability improves recovery guarantees at the cost of write amplification and compaction. These trade-offs are reported explicitly rather than hidden behind one TPS number.

1.3 Versioning

State schema, transaction, signature, and backup formats require explicit version identifiers. A node must reject an incompatible format or run a tested migration; it must not guess a legacy interpretation.

2. Architecture and Consensus

2.1 DAG and authority flow

Authorities receive signed transactions, publish DAG vertices, exchange dependency references, and feed ordered work into execution. A vertex is consensus metadata; it is not itself a committed state transition.

The pipeline is: receive and validate; propagate and order; schedule object access sets; execute deterministic effects; apply and persist the changeset; then advance the checkpoint.

2.2 Safety invariants

• duplicate vertices cannot execute twice;
• missing rounds trigger synchronization;
• DAG traffic cannot create empty checkpoints;
• a root mismatch at equal height is an observable divergence;
• honest nodes converge on checkpoint height, root, and supply.

2.3 Fault model

The design covers delayed, duplicated, reordered, and missing P2P messages, follower or leader termination, and multi-node restart. Byzantine safety still depends on an honest-validator quorum and deterministic execution.

2.4 Components

kanari-core orchestrates execution and checkpoints. kanari-node provides startup, P2P, synchronization, and service wiring. kanari-rpc-server exposes validated APIs. kanari-move-runtime-v1 applies Move state. crates/smt maintains canonical sparse roots.

2.5 Protocol phases

The normal path is: client signing; RPC decoding and admission; pending-queue intake; DAG proposal and synchronization; consensus ordering; Move execution; changeset validation and application; durable checkpoint persistence; and committed-result queries. Each phase has a separate error boundary and should expose latency and failure metrics.

2.6 Byzantine and failure assumptions

Safety depends on the configured Mysticeti-style quorum and deterministic commit rules. Liveness additionally depends on network delivery, available storage, and responsive authorities. A malicious validator may send conflicting or malformed messages, so author, round, parents, signatures, identity, and replay status must be checked before a vertex is injected.

2.7 Limits of the claim

A DAG does not automatically prove fairness, censorship resistance, or a particular finality time. Those properties require protocol-specific proofs and measurements. Kanari reports convergence evidence and treats latency and fairness improvements as engineering goals unless formally specified.

2.8 Consensus safety model

For an authority set of size n and Byzantine bound f, the conventional quorum condition is:

n >= 3f + 1 and q = 2f + 1

Here q is the minimum commit support under the configured BFT protocol. This describes the deployment assumption; the exact commit rule remains defined by the implementation and protocol configuration.

3. Move Execution and Object Model

3.1 Deterministic execution

Move modules express typed resources and application state transitions. Ordered transactions execute deterministically and produce a changeset. Failed execution is atomic: no partial canonical state is accepted.

3.2 Owned and shared objects

Independent owned-object transactions can be scheduled in parallel. Conflicting access sets, shared objects, and hot objects remain dependency-ordered. Object versions and digests prevent stale references from being reused.

Native Coin<KANARI> inputs have strict runtime ownership. A mutable transfer coin must be distinct from the gas object, and a sender cannot mutate another owner's coin. DeFi objects may be passed explicitly across owners for escrow workflows; the Move contract must enforce buyer, seller, admin, and owner roles.

3.3 Gas metering

Gas accounts for bytecode, serialization, vectors, native calls, and value size. Native transfer, split, merge, burn, and gas adjustment paths share the same accounting and fail closed on overflow or insufficient balance.

3.4 Developer workflow

Developers build and test Move packages, publish modules through the Kanari CLI, submit signed transactions through RPC, and inspect committed effects and object references.

3.5 Access-set scheduling

The scheduler classifies inputs as owned, shared, immutable, or gas objects. Independent owned-object transactions may run in parallel; transactions touching the same versioned object are ordered through a dependency lane. Parallel execution must remain equivalent to deterministic serial replay.

3.6 DeFi and escrow obligations

Runtime acceptance of a mutable object does not prove business authority. An escrow module must check buyer, seller, administrator, state transition, amount, and replay conditions on every public entry function. Tests must cover create, delivery, release, dispute, refund, and unauthorized cross-role calls.

3.7 Failure atomicity

Effects are staged as a changeset. Validation covers ownership, versions, duplicate mutable inputs, supply arithmetic, and gas. The applier commits an accepted set atomically from the perspective of canonical state; recovery must never expose a half-applied object graph.

3.8 Conflict rule

For transactions T_i and T_j, parallel execution is valid only when their mutable access sets are disjoint:

Mutable(T_i) ∩ Mutable(T_j) = ∅

If the intersection is non-empty, the scheduler must impose a dependency order or reject the stale reference. This is a scheduling condition, not a replacement for Move-level authorization.

4. State, Storage, and Supply

4.1 Canonical state

Canonical state consists of committed objects, Move resources/modules, and checkpoint metadata. Derived owner indexes, access versions, and visible supply caches are rebuildable and must not silently alter the canonical root.

4.2 Sparse Merkle roots

The SMT uses domain-separated leaf and node hashes. Incremental overlays update affected paths and verify the resulting root before persistence. Full materialization remains an audit and repair path, not the normal hot path.

4.3 RocksDB recovery

Checkpoint markers and canonical indexes are persisted with state overlays. Startup validates markers, object references, and root metadata. Recovery audits compare height, transaction count, state root, object indexes, and native supply across validators.

4.4 Native supply invariant

For native KANARI:

total_supply = circulating_supply + object_locked_supply + untracked_supply

Mint, burn, transfer, split, merge, gas, escrow lock, and escrow release preserve this invariant. Correctly tracked operations finish with untracked_supply = 0. Invalid treasury/object state fails closed.

4.5 Payment economics

Zero-price developer configurations do not mean zero system cost. Validators still pay for CPU, memory, network, storage, compaction, and recovery.

4.6 Canonical versus derived data

The canonical root covers logical state that must be replayable. Owner indexes, access-version caches, query projections, and metrics are derived data and may be rebuilt. A cache must not silently change canonical state during restart or speculative execution.

4.7 Incremental root algorithm

An SMT update changes a leaf and its sibling path. Kanari batches affected leaves through an overlay and reuses unchanged subtrees; it verifies ordering, duplicate-key behavior, node hashes, and the final root before persistence. Serial, parallel, property, and recovery tests are required to establish equivalence to full recomputation.

4.8 Durability boundary

RocksDB provides the storage engine and WAL/recovery behavior; Kanari adds checkpoint markers, schema validation, and root/supply audits. Durability is only as strong as the configured filesystem and device. Unix and Windows deployments must test their actual sync policy and power-loss recovery.

4.9 State transition and root

Let S_h be canonical state at checkpoint h, C_h the accepted changeset, and R_h the state root:

S_(h+1) = Apply(S_h, C_h)

R_(h+1) = H(CanonicalEncode(S_(h+1)))

The incremental SMT must produce the same R_(h+1) as a full recomputation. A recovery audit therefore checks both the persisted root and the replayed root.

5. Cryptography and Security

5.1 Cryptographic agility

kanari-crypto supports Ed25519, K256, P256, Dilithium/ML-DSA2/3/5, Falcon512/1024, SPHINCS+ SHA256 robust, and K256+Dilithium3 or Ed25519+Dilithium3 hybrids. It also provides AES-256-GCM, Argon2id, SHA3, SHAKE256, and BLAKE3.

Classical signatures remain useful for compatibility and speed. Hybrid or post-quantum schemes are appropriate for keys requiring long-term protection. PQC provider maturity and independent-audit status must be tracked.

5.2 Wallet safety

Curve metadata, private-key material, and derived address must agree. Malformed seeds, wrong lengths, hybrid truncation, and key/address mismatches fail closed. HD derivation paths should be versioned in wallet migrations.

5.3 RPC boundary

RPC rejects malformed JSON/BCS, invalid signatures, nonce replay, stale object versions/digests, duplicate mutable inputs, gas overlap, oversized requests, and rate-limit abuse. Admin/debug methods require separate deployment controls.

5.4 DeFi authorization

Runtime object policy prevents unsafe Coin mutation, but it cannot infer application roles. Every public Move entry point that mutates an escrow, pool, vault, or admin object must check the signer and lifecycle state.

5.5 Audit posture

Nightly CI repeats boundary/property tests for RPC, object policy, consensus, and SMT and uploads a RustSec report. This is engineering assurance, not a substitute for an independent audit.

5.6 Algorithm selection

Classical signatures are smaller and usually faster. ML-DSA and SLH-DSA use the NIST standard names while retaining compatibility names where needed. Hybrid signatures require both constituent verifications. Address derivation, serialization, signature framing, and migration rules must match across wallet, RPC, node, and Move-native paths.

5.7 Key lifecycle

Private keys must use a cryptographically secure RNG, authenticated encryption at rest, and zeroization where supported. Stored curve, derivation path, public key, and address are cross-checked on load; mismatch fails closed. Malformed or truncated key material must never panic or silently select another curve.

5.8 Adversarial boundary

Treat every RPC, P2P, Move argument, keystore, and backup byte as hostile. Enforce limits before allocation, canonical decoding, signature-domain separation, nonce/replay checks, object digest/version checks, and bounded work per request. A NIST algorithm name or passing unit test is not an independent audit.

5.9 Authenticated encryption model

For plaintext P, key K, nonce N, and associated metadata A, authenticated encryption returns ciphertext and tag:

AEAD_Encrypt(K, N, P, A) -> (C, tag)

Decryption must reject unless the tag verifies:

AEAD_Decrypt(K, N, C, A, tag) -> P or Reject

Wallet and backup formats must bind version, curve, and metadata through authenticated data so a valid ciphertext cannot be relabeled as another key type.

6. Operations, APIs, and Performance

6.1 Integration surfaces

Applications use the CLI and JSON-RPC for wallet operations, object queries, module publishing, transaction submission, and committed-effect inspection. Move packages define asset, escrow, marketplace, and DeFi behavior.

6.2 Multi-node operation

Validators must use the same binary and compatible persistence schema, isolated data directories, stable peer identity, and monitored disk capacity. Operators should alert on root mismatch, stalled synchronization, unexpected supply, RPC errors, and RocksDB write stalls.

6.3 Measured results

The current campaign reports:

• 4-node live chaos with duplicate P2P publishes, delay, node kills, restarts, and adversarial RPC: roots and supply converged; no server/network errors. • Persistent 4-node profile: 100/100 successful transactions, approximately 47 TPS aggregate lane throughput on the tested Windows host. • In-memory owned-object production benchmark: approximately 13K TPS under its stated workload.

These values are not interchangeable. Persistent RocksDB, signature choice, object fanout, validator count, and transaction mix materially change throughput.

6.4 Load methodology

Every benchmark should record commit, OS, CPU/RAM, validator count, storage backend, sender count, object fanout, transaction count, duration, failures, root convergence, and supply convergence. Setup fanout must be separated from execution TPS.

6.5 Capacity interpretation

Throughput is a vector: persistent versus in-memory state, signature scheme, transaction bytes, object count, shared-object contention, checkpoint frequency, network delay, and compaction all matter. Capacity reports should include p50/p95/p99 latency, success/failure counts, CPU, RSS, disk writes, compaction bytes, queue depth, and recovery time.

6.6 Production topology

Nodes may be placed in different regions when advertised addresses, firewall rules, time synchronization, bandwidth, and latency are configured correctly. Public RPC should use TLS or a hardened reverse proxy. P2P should use stable identities and explicit bootstrap/static peers; admin/debug endpoints should remain private or strongly authenticated.

6.7 Observability

Alert on root divergence, supply mismatch, untracked supply, checkpoint stagnation, pending growth, sync gaps, P2P queue saturation, RocksDB write stalls, compaction debt, failed signatures, and repeated nonce/object-version failures. Logs must never contain passwords or private keys.

6.8 Measurement equations

For (N) committed transactions over elapsed time Δt, measured throughput is:

TPS = N / Delta_t

This excludes setup unless explicitly stated. For a parallel run with lanes (L_k), aggregate throughput is:

TPS_aggregate = sum(N_k / Delta_t_k)

The report must also state failures, storage backend, signature scheme, fanout, and root/supply convergence; TPS alone is not a safety or capacity claim.

7. Roadmap and Conclusion

7.1 Near-term work

1. Complete multi-hour and multi-day live validator soak with real wallets.
2. Finish persistent 10K+ capacity campaigns after setup fanout is provisioned efficiently.
3. Profile RocksDB compaction, flush, and write-stall behavior under sustained load.
4. Expand nightly fuzz corpora for BCS/RPC, object authorization, consensus, and SMT.
5. Audit every Move native and RPC build/submit path.

7.2 Longer-term work

• migrate away from unmaintained dependencies where compatibility permits; • independently review PQC providers and signature batch verification; • add production metrics, alerting, backup verification, and operator runbooks; • add lane-specific schedulers for owned, shared, and hot objects; • add a streaming validator backup format with compatibility-preserving migration.

7.3 Conclusion

Kanari keeps consensus, execution, storage, and application authorization explicit. The network advances only when real work is committed, and operators can verify that validators agree on state root and supply after failures. This supports continued testnet and product development while preserving an evidence-based path toward production readiness.

7.4 Release gates

A release candidate should have clean reproducible builds, migration tests for supported state and wallet formats, full unit/integration tests, adversarial RPC and Move authorization tests, four-node crash/restart convergence, persistent-load results with hardware metadata, dependency audit output, and an operator runbook. An unmet gate is recorded as a limitation, not hidden by a compatibility fallback.

7.5 Research directions

Priorities include efficient owned-object batching, adaptive object lanes, streaming backup encryption, state-root batching with equivalence tests, ordering-fairness analysis, batch signature verification, and independently reviewed PQC providers. Each must preserve deterministic replay, supply conservation, and migration semantics.

7.6 Closing statement

Kanari should be evaluated like a distributed financial system: by invariants, adversarial tests, operational evidence, and independent review—not by a headline benchmark alone.

8. Verification, Claims, and Reproducibility

8.1 What this document claims

This paper is an engineering specification for the implementation in this repository, not a proof that every deployment is secure. Statements are classified as:

The distinction prevents a benchmark from being mistaken for a protocol guarantee and prevents a library choice from being mistaken for a security certification.

8.2 Reproducible experiment record

Every performance or failure campaign should record the commit identifier, operating system, CPU model and core count, RAM, storage medium, Rust toolchain, build profile, validator count, RPC/P2P ports, transaction mix, sender count, object fanout, gas policy, duration, failures, peak memory, and final root/supply audit. Setup work (wallet derivation, faucet or native fanout, and database creation) must be reported separately from execution throughput.

The repository's scripts under scripts/ are the reference harness. They emit logs and JSON summaries so another operator can distinguish a transaction failure, a node failure, a synchronization delay, and a setup bottleneck. A result without these fields is informative only, not a capacity claim.

8.3 Current verification evidence

The latest engineering campaign recorded:

• SMT: 24 tests passed, including parallel and property-oriented cases.
• RPC server: 37 tests passed, including malformed input, object references, and gas/object overlap.
• Move runtime/state: more than 120 unit and persistence tests passed.
• Four-node chaos: duplicate publishes, 200 ms delay, two-node crash/restart, recovery audit, root convergence, supply convergence, and adversarial RPC probes passed.
• Persistent four-node profile: 100/100 transactions succeeded at approximately 47 aggregate lane TPS on the tested Windows host.
• In-memory owned-object benchmark: approximately 13K TPS for the stated deterministic workload; this is not persistent-network TPS.

These results are evidence for the tested scenarios only. They do not establish a universal TPS, latency, validator count, or Byzantine tolerance beyond the configured protocol assumptions.

8.4 Safety and liveness obligations

For every committed checkpoint, validators must agree on the checkpoint height, transaction effects, canonical state root, object versions, and native supply summary. For every rejected transaction, no partial canonical mutation may remain. For every restart, recovery must either restore the last complete checkpoint or fail closed; it must not silently invent objects, supply, or ownership.

Liveness is conditional on network synchrony, sufficient honest validators, available storage, and a functioning execution queue. A stalled or partitioned node is not evidence of a safety violation, but an operator must alert on prolonged root divergence, synchronization gaps, write stalls, or unbounded pending work.

8.5 Security review boundary

The review boundary includes Move authorization, native functions, transaction decoding, signature and nonce checks, object version/digest checks, gas/input overlap, consensus message validation, peer admission, persistence/recovery, key storage, and dependency advisories. PQC implementations are treated as cryptographic dependencies, not as an independent audit of Kanari itself. Public deployments still require key rotation, secret backup, TLS or a trusted reverse proxy, restricted admin endpoints, rate limits, and incident procedures.

8.6 Known limits and acceptance gates

Before a production release, the project should complete a multi-hour or multi-day four-node soak with real wallets, crash/restart during persistent load, larger RocksDB compaction/write-stall profiles, nightly fuzzing for BCS/RPC/object authorization/consensus/SMT, and an external review of native/RPC paths. A release may ship with an explicit limitation, but it must not label an unmeasured property as guaranteed.

8.7 Current implementation inventory

The implementation described by this paper is distributed across these repository surfaces:

The source of truth for behavior is the matching code, tests, migration notes, and release commit. This table is an audit map, not a claim that every path is independently certified.

9. References

The design uses established standards and research as design inputs. These references explain the underlying primitives; they do not certify the Kanari implementation.

1. Babel, Chursin, Danezis et al., Mysticeti: Reaching the Limits of Latency with Uncertified DAGs, arXiv:2310.14821 (2023). https://arxiv.org/abs/2310.14821
2. NIST, FIPS 204: Module-Lattice-Based Digital Signature Standard (ML-DSA) (13 Aug 2024). https://csrc.nist.gov/pubs/fips/204/final
3. NIST, FIPS 205: Stateless Hash-Based Digital Signature Standard (SLH-DSA) (13 Aug 2024). https://csrc.nist.gov/pubs/fips/205/final
4. Josefsson and Liusvaara, RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA) (2017). https://www.rfc-editor.org/rfc/rfc8032
5. Biryukov, Dinu, Khovratovich, and Josefsson, RFC 9106: Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications (2021). https://www.rfc-editor.org/rfc/rfc9106
6. Facebook/Meta, RocksDB Overview and Recovery Notes. https://github.com/facebook/rocksdb/wiki/RocksDB-Overview
7. The Move Book, Ownership, Object Model, and Fast Path. https://move-book.com/
8. NIST, Post-Quantum Cryptography FAQ and validation material. https://csrc.nist.gov/Projects/post-quantum-cryptography

Citation policy

Normative protocol behavior is defined by the Kanari source code, tests, and versioned migration notes. External papers and standards are cited to explain terminology and security assumptions only. When an implementation differs from a cited paper or standard, this document intentionally describes the implementation rather than implying equivalence.