Generated: 2025-06-08T21:39:18Z

--- START OF FILE: docs/build/ao-connect.md ---
# HyperBEAM from AO Connect
This guide explains how to interact with a process using HyperBEAM and `aoconnect`.

## Prerequisites
- Node.js environment
- `@permaweb/aoconnect` library
- The latest version of `aos`
- Wallet file (`wallet.json`) containing your cryptographic keys
- A `HyperBEAM` node running with the `genesis_wasm` profile (`rebar3 as genesis_wasm shell` from your HyperBEAM directory)
- The Process ID for a process created with `genesis_wasm` (this is the default in the latest version of `aos`).

## Step 1: Environment Setup
Install necessary dependencies:

```bash
npm install @permaweb/aoconnect
```

Ensure your wallet file (`wallet.json`) is correctly formatted and placed in your project directory.

> NOTE: you can create a test wallet using this line:
> `npx -y @permaweb/wallet > wallet.json`

## Step 2: Establish Connection
Create a new JavaScript file (e.g., `index.js`) and set up your Permaweb connection. You will need a `processId` of a process that you want to interact with.

```javascript
import { connect, createSigner } from '@permaweb/aoconnect'
import fs from 'node:fs'

const jwk = JSON.parse(fs.readFileSync('wallet.json', 'utf-8'))

// The Process ID to interact with
const processId = "<your genesis_wasm generated process id>";

const { request } = connect({
    MODE: 'mainnet',
    URL: 'http://localhost:8734',
    signer: createSigner(jwk)
})
```

## Step 3: Pushing a Message to a Process
Use the `request` function to send a message to the process. In `aoconnect`, this is done by using the `push` hyperpath.

```javascript
const processResult = await request({
    path: `/${processId}~process@1.0/push/serialize~json@1.0`,
    method: 'POST',
    target: processId,
    "signingFormat": "ANS-104"
})

console.log(processResult)
```

## Full Example

To run the full script, combine the snippets from Step 2 and 3 into `index.js`:

```javascript
import { connect, createSigner } from '@permaweb/aoconnect'
import fs from 'node:fs'

const jwk = JSON.parse(fs.readFileSync('wallet.json', 'utf-8'))

const processId = "<your genesis_wasm generated process id>";

const { request } = connect({
    MODE: 'mainnet',
    URL: 'http://localhost:8734',
    signer: createSigner(jwk)
})

const processResult = await request({
    path: `/${processId}~process@1.0/push/serialize~json@1.0`,
    method: 'POST',
    target: processId,
    "signingFormat": "ANS-104"
})

console.log(processResult)
```

Now, run it:
```bash
node index.js
```

You should see an object logged to the console, containing the ID of the message that was sent.

## Conclusion
Following these steps, you've successfully sent a message to a process. This is a fundamental interaction for building applications on hyperAOS.
--- END OF FILE: docs/build/ao-connect.md ---

--- START OF FILE: docs/build/building-devices.md ---
# Extending HyperBEAM with Devices

We encourage you to extend HyperBEAM with devices for functionality that is general purpose and reusable across different applications.

## What are Devices?

As explained in the [introduction](../introduction/hyperbeam-devices.md), devices are the core functional units within HyperBEAM. They are self-contained modules that process messages and perform specific actions, forming the building blocks of your application's logic.

HyperBEAM comes with a set of powerful [built-in devices](../devices/what-are-devices.md) that handle everything from process management (`~process@1.0`) and message scheduling (`~scheduler@1.0`) to executing WebAssembly (`~wasm64@1.0`) and Lua scripts (`~lua@5.3a`).

## Creating Your Own Devices (Coming Soon)

We will create more in depth guides for building devices in Lua and Erlang in the future.

--- END OF FILE: docs/build/building-devices.md ---

--- START OF FILE: docs/build/extending-hyperbeam.md ---
# Extending HyperBEAM

HyperBEAM's modular design, built on AO-Core principles and Erlang/OTP, makes it highly extensible. You can add new functionalities or modify existing behaviors primarily by creating new **Devices** or implementing **Pre/Post-Processors**.

!!! warning "Advanced Topic"
    Extending HyperBEAM requires a good understanding of Erlang/OTP, the AO-Core protocol, and HyperBEAM's internal architecture. This guide provides a high-level overview; detailed implementation requires deeper exploration of the source code.

## Approach 1: Creating New Devices

This is the most common way to add significant new capabilities.
A Device is essentially an Erlang module (typically named `dev_*.erl`) that processes AO-Core messages.

**Steps:**

1.  **Define Purpose:** Clearly define what your device will do. What kind of messages will it process? What state will it manage (if any)? What functions (keys) will it expose?
2.  **Create Module:** Create a new Erlang module (e.g., `src/dev_my_new_device.erl`).
3.  **Implement `info/0..2` (Optional but Recommended):** Define an `info` function to signal capabilities and requirements to HyperBEAM (e.g., exported keys, variant/version ID).
    ```erlang
    info() ->
        #{
          variant => <<"MyNewDevice/1.0">>,
          exports => [<<"do_something">>, <<"get_status">>]
        }.
    ```
4.  **Implement Key Functions:** Create Erlang functions corresponding to the keys your device exposes. These functions typically take `StateMessage`, `InputMessage`, and `Environment` as arguments and return `{ok, NewMessage}` or `{error, Reason}`.
    ```erlang
    do_something(StateMsg, InputMsg, Env) ->
        % ... perform action based on InputMsg ...
        NewState = ..., % Calculate new state
        {ok, NewState}.

    get_status(StateMsg, _InputMsg, _Env) ->
        % ... read status from StateMsg ...
        StatusData = ..., 
        {ok, StatusData}.
    ```
5.  **Handle State (If Applicable):** Devices can be stateless or stateful. Stateful devices manage their state within the `StateMessage` passed between function calls.
6.  **Register Device:** Ensure HyperBEAM knows about your device. This might involve adding it to build configurations or potentially a dynamic registration mechanism if available.
7.  **Testing:** Write EUnit tests for your device's functions.

**Example Idea:** A device that bridges to another blockchain network, allowing AO processes to read data or trigger transactions on that chain.

## Approach 2: Building Pre/Post-Processors

Pre/post-processors allow you to intercept incoming requests *before* they reach the target device/process (`preprocess`) or modify the response *after* execution (`postprocess`). These are often implemented using the `dev_stack` device or specific hooks within the request handling pipeline.

**Use Cases:**

*   **Authentication/Authorization:** Checking signatures or permissions before allowing execution.
*   **Request Modification:** Rewriting requests, adding metadata, or routing based on specific criteria.
*   **Response Formatting:** Changing the structure or content type of the response.
*   **Metering/Logging:** Recording request details or charging for usage before or after execution.

**Implementation:**

Processors often involve checking specific conditions (like request path or headers) and then either:

a.  Passing the request through unchanged.
b.  Modifying the request/response message structure.
c.  Returning an error or redirect.
<!-- d. The guide on [Building Pre/Post-Processors](TODO:link-to-pre-post-processor-guide-once-available) provides a detailed example pattern, particularly focusing on exempting certain routes. -->

**Example Idea:** A preprocessor that automatically adds a timestamp tag to all incoming messages for a specific process.
<!-- 
## Approach 3: Modifying Existing Devices (Use with Caution)

You could directly modify the source code of existing `dev_*.erl` modules. However, this is generally discouraged as it makes future updates harder and can break compatibility. -->

## Approach 3: Custom Routing Strategies

While `dev_router` provides basic strategies (round-robin, etc.), you could potentially implement a custom load balancing or routing strategy module that `dev_router` could be configured to use. This would involve understanding the interfaces expected by `dev_router`.

**Example Idea:** A routing strategy that queries worker nodes for their specific capabilities before forwarding a request.

## Getting Started

1.  **Familiarize Yourself:** Deeply understand Erlang/OTP and the HyperBEAM codebase (`src/` directory), especially [`hb_ao.erl`](../resources/source-code/hb_ao.md), [`hb_message.erl`](../resources/source-code/hb_message.md), and existing `dev_*.erl` modules relevant to your idea.
2.  **Study Examples:** Look at simple devices like `dev_patch.erl` or more complex ones like `dev_process.erl` to understand patterns.
3.  **Start Small:** Implement a minimal version of your idea first.
4.  **Test Rigorously:** Use `rebar3 eunit` extensively.
5.  **Engage Community:** Ask questions in developer channels if you get stuck.

Extending HyperBEAM allows you to tailor the AO network's capabilities to specific needs, contributing to its rich and evolving ecosystem.

--- END OF FILE: docs/build/extending-hyperbeam.md ---

--- START OF FILE: docs/build/migrating-from-legacynet.md ---
# Migrating from `legacynet` to HyperBEAM

HyperBEAM represents a significant evolution from the original `legacynet`, offering a more robust, performant, and feature-rich environment for running AO processes. If you have processes currently running on `legacynet`, migrating them to HyperBEAM is a crucial step to leverage these advancements.

## Why Migrate to HyperBEAM?

HyperBEAM is not just an update; it's a new foundation designed for building high-performance decentralized applications. Key benefits include:

*   **Enhanced Performance:** Built on Erlang/OTP, HyperBEAM's architecture is optimized for concurrency and fault tolerance, resulting in faster scheduling and more responsive applications.
*   **Powerful Developer Tools:** HyperBEAM exposes all of it's state through HTTP, you can use any standard HTTP library to interact with it. 
*   **Easy Extensibility:** It allows core feature extensibility through [modular devices](../introduction/hyperbeam-devices.md).

The process of migration involves updating your process to take advantage of the new features available in HyperBEAM. One of the most impactful new features is the ability to directly expose parts of your process state for immediate reading via HTTP, which dramatically improves the performance of web frontends and data-driven services.

## Exposing Process State with the Patch Device

The [`~patch@1.0`](../resources/source-code/dev_patch.md) device provides a mechanism for AO processes to expose parts of their internal state, making it readable via direct HTTP GET requests along the process's HyperPATH.

### Why Use the Patch Device?

Standard AO process execution typically involves sending a message to a process, letting it compute, and then potentially reading results from its outbox or state after the computation is scheduled and finished. This is asynchronous.

The `patch` device allows for a more direct, synchronous-like read pattern. A process can use it to "patch" specific data elements from its internal state into a location that becomes directly accessible via a HyperPATH GET request *before* the full asynchronous scheduling might complete.

This is particularly useful for:

*   **Web Interfaces:** Building frontends that need to quickly read specific data points from an AO process without waiting for a full message round-trip.
*   **Data Feeds:** Exposing specific metrics or state variables for monitoring or integration with other systems.
*   **Caching:** Allowing frequently accessed data to be retrieved efficiently via simple HTTP GETs.

### How it Works

1.  **Process Logic:** Inside your AO process code (e.g., in Lua or WASM), when you want to expose data, you construct an *outbound message* targeted at the [`~patch@1.0`](../resources/source-code/dev_patch.md) device.
2.  **Patch Message Format:** This outbound message typically includes tags that specify:
    *   `device = 'patch@1.0'`
    *   A `cache` tag containing a table. The **keys** within this table become the final segments in the HyperPATH used to access the data, and the **values** are the data itself.
    *   Example Lua using `aos`: `Send({ Target = ao.id, device = 'patch@1.0', cache = { mydatakey = MyValue } })`
3.  **HyperBEAM Execution:** When HyperBEAM executes the process schedule and encounters this outbound message:
    *   It invokes the `dev_patch` module.
    *   `dev_patch` inspects the message.
    *   It takes the keys from the `cache` table (`mydatakey` in the example) and their associated values (`MyValue`) and makes these values available under the `/cache/` path segment.
4.  **HTTP Access:** You (or any HTTP client) can now access this data directly using a GET request:
    ```
    GET /<process-id>~process@1.0/compute/cache/<mydatakey>
    # Or potentially using /now/
    GET /<process-id>~process@1.0/now/cache/<mydatakey>
    ```
    The HyperBEAM node serving the request will resolve the path up to `/compute/cache` (or `/now/cache`), then use the logic associated with the patched data (`mydatakey`) to return the `MyValue` directly.

### Initial State Sync (Optional)

It can be beneficial to expose the initial state of your process via the `patch` device as soon as the process is loaded or spawned. This makes key data points immediately accessible via HTTP GET requests without requiring an initial interaction message to trigger a `Send` to the patch device.

This pattern typically involves checking a flag within your process state to ensure the initial sync only happens once. Here's an example from the Token Blueprint, demonstrating how to sync `Balances` and `TotalSupply` right after the process starts:

```lua
-- Place this logic at the top level of your process script, 
-- outside of specific handlers, so it runs on load.

-- Initialize the sync flag if it doesn't exist
InitialSync = InitialSync or 'INCOMPLETE'

-- Sync state on spawn/load if not already done
if InitialSync == 'INCOMPLETE' then
  -- Send the relevant state variables to the patch device
  Send({ device = 'patch@1.0', cache = { balances = Balances, totalsupply = TotalSupply } })
  -- Update the flag to prevent re-syncing on subsequent executions
  InitialSync = 'COMPLETE'
  print("Initial state sync complete. Balances and TotalSupply patched.")
end
```

**Explanation:**

1.  `InitialSync = InitialSync or 'INCOMPLETE'`: This line ensures the `InitialSync` variable exists in the process state, initializing it to `'INCOMPLETE'` if it's the first time the code runs.
2.  `if InitialSync == 'INCOMPLETE' then`: The code proceeds only if the initial sync hasn't been marked as complete.
3.  `Send(...)`: The relevant state (`Balances`, `TotalSupply`) is sent to the `patch` device, making it available under `/cache/balances` and `/cache/totalsupply`.
4.  `InitialSync = 'COMPLETE'`: The flag is updated, so this block won't execute again in future message handlers within the same process lifecycle.

This ensures that clients or frontends can immediately query essential data like token balances as soon as the process ID is known, improving the responsiveness of applications built on AO.

### Example (Lua in `aos`)

```lua
-- In your process code (e.g., loaded via .load)
Handlers.add(
  "PublishData",
  Handlers.utils.hasMatchingTag("Action", "PublishData"),
  function (msg)
    local dataToPublish = "Some important state: " .. math.random()
    -- Expose 'currentstatus' key under the 'cache' path
    Send({ device = 'patch@1.0', cache = { currentstatus = dataToPublish } })
    print("Published data to /cache/currentstatus")
  end
)
```

```bash
-- Spawning and interacting
default@aos-2.0.6> MyProcess = spawn(MyModule)

default@aos-2.0.6> Send({ Target = MyProcess, Action = "PublishData" })
-- Wait a moment for scheduling
```

### Avoiding Key Conflicts

When defining keys within the `cache` table (e.g., `cache = { mydatakey = MyValue }`), these keys become path segments under `/cache/` (e.g., `/compute/cache/mydatakey` or `/now/cache/mydatakey`). It's important to choose keys that do not conflict with existing, reserved path segments used by HyperBEAM or the `~process` device itself for state access.

Using reserved keywords as your cache keys can lead to routing conflicts or prevent you from accessing your patched data as expected. While the exact list can depend on device implementations, it's wise to avoid keys commonly associated with state access, such as: `now`, `compute`, `state`, `info`, `test`.

It's recommended to use descriptive and specific keys for your cached data to prevent clashes with the underlying HyperPATH routing mechanisms. For example, instead of `cache = { state = ... }`, prefer `cache = { myappstate = ... }` or `cache = { usercount = ... }`.

!!! warning
    Be aware that HTTP path resolution is case-insensitive and automatically normalizes paths to lowercase. While the `patch` device itself stores keys with case sensitivity (e.g., distinguishing `MyKey` from `mykey`), accessing them via an HTTP GET request will treat `/cache/MyKey` and `/cache/mykey` as the same path. This means that using keys that only differ in case (like `MyKey` and `mykey` in your `cache` table) will result in unpredictable behavior or data overwrites when accessed via HyperPATH. To prevent these issues, it is **strongly recommended** to use **consistently lowercase keys** within the `cache` table (e.g., `mykey`, `usercount`, `appstate`).

## Key Points

*   **Path Structure:** The data is exposed under the `/cache/` path segment. The tag name you use *inside* the `cache` table in the `Send` call (e.g., `currentstatus`) becomes the final segment in the accessible HyperPATH (e.g., `/compute/cache/currentstatus`).
*   **Data Types:** The `patch` device typically handles basic data types (strings, numbers) within the `cache` table effectively. Complex nested tables might require specific encoding or handling.
*   **`compute` vs `now`:** Accessing patched data via `/compute/cache/...` typically serves the last known patched value quickly. Accessing via `/now/cache/...` might involve more computation to ensure the absolute latest state before checking for the patched key under `/cache/`.
*   **Not a Replacement for State:** Patching is primarily for *exposing* reads. It doesn't replace the core state management within your process handler logic.

By using the `patch` device, you can make parts of your AO process state easily and efficiently readable over standard HTTP, bridging the gap between decentralized computation and web-based applications.
--- END OF FILE: docs/build/migrating-from-legacynet.md ---

--- START OF FILE: docs/build/quick-start.md ---
# Quick Start with HyperBEAM

Welcome to building on HyperBEAM, the decentralized operating system built on AO.

HyperBEAM leverages the permanent storage of Arweave with the flexible, scalable computation enabled by the AO-Core protocol and its HyperBEAM implementation. This allows you to create truly autonomous applications, agents, and services that run trustlessly and permissionlessly.

<!-- ## Why build on HyperBEAM?

Current cloud providers offer centralized compute, which means you have to trust them with your data and your money.  HyperBEAM flips the script and gives you severless decentralized compute where you own your data and you pay for only what you need.  -->

## Thinking in HyperBEAM

Your serverless function can be a simple Lua script, or it can be a more complex WASM module. It will be deployed as a process on HyperBEAM whose state is stored on Arweave and is cached on HyperBEAM nodes. This gives you both benefits: permanence and speed.
    
At its heart, building on HyperBEAM involves:

1.  **Processes:** Think of these as independent programs or stateful contracts. Each process has a unique ID and maintains its own state.
2.  **Messages:** You interact with processes by sending them messages. These messages trigger computations, update state, or cause the process to interact with other processes or the outside world.

Messages are processed by [Devices](../introduction/ao-devices.md), which define *how* the computation happens (e.g., running WASM code, executing Lua scripts, managing state transitions).

## Starting `aos`: Your Development Environment

The primary tool for interacting with AO and developing processes is `aos`, a command-line interface and development environment.

=== "npm"
    ```bash
    npm i -g https://get_ao.arweave.net
    ```

=== "bun"
    ```bash
    bun install -g https://get_ao.arweave.net
    ```

=== "pnpm"
    ```bash
    pnpm add -g https://get_ao.arweave.net
    ```

While you don't need to run a HyperBEAM node yourself, you do need to connect to one to interact with the network during development.

To start `aos`, simply run the command in your terminal:

```bash
aos --mainnet "https://dev-router.forward.computer" myMainnetProcess
```

This connects you to an interactive Lua environment running within a **process** on the AO network. This process acts as your command-line interface (CLI) to the AO network, allowing you to interact with other processes, manage your wallet, and develop new AO processes. When you specify `--mainnet <URL>`, it connects to the `genesis_wasm` device running on the HyperBEAM node at the supplied URL.

!!! note
    **What `aos` is doing:**

    *   **Connecting:** Establishes a connection from your terminal to a remote process running the `aos` environment.
    *   **Loading Wallet:** Looks for a default Arweave key file (usually `~/.aos.json` or specified via arguments) to load into the remote process context for signing outgoing messages.
    *   **Providing Interface:** Gives you a Lua prompt (`default@aos-2.0.6>`) within the remote process where you can:
        *   Load code for new persistent processes on the network.
        *   Send messages to existing network processes.
        *   Inspect process state.
        *   Manage your local environment.

## Initializing a Variable

From the `aos` prompt, you can assign a variable. Let's assign a basic Lua process that just holds some data:

```lua
default@aos-2.0.6> myVariable = "Hello from aos!"
```

This assigns the string "Hello from aos!" to the variable `myVariable` within the current process's Lua environment.

```lua
default@aos-2.0.6> myVariable
Hello from aos!
```

This displays the content of `myVariable`.

## Sending Your First Message

Let's send our variable to another process.

```lua
default@aos-2.0.6> Send({ Target = ao.id, Data = myVariable })
```

You should see the following output:

```lua
New Message From <your-process-id>: Data = Hello from aos!
```

## Creating Your First Handler

Handlers are decentralized functions that can be triggered by messages.

Follow these steps to create and interact with your first message handler in AO:

1.  **Create a Lua File to Handle Messages:**
    Create a new file named `main.lua` in your local directory and add the following Lua code:

    ```lua
    Handlers.add(
      "HelloWorld",
      function(msg)
        print("Handler triggered by message from: " .. msg.From)
        msg.reply({ Data = "Hello back from your process!" })
      end
    )

    print("HelloWorld handler loaded.")
    ```

    *   `
--- END OF FILE: docs/build/quick-start.md ---

--- START OF FILE: docs/build/serverless-decentralized-compute.md ---
# Serverless Decentralized Compute on AO

AO enables powerful "serverless" computation patterns by allowing you to run code (WASM, Lua) directly within decentralized processes, triggered by messages. Furthermore, if computations are performed on nodes running in Trusted Execution Environments (TEEs), you can obtain cryptographic attestations verifying the execution integrity.

## Core Concept: Compute Inside Processes

Instead of deploying code to centralized servers, you deploy code *to* the Arweave permaweb and instantiate it as an AO process. Interactions happen by sending messages to this process ID.

*   **Code Deployment:** Your WASM binary or Lua script is uploaded to Arweave, getting a permanent transaction ID.
*   **Process Spawning:** You create an AO process, associating it with your code's transaction ID and specifying the appropriate compute device ([`~wasm64@1.0`](../devices/wasm64-at-1-0.md) or [`~lua@5.3a`](../devices/lua-at-5-3a.md)).
*   **Execution via Messages:** Sending a message to the process ID triggers the HyperBEAM node (that picks up the message) to:
    1.  Load the process state.
    2.  Fetch the associated WASM/Lua code from Arweave.
    3.  Execute the code using the relevant device ([`dev_wasm`](../resources/source-code/dev_wasm.md) or [`dev_lua`](../resources/source-code/dev_lua.md)), passing the message data and current state.
    4.  Update the process state based on the execution results.
<!-- 
## Example 1: Running WASM Containers

WebAssembly (WASM) allows you to run precompiled code written in languages like Rust, C++, Go, or AssemblyScript within your AO process.

1.  **Compile:** Compile your code (e.g., Rust) to a WASM target.
2.  **Upload:** Upload the `.wasm` file to Arweave to get a `<WasmCodeTxID>`.
3.  **Spawn Process (using `aos`):**
    ```lua
    default@aos-2.0.6> Send({ Target = "AOS", Action = "Spawn", Module = "<WasmCodeTxID>", Scheduler = "<OptionalSchedulerProcessID>" })
    -- This returns a <ProcessID>
    ```
    *(Note: The exact spawning mechanism might vary; consult `aos` or relevant SDK documentation. You specify that this process uses WASM.)*
4.  **Send Message to Trigger Execution:**
    ```lua
    default@aos-2.0.6> Send({ Target = "<ProcessID>", Action = "ExecuteFunction", InputData = "Some data for WASM" })
    ```
    The HyperBEAM node executing this will load the WASM module identified by `<WasmCodeTxID>`, run its handler function (triggered by `Action = "ExecuteFunction"`) with `"Some data for WASM"` as input, and update the state of `<ProcessID>`.

## Example 2: Running Lua Scripts

Lua provides a lightweight scripting environment directly within AO.

1.  **Write Script:** Create your `my_script.lua` file.
    ```lua
    -- my_script.lua
    Handlers.add(
      "Calculate",
      Handlers.utils.hasMatchingTag("Action", "Calculate"),
      function (msg)
        local input = tonumber(msg.Tags.Value) or 0
        local result = input * input
        -- Update state or send messages back
        ao.send({ Target = msg.From, Data = "Result: " .. result })
        print("Calculated square of " .. input .. ": " .. result)
      end
    )
    ```
2.  **Load & Spawn (using `aos`):**
    ```lua
    default@aos-2.0.6> .load my_script.lua
    default@aos-2.0.6> MyLuaProcess = spawn(MyModule)
    ```
3.  **Send Message:**
    ```lua
    default@aos-2.0.6> Send({ Target = MyLuaProcess, Action = "Calculate", Value = "7" })
    ```
    The node executes the `Calculate` handler within the Lua script associated with `MyLuaProcess`. -->

## TEE Attestations (via [`~snp@1.0`](../resources/source-code/dev_snp.md))

If a HyperBEAM node performing these computations runs within a supported Trusted Execution Environment (like AMD SEV-SNP), it can provide cryptographic proof of execution.

*   **How it works:** The [`~snp@1.0`](../resources/source-code/dev_snp.md) device interacts with the TEE hardware.
*   **Signed Responses:** When a TEE-enabled node processes your message (e.g., executes your WASM function), the HTTP response containing the result can be cryptographically signed by a key that *provably* only exists inside the TEE.
*   **Verification:** Clients receiving this response can verify the signature against the TEE platform's attestation mechanism (e.g., AMD's KDS) to gain high confidence that the computation was performed correctly and confidentially within the secure environment, untampered by the node operator.

**Obtaining Attested Responses:**

This usually involves interacting with nodes specifically advertised as TEE-enabled. The exact mechanism for requesting and verifying attestations depends on the specific TEE technology and node configuration.

*   The HTTP response headers might contain specific signature or attestation data (e.g., using HTTP Message Signatures RFC-9421 via [`dev_codec_httpsig`](../resources/source-code/dev_codec_httpsig.md)).
*   You might query the [`~snp@1.0`](../resources/source-code/dev_snp.md) device directly on the node to get its attestation report.

Refer to documentation on [TEE Nodes](../run/tee-nodes.md) and the [`~snp@1.0`](../resources/source-code/dev_snp.md) device for details.

By leveraging WASM, Lua, and optional TEE attestations, AO provides a powerful platform for building complex, verifiable, and truly decentralized serverless applications.

--- END OF FILE: docs/build/serverless-decentralized-compute.md ---

--- START OF FILE: docs/devices/json-at-1-0.md ---
# Device: ~json@1.0

## Overview

The [`~json@1.0`](../resources/source-code/dev_json_iface.md) device provides a mechanism to interact with JSON (JavaScript Object Notation) data structures using HyperPATHs. It allows treating a JSON document or string as a stateful entity against which HyperPATH queries can be executed.

This device is useful for:

*   Serializing and deserializing JSON data.
*   Querying and modifying JSON objects.
*   Integrating with other devices and operations via HyperPATH chaining.

## Core Functions (Keys)

### Serialization

*   **`GET /~json@1.0/serialize` (Direct Serialize Action)**
    *   **Action:** Serializes the input message or data into a JSON string.
    *   **Example:** `GET /~json@1.0/serialize` - serializes the current message as JSON.
    *   **HyperPATH:** The path segment `/serialize` directly follows the device identifier.

*   **`GET /<PreviousPath>/~json@1.0/serialize` (Chained Serialize Action)**
    *   **Action:** Takes arbitrary data output from `<PreviousPath>` (another device or operation) and returns its serialized JSON string representation.
    *   **Example:** `GET /~meta@1.0/info/~json@1.0/serialize` - fetches node info from the meta device and then pipes it to the JSON device to serialize the result as JSON.
    *   **HyperPATH:** This segment (`/~json@1.0/serialize`) is appended to a previous HyperPATH segment.

## HyperPATH Chaining Example

The JSON device is particularly useful in HyperPATH chains to convert output from other devices into JSON format:

```
GET /~meta@1.0/info/~json@1.0/serialize
```

This retrieves the node configuration from the meta device and serializes it to JSON.

## See Also

- [Message Device](../resources/source-code/dev_message.md) - Works well with JSON serialization
- [Meta Device](../resources/source-code/dev_meta.md) - Can provide configuration data to serialize

[json module](../resources/source-code/dev_codec_json.md)
--- END OF FILE: docs/devices/json-at-1-0.md ---

--- START OF FILE: docs/devices/lua-at-5-3a.md ---
# Device: ~lua@5.3a

## Overview

The [`~lua@5.3a`](../resources/source-code/dev_lua.md) device enables the execution of Lua scripts within the HyperBEAM environment. It provides an isolated sandbox where Lua code can process incoming messages, interact with other devices, and manage state.

## Core Concept: Lua Script Execution

This device allows processes to perform computations defined in Lua scripts. Similar to the [`~wasm64@1.0`](../resources/source-code/dev_wasm.md) device, it manages the lifecycle of a Lua execution state associated with the process.

## Key Functions (Keys)

These keys are typically used within an execution stack (managed by [`dev_stack`](../resources/source-code/dev_stack.md)) for an AO process.

*   **`init`**
    *   **Action:** Initializes the Lua environment for the process. It finds and loads the Lua script(s) associated with the process, creates a `luerl` state, applies sandboxing rules if specified, installs the [`dev_lua_lib`](../resources/source-code/dev_lua_lib.md) (providing AO-specific functions like `ao.send`), and stores the initialized state in the process's private area (`priv/state`).
    *   **Inputs (Expected in Process Definition or `init` Message):**
        *   `script`: Can be:
            *   An Arweave Transaction ID of the Lua script file.
            *   A list of script IDs or script message maps.
            *   A message map containing the Lua script in its `body` tag (Content-Type `application/lua` or `text/x-lua`).
            *   A map where keys are module names and values are script IDs/messages.
        *   `sandbox`: (Optional) Controls Lua sandboxing. Can be `true` (uses default sandbox list), `false` (no sandbox), or a map/list specifying functions to disable and their return values.
    *   **Outputs (Stored in `priv/`):**
        *   `state`: The initialized `luerl` state handle.
*   **`<FunctionName>` (Default Handler - `compute`)**
    *   **Action:** Executes a specific function within the loaded Lua script(s). This is the default handler; if a key matching a Lua function name is called on the device, this logic runs.
    *   **Inputs (Expected in Process State or Incoming Message):**
        *   `priv/state`: The Lua state obtained during `init`.
        *   The **key** being accessed (used as the default function name).
        *   `function` or `body/function`: (Optional) Overrides the function name derived from the key.
        *   `parameters` or `body/parameters`: (Optional) Arguments to pass to the Lua function. Defaults to a list containing the process message, the request message, and an empty options map.
    *   **Response:** The results returned by the Lua function call, typically encoded. The device also updates the `priv/state` with the Lua state after execution.
*   **`snapshot`**
    *   **Action:** Captures the current state of the running Lua environment. `luerl` state is serializable.
    *   **Inputs:** `priv/state`.
    *   **Outputs:** A message containing the serialized Lua state, typically tagged with `[Prefix]/State`.
*   **`normalize` (Internal Helper)**
    *   **Action:** Ensures a consistent state representation by loading a Lua state from a snapshot (`[Prefix]/State`) if a live state (`priv/state`) isn't already present.
*   **`functions`**
    *   **Action:** Returns a list of all globally defined functions within the current Lua state.
    *   **Inputs:** `priv/state`.
    *   **Response:** A list of function names.

## Sandboxing

The `sandbox` option in the process definition restricts potentially harmful Lua functions (like file I/O, OS commands, loading arbitrary code). By default (`sandbox = true`), common dangerous functions are disabled. You can customize the sandbox rules.

## AO Library (`dev_lua_lib`)

The `init` function automatically installs a helper library ([`dev_lua_lib`](../resources/source-code/dev_lua_lib.md)) into the Lua state. This library typically provides functions for interacting with the AO environment from within the Lua script, such as:

*   `ao.send({ Target = ..., ... })`: To send messages from the process.
*   Access to message tags and data.

## Usage within `dev_stack`

Like [`~wasm64@1.0`](../resources/source-code/dev_wasm.md), the `~lua@5.3a` device is typically used within an execution stack.

```text
# Example Process Definition Snippet
Execution-Device: stack@1.0
Execution-Stack: scheduler@1.0, lua@5.3a
Script: <LuaScriptTxID>
Sandbox: true
```

This device offers a lightweight, integrated scripting capability for AO processes, suitable for a wide range of tasks from simple logic to more complex state management and interactions.

[lua module](../resources/source-code/dev_lua.md)

--- END OF FILE: docs/devices/lua-at-5-3a.md ---

--- START OF FILE: docs/devices/message-at-1-0.md ---
# Device: ~message@1.0

## Overview

The [`~message@1.0`](../resources/source-code/dev_message.md) device is a fundamental built-in device in HyperBEAM. It serves as the identity device for standard AO-Core messages, which are represented as Erlang maps internally. Its primary function is to allow manipulation and inspection of these message maps directly via HyperPATH requests, without needing a persistent process state.

This device is particularly useful for:

*   Creating and modifying transient messages on the fly using query parameters.
*   Retrieving specific values from a message map.
*   Inspecting the keys of a message.
*   Handling message commitments and verification (though often delegated to specialized commitment devices like [`httpsig@1.0`](../resources/source-code/dev_codec_httpsig.md)).

## Core Functionality

The `message@1.0` device treats the message itself as the state it operates on. Key operations are accessed via path segments in the HyperPATH.

### Key Access (`/key`)

To retrieve the value associated with a specific key in the message map, simply append the key name to the path. Key lookup is case-insensitive.

**Example:**

```
GET /~message@1.0&hello=world&Key=Value/key
```

**Response:**

```
"Value"
```

### Reserved Keys

The `message@1.0` device reserves several keys for specific operations:

*   **`get`**: (Default operation if path segment matches a key in the map) Retrieves the value of a specified key. Behaves identically to accessing `/key` directly.
*   **`set`**: Modifies the message by adding or updating key-value pairs. Requires additional parameters (usually in the request body or subsequent path segments/query params, depending on implementation specifics).
    *   Supports deep merging of maps.
    *   Setting a key to `unset` removes it.
    *   Overwriting keys that are part of existing commitments will typically remove those commitments unless the new value matches the old one.
*   **`set_path`**: A special case for setting the `path` key itself, which cannot be done via the standard `set` operation.
*   **`remove`**: Removes one or more specified keys from the message. Requires an `item` or `items` parameter.
*   **`keys`**: Returns a list of all public (non-private) keys present in the message map.
*   **`id`**: Calculates and returns the ID (hash) of the message. Considers active commitments based on specified `committers`. May delegate ID calculation to a device specified by the message's `id-device` key
*   **`commit`**: Creates a commitment (e.g., a signature) for the message. Requires parameters like `commitment-device` and potentially committer information. Delegates the actual commitment generation to the specified device (default [`httpsig@1.0`](../resources/source-code/dev_codec_httpsig.md)).
*   **`committers`**: Returns a list of committers associated with the commitments in the message. Can be filtered by request parameters.
*   **`commitments`**: Used internally and in requests to filter or specify which commitments to operate on (e.g., for `id` or `verify`).
*   **`verify`**: Verifies the commitments attached to the message. Can be filtered by `committers` or specific `commitment` IDs in the request. Delegates verification to the device specified in each commitment (`commitment-device`).

### Private Keys

Keys prefixed with `priv` (e.g., `priv_key`, `private.data`) are considered private and cannot be accessed or listed via standard `get` or `keys` operations.

## HyperPATH Example

This example demonstrates creating a transient message and retrieving a value:

```
GET /~message@1.0&hello=world&k=v/k
```

**Breakdown:**

1.  `~message@1.0`: Sets the root device.
2.  `&hello=world&k=v`: Query parameters create the initial message: `#{ <<"hello">> => <<"world">>, <<"k">> => <<"v">> }`.
3.  `/k`: The path segment requests the value for the key `k`.

**Response:**

```
"v"
``` 
--- END OF FILE: docs/devices/message-at-1-0.md ---

--- START OF FILE: docs/devices/meta-at-1-0.md ---
# Device: ~meta@1.0

## Overview

The [`~meta@1.0`](../resources/source-code/dev_meta.md) device provides access to metadata and configuration information about the local HyperBEAM node and the broader AO network.

This device is essential for:

## Core Functions (Keys)

### `info`

Retrieves or modifies the node's configuration message (often referred to as `NodeMsg` internally).

*   **`GET /~meta@1.0/info`**
    *   **Action:** Returns the current node configuration message.
    *   **Response:** A message map containing the node's settings. Sensitive keys (like private wallets) are filtered out. Dynamically generated keys like the node's public `address` are added if a wallet is configured.
*   **`POST /~meta@1.0/info`**
    *   **Action:** Updates the node's configuration message. Requires the request to be signed by the node's configured `operator` key/address.
    *   **Request Body:** A message map containing the configuration keys and values to update.
    *   **Response:** Confirmation message indicating success or failure.
    *   **Note:** Once a node's configuration is marked as `initialized = permanent`, it cannot be changed via this method.

## Key Configuration Parameters Managed by `~meta`

While the `info` key is the primary interaction point, the `NodeMsg` managed by `~meta` holds crucial configuration parameters affecting the entire node's behavior, including (but not limited to):

*   `port`: HTTP server port.
*   `priv_wallet` / `key_location`: Path to the node's Arweave key file.
*   `operator`: The address designated as the node operator (defaults to the address derived from `priv_wallet`).
*   `initialized`: Status indicating if the node setup is temporary or permanent.
*   `preprocessor` / `postprocessor`: Optional messages defining pre/post-processing logic for requests.
*   `routes`: Routing table used by [`dev_router`](../resources/source-code/dev_router.md).
*   `store`: Configuration for data storage.
*   `trace`: Debug tracing options.
*   `p4_*`: Payment configuration.
*   `faff_*`: Access control lists.

*(Refer to `hb_opts.erl` for a comprehensive list of options.)*

## Utility Functions (Internal/Module Level)

The [`dev_meta.erl`](../resources/source-code/dev_meta.md) module also contains helper functions used internally or callable from other Erlang modules:

*   `is_operator(<RequestMsg>, <NodeMsg>) -> boolean()`: Checks if the signer of `RequestMsg` matches the configured `operator` in `NodeMsg`.

## Pre/Post-Processing Hooks

The `~meta` device applies the node's configured `preprocessor` message before resolving the main request and the `postprocessor` message after obtaining the result, allowing for global interception and modification of requests/responses.

## Initialization

Before a node can process general requests, it usually needs to be initialized. Attempts to access devices other than `~meta@1.0/info` before initialization typically result in an error. Initialization often involves setting essential parameters like the operator key via a `POST` to `info`.

[meta module](../resources/source-code/dev_meta.md)
--- END OF FILE: docs/devices/meta-at-1-0.md ---

--- START OF FILE: docs/devices/process-at-1-0.md ---
# Device: ~process@1.0

## Overview

The [`~process@1.0`](../resources/source-code/dev_process.md) device represents a persistent, shared execution environment within HyperBEAM, analogous to a process or actor in other systems. It allows for stateful computation and interaction over time.

## Core Concept: Orchestration

A message tagged with `Device: process@1.0` (the "Process Definition Message") doesn't typically perform computation itself. Instead, it defines *which other devices* should be used for key aspects of its lifecycle:

*   **Scheduler Device:** Determines the order of incoming messages (assignments) to be processed. (Defaults to [`~scheduler@1.0`](../resources/source-code/dev_scheduler.md)).
*   **Execution Device:** Executes the actual computation based on the current state and the scheduled message. Often configured as [`dev_stack`](../resources/source-code/dev_stack.md) to allow multiple computational steps (e.g., running WASM, applying cron jobs, handling proofs).
*   **Push Device:** Handles the injection of new messages into the process's schedule. (Defaults to [`~push@1.0`](../resources/source-code/dev_push.md)).

The `~process@1.0` device acts as a router, intercepting requests and delegating them to the appropriate configured device (scheduler, executor, etc.) by temporarily swapping the device tag on the message before resolving.

## Key Functions (Keys)

These keys are accessed via HyperPATHs relative to the Process Definition Message ID (`<ProcessID>`).

*   **`GET /<ProcessID>~process@1.0/schedule`**
    *   **Action:** Delegates to the configured Scheduler Device (via the process's `schedule/3` function) to retrieve the current schedule or state.
    *   **Response:** Depends on the Scheduler Device implementation (e.g., list of message IDs).
*   **`POST /<ProcessID>~process@1.0/schedule`**
    *   **Action:** Delegates to the configured Push Device (via the process's `push/3` function) to add a new message to the process's schedule.
    *   **Request Body:** The message to be added.
    *   **Response:** Confirmation or result from the Push Device.
*   **`GET /<ProcessID>~process@1.0/compute/<TargetSlotOrMsgID>`**
    *   **Action:** Computes the process state up to a specific point identified by `<TargetSlotOrMsgID>` (either a slot number or a message ID within the schedule). It retrieves assignments from the Scheduler Device and applies them sequentially using the configured Execution Device.
    *   **Response:** The process state message after executing up to the target slot/message.
    *   **Caching:** Results are cached aggressively (see [`dev_process_cache`](../resources/source-code/dev_process_cache.md)) to avoid recomputation.
*   **`GET /<ProcessID>~process@1.0/now`**
    *   **Action:** Computes and returns the `Results` key from the *latest* known state of the process. This typically involves computing all pending assignments.
    *   **Response:** The value of the `Results` key from the final state.
*   **`GET /<ProcessID>~process@1.0/slot`**
    *   **Action:** Delegates to the configured Scheduler Device to query information about a specific slot or the current slot number.
    *   **Response:** Depends on the Scheduler Device implementation.
*   **`GET /<ProcessID>~process@1.0/snapshot`**
    *   **Action:** Delegates to the configured Execution Device to generate a snapshot of the current process state. This often involves running the execution stack in a specific "map" mode to gather state from different components.
    *   **Response:** A message representing the process snapshot, often marked for caching.

## Process Definition Example

A typical process definition message might look like this (represented conceptually):

```text
Device: process@1.0
Scheduler-Device: [`scheduler@1.0`](../resources/source-code/dev_scheduler.md)
Execution-Device: [`stack@1.0`](../resources/source-code/dev_stack.md)
Execution-Stack: "[`scheduler@1.0`](../resources/source-code/dev_scheduler.md)", "[`cron@1.0`](../resources/source-code/dev_cron.md)", "[`wasm64@1.0`](../resources/source-code/dev_wasm.md)", "[`PoDA@1.0`](../resources/source-code/dev_poda.md)"
Cron-Frequency: 10-Minutes
WASM-Image: <WASMImageTxID>
PoDA:
    Device: [`PoDA/1.0`](../resources/source-code/dev_poda.md)
    Authority: <AddressA>
    Authority: <AddressB>
    Quorum: 2
```

This defines a process that uses:
*   The standard scheduler.
*   A stack executor that runs scheduling logic, cron jobs, a WASM module, and a Proof-of-Data-Availability check.

## State Management & Caching

`~process@1.0` relies heavily on caching ([`dev_process_cache`](../resources/source-code/dev_process_cache.md)) to optimize performance. Full state snapshots and intermediate results are cached periodically (configurable via `Cache-Frequency` and `Cache-Keys` options) to avoid recomputing the entire history for every request.

## Initialization (`init`)

Processes often require an initialization step before they can process messages. This is typically triggered by calling the `init` key on the configured Execution Device via the process path (`/<ProcessID>~process@1.0/init`). This allows components within the execution stack (like WASM modules) to set up their initial state.

[process module](../resources/source-code/dev_process.md)

--- END OF FILE: docs/devices/process-at-1-0.md ---

--- START OF FILE: docs/devices/relay-at-1-0.md ---
# Device: ~relay@1.0

## Overview

The [`~relay@1.0`](../resources/source-code/dev_relay.md) device enables HyperBEAM nodes to send messages to external HTTP endpoints or other AO nodes.

## Core Concept: Message Forwarding

This device acts as an HTTP client within the AO ecosystem. It allows a node or process to make outbound HTTP requests.

## Key Functions (Keys)

*   **`call`**
    *   **Action:** Sends an HTTP request to a specified target and waits synchronously for the response.
    *   **Inputs (from Request Message or Base Message M1):**
        *   `target`: (Optional) A message map defining the request to be sent. Defaults to the original incoming request (`Msg2` or `M1`).
        *   `relay-path` or `path`: The URL/path to send the request to.
        *   `relay-method` or `method`: The HTTP method (GET, POST, etc.).
        *   `relay-body` or `body`: The request body.
        *   `requires-sign`: (Optional, boolean) If true, the request message (`target`) will be signed using the node's key before sending. Defaults to `false`.
        *   `http-client`: (Optional) Specify a custom HTTP client module to use (defaults to node's configured `relay_http_client`).
    *   **Response:** `{ok, <ResponseMessage>}` where `<ResponseMessage>` is the full message received from the remote peer, or `{error, Reason}`.
    *   **Example HyperPATH:**
        ```
        GET /~relay@1.0/call?method=GET&path=https://example.com
        ```
*   **`cast`**
    *   **Action:** Sends an HTTP request asynchronously. The device returns immediately after spawning a process to send the request; it does not wait for or return the response from the remote peer.
    *   **Inputs:** Same as `call`.
    *   **Response:** `{ok, <<"OK">>}`.
*   **`preprocess`**
    *   **Action:** This function is designed to be used as a node's global `preprocessor` (configured via [`~meta@1.0`](../resources/source-code/dev_meta.md)). When configured, it intercepts *all* incoming requests to the node and automatically rewrites them to be relayed via the `call` key. This effectively turns the node into a pure forwarding proxy, using its routing table ([`dev_router`](../resources/source-code/dev_router.md)) to determine the destination.
    *   **Response:** A message structure that invokes `/~relay@1.0/call` with the original request as the target body.

## Use Cases

*   **Inter-Node Communication:** Sending messages between HyperBEAM nodes.
*   **External API Calls:** Allowing AO processes to interact with traditional web APIs.
*   **Routing Nodes:** Nodes configured with the `preprocess` key act as dedicated routers/proxies.
*   **Client-Side Relaying:** A local HyperBEAM instance can use `~relay@1.0` to forward requests to public compute nodes.

## Interaction with Routing

When `call` or `cast` is invoked, the actual HTTP request dispatch is handled by `hb_http:request/2`. This function often utilizes the node's routing configuration ([`dev_router`](../resources/source-code/dev_router.md)) to determine the specific peer/URL to send the request to, especially if the target path is an AO process ID or another internal identifier rather than a full external URL.

[relay module](../resources/source-code/dev_relay.md)

--- END OF FILE: docs/devices/relay-at-1-0.md ---

--- START OF FILE: docs/devices/scheduler-at-1-0.md ---
# Device: ~scheduler@1.0

## Overview

The [`~scheduler@1.0`](../resources/source-code/dev_scheduler.md) device manages the queueing and ordering of messages targeted at a specific process ([`~process@1.0`](../resources/source-code/dev_process.md)). It ensures that messages are processed according to defined scheduling rules.

## Core Concept: Message Ordering

When messages are sent to an AO process (typically via the [`~push@1.0`](../resources/source-code/dev_push.md) device or a `POST` to the process's `/schedule` endpoint), they are added to a queue managed by the Scheduler Device associated with that process. The scheduler ensures that messages are processed one after another in a deterministic order, typically based on arrival time and potentially other factors like message nonces or timestamps (depending on the specific scheduler implementation details).

The [`~process@1.0`](../resources/source-code/dev_process.md) device interacts with its configured Scheduler Device (which defaults to `~scheduler@1.0`) primarily through the `next` key to retrieve the next message to be executed.

## Slot System

Slots are a fundamental concept in the `~scheduler@1.0` device, providing a structured mechanism for organizing and sequencing computation.

*   **Sequential Ordering:** Slots act as numbered containers (starting at 0) that hold specific messages or tasks to be processed in a deterministic order.
*   **State Tracking:** The `at-slot` key in a process's state (or a similar internal field like `current-slot` within the scheduler itself) tracks execution progress, indicating which messages have been processed and which are pending. The `slot` function can be used to query this.
*   **Assignment Storage:** Each slot contains an "assignment" - the cryptographically verified message waiting to be executed. These assignments are retrieved using the `schedule` function or internally via `next`.
*   **Schedule Organization:** The collection of all slots for a process forms its "schedule".
*   **Application Scenarios:**
    * **Scheduling Messages:** When a message is posted to a process (e.g., via `register`), it's assigned to the next available slot.
    * **Status Monitoring:** Clients can query a process's current slot (via the `slot` function) to check progress.
    * **Task Retrieval:** Processes find their next task by requesting the next assignment via the `next` function, which implicitly uses the next slot number based on the current state.
    * **Distributed Consistency:** Slots ensure deterministic execution order across nodes, crucial for maintaining consistency in AO.

This slotting mechanism is central to AO processes built on HyperBEAM, allowing for deterministic, verifiable computation.

## Key Functions (Keys)

These keys are typically accessed via the [`~process@1.0`](../resources/source-code/dev_process.md) device, which delegates the calls to its configured scheduler.

*   **`schedule` (Handler for `GET /<ProcessID>~process@1.0/schedule`)**
    *   **Action:** Retrieves the list of pending assignments (messages) for the process. May support cursor-based traversal for long schedules.
    *   **Response:** A message map containing the assignments, often keyed by slot number or message ID.
*   **`register` (Handler for `POST /<ProcessID>~process@1.0/schedule`)**
    *   **Action:** Adds/registers a new message to the process's schedule. If this is the first message for a process, it might initialize the scheduler state.
    *   **Request Body:** The message to schedule.
    *   **Response:** Confirmation, potentially including the assigned slot or message ID.
*   **`slot` (Handler for `GET /<ProcessID>~process@1.0/slot`)**
    *   **Action:** Queries the current or a specific slot number within the process's schedule.
    *   **Response:** Information about the requested slot, such as the current highest slot number.
*   **`status` (Handler for `GET /<ProcessID>~process@1.0/status`)**
    *   **Action:** Retrieves status information about the scheduler for the process.
    *   **Response:** A status message.
*   **`next` (Internal Key used by [`~process@1.0`](../resources/source-code/dev_process.md))**
    *   **Action:** Retrieves the next assignment message from the schedule based on the process's current `at-slot` state.
    *   **State Management:** Requires the current process state (`Msg1`) containing the `at-slot` key.
    *   **Response:** `{ok, #{ "body" => <NextAssignmentMsg>, "state" => <UpdatedProcessState> }}` or `{error, Reason}` if no next assignment is found.
    *   **Caching & Lookahead:** The implementation uses internal caching (`dev_scheduler_cache`, `priv/assignments`) and potentially background lookahead workers to optimize fetching subsequent assignments.
*   **`init` (Internal Key)**
    *   **Action:** Initializes the scheduler state for a process, often called when the process itself is initialized.
*   **`checkpoint` (Internal Key)**
    *   **Action:** Triggers the scheduler to potentially persist its current state or perform other checkpointing operations.

## Interaction with Other Components

*   [`~process@1.0`](../resources/source-code/dev_process.md): The primary user of the scheduler, calling `next` to drive process execution.
*   [`~push@1.0`](../resources/source-code/dev_push.md): Often used to add messages to the schedule via `POST /schedule`.
*   `dev_scheduler_cache`: Internal module used for caching assignments locally on the node to reduce latency.
*   Scheduling Unit (SU): Schedulers may interact with external entities (like Arweave gateways or dedicated SU nodes) to fetch or commit schedules, although `~scheduler@1.0` aims for a simpler, often node-local or SU-client model.

`~scheduler@1.0` provides the fundamental mechanism for ordered, sequential execution within the potentially asynchronous and parallel environment of AO.

[scheduler module](../resources/source-code/dev_scheduler.md)

--- END OF FILE: docs/devices/scheduler-at-1-0.md ---

--- START OF FILE: docs/devices/wasm64-at-1-0.md ---
# Device: ~wasm64@1.0

## Overview

The [`~wasm64@1.0`](../resources/source-code/dev_wasm.md) device enables the execution of 64-bit WebAssembly (WASM) code within the HyperBEAM environment. It provides a sandboxed environment for running compiled code from various languages (like Rust, C++, Go) that target WASM.

## Core Concept: WASM Execution

This device allows AO processes to perform complex computations defined in WASM modules, which can be written in languages like Rust, C++, C, Go, etc., and compiled to WASM.

The device manages the lifecycle of a WASM instance associated with the process state.

## Key Functions (Keys)

These keys are typically used within an execution stack (managed by [`dev_stack`](../resources/source-code/dev_stack.md)) for an AO process.

*   **`init`**
    *   **Action:** Initializes the WASM environment for the process. It locates the WASM image (binary), starts a WAMR instance, and stores the instance handle and helper functions (for reading/writing WASM memory) in the process's private state (`priv/...`).
    *   **Inputs (Expected in Process Definition or `init` Message):**
        *   `[Prefix]/image`: The Arweave Transaction ID of the WASM binary, or the WASM binary itself, or a message containing the WASM binary in its body.
        *   `[Prefix]/Mode`: (Optional) Specifies execution mode (`WASM` (default) or `AOT` if allowed by node config).
    *   **Outputs (Stored in `priv/`):**
        *   `[Prefix]/instance`: The handle to the running WAMR instance.
        *   `[Prefix]/write`: A function to write data into the WASM instance's memory.
        *   `[Prefix]/read`: A function to read data from the WASM instance's memory.
        *   `[Prefix]/import-resolver`: A function used to handle calls *from* the WASM module back *to* the AO environment (imports).
*   **`compute`**
    *   **Action:** Executes a function within the initialized WASM instance. It retrieves the target function name and parameters from the incoming message or process definition and calls the WASM instance via `hb_beamr`.
    *   **Inputs (Expected in Process State or Incoming Message):**
        *   `priv/[Prefix]/instance`: The handle obtained during `init`.
        *   `function` or `body/function`: The name of the WASM function to call.
        *   `parameters` or `body/parameters`: A list of parameters to pass to the WASM function.
    *   **Outputs (Stored in `results/`):**
        *   `results/[Prefix]/type`: The result type returned by the WASM function.
        *   `results/[Prefix]/output`: The actual result value returned by the WASM function.
*   **`import`**
    *   **Action:** Handles calls originating *from* the WASM module (imports). The default implementation (`default_import_resolver`) resolves these calls by treating them as sub-calls within the AO environment, allowing WASM code to invoke other AO device functions or access process state via the `hb_ao:resolve` mechanism.
    *   **Inputs (Provided by `hb_beamr`):** Module name, function name, arguments, signature.
    *   **Response:** Returns the result of the resolved AO call back to the WASM instance.
*   **`snapshot`**
    *   **Action:** Captures the current memory state of the running WASM instance. This is used for checkpointing and restoring process state.
    *   **Inputs:** `priv/[Prefix]/instance`.
    *   **Outputs:** A message containing the raw binary snapshot of the WASM memory state, typically tagged with `[Prefix]/State`.
*   **`normalize` (Internal Helper)**
    *   **Action:** Ensures a consistent state representation for computation, primarily by loading a WASM instance from a snapshot (`[Prefix]/State`) if a live instance (`priv/[Prefix]/instance`) isn't already present. This allows resuming execution from a cached state.
*   **`terminate`**
    *   **Action:** Stops and cleans up the running WASM instance associated with the process.
    *   **Inputs:** `priv/[Prefix]/instance`.

## Usage within `dev_stack`

The `~wasm64@1.0` device is almost always used as part of an execution stack configured in the Process Definition Message and managed by [`dev_stack`](../resources/source-code/dev_stack.md). [`dev_stack`](../resources/source-code/dev_stack.md) ensures that `init` is called on the first pass, `compute` on subsequent passes, and potentially `snapshot` or `terminate` as needed.

```text
# Example Process Definition Snippet
Execution-Device: [`stack@1.0`](../resources/source-code/dev_stack.md)
Execution-Stack: "[`scheduler@1.0`](../resources/source-code/dev_scheduler.md)", "wasm64@1.0"
WASM-Image: <WASMImageTxID>
```

This setup allows AO processes to leverage the computational power and language flexibility offered by WebAssembly in a decentralized, verifiable manner.

[wasm module](../resources/source-code/dev_wasm.md)

--- END OF FILE: docs/devices/wasm64-at-1-0.md ---

--- START OF FILE: docs/devices/what-are-devices.md ---
# What are HyperBEAM Devices?

Devices are the core functional units within HyperBEAM and AO-Core. They define how messages are processed and what actions can be performed.

Each device listed here represents a specific capability available to AO processes and nodes. Understanding these devices is key to building complex applications and configuring your HyperBEAM node effectively.

## Available Devices

Below is a list of documented built-in devices. Each page details the device's purpose, available functions (keys), and usage examples where applicable.

*   [`~message@1.0`](./message-at-1-0.md): Base message handling and manipulation.
*   [`~meta@1.0`](./meta-at-1-0.md): Node configuration and metadata.
*   [`~process@1.0`](./process-at-1-0.md): Persistent, shared process execution environment.
*   [`~scheduler@1.0`](./scheduler-at-1-0.md): Message scheduling and execution ordering for processes.
*   [`~wasm64@1.0`](./wasm64-at-1-0.md): WebAssembly (WASM) execution engine.
*   [`~lua@5.3a`](./lua-at-5-3a.md): Lua script execution engine.
*   [`~relay@1.0`](./relay-at-1-0.md): Relaying messages to other nodes or HTTP endpoints.
*   [`~json@1.0`](./json-at-1-0.md): Provides access to JSON data structures using HyperPATHs.

There can exist many more devices, but these are a few of the ones that are built into HyperBEAM.

## Device Naming and Versioning

Devices are typically referenced using a name and version, like `~<name>@<version>` (e.g., `~process@1.0`). The tilde (`~`) often indicates a primary, user-facing device, while internal or utility devices might use a `dev_` prefix in the source code (e.g., `dev_router`).

Versioning indicates the specific interface and behavior of the device. Changes to a device that break backward compatibility usually result in a version increment.

--- END OF FILE: docs/devices/what-are-devices.md ---

--- START OF FILE: docs/introduction/hyperbeam-devices.md ---
# AO Devices

In AO-Core and its implementation HyperBEAM, **Devices** are modular components responsible for processing and interpreting [Messages](./what-is-ao-core.md#core-concepts). They define the specific logic for how computations are performed, data is handled, or interactions occur within the AO ecosystem.

Think of Devices as specialized engines or services that can be plugged into the AO framework. This modularity is key to AO's flexibility and extensibility.

## Purpose of Devices

*   **Define Computation:** Devices dictate *how* a message's instructions are executed. One device might run WASM code, another might manage process state, and yet another might simply relay data.
*   **Enable Specialization:** Nodes running HyperBEAM can choose which Devices to support, allowing them to specialize in certain tasks (e.g., high-compute tasks, storage-focused tasks, secure TEE operations).
*   **Promote Modularity:** New functionalities can be added to AO by creating new Devices, without altering the core protocol.
*   **Distribute Workload:** Different Devices can handle different parts of a complex task, enabling parallel processing and efficient resource utilization across the network.

## Familiar Examples

HyperBEAM includes many preloaded devices that provide core functionality. Some key examples include:

*   [`~meta@1.0`](../devices/meta-at-1-0.md): Configures the node itself (hardware specs, supported devices, payment info).
*   [`~process@1.0`](../devices/process-at-1-0.md): Manages persistent, shared computational states (like traditional smart contracts, but more flexible).
*   [`~scheduler@1.0`](../devices/scheduler-at-1-0.md): Handles the ordering and execution of messages within a process.
*   [`~wasm64@1.0`](../devices/wasm64-at-1-0.md): Executes WebAssembly (WASM) code, allowing for complex computations written in languages like Rust, C++, etc.
*   [`~lua@5.3a`](../devices/lua-at-5-3a.md): Executes Lua scripts.
*   [`~relay@1.0`](../devices/relay-at-1-0.md): Forwards messages between AO nodes or to external HTTP endpoints.
*   [`~json@1.0`](../devices/json-at-1-0.md): Provides access to JSON data structures using HyperPATHs.
*   [`~message@1.0`](../devices/message-at-1-0.md): Manages message state and processing.
*   [`~patch@1.0`](../guides/exposing-process-state.md): Applies state updates directly to a process, often used for migrating or managing process data.

## Beyond the Basics

Devices aren't limited to just computation or state management. They can represent more abstract concepts:

*   **Security Devices** ([`~snp@1.0`](../resources/source-code/dev_snp.md), [`dev_codec_httpsig`](../resources/source-code/dev_codec_httpsig.md)): Handle tasks related to Trusted Execution Environments (TEEs) or message signing, adding layers of security and verification.
*   **Payment/Access Control Devices** ([`~p4@1.0`](../resources/source-code/dev_p4.md), [`~faff@1.0`](../resources/source-code/dev_faff.md)): Manage metering, billing, or access control for node services.
*   **Workflow/Utility Devices** ([`dev_cron`](../resources/source-code/dev_cron.md), [`dev_stack`](../resources/source-code/dev_stack.md), [`dev_monitor`](../resources/source-code/dev_monitor.md)): Coordinate complex execution flows, schedule tasks, or monitor process activity.

## Using Devices

Devices are typically invoked via [HyperPATHs](./hyperpaths-in-hyperbeam.md). The path specifies which Device should interpret the subsequent parts of the path or the request body.

```
# Example: Execute the 'now' key on the process device for a specific process
/<procId>~process@1.0/now

# Example: Relay a GET request via the relay device
/~relay@1.0/call?method=GET&path=https://example.com
```

The specific functions or 'keys' available for each Device are documented individually. See the [Devices section](../devices/index.md) for details on specific built-in devices. 

## The Potential of Devices

The modular nature of AO Devices opens up vast possibilities for future expansion and innovation. The current set of preloaded and community devices is just the beginning. As the AO ecosystem evolves, we can anticipate the development of new devices catering to increasingly specialized needs:

*   **Specialized Hardware Integration:** Devices could be created to interface directly with specialized hardware accelerators like GPUs (for AI/ML tasks such as running large language models), TPUs, or FPGAs, allowing AO processes to leverage high-performance computing resources securely and verifiably.
*   **Advanced Cryptography:** New devices could implement cutting-edge cryptographic techniques, such as zero-knowledge proofs (ZKPs) or fully homomorphic encryption (FHE), enabling enhanced privacy and complex computations on encrypted data.
*   **Cross-Chain & Off-Chain Bridges:** Devices could act as secure bridges to other blockchain networks or traditional Web2 APIs, facilitating seamless interoperability and data exchange between AO and the wider digital world.
*   **AI/ML Specific Devices:** Beyond raw GPU access, specialized devices could offer higher-level AI/ML functionalities, like optimized model inference engines or distributed training frameworks.
*   **Domain-Specific Logic:** Communities or organizations could develop devices tailored to specific industries or use cases, such as decentralized finance (DeFi) primitives, scientific computing libraries, or decentralized identity management systems.

The Device framework ensures that AO can adapt and grow, incorporating new technologies and computational paradigms without requiring fundamental changes to the core protocol. This extensibility is key to AO's long-term vision of becoming a truly global, decentralized computer.

--- END OF FILE: docs/introduction/hyperbeam-devices.md ---

--- START OF FILE: docs/introduction/hyperpaths-in-hyperbeam.md ---
# HyperPATHs in HyperBEAM

## Overview

Understanding how to construct and interpret paths in AO-Core is fundamental to working with HyperBEAM. This guide explains the structure and components of AO-Core paths, enabling you to effectively interact with processes and access their data.

## HyperPATH Structure

Let's examine a typical HyperBEAM endpoint piece-by-piece:

```bash
https://dev-router.forward.computer/<procId>~process@1.0/now
```

### Node URL (`router-1.forward.computer`)

The HTTP response from this node includes a signature from the host's key. By accessing the [`~snp@1.0`](../resources/source-code/dev_snp.md) device, you can verify that the node is running in a genuine Trusted Execution Environment (TEE), ensuring computation integrity. You can replace `router-1.forward.computer` with any HyperBEAM TEE node operated by any party while maintaining trustless guarantees.

### Process Path (`/<procId>~process@1.0`)

Every path in AO-Core represents a program. Think of the URL bar as a Unix-style command-line interface, providing access to AO's trustless and verifiable compute. Each path component (between `/` characters) represents a step in the computation. In this example, we instruct the AO-Core node to:

1. Load a specific message from its caches (local, another node, or Arweave)
2. Interpret it with the [`~process@1.0`](../devices/process-at-1-0.md) device
3. The process device implements a shared computing environment with consistent state between users

### State Access (`/now` or `/compute`)

Devices in AO-Core expose keys accessible via path components. Each key executes a function on the device:

- `now`: Calculates real-time process state
- `compute`: Serves the latest known state (faster than checking for new messages)

Under the surface, these keys represent AO-Core messages. As we progress through the path, AO-Core applies each message to the existing state. You can access the full process state by visiting:
```bash
/<procId>~process@1.0/now
```

### State Navigation

You can browse through sub-messages and data fields by accessing them as keys. For example, if a process stores its interaction count in a field named `cache`, you can access it like this:
```bash
/<procId>~process@1.0/compute/cache
```
This shows the 'cache' of your process. Each response is:

- A message with a signature attesting to its correctness
- A hashpath describing its generation
- Transferable to other AO-Core nodes for uninterrupted execution

### Query Parameters and Type Casting

Beyond path segments, HyperBEAM URLs can include query parameters that utilize a special type casting syntax. This allows specifying the desired data type for a parameter directly within the URL using the format `key+type=value`.

- **Syntax**: A `+` symbol separates the parameter key from its intended type (e.g., `count+integer=42`, `items+list="apple",7`).
- **Mechanism**: The HyperBEAM node identifies the `+type` suffix (e.g., `+integer`, `+list`, `+map`, `+float`, `+atom`, `+resolve`). It then uses internal functions ([`hb_singleton:maybe_typed`](../resources/source-code/hb_singleton.md) and [`dev_codec_structured:decode_value`](../resources/source-code/dev_codec_structured.md)) to decode and cast the provided value string into the corresponding Erlang data type before incorporating it into the message.
- **Supported Types**: Common types include `integer`, `float`, `list`, `map`, `atom`, `binary` (often implicit), and `resolve` (for path resolution). List values often follow the [HTTP Structured Fields format (RFC 8941)](https://www.rfc-editor.org/rfc/rfc8941.html).

This powerful feature enables the expression of complex data structures directly in URLs.

## Examples

The following examples illustrate using HyperPATH with various AO-Core processes and devices. While these cover a few specific use cases, HyperBEAM's extensible nature allows interaction with any device or process via HyperPATH. For a deeper understanding, we encourage exploring the [source code](https://github.com/permaweb/hyperbeam) and experimenting with different paths.

### Example 1: Accessing Full Process State

To get the complete, real-time state of a process identified by `<procId>`, use the `/now` path component with the [`~process@1.0`](../devices/process-at-1-0.md) device:

```bash
GET /<procId>~process@1.0/now
```

This instructs the AO-Core node to load the process and execute the `now` function on the [`~process@1.0`](../devices/process-at-1-0.md) device.

### Example 2: Navigating to Specific Process Data

If a process maintains its state in a map and you want to access a specific field, like `at-slot`, using the faster `/compute` endpoint:

```bash
GET /<procId>~process@1.0/compute/cache
```

This accesses the `compute` key on the [`~process@1.0`](../devices/process-at-1-0.md) device and then navigates to the `cache` key within the resulting state map. Using this path, you will see the latest 'cache' of your process (the number of interactions it has received). Every piece of relevant information about your process can be accessed similarly, effectively providing a native API.

(Note: This represents direct navigation within the process state structure. For accessing data specifically published via the `~patch@1.0` device, see the documentation on [Exposing Process State](../build/migrating-from-legacynet.md#exposing-process-state-with-the-patch-device), which typically uses the `/cache/` path.)

### Example 3: Basic `~message@1.0` Usage

Here's a simple example of using [`~message@1.0`](../devices/message-at-1-0.md) to create a message and retrieve a value:

```bash
GET /~message@1.0&greeting="Hello"&count+integer=42/count
```

1.  **Base:** `/` - The base URL of the HyperBEAM node.
2.  **Root Device:** [`~message@1.0`](../devices/message-at-1-0.md)
3.  **Query Params:** `greeting="Hello"` (binary) and `count+integer=42` (integer), forming the message `#{ <<"greeting">> => <<"Hello">>, <<"count">> => 42 }`.
4.  **Path:** `/count` tells `~message@1.0` to retrieve the value associated with the key `count`.

**Response:** The integer `42`.

### Example 4: Using the `~message@1.0` Device with Type Casting

The [`~message@1.0`](../devices/message-at-1-0.md) device can be used to construct and query transient messages, utilizing type casting in query parameters.

Consider the following URL:

```bash
GET /~message@1.0&name="Alice"&age+integer=30&items+list="apple",1,"banana"&config+map=key1="val1";key2=true/[PATH]
```

HyperBEAM processes this as follows:

1.  **Base:** `/` - The base URL of the HyperBEAM node.
2.  **Root Device:** [`~message@1.0`](../devices/message-at-1-0.md)
3.  **Query Parameters (with type casting):**
    *   `name="Alice"` -> `#{ <<"name">> => <<"Alice">> }` (binary)
    *   `age+integer=30` -> `#{ <<"age">> => 30 }` (integer)
    *   `items+list="apple",1,"banana"` -> `#{ <<"items">> => [<<"apple">>, 1, <<"banana">>] }` (list)
    *   `config+map=key1="val1";key2=true` -> `#{ <<"config">> => #{<<"key1">> => <<"val1">>, <<"key2">> => true} }` (map)
4.  **Initial Message Map:** A combination of the above key-value pairs.
5.  **Path Evaluation:**
    *   If `[PATH]` is `/items/1`, the response is the integer `1`.
    *   If `[PATH]` is `/config/key1`, the response is the binary `<<"val1">>`.
--- END OF FILE: docs/introduction/hyperpaths-in-hyperbeam.md ---

--- START OF FILE: docs/introduction/what-is-ao-core.md ---
# What is AO-Core?

AO-Core is the foundational protocol underpinning the [AO Computer](https://ao.arweave.net). It defines a minimal, generalized model for decentralized computation built around standard web technologies like HTTP. Think of it as a way to interpret the Arweave permaweb not just as static storage, but as a dynamic, programmable, and infinitely scalable computing environment.

## Core Concepts

AO-Core revolves around three fundamental components:

<div class="grid-docs">

<div class="grid-docs-card">
<p><strong>Messages</strong></p>
<div class="grid-docs-card-fig">
<svg width="73" height="26" viewBox="0 0 73 26" fill="none" xmlns="http://www.w3.org/2000/svg">
<line x1="0.5" x2="0.5" y2="26" stroke="#5F5F5F"/>
<line x1="72.5" x2="72.5" y2="26" stroke="#5F5F5F"/>
<path d="M9 13H21.0416" stroke="#5F5F5F" stroke-width="2" stroke-linecap="square"/>
<path d="M31.0416 13H43.0832" stroke="#5F5F5F" stroke-width="2" stroke-linecap="square"/>
<path d="M53.0832 13H65.1248" stroke="#5F5F5F" stroke-width="2" stroke-linecap="square"/>
</svg>
</div>
<p>The smallest units of data and computation. Messages can be simple data blobs or maps of named functions.</p> <p>They are the primary means of communication and triggering execution within the system.</p> <p>Messages are cryptographically linked, forming a verifiable computation graph.</p>
</div>

<div class="grid-docs-card">
<p><strong>Devices</strong></p>

<div class="grid-docs-card-fig">
<svg width="85" height="68" viewBox="0 0 85 68" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M54 26H72V50" stroke="#6F6F6F" stroke-width="1" stroke-linejoin="round" stroke-dasharray="1 1"/>
<path d="M25 1H43V25" stroke="#6F6F6F" stroke-width="1" stroke-linejoin="round" stroke-dasharray="1 1"/>
<rect x="0.238661" y="0.625025" width="25.4567" height="18.2528" rx="0.954642" fill="white" stroke="#6F6F6F" stroke-width="1"/>
<rect x="29.8775" y="25.0153" width="25.4567" height="18.2528" rx="0.954642" fill="white" stroke="#6F6F6F" stroke-width="1"/>
<rect x="59.2387" y="49.2387" width="25.4567" height="18.2528" rx="0.954642" fill="white" stroke="#6F6F6F" stroke-width="1"/>
</svg>
</div>
<div>
<p>Modules responsible for interpreting and processing messages. </p> <p>Each device defines specific logic for how messages are handled (e.g., executing WASM, storing data, relaying information). </p><p>This modular design allows nodes to specialize and the system to be highly extensible.</p>
</div>
</div>

<div class="grid-docs-card">
<p><strong>Paths</strong></p>
<div class="grid-docs-card-fig">
<svg width="66" height="66" viewBox="0 0 66 66" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M15 31H28" stroke="#5F5F5F" stroke-width="1" stroke-dasharray="1 1"/>
<path d="M35 51V38" stroke="#5F5F5F" stroke-width="1" stroke-dasharray="1 1"/>
<path d="M42 24.1924L51.1924 15" stroke="#5F5F5F" stroke-width="1" stroke-dasharray="1 1"/>
<rect x="0.8" y="23.8" width="14.4" height="14.4" fill="white" stroke="#5F5F5F" stroke-width="1"/>
<rect x="27.8" y="23.8" width="14.4" height="14.4" fill="white" stroke="#5F5F5F" stroke-width="1"/>
<rect x="27.8" y="50.8" width="14.4" height="14.4" fill="white" stroke="#5F5F5F" stroke-width="1"/>
<rect x="50.8" y="0.8" width="14.4" height="14.4" fill="white" stroke="#5F5F5F" stroke-width="1"/>
</svg>
</div>
<p>Structures that link messages over time, creating a verifiable history of computations. </p> <p>Paths allow users to navigate the computation graph and access specific states or results. </p> <p>They leverage <code>HashPaths</code>, cryptographic fingerprints representing the sequence of operations leading to a specific message state, ensuring traceability and integrity.</p>
</div>

</div>

## Key Principles

*   **Minimalism:** AO-Core provides the simplest possible representation of data and computation, avoiding prescriptive consensus mechanisms or specific VM requirements.
*   **HTTP Native:** Designed for compatibility with HTTP protocols, making it accessible via standard web tools and infrastructure.
*   **Scalability:** By allowing parallel message processing and modular device execution, AO-Core enables hyper-parallel computing, overcoming the limitations of traditional sequential blockchains.
*   **Permissionlessness & Trustlessness:** While AO-Core itself is minimal, it provides the framework upon which higher-level protocols like AO can build systems that allow anyone to participate (`permissionlessness`) without needing to trust intermediaries (`trustlessness`). Users can choose their desired security and performance trade-offs.

AO-Core transforms the permanent data storage of Arweave into a global, shared computation space, enabling the creation of complex, autonomous, and scalable decentralized applications.

<!-- *See also: [The AO-Core Protocol Specification (Draft)](https://github.com/permaweb/ao-core/blob/main/spec.md)*  -->
--- END OF FILE: docs/introduction/what-is-ao-core.md ---

--- START OF FILE: docs/introduction/what-is-hyperbeam.md ---
# What is HyperBEAM?
<img src="https://arweave.net/S3qpd4CF_VSPD9DfVaWD4McFQy6XAUto2FLidcjofpM" alt="hb-flag" width="48" />

HyperBEAM is the primary, production-ready implementation of the [AO-Core protocol](./what-is-ao-core.md), built on the robust Erlang/OTP framework. It serves as a decentralized operating system, powering the AO Computer—a scalable, trust-minimized, distributed supercomputer built on permanent storage. HyperBEAM provides the runtime environment and essential services to execute AO-Core computations across a network of distributed nodes.

## Why HyperBEAM Matters

HyperBEAM transforms the abstract concepts of AO-Core—such as [Messages](./what-is-ao-core.md#core-concepts), [Devices](./what-is-ao-core.md#core-concepts), and [Paths](./what-is-ao-core.md#core-concepts)—into a concrete, operational system. Here's why it's pivotal to the AO ecosystem:

- **Modularity via Devices:** HyperBEAM introduces a uniquely modular architecture centered around [Devices](./hyperbeam-devices.md). These pluggable components define specific computational logic—like running WASM, managing state, or relaying data—allowing for unprecedented flexibility. Users can extend the system by creating custom Devices to fit their specific computational needs.
- **Decentralized OS:** It equips nodes with the infrastructure to join the AO network, manage resources, execute computations, and communicate seamlessly.

Built on the Erlang/OTP framework, HyperBEAM provides a robust and secure foundation that leverages the BEAM virtual machine for exceptional concurrency, fault tolerance, and scalability. This abstracts away underlying hardware, allowing diverse nodes to contribute resources without compatibility issues. The system governs how nodes coordinate and interact.

In essence, HyperBEAM is the engine that drives the AO Computer, enabling a vision of decentralized, verifiable computing at scale.

## Core Components & Features

- **Modular Devices:** The heart of HyperBEAM's extensibility. It includes essential built-in devices like [`~meta`](../devices/meta-at-1-0.md), [`~relay`](../devices/relay-at-1-0.md), [`~process`](../devices/process-at-1-0.md), [`~scheduler`](../devices/scheduler-at-1-0.md), and [`~wasm64`](../devices/wasm64-at-1-0.md) for core functionality, but the system is designed for easy addition of new custom devices.
- **Message System:** Everything in HyperBEAM is a "Message" — a map of named functions or binary data that can be processed, transformed, and cryptographically verified.
- **HTTP Interface:** Nodes expose an HTTP server for interaction via standard web requests and HyperPATHs, structured URLs that represent computation paths (effectively a sequence of state transformations for messages).

## Architecture

*   **Initialization Flow:** When a HyperBEAM node starts, it initializes the name service, scheduler registry, timestamp server, and HTTP server, establishing core services for process management, timing, communication, and storage.
*   **Compute Model:** Computation follows the pattern `Message1(Message2) => Message3`, where messages are resolved through their devices and [paths](./hyperpaths-in-hyperbeam.md). The integrity and history of these computations are ensured by **hashpaths**, which serves as a cryptographic audit trail.
*   **Scheduler System:** The scheduler component manages execution order using [slots](../devices/scheduler-at-1-0.md#slot-system) — sequential positions that guarantee deterministic computation.
*   **Process Slots:** Each process has numbered slots starting from 0 that track message execution order, ensuring consistent computation even across distributed nodes.

## HTTP API and Pathing

HyperBEAM exposes a powerful HTTP API that allows for interacting with processes and accessing data through structured URL patterns. We call URLs that represent computation paths **[HyperPATHs](./hyperpaths-in-hyperbeam.md)**. The URL bar effectively functions as a command-line interface for AO's trustless and verifiable compute.

For a comprehensive guide on constructing and interpreting paths in HyperBEAM, including detailed examples and best practices, see [HyperPATHs in HyperBEAM](./hyperpaths-in-hyperbeam.md).

In essence, HyperBEAM is the engine that powers the AO Computer, enabling the vision of a scalable, trust-minimized, decentralized supercomputer built on permanent storage.
--- END OF FILE: docs/introduction/what-is-hyperbeam.md ---

--- START OF FILE: docs/resources/llms.md ---
---
hide:
  - navigation
  - toc
---

# LLM Context Files

This section provides access to specially formatted files intended for consumption by Large Language Models (LLMs) to provide context about the HyperBEAM documentation.

1.  **[LLM Summary (llms.txt)](../llms.txt)**
    *   **Content**: Contains a brief summary of the HyperBEAM documentation structure and a list of relative file paths for all markdown documents included in the build.
    *   **Usage**: Useful for providing an LLM with a high-level overview and the available navigation routes within the documentation.

2.  **[LLM Full Content (llms-full.txt)](../llms-full.txt)**
    *   **Content**: A single text file containing the complete, concatenated content of all markdown documents from the specified documentation directories (`begin`, `run`, `guides`, `devices`, `resources`). Each file's content is clearly demarcated.
    *   **Usage**: Ideal for feeding the entire documentation content into an LLM for comprehensive context, analysis, or question-answering based on the full documentation set.

> **Generation Process:**
>   These files are automatically generated by the `docs/build-all.sh` script during the documentation build process. They consolidate information from the following directories: `docs/introduction`, `docs/run`, `docs/build`, `docs/devices`, `docs/resources`
--- END OF FILE: docs/resources/llms.md ---

--- START OF FILE: docs/resources/reference/faq.md ---
# Frequently Asked Questions

This page answers common questions about HyperBEAM, its components, and how to use them effectively.

## General Questions

### What is HyperBEAM?

HyperBEAM is a client implementation of the AO-Core protocol written in Erlang. It serves as the node software for a decentralized operating system that allows operators to offer computational resources to users in the AO network.

### How does HyperBEAM differ from other distributed systems?

HyperBEAM focuses on true decentralization with asynchronous message passing between isolated processes. Unlike many distributed systems that rely on central coordination, HyperBEAM nodes can operate independently while still forming a cohesive network. Additionally, its Erlang foundation provides robust fault tolerance and concurrency capabilities.

### What can I build with HyperBEAM?

You can build a wide range of applications, including:

- Decentralized applications (dApps)
- Distributed computation systems
- Peer-to-peer services
- Resilient microservices
- IoT device networks
- Decentralized storage solutions

### Is HyperBEAM open source?

Yes, HyperBEAM is source available on [GitHub](https://github.com/permaweb/HyperBEAM) and licensed under the Business Source License.

### What is the current focus or phase of HyperBEAM development?

The initial development phase focuses on integrating AO processes more deeply with HyperBEAM. A key part of this is phasing out the reliance on traditional "dryrun" simulations for reading process state. Instead, processes are encouraged to use the [~patch@1.0 device](../../resources/source-code/dev_patch.md) to expose specific parts of their state directly via HyperPATH GET requests. This allows for more efficient and direct state access, particularly for web interfaces and external integrations. You can learn more about this mechanism in the [Exposing Process State with the Patch Device](../../build/migrating-from-legacynet.md#exposing-process-state-with-the-patch-device) guide.

## Installation and Setup

### What are the system requirements for running HyperBEAM?

Currently, HyperBEAM is primarily tested and documented for Ubuntu 22.04 and macOS. Other platforms will be added in future updates. For detailed requirements, see the [System Requirements](../../run/configuring-your-machine.md) page.

### Can I run HyperBEAM in a container?

While technically possible, running HyperBEAM in Docker containers or other containerization technologies is currently not recommended. The containerization approach may introduce additional complexity and potential performance issues. We recommend running HyperBEAM directly on the host system until container support is more thoroughly tested and optimized.

### How do I update HyperBEAM to the latest version?

To update HyperBEAM:

1. Pull the latest code from the repository
2. Rebuild the application
3. Restart the HyperBEAM service

Specific update instructions will vary depending on your [installation method](../../run/running-a-hyperbeam-node.md).

### Can I run multiple HyperBEAM nodes on a single machine?

Yes, you can run multiple HyperBEAM nodes on a single machine, but you'll need to configure them to use different ports and data directories to avoid conflicts. However, this is not recommended for production environments as each node should ideally have a unique IP address to properly participate in the network. Running multiple nodes on a single machine is primarily useful for development and testing purposes.

## Architecture and Components

### What is the difference between HyperBEAM and Compute Unit?

- **HyperBEAM**: The Erlang-based node software that handles message routing, process management, and device coordination.
- **Compute Unit (CU)**: A NodeJS implementation that executes WebAssembly modules and handles computational tasks.

Together, these components form a complete execution environment for AO processes.

## Development and Usage

### What programming languages can I use with HyperBEAM?

You can use any programming language that compiles to WebAssembly (WASM) for creating modules that run on the Compute Unit. This includes languages like:

- Lua
- Rust
- C/C++
- And many others with WebAssembly support

### How do I debug processes running in HyperBEAM?

Debugging processes in HyperBEAM can be done through:

1. Logging messages to the system log (`DEBUG=HB_PRINT rebar3 shell`)
2. Monitoring process state and message flow
3. Inspecting memory usage and performance metrics

### Is there a limit to how many processes can run on a node?

The practical limit depends on your hardware resources. Erlang is designed to handle millions of lightweight processes efficiently, but the actual number will be determined by:

- Available memory
- CPU capacity
- Network bandwidth
- Storage speed
- The complexity of your processes


## Troubleshooting

### What should I do if a node becomes unresponsive?

If a node becomes unresponsive:

1. Check the node's logs for error messages
2. Verify network connectivity
3. Ensure sufficient system resources
4. Restart the node if necessary
5. Check for configuration issues

For persistent problems, consult the [Troubleshooting](troubleshooting.md) page.

### Where can I get help if I encounter issues?

If you encounter issues:

- Check the [Troubleshooting](troubleshooting.md) guide
- Search or ask questions on [GitHub Issues](https://github.com/permaweb/HyperBEAM/issues)
- Join the community on [Discord](https://discord.gg/V3yjzrBxPM)
--- END OF FILE: docs/resources/reference/faq.md ---

--- START OF FILE: docs/resources/reference/glossary.md ---
# Glossary

This glossary provides definitions for terms and concepts used throughout the HyperBEAM documentation. For a comprehensive glossary of permaweb-specific terminology, check out the [permaweb glossary](#permaweb-glossary) section below.

## AO-Core Protocol
The underlying protocol that HyperBEAM implements, enabling decentralized computing and communication between nodes. AO-Core provides a framework into which any number of different computational models, encapsulated as primitive devices, can be attached.

## Asynchronous Message Passing
A communication paradigm where senders don't wait for receivers to be ready, allowing for non-blocking operations and better scalability.

## Checkpoint
A saved state of a process that can be used to resume execution from a known point, used for persistence and recovery.

## Compute Unit (CU)
The NodeJS component of HyperBEAM that executes WebAssembly modules and handles computational tasks.

## Decentralized Execution
The ability to run processes across a distributed network without centralized control or coordination.

## Device
A functional unit in HyperBEAM that provides specific capabilities to the system, such as storage, networking, or computational resources.

## Erlang
The programming language used to implement the HyperBEAM core, known for its robustness and support for building distributed, fault-tolerant applications.

## ~flat@1.0
A format used for encoding settings files in HyperBEAM configuration, using HTTP header styling.

## Hashpaths
A mechanism for referencing locations in a program's state-space prior to execution. These state-space links are represented as Merklized lists of programs inputs and initial states.

## HyperBEAM
The Erlang-based node software that handles message routing, process management, and device coordination in the HyperBEAM ecosystem.

## Message
A data structure used for communication between processes in the HyperBEAM system. Messages can be interpreted as a binary term or as a collection of named functions (a Map of functions).

## Module
A unit of code that can be loaded and executed by the Compute Unit, typically in WebAssembly format.

## Node
An instance of HyperBEAM running on a physical or virtual machine that participates in the distributed network.

## ~p4@1.0
A device that runs as a pre-processor and post-processor in HyperBEAM, enabling a framework for node operators to sell usage of their machine's hardware to execute AO-Core devices.

## Process
An independent unit of computation in HyperBEAM with its own state and execution context.

## Process ID
A unique identifier assigned to a process within the HyperBEAM system.

## ~scheduler@1.0
A device used to assign a linear hashpath to an execution, such that all users may access it with a deterministic ordering.

## ~compute-lite@1.0
A lightweight device wrapping a local WASM executor, used for executing legacynet AO processes inside HyperBEAM.

## ~json-iface@1.0
A device that offers a translation layer between the JSON-encoded message format used by legacy versions and HyperBEAM's native HTTP message format.

## ~meta@1.0
A device used to configure the node's hardware, supported devices, metering and payments information, amongst other configuration options.

## ~process@1.0
A device that enables users to create persistent, shared executions that can be accessed by any number of users, each of whom may add additional inputs to its hashpath.

## ~relay@1.0
A device used to relay messages between nodes and the wider HTTP network. It offers an interface for sending and receiving messages using a variety of execution strategies.

## ~simple-pay@1.0
A simple, flexible pricing device that can be used in conjunction with p4@1.0 to offer flat-fees for the execution of AO-Core messages.

## ~snp@1.0
A device used to generate and validate proofs that a node is executing inside a Trusted Execution Environment (TEE).

## ~wasm64@1.0
A device used to execute WebAssembly code, using the Web Assembly Micro-Runtime (WAMR) under-the-hood.

## ~stack@1.0
A device used to execute an ordered set of devices over the same inputs, allowing users to create complex combinations of other devices.

## Trusted Execution Environment (TEE)
A secure area inside a processor that ensures the confidentiality and integrity of code and data loaded within it. Used in HyperBEAM for trust-minimized computation.

## WebAssembly (WASM)
A binary instruction format that serves as a portable compilation target for programming languages, enabling deployment on the web and other environments.

## Permaweb Glossary

For a more comprehensive glossary of terms used in the permaweb, try the [Permaweb Glossary](https://glossary.arweave.net). Or use it below:


<style>
.dark-mode-iframe-container { display: none; }
.light-mode-iframe-container { display: block; }
[data-md-color-scheme="slate"] .light-mode-iframe-container { display: none; }
[data-md-color-scheme="slate"] .dark-mode-iframe-container { display: block; }

/* Explicitly handle default scheme */
[data-md-color-scheme="default"] .dark-mode-iframe-container { display: none; }
[data-md-color-scheme="default"] .light-mode-iframe-container { display: block; }
</style>

<div class="mt-6">
  <div class="light-mode-iframe-container">
    <iframe 
     id="glossary-frame-light" 
     src="https://glossary.arweave.net/?hide-header=true&bg-color=%23FFFFFF&text-color=%231A1A1A&heading-color=%233C3C3C&tag-text=%23ffffff&button-text=%23ffffff"
     width="100%" 
     height="400" 
     frameborder="0" 
     scrolling="no">
    </iframe>
  </div>
  <div class="dark-mode-iframe-container">
    <iframe 
     class="w-full"
	 width="100%" 
     height="400"  
	 frameborder="0" 
	 scrolling="no"
     src="https://glossary.arweave.net/?hide-header=true&bg-color=%231F2129&text-color=%23e0e0e0&heading-color=%23ffffff&border-color=%23444444&hover-bg=%23222222&button-text=%23ffffff&section-bg=%23333333&section-color=%23ffffff&category-bg=%23333333&category-text=%23ffffff&tag-text=%23ffffff&secondary-text=%23a0a0a0&result-bg=%231e1e1e&result-hover=%23333333"
     >
    </iframe>
  </div>
</div>
--- END OF FILE: docs/resources/reference/glossary.md ---

--- START OF FILE: docs/resources/reference/troubleshooting.md ---
# Troubleshooting Guide

This guide addresses common issues you might encounter when working with HyperBEAM and the Compute Unit.

## Installation Issues

### Erlang Installation Fails

**Symptoms**: Errors during Erlang compilation or installation

**Solutions**:

- Ensure all required dependencies are installed: `sudo apt-get install -y libssl-dev ncurses-dev make cmake gcc g++`
- Try configuring with fewer options: `./configure --without-wx --without-debugger --without-observer --without-et`
- Check disk space, as compilation requires several GB of free space

### Rebar3 Bootstrap Fails

**Symptoms**: Errors when running `./bootstrap` for Rebar3

**Solutions**:

- Verify Erlang is correctly installed: `erl -eval 'erlang:display(erlang:system_info(otp_release)), halt().'`
- Ensure you have the latest version of the repository: `git fetch && git reset --hard origin/master`
- Try manually downloading a precompiled Rebar3 binary

## HyperBEAM Issues

### HyperBEAM Won't Start

**Symptoms**: Errors when running `rebar3 shell` or the HyperBEAM startup command

**Solutions**:

- Check for port conflicts: Another service might be using the configured port
- Verify the wallet key file exists and is accessible
- Examine Erlang crash dumps for detailed error information
- Ensure all required dependencies are installed

### HyperBEAM Crashes During Operation

**Symptoms**: Unexpected termination of the HyperBEAM process

**Solutions**:

- Check system resources (memory, disk space)
- Examine Erlang crash dumps for details
- Reduce memory limits if the system is resource-constrained
- Check for network connectivity issues if connecting to external services

## Compute Unit Issues

### Compute Unit Won't Start

**Symptoms**: Errors when running `npm start` in the CU directory

**Solutions**:

- Verify Node.js is installed correctly: `node -v`
- Ensure all dependencies are installed: `npm i`
- Check that the wallet file exists and is correctly formatted
- Verify the `.env` file has all required settings

### Memory Errors in Compute Unit

**Symptoms**: Out of memory errors or excessive memory usage

**Solutions**:

- Adjust the `PROCESS_WASM_MEMORY_MAX_LIMIT` environment variable
- Enable garbage collection by setting an appropriate `GC_INTERVAL_MS`
- Monitor memory usage and adjust limits as needed
- If on a low-memory system, reduce concurrent process execution

## Integration Issues

### HyperBEAM Can't Connect to Compute Unit

**Symptoms**: Connection errors in HyperBEAM logs when trying to reach the CU

**Solutions**:

- Verify the CU is running: `curl http://localhost:6363`
- Ensure there are no firewall rules blocking the connection
- Verify network configuration if components are on different machines

### Process Execution Fails

**Symptoms**: Errors when deploying or executing processes

**Solutions**:

- Check both HyperBEAM and CU logs for specific error messages
- Verify that the WASM module is correctly compiled and valid
- Test with a simple example process to isolate the issue
- Adjust memory limits if the process requires more resources

## Getting Help

If you're still experiencing issues after trying these troubleshooting steps:

1. Check the [GitHub repository](https://github.com/permaweb/HyperBEAM) for known issues
2. Join the [Discord community](https://discord.gg/V3yjzrBxPM) for support
3. Open an issue on GitHub with detailed information about your problem 
--- END OF FILE: docs/resources/reference/troubleshooting.md ---

--- START OF FILE: docs/resources/source-code/ar_bundles.md ---
# [Module ar_bundles.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/ar_bundles.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_bundle_tags-1">add_bundle_tags/1*</a></td><td></td></tr><tr><td valign="top"><a href="#add_list_tags-1">add_list_tags/1*</a></td><td></td></tr><tr><td valign="top"><a href="#add_manifest_tags-2">add_manifest_tags/2*</a></td><td></td></tr><tr><td valign="top"><a href="#ar_bundles_test_-0">ar_bundles_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#assert_data_item-7">assert_data_item/7*</a></td><td></td></tr><tr><td valign="top"><a href="#check_size-2">check_size/2*</a></td><td>Force that a binary is either empty or the given number of bytes.</td></tr><tr><td valign="top"><a href="#check_type-2">check_type/2*</a></td><td>Ensure that a value is of the given type.</td></tr><tr><td valign="top"><a href="#data_item_signature_data-1">data_item_signature_data/1</a></td><td>Generate the data segment to be signed for a data item.</td></tr><tr><td valign="top"><a href="#data_item_signature_data-2">data_item_signature_data/2*</a></td><td></td></tr><tr><td valign="top"><a href="#decode_avro_name-3">decode_avro_name/3*</a></td><td></td></tr><tr><td valign="top"><a href="#decode_avro_tags-2">decode_avro_tags/2*</a></td><td>Decode Avro blocks (for tags) from binary.</td></tr><tr><td valign="top"><a href="#decode_avro_value-4">decode_avro_value/4*</a></td><td></td></tr><tr><td valign="top"><a href="#decode_bundle_header-2">decode_bundle_header/2*</a></td><td></td></tr><tr><td valign="top"><a href="#decode_bundle_header-3">decode_bundle_header/3*</a></td><td></td></tr><tr><td valign="top"><a href="#decode_bundle_items-2">decode_bundle_items/2*</a></td><td></td></tr><tr><td valign="top"><a href="#decode_optional_field-1">decode_optional_field/1*</a></td><td></td></tr><tr><td valign="top"><a href="#decode_signature-1">decode_signature/1*</a></td><td>Decode the signature from a binary format.</td></tr><tr><td valign="top"><a href="#decode_tags-1">decode_tags/1</a></td><td>Decode tags from a binary format using Apache Avro.</td></tr><tr><td valign="top"><a href="#decode_vint-3">decode_vint/3*</a></td><td></td></tr><tr><td valign="top"><a href="#decode_zigzag-1">decode_zigzag/1*</a></td><td>Decode a VInt encoded ZigZag integer from binary.</td></tr><tr><td valign="top"><a href="#deserialize-1">deserialize/1</a></td><td>Convert binary data back to a #tx record.</td></tr><tr><td valign="top"><a href="#deserialize-2">deserialize/2</a></td><td></td></tr><tr><td valign="top"><a href="#encode_avro_string-1">encode_avro_string/1*</a></td><td>Encode a string for Avro using ZigZag and VInt encoding.</td></tr><tr><td valign="top"><a href="#encode_optional_field-1">encode_optional_field/1*</a></td><td>Encode an optional field (target, anchor) with a presence byte.</td></tr><tr><td valign="top"><a href="#encode_signature_type-1">encode_signature_type/1*</a></td><td>Only RSA 4096 is currently supported.</td></tr><tr><td valign="top"><a href="#encode_tags-1">encode_tags/1</a></td><td>Encode tags into a binary format using Apache Avro.</td></tr><tr><td valign="top"><a href="#encode_tags_size-2">encode_tags_size/2*</a></td><td></td></tr><tr><td valign="top"><a href="#encode_vint-1">encode_vint/1*</a></td><td>Encode a ZigZag integer to VInt binary format.</td></tr><tr><td valign="top"><a href="#encode_vint-2">encode_vint/2*</a></td><td></td></tr><tr><td valign="top"><a href="#encode_zigzag-1">encode_zigzag/1*</a></td><td>Encode an integer using ZigZag encoding.</td></tr><tr><td valign="top"><a href="#enforce_valid_tx-1">enforce_valid_tx/1*</a></td><td>Take an item and ensure that it is of valid form.</td></tr><tr><td valign="top"><a href="#finalize_bundle_data-1">finalize_bundle_data/1*</a></td><td></td></tr><tr><td valign="top"><a href="#find-2">find/2</a></td><td>Find an item in a bundle-map/list and return it.</td></tr><tr><td valign="top"><a href="#find_single_layer-2">find_single_layer/2*</a></td><td>An internal helper for finding an item in a single-layer of a bundle.</td></tr><tr><td valign="top"><a href="#format-1">format/1</a></td><td></td></tr><tr><td valign="top"><a href="#format-2">format/2</a></td><td></td></tr><tr><td valign="top"><a href="#format_binary-1">format_binary/1*</a></td><td></td></tr><tr><td valign="top"><a href="#format_data-2">format_data/2*</a></td><td></td></tr><tr><td valign="top"><a href="#format_line-2">format_line/2*</a></td><td></td></tr><tr><td valign="top"><a href="#format_line-3">format_line/3*</a></td><td></td></tr><tr><td valign="top"><a href="#hd-1">hd/1</a></td><td>Return the first item in a bundle-map/list.</td></tr><tr><td valign="top"><a href="#id-1">id/1</a></td><td>Return the ID of an item -- either signed or unsigned as specified.</td></tr><tr><td valign="top"><a href="#id-2">id/2</a></td><td></td></tr><tr><td valign="top"><a href="#is_signed-1">is_signed/1</a></td><td>Check if an item is signed.</td></tr><tr><td valign="top"><a href="#manifest-1">manifest/1</a></td><td></td></tr><tr><td valign="top"><a href="#manifest_item-1">manifest_item/1</a></td><td>Return the manifest item in a bundle-map/list.</td></tr><tr><td valign="top"><a href="#map-1">map/1</a></td><td>Convert an item containing a map or list into an Erlang map.</td></tr><tr><td valign="top"><a href="#maybe_map_to_list-1">maybe_map_to_list/1*</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_unbundle-1">maybe_unbundle/1*</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_unbundle_map-1">maybe_unbundle_map/1*</a></td><td></td></tr><tr><td valign="top"><a href="#member-2">member/2</a></td><td>Check if an item exists in a bundle-map/list.</td></tr><tr><td valign="top"><a href="#new_item-4">new_item/4</a></td><td>Create a new data item.</td></tr><tr><td valign="top"><a href="#new_manifest-1">new_manifest/1*</a></td><td></td></tr><tr><td valign="top"><a href="#normalize-1">normalize/1</a></td><td></td></tr><tr><td valign="top"><a href="#normalize_data-1">normalize_data/1*</a></td><td>Ensure that a data item (potentially containing a map or list) has a standard, serialized form.</td></tr><tr><td valign="top"><a href="#normalize_data_size-1">normalize_data_size/1*</a></td><td>Reset the data size of a data item.</td></tr><tr><td valign="top"><a href="#ok_or_throw-3">ok_or_throw/3*</a></td><td>Throw an error if the given value is not ok.</td></tr><tr><td valign="top"><a href="#parse_manifest-1">parse_manifest/1</a></td><td></td></tr><tr><td valign="top"><a href="#print-1">print/1</a></td><td></td></tr><tr><td valign="top"><a href="#reset_ids-1">reset_ids/1</a></td><td>Re-calculate both of the IDs for an item.</td></tr><tr><td valign="top"><a href="#run_test-0">run_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#serialize-1">serialize/1</a></td><td>Convert a #tx record to its binary representation.</td></tr><tr><td valign="top"><a href="#serialize-2">serialize/2</a></td><td></td></tr><tr><td valign="top"><a href="#serialize_bundle_data-2">serialize_bundle_data/2*</a></td><td></td></tr><tr><td valign="top"><a href="#sign_item-2">sign_item/2</a></td><td>Sign a data item.</td></tr><tr><td valign="top"><a href="#signer-1">signer/1</a></td><td>Return the address of the signer of an item, if it is signed.</td></tr><tr><td valign="top"><a href="#test_basic_member_id-0">test_basic_member_id/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_bundle_map-0">test_bundle_map/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_bundle_with_one_item-0">test_bundle_with_one_item/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_bundle_with_two_items-0">test_bundle_with_two_items/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_deep_member-0">test_deep_member/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_empty_bundle-0">test_empty_bundle/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_extremely_large_bundle-0">test_extremely_large_bundle/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_no_tags-0">test_no_tags/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_recursive_bundle-0">test_recursive_bundle/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_serialize_deserialize_deep_signed_bundle-0">test_serialize_deserialize_deep_signed_bundle/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_unsigned_data_item_id-0">test_unsigned_data_item_id/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_unsigned_data_item_normalization-0">test_unsigned_data_item_normalization/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_with_tags-0">test_with_tags/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_with_zero_length_tag-0">test_with_zero_length_tag/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to_serialized_pair-1">to_serialized_pair/1*</a></td><td></td></tr><tr><td valign="top"><a href="#type-1">type/1</a></td><td></td></tr><tr><td valign="top"><a href="#unbundle-1">unbundle/1*</a></td><td></td></tr><tr><td valign="top"><a href="#unbundle_list-1">unbundle_list/1*</a></td><td></td></tr><tr><td valign="top"><a href="#update_ids-1">update_ids/1*</a></td><td>Take an item and ensure that both the unsigned and signed IDs are
appropriately set.</td></tr><tr><td valign="top"><a href="#utf8_encoded-1">utf8_encoded/1*</a></td><td>Encode a UTF-8 string to binary.</td></tr><tr><td valign="top"><a href="#verify_data_item_id-1">verify_data_item_id/1*</a></td><td>Verify the data item's ID matches the signature.</td></tr><tr><td valign="top"><a href="#verify_data_item_signature-1">verify_data_item_signature/1*</a></td><td>Verify the data item's signature.</td></tr><tr><td valign="top"><a href="#verify_data_item_tags-1">verify_data_item_tags/1*</a></td><td>Verify the validity of the data item's tags.</td></tr><tr><td valign="top"><a href="#verify_item-1">verify_item/1</a></td><td>Verify the validity of a data item.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_bundle_tags-1"></a>

### add_bundle_tags/1 * ###

`add_bundle_tags(Tags) -> any()`

<a name="add_list_tags-1"></a>

### add_list_tags/1 * ###

`add_list_tags(Tags) -> any()`

<a name="add_manifest_tags-2"></a>

### add_manifest_tags/2 * ###

`add_manifest_tags(Tags, ManifestID) -> any()`

<a name="ar_bundles_test_-0"></a>

### ar_bundles_test_/0 * ###

`ar_bundles_test_() -> any()`

<a name="assert_data_item-7"></a>

### assert_data_item/7 * ###

`assert_data_item(KeyType, Owner, Target, Anchor, Tags, Data, DataItem) -> any()`

<a name="check_size-2"></a>

### check_size/2 * ###

`check_size(Bin, Sizes) -> any()`

Force that a binary is either empty or the given number of bytes.

<a name="check_type-2"></a>

### check_type/2 * ###

`check_type(Value, X2) -> any()`

Ensure that a value is of the given type.

<a name="data_item_signature_data-1"></a>

### data_item_signature_data/1 ###

`data_item_signature_data(RawItem) -> any()`

Generate the data segment to be signed for a data item.

<a name="data_item_signature_data-2"></a>

### data_item_signature_data/2 * ###

`data_item_signature_data(RawItem, X2) -> any()`

<a name="decode_avro_name-3"></a>

### decode_avro_name/3 * ###

`decode_avro_name(NameSize, Rest, Count) -> any()`

<a name="decode_avro_tags-2"></a>

### decode_avro_tags/2 * ###

`decode_avro_tags(Binary, Count) -> any()`

Decode Avro blocks (for tags) from binary.

<a name="decode_avro_value-4"></a>

### decode_avro_value/4 * ###

`decode_avro_value(ValueSize, Name, Rest, Count) -> any()`

<a name="decode_bundle_header-2"></a>

### decode_bundle_header/2 * ###

`decode_bundle_header(Count, Bin) -> any()`

<a name="decode_bundle_header-3"></a>

### decode_bundle_header/3 * ###

`decode_bundle_header(Count, ItemsBin, Header) -> any()`

<a name="decode_bundle_items-2"></a>

### decode_bundle_items/2 * ###

`decode_bundle_items(RestItems, ItemsBin) -> any()`

<a name="decode_optional_field-1"></a>

### decode_optional_field/1 * ###

`decode_optional_field(X1) -> any()`

<a name="decode_signature-1"></a>

### decode_signature/1 * ###

`decode_signature(Other) -> any()`

Decode the signature from a binary format. Only RSA 4096 is currently supported.
Note: the signature type '1' corresponds to RSA 4096 - but it is is written in
little-endian format which is why we match on `<<1, 0>>`.

<a name="decode_tags-1"></a>

### decode_tags/1 ###

`decode_tags(X1) -> any()`

Decode tags from a binary format using Apache Avro.

<a name="decode_vint-3"></a>

### decode_vint/3 * ###

`decode_vint(X1, Result, Shift) -> any()`

<a name="decode_zigzag-1"></a>

### decode_zigzag/1 * ###

`decode_zigzag(Binary) -> any()`

Decode a VInt encoded ZigZag integer from binary.

<a name="deserialize-1"></a>

### deserialize/1 ###

`deserialize(Binary) -> any()`

Convert binary data back to a #tx record.

<a name="deserialize-2"></a>

### deserialize/2 ###

`deserialize(Item, X2) -> any()`

<a name="encode_avro_string-1"></a>

### encode_avro_string/1 * ###

`encode_avro_string(String) -> any()`

Encode a string for Avro using ZigZag and VInt encoding.

<a name="encode_optional_field-1"></a>

### encode_optional_field/1 * ###

`encode_optional_field(Field) -> any()`

Encode an optional field (target, anchor) with a presence byte.

<a name="encode_signature_type-1"></a>

### encode_signature_type/1 * ###

`encode_signature_type(X1) -> any()`

Only RSA 4096 is currently supported.
Note: the signature type '1' corresponds to RSA 4096 -- but it is is written in
little-endian format which is why we encode to `<<1, 0>>`.

<a name="encode_tags-1"></a>

### encode_tags/1 ###

`encode_tags(Tags) -> any()`

Encode tags into a binary format using Apache Avro.

<a name="encode_tags_size-2"></a>

### encode_tags_size/2 * ###

`encode_tags_size(Tags, EncodedTags) -> any()`

<a name="encode_vint-1"></a>

### encode_vint/1 * ###

`encode_vint(ZigZag) -> any()`

Encode a ZigZag integer to VInt binary format.

<a name="encode_vint-2"></a>

### encode_vint/2 * ###

`encode_vint(ZigZag, Acc) -> any()`

<a name="encode_zigzag-1"></a>

### encode_zigzag/1 * ###

`encode_zigzag(Int) -> any()`

Encode an integer using ZigZag encoding.

<a name="enforce_valid_tx-1"></a>

### enforce_valid_tx/1 * ###

`enforce_valid_tx(List) -> any()`

Take an item and ensure that it is of valid form. Useful for ensuring
that a message is viable for serialization/deserialization before execution.
This function should throw simple, easy to follow errors to aid devs in
debugging issues.

<a name="finalize_bundle_data-1"></a>

### finalize_bundle_data/1 * ###

`finalize_bundle_data(Processed) -> any()`

<a name="find-2"></a>

### find/2 ###

`find(Key, Map) -> any()`

Find an item in a bundle-map/list and return it.

<a name="find_single_layer-2"></a>

### find_single_layer/2 * ###

`find_single_layer(UnsignedID, TX) -> any()`

An internal helper for finding an item in a single-layer of a bundle.
Does not recurse! You probably want `find/2` in most cases.

<a name="format-1"></a>

### format/1 ###

`format(Item) -> any()`

<a name="format-2"></a>

### format/2 ###

`format(Item, Indent) -> any()`

<a name="format_binary-1"></a>

### format_binary/1 * ###

`format_binary(Bin) -> any()`

<a name="format_data-2"></a>

### format_data/2 * ###

`format_data(Item, Indent) -> any()`

<a name="format_line-2"></a>

### format_line/2 * ###

`format_line(Str, Indent) -> any()`

<a name="format_line-3"></a>

### format_line/3 * ###

`format_line(RawStr, Fmt, Ind) -> any()`

<a name="hd-1"></a>

### hd/1 ###

`hd(Tx) -> any()`

Return the first item in a bundle-map/list.

<a name="id-1"></a>

### id/1 ###

`id(Item) -> any()`

Return the ID of an item -- either signed or unsigned as specified.
If the item is unsigned and the user requests the signed ID, we return
the atom `not_signed`. In all other cases, we return the ID of the item.

<a name="id-2"></a>

### id/2 ###

`id(Item, Type) -> any()`

<a name="is_signed-1"></a>

### is_signed/1 ###

`is_signed(Item) -> any()`

Check if an item is signed.

<a name="manifest-1"></a>

### manifest/1 ###

`manifest(Map) -> any()`

<a name="manifest_item-1"></a>

### manifest_item/1 ###

`manifest_item(Tx) -> any()`

Return the manifest item in a bundle-map/list.

<a name="map-1"></a>

### map/1 ###

`map(Tx) -> any()`

Convert an item containing a map or list into an Erlang map.

<a name="maybe_map_to_list-1"></a>

### maybe_map_to_list/1 * ###

`maybe_map_to_list(Item) -> any()`

<a name="maybe_unbundle-1"></a>

### maybe_unbundle/1 * ###

`maybe_unbundle(Item) -> any()`

<a name="maybe_unbundle_map-1"></a>

### maybe_unbundle_map/1 * ###

`maybe_unbundle_map(Bundle) -> any()`

<a name="member-2"></a>

### member/2 ###

`member(Key, Item) -> any()`

Check if an item exists in a bundle-map/list.

<a name="new_item-4"></a>

### new_item/4 ###

`new_item(Target, Anchor, Tags, Data) -> any()`

Create a new data item. Should only be used for testing.

<a name="new_manifest-1"></a>

### new_manifest/1 * ###

`new_manifest(Index) -> any()`

<a name="normalize-1"></a>

### normalize/1 ###

`normalize(Item) -> any()`

<a name="normalize_data-1"></a>

### normalize_data/1 * ###

`normalize_data(Bundle) -> any()`

Ensure that a data item (potentially containing a map or list) has a standard, serialized form.

<a name="normalize_data_size-1"></a>

### normalize_data_size/1 * ###

`normalize_data_size(Item) -> any()`

Reset the data size of a data item. Assumes that the data is already normalized.

<a name="ok_or_throw-3"></a>

### ok_or_throw/3 * ###

`ok_or_throw(TX, X2, Error) -> any()`

Throw an error if the given value is not ok.

<a name="parse_manifest-1"></a>

### parse_manifest/1 ###

`parse_manifest(Item) -> any()`

<a name="print-1"></a>

### print/1 ###

`print(Item) -> any()`

<a name="reset_ids-1"></a>

### reset_ids/1 ###

`reset_ids(Item) -> any()`

Re-calculate both of the IDs for an item. This is a wrapper
function around `update_id/1` that ensures both IDs are set from
scratch.

<a name="run_test-0"></a>

### run_test/0 * ###

`run_test() -> any()`

<a name="serialize-1"></a>

### serialize/1 ###

`serialize(TX) -> any()`

Convert a #tx record to its binary representation.

<a name="serialize-2"></a>

### serialize/2 ###

`serialize(TX, X2) -> any()`

<a name="serialize_bundle_data-2"></a>

### serialize_bundle_data/2 * ###

`serialize_bundle_data(Map, Manifest) -> any()`

<a name="sign_item-2"></a>

### sign_item/2 ###

`sign_item(RawItem, X2) -> any()`

Sign a data item.

<a name="signer-1"></a>

### signer/1 ###

`signer(Tx) -> any()`

Return the address of the signer of an item, if it is signed.

<a name="test_basic_member_id-0"></a>

### test_basic_member_id/0 * ###

`test_basic_member_id() -> any()`

<a name="test_bundle_map-0"></a>

### test_bundle_map/0 * ###

`test_bundle_map() -> any()`

<a name="test_bundle_with_one_item-0"></a>

### test_bundle_with_one_item/0 * ###

`test_bundle_with_one_item() -> any()`

<a name="test_bundle_with_two_items-0"></a>

### test_bundle_with_two_items/0 * ###

`test_bundle_with_two_items() -> any()`

<a name="test_deep_member-0"></a>

### test_deep_member/0 * ###

`test_deep_member() -> any()`

<a name="test_empty_bundle-0"></a>

### test_empty_bundle/0 * ###

`test_empty_bundle() -> any()`

<a name="test_extremely_large_bundle-0"></a>

### test_extremely_large_bundle/0 * ###

`test_extremely_large_bundle() -> any()`

<a name="test_no_tags-0"></a>

### test_no_tags/0 * ###

`test_no_tags() -> any()`

<a name="test_recursive_bundle-0"></a>

### test_recursive_bundle/0 * ###

`test_recursive_bundle() -> any()`

<a name="test_serialize_deserialize_deep_signed_bundle-0"></a>

### test_serialize_deserialize_deep_signed_bundle/0 * ###

`test_serialize_deserialize_deep_signed_bundle() -> any()`

<a name="test_unsigned_data_item_id-0"></a>

### test_unsigned_data_item_id/0 * ###

`test_unsigned_data_item_id() -> any()`

<a name="test_unsigned_data_item_normalization-0"></a>

### test_unsigned_data_item_normalization/0 * ###

`test_unsigned_data_item_normalization() -> any()`

<a name="test_with_tags-0"></a>

### test_with_tags/0 * ###

`test_with_tags() -> any()`

<a name="test_with_zero_length_tag-0"></a>

### test_with_zero_length_tag/0 * ###

`test_with_zero_length_tag() -> any()`

<a name="to_serialized_pair-1"></a>

### to_serialized_pair/1 * ###

`to_serialized_pair(Item) -> any()`

<a name="type-1"></a>

### type/1 ###

`type(Item) -> any()`

<a name="unbundle-1"></a>

### unbundle/1 * ###

`unbundle(Item) -> any()`

<a name="unbundle_list-1"></a>

### unbundle_list/1 * ###

`unbundle_list(Item) -> any()`

<a name="update_ids-1"></a>

### update_ids/1 * ###

`update_ids(Item) -> any()`

Take an item and ensure that both the unsigned and signed IDs are
appropriately set. This function is structured to fall through all cases
of poorly formed items, recursively ensuring its correctness for each case
until the item has a coherent set of IDs.
The cases in turn are:
- The item has no unsigned_id. This is never valid.
- The item has the default signature and ID. This is valid.
- The item has the default signature but a non-default ID. Reset the ID.
- The item has a signature. We calculate the ID from the signature.
- Valid: The item is fully formed and has both an unsigned and signed ID.

<a name="utf8_encoded-1"></a>

### utf8_encoded/1 * ###

`utf8_encoded(String) -> any()`

Encode a UTF-8 string to binary.

<a name="verify_data_item_id-1"></a>

### verify_data_item_id/1 * ###

`verify_data_item_id(DataItem) -> any()`

Verify the data item's ID matches the signature.

<a name="verify_data_item_signature-1"></a>

### verify_data_item_signature/1 * ###

`verify_data_item_signature(DataItem) -> any()`

Verify the data item's signature.

<a name="verify_data_item_tags-1"></a>

### verify_data_item_tags/1 * ###

`verify_data_item_tags(DataItem) -> any()`

Verify the validity of the data item's tags.

<a name="verify_item-1"></a>

### verify_item/1 ###

`verify_item(DataItem) -> any()`

Verify the validity of a data item.


--- END OF FILE: docs/resources/source-code/ar_bundles.md ---

--- START OF FILE: docs/resources/source-code/ar_deep_hash.md ---
# [Module ar_deep_hash.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/ar_deep_hash.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#hash-1">hash/1</a></td><td></td></tr><tr><td valign="top"><a href="#hash_bin-1">hash_bin/1*</a></td><td></td></tr><tr><td valign="top"><a href="#hash_bin_or_list-1">hash_bin_or_list/1*</a></td><td></td></tr><tr><td valign="top"><a href="#hash_list-2">hash_list/2*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="hash-1"></a>

### hash/1 ###

`hash(List) -> any()`

<a name="hash_bin-1"></a>

### hash_bin/1 * ###

`hash_bin(Bin) -> any()`

<a name="hash_bin_or_list-1"></a>

### hash_bin_or_list/1 * ###

`hash_bin_or_list(Bin) -> any()`

<a name="hash_list-2"></a>

### hash_list/2 * ###

`hash_list(List, Acc) -> any()`


--- END OF FILE: docs/resources/source-code/ar_deep_hash.md ---

--- START OF FILE: docs/resources/source-code/ar_rate_limiter.md ---
# [Module ar_rate_limiter.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/ar_rate_limiter.erl)




__Behaviours:__ [`gen_server`](gen_server.md).

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#cut_trace-4">cut_trace/4*</a></td><td></td></tr><tr><td valign="top"><a href="#handle_call-3">handle_call/3</a></td><td></td></tr><tr><td valign="top"><a href="#handle_cast-2">handle_cast/2</a></td><td></td></tr><tr><td valign="top"><a href="#handle_info-2">handle_info/2</a></td><td></td></tr><tr><td valign="top"><a href="#init-1">init/1</a></td><td></td></tr><tr><td valign="top"><a href="#off-0">off/0</a></td><td>Turn rate limiting off.</td></tr><tr><td valign="top"><a href="#on-0">on/0</a></td><td>Turn rate limiting on.</td></tr><tr><td valign="top"><a href="#start_link-1">start_link/1</a></td><td></td></tr><tr><td valign="top"><a href="#terminate-2">terminate/2</a></td><td></td></tr><tr><td valign="top"><a href="#throttle-3">throttle/3</a></td><td>Hang until it is safe to make another request to the given Peer with the
given Path.</td></tr><tr><td valign="top"><a href="#throttle2-3">throttle2/3*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="cut_trace-4"></a>

### cut_trace/4 * ###

`cut_trace(N, Trace, Now, Opts) -> any()`

<a name="handle_call-3"></a>

### handle_call/3 ###

`handle_call(Request, From, State) -> any()`

<a name="handle_cast-2"></a>

### handle_cast/2 ###

`handle_cast(Cast, State) -> any()`

<a name="handle_info-2"></a>

### handle_info/2 ###

`handle_info(Message, State) -> any()`

<a name="init-1"></a>

### init/1 ###

`init(Opts) -> any()`

<a name="off-0"></a>

### off/0 ###

`off() -> any()`

Turn rate limiting off.

<a name="on-0"></a>

### on/0 ###

`on() -> any()`

Turn rate limiting on.

<a name="start_link-1"></a>

### start_link/1 ###

`start_link(Opts) -> any()`

<a name="terminate-2"></a>

### terminate/2 ###

`terminate(Reason, State) -> any()`

<a name="throttle-3"></a>

### throttle/3 ###

`throttle(Peer, Path, Opts) -> any()`

Hang until it is safe to make another request to the given Peer with the
given Path. The limits are configured in include/ar_blacklist_middleware.hrl.

<a name="throttle2-3"></a>

### throttle2/3 * ###

`throttle2(Peer, Path, Opts) -> any()`


--- END OF FILE: docs/resources/source-code/ar_rate_limiter.md ---

--- START OF FILE: docs/resources/source-code/ar_timestamp.md ---
# [Module ar_timestamp.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/ar_timestamp.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#cache-1">cache/1*</a></td><td>Cache the current timestamp from Arweave.</td></tr><tr><td valign="top"><a href="#get-0">get/0</a></td><td>Get the current timestamp from the server, starting the server if it
isn't already running.</td></tr><tr><td valign="top"><a href="#refresher-1">refresher/1*</a></td><td>Refresh the timestamp cache periodically.</td></tr><tr><td valign="top"><a href="#spawn_server-0">spawn_server/0*</a></td><td>Spawn a new server and its refresher.</td></tr><tr><td valign="top"><a href="#start-0">start/0</a></td><td>Check if the server is already running, and if not, start it.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="cache-1"></a>

### cache/1 * ###

`cache(Current) -> any()`

Cache the current timestamp from Arweave.

<a name="get-0"></a>

### get/0 ###

`get() -> any()`

Get the current timestamp from the server, starting the server if it
isn't already running.

<a name="refresher-1"></a>

### refresher/1 * ###

`refresher(TSServer) -> any()`

Refresh the timestamp cache periodically.

<a name="spawn_server-0"></a>

### spawn_server/0 * ###

`spawn_server() -> any()`

Spawn a new server and its refresher.

<a name="start-0"></a>

### start/0 ###

`start() -> any()`

Check if the server is already running, and if not, start it.


--- END OF FILE: docs/resources/source-code/ar_timestamp.md ---

--- START OF FILE: docs/resources/source-code/ar_tx.md ---
# [Module ar_tx.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/ar_tx.erl)




The module with utilities for transaction creation, signing, and verification.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#collect_validation_results-2">collect_validation_results/2*</a></td><td></td></tr><tr><td valign="top"><a href="#do_verify-2">do_verify/2*</a></td><td>Verify transaction.</td></tr><tr><td valign="top"><a href="#json_struct_to_tx-1">json_struct_to_tx/1</a></td><td></td></tr><tr><td valign="top"><a href="#new-4">new/4</a></td><td>Create a new transaction.</td></tr><tr><td valign="top"><a href="#new-5">new/5</a></td><td></td></tr><tr><td valign="top"><a href="#sign-2">sign/2</a></td><td>Cryptographically sign (claim ownership of) a transaction.</td></tr><tr><td valign="top"><a href="#signature_data_segment-1">signature_data_segment/1*</a></td><td>Generate the data segment to be signed for a given TX.</td></tr><tr><td valign="top"><a href="#tx_to_json_struct-1">tx_to_json_struct/1</a></td><td></td></tr><tr><td valign="top"><a href="#verify-1">verify/1</a></td><td>Verify whether a transaction is valid.</td></tr><tr><td valign="top"><a href="#verify_hash-1">verify_hash/1*</a></td><td>Verify that the transaction's ID is a hash of its signature.</td></tr><tr><td valign="top"><a href="#verify_signature-2">verify_signature/2*</a></td><td>Verify the transaction's signature.</td></tr><tr><td valign="top"><a href="#verify_tx_id-2">verify_tx_id/2</a></td><td>Verify the given transaction actually has the given identifier.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="collect_validation_results-2"></a>

### collect_validation_results/2 * ###

`collect_validation_results(TXID, Checks) -> any()`

<a name="do_verify-2"></a>

### do_verify/2 * ###

`do_verify(TX, VerifySignature) -> any()`

Verify transaction.

<a name="json_struct_to_tx-1"></a>

### json_struct_to_tx/1 ###

`json_struct_to_tx(TXStruct) -> any()`

<a name="new-4"></a>

### new/4 ###

`new(Dest, Reward, Qty, Last) -> any()`

Create a new transaction.

<a name="new-5"></a>

### new/5 ###

`new(Dest, Reward, Qty, Last, SigType) -> any()`

<a name="sign-2"></a>

### sign/2 ###

`sign(TX, X2) -> any()`

Cryptographically sign (claim ownership of) a transaction.

<a name="signature_data_segment-1"></a>

### signature_data_segment/1 * ###

`signature_data_segment(TX) -> any()`

Generate the data segment to be signed for a given TX.

<a name="tx_to_json_struct-1"></a>

### tx_to_json_struct/1 ###

`tx_to_json_struct(Tx) -> any()`

<a name="verify-1"></a>

### verify/1 ###

`verify(TX) -> any()`

Verify whether a transaction is valid.

<a name="verify_hash-1"></a>

### verify_hash/1 * ###

`verify_hash(Tx) -> any()`

Verify that the transaction's ID is a hash of its signature.

<a name="verify_signature-2"></a>

### verify_signature/2 * ###

`verify_signature(TX, X2) -> any()`

Verify the transaction's signature.

<a name="verify_tx_id-2"></a>

### verify_tx_id/2 ###

`verify_tx_id(ExpectedID, Tx) -> any()`

Verify the given transaction actually has the given identifier.


--- END OF FILE: docs/resources/source-code/ar_tx.md ---

--- START OF FILE: docs/resources/source-code/ar_wallet.md ---
# [Module ar_wallet.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/ar_wallet.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#compress_ecdsa_pubkey-1">compress_ecdsa_pubkey/1*</a></td><td></td></tr><tr><td valign="top"><a href="#hash_address-1">hash_address/1*</a></td><td></td></tr><tr><td valign="top"><a href="#hmac-1">hmac/1</a></td><td></td></tr><tr><td valign="top"><a href="#hmac-2">hmac/2</a></td><td></td></tr><tr><td valign="top"><a href="#load_key-1">load_key/1</a></td><td>Read the keyfile for the key with the given address from disk.</td></tr><tr><td valign="top"><a href="#load_key-2">load_key/2</a></td><td>Read the keyfile for the key with the given address from disk.</td></tr><tr><td valign="top"><a href="#load_keyfile-1">load_keyfile/1</a></td><td>Extract the public and private key from a keyfile.</td></tr><tr><td valign="top"><a href="#load_keyfile-2">load_keyfile/2</a></td><td>Extract the public and private key from a keyfile.</td></tr><tr><td valign="top"><a href="#new-0">new/0</a></td><td></td></tr><tr><td valign="top"><a href="#new-1">new/1</a></td><td></td></tr><tr><td valign="top"><a href="#new_keyfile-2">new_keyfile/2</a></td><td>Generate a new wallet public and private key, with a corresponding keyfile.</td></tr><tr><td valign="top"><a href="#sign-2">sign/2</a></td><td>Sign some data with a private key.</td></tr><tr><td valign="top"><a href="#sign-3">sign/3</a></td><td>sign some data, hashed using the provided DigestType.</td></tr><tr><td valign="top"><a href="#to_address-1">to_address/1</a></td><td>Generate an address from a public key.</td></tr><tr><td valign="top"><a href="#to_address-2">to_address/2</a></td><td></td></tr><tr><td valign="top"><a href="#to_ecdsa_address-1">to_ecdsa_address/1*</a></td><td></td></tr><tr><td valign="top"><a href="#to_pubkey-1">to_pubkey/1</a></td><td>Find a public key from a wallet.</td></tr><tr><td valign="top"><a href="#to_pubkey-2">to_pubkey/2</a></td><td></td></tr><tr><td valign="top"><a href="#to_rsa_address-1">to_rsa_address/1*</a></td><td></td></tr><tr><td valign="top"><a href="#verify-3">verify/3</a></td><td>Verify that a signature is correct.</td></tr><tr><td valign="top"><a href="#verify-4">verify/4</a></td><td></td></tr><tr><td valign="top"><a href="#wallet_filepath-1">wallet_filepath/1*</a></td><td></td></tr><tr><td valign="top"><a href="#wallet_filepath-3">wallet_filepath/3*</a></td><td></td></tr><tr><td valign="top"><a href="#wallet_filepath2-1">wallet_filepath2/1*</a></td><td></td></tr><tr><td valign="top"><a href="#wallet_name-3">wallet_name/3*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="compress_ecdsa_pubkey-1"></a>

### compress_ecdsa_pubkey/1 * ###

`compress_ecdsa_pubkey(X1) -> any()`

<a name="hash_address-1"></a>

### hash_address/1 * ###

`hash_address(PubKey) -> any()`

<a name="hmac-1"></a>

### hmac/1 ###

`hmac(Data) -> any()`

<a name="hmac-2"></a>

### hmac/2 ###

`hmac(Data, DigestType) -> any()`

<a name="load_key-1"></a>

### load_key/1 ###

`load_key(Addr) -> any()`

Read the keyfile for the key with the given address from disk.
Return not_found if arweave_keyfile_[addr].json or [addr].json is not found
in [data_dir]/?WALLET_DIR.

<a name="load_key-2"></a>

### load_key/2 ###

`load_key(Addr, Opts) -> any()`

Read the keyfile for the key with the given address from disk.
Return not_found if arweave_keyfile_[addr].json or [addr].json is not found
in [data_dir]/?WALLET_DIR.

<a name="load_keyfile-1"></a>

### load_keyfile/1 ###

`load_keyfile(File) -> any()`

Extract the public and private key from a keyfile.

<a name="load_keyfile-2"></a>

### load_keyfile/2 ###

`load_keyfile(File, Opts) -> any()`

Extract the public and private key from a keyfile.

<a name="new-0"></a>

### new/0 ###

`new() -> any()`

<a name="new-1"></a>

### new/1 ###

`new(KeyType) -> any()`

<a name="new_keyfile-2"></a>

### new_keyfile/2 ###

`new_keyfile(KeyType, WalletName) -> any()`

Generate a new wallet public and private key, with a corresponding keyfile.
The provided key is used as part of the file name.

<a name="sign-2"></a>

### sign/2 ###

`sign(Key, Data) -> any()`

Sign some data with a private key.

<a name="sign-3"></a>

### sign/3 ###

`sign(X1, Data, DigestType) -> any()`

sign some data, hashed using the provided DigestType.

<a name="to_address-1"></a>

### to_address/1 ###

`to_address(Pubkey) -> any()`

Generate an address from a public key.

<a name="to_address-2"></a>

### to_address/2 ###

`to_address(PubKey, X2) -> any()`

<a name="to_ecdsa_address-1"></a>

### to_ecdsa_address/1 * ###

`to_ecdsa_address(PubKey) -> any()`

<a name="to_pubkey-1"></a>

### to_pubkey/1 ###

`to_pubkey(Pubkey) -> any()`

Find a public key from a wallet.

<a name="to_pubkey-2"></a>

### to_pubkey/2 ###

`to_pubkey(PubKey, X2) -> any()`

<a name="to_rsa_address-1"></a>

### to_rsa_address/1 * ###

`to_rsa_address(PubKey) -> any()`

<a name="verify-3"></a>

### verify/3 ###

`verify(Key, Data, Sig) -> any()`

Verify that a signature is correct.

<a name="verify-4"></a>

### verify/4 ###

`verify(X1, Data, Sig, DigestType) -> any()`

<a name="wallet_filepath-1"></a>

### wallet_filepath/1 * ###

`wallet_filepath(Wallet) -> any()`

<a name="wallet_filepath-3"></a>

### wallet_filepath/3 * ###

`wallet_filepath(WalletName, PubKey, KeyType) -> any()`

<a name="wallet_filepath2-1"></a>

### wallet_filepath2/1 * ###

`wallet_filepath2(Wallet) -> any()`

<a name="wallet_name-3"></a>

### wallet_name/3 * ###

`wallet_name(WalletName, PubKey, KeyType) -> any()`


--- END OF FILE: docs/resources/source-code/ar_wallet.md ---

--- START OF FILE: docs/resources/source-code/dev_apply.md ---
# [Module dev_apply.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_apply.erl)




A device that executes AO resolutions.

<a name="description"></a>

## Description ##

It can be passed either a key
that points to a singleton message or list of messages to resolve, or a
`base` and `request` pair to execute together via invoking the `pair` key.

When given a message with a `base` and `request` key, the default handler
will invoke `pair` upon it, setting the `path` in the resulting request to
the key that `apply` was invoked with.

If no `base` or `request` key is present, the default handler will invoke
`eval` upon the given message, using the given key as the `source` of the
message/list of messages to resolve.

Paths found in keys interpreted by this device can contain a `base:` or
`request:` prefix to indicate the message from which the path should be
retrieved. If no such prefix is present, the `Request` message is checked
first, and the `Base` message is checked second.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#apply_over_http_test-0">apply_over_http_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#default-4">default/4*</a></td><td>The default handler.</td></tr><tr><td valign="top"><a href="#error_to_message-1">error_to_message/1*</a></td><td>Convert an error to a message.</td></tr><tr><td valign="top"><a href="#eval-3">eval/3*</a></td><td>Apply the request's <code>source</code> key.</td></tr><tr><td valign="top"><a href="#find_message-4">find_message/4*</a></td><td>Find the value of the source key, supporting <code>base:</code> and <code>request:</code>
prefixes.</td></tr><tr><td valign="top"><a href="#find_path-4">find_path/4*</a></td><td>Resolve the given path on the message as <code>message@1.0</code>.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>The device info.</td></tr><tr><td valign="top"><a href="#normalize_path-1">normalize_path/1*</a></td><td>Normalize the path.</td></tr><tr><td valign="top"><a href="#pair-3">pair/3</a></td><td>Apply the message found at <code>request</code> to the message found at <code>base</code>.</td></tr><tr><td valign="top"><a href="#pair-4">pair/4*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_key_test-0">resolve_key_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_pair_test-0">resolve_pair_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_with_prefix_test-0">resolve_with_prefix_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#reverse_resolve_pair_test-0">reverse_resolve_pair_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="apply_over_http_test-0"></a>

### apply_over_http_test/0 * ###

`apply_over_http_test() -> any()`

<a name="default-4"></a>

### default/4 * ###

`default(Key, Base, Request, Opts) -> any()`

The default handler. If the `base` and `request` keys are present in
the given request, then the `pair` function is called. Otherwise, the `eval`
key is used to resolve the request.

<a name="error_to_message-1"></a>

### error_to_message/1 * ###

`error_to_message(Error) -> any()`

Convert an error to a message.

<a name="eval-3"></a>

### eval/3 * ###

`eval(Base, Request, Opts) -> any()`

Apply the request's `source` key. If this key is invoked as a result
of the default handler, the `source` key is set to the key of the request.

<a name="find_message-4"></a>

### find_message/4 * ###

`find_message(Path, Base, Request, Opts) -> any()`

Find the value of the source key, supporting `base:` and `request:`
prefixes.

<a name="find_path-4"></a>

### find_path/4 * ###

`find_path(Path, Base, Request, Opts) -> any()`

Resolve the given path on the message as `message@1.0`.

<a name="info-1"></a>

### info/1 ###

`info(X1) -> any()`

The device info. Forwards all keys aside `pair`, `keys` and `set` are
resolved with the `apply/4` function.

<a name="normalize_path-1"></a>

### normalize_path/1 * ###

`normalize_path(Path) -> any()`

Normalize the path.

<a name="pair-3"></a>

### pair/3 ###

`pair(Base, Request, Opts) -> any()`

Apply the message found at `request` to the message found at `base`.

<a name="pair-4"></a>

### pair/4 * ###

`pair(PathToSet, Base, Request, Opts) -> any()`

<a name="resolve_key_test-0"></a>

### resolve_key_test/0 * ###

`resolve_key_test() -> any()`

<a name="resolve_pair_test-0"></a>

### resolve_pair_test/0 * ###

`resolve_pair_test() -> any()`

<a name="resolve_with_prefix_test-0"></a>

### resolve_with_prefix_test/0 * ###

`resolve_with_prefix_test() -> any()`

<a name="reverse_resolve_pair_test-0"></a>

### reverse_resolve_pair_test/0 * ###

`reverse_resolve_pair_test() -> any()`


--- END OF FILE: docs/resources/source-code/dev_apply.md ---

--- START OF FILE: docs/resources/source-code/dev_cache.md ---
# [Module dev_cache.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_cache.erl)




A device that looks up an ID from a local store and returns it,
honoring the `accept` key to return the correct format.

<a name="description"></a>

## Description ##
The cache also
supports writing messages to the store, if the node message has the
writer's address in its `cache_writers` key.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#cache_write_binary_test-0">cache_write_binary_test/0*</a></td><td>Ensure that we can write direct binaries to the cache.</td></tr><tr><td valign="top"><a href="#cache_write_message_test-0">cache_write_message_test/0*</a></td><td>Test that the cache can be written to and read from using the hb_cache
API.</td></tr><tr><td valign="top"><a href="#is_trusted_writer-2">is_trusted_writer/2*</a></td><td>Verify that the request originates from a trusted writer.</td></tr><tr><td valign="top"><a href="#link-3">link/3</a></td><td>Link a source to a destination in the cache.</td></tr><tr><td valign="top"><a href="#read-3">read/3</a></td><td>Read data from the cache.</td></tr><tr><td valign="top"><a href="#read_from_cache-2">read_from_cache/2*</a></td><td>Read data from the cache via HTTP.</td></tr><tr><td valign="top"><a href="#setup_test_env-0">setup_test_env/0*</a></td><td>Create a test environment with a local store and node.</td></tr><tr><td valign="top"><a href="#write-3">write/3</a></td><td>Write data to the cache.</td></tr><tr><td valign="top"><a href="#write_single-2">write_single/2*</a></td><td>Helper function to write a single data item to the cache.</td></tr><tr><td valign="top"><a href="#write_to_cache-3">write_to_cache/3*</a></td><td>Write data to the cache via HTTP.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="cache_write_binary_test-0"></a>

### cache_write_binary_test/0 * ###

`cache_write_binary_test() -> any()`

Ensure that we can write direct binaries to the cache.

<a name="cache_write_message_test-0"></a>

### cache_write_message_test/0 * ###

`cache_write_message_test() -> any()`

Test that the cache can be written to and read from using the hb_cache
API.

<a name="is_trusted_writer-2"></a>

### is_trusted_writer/2 * ###

`is_trusted_writer(Req, Opts) -> any()`

Verify that the request originates from a trusted writer.
Checks that the single signer of the request is present in the list
of trusted cache writer addresses specified in the options.

<a name="link-3"></a>

### link/3 ###

`link(Base, Req, Opts) -> any()`

Link a source to a destination in the cache.

<a name="read-3"></a>

### read/3 ###

`read(M1, M2, Opts) -> any()`

Read data from the cache.
Retrieves data corresponding to a key from a local store.
The key is extracted from the incoming message under <<"target">>.
The options map may include store configuration.
If the "accept" header is set to <<"application/aos-2">>, the result is
converted to a JSON structure and encoded.

<a name="read_from_cache-2"></a>

### read_from_cache/2 * ###

`read_from_cache(Node, Path) -> any()`

Read data from the cache via HTTP.
Constructs a GET request using the provided path, sends it to the node,
and returns the response.

<a name="setup_test_env-0"></a>

### setup_test_env/0 * ###

`setup_test_env() -> any()`

Create a test environment with a local store and node.
Ensures that the required application is started, configures a local
file-system store, resets the store for a clean state, creates a wallet
for signing requests, and starts a node with the store and trusted cache
writer configuration.

<a name="write-3"></a>

### write/3 ###

`write(M1, M2, Opts) -> any()`

Write data to the cache.
Processes a write request by first verifying that the request comes from a
trusted writer (as defined by the `cache_writers` configuration in the
options). The write type is determined from the message ("single" or "batch")
and the data is stored accordingly.

<a name="write_single-2"></a>

### write_single/2 * ###

`write_single(Msg, Opts) -> any()`

Helper function to write a single data item to the cache.
Extracts the body, location, and operation from the message.
Depending on the type of data (map or binary) or if a link operation is
requested, it writes the data to the store using the appropriate function.

<a name="write_to_cache-3"></a>

### write_to_cache/3 * ###

`write_to_cache(Node, Data, Wallet) -> any()`

Write data to the cache via HTTP.
Constructs a write request message with the provided data, signs it with the
given wallet, sends it to the node, and verifies that the response indicates
a successful write.


--- END OF FILE: docs/resources/source-code/dev_cache.md ---

--- START OF FILE: docs/resources/source-code/dev_cacheviz.md ---
# [Module dev_cacheviz.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_cacheviz.erl)




A device that generates renders (or renderable dot output) of a node's
cache.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#dot-3">dot/3</a></td><td>Output the dot representation of the cache, or a specific path within
the cache set by the <code>target</code> key in the request.</td></tr><tr><td valign="top"><a href="#index-3">index/3</a></td><td>Return a renderer in HTML form for the JSON format.</td></tr><tr><td valign="top"><a href="#js-3">js/3</a></td><td>Return a JS library that can be used to render the JSON format.</td></tr><tr><td valign="top"><a href="#json-3">json/3</a></td><td>Return a JSON representation of the cache graph, suitable for use with
the <code>graph.js</code> library.</td></tr><tr><td valign="top"><a href="#svg-3">svg/3</a></td><td>Output the SVG representation of the cache, or a specific path within
the cache set by the <code>target</code> key in the request.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="dot-3"></a>

### dot/3 ###

`dot(X1, Req, Opts) -> any()`

Output the dot representation of the cache, or a specific path within
the cache set by the `target` key in the request.

<a name="index-3"></a>

### index/3 ###

`index(Base, X2, Opts) -> any()`

Return a renderer in HTML form for the JSON format.

<a name="js-3"></a>

### js/3 ###

`js(X1, X2, Opts) -> any()`

Return a JS library that can be used to render the JSON format.

<a name="json-3"></a>

### json/3 ###

`json(Base, Req, Opts) -> any()`

Return a JSON representation of the cache graph, suitable for use with
the `graph.js` library. If the request specifies a `target` key, we use that
target. Otherwise, we generate a new target by writing the message to the
cache and using the ID of the written message.

<a name="svg-3"></a>

### svg/3 ###

`svg(Base, Req, Opts) -> any()`

Output the SVG representation of the cache, or a specific path within
the cache set by the `target` key in the request.


--- END OF FILE: docs/resources/source-code/dev_cacheviz.md ---

--- START OF FILE: docs/resources/source-code/dev_codec_ans104.md ---
# [Module dev_codec_ans104.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_codec_ans104.erl)




Codec for managing transformations from `ar_bundles`-style Arweave TX
records to and from TABMs.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#commit-3">commit/3</a></td><td>Sign a message using the <code>priv_wallet</code> key in the options.</td></tr><tr><td valign="top"><a href="#content_type-1">content_type/1</a></td><td>Return the content type for the codec.</td></tr><tr><td valign="top"><a href="#deduplicating_from_list-2">deduplicating_from_list/2*</a></td><td>Deduplicate a list of key-value pairs by key, generating a list of
values for each normalized key if there are duplicates.</td></tr><tr><td valign="top"><a href="#deserialize-3">deserialize/3</a></td><td>Deserialize a binary ans104 message to a TABM.</td></tr><tr><td valign="top"><a href="#do_from-3">do_from/3*</a></td><td></td></tr><tr><td valign="top"><a href="#encoded_tags_to_map-1">encoded_tags_to_map/1*</a></td><td>Convert an ANS-104 encoded tag list into a HyperBEAM-compatible map.</td></tr><tr><td valign="top"><a href="#from-3">from/3</a></td><td>Convert a #tx record into a message map recursively.</td></tr><tr><td valign="top"><a href="#from_maintains_tag_name_case_test-0">from_maintains_tag_name_case_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#normal_tags-1">normal_tags/1*</a></td><td>Check whether a list of key-value pairs contains only normalized keys.</td></tr><tr><td valign="top"><a href="#normal_tags_test-0">normal_tags_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#only_committed_maintains_target_test-0">only_committed_maintains_target_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#restore_tag_name_case_from_cache_test-0">restore_tag_name_case_from_cache_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#serialize-3">serialize/3</a></td><td>Serialize a message or TX to a binary.</td></tr><tr><td valign="top"><a href="#signed_duplicated_tag_name_test-0">signed_duplicated_tag_name_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#simple_signed_to_httpsig_test_disabled-0">simple_signed_to_httpsig_test_disabled/0*</a></td><td></td></tr><tr><td valign="top"><a href="#simple_to_conversion_test-0">simple_to_conversion_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#tag_map_to_encoded_tags-1">tag_map_to_encoded_tags/1*</a></td><td>Convert a HyperBEAM-compatible map into an ANS-104 encoded tag list,
recreating the original order of the tags.</td></tr><tr><td valign="top"><a href="#to-3">to/3</a></td><td>Internal helper to translate a message to its #tx record representation,
which can then be used by ar_bundles to serialize the message.</td></tr><tr><td valign="top"><a href="#type_tag_test-0">type_tag_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#unsigned_duplicated_tag_name_test-0">unsigned_duplicated_tag_name_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#verify-3">verify/3</a></td><td>Verify an ANS-104 commitment.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="commit-3"></a>

### commit/3 ###

`commit(Msg, Req, Opts) -> any()`

Sign a message using the `priv_wallet` key in the options. Supports both
the `hmac-sha256` and `rsa-pss-sha256` algorithms, offering unsigned and
signed commitments.

<a name="content_type-1"></a>

### content_type/1 ###

`content_type(X1) -> any()`

Return the content type for the codec.

<a name="deduplicating_from_list-2"></a>

### deduplicating_from_list/2 * ###

`deduplicating_from_list(Tags, Opts) -> any()`

Deduplicate a list of key-value pairs by key, generating a list of
values for each normalized key if there are duplicates.

<a name="deserialize-3"></a>

### deserialize/3 ###

`deserialize(Binary, Req, Opts) -> any()`

Deserialize a binary ans104 message to a TABM.

<a name="do_from-3"></a>

### do_from/3 * ###

`do_from(RawTX, Req, Opts) -> any()`

<a name="encoded_tags_to_map-1"></a>

### encoded_tags_to_map/1 * ###

`encoded_tags_to_map(Tags) -> any()`

Convert an ANS-104 encoded tag list into a HyperBEAM-compatible map.

<a name="from-3"></a>

### from/3 ###

`from(Binary, Req, Opts) -> any()`

Convert a #tx record into a message map recursively.

<a name="from_maintains_tag_name_case_test-0"></a>

### from_maintains_tag_name_case_test/0 * ###

`from_maintains_tag_name_case_test() -> any()`

<a name="normal_tags-1"></a>

### normal_tags/1 * ###

`normal_tags(Tags) -> any()`

Check whether a list of key-value pairs contains only normalized keys.

<a name="normal_tags_test-0"></a>

### normal_tags_test/0 * ###

`normal_tags_test() -> any()`

<a name="only_committed_maintains_target_test-0"></a>

### only_committed_maintains_target_test/0 * ###

`only_committed_maintains_target_test() -> any()`

<a name="restore_tag_name_case_from_cache_test-0"></a>

### restore_tag_name_case_from_cache_test/0 * ###

`restore_tag_name_case_from_cache_test() -> any()`

<a name="serialize-3"></a>

### serialize/3 ###

`serialize(Msg, Req, Opts) -> any()`

Serialize a message or TX to a binary.

<a name="signed_duplicated_tag_name_test-0"></a>

### signed_duplicated_tag_name_test/0 * ###

`signed_duplicated_tag_name_test() -> any()`

<a name="simple_signed_to_httpsig_test_disabled-0"></a>

### simple_signed_to_httpsig_test_disabled/0 * ###

`simple_signed_to_httpsig_test_disabled() -> any()`

<a name="simple_to_conversion_test-0"></a>

### simple_to_conversion_test/0 * ###

`simple_to_conversion_test() -> any()`

<a name="tag_map_to_encoded_tags-1"></a>

### tag_map_to_encoded_tags/1 * ###

`tag_map_to_encoded_tags(TagMap) -> any()`

Convert a HyperBEAM-compatible map into an ANS-104 encoded tag list,
recreating the original order of the tags.

<a name="to-3"></a>

### to/3 ###

`to(Binary, Req, Opts) -> any()`

Internal helper to translate a message to its #tx record representation,
which can then be used by ar_bundles to serialize the message. We call the
message's device in order to get the keys that we will be checkpointing. We
do this recursively to handle nested messages. The base case is that we hit
a binary, which we return as is.

<a name="type_tag_test-0"></a>

### type_tag_test/0 * ###

`type_tag_test() -> any()`

<a name="unsigned_duplicated_tag_name_test-0"></a>

### unsigned_duplicated_tag_name_test/0 * ###

`unsigned_duplicated_tag_name_test() -> any()`

<a name="verify-3"></a>

### verify/3 ###

`verify(Msg, Req, Opts) -> any()`

Verify an ANS-104 commitment.


--- END OF FILE: docs/resources/source-code/dev_codec_ans104.md ---

--- START OF FILE: docs/resources/source-code/dev_codec_flat.md ---
# [Module dev_codec_flat.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_codec_flat.erl)




A codec for turning TABMs into/from flat Erlang maps that have
(potentially multi-layer) paths as their keys, and a normal TABM binary as
their value.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#binary_passthrough_test-0">binary_passthrough_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#commit-3">commit/3</a></td><td></td></tr><tr><td valign="top"><a href="#deep_nesting_test-0">deep_nesting_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#deserialize-1">deserialize/1</a></td><td></td></tr><tr><td valign="top"><a href="#empty_map_test-0">empty_map_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#from-3">from/3</a></td><td>Convert a flat map to a TABM.</td></tr><tr><td valign="top"><a href="#inject_at_path-3">inject_at_path/3*</a></td><td></td></tr><tr><td valign="top"><a href="#inject_at_path-4">inject_at_path/4*</a></td><td></td></tr><tr><td valign="top"><a href="#multiple_paths_test-0">multiple_paths_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#nested_conversion_test-0">nested_conversion_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#path_list_test-0">path_list_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#serialize-1">serialize/1</a></td><td></td></tr><tr><td valign="top"><a href="#serialize-2">serialize/2</a></td><td></td></tr><tr><td valign="top"><a href="#simple_conversion_test-0">simple_conversion_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to-3">to/3</a></td><td>Convert a TABM to a flat map.</td></tr><tr><td valign="top"><a href="#verify-3">verify/3</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="binary_passthrough_test-0"></a>

### binary_passthrough_test/0 * ###

`binary_passthrough_test() -> any()`

<a name="commit-3"></a>

### commit/3 ###

`commit(Msg, Req, Opts) -> any()`

<a name="deep_nesting_test-0"></a>

### deep_nesting_test/0 * ###

`deep_nesting_test() -> any()`

<a name="deserialize-1"></a>

### deserialize/1 ###

`deserialize(Bin) -> any()`

<a name="empty_map_test-0"></a>

### empty_map_test/0 * ###

`empty_map_test() -> any()`

<a name="from-3"></a>

### from/3 ###

`from(Bin, Req, Opts) -> any()`

Convert a flat map to a TABM.

<a name="inject_at_path-3"></a>

### inject_at_path/3 * ###

`inject_at_path(Rest, Value, Map) -> any()`

<a name="inject_at_path-4"></a>

### inject_at_path/4 * ###

`inject_at_path(Rest, Value, Map, Opts) -> any()`

<a name="multiple_paths_test-0"></a>

### multiple_paths_test/0 * ###

`multiple_paths_test() -> any()`

<a name="nested_conversion_test-0"></a>

### nested_conversion_test/0 * ###

`nested_conversion_test() -> any()`

<a name="path_list_test-0"></a>

### path_list_test/0 * ###

`path_list_test() -> any()`

<a name="serialize-1"></a>

### serialize/1 ###

`serialize(Map) -> any()`

<a name="serialize-2"></a>

### serialize/2 ###

`serialize(Map, Opts) -> any()`

<a name="simple_conversion_test-0"></a>

### simple_conversion_test/0 * ###

`simple_conversion_test() -> any()`

<a name="to-3"></a>

### to/3 ###

`to(Bin, Req, Opts) -> any()`

Convert a TABM to a flat map.

<a name="verify-3"></a>

### verify/3 ###

`verify(Msg, Req, Opts) -> any()`


--- END OF FILE: docs/resources/source-code/dev_codec_flat.md ---

--- START OF FILE: docs/resources/source-code/dev_codec_httpsig_conv.md ---
# [Module dev_codec_httpsig_conv.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_codec_httpsig_conv.erl)




A codec that marshals TABM encoded messages to and from the "HTTP"
message structure.

<a name="description"></a>

## Description ##

Every HTTP message is an HTTP multipart message.
See https://datatracker.ietf.org/doc/html/rfc7578

For each TABM Key:

The Key/Value Pair will be encoded according to the following rules:
"signatures" -> {SignatureInput, Signature} header Tuples, each encoded
as a Structured Field Dictionary
"body" ->
- if a map, then recursively encode as its own HyperBEAM message
- otherwise encode as a normal field
_ -> encode as a normal field

Each field will be mapped to the HTTP Message according to the following
rules:
"body" -> always encoded part of the body as with Content-Disposition
type of "inline"
_ ->
- If the byte size of the value is less than the ?MAX_TAG_VALUE,
then encode as a header, also attempting to encode as a
structured field.
- Otherwise encode the value as a part in the multipart response
<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#body_to_parts-3">body_to_parts/3*</a></td><td>Split the body into parts, if it is a multipart.</td></tr><tr><td valign="top"><a href="#body_to_tabm-2">body_to_tabm/2*</a></td><td>Generate the body TABM from the <code>body</code> key of the encoded message.</td></tr><tr><td valign="top"><a href="#boundary_from_parts-1">boundary_from_parts/1*</a></td><td>Generate a unique, reproducible boundary for the
multipart body, however we cannot use the id of the message as
the boundary, as the id is not known until the message is
encoded.</td></tr><tr><td valign="top"><a href="#do_to-3">do_to/3*</a></td><td></td></tr><tr><td valign="top"><a href="#encode_body_part-4">encode_body_part/4*</a></td><td>Encode a multipart body part to a flat binary.</td></tr><tr><td valign="top"><a href="#encode_http_msg-2">encode_http_msg/2</a></td><td>Encode a HTTP message into a binary.</td></tr><tr><td valign="top"><a href="#encode_message_with_links_test-0">encode_message_with_links_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#field_to_http-3">field_to_http/3*</a></td><td>All maps are encoded into the body of the HTTP message
to be further encoded later.</td></tr><tr><td valign="top"><a href="#from-3">from/3</a></td><td>Convert a HTTP Message into a TABM.</td></tr><tr><td valign="top"><a href="#from_body_part-3">from_body_part/3*</a></td><td>Parse a single part of a multipart body into a TABM.</td></tr><tr><td valign="top"><a href="#group_ids-1">group_ids/1*</a></td><td>Group all elements with:
1.</td></tr><tr><td valign="top"><a href="#group_maps-1">group_maps/1*</a></td><td>Merge maps at the same level, if possible.</td></tr><tr><td valign="top"><a href="#group_maps-4">group_maps/4*</a></td><td></td></tr><tr><td valign="top"><a href="#group_maps_flat_compatible_test-0">group_maps_flat_compatible_test/0*</a></td><td>The grouped maps encoding is a subset of the flat encoding,
where on keys with maps values are flattened.</td></tr><tr><td valign="top"><a href="#group_maps_test-0">group_maps_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#inline_key-1">inline_key/1*</a></td><td>given a message, returns a binary tuple:
- A list of pairs to add to the msg, if any
- the field name for the inlined key.</td></tr><tr><td valign="top"><a href="#inline_key-2">inline_key/2*</a></td><td></td></tr><tr><td valign="top"><a href="#to-3">to/3</a></td><td>Convert a TABM into an HTTP Message.</td></tr><tr><td valign="top"><a href="#to-4">to/4*</a></td><td></td></tr><tr><td valign="top"><a href="#ungroup_ids-2">ungroup_ids/2*</a></td><td>Decode the <code>ao-ids</code> key into a map.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="body_to_parts-3"></a>

### body_to_parts/3 * ###

`body_to_parts(ContentType, Body, Opts) -> any()`

Split the body into parts, if it is a multipart.

<a name="body_to_tabm-2"></a>

### body_to_tabm/2 * ###

`body_to_tabm(HTTP, Opts) -> any()`

Generate the body TABM from the `body` key of the encoded message.

<a name="boundary_from_parts-1"></a>

### boundary_from_parts/1 * ###

`boundary_from_parts(PartList) -> any()`

Generate a unique, reproducible boundary for the
multipart body, however we cannot use the id of the message as
the boundary, as the id is not known until the message is
encoded. Subsequently, we generate each body part individually,
concatenate them, and apply a SHA2-256 hash to the result.
This ensures that the boundary is unique, reproducible, and
secure.

<a name="do_to-3"></a>

### do_to/3 * ###

`do_to(Binary, FormatOpts, Opts) -> any()`

<a name="encode_body_part-4"></a>

### encode_body_part/4 * ###

`encode_body_part(PartName, BodyPart, InlineKey, Opts) -> any()`

Encode a multipart body part to a flat binary.

<a name="encode_http_msg-2"></a>

### encode_http_msg/2 ###

`encode_http_msg(Msg, Opts) -> any()`

Encode a HTTP message into a binary.

<a name="encode_message_with_links_test-0"></a>

### encode_message_with_links_test/0 * ###

`encode_message_with_links_test() -> any()`

<a name="field_to_http-3"></a>

### field_to_http/3 * ###

`field_to_http(Httpsig, X2, Opts) -> any()`

All maps are encoded into the body of the HTTP message
to be further encoded later.

<a name="from-3"></a>

### from/3 ###

`from(Bin, Req, Opts) -> any()`

Convert a HTTP Message into a TABM.
HTTP Structured Field is encoded into it's equivalent TABM encoding.

<a name="from_body_part-3"></a>

### from_body_part/3 * ###

`from_body_part(InlinedKey, Part, Opts) -> any()`

Parse a single part of a multipart body into a TABM.

<a name="group_ids-1"></a>

### group_ids/1 * ###

`group_ids(Map) -> any()`

Group all elements with:
1. A key that ?IS_ID returns true for, and
2. A value that is immediate
into a combined SF dict-_like_ structure. If not encoded, these keys would
be sent as headers and lower-cased, losing their comparability against the
original keys. The structure follows all SF dict rules, except that it allows
for keys to contain capitals. The HyperBEAM SF parser will accept these keys,
but standard RFC 8741 parsers will not. Subsequently, the resulting `ao-cased`
key is not added to the `ao-types` map.

<a name="group_maps-1"></a>

### group_maps/1 * ###

`group_maps(Map) -> any()`

Merge maps at the same level, if possible.

<a name="group_maps-4"></a>

### group_maps/4 * ###

`group_maps(Map, Parent, Top, Opts) -> any()`

<a name="group_maps_flat_compatible_test-0"></a>

### group_maps_flat_compatible_test/0 * ###

`group_maps_flat_compatible_test() -> any()`

The grouped maps encoding is a subset of the flat encoding,
where on keys with maps values are flattened.

So despite needing a special encoder to produce it
We can simply apply the flat encoder to it to get back
the original message.

The test asserts that is indeed the case.

<a name="group_maps_test-0"></a>

### group_maps_test/0 * ###

`group_maps_test() -> any()`

<a name="inline_key-1"></a>

### inline_key/1 * ###

`inline_key(Msg) -> any()`

given a message, returns a binary tuple:
- A list of pairs to add to the msg, if any
- the field name for the inlined key

In order to preserve the field name of the inlined
part, an additional field may need to be added

<a name="inline_key-2"></a>

### inline_key/2 * ###

`inline_key(Msg, Opts) -> any()`

<a name="to-3"></a>

### to/3 ###

`to(TABM, Req, Opts) -> any()`

Convert a TABM into an HTTP Message. The HTTP Message is a simple Erlang Map
that can translated to a given web server Response API

<a name="to-4"></a>

### to/4 * ###

`to(Bin, Req, FormatOpts, Opts) -> any()`

<a name="ungroup_ids-2"></a>

### ungroup_ids/2 * ###

`ungroup_ids(Msg, Opts) -> any()`

Decode the `ao-ids` key into a map.


--- END OF FILE: docs/resources/source-code/dev_codec_httpsig_conv.md ---

--- START OF FILE: docs/resources/source-code/dev_codec_httpsig_siginfo.md ---
# [Module dev_codec_httpsig_siginfo.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_codec_httpsig_siginfo.erl)




A module for converting between commitments and their encoded `signature`
and `signature-input` keys.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_derived_specifiers-1">add_derived_specifiers/1</a></td><td>Normalize key parameters to ensure their names are correct for inclusion
in the <code>signature-input</code> and associated keys.</td></tr><tr><td valign="top"><a href="#commitment_to_alg-2">commitment_to_alg/2*</a></td><td>Calculate an <code>alg</code> string from a commitment message, using its
<code>commitment-device</code> and optionally, its <code>type</code> key.</td></tr><tr><td valign="top"><a href="#commitment_to_device_specifiers-2">commitment_to_device_specifiers/2*</a></td><td>Convert an <code>alg</code> to a commitment device.</td></tr><tr><td valign="top"><a href="#commitment_to_sf_siginfo-3">commitment_to_sf_siginfo/3*</a></td><td>Generate a <code>signature</code> and <code>signature-input</code> key pair from a given
commitment.</td></tr><tr><td valign="top"><a href="#commitment_to_sig_name-1">commitment_to_sig_name/1</a></td><td>Generate a signature name from a commitment.</td></tr><tr><td valign="top"><a href="#commitments_to_siginfo-3">commitments_to_siginfo/3</a></td><td>Generate a <code>signature</code> and <code>signature-input</code> key pair from a commitment
map.</td></tr><tr><td valign="top"><a href="#committed_keys_to_siginfo-1">committed_keys_to_siginfo/1</a></td><td>Convert committed keys to their siginfo format.</td></tr><tr><td valign="top"><a href="#decoding_nested_map_binary-1">decoding_nested_map_binary/1*</a></td><td></td></tr><tr><td valign="top"><a href="#from_siginfo_keys-3">from_siginfo_keys/3</a></td><td>Normalize a list of <code>httpsig@1.0</code> keys to their equivalents in AO-Core
format.</td></tr><tr><td valign="top"><a href="#get_additional_params-1">get_additional_params/1*</a></td><td></td></tr><tr><td valign="top"><a href="#nested_map_to_string-1">nested_map_to_string/1*</a></td><td></td></tr><tr><td valign="top"><a href="#remove_derived_specifiers-1">remove_derived_specifiers/1</a></td><td>Remove derived specifiers from a list of component identifiers.</td></tr><tr><td valign="top"><a href="#sf_siginfo_to_commitment-5">sf_siginfo_to_commitment/5*</a></td><td>Take a signature and signature-input as parsed structured-fields and
return a commitment.</td></tr><tr><td valign="top"><a href="#siginfo_to_commitments-3">siginfo_to_commitments/3</a></td><td>Take a message with a <code>signature</code> and <code>signature-input</code> key pair and
return a map of commitments.</td></tr><tr><td valign="top"><a href="#to_siginfo_keys-3">to_siginfo_keys/3</a></td><td>Normalize a list of AO-Core keys to their equivalents in <code>httpsig@1.0</code>
format.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_derived_specifiers-1"></a>

### add_derived_specifiers/1 ###

`add_derived_specifiers(ComponentIdentifiers) -> any()`

Normalize key parameters to ensure their names are correct for inclusion
in the `signature-input` and associated keys.

<a name="commitment_to_alg-2"></a>

### commitment_to_alg/2 * ###

`commitment_to_alg(Commitment, Opts) -> any()`

Calculate an `alg` string from a commitment message, using its
`commitment-device` and optionally, its `type` key.

<a name="commitment_to_device_specifiers-2"></a>

### commitment_to_device_specifiers/2 * ###

`commitment_to_device_specifiers(Commitment, Opts) -> any()`

Convert an `alg` to a commitment device. If the `alg` has the form of
a device specifier (`x@y.z...[/type]`), return the device. Otherwise, we
assume that the `alg` is a `type` of the `httpsig@1.0` algorithm.
`type` is an optional key that allows for subtyping of the algorithm. When
provided, in the `alg` it is parsed and returned as the `type` key in the
commitment message.

<a name="commitment_to_sf_siginfo-3"></a>

### commitment_to_sf_siginfo/3 * ###

`commitment_to_sf_siginfo(Msg, Commitment, Opts) -> any()`

Generate a `signature` and `signature-input` key pair from a given
commitment.

<a name="commitment_to_sig_name-1"></a>

### commitment_to_sig_name/1 ###

`commitment_to_sig_name(Commitment) -> any()`

Generate a signature name from a commitment. The commitment message is
not expected to be complete: Only the `commitment-device`, and the
`committer` or `keyid` keys are required.

<a name="commitments_to_siginfo-3"></a>

### commitments_to_siginfo/3 ###

`commitments_to_siginfo(Msg, Comms, Opts) -> any()`

Generate a `signature` and `signature-input` key pair from a commitment
map.

<a name="committed_keys_to_siginfo-1"></a>

### committed_keys_to_siginfo/1 ###

`committed_keys_to_siginfo(Msg) -> any()`

Convert committed keys to their siginfo format. This involves removing
the `body` key from the committed keys, if present, and replacing it with
the `content-digest` key.

<a name="decoding_nested_map_binary-1"></a>

### decoding_nested_map_binary/1 * ###

`decoding_nested_map_binary(Bin) -> any()`

<a name="from_siginfo_keys-3"></a>

### from_siginfo_keys/3 ###

`from_siginfo_keys(HTTPEncMsg, BodyKeys, SigInfoCommitted) -> any()`

Normalize a list of `httpsig@1.0` keys to their equivalents in AO-Core
format. There are three stages:
1. Remove the @ prefix from the component identifiers, if present.
2. Replace `content-digest` with the body keys, if present.
3. Replace the `body` key again with the value of the `ao-body-key` key, if
present. This is possible because the keys derived from the body often
contain the `body` key itself.
4. If the `content-type` starts with `multipart/`, we remove it.

<a name="get_additional_params-1"></a>

### get_additional_params/1 * ###

`get_additional_params(Commitment) -> any()`

<a name="nested_map_to_string-1"></a>

### nested_map_to_string/1 * ###

`nested_map_to_string(Map) -> any()`

<a name="remove_derived_specifiers-1"></a>

### remove_derived_specifiers/1 ###

`remove_derived_specifiers(ComponentIdentifiers) -> any()`

Remove derived specifiers from a list of component identifiers.

<a name="sf_siginfo_to_commitment-5"></a>

### sf_siginfo_to_commitment/5 * ###

`sf_siginfo_to_commitment(Msg, BodyKeys, SFSig, SFSigInput, Opts) -> any()`

Take a signature and signature-input as parsed structured-fields and
return a commitment.

<a name="siginfo_to_commitments-3"></a>

### siginfo_to_commitments/3 ###

`siginfo_to_commitments(Msg, BodyKeys, Opts) -> any()`

Take a message with a `signature` and `signature-input` key pair and
return a map of commitments.

<a name="to_siginfo_keys-3"></a>

### to_siginfo_keys/3 ###

`to_siginfo_keys(Msg, Commitment, Opts) -> any()`

Normalize a list of AO-Core keys to their equivalents in `httpsig@1.0`
format. This involves:
- If the HTTPSig message given has an `ao-body-key` key and the committed keys
list contains it, we replace it in the list with the `body` key and add the
`ao-body-key` key.
- If the list contains a `body` key, we replace it with the `content-digest`
key.
- Otherwise, we return the list unchanged.


--- END OF FILE: docs/resources/source-code/dev_codec_httpsig_siginfo.md ---

--- START OF FILE: docs/resources/source-code/dev_codec_httpsig.md ---
# [Module dev_codec_httpsig.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_codec_httpsig.erl)




This module implements HTTP Message Signatures as described in RFC-9421
(https://datatracker.ietf.org/doc/html/rfc9421), as an AO-Core device.

<a name="description"></a>

## Description ##
It implements the codec standard (from/1, to/1), as well as the optional
commitment functions (id/3, sign/3, verify/3). The commitment functions
are found in this module, while the codec functions are relayed to the
`dev_codec_httpsig_conv` module.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_content_digest-2">add_content_digest/2</a></td><td>If the <code>body</code> key is present and a binary, replace it with a
content-digest.</td></tr><tr><td valign="top"><a href="#commit-3">commit/3</a></td><td>Commit to a message using the HTTP-Signature format.</td></tr><tr><td valign="top"><a href="#committed_id_test-0">committed_id_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#from-3">from/3</a></td><td></td></tr><tr><td valign="top"><a href="#key_present-2">key_present/2*</a></td><td>Calculate if a key or its <code>+link</code> TABM variant is present in a message.</td></tr><tr><td valign="top"><a href="#keys_to_commit-3">keys_to_commit/3*</a></td><td>Derive the set of keys to commit to from a <code>commit</code> request and a
base message.</td></tr><tr><td valign="top"><a href="#maybe_bundle_tag_commitment-3">maybe_bundle_tag_commitment/3*</a></td><td>Annotate the commitment with the <code>bundle</code> key if the request contains
it.</td></tr><tr><td valign="top"><a href="#multicommitted_id_test-0">multicommitted_id_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#normalize_for_encoding-3">normalize_for_encoding/3</a></td><td>Given a base message and a commitment, derive the message and commitment
normalized for encoding.</td></tr><tr><td valign="top"><a href="#opts-1">opts/1*</a></td><td>Generate the <code>Opts</code> to use during AO-Core operations in the codec.</td></tr><tr><td valign="top"><a href="#serialize-2">serialize/2</a></td><td>A helper utility for creating a direct encoding of a HTTPSig message.</td></tr><tr><td valign="top"><a href="#serialize-3">serialize/3</a></td><td></td></tr><tr><td valign="top"><a href="#sign_and_verify_link_test-0">sign_and_verify_link_test/0*</a></td><td>Test that we can sign and verify a message with a link.</td></tr><tr><td valign="top"><a href="#signature_base-3">signature_base/3*</a></td><td>create the signature base that will be signed in order to create the
Signature and SignatureInput.</td></tr><tr><td valign="top"><a href="#signature_components_line-3">signature_components_line/3*</a></td><td>Given a list of Component Identifiers and a Request/Response Message
context, create the "signature-base-line" portion of the signature base.</td></tr><tr><td valign="top"><a href="#signature_params_line-2">signature_params_line/2*</a></td><td>construct the "signature-params-line" part of the signature base.</td></tr><tr><td valign="top"><a href="#to-3">to/3</a></td><td></td></tr><tr><td valign="top"><a href="#validate_large_message_from_http_test-0">validate_large_message_from_http_test/0*</a></td><td>Ensure that we can validate a signature on an extremely large and complex
message that is sent over HTTP, signed with the codec.</td></tr><tr><td valign="top"><a href="#verify-3">verify/3</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_content_digest-2"></a>

### add_content_digest/2 ###

`add_content_digest(Msg, Opts) -> any()`

If the `body` key is present and a binary, replace it with a
content-digest.

<a name="commit-3"></a>

### commit/3 ###

`commit(Msg, Req, Opts) -> any()`

Commit to a message using the HTTP-Signature format. We use the `type`
parameter to determine the type of commitment to use. If the `type` parameter
is `signed`, we default to the rsa-pss-sha512 algorithm. If the `type`
parameter is `unsigned`, we default to the hmac-sha256 algorithm.

<a name="committed_id_test-0"></a>

### committed_id_test/0 * ###

`committed_id_test() -> any()`

<a name="from-3"></a>

### from/3 ###

`from(Msg, Req, Opts) -> any()`

<a name="key_present-2"></a>

### key_present/2 * ###

`key_present(Key, Msg) -> any()`

Calculate if a key or its `+link` TABM variant is present in a message.

<a name="keys_to_commit-3"></a>

### keys_to_commit/3 * ###

`keys_to_commit(Base, Req, Opts) -> any()`

Derive the set of keys to commit to from a `commit` request and a
base message.

<a name="maybe_bundle_tag_commitment-3"></a>

### maybe_bundle_tag_commitment/3 * ###

`maybe_bundle_tag_commitment(Commitment, Req, Opts) -> any()`

Annotate the commitment with the `bundle` key if the request contains
it.

<a name="multicommitted_id_test-0"></a>

### multicommitted_id_test/0 * ###

`multicommitted_id_test() -> any()`

<a name="normalize_for_encoding-3"></a>

### normalize_for_encoding/3 ###

`normalize_for_encoding(Msg, Commitment, Opts) -> any()`

Given a base message and a commitment, derive the message and commitment
normalized for encoding.

<a name="opts-1"></a>

### opts/1 * ###

`opts(RawOpts) -> any()`

Generate the `Opts` to use during AO-Core operations in the codec.

<a name="serialize-2"></a>

### serialize/2 ###

`serialize(Msg, Opts) -> any()`

A helper utility for creating a direct encoding of a HTTPSig message.

This function supports two modes of operation:
1. `format: binary`, yielding a raw binary HTTP/1.1-style response that can
either be stored or emitted raw accross a transport medium.
2. `format: components`, yielding a message containing `headers` and `body`
keys, suitable for use in connecting to HTTP-response flows implemented
by other servers.

Optionally, the `index` key can be set to override resolution of the default
index page into HTTP responses that do not contain their own `body` field.

<a name="serialize-3"></a>

### serialize/3 ###

`serialize(Msg, Req, Opts) -> any()`

<a name="sign_and_verify_link_test-0"></a>

### sign_and_verify_link_test/0 * ###

`sign_and_verify_link_test() -> any()`

Test that we can sign and verify a message with a link. We use

<a name="signature_base-3"></a>

### signature_base/3 * ###

`signature_base(EncodedMsg, Commitment, Opts) -> any()`

create the signature base that will be signed in order to create the
Signature and SignatureInput.

This implements a portion of RFC-9421 see:
https://datatracker.ietf.org/doc/html/rfc9421#name-creating-the-signature-base

<a name="signature_components_line-3"></a>

### signature_components_line/3 * ###

`signature_components_line(Req, Commitment, Opts) -> any()`

Given a list of Component Identifiers and a Request/Response Message
context, create the "signature-base-line" portion of the signature base

<a name="signature_params_line-2"></a>

### signature_params_line/2 * ###

`signature_params_line(RawCommitment, Opts) -> any()`

construct the "signature-params-line" part of the signature base.

See https://datatracker.ietf.org/doc/html/rfc9421#section-2.5-7.3.2.4

<a name="to-3"></a>

### to/3 ###

`to(Msg, Req, Opts) -> any()`

<a name="validate_large_message_from_http_test-0"></a>

### validate_large_message_from_http_test/0 * ###

`validate_large_message_from_http_test() -> any()`

Ensure that we can validate a signature on an extremely large and complex
message that is sent over HTTP, signed with the codec.

<a name="verify-3"></a>

### verify/3 ###

`verify(Base, Req, RawOpts) -> any()`


--- END OF FILE: docs/resources/source-code/dev_codec_httpsig.md ---

--- START OF FILE: docs/resources/source-code/dev_codec_json.md ---
# [Module dev_codec_json.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_codec_json.erl)




A simple JSON codec for HyperBEAM's message format.

<a name="description"></a>

## Description ##
Takes a
message as TABM and returns an encoded JSON string representation.
This codec utilizes the httpsig@1.0 codec for signing and verifying.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#commit-3">commit/3</a></td><td></td></tr><tr><td valign="top"><a href="#committed-3">committed/3</a></td><td></td></tr><tr><td valign="top"><a href="#content_type-1">content_type/1</a></td><td>Return the content type for the codec.</td></tr><tr><td valign="top"><a href="#deserialize-3">deserialize/3</a></td><td>Deserialize the JSON string found at the given path.</td></tr><tr><td valign="top"><a href="#from-3">from/3</a></td><td>Decode a JSON string to a message.</td></tr><tr><td valign="top"><a href="#serialize-3">serialize/3</a></td><td>Serialize a message to a JSON string.</td></tr><tr><td valign="top"><a href="#to-3">to/3</a></td><td>Encode a message to a JSON string.</td></tr><tr><td valign="top"><a href="#verify-3">verify/3</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="commit-3"></a>

### commit/3 ###

`commit(Msg, Req, Opts) -> any()`

<a name="committed-3"></a>

### committed/3 ###

`committed(Msg, Req, Opts) -> any()`

<a name="content_type-1"></a>

### content_type/1 ###

`content_type(X1) -> any()`

Return the content type for the codec.

<a name="deserialize-3"></a>

### deserialize/3 ###

`deserialize(Base, Req, Opts) -> any()`

Deserialize the JSON string found at the given path.

<a name="from-3"></a>

### from/3 ###

`from(Map, Req, Opts) -> any()`

Decode a JSON string to a message.

<a name="serialize-3"></a>

### serialize/3 ###

`serialize(Base, Msg, Opts) -> any()`

Serialize a message to a JSON string.

<a name="to-3"></a>

### to/3 ###

`to(Msg, Req, Opts) -> any()`

Encode a message to a JSON string.

<a name="verify-3"></a>

### verify/3 ###

`verify(Msg, Req, Opts) -> any()`


--- END OF FILE: docs/resources/source-code/dev_codec_json.md ---

--- START OF FILE: docs/resources/source-code/dev_codec_structured.md ---
# [Module dev_codec_structured.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_codec_structured.erl)




A device implementing the codec interface (to/1, from/1) for
HyperBEAM's internal, richly typed message format.

<a name="description"></a>

## Description ##

This format mirrors HTTP Structured Fields, aside from its limitations of
compound type depths, as well as limited floating point representations.

As with all AO-Core codecs, its target format (the format it expects to
receive in the `to/1` function, and give in `from/1`) is TABM.

For more details, see the HTTP Structured Fields (RFC-9651) specification.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#commit-3">commit/3</a></td><td></td></tr><tr><td valign="top"><a href="#decode_ao_types-2">decode_ao_types/2</a></td><td>Parse the <code>ao-types</code> field of a TABM and return a map of keys and their
types.</td></tr><tr><td valign="top"><a href="#decode_value-2">decode_value/2</a></td><td>Convert non-binary values to binary for serialization.</td></tr><tr><td valign="top"><a href="#encode_ao_types-2">encode_ao_types/2</a></td><td>Generate an <code>ao-types</code> structured field from a map of keys and their
types.</td></tr><tr><td valign="top"><a href="#encode_value-1">encode_value/1</a></td><td>Convert a term to a binary representation, emitting its type for
serialization as a separate tag.</td></tr><tr><td valign="top"><a href="#from-3">from/3</a></td><td>Convert a rich message into a 'Type-Annotated-Binary-Message' (TABM).</td></tr><tr><td valign="top"><a href="#implicit_keys-1">implicit_keys/1*</a></td><td>Find the implicit keys of a TABM.</td></tr><tr><td valign="top"><a href="#implicit_keys-2">implicit_keys/2</a></td><td></td></tr><tr><td valign="top"><a href="#is_list_from_ao_types-2">is_list_from_ao_types/2</a></td><td>Determine if the <code>ao-types</code> field of a TABM indicates that the message
is a list.</td></tr><tr><td valign="top"><a href="#linkify_mode-2">linkify_mode/2*</a></td><td>Discern the linkify mode from the request and the options.</td></tr><tr><td valign="top"><a href="#list_encoding_test-0">list_encoding_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to-3">to/3</a></td><td>Convert a TABM into a native HyperBEAM message.</td></tr><tr><td valign="top"><a href="#verify-3">verify/3</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="commit-3"></a>

### commit/3 ###

`commit(Msg, Req, Opts) -> any()`

<a name="decode_ao_types-2"></a>

### decode_ao_types/2 ###

`decode_ao_types(Msg, Opts) -> any()`

Parse the `ao-types` field of a TABM and return a map of keys and their
types

<a name="decode_value-2"></a>

### decode_value/2 ###

`decode_value(Type, Value) -> any()`

Convert non-binary values to binary for serialization.

<a name="encode_ao_types-2"></a>

### encode_ao_types/2 ###

`encode_ao_types(Types, Opts) -> any()`

Generate an `ao-types` structured field from a map of keys and their
types.

<a name="encode_value-1"></a>

### encode_value/1 ###

`encode_value(Value) -> any()`

Convert a term to a binary representation, emitting its type for
serialization as a separate tag.

<a name="from-3"></a>

### from/3 ###

`from(Bin, Req, Opts) -> any()`

Convert a rich message into a 'Type-Annotated-Binary-Message' (TABM).

<a name="implicit_keys-1"></a>

### implicit_keys/1 * ###

`implicit_keys(Req) -> any()`

Find the implicit keys of a TABM.

<a name="implicit_keys-2"></a>

### implicit_keys/2 ###

`implicit_keys(Req, Opts) -> any()`

<a name="is_list_from_ao_types-2"></a>

### is_list_from_ao_types/2 ###

`is_list_from_ao_types(Types, Opts) -> any()`

Determine if the `ao-types` field of a TABM indicates that the message
is a list.

<a name="linkify_mode-2"></a>

### linkify_mode/2 * ###

`linkify_mode(Req, Opts) -> any()`

Discern the linkify mode from the request and the options.

<a name="list_encoding_test-0"></a>

### list_encoding_test/0 * ###

`list_encoding_test() -> any()`

<a name="to-3"></a>

### to/3 ###

`to(Bin, Req, Opts) -> any()`

Convert a TABM into a native HyperBEAM message.

<a name="verify-3"></a>

### verify/3 ###

`verify(Msg, Req, Opts) -> any()`


--- END OF FILE: docs/resources/source-code/dev_codec_structured.md ---

--- START OF FILE: docs/resources/source-code/dev_cron.md ---
# [Module dev_cron.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_cron.erl)




A device that inserts new messages into the schedule to allow processes
to passively 'call' themselves without user interaction.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#every-3">every/3</a></td><td>Exported function for scheduling a recurring message.</td></tr><tr><td valign="top"><a href="#every_worker_loop-4">every_worker_loop/4*</a></td><td></td></tr><tr><td valign="top"><a href="#every_worker_loop_test-0">every_worker_loop_test/0*</a></td><td>This test verifies that a recurring task can be scheduled and executed.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Exported function for getting device info.</td></tr><tr><td valign="top"><a href="#info-3">info/3</a></td><td></td></tr><tr><td valign="top"><a href="#once-3">once/3</a></td><td>Exported function for scheduling a one-time message.</td></tr><tr><td valign="top"><a href="#once_executed_test-0">once_executed_test/0*</a></td><td>This test verifies that a one-time task can be scheduled and executed.</td></tr><tr><td valign="top"><a href="#once_worker-3">once_worker/3*</a></td><td>Internal function for scheduling a one-time message.</td></tr><tr><td valign="top"><a href="#parse_time-1">parse_time/1*</a></td><td>Parse a time string into milliseconds.</td></tr><tr><td valign="top"><a href="#stop-3">stop/3</a></td><td>Exported function for stopping a scheduled task.</td></tr><tr><td valign="top"><a href="#stop_every_test-0">stop_every_test/0*</a></td><td>This test verifies that a recurring task can be stopped by
calling the stop function with the task ID.</td></tr><tr><td valign="top"><a href="#stop_once_test-0">stop_once_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_worker-0">test_worker/0*</a></td><td>This is a helper function that is used to test the cron device.</td></tr><tr><td valign="top"><a href="#test_worker-1">test_worker/1*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="every-3"></a>

### every/3 ###

`every(Msg1, Msg2, Opts) -> any()`

Exported function for scheduling a recurring message.

<a name="every_worker_loop-4"></a>

### every_worker_loop/4 * ###

`every_worker_loop(CronPath, Req, Opts, IntervalMillis) -> any()`

<a name="every_worker_loop_test-0"></a>

### every_worker_loop_test/0 * ###

`every_worker_loop_test() -> any()`

This test verifies that a recurring task can be scheduled and executed.

<a name="info-1"></a>

### info/1 ###

`info(X1) -> any()`

Exported function for getting device info.

<a name="info-3"></a>

### info/3 ###

`info(Msg1, Msg2, Opts) -> any()`

<a name="once-3"></a>

### once/3 ###

`once(Msg1, Msg2, Opts) -> any()`

Exported function for scheduling a one-time message.

<a name="once_executed_test-0"></a>

### once_executed_test/0 * ###

`once_executed_test() -> any()`

This test verifies that a one-time task can be scheduled and executed.

<a name="once_worker-3"></a>

### once_worker/3 * ###

`once_worker(Path, Req, Opts) -> any()`

Internal function for scheduling a one-time message.

<a name="parse_time-1"></a>

### parse_time/1 * ###

`parse_time(BinString) -> any()`

Parse a time string into milliseconds.

<a name="stop-3"></a>

### stop/3 ###

`stop(Msg1, Msg2, Opts) -> any()`

Exported function for stopping a scheduled task.

<a name="stop_every_test-0"></a>

### stop_every_test/0 * ###

`stop_every_test() -> any()`

This test verifies that a recurring task can be stopped by
calling the stop function with the task ID.

<a name="stop_once_test-0"></a>

### stop_once_test/0 * ###

`stop_once_test() -> any()`

<a name="test_worker-0"></a>

### test_worker/0 * ###

`test_worker() -> any()`

This is a helper function that is used to test the cron device.
It is used to increment a counter and update the state of the worker.

<a name="test_worker-1"></a>

### test_worker/1 * ###

`test_worker(State) -> any()`


--- END OF FILE: docs/resources/source-code/dev_cron.md ---

--- START OF FILE: docs/resources/source-code/dev_cu.md ---
# [Module dev_cu.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_cu.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#execute-2">execute/2</a></td><td></td></tr><tr><td valign="top"><a href="#push-2">push/2</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="execute-2"></a>

### execute/2 ###

`execute(CarrierMsg, S) -> any()`

<a name="push-2"></a>

### push/2 ###

`push(Msg, S) -> any()`


--- END OF FILE: docs/resources/source-code/dev_cu.md ---

--- START OF FILE: docs/resources/source-code/dev_dedup.md ---
# [Module dev_dedup.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_dedup.erl)




A device that deduplicates messages in an evaluation stream, returning
status `skip` if the message has already been seen.

<a name="description"></a>

## Description ##

This device is typically used to ensure that a message is only executed
once, even if assigned multiple times, upon a `~process@1.0` evaluation.
It can, however, be used in many other contexts.

This device honors the `pass` key if it is present in the message. If so,
it will only run on the first pass. Additionally, the device supports
a `subject-key` key that allows the caller to specify the key whose ID
should be used for deduplication. If the `subject-key` key is not present,
the device will use the `body` of the request as the subject. If the key is
set to `request`, the device will use the entire request itself as the
subject.

This device runs on the first pass of the `compute` key call if executed
in a stack, and not in subsequent passes. Currently the device stores its
list of already seen items in memory, but at some point it will likely make
sense to drop them in the cache.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#dedup_test-0">dedup_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#dedup_with_multipass_test-0">dedup_with_multipass_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#handle-4">handle/4*</a></td><td>Forward the keys and <code>set</code> functions to the message device, handle all
others with deduplication.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="dedup_test-0"></a>

### dedup_test/0 * ###

`dedup_test() -> any()`

<a name="dedup_with_multipass_test-0"></a>

### dedup_with_multipass_test/0 * ###

`dedup_with_multipass_test() -> any()`

<a name="handle-4"></a>

### handle/4 * ###

`handle(Key, M1, M2, Opts) -> any()`

Forward the keys and `set` functions to the message device, handle all
others with deduplication. This allows the device to be used in any context
where a key is called. If the `dedup-key`

<a name="info-1"></a>

### info/1 ###

`info(M1) -> any()`


--- END OF FILE: docs/resources/source-code/dev_dedup.md ---

--- START OF FILE: docs/resources/source-code/dev_delegated_compute.md ---
# [Module dev_delegated_compute.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_delegated_compute.erl)




Simple wrapper module that enables compute on remote machines,
implementing the JSON-Iface.

<a name="description"></a>

## Description ##
This can be used either as a standalone, to
bring trusted results into the local node, or as the `Execution-Device` of
an AO process.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#compute-3">compute/3</a></td><td></td></tr><tr><td valign="top"><a href="#do_compute-3">do_compute/3*</a></td><td>Execute computation on a remote machine via relay and the JSON-Iface.</td></tr><tr><td valign="top"><a href="#init-3">init/3</a></td><td>Initialize or normalize the compute-lite device.</td></tr><tr><td valign="top"><a href="#normalize-3">normalize/3</a></td><td></td></tr><tr><td valign="top"><a href="#snapshot-3">snapshot/3</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="compute-3"></a>

### compute/3 ###

`compute(Msg1, Msg2, Opts) -> any()`

<a name="do_compute-3"></a>

### do_compute/3 * ###

`do_compute(ProcID, Msg2, Opts) -> any()`

Execute computation on a remote machine via relay and the JSON-Iface.

<a name="init-3"></a>

### init/3 ###

`init(Msg1, Msg2, Opts) -> any()`

Initialize or normalize the compute-lite device. For now, we don't
need to do anything special here.

<a name="normalize-3"></a>

### normalize/3 ###

`normalize(Msg1, Msg2, Opts) -> any()`

<a name="snapshot-3"></a>

### snapshot/3 ###

`snapshot(Msg1, Msg2, Opts) -> any()`


--- END OF FILE: docs/resources/source-code/dev_delegated_compute.md ---

--- START OF FILE: docs/resources/source-code/dev_faff.md ---
# [Module dev_faff.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_faff.erl)




A module that implements a 'friends and family' pricing policy.

<a name="description"></a>

## Description ##

It will allow users to process requests only if their addresses are
in the allow-list for the node.

Fundamentally against the spirit of permissionlessness, but it is useful if
you are running a node for your own purposes and would not like to allow
others to make use of it -- even for a fee. It also serves as a useful
example of how to implement a custom pricing policy, as it implements stubs
for both the pricing and ledger P4 APIs.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#charge-3">charge/3</a></td><td>Charge the user's account if the request is allowed.</td></tr><tr><td valign="top"><a href="#estimate-3">estimate/3</a></td><td>Decide whether or not to service a request from a given address.</td></tr><tr><td valign="top"><a href="#is_admissible-2">is_admissible/2*</a></td><td>Check whether all of the signers of the request are in the allow-list.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="charge-3"></a>

### charge/3 ###

`charge(X1, Req, NodeMsg) -> any()`

Charge the user's account if the request is allowed.

<a name="estimate-3"></a>

### estimate/3 ###

`estimate(X1, Msg, NodeMsg) -> any()`

Decide whether or not to service a request from a given address.

<a name="is_admissible-2"></a>

### is_admissible/2 * ###

`is_admissible(Msg, NodeMsg) -> any()`

Check whether all of the signers of the request are in the allow-list.


--- END OF FILE: docs/resources/source-code/dev_faff.md ---

--- START OF FILE: docs/resources/source-code/dev_genesis_wasm.md ---
# [Module dev_genesis_wasm.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_genesis_wasm.erl)




A device that mimics an environment suitable for `legacynet` AO
processes, using HyperBEAM infrastructure.

<a name="description"></a>

## Description ##
This allows existing `legacynet`
AO process definitions to be used in HyperBEAM.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#collect_events-1">collect_events/1*</a></td><td>Collect events from the port and log them.</td></tr><tr><td valign="top"><a href="#collect_events-2">collect_events/2*</a></td><td></td></tr><tr><td valign="top"><a href="#compute-3">compute/3</a></td><td>All the <code>delegated-compute@1.0</code> device to execute the request.</td></tr><tr><td valign="top"><a href="#ensure_started-1">ensure_started/1*</a></td><td>Ensure the local <code>genesis-wasm@1.0</code> is live.</td></tr><tr><td valign="top"><a href="#init-3">init/3</a></td><td>Initialize the device.</td></tr><tr><td valign="top"><a href="#is_genesis_wasm_server_running-1">is_genesis_wasm_server_running/1*</a></td><td>Check if the genesis-wasm server is running, using the cached process ID
if available.</td></tr><tr><td valign="top"><a href="#log_server_events-1">log_server_events/1*</a></td><td>Log lines of output from the genesis-wasm server.</td></tr><tr><td valign="top"><a href="#normalize-3">normalize/3</a></td><td>Normalize the device.</td></tr><tr><td valign="top"><a href="#snapshot-3">snapshot/3</a></td><td>Snapshot the device.</td></tr><tr><td valign="top"><a href="#status-1">status/1*</a></td><td>Check if the genesis-wasm server is running by requesting its status
endpoint.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="collect_events-1"></a>

### collect_events/1 * ###

`collect_events(Port) -> any()`

Collect events from the port and log them.

<a name="collect_events-2"></a>

### collect_events/2 * ###

`collect_events(Port, Acc) -> any()`

<a name="compute-3"></a>

### compute/3 ###

`compute(Msg, Msg2, Opts) -> any()`

All the `delegated-compute@1.0` device to execute the request. We then apply
the `patch@1.0` device, applying any state patches that the AO process may have
requested.

<a name="ensure_started-1"></a>

### ensure_started/1 * ###

`ensure_started(Opts) -> any()`

Ensure the local `genesis-wasm@1.0` is live. If it not, start it.

<a name="init-3"></a>

### init/3 ###

`init(Msg, Msg2, Opts) -> any()`

Initialize the device.

<a name="is_genesis_wasm_server_running-1"></a>

### is_genesis_wasm_server_running/1 * ###

`is_genesis_wasm_server_running(Opts) -> any()`

Check if the genesis-wasm server is running, using the cached process ID
if available.

<a name="log_server_events-1"></a>

### log_server_events/1 * ###

`log_server_events(Bin) -> any()`

Log lines of output from the genesis-wasm server.

<a name="normalize-3"></a>

### normalize/3 ###

`normalize(Msg, Msg2, Opts) -> any()`

Normalize the device.

<a name="snapshot-3"></a>

### snapshot/3 ###

`snapshot(Msg, Msg2, Opts) -> any()`

Snapshot the device.

<a name="status-1"></a>

### status/1 * ###

`status(Opts) -> any()`

Check if the genesis-wasm server is running by requesting its status
endpoint.


--- END OF FILE: docs/resources/source-code/dev_genesis_wasm.md ---

--- START OF FILE: docs/resources/source-code/dev_green_zone.md ---
# [Module dev_green_zone.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_green_zone.erl)




The green zone device, which provides secure communication and identity
management between trusted nodes.

<a name="description"></a>

## Description ##
It handles node initialization, joining existing green zones, key exchange,
and node identity cloning. All operations are protected by hardware
commitment and encryption.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_trusted_node-4">add_trusted_node/4*</a></td><td>Adds a node to the trusted nodes list with its commitment report.</td></tr><tr><td valign="top"><a href="#become-3">become/3</a></td><td>Clones the identity of a target node in the green zone.</td></tr><tr><td valign="top"><a href="#calculate_node_message-3">calculate_node_message/3*</a></td><td>Generate the node message that should be set prior to joining
a green zone.</td></tr><tr><td valign="top"><a href="#decrypt_zone_key-2">decrypt_zone_key/2*</a></td><td>Decrypts an AES key using the node's RSA private key.</td></tr><tr><td valign="top"><a href="#default_zone_required_opts-1">default_zone_required_opts/1*</a></td><td>Provides the default required options for a green zone.</td></tr><tr><td valign="top"><a href="#encrypt_payload-2">encrypt_payload/2*</a></td><td>Encrypts an AES key with a node's RSA public key.</td></tr><tr><td valign="top"><a href="#finalize_become-5">finalize_become/5*</a></td><td></td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Controls which functions are exposed via the device API.</td></tr><tr><td valign="top"><a href="#info-3">info/3</a></td><td>Provides information about the green zone device and its API.</td></tr><tr><td valign="top"><a href="#init-3">init/3</a></td><td>Initialize the green zone for a node.</td></tr><tr><td valign="top"><a href="#is_trusted-3">is_trusted/3</a></td><td>Returns <code>true</code> if the request is signed by a trusted node.</td></tr><tr><td valign="top"><a href="#join-3">join/3</a></td><td>Initiates the join process for a node to enter an existing green zone.</td></tr><tr><td valign="top"><a href="#join_peer-5">join_peer/5*</a></td><td>Processes a join request to a specific peer node.</td></tr><tr><td valign="top"><a href="#key-3">key/3</a></td><td>Encrypts and provides the node's private key for secure sharing.</td></tr><tr><td valign="top"><a href="#maybe_set_zone_opts-4">maybe_set_zone_opts/4*</a></td><td>Adopts configuration from a peer when joining a green zone.</td></tr><tr><td valign="top"><a href="#rsa_wallet_integration_test-0">rsa_wallet_integration_test/0*</a></td><td>Test RSA operations with the existing wallet structure.</td></tr><tr><td valign="top"><a href="#try_mount_encrypted_volume-2">try_mount_encrypted_volume/2*</a></td><td>Attempts to mount an encrypted volume using the green zone AES key.</td></tr><tr><td valign="top"><a href="#validate_join-3">validate_join/3*</a></td><td>Validates an incoming join request from another node.</td></tr><tr><td valign="top"><a href="#validate_peer_opts-2">validate_peer_opts/2*</a></td><td>Validates that a peer's configuration matches required options.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_trusted_node-4"></a>

### add_trusted_node/4 * ###

<pre><code>
add_trusted_node(NodeAddr::binary(), Report::map(), RequesterPubKey::term(), Opts::map()) -&gt; ok
</code></pre>
<br />

`NodeAddr`: The joining node's address<br />`Report`: The commitment report provided by the joining node<br />`RequesterPubKey`: The joining node's public key<br />`Opts`: A map of configuration options<br />

returns: ok

Adds a node to the trusted nodes list with its commitment report.

This function updates the trusted nodes configuration:
1. Retrieves the current trusted nodes map
2. Adds the new node with its report and public key
3. Updates the node configuration with the new trusted nodes list

<a name="become-3"></a>

### become/3 ###

<pre><code>
become(M1::term(), M2::term(), Opts::map()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

`Opts`: A map of configuration options<br />

returns: `{ok, Map}` on success with confirmation details, or
`{error, Binary}` if the node is not part of a green zone or
identity adoption fails.

Clones the identity of a target node in the green zone.

This function performs the following operations:
1. Retrieves target node location and ID from the configuration
2. Verifies that the local node has a valid shared AES key
3. Requests the target node's encrypted key via its key endpoint
4. Verifies the response is from the expected peer
5. Decrypts the target node's private key using the shared AES key
6. Updates the local node's wallet with the target node's identity

Required configuration in Opts map:
- green_zone_peer_location: Target node's address
- green_zone_peer_id: Target node's unique identifier
- priv_green_zone_aes: The shared AES key for the green zone

<a name="calculate_node_message-3"></a>

### calculate_node_message/3 * ###

`calculate_node_message(RequiredOpts, Req, List) -> any()`

Generate the node message that should be set prior to joining
a green zone.

This function takes a required opts message, a request message, and an
`adopt-config` value. The `adopt-config` value can be a boolean, a list of
fields that should be included in the node message from the request, or a
binary string of fields to include, separated by commas.

<a name="decrypt_zone_key-2"></a>

### decrypt_zone_key/2 * ###

<pre><code>
decrypt_zone_key(EncZoneKey::binary(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`EncZoneKey`: The encrypted zone AES key (Base64 encoded or binary)<br />`Opts`: A map of configuration options<br />

returns: {ok, DecryptedKey} on success with the decrypted AES key

Decrypts an AES key using the node's RSA private key.

This function handles decryption of the zone key:
1. Decodes the encrypted key if it's in Base64 format
2. Extracts the RSA private key components from the wallet
3. Creates an RSA private key record
4. Performs private key decryption on the encrypted key

<a name="default_zone_required_opts-1"></a>

### default_zone_required_opts/1 * ###

<pre><code>
default_zone_required_opts(Opts::map()) -&gt; map()
</code></pre>
<br />

`Opts`: A map of configuration options from which to derive defaults<br />

returns: A map of required configuration options for the green zone

Provides the default required options for a green zone.

This function defines the baseline security requirements for nodes in a green zone:
1. Restricts loading of remote devices and only allows trusted signers
2. Limits to preloaded devices from the initiating machine
3. Enforces specific store configuration
4. Prevents route changes from the defaults
5. Requires matching hooks across all peers
6. Disables message scheduling to prevent conflicts
7. Enforces a permanent state to prevent further configuration changes

<a name="encrypt_payload-2"></a>

### encrypt_payload/2 * ###

<pre><code>
encrypt_payload(AESKey::binary(), RequesterPubKey::term()) -&gt; binary()
</code></pre>
<br />

`AESKey`: The shared AES key (256-bit binary)<br />`RequesterPubKey`: The node's public RSA key<br />

returns: The encrypted AES key

Encrypts an AES key with a node's RSA public key.

This function securely encrypts the shared key for transmission:
1. Extracts the RSA public key components
2. Creates an RSA public key record
3. Performs public key encryption on the AES key

<a name="finalize_become-5"></a>

### finalize_become/5 * ###

`finalize_become(KeyResp, NodeLocation, NodeID, GreenZoneAES, Opts) -> any()`

<a name="info-1"></a>

### info/1 ###

`info(X1) -> any()`

Controls which functions are exposed via the device API.

This function defines the security boundary for the green zone device by
explicitly listing which functions are available through the API.

<a name="info-3"></a>

### info/3 ###

`info(Msg1, Msg2, Opts) -> any()`

Provides information about the green zone device and its API.

This function returns detailed documentation about the device, including:
1. A high-level description of the device's purpose
2. Version information
3. Available API endpoints with their parameters and descriptions

<a name="init-3"></a>

### init/3 ###

<pre><code>
init(M1::term(), M2::term(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`Opts`: A map of configuration options<br />

returns: `{ok, Binary}` on success with confirmation message, or
`{error, Binary}` on failure with error message.

Initialize the green zone for a node.

This function performs the following operations:
1. Validates the node's history to ensure this is a valid initialization
2. Retrieves or creates a required configuration for the green zone
3. Ensures a wallet (keypair) exists or creates a new one
4. Generates a new 256-bit AES key for secure communication
5. Updates the node's configuration with these cryptographic identities

Config options in Opts map:
- green_zone_required_config: (Optional) Custom configuration requirements
- priv_wallet: (Optional) Existing wallet to use instead of creating a new one
- priv_green_zone_aes: (Optional) Existing AES key, if already part of a zone

<a name="is_trusted-3"></a>

### is_trusted/3 ###

`is_trusted(M1, Req, Opts) -> any()`

Returns `true` if the request is signed by a trusted node.

<a name="join-3"></a>

### join/3 ###

<pre><code>
join(M1::term(), M2::term(), Opts::map()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

`M1`: The join request message with target peer information<br />`M2`: Additional request details, may include adoption preferences<br />`Opts`: A map of configuration options for join operations<br />

returns: `{ok, Map}` on success with join response details, or
`{error, Binary}` on failure with error message.

Initiates the join process for a node to enter an existing green zone.

This function performs the following operations depending on the state:
1. Validates the node's history to ensure proper initialization
2. Checks for target peer information (location and ID)
3. If target peer is specified:
a. Generates a commitment report for the peer
b. Prepares and sends a POST request to the target peer
c. Verifies the response and decrypts the returned zone key
d. Updates local configuration with the shared AES key
4. If no peer is specified, processes the join request locally

Config options in Opts map:
- green_zone_peer_location: Target peer's address
- green_zone_peer_id: Target peer's unique identifier
- green_zone_adopt_config:
(Optional) Whether to adopt peer's configuration (default: true)

<a name="join_peer-5"></a>

### join_peer/5 * ###

<pre><code>
join_peer(PeerLocation::binary(), PeerID::binary(), M1::term(), M2::term(), Opts::map()) -&gt; {ok, map()} | {error, map() | binary()}
</code></pre>
<br />

`PeerLocation`: The target peer's address<br />`PeerID`: The target peer's unique identifier<br />`M2`: May contain ShouldMount flag to enable encrypted volume mounting<br />

returns: `{ok, Map}` on success with confirmation message, or
`{error, Map|Binary}` on failure with error details

Processes a join request to a specific peer node.

This function handles the client-side join flow when connecting to a peer:
1. Verifies the node is not already in a green zone
2. Optionally adopts configuration from the target peer
3. Generates a hardware-backed commitment report
4. Sends a POST request to the peer's join endpoint
5. Verifies the response signature
6. Decrypts the returned AES key
7. Updates local configuration with the shared key
8. Optionally mounts an encrypted volume using the shared key

<a name="key-3"></a>

### key/3 ###

<pre><code>
key(M1::term(), M2::term(), Opts::map()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

`Opts`: A map of configuration options<br />

returns: `{ok, Map}` containing the encrypted key and IV on success, or
`{error, Binary}` if the node is not part of a green zone

Encrypts and provides the node's private key for secure sharing.

This function performs the following operations:
1. Retrieves the shared AES key and the node's wallet
2. Verifies that the node is part of a green zone (has a shared AES key)
3. Generates a random initialization vector (IV) for encryption
4. Encrypts the node's private key using AES-256-GCM with the shared key
5. Returns the encrypted key and IV for secure transmission

Required configuration in Opts map:
- priv_green_zone_aes: The shared AES key for the green zone
- priv_wallet: The node's wallet containing the private key to encrypt

<a name="maybe_set_zone_opts-4"></a>

### maybe_set_zone_opts/4 * ###

<pre><code>
maybe_set_zone_opts(PeerLocation::binary(), PeerID::binary(), Req::map(), InitOpts::map()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

`PeerLocation`: The location of the peer node to join<br />`PeerID`: The ID of the peer node to join<br />`Req`: The request message with adoption preferences<br />`InitOpts`: A map of initial configuration options<br />

returns: `{ok, Map}` with updated configuration on success, or
`{error, Binary}` if configuration retrieval fails

Adopts configuration from a peer when joining a green zone.

This function handles the conditional adoption of peer configuration:
1. Checks if adoption is enabled (default: true)
2. Requests required configuration from the peer
3. Verifies the authenticity of the configuration
4. Creates a node message with appropriate settings
5. Updates the local node configuration

Config options:
- green_zone_adopt_config: Controls configuration adoption (boolean, list, or binary)

<a name="rsa_wallet_integration_test-0"></a>

### rsa_wallet_integration_test/0 * ###

`rsa_wallet_integration_test() -> any()`

Test RSA operations with the existing wallet structure.

This test function verifies that encryption and decryption using the RSA keys
from the wallet work correctly. It creates a new wallet, encrypts a test
message with the RSA public key, and then decrypts it with the RSA private
key, asserting that the decrypted message matches the original.

<a name="try_mount_encrypted_volume-2"></a>

### try_mount_encrypted_volume/2 * ###

`try_mount_encrypted_volume(AESKey, Opts) -> any()`

Attempts to mount an encrypted volume using the green zone AES key.

This function handles the complete process of secure storage setup by
delegating to the dev_volume module, which provides a unified interface
for volume management.

The encryption key used for the volume is the same AES key used for green zone
communication, ensuring that only nodes in the green zone can access the data.

<a name="validate_join-3"></a>

### validate_join/3 * ###

<pre><code>
validate_join(M1::term(), Req::map(), Opts::map()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

`M1`: Ignored parameter<br />`Req`: The join request containing commitment report and public key<br />`Opts`: A map of configuration options<br />

returns: `{ok, Map}` on success with encrypted AES key, or
`{error, Binary}` on failure with error message

Validates an incoming join request from another node.

This function handles the server-side join flow when receiving a connection
request:
1. Validates the peer's configuration meets required standards
2. Extracts the commitment report and public key from the request
3. Verifies the hardware-backed commitment report
4. Adds the joining node to the trusted nodes list
5. Encrypts the shared AES key with the peer's public key
6. Returns the encrypted key to the requesting node

<a name="validate_peer_opts-2"></a>

### validate_peer_opts/2 * ###

<pre><code>
validate_peer_opts(Req::map(), Opts::map()) -&gt; boolean()
</code></pre>
<br />

`Req`: The request message containing the peer's configuration<br />`Opts`: A map of the local node's configuration options<br />

returns: true if the peer's configuration is valid, false otherwise

Validates that a peer's configuration matches required options.

This function ensures the peer node meets configuration requirements:
1. Retrieves the local node's required configuration
2. Gets the peer's options from its message
3. Adds required configuration to peer's required options list
4. Verifies the peer's node history is valid
5. Checks that the peer's options match the required configuration


--- END OF FILE: docs/resources/source-code/dev_green_zone.md ---

--- START OF FILE: docs/resources/source-code/dev_hook.md ---
# [Module dev_hook.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_hook.erl)




A generalized interface for `hooking` into HyperBEAM nodes.

<a name="description"></a>

## Description ##

This module allows users to define `hooks` that are executed at various
points in the lifecycle of nodes and message evaluations.

Hooks are maintained in the `node message` options, under the key `on`
key. Each `hook` may have zero or many `handlers` which their request is
executed against. A new `handler` of a hook can be registered by simply
adding a new key to that message. If multiple hooks need to be executed for
a single event, the key's value can be set to a list of hooks.

`hook`s themselves do not need to be added explicitly. Any device can add
a hook by simply executing `dev_hook:on(HookName, Req, Opts)`. This
function is does not affect the hashpath of a message and is not exported on
the device`s API, such that it is not possible to call it directly with
AO-Core resolution.

All handlers are expressed in the form of a message, upon which the hook's
request is evaluated:

AO(HookMsg, Req, Opts) => {Status, Result}

The `Status` and `Result` of the evaluation can be used at the `hook` caller's
discretion. If multiple handlers are to be executed for a single `hook`, the
result of each is used as the input to the next, on the assumption that the
status of the previous is `ok`. If a non-`ok` status is encountered, the
evaluation is halted and the result is returned to the caller. This means
that in most cases, hooks take the form of chainable pipelines of functions,
passing the most pertinent data in the `body` key of both the request and
result. Hook definitions can also set the `hook/result` key to `ignore`, if
the result of the execution should be discarded and the prior value (the
input to the hook) should be used instead. The `hook/commit-request` key can
also be set to `true` if the request should be committed by the node before
execution of the hook.

The default HyperBEAM node implements several useful hooks. They include:

start: Executed when the node starts.
Req/body: The node's initial configuration.
Result/body: The node's possibly updated configuration.
request: Executed when a request is received via the HTTP API.
Req/body: The sequence of messages that the node will evaluate.
Req/request: The raw, unparsed singleton request.
Result/body: The sequence of messages that the node will evaluate.
step: Executed after each message in a sequence has been evaluated.
Req/body: The result of the evaluation.
Result/body: The result of the evaluation.
response: Executed when a response is sent via the HTTP API.
Req/body: The result of the evaluation.
Req/request: The raw, unparsed singleton request that was used to
generate the response.
Result/body: The message to be sent in response to the request.

Additionally, this module implements a traditional device API, allowing the
node operator to register hooks to the node and find those that are
currently active.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#execute_handler-4">execute_handler/4*</a></td><td>Execute a single handler
Handlers are expressed as messages that can be resolved via AO.</td></tr><tr><td valign="top"><a href="#execute_handlers-4">execute_handlers/4*</a></td><td>Execute a list of handlers in sequence.</td></tr><tr><td valign="top"><a href="#find-2">find/2</a></td><td>Get all handlers for a specific hook from the node message options.</td></tr><tr><td valign="top"><a href="#find-3">find/3</a></td><td></td></tr><tr><td valign="top"><a href="#halt_on_error_test-0">halt_on_error_test/0*</a></td><td>Test that pipeline execution halts on error.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Device API information.</td></tr><tr><td valign="top"><a href="#multiple_handlers_test-0">multiple_handlers_test/0*</a></td><td>Test that multiple handlers form a pipeline.</td></tr><tr><td valign="top"><a href="#no_handlers_test-0">no_handlers_test/0*</a></td><td>Test that hooks with no handlers return the original request.</td></tr><tr><td valign="top"><a href="#on-3">on/3</a></td><td>Execute a named hook with the provided request and options
This function finds all handlers for the hook and evaluates them in sequence.</td></tr><tr><td valign="top"><a href="#single_handler_test-0">single_handler_test/0*</a></td><td>Test that a single handler is executed correctly.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="execute_handler-4"></a>

### execute_handler/4 * ###

`execute_handler(HookName, Handler, Req, Opts) -> any()`

Execute a single handler
Handlers are expressed as messages that can be resolved via AO.

<a name="execute_handlers-4"></a>

### execute_handlers/4 * ###

`execute_handlers(HookName, Rest, Req, Opts) -> any()`

Execute a list of handlers in sequence.
The result of each handler is used as input to the next handler.
If a handler returns a non-ok status, execution is halted.

<a name="find-2"></a>

### find/2 ###

`find(HookName, Opts) -> any()`

Get all handlers for a specific hook from the node message options.
Handlers are stored in the `on` key of this message. The `find/2` variant of
this function only takes a hook name and node message, and is not called
directly via the device API. Instead it is used by `on/3` and other internal
functionality to find handlers when necessary. The `find/3` variant can,
however, be called directly via the device API.

<a name="find-3"></a>

### find/3 ###

`find(Base, Req, Opts) -> any()`

<a name="halt_on_error_test-0"></a>

### halt_on_error_test/0 * ###

`halt_on_error_test() -> any()`

Test that pipeline execution halts on error

<a name="info-1"></a>

### info/1 ###

`info(X1) -> any()`

Device API information

<a name="multiple_handlers_test-0"></a>

### multiple_handlers_test/0 * ###

`multiple_handlers_test() -> any()`

Test that multiple handlers form a pipeline

<a name="no_handlers_test-0"></a>

### no_handlers_test/0 * ###

`no_handlers_test() -> any()`

Test that hooks with no handlers return the original request

<a name="on-3"></a>

### on/3 ###

`on(HookName, Req, Opts) -> any()`

Execute a named hook with the provided request and options
This function finds all handlers for the hook and evaluates them in sequence.
The result of each handler is used as input to the next handler.

<a name="single_handler_test-0"></a>

### single_handler_test/0 * ###

`single_handler_test() -> any()`

Test that a single handler is executed correctly


--- END OF FILE: docs/resources/source-code/dev_hook.md ---

--- START OF FILE: docs/resources/source-code/dev_hyperbuddy.md ---
# [Module dev_hyperbuddy.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_hyperbuddy.erl)




A device that renders a REPL-like interface for AO-Core via HTML.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#events-3">events/3</a></td><td>Return the current event counters as a message.</td></tr><tr><td valign="top"><a href="#format-3">format/3</a></td><td>Employ HyperBEAM's internal pretty printer to format a message.</td></tr><tr><td valign="top"><a href="#info-0">info/0</a></td><td>Export an explicit list of files via http.</td></tr><tr><td valign="top"><a href="#metrics-3">metrics/3</a></td><td>The main HTML page for the REPL device.</td></tr><tr><td valign="top"><a href="#return_file-1">return_file/1*</a></td><td>Read a file from disk and serve it as a static HTML page.</td></tr><tr><td valign="top"><a href="#return_file-2">return_file/2</a></td><td></td></tr><tr><td valign="top"><a href="#serve-4">serve/4*</a></td><td>Serve a file from the priv directory.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="events-3"></a>

### events/3 ###

`events(X1, Req, Opts) -> any()`

Return the current event counters as a message.

<a name="format-3"></a>

### format/3 ###

`format(Base, Req, Opts) -> any()`

Employ HyperBEAM's internal pretty printer to format a message.

<a name="info-0"></a>

### info/0 ###

`info() -> any()`

Export an explicit list of files via http.

<a name="metrics-3"></a>

### metrics/3 ###

`metrics(X1, Req, Opts) -> any()`

The main HTML page for the REPL device.

<a name="return_file-1"></a>

### return_file/1 * ###

`return_file(Name) -> any()`

Read a file from disk and serve it as a static HTML page.

<a name="return_file-2"></a>

### return_file/2 ###

`return_file(Device, Name) -> any()`

<a name="serve-4"></a>

### serve/4 * ###

`serve(Key, M1, M2, Opts) -> any()`

Serve a file from the priv directory. Only serves files that are explicitly
listed in the `routes` field of the `info/0` return value.


--- END OF FILE: docs/resources/source-code/dev_hyperbuddy.md ---

--- START OF FILE: docs/resources/source-code/dev_json_iface.md ---
# [Module dev_json_iface.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_json_iface.erl)




A device that provides a way for WASM execution to interact with
the HyperBEAM (and AO) systems, using JSON as a shared data representation.

<a name="description"></a>

## Description ##

The interface is easy to use. It works as follows:

1. The device is given a message that contains a process definition, WASM
environment, and a message that contains the data to be processed,
including the image to be used in part of `execute{pass=1}`.
2. The device is called with `execute{pass=2}`, which reads the result of
the process execution from the WASM environment and adds it to the
message.

The device has the following requirements and interface:

```

       M1/Computed when /Pass == 1 ->
           Assumes:
               M1/priv/wasm/instance
               M1/Process
               M2/Message
               M2/Assignment/Block-Height
           Generates:
               /wasm/handler
               /wasm/params
           Side-effects:
               Writes the process and message as JSON representations into the
               WASM environment.
       M1/Computed when M2/Pass == 2 ->
           Assumes:
               M1/priv/wasm/instance
               M2/Results
               M2/Process
           Generates:
               /Results/Outbox
               /Results/Data
```
<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#aos_stack_benchmark_test_-0">aos_stack_benchmark_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#basic_aos_call_test_-0">basic_aos_call_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#compute-3">compute/3</a></td><td>On first pass prepare the call, on second pass get the results.</td></tr><tr><td valign="top"><a href="#denormalize_message-2">denormalize_message/2*</a></td><td>Normalize a message for AOS-compatibility.</td></tr><tr><td valign="top"><a href="#env_read-3">env_read/3*</a></td><td>Read the results out of the execution environment.</td></tr><tr><td valign="top"><a href="#env_write-5">env_write/5*</a></td><td>Write the message and process into the execution environment.</td></tr><tr><td valign="top"><a href="#generate_aos_msg-2">generate_aos_msg/2</a></td><td></td></tr><tr><td valign="top"><a href="#generate_stack-1">generate_stack/1</a></td><td></td></tr><tr><td valign="top"><a href="#generate_stack-2">generate_stack/2</a></td><td></td></tr><tr><td valign="top"><a href="#header_case_string-1">header_case_string/1*</a></td><td></td></tr><tr><td valign="top"><a href="#init-3">init/3</a></td><td>Initialize the device.</td></tr><tr><td valign="top"><a href="#json_to_message-2">json_to_message/2</a></td><td>Translates a compute result -- either from a WASM execution using the
JSON-Iface, or from a <code>Legacy</code> CU -- and transforms it into a result message.</td></tr><tr><td valign="top"><a href="#maybe_list_to_binary-1">maybe_list_to_binary/1*</a></td><td></td></tr><tr><td valign="top"><a href="#message_to_json_struct-2">message_to_json_struct/2</a></td><td></td></tr><tr><td valign="top"><a href="#message_to_json_struct-3">message_to_json_struct/3*</a></td><td></td></tr><tr><td valign="top"><a href="#normalize_results-1">normalize_results/1*</a></td><td>Normalize the results of an evaluation.</td></tr><tr><td valign="top"><a href="#postprocess_outbox-3">postprocess_outbox/3*</a></td><td>Post-process messages in the outbox to add the correct <code>from-process</code>
and <code>from-image</code> tags.</td></tr><tr><td valign="top"><a href="#prep_call-3">prep_call/3*</a></td><td>Prepare the WASM environment for execution by writing the process string and
the message as JSON representations into the WASM environment.</td></tr><tr><td valign="top"><a href="#prepare_header_case_tags-2">prepare_header_case_tags/2*</a></td><td>Convert a message without an <code>original-tags</code> field into a list of
key-value pairs, with the keys in HTTP header-case.</td></tr><tr><td valign="top"><a href="#prepare_tags-2">prepare_tags/2*</a></td><td>Prepare the tags of a message as a key-value list, for use in the
construction of the JSON-Struct message.</td></tr><tr><td valign="top"><a href="#preprocess_results-2">preprocess_results/2*</a></td><td>After the process returns messages from an evaluation, the
signing node needs to add some tags to each message and spawn such that
the target process knows these messages are created by a process.</td></tr><tr><td valign="top"><a href="#results-3">results/3*</a></td><td>Read the computed results out of the WASM environment, assuming that
the environment has been set up by <code>prep_call/3</code> and that the WASM executor
has been called with <code>computed{pass=1}</code>.</td></tr><tr><td valign="top"><a href="#safe_to_id-1">safe_to_id/1*</a></td><td></td></tr><tr><td valign="top"><a href="#tags_to_map-2">tags_to_map/2*</a></td><td>Convert a message with tags into a map of their key-value pairs.</td></tr><tr><td valign="top"><a href="#test_init-0">test_init/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="aos_stack_benchmark_test_-0"></a>

### aos_stack_benchmark_test_/0 * ###

`aos_stack_benchmark_test_() -> any()`

<a name="basic_aos_call_test_-0"></a>

### basic_aos_call_test_/0 * ###

`basic_aos_call_test_() -> any()`

<a name="compute-3"></a>

### compute/3 ###

`compute(M1, M2, Opts) -> any()`

On first pass prepare the call, on second pass get the results.

<a name="denormalize_message-2"></a>

### denormalize_message/2 * ###

`denormalize_message(Message, Opts) -> any()`

Normalize a message for AOS-compatibility.

<a name="env_read-3"></a>

### env_read/3 * ###

`env_read(M1, M2, Opts) -> any()`

Read the results out of the execution environment.

<a name="env_write-5"></a>

### env_write/5 * ###

`env_write(ProcessStr, MsgStr, Base, Req, Opts) -> any()`

Write the message and process into the execution environment.

<a name="generate_aos_msg-2"></a>

### generate_aos_msg/2 ###

`generate_aos_msg(ProcID, Code) -> any()`

<a name="generate_stack-1"></a>

### generate_stack/1 ###

`generate_stack(File) -> any()`

<a name="generate_stack-2"></a>

### generate_stack/2 ###

`generate_stack(File, Mode) -> any()`

<a name="header_case_string-1"></a>

### header_case_string/1 * ###

`header_case_string(Key) -> any()`

<a name="init-3"></a>

### init/3 ###

`init(M1, M2, Opts) -> any()`

Initialize the device.

<a name="json_to_message-2"></a>

### json_to_message/2 ###

`json_to_message(JSON, Opts) -> any()`

Translates a compute result -- either from a WASM execution using the
JSON-Iface, or from a `Legacy` CU -- and transforms it into a result message.

<a name="maybe_list_to_binary-1"></a>

### maybe_list_to_binary/1 * ###

`maybe_list_to_binary(List) -> any()`

<a name="message_to_json_struct-2"></a>

### message_to_json_struct/2 ###

`message_to_json_struct(RawMsg, Opts) -> any()`

<a name="message_to_json_struct-3"></a>

### message_to_json_struct/3 * ###

`message_to_json_struct(RawMsg, Features, Opts) -> any()`

<a name="normalize_results-1"></a>

### normalize_results/1 * ###

`normalize_results(Msg) -> any()`

Normalize the results of an evaluation.

<a name="postprocess_outbox-3"></a>

### postprocess_outbox/3 * ###

`postprocess_outbox(Msg, Proc, Opts) -> any()`

Post-process messages in the outbox to add the correct `from-process`
and `from-image` tags.

<a name="prep_call-3"></a>

### prep_call/3 * ###

`prep_call(RawM1, RawM2, Opts) -> any()`

Prepare the WASM environment for execution by writing the process string and
the message as JSON representations into the WASM environment.

<a name="prepare_header_case_tags-2"></a>

### prepare_header_case_tags/2 * ###

`prepare_header_case_tags(TABM, Opts) -> any()`

Convert a message without an `original-tags` field into a list of
key-value pairs, with the keys in HTTP header-case.

<a name="prepare_tags-2"></a>

### prepare_tags/2 * ###

`prepare_tags(Msg, Opts) -> any()`

Prepare the tags of a message as a key-value list, for use in the
construction of the JSON-Struct message.

<a name="preprocess_results-2"></a>

### preprocess_results/2 * ###

`preprocess_results(Msg, Opts) -> any()`

After the process returns messages from an evaluation, the
signing node needs to add some tags to each message and spawn such that
the target process knows these messages are created by a process.

<a name="results-3"></a>

### results/3 * ###

`results(M1, M2, Opts) -> any()`

Read the computed results out of the WASM environment, assuming that
the environment has been set up by `prep_call/3` and that the WASM executor
has been called with `computed{pass=1}`.

<a name="safe_to_id-1"></a>

### safe_to_id/1 * ###

`safe_to_id(ID) -> any()`

<a name="tags_to_map-2"></a>

### tags_to_map/2 * ###

`tags_to_map(Msg, Opts) -> any()`

Convert a message with tags into a map of their key-value pairs.

<a name="test_init-0"></a>

### test_init/0 * ###

`test_init() -> any()`


--- END OF FILE: docs/resources/source-code/dev_json_iface.md ---

--- START OF FILE: docs/resources/source-code/dev_local_name.md ---
# [Module dev_local_name.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_local_name.erl)




A device for registering and looking up local names.

<a name="description"></a>

## Description ##
This device uses
the node message to store a local cache of its known names, and the typical
non-volatile storage of the node message to store the names long-term.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#default_lookup-4">default_lookup/4*</a></td><td>Handle all other requests by delegating to the lookup function.</td></tr><tr><td valign="top"><a href="#direct_register-2">direct_register/2</a></td><td>Register a name without checking if the caller is an operator.</td></tr><tr><td valign="top"><a href="#find_names-1">find_names/1*</a></td><td>Returns a message containing all known names.</td></tr><tr><td valign="top"><a href="#generate_test_opts-0">generate_test_opts/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_test-0">http_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Export only the <code>lookup</code> and <code>register</code> functions.</td></tr><tr><td valign="top"><a href="#load_names-1">load_names/1*</a></td><td>Loads all known names from the cache and returns the new <code>node message</code>
with those names loaded into it.</td></tr><tr><td valign="top"><a href="#lookup-3">lookup/3</a></td><td>Takes a <code>key</code> argument and returns the value of the name, if it exists.</td></tr><tr><td valign="top"><a href="#lookup_opts_name_test-0">lookup_opts_name_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#no_names_test-0">no_names_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#register-3">register/3</a></td><td>Takes a <code>key</code> and <code>value</code> argument and registers the name.</td></tr><tr><td valign="top"><a href="#register_test-0">register_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#unauthorized_test-0">unauthorized_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#update_names-2">update_names/2*</a></td><td>Updates the node message with the new names.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="default_lookup-4"></a>

### default_lookup/4 * ###

`default_lookup(Key, X2, Req, Opts) -> any()`

Handle all other requests by delegating to the lookup function.

<a name="direct_register-2"></a>

### direct_register/2 ###

`direct_register(Req, Opts) -> any()`

Register a name without checking if the caller is an operator. Exported
for use by other devices, but not publicly available.

<a name="find_names-1"></a>

### find_names/1 * ###

`find_names(Opts) -> any()`

Returns a message containing all known names.

<a name="generate_test_opts-0"></a>

### generate_test_opts/0 * ###

`generate_test_opts() -> any()`

<a name="http_test-0"></a>

### http_test/0 * ###

`http_test() -> any()`

<a name="info-1"></a>

### info/1 ###

`info(Opts) -> any()`

Export only the `lookup` and `register` functions.

<a name="load_names-1"></a>

### load_names/1 * ###

`load_names(Opts) -> any()`

Loads all known names from the cache and returns the new `node message`
with those names loaded into it.

<a name="lookup-3"></a>

### lookup/3 ###

`lookup(X1, Req, Opts) -> any()`

Takes a `key` argument and returns the value of the name, if it exists.

<a name="lookup_opts_name_test-0"></a>

### lookup_opts_name_test/0 * ###

`lookup_opts_name_test() -> any()`

<a name="no_names_test-0"></a>

### no_names_test/0 * ###

`no_names_test() -> any()`

<a name="register-3"></a>

### register/3 ###

`register(X1, Req, Opts) -> any()`

Takes a `key` and `value` argument and registers the name. The caller
must be the node operator in order to register a name.

<a name="register_test-0"></a>

### register_test/0 * ###

`register_test() -> any()`

<a name="unauthorized_test-0"></a>

### unauthorized_test/0 * ###

`unauthorized_test() -> any()`

<a name="update_names-2"></a>

### update_names/2 * ###

`update_names(LocalNames, Opts) -> any()`

Updates the node message with the new names. Further HTTP requests will
use this new message, removing the need to look up the names from non-volatile
storage.


--- END OF FILE: docs/resources/source-code/dev_local_name.md ---

--- START OF FILE: docs/resources/source-code/dev_lookup.md ---
# [Module dev_lookup.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_lookup.erl)




A device that looks up an ID from a local store and returns it, honoring
the `accept` key to return the correct format.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#aos2_message_lookup_test-0">aos2_message_lookup_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#binary_lookup_test-0">binary_lookup_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_lookup_test-0">http_lookup_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#message_lookup_test-0">message_lookup_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#read-3">read/3</a></td><td>Fetch a resource from the cache using "target" ID extracted from the message.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="aos2_message_lookup_test-0"></a>

### aos2_message_lookup_test/0 * ###

`aos2_message_lookup_test() -> any()`

<a name="binary_lookup_test-0"></a>

### binary_lookup_test/0 * ###

`binary_lookup_test() -> any()`

<a name="http_lookup_test-0"></a>

### http_lookup_test/0 * ###

`http_lookup_test() -> any()`

<a name="message_lookup_test-0"></a>

### message_lookup_test/0 * ###

`message_lookup_test() -> any()`

<a name="read-3"></a>

### read/3 ###

`read(M1, M2, Opts) -> any()`

Fetch a resource from the cache using "target" ID extracted from the message


--- END OF FILE: docs/resources/source-code/dev_lookup.md ---

--- START OF FILE: docs/resources/source-code/dev_lua_lib.md ---
# [Module dev_lua_lib.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_lua_lib.erl)




A module for providing AO library functions to the Lua environment.

<a name="description"></a>

## Description ##

This module contains the implementation of the functions, each by the name
that should be used in the `ao` table in the Lua environment. Every export
is imported into the Lua environment.

Each function adheres closely to the Luerl calling convention, adding the
appropriate node message as a third argument:

fun(Args, State, NodeMsg) -> {ResultTerms, NewState}

As Lua allows for multiple return values, each function returns a list of
terms to grant to the caller. Matching the tuple convention used by AO-Core,
the first term is typically the status, and the second term is the result.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#convert_as-1">convert_as/1*</a></td><td>Converts any <code>as</code> terms from Lua to their HyperBEAM equivalents.</td></tr><tr><td valign="top"><a href="#event-3">event/3</a></td><td>Allows Lua scripts to signal events using the HyperBEAM hosts internal
event system.</td></tr><tr><td valign="top"><a href="#get-3">get/3</a></td><td>A wrapper for <code>hb_ao</code>'s <code>get</code> functionality.</td></tr><tr><td valign="top"><a href="#install-3">install/3</a></td><td>Install the library into the given Lua environment.</td></tr><tr><td valign="top"><a href="#resolve-3">resolve/3</a></td><td>A wrapper function for performing AO-Core resolutions.</td></tr><tr><td valign="top"><a href="#return-3">return/3*</a></td><td>Helper function for returning a result from a Lua function.</td></tr><tr><td valign="top"><a href="#set-3">set/3</a></td><td>Wrapper for <code>hb_ao</code>'s <code>set</code> functionality.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="convert_as-1"></a>

### convert_as/1 * ###

`convert_as(Other) -> any()`

Converts any `as` terms from Lua to their HyperBEAM equivalents.

<a name="event-3"></a>

### event/3 ###

`event(X1, ExecState, Opts) -> any()`

Allows Lua scripts to signal events using the HyperBEAM hosts internal
event system.

<a name="get-3"></a>

### get/3 ###

`get(X1, ExecState, ExecOpts) -> any()`

A wrapper for `hb_ao`'s `get` functionality.

<a name="install-3"></a>

### install/3 ###

`install(Base, State, Opts) -> any()`

Install the library into the given Lua environment.

<a name="resolve-3"></a>

### resolve/3 ###

`resolve(Msgs, ExecState, ExecOpts) -> any()`

A wrapper function for performing AO-Core resolutions. Offers both the
single-message (using `hb_singleton:from/1` to parse) and multiple-message
(using `hb_ao:resolve_many/2`) variants.

<a name="return-3"></a>

### return/3 * ###

`return(Result, ExecState, Opts) -> any()`

Helper function for returning a result from a Lua function.

<a name="set-3"></a>

### set/3 ###

`set(X1, ExecState, ExecOpts) -> any()`

Wrapper for `hb_ao`'s `set` functionality.


--- END OF FILE: docs/resources/source-code/dev_lua_lib.md ---

--- START OF FILE: docs/resources/source-code/dev_lua_test_ledgers.md ---
# [Module dev_lua_test_ledgers.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_lua_test_ledgers.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#apply_names-3">apply_names/3*</a></td><td>Apply a map of environment names to elements in either a map or list.</td></tr><tr><td valign="top"><a href="#balance-3">balance/3*</a></td><td>Retreive a single balance from the ledger.</td></tr><tr><td valign="top"><a href="#balance_total-3">balance_total/3*</a></td><td>Get the total balance for an ID across all ledgers in a set.</td></tr><tr><td valign="top"><a href="#balances-2">balances/2*</a></td><td>Get the balances of a ledger.</td></tr><tr><td valign="top"><a href="#balances-3">balances/3*</a></td><td></td></tr><tr><td valign="top"><a href="#comma_separated_scheduler_list_test-0">comma_separated_scheduler_list_test/0*</a></td><td>Ensure that the <code>hyper-token.lua</code> script can parse comma-separated
IDs in the <code>scheduler</code> field of a message.</td></tr><tr><td valign="top"><a href="#do_apply_names-3">do_apply_names/3*</a></td><td></td></tr><tr><td valign="top"><a href="#ledger-2">ledger/2*</a></td><td>Generate a Lua process definition message.</td></tr><tr><td valign="top"><a href="#ledger-3">ledger/3*</a></td><td></td></tr><tr><td valign="top"><a href="#ledgers-2">ledgers/2*</a></td><td>Get the local expectation of a ledger's balances with peer ledgers.</td></tr><tr><td valign="top"><a href="#lua_script-1">lua_script/1*</a></td><td>Generate a Lua <code>script</code> key from a file or list of files.</td></tr><tr><td valign="top"><a href="#map-2">map/2*</a></td><td>Generate a complete overview of the test environment's balances and
ledgers.</td></tr><tr><td valign="top"><a href="#map-3">map/3*</a></td><td></td></tr><tr><td valign="top"><a href="#multischeduler-0">multischeduler/0*</a></td><td></td></tr><tr><td valign="top"><a href="#multischeduler_test_disabled-0">multischeduler_test_disabled/0*</a></td><td>Verify that sub-ledgers can request and enforce multiple scheduler
commitments.</td></tr><tr><td valign="top"><a href="#normalize_env-1">normalize_env/1*</a></td><td>Normalize a set of processes, representing ledgers in a test environment,
to a canonical form: A map of <code>ID => Proc</code>.</td></tr><tr><td valign="top"><a href="#normalize_without_root-2">normalize_without_root/2*</a></td><td>Return the normalized environment without the root ledger.</td></tr><tr><td valign="top"><a href="#register-3">register/3*</a></td><td>Request that a peer register with a without sub-ledger.</td></tr><tr><td valign="top"><a href="#subledger-2">subledger/2*</a></td><td>Generate a test sub-ledger process definition message.</td></tr><tr><td valign="top"><a href="#subledger-3">subledger/3*</a></td><td></td></tr><tr><td valign="top"><a href="#subledger_deposit-0">subledger_deposit/0*</a></td><td></td></tr><tr><td valign="top"><a href="#subledger_deposit_test_-0">subledger_deposit_test_/0*</a></td><td>Verify that a user can deposit tokens into a sub-ledger.</td></tr><tr><td valign="top"><a href="#subledger_registration_test_disabled-0">subledger_registration_test_disabled/0*</a></td><td>Verify that peer ledgers on the same token are able to register mutually
to establish a peer-to-peer connection.</td></tr><tr><td valign="top"><a href="#subledger_supply-3">subledger_supply/3*</a></td><td>Calculate the supply of tokens in all sub-ledgers, from the balances of
the root ledger.</td></tr><tr><td valign="top"><a href="#subledger_to_subledger-0">subledger_to_subledger/0*</a></td><td></td></tr><tr><td valign="top"><a href="#subledger_to_subledger_test_-0">subledger_to_subledger_test_/0*</a></td><td>Verify that registered sub-ledgers are able to send tokens to each other
without the need for messages on the root ledger.</td></tr><tr><td valign="top"><a href="#subledger_transfer-0">subledger_transfer/0*</a></td><td></td></tr><tr><td valign="top"><a href="#subledger_transfer_test_-0">subledger_transfer_test_/0*</a></td><td>Simulate inter-ledger payments between users on a single sub-ledger:
1.</td></tr><tr><td valign="top"><a href="#supply-2">supply/2*</a></td><td>Get the supply of a ledger, either <code>now</code> or <code>initial</code>.</td></tr><tr><td valign="top"><a href="#supply-3">supply/3*</a></td><td></td></tr><tr><td valign="top"><a href="#test_opts-0">test_opts/0*</a></td><td>Create a node message for the test that avoids looking up unknown
recipients via remote stores.</td></tr><tr><td valign="top"><a href="#transfer-0">transfer/0*</a></td><td></td></tr><tr><td valign="top"><a href="#transfer-5">transfer/5*</a></td><td>Generate a test transfer message.</td></tr><tr><td valign="top"><a href="#transfer-6">transfer/6*</a></td><td></td></tr><tr><td valign="top"><a href="#transfer_test_-0">transfer_test_/0*</a></td><td>Test the <code>transfer</code> function.</td></tr><tr><td valign="top"><a href="#transfer_unauthorized-0">transfer_unauthorized/0*</a></td><td></td></tr><tr><td valign="top"><a href="#transfer_unauthorized_test_-0">transfer_unauthorized_test_/0*</a></td><td>User's must not be able to send tokens they do not own.</td></tr><tr><td valign="top"><a href="#unregistered_peer_transfer-0">unregistered_peer_transfer/0*</a></td><td></td></tr><tr><td valign="top"><a href="#unregistered_peer_transfer_test_-0">unregistered_peer_transfer_test_/0*</a></td><td>Verify that a ledger can send tokens to a peer ledger that is not
registered with it yet.</td></tr><tr><td valign="top"><a href="#user_supply-3">user_supply/3*</a></td><td>Calculate the supply of tokens held by users on a ledger, excluding
those held in sub-ledgers.</td></tr><tr><td valign="top"><a href="#verify_net-3">verify_net/3*</a></td><td>Execute all invariant checks for a pair of root ledger and sub-ledgers.</td></tr><tr><td valign="top"><a href="#verify_net_peer_balances-2">verify_net_peer_balances/2*</a></td><td>Verify the consistency of all expected ledger balances with their peer
ledgers and the actual balances held.</td></tr><tr><td valign="top"><a href="#verify_net_supply-3">verify_net_supply/3*</a></td><td>Verify that the sum of all spendable balances held by ledgers in a
test network is equal to the initial supply of tokens.</td></tr><tr><td valign="top"><a href="#verify_peer_balances-3">verify_peer_balances/3*</a></td><td>Verify that a ledger's expectation of its balances with peer ledgers
is consistent with the actual balances held.</td></tr><tr><td valign="top"><a href="#verify_root_supply-2">verify_root_supply/2*</a></td><td>Verify that the initial supply of tokens on the root ledger is the same
as the current supply.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="apply_names-3"></a>

### apply_names/3 * ###

`apply_names(Map, EnvNames, Opts) -> any()`

Apply a map of environment names to elements in either a map or list.
Expects a map of `ID or ProcMsg or Wallet => Name` as the `EnvNames` argument,
and a potentially deep map or list of elements to apply the names to.

<a name="balance-3"></a>

### balance/3 * ###

`balance(ProcMsg, User, Opts) -> any()`

Retreive a single balance from the ledger.

<a name="balance_total-3"></a>

### balance_total/3 * ###

`balance_total(Procs, ID, Opts) -> any()`

Get the total balance for an ID across all ledgers in a set.

<a name="balances-2"></a>

### balances/2 * ###

`balances(ProcMsg, Opts) -> any()`

Get the balances of a ledger.

<a name="balances-3"></a>

### balances/3 * ###

`balances(Mode, ProcMsg, Opts) -> any()`

<a name="comma_separated_scheduler_list_test-0"></a>

### comma_separated_scheduler_list_test/0 * ###

`comma_separated_scheduler_list_test() -> any()`

Ensure that the `hyper-token.lua` script can parse comma-separated
IDs in the `scheduler` field of a message.

<a name="do_apply_names-3"></a>

### do_apply_names/3 * ###

`do_apply_names(Map, EnvNames, Opts) -> any()`

<a name="ledger-2"></a>

### ledger/2 * ###

`ledger(Script, Opts) -> any()`

Generate a Lua process definition message.

<a name="ledger-3"></a>

### ledger/3 * ###

`ledger(Script, Extra, Opts) -> any()`

<a name="ledgers-2"></a>

### ledgers/2 * ###

`ledgers(ProcMsg, Opts) -> any()`

Get the local expectation of a ledger's balances with peer ledgers.

<a name="lua_script-1"></a>

### lua_script/1 * ###

`lua_script(Files) -> any()`

Generate a Lua `script` key from a file or list of files.

<a name="map-2"></a>

### map/2 * ###

`map(Procs, Opts) -> any()`

Generate a complete overview of the test environment's balances and
ledgers. Optionally, a map of environment names can be provided to make the
output more readable.

<a name="map-3"></a>

### map/3 * ###

`map(Procs, EnvNames, Opts) -> any()`

<a name="multischeduler-0"></a>

### multischeduler/0 * ###

`multischeduler() -> any()`

<a name="multischeduler_test_disabled-0"></a>

### multischeduler_test_disabled/0 * ###

`multischeduler_test_disabled() -> any()`

Verify that sub-ledgers can request and enforce multiple scheduler
commitments. `hyper-token` always validates that peer `base` processes
(the uncommitted process ID without its `scheduler` and `authority` fields)
match. It allows us to specify additional constraints on the `scheduler` and
`authority` fields while matching against the local ledger's base process
message. This test validates the correctness of these constraints.

The grammar supported by `hyper-token.lua` allows for the following, where
`X = scheduler | authority`:
- `X`: A list of `X`s that must (by default) be present in the
peer ledger's `X` field.
- `X-match`: A count of the number of `X`s that must be present in the
peer ledger's `X` field.
- `X-required`: A list of `X`s that always must be present in the
peer ledger's `X` field.

<a name="normalize_env-1"></a>

### normalize_env/1 * ###

`normalize_env(Procs) -> any()`

Normalize a set of processes, representing ledgers in a test environment,
to a canonical form: A map of `ID => Proc`.

<a name="normalize_without_root-2"></a>

### normalize_without_root/2 * ###

`normalize_without_root(RootProc, Procs) -> any()`

Return the normalized environment without the root ledger.

<a name="register-3"></a>

### register/3 * ###

`register(ProcMsg, Peer, Opts) -> any()`

Request that a peer register with a without sub-ledger.

<a name="subledger-2"></a>

### subledger/2 * ###

`subledger(Root, Opts) -> any()`

Generate a test sub-ledger process definition message.

<a name="subledger-3"></a>

### subledger/3 * ###

`subledger(Root, Extra, Opts) -> any()`

<a name="subledger_deposit-0"></a>

### subledger_deposit/0 * ###

`subledger_deposit() -> any()`

<a name="subledger_deposit_test_-0"></a>

### subledger_deposit_test_/0 * ###

`subledger_deposit_test_() -> any()`

Verify that a user can deposit tokens into a sub-ledger.

<a name="subledger_registration_test_disabled-0"></a>

### subledger_registration_test_disabled/0 * ###

`subledger_registration_test_disabled() -> any()`

Verify that peer ledgers on the same token are able to register mutually
to establish a peer-to-peer connection.

Disabled as explicit peer registration is not required for `hyper-token.lua`
to function.

<a name="subledger_supply-3"></a>

### subledger_supply/3 * ###

`subledger_supply(RootProc, AllProcs, Opts) -> any()`

Calculate the supply of tokens in all sub-ledgers, from the balances of
the root ledger.

<a name="subledger_to_subledger-0"></a>

### subledger_to_subledger/0 * ###

`subledger_to_subledger() -> any()`

<a name="subledger_to_subledger_test_-0"></a>

### subledger_to_subledger_test_/0 * ###

`subledger_to_subledger_test_() -> any()`

Verify that registered sub-ledgers are able to send tokens to each other
without the need for messages on the root ledger.

<a name="subledger_transfer-0"></a>

### subledger_transfer/0 * ###

`subledger_transfer() -> any()`

<a name="subledger_transfer_test_-0"></a>

### subledger_transfer_test_/0 * ###

`subledger_transfer_test_() -> any()`

Simulate inter-ledger payments between users on a single sub-ledger:
1. Alice has tokens on the root ledger.
2. Alice sends tokens to the sub-ledger from the root ledger.
3. Alice sends tokens to Bob on the sub-ledger.
4. Bob sends tokens to Alice on the root ledger.

<a name="supply-2"></a>

### supply/2 * ###

`supply(ProcMsg, Opts) -> any()`

Get the supply of a ledger, either `now` or `initial`.

<a name="supply-3"></a>

### supply/3 * ###

`supply(Mode, ProcMsg, Opts) -> any()`

<a name="test_opts-0"></a>

### test_opts/0 * ###

`test_opts() -> any()`

Create a node message for the test that avoids looking up unknown
recipients via remote stores. This improves test performance.

<a name="transfer-0"></a>

### transfer/0 * ###

`transfer() -> any()`

<a name="transfer-5"></a>

### transfer/5 * ###

`transfer(ProcMsg, Sender, Recipient, Quantity, Opts) -> any()`

Generate a test transfer message.

<a name="transfer-6"></a>

### transfer/6 * ###

`transfer(ProcMsg, Sender, Recipient, Quantity, Route, Opts) -> any()`

<a name="transfer_test_-0"></a>

### transfer_test_/0 * ###

`transfer_test_() -> any()`

Test the `transfer` function.
1. Alice has 100 tokens on a root ledger.
2. Alice sends 1 token to Bob.
3. Alice has 99 tokens, and Bob has 1 token.

<a name="transfer_unauthorized-0"></a>

### transfer_unauthorized/0 * ###

`transfer_unauthorized() -> any()`

<a name="transfer_unauthorized_test_-0"></a>

### transfer_unauthorized_test_/0 * ###

`transfer_unauthorized_test_() -> any()`

User's must not be able to send tokens they do not own. We test three
cases:
1. Transferring a token when the sender has no tokens.
2. Transferring a token when the sender has less tokens than the amount
being transferred.
3. Transferring a binary-encoded amount of tokens that exceed the quantity
of tokens the sender has available.

<a name="unregistered_peer_transfer-0"></a>

### unregistered_peer_transfer/0 * ###

`unregistered_peer_transfer() -> any()`

<a name="unregistered_peer_transfer_test_-0"></a>

### unregistered_peer_transfer_test_/0 * ###

`unregistered_peer_transfer_test_() -> any()`

Verify that a ledger can send tokens to a peer ledger that is not
registered with it yet. Each peer ledger must have precisely the same process
base message, granting transitive security properties: If a peer trusts its
own compute and assignment mechanism, then it can trust messages from exact
duplicates of itself. In order for this to be safe, the peer ledger network's
base process message must implement sufficicient rollback protections and
compute correctness guarantees.

<a name="user_supply-3"></a>

### user_supply/3 * ###

`user_supply(Proc, AllProcs, Opts) -> any()`

Calculate the supply of tokens held by users on a ledger, excluding
those held in sub-ledgers.

<a name="verify_net-3"></a>

### verify_net/3 * ###

`verify_net(RootProc, AllProcs, Opts) -> any()`

Execute all invariant checks for a pair of root ledger and sub-ledgers.

<a name="verify_net_peer_balances-2"></a>

### verify_net_peer_balances/2 * ###

`verify_net_peer_balances(AllProcs, Opts) -> any()`

Verify the consistency of all expected ledger balances with their peer
ledgers and the actual balances held.

<a name="verify_net_supply-3"></a>

### verify_net_supply/3 * ###

`verify_net_supply(RootProc, AllProcs, Opts) -> any()`

Verify that the sum of all spendable balances held by ledgers in a
test network is equal to the initial supply of tokens.

<a name="verify_peer_balances-3"></a>

### verify_peer_balances/3 * ###

`verify_peer_balances(ValidateProc, AllProcs, Opts) -> any()`

Verify that a ledger's expectation of its balances with peer ledgers
is consistent with the actual balances held.

<a name="verify_root_supply-2"></a>

### verify_root_supply/2 * ###

`verify_root_supply(RootProc, Opts) -> any()`

Verify that the initial supply of tokens on the root ledger is the same
as the current supply. This invariant will not hold for sub-ledgers, as they
'mint' tokens in their local supply when they receive them from other ledgers.


--- END OF FILE: docs/resources/source-code/dev_lua_test_ledgers.md ---

--- START OF FILE: docs/resources/source-code/dev_lua_test.md ---
# [Module dev_lua_test.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_lua_test.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#exec_test-2">exec_test/2*</a></td><td>Generate an EUnit test for a given function.</td></tr><tr><td valign="top"><a href="#exec_test_-0">exec_test_/0*</a></td><td>Main entrypoint for Lua tests.</td></tr><tr><td valign="top"><a href="#new_state-1">new_state/1*</a></td><td>Create a new Lua environment for a given script.</td></tr><tr><td valign="top"><a href="#parse_spec-1">parse_spec/1</a></td><td>Parse a string representation of test descriptions received from the
command line via the <code>LUA_TESTS</code> environment variable.</td></tr><tr><td valign="top"><a href="#suite-2">suite/2*</a></td><td>Generate an EUnit test suite for a given Lua script.</td></tr><tr><td valign="top"><a href="#terminates_with-2">terminates_with/2*</a></td><td>Check if a string terminates with a given suffix.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="exec_test-2"></a>

### exec_test/2 * ###

`exec_test(State, Function) -> any()`

Generate an EUnit test for a given function.

<a name="exec_test_-0"></a>

### exec_test_/0 * ###

`exec_test_() -> any()`

Main entrypoint for Lua tests.

<a name="new_state-1"></a>

### new_state/1 * ###

`new_state(File) -> any()`

Create a new Lua environment for a given script.

<a name="parse_spec-1"></a>

### parse_spec/1 ###

`parse_spec(Str) -> any()`

Parse a string representation of test descriptions received from the
command line via the `LUA_TESTS` environment variable.

Supported syntax in loose BNF/RegEx:

Definitions := (ModDef,)+
ModDef      := ModName(TestDefs)?
ModName     := ModuleInLUA_SCRIPTS|(FileName[.lua])?
TestDefs    := (:TestDef)+
TestDef     := TestName

File names ending in `.lua` are assumed to be relative paths from the current
working directory. Module names lacking the `.lua` extension are assumed to
be modules found in the `LUA_SCRIPTS` environment variable (defaulting to
`scripts/`).

For example, to run a single test one could call the following:

LUA_TESTS=~/src/LuaScripts/test.yourTest rebar3 lua-tests

To specify that one would like to run all of the tests in the
`scripts/test.lua` file and two tests from the `scripts/test2.lua` file, the
user could provide the following test definition:

LUA_TESTS="test,scripts/test2.userTest1|userTest2" rebar3 lua-tests

<a name="suite-2"></a>

### suite/2 * ###

`suite(File, Funcs) -> any()`

Generate an EUnit test suite for a given Lua script. If the `Funcs` is
the atom `tests` we find all of the global functions in the script, then
filter for those ending in `_test` in a similar fashion to Eunit.

<a name="terminates_with-2"></a>

### terminates_with/2 * ###

`terminates_with(String, Suffix) -> any()`

Check if a string terminates with a given suffix.


--- END OF FILE: docs/resources/source-code/dev_lua_test.md ---

--- START OF FILE: docs/resources/source-code/dev_lua.md ---
# [Module dev_lua.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_lua.erl)




A device that calls a Lua module upon a request and returns the result.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#ao_core_resolution_from_lua_test-0">ao_core_resolution_from_lua_test/0*</a></td><td>Run an AO-Core resolution from the Lua environment.</td></tr><tr><td valign="top"><a href="#ao_core_sandbox_test-0">ao_core_sandbox_test/0*</a></td><td>Run an AO-Core resolution from the Lua environment.</td></tr><tr><td valign="top"><a href="#aos_authority_not_trusted_test-0">aos_authority_not_trusted_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#aos_process_benchmark_test_-0">aos_process_benchmark_test_/0*</a></td><td>Benchmark the performance of Lua executions.</td></tr><tr><td valign="top"><a href="#compute-4">compute/4*</a></td><td>Call the Lua script with the given arguments.</td></tr><tr><td valign="top"><a href="#decode-2">decode/2</a></td><td>Decode a Lua result into a HyperBEAM <code>structured@1.0</code> message.</td></tr><tr><td valign="top"><a href="#decode_params-3">decode_params/3*</a></td><td>Decode a list of Lua references, as found in a stack trace, into a
list of Erlang terms.</td></tr><tr><td valign="top"><a href="#decode_stacktrace-3">decode_stacktrace/3*</a></td><td>Parse a Lua stack trace into a list of messages.</td></tr><tr><td valign="top"><a href="#decode_stacktrace-4">decode_stacktrace/4*</a></td><td></td></tr><tr><td valign="top"><a href="#direct_benchmark_test-0">direct_benchmark_test/0*</a></td><td>Benchmark the performance of Lua executions.</td></tr><tr><td valign="top"><a href="#encode-2">encode/2</a></td><td>Encode a HyperBEAM <code>structured@1.0</code> message into a Lua term.</td></tr><tr><td valign="top"><a href="#ensure_initialized-3">ensure_initialized/3*</a></td><td>Initialize the Lua VM if it is not already initialized.</td></tr><tr><td valign="top"><a href="#error_response_test-0">error_response_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#find_modules-2">find_modules/2*</a></td><td>Find the script in the base message, either by ID or by string.</td></tr><tr><td valign="top"><a href="#functions-3">functions/3</a></td><td>Return a list of all functions in the Lua environment.</td></tr><tr><td valign="top"><a href="#generate_lua_process-2">generate_lua_process/2*</a></td><td>Generate a Lua process message.</td></tr><tr><td valign="top"><a href="#generate_stack-1">generate_stack/1*</a></td><td>Generate a stack message for the Lua process.</td></tr><tr><td valign="top"><a href="#generate_test_message-2">generate_test_message/2*</a></td><td>Generate a test message for a Lua process.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>All keys that are not directly available in the base message are
resolved by calling the Lua function in the module of the same name.</td></tr><tr><td valign="top"><a href="#init-3">init/3</a></td><td>Initialize the device state, loading the script into memory if it is
a reference.</td></tr><tr><td valign="top"><a href="#initialize-3">initialize/3*</a></td><td>Initialize a new Lua state with a given base message and module.</td></tr><tr><td valign="top"><a href="#invoke_aos_test-0">invoke_aos_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#invoke_non_compute_key_test-0">invoke_non_compute_key_test/0*</a></td><td>Call a non-compute key on a Lua device message and ensure that the
function of the same name in the script is called.</td></tr><tr><td valign="top"><a href="#load_modules-2">load_modules/2*</a></td><td>Load a list of modules for installation into the Lua VM.</td></tr><tr><td valign="top"><a href="#load_modules-3">load_modules/3*</a></td><td></td></tr><tr><td valign="top"><a href="#load_modules_by_id-0">load_modules_by_id/0*</a></td><td></td></tr><tr><td valign="top"><a href="#load_modules_by_id_test_-0">load_modules_by_id_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#lua_http_hook_test-0">lua_http_hook_test/0*</a></td><td>Use a Lua module as a hook on the HTTP server via <code>~meta@1.0</code>.</td></tr><tr><td valign="top"><a href="#multiple_modules_test-0">multiple_modules_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#normalize-3">normalize/3</a></td><td>Restore the Lua state from a snapshot, if it exists.</td></tr><tr><td valign="top"><a href="#process_response-3">process_response/3*</a></td><td>Process a response to a Luerl invocation.</td></tr><tr><td valign="top"><a href="#pure_lua_process_benchmark-0">pure_lua_process_benchmark/0*</a></td><td></td></tr><tr><td valign="top"><a href="#pure_lua_process_benchmark_test_-0">pure_lua_process_benchmark_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#pure_lua_process_test-0">pure_lua_process_test/0*</a></td><td>Call a process whose <code>execution-device</code> is set to <code>lua@5.3a</code>.</td></tr><tr><td valign="top"><a href="#sandbox-3">sandbox/3*</a></td><td>Sandbox (render inoperable) a set of Lua functions.</td></tr><tr><td valign="top"><a href="#sandboxed_failure_test-0">sandboxed_failure_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#simple_invocation_test-0">simple_invocation_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#snapshot-3">snapshot/3</a></td><td>Snapshot the Lua state from a live computation.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="ao_core_resolution_from_lua_test-0"></a>

### ao_core_resolution_from_lua_test/0 * ###

`ao_core_resolution_from_lua_test() -> any()`

Run an AO-Core resolution from the Lua environment.

<a name="ao_core_sandbox_test-0"></a>

### ao_core_sandbox_test/0 * ###

`ao_core_sandbox_test() -> any()`

Run an AO-Core resolution from the Lua environment.

<a name="aos_authority_not_trusted_test-0"></a>

### aos_authority_not_trusted_test/0 * ###

`aos_authority_not_trusted_test() -> any()`

<a name="aos_process_benchmark_test_-0"></a>

### aos_process_benchmark_test_/0 * ###

`aos_process_benchmark_test_() -> any()`

Benchmark the performance of Lua executions.

<a name="compute-4"></a>

### compute/4 * ###

`compute(Key, RawBase, Req, Opts) -> any()`

Call the Lua script with the given arguments.

<a name="decode-2"></a>

### decode/2 ###

`decode(EncMsg, Opts) -> any()`

Decode a Lua result into a HyperBEAM `structured@1.0` message.

<a name="decode_params-3"></a>

### decode_params/3 * ###

`decode_params(Rest, State, Opts) -> any()`

Decode a list of Lua references, as found in a stack trace, into a
list of Erlang terms.

<a name="decode_stacktrace-3"></a>

### decode_stacktrace/3 * ###

`decode_stacktrace(StackTrace, State0, Opts) -> any()`

Parse a Lua stack trace into a list of messages.

<a name="decode_stacktrace-4"></a>

### decode_stacktrace/4 * ###

`decode_stacktrace(Rest, State, Acc, Opts) -> any()`

<a name="direct_benchmark_test-0"></a>

### direct_benchmark_test/0 * ###

`direct_benchmark_test() -> any()`

Benchmark the performance of Lua executions.

<a name="encode-2"></a>

### encode/2 ###

`encode(Map, Opts) -> any()`

Encode a HyperBEAM `structured@1.0` message into a Lua term.

<a name="ensure_initialized-3"></a>

### ensure_initialized/3 * ###

`ensure_initialized(Base, Req, Opts) -> any()`

Initialize the Lua VM if it is not already initialized. Optionally takes
the script as a  Binary string. If not provided, the module will be loaded
from the base message.

<a name="error_response_test-0"></a>

### error_response_test/0 * ###

`error_response_test() -> any()`

<a name="find_modules-2"></a>

### find_modules/2 * ###

`find_modules(Base, Opts) -> any()`

Find the script in the base message, either by ID or by string.

<a name="functions-3"></a>

### functions/3 ###

`functions(Base, Req, Opts) -> any()`

Return a list of all functions in the Lua environment.

<a name="generate_lua_process-2"></a>

### generate_lua_process/2 * ###

`generate_lua_process(File, Opts) -> any()`

Generate a Lua process message.

<a name="generate_stack-1"></a>

### generate_stack/1 * ###

`generate_stack(File) -> any()`

Generate a stack message for the Lua process.

<a name="generate_test_message-2"></a>

### generate_test_message/2 * ###

`generate_test_message(Process, Opts) -> any()`

Generate a test message for a Lua process.

<a name="info-1"></a>

### info/1 ###

`info(Base) -> any()`

All keys that are not directly available in the base message are
resolved by calling the Lua function in the module of the same name.
Additionally, we exclude the `keys`, `set`, `encode` and `decode` functions
which are `message@1.0` core functions, and Lua public utility functions.

<a name="init-3"></a>

### init/3 ###

`init(Base, Req, Opts) -> any()`

Initialize the device state, loading the script into memory if it is
a reference.

<a name="initialize-3"></a>

### initialize/3 * ###

`initialize(Base, Modules, Opts) -> any()`

Initialize a new Lua state with a given base message and module.

<a name="invoke_aos_test-0"></a>

### invoke_aos_test/0 * ###

`invoke_aos_test() -> any()`

<a name="invoke_non_compute_key_test-0"></a>

### invoke_non_compute_key_test/0 * ###

`invoke_non_compute_key_test() -> any()`

Call a non-compute key on a Lua device message and ensure that the
function of the same name in the script is called.

<a name="load_modules-2"></a>

### load_modules/2 * ###

`load_modules(Modules, Opts) -> any()`

Load a list of modules for installation into the Lua VM.

<a name="load_modules-3"></a>

### load_modules/3 * ###

`load_modules(Rest, Opts, Acc) -> any()`

<a name="load_modules_by_id-0"></a>

### load_modules_by_id/0 * ###

`load_modules_by_id() -> any()`

<a name="load_modules_by_id_test_-0"></a>

### load_modules_by_id_test_/0 * ###

`load_modules_by_id_test_() -> any()`

<a name="lua_http_hook_test-0"></a>

### lua_http_hook_test/0 * ###

`lua_http_hook_test() -> any()`

Use a Lua module as a hook on the HTTP server via `~meta@1.0`.

<a name="multiple_modules_test-0"></a>

### multiple_modules_test/0 * ###

`multiple_modules_test() -> any()`

<a name="normalize-3"></a>

### normalize/3 ###

`normalize(Base, Req, RawOpts) -> any()`

Restore the Lua state from a snapshot, if it exists.

<a name="process_response-3"></a>

### process_response/3 * ###

`process_response(X1, Priv, Opts) -> any()`

Process a response to a Luerl invocation. Returns the typical AO-Core
HyperBEAM response format.

<a name="pure_lua_process_benchmark-0"></a>

### pure_lua_process_benchmark/0 * ###

`pure_lua_process_benchmark() -> any()`

<a name="pure_lua_process_benchmark_test_-0"></a>

### pure_lua_process_benchmark_test_/0 * ###

`pure_lua_process_benchmark_test_() -> any()`

<a name="pure_lua_process_test-0"></a>

### pure_lua_process_test/0 * ###

`pure_lua_process_test() -> any()`

Call a process whose `execution-device` is set to `lua@5.3a`.

<a name="sandbox-3"></a>

### sandbox/3 * ###

`sandbox(State, Map, Opts) -> any()`

Sandbox (render inoperable) a set of Lua functions. Each function is
referred to as if it is a path in AO-Core, with its value being what to
return to the caller. For example, 'os.exit' would be referred to as
referred to as `os/exit`. If preferred, a list rather than a map may be
provided, in which case the functions all return `sandboxed`.

<a name="sandboxed_failure_test-0"></a>

### sandboxed_failure_test/0 * ###

`sandboxed_failure_test() -> any()`

<a name="simple_invocation_test-0"></a>

### simple_invocation_test/0 * ###

`simple_invocation_test() -> any()`

<a name="snapshot-3"></a>

### snapshot/3 ###

`snapshot(Base, Req, Opts) -> any()`

Snapshot the Lua state from a live computation. Normalizes its `priv`
state element, then serializes the state to a binary.


--- END OF FILE: docs/resources/source-code/dev_lua.md ---

--- START OF FILE: docs/resources/source-code/dev_manifest.md ---
# [Module dev_manifest.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_manifest.erl)




An Arweave path manifest resolution device.

<a name="description"></a>

## Description ##
Follows the v1 schema:
https://specs.ar.io/?tx=lXLd0OPwo-dJLB_Amz5jgIeDhiOkjXuM3-r0H_aiNj0<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#info-0">info/0</a></td><td>Use the <code>route/4</code> function as the handler for all requests, aside
from <code>keys</code> and <code>set</code>, which are handled by the default resolver.</td></tr><tr><td valign="top"><a href="#manifest-3">manifest/3*</a></td><td>Find and deserialize a manifest from the given base.</td></tr><tr><td valign="top"><a href="#resolve_test-0">resolve_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#route-4">route/4*</a></td><td>Route a request to the associated data via its manifest.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="info-0"></a>

### info/0 ###

`info() -> any()`

Use the `route/4` function as the handler for all requests, aside
from `keys` and `set`, which are handled by the default resolver.

<a name="manifest-3"></a>

### manifest/3 * ###

`manifest(Base, Req, Opts) -> any()`

Find and deserialize a manifest from the given base.

<a name="resolve_test-0"></a>

### resolve_test/0 * ###

`resolve_test() -> any()`

<a name="route-4"></a>

### route/4 * ###

`route(Key, M1, M2, Opts) -> any()`

Route a request to the associated data via its manifest.


--- END OF FILE: docs/resources/source-code/dev_manifest.md ---

--- START OF FILE: docs/resources/source-code/dev_message.md ---
# [Module dev_message.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_message.erl)




The identity device: For non-reserved keys, it simply returns a key
from the message as it is found in the message's underlying Erlang map.

<a name="description"></a>

## Description ##
Private keys (`priv[.*]`) are not included.
Reserved keys are: `id`, `commitments`, `committers`, `keys`, `path`,
`set`, `remove`, `get`, and `verify`. Their function comments describe the
behaviour of the device when these keys are set.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#calculate_id-3">calculate_id/3*</a></td><td></td></tr><tr><td valign="top"><a href="#cannot_get_private_keys_test-0">cannot_get_private_keys_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#case_insensitive_get-3">case_insensitive_get/3*</a></td><td>Key matching should be case insensitive, following RFC-9110, so we
implement a case-insensitive key lookup rather than delegating to
<code>hb_maps:get/2</code>.</td></tr><tr><td valign="top"><a href="#case_insensitive_get_test-0">case_insensitive_get_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#commit-3">commit/3</a></td><td>Commit to a message, using the <code>commitment-device</code> key to specify the
device that should be used to commit to the message.</td></tr><tr><td valign="top"><a href="#commitment_ids_from_committers-3">commitment_ids_from_committers/3*</a></td><td>Returns a list of commitment IDs in a commitments map that are relevant
for a list of given committer addresses.</td></tr><tr><td valign="top"><a href="#commitment_ids_from_request-3">commitment_ids_from_request/3*</a></td><td>Implements a standardized form of specifying commitment IDs for a
message request.</td></tr><tr><td valign="top"><a href="#committed-3">committed/3</a></td><td>Return the list of committed keys from a message.</td></tr><tr><td valign="top"><a href="#committers-1">committers/1</a></td><td>Return the committers of a message that are present in the given request.</td></tr><tr><td valign="top"><a href="#committers-2">committers/2</a></td><td></td></tr><tr><td valign="top"><a href="#committers-3">committers/3</a></td><td></td></tr><tr><td valign="top"><a href="#deep_unset_test-0">deep_unset_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_commitments_loaded-2">ensure_commitments_loaded/2*</a></td><td>Ensure that the <code>commitments</code> submessage of a base message is fully
loaded into local memory.</td></tr><tr><td valign="top"><a href="#get-3">get/3</a></td><td>Return the value associated with the key as it exists in the message's
underlying Erlang map.</td></tr><tr><td valign="top"><a href="#get-4">get/4</a></td><td></td></tr><tr><td valign="top"><a href="#get_keys_mod_test-0">get_keys_mod_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#id-1">id/1</a></td><td>Return the ID of a message, using the <code>committers</code> list if it exists.</td></tr><tr><td valign="top"><a href="#id-2">id/2</a></td><td></td></tr><tr><td valign="top"><a href="#id-3">id/3</a></td><td></td></tr><tr><td valign="top"><a href="#id_device-2">id_device/2*</a></td><td>Locate the ID device of a message.</td></tr><tr><td valign="top"><a href="#index-3">index/3</a></td><td>Generate an index page for a message, in the event that the <code>body</code> and
<code>content-type</code> of a message returned to the client are both empty.</td></tr><tr><td valign="top"><a href="#info-0">info/0</a></td><td>Return the info for the identity device.</td></tr><tr><td valign="top"><a href="#is_private_mod_test-0">is_private_mod_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#key_from_device_test-0">key_from_device_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#keys-1">keys/1</a></td><td>Get the public keys of a message.</td></tr><tr><td valign="top"><a href="#keys-2">keys/2</a></td><td></td></tr><tr><td valign="top"><a href="#keys_from_device_test-0">keys_from_device_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#private_keys_are_filtered_test-0">private_keys_are_filtered_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#remove-2">remove/2</a></td><td>Remove a key or keys from a message.</td></tr><tr><td valign="top"><a href="#remove-3">remove/3</a></td><td></td></tr><tr><td valign="top"><a href="#remove_test-0">remove_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#set-3">set/3</a></td><td>Deep merge keys in a message.</td></tr><tr><td valign="top"><a href="#set_conflicting_keys_test-0">set_conflicting_keys_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#set_ignore_undefined_test-0">set_ignore_undefined_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#set_path-3">set_path/3</a></td><td>Special case of <code>set/3</code> for setting the <code>path</code> key.</td></tr><tr><td valign="top"><a href="#unset_with_set_test-0">unset_with_set_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#verify-3">verify/3</a></td><td>Verify a message.</td></tr><tr><td valign="top"><a href="#verify_commitment-3">verify_commitment/3*</a></td><td>Execute a function for a single commitment in the context of its
parent message.</td></tr><tr><td valign="top"><a href="#verify_test-0">verify_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#with_relevant_commitments-3">with_relevant_commitments/3*</a></td><td>Return a message with only the relevant commitments for a given request.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="calculate_id-3"></a>

### calculate_id/3 * ###

`calculate_id(Base, Req, NodeOpts) -> any()`

<a name="cannot_get_private_keys_test-0"></a>

### cannot_get_private_keys_test/0 * ###

`cannot_get_private_keys_test() -> any()`

<a name="case_insensitive_get-3"></a>

### case_insensitive_get/3 * ###

`case_insensitive_get(Key, Msg, Opts) -> any()`

Key matching should be case insensitive, following RFC-9110, so we
implement a case-insensitive key lookup rather than delegating to
`hb_maps:get/2`. Encode the key to a binary if it is not already.

<a name="case_insensitive_get_test-0"></a>

### case_insensitive_get_test/0 * ###

`case_insensitive_get_test() -> any()`

<a name="commit-3"></a>

### commit/3 ###

`commit(Self, Req, Opts) -> any()`

Commit to a message, using the `commitment-device` key to specify the
device that should be used to commit to the message. If the key is not set,
the default device (`httpsig@1.0`) is used.

<a name="commitment_ids_from_committers-3"></a>

### commitment_ids_from_committers/3 * ###

`commitment_ids_from_committers(CommitterAddrs, Commitments, Opts) -> any()`

Returns a list of commitment IDs in a commitments map that are relevant
for a list of given committer addresses.

<a name="commitment_ids_from_request-3"></a>

### commitment_ids_from_request/3 * ###

`commitment_ids_from_request(Base, Req, Opts) -> any()`

Implements a standardized form of specifying commitment IDs for a
message request. The caller may specify a list of committers (by address)
or a list of commitment IDs directly. They may specify both, in which case
the returned list will be the union of the two lists. In each case, they
may specify `all` or `none` for each group. If no specifiers are provided,
the default is `all` for commitments -- also implying `all` for committers.

<a name="committed-3"></a>

### committed/3 ###

`committed(Self, Req, Opts) -> any()`

Return the list of committed keys from a message.

<a name="committers-1"></a>

### committers/1 ###

`committers(Base) -> any()`

Return the committers of a message that are present in the given request.

<a name="committers-2"></a>

### committers/2 ###

`committers(Base, Req) -> any()`

<a name="committers-3"></a>

### committers/3 ###

`committers(X1, X2, NodeOpts) -> any()`

<a name="deep_unset_test-0"></a>

### deep_unset_test/0 * ###

`deep_unset_test() -> any()`

<a name="ensure_commitments_loaded-2"></a>

### ensure_commitments_loaded/2 * ###

`ensure_commitments_loaded(NonRelevant, Opts) -> any()`

Ensure that the `commitments` submessage of a base message is fully
loaded into local memory.

<a name="get-3"></a>

### get/3 ###

`get(Key, Msg, Opts) -> any()`

Return the value associated with the key as it exists in the message's
underlying Erlang map. First check the public keys, then check case-
insensitively if the key is a binary.

<a name="get-4"></a>

### get/4 ###

`get(Key, Msg, Msg2, Opts) -> any()`

<a name="get_keys_mod_test-0"></a>

### get_keys_mod_test/0 * ###

`get_keys_mod_test() -> any()`

<a name="id-1"></a>

### id/1 ###

`id(Base) -> any()`

Return the ID of a message, using the `committers` list if it exists.
If the `committers` key is `all`, return the ID including all known
commitments -- `none` yields the ID without any commitments. If the
`committers` key is a list/map, return the ID including only the specified
commitments.

The `id-device` key in the message can be used to specify the device that
should be used to calculate the ID. If it is not set, the default device
(`httpsig@1.0`) is used.

Note: This function _does not_ use AO-Core's `get/3` function, as it
as it would require significant computation. We may want to change this
if/when non-map message structures are created.

<a name="id-2"></a>

### id/2 ###

`id(Base, Req) -> any()`

<a name="id-3"></a>

### id/3 ###

`id(Base, Req, NodeOpts) -> any()`

<a name="id_device-2"></a>

### id_device/2 * ###

`id_device(X1, Opts) -> any()`

Locate the ID device of a message. The ID device is determined the
`device` set in _all_ of the commitments. If no commitments are present,
the default device (`httpsig@1.0`) is used.

<a name="index-3"></a>

### index/3 ###

`index(Msg, Req, Opts) -> any()`

Generate an index page for a message, in the event that the `body` and
`content-type` of a message returned to the client are both empty. We do this
as follows:
1. Find the `default_index` key of the node message. If it is a binary,
it is assumed to be the name of a device, and we execute the resolution
`as` that ID.
2. Merge the base message with the default index message, favoring the default
index message's keys over those in the base message, unless the default
was a device name.
3. Execute the `default_index_path` (base: `index`) upon the message,
giving the rest of the request unchanged.

<a name="info-0"></a>

### info/0 ###

`info() -> any()`

Return the info for the identity device.

<a name="is_private_mod_test-0"></a>

### is_private_mod_test/0 * ###

`is_private_mod_test() -> any()`

<a name="key_from_device_test-0"></a>

### key_from_device_test/0 * ###

`key_from_device_test() -> any()`

<a name="keys-1"></a>

### keys/1 ###

`keys(Msg) -> any()`

Get the public keys of a message.

<a name="keys-2"></a>

### keys/2 ###

`keys(Msg, Opts) -> any()`

<a name="keys_from_device_test-0"></a>

### keys_from_device_test/0 * ###

`keys_from_device_test() -> any()`

<a name="private_keys_are_filtered_test-0"></a>

### private_keys_are_filtered_test/0 * ###

`private_keys_are_filtered_test() -> any()`

<a name="remove-2"></a>

### remove/2 ###

`remove(Message1, Key) -> any()`

Remove a key or keys from a message.

<a name="remove-3"></a>

### remove/3 ###

`remove(Message1, X2, Opts) -> any()`

<a name="remove_test-0"></a>

### remove_test/0 * ###

`remove_test() -> any()`

<a name="set-3"></a>

### set/3 ###

`set(Message1, NewValuesMsg, Opts) -> any()`

Deep merge keys in a message. Takes a map of key-value pairs and sets
them in the message, overwriting any existing values.

<a name="set_conflicting_keys_test-0"></a>

### set_conflicting_keys_test/0 * ###

`set_conflicting_keys_test() -> any()`

<a name="set_ignore_undefined_test-0"></a>

### set_ignore_undefined_test/0 * ###

`set_ignore_undefined_test() -> any()`

<a name="set_path-3"></a>

### set_path/3 ###

`set_path(Message1, X2, Opts) -> any()`

Special case of `set/3` for setting the `path` key. This cannot be set
using the normal `set` function, as the `path` is a reserved key, necessary
for AO-Core to know the key to evaluate in requests.

<a name="unset_with_set_test-0"></a>

### unset_with_set_test/0 * ###

`unset_with_set_test() -> any()`

<a name="verify-3"></a>

### verify/3 ###

`verify(Self, Req, Opts) -> any()`

Verify a message. By default, all commitments are verified. The
`committers` key in the request can be used to specify that only the
commitments from specific committers should be verified. Similarly, specific
commitments can be specified using the `commitments` key.

<a name="verify_commitment-3"></a>

### verify_commitment/3 * ###

`verify_commitment(Base, Commitment, Opts) -> any()`

Execute a function for a single commitment in the context of its
parent message.
Note: Assumes that the `commitments` key has already been removed from the
message if applicable.

<a name="verify_test-0"></a>

### verify_test/0 * ###

`verify_test() -> any()`

<a name="with_relevant_commitments-3"></a>

### with_relevant_commitments/3 * ###

`with_relevant_commitments(Base, Req, Opts) -> any()`

Return a message with only the relevant commitments for a given request.
See `commitment_ids_from_request/3` for more information on the request format.


--- END OF FILE: docs/resources/source-code/dev_message.md ---

--- START OF FILE: docs/resources/source-code/dev_meta.md ---
# [Module dev_meta.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_meta.erl)




The hyperbeam meta device, which is the default entry point
for all messages processed by the machine.

<a name="description"></a>

## Description ##
This device executes a
AO-Core singleton request, after first applying the node's
pre-processor, if set. The pre-processor can halt the request by
returning an error, or return a modified version if it deems necessary --
the result of the pre-processor is used as the request for the AO-Core
resolver. Additionally, a post-processor can be set, which is executed after
the AO-Core resolver has returned a result.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_dynamic_keys-1">add_dynamic_keys/1*</a></td><td>Add dynamic keys to the node message.</td></tr><tr><td valign="top"><a href="#add_identity_addresses-1">add_identity_addresses/1*</a></td><td></td></tr><tr><td valign="top"><a href="#adopt_node_message-2">adopt_node_message/2</a></td><td>Attempt to adopt changes to a node message.</td></tr><tr><td valign="top"><a href="#authorized_set_node_msg_succeeds_test-0">authorized_set_node_msg_succeeds_test/0*</a></td><td>Test that we can set the node message if the request is signed by the
owner of the node.</td></tr><tr><td valign="top"><a href="#build-3">build/3</a></td><td>Emits the version number and commit hash of the HyperBEAM node source,
if available.</td></tr><tr><td valign="top"><a href="#buildinfo_test-0">buildinfo_test/0*</a></td><td>Test that version information is available and returned correctly.</td></tr><tr><td valign="top"><a href="#claim_node_test-0">claim_node_test/0*</a></td><td>Test that we can claim the node correctly and set the node message after.</td></tr><tr><td valign="top"><a href="#config_test-0">config_test/0*</a></td><td>Test that we can get the node message.</td></tr><tr><td valign="top"><a href="#embed_status-2">embed_status/2*</a></td><td>Wrap the result of a device call in a status.</td></tr><tr><td valign="top"><a href="#filter_node_msg-2">filter_node_msg/2*</a></td><td>Remove items from the node message that are not encodable into a
message.</td></tr><tr><td valign="top"><a href="#halt_request_test-0">halt_request_test/0*</a></td><td>Test that we can halt a request if the hook returns an error.</td></tr><tr><td valign="top"><a href="#handle-2">handle/2</a></td><td>Normalize and route messages downstream based on their path.</td></tr><tr><td valign="top"><a href="#handle_initialize-2">handle_initialize/2*</a></td><td></td></tr><tr><td valign="top"><a href="#handle_resolve-3">handle_resolve/3*</a></td><td>Handle an AO-Core request, which is a list of messages.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Ensure that the helper function <code>adopt_node_message/2</code> is not exported.</td></tr><tr><td valign="top"><a href="#info-3">info/3</a></td><td>Get/set the node message.</td></tr><tr><td valign="top"><a href="#is-2">is/2</a></td><td>Check if the request in question is signed by a given <code>role</code> on the node.</td></tr><tr><td valign="top"><a href="#is-3">is/3</a></td><td></td></tr><tr><td valign="top"><a href="#is_operator-2">is_operator/2</a></td><td>Utility function for determining if a request is from the <code>operator</code> of
the node.</td></tr><tr><td valign="top"><a href="#maybe_sign-2">maybe_sign/2*</a></td><td>Sign the result of a device call if the node is configured to do so.</td></tr><tr><td valign="top"><a href="#message_to_status-2">message_to_status/2*</a></td><td>Get the HTTP status code from a transaction (if it exists).</td></tr><tr><td valign="top"><a href="#modify_request_test-0">modify_request_test/0*</a></td><td>Test that a hook can modify a request.</td></tr><tr><td valign="top"><a href="#permanent_node_message_test-0">permanent_node_message_test/0*</a></td><td>Test that a permanent node message cannot be changed.</td></tr><tr><td valign="top"><a href="#priv_inaccessible_test-0">priv_inaccessible_test/0*</a></td><td>Test that we can't get the node message if the requested key is private.</td></tr><tr><td valign="top"><a href="#request_response_hooks_test-0">request_response_hooks_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_hook-4">resolve_hook/4*</a></td><td>Execute a hook from the node message upon the user's request.</td></tr><tr><td valign="top"><a href="#status_code-2">status_code/2*</a></td><td>Calculate the appropriate HTTP status code for an AO-Core result.</td></tr><tr><td valign="top"><a href="#unauthorized_set_node_msg_fails_test-0">unauthorized_set_node_msg_fails_test/0*</a></td><td>Test that we can't set the node message if the request is not signed by
the owner of the node.</td></tr><tr><td valign="top"><a href="#uninitialized_node_test-0">uninitialized_node_test/0*</a></td><td>Test that an uninitialized node will not run computation.</td></tr><tr><td valign="top"><a href="#update_node_message-2">update_node_message/2*</a></td><td>Validate that the request is signed by the operator of the node, then
allow them to update the node message.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_dynamic_keys-1"></a>

### add_dynamic_keys/1 * ###

`add_dynamic_keys(NodeMsg) -> any()`

Add dynamic keys to the node message.

<a name="add_identity_addresses-1"></a>

### add_identity_addresses/1 * ###

`add_identity_addresses(NodeMsg) -> any()`

<a name="adopt_node_message-2"></a>

### adopt_node_message/2 ###

`adopt_node_message(Request, NodeMsg) -> any()`

Attempt to adopt changes to a node message.

<a name="authorized_set_node_msg_succeeds_test-0"></a>

### authorized_set_node_msg_succeeds_test/0 * ###

`authorized_set_node_msg_succeeds_test() -> any()`

Test that we can set the node message if the request is signed by the
owner of the node.

<a name="build-3"></a>

### build/3 ###

`build(X1, X2, NodeMsg) -> any()`

Emits the version number and commit hash of the HyperBEAM node source,
if available.

We include the short hash separately, as the length of this hash may change in
the future, depending on the git version/config used to build the node.
Subsequently, rather than embedding the `git-short-hash-length`, for the
avoidance of doubt, we include the short hash separately, as well as its long
hash.

<a name="buildinfo_test-0"></a>

### buildinfo_test/0 * ###

`buildinfo_test() -> any()`

Test that version information is available and returned correctly.

<a name="claim_node_test-0"></a>

### claim_node_test/0 * ###

`claim_node_test() -> any()`

Test that we can claim the node correctly and set the node message after.

<a name="config_test-0"></a>

### config_test/0 * ###

`config_test() -> any()`

Test that we can get the node message.

<a name="embed_status-2"></a>

### embed_status/2 * ###

`embed_status(X1, NodeMsg) -> any()`

Wrap the result of a device call in a status.

<a name="filter_node_msg-2"></a>

### filter_node_msg/2 * ###

`filter_node_msg(Msg, NodeMsg) -> any()`

Remove items from the node message that are not encodable into a
message.

<a name="halt_request_test-0"></a>

### halt_request_test/0 * ###

`halt_request_test() -> any()`

Test that we can halt a request if the hook returns an error.

<a name="handle-2"></a>

### handle/2 ###

`handle(NodeMsg, RawRequest) -> any()`

Normalize and route messages downstream based on their path. Messages
with a `Meta` key are routed to the `handle_meta/2` function, while all
other messages are routed to the `handle_resolve/2` function.

<a name="handle_initialize-2"></a>

### handle_initialize/2 * ###

`handle_initialize(Rest, NodeMsg) -> any()`

<a name="handle_resolve-3"></a>

### handle_resolve/3 * ###

`handle_resolve(Req, Msgs, NodeMsg) -> any()`

Handle an AO-Core request, which is a list of messages. We apply
the node's pre-processor to the request first, and then resolve the request
using the node's AO-Core implementation if its response was `ok`.
After execution, we run the node's `response` hook on the result of
the request before returning the result it grants back to the user.

<a name="info-1"></a>

### info/1 ###

`info(X1) -> any()`

Ensure that the helper function `adopt_node_message/2` is not exported.
The naming of this method carefully avoids a clash with the exported `info/3`
function. We would like the node information to be easily accessible via the
`info` endpoint, but AO-Core also uses `info` as the name of the function
that grants device information. The device call takes two or fewer arguments,
so we are safe to use the name for both purposes in this case, as the user
info call will match the three-argument version of the function. If in the
future the `request` is added as an argument to AO-Core's internal `info`
function, we will need to find a different approach.

<a name="info-3"></a>

### info/3 ###

`info(X1, Request, NodeMsg) -> any()`

Get/set the node message. If the request is a `POST`, we check that the
request is signed by the owner of the node. If not, we return the node message
as-is, aside all keys that are private (according to `hb_private`).

<a name="is-2"></a>

### is/2 ###

`is(Request, NodeMsg) -> any()`

Check if the request in question is signed by a given `role` on the node.
The `role` can be one of `operator` or `initiator`.

<a name="is-3"></a>

### is/3 ###

`is(X1, Request, NodeMsg) -> any()`

<a name="is_operator-2"></a>

### is_operator/2 ###

`is_operator(Request, NodeMsg) -> any()`

Utility function for determining if a request is from the `operator` of
the node.

<a name="maybe_sign-2"></a>

### maybe_sign/2 * ###

`maybe_sign(Res, NodeMsg) -> any()`

Sign the result of a device call if the node is configured to do so.

<a name="message_to_status-2"></a>

### message_to_status/2 * ###

`message_to_status(Item, NodeMsg) -> any()`

Get the HTTP status code from a transaction (if it exists).

<a name="modify_request_test-0"></a>

### modify_request_test/0 * ###

`modify_request_test() -> any()`

Test that a hook can modify a request.

<a name="permanent_node_message_test-0"></a>

### permanent_node_message_test/0 * ###

`permanent_node_message_test() -> any()`

Test that a permanent node message cannot be changed.

<a name="priv_inaccessible_test-0"></a>

### priv_inaccessible_test/0 * ###

`priv_inaccessible_test() -> any()`

Test that we can't get the node message if the requested key is private.

<a name="request_response_hooks_test-0"></a>

### request_response_hooks_test/0 * ###

`request_response_hooks_test() -> any()`

<a name="resolve_hook-4"></a>

### resolve_hook/4 * ###

`resolve_hook(HookName, InitiatingRequest, Body, NodeMsg) -> any()`

Execute a hook from the node message upon the user's request. The
invocation of the hook provides a request of the following form:

```

       /path => request | response
       /request => the original request singleton
       /body => parsed sequence of messages to process | the execution result
```

<a name="status_code-2"></a>

### status_code/2 * ###

`status_code(X1, NodeMsg) -> any()`

Calculate the appropriate HTTP status code for an AO-Core result.
The order of precedence is:
1. The status code from the message.
2. The HTTP representation of the status code.
3. The default status code.

<a name="unauthorized_set_node_msg_fails_test-0"></a>

### unauthorized_set_node_msg_fails_test/0 * ###

`unauthorized_set_node_msg_fails_test() -> any()`

Test that we can't set the node message if the request is not signed by
the owner of the node.

<a name="uninitialized_node_test-0"></a>

### uninitialized_node_test/0 * ###

`uninitialized_node_test() -> any()`

Test that an uninitialized node will not run computation.

<a name="update_node_message-2"></a>

### update_node_message/2 * ###

`update_node_message(Request, NodeMsg) -> any()`

Validate that the request is signed by the operator of the node, then
allow them to update the node message.


--- END OF FILE: docs/resources/source-code/dev_meta.md ---

--- START OF FILE: docs/resources/source-code/dev_monitor.md ---
# [Module dev_monitor.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_monitor.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_monitor-2">add_monitor/2</a></td><td></td></tr><tr><td valign="top"><a href="#end_of_schedule-1">end_of_schedule/1</a></td><td></td></tr><tr><td valign="top"><a href="#execute-2">execute/2</a></td><td></td></tr><tr><td valign="top"><a href="#init-3">init/3</a></td><td></td></tr><tr><td valign="top"><a href="#signal-2">signal/2*</a></td><td></td></tr><tr><td valign="top"><a href="#uses-0">uses/0</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_monitor-2"></a>

### add_monitor/2 ###

`add_monitor(Mon, State) -> any()`

<a name="end_of_schedule-1"></a>

### end_of_schedule/1 ###

`end_of_schedule(State) -> any()`

<a name="execute-2"></a>

### execute/2 ###

`execute(Message, State) -> any()`

<a name="init-3"></a>

### init/3 ###

`init(State, X2, InitState) -> any()`

<a name="signal-2"></a>

### signal/2 * ###

`signal(State, Signal) -> any()`

<a name="uses-0"></a>

### uses/0 ###

`uses() -> any()`


--- END OF FILE: docs/resources/source-code/dev_monitor.md ---

--- START OF FILE: docs/resources/source-code/dev_multipass.md ---
# [Module dev_multipass.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_multipass.erl)




A device that triggers repass events until a certain counter has been
reached.

<a name="description"></a>

## Description ##
This is useful for certain types of stacks that need various
execution passes to be completed in sequence across devices.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#basic_multipass_test-0">basic_multipass_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#handle-4">handle/4*</a></td><td>Forward the keys function to the message device, handle all others
with deduplication.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="basic_multipass_test-0"></a>

### basic_multipass_test/0 * ###

`basic_multipass_test() -> any()`

<a name="handle-4"></a>

### handle/4 * ###

`handle(Key, M1, M2, Opts) -> any()`

Forward the keys function to the message device, handle all others
with deduplication. We only act on the first pass.

<a name="info-1"></a>

### info/1 ###

`info(M1) -> any()`


--- END OF FILE: docs/resources/source-code/dev_multipass.md ---

--- START OF FILE: docs/resources/source-code/dev_name.md ---
# [Module dev_name.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_name.erl)




A device for resolving names to their corresponding values, through the
use of a `resolver` interface.

<a name="description"></a>

## Description ##
Each `resolver` is a message that can be
given a `key` and returns an associated value. The device will attempt to
match the key against each resolver in turn, and return the value of the
first resolver that matches.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#execute_resolver-3">execute_resolver/3*</a></td><td>Execute a resolver with the given key and return its value.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Configure the <code>default</code> key to proxy to the <code>resolver/4</code> function.</td></tr><tr><td valign="top"><a href="#load_and_execute_test-0">load_and_execute_test/0*</a></td><td>Test that we can resolve messages from a name loaded with the device.</td></tr><tr><td valign="top"><a href="#match_resolver-3">match_resolver/3*</a></td><td>Find the first resolver that matches the key and return its value.</td></tr><tr><td valign="top"><a href="#message_lookup_device_resolver-1">message_lookup_device_resolver/1*</a></td><td></td></tr><tr><td valign="top"><a href="#multiple_resolvers_test-0">multiple_resolvers_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#no_resolvers_test-0">no_resolvers_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve-4">resolve/4*</a></td><td>Resolve a name to its corresponding value.</td></tr><tr><td valign="top"><a href="#single_resolver_test-0">single_resolver_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="execute_resolver-3"></a>

### execute_resolver/3 * ###

`execute_resolver(Key, Resolver, Opts) -> any()`

Execute a resolver with the given key and return its value.

<a name="info-1"></a>

### info/1 ###

`info(X1) -> any()`

Configure the `default` key to proxy to the `resolver/4` function.
Exclude the `keys` and `set` keys from being processed by this device, as
these are needed to modify the base message itself.

<a name="load_and_execute_test-0"></a>

### load_and_execute_test/0 * ###

`load_and_execute_test() -> any()`

Test that we can resolve messages from a name loaded with the device.

<a name="match_resolver-3"></a>

### match_resolver/3 * ###

`match_resolver(Key, Resolvers, Opts) -> any()`

Find the first resolver that matches the key and return its value.

<a name="message_lookup_device_resolver-1"></a>

### message_lookup_device_resolver/1 * ###

`message_lookup_device_resolver(Msg) -> any()`

<a name="multiple_resolvers_test-0"></a>

### multiple_resolvers_test/0 * ###

`multiple_resolvers_test() -> any()`

<a name="no_resolvers_test-0"></a>

### no_resolvers_test/0 * ###

`no_resolvers_test() -> any()`

<a name="resolve-4"></a>

### resolve/4 * ###

`resolve(Key, X2, Req, Opts) -> any()`

Resolve a name to its corresponding value. The name is given by the key
called. For example, `GET /~name@1.0/hello&load=false` grants the value of
`hello`. If the `load` key is set to `true`, the value is treated as a
pointer and its contents is loaded from the cache. For example,
`GET /~name@1.0/reference` yields the message at the path specified by the
`reference` key.

<a name="single_resolver_test-0"></a>

### single_resolver_test/0 * ###

`single_resolver_test() -> any()`


--- END OF FILE: docs/resources/source-code/dev_name.md ---

--- START OF FILE: docs/resources/source-code/dev_node_process.md ---
# [Module dev_node_process.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_node_process.erl)




A device that implements the singleton pattern for processes specific
to an individual node.

<a name="description"></a>

## Description ##

This device uses the `local-name@1.0` device to
register processes with names locally, persistenting them across reboots.

Definitions of singleton processes are expected to be found with their
names in the `node_processes` section of the node message.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#augment_definition-2">augment_definition/2*</a></td><td>Augment the given process definition with the node's address.</td></tr><tr><td valign="top"><a href="#generate_test_opts-0">generate_test_opts/0*</a></td><td>Helper function to generate a test environment and its options.</td></tr><tr><td valign="top"><a href="#generate_test_opts-1">generate_test_opts/1*</a></td><td></td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Register a default handler for the device.</td></tr><tr><td valign="top"><a href="#lookup-4">lookup/4*</a></td><td>Lookup a process by name.</td></tr><tr><td valign="top"><a href="#lookup_execute_test-0">lookup_execute_test/0*</a></td><td>Test that a process can be spawned, executed upon, and its result retrieved.</td></tr><tr><td valign="top"><a href="#lookup_no_spawn_test-0">lookup_no_spawn_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#lookup_spawn_test-0">lookup_spawn_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#spawn_register-2">spawn_register/2*</a></td><td>Spawn a new process according to the process definition found in the
node message, and register it with the given name.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="augment_definition-2"></a>

### augment_definition/2 * ###

`augment_definition(BaseDef, Opts) -> any()`

Augment the given process definition with the node's address.

<a name="generate_test_opts-0"></a>

### generate_test_opts/0 * ###

`generate_test_opts() -> any()`

Helper function to generate a test environment and its options.

<a name="generate_test_opts-1"></a>

### generate_test_opts/1 * ###

`generate_test_opts(Defs) -> any()`

<a name="info-1"></a>

### info/1 ###

`info(Opts) -> any()`

Register a default handler for the device. Inherits `keys` and `set`
from the default device.

<a name="lookup-4"></a>

### lookup/4 * ###

`lookup(Name, Base, Req, Opts) -> any()`

Lookup a process by name.

<a name="lookup_execute_test-0"></a>

### lookup_execute_test/0 * ###

`lookup_execute_test() -> any()`

Test that a process can be spawned, executed upon, and its result retrieved.

<a name="lookup_no_spawn_test-0"></a>

### lookup_no_spawn_test/0 * ###

`lookup_no_spawn_test() -> any()`

<a name="lookup_spawn_test-0"></a>

### lookup_spawn_test/0 * ###

`lookup_spawn_test() -> any()`

<a name="spawn_register-2"></a>

### spawn_register/2 * ###

`spawn_register(Name, Opts) -> any()`

Spawn a new process according to the process definition found in the
node message, and register it with the given name.


--- END OF FILE: docs/resources/source-code/dev_node_process.md ---

--- START OF FILE: docs/resources/source-code/dev_p4.md ---
# [Module dev_p4.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_p4.erl)




The HyperBEAM core payment ledger.

<a name="description"></a>

## Description ##

This module allows the operator to
specify another device that can act as a pricing mechanism for transactions
on the node, as well as orchestrating a payment ledger to calculate whether
the node should fulfil services for users.

The device requires the following node message settings in order to function:

- `p4_pricing-device`: The device that will estimate the cost of a request.
- `p4_ledger-device`: The device that will act as a payment ledger.

The pricing device should implement the following keys:

```
<code>GET /estimate?type=pre|post&body=[...]&request=RequestMessage</code><code>GET /price?type=pre|post&body=[...]&request=RequestMessage</code>
```

The `body` key is used to pass either the request or response messages to the
device. The `type` key is used to specify whether the inquiry is for a request
(pre) or a response (post) object. Requests carry lists of messages that will
be executed, while responses carry the results of the execution. The `price`
key may return `infinity` if the node will not serve a user under any
circumstances. Else, the value returned by the `price` key will be passed to
the ledger device as the `amount` key.

A ledger device should implement the following keys:

```
<code>POST /credit?message=PaymentMessage&request=RequestMessage</code><code>POST /charge?amount=PriceMessage&request=RequestMessage</code><code>GET /balance?request=RequestMessage</code>
```

The `type` key is optional and defaults to `pre`. If `type` is set to `post`,
the charge must be applied to the ledger, whereas the `pre` type is used to
check whether the charge would succeed before execution.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#balance-3">balance/3</a></td><td>Get the balance of a user in the ledger.</td></tr><tr><td valign="top"><a href="#faff_test-0">faff_test/0*</a></td><td>Simple test of p4's capabilities with the <code>faff@1.0</code> device.</td></tr><tr><td valign="top"><a href="#hyper_token_ledger-0">hyper_token_ledger/0*</a></td><td></td></tr><tr><td valign="top"><a href="#hyper_token_ledger_test_-0">hyper_token_ledger_test_/0*</a></td><td>Ensure that Lua scripts can be used as pricing and ledger devices.</td></tr><tr><td valign="top"><a href="#is_chargable_req-2">is_chargable_req/2*</a></td><td>The node operator may elect to make certain routes non-chargable, using
the <code>routes</code> syntax also used to declare routes in <code>router@1.0</code>.</td></tr><tr><td valign="top"><a href="#non_chargable_route_test-0">non_chargable_route_test/0*</a></td><td>Test that a non-chargable route is not charged for.</td></tr><tr><td valign="top"><a href="#request-3">request/3</a></td><td>Estimate the cost of a transaction and decide whether to proceed with
a request.</td></tr><tr><td valign="top"><a href="#response-3">response/3</a></td><td>Postprocess the request after it has been fulfilled.</td></tr><tr><td valign="top"><a href="#test_opts-1">test_opts/1*</a></td><td></td></tr><tr><td valign="top"><a href="#test_opts-2">test_opts/2*</a></td><td></td></tr><tr><td valign="top"><a href="#test_opts-3">test_opts/3*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="balance-3"></a>

### balance/3 ###

`balance(X1, Req, NodeMsg) -> any()`

Get the balance of a user in the ledger.

<a name="faff_test-0"></a>

### faff_test/0 * ###

`faff_test() -> any()`

Simple test of p4's capabilities with the `faff@1.0` device.

<a name="hyper_token_ledger-0"></a>

### hyper_token_ledger/0 * ###

`hyper_token_ledger() -> any()`

<a name="hyper_token_ledger_test_-0"></a>

### hyper_token_ledger_test_/0 * ###

`hyper_token_ledger_test_() -> any()`

Ensure that Lua scripts can be used as pricing and ledger devices. Our
scripts come in two components:
1. A `process` script which is executed as a persistent `local-process` on the
node, and which maintains the state of the ledger. This process runs
`hyper-token.lua` as its base, then adds the logic of `hyper-token-p4.lua`
to it. This secondary script implements the `charge` function that `p4@1.0`
will call to charge a user's account.
2. A `client` script, which is executed as a `p4@1.0` ledger device, which
uses `~push@1.0` to send requests to the ledger `process`.

<a name="is_chargable_req-2"></a>

### is_chargable_req/2 * ###

`is_chargable_req(Req, NodeMsg) -> any()`

The node operator may elect to make certain routes non-chargable, using
the `routes` syntax also used to declare routes in `router@1.0`.

<a name="non_chargable_route_test-0"></a>

### non_chargable_route_test/0 * ###

`non_chargable_route_test() -> any()`

Test that a non-chargable route is not charged for.

<a name="request-3"></a>

### request/3 ###

`request(State, Raw, NodeMsg) -> any()`

Estimate the cost of a transaction and decide whether to proceed with
a request. The default behavior if `pricing-device` or `p4_balances` are
not set is to proceed, so it is important that a user initialize them.

<a name="response-3"></a>

### response/3 ###

`response(State, RawResponse, NodeMsg) -> any()`

Postprocess the request after it has been fulfilled.

<a name="test_opts-1"></a>

### test_opts/1 * ###

`test_opts(Opts) -> any()`

<a name="test_opts-2"></a>

### test_opts/2 * ###

`test_opts(Opts, PricingDev) -> any()`

<a name="test_opts-3"></a>

### test_opts/3 * ###

`test_opts(Opts, PricingDev, LedgerDev) -> any()`


--- END OF FILE: docs/resources/source-code/dev_p4.md ---

--- START OF FILE: docs/resources/source-code/dev_patch.md ---
# [Module dev_patch.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_patch.erl)




A device that can be used to reorganize a message: Moving data from
one path inside it to another.

<a name="description"></a>

## Description ##

This device's function runs in two modes:

1. When using `all` to move all data at the path given in `from` to the
path given in `to`.
2. When using `patches` to move all submessages in the source to the target,
_if_ they have a `method` key of `PATCH` or a `device` key of `patch@1.0`.

Source and destination paths may be prepended by `base:` or `req:` keys to
indicate that they are relative to either of the message's that the
computation is being performed on.

The search order for finding the source and destination keys is as follows,
where `X` is either `from` or `to`:

1. The `patch-X` key of the execution message.
2. The `X` key of the execution message.
3. The `patch-X` key of the request message.
4. The `X` key of the request message.

Additionally, this device implements the standard computation device keys,
allowing it to be used as an element of an execution stack pipeline, etc.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#all-3">all/3</a></td><td>Get the value found at the <code>patch-from</code> key of the message, or the
<code>from</code> key if the former is not present.</td></tr><tr><td valign="top"><a href="#all_mode_test-0">all_mode_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#compute-3">compute/3</a></td><td></td></tr><tr><td valign="top"><a href="#init-3">init/3</a></td><td>Necessary hooks for compliance with the <code>execution-device</code> standard.</td></tr><tr><td valign="top"><a href="#move-4">move/4*</a></td><td>Unified executor for the <code>all</code> and <code>patches</code> modes.</td></tr><tr><td valign="top"><a href="#normalize-3">normalize/3</a></td><td></td></tr><tr><td valign="top"><a href="#patch_to_submessage_test-0">patch_to_submessage_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#patches-3">patches/3</a></td><td>Find relevant <code>PATCH</code> messages in the given source key of the execution
and request messages, and apply them to the given destination key of the
request.</td></tr><tr><td valign="top"><a href="#req_prefix_test-0">req_prefix_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#snapshot-3">snapshot/3</a></td><td></td></tr><tr><td valign="top"><a href="#uninitialized_patch_test-0">uninitialized_patch_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="all-3"></a>

### all/3 ###

`all(Msg1, Msg2, Opts) -> any()`

Get the value found at the `patch-from` key of the message, or the
`from` key if the former is not present. Remove it from the message and set
the new source to the value found.

<a name="all_mode_test-0"></a>

### all_mode_test/0 * ###

`all_mode_test() -> any()`

<a name="compute-3"></a>

### compute/3 ###

`compute(Msg1, Msg2, Opts) -> any()`

<a name="init-3"></a>

### init/3 ###

`init(Msg1, Msg2, Opts) -> any()`

Necessary hooks for compliance with the `execution-device` standard.

<a name="move-4"></a>

### move/4 * ###

`move(Mode, Msg1, Msg2, Opts) -> any()`

Unified executor for the `all` and `patches` modes.

<a name="normalize-3"></a>

### normalize/3 ###

`normalize(Msg1, Msg2, Opts) -> any()`

<a name="patch_to_submessage_test-0"></a>

### patch_to_submessage_test/0 * ###

`patch_to_submessage_test() -> any()`

<a name="patches-3"></a>

### patches/3 ###

`patches(Msg1, Msg2, Opts) -> any()`

Find relevant `PATCH` messages in the given source key of the execution
and request messages, and apply them to the given destination key of the
request.

<a name="req_prefix_test-0"></a>

### req_prefix_test/0 * ###

`req_prefix_test() -> any()`

<a name="snapshot-3"></a>

### snapshot/3 ###

`snapshot(Msg1, Msg2, Opts) -> any()`

<a name="uninitialized_patch_test-0"></a>

### uninitialized_patch_test/0 * ###

`uninitialized_patch_test() -> any()`


--- END OF FILE: docs/resources/source-code/dev_patch.md ---

--- START OF FILE: docs/resources/source-code/dev_poda.md ---
# [Module dev_poda.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_poda.erl)




A simple exemplar decentralized proof of authority consensus algorithm
A simple exemplar decentralized proof of authority consensus algorithm
for AO processes.

<a name="description"></a>

## Description ##

This device is split into two flows, spanning three
actions.

Execution flow:
1. Initialization.
2. Validation of incoming messages before execution.
Commitment flow:
1. Adding commitments to results, either on a CU or MU.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_commitments-3">add_commitments/3*</a></td><td></td></tr><tr><td valign="top"><a href="#commit_to_results-3">commit_to_results/3*</a></td><td></td></tr><tr><td valign="top"><a href="#execute-3">execute/3</a></td><td></td></tr><tr><td valign="top"><a href="#extract_opts-1">extract_opts/1*</a></td><td></td></tr><tr><td valign="top"><a href="#find_process-2">find_process/2*</a></td><td>Find the process that this message is targeting, in order to
determine which commitments to add.</td></tr><tr><td valign="top"><a href="#init-2">init/2</a></td><td></td></tr><tr><td valign="top"><a href="#is_user_signed-1">is_user_signed/1</a></td><td>Determines if a user committed.</td></tr><tr><td valign="top"><a href="#pfiltermap-2">pfiltermap/2*</a></td><td>Helper function for parallel execution of commitment
gathering.</td></tr><tr><td valign="top"><a href="#push-3">push/3</a></td><td>Hook used by the MU pathway (currently) to add commitments to an
outbound message if the computation requests it.</td></tr><tr><td valign="top"><a href="#return_error-2">return_error/2*</a></td><td></td></tr><tr><td valign="top"><a href="#validate-2">validate/2*</a></td><td></td></tr><tr><td valign="top"><a href="#validate_commitment-3">validate_commitment/3*</a></td><td></td></tr><tr><td valign="top"><a href="#validate_stage-3">validate_stage/3*</a></td><td></td></tr><tr><td valign="top"><a href="#validate_stage-4">validate_stage/4*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_commitments-3"></a>

### add_commitments/3 * ###

`add_commitments(NewMsg, S, Opts) -> any()`

<a name="commit_to_results-3"></a>

### commit_to_results/3 * ###

`commit_to_results(Msg, S, Opts) -> any()`

<a name="execute-3"></a>

### execute/3 ###

`execute(Outer, S, Opts) -> any()`

<a name="extract_opts-1"></a>

### extract_opts/1 * ###

`extract_opts(Params) -> any()`

<a name="find_process-2"></a>

### find_process/2 * ###

`find_process(Item, X2) -> any()`

Find the process that this message is targeting, in order to
determine which commitments to add.

<a name="init-2"></a>

### init/2 ###

`init(S, Params) -> any()`

<a name="is_user_signed-1"></a>

### is_user_signed/1 ###

`is_user_signed(Tx) -> any()`

Determines if a user committed

<a name="pfiltermap-2"></a>

### pfiltermap/2 * ###

`pfiltermap(Pred, List) -> any()`

Helper function for parallel execution of commitment
gathering.

<a name="push-3"></a>

### push/3 ###

`push(Item, S, Opts) -> any()`

Hook used by the MU pathway (currently) to add commitments to an
outbound message if the computation requests it.

<a name="return_error-2"></a>

### return_error/2 * ###

`return_error(S, Reason) -> any()`

<a name="validate-2"></a>

### validate/2 * ###

`validate(Msg, Opts) -> any()`

<a name="validate_commitment-3"></a>

### validate_commitment/3 * ###

`validate_commitment(Msg, Comm, Opts) -> any()`

<a name="validate_stage-3"></a>

### validate_stage/3 * ###

`validate_stage(X1, Msg, Opts) -> any()`

<a name="validate_stage-4"></a>

### validate_stage/4 * ###

`validate_stage(X1, Tx, Content, Opts) -> any()`


--- END OF FILE: docs/resources/source-code/dev_poda.md ---

--- START OF FILE: docs/resources/source-code/dev_process_cache.md ---
# [Module dev_process_cache.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_process_cache.erl)




A wrapper around the hb_cache module that provides a more
convenient interface for reading the result of a process at a given slot or
message ID.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#find_latest_outputs-1">find_latest_outputs/1*</a></td><td>Test for retrieving the latest computed output for a process.</td></tr><tr><td valign="top"><a href="#first_with_path-4">first_with_path/4*</a></td><td>Find the latest assignment with the requested path suffix.</td></tr><tr><td valign="top"><a href="#first_with_path-5">first_with_path/5*</a></td><td></td></tr><tr><td valign="top"><a href="#latest-2">latest/2</a></td><td>Retrieve the latest slot for a given process.</td></tr><tr><td valign="top"><a href="#latest-3">latest/3</a></td><td></td></tr><tr><td valign="top"><a href="#latest-4">latest/4</a></td><td></td></tr><tr><td valign="top"><a href="#path-3">path/3*</a></td><td>Calculate the path of a result, given a process ID and a slot.</td></tr><tr><td valign="top"><a href="#path-4">path/4*</a></td><td></td></tr><tr><td valign="top"><a href="#process_cache_suite_test_-0">process_cache_suite_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td>Read the result of a process at a given slot.</td></tr><tr><td valign="top"><a href="#read-3">read/3</a></td><td></td></tr><tr><td valign="top"><a href="#test_write_and_read_output-1">test_write_and_read_output/1*</a></td><td>Test for writing multiple computed outputs, then getting them by
their slot number and by their signed and unsigned IDs.</td></tr><tr><td valign="top"><a href="#write-4">write/4</a></td><td>Write a process computation result to the cache.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="find_latest_outputs-1"></a>

### find_latest_outputs/1 * ###

`find_latest_outputs(Opts) -> any()`

Test for retrieving the latest computed output for a process.

<a name="first_with_path-4"></a>

### first_with_path/4 * ###

`first_with_path(ProcID, RequiredPath, Slots, Opts) -> any()`

Find the latest assignment with the requested path suffix.

<a name="first_with_path-5"></a>

### first_with_path/5 * ###

`first_with_path(ProcID, Required, Rest, Opts, Store) -> any()`

<a name="latest-2"></a>

### latest/2 ###

`latest(ProcID, Opts) -> any()`

Retrieve the latest slot for a given process. Optionally state a limit
on the slot number to search for, as well as a required path that the slot
must have.

<a name="latest-3"></a>

### latest/3 ###

`latest(ProcID, RequiredPath, Opts) -> any()`

<a name="latest-4"></a>

### latest/4 ###

`latest(ProcID, RawRequiredPath, Limit, Opts) -> any()`

<a name="path-3"></a>

### path/3 * ###

`path(ProcID, Ref, Opts) -> any()`

Calculate the path of a result, given a process ID and a slot.

<a name="path-4"></a>

### path/4 * ###

`path(ProcID, Ref, PathSuffix, Opts) -> any()`

<a name="process_cache_suite_test_-0"></a>

### process_cache_suite_test_/0 * ###

`process_cache_suite_test_() -> any()`

<a name="read-2"></a>

### read/2 ###

`read(ProcID, Opts) -> any()`

Read the result of a process at a given slot.

<a name="read-3"></a>

### read/3 ###

`read(ProcID, SlotRef, Opts) -> any()`

<a name="test_write_and_read_output-1"></a>

### test_write_and_read_output/1 * ###

`test_write_and_read_output(Opts) -> any()`

Test for writing multiple computed outputs, then getting them by
their slot number and by their signed and unsigned IDs.

<a name="write-4"></a>

### write/4 ###

`write(ProcID, Slot, Msg, Opts) -> any()`

Write a process computation result to the cache.


--- END OF FILE: docs/resources/source-code/dev_process_cache.md ---

--- START OF FILE: docs/resources/source-code/dev_process_worker.md ---
# [Module dev_process_worker.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_process_worker.erl)




A long-lived process worker that keeps state in memory between
calls.

<a name="description"></a>

## Description ##
Implements the interface of `hb_ao` to receive and respond
to computation requests regarding a process as a singleton.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#await-5">await/5</a></td><td>Await a resolution from a worker executing the <code>process@1.0</code> device.</td></tr><tr><td valign="top"><a href="#group-3">group/3</a></td><td>Returns a group name for a request.</td></tr><tr><td valign="top"><a href="#grouper_test-0">grouper_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#info_test-0">info_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#notify_compute-4">notify_compute/4</a></td><td>Notify any waiters for a specific slot of the computed results.</td></tr><tr><td valign="top"><a href="#notify_compute-5">notify_compute/5*</a></td><td></td></tr><tr><td valign="top"><a href="#process_to_group_name-2">process_to_group_name/2*</a></td><td></td></tr><tr><td valign="top"><a href="#send_notification-4">send_notification/4*</a></td><td></td></tr><tr><td valign="top"><a href="#server-3">server/3</a></td><td>Spawn a new worker process.</td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td>Stop a worker process.</td></tr><tr><td valign="top"><a href="#test_init-0">test_init/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="await-5"></a>

### await/5 ###

`await(Worker, GroupName, Msg1, Msg2, Opts) -> any()`

Await a resolution from a worker executing the `process@1.0` device.

<a name="group-3"></a>

### group/3 ###

`group(Msg1, Msg2, Opts) -> any()`

Returns a group name for a request. The worker is responsible for all
computation work on the same process on a single node, so we use the
process ID as the group name.

<a name="grouper_test-0"></a>

### grouper_test/0 * ###

`grouper_test() -> any()`

<a name="info_test-0"></a>

### info_test/0 * ###

`info_test() -> any()`

<a name="notify_compute-4"></a>

### notify_compute/4 ###

`notify_compute(GroupName, SlotToNotify, Msg3, Opts) -> any()`

Notify any waiters for a specific slot of the computed results.

<a name="notify_compute-5"></a>

### notify_compute/5 * ###

`notify_compute(GroupName, SlotToNotify, Msg3, Opts, Count) -> any()`

<a name="process_to_group_name-2"></a>

### process_to_group_name/2 * ###

`process_to_group_name(Msg1, Opts) -> any()`

<a name="send_notification-4"></a>

### send_notification/4 * ###

`send_notification(Listener, GroupName, SlotToNotify, Msg3) -> any()`

<a name="server-3"></a>

### server/3 ###

`server(GroupName, Msg1, Opts) -> any()`

Spawn a new worker process. This is called after the end of the first
execution of `hb_ao:resolve/3`, so the state we are given is the
already current.

<a name="stop-1"></a>

### stop/1 ###

`stop(Worker) -> any()`

Stop a worker process.

<a name="test_init-0"></a>

### test_init/0 * ###

`test_init() -> any()`


--- END OF FILE: docs/resources/source-code/dev_process_worker.md ---

--- START OF FILE: docs/resources/source-code/dev_process.md ---
# [Module dev_process.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_process.erl)




This module contains the device implementation of AO processes
in AO-Core.

<a name="description"></a>

## Description ##

The core functionality of the module is in 'routing' requests
for different functionality (scheduling, computing, and pushing messages)
to the appropriate device. This is achieved by swapping out the device
of the process message with the necessary component in order to run the
execution, then swapping it back before returning. Computation is supported
as a stack of devices, customizable by the user, while the scheduling
device is (by default) a single device.

This allows the devices to share state as needed. Additionally, after each
computation step the device caches the result at a path relative to the
process definition itself, such that the process message's ID can act as an
immutable reference to the process's growing list of interactions. See
`dev_process_cache` for details.

The external API of the device is as follows:

```

   GET /ID/Schedule:                Returns the messages in the schedule
   POST /ID/Schedule:               Adds a message to the schedule
   GET /ID/Compute/[IDorSlotNum]:   Returns the state of the process after
                                    applying a message
   GET /ID/Now:                     Returns the <code>/Results</code> key of the latest
                                    computed message
```

An example process definition will look like this:

```

       Device: Process/1.0
       Scheduler-Device: Scheduler/1.0
       Execution-Device: Stack/1.0
       Execution-Stack: "Scheduler/1.0", "Cron/1.0", "WASM/1.0", "PoDA/1.0"
       Cron-Frequency: 10-Minutes
       WASM-Image: WASMImageID
       PoDA:
           Device: PoDA/1.0
           Authority: A
           Authority: B
           Authority: C
           Quorum: 2
```

Runtime options:
Cache-Frequency: The number of assignments that will be computed
before the full (restorable) state should be cached.
Cache-Keys:      A list of the keys that should be cached for all
assignments, in addition to `/Results`.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#aos_browsable_state_test_-0">aos_browsable_state_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#aos_compute_test_-0">aos_compute_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#aos_persistent_worker_benchmark_test_-0">aos_persistent_worker_benchmark_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#aos_state_access_via_http_test_-0">aos_state_access_via_http_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#aos_state_patch_test_-0">aos_state_patch_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#as_process-2">as_process/2</a></td><td>Change the message to for that has the device set as this module.</td></tr><tr><td valign="top"><a href="#compute-3">compute/3</a></td><td>Compute the result of an assignment applied to the process state, if it
is the next message.</td></tr><tr><td valign="top"><a href="#compute_slot-5">compute_slot/5*</a></td><td>Compute a single slot for a process, given an initialized state.</td></tr><tr><td valign="top"><a href="#compute_to_slot-5">compute_to_slot/5*</a></td><td>Continually get and apply the next assignment from the scheduler until
we reach the target slot that the user has requested.</td></tr><tr><td valign="top"><a href="#default_device-3">default_device/3*</a></td><td>Returns the default device for a given piece of functionality.</td></tr><tr><td valign="top"><a href="#default_device_index-1">default_device_index/1*</a></td><td></td></tr><tr><td valign="top"><a href="#dev_test_process-0">dev_test_process/0</a></td><td>Generate a device that has a stack of two <code>dev_test</code>s for
execution.</td></tr><tr><td valign="top"><a href="#do_test_restore-0">do_test_restore/0</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_loaded-3">ensure_loaded/3*</a></td><td>Ensure that the process message we have in memory is live and
up-to-date.</td></tr><tr><td valign="top"><a href="#ensure_process_key-2">ensure_process_key/2</a></td><td>Helper function to store a copy of the <code>process</code> key in the message.</td></tr><tr><td valign="top"><a href="#get_scheduler_slot_test-0">get_scheduler_slot_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_wasm_process_by_id_test-0">http_wasm_process_by_id_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>When the info key is called, we should return the process exports.</td></tr><tr><td valign="top"><a href="#init-0">init/0</a></td><td></td></tr><tr><td valign="top"><a href="#init-3">init/3*</a></td><td>Before computation begins, a boot phase is required.</td></tr><tr><td valign="top"><a href="#next-3">next/3*</a></td><td></td></tr><tr><td valign="top"><a href="#now-3">now/3</a></td><td>Returns the known state of the process at either the current slot, or
the latest slot in the cache depending on the <code>process_now_from_cache</code> option.</td></tr><tr><td valign="top"><a href="#now_results_test_-0">now_results_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#persistent_process_test-0">persistent_process_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#prior_results_accessible_test_-0">prior_results_accessible_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#process_id-3">process_id/3</a></td><td>Returns the process ID of the current process.</td></tr><tr><td valign="top"><a href="#push-3">push/3</a></td><td>Recursively push messages to the scheduler until we find a message
that does not lead to any further messages being scheduled.</td></tr><tr><td valign="top"><a href="#recursive_path_resolution_test-0">recursive_path_resolution_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#restore_test_-0">restore_test_/0*</a></td><td>Manually test state restoration without using the cache.</td></tr><tr><td valign="top"><a href="#run_as-4">run_as/4*</a></td><td>Run a message against Msg1, with the device being swapped out for
the device found at <code>Key</code>.</td></tr><tr><td valign="top"><a href="#schedule-3">schedule/3</a></td><td>Wraps functions in the Scheduler device.</td></tr><tr><td valign="top"><a href="#schedule_aos_call-2">schedule_aos_call/2</a></td><td></td></tr><tr><td valign="top"><a href="#schedule_aos_call-3">schedule_aos_call/3</a></td><td></td></tr><tr><td valign="top"><a href="#schedule_on_process_test_-0">schedule_on_process_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#schedule_test_message-3">schedule_test_message/3*</a></td><td></td></tr><tr><td valign="top"><a href="#schedule_test_message-4">schedule_test_message/4*</a></td><td></td></tr><tr><td valign="top"><a href="#schedule_wasm_call-3">schedule_wasm_call/3*</a></td><td></td></tr><tr><td valign="top"><a href="#schedule_wasm_call-4">schedule_wasm_call/4*</a></td><td></td></tr><tr><td valign="top"><a href="#simple_wasm_persistent_worker_benchmark_test-0">simple_wasm_persistent_worker_benchmark_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#slot-3">slot/3</a></td><td></td></tr><tr><td valign="top"><a href="#snapshot-3">snapshot/3</a></td><td></td></tr><tr><td valign="top"><a href="#store_result-5">store_result/5*</a></td><td>Store the resulting state in the cache, potentially with the snapshot
key.</td></tr><tr><td valign="top"><a href="#test_aos_process-0">test_aos_process/0</a></td><td>Generate a process message with a random number, and the
<code>dev_wasm</code> device for execution.</td></tr><tr><td valign="top"><a href="#test_aos_process-1">test_aos_process/1</a></td><td></td></tr><tr><td valign="top"><a href="#test_aos_process-2">test_aos_process/2*</a></td><td></td></tr><tr><td valign="top"><a href="#test_base_process-0">test_base_process/0*</a></td><td>Generate a process message with a random number, and no
executor.</td></tr><tr><td valign="top"><a href="#test_base_process-1">test_base_process/1*</a></td><td></td></tr><tr><td valign="top"><a href="#test_device_compute_test-0">test_device_compute_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_wasm_process-1">test_wasm_process/1</a></td><td></td></tr><tr><td valign="top"><a href="#test_wasm_process-2">test_wasm_process/2*</a></td><td></td></tr><tr><td valign="top"><a href="#wasm_compute_from_id_test-0">wasm_compute_from_id_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#wasm_compute_test-0">wasm_compute_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="aos_browsable_state_test_-0"></a>

### aos_browsable_state_test_/0 * ###

`aos_browsable_state_test_() -> any()`

<a name="aos_compute_test_-0"></a>

### aos_compute_test_/0 * ###

`aos_compute_test_() -> any()`

<a name="aos_persistent_worker_benchmark_test_-0"></a>

### aos_persistent_worker_benchmark_test_/0 * ###

`aos_persistent_worker_benchmark_test_() -> any()`

<a name="aos_state_access_via_http_test_-0"></a>

### aos_state_access_via_http_test_/0 * ###

`aos_state_access_via_http_test_() -> any()`

<a name="aos_state_patch_test_-0"></a>

### aos_state_patch_test_/0 * ###

`aos_state_patch_test_() -> any()`

<a name="as_process-2"></a>

### as_process/2 ###

`as_process(Msg1, Opts) -> any()`

Change the message to for that has the device set as this module.
In situations where the key that is `run_as` returns a message with a
transformed device, this is useful.

<a name="compute-3"></a>

### compute/3 ###

`compute(Msg1, Msg2, Opts) -> any()`

Compute the result of an assignment applied to the process state, if it
is the next message.

<a name="compute_slot-5"></a>

### compute_slot/5 * ###

`compute_slot(ProcID, State, RawInputMsg, ReqMsg, Opts) -> any()`

Compute a single slot for a process, given an initialized state.

<a name="compute_to_slot-5"></a>

### compute_to_slot/5 * ###

`compute_to_slot(ProcID, Msg1, Msg2, TargetSlot, Opts) -> any()`

Continually get and apply the next assignment from the scheduler until
we reach the target slot that the user has requested.

<a name="default_device-3"></a>

### default_device/3 * ###

`default_device(Msg1, Key, Opts) -> any()`

Returns the default device for a given piece of functionality. Expects
the `process/variant` key to be set in the message. The `execution-device`
_must_ be set in all processes aside those marked with `ao.TN.1` variant.
This is in order to ensure that post-mainnet processes do not default to
using infrastructure that should not be present on nodes in the future.

<a name="default_device_index-1"></a>

### default_device_index/1 * ###

`default_device_index(X1) -> any()`

<a name="dev_test_process-0"></a>

### dev_test_process/0 ###

`dev_test_process() -> any()`

Generate a device that has a stack of two `dev_test`s for
execution. This should generate a message state has doubled
`Already-Seen` elements for each assigned slot.

<a name="do_test_restore-0"></a>

### do_test_restore/0 ###

`do_test_restore() -> any()`

<a name="ensure_loaded-3"></a>

### ensure_loaded/3 * ###

`ensure_loaded(Msg1, Msg2, Opts) -> any()`

Ensure that the process message we have in memory is live and
up-to-date.

<a name="ensure_process_key-2"></a>

### ensure_process_key/2 ###

`ensure_process_key(Msg1, Opts) -> any()`

Helper function to store a copy of the `process` key in the message.

<a name="get_scheduler_slot_test-0"></a>

### get_scheduler_slot_test/0 * ###

`get_scheduler_slot_test() -> any()`

<a name="http_wasm_process_by_id_test-0"></a>

### http_wasm_process_by_id_test/0 * ###

`http_wasm_process_by_id_test() -> any()`

<a name="info-1"></a>

### info/1 ###

`info(Msg1) -> any()`

When the info key is called, we should return the process exports.

<a name="init-0"></a>

### init/0 ###

`init() -> any()`

<a name="init-3"></a>

### init/3 * ###

`init(Msg1, Msg2, Opts) -> any()`

Before computation begins, a boot phase is required. This phase
allows devices on the execution stack to initialize themselves. We set the
`Initialized` key to `True` to indicate that the process has been
initialized.

<a name="next-3"></a>

### next/3 * ###

`next(Msg1, Msg2, Opts) -> any()`

<a name="now-3"></a>

### now/3 ###

`now(RawMsg1, Msg2, Opts) -> any()`

Returns the known state of the process at either the current slot, or
the latest slot in the cache depending on the `process_now_from_cache` option.

<a name="now_results_test_-0"></a>

### now_results_test_/0 * ###

`now_results_test_() -> any()`

<a name="persistent_process_test-0"></a>

### persistent_process_test/0 * ###

`persistent_process_test() -> any()`

<a name="prior_results_accessible_test_-0"></a>

### prior_results_accessible_test_/0 * ###

`prior_results_accessible_test_() -> any()`

<a name="process_id-3"></a>

### process_id/3 ###

`process_id(Msg1, Msg2, Opts) -> any()`

Returns the process ID of the current process.

<a name="push-3"></a>

### push/3 ###

`push(Msg1, Msg2, Opts) -> any()`

Recursively push messages to the scheduler until we find a message
that does not lead to any further messages being scheduled.

<a name="recursive_path_resolution_test-0"></a>

### recursive_path_resolution_test/0 * ###

`recursive_path_resolution_test() -> any()`

<a name="restore_test_-0"></a>

### restore_test_/0 * ###

`restore_test_() -> any()`

Manually test state restoration without using the cache.

<a name="run_as-4"></a>

### run_as/4 * ###

`run_as(Key, Msg1, Msg2, Opts) -> any()`

Run a message against Msg1, with the device being swapped out for
the device found at `Key`. After execution, the device is swapped back
to the original device if the device is the same as we left it.

<a name="schedule-3"></a>

### schedule/3 ###

`schedule(Msg1, Msg2, Opts) -> any()`

Wraps functions in the Scheduler device.

<a name="schedule_aos_call-2"></a>

### schedule_aos_call/2 ###

`schedule_aos_call(Msg1, Code) -> any()`

<a name="schedule_aos_call-3"></a>

### schedule_aos_call/3 ###

`schedule_aos_call(Msg1, Code, Opts) -> any()`

<a name="schedule_on_process_test_-0"></a>

### schedule_on_process_test_/0 * ###

`schedule_on_process_test_() -> any()`

<a name="schedule_test_message-3"></a>

### schedule_test_message/3 * ###

`schedule_test_message(Msg1, Text, Opts) -> any()`

<a name="schedule_test_message-4"></a>

### schedule_test_message/4 * ###

`schedule_test_message(Msg1, Text, MsgBase, Opts) -> any()`

<a name="schedule_wasm_call-3"></a>

### schedule_wasm_call/3 * ###

`schedule_wasm_call(Msg1, FuncName, Params) -> any()`

<a name="schedule_wasm_call-4"></a>

### schedule_wasm_call/4 * ###

`schedule_wasm_call(Msg1, FuncName, Params, Opts) -> any()`

<a name="simple_wasm_persistent_worker_benchmark_test-0"></a>

### simple_wasm_persistent_worker_benchmark_test/0 * ###

`simple_wasm_persistent_worker_benchmark_test() -> any()`

<a name="slot-3"></a>

### slot/3 ###

`slot(Msg1, Msg2, Opts) -> any()`

<a name="snapshot-3"></a>

### snapshot/3 ###

`snapshot(RawMsg1, Msg2, Opts) -> any()`

<a name="store_result-5"></a>

### store_result/5 * ###

`store_result(ProcID, Slot, Msg3, Msg2, Opts) -> any()`

Store the resulting state in the cache, potentially with the snapshot
key.

<a name="test_aos_process-0"></a>

### test_aos_process/0 ###

`test_aos_process() -> any()`

Generate a process message with a random number, and the
`dev_wasm` device for execution.

<a name="test_aos_process-1"></a>

### test_aos_process/1 ###

`test_aos_process(Opts) -> any()`

<a name="test_aos_process-2"></a>

### test_aos_process/2 * ###

`test_aos_process(Opts, Stack) -> any()`

<a name="test_base_process-0"></a>

### test_base_process/0 * ###

`test_base_process() -> any()`

Generate a process message with a random number, and no
executor.

<a name="test_base_process-1"></a>

### test_base_process/1 * ###

`test_base_process(Opts) -> any()`

<a name="test_device_compute_test-0"></a>

### test_device_compute_test/0 * ###

`test_device_compute_test() -> any()`

<a name="test_wasm_process-1"></a>

### test_wasm_process/1 ###

`test_wasm_process(WASMImage) -> any()`

<a name="test_wasm_process-2"></a>

### test_wasm_process/2 * ###

`test_wasm_process(WASMImage, Opts) -> any()`

<a name="wasm_compute_from_id_test-0"></a>

### wasm_compute_from_id_test/0 * ###

`wasm_compute_from_id_test() -> any()`

<a name="wasm_compute_test-0"></a>

### wasm_compute_test/0 * ###

`wasm_compute_test() -> any()`


--- END OF FILE: docs/resources/source-code/dev_process.md ---

--- START OF FILE: docs/resources/source-code/dev_push.md ---
# [Module dev_push.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_push.erl)




`push@1.0` takes a message or slot number, evaluates it, and recursively
pushes the resulting messages to other processes.

<a name="description"></a>

## Description ##
The `push`ing mechanism
continues until the there are no remaining messages to push.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#apply_security-4">apply_security/4*</a></td><td>Apply the recipient's security policy to the message.</td></tr><tr><td valign="top"><a href="#apply_security-5">apply_security/5*</a></td><td></td></tr><tr><td valign="top"><a href="#augment_message-3">augment_message/3*</a></td><td>Set the necessary keys in order for the recipient to know where the
message came from.</td></tr><tr><td valign="top"><a href="#calculate_base_id-2">calculate_base_id/2*</a></td><td>Calculate the base ID for a process.</td></tr><tr><td valign="top"><a href="#commit_result-4">commit_result/4*</a></td><td>Attempt to sign a result message with the given committers.</td></tr><tr><td valign="top"><a href="#do_push-3">do_push/3*</a></td><td>Push a message or slot number, including its downstream results.</td></tr><tr><td valign="top"><a href="#extract-2">extract/2*</a></td><td>Return either the <code>target</code> or the <code>hint</code>.</td></tr><tr><td valign="top"><a href="#find_type-2">find_type/2*</a></td><td></td></tr><tr><td valign="top"><a href="#full_push_test_-0">full_push_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#is_async-3">is_async/3*</a></td><td>Determine if the push is asynchronous.</td></tr><tr><td valign="top"><a href="#message_to_legacynet_scheduler_script-0">message_to_legacynet_scheduler_script/0*</a></td><td></td></tr><tr><td valign="top"><a href="#multi_process_push_test_-0">multi_process_push_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#normalize_message-2">normalize_message/2*</a></td><td>Augment the message with from-* keys, if it doesn't already have them.</td></tr><tr><td valign="top"><a href="#parse_redirect-2">parse_redirect/2*</a></td><td></td></tr><tr><td valign="top"><a href="#ping_pong_script-1">ping_pong_script/1*</a></td><td>Test that a message that generates another message which resides on an
ANS-104 scheduler leads to <code>~push@1.0</code> re-signing the message correctly.</td></tr><tr><td valign="top"><a href="#push-3">push/3</a></td><td>Push either a message or an assigned slot number.</td></tr><tr><td valign="top"><a href="#push_as_identity_test_-0">push_as_identity_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#push_prompts_encoding_change-0">push_prompts_encoding_change/0*</a></td><td></td></tr><tr><td valign="top"><a href="#push_prompts_encoding_change_test_-0">push_prompts_encoding_change_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#push_result_message-4">push_result_message/4*</a></td><td>Push a downstream message result.</td></tr><tr><td valign="top"><a href="#push_with_mode-3">push_with_mode/3*</a></td><td></td></tr><tr><td valign="top"><a href="#push_with_redirect_hint_test_disabled-0">push_with_redirect_hint_test_disabled/0*</a></td><td></td></tr><tr><td valign="top"><a href="#remote_schedule_result-3">remote_schedule_result/3*</a></td><td></td></tr><tr><td valign="top"><a href="#reply_script-0">reply_script/0*</a></td><td></td></tr><tr><td valign="top"><a href="#schedule_initial_message-3">schedule_initial_message/3*</a></td><td>Push a message or a process, prior to pushing the resulting slot number.</td></tr><tr><td valign="top"><a href="#schedule_result-4">schedule_result/4*</a></td><td>Add the necessary keys to the message to be scheduled, then schedule it.</td></tr><tr><td valign="top"><a href="#schedule_result-5">schedule_result/5*</a></td><td></td></tr><tr><td valign="top"><a href="#split_target-1">split_target/1*</a></td><td>Split the target into the process ID and the optional query string.</td></tr><tr><td valign="top"><a href="#target_process-2">target_process/2*</a></td><td>Find the target process ID for a message to push.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="apply_security-4"></a>

### apply_security/4 * ###

`apply_security(Msg, TargetProcess, Codec, Opts) -> any()`

Apply the recipient's security policy to the message. Observes the
following parameters in order to calculate the appropriate security policy:
- `policy`: A message that generates a security policy message.
- `authority`: A single committer, or list of comma separated committers.
- (Default: Signs with default wallet)

<a name="apply_security-5"></a>

### apply_security/5 * ###

`apply_security(X1, Msg, TargetProcess, Codec, Opts) -> any()`

<a name="augment_message-3"></a>

### augment_message/3 * ###

`augment_message(Origin, ToSched, Opts) -> any()`

Set the necessary keys in order for the recipient to know where the
message came from.

<a name="calculate_base_id-2"></a>

### calculate_base_id/2 * ###

`calculate_base_id(GivenProcess, Opts) -> any()`

Calculate the base ID for a process. The base ID is not just the
uncommitted process ID. It also excludes the `authority` and `scheduler`
keys.

<a name="commit_result-4"></a>

### commit_result/4 * ###

`commit_result(Msg, Committers, Codec, Opts) -> any()`

Attempt to sign a result message with the given committers.

<a name="do_push-3"></a>

### do_push/3 * ###

`do_push(PrimaryProcess, Assignment, Opts) -> any()`

Push a message or slot number, including its downstream results.

<a name="extract-2"></a>

### extract/2 * ###

`extract(X1, Raw) -> any()`

Return either the `target` or the `hint`.

<a name="find_type-2"></a>

### find_type/2 * ###

`find_type(Req, Opts) -> any()`

<a name="full_push_test_-0"></a>

### full_push_test_/0 * ###

`full_push_test_() -> any()`

<a name="is_async-3"></a>

### is_async/3 * ###

`is_async(Process, Req, Opts) -> any()`

Determine if the push is asynchronous.

<a name="message_to_legacynet_scheduler_script-0"></a>

### message_to_legacynet_scheduler_script/0 * ###

`message_to_legacynet_scheduler_script() -> any()`

<a name="multi_process_push_test_-0"></a>

### multi_process_push_test_/0 * ###

`multi_process_push_test_() -> any()`

<a name="normalize_message-2"></a>

### normalize_message/2 * ###

`normalize_message(MsgToPush, Opts) -> any()`

Augment the message with from-* keys, if it doesn't already have them.

<a name="parse_redirect-2"></a>

### parse_redirect/2 * ###

`parse_redirect(Location, Opts) -> any()`

<a name="ping_pong_script-1"></a>

### ping_pong_script/1 * ###

`ping_pong_script(Limit) -> any()`

Test that a message that generates another message which resides on an
ANS-104 scheduler leads to `~push@1.0` re-signing the message correctly.
Requires `ENABLE_GENESIS_WASM` to be enabled.

<a name="push-3"></a>

### push/3 ###

`push(Base, Req, Opts) -> any()`

Push either a message or an assigned slot number. If a `Process` is
provided in the `body` of the request, it will be scheduled (initializing
it if it does not exist). Otherwise, the message specified by the given
`slot` key will be pushed.

Optional parameters:

`/result-depth`: The depth to which the full contents of the result
will be included in the response. Default: 1, returning
the full result of the first message, but only the 'tree'
of downstream messages.

`/push-mode`: Whether or not the push should be done asynchronously.
Default: `sync`, pushing synchronously.

<a name="push_as_identity_test_-0"></a>

### push_as_identity_test_/0 * ###

`push_as_identity_test_() -> any()`

<a name="push_prompts_encoding_change-0"></a>

### push_prompts_encoding_change/0 * ###

`push_prompts_encoding_change() -> any()`

<a name="push_prompts_encoding_change_test_-0"></a>

### push_prompts_encoding_change_test_/0 * ###

`push_prompts_encoding_change_test_() -> any()`

<a name="push_result_message-4"></a>

### push_result_message/4 * ###

`push_result_message(TargetProcess, MsgToPush, Origin, Opts) -> any()`

Push a downstream message result. The `Origin` map contains information
about the origin of the message: The process that originated the message,
the slot number from which it was sent, and the outbox key of the message,
and the depth to which downstream results should be included in the message.

<a name="push_with_mode-3"></a>

### push_with_mode/3 * ###

`push_with_mode(Process, Req, Opts) -> any()`

<a name="push_with_redirect_hint_test_disabled-0"></a>

### push_with_redirect_hint_test_disabled/0 * ###

`push_with_redirect_hint_test_disabled() -> any()`

<a name="remote_schedule_result-3"></a>

### remote_schedule_result/3 * ###

`remote_schedule_result(Location, SignedReq, Opts) -> any()`

<a name="reply_script-0"></a>

### reply_script/0 * ###

`reply_script() -> any()`

<a name="schedule_initial_message-3"></a>

### schedule_initial_message/3 * ###

`schedule_initial_message(Base, Req, Opts) -> any()`

Push a message or a process, prior to pushing the resulting slot number.

<a name="schedule_result-4"></a>

### schedule_result/4 * ###

`schedule_result(TargetProcess, MsgToPush, Origin, Opts) -> any()`

Add the necessary keys to the message to be scheduled, then schedule it.
If the remote scheduler does not support the given codec, it will be
downgraded and re-signed.

<a name="schedule_result-5"></a>

### schedule_result/5 * ###

`schedule_result(TargetProcess, MsgToPush, Codec, Origin, Opts) -> any()`

<a name="split_target-1"></a>

### split_target/1 * ###

`split_target(RawTarget) -> any()`

Split the target into the process ID and the optional query string.

<a name="target_process-2"></a>

### target_process/2 * ###

`target_process(MsgToPush, Opts) -> any()`

Find the target process ID for a message to push.


--- END OF FILE: docs/resources/source-code/dev_push.md ---

--- START OF FILE: docs/resources/source-code/dev_relay.md ---
# [Module dev_relay.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_relay.erl)




This module implements the relay device, which is responsible for
relaying messages between nodes and other HTTP(S) endpoints.

<a name="description"></a>

## Description ##

It can be called in either `call` or `cast` mode. In `call` mode, it
returns a `{ok, Result}` tuple, where `Result` is the response from the
remote peer to the message sent. In `cast` mode, the invocation returns
immediately, and the message is relayed asynchronously. No response is given
and the device returns `{ok, <<"OK">>}`.

Example usage:

```

       curl /~relay@.1.0/call?method=GET?0.path=https://www.arweave.net/
```
<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#call-3">call/3</a></td><td>Execute a <code>call</code> request using a node's routes.</td></tr><tr><td valign="top"><a href="#call_get_test-0">call_get_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#cast-3">cast/3</a></td><td>Execute a request in the same way as <code>call/3</code>, but asynchronously.</td></tr><tr><td valign="top"><a href="#commit_request_test-0">commit_request_test/0*</a></td><td>Test that a <code>relay@1.0/call</code> correctly commits requests as specified.</td></tr><tr><td valign="top"><a href="#relay_nearest_test-0">relay_nearest_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#request-3">request/3</a></td><td>Preprocess a request to check if it should be relayed to a different node.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="call-3"></a>

### call/3 ###

`call(M1, RawM2, Opts) -> any()`

Execute a `call` request using a node's routes.

Supports the following options:
- `target`: The target message to relay. Defaults to the original message.
- `relay-path`: The path to relay the message to. Defaults to the original path.
- `method`: The method to use for the request. Defaults to the original method.
- `commit-request`: Whether the request should be committed before dispatching.
Defaults to `false`.

<a name="call_get_test-0"></a>

### call_get_test/0 * ###

`call_get_test() -> any()`

<a name="cast-3"></a>

### cast/3 ###

`cast(M1, M2, Opts) -> any()`

Execute a request in the same way as `call/3`, but asynchronously. Always
returns `<<"OK">>`.

<a name="commit_request_test-0"></a>

### commit_request_test/0 * ###

`commit_request_test() -> any()`

Test that a `relay@1.0/call` correctly commits requests as specified.
We validate this by configuring two nodes: One that will execute a given
request from a user, but only if the request is committed. The other node
re-routes all requests to the first node, using `call`'s `commit-request`
key to sign the request during proxying. The initial request is not signed,
such that the first node would otherwise reject the request outright.

<a name="relay_nearest_test-0"></a>

### relay_nearest_test/0 * ###

`relay_nearest_test() -> any()`

<a name="request-3"></a>

### request/3 ###

`request(Msg1, Msg2, Opts) -> any()`

Preprocess a request to check if it should be relayed to a different node.


--- END OF FILE: docs/resources/source-code/dev_relay.md ---

--- START OF FILE: docs/resources/source-code/dev_router.md ---
# [Module dev_router.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_router.erl)




A device that routes outbound messages from the node to their
appropriate network recipients via HTTP.

<a name="description"></a>

## Description ##

All messages are initially
routed to a single process per node, which then load-balances them
between downstream workers that perform the actual requests.

The routes for the router are defined in the `routes` key of the `Opts`,
as a precidence-ordered list of maps. The first map that matches the
message will be used to determine the route.

Multiple nodes can be specified as viable for a single route, with the
`Choose` key determining how many nodes to choose from the list (defaulting
to 1). The `Strategy` key determines the load distribution strategy,
which can be one of `Random`, `By-Base`, or `Nearest`. The route may also
define additional parallel execution parameters, which are used by the
`hb_http` module to manage control of requests.

The structure of the routes should be as follows:

```

       Node?: The node to route the message to.
       Nodes?: A list of nodes to route the message to.
       Strategy?: The load distribution strategy to use.
       Choose?: The number of nodes to choose from the list.
       Template?: A message template to match the message against, either as a
                  map or a path regex.
```
<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_route_test-0">add_route_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#apply_route-3">apply_route/3*</a></td><td>Apply a node map's rules for transforming the path of the message.</td></tr><tr><td valign="top"><a href="#apply_routes-3">apply_routes/3*</a></td><td>Generate a <code>uri</code> key for each node in a route.</td></tr><tr><td valign="top"><a href="#binary_to_bignum-1">binary_to_bignum/1*</a></td><td>Cast a human-readable or native-encoded ID to a big integer.</td></tr><tr><td valign="top"><a href="#by_base_determinism_test-0">by_base_determinism_test/0*</a></td><td>Ensure that <code>By-Base</code> always chooses the same node for the same
hashpath.</td></tr><tr><td valign="top"><a href="#choose-5">choose/5*</a></td><td>Implements the load distribution strategies if given a cluster.</td></tr><tr><td valign="top"><a href="#choose_1_test-1">choose_1_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#choose_n_test-1">choose_n_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#device_call_from_singleton_test-0">device_call_from_singleton_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#do_apply_route-3">do_apply_route/3*</a></td><td></td></tr><tr><td valign="top"><a href="#dynamic_route_provider_test-0">dynamic_route_provider_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#dynamic_router-0">dynamic_router/0*</a></td><td></td></tr><tr><td valign="top"><a href="#dynamic_router_test_-0">dynamic_router_test_/0*</a></td><td>Example of a Lua module being used as the <code>route_provider</code> for a
HyperBEAM node.</td></tr><tr><td valign="top"><a href="#dynamic_routing_by_performance-0">dynamic_routing_by_performance/0*</a></td><td></td></tr><tr><td valign="top"><a href="#dynamic_routing_by_performance_test_-0">dynamic_routing_by_performance_test_/0*</a></td><td>Demonstrates routing tables being dynamically created and adjusted
according to the real-time performance of nodes.</td></tr><tr><td valign="top"><a href="#explicit_route_test-0">explicit_route_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#extract_base-2">extract_base/2*</a></td><td>Extract the base message ID from a request message.</td></tr><tr><td valign="top"><a href="#field_distance-2">field_distance/2*</a></td><td>Calculate the minimum distance between two numbers
(either progressing backwards or forwards), assuming a
256-bit field.</td></tr><tr><td valign="top"><a href="#find_target_path-2">find_target_path/2*</a></td><td>Find the target path to route for a request message.</td></tr><tr><td valign="top"><a href="#generate_hashpaths-1">generate_hashpaths/1*</a></td><td></td></tr><tr><td valign="top"><a href="#generate_nodes-1">generate_nodes/1*</a></td><td></td></tr><tr><td valign="top"><a href="#get_routes_test-0">get_routes_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Exported function for getting device info, controls which functions are
exposed via the device API.</td></tr><tr><td valign="top"><a href="#info-3">info/3</a></td><td>HTTP info response providing information about this device.</td></tr><tr><td valign="top"><a href="#load_routes-1">load_routes/1*</a></td><td>Load the current routes for the node.</td></tr><tr><td valign="top"><a href="#local_dynamic_router-0">local_dynamic_router/0*</a></td><td></td></tr><tr><td valign="top"><a href="#local_dynamic_router_test_-0">local_dynamic_router_test_/0*</a></td><td>Example of a Lua module being used as the <code>route_provider</code> for a
HyperBEAM node.</td></tr><tr><td valign="top"><a href="#local_process_route_provider-0">local_process_route_provider/0*</a></td><td></td></tr><tr><td valign="top"><a href="#local_process_route_provider_test_-0">local_process_route_provider_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#lowest_distance-1">lowest_distance/1*</a></td><td>Find the node with the lowest distance to the given hashpath.</td></tr><tr><td valign="top"><a href="#lowest_distance-2">lowest_distance/2*</a></td><td></td></tr><tr><td valign="top"><a href="#match-3">match/3</a></td><td>Find the first matching template in a list of known routes.</td></tr><tr><td valign="top"><a href="#match_routes-3">match_routes/3*</a></td><td></td></tr><tr><td valign="top"><a href="#match_routes-4">match_routes/4*</a></td><td></td></tr><tr><td valign="top"><a href="#preprocess-3">preprocess/3</a></td><td>Preprocess a request to check if it should be relayed to a different node.</td></tr><tr><td valign="top"><a href="#register-3">register/3</a></td><td>Register function that allows telling the current node to register
a new route with a remote router node.</td></tr><tr><td valign="top"><a href="#request_hook_reroute_to_nearest_test-0">request_hook_reroute_to_nearest_test/0*</a></td><td>Test that the <code>preprocess/3</code> function re-routes a request to remote
peers via <code>~relay@1.0</code>, according to the node's routing table.</td></tr><tr><td valign="top"><a href="#route-2">route/2</a></td><td>Find the appropriate route for the given message.</td></tr><tr><td valign="top"><a href="#route-3">route/3</a></td><td></td></tr><tr><td valign="top"><a href="#route_provider_test-0">route_provider_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#route_regex_matches_test-0">route_regex_matches_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#route_template_message_matches_test-0">route_template_message_matches_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#routes-3">routes/3</a></td><td>Device function that returns all known routes.</td></tr><tr><td valign="top"><a href="#simulate-4">simulate/4*</a></td><td></td></tr><tr><td valign="top"><a href="#simulation_distribution-2">simulation_distribution/2*</a></td><td></td></tr><tr><td valign="top"><a href="#simulation_occurences-2">simulation_occurences/2*</a></td><td></td></tr><tr><td valign="top"><a href="#strategy_suite_test_-0">strategy_suite_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#template_matches-3">template_matches/3*</a></td><td>Check if a message matches a message template or path regex.</td></tr><tr><td valign="top"><a href="#unique_nodes-1">unique_nodes/1*</a></td><td></td></tr><tr><td valign="top"><a href="#unique_test-1">unique_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#weighted_random_strategy_test-0">weighted_random_strategy_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#within_norms-3">within_norms/3*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_route_test-0"></a>

### add_route_test/0 * ###

`add_route_test() -> any()`

<a name="apply_route-3"></a>

### apply_route/3 * ###

`apply_route(Msg, Route, Opts) -> any()`

Apply a node map's rules for transforming the path of the message.
Supports the following keys:
- `opts`: A map of options to pass to the request.
- `prefix`: The prefix to add to the path.
- `suffix`: The suffix to add to the path.
- `replace`: A regex to replace in the path.

<a name="apply_routes-3"></a>

### apply_routes/3 * ###

`apply_routes(Msg, R, Opts) -> any()`

Generate a `uri` key for each node in a route.

<a name="binary_to_bignum-1"></a>

### binary_to_bignum/1 * ###

`binary_to_bignum(Bin) -> any()`

Cast a human-readable or native-encoded ID to a big integer.

<a name="by_base_determinism_test-0"></a>

### by_base_determinism_test/0 * ###

`by_base_determinism_test() -> any()`

Ensure that `By-Base` always chooses the same node for the same
hashpath.

<a name="choose-5"></a>

### choose/5 * ###

`choose(N, X2, Hashpath, Nodes, Opts) -> any()`

Implements the load distribution strategies if given a cluster.

<a name="choose_1_test-1"></a>

### choose_1_test/1 * ###

`choose_1_test(Strategy) -> any()`

<a name="choose_n_test-1"></a>

### choose_n_test/1 * ###

`choose_n_test(Strategy) -> any()`

<a name="device_call_from_singleton_test-0"></a>

### device_call_from_singleton_test/0 * ###

`device_call_from_singleton_test() -> any()`

<a name="do_apply_route-3"></a>

### do_apply_route/3 * ###

`do_apply_route(X1, R, Opts) -> any()`

<a name="dynamic_route_provider_test-0"></a>

### dynamic_route_provider_test/0 * ###

`dynamic_route_provider_test() -> any()`

<a name="dynamic_router-0"></a>

### dynamic_router/0 * ###

`dynamic_router() -> any()`

<a name="dynamic_router_test_-0"></a>

### dynamic_router_test_/0 * ###

`dynamic_router_test_() -> any()`

Example of a Lua module being used as the `route_provider` for a
HyperBEAM node. The module utilized in this example dynamically adjusts the
likelihood of routing to a given node, depending upon price and performance.
also include preprocessing support for routing

<a name="dynamic_routing_by_performance-0"></a>

### dynamic_routing_by_performance/0 * ###

`dynamic_routing_by_performance() -> any()`

<a name="dynamic_routing_by_performance_test_-0"></a>

### dynamic_routing_by_performance_test_/0 * ###

`dynamic_routing_by_performance_test_() -> any()`

Demonstrates routing tables being dynamically created and adjusted
according to the real-time performance of nodes. This test utilizes the
`dynamic-router` script to manage routes and recalculate weights based on the
reported performance.

<a name="explicit_route_test-0"></a>

### explicit_route_test/0 * ###

`explicit_route_test() -> any()`

<a name="extract_base-2"></a>

### extract_base/2 * ###

`extract_base(RawPath, Opts) -> any()`

Extract the base message ID from a request message. Produces a single
binary ID that can be used for routing decisions.

<a name="field_distance-2"></a>

### field_distance/2 * ###

`field_distance(A, B) -> any()`

Calculate the minimum distance between two numbers
(either progressing backwards or forwards), assuming a
256-bit field.

<a name="find_target_path-2"></a>

### find_target_path/2 * ###

`find_target_path(Msg, Opts) -> any()`

Find the target path to route for a request message.

<a name="generate_hashpaths-1"></a>

### generate_hashpaths/1 * ###

`generate_hashpaths(Runs) -> any()`

<a name="generate_nodes-1"></a>

### generate_nodes/1 * ###

`generate_nodes(N) -> any()`

<a name="get_routes_test-0"></a>

### get_routes_test/0 * ###

`get_routes_test() -> any()`

<a name="info-1"></a>

### info/1 ###

`info(X1) -> any()`

Exported function for getting device info, controls which functions are
exposed via the device API.

<a name="info-3"></a>

### info/3 ###

`info(Msg1, Msg2, Opts) -> any()`

HTTP info response providing information about this device

<a name="load_routes-1"></a>

### load_routes/1 * ###

`load_routes(Opts) -> any()`

Load the current routes for the node. Allows either explicit routes from
the node message's `routes` key, or dynamic routes generated by resolving the
`route_provider` message.

<a name="local_dynamic_router-0"></a>

### local_dynamic_router/0 * ###

`local_dynamic_router() -> any()`

<a name="local_dynamic_router_test_-0"></a>

### local_dynamic_router_test_/0 * ###

`local_dynamic_router_test_() -> any()`

Example of a Lua module being used as the `route_provider` for a
HyperBEAM node. The module utilized in this example dynamically adjusts the
likelihood of routing to a given node, depending upon price and performance.

<a name="local_process_route_provider-0"></a>

### local_process_route_provider/0 * ###

`local_process_route_provider() -> any()`

<a name="local_process_route_provider_test_-0"></a>

### local_process_route_provider_test_/0 * ###

`local_process_route_provider_test_() -> any()`

<a name="lowest_distance-1"></a>

### lowest_distance/1 * ###

`lowest_distance(Nodes) -> any()`

Find the node with the lowest distance to the given hashpath.

<a name="lowest_distance-2"></a>

### lowest_distance/2 * ###

`lowest_distance(Nodes, X) -> any()`

<a name="match-3"></a>

### match/3 ###

`match(Base, Req, Opts) -> any()`

Find the first matching template in a list of known routes. Allows the
path to be specified by either the explicit `path` (for internal use by this
module), or `route-path` for use by external devices and users.

<a name="match_routes-3"></a>

### match_routes/3 * ###

`match_routes(ToMatch, Routes, Opts) -> any()`

<a name="match_routes-4"></a>

### match_routes/4 * ###

`match_routes(ToMatch, Routes, Keys, Opts) -> any()`

<a name="preprocess-3"></a>

### preprocess/3 ###

`preprocess(Msg1, Msg2, Opts) -> any()`

Preprocess a request to check if it should be relayed to a different node.

<a name="register-3"></a>

### register/3 ###

`register(M1, M2, Opts) -> any()`

Register function that allows telling the current node to register
a new route with a remote router node. This function should also be idempotent.
so that it can be called only once.

<a name="request_hook_reroute_to_nearest_test-0"></a>

### request_hook_reroute_to_nearest_test/0 * ###

`request_hook_reroute_to_nearest_test() -> any()`

Test that the `preprocess/3` function re-routes a request to remote
peers via `~relay@1.0`, according to the node's routing table.

<a name="route-2"></a>

### route/2 ###

`route(Msg, Opts) -> any()`

Find the appropriate route for the given message. If we are able to
resolve to a single host+path, we return that directly. Otherwise, we return
the matching route (including a list of nodes under `nodes`) from the list of
routes.

If we have a route that has multiple resolving nodes, check
the load distribution strategy and choose a node. Supported strategies:

```

            All: Return all nodes (default).
         Random: Distribute load evenly across all nodes, non-deterministically.
        By-Base: According to the base message's hashpath.
      By-Weight: According to the node's <code>weight</code> key.
        Nearest: According to the distance of the node's wallet address to the
                 base message's hashpath.
```

`By-Base` will ensure that all traffic for the same hashpath is routed to the
same node, minimizing work duplication, while `Random` ensures a more even
distribution of the requests.

Can operate as a `~router@1.0` device, which will ignore the base message,
routing based on the Opts and request message provided, or as a standalone
function, taking only the request message and the `Opts` map.

<a name="route-3"></a>

### route/3 ###

`route(X1, Msg, Opts) -> any()`

<a name="route_provider_test-0"></a>

### route_provider_test/0 * ###

`route_provider_test() -> any()`

<a name="route_regex_matches_test-0"></a>

### route_regex_matches_test/0 * ###

`route_regex_matches_test() -> any()`

<a name="route_template_message_matches_test-0"></a>

### route_template_message_matches_test/0 * ###

`route_template_message_matches_test() -> any()`

<a name="routes-3"></a>

### routes/3 ###

`routes(M1, M2, Opts) -> any()`

Device function that returns all known routes.

<a name="simulate-4"></a>

### simulate/4 * ###

`simulate(Runs, ChooseN, Nodes, Strategy) -> any()`

<a name="simulation_distribution-2"></a>

### simulation_distribution/2 * ###

`simulation_distribution(SimRes, Nodes) -> any()`

<a name="simulation_occurences-2"></a>

### simulation_occurences/2 * ###

`simulation_occurences(SimRes, Nodes) -> any()`

<a name="strategy_suite_test_-0"></a>

### strategy_suite_test_/0 * ###

`strategy_suite_test_() -> any()`

<a name="template_matches-3"></a>

### template_matches/3 * ###

`template_matches(ToMatch, Template, Opts) -> any()`

Check if a message matches a message template or path regex.

<a name="unique_nodes-1"></a>

### unique_nodes/1 * ###

`unique_nodes(Simulation) -> any()`

<a name="unique_test-1"></a>

### unique_test/1 * ###

`unique_test(Strategy) -> any()`

<a name="weighted_random_strategy_test-0"></a>

### weighted_random_strategy_test/0 * ###

`weighted_random_strategy_test() -> any()`

<a name="within_norms-3"></a>

### within_norms/3 * ###

`within_norms(SimRes, Nodes, TestSize) -> any()`


--- END OF FILE: docs/resources/source-code/dev_router.md ---

--- START OF FILE: docs/resources/source-code/dev_scheduler_cache.md ---
# [Module dev_scheduler_cache.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_scheduler_cache.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#latest-2">latest/2</a></td><td>Get the latest assignment from the cache.</td></tr><tr><td valign="top"><a href="#list-2">list/2</a></td><td>Get the assignments for a process.</td></tr><tr><td valign="top"><a href="#read-3">read/3</a></td><td>Get an assignment message from the cache.</td></tr><tr><td valign="top"><a href="#read_location-2">read_location/2</a></td><td>Read the latest known scheduler location for an address.</td></tr><tr><td valign="top"><a href="#write-2">write/2</a></td><td>Write an assignment message into the cache.</td></tr><tr><td valign="top"><a href="#write_location-2">write_location/2</a></td><td>Write the latest known scheduler location for an address.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="latest-2"></a>

### latest/2 ###

`latest(ProcID, Opts) -> any()`

Get the latest assignment from the cache.

<a name="list-2"></a>

### list/2 ###

`list(ProcID, Opts) -> any()`

Get the assignments for a process.

<a name="read-3"></a>

### read/3 ###

`read(ProcID, Slot, Opts) -> any()`

Get an assignment message from the cache.

<a name="read_location-2"></a>

### read_location/2 ###

`read_location(Address, Opts) -> any()`

Read the latest known scheduler location for an address.

<a name="write-2"></a>

### write/2 ###

`write(Assignment, Opts) -> any()`

Write an assignment message into the cache.

<a name="write_location-2"></a>

### write_location/2 ###

`write_location(LocationMsg, Opts) -> any()`

Write the latest known scheduler location for an address.


--- END OF FILE: docs/resources/source-code/dev_scheduler_cache.md ---

--- START OF FILE: docs/resources/source-code/dev_scheduler_formats.md ---
# [Module dev_scheduler_formats.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_scheduler_formats.erl)




This module is used by dev_scheduler in order to produce outputs that
are compatible with various forms of AO clients.

<a name="description"></a>

## Description ##

It features two main formats:

- `application/json`
- `application/http`

The `application/json` format is a legacy format that is not recommended for
new integrations of the AO protocol.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#aos2_normalize_data-1">aos2_normalize_data/1*</a></td><td>The <code>hb_gateway_client</code> module expects all JSON structures to at least
have a <code>data</code> field.</td></tr><tr><td valign="top"><a href="#aos2_normalize_types-1">aos2_normalize_types/1</a></td><td>Normalize an AOS2 formatted message to ensure that all field NAMES and
types are correct.</td></tr><tr><td valign="top"><a href="#aos2_to_assignment-2">aos2_to_assignment/2</a></td><td>Create and normalize an assignment from an AOS2-style JSON structure.</td></tr><tr><td valign="top"><a href="#aos2_to_assignments-3">aos2_to_assignments/3</a></td><td>Convert an AOS2-style JSON structure to a normalized HyperBEAM
assignments response.</td></tr><tr><td valign="top"><a href="#assignment_to_aos2-2">assignment_to_aos2/2*</a></td><td>Convert an assignment to an AOS2-compatible JSON structure.</td></tr><tr><td valign="top"><a href="#assignments_to_aos2-4">assignments_to_aos2/4</a></td><td></td></tr><tr><td valign="top"><a href="#assignments_to_bundle-4">assignments_to_bundle/4</a></td><td>Generate a <code>GET /schedule</code> response for a process as HTTP-sig bundles.</td></tr><tr><td valign="top"><a href="#assignments_to_bundle-5">assignments_to_bundle/5*</a></td><td></td></tr><tr><td valign="top"><a href="#cursor-2">cursor/2*</a></td><td>Generate a cursor for an assignment.</td></tr><tr><td valign="top"><a href="#format_opts-1">format_opts/1*</a></td><td>For all scheduler format operations, we do not calculate hashpaths,
perform cache lookups, or await inprogress results.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="aos2_normalize_data-1"></a>

### aos2_normalize_data/1 * ###

`aos2_normalize_data(JSONStruct) -> any()`

The `hb_gateway_client` module expects all JSON structures to at least
have a `data` field. This function ensures that.

<a name="aos2_normalize_types-1"></a>

### aos2_normalize_types/1 ###

`aos2_normalize_types(Msg) -> any()`

Normalize an AOS2 formatted message to ensure that all field NAMES and
types are correct. This involves converting field names to integers and
specific field names to their canonical form.
NOTE: This will result in a message that is not verifiable! It is, however,
necessary for gaining compatibility with the AOS2-style scheduling API.

<a name="aos2_to_assignment-2"></a>

### aos2_to_assignment/2 ###

`aos2_to_assignment(A, RawOpts) -> any()`

Create and normalize an assignment from an AOS2-style JSON structure.
NOTE: This method is destructive to the verifiability of the assignment.

<a name="aos2_to_assignments-3"></a>

### aos2_to_assignments/3 ###

`aos2_to_assignments(ProcID, Body, RawOpts) -> any()`

Convert an AOS2-style JSON structure to a normalized HyperBEAM
assignments response.

<a name="assignment_to_aos2-2"></a>

### assignment_to_aos2/2 * ###

`assignment_to_aos2(Assignment, RawOpts) -> any()`

Convert an assignment to an AOS2-compatible JSON structure.

<a name="assignments_to_aos2-4"></a>

### assignments_to_aos2/4 ###

`assignments_to_aos2(ProcID, Assignments, More, RawOpts) -> any()`

<a name="assignments_to_bundle-4"></a>

### assignments_to_bundle/4 ###

`assignments_to_bundle(ProcID, Assignments, More, Opts) -> any()`

Generate a `GET /schedule` response for a process as HTTP-sig bundles.

<a name="assignments_to_bundle-5"></a>

### assignments_to_bundle/5 * ###

`assignments_to_bundle(ProcID, Assignments, More, TimeInfo, RawOpts) -> any()`

<a name="cursor-2"></a>

### cursor/2 * ###

`cursor(Assignment, RawOpts) -> any()`

Generate a cursor for an assignment. This should be the slot number, at
least in the case of mainnet `ao.N.1` assignments. In the case of legacynet
(`ao.TN.1`) assignments, we may want to use the assignment ID.

<a name="format_opts-1"></a>

### format_opts/1 * ###

`format_opts(Opts) -> any()`

For all scheduler format operations, we do not calculate hashpaths,
perform cache lookups, or await inprogress results.


--- END OF FILE: docs/resources/source-code/dev_scheduler_formats.md ---

--- START OF FILE: docs/resources/source-code/dev_scheduler_registry.md ---
# [Module dev_scheduler_registry.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_scheduler_registry.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#create_and_find_process_test-0">create_and_find_process_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#create_multiple_processes_test-0">create_multiple_processes_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#find-1">find/1</a></td><td>Find a process associated with the processor ID in the local registry
If the process is not found, it will not create a new one.</td></tr><tr><td valign="top"><a href="#find-2">find/2</a></td><td>Find a process associated with the processor ID in the local registry
If the process is not found and <code>GenIfNotHosted</code> is true, it attemps to
create a new one.</td></tr><tr><td valign="top"><a href="#find-3">find/3</a></td><td>Same as <code>find/2</code> but with additional options passed when spawning a
new process (if needed).</td></tr><tr><td valign="top"><a href="#find_non_existent_process_test-0">find_non_existent_process_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#generate_test_procs-0">generate_test_procs/0*</a></td><td></td></tr><tr><td valign="top"><a href="#get_all_processes_test-0">get_all_processes_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#get_processes-0">get_processes/0</a></td><td>Return a list of all currently registered ProcID.</td></tr><tr><td valign="top"><a href="#get_wallet-0">get_wallet/0</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_new_proc-3">maybe_new_proc/3*</a></td><td></td></tr><tr><td valign="top"><a href="#start-0">start/0</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="create_and_find_process_test-0"></a>

### create_and_find_process_test/0 * ###

`create_and_find_process_test() -> any()`

<a name="create_multiple_processes_test-0"></a>

### create_multiple_processes_test/0 * ###

`create_multiple_processes_test() -> any()`

<a name="find-1"></a>

### find/1 ###

`find(ProcID) -> any()`

Find a process associated with the processor ID in the local registry
If the process is not found, it will not create a new one

<a name="find-2"></a>

### find/2 ###

`find(ProcID, ProcMsgOrFalse) -> any()`

Find a process associated with the processor ID in the local registry
If the process is not found and `GenIfNotHosted` is true, it attemps to
create a new one

<a name="find-3"></a>

### find/3 ###

`find(ProcID, ProcMsgOrFalse, Opts) -> any()`

Same as `find/2` but with additional options passed when spawning a
new process (if needed)

<a name="find_non_existent_process_test-0"></a>

### find_non_existent_process_test/0 * ###

`find_non_existent_process_test() -> any()`

<a name="generate_test_procs-0"></a>

### generate_test_procs/0 * ###

`generate_test_procs() -> any()`

<a name="get_all_processes_test-0"></a>

### get_all_processes_test/0 * ###

`get_all_processes_test() -> any()`

<a name="get_processes-0"></a>

### get_processes/0 ###

`get_processes() -> any()`

Return a list of all currently registered ProcID.

<a name="get_wallet-0"></a>

### get_wallet/0 ###

`get_wallet() -> any()`

<a name="maybe_new_proc-3"></a>

### maybe_new_proc/3 * ###

`maybe_new_proc(ProcID, ProcMsg, Opts) -> any()`

<a name="start-0"></a>

### start/0 ###

`start() -> any()`


--- END OF FILE: docs/resources/source-code/dev_scheduler_registry.md ---

--- START OF FILE: docs/resources/source-code/dev_scheduler_server.md ---
# [Module dev_scheduler_server.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_scheduler_server.erl)




A long-lived server that schedules messages for a process.

<a name="description"></a>

## Description ##
It acts as a deliberate 'bottleneck' to prevent the server accidentally
assigning multiple messages to the same slot.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#assign-3">assign/3*</a></td><td>Assign a message to the next slot.</td></tr><tr><td valign="top"><a href="#commit_assignment-2">commit_assignment/2*</a></td><td>Commit to the assignment using all of our appropriate wallets.</td></tr><tr><td valign="top"><a href="#commitment_wallets-2">commitment_wallets/2*</a></td><td>Determine the appropriate list of keys to use to commit assignments for
a process.</td></tr><tr><td valign="top"><a href="#do_assign-3">do_assign/3*</a></td><td>Generate and store the actual assignment message.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Get the current slot from the scheduling server.</td></tr><tr><td valign="top"><a href="#maybe_inform_recipient-5">maybe_inform_recipient/5*</a></td><td>Potentially inform the caller that the assignment has been scheduled.</td></tr><tr><td valign="top"><a href="#new_proc_test-0">new_proc_test/0*</a></td><td>Test the basic functionality of the server.</td></tr><tr><td valign="top"><a href="#next_hashchain-3">next_hashchain/3*</a></td><td>Create the next element in a chain of hashes that links this and prior
assignments.</td></tr><tr><td valign="top"><a href="#schedule-2">schedule/2</a></td><td>Call the appropriate scheduling server to assign a message.</td></tr><tr><td valign="top"><a href="#server-1">server/1*</a></td><td>The main loop of the server.</td></tr><tr><td valign="top"><a href="#start-3">start/3</a></td><td>Start a scheduling server for a given computation.</td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="assign-3"></a>

### assign/3 * ###

`assign(State, Message, ReplyPID) -> any()`

Assign a message to the next slot.

<a name="commit_assignment-2"></a>

### commit_assignment/2 * ###

`commit_assignment(BaseAssignment, State) -> any()`

Commit to the assignment using all of our appropriate wallets.

<a name="commitment_wallets-2"></a>

### commitment_wallets/2 * ###

`commitment_wallets(ProcMsg, Opts) -> any()`

Determine the appropriate list of keys to use to commit assignments for
a process.

<a name="do_assign-3"></a>

### do_assign/3 * ###

`do_assign(State, Message, ReplyPID) -> any()`

Generate and store the actual assignment message.

<a name="info-1"></a>

### info/1 ###

`info(ProcID) -> any()`

Get the current slot from the scheduling server.

<a name="maybe_inform_recipient-5"></a>

### maybe_inform_recipient/5 * ###

`maybe_inform_recipient(Mode, ReplyPID, Message, Assignment, State) -> any()`

Potentially inform the caller that the assignment has been scheduled.
The main assignment loop calls this function repeatedly at different stages
of the assignment process. The scheduling mode determines which stages
trigger an update.

<a name="new_proc_test-0"></a>

### new_proc_test/0 * ###

`new_proc_test() -> any()`

Test the basic functionality of the server.

<a name="next_hashchain-3"></a>

### next_hashchain/3 * ###

`next_hashchain(HashChain, Message, Opts) -> any()`

Create the next element in a chain of hashes that links this and prior
assignments.

<a name="schedule-2"></a>

### schedule/2 ###

`schedule(AOProcID, Message) -> any()`

Call the appropriate scheduling server to assign a message.

<a name="server-1"></a>

### server/1 * ###

`server(State) -> any()`

The main loop of the server. Simply waits for messages to assign and
returns the current slot.

<a name="start-3"></a>

### start/3 ###

`start(ProcID, Proc, Opts) -> any()`

Start a scheduling server for a given computation.

<a name="stop-1"></a>

### stop/1 ###

`stop(ProcID) -> any()`


--- END OF FILE: docs/resources/source-code/dev_scheduler_server.md ---

--- START OF FILE: docs/resources/source-code/dev_scheduler.md ---
# [Module dev_scheduler.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_scheduler.erl)




A simple scheduler scheme for AO.

<a name="description"></a>

## Description ##
This device expects a message of the form:
Process: `#{ id, Scheduler: #{ Authority } }`

```

   It exposes the following keys for scheduling:<code>#{ method: GET, path: <<"/info">> }</code> ->
           Returns information about the scheduler.<code>#{ method: GET, path: <<"/slot">> }</code> -> <code>slot(Msg1, Msg2, Opts)</code>
           Returns the current slot for a process.<code>#{ method: GET, path: <<"/schedule">> }</code> -> <code>get_schedule(Msg1, Msg2, Opts)</code>
           Returns the schedule for a process in a cursor-traversable format.<code>#{ method: POST, path: <<"/schedule">> }</code> -> <code>post_schedule(Msg1, Msg2, Opts)</code>
           Schedules a new message for a process, or starts a new scheduler
           for the given message.
```
<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#benchmark_suite-2">benchmark_suite/2*</a></td><td></td></tr><tr><td valign="top"><a href="#benchmark_suite_test_-0">benchmark_suite_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#cache_remote_schedule-2">cache_remote_schedule/2*</a></td><td>Cache a schedule received from a remote scheduler.</td></tr><tr><td valign="top"><a href="#check_lookahead_and_local_cache-4">check_lookahead_and_local_cache/4*</a></td><td>Check if we have a result from a lookahead worker or from our local
cache.</td></tr><tr><td valign="top"><a href="#checkpoint-1">checkpoint/1</a></td><td>Returns the current state of the scheduler.</td></tr><tr><td valign="top"><a href="#do_get_remote_schedule-6">do_get_remote_schedule/6*</a></td><td>Get a schedule from a remote scheduler, unless we already have already
read all of the assignments from the local cache.</td></tr><tr><td valign="top"><a href="#do_post_schedule-4">do_post_schedule/4*</a></td><td>Post schedule the message.</td></tr><tr><td valign="top"><a href="#filter_json_assignments-4">filter_json_assignments/4*</a></td><td>Filter JSON assignment results from a remote legacy scheduler.</td></tr><tr><td valign="top"><a href="#find_message_to_schedule-3">find_message_to_schedule/3*</a></td><td>Search the given base and request message pair to find the message to
schedule.</td></tr><tr><td valign="top"><a href="#find_next_assignment-5">find_next_assignment/5*</a></td><td>Get the assignments for a process from the message cache, local cache,
or the inbox (thanks to a lookahead-worker).</td></tr><tr><td valign="top"><a href="#find_process_message-4">find_process_message/4*</a></td><td>Find the process message for a given process ID and base message.</td></tr><tr><td valign="top"><a href="#find_remote_scheduler-3">find_remote_scheduler/3*</a></td><td>Use the SchedulerLocation to find the remote path and return a redirect.</td></tr><tr><td valign="top"><a href="#find_server-3">find_server/3*</a></td><td>Locate the correct scheduling server for a given process.</td></tr><tr><td valign="top"><a href="#find_server-4">find_server/4*</a></td><td></td></tr><tr><td valign="top"><a href="#find_target_id-3">find_target_id/3*</a></td><td>Find the schedule ID from a given request.</td></tr><tr><td valign="top"><a href="#generate_local_schedule-5">generate_local_schedule/5*</a></td><td>Generate a <code>GET /schedule</code> response for a process.</td></tr><tr><td valign="top"><a href="#generate_redirect-3">generate_redirect/3*</a></td><td>Generate a redirect message to a scheduler.</td></tr><tr><td valign="top"><a href="#get_hint-2">get_hint/2*</a></td><td>If a hint is present in the string, return it.</td></tr><tr><td valign="top"><a href="#get_local_assignments-4">get_local_assignments/4*</a></td><td>Get the assignments for a process, and whether the request was truncated.</td></tr><tr><td valign="top"><a href="#get_local_schedule_test-0">get_local_schedule_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#get_location-3">get_location/3*</a></td><td>Search for the location of the scheduler in the scheduler-location
cache.</td></tr><tr><td valign="top"><a href="#get_remote_schedule-5">get_remote_schedule/5*</a></td><td>Get a schedule from a remote scheduler, but first read all of the
assignments from the local cache that we already know about.</td></tr><tr><td valign="top"><a href="#get_schedule-3">get_schedule/3*</a></td><td>Generate and return a schedule for a process, optionally between
two slots -- labelled as <code>from</code> and <code>to</code>.</td></tr><tr><td valign="top"><a href="#http_get_json_schedule_test_-0">http_get_json_schedule_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_get_legacy_schedule_as_aos2_test_-0">http_get_legacy_schedule_as_aos2_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_get_legacy_schedule_slot_range_test_-0">http_get_legacy_schedule_slot_range_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_get_legacy_schedule_test_-0">http_get_legacy_schedule_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_get_legacy_slot_test_-0">http_get_legacy_slot_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_get_schedule-4">http_get_schedule/4*</a></td><td></td></tr><tr><td valign="top"><a href="#http_get_schedule-5">http_get_schedule/5*</a></td><td></td></tr><tr><td valign="top"><a href="#http_get_schedule_redirect-0">http_get_schedule_redirect/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_get_schedule_redirect_test_-0">http_get_schedule_redirect_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_get_schedule_test_-0">http_get_schedule_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_get_slot-2">http_get_slot/2*</a></td><td></td></tr><tr><td valign="top"><a href="#http_init-0">http_init/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_init-1">http_init/1*</a></td><td></td></tr><tr><td valign="top"><a href="#http_post_legacy_schedule_test_-0">http_post_legacy_schedule_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_post_schedule-0">http_post_schedule/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_post_schedule_sign-4">http_post_schedule_sign/4*</a></td><td></td></tr><tr><td valign="top"><a href="#http_post_schedule_test_-0">http_post_schedule_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#info-0">info/0</a></td><td>This device uses a default_handler to route requests to the correct
function.</td></tr><tr><td valign="top"><a href="#is_local_scheduler-4">is_local_scheduler/4*</a></td><td>Determine if a scheduler is local.</td></tr><tr><td valign="top"><a href="#location-3">location/3</a></td><td>Router for <code>record</code> requests.</td></tr><tr><td valign="top"><a href="#many_clients-1">many_clients/1*</a></td><td></td></tr><tr><td valign="top"><a href="#message_cached_assignments-2">message_cached_assignments/2*</a></td><td>Non-device exported helper to get the cached assignments held in a
process.</td></tr><tr><td valign="top"><a href="#next-3">next/3</a></td><td>Load the schedule for a process into the cache, then return the next
assignment.</td></tr><tr><td valign="top"><a href="#node_from_redirect-2">node_from_redirect/2*</a></td><td>Get the node URL from a redirect.</td></tr><tr><td valign="top"><a href="#parse_schedulers-1">parse_schedulers/1</a></td><td>General utility functions that are available to other modules.</td></tr><tr><td valign="top"><a href="#post_legacy_schedule-4">post_legacy_schedule/4*</a></td><td></td></tr><tr><td valign="top"><a href="#post_location-3">post_location/3*</a></td><td>Generate a new scheduler location record and register it.</td></tr><tr><td valign="top"><a href="#post_remote_schedule-4">post_remote_schedule/4*</a></td><td></td></tr><tr><td valign="top"><a href="#post_schedule-3">post_schedule/3*</a></td><td>Schedules a new message on the SU.</td></tr><tr><td valign="top"><a href="#read_local_assignments-4">read_local_assignments/4*</a></td><td>Get the assignments for a process.</td></tr><tr><td valign="top"><a href="#redirect_from_graphql-0">redirect_from_graphql/0*</a></td><td></td></tr><tr><td valign="top"><a href="#redirect_from_graphql_test_-0">redirect_from_graphql_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#redirect_to_hint_test-0">redirect_to_hint_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#register_location_on_boot_test-0">register_location_on_boot_test/0*</a></td><td>Test that a scheduler location is registered on boot.</td></tr><tr><td valign="top"><a href="#register_new_process_test-0">register_new_process_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#register_scheduler_test-0">register_scheduler_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#remote_slot-3">remote_slot/3*</a></td><td>Get the current slot from a remote scheduler.</td></tr><tr><td valign="top"><a href="#remote_slot-4">remote_slot/4*</a></td><td>Get the current slot from a remote scheduler, based on the variant of
the process's scheduler.</td></tr><tr><td valign="top"><a href="#router-4">router/4</a></td><td>The default handler for the scheduler device.</td></tr><tr><td valign="top"><a href="#schedule-3">schedule/3</a></td><td>A router for choosing between getting the existing schedule, or
scheduling a new message.</td></tr><tr><td valign="top"><a href="#schedule_message_and_get_slot_test-0">schedule_message_and_get_slot_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#single_resolution-1">single_resolution/1*</a></td><td></td></tr><tr><td valign="top"><a href="#slot-3">slot/3</a></td><td>Returns information about the current slot for a process.</td></tr><tr><td valign="top"><a href="#spawn_lookahead_worker-3">spawn_lookahead_worker/3*</a></td><td>Spawn a new Erlang process to fetch the next assignments from the local
cache, if we have them available.</td></tr><tr><td valign="top"><a href="#start-0">start/0</a></td><td>Helper to ensure that the environment is started.</td></tr><tr><td valign="top"><a href="#status-3">status/3</a></td><td>Returns information about the entire scheduler.</td></tr><tr><td valign="top"><a href="#status_test-0">status_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_process-0">test_process/0</a></td><td>Generate a _transformed_ process message, not as they are generated
by users.</td></tr><tr><td valign="top"><a href="#test_process-1">test_process/1*</a></td><td></td></tr><tr><td valign="top"><a href="#validate_next_slot-5">validate_next_slot/5*</a></td><td>Validate the <code>next</code> slot generated by <code>find_next_assignment</code>.</td></tr><tr><td valign="top"><a href="#without_hint-1">without_hint/1*</a></td><td>Take a process ID or target with a potential hint and return just the
process ID.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="benchmark_suite-2"></a>

### benchmark_suite/2 * ###

`benchmark_suite(Port, Base) -> any()`

<a name="benchmark_suite_test_-0"></a>

### benchmark_suite_test_/0 * ###

`benchmark_suite_test_() -> any()`

<a name="cache_remote_schedule-2"></a>

### cache_remote_schedule/2 * ###

`cache_remote_schedule(Schedule, Opts) -> any()`

Cache a schedule received from a remote scheduler.

<a name="check_lookahead_and_local_cache-4"></a>

### check_lookahead_and_local_cache/4 * ###

`check_lookahead_and_local_cache(Msg1, ProcID, TargetSlot, Opts) -> any()`

Check if we have a result from a lookahead worker or from our local
cache. If we have a result in the local cache, we may also start a new
lookahead worker to fetch the next assignments if we have them locally,
ahead of time. This can be enabled/disabled with the `scheduler_lookahead`
option.

<a name="checkpoint-1"></a>

### checkpoint/1 ###

`checkpoint(State) -> any()`

Returns the current state of the scheduler.

<a name="do_get_remote_schedule-6"></a>

### do_get_remote_schedule/6 * ###

`do_get_remote_schedule(ProcID, LocalAssignments, From, To, Redirect, Opts) -> any()`

Get a schedule from a remote scheduler, unless we already have already
read all of the assignments from the local cache.

<a name="do_post_schedule-4"></a>

### do_post_schedule/4 * ###

`do_post_schedule(ProcID, PID, Msg2, Opts) -> any()`

Post schedule the message. `Msg2` by this point has been refined to only
committed keys, and to only include the `target` message that is to be
scheduled.

<a name="filter_json_assignments-4"></a>

### filter_json_assignments/4 * ###

`filter_json_assignments(JSONRes, To, From, Opts) -> any()`

Filter JSON assignment results from a remote legacy scheduler.

<a name="find_message_to_schedule-3"></a>

### find_message_to_schedule/3 * ###

`find_message_to_schedule(Msg1, Msg2, Opts) -> any()`

Search the given base and request message pair to find the message to
schedule. The precidence order for search is as follows:
1. A key in `Msg2` with the value `self`, indicating that the entire message
is the subject.
2. A key in `Msg2` with another value, present in that message.
3. The body of the message.
4. The message itself.

<a name="find_next_assignment-5"></a>

### find_next_assignment/5 * ###

`find_next_assignment(Msg1, Msg2, Schedule, LastSlot, Opts) -> any()`

Get the assignments for a process from the message cache, local cache,
or the inbox (thanks to a lookahead-worker).

<a name="find_process_message-4"></a>

### find_process_message/4 * ###

`find_process_message(ProcID, Msg1, ToSched, Opts) -> any()`

Find the process message for a given process ID and base message.

<a name="find_remote_scheduler-3"></a>

### find_remote_scheduler/3 * ###

`find_remote_scheduler(ProcID, Rest, Opts) -> any()`

Use the SchedulerLocation to find the remote path and return a redirect.
If there are multiple locations, try each one in turn until we find the first
that matches.

<a name="find_server-3"></a>

### find_server/3 * ###

`find_server(ProcID, Msg1, Opts) -> any()`

Locate the correct scheduling server for a given process.

<a name="find_server-4"></a>

### find_server/4 * ###

`find_server(ProcID, Msg1, ToSched, Opts) -> any()`

<a name="find_target_id-3"></a>

### find_target_id/3 * ###

`find_target_id(Msg1, Msg2, Opts) -> any()`

Find the schedule ID from a given request. The precidence order for
search is as follows:
[1. `ToSched/id` -- in the case of `POST schedule`, handled locally]
2. `Msg2/target`
3. `Msg2/id` when `Msg2` has `type: Process`
4. `Msg1/process/id`
5. `Msg1/id` when `Msg1` has `type: Process`
6. `Msg2/id`

<a name="generate_local_schedule-5"></a>

### generate_local_schedule/5 * ###

`generate_local_schedule(Format, ProcID, From, To, Opts) -> any()`

Generate a `GET /schedule` response for a process.

<a name="generate_redirect-3"></a>

### generate_redirect/3 * ###

`generate_redirect(ProcID, SchedulerLocation, Opts) -> any()`

Generate a redirect message to a scheduler.

<a name="get_hint-2"></a>

### get_hint/2 * ###

`get_hint(Str, Opts) -> any()`

If a hint is present in the string, return it. Else, return not_found.

<a name="get_local_assignments-4"></a>

### get_local_assignments/4 * ###

`get_local_assignments(ProcID, From, RequestedTo, Opts) -> any()`

Get the assignments for a process, and whether the request was truncated.

<a name="get_local_schedule_test-0"></a>

### get_local_schedule_test/0 * ###

`get_local_schedule_test() -> any()`

<a name="get_location-3"></a>

### get_location/3 * ###

`get_location(Msg1, Req, Opts) -> any()`

Search for the location of the scheduler in the scheduler-location
cache. If an address is provided, we search for the location of that
specific scheduler. Otherwise, we return the location record for the current
node's scheduler, if it has been established.

<a name="get_remote_schedule-5"></a>

### get_remote_schedule/5 * ###

`get_remote_schedule(RawProcID, From, To, Redirect, Opts) -> any()`

Get a schedule from a remote scheduler, but first read all of the
assignments from the local cache that we already know about.

<a name="get_schedule-3"></a>

### get_schedule/3 * ###

`get_schedule(Msg1, Msg2, Opts) -> any()`

Generate and return a schedule for a process, optionally between
two slots -- labelled as `from` and `to`. If the schedule is not local,
we redirect to the remote scheduler or proxy based on the node opts.

<a name="http_get_json_schedule_test_-0"></a>

### http_get_json_schedule_test_/0 * ###

`http_get_json_schedule_test_() -> any()`

<a name="http_get_legacy_schedule_as_aos2_test_-0"></a>

### http_get_legacy_schedule_as_aos2_test_/0 * ###

`http_get_legacy_schedule_as_aos2_test_() -> any()`

<a name="http_get_legacy_schedule_slot_range_test_-0"></a>

### http_get_legacy_schedule_slot_range_test_/0 * ###

`http_get_legacy_schedule_slot_range_test_() -> any()`

<a name="http_get_legacy_schedule_test_-0"></a>

### http_get_legacy_schedule_test_/0 * ###

`http_get_legacy_schedule_test_() -> any()`

<a name="http_get_legacy_slot_test_-0"></a>

### http_get_legacy_slot_test_/0 * ###

`http_get_legacy_slot_test_() -> any()`

<a name="http_get_schedule-4"></a>

### http_get_schedule/4 * ###

`http_get_schedule(N, PMsg, From, To) -> any()`

<a name="http_get_schedule-5"></a>

### http_get_schedule/5 * ###

`http_get_schedule(N, PMsg, From, To, Format) -> any()`

<a name="http_get_schedule_redirect-0"></a>

### http_get_schedule_redirect/0 * ###

`http_get_schedule_redirect() -> any()`

<a name="http_get_schedule_redirect_test_-0"></a>

### http_get_schedule_redirect_test_/0 * ###

`http_get_schedule_redirect_test_() -> any()`

<a name="http_get_schedule_test_-0"></a>

### http_get_schedule_test_/0 * ###

`http_get_schedule_test_() -> any()`

<a name="http_get_slot-2"></a>

### http_get_slot/2 * ###

`http_get_slot(N, PMsg) -> any()`

<a name="http_init-0"></a>

### http_init/0 * ###

`http_init() -> any()`

<a name="http_init-1"></a>

### http_init/1 * ###

`http_init(Opts) -> any()`

<a name="http_post_legacy_schedule_test_-0"></a>

### http_post_legacy_schedule_test_/0 * ###

`http_post_legacy_schedule_test_() -> any()`

<a name="http_post_schedule-0"></a>

### http_post_schedule/0 * ###

`http_post_schedule() -> any()`

<a name="http_post_schedule_sign-4"></a>

### http_post_schedule_sign/4 * ###

`http_post_schedule_sign(Node, Msg, ProcessMsg, Wallet) -> any()`

<a name="http_post_schedule_test_-0"></a>

### http_post_schedule_test_/0 * ###

`http_post_schedule_test_() -> any()`

<a name="info-0"></a>

### info/0 ###

`info() -> any()`

This device uses a default_handler to route requests to the correct
function.

<a name="is_local_scheduler-4"></a>

### is_local_scheduler/4 * ###

`is_local_scheduler(ProcID, ProcMsg, Rest, Opts) -> any()`

Determine if a scheduler is local. If so, return the PID and options.
We start the local server if we _can_ be the scheduler and it does not already
exist.

<a name="location-3"></a>

### location/3 ###

`location(Msg1, Msg2, Opts) -> any()`

Router for `record` requests. Expects either a `POST` or `GET` request.

<a name="many_clients-1"></a>

### many_clients/1 * ###

`many_clients(Opts) -> any()`

<a name="message_cached_assignments-2"></a>

### message_cached_assignments/2 * ###

`message_cached_assignments(Msg, Opts) -> any()`

Non-device exported helper to get the cached assignments held in a
process.

<a name="next-3"></a>

### next/3 ###

`next(Msg1, Msg2, Opts) -> any()`

Load the schedule for a process into the cache, then return the next
assignment. Assumes that Msg1 is a `dev_process` or similar message, having
a `Current-Slot` key. It stores a local cache of the schedule in the
`priv/To-Process` key.

<a name="node_from_redirect-2"></a>

### node_from_redirect/2 * ###

`node_from_redirect(Redirect, Opts) -> any()`

Get the node URL from a redirect.

<a name="parse_schedulers-1"></a>

### parse_schedulers/1 ###

`parse_schedulers(SchedLoc) -> any()`

General utility functions that are available to other modules.

<a name="post_legacy_schedule-4"></a>

### post_legacy_schedule/4 * ###

`post_legacy_schedule(ProcID, OnlyCommitted, Node, Opts) -> any()`

<a name="post_location-3"></a>

### post_location/3 * ###

`post_location(Msg1, RawReq, Opts) -> any()`

Generate a new scheduler location record and register it. We both send
the new scheduler-location to the given registry, and return it to the caller.

<a name="post_remote_schedule-4"></a>

### post_remote_schedule/4 * ###

`post_remote_schedule(RawProcID, Redirect, OnlyCommitted, Opts) -> any()`

<a name="post_schedule-3"></a>

### post_schedule/3 * ###

`post_schedule(Msg1, Msg2, Opts) -> any()`

Schedules a new message on the SU. Searches Msg1 for the appropriate ID,
then uses the wallet address of the scheduler to determine if the message is
for this scheduler. If so, it schedules the message and returns the assignment.

<a name="read_local_assignments-4"></a>

### read_local_assignments/4 * ###

`read_local_assignments(ProcID, From, To, Opts) -> any()`

Get the assignments for a process.

<a name="redirect_from_graphql-0"></a>

### redirect_from_graphql/0 * ###

`redirect_from_graphql() -> any()`

<a name="redirect_from_graphql_test_-0"></a>

### redirect_from_graphql_test_/0 * ###

`redirect_from_graphql_test_() -> any()`

<a name="redirect_to_hint_test-0"></a>

### redirect_to_hint_test/0 * ###

`redirect_to_hint_test() -> any()`

<a name="register_location_on_boot_test-0"></a>

### register_location_on_boot_test/0 * ###

`register_location_on_boot_test() -> any()`

Test that a scheduler location is registered on boot.

<a name="register_new_process_test-0"></a>

### register_new_process_test/0 * ###

`register_new_process_test() -> any()`

<a name="register_scheduler_test-0"></a>

### register_scheduler_test/0 * ###

`register_scheduler_test() -> any()`

<a name="remote_slot-3"></a>

### remote_slot/3 * ###

`remote_slot(ProcID, Redirect, Opts) -> any()`

Get the current slot from a remote scheduler.

<a name="remote_slot-4"></a>

### remote_slot/4 * ###

`remote_slot(X1, ProcID, Node, Opts) -> any()`

Get the current slot from a remote scheduler, based on the variant of
the process's scheduler.

<a name="router-4"></a>

### router/4 ###

`router(X1, Msg1, Msg2, Opts) -> any()`

The default handler for the scheduler device.

<a name="schedule-3"></a>

### schedule/3 ###

`schedule(Msg1, Msg2, Opts) -> any()`

A router for choosing between getting the existing schedule, or
scheduling a new message.

<a name="schedule_message_and_get_slot_test-0"></a>

### schedule_message_and_get_slot_test/0 * ###

`schedule_message_and_get_slot_test() -> any()`

<a name="single_resolution-1"></a>

### single_resolution/1 * ###

`single_resolution(Opts) -> any()`

<a name="slot-3"></a>

### slot/3 ###

`slot(M1, M2, Opts) -> any()`

Returns information about the current slot for a process.

<a name="spawn_lookahead_worker-3"></a>

### spawn_lookahead_worker/3 * ###

`spawn_lookahead_worker(ProcID, Slot, Opts) -> any()`

Spawn a new Erlang process to fetch the next assignments from the local
cache, if we have them available.

<a name="start-0"></a>

### start/0 ###

`start() -> any()`

Helper to ensure that the environment is started.

<a name="status-3"></a>

### status/3 ###

`status(M1, M2, Opts) -> any()`

Returns information about the entire scheduler.

<a name="status_test-0"></a>

### status_test/0 * ###

`status_test() -> any()`

<a name="test_process-0"></a>

### test_process/0 ###

`test_process() -> any()`

Generate a _transformed_ process message, not as they are generated
by users. See `dev_process` for examples of AO process messages.

<a name="test_process-1"></a>

### test_process/1 * ###

`test_process(Address) -> any()`

<a name="validate_next_slot-5"></a>

### validate_next_slot/5 * ###

`validate_next_slot(Msg1, Assignments, Lookahead, Last, Opts) -> any()`

Validate the `next` slot generated by `find_next_assignment`.

<a name="without_hint-1"></a>

### without_hint/1 * ###

`without_hint(Target) -> any()`

Take a process ID or target with a potential hint and return just the
process ID.


--- END OF FILE: docs/resources/source-code/dev_scheduler.md ---

--- START OF FILE: docs/resources/source-code/dev_simple_pay.md ---
# [Module dev_simple_pay.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_simple_pay.erl)




A simple device that allows the operator to specify a price for a
request and then charge the user for it, on a per message basis.

<a name="description"></a>

## Description ##
The device's ledger is stored in the node message at `simple_pay_ledger`,
and can be topped-up by either the operator, or an external device. The
price is specified in the node message at `simple_pay_price`.
This device acts as both a pricing device and a ledger device, by p4's
definition.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#balance-3">balance/3</a></td><td>Get the balance of a user in the ledger.</td></tr><tr><td valign="top"><a href="#charge-3">charge/3</a></td><td>Preprocess a request by checking the ledger and charging the user.</td></tr><tr><td valign="top"><a href="#estimate-3">estimate/3</a></td><td>Estimate the cost of a request by counting the number of messages in
the request, then multiplying by the per-message price.</td></tr><tr><td valign="top"><a href="#get_balance-2">get_balance/2*</a></td><td>Get the balance of a user in the ledger.</td></tr><tr><td valign="top"><a href="#get_balance_and_top_up_test-0">get_balance_and_top_up_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#is_operator-2">is_operator/2*</a></td><td>Check if the request is from the operator.</td></tr><tr><td valign="top"><a href="#is_operator-3">is_operator/3*</a></td><td></td></tr><tr><td valign="top"><a href="#set_balance-3">set_balance/3*</a></td><td>Adjust a user's balance, normalizing their wallet ID first.</td></tr><tr><td valign="top"><a href="#test_opts-1">test_opts/1*</a></td><td></td></tr><tr><td valign="top"><a href="#topup-3">topup/3</a></td><td>Top up the user's balance in the ledger.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="balance-3"></a>

### balance/3 ###

`balance(X1, RawReq, NodeMsg) -> any()`

Get the balance of a user in the ledger.

<a name="charge-3"></a>

### charge/3 ###

`charge(X1, RawReq, NodeMsg) -> any()`

Preprocess a request by checking the ledger and charging the user. We
can charge the user at this stage because we know statically what the price
will be

<a name="estimate-3"></a>

### estimate/3 ###

`estimate(X1, EstimateReq, NodeMsg) -> any()`

Estimate the cost of a request by counting the number of messages in
the request, then multiplying by the per-message price. The operator does
not pay for their own requests.

<a name="get_balance-2"></a>

### get_balance/2 * ###

`get_balance(Signer, NodeMsg) -> any()`

Get the balance of a user in the ledger.

<a name="get_balance_and_top_up_test-0"></a>

### get_balance_and_top_up_test/0 * ###

`get_balance_and_top_up_test() -> any()`

<a name="is_operator-2"></a>

### is_operator/2 * ###

`is_operator(Req, NodeMsg) -> any()`

Check if the request is from the operator.

<a name="is_operator-3"></a>

### is_operator/3 * ###

`is_operator(Req, NodeMsg, OperatorAddr) -> any()`

<a name="set_balance-3"></a>

### set_balance/3 * ###

`set_balance(Signer, Amount, NodeMsg) -> any()`

Adjust a user's balance, normalizing their wallet ID first.

<a name="test_opts-1"></a>

### test_opts/1 * ###

`test_opts(Ledger) -> any()`

<a name="topup-3"></a>

### topup/3 ###

`topup(X1, Req, NodeMsg) -> any()`

Top up the user's balance in the ledger.


--- END OF FILE: docs/resources/source-code/dev_simple_pay.md ---

--- START OF FILE: docs/resources/source-code/dev_snp_nif.md ---
# [Module dev_snp_nif.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_snp_nif.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#check_snp_support-0">check_snp_support/0</a></td><td></td></tr><tr><td valign="top"><a href="#compute_launch_digest-1">compute_launch_digest/1</a></td><td></td></tr><tr><td valign="top"><a href="#compute_launch_digest_test-0">compute_launch_digest_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#generate_attestation_report-2">generate_attestation_report/2</a></td><td></td></tr><tr><td valign="top"><a href="#generate_attestation_report_test-0">generate_attestation_report_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#init-0">init/0*</a></td><td></td></tr><tr><td valign="top"><a href="#not_loaded-1">not_loaded/1*</a></td><td></td></tr><tr><td valign="top"><a href="#verify_measurement-2">verify_measurement/2</a></td><td></td></tr><tr><td valign="top"><a href="#verify_measurement_test-0">verify_measurement_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#verify_signature-1">verify_signature/1</a></td><td></td></tr><tr><td valign="top"><a href="#verify_signature_test-0">verify_signature_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="check_snp_support-0"></a>

### check_snp_support/0 ###

`check_snp_support() -> any()`

<a name="compute_launch_digest-1"></a>

### compute_launch_digest/1 ###

`compute_launch_digest(Args) -> any()`

<a name="compute_launch_digest_test-0"></a>

### compute_launch_digest_test/0 * ###

`compute_launch_digest_test() -> any()`

<a name="generate_attestation_report-2"></a>

### generate_attestation_report/2 ###

`generate_attestation_report(UniqueData, VMPL) -> any()`

<a name="generate_attestation_report_test-0"></a>

### generate_attestation_report_test/0 * ###

`generate_attestation_report_test() -> any()`

<a name="init-0"></a>

### init/0 * ###

`init() -> any()`

<a name="not_loaded-1"></a>

### not_loaded/1 * ###

`not_loaded(Line) -> any()`

<a name="verify_measurement-2"></a>

### verify_measurement/2 ###

`verify_measurement(Report, Expected) -> any()`

<a name="verify_measurement_test-0"></a>

### verify_measurement_test/0 * ###

`verify_measurement_test() -> any()`

<a name="verify_signature-1"></a>

### verify_signature/1 ###

`verify_signature(Report) -> any()`

<a name="verify_signature_test-0"></a>

### verify_signature_test/0 * ###

`verify_signature_test() -> any()`


--- END OF FILE: docs/resources/source-code/dev_snp_nif.md ---

--- START OF FILE: docs/resources/source-code/dev_snp.md ---
# [Module dev_snp.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_snp.erl)




This device offers an interface for validating AMD SEV-SNP commitments,
as well as generating them, if called in an appropriate environment.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#execute_is_trusted-3">execute_is_trusted/3*</a></td><td>Ensure that all of the software hashes are trusted.</td></tr><tr><td valign="top"><a href="#generate-3">generate/3</a></td><td>Generate an commitment report and emit it as a message, including all of
the necessary data to generate the nonce (ephemeral node address + node
message ID), as well as the expected measurement (firmware, kernel, and VMSAs
hashes).</td></tr><tr><td valign="top"><a href="#generate_nonce-2">generate_nonce/2*</a></td><td>Generate the nonce to use in the commitment report.</td></tr><tr><td valign="top"><a href="#is_debug-1">is_debug/1*</a></td><td>Ensure that the node's debug policy is disabled.</td></tr><tr><td valign="top"><a href="#real_node_test-0">real_node_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#report_data_matches-3">report_data_matches/3*</a></td><td>Ensure that the report data matches the expected report data.</td></tr><tr><td valign="top"><a href="#trusted-3">trusted/3</a></td><td>Validates if a given message parameter matches a trusted value from the SNP trusted list
Returns {ok, true} if the message is trusted, {ok, false} otherwise.</td></tr><tr><td valign="top"><a href="#verify-3">verify/3</a></td><td>Verify an commitment report message; validating the identity of a
remote node, its ephemeral private address, and the integrity of the report.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="execute_is_trusted-3"></a>

### execute_is_trusted/3 * ###

`execute_is_trusted(M1, Msg, NodeOpts) -> any()`

Ensure that all of the software hashes are trusted. The caller may set
a specific device to use for the `is-trusted` key. The device must then
implement the `trusted` resolver.

<a name="generate-3"></a>

### generate/3 ###

`generate(M1, M2, Opts) -> any()`

Generate an commitment report and emit it as a message, including all of
the necessary data to generate the nonce (ephemeral node address + node
message ID), as well as the expected measurement (firmware, kernel, and VMSAs
hashes).

<a name="generate_nonce-2"></a>

### generate_nonce/2 * ###

`generate_nonce(RawAddress, RawNodeMsgID) -> any()`

Generate the nonce to use in the commitment report.

<a name="is_debug-1"></a>

### is_debug/1 * ###

`is_debug(Report) -> any()`

Ensure that the node's debug policy is disabled.

<a name="real_node_test-0"></a>

### real_node_test/0 * ###

`real_node_test() -> any()`

<a name="report_data_matches-3"></a>

### report_data_matches/3 * ###

`report_data_matches(Address, NodeMsgID, ReportData) -> any()`

Ensure that the report data matches the expected report data.

<a name="trusted-3"></a>

### trusted/3 ###

`trusted(Msg1, Msg2, NodeOpts) -> any()`

Validates if a given message parameter matches a trusted value from the SNP trusted list
Returns {ok, true} if the message is trusted, {ok, false} otherwise

<a name="verify-3"></a>

### verify/3 ###

`verify(M1, M2, NodeOpts) -> any()`

Verify an commitment report message; validating the identity of a
remote node, its ephemeral private address, and the integrity of the report.
The checks that must be performed to validate the report are:
1. Verify the address and the node message ID are the same as the ones
used to generate the nonce.
2. Verify the address that signed the message is the same as the one used
to generate the nonce.
3. Verify that the debug flag is disabled.
4. Verify that the firmware, kernel, and OS (VMSAs) hashes, part of the
measurement, are trusted.
5. Verify the measurement is valid.
6. Verify the report's certificate chain to hardware root of trust.


--- END OF FILE: docs/resources/source-code/dev_snp.md ---

--- START OF FILE: docs/resources/source-code/dev_stack.md ---
# [Module dev_stack.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_stack.erl)




A device that contains a stack of other devices, and manages their
execution.

<a name="description"></a>

## Description ##

It can run in two modes: fold (the default), and map.

In fold mode, it runs upon input messages in the order of their keys. A
stack maintains and passes forward a state (expressed as a message) as it
progresses through devices.

For example, a stack of devices as follows:

```

   Device -> Stack
   Device-Stack/1/Name -> Add-One-Device
   Device-Stack/2/Name -> Add-Two-Device
```

When called with the message:

```

   #{ Path = "FuncName", binary => <code><<"0">></code> }
```

Will produce the output:

```

   #{ Path = "FuncName", binary => <code><<"3">></code> }
   {ok, #{ bin => <code><<"3">></code> }}
```

In map mode, the stack will run over all the devices in the stack, and
combine their results into a single message. Each of the devices'
output values have a key that is the device's name in the `Device-Stack`
(its number if the stack is a list).

You can switch between fold and map modes by setting the `Mode` key in the
`Msg2` to either `Fold` or `Map`, or set it globally for the stack by
setting the `Mode` key in the `Msg1` message. The key in `Msg2` takes
precedence over the key in `Msg1`.

The key that is called upon the device stack is the same key that is used
upon the devices that are contained within it. For example, in the above
scenario we resolve FuncName on the stack, leading FuncName to be called on
Add-One-Device and Add-Two-Device.

A device stack responds to special statuses upon responses as follows:

`skip`: Skips the rest of the device stack for the current pass.

`pass`: Causes the stack to increment its pass number and re-execute
the stack from the first device, maintaining the state
accumulated so far. Only available in fold mode.

In all cases, the device stack will return the accumulated state to the
caller as the result of the call to the stack.

The dev_stack adds additional metadata to the message in order to track
the state of its execution as it progresses through devices. These keys
are as follows:

`Stack-Pass`: The number of times the stack has reset and re-executed
from the first device for the current message.

`Input-Prefix`: The prefix that the device should use for its outputs
and inputs.

`Output-Prefix`: The device that was previously executed.

All counters used by the stack are initialized to 1.

Additionally, as implemented in HyperBEAM, the device stack will honor a
number of options that are passed to it as keys in the message. Each of
these options is also passed through to the devices contained within the
stack during execution. These options include:

`Error-Strategy`: Determines how the stack handles errors from devices.
See `maybe_error/5` for more information.

`Allow-Multipass`: Determines whether the stack is allowed to automatically
re-execute from the first device when the `pass` tag is returned. See
`maybe_pass/3` for more information.

Under-the-hood, dev_stack uses a `default` handler to resolve all calls to
devices, aside `set/2` which it calls itself to mutate the message's `device`
key in order to change which device is currently being executed. This method
allows dev_stack to ensure that the message's HashPath is always correct,
even as it delegates calls to other devices. An example flow for a `dev_stack`
execution is as follows:

```

   	/Msg1/AlicesExcitingKey ->
   		dev_stack:execute ->
   			/Msg1/Set?device=/Device-Stack/1 ->
   			/Msg2/AlicesExcitingKey ->
   			/Msg3/Set?device=/Device-Stack/2 ->
   			/Msg4/AlicesExcitingKey
   			... ->
   			/MsgN/Set?device=[This-Device] ->
   		returns {ok, /MsgN+1} ->
   	/MsgN+1
```

In this example, the `device` key is mutated a number of times, but the
resulting HashPath remains correct and verifiable.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#benchmark_test-0">benchmark_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#example_device_for_stack_test-0">example_device_for_stack_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#generate_append_device-1">generate_append_device/1</a></td><td></td></tr><tr><td valign="top"><a href="#generate_append_device-2">generate_append_device/2*</a></td><td></td></tr><tr><td valign="top"><a href="#increment_pass-2">increment_pass/2*</a></td><td>Helper to increment the pass number.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td></td></tr><tr><td valign="top"><a href="#input_and_output_prefixes_test-0">input_and_output_prefixes_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#input_output_prefixes_passthrough_test-0">input_output_prefixes_passthrough_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#input_prefix-3">input_prefix/3</a></td><td>Return the input prefix for the stack.</td></tr><tr><td valign="top"><a href="#many_devices_test-0">many_devices_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_error-5">maybe_error/5*</a></td><td></td></tr><tr><td valign="top"><a href="#no_prefix_test-0">no_prefix_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#not_found_test-0">not_found_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#output_prefix-3">output_prefix/3</a></td><td>Return the output prefix for the stack.</td></tr><tr><td valign="top"><a href="#output_prefix_test-0">output_prefix_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#pass_test-0">pass_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#prefix-3">prefix/3</a></td><td>Return the default prefix for the stack.</td></tr><tr><td valign="top"><a href="#reinvocation_test-0">reinvocation_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_fold-3">resolve_fold/3*</a></td><td>The main device stack execution engine.</td></tr><tr><td valign="top"><a href="#resolve_fold-4">resolve_fold/4*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_map-3">resolve_map/3*</a></td><td>Map over the devices in the stack, accumulating the output in a single
message of keys and values, where keys are the same as the keys in the
original message (typically a number).</td></tr><tr><td valign="top"><a href="#router-3">router/3*</a></td><td></td></tr><tr><td valign="top"><a href="#router-4">router/4</a></td><td>The device stack key router.</td></tr><tr><td valign="top"><a href="#simple_map_test-0">simple_map_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#simple_stack_execute_test-0">simple_stack_execute_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#skip_test-0">skip_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_prefix_msg-0">test_prefix_msg/0*</a></td><td></td></tr><tr><td valign="top"><a href="#transform-3">transform/3*</a></td><td>Return Message1, transformed such that the device named <code>Key</code> from the
<code>Device-Stack</code> key in the message takes the place of the original <code>Device</code>
key.</td></tr><tr><td valign="top"><a href="#transform_external_call_device_test-0">transform_external_call_device_test/0*</a></td><td>Ensure we can generate a transformer message that can be called to
return a version of msg1 with only that device attached.</td></tr><tr><td valign="top"><a href="#transform_internal_call_device_test-0">transform_internal_call_device_test/0*</a></td><td>Test that the transform function can be called correctly internally
by other functions in the module.</td></tr><tr><td valign="top"><a href="#transformer_message-2">transformer_message/2*</a></td><td>Return a message which, when given a key, will transform the message
such that the device named <code>Key</code> from the <code>Device-Stack</code> key in the message
takes the place of the original <code>Device</code> key.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="benchmark_test-0"></a>

### benchmark_test/0 * ###

`benchmark_test() -> any()`

<a name="example_device_for_stack_test-0"></a>

### example_device_for_stack_test/0 * ###

`example_device_for_stack_test() -> any()`

<a name="generate_append_device-1"></a>

### generate_append_device/1 ###

`generate_append_device(Separator) -> any()`

<a name="generate_append_device-2"></a>

### generate_append_device/2 * ###

`generate_append_device(Separator, Status) -> any()`

<a name="increment_pass-2"></a>

### increment_pass/2 * ###

`increment_pass(Message, Opts) -> any()`

Helper to increment the pass number.

<a name="info-1"></a>

### info/1 ###

`info(Msg) -> any()`

<a name="input_and_output_prefixes_test-0"></a>

### input_and_output_prefixes_test/0 * ###

`input_and_output_prefixes_test() -> any()`

<a name="input_output_prefixes_passthrough_test-0"></a>

### input_output_prefixes_passthrough_test/0 * ###

`input_output_prefixes_passthrough_test() -> any()`

<a name="input_prefix-3"></a>

### input_prefix/3 ###

`input_prefix(Msg1, Msg2, Opts) -> any()`

Return the input prefix for the stack.

<a name="many_devices_test-0"></a>

### many_devices_test/0 * ###

`many_devices_test() -> any()`

<a name="maybe_error-5"></a>

### maybe_error/5 * ###

`maybe_error(Message1, Message2, DevNum, Info, Opts) -> any()`

<a name="no_prefix_test-0"></a>

### no_prefix_test/0 * ###

`no_prefix_test() -> any()`

<a name="not_found_test-0"></a>

### not_found_test/0 * ###

`not_found_test() -> any()`

<a name="output_prefix-3"></a>

### output_prefix/3 ###

`output_prefix(Msg1, Msg2, Opts) -> any()`

Return the output prefix for the stack.

<a name="output_prefix_test-0"></a>

### output_prefix_test/0 * ###

`output_prefix_test() -> any()`

<a name="pass_test-0"></a>

### pass_test/0 * ###

`pass_test() -> any()`

<a name="prefix-3"></a>

### prefix/3 ###

`prefix(Msg1, Msg2, Opts) -> any()`

Return the default prefix for the stack.

<a name="reinvocation_test-0"></a>

### reinvocation_test/0 * ###

`reinvocation_test() -> any()`

<a name="resolve_fold-3"></a>

### resolve_fold/3 * ###

`resolve_fold(Message1, Message2, Opts) -> any()`

The main device stack execution engine. See the moduledoc for more
information.

<a name="resolve_fold-4"></a>

### resolve_fold/4 * ###

`resolve_fold(Message1, Message2, DevNum, Opts) -> any()`

<a name="resolve_map-3"></a>

### resolve_map/3 * ###

`resolve_map(Message1, Message2, Opts) -> any()`

Map over the devices in the stack, accumulating the output in a single
message of keys and values, where keys are the same as the keys in the
original message (typically a number).

<a name="router-3"></a>

### router/3 * ###

`router(Message1, Message2, Opts) -> any()`

<a name="router-4"></a>

### router/4 ###

`router(Key, Message1, Message2, Opts) -> any()`

The device stack key router. Sends the request to `resolve_stack`,
except for `set/2` which is handled by the default implementation in
`dev_message`.

<a name="simple_map_test-0"></a>

### simple_map_test/0 * ###

`simple_map_test() -> any()`

<a name="simple_stack_execute_test-0"></a>

### simple_stack_execute_test/0 * ###

`simple_stack_execute_test() -> any()`

<a name="skip_test-0"></a>

### skip_test/0 * ###

`skip_test() -> any()`

<a name="test_prefix_msg-0"></a>

### test_prefix_msg/0 * ###

`test_prefix_msg() -> any()`

<a name="transform-3"></a>

### transform/3 * ###

`transform(Msg1, Key, Opts) -> any()`

Return Message1, transformed such that the device named `Key` from the
`Device-Stack` key in the message takes the place of the original `Device`
key. This transformation allows dev_stack to correctly track the HashPath
of the message as it delegates execution to devices contained within it.

<a name="transform_external_call_device_test-0"></a>

### transform_external_call_device_test/0 * ###

`transform_external_call_device_test() -> any()`

Ensure we can generate a transformer message that can be called to
return a version of msg1 with only that device attached.

<a name="transform_internal_call_device_test-0"></a>

### transform_internal_call_device_test/0 * ###

`transform_internal_call_device_test() -> any()`

Test that the transform function can be called correctly internally
by other functions in the module.

<a name="transformer_message-2"></a>

### transformer_message/2 * ###

`transformer_message(Msg1, Opts) -> any()`

Return a message which, when given a key, will transform the message
such that the device named `Key` from the `Device-Stack` key in the message
takes the place of the original `Device` key. This allows users to call
a single device from the stack:

/Msg1/Transform/DeviceName/keyInDevice ->
keyInDevice executed on DeviceName against Msg1.


--- END OF FILE: docs/resources/source-code/dev_stack.md ---

--- START OF FILE: docs/resources/source-code/dev_test.md ---
# [Module dev_test.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_test.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#compute-3">compute/3</a></td><td>Example implementation of a <code>compute</code> handler.</td></tr><tr><td valign="top"><a href="#compute_test-0">compute_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#delay-3">delay/3</a></td><td>Does nothing, just sleeps <code>Req/duration or 750</code> ms and returns the
appropriate form in order to be used as a hook.</td></tr><tr><td valign="top"><a href="#device_with_function_key_module_test-0">device_with_function_key_module_test/0*</a></td><td>Tests the resolution of a default function.</td></tr><tr><td valign="top"><a href="#increment_counter-3">increment_counter/3</a></td><td>Find a test worker's PID and send it an increment message.</td></tr><tr><td valign="top"><a href="#index-3">index/3</a></td><td>Example index handler.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Exports a default_handler function that can be used to test the
handler resolution mechanism.</td></tr><tr><td valign="top"><a href="#info-3">info/3</a></td><td>Exports a default_handler function that can be used to test the
handler resolution mechanism.</td></tr><tr><td valign="top"><a href="#init-3">init/3</a></td><td>Example <code>init/3</code> handler.</td></tr><tr><td valign="top"><a href="#load-3">load/3</a></td><td>Return a message with the device set to this module.</td></tr><tr><td valign="top"><a href="#mul-2">mul/2</a></td><td>Example implementation of an <code>imported</code> function for a WASM
executor.</td></tr><tr><td valign="top"><a href="#postprocess-3">postprocess/3</a></td><td>Set the <code>postprocessor-called</code> key to true in the HTTP server.</td></tr><tr><td valign="top"><a href="#restore-3">restore/3</a></td><td>Example <code>restore/3</code> handler.</td></tr><tr><td valign="top"><a href="#restore_test-0">restore_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#snapshot-3">snapshot/3</a></td><td>Do nothing when asked to snapshot.</td></tr><tr><td valign="top"><a href="#test_func-1">test_func/1</a></td><td></td></tr><tr><td valign="top"><a href="#update_state-3">update_state/3</a></td><td>Find a test worker's PID and send it an update message.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="compute-3"></a>

### compute/3 ###

`compute(Msg1, Msg2, Opts) -> any()`

Example implementation of a `compute` handler. Makes a running list of
the slots that have been computed in the state message and places the new
slot number in the results key.

<a name="compute_test-0"></a>

### compute_test/0 * ###

`compute_test() -> any()`

<a name="delay-3"></a>

### delay/3 ###

`delay(Msg1, Req, Opts) -> any()`

Does nothing, just sleeps `Req/duration or 750` ms and returns the
appropriate form in order to be used as a hook.

<a name="device_with_function_key_module_test-0"></a>

### device_with_function_key_module_test/0 * ###

`device_with_function_key_module_test() -> any()`

Tests the resolution of a default function.

<a name="increment_counter-3"></a>

### increment_counter/3 ###

`increment_counter(Msg1, Msg2, Opts) -> any()`

Find a test worker's PID and send it an increment message.

<a name="index-3"></a>

### index/3 ###

`index(Msg, Req, Opts) -> any()`

Example index handler.

<a name="info-1"></a>

### info/1 ###

`info(X1) -> any()`

Exports a default_handler function that can be used to test the
handler resolution mechanism.

<a name="info-3"></a>

### info/3 ###

`info(Msg1, Msg2, Opts) -> any()`

Exports a default_handler function that can be used to test the
handler resolution mechanism.

<a name="init-3"></a>

### init/3 ###

`init(Msg, Msg2, Opts) -> any()`

Example `init/3` handler. Sets the `Already-Seen` key to an empty list.

<a name="load-3"></a>

### load/3 ###

`load(Base, X2, Opts) -> any()`

Return a message with the device set to this module.

<a name="mul-2"></a>

### mul/2 ###

`mul(Msg1, Msg2) -> any()`

Example implementation of an `imported` function for a WASM
executor.

<a name="postprocess-3"></a>

### postprocess/3 ###

`postprocess(Msg, X2, Opts) -> any()`

Set the `postprocessor-called` key to true in the HTTP server.

<a name="restore-3"></a>

### restore/3 ###

`restore(Msg, Msg2, Opts) -> any()`

Example `restore/3` handler. Sets the hidden key `Test/Started` to the
value of `Current-Slot` and checks whether the `Already-Seen` key is valid.

<a name="restore_test-0"></a>

### restore_test/0 * ###

`restore_test() -> any()`

<a name="snapshot-3"></a>

### snapshot/3 ###

`snapshot(Msg1, Msg2, Opts) -> any()`

Do nothing when asked to snapshot.

<a name="test_func-1"></a>

### test_func/1 ###

`test_func(X1) -> any()`

<a name="update_state-3"></a>

### update_state/3 ###

`update_state(Msg, Msg2, Opts) -> any()`

Find a test worker's PID and send it an update message.


--- END OF FILE: docs/resources/source-code/dev_test.md ---

--- START OF FILE: docs/resources/source-code/dev_volume.md ---
# [Module dev_volume.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_volume.erl)




Secure Volume Management for HyperBEAM Nodes.

<a name="description"></a>

## Description ##

This module handles encrypted storage operations for HyperBEAM, providing
a robust and secure approach to data persistence. It manages the complete
lifecycle of encrypted volumes from detection to creation, formatting, and
mounting.

Key responsibilities:
- Volume detection and initialization
- Encrypted partition creation and formatting
- Secure mounting using cryptographic keys
- Store path reconfiguration to use mounted volumes
- Automatic handling of various system states
(new device, existing partition, etc.)

The primary entry point is the `mount/3` function, which orchestrates the
entire process based on the provided configuration parameters. This module
works alongside `hb_volume` which provides the low-level operations for
device manipulation.

Security considerations:
- Ensures data at rest is protected through LUKS encryption
- Provides proper volume sanitization and secure mounting
- IMPORTANT: This module only applies configuration set in node options and
does NOT accept disk operations via HTTP requests. It cannot format arbitrary
disks as all operations are safeguarded by host operating system permissions
enforced upon the HyperBEAM environment.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#check_base_device-8">check_base_device/8*</a></td><td>Check if the base device exists and if it does, check if the partition exists.</td></tr><tr><td valign="top"><a href="#check_partition-8">check_partition/8*</a></td><td>Check if the partition exists.</td></tr><tr><td valign="top"><a href="#create_and_mount_partition-8">create_and_mount_partition/8*</a></td><td>Create, format and mount a new partition.</td></tr><tr><td valign="top"><a href="#decrypt_volume_key-2">decrypt_volume_key/2*</a></td><td>Decrypts an encrypted volume key using the node's private key.</td></tr><tr><td valign="top"><a href="#format_and_mount-6">format_and_mount/6*</a></td><td>Format and mount a newly created partition.</td></tr><tr><td valign="top"><a href="#info-1">info/1</a></td><td>Exported function for getting device info, controls which functions are
exposed via the device API.</td></tr><tr><td valign="top"><a href="#info-3">info/3</a></td><td>HTTP info response providing information about this device.</td></tr><tr><td valign="top"><a href="#mount-3">mount/3</a></td><td>Handles the complete process of secure encrypted volume mounting.</td></tr><tr><td valign="top"><a href="#mount_existing_partition-6">mount_existing_partition/6*</a></td><td>Mount an existing partition.</td></tr><tr><td valign="top"><a href="#mount_formatted_partition-6">mount_formatted_partition/6*</a></td><td>Mount a newly formatted partition.</td></tr><tr><td valign="top"><a href="#public_key-3">public_key/3</a></td><td>Returns the node's public key for secure key exchange.</td></tr><tr><td valign="top"><a href="#update_node_config-2">update_node_config/2*</a></td><td>Update the node's configuration with the new store.</td></tr><tr><td valign="top"><a href="#update_store_path-2">update_store_path/2*</a></td><td>Update the store path to use the mounted volume.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="check_base_device-8"></a>

### check_base_device/8 * ###

<pre><code>
check_base_device(Device::term(), Partition::term(), PartitionType::term(), VolumeName::term(), MountPoint::term(), StorePath::term(), Key::term(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`Device`: The base device to check.<br />`Partition`: The partition to check.<br />`PartitionType`: The type of partition to check.<br />`VolumeName`: The name of the volume to check.<br />`MountPoint`: The mount point to check.<br />`StorePath`: The store path to check.<br />`Key`: The key to check.<br />`Opts`: The options to check.<br />

returns: `{ok, Binary}` on success with operation result message, or
`{error, Binary}` on failure with error message.

Check if the base device exists and if it does, check if the partition exists.

<a name="check_partition-8"></a>

### check_partition/8 * ###

<pre><code>
check_partition(Device::term(), Partition::term(), PartitionType::term(), VolumeName::term(), MountPoint::term(), StorePath::term(), Key::term(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`Device`: The base device to check.<br />`Partition`: The partition to check.<br />`PartitionType`: The type of partition to check.<br />`VolumeName`: The name of the volume to check.<br />`MountPoint`: The mount point to check.<br />`StorePath`: The store path to check.<br />`Key`: The key to check.<br />`Opts`: The options to check.<br />

returns: `{ok, Binary}` on success with operation result message, or
`{error, Binary}` on failure with error message.

Check if the partition exists. If it does, attempt to mount it.
If it doesn't exist, create it, format it with encryption and mount it.

<a name="create_and_mount_partition-8"></a>

### create_and_mount_partition/8 * ###

<pre><code>
create_and_mount_partition(Device::term(), Partition::term(), PartitionType::term(), Key::term(), MountPoint::term(), VolumeName::term(), StorePath::term(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`Device`: The device to create the partition on.<br />`Partition`: The partition to create.<br />`PartitionType`: The type of partition to create.<br />`Key`: The key to create the partition with.<br />`MountPoint`: The mount point to mount the partition to.<br />`VolumeName`: The name of the volume to mount.<br />`StorePath`: The store path to mount.<br />`Opts`: The options to mount.<br />

returns: `{ok, Binary}` on success with operation result message, or
`{error, Binary}` on failure with error message.

Create, format and mount a new partition.

<a name="decrypt_volume_key-2"></a>

### decrypt_volume_key/2 * ###

<pre><code>
decrypt_volume_key(EncryptedKeyBase64::binary(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`Opts`: A map of configuration options.<br />

returns: `{ok, DecryptedKey}` on successful decryption, or
`{error, Binary}` if decryption fails.

Decrypts an encrypted volume key using the node's private key.

This function takes an encrypted key (typically sent by a client who encrypted
it with the node's public key) and decrypts it using the node's private RSA key.

<a name="format_and_mount-6"></a>

### format_and_mount/6 * ###

<pre><code>
format_and_mount(Partition::term(), Key::term(), MountPoint::term(), VolumeName::term(), StorePath::term(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`Partition`: The partition to format and mount.<br />`Key`: The key to format and mount the partition with.<br />`MountPoint`: The mount point to mount the partition to.<br />`VolumeName`: The name of the volume to mount.<br />`StorePath`: The store path to mount.<br />`Opts`: The options to mount.<br />

returns: `{ok, Binary}` on success with operation result message, or
`{error, Binary}` on failure with error message.

Format and mount a newly created partition.

<a name="info-1"></a>

### info/1 ###

`info(X1) -> any()`

Exported function for getting device info, controls which functions are
exposed via the device API.

<a name="info-3"></a>

### info/3 ###

`info(Msg1, Msg2, Opts) -> any()`

HTTP info response providing information about this device

<a name="mount-3"></a>

### mount/3 ###

<pre><code>
mount(M1::term(), M2::term(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`M1`: Base message for context.<br />`M2`: Request message with operation details.<br />`Opts`: A map of configuration options for volume operations.<br />

returns: `{ok, Binary}` on success with operation result message, or
`{error, Binary}` on failure with error message.

Handles the complete process of secure encrypted volume mounting.

This function performs the following operations depending on the state:
1. Validates the encryption key is present
2. Checks if the base device exists
3. Checks if the partition exists on the device
4. If the partition exists, attempts to mount it
5. If the partition doesn't exist, creates it, formats it with encryption
and mounts it
6. Updates the node's store configuration to use the mounted volume

Config options in Opts map:
- priv_volume_key: (Required) The encryption key
- volume_device: Base device path
- volume_partition: Partition path
- volume_partition_type: Filesystem type
- volume_name: Name for encrypted volume
- volume_mount_point: Where to mount
- volume_store_path: Store path on volume

<a name="mount_existing_partition-6"></a>

### mount_existing_partition/6 * ###

<pre><code>
mount_existing_partition(Partition::term(), Key::term(), MountPoint::term(), VolumeName::term(), StorePath::term(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`Partition`: The partition to mount.<br />`Key`: The key to mount.<br />`MountPoint`: The mount point to mount.<br />`VolumeName`: The name of the volume to mount.<br />`StorePath`: The store path to mount.<br />`Opts`: The options to mount.<br />

returns: `{ok, Binary}` on success with operation result message, or
`{error, Binary}` on failure with error message.

Mount an existing partition.

<a name="mount_formatted_partition-6"></a>

### mount_formatted_partition/6 * ###

<pre><code>
mount_formatted_partition(Partition::term(), Key::term(), MountPoint::term(), VolumeName::term(), StorePath::term(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`Partition`: The partition to mount.<br />`Key`: The key to mount the partition with.<br />`MountPoint`: The mount point to mount the partition to.<br />`VolumeName`: The name of the volume to mount.<br />`StorePath`: The store path to mount.<br />`Opts`: The options to mount.<br />

returns: `{ok, Binary}` on success with operation result message, or
`{error, Binary}` on failure with error message.

Mount a newly formatted partition.

<a name="public_key-3"></a>

### public_key/3 ###

<pre><code>
public_key(M1::term(), M2::term(), Opts::map()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

`Opts`: A map of configuration options.<br />

returns: `{ok, Map}` containing the node's public key on success, or
`{error, Binary}` if the node's wallet is not available.

Returns the node's public key for secure key exchange.

This function retrieves the node's wallet and extracts the public key
for encryption purposes. It allows users to securely exchange encryption keys
by first encrypting their volume key with the node's public key.

The process ensures that sensitive keys are never transmitted in plaintext.
The encrypted key can then be securely sent to the node, which will decrypt it
using its private key before using it for volume encryption.

<a name="update_node_config-2"></a>

### update_node_config/2 * ###

<pre><code>
update_node_config(NewStore::term(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`NewStore`: The new store to update the node's configuration with.<br />`Opts`: The options to update the node's configuration with.<br />

returns: `{ok, Binary}` on success with operation result message, or
`{error, Binary}` on failure with error message.

Update the node's configuration with the new store.

<a name="update_store_path-2"></a>

### update_store_path/2 * ###

<pre><code>
update_store_path(StorePath::term(), Opts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`StorePath`: The store path to update.<br />`Opts`: The options to update.<br />

returns: `{ok, Binary}` on success with operation result message, or
`{error, Binary}` on failure with error message.

Update the store path to use the mounted volume.


--- END OF FILE: docs/resources/source-code/dev_volume.md ---

--- START OF FILE: docs/resources/source-code/dev_wasi.md ---
# [Module dev_wasi.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_wasi.erl)




A virtual filesystem device.

<a name="description"></a>

## Description ##
Implements a file-system-as-map structure, which is traversible externally.
Each file is a binary and each directory is an AO-Core message.
Additionally, this module adds a series of WASI-preview-1 compatible
functions for accessing the filesystem as imported functions by WASM
modules.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#basic_aos_exec_test-0">basic_aos_exec_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#clock_time_get-3">clock_time_get/3</a></td><td></td></tr><tr><td valign="top"><a href="#compute-1">compute/1</a></td><td></td></tr><tr><td valign="top"><a href="#fd_read-3">fd_read/3</a></td><td>Read from a file using the WASI-p1 standard interface.</td></tr><tr><td valign="top"><a href="#fd_read-5">fd_read/5*</a></td><td></td></tr><tr><td valign="top"><a href="#fd_write-3">fd_write/3</a></td><td>WASM stdlib implementation of <code>fd_write</code>, using the WASI-p1 standard
interface.</td></tr><tr><td valign="top"><a href="#fd_write-5">fd_write/5*</a></td><td></td></tr><tr><td valign="top"><a href="#gen_test_aos_msg-1">gen_test_aos_msg/1*</a></td><td></td></tr><tr><td valign="top"><a href="#gen_test_env-0">gen_test_env/0*</a></td><td></td></tr><tr><td valign="top"><a href="#generate_wasi_stack-3">generate_wasi_stack/3*</a></td><td></td></tr><tr><td valign="top"><a href="#init-0">init/0*</a></td><td></td></tr><tr><td valign="top"><a href="#init-3">init/3</a></td><td>On-boot, initialize the virtual file system with:
- Empty stdio files
- WASI-preview-1 compatible functions for accessing the filesystem
- File descriptors for those files.</td></tr><tr><td valign="top"><a href="#parse_iovec-2">parse_iovec/2*</a></td><td>Parse an iovec in WASI-preview-1 format.</td></tr><tr><td valign="top"><a href="#path_open-3">path_open/3</a></td><td>Adds a file descriptor to the state message.</td></tr><tr><td valign="top"><a href="#stdout-1">stdout/1</a></td><td>Return the stdout buffer from a state message.</td></tr><tr><td valign="top"><a href="#vfs_is_serializable_test-0">vfs_is_serializable_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#wasi_stack_is_serializable_test-0">wasi_stack_is_serializable_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="basic_aos_exec_test-0"></a>

### basic_aos_exec_test/0 * ###

`basic_aos_exec_test() -> any()`

<a name="clock_time_get-3"></a>

### clock_time_get/3 ###

`clock_time_get(Msg1, Msg2, Opts) -> any()`

<a name="compute-1"></a>

### compute/1 ###

`compute(Msg1) -> any()`

<a name="fd_read-3"></a>

### fd_read/3 ###

`fd_read(Msg1, Msg2, Opts) -> any()`

Read from a file using the WASI-p1 standard interface.

<a name="fd_read-5"></a>

### fd_read/5 * ###

`fd_read(S, Instance, X3, BytesRead, Opts) -> any()`

<a name="fd_write-3"></a>

### fd_write/3 ###

`fd_write(Msg1, Msg2, Opts) -> any()`

WASM stdlib implementation of `fd_write`, using the WASI-p1 standard
interface.

<a name="fd_write-5"></a>

### fd_write/5 * ###

`fd_write(S, Instance, X3, BytesWritten, Opts) -> any()`

<a name="gen_test_aos_msg-1"></a>

### gen_test_aos_msg/1 * ###

`gen_test_aos_msg(Command) -> any()`

<a name="gen_test_env-0"></a>

### gen_test_env/0 * ###

`gen_test_env() -> any()`

<a name="generate_wasi_stack-3"></a>

### generate_wasi_stack/3 * ###

`generate_wasi_stack(File, Func, Params) -> any()`

<a name="init-0"></a>

### init/0 * ###

`init() -> any()`

<a name="init-3"></a>

### init/3 ###

`init(M1, M2, Opts) -> any()`

On-boot, initialize the virtual file system with:
- Empty stdio files
- WASI-preview-1 compatible functions for accessing the filesystem
- File descriptors for those files.

<a name="parse_iovec-2"></a>

### parse_iovec/2 * ###

`parse_iovec(Instance, Ptr) -> any()`

Parse an iovec in WASI-preview-1 format.

<a name="path_open-3"></a>

### path_open/3 ###

`path_open(Msg1, Msg2, Opts) -> any()`

Adds a file descriptor to the state message.
path_open(M, Instance, [FDPtr, LookupFlag, PathPtr|_]) ->

<a name="stdout-1"></a>

### stdout/1 ###

`stdout(M) -> any()`

Return the stdout buffer from a state message.

<a name="vfs_is_serializable_test-0"></a>

### vfs_is_serializable_test/0 * ###

`vfs_is_serializable_test() -> any()`

<a name="wasi_stack_is_serializable_test-0"></a>

### wasi_stack_is_serializable_test/0 * ###

`wasi_stack_is_serializable_test() -> any()`


--- END OF FILE: docs/resources/source-code/dev_wasi.md ---

--- START OF FILE: docs/resources/source-code/dev_wasm.md ---
# [Module dev_wasm.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/dev_wasm.erl)




A device that executes a WASM image on messages using the Memory-64
preview standard.

<a name="description"></a>

## Description ##

In the backend, this device uses `beamr`: An Erlang wrapper
for WAMR, the WebAssembly Micro Runtime.

The device has the following requirements and interface:

```

       M1/Init ->
           Assumes:
               M1/process
               M1/[Prefix]/image
           Generates:
               /priv/[Prefix]/instance
               /priv/[Prefix]/import-resolver
           Side-effects:
               Creates a WASM executor loaded in memory of the HyperBEAM node.
       M1/Compute ->
           Assumes:
               M1/priv/[Prefix]/instance
               M1/priv/[Prefix]/import-resolver
               M1/process
               M2/message
               M2/message/function OR M1/function
               M2/message/parameters OR M1/parameters
           Generates:
               /results/[Prefix]/type
               /results/[Prefix]/output
           Side-effects:
               Calls the WASM executor with the message and process.
       M1/[Prefix]/state ->
           Assumes:
               M1/priv/[Prefix]/instance
           Generates:
               Raw binary WASM state
```
<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#basic_execution_64_test-0">basic_execution_64_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#basic_execution_test-0">basic_execution_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#benchmark_test-0">benchmark_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#cache_wasm_image-1">cache_wasm_image/1</a></td><td></td></tr><tr><td valign="top"><a href="#cache_wasm_image-2">cache_wasm_image/2</a></td><td></td></tr><tr><td valign="top"><a href="#compute-3">compute/3</a></td><td>Call the WASM executor with a message that has been prepared by a prior
pass.</td></tr><tr><td valign="top"><a href="#default_import_resolver-3">default_import_resolver/3*</a></td><td>Take a BEAMR import call and resolve it using <code>hb_ao</code>.</td></tr><tr><td valign="top"><a href="#import-3">import/3</a></td><td>Handle standard library calls by:
1.</td></tr><tr><td valign="top"><a href="#imported_function_test-0">imported_function_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#info-2">info/2</a></td><td>Export all functions aside the <code>instance/3</code> function.</td></tr><tr><td valign="top"><a href="#init-0">init/0*</a></td><td></td></tr><tr><td valign="top"><a href="#init-3">init/3</a></td><td>Boot a WASM image on the image stated in the <code>process/image</code> field of
the message.</td></tr><tr><td valign="top"><a href="#init_test-0">init_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#input_prefix_test-0">input_prefix_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#instance-3">instance/3</a></td><td>Get the WASM instance from the message.</td></tr><tr><td valign="top"><a href="#normalize-3">normalize/3</a></td><td>Normalize the message to have an open WASM instance, but no literal
<code>State</code> key.</td></tr><tr><td valign="top"><a href="#process_prefixes_test-0">process_prefixes_test/0*</a></td><td>Test that realistic prefixing for a <code>dev_process</code> works --
including both inputs (from <code>Process/</code>) and outputs (to the
Device-Key) work.</td></tr><tr><td valign="top"><a href="#snapshot-3">snapshot/3</a></td><td>Serialize the WASM state to a binary.</td></tr><tr><td valign="top"><a href="#state_export_and_restore_test-0">state_export_and_restore_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#terminate-3">terminate/3</a></td><td>Tear down the WASM executor.</td></tr><tr><td valign="top"><a href="#test_run_wasm-4">test_run_wasm/4*</a></td><td></td></tr><tr><td valign="top"><a href="#undefined_import_stub-3">undefined_import_stub/3*</a></td><td>Log the call to the standard library as an event, and write the
call details into the message.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="basic_execution_64_test-0"></a>

### basic_execution_64_test/0 * ###

`basic_execution_64_test() -> any()`

<a name="basic_execution_test-0"></a>

### basic_execution_test/0 * ###

`basic_execution_test() -> any()`

<a name="benchmark_test-0"></a>

### benchmark_test/0 * ###

`benchmark_test() -> any()`

<a name="cache_wasm_image-1"></a>

### cache_wasm_image/1 ###

`cache_wasm_image(Image) -> any()`

<a name="cache_wasm_image-2"></a>

### cache_wasm_image/2 ###

`cache_wasm_image(Image, Opts) -> any()`

<a name="compute-3"></a>

### compute/3 ###

`compute(RawM1, M2, Opts) -> any()`

Call the WASM executor with a message that has been prepared by a prior
pass.

<a name="default_import_resolver-3"></a>

### default_import_resolver/3 * ###

`default_import_resolver(Msg1, Msg2, Opts) -> any()`

Take a BEAMR import call and resolve it using `hb_ao`.

<a name="import-3"></a>

### import/3 ###

`import(Msg1, Msg2, Opts) -> any()`

Handle standard library calls by:
1. Adding the right prefix to the path from BEAMR.
2. Adding the state to the message at the stdlib path.
3. Resolving the adjusted-path-Msg2 against the added-state-Msg1.
4. If it succeeds, return the new state from the message.
5. If it fails with `not_found`, call the stub handler.

<a name="imported_function_test-0"></a>

### imported_function_test/0 * ###

`imported_function_test() -> any()`

<a name="info-2"></a>

### info/2 ###

`info(Msg1, Opts) -> any()`

Export all functions aside the `instance/3` function.

<a name="init-0"></a>

### init/0 * ###

`init() -> any()`

<a name="init-3"></a>

### init/3 ###

`init(M1, M2, Opts) -> any()`

Boot a WASM image on the image stated in the `process/image` field of
the message.

<a name="init_test-0"></a>

### init_test/0 * ###

`init_test() -> any()`

<a name="input_prefix_test-0"></a>

### input_prefix_test/0 * ###

`input_prefix_test() -> any()`

<a name="instance-3"></a>

### instance/3 ###

`instance(M1, M2, Opts) -> any()`

Get the WASM instance from the message. Note that this function is exported
such that other devices can use it, but it is excluded from calls from AO-Core
resolution directly.

<a name="normalize-3"></a>

### normalize/3 ###

`normalize(RawM1, M2, Opts) -> any()`

Normalize the message to have an open WASM instance, but no literal
`State` key. Ensure that we do not change the hashpath during this process.

<a name="process_prefixes_test-0"></a>

### process_prefixes_test/0 * ###

`process_prefixes_test() -> any()`

Test that realistic prefixing for a `dev_process` works --
including both inputs (from `Process/`) and outputs (to the
Device-Key) work

<a name="snapshot-3"></a>

### snapshot/3 ###

`snapshot(M1, M2, Opts) -> any()`

Serialize the WASM state to a binary.

<a name="state_export_and_restore_test-0"></a>

### state_export_and_restore_test/0 * ###

`state_export_and_restore_test() -> any()`

<a name="terminate-3"></a>

### terminate/3 ###

`terminate(M1, M2, Opts) -> any()`

Tear down the WASM executor.

<a name="test_run_wasm-4"></a>

### test_run_wasm/4 * ###

`test_run_wasm(File, Func, Params, AdditionalMsg) -> any()`

<a name="undefined_import_stub-3"></a>

### undefined_import_stub/3 * ###

`undefined_import_stub(Msg1, Msg2, Opts) -> any()`

Log the call to the standard library as an event, and write the
call details into the message.


--- END OF FILE: docs/resources/source-code/dev_wasm.md ---

--- START OF FILE: docs/resources/source-code/hb_ao_test_vectors.md ---
# [Module hb_ao_test_vectors.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_ao_test_vectors.erl)




Uses a series of different `Opts` values to test the resolution engine's
execution under different circumstances.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#as_path_test-1">as_path_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#basic_get_test-1">basic_get_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#basic_set_test-1">basic_set_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#continue_as_test-1">continue_as_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#deep_recursive_get_test-1">deep_recursive_get_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#deep_set_new_messages_test-0">deep_set_new_messages_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#deep_set_test-1">deep_set_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#deep_set_with_device_test-1">deep_set_with_device_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#denormalized_device_key_test-1">denormalized_device_key_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#device_excludes_test-1">device_excludes_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#device_exports_test-1">device_exports_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#device_with_default_handler_function_test-1">device_with_default_handler_function_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#device_with_handler_function_test-1">device_with_handler_function_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#exec_dummy_device-2">exec_dummy_device/2*</a></td><td>Ensure that we can read a device from the cache then execute it.</td></tr><tr><td valign="top"><a href="#gen_default_device-0">gen_default_device/0*</a></td><td>Create a simple test device that implements the default handler.</td></tr><tr><td valign="top"><a href="#gen_handler_device-0">gen_handler_device/0*</a></td><td>Create a simple test device that implements the handler key.</td></tr><tr><td valign="top"><a href="#generate_device_with_keys_using_args-0">generate_device_with_keys_using_args/0*</a></td><td>Generates a test device with three keys, each of which uses
progressively more of the arguments that can be passed to a device key.</td></tr><tr><td valign="top"><a href="#get_as_with_device_test-1">get_as_with_device_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#get_with_device_test-1">get_with_device_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#key_from_id_device_with_args_test-1">key_from_id_device_with_args_test/1*</a></td><td>Test that arguments are passed to a device key as expected.</td></tr><tr><td valign="top"><a href="#key_to_binary_test-1">key_to_binary_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#list_transform_test-1">list_transform_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#load_as_test-1">load_as_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#load_device_test-0">load_device_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#recursive_get_test-1">recursive_get_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_binary_key_test-1">resolve_binary_key_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_from_multiple_keys_test-1">resolve_from_multiple_keys_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_id_test-1">resolve_id_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_key_twice_test-1">resolve_key_twice_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_path_element_test-1">resolve_path_element_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_simple_test-1">resolve_simple_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#run_all_test_-0">run_all_test_/0*</a></td><td>Run each test in the file with each set of options.</td></tr><tr><td valign="top"><a href="#run_test-0">run_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#set_with_device_test-1">set_with_device_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#start_as_test-1">start_as_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#start_as_with_parameters_test-1">start_as_with_parameters_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#step_hook_test-1">step_hook_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#test_opts-0">test_opts/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_suite-0">test_suite/0*</a></td><td></td></tr><tr><td valign="top"><a href="#untrusted_load_device_test-0">untrusted_load_device_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="as_path_test-1"></a>

### as_path_test/1 * ###

`as_path_test(Opts) -> any()`

<a name="basic_get_test-1"></a>

### basic_get_test/1 * ###

`basic_get_test(Opts) -> any()`

<a name="basic_set_test-1"></a>

### basic_set_test/1 * ###

`basic_set_test(Opts) -> any()`

<a name="continue_as_test-1"></a>

### continue_as_test/1 * ###

`continue_as_test(Opts) -> any()`

<a name="deep_recursive_get_test-1"></a>

### deep_recursive_get_test/1 * ###

`deep_recursive_get_test(Opts) -> any()`

<a name="deep_set_new_messages_test-0"></a>

### deep_set_new_messages_test/0 * ###

`deep_set_new_messages_test() -> any()`

<a name="deep_set_test-1"></a>

### deep_set_test/1 * ###

`deep_set_test(Opts) -> any()`

<a name="deep_set_with_device_test-1"></a>

### deep_set_with_device_test/1 * ###

`deep_set_with_device_test(Opts) -> any()`

<a name="denormalized_device_key_test-1"></a>

### denormalized_device_key_test/1 * ###

`denormalized_device_key_test(Opts) -> any()`

<a name="device_excludes_test-1"></a>

### device_excludes_test/1 * ###

`device_excludes_test(Opts) -> any()`

<a name="device_exports_test-1"></a>

### device_exports_test/1 * ###

`device_exports_test(Opts) -> any()`

<a name="device_with_default_handler_function_test-1"></a>

### device_with_default_handler_function_test/1 * ###

`device_with_default_handler_function_test(Opts) -> any()`

<a name="device_with_handler_function_test-1"></a>

### device_with_handler_function_test/1 * ###

`device_with_handler_function_test(Opts) -> any()`

<a name="exec_dummy_device-2"></a>

### exec_dummy_device/2 * ###

`exec_dummy_device(SigningWallet, Opts) -> any()`

Ensure that we can read a device from the cache then execute it. By
extension, this will also allow us to load a device from Arweave due to the
remote store implementations.

<a name="gen_default_device-0"></a>

### gen_default_device/0 * ###

`gen_default_device() -> any()`

Create a simple test device that implements the default handler.

<a name="gen_handler_device-0"></a>

### gen_handler_device/0 * ###

`gen_handler_device() -> any()`

Create a simple test device that implements the handler key.

<a name="generate_device_with_keys_using_args-0"></a>

### generate_device_with_keys_using_args/0 * ###

`generate_device_with_keys_using_args() -> any()`

Generates a test device with three keys, each of which uses
progressively more of the arguments that can be passed to a device key.

<a name="get_as_with_device_test-1"></a>

### get_as_with_device_test/1 * ###

`get_as_with_device_test(Opts) -> any()`

<a name="get_with_device_test-1"></a>

### get_with_device_test/1 * ###

`get_with_device_test(Opts) -> any()`

<a name="key_from_id_device_with_args_test-1"></a>

### key_from_id_device_with_args_test/1 * ###

`key_from_id_device_with_args_test(Opts) -> any()`

Test that arguments are passed to a device key as expected.
Particularly, we need to ensure that the key function in the device can
specify any arity (1 through 3) and the call is handled correctly.

<a name="key_to_binary_test-1"></a>

### key_to_binary_test/1 * ###

`key_to_binary_test(Opts) -> any()`

<a name="list_transform_test-1"></a>

### list_transform_test/1 * ###

`list_transform_test(Opts) -> any()`

<a name="load_as_test-1"></a>

### load_as_test/1 * ###

`load_as_test(Opts) -> any()`

<a name="load_device_test-0"></a>

### load_device_test/0 * ###

`load_device_test() -> any()`

<a name="recursive_get_test-1"></a>

### recursive_get_test/1 * ###

`recursive_get_test(Opts) -> any()`

<a name="resolve_binary_key_test-1"></a>

### resolve_binary_key_test/1 * ###

`resolve_binary_key_test(Opts) -> any()`

<a name="resolve_from_multiple_keys_test-1"></a>

### resolve_from_multiple_keys_test/1 * ###

`resolve_from_multiple_keys_test(Opts) -> any()`

<a name="resolve_id_test-1"></a>

### resolve_id_test/1 * ###

`resolve_id_test(Opts) -> any()`

<a name="resolve_key_twice_test-1"></a>

### resolve_key_twice_test/1 * ###

`resolve_key_twice_test(Opts) -> any()`

<a name="resolve_path_element_test-1"></a>

### resolve_path_element_test/1 * ###

`resolve_path_element_test(Opts) -> any()`

<a name="resolve_simple_test-1"></a>

### resolve_simple_test/1 * ###

`resolve_simple_test(Opts) -> any()`

<a name="run_all_test_-0"></a>

### run_all_test_/0 * ###

`run_all_test_() -> any()`

Run each test in the file with each set of options. Start and reset
the store for each test.

<a name="run_test-0"></a>

### run_test/0 * ###

`run_test() -> any()`

<a name="set_with_device_test-1"></a>

### set_with_device_test/1 * ###

`set_with_device_test(Opts) -> any()`

<a name="start_as_test-1"></a>

### start_as_test/1 * ###

`start_as_test(Opts) -> any()`

<a name="start_as_with_parameters_test-1"></a>

### start_as_with_parameters_test/1 * ###

`start_as_with_parameters_test(Opts) -> any()`

<a name="step_hook_test-1"></a>

### step_hook_test/1 * ###

`step_hook_test(InitOpts) -> any()`

<a name="test_opts-0"></a>

### test_opts/0 * ###

`test_opts() -> any()`

<a name="test_suite-0"></a>

### test_suite/0 * ###

`test_suite() -> any()`

<a name="untrusted_load_device_test-0"></a>

### untrusted_load_device_test/0 * ###

`untrusted_load_device_test() -> any()`


--- END OF FILE: docs/resources/source-code/hb_ao_test_vectors.md ---

--- START OF FILE: docs/resources/source-code/hb_ao.md ---
# [Module hb_ao.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_ao.erl)




This module is the root of the device call logic of the
AO-Core protocol in HyperBEAM.

<a name="description"></a>

## Description ##

At the implementation level, every message is simply a collection of keys,
dictated by its `Device`, that can be resolved in order to yield their
values. Each key may contain a link to another message or a raw value:

`ao(BaseMessage, RequestMessage) -> {Status, Result}`

Under-the-hood, `AO-Core(BaseMessage, RequestMessage)` leads to a lookup of
the `device` key of the base message, followed by the evaluation of
`DeviceMod:PathPart(BaseMessage, RequestMessage)`, which defines the user
compute to be performed. If `BaseMessage` does not specify a device,
`~message@1.0` is assumed. The key to resolve is specified by the `path`
field of the message.

After each output, the `HashPath` is updated to include the `RequestMessage`
that was executed upon it.

Because each message implies a device that can resolve its keys, as well
as generating a merkle tree of the computation that led to the result,
you can see the AO-Core protocol as a system for cryptographically chaining
the execution of `combinators`. See `docs/ao-core-protocol.md` for more
information about AO-Core.

The `key(BaseMessage, RequestMessage)` pattern is repeated throughout the
HyperBEAM codebase, sometimes with `BaseMessage` replaced with `Msg1`, `M1`
or similar, and `RequestMessage` replaced with `Msg2`, `M2`, etc.

The result of any computation can be either a new message or a raw literal
value (a binary, integer, float, atom, or list of such values).

Devices can be expressed as either modules or maps. They can also be
referenced by an Arweave ID, which can be used to load a device from
the network (depending on the value of the `load_remote_devices` and
`trusted_device_signers` environment settings).

HyperBEAM device implementations are defined as follows:

```

       DevMod:ExportedFunc : Key resolution functions. All are assumed to be
                             device keys (thus, present in every message that
                             uses it) unless specified by <code>DevMod:info()</code>.
                             Each function takes a set of parameters
                             of the form <code>DevMod:KeyHandler(Msg1, Msg2, Opts)</code>.
                             Each of these arguments can be ommitted if not
                             needed. Non-exported functions are not assumed
                             to be device keys.
       DevMod:info : Optional. Returns a map of options for the device. All
                     options are optional and assumed to be the defaults if
                     not specified. This function can accept a <code>Message1</code> as
                     an argument, allowing it to specify its functionality
                     based on a specific message if appropriate.
       info/exports : Overrides the export list of the Erlang module, such that
                     only the functions in this list are assumed to be device
                     keys. Defaults to all of the functions that DevMod
                     exports in the Erlang environment.
       info/excludes : A list of keys that should not be resolved by the device,
                       despite being present in the Erlang module exports list.
       info/handler : A function that should be used to handle _all_ keys for
                      messages using the device.
       info/default : A function that should be used to handle all keys that
                      are not explicitly implemented by the device. Defaults to
                      the <code>dev_message</code> device, which contains general keys for
                      interacting with messages.
       info/default_mod : A different device module that should be used to
                      handle all keys that are not explicitly implemented
                      by the device. Defaults to the <code>dev_message</code> device.
       info/grouper : A function that returns the concurrency 'group' name for
                      an execution. Executions with the same group name will
                      be executed by sending a message to the associated process
                      and waiting for a response. This allows you to control
                      concurrency of execution and to allow executions to share
                      in-memory state as applicable. Default: A derivation of
                      Msg1+Msg2. This means that concurrent calls for the same
                      output will lead to only a single execution.
       info/worker : A function that should be run as the 'server' loop of
                     the executor for interactions using the device.
   The HyperBEAM resolver also takes a number of runtime options that change
   the way that the environment operates:<code>update_hashpath</code>:  Whether to add the <code>Msg2</code> to <code>HashPath</code> for the <code>Msg3</code>.
   					Default: true.<code>add_key</code>:          Whether to add the key to the start of the arguments.
   					Default: <code><not set></code>.
```
<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#deep_set-4">deep_set/4</a></td><td>Recursively search a map, resolving keys, and set the value of the key
at the given path.</td></tr><tr><td valign="top"><a href="#default_module-0">default_module/0*</a></td><td>The default device is the identity device, which simply returns the
value associated with any key as it exists in its Erlang map.</td></tr><tr><td valign="top"><a href="#device_set-4">device_set/4*</a></td><td>Call the device's <code>set</code> function.</td></tr><tr><td valign="top"><a href="#device_set-5">device_set/5*</a></td><td></td></tr><tr><td valign="top"><a href="#do_resolve_many-2">do_resolve_many/2*</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_message_loaded-2">ensure_message_loaded/2*</a></td><td>Ensure that a message is loaded from the cache if it is an ID, or
a link, such that it is ready for execution.</td></tr><tr><td valign="top"><a href="#error_execution-5">error_execution/5*</a></td><td>Handle an error in a device call.</td></tr><tr><td valign="top"><a href="#error_infinite-3">error_infinite/3*</a></td><td>Catch all return if we are in an infinite loop.</td></tr><tr><td valign="top"><a href="#error_invalid_intermediate_status-5">error_invalid_intermediate_status/5*</a></td><td></td></tr><tr><td valign="top"><a href="#error_invalid_message-3">error_invalid_message/3*</a></td><td>Catch all return if the message is invalid.</td></tr><tr><td valign="top"><a href="#find_exported_function-5">find_exported_function/5</a></td><td>Find the function with the highest arity that has the given name, if it
exists.</td></tr><tr><td valign="top"><a href="#force_message-2">force_message/2</a></td><td></td></tr><tr><td valign="top"><a href="#get-2">get/2</a></td><td>Shortcut for resolving a key in a message without its status if it is
<code>ok</code>.</td></tr><tr><td valign="top"><a href="#get-3">get/3</a></td><td></td></tr><tr><td valign="top"><a href="#get-4">get/4</a></td><td></td></tr><tr><td valign="top"><a href="#get_first-2">get_first/2</a></td><td>take a sequence of base messages and paths, then return the value of the
first message that can be resolved using a path.</td></tr><tr><td valign="top"><a href="#get_first-3">get_first/3</a></td><td></td></tr><tr><td valign="top"><a href="#info-2">info/2</a></td><td>Get the info map for a device, optionally giving it a message if the
device's info function is parameterized by one.</td></tr><tr><td valign="top"><a href="#info-3">info/3*</a></td><td></td></tr><tr><td valign="top"><a href="#info_handler_to_fun-4">info_handler_to_fun/4*</a></td><td>Parse a handler key given by a device's <code>info</code>.</td></tr><tr><td valign="top"><a href="#internal_opts-1">internal_opts/1*</a></td><td>The execution options that are used internally by this module
when calling itself.</td></tr><tr><td valign="top"><a href="#is_exported-3">is_exported/3*</a></td><td></td></tr><tr><td valign="top"><a href="#is_exported-4">is_exported/4</a></td><td>Check if a device is guarding a key via its <code>exports</code> list.</td></tr><tr><td valign="top"><a href="#keys-1">keys/1</a></td><td>Shortcut to get the list of keys from a message.</td></tr><tr><td valign="top"><a href="#keys-2">keys/2</a></td><td></td></tr><tr><td valign="top"><a href="#keys-3">keys/3</a></td><td></td></tr><tr><td valign="top"><a href="#load_device-2">load_device/2</a></td><td>Load a device module from its name or a message ID.</td></tr><tr><td valign="top"><a href="#maybe_force_message-2">maybe_force_message/2*</a></td><td>Force the result of a device call into a message if the result is not
requested by the <code>Opts</code>.</td></tr><tr><td valign="top"><a href="#message_to_device-2">message_to_device/2</a></td><td>Extract the device module from a message.</td></tr><tr><td valign="top"><a href="#message_to_fun-3">message_to_fun/3</a></td><td>Calculate the Erlang function that should be called to get a value for
a given key from a device.</td></tr><tr><td valign="top"><a href="#normalize_key-1">normalize_key/1</a></td><td>Convert a key to a binary in normalized form.</td></tr><tr><td valign="top"><a href="#normalize_key-2">normalize_key/2</a></td><td></td></tr><tr><td valign="top"><a href="#normalize_keys-1">normalize_keys/1</a></td><td>Ensure that a message is processable by the AO-Core resolver: No lists.</td></tr><tr><td valign="top"><a href="#normalize_keys-2">normalize_keys/2</a></td><td></td></tr><tr><td valign="top"><a href="#remove-2">remove/2</a></td><td>Remove a key from a message, using its underlying device.</td></tr><tr><td valign="top"><a href="#remove-3">remove/3</a></td><td></td></tr><tr><td valign="top"><a href="#resolve-2">resolve/2</a></td><td>Get the value of a message's key by running its associated device
function.</td></tr><tr><td valign="top"><a href="#resolve-3">resolve/3</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_many-2">resolve_many/2</a></td><td>Resolve a list of messages in sequence.</td></tr><tr><td valign="top"><a href="#resolve_stage-4">resolve_stage/4*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_stage-5">resolve_stage/5*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_stage-6">resolve_stage/6*</a></td><td></td></tr><tr><td valign="top"><a href="#set-3">set/3</a></td><td>Shortcut for setting a key in the message using its underlying device.</td></tr><tr><td valign="top"><a href="#set-4">set/4</a></td><td></td></tr><tr><td valign="top"><a href="#subresolve-4">subresolve/4*</a></td><td>Execute a sub-resolution.</td></tr><tr><td valign="top"><a href="#truncate_args-2">truncate_args/2</a></td><td>Truncate the arguments of a function to the number of arguments it
actually takes.</td></tr><tr><td valign="top"><a href="#verify_device_compatibility-2">verify_device_compatibility/2*</a></td><td>Verify that a device is compatible with the current machine.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="deep_set-4"></a>

### deep_set/4 ###

`deep_set(Msg, Rest, Value, Opts) -> any()`

Recursively search a map, resolving keys, and set the value of the key
at the given path. This function has special cases for handling `set` calls
where the path is an empty list (`/`). In this case, if the value is an
immediate, non-complex term, we can set it directly. Otherwise, we use the
device's `set` function to set the value.

<a name="default_module-0"></a>

### default_module/0 * ###

`default_module() -> any()`

The default device is the identity device, which simply returns the
value associated with any key as it exists in its Erlang map. It should also
implement the `set` key, which returns a `Message3` with the values changed
according to the `Message2` passed to it.

<a name="device_set-4"></a>

### device_set/4 * ###

`device_set(Msg, Key, Value, Opts) -> any()`

Call the device's `set` function.

<a name="device_set-5"></a>

### device_set/5 * ###

`device_set(Msg, Key, Value, Mode, Opts) -> any()`

<a name="do_resolve_many-2"></a>

### do_resolve_many/2 * ###

`do_resolve_many(MsgList, Opts) -> any()`

<a name="ensure_message_loaded-2"></a>

### ensure_message_loaded/2 * ###

`ensure_message_loaded(MsgID, Opts) -> any()`

Ensure that a message is loaded from the cache if it is an ID, or
a link, such that it is ready for execution.

<a name="error_execution-5"></a>

### error_execution/5 * ###

`error_execution(ExecGroup, Msg2, Whence, X4, Opts) -> any()`

Handle an error in a device call.

<a name="error_infinite-3"></a>

### error_infinite/3 * ###

`error_infinite(Msg1, Msg2, Opts) -> any()`

Catch all return if we are in an infinite loop.

<a name="error_invalid_intermediate_status-5"></a>

### error_invalid_intermediate_status/5 * ###

`error_invalid_intermediate_status(Msg1, Msg2, Msg3, RemainingPath, Opts) -> any()`

<a name="error_invalid_message-3"></a>

### error_invalid_message/3 * ###

`error_invalid_message(Msg1, Msg2, Opts) -> any()`

Catch all return if the message is invalid.

<a name="find_exported_function-5"></a>

### find_exported_function/5 ###

`find_exported_function(Msg, Dev, Key, MaxArity, Opts) -> any()`

Find the function with the highest arity that has the given name, if it
exists.

If the device is a module, we look for a function with the given name.

If the device is a map, we look for a key in the map. First we try to find
the key using its literal value. If that fails, we cast the key to an atom
and try again.

<a name="force_message-2"></a>

### force_message/2 ###

`force_message(X1, Opts) -> any()`

<a name="get-2"></a>

### get/2 ###

`get(Path, Msg) -> any()`

Shortcut for resolving a key in a message without its status if it is
`ok`. This makes it easier to write complex logic on top of messages while
maintaining a functional style.

Additionally, this function supports the `{as, Device, Msg}` syntax, which
allows the key to be resolved using another device to resolve the key,
while maintaining the tracability of the `HashPath` of the output message.

Returns the value of the key if it is found, otherwise returns the default
provided by the user, or `not_found` if no default is provided.

<a name="get-3"></a>

### get/3 ###

`get(Path, Msg, Opts) -> any()`

<a name="get-4"></a>

### get/4 ###

`get(Path, Msg, Default, Opts) -> any()`

<a name="get_first-2"></a>

### get_first/2 ###

`get_first(Paths, Opts) -> any()`

take a sequence of base messages and paths, then return the value of the
first message that can be resolved using a path.

<a name="get_first-3"></a>

### get_first/3 ###

`get_first(Msgs, Default, Opts) -> any()`

<a name="info-2"></a>

### info/2 ###

`info(Msg, Opts) -> any()`

Get the info map for a device, optionally giving it a message if the
device's info function is parameterized by one.

<a name="info-3"></a>

### info/3 * ###

`info(DevMod, Msg, Opts) -> any()`

<a name="info_handler_to_fun-4"></a>

### info_handler_to_fun/4 * ###

`info_handler_to_fun(Handler, Msg, Key, Opts) -> any()`

Parse a handler key given by a device's `info`.

<a name="internal_opts-1"></a>

### internal_opts/1 * ###

`internal_opts(Opts) -> any()`

The execution options that are used internally by this module
when calling itself.

<a name="is_exported-3"></a>

### is_exported/3 * ###

`is_exported(Info, Key, Opts) -> any()`

<a name="is_exported-4"></a>

### is_exported/4 ###

`is_exported(Msg, Dev, Key, Opts) -> any()`

Check if a device is guarding a key via its `exports` list. Defaults to
true if the device does not specify an `exports` list. The `info` function is
always exported, if it exists. Elements of the `exludes` list are not
exported. Note that we check for info _twice_ -- once when the device is
given but the info result is not, and once when the info result is given.
The reason for this is that `info/3` calls other functions that may need to
check if a key is exported, so we must avoid infinite loops. We must, however,
also return a consistent result in the case that only the info result is
given, so we check for it in both cases.

<a name="keys-1"></a>

### keys/1 ###

`keys(Msg) -> any()`

Shortcut to get the list of keys from a message.

<a name="keys-2"></a>

### keys/2 ###

`keys(Msg, Opts) -> any()`

<a name="keys-3"></a>

### keys/3 ###

`keys(Msg, Opts, X3) -> any()`

<a name="load_device-2"></a>

### load_device/2 ###

`load_device(Map, Opts) -> any()`

Load a device module from its name or a message ID.
Returns {ok, Executable} where Executable is the device module. On error,
a tuple of the form {error, Reason} is returned.

<a name="maybe_force_message-2"></a>

### maybe_force_message/2 * ###

`maybe_force_message(X1, Opts) -> any()`

Force the result of a device call into a message if the result is not
requested by the `Opts`. If the result is a literal, we wrap it in a message
and signal the location of the result inside. We also similarly handle ao-result
when the result is a single value and an explicit status code.

<a name="message_to_device-2"></a>

### message_to_device/2 ###

`message_to_device(Msg, Opts) -> any()`

Extract the device module from a message.

<a name="message_to_fun-3"></a>

### message_to_fun/3 ###

`message_to_fun(Msg, Key, Opts) -> any()`

Calculate the Erlang function that should be called to get a value for
a given key from a device.

This comes in 7 forms:
1. The message does not specify a device, so we use the default device.
2. The device has a `handler` key in its `Dev:info()` map, which is a
function that takes a key and returns a function to handle that key. We pass
the key as an additional argument to this function.
3. The device has a function of the name `Key`, which should be called
directly.
4. The device does not implement the key, but does have a default handler
for us to call. We pass it the key as an additional argument.
5. The device does not implement the key, and has no default handler. We use
the default device to handle the key.
Error: If the device is specified, but not loadable, we raise an error.

Returns {ok | add_key, Fun} where Fun is the function to call, and add_key
indicates that the key should be added to the start of the call's arguments.

<a name="normalize_key-1"></a>

### normalize_key/1 ###

`normalize_key(Key) -> any()`

Convert a key to a binary in normalized form.

<a name="normalize_key-2"></a>

### normalize_key/2 ###

`normalize_key(Key, Opts) -> any()`

<a name="normalize_keys-1"></a>

### normalize_keys/1 ###

`normalize_keys(Msg) -> any()`

Ensure that a message is processable by the AO-Core resolver: No lists.

<a name="normalize_keys-2"></a>

### normalize_keys/2 ###

`normalize_keys(Msg1, Opts) -> any()`

<a name="remove-2"></a>

### remove/2 ###

`remove(Msg, Key) -> any()`

Remove a key from a message, using its underlying device.

<a name="remove-3"></a>

### remove/3 ###

`remove(Msg, Key, Opts) -> any()`

<a name="resolve-2"></a>

### resolve/2 ###

`resolve(Path, Opts) -> any()`

Get the value of a message's key by running its associated device
function. Optionally, takes options that control the runtime environment.
This function returns the raw result of the device function call:
`{ok | error, NewMessage}.`
The resolver is composed of a series of discrete phases:
1: Normalization.
2: Cache lookup.
3: Validation check.
4: Persistent-resolver lookup.
5: Device lookup.
6: Execution.
7: Execution of the `step` hook.
8: Subresolution.
9: Cryptographic linking.
10: Result caching.
11: Notify waiters.
12: Fork worker.
13: Recurse or terminate.

<a name="resolve-3"></a>

### resolve/3 ###

`resolve(Msg1, Path, Opts) -> any()`

<a name="resolve_many-2"></a>

### resolve_many/2 ###

`resolve_many(ListMsg, Opts) -> any()`

Resolve a list of messages in sequence. Take the output of the first
message as the input for the next message. Once the last message is resolved,
return the result.
A `resolve_many` call with only a single ID will attempt to read the message
directly from the store. No execution is performed.

<a name="resolve_stage-4"></a>

### resolve_stage/4 * ###

`resolve_stage(X1, Link, Msg2, Opts) -> any()`

<a name="resolve_stage-5"></a>

### resolve_stage/5 * ###

`resolve_stage(X1, Msg1, Msg2, ExecName, Opts) -> any()`

<a name="resolve_stage-6"></a>

### resolve_stage/6 * ###

`resolve_stage(X1, Func, Msg1, Msg2, ExecName, Opts) -> any()`

<a name="set-3"></a>

### set/3 ###

`set(RawMsg1, RawMsg2, Opts) -> any()`

Shortcut for setting a key in the message using its underlying device.
Like the `get/3` function, this function honors the `error_strategy` option.
`set` works with maps and recursive paths while maintaining the appropriate
`HashPath` for each step.

<a name="set-4"></a>

### set/4 ###

`set(Msg1, Key, Value, Opts) -> any()`

<a name="subresolve-4"></a>

### subresolve/4 * ###

`subresolve(RawMsg1, DevID, ReqPath, Opts) -> any()`

Execute a sub-resolution.

<a name="truncate_args-2"></a>

### truncate_args/2 ###

`truncate_args(Fun, Args) -> any()`

Truncate the arguments of a function to the number of arguments it
actually takes.

<a name="verify_device_compatibility-2"></a>

### verify_device_compatibility/2 * ###

`verify_device_compatibility(Msg, Opts) -> any()`

Verify that a device is compatible with the current machine.


--- END OF FILE: docs/resources/source-code/hb_ao.md ---

--- START OF FILE: docs/resources/source-code/hb_app.md ---
# [Module hb_app.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_app.erl)




The main HyperBEAM application module.

__Behaviours:__ [`application`](application.md).

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#start-2">start/2</a></td><td></td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="start-2"></a>

### start/2 ###

`start(StartType, StartArgs) -> any()`

<a name="stop-1"></a>

### stop/1 ###

`stop(State) -> any()`


--- END OF FILE: docs/resources/source-code/hb_app.md ---

--- START OF FILE: docs/resources/source-code/hb_beamr_io.md ---
# [Module hb_beamr_io.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_beamr_io.erl)




Simple interface for memory management for Beamr instances.

<a name="description"></a>

## Description ##

It allows for reading and writing to memory, as well as allocating and
freeing memory by calling the WASM module's exported malloc and free
functions.

Unlike the majority of HyperBEAM modules, this module takes a defensive
approach to type checking, breaking from the conventional Erlang style,
such that failures are caught in the Erlang-side of functions rather than
in the C/WASM-side.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#do_read_string-3">do_read_string/3*</a></td><td></td></tr><tr><td valign="top"><a href="#free-2">free/2</a></td><td>Free space allocated in the Beamr instance's native memory via a
call to the exported free function from the WASM.</td></tr><tr><td valign="top"><a href="#malloc-2">malloc/2</a></td><td>Allocate space for (via an exported malloc function from the WASM) in
the Beamr instance's native memory.</td></tr><tr><td valign="top"><a href="#malloc_test-0">malloc_test/0*</a></td><td>Test allocating and freeing memory.</td></tr><tr><td valign="top"><a href="#read-3">read/3</a></td><td>Read a binary from the Beamr instance's native memory at a given offset
and of a given size.</td></tr><tr><td valign="top"><a href="#read_string-2">read_string/2</a></td><td>Simple helper function to read a string from the Beamr instance's native
memory at a given offset.</td></tr><tr><td valign="top"><a href="#read_string-3">read_string/3*</a></td><td></td></tr><tr><td valign="top"><a href="#read_test-0">read_test/0*</a></td><td>Test reading memory in and out of bounds.</td></tr><tr><td valign="top"><a href="#size-1">size/1</a></td><td>Get the size (in bytes) of the native memory allocated in the Beamr
instance.</td></tr><tr><td valign="top"><a href="#size_test-0">size_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#string_write_and_read_test-0">string_write_and_read_test/0*</a></td><td>Write and read strings to memory.</td></tr><tr><td valign="top"><a href="#write-3">write/3</a></td><td>Write a binary to the Beamr instance's native memory at a given offset.</td></tr><tr><td valign="top"><a href="#write_string-2">write_string/2</a></td><td>Simple helper function to allocate space for (via malloc) and write a
string to the Beamr instance's native memory.</td></tr><tr><td valign="top"><a href="#write_test-0">write_test/0*</a></td><td>Test writing memory in and out of bounds.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="do_read_string-3"></a>

### do_read_string/3 * ###

`do_read_string(WASM, Offset, ChunkSize) -> any()`

<a name="free-2"></a>

### free/2 ###

`free(WASM, Ptr) -> any()`

Free space allocated in the Beamr instance's native memory via a
call to the exported free function from the WASM.

<a name="malloc-2"></a>

### malloc/2 ###

`malloc(WASM, Size) -> any()`

Allocate space for (via an exported malloc function from the WASM) in
the Beamr instance's native memory.

<a name="malloc_test-0"></a>

### malloc_test/0 * ###

`malloc_test() -> any()`

Test allocating and freeing memory.

<a name="read-3"></a>

### read/3 ###

`read(WASM, Offset, Size) -> any()`

Read a binary from the Beamr instance's native memory at a given offset
and of a given size.

<a name="read_string-2"></a>

### read_string/2 ###

`read_string(Port, Offset) -> any()`

Simple helper function to read a string from the Beamr instance's native
memory at a given offset. Memory is read by default in chunks of 8 bytes,
but this can be overridden by passing a different chunk size. Strings are
assumed to be null-terminated.

<a name="read_string-3"></a>

### read_string/3 * ###

`read_string(WASM, Offset, ChunkSize) -> any()`

<a name="read_test-0"></a>

### read_test/0 * ###

`read_test() -> any()`

Test reading memory in and out of bounds.

<a name="size-1"></a>

### size/1 ###

`size(WASM) -> any()`

Get the size (in bytes) of the native memory allocated in the Beamr
instance. Note that WASM memory can never be reduced once granted to an
instance (although it can, of course, be reallocated _inside_ the
environment).

<a name="size_test-0"></a>

### size_test/0 * ###

`size_test() -> any()`

<a name="string_write_and_read_test-0"></a>

### string_write_and_read_test/0 * ###

`string_write_and_read_test() -> any()`

Write and read strings to memory.

<a name="write-3"></a>

### write/3 ###

`write(WASM, Offset, Data) -> any()`

Write a binary to the Beamr instance's native memory at a given offset.

<a name="write_string-2"></a>

### write_string/2 ###

`write_string(WASM, Data) -> any()`

Simple helper function to allocate space for (via malloc) and write a
string to the Beamr instance's native memory. This can be helpful for easily
pushing a string into the instance, such that the resulting pointer can be
passed to exported functions from the instance.
Assumes that the input is either an iolist or a binary, adding a null byte
to the end of the string.

<a name="write_test-0"></a>

### write_test/0 * ###

`write_test() -> any()`

Test writing memory in and out of bounds.


--- END OF FILE: docs/resources/source-code/hb_beamr_io.md ---

--- START OF FILE: docs/resources/source-code/hb_beamr.md ---
# [Module hb_beamr.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_beamr.erl)




BEAMR: A WAMR wrapper for BEAM.

<a name="description"></a>

## Description ##

Beamr is a library that allows you to run WASM modules in BEAM, using the
Webassembly Micro Runtime (WAMR) as its engine. Each WASM module is
executed using a Linked-In Driver (LID) that is loaded into BEAM. It is
designed with a focus on supporting long-running WASM executions that
interact with Erlang functions and processes easily.

Because each WASM module runs as an independent async worker, if you plan
to run many instances in parallel, you should be sure to configure the
BEAM to have enough async worker threads enabled (see `erl +A N` in the
Erlang manuals).

The core API is simple:

```

       start(WasmBinary) -> {ok, Port, Imports, Exports}
           Where:
               WasmBinary is the WASM binary to load.
               Port is the port to the LID.
               Imports is a list of tuples of the form {Module, Function,
                   Args, Signature}.
               Exports is a list of tuples of the form {Function, Args,
                   Signature}.
       stop(Port) -> ok
       call(Port, FunctionName, Args) -> {ok, Result}
           Where:
               FunctionName is the name of the function to call.
               Args is a list of Erlang terms (converted to WASM values by
                   BEAMR) that match the signature of the function.
               Result is a list of Erlang terms (converted from WASM values).
       call(Port, FunName, Args[, Import, State, Opts]) -> {ok, Res, NewState}
           Where:
               ImportFun is a function that will be called upon each import.
               ImportFun must have an arity of 2: Taking an arbitrary <code>state</code>
               term, and a map containing the <code>port</code>, <code>module</code>, <code>func</code>, <code>args</code>,<code>signature</code>, and the <code>options</code> map of the import.
               It must return a tuple of the form {ok, Response, NewState}.
       serialize(Port) -> {ok, Mem}
           Where:
               Port is the port to the LID.
               Mem is a binary representing the full WASM state.
       deserialize(Port, Mem) -> ok
           Where:
               Port is the port to the LID.
               Mem is a binary output of a previous <code>serialize/1</code> call.
```

BEAMR was designed for use in the HyperBEAM project, but is suitable for
deployment in other Erlang applications that need to run WASM modules. PRs
are welcome.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#benchmark_test-0">benchmark_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#call-3">call/3</a></td><td>Call a function in the WASM executor (see moduledoc for more details).</td></tr><tr><td valign="top"><a href="#call-4">call/4</a></td><td></td></tr><tr><td valign="top"><a href="#call-5">call/5</a></td><td></td></tr><tr><td valign="top"><a href="#call-6">call/6</a></td><td></td></tr><tr><td valign="top"><a href="#deserialize-2">deserialize/2</a></td><td>Deserialize a WASM state from a binary.</td></tr><tr><td valign="top"><a href="#dispatch_response-2">dispatch_response/2*</a></td><td>Check the type of an import response and dispatch it to a Beamr port.</td></tr><tr><td valign="top"><a href="#driver_loads_test-0">driver_loads_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#imported_function_test-0">imported_function_test/0*</a></td><td>Test that imported functions can be called from the WASM module.</td></tr><tr><td valign="top"><a href="#is_valid_arg_list-1">is_valid_arg_list/1*</a></td><td>Check that a list of arguments is valid for a WASM function call.</td></tr><tr><td valign="top"><a href="#load_driver-0">load_driver/0*</a></td><td>Load the driver for the WASM executor.</td></tr><tr><td valign="top"><a href="#monitor_call-4">monitor_call/4*</a></td><td>Synchonously monitor the WASM executor for a call result and any
imports that need to be handled.</td></tr><tr><td valign="top"><a href="#multiclient_test-0">multiclient_test/0*</a></td><td>Ensure that processes outside of the initial one can interact with
the WASM executor.</td></tr><tr><td valign="top"><a href="#serialize-1">serialize/1</a></td><td>Serialize the WASM state to a binary.</td></tr><tr><td valign="top"><a href="#simple_wasm_test-0">simple_wasm_test/0*</a></td><td>Test standalone <code>hb_beamr</code> correctly after loading a WASM module.</td></tr><tr><td valign="top"><a href="#start-1">start/1</a></td><td>Start a WASM executor context.</td></tr><tr><td valign="top"><a href="#start-2">start/2</a></td><td></td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td>Stop a WASM executor context.</td></tr><tr><td valign="top"><a href="#stub-3">stub/3</a></td><td>Stub import function for the WASM executor.</td></tr><tr><td valign="top"><a href="#wasm64_test-0">wasm64_test/0*</a></td><td>Test that WASM Memory64 modules load and execute correctly.</td></tr><tr><td valign="top"><a href="#wasm_send-2">wasm_send/2</a></td><td></td></tr><tr><td valign="top"><a href="#worker-2">worker/2*</a></td><td>A worker process that is responsible for handling a WASM instance.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="benchmark_test-0"></a>

### benchmark_test/0 * ###

`benchmark_test() -> any()`

<a name="call-3"></a>

### call/3 ###

`call(PID, FuncRef, Args) -> any()`

Call a function in the WASM executor (see moduledoc for more details).

<a name="call-4"></a>

### call/4 ###

`call(PID, FuncRef, Args, ImportFun) -> any()`

<a name="call-5"></a>

### call/5 ###

`call(PID, FuncRef, Args, ImportFun, StateMsg) -> any()`

<a name="call-6"></a>

### call/6 ###

`call(PID, FuncRef, Args, ImportFun, StateMsg, Opts) -> any()`

<a name="deserialize-2"></a>

### deserialize/2 ###

`deserialize(WASM, Bin) -> any()`

Deserialize a WASM state from a binary.

<a name="dispatch_response-2"></a>

### dispatch_response/2 * ###

`dispatch_response(WASM, Term) -> any()`

Check the type of an import response and dispatch it to a Beamr port.

<a name="driver_loads_test-0"></a>

### driver_loads_test/0 * ###

`driver_loads_test() -> any()`

<a name="imported_function_test-0"></a>

### imported_function_test/0 * ###

`imported_function_test() -> any()`

Test that imported functions can be called from the WASM module.

<a name="is_valid_arg_list-1"></a>

### is_valid_arg_list/1 * ###

`is_valid_arg_list(Args) -> any()`

Check that a list of arguments is valid for a WASM function call.

<a name="load_driver-0"></a>

### load_driver/0 * ###

`load_driver() -> any()`

Load the driver for the WASM executor.

<a name="monitor_call-4"></a>

### monitor_call/4 * ###

`monitor_call(WASM, ImportFun, StateMsg, Opts) -> any()`

Synchonously monitor the WASM executor for a call result and any
imports that need to be handled.

<a name="multiclient_test-0"></a>

### multiclient_test/0 * ###

`multiclient_test() -> any()`

Ensure that processes outside of the initial one can interact with
the WASM executor.

<a name="serialize-1"></a>

### serialize/1 ###

`serialize(WASM) -> any()`

Serialize the WASM state to a binary.

<a name="simple_wasm_test-0"></a>

### simple_wasm_test/0 * ###

`simple_wasm_test() -> any()`

Test standalone `hb_beamr` correctly after loading a WASM module.

<a name="start-1"></a>

### start/1 ###

`start(WasmBinary) -> any()`

Start a WASM executor context. Yields a port to the LID, and the
imports and exports of the WASM module. Optionally, specify a mode
(wasm or aot) to indicate the type of WASM module being loaded.

<a name="start-2"></a>

### start/2 ###

`start(WasmBinary, Mode) -> any()`

<a name="stop-1"></a>

### stop/1 ###

`stop(WASM) -> any()`

Stop a WASM executor context.

<a name="stub-3"></a>

### stub/3 ###

`stub(Msg1, Msg2, Opts) -> any()`

Stub import function for the WASM executor.

<a name="wasm64_test-0"></a>

### wasm64_test/0 * ###

`wasm64_test() -> any()`

Test that WASM Memory64 modules load and execute correctly.

<a name="wasm_send-2"></a>

### wasm_send/2 ###

`wasm_send(WASM, Message) -> any()`

<a name="worker-2"></a>

### worker/2 * ###

`worker(Port, Listener) -> any()`

A worker process that is responsible for handling a WASM instance.
It wraps the WASM port, handling inputs and outputs from the WASM module.
The last sender to the port is always the recipient of its messages, so
be careful to ensure that there is only one active sender to the port at
any time.


--- END OF FILE: docs/resources/source-code/hb_beamr.md ---

--- START OF FILE: docs/resources/source-code/hb_cache_control.md ---
# [Module hb_cache_control.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_cache_control.erl)




Cache control logic for the AO-Core resolver.

<a name="description"></a>

## Description ##
It derives cache settings
from request, response, execution-local node Opts, as well as the global
node Opts. It applies these settings when asked to maybe store/lookup in
response to a request.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#cache_binary_result_test-0">cache_binary_result_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#cache_message_result_test-0">cache_message_result_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#cache_source_to_cache_settings-2">cache_source_to_cache_settings/2*</a></td><td>Convert a cache source to a cache setting.</td></tr><tr><td valign="top"><a href="#derive_cache_settings-2">derive_cache_settings/2*</a></td><td>Derive cache settings from a series of option sources and the opts,
honoring precidence order.</td></tr><tr><td valign="top"><a href="#dispatch_cache_write-4">dispatch_cache_write/4*</a></td><td>Dispatch the cache write to a worker process if requested.</td></tr><tr><td valign="top"><a href="#empty_message_list_test-0">empty_message_list_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#exec_likely_faster_heuristic-3">exec_likely_faster_heuristic/3*</a></td><td>Determine whether we are likely to be faster looking up the result in
our cache (hoping we have it), or executing it directly.</td></tr><tr><td valign="top"><a href="#hashpath_ignore_prevents_storage_test-0">hashpath_ignore_prevents_storage_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#is_explicit_lookup-3">is_explicit_lookup/3*</a></td><td></td></tr><tr><td valign="top"><a href="#lookup-3">lookup/3*</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_lookup-3">maybe_lookup/3</a></td><td>Handles cache lookup, modulated by the caching options requested by
the user.</td></tr><tr><td valign="top"><a href="#maybe_set-3">maybe_set/3*</a></td><td>Takes a key and two maps, returning the first map with the key set to
the value of the second map _if_ the value is not undefined.</td></tr><tr><td valign="top"><a href="#maybe_store-4">maybe_store/4</a></td><td>Write a resulting M3 message to the cache if requested.</td></tr><tr><td valign="top"><a href="#message_source_cache_control_test-0">message_source_cache_control_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#message_without_cache_control_test-0">message_without_cache_control_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#msg_precidence_overrides_test-0">msg_precidence_overrides_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#msg_with_cc-1">msg_with_cc/1*</a></td><td></td></tr><tr><td valign="top"><a href="#multiple_directives_test-0">multiple_directives_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#necessary_messages_not_found_error-3">necessary_messages_not_found_error/3*</a></td><td>Generate a message to return when the necessary messages to execute a
cache lookup are not found in the cache.</td></tr><tr><td valign="top"><a href="#no_cache_directive_test-0">no_cache_directive_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#no_store_directive_test-0">no_store_directive_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#only_if_cached_directive_test-0">only_if_cached_directive_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#only_if_cached_not_found_error-3">only_if_cached_not_found_error/3*</a></td><td>Generate a message to return when <code>only_if_cached</code> was specified, and
we don't have a cached result.</td></tr><tr><td valign="top"><a href="#opts_override_message_settings_test-0">opts_override_message_settings_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#opts_source_cache_control_test-0">opts_source_cache_control_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#opts_with_cc-1">opts_with_cc/1*</a></td><td></td></tr><tr><td valign="top"><a href="#specifiers_to_cache_settings-1">specifiers_to_cache_settings/1*</a></td><td>Convert a cache control list as received via HTTP headers into a
normalized map of simply whether we should store and/or lookup the result.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="cache_binary_result_test-0"></a>

### cache_binary_result_test/0 * ###

`cache_binary_result_test() -> any()`

<a name="cache_message_result_test-0"></a>

### cache_message_result_test/0 * ###

`cache_message_result_test() -> any()`

<a name="cache_source_to_cache_settings-2"></a>

### cache_source_to_cache_settings/2 * ###

`cache_source_to_cache_settings(Msg, Opts) -> any()`

Convert a cache source to a cache setting. The setting _must_ always be
directly in the source, not an AO-Core-derivable value. The
`to_cache_control_map` function is used as the source of settings in all
cases, except where an `Opts` specifies that hashpaths should not be updated,
which leads to the result not being cached (as it may be stored with an
incorrect hashpath).

<a name="derive_cache_settings-2"></a>

### derive_cache_settings/2 * ###

`derive_cache_settings(SourceList, Opts) -> any()`

Derive cache settings from a series of option sources and the opts,
honoring precidence order. The Opts is used as the first source. Returns a
map with `store` and `lookup` keys, each of which is a boolean.

For example, if the last source has a `no_store`, the first expresses no
preference, but the Opts has `cache_control => [always]`, then the result
will contain a `store => true` entry.

<a name="dispatch_cache_write-4"></a>

### dispatch_cache_write/4 * ###

`dispatch_cache_write(Msg1, Msg2, Msg3, Opts) -> any()`

Dispatch the cache write to a worker process if requested.
Invoke the appropriate cache write function based on the type of the message.

<a name="empty_message_list_test-0"></a>

### empty_message_list_test/0 * ###

`empty_message_list_test() -> any()`

<a name="exec_likely_faster_heuristic-3"></a>

### exec_likely_faster_heuristic/3 * ###

`exec_likely_faster_heuristic(Msg1, Msg2, Opts) -> any()`

Determine whether we are likely to be faster looking up the result in
our cache (hoping we have it), or executing it directly.

<a name="hashpath_ignore_prevents_storage_test-0"></a>

### hashpath_ignore_prevents_storage_test/0 * ###

`hashpath_ignore_prevents_storage_test() -> any()`

<a name="is_explicit_lookup-3"></a>

### is_explicit_lookup/3 * ###

`is_explicit_lookup(Msg1, X2, Opts) -> any()`

<a name="lookup-3"></a>

### lookup/3 * ###

`lookup(Msg1, Msg2, Opts) -> any()`

<a name="maybe_lookup-3"></a>

### maybe_lookup/3 ###

`maybe_lookup(Msg1, Msg2, Opts) -> any()`

Handles cache lookup, modulated by the caching options requested by
the user. Honors the following `Opts` cache keys:
`only_if_cached`: If set and we do not find a result in the cache,
return an error with a `Cache-Status` of `miss` and
a 504 `Status`.
`no_cache`:       If set, the cached values are never used. Returns
`continue` to the caller.

<a name="maybe_set-3"></a>

### maybe_set/3 * ###

`maybe_set(Map1, Map2, Opts) -> any()`

Takes a key and two maps, returning the first map with the key set to
the value of the second map _if_ the value is not undefined.

<a name="maybe_store-4"></a>

### maybe_store/4 ###

`maybe_store(Msg1, Msg2, Msg3, Opts) -> any()`

Write a resulting M3 message to the cache if requested. The precedence
order of cache control sources is as follows:
1. The `Opts` map (letting the node operator have the final say).
2. The `Msg3` results message (granted by Msg1's device).
3. The `Msg2` message (the user's request).
Msg1 is not used, such that it can specify cache control information about
itself, without affecting its outputs.

<a name="message_source_cache_control_test-0"></a>

### message_source_cache_control_test/0 * ###

`message_source_cache_control_test() -> any()`

<a name="message_without_cache_control_test-0"></a>

### message_without_cache_control_test/0 * ###

`message_without_cache_control_test() -> any()`

<a name="msg_precidence_overrides_test-0"></a>

### msg_precidence_overrides_test/0 * ###

`msg_precidence_overrides_test() -> any()`

<a name="msg_with_cc-1"></a>

### msg_with_cc/1 * ###

`msg_with_cc(CC) -> any()`

<a name="multiple_directives_test-0"></a>

### multiple_directives_test/0 * ###

`multiple_directives_test() -> any()`

<a name="necessary_messages_not_found_error-3"></a>

### necessary_messages_not_found_error/3 * ###

`necessary_messages_not_found_error(Msg1, Msg2, Opts) -> any()`

Generate a message to return when the necessary messages to execute a
cache lookup are not found in the cache.

<a name="no_cache_directive_test-0"></a>

### no_cache_directive_test/0 * ###

`no_cache_directive_test() -> any()`

<a name="no_store_directive_test-0"></a>

### no_store_directive_test/0 * ###

`no_store_directive_test() -> any()`

<a name="only_if_cached_directive_test-0"></a>

### only_if_cached_directive_test/0 * ###

`only_if_cached_directive_test() -> any()`

<a name="only_if_cached_not_found_error-3"></a>

### only_if_cached_not_found_error/3 * ###

`only_if_cached_not_found_error(Msg1, Msg2, Opts) -> any()`

Generate a message to return when `only_if_cached` was specified, and
we don't have a cached result.

<a name="opts_override_message_settings_test-0"></a>

### opts_override_message_settings_test/0 * ###

`opts_override_message_settings_test() -> any()`

<a name="opts_source_cache_control_test-0"></a>

### opts_source_cache_control_test/0 * ###

`opts_source_cache_control_test() -> any()`

<a name="opts_with_cc-1"></a>

### opts_with_cc/1 * ###

`opts_with_cc(CC) -> any()`

<a name="specifiers_to_cache_settings-1"></a>

### specifiers_to_cache_settings/1 * ###

`specifiers_to_cache_settings(CCSpecifier) -> any()`

Convert a cache control list as received via HTTP headers into a
normalized map of simply whether we should store and/or lookup the result.


--- END OF FILE: docs/resources/source-code/hb_cache_control.md ---

--- START OF FILE: docs/resources/source-code/hb_cache_render.md ---
# [Module hb_cache_render.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_cache_render.erl)




A module that helps to render given Key graphs into the .dot files.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_arc-5">add_arc/5*</a></td><td>Add an arc to the graph.</td></tr><tr><td valign="top"><a href="#add_node-4">add_node/4*</a></td><td>Add a node to the graph.</td></tr><tr><td valign="top"><a href="#cache_path_to_dot-2">cache_path_to_dot/2</a></td><td>Generate a dot file from a cache path and options/store.</td></tr><tr><td valign="top"><a href="#cache_path_to_dot-3">cache_path_to_dot/3</a></td><td></td></tr><tr><td valign="top"><a href="#cache_path_to_graph-3">cache_path_to_graph/3</a></td><td>Main function to collect graph elements.</td></tr><tr><td valign="top"><a href="#cache_path_to_graph-4">cache_path_to_graph/4*</a></td><td></td></tr><tr><td valign="top"><a href="#collect_output-2">collect_output/2*</a></td><td>Helper function to collect output from port.</td></tr><tr><td valign="top"><a href="#dot_to_svg-1">dot_to_svg/1</a></td><td>Convert a dot graph to SVG format.</td></tr><tr><td valign="top"><a href="#extract_label-1">extract_label/1*</a></td><td>Extract a label from a path.</td></tr><tr><td valign="top"><a href="#get_graph_data-3">get_graph_data/3</a></td><td>Get graph data for the Three.js visualization.</td></tr><tr><td valign="top"><a href="#get_label-1">get_label/1*</a></td><td>Extract a readable label from a path.</td></tr><tr><td valign="top"><a href="#get_node_type-1">get_node_type/1*</a></td><td>Convert node color from hb_cache_render to node type for visualization.</td></tr><tr><td valign="top"><a href="#graph_to_dot-2">graph_to_dot/2*</a></td><td>Generate the DOT file from the graph.</td></tr><tr><td valign="top"><a href="#prepare_deeply_nested_complex_message-0">prepare_deeply_nested_complex_message/0</a></td><td></td></tr><tr><td valign="top"><a href="#prepare_signed_data-0">prepare_signed_data/0</a></td><td></td></tr><tr><td valign="top"><a href="#prepare_unsigned_data-0">prepare_unsigned_data/0</a></td><td></td></tr><tr><td valign="top"><a href="#process_composite_node-7">process_composite_node/7*</a></td><td>Process a composite (directory) node.</td></tr><tr><td valign="top"><a href="#process_simple_node-7">process_simple_node/7*</a></td><td>Process a simple (leaf) node.</td></tr><tr><td valign="top"><a href="#render-1">render/1</a></td><td>Render the given Key into svg.</td></tr><tr><td valign="top"><a href="#render-2">render/2</a></td><td></td></tr><tr><td valign="top"><a href="#test_signed-2">test_signed/2*</a></td><td></td></tr><tr><td valign="top"><a href="#test_unsigned-1">test_unsigned/1*</a></td><td></td></tr><tr><td valign="top"><a href="#traverse_store-5">traverse_store/5*</a></td><td>Traverse the store recursively to build the graph.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_arc-5"></a>

### add_arc/5 * ###

`add_arc(Graph, From, To, Label, Opts) -> any()`

Add an arc to the graph

<a name="add_node-4"></a>

### add_node/4 * ###

`add_node(Graph, ID, Color, Opts) -> any()`

Add a node to the graph

<a name="cache_path_to_dot-2"></a>

### cache_path_to_dot/2 ###

`cache_path_to_dot(ToRender, StoreOrOpts) -> any()`

Generate a dot file from a cache path and options/store

<a name="cache_path_to_dot-3"></a>

### cache_path_to_dot/3 ###

`cache_path_to_dot(ToRender, RenderOpts, StoreOrOpts) -> any()`

<a name="cache_path_to_graph-3"></a>

### cache_path_to_graph/3 ###

`cache_path_to_graph(ToRender, GraphOpts, StoreOrOpts) -> any()`

Main function to collect graph elements

<a name="cache_path_to_graph-4"></a>

### cache_path_to_graph/4 * ###

`cache_path_to_graph(InitPath, GraphOpts, Store, Opts) -> any()`

<a name="collect_output-2"></a>

### collect_output/2 * ###

`collect_output(Port, Acc) -> any()`

Helper function to collect output from port

<a name="dot_to_svg-1"></a>

### dot_to_svg/1 ###

`dot_to_svg(DotInput) -> any()`

Convert a dot graph to SVG format

<a name="extract_label-1"></a>

### extract_label/1 * ###

`extract_label(Path) -> any()`

Extract a label from a path

<a name="get_graph_data-3"></a>

### get_graph_data/3 ###

`get_graph_data(Base, MaxSize, Opts) -> any()`

Get graph data for the Three.js visualization

<a name="get_label-1"></a>

### get_label/1 * ###

`get_label(Path) -> any()`

Extract a readable label from a path

<a name="get_node_type-1"></a>

### get_node_type/1 * ###

`get_node_type(Color) -> any()`

Convert node color from hb_cache_render to node type for visualization

<a name="graph_to_dot-2"></a>

### graph_to_dot/2 * ###

`graph_to_dot(Graph, Opts) -> any()`

Generate the DOT file from the graph

<a name="prepare_deeply_nested_complex_message-0"></a>

### prepare_deeply_nested_complex_message/0 ###

`prepare_deeply_nested_complex_message() -> any()`

<a name="prepare_signed_data-0"></a>

### prepare_signed_data/0 ###

`prepare_signed_data() -> any()`

<a name="prepare_unsigned_data-0"></a>

### prepare_unsigned_data/0 ###

`prepare_unsigned_data() -> any()`

<a name="process_composite_node-7"></a>

### process_composite_node/7 * ###

`process_composite_node(Store, Key, Parent, ResolvedPath, JoinedPath, Graph, Opts) -> any()`

Process a composite (directory) node

<a name="process_simple_node-7"></a>

### process_simple_node/7 * ###

`process_simple_node(Store, Key, Parent, ResolvedPath, JoinedPath, Graph, Opts) -> any()`

Process a simple (leaf) node

<a name="render-1"></a>

### render/1 ###

`render(StoreOrOpts) -> any()`

Render the given Key into svg

<a name="render-2"></a>

### render/2 ###

`render(ToRender, StoreOrOpts) -> any()`

<a name="test_signed-2"></a>

### test_signed/2 * ###

`test_signed(Data, Wallet) -> any()`

<a name="test_unsigned-1"></a>

### test_unsigned/1 * ###

`test_unsigned(Data) -> any()`

<a name="traverse_store-5"></a>

### traverse_store/5 * ###

`traverse_store(Store, Path, Parent, Graph, Opts) -> any()`

Traverse the store recursively to build the graph


--- END OF FILE: docs/resources/source-code/hb_cache_render.md ---

--- START OF FILE: docs/resources/source-code/hb_cache.md ---
# [Module hb_cache.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_cache.erl)




A cache of AO-Core protocol messages and compute results.

<a name="description"></a>

## Description ##

HyperBEAM stores all paths in key value stores, abstracted by the `hb_store`
module. Each store has its own storage backend, but each works with simple
key-value pairs. Each store can write binary keys at paths, and link between
paths.

There are three layers to HyperBEAMs internal data representation on-disk:

1. The raw binary data, written to the store at the hash of the content.
Storing binary paths in this way effectively deduplicates the data.
2. The hashpath-graph of all content, stored as a set of links between
hashpaths, their keys, and the data that underlies them. This allows
all messages to share the same hashpath space, such that all requests
from users additively fill-in the hashpath space, minimizing duplicated
compute.
3. Messages, referrable by their IDs (committed or uncommitted). These are
stored as a set of links commitment IDs and the uncommitted message.

Before writing a message to the store, we convert it to Type-Annotated
Binary Messages (TABMs), such that each of the keys in the message is
either a map or a direct binary.

Nested keys are lazily loaded from the stores, such that large deeply
nested messages where only a small part of the data is actually used are
not loaded into memory unnecessarily. In order to ensure that a message is
loaded from the cache after a `read`, we can use the `ensure_loaded/1` and
`ensure_all_loaded/1` functions. Ensure loaded will load the exact value
that has been requested, while ensure all loaded will load the entire
structure of the message into memory.

Lazily loadable `links` are expressed as a tuple of the following form:
`{link, ID, LinkOpts}`, where `ID` is the path to the data in the store,
and `LinkOpts` is a map of suggested options to use when loading the data.
In particular, this module ensures to stash the `store` option in `LinkOpts`,
such that the `read` function can use the correct store without having to
search unnecessarily. By providing an `Opts` argument to `ensure_loaded` or
`ensure_all_loaded`, the caller can specify additional options to use when
loading the data -- overriding the suggested options in the link.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#cache_suite_test_-0">cache_suite_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#calculate_all_ids-2">calculate_all_ids/2*</a></td><td>Calculate the IDs for a message.</td></tr><tr><td valign="top"><a href="#commitment_path-2">commitment_path/2*</a></td><td>Generate the commitment path for a given base path.</td></tr><tr><td valign="top"><a href="#do_write_message-3">do_write_message/3*</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_all_loaded-1">ensure_all_loaded/1</a></td><td>Ensure that all of the components of a message (whether a map, list,
or immediate value) are recursively fully loaded from the stores into memory.</td></tr><tr><td valign="top"><a href="#ensure_all_loaded-2">ensure_all_loaded/2</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_loaded-1">ensure_loaded/1</a></td><td>Ensure that a value is loaded from the cache if it is an ID or a link.</td></tr><tr><td valign="top"><a href="#ensure_loaded-2">ensure_loaded/2</a></td><td></td></tr><tr><td valign="top"><a href="#link-3">link/3</a></td><td>Make a link from one path to another in the store.</td></tr><tr><td valign="top"><a href="#list-2">list/2</a></td><td>List all items under a given path.</td></tr><tr><td valign="top"><a href="#list_numbered-2">list_numbered/2</a></td><td>List all items in a directory, assuming they are numbered.</td></tr><tr><td valign="top"><a href="#prepare_commitments-2">prepare_commitments/2*</a></td><td>The <code>structured@1.0</code> encoder does not typically encode <code>commitments</code>,
subsequently, when we encounter a commitments message we prepare its contents
separately, then write each to the store.</td></tr><tr><td valign="top"><a href="#prepare_links-4">prepare_links/4*</a></td><td>Prepare a set of links from a listing of subpaths.</td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td>Read the message at a path.</td></tr><tr><td valign="top"><a href="#read_ao_types-4">read_ao_types/4*</a></td><td>Read and parse the ao-types for a given path if it is in the supplied
list of subpaths, returning a map of keys and their types.</td></tr><tr><td valign="top"><a href="#read_resolved-3">read_resolved/3</a></td><td>Read the output of a prior computation, given Msg1, Msg2, and some
options.</td></tr><tr><td valign="top"><a href="#run_test-0">run_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#store_read-3">store_read/3*</a></td><td>List all of the subpaths of a given path and return a map of keys and
links to the subpaths, including their types.</td></tr><tr><td valign="top"><a href="#test_deeply_nested_complex_message-1">test_deeply_nested_complex_message/1*</a></td><td>Test deeply nested item storage and retrieval.</td></tr><tr><td valign="top"><a href="#test_device_map_cannot_be_written_test-0">test_device_map_cannot_be_written_test/0*</a></td><td>Test that message whose device is <code>#{}</code> cannot be written.</td></tr><tr><td valign="top"><a href="#test_message_with_list-1">test_message_with_list/1*</a></td><td></td></tr><tr><td valign="top"><a href="#test_signed-1">test_signed/1</a></td><td></td></tr><tr><td valign="top"><a href="#test_signed-2">test_signed/2*</a></td><td></td></tr><tr><td valign="top"><a href="#test_store_ans104_message-1">test_store_ans104_message/1*</a></td><td></td></tr><tr><td valign="top"><a href="#test_store_binary-1">test_store_binary/1*</a></td><td></td></tr><tr><td valign="top"><a href="#test_store_simple_signed_message-1">test_store_simple_signed_message/1*</a></td><td>Test storing and retrieving a simple unsigned item.</td></tr><tr><td valign="top"><a href="#test_store_simple_unsigned_message-1">test_store_simple_unsigned_message/1*</a></td><td>Test storing and retrieving a simple unsigned item.</td></tr><tr><td valign="top"><a href="#test_store_unsigned_empty_message-1">test_store_unsigned_empty_message/1*</a></td><td></td></tr><tr><td valign="top"><a href="#test_store_unsigned_nested_empty_message-1">test_store_unsigned_nested_empty_message/1*</a></td><td></td></tr><tr><td valign="top"><a href="#test_unsigned-1">test_unsigned/1</a></td><td></td></tr><tr><td valign="top"><a href="#to_integer-1">to_integer/1*</a></td><td></td></tr><tr><td valign="top"><a href="#types_to_implicit-1">types_to_implicit/1*</a></td><td>Convert a map of ao-types to an implicit map of types.</td></tr><tr><td valign="top"><a href="#write-2">write/2</a></td><td>Write a message to the cache.</td></tr><tr><td valign="top"><a href="#write_binary-3">write_binary/3</a></td><td>Write a raw binary keys into the store and link it at a given hashpath.</td></tr><tr><td valign="top"><a href="#write_binary-4">write_binary/4*</a></td><td></td></tr><tr><td valign="top"><a href="#write_hashpath-2">write_hashpath/2</a></td><td>Write a hashpath and its message to the store and link it.</td></tr><tr><td valign="top"><a href="#write_hashpath-3">write_hashpath/3*</a></td><td></td></tr><tr><td valign="top"><a href="#write_key-6">write_key/6*</a></td><td>Write a single key for a message into the store.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="cache_suite_test_-0"></a>

### cache_suite_test_/0 * ###

`cache_suite_test_() -> any()`

<a name="calculate_all_ids-2"></a>

### calculate_all_ids/2 * ###

`calculate_all_ids(Bin, Opts) -> any()`

Calculate the IDs for a message.

<a name="commitment_path-2"></a>

### commitment_path/2 * ###

`commitment_path(Base, Opts) -> any()`

Generate the commitment path for a given base path.

<a name="do_write_message-3"></a>

### do_write_message/3 * ###

`do_write_message(Bin, Store, Opts) -> any()`

<a name="ensure_all_loaded-1"></a>

### ensure_all_loaded/1 ###

`ensure_all_loaded(Msg) -> any()`

Ensure that all of the components of a message (whether a map, list,
or immediate value) are recursively fully loaded from the stores into memory.
This is a catch-all function that is useful in situations where ensuring a
message contains no links is important, but it carries potentially extreme
performance costs.

<a name="ensure_all_loaded-2"></a>

### ensure_all_loaded/2 ###

`ensure_all_loaded(Link, Opts) -> any()`

<a name="ensure_loaded-1"></a>

### ensure_loaded/1 ###

`ensure_loaded(Msg) -> any()`

Ensure that a value is loaded from the cache if it is an ID or a link.
If it is not loadable we raise an error. If the value is a message, we will
load only the first `layer` of it: Representing all nested messages inside
the result as links. If the value has an associated `type` key in the extra
options, we apply it to the read value, 'lazily' recreating a `structured@1.0`
form.

<a name="ensure_loaded-2"></a>

### ensure_loaded/2 ###

`ensure_loaded(Lk, RawOpts) -> any()`

<a name="link-3"></a>

### link/3 ###

`link(Existing, New, Opts) -> any()`

Make a link from one path to another in the store.
Note: Argument order is `link(Src, Dst, Opts)`.

<a name="list-2"></a>

### list/2 ###

`list(Path, Opts) -> any()`

List all items under a given path.

<a name="list_numbered-2"></a>

### list_numbered/2 ###

`list_numbered(Path, Opts) -> any()`

List all items in a directory, assuming they are numbered.

<a name="prepare_commitments-2"></a>

### prepare_commitments/2 * ###

`prepare_commitments(RawCommitments, Opts) -> any()`

The `structured@1.0` encoder does not typically encode `commitments`,
subsequently, when we encounter a commitments message we prepare its contents
separately, then write each to the store.

<a name="prepare_links-4"></a>

### prepare_links/4 * ###

`prepare_links(RootPath, Subpaths, Store, Opts) -> any()`

Prepare a set of links from a listing of subpaths.

<a name="read-2"></a>

### read/2 ###

`read(Path, Opts) -> any()`

Read the message at a path. Returns in `structured@1.0` format: Either a
richly typed map or a direct binary.

<a name="read_ao_types-4"></a>

### read_ao_types/4 * ###

`read_ao_types(Path, Subpaths, Store, Opts) -> any()`

Read and parse the ao-types for a given path if it is in the supplied
list of subpaths, returning a map of keys and their types.

<a name="read_resolved-3"></a>

### read_resolved/3 ###

`read_resolved(MsgID1, MsgID2, Opts) -> any()`

Read the output of a prior computation, given Msg1, Msg2, and some
options.

<a name="run_test-0"></a>

### run_test/0 * ###

`run_test() -> any()`

<a name="store_read-3"></a>

### store_read/3 * ###

`store_read(Path, Store, Opts) -> any()`

List all of the subpaths of a given path and return a map of keys and
links to the subpaths, including their types.

<a name="test_deeply_nested_complex_message-1"></a>

### test_deeply_nested_complex_message/1 * ###

`test_deeply_nested_complex_message(Store) -> any()`

Test deeply nested item storage and retrieval

<a name="test_device_map_cannot_be_written_test-0"></a>

### test_device_map_cannot_be_written_test/0 * ###

`test_device_map_cannot_be_written_test() -> any()`

Test that message whose device is `#{}` cannot be written. If it were to
be written, it would cause an infinite loop.

<a name="test_message_with_list-1"></a>

### test_message_with_list/1 * ###

`test_message_with_list(Store) -> any()`

<a name="test_signed-1"></a>

### test_signed/1 ###

`test_signed(Data) -> any()`

<a name="test_signed-2"></a>

### test_signed/2 * ###

`test_signed(Data, Wallet) -> any()`

<a name="test_store_ans104_message-1"></a>

### test_store_ans104_message/1 * ###

`test_store_ans104_message(Store) -> any()`

<a name="test_store_binary-1"></a>

### test_store_binary/1 * ###

`test_store_binary(Store) -> any()`

<a name="test_store_simple_signed_message-1"></a>

### test_store_simple_signed_message/1 * ###

`test_store_simple_signed_message(Store) -> any()`

Test storing and retrieving a simple unsigned item

<a name="test_store_simple_unsigned_message-1"></a>

### test_store_simple_unsigned_message/1 * ###

`test_store_simple_unsigned_message(Store) -> any()`

Test storing and retrieving a simple unsigned item

<a name="test_store_unsigned_empty_message-1"></a>

### test_store_unsigned_empty_message/1 * ###

`test_store_unsigned_empty_message(Store) -> any()`

<a name="test_store_unsigned_nested_empty_message-1"></a>

### test_store_unsigned_nested_empty_message/1 * ###

`test_store_unsigned_nested_empty_message(Store) -> any()`

<a name="test_unsigned-1"></a>

### test_unsigned/1 ###

`test_unsigned(Data) -> any()`

<a name="to_integer-1"></a>

### to_integer/1 * ###

`to_integer(Value) -> any()`

<a name="types_to_implicit-1"></a>

### types_to_implicit/1 * ###

`types_to_implicit(Types) -> any()`

Convert a map of ao-types to an implicit map of types.

<a name="write-2"></a>

### write/2 ###

`write(RawMsg, Opts) -> any()`

Write a message to the cache. For raw binaries, we write the data at
the hashpath of the data (by default the SHA2-256 hash of the data). We link
the unattended ID's hashpath for the keys (including `/commitments`) on the
message to the underlying data and recurse. We then link each commitment ID
to the uncommitted message, such that any of the committed or uncommitted IDs
can be read, and once in memory all of the commitments are available. For
deep messages, the commitments will also be read, such that the ID of the
outer message (which does not include its commitments) will be built upon
the commitments of the inner messages. We do not, however, store the IDs from
commitments on signed _inner_ messages. We may wish to revisit this.

<a name="write_binary-3"></a>

### write_binary/3 ###

`write_binary(Hashpath, Bin, Opts) -> any()`

Write a raw binary keys into the store and link it at a given hashpath.

<a name="write_binary-4"></a>

### write_binary/4 * ###

`write_binary(Hashpath, Bin, Store, Opts) -> any()`

<a name="write_hashpath-2"></a>

### write_hashpath/2 ###

`write_hashpath(Msg, Opts) -> any()`

Write a hashpath and its message to the store and link it.

<a name="write_hashpath-3"></a>

### write_hashpath/3 * ###

`write_hashpath(HP, Msg, Opts) -> any()`

<a name="write_key-6"></a>

### write_key/6 * ###

`write_key(Base, Key, HPAlg, RawCommitments, Store, Opts) -> any()`

Write a single key for a message into the store.


--- END OF FILE: docs/resources/source-code/hb_cache.md ---

--- START OF FILE: docs/resources/source-code/hb_client.md ---
# [Module hb_client.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_client.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_route-3">add_route/3</a></td><td></td></tr><tr><td valign="top"><a href="#arweave_timestamp-0">arweave_timestamp/0</a></td><td>Grab the latest block information from the Arweave gateway node.</td></tr><tr><td valign="top"><a href="#prefix_keys-3">prefix_keys/3*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve-4">resolve/4</a></td><td>Resolve a message pair on a remote node.</td></tr><tr><td valign="top"><a href="#routes-2">routes/2</a></td><td></td></tr><tr><td valign="top"><a href="#upload-2">upload/2</a></td><td>Upload a data item to the bundler node.</td></tr><tr><td valign="top"><a href="#upload-3">upload/3</a></td><td></td></tr><tr><td valign="top"><a href="#upload_empty_message_test-0">upload_empty_message_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#upload_empty_raw_ans104_test-0">upload_empty_raw_ans104_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#upload_raw_ans104_test-0">upload_raw_ans104_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#upload_raw_ans104_with_anchor_test-0">upload_raw_ans104_with_anchor_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#upload_single_layer_message_test-0">upload_single_layer_message_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_route-3"></a>

### add_route/3 ###

`add_route(Node, Route, Opts) -> any()`

<a name="arweave_timestamp-0"></a>

### arweave_timestamp/0 ###

`arweave_timestamp() -> any()`

Grab the latest block information from the Arweave gateway node.

<a name="prefix_keys-3"></a>

### prefix_keys/3 * ###

`prefix_keys(Prefix, Message, Opts) -> any()`

<a name="resolve-4"></a>

### resolve/4 ###

`resolve(Node, Msg1, Msg2, Opts) -> any()`

Resolve a message pair on a remote node.
The message pair is first transformed into a singleton request, by
prefixing the keys in both messages for the path segment that they relate to,
and then adjusting the "Path" field from the second message.

<a name="routes-2"></a>

### routes/2 ###

`routes(Node, Opts) -> any()`

<a name="upload-2"></a>

### upload/2 ###

`upload(Msg, Opts) -> any()`

Upload a data item to the bundler node.
Note: Uploads once per commitment device. Callers should filter the
commitments to only include the ones they are interested in, if this is not
the desired behavior.

<a name="upload-3"></a>

### upload/3 ###

`upload(Msg, Opts, X3) -> any()`

<a name="upload_empty_message_test-0"></a>

### upload_empty_message_test/0 * ###

`upload_empty_message_test() -> any()`

<a name="upload_empty_raw_ans104_test-0"></a>

### upload_empty_raw_ans104_test/0 * ###

`upload_empty_raw_ans104_test() -> any()`

<a name="upload_raw_ans104_test-0"></a>

### upload_raw_ans104_test/0 * ###

`upload_raw_ans104_test() -> any()`

<a name="upload_raw_ans104_with_anchor_test-0"></a>

### upload_raw_ans104_with_anchor_test/0 * ###

`upload_raw_ans104_with_anchor_test() -> any()`

<a name="upload_single_layer_message_test-0"></a>

### upload_single_layer_message_test/0 * ###

`upload_single_layer_message_test() -> any()`


--- END OF FILE: docs/resources/source-code/hb_client.md ---

--- START OF FILE: docs/resources/source-code/hb_crypto.md ---
# [Module hb_crypto.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_crypto.erl)




Implements the cryptographic functions and wraps the primitives
used in HyperBEAM.

<a name="description"></a>

## Description ##

Abstracted such that this (extremely!) dangerous code
can be carefully managed.

HyperBEAM currently implements two hashpath algorithms:

* `sha-256-chain`: A simple chained SHA-256 hash.

* `accumulate-256`: A SHA-256 hash that chains the given IDs and accumulates
their values into a single commitment.

The accumulate algorithm is experimental and at this point only exists to
allow us to test multiple HashPath algorithms in HyperBEAM.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#accumulate-1">accumulate/1</a></td><td>Accumulate two IDs, or a list of IDs, into a single commitment.</td></tr><tr><td valign="top"><a href="#accumulate-2">accumulate/2</a></td><td></td></tr><tr><td valign="top"><a href="#count_zeroes-1">count_zeroes/1*</a></td><td>Count the number of leading zeroes in a bitstring.</td></tr><tr><td valign="top"><a href="#sha256-1">sha256/1</a></td><td>Wrap Erlang's <code>crypto:hash/2</code> to provide a standard interface.</td></tr><tr><td valign="top"><a href="#sha256_chain-2">sha256_chain/2</a></td><td>Add a new ID to the end of a SHA-256 hash chain.</td></tr><tr><td valign="top"><a href="#sha256_chain_test-0">sha256_chain_test/0*</a></td><td>Check that <code>sha-256-chain</code> correctly produces a hash matching
the machine's OpenSSL lib's output.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="accumulate-1"></a>

### accumulate/1 ###

`accumulate(IDs) -> any()`

Accumulate two IDs, or a list of IDs, into a single commitment. This
function requires that the IDs given are already cryptographically-secure,
256-bit values. No further cryptographic operations are performed upon the
values, they are simply added together.

This is useful in situations where the ordering of the IDs is not important,
or explicitly detrimental to the utility of the final commitment. No ordering
information is preserved in the final commitment.

<a name="accumulate-2"></a>

### accumulate/2 ###

`accumulate(ID1, ID2) -> any()`

<a name="count_zeroes-1"></a>

### count_zeroes/1 * ###

`count_zeroes(X1) -> any()`

Count the number of leading zeroes in a bitstring.

<a name="sha256-1"></a>

### sha256/1 ###

`sha256(Data) -> any()`

Wrap Erlang's `crypto:hash/2` to provide a standard interface.
Under-the-hood, this uses OpenSSL.

<a name="sha256_chain-2"></a>

### sha256_chain/2 ###

`sha256_chain(ID1, ID2) -> any()`

Add a new ID to the end of a SHA-256 hash chain.

<a name="sha256_chain_test-0"></a>

### sha256_chain_test/0 * ###

`sha256_chain_test() -> any()`

Check that `sha-256-chain` correctly produces a hash matching
the machine's OpenSSL lib's output. Further (in case of a bug in our
or Erlang's usage of OpenSSL), check that the output has at least has
a high level of entropy.


--- END OF FILE: docs/resources/source-code/hb_crypto.md ---

--- START OF FILE: docs/resources/source-code/hb_debugger.md ---
# [Module hb_debugger.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_debugger.erl)




A module that provides bootstrapping interfaces for external debuggers
to connect to HyperBEAM.

<a name="description"></a>

## Description ##

The simplest way to utilize an external graphical debugger is to use the
`erlang-ls` extension for VS Code, Emacs, or other Language Server Protocol
(LSP) compatible editors. This repository contains a `launch.json`
configuration file for VS Code that can be used to spawn a new HyperBEAM,
attach the debugger to it, and execute the specified `Module:Function(Args)`.
Additionally, the node can be started with `rebar3 debugging` in order to
allow access to the console while also allowing the debugger to attach.

Boot time is approximately 10 seconds.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#await_breakpoint-0">await_breakpoint/0</a></td><td>Await a new breakpoint being set by the debugger.</td></tr><tr><td valign="top"><a href="#await_breakpoint-1">await_breakpoint/1*</a></td><td></td></tr><tr><td valign="top"><a href="#await_debugger-0">await_debugger/0*</a></td><td>Await a debugger to be attached to the node.</td></tr><tr><td valign="top"><a href="#await_debugger-1">await_debugger/1*</a></td><td></td></tr><tr><td valign="top"><a href="#interpret-1">interpret/1*</a></td><td>Attempt to interpret a specified module to load it into the debugger.</td></tr><tr><td valign="top"><a href="#interpret_modules-1">interpret_modules/1*</a></td><td>Interpret modules from a list of atom prefixes.</td></tr><tr><td valign="top"><a href="#is_debugging_node_connected-0">is_debugging_node_connected/0*</a></td><td>Is another Distributed Erlang node connected to us?.</td></tr><tr><td valign="top"><a href="#start-0">start/0</a></td><td></td></tr><tr><td valign="top"><a href="#start_and_break-2">start_and_break/2</a></td><td>A bootstrapping function to wait for an external debugger to be attached,
then add a breakpoint on the specified <code>Module:Function(Args)</code>, then call it.</td></tr><tr><td valign="top"><a href="#start_and_break-3">start_and_break/3</a></td><td></td></tr><tr><td valign="top"><a href="#start_and_break-4">start_and_break/4</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="await_breakpoint-0"></a>

### await_breakpoint/0 ###

`await_breakpoint() -> any()`

Await a new breakpoint being set by the debugger.

<a name="await_breakpoint-1"></a>

### await_breakpoint/1 * ###

`await_breakpoint(N) -> any()`

<a name="await_debugger-0"></a>

### await_debugger/0 * ###

`await_debugger() -> any()`

Await a debugger to be attached to the node.

<a name="await_debugger-1"></a>

### await_debugger/1 * ###

`await_debugger(N) -> any()`

<a name="interpret-1"></a>

### interpret/1 * ###

`interpret(Module) -> any()`

Attempt to interpret a specified module to load it into the debugger.
`int:i/1` seems to have an issue that will cause it to fail sporadically
with `error:undef` on some modules. This error appears not to be catchable
through the normal means. Subsequently, we attempt the load in a separate
process and wait for it to complete. If we do not receive a response in a
reasonable amount of time, we assume that the module failed to load and
return `false`.

<a name="interpret_modules-1"></a>

### interpret_modules/1 * ###

`interpret_modules(Prefixes) -> any()`

Interpret modules from a list of atom prefixes.

<a name="is_debugging_node_connected-0"></a>

### is_debugging_node_connected/0 * ###

`is_debugging_node_connected() -> any()`

Is another Distributed Erlang node connected to us?

<a name="start-0"></a>

### start/0 ###

`start() -> any()`

<a name="start_and_break-2"></a>

### start_and_break/2 ###

`start_and_break(Module, Function) -> any()`

A bootstrapping function to wait for an external debugger to be attached,
then add a breakpoint on the specified `Module:Function(Args)`, then call it.

<a name="start_and_break-3"></a>

### start_and_break/3 ###

`start_and_break(Module, Function, Args) -> any()`

<a name="start_and_break-4"></a>

### start_and_break/4 ###

`start_and_break(Module, Function, Args, DebuggerScope) -> any()`


--- END OF FILE: docs/resources/source-code/hb_debugger.md ---

--- START OF FILE: docs/resources/source-code/hb_escape.md ---
# [Module hb_escape.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_escape.erl)




Escape and unescape mixed case values for use in HTTP headers.

<a name="description"></a>

## Description ##
This is necessary for encodings of AO-Core messages for transmission in
HTTP/2 and HTTP/3, because uppercase header keys are explicitly disallowed.
While most map keys in HyperBEAM are normalized to lowercase, IDs are not.
Subsequently, we encode all header keys to lowercase %-encoded URI-style
strings because transmission.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#decode-1">decode/1</a></td><td>Decode a URI-encoded string back to a binary.</td></tr><tr><td valign="top"><a href="#decode_keys-2">decode_keys/2</a></td><td>Return a message with all of its keys decoded.</td></tr><tr><td valign="top"><a href="#encode-1">encode/1</a></td><td>Encode a binary as a URI-encoded string.</td></tr><tr><td valign="top"><a href="#encode_keys-2">encode_keys/2</a></td><td>URI encode keys in the base layer of a message.</td></tr><tr><td valign="top"><a href="#escape_byte-1">escape_byte/1*</a></td><td>Escape a single byte as a URI-encoded string.</td></tr><tr><td valign="top"><a href="#escape_unescape_identity_test-0">escape_unescape_identity_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#escape_unescape_special_chars_test-0">escape_unescape_special_chars_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#hex_digit-1">hex_digit/1*</a></td><td></td></tr><tr><td valign="top"><a href="#hex_value-1">hex_value/1*</a></td><td></td></tr><tr><td valign="top"><a href="#percent_escape-1">percent_escape/1*</a></td><td>Escape a list of characters as a URI-encoded string.</td></tr><tr><td valign="top"><a href="#percent_unescape-1">percent_unescape/1*</a></td><td>Unescape a URI-encoded string.</td></tr><tr><td valign="top"><a href="#unescape_specific_test-0">unescape_specific_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#uppercase_test-0">uppercase_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="decode-1"></a>

### decode/1 ###

`decode(Bin) -> any()`

Decode a URI-encoded string back to a binary.

<a name="decode_keys-2"></a>

### decode_keys/2 ###

`decode_keys(Msg, Opts) -> any()`

Return a message with all of its keys decoded.

<a name="encode-1"></a>

### encode/1 ###

`encode(Bin) -> any()`

Encode a binary as a URI-encoded string.

<a name="encode_keys-2"></a>

### encode_keys/2 ###

`encode_keys(Msg, Opts) -> any()`

URI encode keys in the base layer of a message. Does not recurse.

<a name="escape_byte-1"></a>

### escape_byte/1 * ###

`escape_byte(C) -> any()`

Escape a single byte as a URI-encoded string.

<a name="escape_unescape_identity_test-0"></a>

### escape_unescape_identity_test/0 * ###

`escape_unescape_identity_test() -> any()`

<a name="escape_unescape_special_chars_test-0"></a>

### escape_unescape_special_chars_test/0 * ###

`escape_unescape_special_chars_test() -> any()`

<a name="hex_digit-1"></a>

### hex_digit/1 * ###

`hex_digit(N) -> any()`

<a name="hex_value-1"></a>

### hex_value/1 * ###

`hex_value(C) -> any()`

<a name="percent_escape-1"></a>

### percent_escape/1 * ###

`percent_escape(Cs) -> any()`

Escape a list of characters as a URI-encoded string.

<a name="percent_unescape-1"></a>

### percent_unescape/1 * ###

`percent_unescape(Cs) -> any()`

Unescape a URI-encoded string.

<a name="unescape_specific_test-0"></a>

### unescape_specific_test/0 * ###

`unescape_specific_test() -> any()`

<a name="uppercase_test-0"></a>

### uppercase_test/0 * ###

`uppercase_test() -> any()`


--- END OF FILE: docs/resources/source-code/hb_escape.md ---

--- START OF FILE: docs/resources/source-code/hb_event.md ---
# [Module hb_event.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_event.erl)




Wrapper for incrementing prometheus counters.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#await_prometheus_started-0">await_prometheus_started/0*</a></td><td>Delay the event server until prometheus is started.</td></tr><tr><td valign="top"><a href="#counters-0">counters/0</a></td><td>Return a message containing the current counter values for all logged
HyperBEAM events.</td></tr><tr><td valign="top"><a href="#handle_events-0">handle_events/0*</a></td><td></td></tr><tr><td valign="top"><a href="#handle_tracer-3">handle_tracer/3*</a></td><td></td></tr><tr><td valign="top"><a href="#increment-3">increment/3</a></td><td>Increment the counter for the given topic and message.</td></tr><tr><td valign="top"><a href="#increment-4">increment/4</a></td><td></td></tr><tr><td valign="top"><a href="#log-1">log/1</a></td><td>Debugging log logging function.</td></tr><tr><td valign="top"><a href="#log-2">log/2</a></td><td></td></tr><tr><td valign="top"><a href="#log-3">log/3</a></td><td></td></tr><tr><td valign="top"><a href="#log-4">log/4</a></td><td></td></tr><tr><td valign="top"><a href="#log-5">log/5</a></td><td></td></tr><tr><td valign="top"><a href="#log-6">log/6</a></td><td></td></tr><tr><td valign="top"><a href="#parse_name-1">parse_name/1*</a></td><td></td></tr><tr><td valign="top"><a href="#raw_counters-0">raw_counters/0*</a></td><td></td></tr><tr><td valign="top"><a href="#server-0">server/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="await_prometheus_started-0"></a>

### await_prometheus_started/0 * ###

`await_prometheus_started() -> any()`

Delay the event server until prometheus is started.

<a name="counters-0"></a>

### counters/0 ###

`counters() -> any()`

Return a message containing the current counter values for all logged
HyperBEAM events. The result comes in a form as follows:
/GroupName/EventName -> Count
Where the `EventName` is derived from the value of the first term sent to the
`?event(...)` macros.

<a name="handle_events-0"></a>

### handle_events/0 * ###

`handle_events() -> any()`

<a name="handle_tracer-3"></a>

### handle_tracer/3 * ###

`handle_tracer(Topic, X, Opts) -> any()`

<a name="increment-3"></a>

### increment/3 ###

`increment(Topic, Message, Opts) -> any()`

Increment the counter for the given topic and message. Registers the
counter if it doesn't exist. If the topic is `global`, the message is ignored.
This means that events must specify a topic if they want to be counted,
filtering debug messages. Similarly, events with a topic that begins with
`debug` are ignored.

<a name="increment-4"></a>

### increment/4 ###

`increment(Topic, Message, Opts, Count) -> any()`

<a name="log-1"></a>

### log/1 ###

`log(X) -> any()`

Debugging log logging function. For now, it just prints to standard
error.

<a name="log-2"></a>

### log/2 ###

`log(Topic, X) -> any()`

<a name="log-3"></a>

### log/3 ###

`log(Topic, X, Mod) -> any()`

<a name="log-4"></a>

### log/4 ###

`log(Topic, X, Mod, Func) -> any()`

<a name="log-5"></a>

### log/5 ###

`log(Topic, X, Mod, Func, Line) -> any()`

<a name="log-6"></a>

### log/6 ###

`log(Topic, X, Mod, Func, Line, Opts) -> any()`

<a name="parse_name-1"></a>

### parse_name/1 * ###

`parse_name(Name) -> any()`

<a name="raw_counters-0"></a>

### raw_counters/0 * ###

`raw_counters() -> any()`

<a name="server-0"></a>

### server/0 * ###

`server() -> any()`


--- END OF FILE: docs/resources/source-code/hb_event.md ---

--- START OF FILE: docs/resources/source-code/hb_examples.md ---
# [Module hb_examples.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_examples.erl)




This module contains end-to-end tests for Hyperbeam, accessing through
the HTTP interface.

<a name="description"></a>

## Description ##
As well as testing the system, you can use these tests
as examples of how to interact with HyperBEAM nodes.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#create_schedule_aos2_test_disabled-0">create_schedule_aos2_test_disabled/0*</a></td><td></td></tr><tr><td valign="top"><a href="#paid_wasm-0">paid_wasm/0*</a></td><td></td></tr><tr><td valign="top"><a href="#paid_wasm_test_-0">paid_wasm_test_/0*</a></td><td>Gain signed WASM responses from a node and verify them.</td></tr><tr><td valign="top"><a href="#relay_with_payments_test-0">relay_with_payments_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#relay_with_payments_test_-0">relay_with_payments_test_/0*</a></td><td>Start a node running the simple pay meta device, and use it to relay
a message for a client.</td></tr><tr><td valign="top"><a href="#schedule-2">schedule/2*</a></td><td></td></tr><tr><td valign="top"><a href="#schedule-3">schedule/3*</a></td><td></td></tr><tr><td valign="top"><a href="#schedule-4">schedule/4*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="create_schedule_aos2_test_disabled-0"></a>

### create_schedule_aos2_test_disabled/0 * ###

`create_schedule_aos2_test_disabled() -> any()`

<a name="paid_wasm-0"></a>

### paid_wasm/0 * ###

`paid_wasm() -> any()`

<a name="paid_wasm_test_-0"></a>

### paid_wasm_test_/0 * ###

`paid_wasm_test_() -> any()`

Gain signed WASM responses from a node and verify them.
1. Start the client with a small balance.
2. Execute a simple WASM function on the host node.
3. Verify the response is correct and signed by the host node.
4. Get the balance of the client and verify it has been deducted.

<a name="relay_with_payments_test-0"></a>

### relay_with_payments_test/0 * ###

`relay_with_payments_test() -> any()`

<a name="relay_with_payments_test_-0"></a>

### relay_with_payments_test_/0 * ###

`relay_with_payments_test_() -> any()`

Start a node running the simple pay meta device, and use it to relay
a message for a client. We must ensure:
1. When the client has no balance, the relay fails.
2. The operator is able to topup for the client.
3. The client has the correct balance after the topup.
4. The relay succeeds when the client has enough balance.
5. The received message is signed by the host using http-sig and validates
correctly.

<a name="schedule-2"></a>

### schedule/2 * ###

`schedule(ProcMsg, Target) -> any()`

<a name="schedule-3"></a>

### schedule/3 * ###

`schedule(ProcMsg, Target, Wallet) -> any()`

<a name="schedule-4"></a>

### schedule/4 * ###

`schedule(ProcMsg, Target, Wallet, Node) -> any()`


--- END OF FILE: docs/resources/source-code/hb_examples.md ---

--- START OF FILE: docs/resources/source-code/hb_features.md ---
# [Module hb_features.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_features.erl)




A module that exports a list of feature flags that the node supports
using the `-ifdef` macro.

<a name="description"></a>

## Description ##
As a consequence, this module acts as a proxy of information between the
build system and the runtime execution environment.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#all-0">all/0</a></td><td>Returns a list of all feature flags that the node supports.</td></tr><tr><td valign="top"><a href="#enabled-1">enabled/1</a></td><td>Returns true if the feature flag is enabled.</td></tr><tr><td valign="top"><a href="#genesis_wasm-0">genesis_wasm/0</a></td><td></td></tr><tr><td valign="top"><a href="#http3-0">http3/0</a></td><td></td></tr><tr><td valign="top"><a href="#rocksdb-0">rocksdb/0</a></td><td></td></tr><tr><td valign="top"><a href="#test-0">test/0</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="all-0"></a>

### all/0 ###

`all() -> any()`

Returns a list of all feature flags that the node supports.

<a name="enabled-1"></a>

### enabled/1 ###

`enabled(Feature) -> any()`

Returns true if the feature flag is enabled.

<a name="genesis_wasm-0"></a>

### genesis_wasm/0 ###

`genesis_wasm() -> any()`

<a name="http3-0"></a>

### http3/0 ###

`http3() -> any()`

<a name="rocksdb-0"></a>

### rocksdb/0 ###

`rocksdb() -> any()`

<a name="test-0"></a>

### test/0 ###

`test() -> any()`


--- END OF FILE: docs/resources/source-code/hb_features.md ---

--- START OF FILE: docs/resources/source-code/hb_gateway_client.md ---
# [Module hb_gateway_client.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_gateway_client.erl)




Implementation of Arweave's GraphQL API to gain access to specific
items of data stored on the network.

<a name="description"></a>

## Description ##
This module must be used to get full HyperBEAM `structured@1.0` form messages
from data items stored on the network, as Arweave gateways do not presently
expose all necessary fields to retrieve this information outside of the
GraphQL API. When gateways integrate serving in `httpsig@1.0` form, this
module will be deprecated.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#ans104_no_data_item_test-0">ans104_no_data_item_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#ao_dataitem_test-0">ao_dataitem_test/0*</a></td><td>Test optimistic index.</td></tr><tr><td valign="top"><a href="#data-2">data/2</a></td><td>Get the data associated with a transaction by its ID, using the node's
Arweave <code>gateway</code> peers.</td></tr><tr><td valign="top"><a href="#decode_id_or_null-1">decode_id_or_null/1*</a></td><td></td></tr><tr><td valign="top"><a href="#decode_or_null-1">decode_or_null/1*</a></td><td></td></tr><tr><td valign="top"><a href="#item_spec-0">item_spec/0*</a></td><td>Gives the fields of a transaction that are needed to construct an
ANS-104 message.</td></tr><tr><td valign="top"><a href="#l1_transaction_test-0">l1_transaction_test/0*</a></td><td>Test l1 message from graphql.</td></tr><tr><td valign="top"><a href="#l2_dataitem_test-0">l2_dataitem_test/0*</a></td><td>Test l2 message from graphql.</td></tr><tr><td valign="top"><a href="#normalize_null-1">normalize_null/1*</a></td><td></td></tr><tr><td valign="top"><a href="#query-2">query/2*</a></td><td>Run a GraphQL request encoded as a binary.</td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td>Get a data item (including data and tags) by its ID, using the node's
GraphQL peers.</td></tr><tr><td valign="top"><a href="#result_to_message-2">result_to_message/2</a></td><td>Takes a GraphQL item node, matches it with the appropriate data from a
gateway, then returns <code>{ok, ParsedMsg}</code>.</td></tr><tr><td valign="top"><a href="#result_to_message-3">result_to_message/3*</a></td><td></td></tr><tr><td valign="top"><a href="#scheduler_location-2">scheduler_location/2</a></td><td>Find the location of the scheduler based on its ID, through GraphQL.</td></tr><tr><td valign="top"><a href="#scheduler_location_test-0">scheduler_location_test/0*</a></td><td>Test that we can get the scheduler location.</td></tr><tr><td valign="top"><a href="#subindex_to_tags-1">subindex_to_tags/1*</a></td><td>Takes a list of messages with <code>name</code> and <code>value</code> fields, and formats
them as a GraphQL <code>tags</code> argument.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="ans104_no_data_item_test-0"></a>

### ans104_no_data_item_test/0 * ###

`ans104_no_data_item_test() -> any()`

<a name="ao_dataitem_test-0"></a>

### ao_dataitem_test/0 * ###

`ao_dataitem_test() -> any()`

Test optimistic index

<a name="data-2"></a>

### data/2 ###

`data(ID, Opts) -> any()`

Get the data associated with a transaction by its ID, using the node's
Arweave `gateway` peers. The item is expected to be available in its
unmodified (by caches or other proxies) form at the following location:
https://<gateway>/raw/<id>
where `&lt;id&gt;` is the base64-url-encoded transaction ID.

<a name="decode_id_or_null-1"></a>

### decode_id_or_null/1 * ###

`decode_id_or_null(Bin) -> any()`

<a name="decode_or_null-1"></a>

### decode_or_null/1 * ###

`decode_or_null(Bin) -> any()`

<a name="item_spec-0"></a>

### item_spec/0 * ###

`item_spec() -> any()`

Gives the fields of a transaction that are needed to construct an
ANS-104 message.

<a name="l1_transaction_test-0"></a>

### l1_transaction_test/0 * ###

`l1_transaction_test() -> any()`

Test l1 message from graphql

<a name="l2_dataitem_test-0"></a>

### l2_dataitem_test/0 * ###

`l2_dataitem_test() -> any()`

Test l2 message from graphql

<a name="normalize_null-1"></a>

### normalize_null/1 * ###

`normalize_null(Bin) -> any()`

<a name="query-2"></a>

### query/2 * ###

`query(Query, Opts) -> any()`

Run a GraphQL request encoded as a binary. The node message may contain
a list of URLs to use, optionally as a tuple with an additional map of options
to use for the request.

<a name="read-2"></a>

### read/2 ###

`read(ID, Opts) -> any()`

Get a data item (including data and tags) by its ID, using the node's
GraphQL peers.
It uses the following GraphQL schema:
type Transaction {
id: ID!
anchor: String!
signature: String!
recipient: String!
owner: Owner { address: String! key: String! }!
fee: Amount!
quantity: Amount!
data: MetaData!
tags: [Tag { name: String! value: String! }!]!
}
type Amount {
winston: String!
ar: String!
}

<a name="result_to_message-2"></a>

### result_to_message/2 ###

`result_to_message(Item, Opts) -> any()`

Takes a GraphQL item node, matches it with the appropriate data from a
gateway, then returns `{ok, ParsedMsg}`.

<a name="result_to_message-3"></a>

### result_to_message/3 * ###

`result_to_message(ExpectedID, Item, Opts) -> any()`

<a name="scheduler_location-2"></a>

### scheduler_location/2 ###

`scheduler_location(Address, Opts) -> any()`

Find the location of the scheduler based on its ID, through GraphQL.

<a name="scheduler_location_test-0"></a>

### scheduler_location_test/0 * ###

`scheduler_location_test() -> any()`

Test that we can get the scheduler location.

<a name="subindex_to_tags-1"></a>

### subindex_to_tags/1 * ###

`subindex_to_tags(Subindex) -> any()`

Takes a list of messages with `name` and `value` fields, and formats
them as a GraphQL `tags` argument.


--- END OF FILE: docs/resources/source-code/hb_gateway_client.md ---

--- START OF FILE: docs/resources/source-code/hb_http_benchmark_tests.md ---
# [Module hb_http_benchmark_tests.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_http_benchmark_tests.erl)





--- END OF FILE: docs/resources/source-code/hb_http_benchmark_tests.md ---

--- START OF FILE: docs/resources/source-code/hb_http_client_sup.md ---
# [Module hb_http_client_sup.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_http_client_sup.erl)




The supervisor for the gun HTTP client wrapper.

__Behaviours:__ [`supervisor`](supervisor.md).

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#init-1">init/1</a></td><td></td></tr><tr><td valign="top"><a href="#start_link-1">start_link/1</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="init-1"></a>

### init/1 ###

`init(Opts) -> any()`

<a name="start_link-1"></a>

### start_link/1 ###

`start_link(Opts) -> any()`


--- END OF FILE: docs/resources/source-code/hb_http_client_sup.md ---

--- START OF FILE: docs/resources/source-code/hb_http_client.md ---
# [Module hb_http_client.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_http_client.erl)




A wrapper library for gun.

__Behaviours:__ [`gen_server`](gen_server.md).

<a name="description"></a>

## Description ##
This module originates from the Arweave
project, and has been modified for use in HyperBEAM.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#await_response-2">await_response/2*</a></td><td></td></tr><tr><td valign="top"><a href="#dec_prometheus_gauge-1">dec_prometheus_gauge/1*</a></td><td>Safe wrapper for prometheus_gauge:dec/2.</td></tr><tr><td valign="top"><a href="#download_metric-2">download_metric/2*</a></td><td></td></tr><tr><td valign="top"><a href="#get_status_class-1">get_status_class/1*</a></td><td>Return the HTTP status class label for cowboy_requests_total and
gun_requests_total metrics.</td></tr><tr><td valign="top"><a href="#gun_req-3">gun_req/3*</a></td><td></td></tr><tr><td valign="top"><a href="#handle_call-3">handle_call/3</a></td><td></td></tr><tr><td valign="top"><a href="#handle_cast-2">handle_cast/2</a></td><td></td></tr><tr><td valign="top"><a href="#handle_info-2">handle_info/2</a></td><td></td></tr><tr><td valign="top"><a href="#httpc_req-3">httpc_req/3*</a></td><td></td></tr><tr><td valign="top"><a href="#inc_prometheus_counter-3">inc_prometheus_counter/3*</a></td><td></td></tr><tr><td valign="top"><a href="#inc_prometheus_gauge-1">inc_prometheus_gauge/1*</a></td><td>Safe wrapper for prometheus_gauge:inc/2.</td></tr><tr><td valign="top"><a href="#init-1">init/1</a></td><td></td></tr><tr><td valign="top"><a href="#init_prometheus-1">init_prometheus/1*</a></td><td></td></tr><tr><td valign="top"><a href="#log-5">log/5*</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_invoke_monitor-2">maybe_invoke_monitor/2*</a></td><td>Invoke the HTTP monitor message with AO-Core, if it is set in the
node message key.</td></tr><tr><td valign="top"><a href="#method_to_bin-1">method_to_bin/1*</a></td><td></td></tr><tr><td valign="top"><a href="#open_connection-2">open_connection/2*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_peer-2">parse_peer/2*</a></td><td></td></tr><tr><td valign="top"><a href="#record_duration-2">record_duration/2*</a></td><td>Record the duration of the request in an async process.</td></tr><tr><td valign="top"><a href="#record_response_status-3">record_response_status/3*</a></td><td></td></tr><tr><td valign="top"><a href="#reply_error-2">reply_error/2*</a></td><td></td></tr><tr><td valign="top"><a href="#req-2">req/2</a></td><td></td></tr><tr><td valign="top"><a href="#req-3">req/3*</a></td><td></td></tr><tr><td valign="top"><a href="#request-3">request/3*</a></td><td></td></tr><tr><td valign="top"><a href="#start_link-1">start_link/1</a></td><td></td></tr><tr><td valign="top"><a href="#terminate-2">terminate/2</a></td><td></td></tr><tr><td valign="top"><a href="#upload_metric-1">upload_metric/1*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="await_response-2"></a>

### await_response/2 * ###

`await_response(Args, Opts) -> any()`

<a name="dec_prometheus_gauge-1"></a>

### dec_prometheus_gauge/1 * ###

`dec_prometheus_gauge(Name) -> any()`

Safe wrapper for prometheus_gauge:dec/2.

<a name="download_metric-2"></a>

### download_metric/2 * ###

`download_metric(Data, X2) -> any()`

<a name="get_status_class-1"></a>

### get_status_class/1 * ###

`get_status_class(Data) -> any()`

Return the HTTP status class label for cowboy_requests_total and
gun_requests_total metrics.

<a name="gun_req-3"></a>

### gun_req/3 * ###

`gun_req(Args, ReestablishedConnection, Opts) -> any()`

<a name="handle_call-3"></a>

### handle_call/3 ###

`handle_call(Request, From, State) -> any()`

<a name="handle_cast-2"></a>

### handle_cast/2 ###

`handle_cast(Cast, State) -> any()`

<a name="handle_info-2"></a>

### handle_info/2 ###

`handle_info(Message, State) -> any()`

<a name="httpc_req-3"></a>

### httpc_req/3 * ###

`httpc_req(Args, X2, Opts) -> any()`

<a name="inc_prometheus_counter-3"></a>

### inc_prometheus_counter/3 * ###

`inc_prometheus_counter(Name, Labels, Value) -> any()`

<a name="inc_prometheus_gauge-1"></a>

### inc_prometheus_gauge/1 * ###

`inc_prometheus_gauge(Name) -> any()`

Safe wrapper for prometheus_gauge:inc/2.

<a name="init-1"></a>

### init/1 ###

`init(Opts) -> any()`

<a name="init_prometheus-1"></a>

### init_prometheus/1 * ###

`init_prometheus(Opts) -> any()`

<a name="log-5"></a>

### log/5 * ###

`log(Type, Event, X3, Reason, Opts) -> any()`

<a name="maybe_invoke_monitor-2"></a>

### maybe_invoke_monitor/2 * ###

`maybe_invoke_monitor(Details, Opts) -> any()`

Invoke the HTTP monitor message with AO-Core, if it is set in the
node message key. We invoke the given message with the `body` set to a signed
version of the details. This allows node operators to configure their machine
to record duration statistics into customized data stores, computations, or
processes etc. Additionally, we include the `http_reference` value, if set in
the given `opts`.

We use `hb_ao:get` rather than `hb_opts:get`, as settings configured
by the `~router@1.0` route `opts` key are unable to generate atoms.

<a name="method_to_bin-1"></a>

### method_to_bin/1 * ###

`method_to_bin(X1) -> any()`

<a name="open_connection-2"></a>

### open_connection/2 * ###

`open_connection(X1, Opts) -> any()`

<a name="parse_peer-2"></a>

### parse_peer/2 * ###

`parse_peer(Peer, Opts) -> any()`

<a name="record_duration-2"></a>

### record_duration/2 * ###

`record_duration(Details, Opts) -> any()`

Record the duration of the request in an async process. We write the
data to prometheus if the application is enabled, as well as invoking the
`http_monitor` if appropriate.

<a name="record_response_status-3"></a>

### record_response_status/3 * ###

`record_response_status(Method, Path, Response) -> any()`

<a name="reply_error-2"></a>

### reply_error/2 * ###

`reply_error(PendingRequests, Reason) -> any()`

<a name="req-2"></a>

### req/2 ###

`req(Args, Opts) -> any()`

<a name="req-3"></a>

### req/3 * ###

`req(Args, ReestablishedConnection, Opts) -> any()`

<a name="request-3"></a>

### request/3 * ###

`request(PID, Args, Opts) -> any()`

<a name="start_link-1"></a>

### start_link/1 ###

`start_link(Opts) -> any()`

<a name="terminate-2"></a>

### terminate/2 ###

`terminate(Reason, State) -> any()`

<a name="upload_metric-1"></a>

### upload_metric/1 * ###

`upload_metric(X1) -> any()`


--- END OF FILE: docs/resources/source-code/hb_http_client.md ---

--- START OF FILE: docs/resources/source-code/hb_http_server.md ---
# [Module hb_http_server.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_http_server.erl)




A router that attaches a HTTP server to the AO-Core resolver.

<a name="description"></a>

## Description ##

Because AO-Core is built to speak in HTTP semantics, this module
only has to marshal the HTTP request into a message, and then
pass it to the AO-Core resolver.

`hb_http:reply/4` is used to respond to the client, handling the
process of converting a message back into an HTTP response.

The router uses an `Opts` message as its Cowboy initial state,
such that changing it on start of the router server allows for
the execution parameters of all downstream requests to be controlled.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#allowed_methods-2">allowed_methods/2</a></td><td>Return the list of allowed methods for the HTTP server.</td></tr><tr><td valign="top"><a href="#cors_reply-2">cors_reply/2*</a></td><td>Reply to CORS preflight requests.</td></tr><tr><td valign="top"><a href="#get_opts-0">get_opts/0</a></td><td>Get the node message for the current process.</td></tr><tr><td valign="top"><a href="#get_opts-1">get_opts/1</a></td><td></td></tr><tr><td valign="top"><a href="#handle_request-3">handle_request/3*</a></td><td>Handle all non-CORS preflight requests as AO-Core requests.</td></tr><tr><td valign="top"><a href="#http3_conn_sup_loop-0">http3_conn_sup_loop/0*</a></td><td></td></tr><tr><td valign="top"><a href="#init-2">init/2</a></td><td>Entrypoint for all HTTP requests.</td></tr><tr><td valign="top"><a href="#new_server-1">new_server/1*</a></td><td>Trigger the creation of a new HTTP server node.</td></tr><tr><td valign="top"><a href="#read_body-1">read_body/1*</a></td><td>Helper to grab the full body of a HTTP request, even if it's chunked.</td></tr><tr><td valign="top"><a href="#read_body-2">read_body/2*</a></td><td></td></tr><tr><td valign="top"><a href="#set_default_opts-1">set_default_opts/1</a></td><td>Apply the default node message to the given opts map.</td></tr><tr><td valign="top"><a href="#set_node_opts_test-0">set_node_opts_test/0*</a></td><td>Ensure that the <code>start</code> hook can be used to modify the node options.</td></tr><tr><td valign="top"><a href="#set_opts-1">set_opts/1</a></td><td>Merges the provided <code>Opts</code> with uncommitted values from <code>Request</code>,
preserves the http_server value, and updates node_history by prepending
the <code>Request</code>.</td></tr><tr><td valign="top"><a href="#set_opts-2">set_opts/2</a></td><td></td></tr><tr><td valign="top"><a href="#set_opts_test-0">set_opts_test/0*</a></td><td>Test the set_opts/2 function that merges request with options,
manages node history, and updates server state.</td></tr><tr><td valign="top"><a href="#set_proc_server_id-1">set_proc_server_id/1</a></td><td>Initialize the server ID for the current process.</td></tr><tr><td valign="top"><a href="#start-0">start/0</a></td><td>Starts the HTTP server.</td></tr><tr><td valign="top"><a href="#start-1">start/1</a></td><td></td></tr><tr><td valign="top"><a href="#start_http2-3">start_http2/3*</a></td><td></td></tr><tr><td valign="top"><a href="#start_http3-3">start_http3/3*</a></td><td></td></tr><tr><td valign="top"><a href="#start_node-0">start_node/0</a></td><td>Test that we can start the server, send a message, and get a response.</td></tr><tr><td valign="top"><a href="#start_node-1">start_node/1</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="allowed_methods-2"></a>

### allowed_methods/2 ###

`allowed_methods(Req, State) -> any()`

Return the list of allowed methods for the HTTP server.

<a name="cors_reply-2"></a>

### cors_reply/2 * ###

`cors_reply(Req, ServerID) -> any()`

Reply to CORS preflight requests.

<a name="get_opts-0"></a>

### get_opts/0 ###

`get_opts() -> any()`

Get the node message for the current process.

<a name="get_opts-1"></a>

### get_opts/1 ###

`get_opts(NodeMsg) -> any()`

<a name="handle_request-3"></a>

### handle_request/3 * ###

`handle_request(RawReq, Body, ServerID) -> any()`

Handle all non-CORS preflight requests as AO-Core requests. Execution
starts by parsing the HTTP request into HyerBEAM's message format, then
passing the message directly to `meta@1.0` which handles calling AO-Core in
the appropriate way.

<a name="http3_conn_sup_loop-0"></a>

### http3_conn_sup_loop/0 * ###

`http3_conn_sup_loop() -> any()`

<a name="init-2"></a>

### init/2 ###

`init(Req, ServerID) -> any()`

Entrypoint for all HTTP requests. Receives the Cowboy request option and
the server ID, which can be used to lookup the node message.

<a name="new_server-1"></a>

### new_server/1 * ###

`new_server(RawNodeMsg) -> any()`

Trigger the creation of a new HTTP server node. Accepts a `NodeMsg`
message, which is used to configure the server. This function executed the
`start` hook on the node, giving it the opportunity to modify the `NodeMsg`
before it is used to configure the server. The `start` hook expects gives and
expects the node message to be in the `body` key.

<a name="read_body-1"></a>

### read_body/1 * ###

`read_body(Req) -> any()`

Helper to grab the full body of a HTTP request, even if it's chunked.

<a name="read_body-2"></a>

### read_body/2 * ###

`read_body(Req0, Acc) -> any()`

<a name="set_default_opts-1"></a>

### set_default_opts/1 ###

`set_default_opts(Opts) -> any()`

Apply the default node message to the given opts map.

<a name="set_node_opts_test-0"></a>

### set_node_opts_test/0 * ###

`set_node_opts_test() -> any()`

Ensure that the `start` hook can be used to modify the node options. We
do this by creating a message with a device that has a `start` key. This
key takes the message's body (the anticipated node options) and returns a
modified version of that body, which will be used to configure the node. We
then check that the node options were modified as we expected.

<a name="set_opts-1"></a>

### set_opts/1 ###

`set_opts(Opts) -> any()`

Merges the provided `Opts` with uncommitted values from `Request`,
preserves the http_server value, and updates node_history by prepending
the `Request`. If a server reference exists, updates the Cowboy environment
variable 'node_msg' with the resulting options map.

<a name="set_opts-2"></a>

### set_opts/2 ###

`set_opts(Request, Opts) -> any()`

<a name="set_opts_test-0"></a>

### set_opts_test/0 * ###

`set_opts_test() -> any()`

Test the set_opts/2 function that merges request with options,
manages node history, and updates server state.

<a name="set_proc_server_id-1"></a>

### set_proc_server_id/1 ###

`set_proc_server_id(ServerID) -> any()`

Initialize the server ID for the current process.

<a name="start-0"></a>

### start/0 ###

`start() -> any()`

Starts the HTTP server. Optionally accepts an `Opts` message, which
is used as the source for server configuration settings, as well as the
`Opts` argument to use for all AO-Core resolution requests downstream.

<a name="start-1"></a>

### start/1 ###

`start(Opts) -> any()`

<a name="start_http2-3"></a>

### start_http2/3 * ###

`start_http2(ServerID, ProtoOpts, NodeMsg) -> any()`

<a name="start_http3-3"></a>

### start_http3/3 * ###

`start_http3(ServerID, ProtoOpts, NodeMsg) -> any()`

<a name="start_node-0"></a>

### start_node/0 ###

`start_node() -> any()`

Test that we can start the server, send a message, and get a response.

<a name="start_node-1"></a>

### start_node/1 ###

`start_node(Opts) -> any()`


--- END OF FILE: docs/resources/source-code/hb_http_server.md ---

--- START OF FILE: docs/resources/source-code/hb_http.md ---
# [Module hb_http.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_http.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#accept_to_codec-2">accept_to_codec/2</a></td><td>Calculate the codec name to use for a reply given its initiating Cowboy
request, the parsed TABM request, and the response message.</td></tr><tr><td valign="top"><a href="#add_cors_headers-3">add_cors_headers/3*</a></td><td>Add permissive CORS headers to a message, if the message has not already
specified CORS headers.</td></tr><tr><td valign="top"><a href="#allowed_status-2">allowed_status/2*</a></td><td>Check if a status is allowed, according to the configuration.</td></tr><tr><td valign="top"><a href="#ans104_wasm_test-0">ans104_wasm_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#codec_to_content_type-2">codec_to_content_type/2*</a></td><td>Call the <code>content-type</code> key on a message with the given codec, using
a fast-path for options that are not needed for this one-time lookup.</td></tr><tr><td valign="top"><a href="#cors_get_test-0">cors_get_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#default_codec-1">default_codec/1*</a></td><td>Return the default codec for the given options.</td></tr><tr><td valign="top"><a href="#empty_inbox-1">empty_inbox/1*</a></td><td>Empty the inbox of the current process for all messages with the given
reference.</td></tr><tr><td valign="top"><a href="#encode_reply-4">encode_reply/4*</a></td><td>Generate the headers and body for a HTTP response message.</td></tr><tr><td valign="top"><a href="#get-2">get/2</a></td><td>Gets a URL via HTTP and returns the resulting message in deserialized
form.</td></tr><tr><td valign="top"><a href="#get-3">get/3</a></td><td></td></tr><tr><td valign="top"><a href="#get_deep_signed_wasm_state_test-0">get_deep_signed_wasm_state_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#get_deep_unsigned_wasm_state_test-0">get_deep_unsigned_wasm_state_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#http_response_to_httpsig-4">http_response_to_httpsig/4*</a></td><td>Convert a HTTP response to a httpsig message.</td></tr><tr><td valign="top"><a href="#httpsig_to_tabm_singleton-3">httpsig_to_tabm_singleton/3*</a></td><td>HTTPSig messages are inherently mixed into the transport layer, so they
require special handling in order to be converted to a normalized message.</td></tr><tr><td valign="top"><a href="#index_request_test-0">index_request_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#index_test-0">index_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#message_to_request-2">message_to_request/2</a></td><td>Given a message, return the information needed to make the request.</td></tr><tr><td valign="top"><a href="#mime_to_codec-2">mime_to_codec/2*</a></td><td>Find a codec name from a mime-type.</td></tr><tr><td valign="top"><a href="#multirequest-5">multirequest/5*</a></td><td>Dispatch the same HTTP request to many nodes.</td></tr><tr><td valign="top"><a href="#multirequest_opt-5">multirequest_opt/5*</a></td><td>Get a value for a multirequest option from the config or message.</td></tr><tr><td valign="top"><a href="#multirequest_opts-3">multirequest_opts/3*</a></td><td>Get the multirequest options from the config or message.</td></tr><tr><td valign="top"><a href="#nested_ao_resolve_test-0">nested_ao_resolve_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#normalize_unsigned-3">normalize_unsigned/3*</a></td><td>Add the method and path to a message, if they are not already present.</td></tr><tr><td valign="top"><a href="#parallel_multirequest-8">parallel_multirequest/8*</a></td><td>Dispatch the same HTTP request to many nodes in parallel.</td></tr><tr><td valign="top"><a href="#parallel_responses-7">parallel_responses/7*</a></td><td>Collect the necessary number of responses, and stop workers if
configured to do so.</td></tr><tr><td valign="top"><a href="#post-3">post/3</a></td><td>Posts a message to a URL on a remote peer via HTTP.</td></tr><tr><td valign="top"><a href="#post-4">post/4</a></td><td></td></tr><tr><td valign="top"><a href="#prepare_request-6">prepare_request/6*</a></td><td>Turn a set of request arguments into a request message, formatted in the
preferred format.</td></tr><tr><td valign="top"><a href="#remove_unless_signed-3">remove_unless_signed/3*</a></td><td>Remove all keys from the message unless they are signed.</td></tr><tr><td valign="top"><a href="#reply-4">reply/4</a></td><td>Reply to the client's HTTP request with a message.</td></tr><tr><td valign="top"><a href="#reply-5">reply/5*</a></td><td></td></tr><tr><td valign="top"><a href="#req_to_tabm_singleton-3">req_to_tabm_singleton/3</a></td><td>Convert a cowboy request to a normalized message.</td></tr><tr><td valign="top"><a href="#request-2">request/2</a></td><td>Posts a binary to a URL on a remote peer via HTTP, returning the raw
binary body.</td></tr><tr><td valign="top"><a href="#request-4">request/4</a></td><td></td></tr><tr><td valign="top"><a href="#request-5">request/5</a></td><td></td></tr><tr><td valign="top"><a href="#route_to_request-3">route_to_request/3*</a></td><td>Parse a <code>dev_router:route</code> response and return a tuple of request
parameters.</td></tr><tr><td valign="top"><a href="#run_wasm_signed_test-0">run_wasm_signed_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#run_wasm_unsigned_test-0">run_wasm_unsigned_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#send_large_signed_request_test-0">send_large_signed_request_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#serial_multirequest-7">serial_multirequest/7*</a></td><td>Serially request a message, collecting responses until the required
number of responses have been gathered.</td></tr><tr><td valign="top"><a href="#simple_ao_resolve_signed_test-0">simple_ao_resolve_signed_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#simple_ao_resolve_unsigned_test-0">simple_ao_resolve_unsigned_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#start-0">start/0</a></td><td></td></tr><tr><td valign="top"><a href="#wasm_compute_request-3">wasm_compute_request/3*</a></td><td></td></tr><tr><td valign="top"><a href="#wasm_compute_request-4">wasm_compute_request/4*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="accept_to_codec-2"></a>

### accept_to_codec/2 ###

`accept_to_codec(TABMReq, Opts) -> any()`

Calculate the codec name to use for a reply given its initiating Cowboy
request, the parsed TABM request, and the response message. The precidence
order for finding the codec is:
1. The `accept-codec` field in the message
2. The `accept` field in the request headers
3. The default codec
Options can be specified in mime-type format (`application/*`) or in
AO device format (`device@1.0`).

<a name="add_cors_headers-3"></a>

### add_cors_headers/3 * ###

`add_cors_headers(Msg, ReqHdr, Opts) -> any()`

Add permissive CORS headers to a message, if the message has not already
specified CORS headers.

<a name="allowed_status-2"></a>

### allowed_status/2 * ###

`allowed_status(ResponseMsg, Statuses) -> any()`

Check if a status is allowed, according to the configuration.

<a name="ans104_wasm_test-0"></a>

### ans104_wasm_test/0 * ###

`ans104_wasm_test() -> any()`

<a name="codec_to_content_type-2"></a>

### codec_to_content_type/2 * ###

`codec_to_content_type(Codec, Opts) -> any()`

Call the `content-type` key on a message with the given codec, using
a fast-path for options that are not needed for this one-time lookup.

<a name="cors_get_test-0"></a>

### cors_get_test/0 * ###

`cors_get_test() -> any()`

<a name="default_codec-1"></a>

### default_codec/1 * ###

`default_codec(Opts) -> any()`

Return the default codec for the given options.

<a name="empty_inbox-1"></a>

### empty_inbox/1 * ###

`empty_inbox(Ref) -> any()`

Empty the inbox of the current process for all messages with the given
reference.

<a name="encode_reply-4"></a>

### encode_reply/4 * ###

`encode_reply(Status, TABMReq, Message, Opts) -> any()`

Generate the headers and body for a HTTP response message.

<a name="get-2"></a>

### get/2 ###

`get(Node, Opts) -> any()`

Gets a URL via HTTP and returns the resulting message in deserialized
form.

<a name="get-3"></a>

### get/3 ###

`get(Node, PathBin, Opts) -> any()`

<a name="get_deep_signed_wasm_state_test-0"></a>

### get_deep_signed_wasm_state_test/0 * ###

`get_deep_signed_wasm_state_test() -> any()`

<a name="get_deep_unsigned_wasm_state_test-0"></a>

### get_deep_unsigned_wasm_state_test/0 * ###

`get_deep_unsigned_wasm_state_test() -> any()`

<a name="http_response_to_httpsig-4"></a>

### http_response_to_httpsig/4 * ###

`http_response_to_httpsig(Status, HeaderMap, Body, Opts) -> any()`

Convert a HTTP response to a httpsig message.

<a name="httpsig_to_tabm_singleton-3"></a>

### httpsig_to_tabm_singleton/3 * ###

`httpsig_to_tabm_singleton(Req, Body, Opts) -> any()`

HTTPSig messages are inherently mixed into the transport layer, so they
require special handling in order to be converted to a normalized message.
In particular, the signatures are verified if present and required by the
node configuration. Additionally, non-committed fields are removed from the
message if it is signed, with the exception of the `path` and `method` fields.

<a name="index_request_test-0"></a>

### index_request_test/0 * ###

`index_request_test() -> any()`

<a name="index_test-0"></a>

### index_test/0 * ###

`index_test() -> any()`

<a name="message_to_request-2"></a>

### message_to_request/2 ###

`message_to_request(M, Opts) -> any()`

Given a message, return the information needed to make the request.

<a name="mime_to_codec-2"></a>

### mime_to_codec/2 * ###

`mime_to_codec(X1, Opts) -> any()`

Find a codec name from a mime-type.

<a name="multirequest-5"></a>

### multirequest/5 * ###

`multirequest(Config, Method, Path, Message, Opts) -> any()`

Dispatch the same HTTP request to many nodes. Can be configured to
await responses from all nodes or just one, and to halt all requests after
after it has received the required number of responses, or to leave all
requests running until they have all completed. Default: Race for first
response.

Expects a config message of the following form:
/Nodes/1..n: Hostname | #{ hostname => Hostname, address => Address }
/Responses: Number of responses to gather
/Stop-After: Should we stop after the required number of responses?
/Parallel: Should we run the requests in parallel?

<a name="multirequest_opt-5"></a>

### multirequest_opt/5 * ###

`multirequest_opt(Key, Config, Message, Default, Opts) -> any()`

Get a value for a multirequest option from the config or message.

<a name="multirequest_opts-3"></a>

### multirequest_opts/3 * ###

`multirequest_opts(Config, Message, Opts) -> any()`

Get the multirequest options from the config or message. The options in
the message take precidence over the options in the config.

<a name="nested_ao_resolve_test-0"></a>

### nested_ao_resolve_test/0 * ###

`nested_ao_resolve_test() -> any()`

<a name="normalize_unsigned-3"></a>

### normalize_unsigned/3 * ###

`normalize_unsigned(Req, Msg, Opts) -> any()`

Add the method and path to a message, if they are not already present.
Remove browser-added fields that are unhelpful during processing (for example,
`content-length`).
The precidence order for finding the path is:
1. The path in the message
2. The path in the request URI

<a name="parallel_multirequest-8"></a>

### parallel_multirequest/8 * ###

`parallel_multirequest(Nodes, Responses, StopAfter, Method, Path, Message, Statuses, Opts) -> any()`

Dispatch the same HTTP request to many nodes in parallel.

<a name="parallel_responses-7"></a>

### parallel_responses/7 * ###

`parallel_responses(Res, Procs, Ref, Awaiting, StopAfter, Statuses, Opts) -> any()`

Collect the necessary number of responses, and stop workers if
configured to do so.

<a name="post-3"></a>

### post/3 ###

`post(Node, Message, Opts) -> any()`

Posts a message to a URL on a remote peer via HTTP. Returns the
resulting message in deserialized form.

<a name="post-4"></a>

### post/4 ###

`post(Node, Path, Message, Opts) -> any()`

<a name="prepare_request-6"></a>

### prepare_request/6 * ###

`prepare_request(Format, Method, Peer, Path, RawMessage, Opts) -> any()`

Turn a set of request arguments into a request message, formatted in the
preferred format. This function honors the `accept-bundle` option, if it is
already present in the message, and sets it to `true` if it is not.

<a name="remove_unless_signed-3"></a>

### remove_unless_signed/3 * ###

`remove_unless_signed(Key, Msg, Opts) -> any()`

Remove all keys from the message unless they are signed.

<a name="reply-4"></a>

### reply/4 ###

`reply(Req, TABMReq, Message, Opts) -> any()`

Reply to the client's HTTP request with a message.

<a name="reply-5"></a>

### reply/5 * ###

`reply(Req, TABMReq, BinStatus, RawMessage, Opts) -> any()`

<a name="req_to_tabm_singleton-3"></a>

### req_to_tabm_singleton/3 ###

`req_to_tabm_singleton(Req, Body, Opts) -> any()`

Convert a cowboy request to a normalized message.

<a name="request-2"></a>

### request/2 ###

`request(Message, Opts) -> any()`

Posts a binary to a URL on a remote peer via HTTP, returning the raw
binary body.

<a name="request-4"></a>

### request/4 ###

`request(Method, Peer, Path, Opts) -> any()`

<a name="request-5"></a>

### request/5 ###

`request(Method, Config, Path, Message, Opts) -> any()`

<a name="route_to_request-3"></a>

### route_to_request/3 * ###

`route_to_request(M, X2, Opts) -> any()`

Parse a `dev_router:route` response and return a tuple of request
parameters.

<a name="run_wasm_signed_test-0"></a>

### run_wasm_signed_test/0 * ###

`run_wasm_signed_test() -> any()`

<a name="run_wasm_unsigned_test-0"></a>

### run_wasm_unsigned_test/0 * ###

`run_wasm_unsigned_test() -> any()`

<a name="send_large_signed_request_test-0"></a>

### send_large_signed_request_test/0 * ###

`send_large_signed_request_test() -> any()`

<a name="serial_multirequest-7"></a>

### serial_multirequest/7 * ###

`serial_multirequest(Nodes, Remaining, Method, Path, Message, Statuses, Opts) -> any()`

Serially request a message, collecting responses until the required
number of responses have been gathered. Ensure that the statuses are
allowed, according to the configuration.

<a name="simple_ao_resolve_signed_test-0"></a>

### simple_ao_resolve_signed_test/0 * ###

`simple_ao_resolve_signed_test() -> any()`

<a name="simple_ao_resolve_unsigned_test-0"></a>

### simple_ao_resolve_unsigned_test/0 * ###

`simple_ao_resolve_unsigned_test() -> any()`

<a name="start-0"></a>

### start/0 ###

`start() -> any()`

<a name="wasm_compute_request-3"></a>

### wasm_compute_request/3 * ###

`wasm_compute_request(ImageFile, Func, Params) -> any()`

<a name="wasm_compute_request-4"></a>

### wasm_compute_request/4 * ###

`wasm_compute_request(ImageFile, Func, Params, ResultPath) -> any()`


--- END OF FILE: docs/resources/source-code/hb_http.md ---

--- START OF FILE: docs/resources/source-code/hb_json.md ---
# [Module hb_json.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_json.erl)




Wrapper for encoding and decoding JSON.

<a name="description"></a>

## Description ##
Supports maps and Jiffy's old
`ejson` format. This module abstracts the underlying JSON library, allowing
us to switch between libraries as needed in the future.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#decode-1">decode/1</a></td><td>Takes a JSON string and decodes it into an Erlang term.</td></tr><tr><td valign="top"><a href="#decode-2">decode/2</a></td><td></td></tr><tr><td valign="top"><a href="#encode-1">encode/1</a></td><td>Takes a term in Erlang's native form and encodes it as a JSON string.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="decode-1"></a>

### decode/1 ###

`decode(Bin) -> any()`

Takes a JSON string and decodes it into an Erlang term.

<a name="decode-2"></a>

### decode/2 ###

`decode(Bin, Opts) -> any()`

<a name="encode-1"></a>

### encode/1 ###

`encode(Term) -> any()`

Takes a term in Erlang's native form and encodes it as a JSON string.


--- END OF FILE: docs/resources/source-code/hb_json.md ---

--- START OF FILE: docs/resources/source-code/hb_keccak.md ---
# [Module hb_keccak.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_keccak.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#hash_to_checksum_address-2">hash_to_checksum_address/2*</a></td><td></td></tr><tr><td valign="top"><a href="#init-0">init/0*</a></td><td></td></tr><tr><td valign="top"><a href="#keccak_256-1">keccak_256/1</a></td><td></td></tr><tr><td valign="top"><a href="#keccak_256_key_test-0">keccak_256_key_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#keccak_256_key_to_address_test-0">keccak_256_key_to_address_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#keccak_256_test-0">keccak_256_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#key_to_ethereum_address-1">key_to_ethereum_address/1</a></td><td></td></tr><tr><td valign="top"><a href="#sha3_256-1">sha3_256/1</a></td><td></td></tr><tr><td valign="top"><a href="#sha3_256_test-0">sha3_256_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to_hex-1">to_hex/1*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="hash_to_checksum_address-2"></a>

### hash_to_checksum_address/2 * ###

`hash_to_checksum_address(Last40, Hash) -> any()`

<a name="init-0"></a>

### init/0 * ###

`init() -> any()`

<a name="keccak_256-1"></a>

### keccak_256/1 ###

`keccak_256(Bin) -> any()`

<a name="keccak_256_key_test-0"></a>

### keccak_256_key_test/0 * ###

`keccak_256_key_test() -> any()`

<a name="keccak_256_key_to_address_test-0"></a>

### keccak_256_key_to_address_test/0 * ###

`keccak_256_key_to_address_test() -> any()`

<a name="keccak_256_test-0"></a>

### keccak_256_test/0 * ###

`keccak_256_test() -> any()`

<a name="key_to_ethereum_address-1"></a>

### key_to_ethereum_address/1 ###

`key_to_ethereum_address(Key) -> any()`

<a name="sha3_256-1"></a>

### sha3_256/1 ###

`sha3_256(Bin) -> any()`

<a name="sha3_256_test-0"></a>

### sha3_256_test/0 * ###

`sha3_256_test() -> any()`

<a name="to_hex-1"></a>

### to_hex/1 * ###

`to_hex(Bin) -> any()`


--- END OF FILE: docs/resources/source-code/hb_keccak.md ---

--- START OF FILE: docs/resources/source-code/hb_link.md ---
# [Module hb_link.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_link.erl)




Utility functions for working with links.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#decode_all_links-1">decode_all_links/1</a></td><td>Decode links embedded in the headers of a message.</td></tr><tr><td valign="top"><a href="#format-1">format/1</a></td><td>Format a link as a short string suitable for printing.</td></tr><tr><td valign="top"><a href="#format-2">format/2</a></td><td></td></tr><tr><td valign="top"><a href="#format_unresolved-1">format_unresolved/1*</a></td><td>Format a link without resolving it.</td></tr><tr><td valign="top"><a href="#is_link_key-1">is_link_key/1</a></td><td>Determine if a key is an encoded link.</td></tr><tr><td valign="top"><a href="#normalize-2">normalize/2</a></td><td>Takes a message and ensures that it is normalized:.</td></tr><tr><td valign="top"><a href="#normalize-3">normalize/3</a></td><td></td></tr><tr><td valign="top"><a href="#offload_linked_message_test-0">offload_linked_message_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#offload_list_test-0">offload_list_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#read-1">read/1</a></td><td>Read a link into memory.</td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td></td></tr><tr><td valign="top"><a href="#remove_link_specifier-1">remove_link_specifier/1</a></td><td>Remove any <code>+link</code> suffixes from a key.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="decode_all_links-1"></a>

### decode_all_links/1 ###

`decode_all_links(Msg) -> any()`

Decode links embedded in the headers of a message.

<a name="format-1"></a>

### format/1 ###

`format(Link) -> any()`

Format a link as a short string suitable for printing. Checks the node
options (optionally) given, to see if it should resolve the link to a value
before printing.

<a name="format-2"></a>

### format/2 ###

`format(Link, Opts) -> any()`

<a name="format_unresolved-1"></a>

### format_unresolved/1 * ###

`format_unresolved(X1) -> any()`

Format a link without resolving it.

<a name="is_link_key-1"></a>

### is_link_key/1 ###

`is_link_key(Key) -> any()`

Determine if a key is an encoded link.

<a name="normalize-2"></a>

### normalize/2 ###

`normalize(Msg, Opts) -> any()`

Takes a message and ensures that it is normalized:

- All literal (binary) lazily-loadable values are in-memory.
- All submaps are represented as links, optionally offloading their local
values to the cache.
- All other values are left unchanged (including their potential types).

The response is a non-recursive, fully loaded message. It may still contain
types, but all submessages are guaranteed to be linkified. This stands in
contrast to `linkify`, which takes a structured message and returns a message
with structured links.

<a name="normalize-3"></a>

### normalize/3 ###

`normalize(Msg, Mode, Opts) -> any()`

<a name="offload_linked_message_test-0"></a>

### offload_linked_message_test/0 * ###

`offload_linked_message_test() -> any()`

<a name="offload_list_test-0"></a>

### offload_list_test/0 * ###

`offload_list_test() -> any()`

<a name="read-1"></a>

### read/1 ###

`read(Link) -> any()`

Read a link into memory. Uses `hb_cache:ensure_loaded/2` under-the-hood.

<a name="read-2"></a>

### read/2 ###

`read(Link, Opts) -> any()`

<a name="remove_link_specifier-1"></a>

### remove_link_specifier/1 ###

`remove_link_specifier(Key) -> any()`

Remove any `+link` suffixes from a key.


--- END OF FILE: docs/resources/source-code/hb_link.md ---

--- START OF FILE: docs/resources/source-code/hb_logger.md ---
# [Module hb_logger.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_logger.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#console-2">console/2*</a></td><td></td></tr><tr><td valign="top"><a href="#log-2">log/2</a></td><td></td></tr><tr><td valign="top"><a href="#loop-1">loop/1*</a></td><td></td></tr><tr><td valign="top"><a href="#register-1">register/1</a></td><td></td></tr><tr><td valign="top"><a href="#report-1">report/1</a></td><td></td></tr><tr><td valign="top"><a href="#start-0">start/0</a></td><td></td></tr><tr><td valign="top"><a href="#start-1">start/1</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="console-2"></a>

### console/2 * ###

`console(State, Act) -> any()`

<a name="log-2"></a>

### log/2 ###

`log(Monitor, Data) -> any()`

<a name="loop-1"></a>

### loop/1 * ###

`loop(State) -> any()`

<a name="register-1"></a>

### register/1 ###

`register(Monitor) -> any()`

<a name="report-1"></a>

### report/1 ###

`report(Monitor) -> any()`

<a name="start-0"></a>

### start/0 ###

`start() -> any()`

<a name="start-1"></a>

### start/1 ###

`start(Client) -> any()`


--- END OF FILE: docs/resources/source-code/hb_logger.md ---

--- START OF FILE: docs/resources/source-code/hb_maps.md ---
# [Module hb_maps.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_maps.erl)




An abstraction for working with maps in HyperBEAM, matching the
generic `maps` module, but additionally supporting the resolution of
links as they are encountered.

<a name="description"></a>

## Description ##

These functions must be used extremely
carefully. In virtually all circumstances, the `hb_ao:resolve/3` or
`hb_ao:get/3` functions should be used instead, as they will execute the
full AO-Core protocol upon requests (normalizing keys, applying the
appropriate device's functions, as well as resolving links). By using this
module's functions, you are implicitly making the assumption that the message
in question is of the `~message@1.0` form, ignoring any other keys that its
actual device may present. This module is intended for the extremely rare
circumstances in which the additional overhead of the full AO-Core
execution cycle is not acceptable, and the data in question is known to
conform to the `~message@1.0` form.

If you do not understand any/all of the above, you are in the wrong place!
Utilise the `hb_ao` module and read the documentation therein, saving
yourself from the inevitable issues that will arise from using this
module without understanding the full implications. You have been warned.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#filter-2">filter/2</a></td><td></td></tr><tr><td valign="top"><a href="#filter-3">filter/3</a></td><td></td></tr><tr><td valign="top"><a href="#filter_passively_loads_test-0">filter_passively_loads_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#filter_with_link_test-0">filter_with_link_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#filtermap-2">filtermap/2</a></td><td></td></tr><tr><td valign="top"><a href="#filtermap-3">filtermap/3</a></td><td></td></tr><tr><td valign="top"><a href="#filtermap_passively_loads_test-0">filtermap_passively_loads_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#filtermap_with_link_test-0">filtermap_with_link_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#find-2">find/2</a></td><td></td></tr><tr><td valign="top"><a href="#find-3">find/3</a></td><td></td></tr><tr><td valign="top"><a href="#fold-3">fold/3</a></td><td></td></tr><tr><td valign="top"><a href="#fold-4">fold/4</a></td><td></td></tr><tr><td valign="top"><a href="#fold_with_typed_link_test-0">fold_with_typed_link_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#from_list-1">from_list/1</a></td><td></td></tr><tr><td valign="top"><a href="#get-2">get/2</a></td><td></td></tr><tr><td valign="top"><a href="#get-3">get/3</a></td><td></td></tr><tr><td valign="top"><a href="#get-4">get/4</a></td><td>Get a value from a map, resolving links as they are encountered in both
the TABM encoded link format, as well as the structured type.</td></tr><tr><td valign="top"><a href="#get_with_link_test-0">get_with_link_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#get_with_typed_link_test-0">get_with_typed_link_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#is_key-2">is_key/2</a></td><td></td></tr><tr><td valign="top"><a href="#is_key-3">is_key/3</a></td><td></td></tr><tr><td valign="top"><a href="#keys-1">keys/1</a></td><td></td></tr><tr><td valign="top"><a href="#keys-2">keys/2</a></td><td></td></tr><tr><td valign="top"><a href="#map-2">map/2</a></td><td></td></tr><tr><td valign="top"><a href="#map-3">map/3</a></td><td></td></tr><tr><td valign="top"><a href="#map_with_link_test-0">map_with_link_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#merge-2">merge/2</a></td><td></td></tr><tr><td valign="top"><a href="#merge-3">merge/3</a></td><td></td></tr><tr><td valign="top"><a href="#put-3">put/3</a></td><td></td></tr><tr><td valign="top"><a href="#put-4">put/4</a></td><td></td></tr><tr><td valign="top"><a href="#remove-2">remove/2</a></td><td></td></tr><tr><td valign="top"><a href="#remove-3">remove/3</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_on_link_test-0">resolve_on_link_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#size-1">size/1</a></td><td></td></tr><tr><td valign="top"><a href="#size-2">size/2</a></td><td></td></tr><tr><td valign="top"><a href="#take-2">take/2</a></td><td></td></tr><tr><td valign="top"><a href="#take-3">take/3</a></td><td></td></tr><tr><td valign="top"><a href="#to_list-1">to_list/1</a></td><td></td></tr><tr><td valign="top"><a href="#to_list-2">to_list/2</a></td><td></td></tr><tr><td valign="top"><a href="#update_with-3">update_with/3</a></td><td></td></tr><tr><td valign="top"><a href="#update_with-4">update_with/4</a></td><td></td></tr><tr><td valign="top"><a href="#values-1">values/1</a></td><td></td></tr><tr><td valign="top"><a href="#values-2">values/2</a></td><td></td></tr><tr><td valign="top"><a href="#with-2">with/2</a></td><td></td></tr><tr><td valign="top"><a href="#with-3">with/3</a></td><td></td></tr><tr><td valign="top"><a href="#without-2">without/2</a></td><td></td></tr><tr><td valign="top"><a href="#without-3">without/3</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="filter-2"></a>

### filter/2 ###

<pre><code>
filter(Fun::fun((Key::term(), Value::term()) -&gt; boolean()), Map::map()) -&gt; map()
</code></pre>
<br />

<a name="filter-3"></a>

### filter/3 ###

<pre><code>
filter(Fun::fun((Key::term(), Value::term()) -&gt; boolean()), Map::map(), Opts::map()) -&gt; map()
</code></pre>
<br />

<a name="filter_passively_loads_test-0"></a>

### filter_passively_loads_test/0 * ###

`filter_passively_loads_test() -> any()`

<a name="filter_with_link_test-0"></a>

### filter_with_link_test/0 * ###

`filter_with_link_test() -> any()`

<a name="filtermap-2"></a>

### filtermap/2 ###

<pre><code>
filtermap(Fun::fun((Key::term(), Value::term()) -&gt; {boolean(), term()}), Map::map()) -&gt; map()
</code></pre>
<br />

<a name="filtermap-3"></a>

### filtermap/3 ###

<pre><code>
filtermap(Fun::fun((Key::term(), Value::term()) -&gt; {boolean(), term()}), Map::map(), Opts::map()) -&gt; map()
</code></pre>
<br />

<a name="filtermap_passively_loads_test-0"></a>

### filtermap_passively_loads_test/0 * ###

`filtermap_passively_loads_test() -> any()`

<a name="filtermap_with_link_test-0"></a>

### filtermap_with_link_test/0 * ###

`filtermap_with_link_test() -> any()`

<a name="find-2"></a>

### find/2 ###

<pre><code>
find(Key::term(), Map::map()) -&gt; {ok, term()} | error
</code></pre>
<br />

<a name="find-3"></a>

### find/3 ###

<pre><code>
find(Key::term(), Map::map(), Opts::map()) -&gt; {ok, term()} | error
</code></pre>
<br />

<a name="fold-3"></a>

### fold/3 ###

<pre><code>
fold(Fun::fun((Key::term(), Value::term(), Acc::term()) -&gt; term()), Acc::term(), Map::map()) -&gt; term()
</code></pre>
<br />

<a name="fold-4"></a>

### fold/4 ###

<pre><code>
fold(Fun::fun((Key::term(), Value::term(), Acc::term()) -&gt; term()), Acc::term(), Map::map(), Opts::map()) -&gt; term()
</code></pre>
<br />

<a name="fold_with_typed_link_test-0"></a>

### fold_with_typed_link_test/0 * ###

`fold_with_typed_link_test() -> any()`

<a name="from_list-1"></a>

### from_list/1 ###

<pre><code>
from_list(List::[{Key::term(), Value::term()}]) -&gt; map()
</code></pre>
<br />

<a name="get-2"></a>

### get/2 ###

<pre><code>
get(Key::term(), Map::map()) -&gt; term()
</code></pre>
<br />

<a name="get-3"></a>

### get/3 ###

<pre><code>
get(Key::term(), Map::map(), Default::term()) -&gt; term()
</code></pre>
<br />

<a name="get-4"></a>

### get/4 ###

<pre><code>
get(Key::term(), Map::map(), Default::term(), Opts::map()) -&gt; term()
</code></pre>
<br />

Get a value from a map, resolving links as they are encountered in both
the TABM encoded link format, as well as the structured type.

<a name="get_with_link_test-0"></a>

### get_with_link_test/0 * ###

`get_with_link_test() -> any()`

<a name="get_with_typed_link_test-0"></a>

### get_with_typed_link_test/0 * ###

`get_with_typed_link_test() -> any()`

<a name="is_key-2"></a>

### is_key/2 ###

<pre><code>
is_key(Key::term(), Map::map()) -&gt; boolean()
</code></pre>
<br />

<a name="is_key-3"></a>

### is_key/3 ###

<pre><code>
is_key(Key::term(), Map::map(), Opts::map()) -&gt; boolean()
</code></pre>
<br />

<a name="keys-1"></a>

### keys/1 ###

<pre><code>
keys(Map::map()) -&gt; [term()]
</code></pre>
<br />

<a name="keys-2"></a>

### keys/2 ###

<pre><code>
keys(Map::map(), Opts::map()) -&gt; [term()]
</code></pre>
<br />

<a name="map-2"></a>

### map/2 ###

<pre><code>
map(Fun::fun((Key::term(), Value::term()) -&gt; term()), Map::map()) -&gt; map()
</code></pre>
<br />

<a name="map-3"></a>

### map/3 ###

<pre><code>
map(Fun::fun((Key::term(), Value::term()) -&gt; term()), Map::map(), Opts::map()) -&gt; map()
</code></pre>
<br />

<a name="map_with_link_test-0"></a>

### map_with_link_test/0 * ###

`map_with_link_test() -> any()`

<a name="merge-2"></a>

### merge/2 ###

<pre><code>
merge(Map1::map(), Map2::map()) -&gt; map()
</code></pre>
<br />

<a name="merge-3"></a>

### merge/3 ###

<pre><code>
merge(Map1::map(), Map2::map(), Opts::map()) -&gt; map()
</code></pre>
<br />

<a name="put-3"></a>

### put/3 ###

<pre><code>
put(Key::term(), Value::term(), Map::map()) -&gt; map()
</code></pre>
<br />

<a name="put-4"></a>

### put/4 ###

<pre><code>
put(Key::term(), Value::term(), Map::map(), Opts::map()) -&gt; map()
</code></pre>
<br />

<a name="remove-2"></a>

### remove/2 ###

<pre><code>
remove(Key::term(), Map::map()) -&gt; map()
</code></pre>
<br />

<a name="remove-3"></a>

### remove/3 ###

<pre><code>
remove(Key::term(), Map::map(), Opts::map()) -&gt; map()
</code></pre>
<br />

<a name="resolve_on_link_test-0"></a>

### resolve_on_link_test/0 * ###

`resolve_on_link_test() -> any()`

<a name="size-1"></a>

### size/1 ###

<pre><code>
size(Map::map()) -&gt; non_neg_integer()
</code></pre>
<br />

<a name="size-2"></a>

### size/2 ###

<pre><code>
size(Map::map(), Opts::map()) -&gt; non_neg_integer()
</code></pre>
<br />

<a name="take-2"></a>

### take/2 ###

<pre><code>
take(N::non_neg_integer(), Map::map()) -&gt; map()
</code></pre>
<br />

<a name="take-3"></a>

### take/3 ###

<pre><code>
take(N::non_neg_integer(), Map::map(), Opts::map()) -&gt; map()
</code></pre>
<br />

<a name="to_list-1"></a>

### to_list/1 ###

<pre><code>
to_list(Map::map()) -&gt; [{Key::term(), Value::term()}]
</code></pre>
<br />

<a name="to_list-2"></a>

### to_list/2 ###

<pre><code>
to_list(Map::map(), Opts::map()) -&gt; [{Key::term(), Value::term()}]
</code></pre>
<br />

<a name="update_with-3"></a>

### update_with/3 ###

<pre><code>
update_with(Key::term(), Fun::fun((Value::term()) -&gt; term()), Map::map()) -&gt; map()
</code></pre>
<br />

<a name="update_with-4"></a>

### update_with/4 ###

<pre><code>
update_with(Key::term(), Fun::fun((Value::term()) -&gt; term()), Map::map(), Opts::map()) -&gt; map()
</code></pre>
<br />

<a name="values-1"></a>

### values/1 ###

<pre><code>
values(Map::map()) -&gt; [term()]
</code></pre>
<br />

<a name="values-2"></a>

### values/2 ###

<pre><code>
values(Map::map(), Opts::map()) -&gt; [term()]
</code></pre>
<br />

<a name="with-2"></a>

### with/2 ###

<pre><code>
with(Keys::[term()], Map::map()) -&gt; map()
</code></pre>
<br />

<a name="with-3"></a>

### with/3 ###

<pre><code>
with(Keys::[term()], Map::map(), Opts::map()) -&gt; map()
</code></pre>
<br />

<a name="without-2"></a>

### without/2 ###

<pre><code>
without(Keys::[term()], Map::map()) -&gt; map()
</code></pre>
<br />

<a name="without-3"></a>

### without/3 ###

<pre><code>
without(Keys::[term()], Map::map(), Opts::map()) -&gt; map()
</code></pre>
<br />


--- END OF FILE: docs/resources/source-code/hb_maps.md ---

--- START OF FILE: docs/resources/source-code/hb_message_test_vectors.md ---
# [Module hb_message_test_vectors.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_message_test_vectors.erl)




A battery of test vectors for message codecs, implementing the
`message@1.0` encoding and commitment APIs.

<a name="description"></a>

## Description ##
Additionally, this module
houses tests that ensure the general functioning of the `hb_message` API.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#basic_message_codec_test-2">basic_message_codec_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#binary_to_binary_test-2">binary_to_binary_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#bundled_and_unbundled_ids_differ_test-2">bundled_and_unbundled_ids_differ_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#bundled_ordering_test-2">bundled_ordering_test/2*</a></td><td>Ensure that a httpsig@1.0 message which is bundled and requests an
invalid ordering of keys is normalized to a valid ordering.</td></tr><tr><td valign="top"><a href="#codec_roundtrip_conversion_is_idempotent_test-2">codec_roundtrip_conversion_is_idempotent_test/2*</a></td><td>Ensure that converting a message to a codec, then back to TABM multiple
times results in the same message being returned.</td></tr><tr><td valign="top"><a href="#codec_test_suite-1">codec_test_suite/1*</a></td><td></td></tr><tr><td valign="top"><a href="#committed_empty_keys_test-2">committed_empty_keys_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#committed_keys_test-2">committed_keys_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#complex_signed_message_test-2">complex_signed_message_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#deep_multisignature_test-0">deep_multisignature_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#deep_typed_message_id_test-2">deep_typed_message_id_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#deeply_nested_committed_keys_test-0">deeply_nested_committed_keys_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#deeply_nested_message_with_content_test-2">deeply_nested_message_with_content_test/2*</a></td><td>Test that we can convert a 3 layer nested message into a tx record and back.</td></tr><tr><td valign="top"><a href="#deeply_nested_message_with_only_content-2">deeply_nested_message_with_only_content/2*</a></td><td></td></tr><tr><td valign="top"><a href="#default_keys_removed_test-0">default_keys_removed_test/0*</a></td><td>Test that the filter_default_keys/1 function removes TX fields
that have the default values found in the tx record, but not those that
have been set by the user.</td></tr><tr><td valign="top"><a href="#empty_body_test-2">empty_body_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#empty_string_in_nested_tag_test-2">empty_string_in_nested_tag_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#encode_balance_table-3">encode_balance_table/3*</a></td><td></td></tr><tr><td valign="top"><a href="#encode_large_balance_table_test-2">encode_large_balance_table_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#encode_small_balance_table_test-2">encode_small_balance_table_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#find_multiple_commitments_test_disabled-0">find_multiple_commitments_test_disabled/0*</a></td><td></td></tr><tr><td valign="top"><a href="#hashpath_sign_verify_test-2">hashpath_sign_verify_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#id_of_deep_message_and_link_message_match_test-2">id_of_deep_message_and_link_message_match_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#id_of_linked_message_test-2">id_of_linked_message_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#is_idempotent-3">is_idempotent/3*</a></td><td>Tests a message transforming function to ensure that it is idempotent.</td></tr><tr><td valign="top"><a href="#large_body_committed_keys_test-2">large_body_committed_keys_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#match_modes_test-0">match_modes_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#match_test-2">match_test/2*</a></td><td>Test that the message matching function works.</td></tr><tr><td valign="top"><a href="#message_with_large_keys_test-2">message_with_large_keys_test/2*</a></td><td>Test that the data field is correctly managed when we have multiple
uses for it (the 'data' key itself, as well as keys that cannot fit in
tags).</td></tr><tr><td valign="top"><a href="#message_with_simple_embedded_list_test-2">message_with_simple_embedded_list_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#minimization_test-0">minimization_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#nested_body_list_test-2">nested_body_list_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#nested_empty_map_test-2">nested_empty_map_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#nested_message_with_large_content_test-2">nested_message_with_large_content_test/2*</a></td><td>Test that the data field is correctly managed when we have multiple
uses for it (the 'data' key itself, as well as keys that cannot fit in
tags).</td></tr><tr><td valign="top"><a href="#nested_message_with_large_keys_and_content_test-2">nested_message_with_large_keys_and_content_test/2*</a></td><td>Check that large keys and data fields are correctly handled together.</td></tr><tr><td valign="top"><a href="#nested_message_with_large_keys_test-2">nested_message_with_large_keys_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#nested_structured_fields_test-2">nested_structured_fields_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#priv_survives_conversion_test-2">priv_survives_conversion_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#recursive_nested_list_test-2">recursive_nested_list_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#run_test-0">run_test/0*</a></td><td>Test invocation function, making it easier to run a specific test.</td></tr><tr><td valign="top"><a href="#set_body_codec_test-2">set_body_codec_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#sign_deep_message_from_lazy_cache_read_test-2">sign_deep_message_from_lazy_cache_read_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#sign_links_test-2">sign_links_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#sign_node_message_test-2">sign_node_message_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#signed_deep_message_test-2">signed_deep_message_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#signed_list_test-2">signed_list_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#signed_message_encode_decode_verify_test-2">signed_message_encode_decode_verify_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#signed_message_with_derived_components_test-2">signed_message_with_derived_components_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#signed_nested_data_key_test-2">signed_nested_data_key_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#signed_nested_message_with_child_test-2">signed_nested_message_with_child_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#signed_non_bundle_is_bundlable_test-2">signed_non_bundle_is_bundlable_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#signed_only_committed_data_field_test-2">signed_only_committed_data_field_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#signed_with_inner_signed_message_test-2">signed_with_inner_signed_message_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#simple_nested_message_test-2">simple_nested_message_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#simple_signed_nested_message_test-2">simple_signed_nested_message_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#single_layer_message_to_encoding_test-2">single_layer_message_to_encoding_test/2*</a></td><td>Test that we can convert a message into a tx record and back.</td></tr><tr><td valign="top"><a href="#specific_order_deeply_nested_signed_message_test-2">specific_order_deeply_nested_signed_message_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#specific_order_signed_message_test-2">specific_order_signed_message_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#structured_field_atom_parsing_test-2">structured_field_atom_parsing_test/2*</a></td><td>Structured field parsing tests.</td></tr><tr><td valign="top"><a href="#structured_field_decimal_parsing_test-2">structured_field_decimal_parsing_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#suite_name-1">suite_name/1*</a></td><td>Create a name for a suite from a codec spec.</td></tr><tr><td valign="top"><a href="#suite_test_-0">suite_test_/0*</a></td><td>Organizes a test battery for the <code>hb_message</code> module and its codecs.</td></tr><tr><td valign="top"><a href="#suite_test_opts-0">suite_test_opts/0*</a></td><td>Return a set of options for testing, taking the codec name as an
argument.</td></tr><tr><td valign="top"><a href="#suite_test_opts-1">suite_test_opts/1*</a></td><td></td></tr><tr><td valign="top"><a href="#tabm_conversion_is_idempotent_test-2">tabm_conversion_is_idempotent_test/2*</a></td><td>Ensure that converting a message to/from TABM multiple times repeatedly
does not alter the message's contents.</td></tr><tr><td valign="top"><a href="#test_codecs-0">test_codecs/0*</a></td><td>Return a list of codecs to test.</td></tr><tr><td valign="top"><a href="#test_opts-1">test_opts/1*</a></td><td></td></tr><tr><td valign="top"><a href="#test_suite-0">test_suite/0*</a></td><td></td></tr><tr><td valign="top"><a href="#unsigned_id_test-2">unsigned_id_test/2*</a></td><td></td></tr><tr><td valign="top"><a href="#verify_nested_complex_signed_test-2">verify_nested_complex_signed_test/2*</a></td><td>Check that a nested signed message with an embedded typed list can
be further nested and signed.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="basic_message_codec_test-2"></a>

### basic_message_codec_test/2 * ###

`basic_message_codec_test(Codec, Opts) -> any()`

<a name="binary_to_binary_test-2"></a>

### binary_to_binary_test/2 * ###

`binary_to_binary_test(Codec, Opts) -> any()`

<a name="bundled_and_unbundled_ids_differ_test-2"></a>

### bundled_and_unbundled_ids_differ_test/2 * ###

`bundled_and_unbundled_ids_differ_test(Codec, Opts) -> any()`

<a name="bundled_ordering_test-2"></a>

### bundled_ordering_test/2 * ###

`bundled_ordering_test(Codec, Opts) -> any()`

Ensure that a httpsig@1.0 message which is bundled and requests an
invalid ordering of keys is normalized to a valid ordering.

<a name="codec_roundtrip_conversion_is_idempotent_test-2"></a>

### codec_roundtrip_conversion_is_idempotent_test/2 * ###

`codec_roundtrip_conversion_is_idempotent_test(Codec, Opts) -> any()`

Ensure that converting a message to a codec, then back to TABM multiple
times results in the same message being returned. This test differs from its
TABM form, as it shuttles (`to-from-to-...`), while the TABM test repeatedly
encodes in a single direction (`to->to->...`).

<a name="codec_test_suite-1"></a>

### codec_test_suite/1 * ###

`codec_test_suite(Codecs) -> any()`

<a name="committed_empty_keys_test-2"></a>

### committed_empty_keys_test/2 * ###

`committed_empty_keys_test(Codec, Opts) -> any()`

<a name="committed_keys_test-2"></a>

### committed_keys_test/2 * ###

`committed_keys_test(Codec, Opts) -> any()`

<a name="complex_signed_message_test-2"></a>

### complex_signed_message_test/2 * ###

`complex_signed_message_test(Codec, Opts) -> any()`

<a name="deep_multisignature_test-0"></a>

### deep_multisignature_test/0 * ###

`deep_multisignature_test() -> any()`

<a name="deep_typed_message_id_test-2"></a>

### deep_typed_message_id_test/2 * ###

`deep_typed_message_id_test(Codec, Opts) -> any()`

<a name="deeply_nested_committed_keys_test-0"></a>

### deeply_nested_committed_keys_test/0 * ###

`deeply_nested_committed_keys_test() -> any()`

<a name="deeply_nested_message_with_content_test-2"></a>

### deeply_nested_message_with_content_test/2 * ###

`deeply_nested_message_with_content_test(Codec, Opts) -> any()`

Test that we can convert a 3 layer nested message into a tx record and back.

<a name="deeply_nested_message_with_only_content-2"></a>

### deeply_nested_message_with_only_content/2 * ###

`deeply_nested_message_with_only_content(Codec, Opts) -> any()`

<a name="default_keys_removed_test-0"></a>

### default_keys_removed_test/0 * ###

`default_keys_removed_test() -> any()`

Test that the filter_default_keys/1 function removes TX fields
that have the default values found in the tx record, but not those that
have been set by the user.

<a name="empty_body_test-2"></a>

### empty_body_test/2 * ###

`empty_body_test(Codec, Opts) -> any()`

<a name="empty_string_in_nested_tag_test-2"></a>

### empty_string_in_nested_tag_test/2 * ###

`empty_string_in_nested_tag_test(Codec, Opts) -> any()`

<a name="encode_balance_table-3"></a>

### encode_balance_table/3 * ###

`encode_balance_table(Size, Codec, Opts) -> any()`

<a name="encode_large_balance_table_test-2"></a>

### encode_large_balance_table_test/2 * ###

`encode_large_balance_table_test(Codec, Opts) -> any()`

<a name="encode_small_balance_table_test-2"></a>

### encode_small_balance_table_test/2 * ###

`encode_small_balance_table_test(Codec, Opts) -> any()`

<a name="find_multiple_commitments_test_disabled-0"></a>

### find_multiple_commitments_test_disabled/0 * ###

`find_multiple_commitments_test_disabled() -> any()`

<a name="hashpath_sign_verify_test-2"></a>

### hashpath_sign_verify_test/2 * ###

`hashpath_sign_verify_test(Codec, Opts) -> any()`

<a name="id_of_deep_message_and_link_message_match_test-2"></a>

### id_of_deep_message_and_link_message_match_test/2 * ###

`id_of_deep_message_and_link_message_match_test(Codec, Opts) -> any()`

<a name="id_of_linked_message_test-2"></a>

### id_of_linked_message_test/2 * ###

`id_of_linked_message_test(Codec, Opts) -> any()`

<a name="is_idempotent-3"></a>

### is_idempotent/3 * ###

`is_idempotent(Func, Msg, Opts) -> any()`

Tests a message transforming function to ensure that it is idempotent.
Runs the conversion a total of 3 times, ensuring that the result remains
unchanged. This function takes transformation functions that result in
`{ok, Res}`-form messages, as well as bare message results.

<a name="large_body_committed_keys_test-2"></a>

### large_body_committed_keys_test/2 * ###

`large_body_committed_keys_test(Codec, Opts) -> any()`

<a name="match_modes_test-0"></a>

### match_modes_test/0 * ###

`match_modes_test() -> any()`

<a name="match_test-2"></a>

### match_test/2 * ###

`match_test(Codec, Opts) -> any()`

Test that the message matching function works.

<a name="message_with_large_keys_test-2"></a>

### message_with_large_keys_test/2 * ###

`message_with_large_keys_test(Codec, Opts) -> any()`

Test that the data field is correctly managed when we have multiple
uses for it (the 'data' key itself, as well as keys that cannot fit in
tags).

<a name="message_with_simple_embedded_list_test-2"></a>

### message_with_simple_embedded_list_test/2 * ###

`message_with_simple_embedded_list_test(Codec, Opts) -> any()`

<a name="minimization_test-0"></a>

### minimization_test/0 * ###

`minimization_test() -> any()`

<a name="nested_body_list_test-2"></a>

### nested_body_list_test/2 * ###

`nested_body_list_test(Codec, Opts) -> any()`

<a name="nested_empty_map_test-2"></a>

### nested_empty_map_test/2 * ###

`nested_empty_map_test(Codec, Opts) -> any()`

<a name="nested_message_with_large_content_test-2"></a>

### nested_message_with_large_content_test/2 * ###

`nested_message_with_large_content_test(Codec, Opts) -> any()`

Test that the data field is correctly managed when we have multiple
uses for it (the 'data' key itself, as well as keys that cannot fit in
tags).

<a name="nested_message_with_large_keys_and_content_test-2"></a>

### nested_message_with_large_keys_and_content_test/2 * ###

`nested_message_with_large_keys_and_content_test(Codec, Opts) -> any()`

Check that large keys and data fields are correctly handled together.

<a name="nested_message_with_large_keys_test-2"></a>

### nested_message_with_large_keys_test/2 * ###

`nested_message_with_large_keys_test(Codec, Opts) -> any()`

<a name="nested_structured_fields_test-2"></a>

### nested_structured_fields_test/2 * ###

`nested_structured_fields_test(Codec, Opts) -> any()`

<a name="priv_survives_conversion_test-2"></a>

### priv_survives_conversion_test/2 * ###

`priv_survives_conversion_test(Codec, Opts) -> any()`

<a name="recursive_nested_list_test-2"></a>

### recursive_nested_list_test/2 * ###

`recursive_nested_list_test(Codec, Opts) -> any()`

<a name="run_test-0"></a>

### run_test/0 * ###

`run_test() -> any()`

Test invocation function, making it easier to run a specific test.
Disable/enable as needed.

<a name="set_body_codec_test-2"></a>

### set_body_codec_test/2 * ###

`set_body_codec_test(Codec, Opts) -> any()`

<a name="sign_deep_message_from_lazy_cache_read_test-2"></a>

### sign_deep_message_from_lazy_cache_read_test/2 * ###

`sign_deep_message_from_lazy_cache_read_test(Codec, Opts) -> any()`

<a name="sign_links_test-2"></a>

### sign_links_test/2 * ###

`sign_links_test(Codec, Opts) -> any()`

<a name="sign_node_message_test-2"></a>

### sign_node_message_test/2 * ###

`sign_node_message_test(Codec, Opts) -> any()`

<a name="signed_deep_message_test-2"></a>

### signed_deep_message_test/2 * ###

`signed_deep_message_test(Codec, Opts) -> any()`

<a name="signed_list_test-2"></a>

### signed_list_test/2 * ###

`signed_list_test(Codec, Opts) -> any()`

<a name="signed_message_encode_decode_verify_test-2"></a>

### signed_message_encode_decode_verify_test/2 * ###

`signed_message_encode_decode_verify_test(Codec, Opts) -> any()`

<a name="signed_message_with_derived_components_test-2"></a>

### signed_message_with_derived_components_test/2 * ###

`signed_message_with_derived_components_test(Codec, Opts) -> any()`

<a name="signed_nested_data_key_test-2"></a>

### signed_nested_data_key_test/2 * ###

`signed_nested_data_key_test(Codec, Opts) -> any()`

<a name="signed_nested_message_with_child_test-2"></a>

### signed_nested_message_with_child_test/2 * ###

`signed_nested_message_with_child_test(Codec, Opts) -> any()`

<a name="signed_non_bundle_is_bundlable_test-2"></a>

### signed_non_bundle_is_bundlable_test/2 * ###

`signed_non_bundle_is_bundlable_test(Codec, Opts) -> any()`

<a name="signed_only_committed_data_field_test-2"></a>

### signed_only_committed_data_field_test/2 * ###

`signed_only_committed_data_field_test(Codec, Opts) -> any()`

<a name="signed_with_inner_signed_message_test-2"></a>

### signed_with_inner_signed_message_test/2 * ###

`signed_with_inner_signed_message_test(Codec, Opts) -> any()`

<a name="simple_nested_message_test-2"></a>

### simple_nested_message_test/2 * ###

`simple_nested_message_test(Codec, Opts) -> any()`

<a name="simple_signed_nested_message_test-2"></a>

### simple_signed_nested_message_test/2 * ###

`simple_signed_nested_message_test(Codec, Opts) -> any()`

<a name="single_layer_message_to_encoding_test-2"></a>

### single_layer_message_to_encoding_test/2 * ###

`single_layer_message_to_encoding_test(Codec, Opts) -> any()`

Test that we can convert a message into a tx record and back.

<a name="specific_order_deeply_nested_signed_message_test-2"></a>

### specific_order_deeply_nested_signed_message_test/2 * ###

`specific_order_deeply_nested_signed_message_test(RawCodec, Opts) -> any()`

<a name="specific_order_signed_message_test-2"></a>

### specific_order_signed_message_test/2 * ###

`specific_order_signed_message_test(RawCodec, Opts) -> any()`

<a name="structured_field_atom_parsing_test-2"></a>

### structured_field_atom_parsing_test/2 * ###

`structured_field_atom_parsing_test(Codec, Opts) -> any()`

Structured field parsing tests.

<a name="structured_field_decimal_parsing_test-2"></a>

### structured_field_decimal_parsing_test/2 * ###

`structured_field_decimal_parsing_test(Codec, Opts) -> any()`

<a name="suite_name-1"></a>

### suite_name/1 * ###

`suite_name(CodecSpec) -> any()`

Create a name for a suite from a codec spec.

<a name="suite_test_-0"></a>

### suite_test_/0 * ###

`suite_test_() -> any()`

Organizes a test battery for the `hb_message` module and its codecs.

<a name="suite_test_opts-0"></a>

### suite_test_opts/0 * ###

`suite_test_opts() -> any()`

Return a set of options for testing, taking the codec name as an
argument. We do not presently use the codec name in the test, but we may
wish to do so in the future.

<a name="suite_test_opts-1"></a>

### suite_test_opts/1 * ###

`suite_test_opts(OptsName) -> any()`

<a name="tabm_conversion_is_idempotent_test-2"></a>

### tabm_conversion_is_idempotent_test/2 * ###

`tabm_conversion_is_idempotent_test(Codec, Opts) -> any()`

Ensure that converting a message to/from TABM multiple times repeatedly
does not alter the message's contents.

<a name="test_codecs-0"></a>

### test_codecs/0 * ###

`test_codecs() -> any()`

Return a list of codecs to test. Disable these as necessary if you need
to test the functionality of a single codec, etc.

<a name="test_opts-1"></a>

### test_opts/1 * ###

`test_opts(X1) -> any()`

<a name="test_suite-0"></a>

### test_suite/0 * ###

`test_suite() -> any()`

<a name="unsigned_id_test-2"></a>

### unsigned_id_test/2 * ###

`unsigned_id_test(Codec, Opts) -> any()`

<a name="verify_nested_complex_signed_test-2"></a>

### verify_nested_complex_signed_test/2 * ###

`verify_nested_complex_signed_test(Codec, Opts) -> any()`

Check that a nested signed message with an embedded typed list can
be further nested and signed. We then encode and decode the message. This
tests a large portion of the complex type encodings that HyperBEAM uses
together.


--- END OF FILE: docs/resources/source-code/hb_message_test_vectors.md ---

--- START OF FILE: docs/resources/source-code/hb_message.md ---
# [Module hb_message.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_message.erl)




This module acts an adapter between messages, as modeled in the
AO-Core protocol, and their uderlying binary representations and formats.

<a name="description"></a>

## Description ##

Unless you are implementing a new message serialization codec, you should
not need to interact with this module directly. Instead, use the
`hb_ao` interfaces to interact with all messages. The `dev_message`
module implements a device interface for abstracting over the different
message formats.

`hb_message` and the HyperBEAM caches can interact with multiple different
types of message formats:

- Richly typed AO-Core structured messages.
- Arweave transations.
- ANS-104 data items.
- HTTP Signed Messages.
- Flat Maps.

This module is responsible for converting between these formats. It does so
by normalizing messages to a common format: `Type Annotated Binary Messages`
(TABM). TABMs are deep Erlang maps with keys than only contain either other
TABMs or binary values. By marshalling all messages into this format, they
can easily be coerced into other output formats. For example, generating a
`HTTP Signed Message` format output from an Arweave transaction. TABM is
also a simple format from a computational perspective (only binary literals
and O(1) access maps), such that operations upon them are efficient.

The structure of the conversions is as follows:

<pre>
Arweave TX/ANS-104 ==> dev_codec_ans104:from/1 ==> TABM
HTTP Signed Message ==> dev_codec_httpsig_conv:from/1 ==> TABM
Flat Maps ==> dev_codec_flat:from/1 ==> TABM

TABM ==> dev_codec_structured:to/1 ==> AO-Core Message
AO-Core Message ==> dev_codec_structured:from/1 ==> TABM

TABM ==> dev_codec_ans104:to/1 ==> Arweave TX/ANS-104
TABM ==> dev_codec_httpsig_conv:to/1 ==> HTTP Signed Message
TABM ==> dev_codec_flat:to/1 ==> Flat Maps
...
</pre>

Additionally, this module provides a number of utility functions for
manipulating messages. For example, `hb_message:sign/2` to sign a message of
arbitrary type, or `hb_message:format/1` to print an AO-Core/TABM message in
a human-readable format.

The `hb_cache` module is responsible for storing and retrieving messages in
the HyperBEAM stores configured on the node. Each store has its own storage
backend, but each works with simple key-value pairs. Subsequently, the
`hb_cache` module uses TABMs as the internal format for storing and
retrieving messages.

Test vectors to ensure the functioning of this module and the codecs that
interact with it are found in `hb_message_test_vectors.erl`.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#commit-2">commit/2</a></td><td>Sign a message with the given wallet.</td></tr><tr><td valign="top"><a href="#commit-3">commit/3</a></td><td></td></tr><tr><td valign="top"><a href="#commitment-2">commitment/2</a></td><td>Extract a commitment from a message given a <code>committer</code> ID, or a spec
message to match against.</td></tr><tr><td valign="top"><a href="#commitment-3">commitment/3</a></td><td></td></tr><tr><td valign="top"><a href="#commitment_devices-2">commitment_devices/2</a></td><td>Return the devices for which there are commitments on a message.</td></tr><tr><td valign="top"><a href="#committed-3">committed/3</a></td><td>Return the list of committed keys from a message.</td></tr><tr><td valign="top"><a href="#conversion_spec_to_req-2">conversion_spec_to_req/2*</a></td><td>Get a codec device and request params from the given conversion request.</td></tr><tr><td valign="top"><a href="#convert-3">convert/3</a></td><td>Convert a message from one format to another.</td></tr><tr><td valign="top"><a href="#convert-4">convert/4</a></td><td></td></tr><tr><td valign="top"><a href="#default_tx_list-0">default_tx_list/0</a></td><td>Get the ordered list of fields as AO-Core keys and default values of
the tx record.</td></tr><tr><td valign="top"><a href="#default_tx_message-0">default_tx_message/0*</a></td><td>Get the normalized fields and default values of the tx record.</td></tr><tr><td valign="top"><a href="#filter_default_keys-1">filter_default_keys/1</a></td><td>Remove keys from a map that have the default values found in the tx
record.</td></tr><tr><td valign="top"><a href="#find_target-3">find_target/3</a></td><td>Implements a standard pattern in which the target for an operation is
found by looking for a <code>target</code> key in the request.</td></tr><tr><td valign="top"><a href="#format-1">format/1</a></td><td>Format a message for printing, optionally taking an indentation level
to start from.</td></tr><tr><td valign="top"><a href="#format-2">format/2</a></td><td></td></tr><tr><td valign="top"><a href="#from_tabm-4">from_tabm/4*</a></td><td></td></tr><tr><td valign="top"><a href="#id-1">id/1</a></td><td>Return the ID of a message.</td></tr><tr><td valign="top"><a href="#id-2">id/2</a></td><td></td></tr><tr><td valign="top"><a href="#id-3">id/3</a></td><td></td></tr><tr><td valign="top"><a href="#is_signed_key-3">is_signed_key/3</a></td><td>Determine whether a specific key is part of a message's commitments.</td></tr><tr><td valign="top"><a href="#match-2">match/2</a></td><td>Check if two maps match, including recursively checking nested maps.</td></tr><tr><td valign="top"><a href="#match-3">match/3</a></td><td></td></tr><tr><td valign="top"><a href="#match-4">match/4</a></td><td></td></tr><tr><td valign="top"><a href="#matchable_keys-1">matchable_keys/1*</a></td><td></td></tr><tr><td valign="top"><a href="#minimize-1">minimize/1</a></td><td>Remove keys from the map that can be regenerated.</td></tr><tr><td valign="top"><a href="#minimize-2">minimize/2*</a></td><td></td></tr><tr><td valign="top"><a href="#normalize-2">normalize/2*</a></td><td>Return a map with only the keys that necessary, without those that can
be regenerated.</td></tr><tr><td valign="top"><a href="#print-1">print/1</a></td><td>Pretty-print a message.</td></tr><tr><td valign="top"><a href="#print-2">print/2*</a></td><td></td></tr><tr><td valign="top"><a href="#restore_priv-3">restore_priv/3*</a></td><td>Add the existing <code>priv</code> sub-map back to a converted message, honoring
any existing <code>priv</code> sub-map that may already be present.</td></tr><tr><td valign="top"><a href="#signers-2">signers/2</a></td><td>Return all of the committers on a message that have 'normal', 256 bit,
addresses.</td></tr><tr><td valign="top"><a href="#to_tabm-3">to_tabm/3*</a></td><td></td></tr><tr><td valign="top"><a href="#type-1">type/1</a></td><td>Return the type of an encoded message.</td></tr><tr><td valign="top"><a href="#uncommitted-1">uncommitted/1</a></td><td>Return the unsigned version of a message in AO-Core format.</td></tr><tr><td valign="top"><a href="#uncommitted-2">uncommitted/2</a></td><td></td></tr><tr><td valign="top"><a href="#unsafe_match-5">unsafe_match/5*</a></td><td></td></tr><tr><td valign="top"><a href="#verify-1">verify/1</a></td><td>wrapper function to verify a message.</td></tr><tr><td valign="top"><a href="#verify-2">verify/2</a></td><td></td></tr><tr><td valign="top"><a href="#verify-3">verify/3</a></td><td></td></tr><tr><td valign="top"><a href="#with_commitments-3">with_commitments/3</a></td><td>Filter messages that do not match the 'spec' given.</td></tr><tr><td valign="top"><a href="#with_only_committed-2">with_only_committed/2</a></td><td>Return a message with only the committed keys.</td></tr><tr><td valign="top"><a href="#with_only_committers-2">with_only_committers/2</a></td><td>Return the message with only the specified committers attached.</td></tr><tr><td valign="top"><a href="#with_only_committers-3">with_only_committers/3</a></td><td></td></tr><tr><td valign="top"><a href="#without_commitments-3">without_commitments/3</a></td><td>Filter messages that match the 'spec' given.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="commit-2"></a>

### commit/2 ###

`commit(Msg, WalletOrOpts) -> any()`

Sign a message with the given wallet.

<a name="commit-3"></a>

### commit/3 ###

`commit(Msg, Wallet, Format) -> any()`

<a name="commitment-2"></a>

### commitment/2 ###

`commitment(Committer, Msg) -> any()`

Extract a commitment from a message given a `committer` ID, or a spec
message to match against. Returns only the first matching commitment, or
`not_found`.

<a name="commitment-3"></a>

### commitment/3 ###

`commitment(CommitterID, Msg, Opts) -> any()`

<a name="commitment_devices-2"></a>

### commitment_devices/2 ###

`commitment_devices(Msg, Opts) -> any()`

Return the devices for which there are commitments on a message.

<a name="committed-3"></a>

### committed/3 ###

`committed(Msg, List, Opts) -> any()`

Return the list of committed keys from a message.

<a name="conversion_spec_to_req-2"></a>

### conversion_spec_to_req/2 * ###

`conversion_spec_to_req(Spec, Opts) -> any()`

Get a codec device and request params from the given conversion request.
Expects conversion spec to either be a binary codec name, or a map with a
`device` key and other parameters. Additionally honors the `always_bundle`
key in the node message if present.

<a name="convert-3"></a>

### convert/3 ###

`convert(Msg, TargetFormat, Opts) -> any()`

Convert a message from one format to another. Taking a message in the
source format, a target format, and a set of opts. If not given, the source
is assumed to be `structured@1.0`. Additional codecs can be added by ensuring they
are part of the `Opts` map -- either globally, or locally for a computation.

The encoding happens in two phases:
1. Convert the message to a TABM.
2. Convert the TABM to the target format.

The conversion to a TABM is done by the `structured@1.0` codec, which is always
available. The conversion from a TABM is done by the target codec.

<a name="convert-4"></a>

### convert/4 ###

`convert(Msg, TargetFormat, SourceFormat, Opts) -> any()`

<a name="default_tx_list-0"></a>

### default_tx_list/0 ###

`default_tx_list() -> any()`

Get the ordered list of fields as AO-Core keys and default values of
the tx record.

<a name="default_tx_message-0"></a>

### default_tx_message/0 * ###

`default_tx_message() -> any()`

Get the normalized fields and default values of the tx record.

<a name="filter_default_keys-1"></a>

### filter_default_keys/1 ###

`filter_default_keys(Map) -> any()`

Remove keys from a map that have the default values found in the tx
record.

<a name="find_target-3"></a>

### find_target/3 ###

`find_target(Self, Req, Opts) -> any()`

Implements a standard pattern in which the target for an operation is
found by looking for a `target` key in the request. If the target is `self`,
or not present, the operation is performed on the original message. Otherwise,
the target is expected to be a key in the message, and the operation is
performed on the value of that key.

<a name="format-1"></a>

### format/1 ###

`format(Item) -> any()`

Format a message for printing, optionally taking an indentation level
to start from.

<a name="format-2"></a>

### format/2 ###

`format(Bin, Indent) -> any()`

<a name="from_tabm-4"></a>

### from_tabm/4 * ###

`from_tabm(Msg, TargetFormat, OldPriv, Opts) -> any()`

<a name="id-1"></a>

### id/1 ###

`id(Msg) -> any()`

Return the ID of a message.

<a name="id-2"></a>

### id/2 ###

`id(Msg, Opts) -> any()`

<a name="id-3"></a>

### id/3 ###

`id(Msg, RawCommitters, Opts) -> any()`

<a name="is_signed_key-3"></a>

### is_signed_key/3 ###

`is_signed_key(Key, Msg, Opts) -> any()`

Determine whether a specific key is part of a message's commitments.

<a name="match-2"></a>

### match/2 ###

`match(Map1, Map2) -> any()`

Check if two maps match, including recursively checking nested maps.
Takes an optional mode argument to control the matching behavior:
`strict`: All keys in both maps be present and match.
`only_present`: Only present keys in both maps must match.
`primary`: Only the primary map's keys must be present.
Returns `true` or `{ErrType, Err}`.

<a name="match-3"></a>

### match/3 ###

`match(Map1, Map2, Mode) -> any()`

<a name="match-4"></a>

### match/4 ###

`match(Map1, Map2, Mode, Opts) -> any()`

<a name="matchable_keys-1"></a>

### matchable_keys/1 * ###

`matchable_keys(Map) -> any()`

<a name="minimize-1"></a>

### minimize/1 ###

`minimize(Msg) -> any()`

Remove keys from the map that can be regenerated. Optionally takes an
additional list of keys to include in the minimization.

<a name="minimize-2"></a>

### minimize/2 * ###

`minimize(RawVal, ExtraKeys) -> any()`

<a name="normalize-2"></a>

### normalize/2 * ###

`normalize(Map, Opts) -> any()`

Return a map with only the keys that necessary, without those that can
be regenerated.

<a name="print-1"></a>

### print/1 ###

`print(Msg) -> any()`

Pretty-print a message.

<a name="print-2"></a>

### print/2 * ###

`print(Msg, Indent) -> any()`

<a name="restore_priv-3"></a>

### restore_priv/3 * ###

`restore_priv(Msg, EmptyPriv, Opts) -> any()`

Add the existing `priv` sub-map back to a converted message, honoring
any existing `priv` sub-map that may already be present.

<a name="signers-2"></a>

### signers/2 ###

`signers(Msg, Opts) -> any()`

Return all of the committers on a message that have 'normal', 256 bit,
addresses.

<a name="to_tabm-3"></a>

### to_tabm/3 * ###

`to_tabm(Msg, SourceFormat, Opts) -> any()`

<a name="type-1"></a>

### type/1 ###

`type(TX) -> any()`

Return the type of an encoded message.

<a name="uncommitted-1"></a>

### uncommitted/1 ###

`uncommitted(Msg) -> any()`

Return the unsigned version of a message in AO-Core format.

<a name="uncommitted-2"></a>

### uncommitted/2 ###

`uncommitted(Bin, Opts) -> any()`

<a name="unsafe_match-5"></a>

### unsafe_match/5 * ###

`unsafe_match(Map1, Map2, Mode, Path, Opts) -> any()`

<a name="verify-1"></a>

### verify/1 ###

`verify(Msg) -> any()`

wrapper function to verify a message.

<a name="verify-2"></a>

### verify/2 ###

`verify(Msg, Committers) -> any()`

<a name="verify-3"></a>

### verify/3 ###

`verify(Msg, Committers, Opts) -> any()`

<a name="with_commitments-3"></a>

### with_commitments/3 ###

`with_commitments(Spec, Msg, Opts) -> any()`

Filter messages that do not match the 'spec' given. The underlying match
is performed in the `only_present` mode, such that match specifications only
need to specify the keys that must be present.

<a name="with_only_committed-2"></a>

### with_only_committed/2 ###

`with_only_committed(Msg, Opts) -> any()`

Return a message with only the committed keys. If no commitments are
present, the message is returned unchanged. This means that you need to
check if the message is:
- Committed
- Verifies
...before using the output of this function as the 'canonical' message. This
is such that expensive operations like signature verification are not
performed unless necessary.

<a name="with_only_committers-2"></a>

### with_only_committers/2 ###

`with_only_committers(Msg, Committers) -> any()`

Return the message with only the specified committers attached.

<a name="with_only_committers-3"></a>

### with_only_committers/3 ###

`with_only_committers(Msg, Committers, Opts) -> any()`

<a name="without_commitments-3"></a>

### without_commitments/3 ###

`without_commitments(Spec, Msg, Opts) -> any()`

Filter messages that match the 'spec' given. Inverts the `with_commitments/2`
function, such that only messages that do _not_ match the spec are returned.


--- END OF FILE: docs/resources/source-code/hb_message.md ---

--- START OF FILE: docs/resources/source-code/hb_metrics_collector.md ---
# [Module hb_metrics_collector.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_metrics_collector.erl)




__Behaviours:__ [`prometheus_collector`](prometheus_collector.md).

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#collect_metrics-2">collect_metrics/2</a></td><td></td></tr><tr><td valign="top"><a href="#collect_mf-2">collect_mf/2</a></td><td></td></tr><tr><td valign="top"><a href="#create_gauge-3">create_gauge/3*</a></td><td></td></tr><tr><td valign="top"><a href="#deregister_cleanup-1">deregister_cleanup/1</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="collect_metrics-2"></a>

### collect_metrics/2 ###

`collect_metrics(X1, SystemLoad) -> any()`

<a name="collect_mf-2"></a>

### collect_mf/2 ###

`collect_mf(Registry, Callback) -> any()`

<a name="create_gauge-3"></a>

### create_gauge/3 * ###

`create_gauge(Name, Help, Data) -> any()`

<a name="deregister_cleanup-1"></a>

### deregister_cleanup/1 ###

`deregister_cleanup(X1) -> any()`


--- END OF FILE: docs/resources/source-code/hb_metrics_collector.md ---

--- START OF FILE: docs/resources/source-code/hb_name.md ---
# [Module hb_name.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_name.erl)




An abstraction for name registration/deregistration in HyperBEAM.

<a name="description"></a>

## Description ##
Its motivation is to provide a way to register names that are not necessarily
atoms, but can be any term (for example: hashpaths or `process@1.0` IDs).
An important characteristic of these functions is that they are atomic:
There can only ever be one registrant for a given name at a time.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#all-0">all/0</a></td><td>List the names in the registry.</td></tr><tr><td valign="top"><a href="#all_test-0">all_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#atom_test-0">atom_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#basic_test-1">basic_test/1*</a></td><td></td></tr><tr><td valign="top"><a href="#cleanup_test-0">cleanup_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#concurrency_test-0">concurrency_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#dead_process_test-0">dead_process_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#ets_lookup-1">ets_lookup/1*</a></td><td></td></tr><tr><td valign="top"><a href="#lookup-1">lookup/1</a></td><td>Lookup a name -> PID.</td></tr><tr><td valign="top"><a href="#register-1">register/1</a></td><td>Register a name.</td></tr><tr><td valign="top"><a href="#register-2">register/2</a></td><td></td></tr><tr><td valign="top"><a href="#spawn_test_workers-1">spawn_test_workers/1*</a></td><td></td></tr><tr><td valign="top"><a href="#start-0">start/0</a></td><td></td></tr><tr><td valign="top"><a href="#start_ets-0">start_ets/0*</a></td><td></td></tr><tr><td valign="top"><a href="#term_test-0">term_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#unregister-1">unregister/1</a></td><td>Unregister a name.</td></tr><tr><td valign="top"><a href="#wait_for_cleanup-2">wait_for_cleanup/2*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="all-0"></a>

### all/0 ###

`all() -> any()`

List the names in the registry.

<a name="all_test-0"></a>

### all_test/0 * ###

`all_test() -> any()`

<a name="atom_test-0"></a>

### atom_test/0 * ###

`atom_test() -> any()`

<a name="basic_test-1"></a>

### basic_test/1 * ###

`basic_test(Term) -> any()`

<a name="cleanup_test-0"></a>

### cleanup_test/0 * ###

`cleanup_test() -> any()`

<a name="concurrency_test-0"></a>

### concurrency_test/0 * ###

`concurrency_test() -> any()`

<a name="dead_process_test-0"></a>

### dead_process_test/0 * ###

`dead_process_test() -> any()`

<a name="ets_lookup-1"></a>

### ets_lookup/1 * ###

`ets_lookup(Name) -> any()`

<a name="lookup-1"></a>

### lookup/1 ###

`lookup(Name) -> any()`

Lookup a name -> PID.

<a name="register-1"></a>

### register/1 ###

`register(Name) -> any()`

Register a name. If the name is already registered, the registration
will fail. The name can be any Erlang term.

<a name="register-2"></a>

### register/2 ###

`register(Name, Pid) -> any()`

<a name="spawn_test_workers-1"></a>

### spawn_test_workers/1 * ###

`spawn_test_workers(Name) -> any()`

<a name="start-0"></a>

### start/0 ###

`start() -> any()`

<a name="start_ets-0"></a>

### start_ets/0 * ###

`start_ets() -> any()`

<a name="term_test-0"></a>

### term_test/0 * ###

`term_test() -> any()`

<a name="unregister-1"></a>

### unregister/1 ###

`unregister(Name) -> any()`

Unregister a name.

<a name="wait_for_cleanup-2"></a>

### wait_for_cleanup/2 * ###

`wait_for_cleanup(Name, Retries) -> any()`


--- END OF FILE: docs/resources/source-code/hb_name.md ---

--- START OF FILE: docs/resources/source-code/hb_opts.md ---
# [Module hb_opts.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_opts.erl)




A module for interacting with local and global options inside
HyperBEAM.

<a name="description"></a>

## Description ##

Options are set globally, but can also be overridden using an
an optional local `Opts` map argument. Many functions across the HyperBEAM
environment accept an `Opts` argument, which can be used to customize
behavior.

Options set in an `Opts` map must _never_ change the behavior of a function
that should otherwise be deterministic. Doing so may lead to loss of funds
by the HyperBEAM node operator, as the results of their executions will be
different than those of other node operators. If they are economically
staked on the correctness of these results, they may experience punishments
for non-verifiable behavior. Instead, if a local node setting makes
deterministic behavior impossible, the caller should fail the execution
with a refusal to execute.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#as-2">as/2</a></td><td>Find a given identity from the <code>identities</code> map, and return the options
merged with the sub-options for that identity.</td></tr><tr><td valign="top"><a href="#cached_os_env-2">cached_os_env/2*</a></td><td>Cache the result of os:getenv/1 in the process dictionary, as it never
changes during the lifetime of a node.</td></tr><tr><td valign="top"><a href="#check_required_opts-2">check_required_opts/2</a></td><td>Utility function to check for required options in a list.</td></tr><tr><td valign="top"><a href="#config_lookup-3">config_lookup/3*</a></td><td>An abstraction for looking up configuration variables.</td></tr><tr><td valign="top"><a href="#default_message-0">default_message/0</a></td><td>The default configuration options of the hyperbeam node.</td></tr><tr><td valign="top"><a href="#ensure_node_history-2">ensure_node_history/2</a></td><td>Ensures all items in a node history meet required configuration options.</td></tr><tr><td valign="top"><a href="#get-1">get/1</a></td><td>Get an option from the global options, optionally overriding with a
local <code>Opts</code> map if <code>prefer</code> or <code>only</code> is set to <code>local</code>.</td></tr><tr><td valign="top"><a href="#get-2">get/2</a></td><td></td></tr><tr><td valign="top"><a href="#get-3">get/3</a></td><td></td></tr><tr><td valign="top"><a href="#global_get-3">global_get/3*</a></td><td>Get an environment variable or configuration key.</td></tr><tr><td valign="top"><a href="#identities-1">identities/1</a></td><td>Find all known IDs and their sub-options from the <code>priv_ids</code> map.</td></tr><tr><td valign="top"><a href="#identities-2">identities/2*</a></td><td></td></tr><tr><td valign="top"><a href="#load-1">load/1</a></td><td>Parse a <code>flat@1.0</code> encoded file into a map, matching the types of the
keys to those in the default message.</td></tr><tr><td valign="top"><a href="#load-2">load/2</a></td><td></td></tr><tr><td valign="top"><a href="#load_bin-2">load_bin/2</a></td><td></td></tr><tr><td valign="top"><a href="#mimic_default_types-3">mimic_default_types/3</a></td><td>Mimic the types of the default message for a given map.</td></tr><tr><td valign="top"><a href="#normalize_default-1">normalize_default/1*</a></td><td>Get an option from environment variables, optionally consulting the
<code>hb_features</code> of the node if a conditional default tuple is provided.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="as-2"></a>

### as/2 ###

`as(Identity, Opts) -> any()`

Find a given identity from the `identities` map, and return the options
merged with the sub-options for that identity.

<a name="cached_os_env-2"></a>

### cached_os_env/2 * ###

`cached_os_env(Key, DefaultValue) -> any()`

Cache the result of os:getenv/1 in the process dictionary, as it never
changes during the lifetime of a node.

<a name="check_required_opts-2"></a>

### check_required_opts/2 ###

<pre><code>
check_required_opts(KeyValuePairs::[{binary(), term()}], Opts::map()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

`KeyValuePairs`: A list of {Name, Value} pairs to check.<br />`Opts`: The original options map to return if validation succeeds.<br />

returns: `{ok, Opts}` if all required options are present, or
`{error, <<"Missing required parameters: ", MissingOptsStr/binary>>}`
where `MissingOptsStr` is a comma-separated list of missing option names.

Utility function to check for required options in a list.
Takes a list of {Name, Value} pairs and returns:
- {ok, Opts} when all required options are present (Value =/= not_found)
- {error, ErrorMsg} with a message listing all missing options when any are not_found

<a name="config_lookup-3"></a>

### config_lookup/3 * ###

`config_lookup(Key, Default, Opts) -> any()`

An abstraction for looking up configuration variables. In the future,
this is the function that we will want to change to support a more dynamic
configuration system.

<a name="default_message-0"></a>

### default_message/0 ###

`default_message() -> any()`

The default configuration options of the hyperbeam node.

<a name="ensure_node_history-2"></a>

### ensure_node_history/2 ###

<pre><code>
ensure_node_history(NodeHistory::list() | term(), RequiredOpts::map()) -&gt; {ok, binary()} | {error, binary()}
</code></pre>
<br />

`RequiredOpts`: A map of options that must be present and unchanging<br />

returns: 
`{ok, <<"valid">>}` when validation passes
`{error, <<"missing_keys">>}` when required keys are missing from first item
`{error, <<"invalid_values">>}` when first item values don't match requirements
`{error, <<"modified_required_key">>}` when history items modify required keys
`{error, <<"validation_failed">>}` when other validation errors occur

Ensures all items in a node history meet required configuration options.

This function verifies that the first item (complete opts) contains all required
configuration options and that their values match the expected format. Then it
validates that subsequent history items (which represent differences) never
modify any of the required keys from the first item.

Validation is performed in two steps:
1. Checks that the first item has all required keys and valid values
2. Verifies that subsequent items don't modify any required keys from the first item

<a name="get-1"></a>

### get/1 ###

`get(Key) -> any()`

Get an option from the global options, optionally overriding with a
local `Opts` map if `prefer` or `only` is set to `local`. If the `only`
option is provided in the `local` map, only keys found in the corresponding
(`local` or `global`) map will be returned. This function also offers users
a way to specify a default value to return if the option is not set.

`prefer` defaults to `local`.

<a name="get-2"></a>

### get/2 ###

`get(Key, Default) -> any()`

<a name="get-3"></a>

### get/3 ###

`get(Key, Default, Opts) -> any()`

<a name="global_get-3"></a>

### global_get/3 * ###

`global_get(Key, Default, Opts) -> any()`

Get an environment variable or configuration key.

<a name="identities-1"></a>

### identities/1 ###

`identities(Opts) -> any()`

Find all known IDs and their sub-options from the `priv_ids` map. Allows
the identities to be named, or based on addresses. The results are normalized
such that the map returned by this function contains both mechanisms for
finding an identity and its sub-options. Additionally, sub-options are also
normalized such that the `address` property is present and accurate for all
given identities.

<a name="identities-2"></a>

### identities/2 * ###

`identities(Default, Opts) -> any()`

<a name="load-1"></a>

### load/1 ###

`load(Path) -> any()`

Parse a `flat@1.0` encoded file into a map, matching the types of the
keys to those in the default message.

<a name="load-2"></a>

### load/2 ###

`load(Path, Opts) -> any()`

<a name="load_bin-2"></a>

### load_bin/2 ###

`load_bin(Bin, Opts) -> any()`

<a name="mimic_default_types-3"></a>

### mimic_default_types/3 ###

`mimic_default_types(Map, Mode, Opts) -> any()`

Mimic the types of the default message for a given map.

<a name="normalize_default-1"></a>

### normalize_default/1 * ###

`normalize_default(Default) -> any()`

Get an option from environment variables, optionally consulting the
`hb_features` of the node if a conditional default tuple is provided.


--- END OF FILE: docs/resources/source-code/hb_opts.md ---

--- START OF FILE: docs/resources/source-code/hb_path.md ---
# [Module hb_path.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_path.erl)




This module provides utilities for manipulating the paths of a
message: Its request path (referred to in messages as just the `Path`), and
its HashPath.

<a name="description"></a>

## Description ##

A HashPath is a rolling Merkle list of the messages that have been applied
in order to generate a given message. Because applied messages can
themselves be the result of message applications with the AO-Core protocol,
the HashPath can be thought of as the tree of messages that represent the
history of a given message. The initial message on a HashPath is referred to
by its ID and serves as its user-generated 'root'.

Specifically, the HashPath can be generated by hashing the previous HashPath
and the current message. This means that each message in the HashPath is
dependent on all previous messages.

```

       Msg1.HashPath = Msg1.ID
       Msg3.HashPath = Msg1.Hash(Msg1.HashPath, Msg2.ID)
       Msg3.{...} = AO-Core.apply(Msg1, Msg2)
       ...
```

A message's ID itself includes its HashPath, leading to the mixing of
a Msg2's merkle list into the resulting Msg3's HashPath. This allows a single
message to represent a history _tree_ of all of the messages that were
applied to generate it -- rather than just a linear history.

A message may also specify its own algorithm for generating its HashPath,
which allows for custom logic to be used for representing the history of a
message. When Msg2's are applied to a Msg1, the resulting Msg3's HashPath
will be generated according to Msg1's algorithm choice.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#do_to_binary-1">do_to_binary/1*</a></td><td></td></tr><tr><td valign="top"><a href="#from_message-3">from_message/3</a></td><td>Extract the request path or hashpath from a message.</td></tr><tr><td valign="top"><a href="#hashpath-2">hashpath/2</a></td><td>Add an ID of a Msg2 to the HashPath of another message.</td></tr><tr><td valign="top"><a href="#hashpath-3">hashpath/3</a></td><td></td></tr><tr><td valign="top"><a href="#hashpath-4">hashpath/4</a></td><td></td></tr><tr><td valign="top"><a href="#hashpath_alg-2">hashpath_alg/2</a></td><td>Get the hashpath function for a message from its HashPath-Alg.</td></tr><tr><td valign="top"><a href="#hashpath_direct_msg2_test-0">hashpath_direct_msg2_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#hashpath_test-0">hashpath_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#hd-2">hd/2</a></td><td>Extract the first key from a <code>Message2</code>'s <code>Path</code> field.</td></tr><tr><td valign="top"><a href="#hd_test-0">hd_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#matches-2">matches/2</a></td><td>Check if two keys match.</td></tr><tr><td valign="top"><a href="#multiple_hashpaths_test-0">multiple_hashpaths_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#normalize-1">normalize/1</a></td><td>Normalize a path to a binary, removing the leading slash if present.</td></tr><tr><td valign="top"><a href="#pop_from_message_test-0">pop_from_message_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#pop_from_path_list_test-0">pop_from_path_list_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#pop_request-2">pop_request/2</a></td><td>Pop the next element from a request path or path list.</td></tr><tr><td valign="top"><a href="#priv_remaining-2">priv_remaining/2</a></td><td>Return the <code>Remaining-Path</code> of a message, from its hidden <code>AO-Core</code>
key.</td></tr><tr><td valign="top"><a href="#priv_store_remaining-2">priv_store_remaining/2</a></td><td>Store the remaining path of a message in its hidden <code>AO-Core</code> key.</td></tr><tr><td valign="top"><a href="#priv_store_remaining-3">priv_store_remaining/3</a></td><td></td></tr><tr><td valign="top"><a href="#push_request-2">push_request/2</a></td><td>Add a message to the head (next to execute) of a request path.</td></tr><tr><td valign="top"><a href="#push_request-3">push_request/3</a></td><td></td></tr><tr><td valign="top"><a href="#queue_request-2">queue_request/2</a></td><td>Queue a message at the back of a request path.</td></tr><tr><td valign="top"><a href="#queue_request-3">queue_request/3</a></td><td></td></tr><tr><td valign="top"><a href="#regex_matches-2">regex_matches/2</a></td><td>Check if two keys match using regex.</td></tr><tr><td valign="top"><a href="#regex_matches_test-0">regex_matches_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#term_to_path_parts-1">term_to_path_parts/1</a></td><td>Convert a term into an executable path.</td></tr><tr><td valign="top"><a href="#term_to_path_parts-2">term_to_path_parts/2</a></td><td></td></tr><tr><td valign="top"><a href="#term_to_path_parts_test-0">term_to_path_parts_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#tl-2">tl/2</a></td><td>Return the message without its first path element.</td></tr><tr><td valign="top"><a href="#tl_test-0">tl_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to_binary-1">to_binary/1</a></td><td>Convert a path of any form to a binary.</td></tr><tr><td valign="top"><a href="#to_binary_test-0">to_binary_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#validate_path_transitions-2">validate_path_transitions/2*</a></td><td></td></tr><tr><td valign="top"><a href="#verify_hashpath-2">verify_hashpath/2</a></td><td>Verify the HashPath of a message, given a list of messages that
represent its history.</td></tr><tr><td valign="top"><a href="#verify_hashpath_test-0">verify_hashpath_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="do_to_binary-1"></a>

### do_to_binary/1 * ###

`do_to_binary(Path) -> any()`

<a name="from_message-3"></a>

### from_message/3 ###

`from_message(Type, Link, Opts) -> any()`

Extract the request path or hashpath from a message. We do not use
AO-Core for this resolution because this function is called from inside AO-Core
itself. This imparts a requirement: the message's device must store a
viable hashpath and path in its Erlang map at all times, unless the message
is directly from a user (in which case paths and hashpaths will not have
been assigned yet).

<a name="hashpath-2"></a>

### hashpath/2 ###

`hashpath(Bin, Opts) -> any()`

Add an ID of a Msg2 to the HashPath of another message.

<a name="hashpath-3"></a>

### hashpath/3 ###

`hashpath(Msg1, Msg2, Opts) -> any()`

<a name="hashpath-4"></a>

### hashpath/4 ###

`hashpath(Msg1, Msg2, HashpathAlg, Opts) -> any()`

<a name="hashpath_alg-2"></a>

### hashpath_alg/2 ###

`hashpath_alg(Msg, Opts) -> any()`

Get the hashpath function for a message from its HashPath-Alg.
If no hashpath algorithm is specified, the protocol defaults to
`sha-256-chain`.

<a name="hashpath_direct_msg2_test-0"></a>

### hashpath_direct_msg2_test/0 * ###

`hashpath_direct_msg2_test() -> any()`

<a name="hashpath_test-0"></a>

### hashpath_test/0 * ###

`hashpath_test() -> any()`

<a name="hd-2"></a>

### hd/2 ###

`hd(Msg2, Opts) -> any()`

Extract the first key from a `Message2`'s `Path` field.
Note: This function uses the `dev_message:get/2` function, rather than
a generic call as the path should always be an explicit key in the message.

<a name="hd_test-0"></a>

### hd_test/0 * ###

`hd_test() -> any()`

<a name="matches-2"></a>

### matches/2 ###

`matches(Key1, Key2) -> any()`

Check if two keys match.

<a name="multiple_hashpaths_test-0"></a>

### multiple_hashpaths_test/0 * ###

`multiple_hashpaths_test() -> any()`

<a name="normalize-1"></a>

### normalize/1 ###

`normalize(Path) -> any()`

Normalize a path to a binary, removing the leading slash if present.

<a name="pop_from_message_test-0"></a>

### pop_from_message_test/0 * ###

`pop_from_message_test() -> any()`

<a name="pop_from_path_list_test-0"></a>

### pop_from_path_list_test/0 * ###

`pop_from_path_list_test() -> any()`

<a name="pop_request-2"></a>

### pop_request/2 ###

`pop_request(Msg, Opts) -> any()`

Pop the next element from a request path or path list.

<a name="priv_remaining-2"></a>

### priv_remaining/2 ###

`priv_remaining(Msg, Opts) -> any()`

Return the `Remaining-Path` of a message, from its hidden `AO-Core`
key. Does not use the `get` or set `hb_private` functions, such that it
can be safely used inside the main AO-Core resolve function.

<a name="priv_store_remaining-2"></a>

### priv_store_remaining/2 ###

`priv_store_remaining(Msg, RemainingPath) -> any()`

Store the remaining path of a message in its hidden `AO-Core` key.

<a name="priv_store_remaining-3"></a>

### priv_store_remaining/3 ###

`priv_store_remaining(Msg, RemainingPath, Opts) -> any()`

<a name="push_request-2"></a>

### push_request/2 ###

`push_request(Msg, Path) -> any()`

Add a message to the head (next to execute) of a request path.

<a name="push_request-3"></a>

### push_request/3 ###

`push_request(Msg, Path, Opts) -> any()`

<a name="queue_request-2"></a>

### queue_request/2 ###

`queue_request(Msg, Path) -> any()`

Queue a message at the back of a request path. `path` is the only
key that we cannot use dev_message's `set/3` function for (as it expects
the compute path to be there), so we use `hb_maps:put/3` instead.

<a name="queue_request-3"></a>

### queue_request/3 ###

`queue_request(Msg, Path, Opts) -> any()`

<a name="regex_matches-2"></a>

### regex_matches/2 ###

`regex_matches(Path1, Path2) -> any()`

Check if two keys match using regex.

<a name="regex_matches_test-0"></a>

### regex_matches_test/0 * ###

`regex_matches_test() -> any()`

<a name="term_to_path_parts-1"></a>

### term_to_path_parts/1 ###

`term_to_path_parts(Path) -> any()`

Convert a term into an executable path. Supports binaries, lists, and
atoms. Notably, it does not support strings as lists of characters.

<a name="term_to_path_parts-2"></a>

### term_to_path_parts/2 ###

`term_to_path_parts(Link, Opts) -> any()`

<a name="term_to_path_parts_test-0"></a>

### term_to_path_parts_test/0 * ###

`term_to_path_parts_test() -> any()`

<a name="tl-2"></a>

### tl/2 ###

`tl(Msg2, Opts) -> any()`

Return the message without its first path element. Note that this
is the only transformation in AO-Core that does _not_ make a log of its
transformation. Subsequently, the message's IDs will not be verifiable
after executing this transformation.
This may or may not be the mainnet behavior we want.

<a name="tl_test-0"></a>

### tl_test/0 * ###

`tl_test() -> any()`

<a name="to_binary-1"></a>

### to_binary/1 ###

`to_binary(Path) -> any()`

Convert a path of any form to a binary.

<a name="to_binary_test-0"></a>

### to_binary_test/0 * ###

`to_binary_test() -> any()`

<a name="validate_path_transitions-2"></a>

### validate_path_transitions/2 * ###

`validate_path_transitions(X, Opts) -> any()`

<a name="verify_hashpath-2"></a>

### verify_hashpath/2 ###

`verify_hashpath(Rest, Opts) -> any()`

Verify the HashPath of a message, given a list of messages that
represent its history.

<a name="verify_hashpath_test-0"></a>

### verify_hashpath_test/0 * ###

`verify_hashpath_test() -> any()`


--- END OF FILE: docs/resources/source-code/hb_path.md ---

--- START OF FILE: docs/resources/source-code/hb_persistent.md ---
# [Module hb_persistent.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_persistent.erl)




Creates and manages long-lived AO-Core resolution processes.

<a name="description"></a>

## Description ##

These can be useful for situations where a message is large and expensive
to serialize and deserialize, or when executions should be deliberately
serialized to avoid parallel executions of the same computation. This
module is called during the core `hb_ao` execution process, so care
must be taken to avoid recursive spawns/loops.

Built using the `pg` module, which is a distributed Erlang process group
manager.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#await-4">await/4</a></td><td>If there was already an Erlang process handling this execution,
we should register with them and wait for them to notify us of
completion.</td></tr><tr><td valign="top"><a href="#deduplicated_execution_test-0">deduplicated_execution_test/0*</a></td><td>Test merging and returning a value with a persistent worker.</td></tr><tr><td valign="top"><a href="#default_await-5">default_await/5</a></td><td>Default await function that waits for a resolution from a worker.</td></tr><tr><td valign="top"><a href="#default_grouper-3">default_grouper/3</a></td><td>Create a group name from a Msg1 and Msg2 pair as a tuple.</td></tr><tr><td valign="top"><a href="#default_worker-3">default_worker/3</a></td><td>A server function for handling persistent executions.</td></tr><tr><td valign="top"><a href="#do_monitor-3">do_monitor/3*</a></td><td></td></tr><tr><td valign="top"><a href="#find_execution-2">find_execution/2*</a></td><td>Find a group with the given name.</td></tr><tr><td valign="top"><a href="#find_or_register-3">find_or_register/3</a></td><td>Register the process to lead an execution if none is found, otherwise
signal that we should await resolution.</td></tr><tr><td valign="top"><a href="#find_or_register-4">find_or_register/4*</a></td><td></td></tr><tr><td valign="top"><a href="#forward_work-2">forward_work/2</a></td><td>Forward requests to a newly delegated execution process.</td></tr><tr><td valign="top"><a href="#group-3">group/3</a></td><td>Calculate the group name for a Msg1 and Msg2 pair.</td></tr><tr><td valign="top"><a href="#notify-4">notify/4</a></td><td>Check our inbox for processes that are waiting for the resolution
of this execution.</td></tr><tr><td valign="top"><a href="#persistent_worker_test-0">persistent_worker_test/0*</a></td><td>Test spawning a default persistent worker.</td></tr><tr><td valign="top"><a href="#register_groupname-2">register_groupname/2*</a></td><td>Register for performing an AO-Core resolution.</td></tr><tr><td valign="top"><a href="#send_response-4">send_response/4*</a></td><td>Helper function that wraps responding with a new Msg3.</td></tr><tr><td valign="top"><a href="#spawn_after_execution_test-0">spawn_after_execution_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#spawn_test_client-2">spawn_test_client/2*</a></td><td></td></tr><tr><td valign="top"><a href="#spawn_test_client-3">spawn_test_client/3*</a></td><td></td></tr><tr><td valign="top"><a href="#start-0">start/0*</a></td><td>Ensure that the <code>pg</code> module is started.</td></tr><tr><td valign="top"><a href="#start_monitor-0">start_monitor/0</a></td><td>Start a monitor that prints the current members of the group every
n seconds.</td></tr><tr><td valign="top"><a href="#start_monitor-1">start_monitor/1</a></td><td></td></tr><tr><td valign="top"><a href="#start_monitor-2">start_monitor/2*</a></td><td></td></tr><tr><td valign="top"><a href="#start_worker-2">start_worker/2</a></td><td>Start a worker process that will hold a message in memory for
future executions.</td></tr><tr><td valign="top"><a href="#start_worker-3">start_worker/3</a></td><td></td></tr><tr><td valign="top"><a href="#stop_monitor-1">stop_monitor/1</a></td><td></td></tr><tr><td valign="top"><a href="#test_device-0">test_device/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_device-1">test_device/1*</a></td><td></td></tr><tr><td valign="top"><a href="#unregister-3">unregister/3*</a></td><td>Unregister for being the leader on an AO-Core resolution.</td></tr><tr><td valign="top"><a href="#unregister_groupname-2">unregister_groupname/2*</a></td><td></td></tr><tr><td valign="top"><a href="#unregister_notify-4">unregister_notify/4</a></td><td>Unregister as the leader for an execution and notify waiting processes.</td></tr><tr><td valign="top"><a href="#wait_for_test_result-1">wait_for_test_result/1*</a></td><td></td></tr><tr><td valign="top"><a href="#worker_event-5">worker_event/5*</a></td><td>Log an event with the worker process.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="await-4"></a>

### await/4 ###

`await(Worker, Msg1, Msg2, Opts) -> any()`

If there was already an Erlang process handling this execution,
we should register with them and wait for them to notify us of
completion.

<a name="deduplicated_execution_test-0"></a>

### deduplicated_execution_test/0 * ###

`deduplicated_execution_test() -> any()`

Test merging and returning a value with a persistent worker.

<a name="default_await-5"></a>

### default_await/5 ###

`default_await(Worker, GroupName, Msg1, Msg2, Opts) -> any()`

Default await function that waits for a resolution from a worker.

<a name="default_grouper-3"></a>

### default_grouper/3 ###

`default_grouper(Msg1, Msg2, Opts) -> any()`

Create a group name from a Msg1 and Msg2 pair as a tuple.

<a name="default_worker-3"></a>

### default_worker/3 ###

`default_worker(GroupName, Msg1, Opts) -> any()`

A server function for handling persistent executions.

<a name="do_monitor-3"></a>

### do_monitor/3 * ###

`do_monitor(Group, Last, Opts) -> any()`

<a name="find_execution-2"></a>

### find_execution/2 * ###

`find_execution(Groupname, Opts) -> any()`

Find a group with the given name.

<a name="find_or_register-3"></a>

### find_or_register/3 ###

`find_or_register(Msg1, Msg2, Opts) -> any()`

Register the process to lead an execution if none is found, otherwise
signal that we should await resolution.

<a name="find_or_register-4"></a>

### find_or_register/4 * ###

`find_or_register(GroupName, Msg1, Msg2, Opts) -> any()`

<a name="forward_work-2"></a>

### forward_work/2 ###

`forward_work(NewPID, Opts) -> any()`

Forward requests to a newly delegated execution process.

<a name="group-3"></a>

### group/3 ###

`group(Msg1, Msg2, Opts) -> any()`

Calculate the group name for a Msg1 and Msg2 pair. Uses the Msg1's
`group` function if it is found in the `info`, otherwise uses the default.

<a name="notify-4"></a>

### notify/4 ###

`notify(GroupName, Msg2, Msg3, Opts) -> any()`

Check our inbox for processes that are waiting for the resolution
of this execution. Comes in two forms:
1. Notify on group name alone.
2. Notify on group name and Msg2.

<a name="persistent_worker_test-0"></a>

### persistent_worker_test/0 * ###

`persistent_worker_test() -> any()`

Test spawning a default persistent worker.

<a name="register_groupname-2"></a>

### register_groupname/2 * ###

`register_groupname(Groupname, Opts) -> any()`

Register for performing an AO-Core resolution.

<a name="send_response-4"></a>

### send_response/4 * ###

`send_response(Listener, GroupName, Msg2, Msg3) -> any()`

Helper function that wraps responding with a new Msg3.

<a name="spawn_after_execution_test-0"></a>

### spawn_after_execution_test/0 * ###

`spawn_after_execution_test() -> any()`

<a name="spawn_test_client-2"></a>

### spawn_test_client/2 * ###

`spawn_test_client(Msg1, Msg2) -> any()`

<a name="spawn_test_client-3"></a>

### spawn_test_client/3 * ###

`spawn_test_client(Msg1, Msg2, Opts) -> any()`

<a name="start-0"></a>

### start/0 * ###

`start() -> any()`

Ensure that the `pg` module is started.

<a name="start_monitor-0"></a>

### start_monitor/0 ###

`start_monitor() -> any()`

Start a monitor that prints the current members of the group every
n seconds.

<a name="start_monitor-1"></a>

### start_monitor/1 ###

`start_monitor(Group) -> any()`

<a name="start_monitor-2"></a>

### start_monitor/2 * ###

`start_monitor(Group, Opts) -> any()`

<a name="start_worker-2"></a>

### start_worker/2 ###

`start_worker(Msg, Opts) -> any()`

Start a worker process that will hold a message in memory for
future executions.

<a name="start_worker-3"></a>

### start_worker/3 ###

`start_worker(GroupName, NotMsg, Opts) -> any()`

<a name="stop_monitor-1"></a>

### stop_monitor/1 ###

`stop_monitor(PID) -> any()`

<a name="test_device-0"></a>

### test_device/0 * ###

`test_device() -> any()`

<a name="test_device-1"></a>

### test_device/1 * ###

`test_device(Base) -> any()`

<a name="unregister-3"></a>

### unregister/3 * ###

`unregister(Msg1, Msg2, Opts) -> any()`

Unregister for being the leader on an AO-Core resolution.

<a name="unregister_groupname-2"></a>

### unregister_groupname/2 * ###

`unregister_groupname(Groupname, Opts) -> any()`

<a name="unregister_notify-4"></a>

### unregister_notify/4 ###

`unregister_notify(GroupName, Msg2, Msg3, Opts) -> any()`

Unregister as the leader for an execution and notify waiting processes.

<a name="wait_for_test_result-1"></a>

### wait_for_test_result/1 * ###

`wait_for_test_result(Ref) -> any()`

<a name="worker_event-5"></a>

### worker_event/5 * ###

`worker_event(Group, Data, Msg1, Msg2, Opts) -> any()`

Log an event with the worker process. If we used the default grouper
function, we should also include the Msg1 and Msg2 in the event. If we did not,
we assume that the group name expresses enough information to identify the
request.


--- END OF FILE: docs/resources/source-code/hb_persistent.md ---

--- START OF FILE: docs/resources/source-code/hb_private.md ---
# [Module hb_private.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_private.erl)




This module provides basic helper utilities for managing the
private element of a message, which can be used to store state that is
not included in serialized messages, or those granted to users via the
APIs.

<a name="description"></a>

## Description ##

Private elements of a message can be useful for storing state that
is only relevant temporarily. For example, a device might use the private
element to store a cache of values that are expensive to recompute. They
should _not_ be used for encoding state that makes the execution of a
device non-deterministic (unless you are sure you know what you are doing).

The `set` and `get` functions of this module allow you to run those keys
as AO-Core paths if you would like to have private `devices` in the
messages non-public zone.

See `hb_ao` for more information about the AO-Core protocol
and private elements of messages.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#from_message-1">from_message/1</a></td><td>Return the <code>private</code> key from a message.</td></tr><tr><td valign="top"><a href="#get-3">get/3</a></td><td>Helper for getting a value from the private element of a message.</td></tr><tr><td valign="top"><a href="#get-4">get/4</a></td><td></td></tr><tr><td valign="top"><a href="#get_private_key_test-0">get_private_key_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#is_private-1">is_private/1</a></td><td>Check if a key is private.</td></tr><tr><td valign="top"><a href="#priv_ao_opts-1">priv_ao_opts/1*</a></td><td>The opts map that should be used when resolving paths against the
private element of a message.</td></tr><tr><td valign="top"><a href="#remove_private_specifier-2">remove_private_specifier/2*</a></td><td>Remove the first key from the path if it is a private specifier.</td></tr><tr><td valign="top"><a href="#reset-1">reset/1</a></td><td>Unset all of the private keys in a message.</td></tr><tr><td valign="top"><a href="#set-3">set/3</a></td><td></td></tr><tr><td valign="top"><a href="#set-4">set/4</a></td><td>Helper function for setting a key in the private element of a message.</td></tr><tr><td valign="top"><a href="#set_priv-2">set_priv/2</a></td><td>Helper function for setting the complete private element of a message.</td></tr><tr><td valign="top"><a href="#set_private_test-0">set_private_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="from_message-1"></a>

### from_message/1 ###

`from_message(Msg) -> any()`

Return the `private` key from a message. If the key does not exist, an
empty map is returned.

<a name="get-3"></a>

### get/3 ###

`get(Key, Msg, Opts) -> any()`

Helper for getting a value from the private element of a message. Uses
AO-Core resolve under-the-hood, removing the private specifier from the
path if it exists.

<a name="get-4"></a>

### get/4 ###

`get(InputPath, Msg, Default, Opts) -> any()`

<a name="get_private_key_test-0"></a>

### get_private_key_test/0 * ###

`get_private_key_test() -> any()`

<a name="is_private-1"></a>

### is_private/1 ###

`is_private(Key) -> any()`

Check if a key is private.

<a name="priv_ao_opts-1"></a>

### priv_ao_opts/1 * ###

`priv_ao_opts(Opts) -> any()`

The opts map that should be used when resolving paths against the
private element of a message.

<a name="remove_private_specifier-2"></a>

### remove_private_specifier/2 * ###

`remove_private_specifier(InputPath, Opts) -> any()`

Remove the first key from the path if it is a private specifier.

<a name="reset-1"></a>

### reset/1 ###

`reset(Msg) -> any()`

Unset all of the private keys in a message.

<a name="set-3"></a>

### set/3 ###

`set(Msg, PrivMap, Opts) -> any()`

<a name="set-4"></a>

### set/4 ###

`set(Msg, InputPath, Value, Opts) -> any()`

Helper function for setting a key in the private element of a message.

<a name="set_priv-2"></a>

### set_priv/2 ###

`set_priv(Msg, PrivMap) -> any()`

Helper function for setting the complete private element of a message.

<a name="set_private_test-0"></a>

### set_private_test/0 * ###

`set_private_test() -> any()`


--- END OF FILE: docs/resources/source-code/hb_private.md ---

--- START OF FILE: docs/resources/source-code/hb_process_monitor.md ---
# [Module hb_process_monitor.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_process_monitor.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#handle_crons-1">handle_crons/1*</a></td><td></td></tr><tr><td valign="top"><a href="#server-1">server/1*</a></td><td></td></tr><tr><td valign="top"><a href="#start-1">start/1</a></td><td></td></tr><tr><td valign="top"><a href="#start-2">start/2</a></td><td></td></tr><tr><td valign="top"><a href="#start-3">start/3</a></td><td></td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td></td></tr><tr><td valign="top"><a href="#ticker-2">ticker/2*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="handle_crons-1"></a>

### handle_crons/1 * ###

`handle_crons(State) -> any()`

<a name="server-1"></a>

### server/1 * ###

`server(State) -> any()`

<a name="start-1"></a>

### start/1 ###

`start(ProcID) -> any()`

<a name="start-2"></a>

### start/2 ###

`start(ProcID, Rate) -> any()`

<a name="start-3"></a>

### start/3 ###

`start(ProcID, Rate, Cursor) -> any()`

<a name="stop-1"></a>

### stop/1 ###

`stop(PID) -> any()`

<a name="ticker-2"></a>

### ticker/2 * ###

`ticker(Monitor, Rate) -> any()`


--- END OF FILE: docs/resources/source-code/hb_process_monitor.md ---

--- START OF FILE: docs/resources/source-code/hb_router.md ---
# [Module hb_router.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_router.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#find-2">find/2</a></td><td></td></tr><tr><td valign="top"><a href="#find-3">find/3</a></td><td></td></tr><tr><td valign="top"><a href="#find-4">find/4*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="find-2"></a>

### find/2 ###

`find(Type, ID) -> any()`

<a name="find-3"></a>

### find/3 ###

`find(Type, ID, Address) -> any()`

<a name="find-4"></a>

### find/4 * ###

`find(Type, ID, Address, Opts) -> any()`


--- END OF FILE: docs/resources/source-code/hb_router.md ---

--- START OF FILE: docs/resources/source-code/hb_singleton.md ---
# [Module hb_singleton.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_singleton.erl)




A parser that translates AO-Core HTTP API requests in TABM format
into an ordered list of messages to evaluate.

<a name="description"></a>

## Description ##

The details of this format
are described in `docs/ao-core-http-api.md`.

Syntax overview:

```

       Singleton: Message containing keys and a <code>path</code> field,
                  which may also contain a query string of key-value pairs.
       Path:
           - /Part1/Part2/.../PartN/ => [Part1, Part2, ..., PartN]
           - /ID/Part2/.../PartN => [ID, Part2, ..., PartN]
       Part: (Key + Resolution), Device?, #{ K => V}?
           - Part => #{ path => Part }
           - <code>Part&Key=Value => #{ path => Part, Key => Value }</code>
           - <code>Part&Key => #{ path => Part, Key => true }</code>
           - <code>Part&k1=v1&k2=v2 => #{ path => Part, k1 => `<<"v1">></code>, k2 => <code><<"v2">></code> }'
           - <code>Part~Device => {as, Device, #{ path => Part }}</code>
           - <code>Part~D&K1=V1 => {as, D, #{ path => Part, K1 => `<<"v1">></code> }}'
           - <code>pt&k1+int=1 => #{ path => pt, k1 => 1 }</code>
           - <code>pt~d&k1+int=1 => {as, d, #{ path => pt, k1 => 1 }}</code>
           - <code>(/nested/path) => Resolution of the path /nested/path</code>
           - <code>(/nested/path&k1=v1) => (resolve /nested/path)#{k1 => v1}</code>
           - <code>(/nested/path~D&K1=V1) => (resolve /nested/path)#{K1 => V1}</code>
           - <code>pt&k1+res=(/a/b/c) => #{ path => pt, k1 => (resolve /a/b/c) }</code>
       Key:
           - key: <code><<"value">></code> => #{ key => <code><<"value">></code>, ... } for all messages
           - n.key: <code><<"value">></code> => #{ key => <code><<"value">></code>, ... } for Nth message
           - key+int: 1 => #{ key => 1, ... }
           - key+res: /nested/path => #{ key => (resolve /nested/path), ... }
           - N.Key+res=(/a/b/c) => #{ Key => (resolve /a/b/c), ... }
```

<a name="types"></a>

## Data Types ##




### <a name="type-ao_message">ao_message()</a> ###


<pre><code>
ao_message() = map() | binary()
</code></pre>




### <a name="type-tabm_message">tabm_message()</a> ###


<pre><code>
tabm_message() = map()
</code></pre>

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#all_path_parts-2">all_path_parts/2*</a></td><td>Extract all of the parts from the binary, given (a list of) separators.</td></tr><tr><td valign="top"><a href="#append_path-2">append_path/2*</a></td><td></td></tr><tr><td valign="top"><a href="#apply_types-2">apply_types/2*</a></td><td>Step 3: Apply types to values and remove specifiers.</td></tr><tr><td valign="top"><a href="#basic_hashpath_test-0">basic_hashpath_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#basic_hashpath_to_test-0">basic_hashpath_to_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#build_messages-3">build_messages/3*</a></td><td>Step 5: Merge the base message with the scoped messages.</td></tr><tr><td valign="top"><a href="#decode_string-1">decode_string/1*</a></td><td>Attempt Cowboy URL decode, then sanitize the result.</td></tr><tr><td valign="top"><a href="#do_build-4">do_build/4*</a></td><td></td></tr><tr><td valign="top"><a href="#from-2">from/2</a></td><td>Normalize a singleton TABM message into a list of executable AO-Core
messages.</td></tr><tr><td valign="top"><a href="#group_scoped-2">group_scoped/2*</a></td><td>Step 4: Group headers/query by N-scope.</td></tr><tr><td valign="top"><a href="#inlined_keys_test-0">inlined_keys_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#inlined_keys_to_test-0">inlined_keys_to_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_join-2">maybe_join/2*</a></td><td>Join a list of items with a separator, or return the first item if there
is only one item.</td></tr><tr><td valign="top"><a href="#maybe_subpath-2">maybe_subpath/2*</a></td><td>Check if the string is a subpath, returning it in parsed form,
or the original string with a specifier.</td></tr><tr><td valign="top"><a href="#maybe_typed-3">maybe_typed/3*</a></td><td>Parse a key's type (applying it to the value) and device name if present.</td></tr><tr><td valign="top"><a href="#multiple_inlined_keys_test-0">multiple_inlined_keys_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#multiple_inlined_keys_to_test-0">multiple_inlined_keys_to_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#multiple_messages_test-0">multiple_messages_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#multiple_messages_to_test-0">multiple_messages_to_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#normalize_base-1">normalize_base/1*</a></td><td>Normalize the base path.</td></tr><tr><td valign="top"><a href="#parse_explicit_message_test-0">parse_explicit_message_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_full_path-1">parse_full_path/1*</a></td><td>Parse the relative reference into path, query, and fragment.</td></tr><tr><td valign="top"><a href="#parse_inlined_key_val-2">parse_inlined_key_val/2*</a></td><td>Extrapolate the inlined key-value pair from a path segment.</td></tr><tr><td valign="top"><a href="#parse_part-2">parse_part/2*</a></td><td>Parse a path part into a message or an ID.</td></tr><tr><td valign="top"><a href="#parse_part_mods-3">parse_part_mods/3*</a></td><td>Parse part modifiers:
1.</td></tr><tr><td valign="top"><a href="#parse_scope-1">parse_scope/1*</a></td><td>Get the scope of a key.</td></tr><tr><td valign="top"><a href="#part-2">part/2*</a></td><td>Extract the characters from the binary until a separator is found.</td></tr><tr><td valign="top"><a href="#part-4">part/4*</a></td><td></td></tr><tr><td valign="top"><a href="#path_messages-2">path_messages/2*</a></td><td>Step 2: Decode, split and sanitize the path.</td></tr><tr><td valign="top"><a href="#path_parts-2">path_parts/2*</a></td><td>Split the path into segments, filtering out empty segments and
segments that are too long.</td></tr><tr><td valign="top"><a href="#path_parts_test-0">path_parts_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#scoped_key_test-0">scoped_key_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#scoped_key_to_test-0">scoped_key_to_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#simple_to_test-0">simple_to_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#single_message_test-0">single_message_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#subpath_in_inlined_test-0">subpath_in_inlined_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#subpath_in_inlined_to_test-0">subpath_in_inlined_to_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#subpath_in_key_test-0">subpath_in_key_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#subpath_in_key_to_test-0">subpath_in_key_to_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#subpath_in_path_test-0">subpath_in_path_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#subpath_in_path_to_test-0">subpath_in_path_to_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to-1">to/1</a></td><td>Convert a list of AO-Core message into TABM message.</td></tr><tr><td valign="top"><a href="#to_suite_test_-0">to_suite_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#type-1">type/1*</a></td><td></td></tr><tr><td valign="top"><a href="#typed_key_test-0">typed_key_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#typed_key_to_test-0">typed_key_to_test/0*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="all_path_parts-2"></a>

### all_path_parts/2 * ###

`all_path_parts(Sep, Bin) -> any()`

Extract all of the parts from the binary, given (a list of) separators.

<a name="append_path-2"></a>

### append_path/2 * ###

`append_path(PathPart, Message) -> any()`

<a name="apply_types-2"></a>

### apply_types/2 * ###

`apply_types(Msg, Opts) -> any()`

Step 3: Apply types to values and remove specifiers.

<a name="basic_hashpath_test-0"></a>

### basic_hashpath_test/0 * ###

`basic_hashpath_test() -> any()`

<a name="basic_hashpath_to_test-0"></a>

### basic_hashpath_to_test/0 * ###

`basic_hashpath_to_test() -> any()`

<a name="build_messages-3"></a>

### build_messages/3 * ###

`build_messages(Msgs, ScopedModifications, Opts) -> any()`

Step 5: Merge the base message with the scoped messages.

<a name="decode_string-1"></a>

### decode_string/1 * ###

`decode_string(B) -> any()`

Attempt Cowboy URL decode, then sanitize the result.

<a name="do_build-4"></a>

### do_build/4 * ###

`do_build(I, Rest, ScopedKeys, Opts) -> any()`

<a name="from-2"></a>

### from/2 ###

`from(RawMsg, Opts) -> any()`

Normalize a singleton TABM message into a list of executable AO-Core
messages.

<a name="group_scoped-2"></a>

### group_scoped/2 * ###

`group_scoped(Map, Msgs) -> any()`

Step 4: Group headers/query by N-scope.
`N.Key` => applies to Nth step. Otherwise => `global`

<a name="inlined_keys_test-0"></a>

### inlined_keys_test/0 * ###

`inlined_keys_test() -> any()`

<a name="inlined_keys_to_test-0"></a>

### inlined_keys_to_test/0 * ###

`inlined_keys_to_test() -> any()`

<a name="maybe_join-2"></a>

### maybe_join/2 * ###

`maybe_join(Items, Sep) -> any()`

Join a list of items with a separator, or return the first item if there
is only one item. If there are no items, return an empty binary.

<a name="maybe_subpath-2"></a>

### maybe_subpath/2 * ###

`maybe_subpath(Str, Opts) -> any()`

Check if the string is a subpath, returning it in parsed form,
or the original string with a specifier.

<a name="maybe_typed-3"></a>

### maybe_typed/3 * ###

`maybe_typed(Key, Value, Opts) -> any()`

Parse a key's type (applying it to the value) and device name if present.
We allow `` characters as type indicators because some URL-string encoders
(e.g. Chrome) will encode `+` characters in a form that query-string parsers
interpret as `` characters.

<a name="multiple_inlined_keys_test-0"></a>

### multiple_inlined_keys_test/0 * ###

`multiple_inlined_keys_test() -> any()`

<a name="multiple_inlined_keys_to_test-0"></a>

### multiple_inlined_keys_to_test/0 * ###

`multiple_inlined_keys_to_test() -> any()`

<a name="multiple_messages_test-0"></a>

### multiple_messages_test/0 * ###

`multiple_messages_test() -> any()`

<a name="multiple_messages_to_test-0"></a>

### multiple_messages_to_test/0 * ###

`multiple_messages_to_test() -> any()`

<a name="normalize_base-1"></a>

### normalize_base/1 * ###

`normalize_base(Rest) -> any()`

Normalize the base path.

<a name="parse_explicit_message_test-0"></a>

### parse_explicit_message_test/0 * ###

`parse_explicit_message_test() -> any()`

<a name="parse_full_path-1"></a>

### parse_full_path/1 * ###

`parse_full_path(RelativeRef) -> any()`

Parse the relative reference into path, query, and fragment.

<a name="parse_inlined_key_val-2"></a>

### parse_inlined_key_val/2 * ###

`parse_inlined_key_val(Bin, Opts) -> any()`

Extrapolate the inlined key-value pair from a path segment. If the
key has a value, it may provide a type (as with typical keys), but if a
value is not provided, it is assumed to be a boolean `true`.

<a name="parse_part-2"></a>

### parse_part/2 * ###

`parse_part(ID, Opts) -> any()`

Parse a path part into a message or an ID.
Applies the syntax rules outlined in the module doc, in the following order:
1. ID
2. Part subpath resolutions
3. Inlined key-value pairs
4. Device specifier

<a name="parse_part_mods-3"></a>

### parse_part_mods/3 * ###

`parse_part_mods(X1, Msg, Opts) -> any()`

Parse part modifiers:
1. `~Device` => `{as, Device, Msg}`
2. `&K=V` => `Msg#{ K => V }`

<a name="parse_scope-1"></a>

### parse_scope/1 * ###

`parse_scope(KeyBin) -> any()`

Get the scope of a key. Adds 1 to account for the base message.

<a name="part-2"></a>

### part/2 * ###

`part(Sep, Bin) -> any()`

Extract the characters from the binary until a separator is found.
The first argument of the function is an explicit separator character, or
a list of separator characters. Returns a tuple with the separator, the
accumulated characters, and the rest of the binary.

<a name="part-4"></a>

### part/4 * ###

`part(Seps, X2, Depth, CurrAcc) -> any()`

<a name="path_messages-2"></a>

### path_messages/2 * ###

`path_messages(RawBin, Opts) -> any()`

Step 2: Decode, split and sanitize the path. Split by `/` but avoid
subpath components, such that their own path parts are not dissociated from
their parent path.

<a name="path_parts-2"></a>

### path_parts/2 * ###

`path_parts(Sep, PathBin) -> any()`

Split the path into segments, filtering out empty segments and
segments that are too long.

<a name="path_parts_test-0"></a>

### path_parts_test/0 * ###

`path_parts_test() -> any()`

<a name="scoped_key_test-0"></a>

### scoped_key_test/0 * ###

`scoped_key_test() -> any()`

<a name="scoped_key_to_test-0"></a>

### scoped_key_to_test/0 * ###

`scoped_key_to_test() -> any()`

<a name="simple_to_test-0"></a>

### simple_to_test/0 * ###

`simple_to_test() -> any()`

<a name="single_message_test-0"></a>

### single_message_test/0 * ###

`single_message_test() -> any()`

<a name="subpath_in_inlined_test-0"></a>

### subpath_in_inlined_test/0 * ###

`subpath_in_inlined_test() -> any()`

<a name="subpath_in_inlined_to_test-0"></a>

### subpath_in_inlined_to_test/0 * ###

`subpath_in_inlined_to_test() -> any()`

<a name="subpath_in_key_test-0"></a>

### subpath_in_key_test/0 * ###

`subpath_in_key_test() -> any()`

<a name="subpath_in_key_to_test-0"></a>

### subpath_in_key_to_test/0 * ###

`subpath_in_key_to_test() -> any()`

<a name="subpath_in_path_test-0"></a>

### subpath_in_path_test/0 * ###

`subpath_in_path_test() -> any()`

<a name="subpath_in_path_to_test-0"></a>

### subpath_in_path_to_test/0 * ###

`subpath_in_path_to_test() -> any()`

<a name="to-1"></a>

### to/1 ###

<pre><code>
to(Messages::[<a href="#type-ao_message">ao_message()</a>]) -&gt; <a href="#type-tabm_message">tabm_message()</a>
</code></pre>
<br />

Convert a list of AO-Core message into TABM message.

<a name="to_suite_test_-0"></a>

### to_suite_test_/0 * ###

`to_suite_test_() -> any()`

<a name="type-1"></a>

### type/1 * ###

`type(Value) -> any()`

<a name="typed_key_test-0"></a>

### typed_key_test/0 * ###

`typed_key_test() -> any()`

<a name="typed_key_to_test-0"></a>

### typed_key_to_test/0 * ###

`typed_key_to_test() -> any()`


--- END OF FILE: docs/resources/source-code/hb_singleton.md ---

--- START OF FILE: docs/resources/source-code/hb_store_fs.md ---
# [Module hb_store_fs.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_store_fs.erl)




A key-value store implementation, following the `hb_store` behavior
and interface.

<a name="description"></a>

## Description ##

This implementation utilizes the node's local file system as
its storage mechanism, offering an alternative to other store's that require
the compilation of additional libraries in order to function.

As this store implementation operates using Erlang's native `file` and
`filelib` mechanisms, it largely inherits its performance characteristics
from those of the underlying OS/filesystem drivers. Certain filesystems can
be quite performant for the types of workload that HyperBEAM AO-Core execution
requires (many reads and writes to explicit keys, few directory 'listing' or
search operations), awhile others perform suboptimally.

Additionally, thisstore implementation offers the ability for simple
integration of HyperBEAM with other non-volatile storage media: `hb_store_fs`
will interact with any service that implements the host operating system's
native filesystem API. By mounting devices via `FUSE` (etc), HyperBEAM is
able to interact with a large number of existing storage systems (for example,
S3-compatible cloud storage APIs, etc).<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_prefix-2">add_prefix/2*</a></td><td>Add the directory prefix to a path.</td></tr><tr><td valign="top"><a href="#list-2">list/2</a></td><td>List contents of a directory in the store.</td></tr><tr><td valign="top"><a href="#make_group-2">make_group/2</a></td><td>Create a directory (group) in the store.</td></tr><tr><td valign="top"><a href="#make_link-3">make_link/3</a></td><td>Create a symlink, handling the case where the link would point to itself.</td></tr><tr><td valign="top"><a href="#read-1">read/1*</a></td><td></td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td>Read a key from the store, following symlinks as needed.</td></tr><tr><td valign="top"><a href="#remove_prefix-2">remove_prefix/2*</a></td><td>Remove the directory prefix from a path.</td></tr><tr><td valign="top"><a href="#reset-1">reset/1</a></td><td>Reset the store by completely removing its directory and recreating it.</td></tr><tr><td valign="top"><a href="#resolve-2">resolve/2</a></td><td>Replace links in a path successively, returning the final path.</td></tr><tr><td valign="top"><a href="#resolve-3">resolve/3*</a></td><td></td></tr><tr><td valign="top"><a href="#scope-0">scope/0</a></td><td>The file-based store is always local, for now.</td></tr><tr><td valign="top"><a href="#scope-1">scope/1</a></td><td></td></tr><tr><td valign="top"><a href="#start-1">start/1</a></td><td>Initialize the file system store with the given data directory.</td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td>Stop the file system store.</td></tr><tr><td valign="top"><a href="#type-1">type/1*</a></td><td></td></tr><tr><td valign="top"><a href="#type-2">type/2</a></td><td>Determine the type of a key in the store.</td></tr><tr><td valign="top"><a href="#write-3">write/3</a></td><td>Write a value to the specified path in the store.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_prefix-2"></a>

### add_prefix/2 * ###

`add_prefix(X1, Path) -> any()`

Add the directory prefix to a path.

<a name="list-2"></a>

### list/2 ###

`list(Opts, Path) -> any()`

List contents of a directory in the store.

<a name="make_group-2"></a>

### make_group/2 ###

`make_group(Opts, Path) -> any()`

Create a directory (group) in the store.

<a name="make_link-3"></a>

### make_link/3 ###

`make_link(Opts, Link, New) -> any()`

Create a symlink, handling the case where the link would point to itself.

<a name="read-1"></a>

### read/1 * ###

`read(Path) -> any()`

<a name="read-2"></a>

### read/2 ###

`read(Opts, Key) -> any()`

Read a key from the store, following symlinks as needed.

<a name="remove_prefix-2"></a>

### remove_prefix/2 * ###

`remove_prefix(X1, Path) -> any()`

Remove the directory prefix from a path.

<a name="reset-1"></a>

### reset/1 ###

`reset(X1) -> any()`

Reset the store by completely removing its directory and recreating it.

<a name="resolve-2"></a>

### resolve/2 ###

`resolve(Opts, RawPath) -> any()`

Replace links in a path successively, returning the final path.
Each element of the path is resolved in turn, with the result of each
resolution becoming the prefix for the next resolution. This allows
paths to resolve across many links. For example, a structure as follows:

/a/b/c: "Not the right data"
/a/b -> /a/alt-b
/a/alt-b/c: "Correct data"

will resolve "a/b/c" to "Correct data".

<a name="resolve-3"></a>

### resolve/3 * ###

`resolve(Opts, CurrPath, Rest) -> any()`

<a name="scope-0"></a>

### scope/0 ###

`scope() -> any()`

The file-based store is always local, for now. In the future, we may
want to allow that an FS store is shared across a cluster and thus remote.

<a name="scope-1"></a>

### scope/1 ###

`scope(X1) -> any()`

<a name="start-1"></a>

### start/1 ###

`start(X1) -> any()`

Initialize the file system store with the given data directory.

<a name="stop-1"></a>

### stop/1 ###

`stop(X1) -> any()`

Stop the file system store. Currently a no-op.

<a name="type-1"></a>

### type/1 * ###

`type(Path) -> any()`

<a name="type-2"></a>

### type/2 ###

`type(Opts, Key) -> any()`

Determine the type of a key in the store.

<a name="write-3"></a>

### write/3 ###

`write(Opts, PathComponents, Value) -> any()`

Write a value to the specified path in the store.


--- END OF FILE: docs/resources/source-code/hb_store_fs.md ---

--- START OF FILE: docs/resources/source-code/hb_store_gateway.md ---
# [Module hb_store_gateway.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_store_gateway.erl)




A store module that reads data from the nodes Arweave gateway and
GraphQL routes, additionally including additional store-specific routes.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#cache_read_message_test-0">cache_read_message_test/0*</a></td><td>Ensure that saving to the gateway store works.</td></tr><tr><td valign="top"><a href="#external_http_access_test-0">external_http_access_test/0*</a></td><td>Test that the default node config allows for data to be accessed.</td></tr><tr><td valign="top"><a href="#graphql_as_store_test_-0">graphql_as_store_test_/0*</a></td><td>Store is accessible via the default options.</td></tr><tr><td valign="top"><a href="#graphql_from_cache_test-0">graphql_from_cache_test/0*</a></td><td>Stored messages are accessible via <code>hb_cache</code> accesses.</td></tr><tr><td valign="top"><a href="#list-2">list/2</a></td><td></td></tr><tr><td valign="top"><a href="#manual_local_cache_test-0">manual_local_cache_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_cache-2">maybe_cache/2*</a></td><td>Cache the data if the cache is enabled.</td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td>Read the data at the given key from the GraphQL route.</td></tr><tr><td valign="top"><a href="#resolve-2">resolve/2</a></td><td></td></tr><tr><td valign="top"><a href="#scope-1">scope/1</a></td><td>The scope of a GraphQL store is always remote, due to performance.</td></tr><tr><td valign="top"><a href="#specific_route_test-0">specific_route_test/0*</a></td><td>Routes can be specified in the options, overriding the default routes.</td></tr><tr><td valign="top"><a href="#store_opts_test-0">store_opts_test/0*</a></td><td>Test to verify store opts is being set for Data-Protocol ao.</td></tr><tr><td valign="top"><a href="#type-2">type/2</a></td><td>Get the type of the data at the given key.</td></tr><tr><td valign="top"><a href="#verifiability_test-0">verifiability_test/0*</a></td><td>Test that items retreived from the gateway store are verifiable.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="cache_read_message_test-0"></a>

### cache_read_message_test/0 * ###

`cache_read_message_test() -> any()`

Ensure that saving to the gateway store works.

<a name="external_http_access_test-0"></a>

### external_http_access_test/0 * ###

`external_http_access_test() -> any()`

Test that the default node config allows for data to be accessed.

<a name="graphql_as_store_test_-0"></a>

### graphql_as_store_test_/0 * ###

`graphql_as_store_test_() -> any()`

Store is accessible via the default options.

<a name="graphql_from_cache_test-0"></a>

### graphql_from_cache_test/0 * ###

`graphql_from_cache_test() -> any()`

Stored messages are accessible via `hb_cache` accesses.

<a name="list-2"></a>

### list/2 ###

`list(StoreOpts, Key) -> any()`

<a name="manual_local_cache_test-0"></a>

### manual_local_cache_test/0 * ###

`manual_local_cache_test() -> any()`

<a name="maybe_cache-2"></a>

### maybe_cache/2 * ###

`maybe_cache(StoreOpts, Data) -> any()`

Cache the data if the cache is enabled. The `store` option may either
be `false` to disable local caching, or a store definition to use as the
cache.

<a name="read-2"></a>

### read/2 ###

`read(StoreOpts, Key) -> any()`

Read the data at the given key from the GraphQL route. Will only attempt
to read the data if the key is an ID.

<a name="resolve-2"></a>

### resolve/2 ###

`resolve(X1, Key) -> any()`

<a name="scope-1"></a>

### scope/1 ###

`scope(X1) -> any()`

The scope of a GraphQL store is always remote, due to performance.

<a name="specific_route_test-0"></a>

### specific_route_test/0 * ###

`specific_route_test() -> any()`

Routes can be specified in the options, overriding the default routes.
We test this by inversion: If the above cache read test works, then we know
that the default routes allow access to the item. If the test below were to
produce the same result, despite an empty 'only' route list, then we would
know that the module is not respecting the route list.

<a name="store_opts_test-0"></a>

### store_opts_test/0 * ###

`store_opts_test() -> any()`

Test to verify store opts is being set for Data-Protocol ao

<a name="type-2"></a>

### type/2 ###

`type(StoreOpts, Key) -> any()`

Get the type of the data at the given key. We potentially cache the
result, so that we don't have to read the data from the GraphQL route
multiple times.

<a name="verifiability_test-0"></a>

### verifiability_test/0 * ###

`verifiability_test() -> any()`

Test that items retreived from the gateway store are verifiable.


--- END OF FILE: docs/resources/source-code/hb_store_gateway.md ---

--- START OF FILE: docs/resources/source-code/hb_store_lmdb.md ---
# [Module hb_store_lmdb.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_store_lmdb.erl)




An LMDB (Lightning Memory Database) implementation of the HyperBeam store interface.

<a name="description"></a>

## Description ##

This module provides a persistent key-value store backend using LMDB, which is a
high-performance embedded transactional database. The implementation follows a
singleton pattern where each database environment gets its own dedicated server
process to manage transactions and coordinate writes.

Key features include:

* Asynchronous writes with batched transactions for performance

* Automatic link resolution for creating symbolic references between keys

* Group support for organizing hierarchical data structures

* Prefix-based key listing for directory-like navigation

* Process-local caching of database handles for efficiency


The module implements a dual-flush strategy: writes are accumulated in memory
and flushed either after an idle timeout or when explicitly requested during
read operations that encounter cache misses.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_path-3">add_path/3</a></td><td>Add two path components together.</td></tr><tr><td valign="top"><a href="#basic_test-0">basic_test/0*</a></td><td>Test suite demonstrating basic store operations.</td></tr><tr><td valign="top"><a href="#cache_debug_test-0">cache_debug_test/0*</a></td><td>Debug test to understand cache linking behavior.</td></tr><tr><td valign="top"><a href="#cache_style_test-0">cache_style_test/0*</a></td><td>Test cache-style usage through hb_store interface.</td></tr><tr><td valign="top"><a href="#commit_manager-2">commit_manager/2*</a></td><td>Background process that enforces maximum flush intervals.</td></tr><tr><td valign="top"><a href="#create_parent_groups-3">create_parent_groups/3*</a></td><td>Helper function to recursively create parent groups.</td></tr><tr><td valign="top"><a href="#ensure_parent_groups-2">ensure_parent_groups/2*</a></td><td>Ensure all parent groups exist for a given path.</td></tr><tr><td valign="top"><a href="#ensure_transaction-1">ensure_transaction/1*</a></td><td>Ensure that the server has an active LMDB transaction for writes.</td></tr><tr><td valign="top"><a href="#exact_hb_store_test-0">exact_hb_store_test/0*</a></td><td>Test that matches the exact hb_store hierarchical test pattern.</td></tr><tr><td valign="top"><a href="#find_env-1">find_env/1*</a></td><td>Retrieve or create the LMDB environment handle for a database.</td></tr><tr><td valign="top"><a href="#find_pid-1">find_pid/1*</a></td><td>Locate an existing server process or spawn a new one if needed.</td></tr><tr><td valign="top"><a href="#fold_after-4">fold_after/4*</a></td><td>Fold over a database after a given path.</td></tr><tr><td valign="top"><a href="#fold_cursor-5">fold_cursor/5*</a></td><td></td></tr><tr><td valign="top"><a href="#group_test-0">group_test/0*</a></td><td>Group test - verifies group creation and type detection.</td></tr><tr><td valign="top"><a href="#is_link-1">is_link/1*</a></td><td>Helper function to check if a value is a link and extract the target.</td></tr><tr><td valign="top"><a href="#isolated_type_debug_test-0">isolated_type_debug_test/0*</a></td><td>Isolated test focusing on the exact cache issue.</td></tr><tr><td valign="top"><a href="#link_fragment_test-0">link_fragment_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#link_key_list_test-0">link_key_list_test/0*</a></td><td>Link key list test - verifies symbolic link creation using structured key paths.</td></tr><tr><td valign="top"><a href="#link_test-0">link_test/0*</a></td><td>Link test - verifies symbolic link creation and resolution.</td></tr><tr><td valign="top"><a href="#list-2">list/2</a></td><td>List all keys that start with a given prefix.</td></tr><tr><td valign="top"><a href="#list_test-0">list_test/0*</a></td><td>List test - verifies prefix-based key listing functionality.</td></tr><tr><td valign="top"><a href="#list_with_link_test-0">list_with_link_test/0*</a></td><td>Test that list function resolves links correctly.</td></tr><tr><td valign="top"><a href="#make_group-2">make_group/2</a></td><td>Create a group entry that can contain other keys hierarchically.</td></tr><tr><td valign="top"><a href="#make_link-3">make_link/3</a></td><td>Create a symbolic link from a new key to an existing key.</td></tr><tr><td valign="top"><a href="#nested_map_cache_test-0">nested_map_cache_test/0*</a></td><td>Test nested map storage with cache-like linking behavior.</td></tr><tr><td valign="top"><a href="#notify_flush-1">notify_flush/1*</a></td><td>Notify all processes waiting for a flush operation to complete.</td></tr><tr><td valign="top"><a href="#path-2">path/2</a></td><td>Transform a path into the store's canonical form.</td></tr><tr><td valign="top"><a href="#path_traversal_link_test-0">path_traversal_link_test/0*</a></td><td>Path traversal link test - verifies link resolution during path traversal.</td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td>Read a value from the database by key, with automatic link resolution.</td></tr><tr><td valign="top"><a href="#read_direct-2">read_direct/2*</a></td><td>Read a value directly from the database with link resolution.</td></tr><tr><td valign="top"><a href="#read_with_flush-2">read_with_flush/2*</a></td><td>Read with immediate flush for cases where we need to see recent writes.</td></tr><tr><td valign="top"><a href="#read_with_retry-2">read_with_retry/2*</a></td><td>Unified read function that handles LMDB reads with retry logic.</td></tr><tr><td valign="top"><a href="#read_with_retry-3">read_with_retry/3*</a></td><td></td></tr><tr><td valign="top"><a href="#reconstruct_map-2">reconstruct_map/2*</a></td><td></td></tr><tr><td valign="top"><a href="#reset-1">reset/1</a></td><td>Completely delete the database directory and all its contents.</td></tr><tr><td valign="top"><a href="#resolve-2">resolve/2</a></td><td>Resolve a path by following any symbolic links.</td></tr><tr><td valign="top"><a href="#resolve_path_links-2">resolve_path_links/2*</a></td><td>Resolve links in a path, checking each segment except the last.</td></tr><tr><td valign="top"><a href="#resolve_path_links-3">resolve_path_links/3*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve_path_links_acc-4">resolve_path_links_acc/4*</a></td><td></td></tr><tr><td valign="top"><a href="#scope-0">scope/0</a></td><td>Return the scope of this storage backend.</td></tr><tr><td valign="top"><a href="#scope-1">scope/1</a></td><td>Return the scope of this storage backend (ignores parameters).</td></tr><tr><td valign="top"><a href="#server-1">server/1*</a></td><td>Main server loop that handles database operations and manages transactions.</td></tr><tr><td valign="top"><a href="#server_flush-1">server_flush/1*</a></td><td>Commit the current transaction to disk and clean up state.</td></tr><tr><td valign="top"><a href="#server_write-3">server_write/3*</a></td><td>Add a key-value pair to the current transaction, creating one if needed.</td></tr><tr><td valign="top"><a href="#start-1">start/1</a></td><td>Start the LMDB storage system for a given database configuration.</td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td>Gracefully shut down the database server and close the environment.</td></tr><tr><td valign="top"><a href="#sync-1">sync/1*</a></td><td>Force an immediate flush of all pending writes to disk.</td></tr><tr><td valign="top"><a href="#to_path-1">to_path/1*</a></td><td>Helper function to convert to a path.</td></tr><tr><td valign="top"><a href="#type-2">type/2</a></td><td>Determine whether a key represents a simple value or composite group.</td></tr><tr><td valign="top"><a href="#type_test-0">type_test/0*</a></td><td>Type test - verifies type detection for both simple and composite entries.</td></tr><tr><td valign="top"><a href="#write-3">write/3</a></td><td>Write a key-value pair to the database asynchronously.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_path-3"></a>

### add_path/3 ###

`add_path(Opts, Path1, Path2) -> any()`

Add two path components together.
For LMDB, this concatenates the path lists.

<a name="basic_test-0"></a>

### basic_test/0 * ###

`basic_test() -> any()`

Test suite demonstrating basic store operations.

The following functions implement unit tests using EUnit to verify that
the LMDB store implementation correctly handles various scenarios including
basic read/write operations, hierarchical listing, group creation, link
resolution, and type detection.

Basic store test - verifies fundamental read/write functionality.

This test creates a temporary database, writes a key-value pair, reads it
back to verify correctness, and cleans up by stopping the database. It
serves as a sanity check that the basic storage mechanism is working.

<a name="cache_debug_test-0"></a>

### cache_debug_test/0 * ###

`cache_debug_test() -> any()`

Debug test to understand cache linking behavior

<a name="cache_style_test-0"></a>

### cache_style_test/0 * ###

`cache_style_test() -> any()`

Test cache-style usage through hb_store interface

<a name="commit_manager-2"></a>

### commit_manager/2 * ###

`commit_manager(Opts, Server) -> any()`

Background process that enforces maximum flush intervals.

This function runs in a separate process linked to the main server and
ensures that transactions are committed within a reasonable time frame
even during periods of continuous write activity. It sends periodic
flush requests to the main server based on the configured maximum flush time.

The commit manager provides a safety net against data loss by preventing
transactions from remaining uncommitted indefinitely. It works in conjunction
with the idle timeout mechanism to provide comprehensive data safety guarantees.

The process runs in an infinite loop, coordinating with the main server
through message passing and restarting its timer after each successful flush.

<a name="create_parent_groups-3"></a>

### create_parent_groups/3 * ###

`create_parent_groups(Opts, Current, Rest) -> any()`

Helper function to recursively create parent groups.

<a name="ensure_parent_groups-2"></a>

### ensure_parent_groups/2 * ###

<pre><code>
ensure_parent_groups(Opts::map(), Path::binary()) -&gt; ok
</code></pre>
<br />

`Opts`: Database configuration map<br />`Path`: The path whose parents should exist<br />

returns: ok

Ensure all parent groups exist for a given path.

This function creates the necessary parent groups for a path, similar to
how filesystem stores use ensure_dir. For example, if the path is
"a/b/c/file", it will ensure groups "a", "a/b", and "a/b/c" exist.

<a name="ensure_transaction-1"></a>

### ensure_transaction/1 * ###

`ensure_transaction(State) -> any()`

Ensure that the server has an active LMDB transaction for writes.

This function implements lazy transaction creation by checking if a transaction
already exists in the server state. If not, it creates a new read-write
transaction and opens the default database within it.

The lazy approach improves efficiency by avoiding transaction overhead when
the server is idle, while ensuring that write operations always have a
transaction available when needed.

Transactions in LMDB are lightweight but still represent a commitment of
resources, so creating them only when needed helps optimize memory usage
and system performance.

<a name="exact_hb_store_test-0"></a>

### exact_hb_store_test/0 * ###

`exact_hb_store_test() -> any()`

Test that matches the exact hb_store hierarchical test pattern

<a name="find_env-1"></a>

### find_env/1 * ###

`find_env(Opts) -> any()`

Retrieve or create the LMDB environment handle for a database.

<a name="find_pid-1"></a>

### find_pid/1 * ###

`find_pid(StoreOpts) -> any()`

Locate an existing server process or spawn a new one if needed.

<a name="fold_after-4"></a>

### fold_after/4 * ###

`fold_after(Opts, Path, Fun, Acc) -> any()`

Fold over a database after a given path. The `Fun` is called with
the key and value, and the accumulator.

<a name="fold_cursor-5"></a>

### fold_cursor/5 * ###

`fold_cursor(X1, Txn, Cur, Fun, Acc) -> any()`

<a name="group_test-0"></a>

### group_test/0 * ###

`group_test() -> any()`

Group test - verifies group creation and type detection.

This test creates a group entry and verifies that it is correctly identified
as a composite type and cannot be read directly (like filesystem directories).

<a name="is_link-1"></a>

### is_link/1 * ###

`is_link(Value) -> any()`

Helper function to check if a value is a link and extract the target.

<a name="isolated_type_debug_test-0"></a>

### isolated_type_debug_test/0 * ###

`isolated_type_debug_test() -> any()`

Isolated test focusing on the exact cache issue

<a name="link_fragment_test-0"></a>

### link_fragment_test/0 * ###

`link_fragment_test() -> any()`

<a name="link_key_list_test-0"></a>

### link_key_list_test/0 * ###

`link_key_list_test() -> any()`

Link key list test - verifies symbolic link creation using structured key paths.

This test demonstrates the store's ability to handle complex key structures
represented as lists of binary segments, and verifies that symbolic links
work correctly when the target key is specified as a list rather than a
flat binary string.

The test creates a hierarchical key structure using a list format (which
presumably gets converted to a path-like binary internally), creates a
symbolic link pointing to that structured key, and verifies that link
resolution works transparently to return the original value.

This is particularly important for applications that organize data in
hierarchical structures where keys represent nested paths or categories,
and need to create shortcuts or aliases to deeply nested data.

<a name="link_test-0"></a>

### link_test/0 * ###

`link_test() -> any()`

Link test - verifies symbolic link creation and resolution.

This test creates a regular key-value pair, creates a link pointing to it,
and verifies that reading from the link location returns the original value.
This demonstrates the transparent link resolution mechanism.

<a name="list-2"></a>

### list/2 ###

<pre><code>
list(Opts::map(), Path::binary()) -&gt; {ok, [binary()]} | {error, term()}
</code></pre>
<br />

`Path`: Binary prefix to search for<br />

returns: {ok, [Key]} list of matching keys, {error, Reason} on failure

List all keys that start with a given prefix.

This function provides directory-like navigation by finding all keys that
begin with the specified path prefix. It uses LMDB's fold operation to
efficiently scan through the database and collect matching keys.

The implementation only returns keys that are longer than the prefix itself,
ensuring that the prefix acts like a directory separator. For example,
listing with prefix "colors" will return "colors/red" and "colors/blue"
but not "colors" itself.

If the Path points to a link, the function resolves the link and lists
the contents of the target directory instead.

This is particularly useful for implementing hierarchical data organization
and providing tree-like navigation interfaces in applications.

<a name="list_test-0"></a>

### list_test/0 * ###

`list_test() -> any()`

List test - verifies prefix-based key listing functionality.

This test creates several keys with hierarchical names and verifies that
the list operation correctly returns only keys matching a specific prefix.
It demonstrates the directory-like navigation capabilities of the store.

<a name="list_with_link_test-0"></a>

### list_with_link_test/0 * ###

`list_with_link_test() -> any()`

Test that list function resolves links correctly

<a name="make_group-2"></a>

### make_group/2 ###

<pre><code>
make_group(Opts::map(), GroupName::binary()) -&gt; ok | {error, term()}
</code></pre>
<br />

`Opts`: Database configuration map<br />`GroupName`: Binary name for the group<br />

returns: Result of the write operation

Create a group entry that can contain other keys hierarchically.

Groups in the HyperBeam system represent composite entries that can contain
child elements, similar to directories in a filesystem. This function creates
a group by storing the special value "group" at the specified key.

The group mechanism allows applications to organize data hierarchically and
provides semantic meaning that can be used by navigation and visualization
tools to present appropriate user interfaces.

Groups can be identified later using the type/2 function, which will return
'composite' for group entries versus 'simple' for regular key-value pairs.

<a name="make_link-3"></a>

### make_link/3 ###

<pre><code>
make_link(Opts::map(), Existing::binary() | list(), New::binary()) -&gt; ok
</code></pre>
<br />

`Existing`: The key that already exists and contains the target value<br />`New`: The new key that should link to the existing key<br />

returns: Result of the write operation

Create a symbolic link from a new key to an existing key.

This function implements a symbolic link mechanism by storing a special
"link:" prefixed value at the new key location. When the new key is read,
the system will automatically resolve the link and return the value from
the target key instead.

Links provide a way to create aliases, shortcuts, or alternative access
paths to the same underlying data without duplicating storage. They can
be chained together to create complex reference structures, though care
should be taken to avoid circular references.

The link resolution happens transparently during read operations, making
links invisible to most application code while providing powerful
organizational capabilities.

<a name="nested_map_cache_test-0"></a>

### nested_map_cache_test/0 * ###

`nested_map_cache_test() -> any()`

Test nested map storage with cache-like linking behavior

This test demonstrates how to store a nested map structure where:
1. Each value is stored at data/{hash_of_value}
2. Links are created to compose the values back into the original map structure
3. Reading the composed structure reconstructs the original nested map

<a name="notify_flush-1"></a>

### notify_flush/1 * ###

`notify_flush(State) -> any()`

Notify all processes waiting for a flush operation to complete.

This function handles the coordination between the server's flush operations
and client processes that may be blocked waiting for data to be committed.
It uses a non-blocking receive loop to collect all pending flush requests
and respond to them immediately.

The non-blocking nature (timeout of 0) ensures that the server doesn't get
stuck waiting for messages that may not exist, while still handling all
queued requests efficiently.

<a name="path-2"></a>

### path/2 ###

`path(Opts, PathParts) -> any()`

Transform a path into the store's canonical form.
For LMDB, paths are simply joined with "/" separators.

<a name="path_traversal_link_test-0"></a>

### path_traversal_link_test/0 * ###

`path_traversal_link_test() -> any()`

Path traversal link test - verifies link resolution during path traversal.

This test verifies that when reading a path as a list, intermediate path
segments that are links get resolved correctly. For example, if "link"
is a symbolic link to "group", then reading ["link", "key"] should
resolve to reading ["group", "key"].

This functionality enables transparent redirection at the directory level,
allowing reorganization of hierarchical data without breaking existing
access patterns.

<a name="read-2"></a>

### read/2 ###

<pre><code>
read(Opts::map(), PathParts::binary() | list()) -&gt; {ok, binary()} | {error, term()}
</code></pre>
<br />

`Opts`: Database configuration map<br />

returns: {ok, Value} on success, {error, Reason} on failure

Read a value from the database by key, with automatic link resolution.

This function attempts to read a value directly from the committed database.
If the key is not found, it triggers a flush operation to ensure any pending
writes are committed before retrying the read.

The function automatically handles link resolution: if a stored value begins
with the "link:" prefix, it extracts the target key and recursively reads
from that location instead. This creates a symbolic link mechanism that
allows multiple keys to reference the same underlying data.

When given a list of path segments, the function first attempts a direct read
for optimal performance. Only if the direct read fails does it perform link
resolution at each level of the path except the final segment, allowing path
traversal through symbolic links to work transparently.

Link resolution is transparent to the caller and can chain through multiple
levels of indirection, though care should be taken to avoid circular references.

<a name="read_direct-2"></a>

### read_direct/2 * ###

`read_direct(Opts, Path) -> any()`

Read a value directly from the database with link resolution.
This is the internal implementation that handles actual database reads.

<a name="read_with_flush-2"></a>

### read_with_flush/2 * ###

`read_with_flush(Opts, Path) -> any()`

Read with immediate flush for cases where we need to see recent writes.
This is used when we expect the key to exist from a recent write operation.

<a name="read_with_retry-2"></a>

### read_with_retry/2 * ###

`read_with_retry(Opts, Path) -> any()`

Unified read function that handles LMDB reads with retry logic.
Returns {ok, Value}, not_found, or performs flush and retries.

<a name="read_with_retry-3"></a>

### read_with_retry/3 * ###

`read_with_retry(Opts, Path, RetriesRemaining) -> any()`

<a name="reconstruct_map-2"></a>

### reconstruct_map/2 * ###

`reconstruct_map(StoreOpts, Path) -> any()`

<a name="reset-1"></a>

### reset/1 ###

`reset(Opts) -> any()`

Completely delete the database directory and all its contents.

This is a destructive operation that removes all data from the specified
database. It first performs a graceful shutdown to ensure data consistency,
then uses the system shell to recursively delete the entire database
directory structure.

This function is primarily intended for testing and development scenarios
where you need to start with a completely clean database state. It should
be used with extreme caution in production environments.

<a name="resolve-2"></a>

### resolve/2 ###

<pre><code>
resolve(Opts::map(), Path::binary() | list()) -&gt; binary()
</code></pre>
<br />

`Path`: The path to resolve (binary or list)<br />

returns: The resolved path as a binary

Resolve a path by following any symbolic links.

For LMDB, we handle links through our own "link:" prefix mechanism.
This function resolves link chains in paths, similar to filesystem symlink resolution.
It's used by the cache to resolve paths before type checking and reading.

<a name="resolve_path_links-2"></a>

### resolve_path_links/2 * ###

`resolve_path_links(Opts, Path) -> any()`

Resolve links in a path, checking each segment except the last.
Returns the resolved path where any intermediate links have been followed.

<a name="resolve_path_links-3"></a>

### resolve_path_links/3 * ###

`resolve_path_links(Opts, Path, Depth) -> any()`

<a name="resolve_path_links_acc-4"></a>

### resolve_path_links_acc/4 * ###

`resolve_path_links_acc(Opts, Tail, AccPath, Depth) -> any()`

<a name="scope-0"></a>

### scope/0 ###

<pre><code>
scope() -&gt; local
</code></pre>
<br />

returns: 'local' always

Return the scope of this storage backend.

The LMDB implementation is always local-only and does not support distributed
operations. This function exists to satisfy the HyperBeam store interface
contract and inform the system about the storage backend's capabilities.

<a name="scope-1"></a>

### scope/1 ###

<pre><code>
scope(X1::term()) -&gt; local
</code></pre>
<br />

returns: 'local' always

Return the scope of this storage backend (ignores parameters).

This is an alternate form of scope/0 that ignores any parameters passed to it.
The LMDB backend is always local regardless of configuration.

<a name="server-1"></a>

### server/1 * ###

`server(State) -> any()`

Main server loop that handles database operations and manages transactions.

This function implements the core server logic using Erlang's selective receive
mechanism. It handles four types of messages: environment requests from readers,
write requests that accumulate in transactions, explicit flush requests that
commit pending data, and stop messages for graceful shutdown.

The server uses a timeout-based flush strategy where it automatically commits
transactions after a period of inactivity. This balances write performance
(by batching operations) with data safety (by limiting the window of potential
data loss).

The server maintains its state as a map containing the LMDB environment,
current transaction handle, and configuration parameters. State updates are
handled functionally by passing modified state maps through tail-recursive calls.

<a name="server_flush-1"></a>

### server_flush/1 * ###

`server_flush(RawState) -> any()`

Commit the current transaction to disk and clean up state.

This function handles the critical operation of persisting accumulated writes
to the database. If a transaction is active, it commits the transaction and
notifies any processes waiting for the flush to complete.

After committing, the server state is cleaned up by removing transaction
references, preparing for the next batch of operations. If no transaction
is active, the function is a no-op.

The notification mechanism ensures that read operations blocked on cache
misses can proceed once fresh data is available.

<a name="server_write-3"></a>

### server_write/3 * ###

`server_write(RawState, Key, Value) -> any()`

Add a key-value pair to the current transaction, creating one if needed.

This function handles write operations by ensuring a transaction is active
and then adding the key-value pair to it using LMDB's native interface.
If no transaction exists, it creates one automatically.

The function uses LMDB's direct NIF interface for maximum performance,
bypassing higher-level abstractions that might add overhead. The write
is added to the transaction but not committed until a flush occurs.

<a name="start-1"></a>

### start/1 ###

<pre><code>
start(Opts::map()) -&gt; {ok, pid()} | {error, term()}
</code></pre>
<br />

returns: {ok, ServerPid} on success, {error, Reason} on failure

Start the LMDB storage system for a given database configuration.

This function initializes or connects to an existing LMDB database instance.
It uses a singleton pattern, so multiple calls with the same configuration
will return the same server process. The server process manages the LMDB
environment and coordinates all database operations.

The StoreOpts map must contain a "prefix" key specifying the
database directory path. Also the required configuration includes "capacity" for
the maximum database size and flush timing parameters.

<a name="stop-1"></a>

### stop/1 ###

`stop(StoreOpts) -> any()`

Gracefully shut down the database server and close the environment.

This function performs an orderly shutdown of the database system by first
stopping the server process (which flushes any pending writes) and then
closing the LMDB environment to release system resources.

The shutdown process ensures that no data is lost and all file handles
are properly closed. After calling stop, the database can be restarted
by calling any other function that triggers server creation.

<a name="sync-1"></a>

### sync/1 * ###

<pre><code>
sync(Opts::map()) -&gt; ok | {error, term()}
</code></pre>
<br />

returns: 'ok' when flush is complete, {error, Reason} on failure

Force an immediate flush of all pending writes to disk.

This function synchronously forces the database server to commit any
pending writes in the current transaction. It blocks until the flush
operation is complete, ensuring that all previously written data is
durably stored before returning.

This is useful when you need to ensure data is persisted immediately,
rather than waiting for the automatic flush timers to trigger. Common
use cases include critical checkpoints, before system shutdown, or
when preparing for read operations that must see the latest writes.

<a name="to_path-1"></a>

### to_path/1 * ###

`to_path(PathParts) -> any()`

Helper function to convert to a path

<a name="type-2"></a>

### type/2 ###

<pre><code>
type(Opts::map(), Key::binary()) -&gt; composite | simple | not_found
</code></pre>
<br />

`Opts`: Database configuration map<br />`Key`: The key to examine<br />

returns: 'composite' for group entries, 'simple' for regular values

Determine whether a key represents a simple value or composite group.

This function reads the value associated with a key and examines its content
to classify the entry type. Keys storing the literal binary "group" are
considered composite (directory-like) entries, while all other values are
treated as simple key-value pairs.

This classification is used by higher-level HyperBeam components to understand
the structure of stored data and provide appropriate navigation interfaces.

<a name="type_test-0"></a>

### type_test/0 * ###

`type_test() -> any()`

Type test - verifies type detection for both simple and composite entries.

This test creates both a group (composite) entry and a regular (simple) entry,
then verifies that the type detection function correctly identifies each one.
This demonstrates the semantic classification system used by the store.

<a name="write-3"></a>

### write/3 ###

<pre><code>
write(Opts::map(), PathParts::binary() | list(), Value::binary()) -&gt; ok
</code></pre>
<br />

`Opts`: Database configuration map<br />`Value`: Binary value to store<br />

returns: 'ok' immediately (write happens asynchronously)

Write a key-value pair to the database asynchronously.

This function sends a write request to the database server process and returns
immediately without waiting for the write to be committed to disk. The server
accumulates writes in a transaction that is periodically flushed based on
timing constraints or explicit flush requests.

The asynchronous nature provides better performance for write-heavy workloads
while the batching strategy ensures data consistency and reduces I/O overhead.
However, recent writes may not be immediately visible to readers until the
next flush occurs.


--- END OF FILE: docs/resources/source-code/hb_store_lmdb.md ---

--- START OF FILE: docs/resources/source-code/hb_store_lru.md ---
# [Module hb_store_lru.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_store_lru.erl)




An in-memory store implementation, following the `hb_store` behavior
and interface.

<a name="description"></a>

## Description ##

This implementation uses a least-recently-used cache first,
and offloads evicted data to a specified non-volatile store over time.

This cache is registered under `{in_memory, HTTPServerID}`, in `hb_name`
so that all processes that are executing using the HTTP server’s Opts
can find it quickly.

The least-recently-used strategy (first is the most recent used, last is the
least recently used) is implemented by keeping track of the order and bytes
on ets tables:
- A cache table containing all the entries along with the value size and
key index.
- A cache indexing table containing all the index pointing to the keys. The
IDs are then sorted to ease the eviction policy.
- A cache statistics table containing all the information about the cache
size, capacity, and indexing.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_cache_entry-3">add_cache_entry/3*</a></td><td></td></tr><tr><td valign="top"><a href="#add_cache_index-3">add_cache_index/3*</a></td><td></td></tr><tr><td valign="top"><a href="#append_key_to_group-2">append_key_to_group/2*</a></td><td></td></tr><tr><td valign="top"><a href="#assign_new_entry-7">assign_new_entry/7*</a></td><td></td></tr><tr><td valign="top"><a href="#cache_size-1">cache_size/1*</a></td><td></td></tr><tr><td valign="top"><a href="#cache_tail_key-1">cache_tail_key/1*</a></td><td></td></tr><tr><td valign="top"><a href="#cache_term_test-0">cache_term_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#clean_old_link-2">clean_old_link/2*</a></td><td>Remove the link association for the the old linked data to the given key.</td></tr><tr><td valign="top"><a href="#convert_if_list-1">convert_if_list/1*</a></td><td></td></tr><tr><td valign="top"><a href="#decrease_cache_size-2">decrease_cache_size/2*</a></td><td></td></tr><tr><td valign="top"><a href="#delete_cache_entry-2">delete_cache_entry/2*</a></td><td></td></tr><tr><td valign="top"><a href="#delete_cache_index-2">delete_cache_index/2*</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_dir-2">ensure_dir/2*</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_dir-3">ensure_dir/3*</a></td><td></td></tr><tr><td valign="top"><a href="#ets_keys-2">ets_keys/2*</a></td><td>List all of the keys in the store for a given path, supporting a special
case for the root.</td></tr><tr><td valign="top"><a href="#evict_all_entries-2">evict_all_entries/2*</a></td><td></td></tr><tr><td valign="top"><a href="#evict_but_able_to_read_from_fs_store_test-0">evict_but_able_to_read_from_fs_store_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#evict_items_with_insufficient_space_test-0">evict_items_with_insufficient_space_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#evict_oldest_entry-3">evict_oldest_entry/3*</a></td><td></td></tr><tr><td valign="top"><a href="#evict_oldest_entry-4">evict_oldest_entry/4*</a></td><td></td></tr><tr><td valign="top"><a href="#evict_oldest_items_test-0">evict_oldest_items_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#fetch_cache_with_retry-2">fetch_cache_with_retry/2*</a></td><td></td></tr><tr><td valign="top"><a href="#fetch_cache_with_retry-3">fetch_cache_with_retry/3*</a></td><td></td></tr><tr><td valign="top"><a href="#get_cache_entry-2">get_cache_entry/2*</a></td><td></td></tr><tr><td valign="top"><a href="#get_index_id-1">get_index_id/1*</a></td><td></td></tr><tr><td valign="top"><a href="#get_persistent_store-1">get_persistent_store/1*</a></td><td></td></tr><tr><td valign="top"><a href="#handle_group-3">handle_group/3*</a></td><td></td></tr><tr><td valign="top"><a href="#increase_cache_size-2">increase_cache_size/2*</a></td><td></td></tr><tr><td valign="top"><a href="#init-2">init/2*</a></td><td>Create the <code>ets</code> tables for the LRU cache:
- The cache of data itself (public, with read concurrency enabled)
- A set for the LRU's stats.</td></tr><tr><td valign="top"><a href="#join-1">join/1*</a></td><td></td></tr><tr><td valign="top"><a href="#link_cache_entry-4">link_cache_entry/4*</a></td><td></td></tr><tr><td valign="top"><a href="#list-2">list/2</a></td><td>List all the keys registered.</td></tr><tr><td valign="top"><a href="#list_test-0">list_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#make_group-2">make_group/2</a></td><td>Create a directory inside the store.</td></tr><tr><td valign="top"><a href="#make_link-3">make_link/3</a></td><td>Make a link from a key to another in the store.</td></tr><tr><td valign="top"><a href="#maybe_convert_to_binary-1">maybe_convert_to_binary/1*</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_create_dir-3">maybe_create_dir/3*</a></td><td></td></tr><tr><td valign="top"><a href="#offload_to_store-5">offload_to_store/5*</a></td><td></td></tr><tr><td valign="top"><a href="#put_cache_entry-4">put_cache_entry/4*</a></td><td></td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td>Retrieve value in the cache from the given key.</td></tr><tr><td valign="top"><a href="#replace_entry-5">replace_entry/5*</a></td><td></td></tr><tr><td valign="top"><a href="#replace_link_test-0">replace_link_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#reset-1">reset/1</a></td><td>Reset the store by completely cleaning the ETS tables and
delegate the reset to the underlying offloading store.</td></tr><tr><td valign="top"><a href="#reset_test-0">reset_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#resolve-2">resolve/2</a></td><td></td></tr><tr><td valign="top"><a href="#resolve-3">resolve/3*</a></td><td></td></tr><tr><td valign="top"><a href="#scope-1">scope/1</a></td><td>The LRU store is always local, for now.</td></tr><tr><td valign="top"><a href="#server_loop-2">server_loop/2*</a></td><td></td></tr><tr><td valign="top"><a href="#start-1">start/1</a></td><td>The default capacity is used when no capacity is provided in the store
options.</td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td>Stop the LRU in memory by offloading the keys in the ETS tables
before exiting the process.</td></tr><tr><td valign="top"><a href="#stop_test-0">stop_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#sync-1">sync/1*</a></td><td>Force the caller to wait until the server has fully processed all
messages in its mailbox, up to the initiation of the call.</td></tr><tr><td valign="top"><a href="#table_keys-1">table_keys/1*</a></td><td></td></tr><tr><td valign="top"><a href="#table_keys-2">table_keys/2*</a></td><td></td></tr><tr><td valign="top"><a href="#table_keys-4">table_keys/4*</a></td><td></td></tr><tr><td valign="top"><a href="#test_opts-1">test_opts/1*</a></td><td>Generate a set of options for testing.</td></tr><tr><td valign="top"><a href="#test_opts-2">test_opts/2*</a></td><td></td></tr><tr><td valign="top"><a href="#type-2">type/2</a></td><td>Determine the type of a key in the store.</td></tr><tr><td valign="top"><a href="#type_test-0">type_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#unknown_value_test-0">unknown_value_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#update_cache_size-3">update_cache_size/3*</a></td><td></td></tr><tr><td valign="top"><a href="#update_recently_used-3">update_recently_used/3*</a></td><td></td></tr><tr><td valign="top"><a href="#write-3">write/3</a></td><td>Write an entry in the cache.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_cache_entry-3"></a>

### add_cache_entry/3 * ###

`add_cache_entry(X1, Key, Value) -> any()`

<a name="add_cache_index-3"></a>

### add_cache_index/3 * ###

`add_cache_index(X1, ID, Key) -> any()`

<a name="append_key_to_group-2"></a>

### append_key_to_group/2 * ###

`append_key_to_group(Key, Group) -> any()`

<a name="assign_new_entry-7"></a>

### assign_new_entry/7 * ###

`assign_new_entry(State, Key, Value, ValueSize, Capacity, Group, Opts) -> any()`

<a name="cache_size-1"></a>

### cache_size/1 * ###

`cache_size(X1) -> any()`

<a name="cache_tail_key-1"></a>

### cache_tail_key/1 * ###

`cache_tail_key(X1) -> any()`

<a name="cache_term_test-0"></a>

### cache_term_test/0 * ###

`cache_term_test() -> any()`

<a name="clean_old_link-2"></a>

### clean_old_link/2 * ###

`clean_old_link(Table, Link) -> any()`

Remove the link association for the the old linked data to the given key

<a name="convert_if_list-1"></a>

### convert_if_list/1 * ###

`convert_if_list(Value) -> any()`

<a name="decrease_cache_size-2"></a>

### decrease_cache_size/2 * ###

`decrease_cache_size(X1, Size) -> any()`

<a name="delete_cache_entry-2"></a>

### delete_cache_entry/2 * ###

`delete_cache_entry(X1, Key) -> any()`

<a name="delete_cache_index-2"></a>

### delete_cache_index/2 * ###

`delete_cache_index(X1, ID) -> any()`

<a name="ensure_dir-2"></a>

### ensure_dir/2 * ###

`ensure_dir(State, Path) -> any()`

<a name="ensure_dir-3"></a>

### ensure_dir/3 * ###

`ensure_dir(State, CurrentPath, Rest) -> any()`

<a name="ets_keys-2"></a>

### ets_keys/2 * ###

`ets_keys(Opts, Path) -> any()`

List all of the keys in the store for a given path, supporting a special
case for the root.

<a name="evict_all_entries-2"></a>

### evict_all_entries/2 * ###

`evict_all_entries(X1, Opts) -> any()`

<a name="evict_but_able_to_read_from_fs_store_test-0"></a>

### evict_but_able_to_read_from_fs_store_test/0 * ###

`evict_but_able_to_read_from_fs_store_test() -> any()`

<a name="evict_items_with_insufficient_space_test-0"></a>

### evict_items_with_insufficient_space_test/0 * ###

`evict_items_with_insufficient_space_test() -> any()`

<a name="evict_oldest_entry-3"></a>

### evict_oldest_entry/3 * ###

`evict_oldest_entry(State, ValueSize, Opts) -> any()`

<a name="evict_oldest_entry-4"></a>

### evict_oldest_entry/4 * ###

`evict_oldest_entry(State, ValueSize, FreeSize, Opts) -> any()`

<a name="evict_oldest_items_test-0"></a>

### evict_oldest_items_test/0 * ###

`evict_oldest_items_test() -> any()`

<a name="fetch_cache_with_retry-2"></a>

### fetch_cache_with_retry/2 * ###

`fetch_cache_with_retry(Opts, Key) -> any()`

<a name="fetch_cache_with_retry-3"></a>

### fetch_cache_with_retry/3 * ###

`fetch_cache_with_retry(Opts, Key, Retries) -> any()`

<a name="get_cache_entry-2"></a>

### get_cache_entry/2 * ###

`get_cache_entry(Table, Key) -> any()`

<a name="get_index_id-1"></a>

### get_index_id/1 * ###

`get_index_id(X1) -> any()`

<a name="get_persistent_store-1"></a>

### get_persistent_store/1 * ###

`get_persistent_store(Opts) -> any()`

<a name="handle_group-3"></a>

### handle_group/3 * ###

`handle_group(State, Key, Opts) -> any()`

<a name="increase_cache_size-2"></a>

### increase_cache_size/2 * ###

`increase_cache_size(X1, ValueSize) -> any()`

<a name="init-2"></a>

### init/2 * ###

`init(From, StoreOpts) -> any()`

Create the `ets` tables for the LRU cache:
- The cache of data itself (public, with read concurrency enabled)
- A set for the LRU's stats.
- An ordered set for the cache's index.

<a name="join-1"></a>

### join/1 * ###

`join(Key) -> any()`

<a name="link_cache_entry-4"></a>

### link_cache_entry/4 * ###

`link_cache_entry(State, Existing, New, Opts) -> any()`

<a name="list-2"></a>

### list/2 ###

`list(Opts, Path) -> any()`

List all the keys registered.

<a name="list_test-0"></a>

### list_test/0 * ###

`list_test() -> any()`

<a name="make_group-2"></a>

### make_group/2 ###

`make_group(Opts, Key) -> any()`

Create a directory inside the store.

<a name="make_link-3"></a>

### make_link/3 ###

`make_link(Opts, Link, New) -> any()`

Make a link from a key to another in the store.

<a name="maybe_convert_to_binary-1"></a>

### maybe_convert_to_binary/1 * ###

`maybe_convert_to_binary(Value) -> any()`

<a name="maybe_create_dir-3"></a>

### maybe_create_dir/3 * ###

`maybe_create_dir(State, DirPath, Value) -> any()`

<a name="offload_to_store-5"></a>

### offload_to_store/5 * ###

`offload_to_store(TailKey, TailValue, Links, Group, Opts) -> any()`

<a name="put_cache_entry-4"></a>

### put_cache_entry/4 * ###

`put_cache_entry(State, Key, Value, Opts) -> any()`

<a name="read-2"></a>

### read/2 ###

`read(Opts, RawKey) -> any()`

Retrieve value in the cache from the given key.
Because the cache uses LRU, the key is moved on the most recent used key to
cycle and re-prioritize cache entry.

<a name="replace_entry-5"></a>

### replace_entry/5 * ###

`replace_entry(State, Key, Value, ValueSize, X5) -> any()`

<a name="replace_link_test-0"></a>

### replace_link_test/0 * ###

`replace_link_test() -> any()`

<a name="reset-1"></a>

### reset/1 ###

`reset(Opts) -> any()`

Reset the store by completely cleaning the ETS tables and
delegate the reset to the underlying offloading store.

<a name="reset_test-0"></a>

### reset_test/0 * ###

`reset_test() -> any()`

<a name="resolve-2"></a>

### resolve/2 ###

`resolve(Opts, Key) -> any()`

<a name="resolve-3"></a>

### resolve/3 * ###

`resolve(Opts, CurrPath, Rest) -> any()`

<a name="scope-1"></a>

### scope/1 ###

`scope(X1) -> any()`

The LRU store is always local, for now.

<a name="server_loop-2"></a>

### server_loop/2 * ###

`server_loop(State, Opts) -> any()`

<a name="start-1"></a>

### start/1 ###

`start(StoreOpts) -> any()`

The default capacity is used when no capacity is provided in the store
options. Maximum number of retries when fetching cache entries that aren't
immediately found due to timing issues in concurrent operations.
Start the LRU cache.

<a name="stop-1"></a>

### stop/1 ###

`stop(Opts) -> any()`

Stop the LRU in memory by offloading the keys in the ETS tables
before exiting the process.

<a name="stop_test-0"></a>

### stop_test/0 * ###

`stop_test() -> any()`

<a name="sync-1"></a>

### sync/1 * ###

`sync(Server) -> any()`

Force the caller to wait until the server has fully processed all
messages in its mailbox, up to the initiation of the call.

<a name="table_keys-1"></a>

### table_keys/1 * ###

`table_keys(TableName) -> any()`

<a name="table_keys-2"></a>

### table_keys/2 * ###

`table_keys(TableName, Prefix) -> any()`

<a name="table_keys-4"></a>

### table_keys/4 * ###

`table_keys(TableName, CurrentKey, Prefix, Acc) -> any()`

<a name="test_opts-1"></a>

### test_opts/1 * ###

`test_opts(PersistentStore) -> any()`

Generate a set of options for testing. The default is to use an `fs` store
as the persistent backing.

<a name="test_opts-2"></a>

### test_opts/2 * ###

`test_opts(PersistentStore, Capacity) -> any()`

<a name="type-2"></a>

### type/2 ###

`type(Opts, Key) -> any()`

Determine the type of a key in the store.

<a name="type_test-0"></a>

### type_test/0 * ###

`type_test() -> any()`

<a name="unknown_value_test-0"></a>

### unknown_value_test/0 * ###

`unknown_value_test() -> any()`

<a name="update_cache_size-3"></a>

### update_cache_size/3 * ###

`update_cache_size(X1, PreviousSize, NewSize) -> any()`

<a name="update_recently_used-3"></a>

### update_recently_used/3 * ###

`update_recently_used(State, Key, Entry) -> any()`

<a name="write-3"></a>

### write/3 ###

`write(Opts, RawKey, Value) -> any()`

Write an entry in the cache.

After writing, the LRU is updated by moving the key in the most-recently-used
key to cycle and re-prioritize cache entry.


--- END OF FILE: docs/resources/source-code/hb_store_lru.md ---

--- START OF FILE: docs/resources/source-code/hb_store_remote_node.md ---
# [Module hb_store_remote_node.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_store_remote_node.erl)




A store module that reads data from another AO node.

<a name="description"></a>

## Description ##
Notably, this store only provides the _read_ side of the store interface.
The write side could be added, returning an commitment that the data has
been written to the remote node. In that case, the node would probably want
to upload it to an Arweave bundler to ensure persistence, too.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#make_link-3">make_link/3</a></td><td>Link a source to a destination in the remote node.</td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td>Read a key from the remote node.</td></tr><tr><td valign="top"><a href="#read_test-0">read_test/0*</a></td><td>Test that we can create a store, write a random message to it, then
start a remote node with that store, and read the message from it.</td></tr><tr><td valign="top"><a href="#resolve-2">resolve/2</a></td><td>Resolve a key path in the remote store.</td></tr><tr><td valign="top"><a href="#scope-1">scope/1</a></td><td>Return the scope of this store.</td></tr><tr><td valign="top"><a href="#type-2">type/2</a></td><td>Determine the type of value at a given key.</td></tr><tr><td valign="top"><a href="#write-3">write/3</a></td><td>Write a key to the remote node.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="make_link-3"></a>

### make_link/3 ###

`make_link(Opts, Source, Destination) -> any()`

Link a source to a destination in the remote node.

Constructs an HTTP POST link request. If a wallet is provided,
the message is signed. Returns {ok, Path} on HTTP 200, or
{error, Reason} on failure.

<a name="read-2"></a>

### read/2 ###

`read(Opts, Key) -> any()`

Read a key from the remote node.

Makes an HTTP GET request to the remote node and returns the
committed message.

<a name="read_test-0"></a>

### read_test/0 * ###

`read_test() -> any()`

Test that we can create a store, write a random message to it, then
start a remote node with that store, and read the message from it.

<a name="resolve-2"></a>

### resolve/2 ###

`resolve(X1, Key) -> any()`

Resolve a key path in the remote store.

For the remote node store, the key is returned as-is.

<a name="scope-1"></a>

### scope/1 ###

`scope(Arg) -> any()`

Return the scope of this store.

For the remote store, the scope is always `remote`.

<a name="type-2"></a>

### type/2 ###

`type(Opts, Key) -> any()`

Determine the type of value at a given key.

Remote nodes support only the `simple` type or `not_found`.

<a name="write-3"></a>

### write/3 ###

`write(Opts, Key, Value) -> any()`

Write a key to the remote node.

Constructs an HTTP POST write request. If a wallet is provided,
the message is signed. Returns {ok, Path} on HTTP 200, or
{error, Reason} on failure.


--- END OF FILE: docs/resources/source-code/hb_store_remote_node.md ---

--- START OF FILE: docs/resources/source-code/hb_store_rocksdb.md ---
# [Module hb_store_rocksdb.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_store_rocksdb.erl)




A process wrapper over rocksdb storage.

__Behaviours:__ [`gen_server`](gen_server.md), [`hb_store`](hb_store.md).

<a name="description"></a>

## Description ##

Replicates functionality of the
hb_fs_store module.

Encodes the item types with the help of prefixes, see `encode_value/2`
and `decode_value/1`
<a name="types"></a>

## Data Types ##




### <a name="type-key">key()</a> ###


<pre><code>
key() = binary() | list()
</code></pre>




### <a name="type-value">value()</a> ###


<pre><code>
value() = binary() | list()
</code></pre>




### <a name="type-value_type">value_type()</a> ###


<pre><code>
value_type() = link | raw | group
</code></pre>

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_path-3">add_path/3</a></td><td>Add two path components together.</td></tr><tr><td valign="top"><a href="#code_change-3">code_change/3</a></td><td></td></tr><tr><td valign="top"><a href="#collect-1">collect/1*</a></td><td></td></tr><tr><td valign="top"><a href="#collect-2">collect/2*</a></td><td></td></tr><tr><td valign="top"><a href="#convert_if_list-1">convert_if_list/1*</a></td><td></td></tr><tr><td valign="top"><a href="#decode_value-1">decode_value/1*</a></td><td></td></tr><tr><td valign="top"><a href="#do_read-2">do_read/2*</a></td><td></td></tr><tr><td valign="top"><a href="#do_resolve-3">do_resolve/3*</a></td><td></td></tr><tr><td valign="top"><a href="#do_write-3">do_write/3*</a></td><td>Write given Key and Value to the database.</td></tr><tr><td valign="top"><a href="#enabled-0">enabled/0</a></td><td>Returns whether the RocksDB store is enabled.</td></tr><tr><td valign="top"><a href="#encode_value-2">encode_value/2*</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_dir-2">ensure_dir/2*</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_dir-3">ensure_dir/3*</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_list-1">ensure_list/1*</a></td><td>Ensure that the given filename is a list, not a binary.</td></tr><tr><td valign="top"><a href="#handle_call-3">handle_call/3</a></td><td></td></tr><tr><td valign="top"><a href="#handle_cast-2">handle_cast/2</a></td><td></td></tr><tr><td valign="top"><a href="#handle_info-2">handle_info/2</a></td><td></td></tr><tr><td valign="top"><a href="#init-1">init/1</a></td><td></td></tr><tr><td valign="top"><a href="#join-1">join/1*</a></td><td></td></tr><tr><td valign="top"><a href="#list-0">list/0</a></td><td>List all items registered in rocksdb store.</td></tr><tr><td valign="top"><a href="#list-2">list/2</a></td><td>Returns the full list of items stored under the given path.</td></tr><tr><td valign="top"><a href="#make_group-2">make_group/2</a></td><td>Creates group under the given path.</td></tr><tr><td valign="top"><a href="#make_link-3">make_link/3</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_append_key_to_group-2">maybe_append_key_to_group/2*</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_convert_to_binary-1">maybe_convert_to_binary/1*</a></td><td></td></tr><tr><td valign="top"><a href="#maybe_create_dir-3">maybe_create_dir/3*</a></td><td></td></tr><tr><td valign="top"><a href="#open_rockdb-1">open_rockdb/1*</a></td><td></td></tr><tr><td valign="top"><a href="#path-2">path/2</a></td><td>Return path.</td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td>Read data by the key.</td></tr><tr><td valign="top"><a href="#reset-1">reset/1</a></td><td></td></tr><tr><td valign="top"><a href="#resolve-2">resolve/2</a></td><td>Replace links in a path with the target of the link.</td></tr><tr><td valign="top"><a href="#scope-1">scope/1</a></td><td>Return scope (local).</td></tr><tr><td valign="top"><a href="#start-1">start/1</a></td><td></td></tr><tr><td valign="top"><a href="#start_link-1">start_link/1</a></td><td>Start the RocksDB store.</td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td></td></tr><tr><td valign="top"><a href="#terminate-2">terminate/2</a></td><td></td></tr><tr><td valign="top"><a href="#type-2">type/2</a></td><td>Get type of the current item.</td></tr><tr><td valign="top"><a href="#write-3">write/3</a></td><td>Write given Key and Value to the database.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_path-3"></a>

### add_path/3 ###

`add_path(Opts, Path1, Path2) -> any()`

Add two path components together. // is not used

<a name="code_change-3"></a>

### code_change/3 ###

`code_change(OldVsn, State, Extra) -> any()`

<a name="collect-1"></a>

### collect/1 * ###

`collect(Iterator) -> any()`

<a name="collect-2"></a>

### collect/2 * ###

`collect(Iterator, Acc) -> any()`

<a name="convert_if_list-1"></a>

### convert_if_list/1 * ###

`convert_if_list(Value) -> any()`

<a name="decode_value-1"></a>

### decode_value/1 * ###

<pre><code>
decode_value(X1::binary()) -&gt; {<a href="#type-value_type">value_type()</a>, binary()}
</code></pre>
<br />

<a name="do_read-2"></a>

### do_read/2 * ###

`do_read(Opts, Key) -> any()`

<a name="do_resolve-3"></a>

### do_resolve/3 * ###

`do_resolve(Opts, FinalPath, Rest) -> any()`

<a name="do_write-3"></a>

### do_write/3 * ###

<pre><code>
do_write(Opts, Key, Value) -&gt; Result
</code></pre>

<ul class="definitions"><li><code>Opts = map()</code></li><li><code>Key = <a href="#type-key">key()</a></code></li><li><code>Value = <a href="#type-value">value()</a></code></li><li><code>Result = ok | {error, any()}</code></li></ul>

Write given Key and Value to the database

<a name="enabled-0"></a>

### enabled/0 ###

`enabled() -> any()`

Returns whether the RocksDB store is enabled.

<a name="encode_value-2"></a>

### encode_value/2 * ###

<pre><code>
encode_value(X1::<a href="#type-value_type">value_type()</a>, Value::binary()) -&gt; binary()
</code></pre>
<br />

<a name="ensure_dir-2"></a>

### ensure_dir/2 * ###

`ensure_dir(DBHandle, BaseDir) -> any()`

<a name="ensure_dir-3"></a>

### ensure_dir/3 * ###

`ensure_dir(DBHandle, CurrentPath, Rest) -> any()`

<a name="ensure_list-1"></a>

### ensure_list/1 * ###

`ensure_list(Value) -> any()`

Ensure that the given filename is a list, not a binary.

<a name="handle_call-3"></a>

### handle_call/3 ###

`handle_call(Request, From, State) -> any()`

<a name="handle_cast-2"></a>

### handle_cast/2 ###

`handle_cast(Request, State) -> any()`

<a name="handle_info-2"></a>

### handle_info/2 ###

`handle_info(Info, State) -> any()`

<a name="init-1"></a>

### init/1 ###

`init(Dir) -> any()`

<a name="join-1"></a>

### join/1 * ###

`join(Key) -> any()`

<a name="list-0"></a>

### list/0 ###

`list() -> any()`

List all items registered in rocksdb store. Should be used only
for testing/debugging, as the underlying operation is doing full traversal
on the KV storage, and is slow.

<a name="list-2"></a>

### list/2 ###

<pre><code>
list(Opts, Path) -&gt; Result
</code></pre>

<ul class="definitions"><li><code>Opts = any()</code></li><li><code>Path = any()</code></li><li><code>Result = {ok, [string()]} | {error, term()}</code></li></ul>

Returns the full list of items stored under the given path. Where the path
child items is relevant to the path of parentItem. (Same as in `hb_store_fs`).

<a name="make_group-2"></a>

### make_group/2 ###

<pre><code>
make_group(Opts, Key) -&gt; Result
</code></pre>

<ul class="definitions"><li><code>Opts = any()</code></li><li><code>Key = binary()</code></li><li><code>Result = ok | {error, already_added}</code></li></ul>

Creates group under the given path.

<a name="make_link-3"></a>

### make_link/3 ###

<pre><code>
make_link(Opts::any(), Key1::<a href="#type-key">key()</a>, New::<a href="#type-key">key()</a>) -&gt; ok
</code></pre>
<br />

<a name="maybe_append_key_to_group-2"></a>

### maybe_append_key_to_group/2 * ###

`maybe_append_key_to_group(Key, CurrentDirContents) -> any()`

<a name="maybe_convert_to_binary-1"></a>

### maybe_convert_to_binary/1 * ###

`maybe_convert_to_binary(Value) -> any()`

<a name="maybe_create_dir-3"></a>

### maybe_create_dir/3 * ###

`maybe_create_dir(DBHandle, DirPath, Value) -> any()`

<a name="open_rockdb-1"></a>

### open_rockdb/1 * ###

`open_rockdb(RawDir) -> any()`

<a name="path-2"></a>

### path/2 ###

`path(Opts, Path) -> any()`

Return path

<a name="read-2"></a>

### read/2 ###

<pre><code>
read(Opts, Key) -&gt; Result
</code></pre>

<ul class="definitions"><li><code>Opts = map()</code></li><li><code>Key = <a href="#type-key">key()</a> | list()</code></li><li><code>Result = {ok, <a href="#type-value">value()</a>} | not_found | {error, {corruption, string()}} | {error, any()}</code></li></ul>

Read data by the key.
Recursively follows link messages

<a name="reset-1"></a>

### reset/1 ###

<pre><code>
reset(Opts::[]) -&gt; ok | no_return()
</code></pre>
<br />

<a name="resolve-2"></a>

### resolve/2 ###

<pre><code>
resolve(Opts, Path) -&gt; Result
</code></pre>

<ul class="definitions"><li><code>Opts = any()</code></li><li><code>Path = binary() | list()</code></li><li><code>Result = not_found | string()</code></li></ul>

Replace links in a path with the target of the link.

<a name="scope-1"></a>

### scope/1 ###

`scope(X1) -> any()`

Return scope (local)

<a name="start-1"></a>

### start/1 ###

`start(Opts) -> any()`

<a name="start_link-1"></a>

### start_link/1 ###

`start_link(Opts) -> any()`

Start the RocksDB store.

<a name="stop-1"></a>

### stop/1 ###

<pre><code>
stop(Opts::any()) -&gt; ok
</code></pre>
<br />

<a name="terminate-2"></a>

### terminate/2 ###

`terminate(Reason, State) -> any()`

<a name="type-2"></a>

### type/2 ###

<pre><code>
type(Opts, Key) -&gt; Result
</code></pre>

<ul class="definitions"><li><code>Opts = map()</code></li><li><code>Key = binary()</code></li><li><code>Result = composite | simple | not_found</code></li></ul>

Get type of the current item

<a name="write-3"></a>

### write/3 ###

<pre><code>
write(Opts, Key, Value) -&gt; Result
</code></pre>

<ul class="definitions"><li><code>Opts = map()</code></li><li><code>Key = <a href="#type-key">key()</a></code></li><li><code>Value = <a href="#type-value">value()</a></code></li><li><code>Result = ok | {error, any()}</code></li></ul>

Write given Key and Value to the database


--- END OF FILE: docs/resources/source-code/hb_store_rocksdb.md ---

--- START OF FILE: docs/resources/source-code/hb_store.md ---
# [Module hb_store.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_store.erl)




A simple abstraction layer for AO key value store operations.

<a name="description"></a>

## Description ##

This interface allows us to swap out the underlying store implementation(s)
as desired, without changing the API that `hb_cache` employs. Additionally,
it enables node operators to customize their configuration to maximize
performance, data availability, and other factors.

Stores can be represented in a node's configuration as either a single
message, or a (`structured@1.0`) list of store messages. If a list of stores
is provided, the node will cycle through each until a viable store is found
to execute the given function.

A valid store must implement a _subset_ of the following functions:
``start/1:      Initialize the store.
stop/1:       Stop any processes (etc.) that manage the store.
reset/1:      Restore the store to its original, empty state.
scope/0:      A tag describing the`scope' of a stores search: `in_memory`,
`local`, `remote`, `arweave`, etc. Used in order to allow
node operators to prioritize their stores for search.
make_group/2: Create a new group of keys in the store with the given ID.
make_link/3:  Create a link (implying one key should redirect to another)
from `existing` to `new` (in that order).
type/2:       Return whether the value found at the given key is a
`composite` (group) type, or a `simple` direct binary.
read/2:       Read the data at the given location, returning a binary
if it is a `simple` value, or a message if it is a complex
term.
write/3:      Write the given `key` with the associated `value` (in that
order) to the store.
list/2:       For `composite` type keys, return a list of its child keys.
path/2:       Optionally transform a list of path parts into the store's
canonical form.
'''
Each function takes a `store` message first, containing an arbitrary set
of its necessary configuration keys, as well as the `store-module` key which
refers to the Erlang module that implements the store.

All functions must return `ok` or `{ok, Result}`, as appropriate. Other
results will lead to the store manager (this module) iterating to the next
store message given by the user. If none of the given store messages are
able to execute a requested service, the store manager will return
`not_found`.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_path-2">add_path/2</a></td><td>Add two path components together.</td></tr><tr><td valign="top"><a href="#add_path-3">add_path/3</a></td><td></td></tr><tr><td valign="top"><a href="#behavior_info-1">behavior_info/1</a></td><td></td></tr><tr><td valign="top"><a href="#benchmark_key_read_write-1">benchmark_key_read_write/1*</a></td><td>Benchmark a store.</td></tr><tr><td valign="top"><a href="#benchmark_key_read_write-3">benchmark_key_read_write/3*</a></td><td></td></tr><tr><td valign="top"><a href="#benchmark_message_read_write-1">benchmark_message_read_write/1*</a></td><td></td></tr><tr><td valign="top"><a href="#benchmark_message_read_write-3">benchmark_message_read_write/3*</a></td><td></td></tr><tr><td valign="top"><a href="#benchmark_suite_test_-0">benchmark_suite_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#call_all-3">call_all/3*</a></td><td>Call a function on all modules in the store.</td></tr><tr><td valign="top"><a href="#call_function-3">call_function/3*</a></td><td>Call a function on the first store module that succeeds.</td></tr><tr><td valign="top"><a href="#do_call_function-3">do_call_function/3*</a></td><td></td></tr><tr><td valign="top"><a href="#do_find-1">do_find/1*</a></td><td></td></tr><tr><td valign="top"><a href="#ensure_instance_alive-2">ensure_instance_alive/2*</a></td><td>Handle a found instance message.</td></tr><tr><td valign="top"><a href="#filter-2">filter/2</a></td><td>Takes a store object and a filter function or match spec, returning a
new store object with only the modules that match the filter.</td></tr><tr><td valign="top"><a href="#find-1">find/1</a></td><td>Find or spawn a store instance by its store opts.</td></tr><tr><td valign="top"><a href="#generate_test_suite-1">generate_test_suite/1</a></td><td></td></tr><tr><td valign="top"><a href="#generate_test_suite-2">generate_test_suite/2</a></td><td></td></tr><tr><td valign="top"><a href="#get_store_scope-1">get_store_scope/1*</a></td><td>Ask a store for its own scope.</td></tr><tr><td valign="top"><a href="#hierarchical_path_resolution_test-1">hierarchical_path_resolution_test/1*</a></td><td>Ensure that we can resolve links through a directory.</td></tr><tr><td valign="top"><a href="#join-1">join/1</a></td><td>Join a list of path components together.</td></tr><tr><td valign="top"><a href="#list-2">list/2</a></td><td>List the keys in a group in the store.</td></tr><tr><td valign="top"><a href="#make_group-2">make_group/2</a></td><td>Make a group in the store.</td></tr><tr><td valign="top"><a href="#make_link-3">make_link/3</a></td><td>Make a link from one path to another in the store.</td></tr><tr><td valign="top"><a href="#path-1">path/1</a></td><td>Create a path from a list of path components.</td></tr><tr><td valign="top"><a href="#path-2">path/2</a></td><td></td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td>Read a key from the store.</td></tr><tr><td valign="top"><a href="#reset-1">reset/1</a></td><td>Delete all of the keys in a store.</td></tr><tr><td valign="top"><a href="#resolve-2">resolve/2</a></td><td>Follow links through the store to resolve a path to its ultimate target.</td></tr><tr><td valign="top"><a href="#resursive_path_resolution_test-1">resursive_path_resolution_test/1*</a></td><td>Ensure that we can resolve links recursively.</td></tr><tr><td valign="top"><a href="#rocks_stores-0">rocks_stores/0*</a></td><td></td></tr><tr><td valign="top"><a href="#scope-2">scope/2</a></td><td>Limit the store scope to only a specific (set of) option(s).</td></tr><tr><td valign="top"><a href="#simple_path_resolution_test-1">simple_path_resolution_test/1*</a></td><td>Test path resolution dynamics.</td></tr><tr><td valign="top"><a href="#sort-2">sort/2</a></td><td>Order a store by a preference of its scopes.</td></tr><tr><td valign="top"><a href="#spawn_instance-1">spawn_instance/1*</a></td><td>Create a new instance of a store and return its term.</td></tr><tr><td valign="top"><a href="#start-1">start/1</a></td><td>Ensure that a store, or list of stores, have all been started.</td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td></td></tr><tr><td valign="top"><a href="#store_suite_test_-0">store_suite_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#test_stores-0">test_stores/0</a></td><td>Return a list of stores for testing.</td></tr><tr><td valign="top"><a href="#type-2">type/2</a></td><td>Get the type of element of a given path in the store.</td></tr><tr><td valign="top"><a href="#write-3">write/3</a></td><td>Write a key with a value to the store.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_path-2"></a>

### add_path/2 ###

`add_path(Path1, Path2) -> any()`

Add two path components together. If no store implements the add_path
function, we concatenate the paths.

<a name="add_path-3"></a>

### add_path/3 ###

`add_path(Store, Path1, Path2) -> any()`

<a name="behavior_info-1"></a>

### behavior_info/1 ###

`behavior_info(X1) -> any()`

<a name="benchmark_key_read_write-1"></a>

### benchmark_key_read_write/1 * ###

`benchmark_key_read_write(Store) -> any()`

Benchmark a store. By default, we write 10,000 keys and read 10,000
keys. This can be altered by setting the `STORE_BENCH_WRITE_OPS` and
`STORE_BENCH_READ_OPS` macros.

<a name="benchmark_key_read_write-3"></a>

### benchmark_key_read_write/3 * ###

`benchmark_key_read_write(Store, WriteOps, ReadOps) -> any()`

<a name="benchmark_message_read_write-1"></a>

### benchmark_message_read_write/1 * ###

`benchmark_message_read_write(Store) -> any()`

<a name="benchmark_message_read_write-3"></a>

### benchmark_message_read_write/3 * ###

`benchmark_message_read_write(Store, WriteOps, ReadOps) -> any()`

<a name="benchmark_suite_test_-0"></a>

### benchmark_suite_test_/0 * ###

`benchmark_suite_test_() -> any()`

<a name="call_all-3"></a>

### call_all/3 * ###

`call_all(X, Function, Args) -> any()`

Call a function on all modules in the store.

<a name="call_function-3"></a>

### call_function/3 * ###

`call_function(X, Function, Args) -> any()`

Call a function on the first store module that succeeds. Returns its
result, or `not_found` if none of the stores succeed. If `TIME_CALLS` is set,
this function will also time the call and increment the appropriate event
counter.

<a name="do_call_function-3"></a>

### do_call_function/3 * ###

`do_call_function(X, Function, Args) -> any()`

<a name="do_find-1"></a>

### do_find/1 * ###

`do_find(StoreOpts) -> any()`

<a name="ensure_instance_alive-2"></a>

### ensure_instance_alive/2 * ###

`ensure_instance_alive(StoreOpts, InstanceMessage) -> any()`

Handle a found instance message. If it contains a PID, we check if it
is alive. If it does not, we return it as is.

<a name="filter-2"></a>

### filter/2 ###

`filter(Module, Filter) -> any()`

Takes a store object and a filter function or match spec, returning a
new store object with only the modules that match the filter. The filter
function takes 2 arguments: the scope and the options. It calls the store's
scope function to get the scope of the module.

<a name="find-1"></a>

### find/1 ###

`find(StoreOpts) -> any()`

Find or spawn a store instance by its store opts.

<a name="generate_test_suite-1"></a>

### generate_test_suite/1 ###

`generate_test_suite(Suite) -> any()`

<a name="generate_test_suite-2"></a>

### generate_test_suite/2 ###

`generate_test_suite(Suite, Stores) -> any()`

<a name="get_store_scope-1"></a>

### get_store_scope/1 * ###

`get_store_scope(Store) -> any()`

Ask a store for its own scope. If it doesn't have one, return the
default scope (local).

<a name="hierarchical_path_resolution_test-1"></a>

### hierarchical_path_resolution_test/1 * ###

`hierarchical_path_resolution_test(Store) -> any()`

Ensure that we can resolve links through a directory.

<a name="join-1"></a>

### join/1 ###

`join(Path) -> any()`

Join a list of path components together.

<a name="list-2"></a>

### list/2 ###

`list(Modules, Path) -> any()`

List the keys in a group in the store. Use only in debugging.
The hyperbeam model assumes that stores are built as efficient hash-based
structures, so this is likely to be very slow for most stores.

<a name="make_group-2"></a>

### make_group/2 ###

`make_group(Modules, Path) -> any()`

Make a group in the store. A group can be seen as a namespace or
'directory' in a filesystem.

<a name="make_link-3"></a>

### make_link/3 ###

`make_link(Modules, Existing, New) -> any()`

Make a link from one path to another in the store.

<a name="path-1"></a>

### path/1 ###

`path(Path) -> any()`

Create a path from a list of path components. If no store implements
the path function, we return the path with the 'default' transformation (id).

<a name="path-2"></a>

### path/2 ###

`path(X1, Path) -> any()`

<a name="read-2"></a>

### read/2 ###

`read(Modules, Key) -> any()`

Read a key from the store.

<a name="reset-1"></a>

### reset/1 ###

`reset(Modules) -> any()`

Delete all of the keys in a store. Should be used with extreme
caution. Lost data can lose money in many/most of hyperbeam's use cases.

<a name="resolve-2"></a>

### resolve/2 ###

`resolve(Modules, Path) -> any()`

Follow links through the store to resolve a path to its ultimate target.

<a name="resursive_path_resolution_test-1"></a>

### resursive_path_resolution_test/1 * ###

`resursive_path_resolution_test(Store) -> any()`

Ensure that we can resolve links recursively.

<a name="rocks_stores-0"></a>

### rocks_stores/0 * ###

`rocks_stores() -> any()`

<a name="scope-2"></a>

### scope/2 ###

`scope(Opts, Scope) -> any()`

Limit the store scope to only a specific (set of) option(s).
Takes either an Opts message or store, and either a single scope or a list
of scopes.

<a name="simple_path_resolution_test-1"></a>

### simple_path_resolution_test/1 * ###

`simple_path_resolution_test(Store) -> any()`

Test path resolution dynamics.

<a name="sort-2"></a>

### sort/2 ###

`sort(Stores, PreferenceOrder) -> any()`

Order a store by a preference of its scopes. This is useful for making
sure that faster (or perhaps cheaper) stores are used first. If a list is
provided, it will be used as a preference order. If a map is provided,
scopes will be ordered by the scores in the map. Any unknown scopes will
default to a score of 0.

<a name="spawn_instance-1"></a>

### spawn_instance/1 * ###

`spawn_instance(StoreOpts) -> any()`

Create a new instance of a store and return its term.

<a name="start-1"></a>

### start/1 ###

`start(StoreOpts) -> any()`

Ensure that a store, or list of stores, have all been started.

<a name="stop-1"></a>

### stop/1 ###

`stop(Modules) -> any()`

<a name="store_suite_test_-0"></a>

### store_suite_test_/0 * ###

`store_suite_test_() -> any()`

<a name="test_stores-0"></a>

### test_stores/0 ###

`test_stores() -> any()`

Return a list of stores for testing. Additional individual functions are
used to generate store options for those whose drivers are not built by
default into all HyperBEAM distributions.

<a name="type-2"></a>

### type/2 ###

`type(Modules, Path) -> any()`

Get the type of element of a given path in the store. This can be
a performance killer if the store is remote etc. Use only when necessary.

<a name="write-3"></a>

### write/3 ###

`write(Modules, Key, Value) -> any()`

Write a key with a value to the store.


--- END OF FILE: docs/resources/source-code/hb_store.md ---

--- START OF FILE: docs/resources/source-code/hb_structured_fields.md ---
# [Module hb_structured_fields.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_structured_fields.erl)




A module for parsing and converting between Erlang and HTTP Structured
Fields, as described in RFC-9651.

<a name="description"></a>

## Description ##

The mapping between Erlang and structured headers types is as follow:

List: list()
Inner list: {list, [item()], params()}
Dictionary: [{binary(), item()}]
There is no distinction between empty list and empty dictionary.
Item with parameters: {item, bare_item(), params()}
Parameters: [{binary(), bare_item()}]
Bare item: one bare_item() that can be of type:
Integer: integer()
Decimal: {decimal, {integer(), integer()}}
String: {string, binary()}
Token: {token, binary()}
Byte sequence: {binary, binary()}
Boolean: boolean()
<a name="types"></a>

## Data Types ##




### <a name="type-sh_bare_item">sh_bare_item()</a> ###


<pre><code>
sh_bare_item() = integer() | <a href="#type-sh_decimal">sh_decimal()</a> | boolean() | {string | token | binary, binary()}
</code></pre>




### <a name="type-sh_decimal">sh_decimal()</a> ###


<pre><code>
sh_decimal() = {decimal, {integer(), integer()}}
</code></pre>




### <a name="type-sh_dictionary">sh_dictionary()</a> ###


<pre><code>
sh_dictionary() = [{binary(), <a href="#type-sh_item">sh_item()</a> | <a href="#type-sh_inner_list">sh_inner_list()</a>}]
</code></pre>




### <a name="type-sh_inner_list">sh_inner_list()</a> ###


<pre><code>
sh_inner_list() = {list, [<a href="#type-sh_item">sh_item()</a>], <a href="#type-sh_params">sh_params()</a>}
</code></pre>




### <a name="type-sh_item">sh_item()</a> ###


<pre><code>
sh_item() = {item, <a href="#type-sh_bare_item">sh_bare_item()</a>, <a href="#type-sh_params">sh_params()</a>}
</code></pre>




### <a name="type-sh_list">sh_list()</a> ###


<pre><code>
sh_list() = [<a href="#type-sh_item">sh_item()</a> | <a href="#type-sh_inner_list">sh_inner_list()</a>]
</code></pre>




### <a name="type-sh_params">sh_params()</a> ###


<pre><code>
sh_params() = [{binary(), <a href="#type-sh_bare_item">sh_bare_item()</a>}]
</code></pre>

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#bare_item-1">bare_item/1</a></td><td></td></tr><tr><td valign="top"><a href="#dictionary-1">dictionary/1</a></td><td></td></tr><tr><td valign="top"><a href="#e2t-1">e2t/1*</a></td><td></td></tr><tr><td valign="top"><a href="#e2tb-1">e2tb/1*</a></td><td></td></tr><tr><td valign="top"><a href="#e2tp-1">e2tp/1*</a></td><td></td></tr><tr><td valign="top"><a href="#escape_string-2">escape_string/2*</a></td><td></td></tr><tr><td valign="top"><a href="#exp_div-1">exp_div/1*</a></td><td></td></tr><tr><td valign="top"><a href="#expected_to_term-1">expected_to_term/1*</a></td><td></td></tr><tr><td valign="top"><a href="#from_bare_item-1">from_bare_item/1</a></td><td>Convert an SF <code>bare_item</code> to an Erlang term.</td></tr><tr><td valign="top"><a href="#inner_list-1">inner_list/1*</a></td><td></td></tr><tr><td valign="top"><a href="#item-1">item/1</a></td><td></td></tr><tr><td valign="top"><a href="#item_or_inner_list-1">item_or_inner_list/1*</a></td><td></td></tr><tr><td valign="top"><a href="#key_to_binary-1">key_to_binary/1*</a></td><td>Convert an Erlang term to a binary key.</td></tr><tr><td valign="top"><a href="#list-1">list/1</a></td><td></td></tr><tr><td valign="top"><a href="#params-1">params/1*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_bare_item-1">parse_bare_item/1</a></td><td>Parse an integer or decimal.</td></tr><tr><td valign="top"><a href="#parse_before_param-2">parse_before_param/2*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_binary-1">parse_binary/1</a></td><td>Parse a byte sequence binary.</td></tr><tr><td valign="top"><a href="#parse_binary-2">parse_binary/2*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_decimal-5">parse_decimal/5*</a></td><td>Parse a decimal binary.</td></tr><tr><td valign="top"><a href="#parse_dict_before_member-2">parse_dict_before_member/2*</a></td><td>Parse a binary SF dictionary before a member.</td></tr><tr><td valign="top"><a href="#parse_dict_before_sep-2">parse_dict_before_sep/2*</a></td><td>Parse a binary SF dictionary before a separator.</td></tr><tr><td valign="top"><a href="#parse_dict_key-3">parse_dict_key/3*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_dictionary-1">parse_dictionary/1</a></td><td>Parse a binary SF dictionary.</td></tr><tr><td valign="top"><a href="#parse_inner_list-2">parse_inner_list/2*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_item-1">parse_item/1</a></td><td>Parse a binary SF item to an SF <code>item</code>.</td></tr><tr><td valign="top"><a href="#parse_item1-1">parse_item1/1*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_list-1">parse_list/1</a></td><td>Parse a binary SF list.</td></tr><tr><td valign="top"><a href="#parse_list_before_member-2">parse_list_before_member/2*</a></td><td>Parse a binary SF list before a member.</td></tr><tr><td valign="top"><a href="#parse_list_before_sep-2">parse_list_before_sep/2*</a></td><td>Parse a binary SF list before a separator.</td></tr><tr><td valign="top"><a href="#parse_list_member-2">parse_list_member/2*</a></td><td>Parse a binary SF list before a member.</td></tr><tr><td valign="top"><a href="#parse_number-3">parse_number/3*</a></td><td>Parse an integer or decimal binary.</td></tr><tr><td valign="top"><a href="#parse_param-3">parse_param/3*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_string-2">parse_string/2*</a></td><td>Parse a string binary.</td></tr><tr><td valign="top"><a href="#parse_struct_hd_test_-0">parse_struct_hd_test_/0*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_token-2">parse_token/2*</a></td><td>Parse a token binary.</td></tr><tr><td valign="top"><a href="#raw_to_binary-1">raw_to_binary/1*</a></td><td></td></tr><tr><td valign="top"><a href="#to_bare_item-1">to_bare_item/1*</a></td><td>Convert an Erlang term to an SF <code>bare_item</code>.</td></tr><tr><td valign="top"><a href="#to_dictionary-1">to_dictionary/1</a></td><td>Convert a map to a dictionary.</td></tr><tr><td valign="top"><a href="#to_dictionary-2">to_dictionary/2*</a></td><td></td></tr><tr><td valign="top"><a href="#to_dictionary_depth_test-0">to_dictionary_depth_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to_dictionary_test-0">to_dictionary_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to_inner_item-1">to_inner_item/1*</a></td><td>Convert an Erlang term to an SF <code>item</code>.</td></tr><tr><td valign="top"><a href="#to_inner_list-1">to_inner_list/1*</a></td><td>Convert an inner list to an SF term.</td></tr><tr><td valign="top"><a href="#to_inner_list-2">to_inner_list/2*</a></td><td></td></tr><tr><td valign="top"><a href="#to_inner_list-3">to_inner_list/3*</a></td><td></td></tr><tr><td valign="top"><a href="#to_item-1">to_item/1</a></td><td>Convert an item to a dictionary.</td></tr><tr><td valign="top"><a href="#to_item-2">to_item/2</a></td><td></td></tr><tr><td valign="top"><a href="#to_item_or_inner_list-1">to_item_or_inner_list/1*</a></td><td>Convert an Erlang term to an SF <code>item</code> or <code>inner_list</code>.</td></tr><tr><td valign="top"><a href="#to_item_test-0">to_item_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to_list-1">to_list/1</a></td><td>Convert a list to an SF term.</td></tr><tr><td valign="top"><a href="#to_list-2">to_list/2*</a></td><td></td></tr><tr><td valign="top"><a href="#to_list_depth_test-0">to_list_depth_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to_list_test-0">to_list_test/0*</a></td><td></td></tr><tr><td valign="top"><a href="#to_param-1">to_param/1*</a></td><td>Convert an Erlang term to an SF <code>parameter</code>.</td></tr><tr><td valign="top"><a href="#trim_ws-1">trim_ws/1*</a></td><td></td></tr><tr><td valign="top"><a href="#trim_ws_end-2">trim_ws_end/2*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="bare_item-1"></a>

### bare_item/1 ###

`bare_item(Integer) -> any()`

<a name="dictionary-1"></a>

### dictionary/1 ###

<pre><code>
dictionary(Map::#{binary() =&gt; <a href="#type-sh_item">sh_item()</a> | <a href="#type-sh_inner_list">sh_inner_list()</a>} | <a href="#type-sh_dictionary">sh_dictionary()</a>) -&gt; iolist()
</code></pre>
<br />

<a name="e2t-1"></a>

### e2t/1 * ###

`e2t(Dict) -> any()`

<a name="e2tb-1"></a>

### e2tb/1 * ###

`e2tb(V) -> any()`

<a name="e2tp-1"></a>

### e2tp/1 * ###

`e2tp(Params) -> any()`

<a name="escape_string-2"></a>

### escape_string/2 * ###

`escape_string(X1, Acc) -> any()`

<a name="exp_div-1"></a>

### exp_div/1 * ###

`exp_div(N) -> any()`

<a name="expected_to_term-1"></a>

### expected_to_term/1 * ###

`expected_to_term(Dict) -> any()`

<a name="from_bare_item-1"></a>

### from_bare_item/1 ###

`from_bare_item(BareItem) -> any()`

Convert an SF `bare_item` to an Erlang term.

<a name="inner_list-1"></a>

### inner_list/1 * ###

`inner_list(X1) -> any()`

<a name="item-1"></a>

### item/1 ###

<pre><code>
item(X1::<a href="#type-sh_item">sh_item()</a>) -&gt; iolist()
</code></pre>
<br />

<a name="item_or_inner_list-1"></a>

### item_or_inner_list/1 * ###

`item_or_inner_list(Value) -> any()`

<a name="key_to_binary-1"></a>

### key_to_binary/1 * ###

`key_to_binary(Key) -> any()`

Convert an Erlang term to a binary key.

<a name="list-1"></a>

### list/1 ###

<pre><code>
list(List::<a href="#type-sh_list">sh_list()</a>) -&gt; iolist()
</code></pre>
<br />

<a name="params-1"></a>

### params/1 * ###

`params(Params) -> any()`

<a name="parse_bare_item-1"></a>

### parse_bare_item/1 ###

`parse_bare_item(X1) -> any()`

Parse an integer or decimal.

<a name="parse_before_param-2"></a>

### parse_before_param/2 * ###

`parse_before_param(X1, Acc) -> any()`

<a name="parse_binary-1"></a>

### parse_binary/1 ###

`parse_binary(Bin) -> any()`

Parse a byte sequence binary.

<a name="parse_binary-2"></a>

### parse_binary/2 * ###

`parse_binary(X1, Acc) -> any()`

<a name="parse_decimal-5"></a>

### parse_decimal/5 * ###

`parse_decimal(R, L1, L2, IntAcc, FracAcc) -> any()`

Parse a decimal binary.

<a name="parse_dict_before_member-2"></a>

### parse_dict_before_member/2 * ###

`parse_dict_before_member(X1, Acc) -> any()`

Parse a binary SF dictionary before a member.

<a name="parse_dict_before_sep-2"></a>

### parse_dict_before_sep/2 * ###

`parse_dict_before_sep(X1, Acc) -> any()`

Parse a binary SF dictionary before a separator.

<a name="parse_dict_key-3"></a>

### parse_dict_key/3 * ###

`parse_dict_key(R, Acc, K) -> any()`

<a name="parse_dictionary-1"></a>

### parse_dictionary/1 ###

<pre><code>
parse_dictionary(X1::binary()) -&gt; <a href="#type-sh_dictionary">sh_dictionary()</a>
</code></pre>
<br />

Parse a binary SF dictionary.

<a name="parse_inner_list-2"></a>

### parse_inner_list/2 * ###

`parse_inner_list(R0, Acc) -> any()`

<a name="parse_item-1"></a>

### parse_item/1 ###

<pre><code>
parse_item(Bin::binary()) -&gt; <a href="#type-sh_item">sh_item()</a>
</code></pre>
<br />

Parse a binary SF item to an SF `item`.

<a name="parse_item1-1"></a>

### parse_item1/1 * ###

`parse_item1(Bin) -> any()`

<a name="parse_list-1"></a>

### parse_list/1 ###

<pre><code>
parse_list(Bin::binary()) -&gt; <a href="#type-sh_list">sh_list()</a>
</code></pre>
<br />

Parse a binary SF list.

<a name="parse_list_before_member-2"></a>

### parse_list_before_member/2 * ###

`parse_list_before_member(R, Acc) -> any()`

Parse a binary SF list before a member.

<a name="parse_list_before_sep-2"></a>

### parse_list_before_sep/2 * ###

`parse_list_before_sep(X1, Acc) -> any()`

Parse a binary SF list before a separator.

<a name="parse_list_member-2"></a>

### parse_list_member/2 * ###

`parse_list_member(R0, Acc) -> any()`

Parse a binary SF list before a member.

<a name="parse_number-3"></a>

### parse_number/3 * ###

`parse_number(R, L, Acc) -> any()`

Parse an integer or decimal binary.

<a name="parse_param-3"></a>

### parse_param/3 * ###

`parse_param(R, Acc, K) -> any()`

<a name="parse_string-2"></a>

### parse_string/2 * ###

`parse_string(X1, Acc) -> any()`

Parse a string binary.

<a name="parse_struct_hd_test_-0"></a>

### parse_struct_hd_test_/0 * ###

`parse_struct_hd_test_() -> any()`

<a name="parse_token-2"></a>

### parse_token/2 * ###

`parse_token(R, Acc) -> any()`

Parse a token binary.

<a name="raw_to_binary-1"></a>

### raw_to_binary/1 * ###

`raw_to_binary(RawList) -> any()`

<a name="to_bare_item-1"></a>

### to_bare_item/1 * ###

`to_bare_item(BareItem) -> any()`

Convert an Erlang term to an SF `bare_item`.

<a name="to_dictionary-1"></a>

### to_dictionary/1 ###

`to_dictionary(Map) -> any()`

Convert a map to a dictionary.

<a name="to_dictionary-2"></a>

### to_dictionary/2 * ###

`to_dictionary(Dict, Rest) -> any()`

<a name="to_dictionary_depth_test-0"></a>

### to_dictionary_depth_test/0 * ###

`to_dictionary_depth_test() -> any()`

<a name="to_dictionary_test-0"></a>

### to_dictionary_test/0 * ###

`to_dictionary_test() -> any()`

<a name="to_inner_item-1"></a>

### to_inner_item/1 * ###

`to_inner_item(Item) -> any()`

Convert an Erlang term to an SF `item`.

<a name="to_inner_list-1"></a>

### to_inner_list/1 * ###

`to_inner_list(Inner) -> any()`

Convert an inner list to an SF term.

<a name="to_inner_list-2"></a>

### to_inner_list/2 * ###

`to_inner_list(Inner, Params) -> any()`

<a name="to_inner_list-3"></a>

### to_inner_list/3 * ###

`to_inner_list(Inner, Rest, Params) -> any()`

<a name="to_item-1"></a>

### to_item/1 ###

`to_item(Item) -> any()`

Convert an item to a dictionary.

<a name="to_item-2"></a>

### to_item/2 ###

`to_item(Item, Params) -> any()`

<a name="to_item_or_inner_list-1"></a>

### to_item_or_inner_list/1 * ###

`to_item_or_inner_list(ItemOrInner) -> any()`

Convert an Erlang term to an SF `item` or `inner_list`.

<a name="to_item_test-0"></a>

### to_item_test/0 * ###

`to_item_test() -> any()`

<a name="to_list-1"></a>

### to_list/1 ###

`to_list(List) -> any()`

Convert a list to an SF term.

<a name="to_list-2"></a>

### to_list/2 * ###

`to_list(Acc, Rest) -> any()`

<a name="to_list_depth_test-0"></a>

### to_list_depth_test/0 * ###

`to_list_depth_test() -> any()`

<a name="to_list_test-0"></a>

### to_list_test/0 * ###

`to_list_test() -> any()`

<a name="to_param-1"></a>

### to_param/1 * ###

`to_param(X1) -> any()`

Convert an Erlang term to an SF `parameter`.

<a name="trim_ws-1"></a>

### trim_ws/1 * ###

`trim_ws(R) -> any()`

<a name="trim_ws_end-2"></a>

### trim_ws_end/2 * ###

`trim_ws_end(Value, N) -> any()`


--- END OF FILE: docs/resources/source-code/hb_structured_fields.md ---

--- START OF FILE: docs/resources/source-code/hb_sup.md ---
# [Module hb_sup.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_sup.erl)




__Behaviours:__ [`supervisor`](supervisor.md).

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#init-1">init/1</a></td><td></td></tr><tr><td valign="top"><a href="#start_link-0">start_link/0</a></td><td></td></tr><tr><td valign="top"><a href="#start_link-1">start_link/1</a></td><td></td></tr><tr><td valign="top"><a href="#store_children-1">store_children/1*</a></td><td>Generate a child spec for stores in the given Opts.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="init-1"></a>

### init/1 ###

`init(Opts) -> any()`

<a name="start_link-0"></a>

### start_link/0 ###

`start_link() -> any()`

<a name="start_link-1"></a>

### start_link/1 ###

`start_link(Opts) -> any()`

<a name="store_children-1"></a>

### store_children/1 * ###

`store_children(Store) -> any()`

Generate a child spec for stores in the given Opts.


--- END OF FILE: docs/resources/source-code/hb_sup.md ---

--- START OF FILE: docs/resources/source-code/hb_test_utils.md ---
# [Module hb_test_utils.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_test_utils.erl)




Simple utilities for testing HyperBEAM.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#run-4">run/4</a></td><td></td></tr><tr><td valign="top"><a href="#satisfies_requirements-1">satisfies_requirements/1*</a></td><td>Determine if the environment satisfies the given test requirements.</td></tr><tr><td valign="top"><a href="#suite_with_opts-2">suite_with_opts/2</a></td><td>Run each test in a suite with each set of options.</td></tr><tr><td valign="top"><a href="#test_store-0">test_store/0</a></td><td>Generate a new, unique test store as an isolated context for an execution.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="run-4"></a>

### run/4 ###

`run(Name, OptsName, Suite, OptsList) -> any()`

<a name="satisfies_requirements-1"></a>

### satisfies_requirements/1 * ###

`satisfies_requirements(Requirements) -> any()`

Determine if the environment satisfies the given test requirements.
Requirements is a list of atoms, each corresponding to a module that must
return true if it exposes an `enabled/0` function.

<a name="suite_with_opts-2"></a>

### suite_with_opts/2 ###

`suite_with_opts(Suite, OptsList) -> any()`

Run each test in a suite with each set of options. Start and reset
the store(s) for each test. Expects suites to be a list of tuples with
the test name, description, and test function.
The list of `Opts` should contain maps with the `name` and `opts` keys.
Each element may also contain a `skip` key with a list of test names to skip.
They can also contain a `desc` key with a description of the options.

<a name="test_store-0"></a>

### test_store/0 ###

`test_store() -> any()`

Generate a new, unique test store as an isolated context for an execution.


--- END OF FILE: docs/resources/source-code/hb_test_utils.md ---

--- START OF FILE: docs/resources/source-code/hb_tracer.md ---
# [Module hb_tracer.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_tracer.erl)




A module for tracing the flow of requests through the system.

<a name="description"></a>

## Description ##
This allows for tracking the lifecycle of a request from HTTP receipt through processing and response.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#checkmark_emoji-0">checkmark_emoji/0*</a></td><td></td></tr><tr><td valign="top"><a href="#failure_emoji-0">failure_emoji/0*</a></td><td></td></tr><tr><td valign="top"><a href="#format_error_trace-1">format_error_trace/1</a></td><td>Format a trace for error in a user-friendly emoji oriented output.</td></tr><tr><td valign="top"><a href="#get_trace-1">get_trace/1</a></td><td>Exports the complete queue of events.</td></tr><tr><td valign="top"><a href="#record_step-2">record_step/2</a></td><td>Register a new step into a tracer.</td></tr><tr><td valign="top"><a href="#stage_to_emoji-1">stage_to_emoji/1*</a></td><td></td></tr><tr><td valign="top"><a href="#start_trace-0">start_trace/0</a></td><td>Start a new tracer acting as queue of events registered.</td></tr><tr><td valign="top"><a href="#trace_loop-1">trace_loop/1*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="checkmark_emoji-0"></a>

### checkmark_emoji/0 * ###

`checkmark_emoji() -> any()`

<a name="failure_emoji-0"></a>

### failure_emoji/0 * ###

`failure_emoji() -> any()`

<a name="format_error_trace-1"></a>

### format_error_trace/1 ###

`format_error_trace(Trace) -> any()`

Format a trace for error in a user-friendly emoji oriented output

<a name="get_trace-1"></a>

### get_trace/1 ###

`get_trace(TracePID) -> any()`

Exports the complete queue of events

<a name="record_step-2"></a>

### record_step/2 ###

`record_step(TracePID, Step) -> any()`

Register a new step into a tracer

<a name="stage_to_emoji-1"></a>

### stage_to_emoji/1 * ###

`stage_to_emoji(Stage) -> any()`

<a name="start_trace-0"></a>

### start_trace/0 ###

`start_trace() -> any()`

Start a new tracer acting as queue of events registered.

<a name="trace_loop-1"></a>

### trace_loop/1 * ###

`trace_loop(Trace) -> any()`


--- END OF FILE: docs/resources/source-code/hb_tracer.md ---

--- START OF FILE: docs/resources/source-code/hb_util.md ---
# [Module hb_util.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_util.erl)




A collection of utility functions for building with HyperBEAM.

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#add_commas-1">add_commas/1*</a></td><td></td></tr><tr><td valign="top"><a href="#addresses_to_binary-1">addresses_to_binary/1*</a></td><td>Serialize the given list of addresses to a binary, using the structured
fields format.</td></tr><tr><td valign="top"><a href="#all_hb_modules-0">all_hb_modules/0</a></td><td>Get all loaded modules that are loaded and are part of HyperBEAM.</td></tr><tr><td valign="top"><a href="#atom-1">atom/1</a></td><td>Coerce a string to an atom.</td></tr><tr><td valign="top"><a href="#bin-1">bin/1</a></td><td>Coerce a value to a binary.</td></tr><tr><td valign="top"><a href="#binary_to_addresses-1">binary_to_addresses/1</a></td><td>Parse a list from a binary.</td></tr><tr><td valign="top"><a href="#count-2">count/2</a></td><td></td></tr><tr><td valign="top"><a href="#debug_fmt-1">debug_fmt/1</a></td><td>Convert a term to a string for debugging print purposes.</td></tr><tr><td valign="top"><a href="#debug_fmt-2">debug_fmt/2</a></td><td></td></tr><tr><td valign="top"><a href="#debug_print-4">debug_print/4</a></td><td>Print a message to the standard error stream, prefixed by the amount
of time that has elapsed since the last call to this function.</td></tr><tr><td valign="top"><a href="#decode-1">decode/1</a></td><td>Try to decode a URL safe base64 into a binary or throw an error when
invalid.</td></tr><tr><td valign="top"><a href="#deep_merge-3">deep_merge/3</a></td><td>Deep merge two maps, recursively merging nested maps.</td></tr><tr><td valign="top"><a href="#do_debug_fmt-2">do_debug_fmt/2*</a></td><td></td></tr><tr><td valign="top"><a href="#do_to_lines-1">do_to_lines/1*</a></td><td></td></tr><tr><td valign="top"><a href="#encode-1">encode/1</a></td><td>Encode a binary to URL safe base64 binary string.</td></tr><tr><td valign="top"><a href="#eunit_print-2">eunit_print/2</a></td><td>Format and print an indented string to standard error.</td></tr><tr><td valign="top"><a href="#find_value-2">find_value/2</a></td><td>Find the value associated with a key in parsed a JSON structure list.</td></tr><tr><td valign="top"><a href="#find_value-3">find_value/3</a></td><td></td></tr><tr><td valign="top"><a href="#find_value-4">find_value/4*</a></td><td></td></tr><tr><td valign="top"><a href="#float-1">float/1</a></td><td>Coerce a string to a float.</td></tr><tr><td valign="top"><a href="#format_address-2">format_address/2*</a></td><td>If the user attempts to print a wallet, format it as an address.</td></tr><tr><td valign="top"><a href="#format_binary-1">format_binary/1</a></td><td>Format a binary as a short string suitable for printing.</td></tr><tr><td valign="top"><a href="#format_debug_trace-3">format_debug_trace/3*</a></td><td>Generate the appropriate level of trace for a given call.</td></tr><tr><td valign="top"><a href="#format_indented-2">format_indented/2</a></td><td>Format a string with an indentation level.</td></tr><tr><td valign="top"><a href="#format_indented-3">format_indented/3</a></td><td></td></tr><tr><td valign="top"><a href="#format_maybe_multiline-2">format_maybe_multiline/2</a></td><td>Format a map as either a single line or a multi-line string depending
on the value of the <code>debug_print_map_line_threshold</code> runtime option.</td></tr><tr><td valign="top"><a href="#format_trace-1">format_trace/1</a></td><td>Format a stack trace as a list of strings, one for each stack frame.</td></tr><tr><td valign="top"><a href="#format_trace-2">format_trace/2*</a></td><td></td></tr><tr><td valign="top"><a href="#format_trace_short-1">format_trace_short/1</a></td><td>Format a trace to a short string.</td></tr><tr><td valign="top"><a href="#format_trace_short-4">format_trace_short/4*</a></td><td></td></tr><tr><td valign="top"><a href="#format_tuple-2">format_tuple/2*</a></td><td>Helper function to format tuples with arity greater than 2.</td></tr><tr><td valign="top"><a href="#get_trace-0">get_trace/0*</a></td><td>Get the trace of the current process.</td></tr><tr><td valign="top"><a href="#hd-1">hd/1</a></td><td>Get the first element (the lowest integer key >= 1) of a numbered map.</td></tr><tr><td valign="top"><a href="#hd-2">hd/2</a></td><td></td></tr><tr><td valign="top"><a href="#hd-3">hd/3</a></td><td></td></tr><tr><td valign="top"><a href="#hd-5">hd/5*</a></td><td></td></tr><tr><td valign="top"><a href="#human_id-1">human_id/1</a></td><td>Convert a native binary ID to a human readable ID.</td></tr><tr><td valign="top"><a href="#human_int-1">human_int/1</a></td><td>Add <code>,</code> characters to a number every 3 digits to make it human readable.</td></tr><tr><td valign="top"><a href="#id-1">id/1</a></td><td>Return the human-readable form of an ID of a message when given either
a message explicitly, raw encoded ID, or an Erlang Arweave <code>tx</code> record.</td></tr><tr><td valign="top"><a href="#id-2">id/2</a></td><td></td></tr><tr><td valign="top"><a href="#int-1">int/1</a></td><td>Coerce a string to an integer.</td></tr><tr><td valign="top"><a href="#is_hb_module-1">is_hb_module/1</a></td><td>Is the given module part of HyperBEAM?.</td></tr><tr><td valign="top"><a href="#is_hb_module-2">is_hb_module/2</a></td><td></td></tr><tr><td valign="top"><a href="#is_human_binary-1">is_human_binary/1*</a></td><td>Determine whether a binary is human-readable.</td></tr><tr><td valign="top"><a href="#is_ordered_list-2">is_ordered_list/2</a></td><td>Determine if the message given is an ordered list, starting from 1.</td></tr><tr><td valign="top"><a href="#is_ordered_list-3">is_ordered_list/3*</a></td><td></td></tr><tr><td valign="top"><a href="#is_string_list-1">is_string_list/1</a></td><td>Is the given term a string list?.</td></tr><tr><td valign="top"><a href="#key_to_atom-2">key_to_atom/2</a></td><td>Convert keys in a map to atoms, lowering <code>-</code> to <code>_</code>.</td></tr><tr><td valign="top"><a href="#list-1">list/1</a></td><td>Coerce a value to a list.</td></tr><tr><td valign="top"><a href="#list_intersection-2">list_intersection/2*</a></td><td>Returns the intersection of two lists, with stable ordering.</td></tr><tr><td valign="top"><a href="#list_replace-3">list_replace/3</a></td><td>Replace a key in a list with a new value.</td></tr><tr><td valign="top"><a href="#list_to_numbered_message-1">list_to_numbered_message/1</a></td><td>Convert a list of elements to a map with numbered keys.</td></tr><tr><td valign="top"><a href="#maybe_throw-2">maybe_throw/2</a></td><td>Throw an exception if the Opts map has an <code>error_strategy</code> key with the
value <code>throw</code>.</td></tr><tr><td valign="top"><a href="#mean-1">mean/1</a></td><td></td></tr><tr><td valign="top"><a href="#message_to_ordered_list-1">message_to_ordered_list/1</a></td><td>Take a message with numbered keys and convert it to a list of tuples
with the associated key as an integer.</td></tr><tr><td valign="top"><a href="#message_to_ordered_list-2">message_to_ordered_list/2</a></td><td></td></tr><tr><td valign="top"><a href="#message_to_ordered_list-4">message_to_ordered_list/4*</a></td><td></td></tr><tr><td valign="top"><a href="#native_id-1">native_id/1</a></td><td>Convert a human readable ID to a native binary ID.</td></tr><tr><td valign="top"><a href="#normalize_trace-1">normalize_trace/1*</a></td><td>Remove all calls from this module from the top of a trace.</td></tr><tr><td valign="top"><a href="#number-1">number/1</a></td><td>Label a list of elements with a number.</td></tr><tr><td valign="top"><a href="#ok-1">ok/1</a></td><td>Unwrap a tuple of the form <code>{ok, Value}</code>, or throw/return, depending on
the value of the <code>error_strategy</code> option.</td></tr><tr><td valign="top"><a href="#ok-2">ok/2</a></td><td></td></tr><tr><td valign="top"><a href="#pick_weighted-2">pick_weighted/2*</a></td><td>Pick a random element from a list, weighted by the values in the list.</td></tr><tr><td valign="top"><a href="#print_trace-3">print_trace/3*</a></td><td></td></tr><tr><td valign="top"><a href="#print_trace-4">print_trace/4</a></td><td>Print the trace of the current stack, up to the first non-hyperbeam
module.</td></tr><tr><td valign="top"><a href="#print_trace_short-4">print_trace_short/4</a></td><td>Print a trace to the standard error stream.</td></tr><tr><td valign="top"><a href="#remove_common-2">remove_common/2</a></td><td>Remove the common prefix from two strings, returning the remainder of the
first string.</td></tr><tr><td valign="top"><a href="#remove_trailing_noise-1">remove_trailing_noise/1*</a></td><td></td></tr><tr><td valign="top"><a href="#remove_trailing_noise-2">remove_trailing_noise/2</a></td><td></td></tr><tr><td valign="top"><a href="#safe_decode-1">safe_decode/1</a></td><td>Safely decode a URL safe base64 into a binary returning an ok or error
tuple.</td></tr><tr><td valign="top"><a href="#safe_encode-1">safe_encode/1</a></td><td>Safely encode a binary to URL safe base64.</td></tr><tr><td valign="top"><a href="#server_id-0">server_id/0*</a></td><td>Retreive the server ID of the calling process, if known.</td></tr><tr><td valign="top"><a href="#server_id-1">server_id/1*</a></td><td></td></tr><tr><td valign="top"><a href="#short_id-1">short_id/1</a></td><td>Return a short ID for the different types of IDs used in AO-Core.</td></tr><tr><td valign="top"><a href="#shuffle-1">shuffle/1*</a></td><td>Shuffle a list.</td></tr><tr><td valign="top"><a href="#stddev-1">stddev/1</a></td><td></td></tr><tr><td valign="top"><a href="#to_hex-1">to_hex/1</a></td><td>Convert a binary to a hex string.</td></tr><tr><td valign="top"><a href="#to_lines-1">to_lines/1*</a></td><td></td></tr><tr><td valign="top"><a href="#to_lower-1">to_lower/1</a></td><td>Convert a binary to a lowercase.</td></tr><tr><td valign="top"><a href="#to_sorted_keys-1">to_sorted_keys/1</a></td><td>Given a map or KVList, return a deterministically ordered list of its keys.</td></tr><tr><td valign="top"><a href="#to_sorted_keys-2">to_sorted_keys/2</a></td><td></td></tr><tr><td valign="top"><a href="#to_sorted_list-1">to_sorted_list/1</a></td><td>Given a map or KVList, return a deterministically sorted list of its
key-value pairs.</td></tr><tr><td valign="top"><a href="#to_sorted_list-2">to_sorted_list/2</a></td><td></td></tr><tr><td valign="top"><a href="#trace_macro_helper-5">trace_macro_helper/5</a></td><td>Utility function to help macro <code>?trace/0</code> remove the first frame of the
stack trace.</td></tr><tr><td valign="top"><a href="#unique-1">unique/1</a></td><td>Take a list and return a list of unique elements.</td></tr><tr><td valign="top"><a href="#until-1">until/1</a></td><td>Utility function to wait for a condition to be true.</td></tr><tr><td valign="top"><a href="#until-2">until/2</a></td><td></td></tr><tr><td valign="top"><a href="#until-3">until/3</a></td><td></td></tr><tr><td valign="top"><a href="#variance-1">variance/1</a></td><td></td></tr><tr><td valign="top"><a href="#weighted_random-1">weighted_random/1</a></td><td>Return a random element from a list, weighted by the values in the list.</td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="add_commas-1"></a>

### add_commas/1 * ###

`add_commas(Rest) -> any()`

<a name="addresses_to_binary-1"></a>

### addresses_to_binary/1 * ###

`addresses_to_binary(List) -> any()`

Serialize the given list of addresses to a binary, using the structured
fields format.

<a name="all_hb_modules-0"></a>

### all_hb_modules/0 ###

`all_hb_modules() -> any()`

Get all loaded modules that are loaded and are part of HyperBEAM.

<a name="atom-1"></a>

### atom/1 ###

`atom(Str) -> any()`

Coerce a string to an atom.

<a name="bin-1"></a>

### bin/1 ###

`bin(Value) -> any()`

Coerce a value to a binary.

<a name="binary_to_addresses-1"></a>

### binary_to_addresses/1 ###

`binary_to_addresses(List) -> any()`

Parse a list from a binary. First attempts to parse the binary as a
structured-fields list, and if that fails, it attempts to parse the list as
a comma-separated value, stripping quotes and whitespace.

<a name="count-2"></a>

### count/2 ###

`count(Item, List) -> any()`

<a name="debug_fmt-1"></a>

### debug_fmt/1 ###

`debug_fmt(X) -> any()`

Convert a term to a string for debugging print purposes.

<a name="debug_fmt-2"></a>

### debug_fmt/2 ###

`debug_fmt(X, Indent) -> any()`

<a name="debug_print-4"></a>

### debug_print/4 ###

`debug_print(X, Mod, Func, LineNum) -> any()`

Print a message to the standard error stream, prefixed by the amount
of time that has elapsed since the last call to this function.

<a name="decode-1"></a>

### decode/1 ###

`decode(Input) -> any()`

Try to decode a URL safe base64 into a binary or throw an error when
invalid.

<a name="deep_merge-3"></a>

### deep_merge/3 ###

`deep_merge(Map1, Map2, Opts) -> any()`

Deep merge two maps, recursively merging nested maps.

<a name="do_debug_fmt-2"></a>

### do_debug_fmt/2 * ###

`do_debug_fmt(Wallet, Indent) -> any()`

<a name="do_to_lines-1"></a>

### do_to_lines/1 * ###

`do_to_lines(In) -> any()`

<a name="encode-1"></a>

### encode/1 ###

`encode(Bin) -> any()`

Encode a binary to URL safe base64 binary string.

<a name="eunit_print-2"></a>

### eunit_print/2 ###

`eunit_print(FmtStr, FmtArgs) -> any()`

Format and print an indented string to standard error.

<a name="find_value-2"></a>

### find_value/2 ###

`find_value(Key, List) -> any()`

Find the value associated with a key in parsed a JSON structure list.

<a name="find_value-3"></a>

### find_value/3 ###

`find_value(Key, Map, Default) -> any()`

<a name="find_value-4"></a>

### find_value/4 * ###

`find_value(Key, Map, Default, Opts) -> any()`

<a name="float-1"></a>

### float/1 ###

`float(Str) -> any()`

Coerce a string to a float.

<a name="format_address-2"></a>

### format_address/2 * ###

`format_address(Wallet, Indent) -> any()`

If the user attempts to print a wallet, format it as an address.

<a name="format_binary-1"></a>

### format_binary/1 ###

`format_binary(Bin) -> any()`

Format a binary as a short string suitable for printing.

<a name="format_debug_trace-3"></a>

### format_debug_trace/3 * ###

`format_debug_trace(Mod, Func, Line) -> any()`

Generate the appropriate level of trace for a given call.

<a name="format_indented-2"></a>

### format_indented/2 ###

`format_indented(Str, Indent) -> any()`

Format a string with an indentation level.

<a name="format_indented-3"></a>

### format_indented/3 ###

`format_indented(RawStr, Fmt, Ind) -> any()`

<a name="format_maybe_multiline-2"></a>

### format_maybe_multiline/2 ###

`format_maybe_multiline(X, Indent) -> any()`

Format a map as either a single line or a multi-line string depending
on the value of the `debug_print_map_line_threshold` runtime option.

<a name="format_trace-1"></a>

### format_trace/1 ###

`format_trace(Stack) -> any()`

Format a stack trace as a list of strings, one for each stack frame.
Each stack frame is formatted if it matches the `stack_print_prefixes`
option. At the first frame that does not match a prefix in the
`stack_print_prefixes` option, the rest of the stack is not formatted.

<a name="format_trace-2"></a>

### format_trace/2 * ###

`format_trace(Rest, Prefixes) -> any()`

<a name="format_trace_short-1"></a>

### format_trace_short/1 ###

`format_trace_short(Trace) -> any()`

Format a trace to a short string.

<a name="format_trace_short-4"></a>

### format_trace_short/4 * ###

`format_trace_short(Max, Latch, Trace, Prefixes) -> any()`

<a name="format_tuple-2"></a>

### format_tuple/2 * ###

`format_tuple(Tuple, Indent) -> any()`

Helper function to format tuples with arity greater than 2.

<a name="get_trace-0"></a>

### get_trace/0 * ###

`get_trace() -> any()`

Get the trace of the current process.

<a name="hd-1"></a>

### hd/1 ###

`hd(Message) -> any()`

Get the first element (the lowest integer key >= 1) of a numbered map.
Optionally, it takes a specifier of whether to return the key or the value,
as well as a standard map of HyperBEAM runtime options.

<a name="hd-2"></a>

### hd/2 ###

`hd(Message, ReturnType) -> any()`

<a name="hd-3"></a>

### hd/3 ###

`hd(Message, ReturnType, Opts) -> any()`

<a name="hd-5"></a>

### hd/5 * ###

`hd(Map, Rest, Index, ReturnType, Opts) -> any()`

<a name="human_id-1"></a>

### human_id/1 ###

`human_id(Bin) -> any()`

Convert a native binary ID to a human readable ID. If the ID is already
a human readable ID, it is returned as is. If it is an ethereum address, it
is returned as is.

<a name="human_int-1"></a>

### human_int/1 ###

`human_int(Float) -> any()`

Add `,` characters to a number every 3 digits to make it human readable.

<a name="id-1"></a>

### id/1 ###

`id(Item) -> any()`

Return the human-readable form of an ID of a message when given either
a message explicitly, raw encoded ID, or an Erlang Arweave `tx` record.

<a name="id-2"></a>

### id/2 ###

`id(TX, Type) -> any()`

<a name="int-1"></a>

### int/1 ###

`int(Str) -> any()`

Coerce a string to an integer.

<a name="is_hb_module-1"></a>

### is_hb_module/1 ###

`is_hb_module(Atom) -> any()`

Is the given module part of HyperBEAM?

<a name="is_hb_module-2"></a>

### is_hb_module/2 ###

`is_hb_module(Atom, Prefixes) -> any()`

<a name="is_human_binary-1"></a>

### is_human_binary/1 * ###

`is_human_binary(Bin) -> any()`

Determine whether a binary is human-readable.

<a name="is_ordered_list-2"></a>

### is_ordered_list/2 ###

`is_ordered_list(Msg, Opts) -> any()`

Determine if the message given is an ordered list, starting from 1.

<a name="is_ordered_list-3"></a>

### is_ordered_list/3 * ###

`is_ordered_list(N, Msg, Opts) -> any()`

<a name="is_string_list-1"></a>

### is_string_list/1 ###

`is_string_list(MaybeString) -> any()`

Is the given term a string list?

<a name="key_to_atom-2"></a>

### key_to_atom/2 ###

`key_to_atom(Key, Mode) -> any()`

Convert keys in a map to atoms, lowering `-` to `_`.

<a name="list-1"></a>

### list/1 ###

`list(Value) -> any()`

Coerce a value to a list.

<a name="list_intersection-2"></a>

### list_intersection/2 * ###

`list_intersection(List1, List2) -> any()`

Returns the intersection of two lists, with stable ordering.

<a name="list_replace-3"></a>

### list_replace/3 ###

`list_replace(List, Key, Value) -> any()`

Replace a key in a list with a new value.

<a name="list_to_numbered_message-1"></a>

### list_to_numbered_message/1 ###

`list_to_numbered_message(Msg) -> any()`

Convert a list of elements to a map with numbered keys.

<a name="maybe_throw-2"></a>

### maybe_throw/2 ###

`maybe_throw(Val, Opts) -> any()`

Throw an exception if the Opts map has an `error_strategy` key with the
value `throw`. Otherwise, return the value.

<a name="mean-1"></a>

### mean/1 ###

`mean(List) -> any()`

<a name="message_to_ordered_list-1"></a>

### message_to_ordered_list/1 ###

`message_to_ordered_list(Message) -> any()`

Take a message with numbered keys and convert it to a list of tuples
with the associated key as an integer. Optionally, it takes a standard
message of HyperBEAM runtime options.

<a name="message_to_ordered_list-2"></a>

### message_to_ordered_list/2 ###

`message_to_ordered_list(Message, Opts) -> any()`

<a name="message_to_ordered_list-4"></a>

### message_to_ordered_list/4 * ###

`message_to_ordered_list(Message, Keys, Key, Opts) -> any()`

<a name="native_id-1"></a>

### native_id/1 ###

`native_id(Bin) -> any()`

Convert a human readable ID to a native binary ID. If the ID is already
a native binary ID, it is returned as is.

<a name="normalize_trace-1"></a>

### normalize_trace/1 * ###

`normalize_trace(Rest) -> any()`

Remove all calls from this module from the top of a trace.

<a name="number-1"></a>

### number/1 ###

`number(List) -> any()`

Label a list of elements with a number.

<a name="ok-1"></a>

### ok/1 ###

`ok(Value) -> any()`

Unwrap a tuple of the form `{ok, Value}`, or throw/return, depending on
the value of the `error_strategy` option.

<a name="ok-2"></a>

### ok/2 ###

`ok(Other, Opts) -> any()`

<a name="pick_weighted-2"></a>

### pick_weighted/2 * ###

`pick_weighted(Rest, Remaining) -> any()`

Pick a random element from a list, weighted by the values in the list.

<a name="print_trace-3"></a>

### print_trace/3 * ###

`print_trace(Stack, Label, CallerInfo) -> any()`

<a name="print_trace-4"></a>

### print_trace/4 ###

`print_trace(Stack, CallMod, CallFunc, CallLine) -> any()`

Print the trace of the current stack, up to the first non-hyperbeam
module. Prints each stack frame on a new line, until it finds a frame that
does not start with a prefix in the `stack_print_prefixes` hb_opts.
Optionally, you may call this function with a custom label and caller info,
which will be used instead of the default.

<a name="print_trace_short-4"></a>

### print_trace_short/4 ###

`print_trace_short(Trace, Mod, Func, Line) -> any()`

Print a trace to the standard error stream.

<a name="remove_common-2"></a>

### remove_common/2 ###

`remove_common(MainStr, SubStr) -> any()`

Remove the common prefix from two strings, returning the remainder of the
first string. This function also coerces lists to binaries where appropriate,
returning the type of the first argument.

<a name="remove_trailing_noise-1"></a>

### remove_trailing_noise/1 * ###

`remove_trailing_noise(Str) -> any()`

<a name="remove_trailing_noise-2"></a>

### remove_trailing_noise/2 ###

`remove_trailing_noise(Str, Noise) -> any()`

<a name="safe_decode-1"></a>

### safe_decode/1 ###

`safe_decode(E) -> any()`

Safely decode a URL safe base64 into a binary returning an ok or error
tuple.

<a name="safe_encode-1"></a>

### safe_encode/1 ###

`safe_encode(Bin) -> any()`

Safely encode a binary to URL safe base64.

<a name="server_id-0"></a>

### server_id/0 * ###

`server_id() -> any()`

Retreive the server ID of the calling process, if known.

<a name="server_id-1"></a>

### server_id/1 * ###

`server_id(Opts) -> any()`

<a name="short_id-1"></a>

### short_id/1 ###

`short_id(Bin) -> any()`

Return a short ID for the different types of IDs used in AO-Core.

<a name="shuffle-1"></a>

### shuffle/1 * ###

`shuffle(List) -> any()`

Shuffle a list.

<a name="stddev-1"></a>

### stddev/1 ###

`stddev(List) -> any()`

<a name="to_hex-1"></a>

### to_hex/1 ###

`to_hex(Bin) -> any()`

Convert a binary to a hex string. Do not use this for anything other than
generating a lower-case, non-special character id. It should not become part of
the core protocol. We use b64u for efficient encoding.

<a name="to_lines-1"></a>

### to_lines/1 * ###

`to_lines(Elems) -> any()`

<a name="to_lower-1"></a>

### to_lower/1 ###

`to_lower(Str) -> any()`

Convert a binary to a lowercase.

<a name="to_sorted_keys-1"></a>

### to_sorted_keys/1 ###

`to_sorted_keys(Msg) -> any()`

Given a map or KVList, return a deterministically ordered list of its keys.

<a name="to_sorted_keys-2"></a>

### to_sorted_keys/2 ###

`to_sorted_keys(Msg, Opts) -> any()`

<a name="to_sorted_list-1"></a>

### to_sorted_list/1 ###

`to_sorted_list(Msg) -> any()`

Given a map or KVList, return a deterministically sorted list of its
key-value pairs.

<a name="to_sorted_list-2"></a>

### to_sorted_list/2 ###

`to_sorted_list(Msg, Opts) -> any()`

<a name="trace_macro_helper-5"></a>

### trace_macro_helper/5 ###

`trace_macro_helper(Fun, X2, Mod, Func, Line) -> any()`

Utility function to help macro `?trace/0` remove the first frame of the
stack trace.

<a name="unique-1"></a>

### unique/1 ###

`unique(List) -> any()`

Take a list and return a list of unique elements. The function is
order-preserving.

<a name="until-1"></a>

### until/1 ###

`until(Condition) -> any()`

Utility function to wait for a condition to be true. Optionally,
you can pass a function that will be called with the current count of
iterations, returning an integer that will be added to the count. Once the
condition is true, the function will return the count.

<a name="until-2"></a>

### until/2 ###

`until(Condition, Count) -> any()`

<a name="until-3"></a>

### until/3 ###

`until(Condition, Fun, Count) -> any()`

<a name="variance-1"></a>

### variance/1 ###

`variance(List) -> any()`

<a name="weighted_random-1"></a>

### weighted_random/1 ###

`weighted_random(List) -> any()`

Return a random element from a list, weighted by the values in the list.


--- END OF FILE: docs/resources/source-code/hb_util.md ---

--- START OF FILE: docs/resources/source-code/hb_volume.md ---
# [Module hb_volume.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb_volume.erl)




<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#change_node_store-2">change_node_store/2</a></td><td></td></tr><tr><td valign="top"><a href="#check_for_device-1">check_for_device/1</a></td><td></td></tr><tr><td valign="top"><a href="#create_actual_partition-2">create_actual_partition/2*</a></td><td></td></tr><tr><td valign="top"><a href="#create_mount_info-3">create_mount_info/3*</a></td><td></td></tr><tr><td valign="top"><a href="#create_partition-2">create_partition/2</a></td><td></td></tr><tr><td valign="top"><a href="#format_disk-2">format_disk/2</a></td><td></td></tr><tr><td valign="top"><a href="#get_partition_info-1">get_partition_info/1*</a></td><td></td></tr><tr><td valign="top"><a href="#list_partitions-0">list_partitions/0</a></td><td></td></tr><tr><td valign="top"><a href="#mount_disk-4">mount_disk/4</a></td><td></td></tr><tr><td valign="top"><a href="#mount_opened_volume-3">mount_opened_volume/3*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_disk_info-2">parse_disk_info/2*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_disk_line-2">parse_disk_line/2*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_disk_model_line-2">parse_disk_model_line/2*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_disk_units_line-2">parse_disk_units_line/2*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_io_size_line-2">parse_io_size_line/2*</a></td><td></td></tr><tr><td valign="top"><a href="#parse_sector_size_line-2">parse_sector_size_line/2*</a></td><td></td></tr><tr><td valign="top"><a href="#process_disk_line-2">process_disk_line/2*</a></td><td></td></tr><tr><td valign="top"><a href="#update_store_config-2">update_store_config/2*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="change_node_store-2"></a>

### change_node_store/2 ###

<pre><code>
change_node_store(StorePath::binary(), CurrentStore::list()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

<a name="check_for_device-1"></a>

### check_for_device/1 ###

<pre><code>
check_for_device(Device::binary()) -&gt; boolean()
</code></pre>
<br />

<a name="create_actual_partition-2"></a>

### create_actual_partition/2 * ###

`create_actual_partition(Device, PartType) -> any()`

<a name="create_mount_info-3"></a>

### create_mount_info/3 * ###

`create_mount_info(Partition, MountPoint, VolumeName) -> any()`

<a name="create_partition-2"></a>

### create_partition/2 ###

<pre><code>
create_partition(Device::binary(), PartType::binary()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

<a name="format_disk-2"></a>

### format_disk/2 ###

<pre><code>
format_disk(Partition::binary(), EncKey::binary()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

<a name="get_partition_info-1"></a>

### get_partition_info/1 * ###

`get_partition_info(Device) -> any()`

<a name="list_partitions-0"></a>

### list_partitions/0 ###

<pre><code>
list_partitions() -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

<a name="mount_disk-4"></a>

### mount_disk/4 ###

<pre><code>
mount_disk(Partition::binary(), EncKey::binary(), MountPoint::binary(), VolumeName::binary()) -&gt; {ok, map()} | {error, binary()}
</code></pre>
<br />

<a name="mount_opened_volume-3"></a>

### mount_opened_volume/3 * ###

`mount_opened_volume(Partition, MountPoint, VolumeName) -> any()`

<a name="parse_disk_info-2"></a>

### parse_disk_info/2 * ###

`parse_disk_info(Device, Lines) -> any()`

<a name="parse_disk_line-2"></a>

### parse_disk_line/2 * ###

`parse_disk_line(Line, Info) -> any()`

<a name="parse_disk_model_line-2"></a>

### parse_disk_model_line/2 * ###

`parse_disk_model_line(Line, Info) -> any()`

<a name="parse_disk_units_line-2"></a>

### parse_disk_units_line/2 * ###

`parse_disk_units_line(Line, Info) -> any()`

<a name="parse_io_size_line-2"></a>

### parse_io_size_line/2 * ###

`parse_io_size_line(Line, Info) -> any()`

<a name="parse_sector_size_line-2"></a>

### parse_sector_size_line/2 * ###

`parse_sector_size_line(Line, Info) -> any()`

<a name="process_disk_line-2"></a>

### process_disk_line/2 * ###

`process_disk_line(Line, X2) -> any()`

<a name="update_store_config-2"></a>

### update_store_config/2 * ###

<pre><code>
update_store_config(StoreConfig::term(), NewPath::binary()) -&gt; term()
</code></pre>
<br />


--- END OF FILE: docs/resources/source-code/hb_volume.md ---

--- START OF FILE: docs/resources/source-code/hb.md ---
# [Module hb.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/hb.erl)




Hyperbeam is a decentralized node implementing the AO-Core protocol
on top of Arweave.

<a name="description"></a>

## Description ##

This protocol offers a computation layer for executing arbitrary logic on
top of the network's data.

Arweave is built to offer a robust, permanent storage layer for static data
over time. It can be seen as a globally distributed key-value store that
allows users to lookup IDs to retrieve data at any point in time:

`Arweave(ID) => Message`

Hyperbeam adds another layer of functionality on top of Arweave's protocol:
Allowing users to store and retrieve not only arbitrary bytes, but also to
perform execution of computation upon that data:

`Hyperbeam(Message1, Message2) => Message3`

When Hyperbeam executes a message, it will return a new message containing
the result of that execution, as well as signed commitments of its
correctness. If the computation that is executed is deterministic, recipients
of the new message are able to verify that the computation was performed
correctly. The new message may be stored back to Arweave if desired,
forming a permanent, verifiable, and decentralized log of computation.

The mechanisms described above form the basis of a decentralized and
verifiable compute engine without any relevant protocol-enforced
scalability limits. It is an implementation of a global, shared
supercomputer.

Hyperbeam can be used for an extremely large variety of applications, from
serving static Arweave data with signed commitments of correctness, to
executing smart contracts that have _built-in_ HTTP APIs. The Hyperbeam
node implementation implements AO, an Actor-Oriented process-based
environment for orchestrating computation over Arweave messages in order to
facilitate the execution of more traditional, consensus-based smart
contracts.

The core abstractions of the Hyperbeam node are broadly as follows:

1. The `hb` and `hb_opts` modules manage the node's configuration,
environment variables, and debugging tools.

2. The `hb_http` and `hb_http_server` modules manage all HTTP-related
functionality. `hb_http_server` handles turning received HTTP requests
into messages and applying those messages with the appropriate devices.
`hb_http` handles making requests and responding with messages. `cowboy`
is used to implement the underlying HTTP server.

3. `hb_ao` implements the computation logic of the node: A mechanism
for resolving messages to other messages, via the application of logic
implemented in `devices`. `hb_ao` also manages the loading of Erlang
modules for each device into the node's environment. There are many
different default devices implemented in the hyperbeam node, using the
namespace `dev_*`. Some of the critical components are:

- `dev_message`: The default handler for all messages that do not
specify their own device. The message device is also used to resolve
keys that are not implemented by the device specified in a message,
unless otherwise signalled.

- `dev_stack`: The device responsible for creating and executing stacks
of other devices on messages that request it. There are many uses for
this device, one of which is the resolution of AO processes.

- `dev_p4`: The device responsible for managing payments for the services
provided by the node.

4. `hb_store`, `hb_cache` and the store implementations forms a layered
system for managing the node's access to persistent storage. `hb_cache`
is used as a resolution mechanism for reading and writing messages, while
`hb_store` provides an abstraction over the underlying persistent key-value
byte storage mechanisms. Example `hb_store` mechanisms can be found in
`hb_store_fs` and `hb_store_remote_node`.

5. `ar_*` modules implement functionality related to the base-layer Arweave
protocol and are largely unchanged from their counterparts in the Arweave
node codebase presently maintained by the Digital History Association
(@dha-team/Arweave).

You can find documentation of a similar form to this note in each of the core
modules of the hyperbeam node.<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#address-0">address/0</a></td><td>Get the address of a wallet.</td></tr><tr><td valign="top"><a href="#address-1">address/1*</a></td><td></td></tr><tr><td valign="top"><a href="#benchmark-2">benchmark/2</a></td><td>Run a function as many times as possible in a given amount of time.</td></tr><tr><td valign="top"><a href="#benchmark-3">benchmark/3</a></td><td>Run multiple instances of a function in parallel for a given amount of time.</td></tr><tr><td valign="top"><a href="#build-0">build/0</a></td><td>Utility function to hot-recompile and load the hyperbeam environment.</td></tr><tr><td valign="top"><a href="#debug_wait-4">debug_wait/4</a></td><td>Utility function to wait for a given amount of time, printing a debug
message to the console first.</td></tr><tr><td valign="top"><a href="#deploy_scripts-0">deploy_scripts/0</a></td><td>Upload all scripts from the <code>scripts</code> directory to the node to Arweave,
printing their IDs.</td></tr><tr><td valign="top"><a href="#deploy_scripts-1">deploy_scripts/1*</a></td><td></td></tr><tr><td valign="top"><a href="#do_start_simple_pay-1">do_start_simple_pay/1*</a></td><td></td></tr><tr><td valign="top"><a href="#init-0">init/0</a></td><td>Initialize system-wide settings for the hyperbeam node.</td></tr><tr><td valign="top"><a href="#no_prod-3">no_prod/3</a></td><td>Utility function to throw an error if the current mode is prod and
non-prod ready code is being executed.</td></tr><tr><td valign="top"><a href="#now-0">now/0</a></td><td>Utility function to get the current time in milliseconds.</td></tr><tr><td valign="top"><a href="#profile-1">profile/1</a></td><td>Utility function to start a profiling session and run a function,
then analyze the results.</td></tr><tr><td valign="top"><a href="#read-1">read/1</a></td><td>Debugging function to read a message from the cache.</td></tr><tr><td valign="top"><a href="#read-2">read/2</a></td><td></td></tr><tr><td valign="top"><a href="#start_mainnet-0">start_mainnet/0</a></td><td>Start a mainnet server without payments.</td></tr><tr><td valign="top"><a href="#start_mainnet-1">start_mainnet/1</a></td><td></td></tr><tr><td valign="top"><a href="#start_simple_pay-0">start_simple_pay/0</a></td><td>Start a server with a <code>simple-pay@1.0</code> pre-processor.</td></tr><tr><td valign="top"><a href="#start_simple_pay-1">start_simple_pay/1</a></td><td></td></tr><tr><td valign="top"><a href="#start_simple_pay-2">start_simple_pay/2</a></td><td></td></tr><tr><td valign="top"><a href="#topup-3">topup/3</a></td><td>Helper for topping up a user's balance on a simple-pay node.</td></tr><tr><td valign="top"><a href="#topup-4">topup/4</a></td><td></td></tr><tr><td valign="top"><a href="#wallet-0">wallet/0</a></td><td></td></tr><tr><td valign="top"><a href="#wallet-1">wallet/1</a></td><td></td></tr><tr><td valign="top"><a href="#wallet-2">wallet/2*</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="address-0"></a>

### address/0 ###

`address() -> any()`

Get the address of a wallet. Defaults to the address of the wallet
specified by the `priv_key_location` configuration key. It can also take a
wallet tuple as an argument.

<a name="address-1"></a>

### address/1 * ###

`address(Wallet) -> any()`

<a name="benchmark-2"></a>

### benchmark/2 ###

`benchmark(Fun, TLen) -> any()`

Run a function as many times as possible in a given amount of time.

<a name="benchmark-3"></a>

### benchmark/3 ###

`benchmark(Fun, TLen, Procs) -> any()`

Run multiple instances of a function in parallel for a given amount of time.

<a name="build-0"></a>

### build/0 ###

`build() -> any()`

Utility function to hot-recompile and load the hyperbeam environment.

<a name="debug_wait-4"></a>

### debug_wait/4 ###

`debug_wait(T, Mod, Func, Line) -> any()`

Utility function to wait for a given amount of time, printing a debug
message to the console first.

<a name="deploy_scripts-0"></a>

### deploy_scripts/0 ###

`deploy_scripts() -> any()`

Upload all scripts from the `scripts` directory to the node to Arweave,
printing their IDs.

<a name="deploy_scripts-1"></a>

### deploy_scripts/1 * ###

`deploy_scripts(Dir) -> any()`

<a name="do_start_simple_pay-1"></a>

### do_start_simple_pay/1 * ###

`do_start_simple_pay(Opts) -> any()`

<a name="init-0"></a>

### init/0 ###

`init() -> any()`

Initialize system-wide settings for the hyperbeam node.

<a name="no_prod-3"></a>

### no_prod/3 ###

`no_prod(X, Mod, Line) -> any()`

Utility function to throw an error if the current mode is prod and
non-prod ready code is being executed. You can find these in the codebase
by looking for ?NO_PROD calls.

<a name="now-0"></a>

### now/0 ###

`now() -> any()`

Utility function to get the current time in milliseconds.

<a name="profile-1"></a>

### profile/1 ###

`profile(Fun) -> any()`

Utility function to start a profiling session and run a function,
then analyze the results. Obviously -- do not use in production.

<a name="read-1"></a>

### read/1 ###

`read(ID) -> any()`

Debugging function to read a message from the cache.
Specify either a scope atom (local or remote) or a store tuple
as the second argument.

<a name="read-2"></a>

### read/2 ###

`read(ID, ScopeAtom) -> any()`

<a name="start_mainnet-0"></a>

### start_mainnet/0 ###

`start_mainnet() -> any()`

Start a mainnet server without payments.

<a name="start_mainnet-1"></a>

### start_mainnet/1 ###

`start_mainnet(Port) -> any()`

<a name="start_simple_pay-0"></a>

### start_simple_pay/0 ###

`start_simple_pay() -> any()`

Start a server with a `simple-pay@1.0` pre-processor.

<a name="start_simple_pay-1"></a>

### start_simple_pay/1 ###

`start_simple_pay(Addr) -> any()`

<a name="start_simple_pay-2"></a>

### start_simple_pay/2 ###

`start_simple_pay(Addr, Port) -> any()`

<a name="topup-3"></a>

### topup/3 ###

`topup(Node, Amount, Recipient) -> any()`

Helper for topping up a user's balance on a simple-pay node.

<a name="topup-4"></a>

### topup/4 ###

`topup(Node, Amount, Recipient, Wallet) -> any()`

<a name="wallet-0"></a>

### wallet/0 ###

`wallet() -> any()`

<a name="wallet-1"></a>

### wallet/1 ###

`wallet(Location) -> any()`

<a name="wallet-2"></a>

### wallet/2 * ###

`wallet(Location, Opts) -> any()`


--- END OF FILE: docs/resources/source-code/hb.md ---

--- START OF FILE: docs/resources/source-code/index.md ---
# Source Code Documentation

Welcome to the source code documentation for HyperBEAM. This section provides detailed insights into the codebase, helping developers understand the structure, functionality, and implementation details of HyperBEAM and its components.

## Overview

HyperBEAM is built with a modular architecture to ensure scalability, maintainability, and extensibility. The source code is organized into distinct components, each serving a specific purpose within the ecosystem.

## Sections

- **HyperBEAM Core**: The main framework that orchestrates data processing, storage, and routing.
- **Compute Unit**: Handles computational tasks and integrates with the HyperBEAM core for distributed processing.
- **Trusted Execution Environment (TEE)**: Ensures secure execution of sensitive operations.
- **Client Libraries**: Tools and SDKs for interacting with HyperBEAM, including the JavaScript client.

## Getting Started

To explore the source code, you can clone the repository from [GitHub](https://github.com/permaweb/HyperBEAM).

## Navigation

Use the navigation menu to dive into specific parts of the codebase. Each module includes detailed documentation, code comments, and examples to assist in understanding and contributing to the project.


--- END OF FILE: docs/resources/source-code/index.md ---

--- START OF FILE: docs/resources/source-code/README.md ---


# The hb application #


## Modules ##


<table width="100%" border="0" summary="list of modules">
<tr><td><a href="ar_bundles.md" class="module">ar_bundles</a></td></tr>
<tr><td><a href="ar_deep_hash.md" class="module">ar_deep_hash</a></td></tr>
<tr><td><a href="ar_rate_limiter.md" class="module">ar_rate_limiter</a></td></tr>
<tr><td><a href="ar_timestamp.md" class="module">ar_timestamp</a></td></tr>
<tr><td><a href="ar_tx.md" class="module">ar_tx</a></td></tr>
<tr><td><a href="ar_wallet.md" class="module">ar_wallet</a></td></tr>
<tr><td><a href="dev_apply.md" class="module">dev_apply</a></td></tr>
<tr><td><a href="dev_cache.md" class="module">dev_cache</a></td></tr>
<tr><td><a href="dev_cacheviz.md" class="module">dev_cacheviz</a></td></tr>
<tr><td><a href="dev_codec_ans104.md" class="module">dev_codec_ans104</a></td></tr>
<tr><td><a href="dev_codec_flat.md" class="module">dev_codec_flat</a></td></tr>
<tr><td><a href="dev_codec_httpsig.md" class="module">dev_codec_httpsig</a></td></tr>
<tr><td><a href="dev_codec_httpsig_conv.md" class="module">dev_codec_httpsig_conv</a></td></tr>
<tr><td><a href="dev_codec_httpsig_siginfo.md" class="module">dev_codec_httpsig_siginfo</a></td></tr>
<tr><td><a href="dev_codec_json.md" class="module">dev_codec_json</a></td></tr>
<tr><td><a href="dev_codec_structured.md" class="module">dev_codec_structured</a></td></tr>
<tr><td><a href="dev_cron.md" class="module">dev_cron</a></td></tr>
<tr><td><a href="dev_cu.md" class="module">dev_cu</a></td></tr>
<tr><td><a href="dev_dedup.md" class="module">dev_dedup</a></td></tr>
<tr><td><a href="dev_delegated_compute.md" class="module">dev_delegated_compute</a></td></tr>
<tr><td><a href="dev_faff.md" class="module">dev_faff</a></td></tr>
<tr><td><a href="dev_genesis_wasm.md" class="module">dev_genesis_wasm</a></td></tr>
<tr><td><a href="dev_green_zone.md" class="module">dev_green_zone</a></td></tr>
<tr><td><a href="dev_hook.md" class="module">dev_hook</a></td></tr>
<tr><td><a href="dev_hyperbuddy.md" class="module">dev_hyperbuddy</a></td></tr>
<tr><td><a href="dev_json_iface.md" class="module">dev_json_iface</a></td></tr>
<tr><td><a href="dev_local_name.md" class="module">dev_local_name</a></td></tr>
<tr><td><a href="dev_lookup.md" class="module">dev_lookup</a></td></tr>
<tr><td><a href="dev_lua.md" class="module">dev_lua</a></td></tr>
<tr><td><a href="dev_lua_lib.md" class="module">dev_lua_lib</a></td></tr>
<tr><td><a href="dev_lua_test.md" class="module">dev_lua_test</a></td></tr>
<tr><td><a href="dev_lua_test_ledgers.md" class="module">dev_lua_test_ledgers</a></td></tr>
<tr><td><a href="dev_manifest.md" class="module">dev_manifest</a></td></tr>
<tr><td><a href="dev_message.md" class="module">dev_message</a></td></tr>
<tr><td><a href="dev_meta.md" class="module">dev_meta</a></td></tr>
<tr><td><a href="dev_monitor.md" class="module">dev_monitor</a></td></tr>
<tr><td><a href="dev_multipass.md" class="module">dev_multipass</a></td></tr>
<tr><td><a href="dev_name.md" class="module">dev_name</a></td></tr>
<tr><td><a href="dev_node_process.md" class="module">dev_node_process</a></td></tr>
<tr><td><a href="dev_p4.md" class="module">dev_p4</a></td></tr>
<tr><td><a href="dev_patch.md" class="module">dev_patch</a></td></tr>
<tr><td><a href="dev_poda.md" class="module">dev_poda</a></td></tr>
<tr><td><a href="dev_process.md" class="module">dev_process</a></td></tr>
<tr><td><a href="dev_process_cache.md" class="module">dev_process_cache</a></td></tr>
<tr><td><a href="dev_process_worker.md" class="module">dev_process_worker</a></td></tr>
<tr><td><a href="dev_push.md" class="module">dev_push</a></td></tr>
<tr><td><a href="dev_relay.md" class="module">dev_relay</a></td></tr>
<tr><td><a href="dev_router.md" class="module">dev_router</a></td></tr>
<tr><td><a href="dev_scheduler.md" class="module">dev_scheduler</a></td></tr>
<tr><td><a href="dev_scheduler_cache.md" class="module">dev_scheduler_cache</a></td></tr>
<tr><td><a href="dev_scheduler_formats.md" class="module">dev_scheduler_formats</a></td></tr>
<tr><td><a href="dev_scheduler_registry.md" class="module">dev_scheduler_registry</a></td></tr>
<tr><td><a href="dev_scheduler_server.md" class="module">dev_scheduler_server</a></td></tr>
<tr><td><a href="dev_simple_pay.md" class="module">dev_simple_pay</a></td></tr>
<tr><td><a href="dev_snp.md" class="module">dev_snp</a></td></tr>
<tr><td><a href="dev_snp_nif.md" class="module">dev_snp_nif</a></td></tr>
<tr><td><a href="dev_stack.md" class="module">dev_stack</a></td></tr>
<tr><td><a href="dev_test.md" class="module">dev_test</a></td></tr>
<tr><td><a href="dev_volume.md" class="module">dev_volume</a></td></tr>
<tr><td><a href="dev_wasi.md" class="module">dev_wasi</a></td></tr>
<tr><td><a href="dev_wasm.md" class="module">dev_wasm</a></td></tr>
<tr><td><a href="hb.md" class="module">hb</a></td></tr>
<tr><td><a href="hb_ao.md" class="module">hb_ao</a></td></tr>
<tr><td><a href="hb_ao_test_vectors.md" class="module">hb_ao_test_vectors</a></td></tr>
<tr><td><a href="hb_app.md" class="module">hb_app</a></td></tr>
<tr><td><a href="hb_beamr.md" class="module">hb_beamr</a></td></tr>
<tr><td><a href="hb_beamr_io.md" class="module">hb_beamr_io</a></td></tr>
<tr><td><a href="hb_cache.md" class="module">hb_cache</a></td></tr>
<tr><td><a href="hb_cache_control.md" class="module">hb_cache_control</a></td></tr>
<tr><td><a href="hb_cache_render.md" class="module">hb_cache_render</a></td></tr>
<tr><td><a href="hb_client.md" class="module">hb_client</a></td></tr>
<tr><td><a href="hb_crypto.md" class="module">hb_crypto</a></td></tr>
<tr><td><a href="hb_debugger.md" class="module">hb_debugger</a></td></tr>
<tr><td><a href="hb_escape.md" class="module">hb_escape</a></td></tr>
<tr><td><a href="hb_event.md" class="module">hb_event</a></td></tr>
<tr><td><a href="hb_examples.md" class="module">hb_examples</a></td></tr>
<tr><td><a href="hb_features.md" class="module">hb_features</a></td></tr>
<tr><td><a href="hb_gateway_client.md" class="module">hb_gateway_client</a></td></tr>
<tr><td><a href="hb_http.md" class="module">hb_http</a></td></tr>
<tr><td><a href="hb_http_benchmark_tests.md" class="module">hb_http_benchmark_tests</a></td></tr>
<tr><td><a href="hb_http_client.md" class="module">hb_http_client</a></td></tr>
<tr><td><a href="hb_http_client_sup.md" class="module">hb_http_client_sup</a></td></tr>
<tr><td><a href="hb_http_server.md" class="module">hb_http_server</a></td></tr>
<tr><td><a href="hb_json.md" class="module">hb_json</a></td></tr>
<tr><td><a href="hb_keccak.md" class="module">hb_keccak</a></td></tr>
<tr><td><a href="hb_link.md" class="module">hb_link</a></td></tr>
<tr><td><a href="hb_logger.md" class="module">hb_logger</a></td></tr>
<tr><td><a href="hb_maps.md" class="module">hb_maps</a></td></tr>
<tr><td><a href="hb_message.md" class="module">hb_message</a></td></tr>
<tr><td><a href="hb_message_test_vectors.md" class="module">hb_message_test_vectors</a></td></tr>
<tr><td><a href="hb_metrics_collector.md" class="module">hb_metrics_collector</a></td></tr>
<tr><td><a href="hb_name.md" class="module">hb_name</a></td></tr>
<tr><td><a href="hb_opts.md" class="module">hb_opts</a></td></tr>
<tr><td><a href="hb_path.md" class="module">hb_path</a></td></tr>
<tr><td><a href="hb_persistent.md" class="module">hb_persistent</a></td></tr>
<tr><td><a href="hb_private.md" class="module">hb_private</a></td></tr>
<tr><td><a href="hb_process_monitor.md" class="module">hb_process_monitor</a></td></tr>
<tr><td><a href="hb_router.md" class="module">hb_router</a></td></tr>
<tr><td><a href="hb_singleton.md" class="module">hb_singleton</a></td></tr>
<tr><td><a href="hb_store.md" class="module">hb_store</a></td></tr>
<tr><td><a href="hb_store_fs.md" class="module">hb_store_fs</a></td></tr>
<tr><td><a href="hb_store_gateway.md" class="module">hb_store_gateway</a></td></tr>
<tr><td><a href="hb_store_lmdb.md" class="module">hb_store_lmdb</a></td></tr>
<tr><td><a href="hb_store_lru.md" class="module">hb_store_lru</a></td></tr>
<tr><td><a href="hb_store_remote_node.md" class="module">hb_store_remote_node</a></td></tr>
<tr><td><a href="hb_store_rocksdb.md" class="module">hb_store_rocksdb</a></td></tr>
<tr><td><a href="hb_structured_fields.md" class="module">hb_structured_fields</a></td></tr>
<tr><td><a href="hb_sup.md" class="module">hb_sup</a></td></tr>
<tr><td><a href="hb_test_utils.md" class="module">hb_test_utils</a></td></tr>
<tr><td><a href="hb_tracer.md" class="module">hb_tracer</a></td></tr>
<tr><td><a href="hb_util.md" class="module">hb_util</a></td></tr>
<tr><td><a href="hb_volume.md" class="module">hb_volume</a></td></tr>
<tr><td><a href="rsa_pss.md" class="module">rsa_pss</a></td></tr></table>


--- END OF FILE: docs/resources/source-code/README.md ---

--- START OF FILE: docs/resources/source-code/rsa_pss.md ---
# [Module rsa_pss.erl](https://github.com/permaweb/HyperBEAM/blob/main/src/rsa_pss.erl)




Distributed under the Mozilla Public License v2.0.

Copyright (c) 2014-2015, Andrew Bennett

__Authors:__ Andrew Bennett ([`andrew@pixid.com`](mailto:andrew@pixid.com)).

<a name="description"></a>

## Description ##
Original available at:
https://github.com/potatosalad/erlang-crypto_rsassa_pss
<a name="types"></a>

## Data Types ##




### <a name="type-rsa_digest_type">rsa_digest_type()</a> ###


<pre><code>
rsa_digest_type() = md5 | sha | sha224 | sha256 | sha384 | sha512
</code></pre>




### <a name="type-rsa_private_key">rsa_private_key()</a> ###


<pre><code>
rsa_private_key() = #RSAPrivateKey{}
</code></pre>




### <a name="type-rsa_public_key">rsa_public_key()</a> ###


<pre><code>
rsa_public_key() = #RSAPublicKey{}
</code></pre>

<a name="index"></a>

## Function Index ##


<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#dp-2">dp/2*</a></td><td></td></tr><tr><td valign="top"><a href="#ep-2">ep/2*</a></td><td></td></tr><tr><td valign="top"><a href="#int_to_bit_size-1">int_to_bit_size/1*</a></td><td></td></tr><tr><td valign="top"><a href="#int_to_bit_size-2">int_to_bit_size/2*</a></td><td></td></tr><tr><td valign="top"><a href="#int_to_byte_size-1">int_to_byte_size/1*</a></td><td></td></tr><tr><td valign="top"><a href="#int_to_byte_size-2">int_to_byte_size/2*</a></td><td></td></tr><tr><td valign="top"><a href="#mgf1-3">mgf1/3*</a></td><td></td></tr><tr><td valign="top"><a href="#mgf1-5">mgf1/5*</a></td><td></td></tr><tr><td valign="top"><a href="#normalize_to_key_size-2">normalize_to_key_size/2*</a></td><td></td></tr><tr><td valign="top"><a href="#pad_to_key_size-2">pad_to_key_size/2*</a></td><td></td></tr><tr><td valign="top"><a href="#sign-3">sign/3</a></td><td></td></tr><tr><td valign="top"><a href="#sign-4">sign/4</a></td><td></td></tr><tr><td valign="top"><a href="#verify-4">verify/4</a></td><td></td></tr><tr><td valign="top"><a href="#verify_legacy-4">verify_legacy/4</a></td><td></td></tr></table>


<a name="functions"></a>

## Function Details ##

<a name="dp-2"></a>

### dp/2 * ###

`dp(B, X2) -> any()`

<a name="ep-2"></a>

### ep/2 * ###

`ep(B, X2) -> any()`

<a name="int_to_bit_size-1"></a>

### int_to_bit_size/1 * ###

`int_to_bit_size(I) -> any()`

<a name="int_to_bit_size-2"></a>

### int_to_bit_size/2 * ###

`int_to_bit_size(I, B) -> any()`

<a name="int_to_byte_size-1"></a>

### int_to_byte_size/1 * ###

`int_to_byte_size(I) -> any()`

<a name="int_to_byte_size-2"></a>

### int_to_byte_size/2 * ###

`int_to_byte_size(I, B) -> any()`

<a name="mgf1-3"></a>

### mgf1/3 * ###

`mgf1(DigestType, Seed, Len) -> any()`

<a name="mgf1-5"></a>

### mgf1/5 * ###

`mgf1(DigestType, Seed, Len, T, Counter) -> any()`

<a name="normalize_to_key_size-2"></a>

### normalize_to_key_size/2 * ###

`normalize_to_key_size(Bits, A) -> any()`

<a name="pad_to_key_size-2"></a>

### pad_to_key_size/2 * ###

`pad_to_key_size(Bytes, Data) -> any()`

<a name="sign-3"></a>

### sign/3 ###

<pre><code>
sign(Message, DigestType, PrivateKey) -&gt; Signature
</code></pre>

<ul class="definitions"><li><code>Message = binary() | {digest, binary()}</code></li><li><code>DigestType = <a href="#type-rsa_digest_type">rsa_digest_type()</a> | atom()</code></li><li><code>PrivateKey = <a href="#type-rsa_private_key">rsa_private_key()</a></code></li><li><code>Signature = binary()</code></li></ul>

<a name="sign-4"></a>

### sign/4 ###

<pre><code>
sign(Message, DigestType, Salt, PrivateKey) -&gt; Signature
</code></pre>

<ul class="definitions"><li><code>Message = binary() | {digest, binary()}</code></li><li><code>DigestType = <a href="#type-rsa_digest_type">rsa_digest_type()</a> | atom()</code></li><li><code>Salt = binary()</code></li><li><code>PrivateKey = <a href="#type-rsa_private_key">rsa_private_key()</a></code></li><li><code>Signature = binary()</code></li></ul>

<a name="verify-4"></a>

### verify/4 ###

<pre><code>
verify(Message, DigestType, Signature, PublicKey) -&gt; boolean()
</code></pre>

<ul class="definitions"><li><code>Message = binary() | {digest, binary()}</code></li><li><code>DigestType = <a href="#type-rsa_digest_type">rsa_digest_type()</a> | atom()</code></li><li><code>Signature = binary()</code></li><li><code>PublicKey = <a href="#type-rsa_public_key">rsa_public_key()</a></code></li></ul>

<a name="verify_legacy-4"></a>

### verify_legacy/4 ###

`verify_legacy(Message, DigestType, Signature, PublicKey) -> any()`


--- END OF FILE: docs/resources/source-code/rsa_pss.md ---

--- START OF FILE: docs/run/configuring-your-machine.md ---
# Configuring Your HyperBEAM Node

This guide details the various ways to configure your HyperBEAM node's behavior, including ports, storage, keys, and logging.

## Configuration (`config.flat`)

The primary way to configure your HyperBEAM node is through a `config.flat` file located in the node's working directory or specified by the `HB_CONFIG_LOCATION` environment variable.

This file uses a simple `Key = Value.` format (note the period at the end of each line).

**Example `config.flat`:**

```erlang
% Set the HTTP port
port = 8080.

% Specify the Arweave key file
priv_key_location = "/path/to/your/wallet.json".

% Set the data store directory
% Note: Storage configuration can be complex. See below.
% store = [{local, [{root, <<"./node_data_mainnet">>}]}]. % Example of complex config, not for config.flat

% Enable verbose logging for specific modules
% debug_print = [hb_http, dev_router]. % Example of complex config, not for config.flat
```

Below is a reference of commonly used configuration keys. Remember that `config.flat` only supports simple key-value pairs (Atoms, Strings, Integers, Booleans). For complex configurations (Lists, Maps), you must use environment variables or `hb:start_mainnet/1`.

### Core Configuration

These options control fundamental HyperBEAM behavior.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `port` | Integer | 8734 | HTTP API port |
| `hb_config_location` | String | "config.flat" | Path to configuration file |
| `priv_key_location` | String | "hyperbeam-key.json" | Path to operator wallet key file |
| `mode` | Atom | debug | Execution mode (debug, prod) |

### Server & Network Configuration

These options control networking behavior and HTTP settings.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `host` | String | "localhost" | Choice of remote node for non-local tasks |
| `gateway` | String | "https://arweave.net" | Default gateway |
| `bundler_ans104` | String | "https://up.arweave.net:443" | Location of ANS-104 bundler |
| `protocol` | Atom | http2 | Protocol for HTTP requests (http1, http2, http3) |
| `http_client` | Atom | gun | HTTP client to use (gun, httpc) |
| `http_connect_timeout` | Integer | 5000 | HTTP connection timeout in milliseconds |
| `http_keepalive` | Integer | 120000 | HTTP keepalive time in milliseconds |
| `http_request_send_timeout` | Integer | 60000 | HTTP request send timeout in milliseconds |
| `relay_http_client` | Atom | httpc | HTTP client for the relay device |
<!-- Complex options like http_extra_opts are omitted as they are not suitable for config.flat -->

### Security & Identity

These options control identity and security settings.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `scheduler_location_ttl` | Integer | 604800000 | TTL for scheduler registration (7 days in ms) |
<!-- Complex options like trusted_device_signers, trusted are omitted -->

### Caching & Storage

These options control caching behavior. **Note:** Detailed storage configuration (`store` option) involves complex data structures and cannot be set via `config.flat`.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `cache_lookup_heuristics` | Boolean | false | Whether to use caching heuristics or always consult the local data store |
| `access_remote_cache_for_client` | Boolean | false | Whether to access data from remote caches for client requests |
| `store_all_signed` | Boolean | true | Whether the node should store all signed messages |
| `await_inprogress` | Atom/Boolean | named | Whether to await in-progress executions (false, named, true) |
<!-- Complex options like cache_control are omitted -->

### Execution & Processing

These options control how HyperBEAM executes messages and processes.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `scheduling_mode` | Atom | local_confirmation | When to inform recipients about scheduled assignments (aggressive, local_confirmation, remote_confirmation) |
| `compute_mode` | Atom | lazy | Whether to execute more messages after returning a result (aggressive, lazy) |
| `process_workers` | Boolean | true | Whether the node should use persistent processes |
| `client_error_strategy` | Atom | throw | What to do if a client error occurs |
| `wasm_allow_aot` | Boolean | false | Allow ahead-of-time compilation for WASM |

### Device Management

These options control how HyperBEAM manages devices.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `load_remote_devices` | Boolean | false | Whether to load devices from remote signers |
<!-- Complex options like preloaded_devices, devices are omitted -->

### Debug & Development

These options control debugging and development features.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `debug_stack_depth` | Integer | 40 | Maximum stack depth for debug printing |
| `debug_print_map_line_threshold` | Integer | 30 | Maximum lines for map printing |
| `debug_print_binary_max` | Integer | 60 | Maximum binary size for debug printing |
| `debug_print_indent` | Integer | 2 | Indentation for debug printing |
| `debug_print_trace` | Atom | short | Trace mode (short, false) |
| `short_trace_len` | Integer | 5 | Length of short traces |
| `debug_hide_metadata` | Boolean | true | Whether to hide metadata in debug output |
| `debug_ids` | Boolean | false | Whether to print IDs in debug output |
| `debug_hide_priv` | Boolean | true | Whether to hide private data in debug output |
<!-- Complex options like debug_print, stack_print_prefixes are omitted -->

**Note:** For the *absolute complete* and most up-to-date list, including complex options not suitable for `config.flat`, refer to the `default_message/0` function in the `hb_opts` module source code.

## Overrides (Environment Variables & Args)

You can override settings from `config.flat` or provide values if the file is missing using environment variables or command-line arguments.

**Using Environment Variables:**

Environment variables typically use an `HB_` prefix followed by the configuration key in uppercase.

*   **`HB_PORT=<port_number>`:** Overrides `hb_port`.
    *   Example: `HB_PORT=8080 rebar3 shell`
*   **`HB_KEY=<path/to/wallet.key>`:** Overrides `hb_key`.
    *   Example: `HB_KEY=~/.keys/arweave_key.json rebar3 shell`
*   **`HB_STORE=<directory_path>`:** Overrides `hb_store`.
    *   Example: `HB_STORE=./node_data_1 rebar3 shell`
*   **`HB_PRINT=<setting>`:** Overrides `hb_print`. `<setting>` can be `true` (or `1`), or a comma-separated list of modules/topics (e.g., `hb_path,hb_ao,ao_result`).
    *   Example: `HB_PRINT=hb_http,dev_router rebar3 shell`
*   **`HB_CONFIG_LOCATION=<path/to/config.flat>`:** Specifies a custom location for the configuration file.

**Using `erl_opts` (Direct Erlang VM Arguments):**

You can also pass arguments directly to the Erlang VM using the `-<key> <value>` format within `erl_opts`. This is generally less common for application configuration than `config.flat` or environment variables.

```bash
rebar3 shell --erl_opts "-hb_port 8080 -hb_key path/to/key.json"
```

**Order of Precedence:**

1.  Command-line arguments (`erl_opts`).
2.  Settings in `config.flat`.
3.  Environment variables (`HB_*`).
4.  Default values from `hb_opts.erl`.

## Configuration in Releases

When running a release build (see [Running a HyperBEAM Node](./running-a-hyperbeam-node.md)), configuration works similarly:

1.  A `config.flat` file will be present in the release directory (e.g., `_build/default/rel/hb/config.flat`). Edit this file to set your desired parameters for the release environment.
2.  Environment variables (`HB_*`) can still be used to override the settings in the release's `config.flat` when starting the node using the `bin/hb` script.

--- END OF FILE: docs/run/configuring-your-machine.md ---

--- START OF FILE: docs/run/joining-running-a-router.md ---
# Joining or Running a Router Node

Router nodes play a crucial role in the HyperBEAM network by directing incoming HTTP requests to appropriate worker nodes capable of handling the requested computation or data retrieval. They act as intelligent load balancers and entry points into the AO ecosystem.

!!! info "Advanced Topic"
    Configuring and running a production-grade router involves considerations beyond the scope of this introductory guide, including network topology, security, high availability, and performance tuning.

## What is a Router?

In HyperBEAM, the `dev_router` module (and associated logic) implements routing functionality. A node configured as a router typically:

1.  Receives external HTTP requests (HyperPATH calls).
2.  Parses the request path to determine the target process, device, and desired operation.
3.  Consults its routing table or logic to select an appropriate downstream worker node (which might be itself or another node).
4.  Forwards the request to the selected worker.
5.  Receives the response from the worker.
6.  Returns the response to the original client.

Routers often maintain information about the capabilities and load of worker nodes they know about.

!!! note "Using Routers as a Client"
    To use a router as a client, simply make HyperPATH requests to the router's URL: `https://dev-router.forward.computer/<process_id>~<device>/<key>...`. The router will automatically route your request to an appropriate worker node.

## Node Registration Process
*Coming soon...*
<!-- HyperBEAM nodes can register themselves with router networks to offer computational services. The registration process involves configuring route parameters and submitting signed registration requests to router nodes.

### Registration Configuration

Before registering with a router, your node needs to be configured with the following parameters:

```erlang
% Core registration parameters
{router_node, "https://dev-router.forward.computer"},  % Target router endpoint
{router_prefix, "/my-process-id~"},                 % Route prefix to register
{router_price, 100},                                % Price for computation (units)
{router_template, "/my-process-id~process@1.0/.*"}, % Route template pattern

% Optional parameters
{as, "SIGNING_PROCESS_ID"},                         % Process ID to sign as (optional)
{trusted_nodes, #{                                  % Trusted node identifiers
    "NODE_ID_1" => true,
    "NODE_ID_2" => true
}}
```

### Registration Methods

#### 1. Automatic Registration via AO Message

The primary registration method uses AO messages sent to the router process:

```lua
-- Send registration message to router
ao.send({
    Target = "ROUTER_PROCESS_ID",
    Action = "register",
    Data = json.encode({
        subject = "self",
        action = "register",
        route = {
            prefix = "/my-process-id~",
            template = "/my-process-id~process@1.0/.*",
            price = 100
        }
    })
})
```

#### 2. Direct HTTP Registration

Nodes can also register directly via HTTP POST to the router's schedule endpoint:

```bash
curl -X POST https://dev-router.forward.computer/router~node-process@1.0/schedule \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "self",
    "action": "register",
    "route": {
      "prefix": "/my-process-id~",
      "template": "/my-process-id~process@1.0/.*",
      "price": 100
    }
  }'
```

#### 3. Programmatic Registration

Using the HyperBEAM device system:

```erlang
% Call the router device's register function
hb_ao:call(RouterProcessID, <<"register">>, #{
    <<"router_node">> => <<"https://dev-router.forward.computer">>,
    <<"router_prefix">> => <<"/my-process-id~">>,
    <<"router_template">> => <<"/my-process-id~process@1.0/.*">>,
    <<"router_price">> => 100
}, Opts).
```

### Trust System and Registration Validation

The registration process includes a two-tier validation system:

#### Trusted Node Registration
Nodes that are pre-configured as trusted can register immediately without additional validation:

```erlang
% Configure trusted nodes in router
{trusted_nodes, #{
    "TRUSTED_NODE_ID_1" => true,
    "TRUSTED_NODE_ID_2" => true
}}
```

Trusted nodes bypass the admissibility check and are immediately added to the routing table.

#### Standard Node Registration
Non-trusted nodes go through an admissibility validation process:

1. **Signature Verification**: The router verifies the registration message is properly signed
2. **Admissibility Check**: The router runs custom logic to determine if the node should be accepted
3. **Route Addition**: If approved, the node is added to the dynamic routing table
4. **Recalculation**: The router recalculates optimal routes including the new node

### Dynamic Router Configuration

The dynamic router system (implemented in `scripts/dynamic-router.lua`) handles registrations with the following logic:

```lua
-- Example router state configuration
local router_state = {
    ["trusted"] = "TRUSTED_SIGNER_ID",  -- Optional trusted signer
    ["is-admissible"] = {               -- Admissibility validation process
        path = "is-admissible",
        -- Custom validation logic
    },
    ["routes"] = {},                    -- Dynamic routing table
    ["performance"] = {}                -- Performance metrics
}
```

## Configuring Routing Behavior

Routing logic is primarily configured through node options, often managed via `hb_opts` or environment variables when starting the node. Key aspects include:

*   **Route Definitions:** Defining patterns (templates) and corresponding downstream targets (worker node URLs or internal handlers). Routes are typically ordered by precedence.
*   **Load Balancing Strategy:** How the router chooses among multiple potential workers for a given route (e.g., round-robin, least connections, latency-based).
*   **Worker Discovery/Management:** How the router learns about available worker nodes and their status.

**Example Configuration Snippet (Conceptual - from `hb_opts` or config file):**

```erlang
{
  routes,
  [
    #{ template => "/~meta@1.0/.*", target => self }, % Handle meta locally
    #{ template => "/PROCESS_ID1~process@1.0/.*", target => "http://worker1.example.com" },
    #{ template => "/PROCESS_ID2~process@1.0/.*", target => "http://worker2.example.com" },
    #{ template => "/.*~wasm64@1.0/.*", target => ["http://wasm_worker1", "http://wasm_worker2"], strategy => round_robin }, % Route WASM requests
    #{ template => "/.*", target => "http://default_worker.example.com" } % Default fallback
  ]
},
{ router_load_balancing_strategy, latency_aware }
```

*(Note: The actual configuration format and options should be verified in the `hb_opts.erl` and `dev_router.erl` source code.)*

## Running a Node with Router Registration

To run a HyperBEAM node that automatically registers with a router network:

### 1. Configure Registration Parameters

Create or update your node configuration file:

```erlang
% config/sys.config or similar
[
    {hyperbeam, [
        {router_node, "https://dev-router.forward.computer"},
        {router_prefix, "/my-unique-prefix~"},
        {router_template, "/my-unique-prefix~process@1.0/.*"},
        {router_price, 100},
        % ... other node configuration
    ]}
].
```

### 2. Start the Node

```bash
# Start HyperBEAM with router registration enabled
DEBUG=HB_PRINT rebar3 shell --config config/sys.config

# Or use environment variables
ROUTER_NODE="https://dev-router.forward.computer" \
ROUTER_PREFIX="/my-prefix~" \
ROUTER_TEMPLATE="/my-prefix~process@1.0/.*" \
ROUTER_PRICE=100 \
rebar3 shell
```

### 3. Manual Registration

If not configured for automatic registration, you can manually trigger registration:

```erlang
% In the Erlang shell
hb_ao:call(router_process_id, <<"register">>, #{}, Opts).
```

## Running a Simple Router

While a dedicated router setup is complex, any HyperBEAM node implicitly performs some level of routing, especially if it needs to interact with other nodes (e.g., via the `~relay@1.0` device). The default configuration might route certain requests internally or have basic forwarding capabilities.

To run a node that explicitly acts *more* like a router, you would typically configure it with specific `routes` pointing to other worker nodes, potentially disabling local execution for certain devices it intends to forward.

## Joining an Existing Router Network

To join an existing router network means to register your HyperBEAM node as a compute provider that can handle requests routed by the network. This makes your node part of the distributed computation infrastructure.

### Prerequisites for Joining

Before joining a router network, ensure your node:

1. **Has computational capabilities** you want to offer (specific devices, WASM execution, etc.)
2. **Is properly configured** with unique process IDs and route templates
3. **Has network connectivity** to communicate with router nodes
4. **Meets any trust requirements** of the target router network

### Joining Process

The joining process is essentially the node registration process detailed above:

1. **Configure your node** with appropriate route parameters
2. **Submit a registration request** to the target router
3. **Pass validation checks** (signature verification, admissibility, etc.)
4. **Get added to the routing table** and start receiving routed requests

Once successfully joined, your node will:
- Receive computational requests from the router
- Execute the requested operations
- Return results to clients via the router
- Participate in the distributed AO network

### Example: Joining router-1.forward.computer

```erlang
% Configure your node to join the public router
{router_node, "https://dev-router.forward.computer"},
{router_prefix, "/my-unique-node-id~"},
{router_template, "/my-unique-node-id~process@1.0/.*"},
{router_price, 50}  % Competitive pricing for services
```



## Monitoring Registration Status

You can monitor your node's registration status through:

### Log Messages
```bash
# Enable debug logging
DEBUG=HB_PRINT rebar3 shell

# Look for registration-related log messages
# [info] Router registration successful
# [debug] Route added to routing table
```

### Router State Queries
```erlang
% Query router for current routing table
hb_ao:call(RouterProcessID, <<"routes">>, #{}, Opts).

% Check if node is registered
hb_ao:call(RouterProcessID, <<"status">>, #{}, Opts).
```

<!-- ## Troubleshooting Registration

Common registration issues and solutions:

### Registration Rejected
- Verify your node's signature is valid
- Check if the router requires trusted node status
- Ensure your route prefix doesn't conflict with existing routes

### Network Connectivity
- Verify the router endpoint is accessible
- Check firewall and network configuration
- Test HTTP connectivity to the router

### Configuration Errors
- Validate all required parameters are set
- Check route template syntax
- Verify price is within acceptable range -->

## Further Exploration

*   Examine the `dev_router.erl` source code for detailed implementation.
*   Review the `scripts/dynamic-router.lua` for router-side logic.
*   Review the available configuration options in `hb_opts.erl` related to routing (`routes`, strategies, etc.).
*   Consult community channels for best practices on deploying production routers. -->

--- END OF FILE: docs/run/joining-running-a-router.md ---

--- START OF FILE: docs/run/running-a-hyperbeam-node.md ---
# Running a HyperBEAM Node

This guide provides the basics for running your own HyperBEAM node, installing dependencies, and connecting to the AO network.

## System Dependencies

To successfully build and run a HyperBEAM node, your system needs several software dependencies installed.

=== "macOS"
    Install core dependencies using [Homebrew](https://brew.sh/):

    ```bash
    brew install cmake git pkg-config openssl ncurses
    ```

=== "Linux (Debian/Ubuntu)"
    Install core dependencies using `apt`:
    ```bash
    sudo apt-get update && sudo apt-get install -y --no-install-recommends \
        build-essential \
        cmake \
        git \
        pkg-config \
        ncurses-dev \
        libssl-dev \
        sudo \
        curl \
        ca-certificates
    ```

=== "Windows (WSL)"
    Using the Windows Subsystem for Linux (WSL) with a distribution like Ubuntu is recommended. Follow the Linux (Debian/Ubuntu) instructions within your WSL environment.

<!-- **Core Dependency Breakdown:**

*   `build-essential` (Linux) / Xcode Command Line Tools (macOS): Basic C/C++ compilers and build tools (gcc, g++, make).
*   `cmake`: Build system generator.
*   `git`: Version control for fetching the source code.
*   `pkg-config`: Helps find installed libraries during compilation.
*   `ncurses-dev` / `ncurses`: Required for some terminal interface elements used by Erlang/OTP.
*   `libssl-dev` / `openssl`: Necessary for cryptographic operations and secure connections (HTTPS). You might need to set specific environment variables for `openssl` during Erlang compilation if building from source on macOS.
*   `sudo` (Linux/macOS): Needed for system-level installations.
*   `curl`: Used for downloading dependencies or interacting with web services.
*   `ca-certificates` (Linux): Required for validating SSL certificates (often handled by the OS on macOS/Windows).

*(Note: Package names may vary slightly on other Linux distributions. Use your system's package manager accordingly, e.g., `yum`, `dnf`, `pacman`.)* -->

### Erlang/OTP

HyperBEAM is built on Erlang/OTP. You need a compatible version installed (check the `rebar.config` or project documentation for specific version requirements, **typically OTP 27**).

Installation methods:

=== "macOS (brew)"
    ```bash
    brew install erlang
    ```

=== "Linux (apt)"
    ```bash
    sudo apt install erlang
    ```
<!-- 
=== "asdf (Recommended)"
    Tools like `asdf-vm` with the `asdf-erlang` plugin are highly recommended for managing multiple Erlang versions across platforms.
    ```bash
    asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
    asdf install erlang <version> # e.g., 27.0
    asdf global erlang <version>
    ``` -->

=== "Source Build"
    Download from [erlang.org](https://www.erlang.org/downloads) and follow the build instructions for your platform.

### Rebar3

Rebar3 is the build tool for Erlang projects.

Installation methods:

=== "macOS (brew)"
    ```bash
    brew install rebar3
    ```

=== "Linux / macOS (Direct Download)"
    Get the `rebar3` binary from the [official website](https://rebar3.org/). Place the downloaded `rebar3` file in your system's `PATH` (e.g., `/usr/local/bin`) and make it executable (`chmod +x rebar3`).

<!-- === "asdf (Recommended)"
    If using `asdf`, you can install it via the `rebar` plugin:
    ```bash
    asdf plugin add rebar https://github.com/asdf-vm/asdf-rebar.git
    asdf install rebar <version> # e.g., 3.23.0
    asdf global rebar <version>
    ``` -->

### Node.js

Node.js might be required for certain JavaScript-related tools or dependencies.

Installation methods:

=== "macOS (brew)"
    ```bash
    brew install node
    ```

=== "Linux (apt)"
    ```bash
    # Check your distribution's recommended method, might need nodesource repo
    sudo apt install nodejs npm 
    ```

=== "asdf (Recommended)"
    `asdf-vm` with the `asdf-nodejs` plugin is recommended.
    ```bash
    asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
    asdf install nodejs <version> # e.g., lts
    asdf global nodejs <version>
    ```

### Rust

Rust is needed if you intend to work with or build components involving WebAssembly (WASM) or certain Native Implemented Functions (NIFs) used by some devices (like `~snp@1.0`).

The recommended way to install Rust on **all platforms** is via `rustup`:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env" # Or follow the instructions provided by rustup
```

## Prerequisites for Running

Before starting a node, ensure you have:

*   Installed the [system dependencies](#system-dependencies) mentioned above.
*   Cloned the [HyperBEAM repository](https://github.com/permaweb/HyperBEAM) (`git clone ...`).
*   Compiled the source code (`rebar3 compile` in the repo directory).
*   An Arweave **wallet keyfile** (e.g., generated via [Wander](https://www.wander.app)). The path to this file is typically set via the `hb_key` configuration option (see [Configuring Your HyperBEAM Node](./configuring-your-machine.md)).

## Starting a Basic Node

The simplest way to start a HyperBEAM node for development or testing is using `rebar3` from the repository's root directory:

```bash
rebar3 shell
```

This command:

1.  Starts the Erlang Virtual Machine (BEAM) with all HyperBEAM modules loaded.
2.  Initializes the node with default settings (from `hb_opts.erl`).
3.  Starts the default HTTP server (typically on **port 10000**), making the node accessible via HyperPATHs.
4.  Drops you into an interactive Erlang shell where you can interact with the running node.

This basic setup is suitable for local development and exploring HyperBEAM's functionalities.

## Optional Build Profiles

HyperBEAM uses build profiles to enable optional features, often requiring extra dependencies. To run a node with specific profiles enabled, use `rebar3 as ... shell`:

**Available Profiles (Examples):**

*   `genesis_wasm`: Enables Genesis WebAssembly support.
*   `rocksdb`: Enables the RocksDB storage backend.
*   `http3`: Enables HTTP/3 support.

**Example Usage:**

```bash
# Start with RocksDB profile
rebar3 as rocksdb shell

# Start with RocksDB and Genesis WASM profiles
rebar3 as rocksdb, genesis_wasm shell
```

*Note: Choose profiles **before** starting the shell, as they affect compile-time options.*

## Node Configuration

HyperBEAM offers various configuration options (port, key file, data storage, logging, etc.). These are primarily set using a `config.flat` file and can be overridden by environment variables or command-line arguments.

See the dedicated [Configuring Your HyperBEAM Node](./configuring-your-machine.md) guide for detailed information on all configuration methods and options.

## Verify Installation

To quickly check if your node is running and accessible, you can send a request to its `~meta@1.0` device (assuming default port 10000):

```bash
curl http://localhost:8734/~meta@1.0/info
```

A JSON response containing node information indicates success.

## Running for Production (Mainnet)

While you can connect to the main AO network using the `rebar3 shell` for testing purposes (potentially using specific configurations or helper functions like `hb:start_mainnet/1` if available and applicable), the standard and recommended method for a stable production deployment (like running on the mainnet) is to build and run a **release**.

**1. Build the Release:**

From the root of the HyperBEAM repository, build the release package. You might include specific profiles needed for your mainnet setup (e.g., `rocksdb` if you intend to use it):

```bash
# Build release with default profile
rebar3 release

# Or, build with specific profiles (example)
# rebar3 as rocksdb release
```

This command compiles the project and packages it along with the Erlang Runtime System (ERTS) and all dependencies into a directory, typically `_build/default/rel/hb`.

**2. Configure the Release:**

Navigate into the release directory (e.g., `cd _build/default/rel/hb`). Ensure you have a correctly configured `config.flat` file here. See the [configuration guide](./configuring-your-machine.md) for details on setting mainnet parameters (port, key file location, store path, specific peers, etc.). Environment variables can also be used to override settings in the release's `config.flat` when starting the node.

**3. Start the Node:**

Use the generated start script (`bin/hb`) to run the node:

```bash
# Start the node in the foreground (logs to console)
./bin/hb console

# Start the node as a background daemon
./bin/hb start

# Check the status
./bin/hb ping
./bin/hb status

# Stop the node
./bin/hb stop
```

Consult the generated `bin/hb` script or Erlang/OTP documentation for more advanced start-up options (e.g., attaching a remote shell).

Running as a release provides a more robust, isolated, and manageable way to operate a node compared to running directly from the `rebar3 shell`.

## Stopping the Node (rebar3 shell)

To stop the node running *within the `rebar3 shell`*, press `Ctrl+C` twice or use the Erlang command `q().`.

## Next Steps

*   **Configure Your Node:** Deep dive into [configuration options](./configuring-your-machine.md).
*   **TEE Nodes:** Learn about running nodes in [Trusted Execution Environments](./tee-nodes.md) for enhanced security.
*   **Routers:** Understand how to configure and run a [router node](./joining-running-a-router.md).

--- END OF FILE: docs/run/running-a-hyperbeam-node.md ---

--- START OF FILE: docs/run/tee-nodes.md ---
# Trusted Execution Environment (TEE)

!!! info "Documentation Coming Soon"
    Detailed documentation about Trusted Execution Environment support in HyperBEAM is currently being developed and will be available soon.

## Overview

HyperBEAM supports Trusted Execution Environments (TEEs) through the `~snp@1.0` device, which enables secure, trust-minimized computation on remote machines. TEEs provide hardware-level isolation and attestation capabilities that allow users to verify that their code is running in a protected environment, exactly as intended, even on untrusted hardware.

The `~snp@1.0` device in HyperBEAM is used to generate and validate proofs that a node is executing inside a Trusted Execution Environment. Nodes executing inside these environments use an ephemeral key pair that provably only exists inside the TEE, and can sign attestations of AO-Core executions in a trust-minimized way.

## Key Features

- Hardware-level isolation for secure computation
- Remote attestation capabilities
- Protected execution state
- Confidential computing support
- Compatibility with AMD SEV-SNP technology

## Coming Soon

Detailed documentation on the following topics will be added:

- TEE setup and configuration
- Using the `~snp@1.0` device
- Verifying TEE attestations
- Developing for TEEs
- Security considerations
- Performance characteristics

If you intend to offer TEE-based computation of AO-Core devices, please see the [HyperBEAM OS repository](https://github.com/permaweb/hb-os) for preliminary details on configuration and deployment. 
--- END OF FILE: docs/run/tee-nodes.md ---