diff --git a/.github/workflows/book-preview-link.yml b/.github/workflows/book-preview-link.yml new file mode 100644 index 00000000..dc2d644a --- /dev/null +++ b/.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 + }); + } diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml new file mode 100644 index 00000000..d283c069 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index 490723eb..3a5b0822 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,6 @@ Cargo.lock /.idea /.vscode /target + +# Ignore the book build directory +/book/book/ diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 00000000..e646f974 --- /dev/null +++ b/book/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["hasanza"] +language = "en" +multilingual = false +src = "src" +title = "The Athena Book" diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 00000000..f7df7d76 --- /dev/null +++ b/book/src/SUMMARY.md @@ -0,0 +1,5 @@ +# Summary + +- [The Athena Book](./chapter_1.md) +- [Introduction](./chapter_2.md) +- [Prerequisites](./chapter_3.md) diff --git a/book/src/chapter_1.md b/book/src/chapter_1.md new file mode 100644 index 00000000..5e02f954 --- /dev/null +++ b/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. + +
+ +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). + +
diff --git a/book/src/chapter_2.md b/book/src/chapter_2.md new file mode 100644 index 00000000..a9cdaaab --- /dev/null +++ b/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! diff --git a/book/src/chapter_3.md b/book/src/chapter_3.md new file mode 100644 index 00000000..178f2a81 --- /dev/null +++ b/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!