Merge branch 'feat/hermes-packaging-docs' of github.com:input-output-…

…hk/hermes into feat/hermes-packaging-docs

.config/dictionaries/project.dic

@@ -4,6 +4,7 @@ adminer
 asyncio
 auditability
 backpressure
+bindgen
 blockfetch
 BROTLI
 cardano
@@ -15,6 +16,7 @@ ciphertext
 codegen
 codepoints
 coti
+crontabs
 cryptoxide
 dbsync
 dcbor
@@ -26,16 +28,29 @@ dotglob
 drep
 dreps
 encryptor
+Errno
 excalidraw
+fadvise
+fcntl
+fdatasync
+fdstat
+Filesize
+filestat
+filesystems
 fmtchk
 fmtfix
 fontawesome
 fsgr
+fstat
+fstatat
+futimens
 genhtml
+GETFL
 gmtime
 hardano
 ideascale
 idents
+IFMT
 Intellij
 iohk
 jetbrains
@@ -45,39 +60,58 @@ Jörmungandr
 kroki
 lcov
 Leshiy
+linkat
 lintfix
 localizable
 mdlint
+miniprotocol
 miniprotocols
 mithril
 mitigations
+mkcron
+mkdelay
+mkdirat
 moderations
 multiera
 nanos
 netkey
 nextest
 oneshot
 openapi
+openat
 opentelemetry
+outlen
+Outparam
 permissioned
 parameterises
 permissionless
 pg_isready
 plpgsql
+pollable
+pread
+preopened
+preopens
 preprod
 psql
 pubkey
 pubspec
+pwrite
 rapidoc
+readlinkat
 redoc
+REMOVEDIR
+renameat
+retriggering
 rustc
 rustdoc
 rustdocflags
 rustflags
 saibatizoku
+Sched
 seckey
 slotno
 stevenj
+symlinkat
 tacho
 testcov
 testdocs
@@ -86,10 +120,20 @@ thiserror
 timelike
 toolsets
 Traceback
+txns
+unlinkat
+utimensat
 vitss
 voteplan
 voteplans
+wasi
 WASI
 wasmtime
 webasm
+webassembly
+WORKDIR
 yoroi
+smac
+bmac
+typenum
+hasher

.gitignore

@@ -22,7 +22,6 @@
 # Icon must end with two \r
 Icon
 
-
 # Thumbnails
 ._*
 
@@ -78,3 +77,7 @@ $RECYCLE.BIN/
 !/.vscode/launch.recommended.json
 !/.vscode/settings.recommended.json
 !/.vscode/tasks.recommended.json
+
+# Dart stuff
+/pubspec.lock
+/.dart_tool/**/*

.vscode/extensions.json

@@ -15,6 +15,13 @@
         "rust-lang.rust-analyzer",
         "JScearcy.rust-doc-viewer",
         "serayuzgur.crates",
-        "panicbit.cargo",
+        "bierner.markdown-checkbox",
+        "bierner.markdown-emoji",
+        "bierner.markdown-footnotes",
+        "bierner.markdown-mermaid",
+        "bpruitt-goddard.mermaid-markdown-syntax-highlighting",
+        "bytecodealliance.wit-idl",
+        "foxundermoon.shell-format",
+        "dtsvet.vscode-wasm",
     ]
 }

Earthfile

@@ -7,17 +7,17 @@ FROM debian:stable-slim
 
 # check-markdown markdown check using catalyst-ci.
 check-markdown:
-    DO github.com/input-output-hk/catalyst-ci/earthly/mdlint:v2.0.10+CHECK
+    DO github.com/input-output-hk/catalyst-ci/earthly/mdlint:v2.7.0+CHECK
 
 # markdown-check-fix markdown check and fix using catalyst-ci.
 markdown-check-fix:
     LOCALLY
 
-    DO github.com/input-output-hk/catalyst-ci/earthly/mdlint:v2.0.10+MDLINT_LOCALLY --src=$(echo ${PWD}) --fix=--fix
+    DO github.com/input-output-hk/catalyst-ci/earthly/mdlint:v2.7.0+MDLINT_LOCALLY --src=$(echo ${PWD}) --fix=--fix
 
 # check-spelling Check spelling in this repo inside a container.
 check-spelling:
-    DO github.com/input-output-hk/catalyst-ci/earthly/cspell:v2.0.10+CHECK
+    DO github.com/input-output-hk/catalyst-ci/earthly/cspell:v2.7.0+CHECK
 
 # check-spelling Check spelling in this repo inside a container.
 spell-list-words:

docs/Earthfile

@@ -6,23 +6,25 @@ VERSION 0.7
 # Copy all the source we need to build the docs
 src:
     # Common src setup
-    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.11+SRC
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.7.0+SRC
 
     # Now copy into that any artifacts we pull from the builds.
     COPY --dir ../+repo-docs/repo /docs/includes
     # copy Rust docs
     COPY ./../hermes+build/doc /docs/src/api/rust-docs
+    # Copy the WASM Component model API Docs
+    COPY --dir ./../wasm/wasi+build/wasi-hermes-docs /docs/src/api/wasi-hermes
 
 # Build the docs here.
 docs:
     FROM +src
 
-    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.11+BUILD
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.7.0+BUILD
 
 # Make a locally runable container that can serve the docs.
 local:
     # Build a self contained service to show built docs locally.
-    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.11+PACKAGE
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.7.0+PACKAGE
 
     # Copy the static pages into the container
     COPY +docs/ /usr/share/nginx/html

docs/src/api/.pages

@@ -1,2 +1,3 @@
 nav:
   - index.md
+  - 'Hermes-WASI API': wasi-hermes

docs/src/architecture/08_concepts/cardano_chain_follower/.pages

@@ -0,0 +1,3 @@
+title: Cardano Chain Follower
+arrange:
+    - 01_overview.md

docs/src/architecture/08_concepts/cardano_chain_follower/01_overview.md

@@ -0,0 +1,78 @@
+# 1. Overview
+
+The `cardano-chain-follower` crate provides functionality to read arbitrary blocks
+and follow updates (new blocks and rollbacks) from a Cardano network (e.g. mainnet, preprod).
+
+Currently, the all communication with a Cardano node (remote or local) is done using the
+[Node-to-Node protocol](https://docs.cardano.org/explore-cardano/cardano-network/about-the-cardano-network).
+A [Mithril snapshot](https://github.com/input-output-hk/mithril) can be configured to be used both when reading blocks
+and following chain updates.
+
+The [Pallas](https://github.com/txpipe/pallas) crate is used under the hood to provide
+node communication, block parsing and other Cardano chain features.
+
+## 1.1 Chain Follow
+
+The chain follower is capable of receiving chain updates from a Cardano node using the ChainSync miniprotocol.
+
+```kroki-excalidraw
+@from_file:architecture/08_concepts/cardano_chain_follower/images/overview.excalidraw
+```
+
+### Read pointer
+
+The read pointer points at the location the chain is being read by a client connection.
+Although the Cardano node maintains a read pointer for each client, the chain follower manages
+its own copy of the read pointer in order to follow the chain even when it's reading data from a Mithril snapshot.
+The follower's read pointer gets updated every time it receives a chain update.
+
+### Chain Updates
+
+The chain follower spawns a background task that keeps a Node-to-Node connection to a Cardano node
+and continuously receives updates from it and sends them to the follower using a async channel.
+A chain update can be either a roll forward (a new block added to the chain) or a rollback.
+
+If any node communication error happens in the background task, this is also sent through the channel.
+
+If the follower has been configured to use a Mithril snapshot, it will generate
+synthetic roll forward chain updates for each block until the snapshot's tip is reached.
+After that, updates are received from the node.
+
+If any errors occur while reading the block from the Mithril snapshot (e.g. the block is missing from the snapshot, I/O errors)
+the background task will fallback to receiving the failed block from the Cardano node.
+
+Below is a simplified flow diagram of the background task's process for producing chain updates.
+
+#### A. Chain update flow diagram
+
+```kroki-excalidraw
+@from_file:architecture/08_concepts/cardano_chain_follower/images/simplified-get-update-flow.excalidraw
+```
+
+## 1.2 Chain Read
+
+*NOTE: Reading blocks does not affect the follower read pointer.*
+
+When reading a single or a range of arbitrary blocks from the chain the follower initiates a new connection with the configured node
+blocks are read using the Blockfetch miniprotocol.
+If configured, available blocks are read from the Mithril snapshot as well.
+
+When a block is requested, the follower will try reading the block from the Mithril snapshot
+first (if configured) and, only if the block is not found, it'll ask the connected node for the block.
+
+When a range of blocks is requested, the follower will try reading as many blocks as it can from the Mithril snapshot
+(if configured) and, if any blocks are not contained in the snapshot, it'll ask the connected node for them.
+
+Below is a simplified flow diagram of the block reading logic.
+
+### A. Single block flow diagram
+
+```kroki-excalidraw
+@from_file:architecture/08_concepts/cardano_chain_follower/images/simplified-reader-single-block-flow.excalidraw
+```
+
+### B. Block range flow diagram
+
+```kroki-excalidraw
+@from_file:architecture/08_concepts/cardano_chain_follower/images/simplified-reader-block-range-flow.excalidraw
+```