dev_process_worker:compute_cached/3 — unwrap AO-Core {ao-result, body} envelope (#942)

.github/workflows/cd.yaml

@@ -28,7 +28,7 @@ jobs:
         uses: google-github-actions/setup-gcloud@v2
 
       - name: Setup build tools (Erlang, Packer and Rebar3)
-        run: | 
+        run: |
           curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
           sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
           sudo apt-get update
@@ -37,7 +37,7 @@ jobs:
           git clone https://github.com/erlang/rebar3.git && cd rebar3 && ./bootstrap && sudo mv rebar3 /usr/local/bin/
 
       - name: Build and release AO/HyperBEAM with Rebar3
-        run: | 
+        run: |
           rebar3 clean
           rebar3 get-deps
           rebar3 compile
@@ -51,7 +51,7 @@ jobs:
           echo "image_name=${TIMESTAMPED_IMAGE_NAME}" >> "$GITHUB_OUTPUT"
 
       - name: Build Packer Image
-        run: | 
+        run: |
           packer init .
           packer validate .
           packer build -var "image_name=${{ steps.set_image_name.outputs.image_name }}" -var "project_id=${{ env.GCP_PROJECT }}" .
@@ -75,13 +75,11 @@ jobs:
       - name: Setup GCloud SDK
         uses: google-github-actions/setup-gcloud@v2
 
-      - name: Create Confidential VM
+      - name: Create VM
         run: |
           gcloud compute instances create ${{ env.GCP_INSTANCE_NAME }} \
             --zone=${{ env.GCP_ZONE }}  \
             --machine-type=n2d-standard-2 \
-            --min-cpu-platform="AMD Milan" \
-            --confidential-compute-type=SEV_SNP \
             --maintenance-policy=TERMINATE \
             --image-family=ubuntu-2404-lts-amd64 \
             --image-project=ubuntu-os-cloud \
@@ -119,7 +117,7 @@ jobs:
       - name: Setup GCloud SDK
         uses: google-github-actions/setup-gcloud@v2
 
-      - name: Delete Confidential VM
+      - name: Delete VM
         run: |
           gcloud compute instances delete ${{ env.GCP_INSTANCE_NAME }} \
             --project=${{ env.GCP_PROJECT }} \

.gitignore

@@ -1,3 +1,4 @@
+config.*
 .rebar3
 _build
 _checkouts
@@ -42,4 +43,4 @@ mkdocs-site/
 mkdocs-site-id.txt
 mkdocs-site-manifest.csv
 
-!test/admissible-report-wallet.json
+!test/config.json

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "native/lib/secp256k1"]
+	path = native/lib/secp256k1
+	url = https://github.com/bitcoin-core/secp256k1.git

.vscode/launch.json

@@ -14,7 +14,7 @@
       "internalConsoleOptions": "openOnSessionStart",
       "module": "hb_debugger",
       "function": "start_and_break",
-      "args": "[${input:moduleName}, ${input:functionName}, [${input:funcArgs}]]"
+      "args": "[${input:moduleName}, ${input:functionName}, [${input:funcArgs}], <<\"${input:debuggerScope}\">>]"
     },
     {
       "name": "Attach to a 'rebar3 debugger' node.",
@@ -65,6 +65,11 @@
       "id": "funcArgs",
       "type": "promptString",
       "description": "(Optional) Pass arguments to the function:"
+    },
+    {
+      "id": "debuggerScope",
+      "type": "promptString",
+      "description": "(Optional) Additional modules/prefixes for debugger scope:"
     }
   ]
 }

.vscode/settings.json

@@ -1,5 +1,6 @@
 {
   "editor.detectIndentation": false,
   "editor.insertSpaces": true,
-  "editor.tabSize": 4
+  "editor.tabSize": 4,
+  "editor.rulers": [80]
 }

.vscode/tasks.json

@@ -14,7 +14,37 @@
     {
       "label": "Stop HyperBEAM",
       "type": "shell",
-      "command": "lsof -i tcp:10000 | tail -n 1 | awk '{print $2}' | xargs kill -9"
+      "command": "lsof -i tcp:8734 | tail -n 1 | awk '{print $2}' | xargs kill -9"
+    },
+    {
+      "label": "Generate a flame graph for a function.",
+      "type": "shell",
+      "command": "rebar3 as eflame shell --eval \"hb_debugger:profile_and_stop(fun() -> ${input:moduleName}:${input:functionName}(${input:funcArgs}) end).\"",
+      "group": "test",
+      "problemMatcher": "$erlang",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": false,
+        "panel": "new"
+      }
+    }
+  ],
+  "inputs": [
+    {
+      "id": "moduleName",
+      "type": "promptString",
+      "description": "Enter module:"
+    },
+    {
+      "id": "functionName", 
+      "type": "promptString",
+      "description": "Enter an exported function name:"
+    },
+    {
+      "id": "funcArgs",
+      "type": "promptString",
+      "description": "(Optional) Pass arguments to the function:"
     }
   ]
 }

AGENTS.md

@@ -0,0 +1,24 @@
+This repository contains HyperBEAM, an implementation of the AO-Core protocol.
+
+To familiarize yourself with AO-Core, read the `README.md` file.
+
+To understand how to write code for HyperBEAM, read `CONTRIBUTING.md` for 
+repository-level guidelines, and `docs/misc/hacking-on-hyperbeam.md` learn about
+its debugging tools and infrastructure.
+
+In addition to the rules outlined in `CONTRIBUTING.md`, you should abide by the
+following:
+
+1. Always be surgical in your edits. Minimize the line-of-code changes you make
+   during every single edit.
+2. Before adding new utilities, search for existing utilities that do something
+   similar. Candidates are often found in `hb_ao`, `hb_util`, and `hb_test_utils`.
+3. Ensure that you understand the differences between Erlang map terms and 
+   AO-Core's messages. Messages are built using maps under-the-hood, but may also
+   be lazy-loaded (linkified), giving them different semantics.
+4. Before submitting any code as 'complete', you **must** validate that your
+   new changes do not break any existing tests across the full suite. You are 
+   never being asked to write a 'toy' implementation of features or changed. Your
+   code must actually work in-production.
+5. Always attempt to leave the codebase in a better state than you found it. More
+   precise, clear, and minimal -- while maintaining the existing featureset.

CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to HyperBEAM.
+
+There are three basic rules for writing and merging PRs to HyperBEAM:
+1. The PR must not introduce additional test failures, flakes, or
+   removal/defeating of existing tests unless agreed by multiple maintainers.
+2. Modifications to the 'kernel layer' must never be made where modifications to
+   the 'application layer' would suffice.
+3. Merged code must abide by the existing style in the repo. Just write and merge
+   code that blends in. This rule sounds unimportant, but over time it is what makes
+   the code maintainable and understandable by a larger set of developers.
+   Spaghetti/mixed styles lowers comprehension, which in a security sensitive
+   environment => bugs => lost value. No broken windows if we can help it.
+
+# The HyperBEAM Style Guide.
+
+**Rule one of style guide club:** _We do not talk about style guide club._
+
+We are here to build a fully decentralized alternative to cyberspace as it 
+is currently constructed. We are not interested in long conversations about
+where to put commas or spaces.
+
+**Rule two of style guide club:** _Blend in._
+
+Rule one does not imply that we do not care about the quality of the codebase.
+Far from it: We know that we will be maintaining this code for decades to come.
+It is important that we are all aligned on style and patterns, but less important
+what those styles and patterns actually are. Having `length(Contributors)` 
+styles adds overhead to understanding the codebase, which over time hides bugs
+and reduces maintainability, but each stylistic choice is largely an opinion
+that -- despite strong feelings -- lacks criticality. Hence, rule two:
+Only write and merge code that actually _blends in_.
+
+Write your code as if you were the author of all of the existing code. If all 
+of the other code is written in a certain style, then copy it. If the style
+of the code in your PR would not _blend in_, then its style is objectively
+in violation of `style guide club`'s rules.
+
+In the event of disagreement, a simple rule should guide our decisions: What
+does the majority of the LoC in the codebase already do? Do that. Then get 
+back to hacking.
+
+If you don't like something about the style, simply contribute. If others
+disagree strongly, the existing style will be kept. If your contributions are
+seen by others as reasonable and inline with the canon, then it will gradually 
+become adopted as the standard in the codebase.
+
+**This concludes the rules of style guide club.**
+
+Remember: Cypherpunks write code!
+
+# A Rough Guide to the HyperBEAM `canon`
+
+You should pick up and continue the style of the codebase as you learn how it 
+works. There is no real substitute for paying attention. There are, however, a 
+few basic rules that are widely established and represent the core `canon` of the
+codebase. As of time of {{`git blame`}}, there is highest consensus around the
+following:
+
+- Always use `-` over `_` in binary key names.
+    - Why: In general we try to follow the HTTP semantics RFC 9110, so all keys
+      should be HTTP-Header-Case. This is the style that has been used for Arweave
+      data protocols since inception, so to avoid confusion we maintain it in
+      HyperBEAM. 
+    - Nuances:
+        - One weirdness we inherit from HTTP-land is that headers are actually
+          case-insensitive, despite the use of capitals in header descriptions,
+          over-the-wire they are lower-case in HTTP/2+. AO-Core shoots for the
+          same semantics for consistency.
+        - In device key resolutions that have multiple words (for example:
+          `i_like(Base, Req, Opts) -> {ok, <<"Turtles!">>}.`) you may be tempted
+          to call `~device@1.0/i_like`. Don't. Instead call `/i-like`.
+          `hb_ao_device` will normalize the keys and match for you.
+        - `hb_opts` uses all atoms for its message keys. This is a mistake. It
+          is nice to be able to lookup keys via atoms (normalizing as above) and
+          we should maintain this, but under the surface the keys should be
+          normal-form binaries. To avoid issues when this is translated, perform
+          `Opts` lookups with only atoms, or use binaries of normal-form if you
+          must.
+- Try to keep lines to around 80 characters-ish. This is not a strict rule because
+  sometimes an 81-85 character line would be very ugly and harder to follow if split.
+  Use your judgement.
+  - Why: Our objective is to keep the code readable. Monster lines, and machine-enforced
+    strict styles, both butcher this. Human/LLM judgement can help here.
+- Add a `%%% @doc` moduledoc to each new module you write, and comment every
+  function you write with a `%% @doc Description` above it. Inline comments are
+  prepended with a single `%`.
+  - Why: This helps humans and LLMs grok your code in the future. It also surfaces
+    useful information in tooltips etc upstream.
+  - Nuance: I do not know why the Erlang style uses `%%%` for moduledocs, `%%` for
+    functions, and `%` for inline comments, but it does. This can help with parsability
+    for some tooling and the effort-cost is minimal, so we use it.
+- Avoid 'waterfalls'-style statements, instead keeping every set of statements
+  nested such that the start and end of the block are indented inline with each
+  other.
+  - Why: This uses slightly more lines, but makes deeply nested code much more
+    readable and comprehensible.
+  - Examples:
+```erlang
+    BadForm = lists:map(
+        fun(X) ->
+            X * lists:sum(lists:fold(
+                fun(Y, Acc) ->
+                    Y * Acc
+                end,
+                [1,2,3]
+            ))
+        end
+    ),
+    GoodForm = lists:map(
+            fun(X) ->
+                X *
+                    lists:sum(
+                        lists:fold(
+                            fun(Y, Acc) ->
+                                Y * Acc
+                            end,
+                            [1,2,3]
+                        )
+                    )
+            end
+        )
+```
+There are a few areas where there is no consensus on patterns or style yet:
+- Expressing docs in the info/[0,1] call of devices. There are a few different
+  styles in different devices in the codebase -- if you want to add info response
+  'inline' docs try to pick one that already exists and see what works/doesn't.
+  We will need to unify them at some point.
+- `maybe ... end` vs nested `case` expressions. `maybe` seems useful and preferable
+  in at least some cases, but bubbling the right error -- rather than just an error --
+  the caller can sometimes be difficult due to the `else` pattern matching.
+  Experimentation with patterns here would be good.

Makefile

@@ -6,9 +6,14 @@ compile:
 WAMR_VERSION = 2.2.0
 WAMR_DIR = _build/wamr
 
-GENESIS_WASM_BRANCH = tillathehun0/cu-experimental
+GENESIS_WASM_BRANCH = feat/hb-unit
 GENESIS_WASM_REPO = https://github.com/permaweb/ao.git
-GENESIS_WASM_SERVER_DIR = _build/genesis-wasm-server
+GENESIS_WASM_SERVER_DIR = _build/genesis_wasm/genesis-wasm-server
+
+HYPERBUDDY_UI_REPO = https://github.com/permaweb/hb-explorer
+HYPERBUDDY_UI_PACKAGE_JSON = https://raw.githubusercontent.com/permaweb/hb-explorer/main/package.json
+HYPERBUDDY_UI_TARGET = src/html/hyperbuddy@1.0/bundle.js
+ARWEAVE_GATEWAY = https://arweave.net
 
 ifdef HB_DEBUG
 	WAMR_FLAGS = -DWAMR_ENABLE_LOG=1 -DWAMR_BUILD_DUMP_CALL_STACK=1 -DCMAKE_BUILD_TYPE=Debug
@@ -50,11 +55,16 @@ $(WAMR_DIR):
 		--single-branch
 
 $(WAMR_DIR)/lib/libvmlib.a: $(WAMR_DIR)
-	sed -i '742a tbl_inst->is_table64 = 1;' ./_build/wamr/core/iwasm/aot/aot_runtime.c; \
+	@if ! grep -Fq 'tbl_inst->is_table64 = 1;' ./_build/wamr/core/iwasm/aot/aot_runtime.c; then \
+		awk 'NR == 742 { print; print "tbl_inst->is_table64 = 1;"; next } { print }' \
+			./_build/wamr/core/iwasm/aot/aot_runtime.c > ./_build/wamr/core/iwasm/aot/aot_runtime.c.tmp && \
+		mv ./_build/wamr/core/iwasm/aot/aot_runtime.c.tmp ./_build/wamr/core/iwasm/aot/aot_runtime.c; \
+	fi; \
 	cmake \
 		$(WAMR_FLAGS) \
 		-S $(WAMR_DIR) \
 		-B $(WAMR_DIR)/lib \
+		-DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
 		-DWAMR_BUILD_TARGET=$(WAMR_BUILD_TARGET) \
 		-DWAMR_BUILD_PLATFORM=$(WAMR_BUILD_PLATFORM) \
 		-DWAMR_BUILD_MEMORY64=1 \
@@ -98,9 +108,26 @@ setup-genesis-wasm: $(GENESIS_WASM_SERVER_DIR)
 		echo "Error: Node.js is not installed. Please install Node.js before continuing."; \
 		echo "For Ubuntu/Debian, you can install it with:"; \
 		echo "  curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && \\"; \
-		echo "  apt-get install -y nodejs && \\"; \
+		echo "  apt-get install -y nodejs=22.16.0-1nodesource1 --allow-downgrades && \\"; \
 		echo "  node -v && npm -v"; \
 		exit 1; \
 	fi
 	@cd $(GENESIS_WASM_SERVER_DIR) && npm install > /dev/null 2>&1 && \
 		echo "Installed genesis-wasm@1.0 server."
+
+# Update hyperbuddy-ui from remote bundle
+update-hyperbuddy-ui:
+	@echo "Fetching package.json from $(HYPERBUDDY_UI_REPO)..." && \
+	TX_ID=$$(curl -s "$(HYPERBUDDY_UI_PACKAGE_JSON)" | grep -o '"bundle"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4) && \
+	if [ -z "$$TX_ID" ]; then \
+		echo "Error: Could not find 'bundle' field in package.json"; \
+		exit 1; \
+	fi && \
+	echo "Found transaction ID: $$TX_ID" && \
+	if [ -f "$(HYPERBUDDY_UI_TARGET)" ]; then \
+		rm "$(HYPERBUDDY_UI_TARGET)" && \
+		echo "Removed existing bundle.js"; \
+	fi && \
+	echo "Downloading source code from Arweave..." && \
+	curl -sL "$(ARWEAVE_GATEWAY)/$$TX_ID" -o "$(HYPERBUDDY_UI_TARGET)" && \
+	echo "Successfully updated $(HYPERBUDDY_UI_TARGET)"