dev: Book Buildout (#19)

* update .gitignore

* create book.yml workflow

* add piltover_logo.png

* add favicon.png

* add book

* fix shrinking logo

* Change book linting rules

---------

Co-authored-by: Brandon Roberts <[email protected]>

.github/linter/book_style.rb

@@ -0,0 +1,9 @@
+all
+# lame rules
+exclude_rule 'MD002'
+exclude_rule 'MD041'
+
+# allow inline HTML for book files
+exclude_rule 'MD033'
+# Allow long lines in the book for now
+exclude_rule 'MD013'

.github/workflows/book.yml

@@ -0,0 +1,30 @@
+name: book
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - book/**
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  book:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Swatinem/rust-cache@v2
+      - name: Build
+        run: |
+          cargo install mdbook
+          mdbook build book
+  
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book/book

.github/workflows/check.yml

@@ -16,7 +16,8 @@ jobs:
       - run: |
           sudo gem install mdl
           mdl -s .github/linter/readme_style.rb README.md
-          mdl -s .github/linter/base_style.rb book .github
+          mdl -s .github/linter/base_style.rb .github
+          mdl -s .github/linter/book_style.rb book
 
   test:
     runs-on: ubuntu-latest

.gitignore

@@ -8,3 +8,6 @@
 # Starkli
 **/account.json
 **/keystore.json
+
+# mdBook
+book/book/

book/book.toml

@@ -0,0 +1,10 @@
+[book]
+authors = ["JimmyFate"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Piltover"
+
+[output.html]
+git-repository-url = "https://github.com/keep-starknet-strange/piltover"
+edit-url-template = "https://github.com/keep-starknet-strange/piltover/issues/new/choose"

book/src/README.md

@@ -0,0 +1,8 @@
+<div style="display: flex; align-items: center;">
+    <div style="padding: 10px;">
+        <h1>Piltover</h1>
+        <p>Starknet Core Contract components in Cairo.</p>
+        <a href="./getting-started/index.html">Enter the City...</a>
+    </div>
+    <img class="resp" src="assets/piltover_logo.png" alt="logo" style="min-width: 300px"/>
+</div>

book/src/SUMMARY.md

@@ -0,0 +1,14 @@
+# Summary
+
+[Introduction](./README.md)
+
+- [Getting Started](./getting-started/README.md)
+  1. [Build](./getting-started/build.md)
+  1. [Test](./getting-started/test.md)
+- [Overview](./overview/README.md)
+- [Components](./components/README.md)
+  1. [config](./components/config.md)
+  1. [messaging](./components/messaging.md)
+- [Contributing](./contributing/README.md)
+  1. [Code Style](./contributing/code-style.md)
+  1. [Additional Resources](./contributing/additional-resources.md)

book/src/components/README.md

@@ -0,0 +1,4 @@
+# Components
+
+* [`config`](./config.md) - Base configuration for appchain contract
+* [`messaging`](./messaging.md) - Appchain - Starknet messaging

book/src/components/config.md

@@ -0,0 +1,17 @@
+## config
+
+```rust
+trait IConfig<T> {
+    fn set_operator(ref self: T, address: ContractAddress);
+
+    fn get_operator(self: @T) -> ContractAddress;
+
+    fn set_program_info(ref self: T, program_hash: felt252, config_hash: felt252);
+
+    fn get_program_info(self: @T) -> (felt252, felt252);
+
+    fn set_facts_registry(ref self: T, address: ContractAddress);
+
+    fn get_facts_registry(self: @T) -> ContractAddress;
+}
+```

book/src/components/messaging.md

@@ -0,0 +1,29 @@
+## messaging
+
+```rust
+trait IMessaging<T> {
+    fn send_message_to_appchain(
+        ref self: T, to_address: ContractAddress, selector: felt252, payload: Span<felt252>
+    ) -> (felt252, felt252);
+
+    fn consume_message_from_appchain(
+        ref self: T, from_address: ContractAddress, payload: Span<felt252>
+    ) -> felt252;
+
+    fn start_message_cancellation(
+        ref self: T,
+        to_address: ContractAddress,
+        selector: felt252,
+        payload: Span<felt252>,
+        nonce: felt252,
+    ) -> felt252;
+
+    fn cancel_message(
+        ref self: T,
+        to_address: ContractAddress,
+        selector: felt252,
+        payload: Span<felt252>,
+        nonce: felt252,
+    ) -> felt252;
+}
+```

book/src/contributing/README.md

@@ -0,0 +1,45 @@
+# Contributing to Piltover
+
+Welcome, contributing to `piltover` is easy!
+
+1. Submit or comment your intent on an issue
+1. We will try to respond quickly
+1. Fork this repo
+1. Submit your PR against `main`
+1. Address PR Review
+
+## Issue
+
+Project tracking is done via GitHub [issues](https://github.com/keep-starknet-strange/piltover/issues).
+First look at open issues to see if your request is already submitted.
+If it is comment on the issue requesting assignment, if not open an issue.
+
+We use 3 issue labels for development:
+
+- `feat` -> suggest new feature
+- `bug` -> create a reproducible bug report
+- `dev` -> non-functional repository changes
+
+These labels are used as prefixes as follows for `issue`, `branch name`, `pr title`:
+
+- `[feat]` -> `feat/{issue #}-{issue name}` -> `feat:`
+- `[bug]` -> `bug/{issue #}-{issue name}` -> `bug:`
+- `[dev]` -> `dev/{issue #}-{issue name}` -> `dev:`
+
+## Submit PR
+
+Ensure your code is well formatted, well tested and well documented. A core contributor
+will review your work. Address changes, ensure ci passes,
+and voilà you're a piltover contributor.
+
+Markdown [linter](https://github.com/markdownlint/markdownlint?tab=readme-ov-file#markdown-lint-tool):
+
+```bash
+mdl -s .github/linter/readme_style.rb README.md
+```
+
+Scarb linter:
+
+```bash
+scarb fmt
+```

book/src/contributing/additional-resources.md

@@ -0,0 +1,7 @@
+## Additional Resources
+
+- [Cairo Book](https://book.cairo-lang.org/)
+- [Starknet Book](https://book.starknet.io/)
+- [Starknet Foundry Book](https://foundry-rs.github.io/starknet-foundry/)
+- [Starknet By Example](https://starknet-by-example.voyager.online/)
+- [Starkli Book](https://book.starkli.rs/)

book/src/contributing/code-style.md

@@ -0,0 +1,18 @@
+# Code Style
+
+## Cairo
+
+- Use `snake_case` for module name and not `PascalCase`.
+
+- Don't import directly a function from a module.
+
+```rust
+// Prefer that:
+let addr = starknet::contract_address_const::<0>();
+
+// Instead of:
+use starknet::contract_address_const;
+let addr = contract_address_const::<0>();
+```
+
+- Document functions inside the trait, and add details if needed in the implementation.

book/src/getting-started/README.md

@@ -0,0 +1,24 @@
+# Getting Started
+
+There are several ways to run `piltover`:
+
+- Install dependencies
+- Run in a dev container
+
+## Install dependencies
+
+`piltover` requires both [scarb](https://docs.swmansion.com/scarb/download.html)
+and [snfoundry](https://foundry-rs.github.io/starknet-foundry). As scarb doesn't
+currently have dependency version resolution we will use `asdf`:
+
+- [install asdf](https://asdf-vm.com/guide/getting-started.html)
+- navigate to project root
+- run `asdf install`
+
+## Run in a dev container
+
+Dev containers provide a dedicated environment for the project. Since the dev
+container configuration is stored in the `.devcontainer` directory, this ensures
+that the environment is strictly identical from one developer to the next.
+
+To run inside a dev container, please follow [Dev Containers tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial).

book/src/getting-started/build.md

@@ -0,0 +1,11 @@
+# Build
+
+## Contracts
+
+Open a terminal and run:
+
+```shell
+scarb build
+```
+
+This will build the smart contracts into `target` directory.

book/src/getting-started/test.md

@@ -0,0 +1,11 @@
+# Test
+
+## Contracts
+
+Open a terminal and run:
+
+```shell
+snforge test
+```
+
+This will execute the tests in `tests` directory and print the results.

book/src/overview/README.md

@@ -0,0 +1,9 @@
+# Overview
+
+The Starknet Core Contract is the foundation for Layer 3s on Starknet.
+
+## L1 Starknet Core Contract
+
+The Starknet Core Contract can be found in the [cairo-lang repository](https://github.com/starkware-libs/cairo-lang/blob/v0.13.1a0/src/starkware/starknet/solidity/Starknet.sol).
+
+It's live version can be viewed on [etherscan](https://etherscan.io/address/0xc662c410C0ECf747543f5bA90660f6ABeBD9C8c4).