Initial commit

.github/workflows/deploy.yml

@@ -0,0 +1,59 @@
+name: Deploy
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+
+jobs:
+  deploy:
+    # Only deploy when there's a push into main with successful CI validation
+    if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # To push a branch
+      pages: write  # To push to a GitHub Pages site
+      id-token: write # To update the deployment status
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install latest mdbook
+        run: |
+          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+          mkdir mdbook
+          curl -sSL $url | tar -xz --directory=./mdbook
+          echo "$PWD/mdbook" >> $GITHUB_PATH
+
+      - name: Install mdbook-linkcheck
+        run: |
+          mkdir -p mdbook-linkcheck
+          cd mdbook-linkcheck
+          curl -L https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip -o mdbook-linkcheck.zip
+          unzip mdbook-linkcheck.zip
+          chmod +x mdbook-linkcheck
+          echo "$PWD" >> $GITHUB_PATH
+
+      - name: Install mdbook-quiz
+        run: |
+          cargo install mdbook-quiz --locked
+
+      - name: Build Book
+        run: |
+          mdbook build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload the html content, ignoring the linkcheck file
+          path: 'book/html'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/main.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  schedule:
+    - cron: "0 5 * * *" # Run daily at 5 AM UTC
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  validate-snippets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Clone Floresta repository
+        run: |
+          git clone https://github.com/vinteumorg/Floresta.git
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Build and run Snippet Checker
+        env:
+          CODE_DIR: ${{ github.workspace }}/Floresta
+        run: |
+          cd snippet-checker
+          cargo build --release
+          ./target/release/snippet_checker

.gitignore

@@ -0,0 +1,11 @@
+book/
+# Auto generated .css and .js
+src/quiz/
+
+.idea
+.vscode
+.DS_Store
+
+target
+tmp
+Cargo.lock

README.md

@@ -0,0 +1,63 @@
+# Floresta Docs
+
+[![CI](https://github.com/JoseSK999/floresta-docs/workflows/CI/badge.svg)](https://github.com/JoseSK999/floresta-docs/actions/workflows/main.yml)
+[![Deploy](https://github.com/JoseSK999/floresta-docs/workflows/Deploy/badge.svg)](https://github.com/JoseSK999/floresta-docs/actions/workflows/deploy.yml)
+
+This repository contains the source for the `Floresta Docs` mdBook, an in-depth explanation of the [Floresta](https://github.com/vinteumorg/Floresta) libraries for building a full Bitcoin node.
+
+You can either build the book locally, as explained below, or read it online.
+
+> [!Note]
+> This book is fully functional and ready to use, though we might add a few appendices or extra chapters down the road.
+
+## Documentation Maintenance
+
+This book heavily uses code snippets that reference actual code from Floresta. We have written a Rust `snippet-checker` script that compares the snippets in the book with the corresponding code in the repository.
+
+This check runs daily at 5 AM UTC, as well as on pull requests and pushes to the main branch, via the `CI` workflow. Whenever the check fails, the script nicely prints the code difference and makes it easy to assess which explanations should be rewritten, if any.
+
+### Deployment
+
+Each time a change is pushed to main, the updated book is automatically deployed online if `CI` completes successfully. In other words, if `CI` and `Deploy` are passing, the deployed book snippets are up-to-date, and all explanations should be consistent with the snippets (although this is a bit harder to ensure).
+
+## Requirements
+
+Building the book requires [mdBook](https://github.com/rust-lang/mdBook). To get it, assuming you have Rust installed, run:
+
+```bash
+cargo install mdbook --locked
+```
+
+Moreover, this book uses two mdBook plugins:
+
+- For checking internal and external links before building, it uses [mdbook-linkcheck](https://github.com/Michael-F-Bryan/mdbook-linkcheck).
+
+```bash
+cargo install mdbook-linkcheck
+```
+
+- For rendering interactive quizzes in the book, it uses [mdbook-quiz](https://github.com/cognitive-engineering-lab/mdbook-quiz).
+
+```bash
+cargo install mdbook-quiz --locked
+```
+
+## Building
+
+Finally, you can build the book by typing:
+
+```bash
+mdbook build
+```
+
+The rendered book will be at the root of this directory, inside `book/html`. You can then just open the `index.html` file in your usual browser.
+
+## Run Snippet Checker
+
+If you want to run the `snippet-checker`, you need to have a local clone of the `Floresta` source code. Then, you should pass a valid path to it via the `CODE_DIR` environment variable.
+
+For instance, if you have cloned `Floresta` into the `~/projects` directory, you would run:
+
+```bash
+CODE_DIR=~/projects/Floresta cargo run --release
+```

book.toml

@@ -0,0 +1,18 @@
+[book]
+authors = ["JoseSK999"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Floresta Docs"
+
+[output.html.playground]
+runnable = false
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.linkcheck]
+follow-web-links = true
+
+[preprocessor.quiz]

quizzes/ch01-01-utreexonode.toml

@@ -0,0 +1,16 @@
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "Which of the following are true about UtreexoNode in Floresta?"
+prompt.distractors = [
+  "It performs transaction validation directly.",
+  "It doesn't interface with a blockchain backend."
+]
+answer.answer = [
+  "It handles P2P connections.",
+  "It broadcasts transactions.",
+  "The Chain must implement BlockchainInterface and UpdatableChainstate."
+]
+context = """
+UtreexoNode is the highest level type in Floresta, handling P2P connections, receiving network data, and broadcasting transactions. The Chain backend must implement the BlockchainInterface and UpdatableChainstate traits.
+"""
+id = "f527ff73-bbde-43b8-8275-c2f8ddd0ab18"

quizzes/ch01-02-chain-backend-api.toml

@@ -0,0 +1,106 @@
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "What is the primary purpose of the BlockchainInterface trait in Floresta?"
+prompt.distractors = [
+  "It manages network connections and broadcasting.",
+  "It handles state updates and transaction processing."
+]
+answer.answer = [
+  "It provides access to blockchain data and state of validation.",
+  "It includes methods to fetch blocks, transactions, and block heights."
+]
+context = """
+The BlockchainInterface trait is primarily focused on getting information from the blockchain and the current state of validation.
+"""
+id = "269ff072-b5a0-468f-a1a4-86cdb1ac1a84"
+
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "Which method in the BlockchainInterface trait is responsible for fetching a block by its hash?"
+prompt.distractors = [
+  "`get_block_height`",
+  "`get_best_block`"
+]
+answer.answer = "`get_block`"
+context = """
+The `get_block` method in the BlockchainInterface trait is responsible for fetching a block given its hash.
+"""
+id = "16281204-1d91-4d96-b19c-0374e9a45851"
+
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "Which two methods in the BlockchainInterface trait are responsible for validation, without updating the internal state?"
+prompt.distractors = [
+  "`connect_block`",
+  "`accept_header`",
+  "`toggle_ibd`"
+]
+answer.answer = [
+  "`update_acc`",
+  "`validate_block`"
+]
+context = """
+The `update_acc` and `validate_block` methods in the BlockchainInterface trait perform validation without updating the internal state of the node.
+"""
+id = "3a675ab8-7309-48d1-a8f4-2ce4cdd443d5"
+
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "What does the UpdatableChainstate trait do in Floresta?"
+prompt.distractors = [
+  "It provides access to the current state of the blockchain without updating the state.",
+  "It manages peer-to-peer connections and networking."
+]
+answer.answer = [
+  "It updates the internal state of the blockchain.",
+  "It validates and adds blocks to the chain."
+]
+context = """
+The UpdatableChainstate trait is responsible for updating the state of the blockchain and performing validations such as connecting new blocks.
+"""
+id = "44d73c6d-ccfd-4200-a67b-01711e404f41"
+
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "Which two methods are critical in the UpdatableChainstate trait for updating the blockchain state?"
+prompt.distractors = [
+  "`get_best_block`",
+  "`flush`"
+]
+answer.answer = [
+  "`connect_block`",
+  "`accept_header`"
+]
+context = """
+The `connect_block` and `accept_header` methods are essential for updating the blockchain state, handling blocks and headers respectively.
+"""
+id = "c0b412ae-5a5c-4437-9e9e-d1161fdcac8f"
+
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "What is the role of the `subscribe` method in the BlockchainInterface trait?"
+prompt.distractors = [
+  "It validates new blocks received by the blockchain.",
+  "It broadcasts transactions to the network."
+]
+answer.answer = "It allows components to receive notifications of new validated blocks."
+context = """
+The `subscribe` method allows other components to subscribe to the BlockchainInterface to receive notifications of newly validated blocks.
+"""
+id = "bc3c6635-34cc-4f03-8fd7-9450b6f77625"
+
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "What are the error types used in the BlockchainInterface and UpdatableChainstate traits?"
+prompt.distractors = [
+  "BlockchainInterface uses any error type bounded by `std::error::Error`.",
+  "UpdatableChainstate uses any error type bounded by `core2::error::Error`."
+]
+answer.answer = [
+  "BlockchainInterface uses any error type bounded by `core2::error::Error`.",
+  "UpdatableChainstate uses the BlockchainError type."
+]
+context = """
+The BlockchainInterface trait can use any error type as long as it implements `core2::error::Error`, while the UpdatableChainstate trait uses a specific BlockchainError type to handle errors.
+"""
+id = "832c5cb7-2bb6-4f9c-9147-90de70837c5a"

quizzes/ch02-01-the-chainstore-trait.toml

@@ -0,0 +1,55 @@
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "What is the primary purpose of the ChainStore trait in Floresta?"
+prompt.distractors = [
+  "To manage peer-to-peer connections.",
+  "To validate blocks and headers.",
+  "To maintain the entire blockchain in memory."
+]
+answer.answer = "To interact with persisted storage."
+context = """
+The ChainStore trait is responsible for interacting with the chain's persisted storage, saving and loading accumulator state, block headers, and other chain-related data.
+"""
+id = "69a3bac8-7dbd-4722-9dda-2a5e506ada87"
+
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "Which of the following methods are used to save and load the accumulator state in ChainStore?"
+prompt.distractors = [
+  "`update_block_index` and `get_block_hash`",
+  "`save_height` and `load_height`",
+  "`flush`"
+]
+answer.answer = "`save_roots` and `load_roots`"
+context = """
+The `save_roots` and `load_roots` methods are used in the ChainStore trait to save and load the accumulator state, which is serialized as a `Vec<u8>`.
+"""
+id = "b944905f-c1e7-403c-95bb-c8f126bc8e88"
+
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "What does the `flush` method in ChainStore ensure?"
+prompt.distractors = [
+  "That only block headers are written to memory.",
+  "That all data is stored temporarily in memory.",
+  "That only block hashes are flushed to disk."
+]
+answer.answer = "That all saved data is written to disk."
+context = """
+The `flush` method in ChainStore ensures that any data saved in memory is written to disk, guaranteeing that it can be recovered after a crash.
+"""
+id = "a5cb47b2-84f0-4e37-805d-1a256839f3cc"
+
+[[questions]]
+type = "MultipleChoice"
+prompt.prompt = "What are the three buckets used in the KvChainStore type?"
+prompt.distractors = [
+  "Headers bucket, Block bucket, Meta bucket",
+  "Index bucket, Meta bucket, Block bucket",
+  "Tx bucket, Index bucket, Meta bucket"
+]
+answer.answer = "Index bucket, Headers bucket, Meta bucket"
+context = """
+The `KvChainStore` type uses three buckets: the `index` bucket for block hashes and heights, the `headers` bucket for block headers, and the `meta` bucket for accumulator state and best chain data.
+"""
+id = "e64845c6-add9-4d32-91b5-dea5cf341365"