Merge pull request #58 from athenavm/add-athena-book

Add athena book

.github/workflows/book-preview-link.yml

@@ -0,0 +1,43 @@
+name: Book Preview Link
+
+on:
+  pull_request:
+    paths:
+      - "book/**"
+    types: [opened, synchronize, reopened]
+
+jobs:
+  preview-link:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Add Preview Link
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            const previewUrl = `https://www.athenavm.org/athena/preview/${context.issue.number}/book/`;
+            const commentBody = `📘 Book preview available at: ${previewUrl}`;
+
+            // Get all comments
+            const comments = await github.rest.issues.listComments({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo
+            });
+
+            // Find our bot comment
+            const botComment = comments.data.find(comment =>
+              comment.user.type === 'Bot' && comment.body.includes('Book preview available at:')
+            );
+
+            if (!botComment) {
+              // Create new comment
+              await github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: commentBody
+              });
+            }

.github/workflows/book.yml

@@ -0,0 +1,77 @@
+# Documentation and mdbook related jobs.
+# Reference: https://github.com/paradigmxyz/reth/blob/main/.github/workflows/book.yml
+
+name: book
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "book/**"
+  pull_request:
+    branches: [main]
+    paths:
+      - "book/**"
+  merge_group:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    name: lint
+    timeout-minutes: 60
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mdbook-linkcheck
+        run: |
+          mkdir mdbook-linkcheck
+          curl -sSL -o mdbook-linkcheck.zip https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip
+          unzip mdbook-linkcheck.zip -d ./mdbook-linkcheck
+          chmod +x $(pwd)/mdbook-linkcheck/mdbook-linkcheck
+          echo $(pwd)/mdbook-linkcheck >> $GITHUB_PATH
+
+      - name: Run linkcheck
+        working-directory: book
+        run: mdbook-linkcheck --standalone
+
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    needs: lint
+
+    timeout-minutes: 60
+
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: "latest"
+
+      - name: Build book
+        working-directory: book
+        run: mdbook build
+
+      - name: Deploy to Staging
+        if: github.ref_name != 'main' || github.event_name != 'push'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book
+          destination_dir: preview/${{ github.event.pull_request.number }}
+
+      # Note: this step will overwrite the work of the previous step.
+      # That's okay since they're mutually exclusive.
+      - name: Deploy
+        if: github.ref_name == 'main' && github.event_name == 'push'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book

.gitignore

@@ -18,3 +18,6 @@ Cargo.lock
 /.idea
 /.vscode
 /target
+
+# Ignore the book build directory
+/book/book/

book/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["hasanza"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Athena Book"

book/src/SUMMARY.md

@@ -0,0 +1,5 @@
+# Summary
+
+- [The Athena Book](./chapter_1.md)
+- [Introduction](./chapter_2.md)
+- [Prerequisites](./chapter_3.md)

book/src/chapter_1.md

@@ -0,0 +1,12 @@
+# The Athena Book
+
+This is the Athena Book, a comprehensive guide to writing programs (i.e., smart contracts) for
+[Athena](https://github.com/athenavm/athena), a deterministic smart contract engine that serves as the VM for the
+[Spacemesh](https://spacemesh.io) network.
+
+<div class="warning">
+
+The book is in active development and a work in progress. If you have any feedback or suggestions, feel free to open an
+issue or create a pull request in the [GitHub repository](https://github.com/athenavm/athena).
+
+</div>

book/src/chapter_2.md

@@ -0,0 +1,24 @@
+# Introduction
+
+Athena is a general-purpose VM that is designed to run smart contracts for the Spacemesh blockchain protocol. While
+Athena is the Spacemesh VM, it's modular and chain agnostic and is designed to work in many places, at L1 and L2, in
+many chains.
+
+At its core is an interpreter that targets the RISC-V instruction set. The ultimate aim behind Athena is to build a
+modern, secure, and performant RISC-V blockchain VM that natively targets ZK execution and proving. In order to achieve
+this, the future plan is to prove Athena program execution using RISC-V zkVMs such as
+[risc0](https://github.com/risc0/risc0/) and [sp1](https://github.com/succinctlabs/sp1/).
+
+Athena supports mainline Rust as its smart contract programming language. Rust is the perfect candidate for writing
+blockchain programs due to its mature ecosystem, high performance, built-in safety features, and powerful and mature
+LLVM toolchain. Athena supports both the RV32IM and RV32EM variants of RISC-V, but for now all Athena programs target
+RV32EM. We chose the "embedded" variant, with 16 rather than 32 registers, in order to facilitate developing a "runtime
+kernel" that will wrap Athena programs when they're run in the zkVMs mentioned above.
+
+Since today Rust doesn't yet fully support RV32EM, we had to create and maintain
+[our own Rust toolchain](https://github.com/athenavm/rustc-rv32e-toolchain/tree/main) with support for this target. For
+now, Athena users need to download this toolchain to be able to compile Athena code, but this process is fully automated
+by the CLI tools. It's our goal to remove this requirement in the not-too-distant future, realizing our vision that
+"Athena is just Rust."
+
+With this, let us start writing programs for Athena!

book/src/chapter_3.md

@@ -0,0 +1,20 @@
+# Prerequisites
+
+Currently, to write, compile, and run smart contracts for Athena, you need to have:
+
+1. Ubuntu 22.04 or newer (support for other operating systems is planned and contributions are welcome),
+1. the Rust language, and
+1. the Athena VM and the Athena toolchain installed on your system.
+
+## Getting Started
+
+To start, simply enter the following command in a terminal:
+
+`curl -L https://install.athenavm.org | bash`
+
+Follow the instructions to add Athena to your shell's path directory, then run
+
+`athup`
+
+to download and install the Athena Rust toolchain. Once these are successfully installed, you are now ready to compile
+and run your first Athena program!