Fluent 백서

Fluent

원문

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
프로젝트로 돌아가기