Fluent 백서

Fluent

원문

bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 13쪽 중 2쪽

constructor tail then runs with the remaining deployment parameters. Execution semantics are unchanged — the rWasm runs under the same engine that ownable accounts dispatch into. The difference is representational: Wrapped accounts ( 0xEF44 ): code field is wrapper(owner_address, metadata) ; REVM looks up the runtime via owner_address on every call. Direct rWasm accounts ( 0xEF52 ): code field is the compiled rWasm itself; REVM executes it without an owner-address indirection. Metadata syscalls ( METADATA_SIZE , METADATA_ACCOUNT_OWNER , METADATA_WRITE ) recognize only the wrapped form and return null or halt against direct rWasm. The rewrite happens because the Wasm runtime's compiled output is already a complete rWasm module — wrapping it with another indirection layer would only add lookup cost. For Solidity and Universal Token contracts the wrapper stays, because their EVM/UT bytecode lives inside the wrapper's metadata field, not at the account address itself. Why this model ​ Three things fall out of ownable-account routing: Shared runtime logic without per-account duplication. One delegated Wasm runtime executes every Wasm contract. Fixing a bug or upgrading behavior happens in one place, not per-deployment. Deterministic dispatch by owner. Given an account's wrapper, the execution engine is decidable in constant time. The router reads one field. Cross-environment composability over shared state. A Solidity contract and a Rust contract are two ownable accounts pointing at two different delegated runtimes. They call each other, they share the state trie, and the host mediates every operation between them with the same rules. The ownable account format Create-time routing Execution-time behavior Direct calls to delegated runtime addresses are blocked Metadata ownership rules The Wasm-wrapper deploy rewrite Why this model ## /system-architecture/precompiles On this page Fluent installs a fixed set of system precompiles at genesis. Each entry below is a callable address with a specific role: dispatching execution to a delegated runtime, verifying a cryptographic primitive, gating a privileged operation, or providing a standard EVM service. The constants come from fluentbase/crates/types/src/genesis.rs ; the contract code that backs each address lives in fluentbase/contracts/<dir>/ . User contracts on Fluent — Solidity, Rust/Wasm, Universal Token — route their execution into one of the delegated runtime dispatchers below. Solidity and Universal Token contracts are stored as ownable accounts ( 0xEF44 magic prefix) that hold a pointer to the dispatcher plus runtime metadata; Wasm contracts are stored as compiled rWasm directly ( 0xEF52 magic prefix) after the executor's deploy-time rewrite. The dispatcher's address holds the runtime bytecode either way. See Runtime Routing and Ownable Accounts for the full mechanism. Addresses are identical across testnet, mainnet, and devnet. Authority addresses default to the values shown below at genesis, but live networks rotate them — treat the defaults as starting points, not current values. 💡 Tip On-chain state for any precompile address can be inspected on Fluentscan . The protocol source-of-truth for these constants is fluentbase/crates/types/src/genesis.rs . Delegated runtime dispatchers ​ Calls to these addresses are not handled by deployed bytecode at the address itself. They are dispatchers: the executor loads the runtime's code, runs it, and the call's storage domain stays at the caller's account. See Runtime Routing and Ownable Accounts for the mechanism. Address Description 0x0000000000000000000000000000000000520001 EVM runtime — see EVM Runtime 0x0000000000000000000000000000000000520003 SVM runtime — reserved, feature-gated, not currently active in mainnet build 0x0000000000000000000000000000000000520008 Universal Token runtime — see Universal Token Runtime 0x0000000000000000000000000000000000520009 WASM runtime — see WASM Runtime Verifier precompiles ​ Reserved addresses for cryptographic verification primitives that have not yet been activated. Each address has stub bytecode installed at genesis but a call returns an unreachable-code error today. Documentation will follow activation. Address Description 0x0000000000000000000000000000000000520005 WebAuthn verifier — reserved, not yet active 0x0000000000000000000000000000000000520006 OAuth2 verifier — reserved, not yet active 0x0000000000000000000000000000000000520007 Nitro verifier — reserved, not yet active System contracts ​ Privileged contracts that gate runtime upgrades, fee withdrawal, deterministic deployment, and cross-domain settlement. Each has a Solidity-style ABI and an authority owner. Address Description 0x0000000000000000000000000000000000520010 Runtime upgrade — replaces the bytecode of a delegated runtime. See Runtime Upgrade Precompile 0x0000000000000000000000000000000000520fee Fee manager — withdraws accumulated protocol fees. See Fee Manager 0x9CAcf613fC29015893728563f423fD26dCdB8Ddc Rollup bridge — cross-chain settlement. See Bridge Architecture 0x4e59b44847b379578588920cA78FbF26c0B4956C CREATE2 factory — deterministic deployment proxy. See CREATE2 Factory EIP-deployed system contracts ​ EIP-track precompiles deployed at protocol-specified addresses. Implementations live in fluentbase/contracts/ like the rest, but their addresses are dictated by the EIP, not by Fluent's 0x520xxx reservation range. Address Description 0x0000F90827F1C53a10cb7A02335B175320002935 EIP-2935 — historical block-hash ring buffer (Prague). See EIP-2935 Block Hash Service 0x0000000000000000000000000000000000000100 EIP-7951 — secp256r1 (P-256) signature verification. See secp256r1 Signature Verification Standard EVM precompiles ​ Fluent ships every standard Ethereum precompile from 0x01 to 0x11 — ecrecover, sha256, ripemd160, identity, modular exponentiation, BN254 curve operations, BLAKE2 compression, KZG point evaluation, and the BLS12-381 family. See Standard EVM Precompiles for the full list and any Fluent-specific notes. Authority addresses ​ Two privileged keys exist at genesis. Both default to 0xa7bf6a9168fe8a111307b7c94b8883fe02b30934 and are intended to be rotated immediately on a live chain (typically to a multisig). The defaults are documented for reference, not as current operational values. Runtime upgrade owner (constant DEFAULT_UPDATE_GENESIS_AUTH ) — initial caller permitted to invoke upgradeTo on the Runtime Upgrade Precompile . Fee manager owner (constant DEFAULT_FEE_MANAGER_AUTH ) — initial caller permitted to invoke withdraw on the Fee Manager . Both contracts read their stored owner first and only fall back to the default when the slot is zero. The constants live in fluentbase/crates/types/src/genesis.rs . Bytecode model ​ Every account on Fluent stores its code as one of four Bytecode variants. Knowing which variant a contract uses determines whether metadata syscalls work, whether REVM dispatches through an owner address, and what the leading bytes of account.code look like. Variant Magic prefix Used by LegacyAnalyzed (no Fluent magic) Plain analyzed EVM bytecode (legacy chain accounts). Eip7702 0xEF01 EIP-7702 account-code delegation (EOAs that delegate to a contract). OwnableAccount 0xEF44 Solidity contracts (owner = EVM Runtime), Universal Token contracts (owner = UT Runtime), and the EVM-style system precompiles. Rwasm 0xEF52 Wasm contracts (after the deploy-time wrapper rewrite), and system contracts pre-deployed at genesis as raw rWasm (Runtime Upgrade, Fee Manager, EIP-2935, secp256r1, etc.). OwnableAccount carries owner_address plus runtime-specific metadata bytes; the runtime is dispatched through on every call. Rwasm accounts execute their bytes directly with no owner-address indirection. Magic bytes reference ​ Constant Value Module WASM_MAGIC_BYTES 0x0061736d (standard \0asm ) crates/types/src/lib.rs UNIVERSAL_TOKEN_MAGIC_BYTES 0x45524320 ( "ERC " ) crates/types/src/lib.rs RWASM_MAGIC_BYTES 0xef52 revm-bytecode/.../rwasm.rs OWNABLE_ACCOUNT_MAGIC_BYTES 0xef44 revm-bytecode/.../ownable_account.rs EIP7702_MAGIC_BYTES 0xef01 revm-bytecode/.../eip7702.rs Delegated runtime dispatchers Verifier precompiles System contracts EIP-deployed system contracts Standard EVM precompiles Authority addresses Bytecode model Magic bytes reference ## /system-architecture/interruption-and-syscalls On this page Runtime execution on Fluent isn't a single uninterrupted run. When a contract needs to read storage, emit an event, create a nested call, or touch shared state in any way, it doesn't do it. It yields back to the host, the host performs the operation, and the runtime resumes from where it stopped. That pattern — the interruption protocol — is how every privileged operation on Fluent is performed. This page covers the protocol itself and the two syscall surfaces layered on top of it. The exec / resume handshake ​ From the host's side, running a runtime frame is a deterministic handshake: The host calls exec with the runtime's input and a fuel budget. The runtime executes until it either finishes or needs something. If it needs something, it yields an interruption request. The host performs the requested operation. The host calls resume with the result, fuel accounting, and any returned data. The runtime picks up from the saved point. Steps 2 through 5 repeat until the runtime returns a final result. There's no other path for a runtime to affect state or interact with the rest of the system. How a yield is signalled ​ The runtime's exit code is overloaded by protocol convention: exit_code <= 0 — the runtime is done. The value is a final status: success, revert, or a specific error class. Return bytes are the final output. exit_code > 0 — the runtime is yielding. The value is a call_id , a transaction-scoped handle pointing at a saved execution context. Return bytes carry the encoded parameters of the syscall being requested. One exit integer carrying both "here is my result" and "here is my interruption" is economical, and it's also consensus-critical. Treating a positive exit as a final status would commit whatever's in the runtime's return buffer as if it were real output. That failure mode is called out in the security invariants . The interruption payload ​ When a runtime yields, the host decodes a payload containing: the call_id identifying the saved context, the syscall parameters (syscall id, input byte range, fuel available, static-context flags), a gas snapshot for deterministic settlement on resume. The host uses call_id to find the saved context to resume later, validates the syscall parameters, and routes the syscall id into the host handler for that operation. How the host handles an interruption ​ Every interruption runs through the same sequence on the host side: Read the syscall input from the runtime's memory at the declared byte range. Validate input lengths and state-context constraints. Reject oversized reads, malformed payloads, and mutating operations invoked from static context. Charge gas according to the operation's fuel procedure. Execute the host operation. Simple calls (hash, storage read) are immediate; compound operations ( CALL , CREATE ) spin up a new frame. Return the immediate result, or — for frame-creating operations — wait for the nested frame to complete. Store the interruption outcome for the resume phase to hand back to the runtime. Every step in this sequence is deterministic across nodes. Same inputs produce the same outputs, the same errors, and the same gas charges everywhere. Anything less would make the syscall a consensus-splitting surface. The resume path ​ After the host operation finishes, the runtime resumes with: its call_id so the executor picks the right saved context, a mapped exit code translating the host action's outcome into a runtime-visible status, the returned data buffer, the consumed or refunded fuel, optionally a pointer at which the runtime wants fuel accounting written as a tuple. The runtime continues from the interrupted instruction, consumes or ignores the returned data, and either finishes or yields again. Two syscall layers ​ The interruption protocol has two sides, and they're not the same API. Layer A — the runtime import layer ​ The public import namespace exposed to runtime code is fluentbase_v1preview . This is what a contract compiled for Fluent sees as available imports: input and output helpers, state selectors (deploy vs main entry, context queries), exec and resume themselves, fuel APIs for self-metered paths, hash and crypto builtins. Each import is bound to a syscall index and a fuel procedure at compile or translation time. Fuel formulas follow predictable shapes — constant, linear in data size, quadratic where appropriate — so every operation has a known cost up front, not one determined at runtime. The import table is part of protocol behavior. Changing it touches every contract that imports from it and every tool that produces compiled runtimes. Layer B — the host interruption syscall IDs ​ When an interruption arrives, the host routes it through its own handler set, indexed by SYSCALL_ID_* constants. These aren't exposed to contracts. They're the protocol-level operations the host knows how to perform: storage, transient storage, and block-level access, call, create, and destroy flows, code, balance, and account queries, metadata ownership and metadata storage operations, the runtime-upgrade governance syscall. Layer A describes what a runtime can ask for . Layer B describes what the host actually does . They evolve together — change one side without the other and the protocol drifts. Transaction-scoped context IDs ​ Every call_id is transaction-scoped. Resumable contexts are created when a runtime frame starts, retained across interruptions within that frame, and forgotten when the transaction finalizes. Per-transaction reset clears recovery state and counters so no context leaks between independent flows. A few guarantees follow: call_id values from one transaction aren't valid in another. A context resumes with the exact state it yielded, not a fresh one. Resume is root-only in the current runtime flow: nested user code can't call resume directly. Only the host drives resume, and only for the call_id the host is currently servicing. Protocol correctness depends on all three holding. Violations show up as call-id confusion or state leakage across frames — both enumerated explicitly in the security invariants . System-runtime envelopes ​ One more protocol surface lives on top of interruption, specific to system-mode runtimes: the structured envelopes introduced in the execution model . When a system runtime yields or finalizes, its payload isn't an opaque return buffer — it's an envelope that explicitly carries return data, storage diffs, emitted logs, metadata updates, and frame outcomes. The host decodes the envelope and applies each piece deterministically. Without the envelope contract, the host would have to reconstruct side effects from ad-hoc return bytes — exactly the parser-driven ambiguity consensus-critical code should not have. The exec / resume handshake How a yield is signalled The interruption payload How the host handles an interruption The resume path Two syscall layers Layer A — the runtime import layer Layer B — the host interruption syscall IDs Transaction-scoped context IDs System-runtime envelopes ## /system-architecture/gas-and-fuel On this page Fluent charges work in two accounting units. Gas is what users pay with — the same EVM-visible unit wallets quote, explorers display, and transactions settle in ETH. Fuel is what the rWasm runtime consumes while executing. Every runtime step is metered in fuel; every transaction is paid in gas; a fixed deterministic conversion links them. If you're writing tooling that estimates costs, building a custom runtime, or auditing gas charging on privileged paths, this split matters. For ordinary contract development it's invisible. Why two units ​ Runtime execution, host operations, and EVM interpretation all need one shared accounting model. Gas alone doesn't work — it was designed around EVM opcodes, and Fluent runs more than the EVM. Fuel is the engine-level unit every runtime shares. Gas stays as the user-facing economic unit Ethereum-compatible tooling expects. One conversion ratio keeps them in lockstep. Anything a user pays gas for translates into a fuel budget the runtime consumes, and any fuel the runtime returns to the host translates back into gas settlement. The conversion ratio ​ The conversion is a fixed protocol constant: FUEL_DENOM_RATE = 20 Each unit of gas is worth 20 units of fuel. The runtime fuel limit for a call is derived from whatever gas is available when the call starts; any consumed or refunded fuel converts back into gas when the runtime returns or yields. Rounding at the conversion boundary is deterministic — every node performs it identically — because any divergence here is consensus-splitting. 🔍 Info Changing FUEL_DENOM_RATE or the rounding rules at the conversion boundary is a fork-level change. Gas and fuel conversion is part of consensus correctness, not a tuning knob. How settlement works ​ Inside a normal call or resume cycle, the host goes through four steps: Compute the runtime fuel limit from the gas remaining in the frame. Invoke the runtime with that limit. Receive back the fuel consumed and any fuel refunded. Convert the deltas into gas and apply them to the interpreter's gas state. That happens on every runtime invocation and every resume. If the runtime doesn't consume its full budget, leftover fuel is refunded as gas. If it runs out of fuel mid-execution, the call aborts with an out-of-gas-class error. Keeping the delegated EVM runtime in sync ​ The delegated EVM runtime runs under rWasm, which creates a subtle accounting risk: the EVM runtime tracks committed gas locally for EVM-visible gas semantics, while the host tracks fuel consumed at the rWasm level. If those two diverge, user-visible gas usage stops matching what the runtime actually did. To prevent that, the delegated EVM runtime syncs its local committed-gas delta back to host-level fuel before every interruption and before every final return. The sync happens at well-defined boundaries so no EVM operation can hide gas usage by yielding before its gas is committed. Import-level fuel schedules ​ Every runtime import carries an explicit fuel formula — a charging procedure attached to the syscall index at compile or translation time. The formula shape depends on the operation: Constant. Some state and control calls have a fixed cost. One charge per invocation, regardless of data size. Linear in data size. Copy, hash, and log operations scale with the bytes they touch. The per-byte rate is part of the import's fuel schedule. Quadratic. A few operations, notably exec , use a quadratic policy that reflects the work they trigger downstream. These formulas aren't optimization heuristics. They're part of the runtime's ABI: a contract compiled for Fluent expects specific charges on specific operations, and changing a formula changes the cost semantics of every existing contract that uses that import. Engine-metered vs self-metered runtimes ​ Not every system runtime meters fuel the same way. Self-metered runtimes charge fuel explicitly in their code. Every operation that costs fuel has a matching charge call, and the runtime does its own bookkeeping. Engine-metered runtimes let the execution engine meter configured precompiles automatically. The runtime doesn't charge itself; the engine inserts fuel accounting at compilation time. The Universal Token runtime is classified as engine-metered. This is a per-runt
프로젝트로 돌아가기