Merge pull request #1 from erigontech/docs/docusaurus-migration

docs: initial migration — Docusaurus 3 site (moved from erigontech/zilkworm#8)

Author: somnergy

.gitignore

@@ -0,0 +1,18 @@
+# Dependencies
+node_modules/
+
+# Production build
+build/
+.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*

README.md

@@ -1,2 +1,100 @@
-# zilkworm-docs
-Public documentation site for zilkworm
+# Zilkworm Docusaurus Site
+
+Source for **https://zilkworm.erigon.tech** — the public documentation for Zilkworm, built with [Docusaurus 3](https://docusaurus.io/).
+
+This repo is the entire site: configuration, theme overrides, the React landing page, and the markdown content under `docs/`. The Docusaurus build emits a static site that is published via GitHub Pages.
+
+## How it works
+
+- **Pages**: every `.md` file under [`docs/`](docs/) becomes a page. The sidebar is autogenerated from the directory tree; ordering comes from `sidebar_position` frontmatter and `_category_.json` in each subfolder.
+- **Landing page**: [`src/pages/index.tsx`](src/pages/index.tsx) is a custom React page served at `/` (hero, mission pillars, capability cards, CTAs). It bypasses the markdown pipeline.
+- **Navbar / footer**: configured in [`docusaurus.config.ts`](docusaurus.config.ts) and the swizzled [`src/theme/Footer/index.tsx`](src/theme/Footer/index.tsx). The footer cross-links sibling sites (Cocoon, Erigon docs) per the shared design spec.
+- **Theme tokens**: brand colors (Erigon orange `#EF7716`), Quantify / Montserrat / Nunito Sans fonts, light + dark surfaces, navbar buttons — all in [`src/css/custom.css`](src/css/custom.css). Fonts are self-hosted under [`static/fonts/`](static/fonts/).
+- **Diagrams**: Mermaid is enabled (`@docusaurus/theme-mermaid`); fenced ` ```mermaid ` blocks render inline.
+- **Search**: client-side via `@easyops-cn/docusaurus-search-local`, indexed at build time.
+- **Analytics**: Plausible script is injected via `headTags` in the config.
+- **Custom domain**: [`static/CNAME`](static/CNAME) pins the site to `zilkworm.erigon.tech` when published from GitHub Pages.
+- **SEO**: Each page has `title` + `description` frontmatter that becomes `<meta name="description">` and `og:description`. Global `og:image`, Twitter card, and site metadata are set in `docusaurus.config.ts`. `sitemap.xml` is generated at build time by `@docusaurus/preset-classic`; `static/robots.txt` references it.
+- **LLM-friendly**: [`scripts/generate-llms.py`](scripts/generate-llms.py) walks `docs/` and writes `static/llms.txt` (page index with descriptions) and `static/llms-full.txt` (full corpus). Regenerate after any docs change:
+  ```bash
+  python3 scripts/generate-llms.py
+  ```
+
+## Render it locally
+
+Requirements: **Node ≥ 20** (Docusaurus 3 requirement).
+
+```bash
+npm install        # one-time
+npm run start      # dev server with hot reload on http://localhost:3000
+```
+
+Other useful scripts (all defined in [`package.json`](package.json)):
+
+```bash
+npm run build      # production build into ./build (static HTML/CSS/JS)
+npm run serve      # serve the production build locally
+npm run typecheck  # tsc — verifies docusaurus.config.ts, sidebars.ts, components
+npm run clear      # clear the .docusaurus cache
+```
+
+## Authoring content
+
+Add a new doc:
+
+1. Create `docs/<section>/<page>.md` (or a new section with its own `_category_.json`).
+2. Add Docusaurus frontmatter:
+
+   ```yaml
+   ---
+   title: Page Title
+   description: One-line meta description used for SEO + cards.
+   sidebar_position: 3
+   ---
+   ```
+
+3. Save — the dev server hot-reloads.
+
+Notes:
+
+- If the title contains a colon, **quote it** (`title: "Foo: Bar"`) — otherwise YAML parsing fails.
+- MDX rejects raw `<` outside code fences. Use `&lt;` or rephrase. Email/URL autolinks (`<a@b.com>`, `<https://…>`) need to be markdown links.
+- Inline JSX is allowed in `.md` files (Docusaurus treats them as MDX). The Welcome page (`docs/index.md`) imports the [`HomeCards`](src/components/HomeCards.tsx) component this way.
+
+## Layout
+
+```
+zilkworm-docs/
+├── docs/                     # markdown content (sidebar autogenerated)
+│   ├── index.md              # Welcome — served at /documentation
+│   ├── basics/               # _category_.json sets label + sidebar position
+│   ├── use-cases/
+│   └── testing/
+├── src/
+│   ├── pages/
+│   │   ├── index.tsx         # custom landing at /
+│   │   └── index.module.css
+│   ├── components/
+│   │   ├── HomeCards.tsx     # 3-card grid used on the Welcome page
+│   │   └── HomeCards.module.css
+│   ├── css/custom.css        # all theme tokens (colors, fonts, buttons, etc.)
+│   └── theme/
+│       ├── Footer/index.tsx  # swizzled footer (matches sibling sites)
+│       └── NotFound/         # swizzled 404
+├── static/
+│   ├── CNAME                 # zilkworm.erigon.tech
+│   ├── fonts/                # self-hosted woff2 — Quantify/Montserrat/NunitoSans
+│   └── img/                  # logos, favicon, OG image
+├── docusaurus.config.ts      # site identity, plugins, navbar, themeConfig
+├── sidebars.ts               # autogenerated sidebar from `docs/`
+└── package.json
+```
+
+## Design spec
+
+This site has two source-of-truth specs in `erigontech/erigon-documents`:
+
+- **[public-docs/docusaurus-design-spec.md](https://github.com/erigontech/erigon-documents/blob/master/public-docs/docusaurus-design-spec.md)** — Shared design across all Erigon docs sites (theme, fonts, footer pattern, NotFound shape, broken-link policy, gotchas). Read this first.
+- **[public-docs/zilkworm-docs-spec.md](https://github.com/erigontech/erigon-documents/blob/master/public-docs/zilkworm-docs-spec.md)** — Zilkworm-specific deltas: site identity, the custom React landing, MDX-conversion map from the GitBook migration, page content goals, tradenames, open questions.
+
+When something visual feels ambiguous or you need to add a new chrome element (navbar button, footer column, color token), check the design spec first — it's the source of truth across all sibling sites. Anything Zilkworm-specific (content structure, page intent, the landing page, the llms generator) belongs in `zilkworm-docs-spec.md`.

docs/basics/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Basics",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false
+}

docs/basics/background.md

@@ -0,0 +1,28 @@
+---
+title: Background
+description: Why Zilkworm exists — Ethereum scaling, ZK proofs, and the case for a native C++ ZKEVM core.
+sidebar_position: 3
+---
+
+
+There are several factors to take into account when thinking about the ZK future of EVMs and blockchains.
+
+Firstly, today's validators on Ethereum-like chains are limited by the speed with which data can be transmitted across the network and then how fast a block can be re-executed. Verifying zero-knowledge proofs of blocks are much more efficient at achieving scaling than on the low end of the infrastructure spectrum. Following a successful rollout of this vision, consensus can progress without needing execute whole blocks. The end goal is then to provide a streamlined end to end application that can generate EVM + State Transition proofs for Ethereum or a similar blockchain.
+
+Secondly, the ZK flow de-facto enables transaction privacy, as the exact nature or contents of the transactions are no longer needed to verify their correctness. This separates EVM itself from the consensus game and enables possibilities like private blockchains. This is not dissimilar to ZK-rollups themselves, but only more native to Ethereum itself with Zilkworm (and similar).
+
+Thirdly, ZK prover backends have never been so performant and easy to work with. There has been an immense jump in prover performance over the past 2 years that makes real-time proving a reality today.
+
+### RISC and no risk
+
+Software technology cannot evolve in isolation and it thrives when the stars of various software domains align. RISC-V's open source minimal ISA has seen massive growth of interest and innovation both in interesting high-performance low-power use cases as well as with provable computation sphere.
+
+The current generation of provers target minimal general purpose ISAs like RISC-V. That means existing client code and EVM code execution can be directly proved. Of course, this is a fairly new domain and it makes a ton more sense for a C++ or Rust software that has mature toolchains for this niche.
+
+For zero-knowledge proofs based EVM/blockchains the proof systems and the overall stacks used to be hand-crafted before and it used to take a while. Whereas now it means feature iterations aren't dependent on heavy developer turnaround time. Additionally, existing (native compilable) projects like EVMOne fits right into become.
+
+### EVM x zkVM = zkEVM
+
+Zilkworm aims to make it easy to integrate different prover backends (zkVMs) that act on a similar ISA (currently only riscv32im and riscv64im). That means it integrates with prover solutions like Succinct's SP1, RISC0, Pico GPU Prover and so on.
+
+Essentially, it's a stateless execution engine that takes the pre-state of a block from an existing execution trace and generates a proof of the state transition function.

docs/basics/faqs.md

@@ -0,0 +1,47 @@
+---
+title: FAQs
+description: Frequently asked questions about Zilkworm — benchmarks, team, timeline, integration plans, and prover backends.
+sidebar_position: 5
+---
+
+
+### Can we see some Benchmarks?
+
+Yes, find Zilkworm's proofs by going to [EthProofs](https://ethproofs.org/)
+
+We are rapidly working to publish continuous results on [EthProofs](https://ethproofs.org/) and they will be published soon.\
+Case by case benchmarks and Tests-Matrix would be released in a couple of weeks.
+
+### Who's working on it?
+
+At the moment the work is being led by Erigon developers. This is a short term "experiment" and we are looking to partner with other organisations to further the efforts.  (reach out to [som@erigon.tech](mailto:som@erigon.tech) or  [pawel.bylica@erigon.tech](mailto:pawel.bylica@erigon.tech) for developer queries)
+
+### What are the timelines?
+
+We're actively working to deliver real-time Ethereum block proofs on 2 GPUs - follow progress on [EthProofs](https://ethproofs.org/).
+
+### Challenges of C++ work in a Rust world?
+
+There are quite a few challenges especially with the provided gcc toolkit on a limited `rv32im` target. We have ironed out most of them. It's not easy though as there is a "first-mover" advantage of some of the prover libraries initially being written in Rust.\
+Having said that, RUST ↔ CPP bridge has zero bottlenecks and works perfectly within Zilkworm.
+
+### Do you have it integrated in Erigon?
+
+We have plans for this integration in two ways
+
+* As a replacement for the current Erigon core for faster performance on x86 and ARM hardware
+* As a prover through JSON-RPC integration
+
+We will publish such plans in a later iteration of Zilkworm
+
+### Can I use Zilkworm with another Execution Layer (EL) client like Nethermind or Besu?
+
+Yes, the integration into other clients for prover would be the same way - over RPC. But in order to use the core directly as an executor, it would need closer collaboration with these other EL clients.
+
+### Prover Killer Performance
+
+For the proof generation itself the performance of intensive crypto operation would be dictated by the underlying prover backend (for instance SP1 or RISC0 or something else). We will publish more results on it in future.
+
+### Plans for integration with other zkVMs/Prover backends
+
+The first rollout will have SP1 as the prover. We will rollout with others in due course of time.

docs/basics/getting-started.md

@@ -0,0 +1,102 @@
+---
+title: Getting Started
+description: Run the Zilkworm prover via the pre-built Docker image — setup, block fetch, dry-run execute, prove, and CUDA acceleration.
+sidebar_position: 1
+---
+
+
+### How to Run
+
+At the moment the building from source requires elaborate setup with Conan, Linux packages and SP1 Turbo SDK pre-requisites. It's recommended to use the pre-built Docker image.
+
+To run with pre-built Docker
+
+```bash
+$ docker run somnergy/z6m_prover --help
+```
+
+```text
+Usage: z6m_prover [OPTIONS] [COMMAND]
+
+Commands:
+  setup    Run setup to generate proving and verifying keys
+  fetch    Fetch block and witness from RPC
+  execute  Execute the guest program without proving
+  prove    Generate a proof for a block
+  verify   Verify a proof using a verification key
+  help     Print this message or the help of the given subcommand(s)
+
+Options:
+      --service                                      
+      --rpc-url <RPC_URL>                            
+      --data-dir <DATA_DIR>                          [default: temp]
+      --save-all-responses                           
+      --prove-every <PROVE_EVERY>                    
+      --execute-every <EXECUTE_EVERY>                
+      --post-every <POST_EVERY>                      
+      --start-block <START_BLOCK>                    
+      --end-block <END_BLOCK>                        
+      --pk-path <PK_PATH>                            [default: pk.bin]
+      --proof-type <PROOF_TYPE>                      [default: compressed]
+      --ethproofs-endpoint <ETHPROOFS_ENDPOINT>      
+      --ethproofs-token <ETHPROOFS_TOKEN>            
+      --ethproofs-cluster-id <ETHPROOFS_CLUSTER_ID>  
+  -h, --help  
+```
+
+#### First Fetch the block
+
+```text
+Usage: z6m_prover fetch [OPTIONS]
+
+Options:
+      --rpc-url <RPC_URL>            RPC endpoint URL
+      --block-number <BLOCK_NUMBER>  Block number to fetch
+      --data-dir <DATA_DIR>          Output directory
+      --save-all-responses           Whether to save all the json files to disk after download
+      --build-eth-test               Whether to create an ethereum/tests format json file too
+  -h, --help                         Print help
+
+```
+
+#### Dry run execute - just use --block-number for this
+
+```text
+Usage: z6m_prover execute [OPTIONS]
+
+Options:
+      --block-number <BLOCK_NUMBER>  Block number to execute [default: 0]
+      --file-name <FILE_NAME>        Whether the input file is an Ethereum/tests file
+      --is-test                      
+      --data-dir <DATA_DIR>          Data directory
+  -h, --help                         Print help
+
+```
+
+#### Fire up the prover
+
+```text
+Usage: z6m_prover prove [OPTIONS]
+Options:
+      --block-number <BLOCK_NUMBER>  JSON file to load ethereum/tests format test from [default: 0]
+      --file-name <FILE_NAME>        Whether the input file is an Ethereum/tests file
+      --is-test                      
+      --data-dir <DATA_DIR>          Data directory
+      --pk-path <PK_PATH>            Proving key path [default: pk.bin]
+      --proof-path <PROOF_PATH>      Proof output path
+      --proof-type <PROOF_TYPE>      Proof type: core, compressed, groth16, plonk [default: compressed]
+  -h, --help                         Print help
+
+```
+
+### NVIDIA CUDA Accelerated proving
+
+First make sure to install NVIDIA drivers and the NVIDIA Container Toolkit https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
+
+```bash
+$ user@machine-with-gpu
+docker run --gpus all --rm --network host -v "$PWD:/work:rw" -v /var/run/docker.sock:/var/run/docker.sock  -w /work -it --entrypoint bash somnergy/z6m_prover
+
+root@instance-20250919-091229:/work# 
+SP1_PROVER=cuda RUST_BACKTRACE=full RUST_LOG=info z6m_prover prove --n 1 --file-name test.json
+```

docs/basics/how-it-works.md

@@ -0,0 +1,51 @@
+---
+title: How it works
+description: Technical details of the Zilkworm prover.
+sidebar_position: 4
+---
+
+
+The actual code of Zilkworm acts as the guest program for a zkVM. In reality though, it's optimized for one or more provers and the minimal riscv32im ISA. The thing about integrating with a certain zkVM prover backend though is that one needs to be careful about its memory boundaries, hardware and environment limitations and provisions.
+
+The zkVM internally generates an execution trace of the underlying riscv32im simulated machine and stitches the lines of execution, memory mutations and storage maps into a proof using the fabric of the constraints of each machine operation.
+
+Nothing in the default pipeline actually assumes a particular proving system. The backend is a plugin. Today you might choose SP1; tomorrow you might test an alternative curve or commitment scheme. Zilkworm doesn’t change; only the witness packing and the backend library do.
+
+In the following sections we will dive deeper into its details assuming the SP1-Prover backend.
+
+```mermaid
+flowchart LR
+    Z["Zilkworm-st"]
+    subgraph SIM["Simulator"]
+        RV["RISC-V<br/>(No-OS)"]
+    end
+    SP["SP1 Prover"]
+    PROOF["STARK<br/>Proof"]
+
+    Z -->|Firmware| SIM
+    SIM -->|Traces| SP
+    SP --> PROOF
+
+    style SIM stroke-dasharray: 2 3
+    style PROOF stroke-dasharray: 5 5
+```
+
+### rv32im compilation
+
+The target ISA such as rv32im is dictated by the underlying prover. In the description used here, SP1 backend for prover uses rv32im. This means the execution trace generation happens with a simulated CPU + memory + ROM in a bare-metal context. That is, the code for Zilkworm-state-transition function wholly runs as a "firmware" without any convenient OS system calls.
+
+The target system of RV32IM means certain compiler and program constraints has to be kept in careful consideration.  Thirty-two-bit integer math has predictable behavior across compilers and is friendlier to constraint systems than ad-hoc 64-bit code paths. The build uses a standard cross-compiler (riscv32-unknown-elf-g++), with flags that keep the binary small and link-time GC aggressive.
+
+### Rust–C++ bridge
+
+A lot of prover code lives in Rust. Zilkworm keeps the execution engine and trace generation in C++ and crosses the boundary through a narrow FFI. There are two practical ways to do this. The first uses a C-compatible ABI: the Rust crate exposes extern "C" functions that accept raw pointers and lengths, and C++ wraps those in RAII helpers. The second uses a binding layer (such as cxx) to generate type-safe shims.
+
+CMake invokes cargo and links the resulting library into the Zilkworm binary. Ownership and lifetimes are spelled out: the side that allocates returns a destructor; all buffers are length-delimited; no globals leak between language runtimes.
+
+### EVMone core
+
+Rather than reinvent EVM semantics, Zilkworm embeds EVMone. The tracing code does not introspect EVMone internals; it observes inputs and outputs at opcode boundaries and normalizes them into records with stable layouts. This matters when you later compare traces across compilers or machines: the format is always the same, and there is no hidden bookkeeping. When precompiles are involved, Zilkworm treats them as explicit events rather than a black box. The trace records the precompile id, inputs, and outputs so the witness either contains enough to re-derive the result or delegates to a host primitive through a well-defined channel.
+
+### Precompiles provided by The Prover SDK via ECALL
+
+Cryptographic operations are heavy, and the RV32IM guest has no business carrying entire big-number libraries if it can avoid it. For those, Zilkworm issues an ECALL with a service id that names the primitive (for example, a Keccak permutation or a BN254 group operation). Arguments are passed as pointers and lengths into guest memory. This pattern keeps the guest compact and also keeps the trace witness small. If the backend knows the primitive, it can treat the event as a constraint.