POC Custom ANT module

.prettierrc

@@ -3,5 +3,6 @@
   "semi": true,
   "printWidth": 80,
   "singleQuote": true,
-  "trailingComma": "all"
+  "trailingComma": "all",
+  "proseWrap": "always"
 }

docs/adr/draft-ant-binary.md

@@ -0,0 +1,144 @@
+# Immutable code + Reassign ArNS as a solution for versioning ANTs
+
+- Status: draft
+- Approvers:
+- Date: [2024-12-10]
+- Authors: Atticus
+
+## Context and Problem Statement
+
+For our ANT processes we current us AOS - an implementation of a lua repl in
+lua - to manage the methods in user ANT processes thru the `eval` method to
+update and modify code.
+
+When it comes to version this mutable process, we run into the issue of not
+being able to trust the version of things in the process - unknown code can be
+run on the process, even accidentally, or deliberately with unknown side
+effects.
+
+This means for versioning we need to dryrun the API's to test what the API's
+actually do when a non-breaking change happens - this is quite a lot of work
+when it comes to understanding where in the versioning timeline an ANT stands
+and it increases code complexity and maintenance for clients.
+
+Ideally we have a version number to operate off of to decide on upgrades.
+
+## Decision Drivers
+
+We need a way to upgrade ANT's that not just updates the code but also is easy
+to understand what the capabilities are - versioning is the best way to do that
+since we can know what each version does. There are other benefits to compiling
+a ANT module as well.
+
+- Updates the ANT source code
+- Accurately able to version the APIs
+
+## Considered Options
+
+- Continue using `eval` to update code and dry run each api to evaluate of the
+  inputs were accepted and outputs are valid
+- Add a handler that accepts messages to run (dry run only and owner-only) then
+  validating each input/output
+  - Similar to the above but would allow one call with results on each api -
+    essentially this is a batch eval method that would reset ANT state on each
+    message it runs.
+- Compile Custom ANT WASM Binary and spawn a new ANT, port over the current
+  ANT's state, then call Reassign-Name to transfer the connected arns name(s) to
+  the new ANT.
+  - note we can have a tag on the new ANT to indicate which ANT it was
+    previously.
+
+## Decision Outcome
+
+<!-- TODO: fill out decision outcome after discussion -->
+
+The proposed outcome here is to use a custom WASM module we compile specifically
+for ANTs instead of using AOS and compiling lua code, with the following
+workflow:
+
+1. Spawn New ANT with an initial ANT state
+   - This is only concerned with ANT, since no custom code would be run.
+2. Reassign the ArNS Names(s) to the new ANT id.
+
+### Positive Consequences
+
+- Code is immutable and we do not need to worry about unknown code running on
+  the ANT.
+- Because the code is immutable we can accurately version it - the first version
+  assigned will be its version forever.
+- More control over dependencies (like aos) so we have a proper understanding of
+  the version of code we do not control.
+  - Context: AOS is our current binary we use and the code is COMPILED lua,
+    rather than eval'd lua. Due to how AOS updates (also thru the use of eval)
+    this further confused the abilities, since we not only have to worry about
+    our ANT version, but AOS version as well.
+- We can leverage the `boot` method to initialize state and have the ANT
+  register itself on the ANT registry
+- When buying names the workflow goes from a 4-5 step process (spawn, load lua,
+  init state (optional), register the ant, register name) to a 2 step process
+  (spawn ant, register name)
+- Optimize the code further by compiling smaller memory footprints (since we
+  have literal thousands of these processes, even small memory footprints add
+  up)
+  - Note we can already do this if we custom-compile AOS and not use existing
+    versions, in fact most of these positive consequences could be achieved
+    without custom ANT code and simple compiling custom AOS first. But if we
+    were to do that we would need to have something like a git submodule, and
+    manage both our module ID and Lua code id.
+
+### Negative Consequences
+
+- Puts the onus on us for understanding how the full build process and
+  dependencies work (good and bad depending on perspective)
+- Increases complexity of build time.
+- Built code is opaque and requires more investigation to match versions with
+  code (our code is on github and you would need to go look at the code instead
+  there instead of in-place in the browser)
+
+## Pros and Cons of the Options
+
+[Compare the pros and cons of each considered option.]
+
+### [option 1]
+
+- `+` [pro 1]
+- `+` [pro 2]
+- `-` [con 1]
+- `-` [con 2]
+
+### [option 2]
+
+- `+` [pro 1]
+- `+` [pro 2]
+- `-` [con 1]
+- `-` [con 2]
+
+### [option 3]
+
+- `+` [pro 1]
+- `+` [pro 2]
+- `-` [con 1]
+- `-` [con 2]
+
+## Links
+
+[Include any relevant links to documents, discussions, or other resources that
+provide additional context or background information.]
+
+- [link 1](url)
+- [link 2](url)
+
+## Related Decisions
+
+[List any related ADRs or decisions that are connected to this one.]
+
+- [ADR-1](1-example.md) - [Title of ADR-1]
+- [ADR-2](2-example.md) - [Title of ADR-2]
+
+## Notes
+
+[Include any additional notes or comments that are relevant to the decision.]
+
+---
+
+[ADR Template]: https://adr.github.io/

docs/adr/template.md

@@ -0,0 +1,97 @@
+# [short title of solved problem and solution]
+
+- Status: [proposed | rejected | accepted | deprecated | superseded by
+  [ADR-5](5-example.md)]
+- Approvers: [list everyone involved in the decision]
+- Date: [YYYY-MM-DD]
+- Authors: [list of authors]
+
+## Context and Problem Statement
+
+[Describe the context and the problem that needs to be solved, capturing the
+background and why this decision is necessary.]
+
+## Decision Drivers
+
+[Identify key factors that influence the decision, such as
+requirements, constraints, and other considerations.]
+
+- [driver 1]
+- [driver 2]
+- [driver 3]
+
+## Considered Options
+
+[List the options that were considered to address the problem, providing a brief
+overview of each.]
+
+- [option 1]
+- [option 2]
+- [option 3]
+
+## Decision Outcome
+
+[Describe the decision that was made, including why it was chosen over the
+other options.]
+
+### Positive Consequences
+
+[Highlight the benefits and positive outcomes expected from this decision.]
+
+- [consequence 1]
+- [consequence 2]
+
+### Negative Consequences
+
+[Identify any drawbacks or negative outcomes that might result from this decision.]
+
+- [consequence 1]
+- [consequence 2]
+
+## Pros and Cons of the Options
+
+[Compare the pros and cons of each considered option.]
+
+### [option 1]
+
+- `+` [pro 1]
+- `+` [pro 2]
+- `-` [con 1]
+- `-` [con 2]
+
+### [option 2]
+
+- `+` [pro 1]
+- `+` [pro 2]
+- `-` [con 1]
+- `-` [con 2]
+
+### [option 3]
+
+- `+` [pro 1]
+- `+` [pro 2]
+- `-` [con 1]
+- `-` [con 2]
+
+## Links
+
+[Include any relevant links to documents, discussions, or other resources that
+provide additional context or background information.]
+
+- [link 1](url)
+- [link 2](url)
+
+## Related Decisions
+
+[List any related ADRs or decisions that are connected to this one.]
+
+- [ADR-1](1-example.md) - [Title of ADR-1]
+- [ADR-2](2-example.md) - [Title of ADR-2]
+
+## Notes
+
+[Include any additional notes or comments that are relevant to the decision.]
+
+---
+
+[ADR Template]: https://adr.github.io/

package.json

@@ -1,16 +1,16 @@
 {
   "type": "module",
   "scripts": {
-    "module:build": "cd src && ao build && cd .. && yarn module:load",
-    "module:publish": "cd src && ao publish process.wasm -w ../tools/key.mjson --tag=\"Memory-Limit\" --value=\"1-gb\" --tag=\"Compute-Limit\" --value=\"9000000000000\" && cd ..",
+    "module:build": "cd src/common && ao build && mv process.wasm ../../tools/fixtures/process.wasm && cd ../..",
+    "module:publish": "ao publish tools/fixtures/process.wasm -w tools/key.json --tag=\"Memory-Limit\" --value=\"2-mb\" --tag=\"Compute-Limit\" --value=\"9000000000000\"",
     "module:load": "node tools/load-module.mjs",
     "module:spawn": "node tools/spawn-module.mjs",
     "lint": "luacheck .",
     "aos:build": "node tools/bundle-aos.mjs",
     "aos:publish": "node tools/bundle-aos.mjs && node tools/publish-aos.mjs",
     "aos:load": "node tools/bundle-aos.mjs && node tools/load-aos.mjs",
     "aos:spawn": "node tools/spawn-aos.mjs",
-    "test": "yarn aos:build && node --test --test-concurrency 1 --experimental-wasm-memory64 **/*.test.mjs",
+    "test": "node --test --test-concurrency 1 --experimental-wasm-memory64 test/balances.test.mjs",
     "prepare": "husky"
   },
   "devDependencies": {

spec/ant_spec.lua

@@ -2,7 +2,7 @@ local balances = require("src.common.balances")
 local controllers = require("src.common.controllers")
 local initialize = require("src.common.initialize")
 local records = require("src.common.records")
-local json = require("src.common.json")
+local json = require("src.common.deps.json")
 
 local fake_address = "1111111111111111111111111111111111111111111"
 

src/common/balances.lua

@@ -1,7 +1,7 @@
 --- Module for managing balances and transactions.
 -- @module balances
 
-local utils = require(".common.utils")
+local utils = require(".utils")
 
 local balances = {}
 

src/common/config.yml

@@ -0,0 +1,3 @@
+stack_size: 262144 # 0.25 mb
+initial_memory: 524288 # 0.5 mb
+maximum_memory: 2097152 # 2 mb

src/common/controllers.lua

@@ -1,4 +1,4 @@
-local utils = require(".common.utils")
+local utils = require(".utils")
 
 local controllers = {}