Add staging docs to main

docs/developer-guides/building-a-blended-app/start-solidity-contract.md

@@ -8,7 +8,6 @@ Step 2: Start Solidity Contract
 
 This guide is based off of the template blended application in this [Github repo](https://github.com/fluentlabs-xyz/blended-template-foundry-cli).
 
-
 ## Solidity Contract with Interface 
 
 Solidity interfaces are useful for calling external contracts that might 

docs/knowledge-base/architecture/README.md

@@ -0,0 +1,29 @@
+---
+title: Architecture
+---
+
+Architecture
+---
+
+Fluent is an Ethereum Layer L2 rollup designed to natively execute EVM, SVM and Wasm-based programs.
+Fluent exists as a unified state machine,
+where all contracts can call each other, regardless of which VM they were originally built for.
+
+As a rollup, Fluent supports scalable and efficient execution by committing state changes to Ethereum L1.
+This process involves compressing the state changes using ZK proofs, specifically SNARKs.
+
+![Fluent base architecture](../../../static/img/kb/fluent-arch.png)
+
+The Fluent operates on a modified version of [Reth](https://github.com/fluentlabs-xyz/fluent),
+using its own execution engine that replaces [Revm](https://github.com/fluentlabs-xyz/revm-rwasm).
+It maintains backward compatibility with most existing Ethereum standards, such as transaction and block structures.
+However, Fluent is not confined to Reth exclusively, as it features an independent execution runtime.
+
+Furthermore,
+Fluent enables a fork-less runtime upgrade model
+by incorporating the most critical and upgradable runtime execution codebase within the genesis state.
+The only persistent element within the runtime is the transaction format.
+
+Additionally, Fluent is always post-Prague compatible and does not support any EIPs implemented before the Prague fork.
+Maintaining backward compatibility with all previous forks is unnecessary.
+The EVM runtime can be upgraded to retain compatibility with EVM.

docs/knowledge-base/architecture/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Architecture",
+    "position": 4,
+    "collapsed": true
+  }

docs/knowledge-base/architecture/abi-format.md

@@ -0,0 +1,178 @@
+---
+title: ABI
+sidebar_position: 3
+---
+ABI
+---
+
+In the realm of EVM applications,
+the Solidity ABI has become the predominant encoding format,
+effectively establishing itself as a primary standard for on-chain interactions today.
+This encoding and decoding schema,
+primarily driven by the Solidity language, is widely used across Ethereum and other EVM-compatible platforms.
+
+However, in the Web2 domain,
+developers opt for ABI encoding/decoding schemes that best fit their specific needs and tasks.
+Notably, Ethereum includes several system precompiles that do not conform to a Solidity-compatible ABI schema.
+
+Blended VM Fluent distinguishes itself by supporting a variety of execution environments, such as EVM and Solana's VM,
+using distinct ABI schemes tailored to each environment.
+In Solana, for instance, there isn't a standardized ABI format,
+granting developers the flexibility to choose any format that suits their requirements.
+
+This flexibility is a hallmark of Fluent, as it does not mandate a single encoding/decoding standard for applications.
+Instead, it empowers developers to select the most suitable option.
+The Fluentbase SDK accommodates this by implementing the necessary ABI encoding/decoding standards,
+allowing developers to freely use any ABI format they prefer.
+
+## Fluentbase Codec
+
+Fluent employs a custom codec for ABI encoding/decoding tailored to various ABIs.
+This Codec includes compatibility modes such as Solidity ABI,
+and is designed to efficiently encode and decode parameters across different VMs.
+
+Fluent Codec is a lightweight library, compatible with no-std environments, and optimized for random reads.
+Although it shares similarities with Solidity ABI encoding,
+it incorporates several optimizations and features
+to enhance efficient data access and handle nested structures more effectively.
+
+The Codec leverages a header/body encoding mode:
+
+- **Header**: Contains all static information.
+- **Body**: Contains all dynamic information.
+
+Key Features:
+
+- **No-std Compatible**: Operates in environments without the standard library.
+- **Configurable Byte Order and Alignment**: Allows customization according to requirements.
+- **Solidity ABI Compatibility Mode**: Seamlessly integrates with Solidity ABI.
+- **Random Access**: Accesses first-level information without requiring full decoding.
+- **Support for Nested Structures**: Encodes nested structures recursively.
+- **Derive Macro Support**: Facilitates custom type encoding/decoding via derive macros.
+
+## Encoding Modes
+
+The library supports two primary encoding modes:
+
+- **SolidityABI**: Applied for external cross-contract calls to handle input parameters and decode outputs effectively.
+- **FluentABI**: Utilized for internal cross-system calls, benefiting from 4-byte stack alignment for efficiency without compromising the developer experience.
+
+### SolidityABI Mode
+
+Parameters:
+
+- Big-endian byte order
+- 32-byte alignment (Solidity compatible)
+- Dynamic structure encoding:
+  - Header
+    - offset (u256) - a position in the structure
+  - Body
+    - length (u256) - a number of elements
+    - recursively encoded elements
+
+Usage example:
+
+```rust
+use fluentbase_codec::SolidityABI;
+SolidityABI::encode(&value, &mut buf, 0)
+```
+
+### FluentABI Mode
+
+Parameters:
+
+- Little-endian byte order
+- 4-byte alignment
+- Dynamic structure encoding:
+  - Header
+    - length (u32) - a total number of elements in the dynamic data
+    - offset (u32) - a position in the buffer
+    - size (u32) - a total number of encoded elements bytes
+  - Body
+    - recursively encoded elements
+
+Usage example:
+
+```rust
+use fluentbase_codec::FluentABI;
+FluentABI::encode(&value, &mut buf, 0)
+```
+
+## Type System
+
+### Primitive Types
+
+Primitive types are encoded directly without any additional metadata,
+offering zero-cost encoding when their alignment matches the stack size.
+
+TODO: add all types
+
+- Integer types: `u8`, `i8`, `u16`, `i16`, `u32`, `i32`, `u64`, `i64`
+- Static arrays: `[T; N]`
+
+### Non-Primitive Types
+
+These types require additional metadata for encoding:
+
+- `Vec<T>`: Dynamic array of encodable elements
+- `HashMap<K,V>`: Hash map with encodable keys and values
+- `HashSet<T>`: Hash set with encodable elements
+
+For dynamic types, the codec stores metadata that enables partial reading. For example:
+
+- Vectors store offset and length information
+- HashMaps store separate metadata for keys and values, allowing independent access
+
+## Important Notes
+
+### Determinism
+
+The encoded binary is not deterministic and should only be used for parameter passing. 
+The encoding order of non-primitive fields affects the data layout after the header,
+though decoding will produce the same result regardless of encoding order.
+
+### Order Sensitivity
+
+The order of encoding operations is significant, especially for non-primitive types,
+as it affects the final binary layout.
+For non-ordered set/map data structures, ordering by key is applied.
+
+## Usage Examples
+
+### Basic Structure
+
+```rust
+use fluentbase_codec::{Codec, FluentABI};
+use bytes::BytesMut;
+
+#[derive(Codec)]
+struct Point {
+    x: u32,
+    y: u32,
+}
+
+// Encoding
+let point = Point { x: 10, y: 20 };
+let mut buf = BytesMut::new();
+FluentABI::encode(&point, &mut buf, 0).unwrap();
+
+// Decoding
+let decoded: Point = FluentABI::decode(&buf, 0).unwrap();
+```
+
+### Dynamic Array Example
+
+```rust
+// Vector encoding with metadata
+let numbers = vec![1, 2, 3];
+
+// FluentABI encoding (with full metadata)
+let mut fluent_buf = BytesMut::new();
+FluentABI::encode(&numbers, &mut fluent_buf, 0).unwrap();
+// Format: [length:3][offset:12][size:12][1][2][3]
+
+// SolidityABI encoding
+let mut solidity_buf = BytesMut::new();
+SolidityABI::encode(&numbers, &mut solidity_buf, 0).unwrap();
+// Format: [offset:32][length:3][1][2][3]
+```

docs/knowledge-base/architecture/account-trie.md

@@ -0,0 +1,41 @@
+---
+title: Account Trie
+sidebar_position: 4
+---
+Account Trie
+---
+
+The account structure in rWASM is designed to be as simple as possible, containing only the most essential fields.
+It's fully compatible with an original Ethereum account structure.
+
+```rust
+pub struct Account {
+    pub address: Address,
+    pub balance: U256,
+    pub nonce: u64,
+    pub code_hash: B256,
+    pub code_size: u64,
+}
+```
+
+Fields description:
+
+- **`address`**: This transient field holds the account address. Currently, a 20-byte address is used to ensure compatibility with the EVM account structure. However, there is a possibility of extending this to 32 bytes in the future to align with the state trie account path, thereby enhancing interoperability.
+- **`balance`**: Represents the account balance as a 256-bit element. This is consistently expressed as a 256-bit Big Endian value, although future changes may be considered.
+- **`nonce`**: Indicates the number of transactions initiated by this account. It increments with each transaction, call, or contract creation, regardless of the operation's success.
+- **`code_hash`**: A Poseidon hash representing the translated bytecode in rWASM format.
+- **`code_size`**: Denotes the size of the compiled bytecode in rWASM IR binary format. This bytecode has successfully passed all static validations and is optimized for ZK proofs.
+
+## State Trie
+
+Fluent operates with state tries through a pure functional approach,
+where every smart contract and root-STF can be represented as a function.
+In this model, the input provides a list of dependencies,
+and the output yields an execution result along with a number of logs.
+
+However, this isn't entirely feasible due to cold storage reads and external storage dependencies,
+such as CODEHASH-like EVM opcodes.
+To address this, Fluent employs an interruption system to "request" missing information from the root-STF.
+This is particularly useful for operations involving cold storage or invalidated warm storage.
+
+The same concept is also used to handle nested calls without incurring additional simulation overhead.

docs/knowledge-base/architecture/address-format.md

@@ -0,0 +1,58 @@
+---
+title: Address Format
+sidebar_position: 5
+---
+Address Format
+---
+
+Address format is used to compute paths inside the tree,
+making interoperability between different EEs almost impossible without additional pre-compiled contracts and/or adapters.
+
+| Chain | Address Format                           | Curve     | Size     |
+|-------|------------------------------------------|-----------|----------|
+| EVM   | `keccak256(uncompressed(G^x)[1:])[12..]` | secp256k1 | 160 bits |
+| SVM   | `G^SHA512(x)[..32]`                      | ed25519   | 256 bits |
+| FVM   | `SHA256(uncompressed(G^x))`              | secp256k1 | 256 bits |
+
+*Table 1. Different blockchains use different address schemes and elliptic curves.*
+
+Mapping addresses is not a viable solution,
+as there is no straightforward way to prove the mapping due to different curves and Solana's use of hashed private keys.
+This would introduce additional challenges and might require developing our versions of Ethereum and Solana wallets,
+which is unlikely.
+
+Our account/state system leverages a Sparse Merkle Binary Trie (SMBT) powered by the Poseidon hashing function.
+This implementation utilizes 254-bit elliptic curve points
+to compute paths within the trie by hashing addresses with Poseidon.
+
+Let’s examine how trie keys are calculated for Ethereum and Solana blockchains:
+
+- For an Ethereum address, it pads to 20 bytes with zeros to achieve a 32-byte size, then splits into two elements to calculate the binary path.
+- For a Solana address, it calculates the path using a 32-byte address, which is longer than the Ethereum’s 20-byte address.
+
+The current function cannot handle Ethereum and Solana addresses simultaneously
+because they occupy different trie spaces due to Ethereum's 20-byte padding.
+This issue also affects Fuel address formats and other blockchain systems, such as Polkadot,
+which employs the Ristretto curve.
+Consequently,
+native interoperability across these platforms is not feasible
+without altering blockchain address formats and cryptographic methods.
+
+## Solution
+
+### Fully Isolated EE
+
+For **Fully Isolated Execution Environments (EE)**, address projection (also known as account emulation) is employed.
+In this model,
+an account is stored within a special EE smart contract (or executor) responsible for managing all balance operations.
+This setup ensures that all balances of the isolated EE coexist in the same account space
+and can interact with external EEs only through specific system calls.
+
+### Partially Compatible EE
+
+For **Partially Compatible Execution Environments (EE)**,
+the same address format and derivation standards as used by Ethereum must be followed.
+The address derivation is as follows:
+
+- **`CREATE` (contract deployment)**: `h(address || nonce)`
+- **`CREATE2`**: `h(deployer, salt, init_code_hash)`

docs/knowledge-base/architecture/blended-vm/README.md

@@ -0,0 +1,10 @@
+---
+title: Blended VM
+---
+Blended VM
+---
+
+Blended VM implements Blended Execution concepts inside Fluent.
+It works on the top of rWasm VM, the runtime system bindings and interruption system.
+rWasm VM represents all state transitions within the VM, including Wasm instructions.
+The interruption system efficiently manages interruptions during system calls or cross-contract calls.

docs/knowledge-base/architecture/blended-vm/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Blended VM",
+    "position": 2,
+    "collapsed": true
+  }

docs/knowledge-base/architecture/blended-vm/evm.md

@@ -0,0 +1,24 @@
+---
+title: EVM
+sidebar_position: 2
+---
+EVM
+---
+
+Fluent integrates with the EVM by leveraging special EVM precompiled contracts.
+These contracts facilitate the execution of EVM bytecode,
+enabling the deployment and operation of smart contracts designed for the EVM ecosystem.
+This allows developers to seamlessly deploy their applications built for EVM platforms using languages like Solidity or
+Viper.
+
+The EVM executor, a Rust-based smart contract, provides two key functions:
+
+1. **`deploy`**: Deploys the EVM application and stores the bytecode state.
+2. **`main`**: Executes the already deployed EVM application.
+
+During deployment, a specialized rWasm proxy is deployed under the smart contract address.
+This proxy redirects all deployment and execution calls to the EVM executor.
+
+The deployment process is identical to that of Ethereum and other Ethereum-compatible platforms.
+Additionally, there are no differences in calling conventions or contract interactions.
+This consistency ensures a smooth app migration process for developers.