docs: add Fluent system architecture guide

docs/knowledge-base/_category_.json

@@ -1,5 +1,5 @@
 {
   "label": "Knowledge Base",
   "position": 7,
-  "collapsed": true
+  "collapsed": false
 }

docs/knowledge-base/system-architecture.md

@@ -0,0 +1,171 @@
+---
+title: Fluent System Architecture
+sidebar_position: 3
+---
+
+Fluent is built as a **blended execution** system: different execution environments can coexist behind one shared state machine and one proving-oriented runtime model.
+
+This page is a practical architecture map based on:
+
+- the `fluentlabs-xyz/tech-book` architecture chapters, and
+- current Fluentbase runtime docs (`fluentbase/docs/*`).
+
+When older tech-book wording and current runtime behavior diverge, this page follows current Fluentbase behavior.
+
+---
+
+## 1) Big picture
+
+At a high level, Fluent has three layers:
+
+1. **Node/consensus shell** (modified Reth stack): transaction/block pipeline, networking, RPC, and chain integration.
+2. **Execution coordination layer** (REVM integration + host): frame lifecycle, journal/state commit rules, privileged host operations.
+3. **Runtime execution layer** (rWasm-based runtime model): contract logic execution, runtime dispatch, and resumable interruption flow.
+
+The key design choice is that **execution** and **state commitment** are deliberately separated:
+
+- runtimes execute logic and can yield,
+- host/REVM performs authoritative stateful operations,
+- final effects are committed deterministically.
+
+---
+
+## 2) Blended execution model
+
+Traditional multi-VM designs often keep separate VM engines with explicit cross-VM bridges.
+Fluent’s architecture instead centers on one execution substrate and shared state semantics.
+
+In practice:
+
+- applications from different VM ecosystems are represented through Fluent runtime routing,
+- they share one address/state space,
+- composability is native and synchronous at execution time.
+
+This is the architectural reason Fluent emphasizes **blended execution** rather than “many isolated VMs in one node.”
+
+---
+
+## 3) Runtime routing via ownable accounts
+
+Fluentbase uses an ownable-account model to decide **which runtime executes an account**.
+
+Conceptually:
+
+- account identity and account state remain local to that account,
+- execution engine is selected by owner/runtime routing,
+- many accounts can share the same runtime implementation safely.
+
+Create-time routing determines runtime class (for example EVM/default path, and other runtime-specific paths via constructor format/prefix rules).
+
+Execution-time behavior then loads delegated runtime logic while preserving account-specific state isolation.
+
+This is the core mechanism that enables one state machine to host multiple EE styles without per-account VM duplication.
+
+---
+
+## 4) Interruption protocol (`exec` / `resume`)
+
+Fluent runtimes are not treated as all-powerful engines.
+When runtime code needs host-authoritative work (stateful/privileged operations), execution uses interruption:
+
+1. runtime executes,
+2. runtime yields with interruption metadata,
+3. host processes the requested action,
+4. runtime resumes from saved context,
+5. flow continues until final exit.
+
+Important properties:
+
+- resumable contexts are transaction-scoped,
+- call IDs are protocol-significant,
+- host remains final authority for sensitive transitions,
+- deterministic resume behavior is required for consensus safety.
+
+This protocol is one of the most important architecture differences from simpler “single engine call” models.
+
+---
+
+## 5) Syscall architecture (two layers)
+
+Fluentbase separates syscall concerns into two related surfaces:
+
+- **Runtime import layer**: what contracts/runtimes can call through the import namespace.
+- **Host interruption syscall IDs**: host-side operation handlers used during interruption processing.
+
+Why this matters:
+
+- API shape and fuel rules at the import layer affect runtime compatibility,
+- handler semantics at host layer affect consensus behavior,
+- both must evolve in lockstep.
+
+---
+
+## 6) Dual metering: gas and fuel
+
+Fluent keeps both:
+
+- **gas** (EVM-visible economics), and
+- **fuel** (runtime execution accounting).
+
+These are linked by deterministic conversion (currently documented as `FUEL_DENOM_RATE = 20`).
+
+Operationally:
+
+- runtime runs under fuel limits derived from remaining gas,
+- consumed/refunded fuel is translated back into gas settlement,
+- conversion behavior is part of protocol consistency.
+
+So metering is not cosmetic; it is a core architecture contract between runtime and host.
+
+---
+
+## 7) System runtimes and structured envelopes
+
+Fluent distinguishes regular contract execution from selected system/runtime paths.
+For system runtime flows, output is carried in structured envelopes so host can deterministically apply:
+
+- return payload,
+- storage/log effects,
+- metadata transitions,
+- frame/continuation outcomes.
+
+This envelope discipline is essential for correctness when execution is resumable and host-mediated.
+
+---
+
+## 8) Upgrade architecture
+
+Fluent supports privileged runtime upgrades through a constrained control plane.
+
+Design intent:
+
+- allow runtime evolution without repeated hard-fork style node rewrites,
+- keep authority and execution-path checks explicit,
+- enforce host-side validation and routing restrictions for upgrade calls.
+
+In other words, runtime extensibility is intentional, but bounded by strict governance and host enforcement.
+
+---
+
+## 9) Security and consensus boundaries
+
+From an architecture perspective, the highest-risk boundaries are:
+
+- runtime routing integrity,
+- interruption/resume integrity,
+- static-context immutability enforcement,
+- bounds-before-allocation in host paths,
+- syscall semantic determinism,
+- upgrade authority boundaries.
+
+Most critical bugs in this type of system come from violating one of those boundaries, not from ordinary application logic.
+
+---
+
+## 10) Practical mental model
+
+If you need one sentence:
+
+**Fluent is a host-governed, interruption-driven, rWasm-centered blended execution architecture where multiple EE styles share one state machine under deterministic routing, metering, and commit rules.**
+
+That model matches the tech-book architecture goals while aligning with current Fluentbase runtime docs and implementation direction.

docs/system-architecture/01-overview.md

@@ -0,0 +1,82 @@
+---
+title: Architecture Overview
+sidebar_position: 1
+---
+
+Fluent is designed as a **blended execution** system: contracts from different execution environments can coexist behind one shared state machine.
+
+This section explains architecture at a systems level (not line-by-line code internals), using:
+
+- `fluentlabs-xyz/tech-book` as the conceptual baseline,
+- current `fluentbase/docs` as implementation-aligned behavior.
+
+## The core architectural idea
+
+Most systems either:
+
+- run one VM everywhere, or
+- run many VMs side-by-side and bridge between them.
+
+Fluent’s model is different:
+
+- one shared execution/state surface,
+- runtime routing to decide how account logic is executed,
+- host-governed interruption protocol for privileged/stateful operations,
+- deterministic commit via REVM integration.
+
+This is why Fluent uses the term **blended execution** instead of just “multi-VM.”
+
+## Three layers to keep in mind
+
+### 1) Node and consensus shell
+
+A modified Reth-based node stack handles standard blockchain concerns:
+
+- networking,
+- tx/block processing,
+- mempool,
+- RPC and external interfaces.
+
+### 2) Execution coordination layer
+
+This layer (REVM integration + host handlers) is responsible for:
+
+- frame lifecycle,
+- state journal/commit rules,
+- privileged host actions,
+- syscall interruption handling.
+
+### 3) Runtime execution layer
+
+This layer runs contract/runtime logic using Fluent’s rWasm-centered runtime model.
+It includes runtime dispatch, resumable contexts, and SDK/system binding boundaries.
+
+## Why this split matters
+
+Execution and commitment are not the same thing:
+
+- runtime executes logic and can yield,
+- host validates and performs privileged state actions,
+- final effects are committed deterministically.
+
+That separation is central to both security and proving ergonomics.
+
+## What this architecture is trying to optimize
+
+Fluent’s architecture balances:
+
+- **compatibility** (especially Ethereum-facing behavior),
+- **composability** (cross-EE calls over shared state),
+- **determinism** (consensus safety),
+- **proving friendliness** (single blended execution model rather than many isolated proof domains).
+
+## Reading order
+
+1. [Execution model](./02-execution-model.md)
+2. [Runtime routing and ownership](./03-runtime-routing-and-ownership.md)
+3. [Interruption and syscall model](./04-interruption-and-syscalls.md)
+4. [Runtime families and blended VM mapping](./05-runtime-families-and-blended-vm.md)
+5. [State and storage model](./06-state-and-storage-model.md)
+6. [Gas/fuel metering model](./07-gas-and-fuel-model.md)
+7. [Upgrade and security boundaries](./08-upgrades-and-security-boundaries.md)
+8. [L2/rollup context](./09-l2-rollup-context.md)

docs/system-architecture/02-execution-model.md

@@ -0,0 +1,61 @@
+---
+title: Execution Model
+sidebar_position: 2
+---
+
+Fluent executes applications under a **shared execution model** rather than isolated per-VM silos.
+
+## Blended execution in practice
+
+At runtime, the system treats different EE styles (EVM-oriented, Wasm-oriented, and other routed runtimes) as parts of one coherent execution domain.
+
+The practical outcome:
+
+- contracts share one state space,
+- cross-runtime interactions are direct and synchronous,
+- composability does not require external asynchronous bridges for in-transaction calls.
+
+## Why not classic multi-VM
+
+Classic multi-VM systems frequently pay extra complexity for:
+
+- state synchronization between VM domains,
+- consistency guarantees across VM boundaries,
+- duplicated invariants in multiple runtimes.
+
+Fluent’s architecture instead centralizes execution coordination and state commitment, and uses runtime routing + interruption to keep policy enforcement unified.
+
+## Integration challenges Fluent must solve
+
+The tech-book highlights several architectural pain points when blending EEs. These remain useful design constraints:
+
+1. **Cryptography mismatch** between ecosystems.
+2. **Address format mismatch** (20-byte vs other formats).
+3. **Different metering models** and gas accounting assumptions.
+4. **Different bytecode/account metadata requirements**.
+5. **Variable storage patterns and data sizes**.
+
+Fluent addresses these by combining:
+
+- runtime-specific execution paths,
+- compatibility-oriented interfaces,
+- raw/storage-oriented interfaces where needed,
+- host-governed syscall/interruption boundaries.
+
+## Deterministic host authority
+
+A key architectural rule: even when runtime code executes most of the business logic, sensitive operations still pass through host authority paths.
+
+This is enforced through interruption protocol and syscall handlers, so consensus-critical behavior is concentrated in one deterministic control plane.
+
+## Conceptual flow
+
+At high level, one transaction follows this shape:
+
+1. tx enters node pipeline,
+2. REVM/frame setup resolves target execution path,
+3. runtime executes until finalization or interruption,
+4. host resolves interruptions and resumes execution as needed,
+5. final result + state effects are committed.
+
+The rest of this section explains each of those moving parts in detail.

docs/system-architecture/03-runtime-routing-and-ownership.md

@@ -0,0 +1,62 @@
+---
+title: Runtime Routing and Ownership
+sidebar_position: 3
+---
+
+Fluentbase separates two concerns that are often conflated:
+
+- **account identity/state**, and
+- **execution engine selection**.
+
+## Ownable-account routing model
+
+In Fluent’s architecture, account execution can be delegated through ownership/runtime metadata.
+That lets many accounts share runtime logic while preserving per-account state isolation.
+
+Why this matters:
+
+- avoids per-account runtime duplication,
+- makes runtime families explicit,
+- gives deterministic dispatch behavior.
+
+## Create-time runtime selection
+
+At deployment time, constructor payload format/prefix and routing rules determine the runtime class.
+
+Examples from current Fluentbase architecture include routed paths such as:
+
+- EVM/default delegated runtime,
+- runtime-specific routed deploy paths (for supported formats),
+- specialized runtime paths (for example universal token runtime pattern).
+
+Once created, account execution follows that routing model consistently.
+
+## Execution-time behavior
+
+When a routed account is called:
+
+- delegated runtime logic is used for execution,
+- account-local state remains attached to the called account,
+- host/REVM maintains authoritative commit semantics.
+
+This is how Fluent gets “shared runtime logic + isolated account state” simultaneously.
+
+## Direct-runtime call policy
+
+Runtime-owner addresses are not intended to be regular user-facing contracts.
+By design, user execution should go through routed account semantics, not bypass routing invariants via direct runtime-owner invocation.
+
+## Metadata and ownership boundaries
+
+Metadata-changing operations are ownership-scoped.
+A runtime family must not freely mutate metadata for accounts owned by another runtime family.
+
+This boundary is part of consensus safety: incorrect ownership checks can become cross-runtime privilege bugs.
+
+## Architectural connection to composability
+
+Routing and ownership are what make cross-EE composability feasible without losing determinism:
+
+- calls remain in one shared state space,
+- each account still has clear execution semantics,
+- host maintains invariant checks at interruption/syscall boundaries.