bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 13쪽 중 3쪽
ime policy decision, not a global behavior — which runtimes are engine-metered is part of the protocol's runtime classification and is versioned accordingly. The full classification table lives in
Precompiles
.
Calldata surcharge
Large calldata payloads attract a quadratic surcharge above a threshold. The reason is practical block-data pressure control: without the surcharge, it's cheap to flood a block with enormous calldata that other users then pay to store and process.
This is block economics, not runtime internals. It shows up in transaction cost estimation and in any tooling that predicts gas for data-heavy transactions.
Operational invariants
A few rules the host enforces at every syscall entry:
Never allocate large host buffers before bounding length.
Untrusted lengths are validated first; only then is memory allocated. Otherwise an untrusted caller can make the host allocate unbounded memory before any gas is charged.
Charge before expensive host work where feasible.
If a host operation is costly, its fuel is debited before the operation runs, not after.
Treat conversion and rounding as consensus surface.
No change to conversion, rounding, or charging order ships as a silent improvement. These are fork-level coordination events.
Why two units
The conversion ratio
How settlement works
Keeping the delegated EVM runtime in sync
Import-level fuel schedules
Engine-metered vs self-metered runtimes
Calldata surcharge
Operational invariants
## /system-architecture/state-and-rpc-compatibility
On this page
Fluent's state model is deliberately Ethereum-shaped on the outside: one trie, account addresses, balances, nonces, code hashes. But some contracts are stored in the runtime-managed
ownable-account wrapper
(see
Runtime Routing
), so what a wallet or indexer reads from a Fluent node isn't always the bytes sitting in storage. The wrapper carries execution metadata that would confuse Ethereum tooling, so the node exposes two RPC views — one normalized for compatibility, one raw for infrastructure.
This page covers the shared-state model and the RPC split on top of it.
One shared state, many runtimes
Every contract — EVM, Wasm, Universal Token, future runtimes like SVM — lives in the same account/state trie. No per-runtime storage silo, no bridge between VM environments, no separate address space. A Solidity contract and a Rust contract are two accounts in the same trie, and a call from one to the other is an ordinary in-transaction call, not a message passed across a boundary.
That's the structural property that makes cross-runtime composability synchronous instead of asynchronous. Two contracts in different runtime families can call each other in a single transaction because the state they read and write is the same state. The host mediates every operation between them with the same rules, regardless of which runtime owns which account.
The cost is that some accounts carry more than plain EVM bytecode in their code field. They carry a wrapper describing which runtime should execute them and what metadata that runtime needs. The RPC story starts there.
The ownable-account wrapper, briefly
The full mechanics live in
Runtime Routing and Ownable Accounts
. For RPC purposes what matters: the
code
field of an ownable account is not the contract's executable bytecode. It's a wrapper carrying a magic header, the delegated runtime address (
owner_address
), and runtime metadata. The executable bytecode lives at the delegated runtime's address, and the wrapper tells the node where to find it.
An Ethereum-compatible client that reads this field expecting plain EVM bytecode gets confused: the wrapper isn't valid EVM code, the code hash doesn't match any EVM interpreter's expectations, bytecode-based identity checks fail. So the RPC layer has to make a choice.
Two views: compatibility and raw
Fluent exposes every account-and-code RPC method in two forms:
Compatibility view
— normalized for Ethereum tooling. For ownable accounts, the node extracts the EVM-facing bytecode from the underlying delegated runtime and returns it; code hashes are adjusted to match the extracted bytecode.
Raw view
— exactly what is stored. For ownable accounts, the node returns the wrapper bytes as-is, with the original code hash. No normalization.
Compatibility method
Raw method
Purpose
eth_getCode
eth_getRawCode
contract code bytes
eth_getAccount
eth_getRawAccount
account fields (balance, nonce, code hash)
eth_getAccountInfo
eth_getRawAccountInfo
combined account info + code payload
For accounts that aren't ownable — EOAs, plain contracts without a wrapper — both views return the same bytes.
When to use which
Compatibility methods
are the right choice for anything built on standard Ethereum assumptions: wallets, app SDKs, Etherscan-style explorers, bytecode-matching verification, generic
eth_*
consumers. These expect account fields shaped like EVM, and the compatibility view gives them exactly that.
Raw methods
are for infrastructure that needs the bytes that actually live in storage. Typical cases:
building or validating account and state proofs against the real trie,
cross-checking state-root or witness pipelines,
indexers that must preserve canonical stored bytes,
debugging divergence between what a client sees and what is persisted,
fork or fork-db tooling where cache keys or bytecode identity must match storage exactly.
If you're writing a Fluent-aware explorer or a proving pipeline, you want raw. Otherwise, stick to compatibility and treat the extraction as invisible.
Difference from upstream Reth
Fluent's node is based on a modified Reth, but upstream Reth doesn't know about ownable-account wrapping. Its
eth_getCode
returns whatever bytes are stored at the account's code field, period. On Fluent that behavior would leak the wrapper to every Ethereum client, which is exactly what the compatibility view is there to prevent.
The fork carries the wrapped-account normalization logic. Default methods lean compatibility-first so downstream Ethereum tooling keeps working; raw methods are the explicit opt-in when you need storage-level truth.
Why the split exists
Both views are necessary. Compatibility-only would leave proof systems and indexers with no way to address the bytes that actually live on-chain — every query would go through a normalization layer they can't invert. Raw-only would force every wallet and SDK to handle Fluent accounts specifically, breaking the "point your tool at the RPC" promise.
Default methods compatibility-first, raw methods explicit. Ethereum tooling sees an Ethereum-shaped chain; Fluent-aware infrastructure sees everything as it is.
One shared state, many runtimes
The ownable-account wrapper, briefly
Two views: compatibility and raw
When to use which
Difference from upstream Reth
Why the split exists
## /system-architecture/runtime-upgrade
On this page
Fluent's delegated runtimes — the EVM runtime, the Wasm runtime, the Universal Token runtime, and others — are protocol-owned bytecode. They decide how every ownable account in their class behaves. Fixing bugs and evolving behavior in those runtimes without a full node rewrite is a design goal. Making absolutely sure no one else can do it is another.
Runtime upgrade is the privileged control plane for this. It's tightly constrained on every axis — who can call it, through what path, with what payload — because an unconstrained upgrade is a total compromise of the chain.
The upgrade flow
A runtime replacement goes through five steps:
The
governance owner
(an externally held key or multisig) calls the runtime-upgrade contract.
The contract
validates
the proposed Wasm artifact and
compiles
it to rWasm.
It invokes the
native upgrade syscall
, passing the target runtime address and the serialized rWasm module.
The
host
verifies the caller arrived through the upgrade precompile's execution path and installs the new code at the target address.
An
upgrade event
is emitted with the target, a genesis reference, and the new code's hash.
The separation matters. Steps 1 and 2 are a contract the governance owner talks to. Step 3 is a syscall that contract is allowed to invoke. Step 4 is host enforcement, which exists precisely because contract-level authorization alone can't guarantee protocol safety. If an attacker found a way to call the upgrade syscall from somewhere that wasn't the upgrade precompile, step 4 is what rejects it.
Contract-level controls
The upgrade contract exposes a minimal surface:
upgradeTo(...)
— the main entry. Only the owner can call it. The argument is the target runtime address plus the new artifact.
changeOwner(...)
— transfers ownership. Assigning the zero address is rejected — there's no valid "burn the key" result from this path.
owner()
— returns the current owner.
renounceOwnership()
— sets the owner to a designated system address, effectively freezing upgrades through the owner-based path while leaving a deterministic default.
A default-owner fallback is defined for the unset state, so the contract always has a well-formed owner to check against. The address, calldata format, and authority constants live on the
Runtime Upgrade Precompile
page.
Host-side enforcement
The upgrade syscall handler runs its own checks on top of whatever the contract enforces:
Not callable in static context.
A
STATICCALL
frame can't trigger an upgrade, full stop.
Only reachable via the runtime-upgrade precompile's execution path.
The host checks which address the call came from and rejects anything that didn't arrive through the precompile.
Payload must decode correctly.
Malformed inputs are rejected before any state change.
Bytecode must be a valid rWasm payload.
Validation happens before installation — the runtime executor is never asked to load garbage.
Installation is deterministic.
The target account is loaded, its code field is replaced with the new bytecode, and the change commits in one host action. There's no multi-step install path where a partial update could leave the runtime undefined.
Host-level checks are what make the overall system safe. Contract-level permissions alone would let a bug in the upgrade contract compromise every delegated runtime on the chain. The host rejects any attempt that didn't arrive through the one blessed execution path, regardless of contract state.
⚠️
Warning
Runtime upgrade changes consensus behavior. Every upgrade is fork-critical change management: deterministic artifacts, coherent network rollout, and post-upgrade verification are not optional.
The legacy testnet hook
One carveout worth knowing about. A chain-id-gated legacy upgrade path exists for historical testnet behavior. It's temporary — documented as such — and should be read as compatibility debt rather than part of the target architecture. Mainnet doesn't use it; auditors should trace it but treat it as out-of-scope for the target security model.
Operational expectations
Upgrading a runtime isn't like deploying a contract. A runtime change affects every account in that runtime's class retroactively, which means every user of the chain lives with the consequences. Treat every upgrade as fork-critical change management:
Produce
deterministic build artifacts
so the artifact installed on chain is byte-identical to what was audited.
Use
multisig or operator quorum
on the governance owner. A single key with unilateral upgrade authority is a single point of failure.
Roll out coherently
across nodes. A chain where some nodes have upgraded and others haven't is a chain that will fork.
Verify post-upgrade.
Check the installed code hash against the expected artifact. Run smoke tests against runtime behavior. Confirm events fired with the expected metadata.
Keep an audit trail.
Who proposed, who approved, who triggered, what was installed, what the hash was. On-chain events help; the operational record matters too.
Runtime extensibility is intentional. It's also one of the most sensitive pieces of infrastructure on the chain, and it should be operated accordingly.
The upgrade flow
Contract-level controls
Host-side enforcement
The legacy testnet hook
Operational expectations
## /system-architecture/security-invariants
On this page
The other pages in this section describe how Fluent works. This page is the list of things that cannot stop being true without the chain breaking. These are the consensus-critical invariants — break any one and the failure mode isn't a bug, it's a consensus split, a privilege escalation, or a host-level instability that affects every account on the chain.
Anyone modifying runtime-host interaction code, syscall handlers, or upgrade paths should treat this as a review checklist.
🚨
Danger
Most critical bugs in this architecture are boundary violations, not ordinary application logic errors. Every invariant below is part of the consensus surface.
Routing integrity
New contracts must route to the correct delegated runtime class. User calls must not bypass routing by targeting a delegated runtime address directly. Metadata ownership boundaries between runtime families must hold. Two contracts with different intended runtimes are fundamentally different contracts, and routing is what enforces that. A misrouted deploy or a successful bypass means the same storage can be interpreted under two different runtime rules, which is how a chain executes contradictory state transitions. Mechanism:
Runtime Routing and Ownable Accounts
.
Interruption integrity
Positive exit codes are
call IDs
, not final statuses. A runtime yielding a positive exit is asking for host action, and its output buffer carries syscall parameters — not committed output. Resume must use the exact recoverable context associated with the
call_id
, and per-transaction reset must clear recovery state so no context survives past its owning transaction. Call-id confusion — treating a yield as a finalization or resuming the wrong context — corrupts execution flow and can leak state across frames. Mechanism:
Interruption and Syscalls
.
Bounds-before-allocation
Untrusted lengths must be validated before the host allocates memory to service them. Memory reads and writes must fail safely when they go out of bounds. Large copy paths — hashing, calldata, log emission — must carry explicit upper bounds. Without these checks, untrusted input can make the host allocate unboundedly and crash itself before any gas is charged, which is a DoS surface on every node simultaneously.
Static-call immutability
State-changing operations must reject static context. That covers ordinary storage mutations, metadata mutations, account lifecycle operations (create, destroy), and privileged runtime state transitions like upgrade.
STATICCALL
exists so callers can invoke untrusted code knowing no state change can result. Any mutation that slips through the static check defeats that guarantee and silently changes the semantics of every existing contract that relies on it.
System-runtime envelope discipline
For system-mode runtimes, structured output envelopes must decode deterministically across nodes. Storage diffs, logs, and metadata updates must only commit on a successful runtime exit — a fatal exit or a decode failure means
no
side effects are applied, not "whatever we managed to parse." Envelope mis-handling is how you commit wrong side effects from a runtime that didn't actually complete.
Upgrade authority boundaries
The runtime-upgrade path must stay tightly scoped to the upgrade precompile's execution path on the host side. Authority defaults and owner transitions must be explicit and reviewed — no silent zero-owner assignment, no ambiguous fallback. Upgrade-authority compromise is full-system compromise; the safety here comes from layering contract-level permissioning under host-level path enforcement. Mechanism:
Runtime Upgrade
.
Fatal-code containment
Non-system user contracts must not be able to surface internal fatal runtime-only classes as normal outputs. Some error classes are meaningful only inside the host-runtime protocol (envelope-decode failures, recovery-state violations). Letting user contracts produce those classes as their return status lets applications impersonate protocol-level failures and confuse every downstream consumer.
Bridge hook consistency
Bridge hooks rely on specific event shapes, data layouts, and ordering guarantees. Any change to the events, the runtime side, or the flow that produces them must update the bridge-side hook logic in the same change. Mismatch here mints, burns, or settles wrong amounts — the most expensive kind of bug a bridge can have.
Panic policy
The release build profile is
panic = "abort"
. Consensus-critical paths must not rely on unwind-based recovery: a panic aborts the process, and any fallback that assumes the stack will be unwound before cleanup is wrong. Design error handling around explicit
Result
returns and anticipated failures. Don't rely on catching implicit panics.
Checklist for syscall-handler changes
Any change that touches a syscall handler should confirm, explicitly, that it:
preserves strict input and state validation,
preserves static-call rejection for mutating branches,
keeps gas and fuel charging order deterministic,
keeps allocation safety bounded and pre-validated,
preserves ownership checks on metadata operations,
keeps interruption and resume symmetry intact.
If any box isn't clearly preserved, the change isn't ready to merge. These aren't style concerns. They're the boundaries this architecture depends on.
Routing integrity
Interruption integrity
Bounds-before-allocation
Static-call immutability
System-runtime envelope discipline
Upgrade authority boundaries
Fatal-code containment
Bridge hook consistency
Panic policy
Checklist for syscall-handler changes
## /system-architecture/rollup-architecture
On this page
Fluent is an Ethereum-aligned L2 rollup. Every block produced on Fluent eventually settles to Ethereum under a cryptographic integrity story, and the way that story is composed — fast preconfirmation plus slow cryptographic adjudication — is what makes the chain usable and safe at the same time.
This page describes the verification pipeline at the protocol level: how batches are committed, how data is made available, how execution is preconfirmed, how disputes are resolved, and how the system halts itself when something breaks. Running a node isn't covered here; see the node runbook in the upstream
fluentbase/docs
.
Shared state, execution-agnostic settlement
Blended execution — EVM, Wasm, and (soon) SVM contracts sharing one state machine — is documented in
Blended 101
. What matters for settlement is that Fluent verifies rollup commitments over
block headers and batch Merkle roots
, not over VM-specific execution traces. Adding a new execution environment doesn't change what the rollup proves; it changes what fits into a block the rollup already knows how to settle.
Each batch is a sequential record identified by a root, a block span, a declared block count, an expected blob count, and timing windows for each phase. Verification parameters are frozen per batch at commit time, so retroactive governance edits can't change the security conditions of an in-flight batch.
Not pure optimistic, not pure validity
Two well-known models sit on either side of what Fluent does.
Optimistic rollups
accept state transitions on the assumption that they're correct and rely on economic challenges to catch faults within a dispute window. They're cheap and fast in the happy path, but the dispute window dominates user-perceived finality.
Validity (ZK) rollups
require a succinct proof for every state transition before accepting it. Security is purely cryptographic at the transition level, but proving cost and latency are non-trivial, and pr프로젝트로 돌아가기