add docs (#110)

Co-authored-by: gd-0 <90608901+gd-0@users.noreply.github.com>
Co-authored-by: Ivan Litteri <67517699+ilitteri@users.noreply.github.com>

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+        working-directory: ./docs
+
+      - name: Build website
+        run: npm run build
+        working-directory: ./docs
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test-docs.yml

@@ -0,0 +1,29 @@
+name: Test Deploy Docs
+
+on:
+  pull_request:
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+        working-directory: ./docs
+
+      - name: Test build website
+        run: npm run build
+        working-directory: ./docs

README.md

@@ -31,6 +31,7 @@ $ make
 build-op-geth                  🏗️ Build OP geth from op-eth directory
 build-op-node                  🏗️ Build OP node from optimism directory
 build-portal                   🏗️ Build based portal from based directory
+build-gateway                  🏗️ Build based gateway from based directory
 build                          🏗️ Build
 clean                          🧹 Clean
 deps                           🚀 Install all dependencies
@@ -60,7 +61,8 @@ To view the logs, run the following:
 ```Shell
 make op-node-logs            // OP node logs
 make op-reth-logs            // OP reth logs
-make based-portal-logs       // Based portal logs
+make gateway-logs            // Based gateway logs
+make portal-logs             // Based portal logs
 
 make logs SERVICE=<service>  // Replace <service> with the service name
 ```
@@ -69,6 +71,7 @@ make logs SERVICE=<service>  // Replace <service> with the service name
 
 ```Shell
 make build-portal            // Build the local portal docker image, named `based_portal_local`
+make build-gateway           // Build the local gateway docker image, named `based_gateway_local`
 make build-op-geth           // Builds the modified op-geth image, named `based_op_geth`
 make build-op-node           // Build the modified op-node image, named `based_op_node`
 ```

based/bin/portal/src/main.rs

@@ -18,7 +18,7 @@ async fn main() -> eyre::Result<()> {
     let addr = SocketAddr::new(IpAddr::V4(args.portal_host), args.portal_port);
     let server = PortalServer::new(args.clone())?;
 
-    info!(gateway_url = %args.gateway_url, fallback_url = %args.fallback_url, fallback_eth_url = %args.fallback_eth_url, "starting Based Portal");
+    info!(%addr, gateway_url = %args.gateway_url, fallback_url = %args.fallback_url, fallback_eth_url = %args.fallback_eth_url, "starting Based Portal");
 
     server.run(addr).await
 }

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/architecture/consensus.md

@@ -0,0 +1,141 @@
+---
+description: Upgrades to the OP node
+---
+
+# OP Node
+
+The OP node was upgraded to support the new based architecture and process `Frag`s. 
+
+The main changes include:
+- a new capability in the P2P server, to support the [new messages](/architecture/p2p.md) 
+- a new `based_` RPC namespace, used by the local gateway to make the initial push of p2p messages
+- an extended `EngineAPI` to enable processing of `Frag` in the execution layer after signature verification
+
+Importantly, all these changes are incremental and backwards compatible. Non-modified nodes will still be able to stay in the network and receive new blocks, they just won't be able to process `Frag`s and provide preconfirmations.
+
+![op-node](../../static/img/architecture_consensus.png)
+
+## P2P Capability
+
+The P2P server is extended to include a new capability to broadcast messages to other OP nodes of the network. The current implementation simply extends the existing libp2p protocol already used by nodes, while in the future we plan to move to a new faster leader-aware gossip.
+
+## RPC
+
+To avoid re-implementing the full p2p in the gateway, a new `based_` namespace is introduced, used by the gateway to make the initial push of p2p messages, which will then be broacast to the rest of the network.
+
+### `based_env`
+
+#### Parameters
+
+- `signature`: The signature of the gateway.
+- `message`: The `EnvV0` message.
+
+#### Returns
+
+- `OK` if the frag was successfully received and published.
+- `ERROR` if the frag was not successfully received/published.
+
+#### Example
+
+```json
+{
+    "id": 1,
+    "jsonrpc": "2.0",
+    "method": "based_env",
+    "params": [{
+        "message": {
+            "basefee": 4,
+            "beneficiary": "0x1234567890123456789012345678901234567890",
+            "difficulty": "0x5",
+            "extraData": "0x010203",
+            "gasLimit": 3,
+            "number": 1,
+            "parentBeaconBlockRoot": "0xe75fae0065403d4091f3d6549c4219db69c96d9de761cfc75fe9792b6166c758",
+            "parentHash": "0xe75fae0065403d4091f3d6549c4219db69c96d9de761cfc75fe9792b6166c758",
+            "prevrandao": "0xe75fae0065403d4091f3d6549c4219db69c96d9de761cfc75fe9792b6166c758",
+            "timestamp": 2
+        }],
+        "signature": "0x4fc733cc2f0b680e15452db40b9453412ccb25507582b192c1ea4fc4deaf709845002ab44af42327ed4b8b12943412810a8d9984ea1609dfc6f77338f8c395b41c"
+    }
+}
+```
+
+### `based_newFrag`
+
+#### Parameters
+
+- `signature`: The signature of the gateway.
+- `message`: The `FragV0` message.
+
+#### Returns
+
+- `OK` if the frag was successfully received and published.
+- `ERROR` if the frag was not successfully received/published.
+
+#### Example
+
+```json
+{
+    "id": 1,
+    "jsonrpc": "2.0",
+    "method": "based_newFrag",
+    "params": [{
+        "message": {
+            "blockNumber": 1,
+            "isLast": true,
+            "seq": 0,
+            "txs": [
+                "0x010203"
+            ]
+        }],
+        "signature": "0xa47da12abd5563f45332e637d1de946c3576902a245511d86826743c8af1f1e2093d4f5efd5b9630c0acc5f2bb23f236b4f7bdbe0d21d281b2bd2ff60c6cf1861b"
+    }
+}
+```
+
+### `based_sealFrag`
+
+#### Parameters
+
+- `signature`: The signature of the gateway.
+- `message`: The `SealV0` message.
+
+#### Returns
+
+- `OK` if the frag was successfully received and published.
+- `ERROR` if the frag was not successfully received/published.
+
+#### Example
+
+```json
+{
+    "id": 1,
+    "jsonrpc": "2.0",
+    "method": "based_sealFrag",
+    "params": [{
+        "message": {
+            "blockHash": "0xe75fae0065403d4091f3d6549c4219db69c96d9de761cfc75fe9792b6166c758",
+            "blockNumber": 123,
+            "gasLimit": 1000000,
+            "gasUsed": 25000,
+            "parentHash": "0xe75fae0065403d4091f3d6549c4219db69c96d9de761cfc75fe9792b6166c758",
+            "receiptsRoot": "0xe75fae0065403d4091f3d6549c4219db69c96d9de761cfc75fe9792b6166c758",
+            "stateRoot": "0xe75fae0065403d4091f3d6549c4219db69c96d9de761cfc75fe9792b6166c758",
+            "totalFrags": 8,
+            "transactionsRoot": "0xe75fae0065403d4091f3d6549c4219db69c96d9de761cfc75fe9792b6166c758"
+        }],
+        "signature": "0x090f69ccf02e0f468cac96f71bbf4b7732c63f3d50a4881f8665c1718570928e4497706eac2fe7da8b47ce355482ada8763614a3575a1af066ad06320b707c531b"
+    }
+}
+
+```
+
+## Engine API Upgrade
+
+New methods in the `based_` namespace are added to enable the OP node to send the `Frag`s payloads to the execution layer (EL). Messages are only sent after singature verification of the gateway identity. The new methods are:
+
+- `engine_newFragV0`
+- `engine_sealFragV0`
+- `engine_envV0`
+
+The processing is detailed in the [next](/architecture/execution.md) section.

docs/docs/architecture/execution.md

@@ -0,0 +1,58 @@
+---
+description: Upgrades to the OP execution layer
+---
+
+
+# Execution
+
+The OP geth was upgraded to receive `Frag`s messages from the OP node, as well as to serve state for RPC calls off the "unsealed block". Because `Frag`s are shared continously from the gateway, the EL can already start pre-processing and preparing for the block seal and sync.
+
+![op-el](../../static/img/architecture_execution.png)
+
+
+## Unsealed Block
+
+We define a new structure, `UnsealedBlock` that represents a block being reconstructed locally from `Frag`s.
+
+```go
+type UnsealedBlock struct {
+    Env                *Env
+    Frags              []Frag
+    LastSequenceNumber *uint64
+    Hash               common.Hash
+
+    Receipts Receipts
+}
+```
+
+### Starting a new unsealed block
+
+After an `engine_envV0` call is received, the EL initializes a new unsealed blocks and prepares the block environment for frags to be applied.
+For the message to be valid, the following conditions must be met:
+- There must not be a an unsealed block in progress.
+- The timestamp must be greater than the previous block's timestamp.
+- The block number must be the next one in the sequence.
+- The parent hash must match the previous block's hash.
+
+After validation, the unsealed block is persisted in the global state via `SetCurrentUnsealedBlock`.
+
+### Inserting frags
+
+Upon receiving `engine_newFragV0` calls, the EL validates the received frag:
+
+- The block number must match the current unsealed block number and there must be an opened unsealed block.
+- The sequence number must be the next one in the sequence (the current unsealed block persists this number). This has several cases:
+    - Before checking the sequence number is the correct one, we must make sure that the current unsealed block's last frags was not the final one (meaning this block is treated as sealed).
+    - If the sequence number is 0 and the unsealed block did not received the last frag, then the frag is the first one and the current unsealed block must have the `LastSequenceNumber` set to nil.
+    - If the sequence number is > 0 and the unsealed block did not received the last frag, then the frag should be the next in the sequence.
+
+
+If valid, the frags are added to the unsealed block. This means executing every transaction in the frag and adding the receipts to the unsealed block.
+
+If the frag is marked as last, the node starts sealing the block and computing the state root.
+
+### Seal verification
+
+With the `engine_sealFragV0` call, the node verifies that the sealed block matches with what the gateway computed. If the verification is successful, the node sets the block as canonical and advances the chain. 
+
+