diff --git a/.gitignore b/.gitignore index ffdb883d..eecbd2be 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,14 @@ src/.vitepress/cache src/.vitepress/cache/deps src/.vitepress/dist +# Auto-generated LLM documentation files (generated during build) +src/public/llms.txt +src/public/llms-full.txt +src/public/ja/llms.txt +src/public/ja/llms-full.txt +src/public/zh/llms.txt +src/public/zh/llms-full.txt + wallet.json # Trunk diff --git a/src/.vitepress/locales.js b/src/.vitepress/locales.js index 604b12d8..40a7fada 100644 --- a/src/.vitepress/locales.js +++ b/src/.vitepress/locales.js @@ -54,6 +54,91 @@ export const localeConfig = (langCode) => ({ }, ], }, + { + text: "Migrating to HyperBEAM", + items: [ + { + text: "Getting Started", + collapsed: false, + items: [ + { + text: "Why Migrate", + link: get_i18n_link( + langCode, + "/migrating-to-hyperbeam/why-migrate", + ), + }, + { + text: "AOS CLI", + link: get_i18n_link( + langCode, + "/migrating-to-hyperbeam/aos-cli", + ), + }, + ], + }, + { + text: "Reading State", + collapsed: false, + items: [ + { + text: "State Exposure", + link: get_i18n_link( + langCode, + "/migrating-to-hyperbeam/state-exposure", + ), + }, + { + text: "Dynamic Reads", + link: get_i18n_link( + langCode, + "/migrating-to-hyperbeam/dynamic-reads", + ), + }, + { + text: "User-Owned Processes", + link: get_i18n_link( + langCode, + "/migrating-to-hyperbeam/user-owned-processes", + ), + }, + ], + }, + { + text: "Building Applications", + collapsed: true, + items: [ + { + text: "Web Serving", + link: get_i18n_link( + langCode, + "/migrating-to-hyperbeam/web-serving", + ), + }, + { + text: "External Data", + link: get_i18n_link( + langCode, + "/migrating-to-hyperbeam/external-data", + ), + }, + ], + }, + { + text: "Developer Tools", + collapsed: true, + items: [ + { + text: "JavaScript SDK", + link: get_i18n_link( + langCode, + "/migrating-to-hyperbeam/javascript-sdk", + ), + }, + ], + }, + ], + }, { text: get_i18n_str(langCode, "tutorials"), link: get_i18n_link(langCode, "/tutorials/index"), @@ -382,44 +467,6 @@ export const localeConfig = (langCode) => ({ }, ], }, - { - text: "Migrating to HyperBEAM", - link: get_i18n_link( - langCode, - "/guides/migrating-to-hyperbeam/why-migrate", - ), - collapsed: true, - items: [ - { - text: "Exposing State", - link: get_i18n_link( - langCode, - "/guides/migrating-to-hyperbeam/exposing-process-state", - ), - }, - { - text: "Reading Dynamic State", - link: get_i18n_link( - langCode, - "/guides/migrating-to-hyperbeam/reading-dynamic-state", - ), - }, - { - text: "Connecting with aos", - link: get_i18n_link( - langCode, - "/guides/migrating-to-hyperbeam/aos-with-hyperbeam", - ), - }, - { - text: "ao-connect & HyperBEAM", - link: get_i18n_link( - langCode, - "/guides/migrating-to-hyperbeam/ao-connect", - ), - }, - ], - }, { text: "Additional Technologies", collapsed: true, @@ -556,6 +603,20 @@ export const localeConfig = (langCode) => ({ }, ], }, + { + text: "Deprecated Features", + collapsed: true, + items: [ + { + text: "Overview", + link: get_i18n_link(langCode, "/references/deprecated/index"), + }, + { + text: "Dry Run", + link: get_i18n_link(langCode, "/references/deprecated/dry-run"), + }, + ], + }, { text: get_i18n_str(langCode, "references-community"), link: get_i18n_link(langCode, "/references/community"), diff --git a/src/guides/aoconnect/calling-dryrun.md b/src/guides/aoconnect/calling-dryrun.md index d50ea519..f27ae4de 100644 --- a/src/guides/aoconnect/calling-dryrun.md +++ b/src/guides/aoconnect/calling-dryrun.md @@ -1,7 +1,17 @@ # Calling DryRun -::: warning DEPRECATION NOTICE -This method of reading state is in the process of being deprecated for processes running on HyperBEAM. It is recommended to use the [State Patching mechanism](../migrating-to-hyperbeam/exposing-process-state.md) to expose state via HTTP for better performance, as calling `dryrun` was known to cause severe bottlenecks in web applications on `legacynet`. +::: danger URGENT DEPRECATION NOTICE +**Legacynet will stop supporting dry runs on October 10, 2025.** If you are running processes on Legacynet, you must take action now. + +This method of reading state is being deprecated for all processes. After deprecation, you have two options: + +1. **Recommended: Migrate to State Patching** - Use the [State Patching mechanism](../../migrating-to-hyperbeam/state-exposure.md) to expose state via HTTP for better performance. This is the recommended approach as `dryrun` was known to cause severe bottlenecks in web applications. + +2. **Alternative: Run Your Own HyperBEAM Node** - You can continue using dry runs by running your own HyperBEAM node infrastructure. + +**Exception for Token Processes**: If you have a token process, HyperBEAM can manage your balance state. You can still patch your token for improved performance. + +**Important for User-Owned Processes**: If your application spawns processes owned by users (not your app), users will need to patch their own processes. See the [User-Owned Processes guide](../../migrating-to-hyperbeam/user-owned-processes.md) for implementation strategies. ::: DryRun is the process of sending a message object to a specific process and getting the Result object back, but the memory is not saved, it is perfect to create a read message to return the current value of memory. For example, a balance of a token, or a result of a transfer, etc. You can use DryRun to obtain an output without sending an actual message. diff --git a/src/guides/migrating-to-hyperbeam/aos-with-hyperbeam.md b/src/guides/migrating-to-hyperbeam/aos-with-hyperbeam.md deleted file mode 100644 index 33260523..00000000 --- a/src/guides/migrating-to-hyperbeam/aos-with-hyperbeam.md +++ /dev/null @@ -1,64 +0,0 @@ -# Connecting to HyperBEAM with `aos` - -This guide explains how to use `aos`, the command-line interface for AO, to connect to a HyperBEAM node for development. - -## Installing `aos` - -The primary tool for interacting with AO and developing processes is `aos`, a command-line interface and development environment. - -::: code-group - -```bash [npm] -npm i -g https://get_ao.arweave.net -``` - -```bash [pnpm] -pnpm add -g https://get_ao.arweave.net -``` - -```bash [bun] -# Bun is not supported yet -# bun install -g https://get_ao.arweave.net -``` - -::: - -## Connecting to a HyperBEAM Node - -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` and connect to a public HyperBEAM node, simply run the command in your terminal: - -```bash -aos --url "https://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. When you specify `--url `, it connects to the `genesis_wasm` device running on the HyperBEAM node at the supplied URL, allowing you to interact with other processes, manage your wallet, and develop new AO processes. - -:::info Running a Local HyperBEAM Node -If you are running HyperBEAM locally and want to use that node when booting up `aos`, you must first start your local node with the genesis_wasm profile: - -```bash -rebar3 as genesis_wasm shell -``` - -Then, you can connect `aos` to it: - -```bash -aos --url "http://localhost:8734" myLocalProcess -``` - -Until `aos` is fully HyperBEAM native, the genesis_wasm profile is required to run a local Compute Unit (CU) for executing `aos`. - -**Process Types** - -Use `--url` when connecting to hyper-aos processes on HyperBEAM. For -standard genesis_wasm processes, the flag is not needed. - -::: - -## Interacting with Mainnet Processes - -:::warning Note on Blocking Calls -Blocking message patterns, such as `Receive` and `ao.send().receive()`, are not available when running `aos` against a HyperBEAM process. HyperBEAM processes do not support the underlying `wasm` modules required for this functionality. You should rely on asynchronous patterns using handlers instead. -::: diff --git a/src/index.md b/src/index.md index 4b7b6e27..6306cb6b 100644 --- a/src/index.md +++ b/src/index.md @@ -12,13 +12,13 @@ hero: link: /welcome/index features: - - title: AO-Core + - title: AO Core details: Learn about the protocol and standard that powers the AO computer. link: /welcome/ao-core-introduction - - title: AO Processes + - title: AO on HyperBEAM details: Build smart contracts and autonomous agents using AO Processes. - link: /welcome/ao-processes + link: /migrating-to-hyperbeam/why-migrate - title: HyperBEAM details: The future of AO, written in Erlang. diff --git a/src/migrating-to-hyperbeam/aos-cli.md b/src/migrating-to-hyperbeam/aos-cli.md new file mode 100644 index 00000000..284aeeec --- /dev/null +++ b/src/migrating-to-hyperbeam/aos-cli.md @@ -0,0 +1,93 @@ +# AOS CLI + +Use the `aos` command-line interface to spawn and connect to processes on HyperBEAM mainnet. + +## Understanding Legacy vs. HyperBEAM + +AO is currently maintaining two networks during the transition to HyperBEAM: + +- **Legacy Network (aos)**: The current stable network that most existing processes run on +- **HyperBEAM Mainnet (hyper-aos)**: The new high-performance network being built out + +HyperAOS represents the future direction of AOS on HyperBEAM, offering improved performance and new capabilities. + +## Installing `aos` + +The primary tool for interacting with AO and developing processes is `aos`, a command-line interface and development environment. + +::: code-group + +```bash [npm] +npm i -g https://get_ao.arweave.net +``` + +```bash [pnpm] +pnpm add -g https://get_ao.arweave.net +``` + +```bash [bun] +# Bun is not supported yet +# bun install -g https://get_ao.arweave.net +``` + +::: + +## Choosing Your Network + +After installing `aos`, when you spawn a new process you'll be presented with a selection menu: + +```bash +aos myProcess +``` + +You'll see: + +``` +? Please select › - Use arrow-keys. Return to submit. +❯ aos + hyper-aos (experimental - DO NOT USE FOR PRODUCTION) +``` + +### Legacy Network Process (aos) + +Select `aos` to spawn a process on the legacy network (default). This creates a standard AO process on the existing stable network, compatible with all current tooling and processes. + +### HyperBEAM Process (hyper-aos) + +Select `hyper-aos` to spawn a process directly on HyperBEAM. This is marked as **experimental** and should not be used for production workloads while HyperBEAM mainnet is being built out. + +:::warning Important +The `hyper-aos` option is experimental and actively under development. Use `aos` (legacy network) for production processes. +::: + +### Connecting to a Specific HyperBEAM Node + +You can also connect directly to a specific HyperBEAM node: + +```bash +aos --url "https://forward.computer" myMainnetProcess +``` + +This connects you to an interactive Lua environment running within a **process** on the HyperBEAM network at the specified URL. + +:::info Running a Local HyperBEAM Node +If you are running HyperBEAM locally and want to use that node when booting up `aos`, you must first start your local node with the genesis_wasm profile: + +```bash +rebar3 as genesis_wasm shell +``` + +Then, you can connect `aos` to it: + +```bash +aos --url "http://localhost:8734" myLocalProcess +``` + +Until `aos` is fully HyperBEAM native, the genesis_wasm profile is required to run a local Compute Unit (CU) for executing `aos`. +::: + +## Interacting with Mainnet Processes + +:::warning Note on Blocking Calls +Blocking message patterns, such as `Receive` and `ao.send().receive()`, are not available when running `aos` against a HyperBEAM process. HyperBEAM processes do not support the underlying `wasm` modules required for this functionality. You should rely on asynchronous patterns using handlers instead. +::: diff --git a/src/guides/migrating-to-hyperbeam/reading-dynamic-state.md b/src/migrating-to-hyperbeam/dynamic-reads.md similarity index 83% rename from src/guides/migrating-to-hyperbeam/reading-dynamic-state.md rename to src/migrating-to-hyperbeam/dynamic-reads.md index f03c6a1f..b6e05e24 100644 --- a/src/guides/migrating-to-hyperbeam/reading-dynamic-state.md +++ b/src/migrating-to-hyperbeam/dynamic-reads.md @@ -1,14 +1,14 @@ -# Reading Dynamic State +# Dynamic Reads -Beyond reading static, cached state from your process, HyperBEAM allows you to perform on-the-fly computations on that state using Lua. This guide explains how to create and use "transformation functions" to return dynamic, computed data without altering the underlying state of your process. +Dynamic reads enable on-the-fly computations on your process state using Lua transformation functions. These functions process cached state and return computed results without modifying the underlying data. -This is a powerful pattern for creating efficient data APIs for your applications, reducing client-side logic, and minimizing data transfer. +This pattern creates efficient data APIs by moving computation from clients to HyperBEAM nodes, reducing both network traffic and client-side complexity. -This guide assumes you are already familiar with [exposing static process state](./exposing-process-state.md). +This guide assumes you are already familiar with [state exposure](./state-exposure.md). -## How it Works: The Lua Device +## How Dynamic Reads Work -The magic behind this is the `lua@5.3a` device, which can execute a Lua script against a message. In this pattern, we use a HyperBEAM URL (hashpath) to construct a pipeline: +Dynamic reads leverage the `lua@5.3a` device to execute Lua scripts against cached state. The HyperBEAM URL constructs a processing pipeline: 1. First, we grab the latest state of an AO process. 2. Then, we pipe that state as the `base` message into the `lua@5.3a` device. diff --git a/src/migrating-to-hyperbeam/external-data.md b/src/migrating-to-hyperbeam/external-data.md new file mode 100644 index 00000000..9d217168 --- /dev/null +++ b/src/migrating-to-hyperbeam/external-data.md @@ -0,0 +1,87 @@ +# External Data + +HyperBEAM provides oracle functionality through its resolve mechanism, enabling AO processes to fetch and consume external data from web APIs. This creates a trustless bridge between on-chain processes and off-chain data sources. + +The oracle service works by taking a base message and combining it with external data fetched via HTTP requests. This "resolve" operation allows your AO processes to react to real-world data, price feeds, weather information, or any other web-accessible API. + +## Key Concepts + +- **Oracle Requests**: Fetch external data through HTTP calls to any web API +- **Trustless Execution**: Results are delivered directly to your process with cryptographic guarantees +- **Relay Device**: The `~relay@1.0` device acts as the oracle gateway to external services + +## Making Oracle Requests + +The oracle service allows your process to query any web API and receive the response directly. Here's how to use it: + +### Basic HTTP Request Example + +To fetch information from an Arweave node: + +```lua +Send({ + target = ao.id, + ["relay-path"] = "https://arweave.net/info", + resolve = "~relay@1.0/call" +}) +``` + +This code: + +- Sets the target to `ao.id` (the current process) to receive the response +- Specifies the external URL to query via `relay-path` +- Uses the `resolve` property with `~relay@1.0/call` to execute the HTTP request + +### Managing Trust + +When working with HyperBeam nodes, you may need to establish trust by adding the node's address to your authorities: + +```lua +table.insert(ao.authorities, "HYPERBEAM_NODE_ADDRESS") +``` + +If you receive a "not trusted" response, this step is required before the resolve operation can succeed. + +### Accessing Response Data + +After a successful resolve operation, you can access the response data from your inbox: + +```lua +Inbox[3].Data +``` + +This will display the JSON data returned from the external API. + +### Additional Example: JSON Placeholder API + +You can query any REST API using the same pattern: + +```lua +Send({ + target = ao.id, + ["relay-path"] = "https://jsonplaceholder.typicode.com/posts", + resolve = "~relay@1.0/call" +}) +``` + +## Technical Details + +The resolve mechanism works by: + +1. Creating a base message with the target and relay path +2. Specifying the resolve function to use (in this case, the relay device's call function) +3. Executing the HTTP request through the relay device +4. Returning the response as a new message to the specified target + +## Common Oracle Use Cases + +- **Price Feeds**: Fetch cryptocurrency or asset prices for DeFi applications +- **Weather Data**: Build parametric insurance or prediction markets +- **Sports Results**: Create betting or fantasy sports applications +- **Random Numbers**: Access external randomness for games or lotteries +- **IoT Data**: Integrate real-world sensor data into smart contracts +- **News & Events**: React to real-world events in your processes + +## Security Considerations + +Always ensure that HyperBeam nodes are trusted before using them for resolve operations. Add node addresses to your `ao.authorities` table to establish trust. diff --git a/src/guides/migrating-to-hyperbeam/ao-connect.md b/src/migrating-to-hyperbeam/javascript-sdk.md similarity index 95% rename from src/guides/migrating-to-hyperbeam/ao-connect.md rename to src/migrating-to-hyperbeam/javascript-sdk.md index fdae38d1..f5590c8f 100644 --- a/src/guides/migrating-to-hyperbeam/ao-connect.md +++ b/src/migrating-to-hyperbeam/javascript-sdk.md @@ -1,6 +1,6 @@ -# HyperBEAM from AO Connect +# JavaScript SDK -This guide explains how to interact with a process using HyperBEAM and `aoconnect`. +Connect to HyperBEAM processes using the `@permaweb/aoconnect` JavaScript library for web and Node.js applications. ## Prerequisites diff --git a/src/guides/migrating-to-hyperbeam/exposing-process-state.md b/src/migrating-to-hyperbeam/state-exposure.md similarity index 61% rename from src/guides/migrating-to-hyperbeam/exposing-process-state.md rename to src/migrating-to-hyperbeam/state-exposure.md index 9ec4d7c3..38a061a6 100644 --- a/src/guides/migrating-to-hyperbeam/exposing-process-state.md +++ b/src/migrating-to-hyperbeam/state-exposure.md @@ -1,14 +1,18 @@ -# Exposing Process State to HyperBEAM +# State Exposure -HyperBEAM introduces a powerful feature for exposing parts of a process's state for immediate reading over HTTP. This improves performance for web frontends and data services by replacing the need for `dryrun` calls, which were a known bottleneck on `legacynet`. +::: danger ACTION REQUIRED +**Legacynet is deprecating dry runs on October 10, 2025.** Migrating to state exposure is now urgent for all processes running on Legacynet. This guide shows you how to expose your process state for direct HTTP access, providing dramatically better performance than dry runs. +::: + +HyperBEAM enables direct HTTP access to process state, eliminating the need for costly `dryrun` calls. This feature dramatically improves performance for web frontends and data services that need to read process data. ## The Patch Device -The [`~patch@1.0`](https://hyperbeam.arweave.net/build/devices/source-code/dev_patch.md) device is the mechanism that allows AO processes to make parts of their internal state readable via direct HTTP GET requests. +The [`~patch@1.0`](https://hyperbeam.arweave.net/build/devices/hyperbeam-devices.html) device is the mechanism that allows AO processes to make parts of their internal state readable via direct HTTP GET requests. -### How it Works +### How State Exposure Works -Exposing state is a four-step process involving your process and HyperBEAM: +State exposure follows a simple four-step pattern: 1. **Process Logic:** From your process (e.g., in Lua or WASM), send an outbound message to the `~patch@1.0` device. 2. **Patch Message Format:** The message must include `device` and `cache` tags. @@ -109,6 +113,61 @@ GET /~process@1.0/cache/mykey Using the `patch` device enables efficient, standard HTTP access to your process state, seamlessly connecting decentralized logic with web applications. +## Patching User-Owned Processes + +If your application spawns processes that are owned by users (not your application), you'll need to provide a way for users to patch their own processes. A common example is marketplace applications where each user has their own process instance. + +### Implementation Strategy + +You can create UI components that allow users to update their processes. Here's an example approach: + +```javascript +import { message, createDataItemSigner } from "@permaweb/aoconnect"; + +async function patchUserProcess(processId) { + // User must sign this message themselves + const signer = createDataItemSigner(window.arweaveWallet); + + const messageId = await message({ + process: processId, + signer, + tags: [{ name: "Action", value: "UpdateToPatch" }], + }); + + return messageId; +} +``` + +In your process code, add a handler that users can trigger: + +```lua +Handlers.add( + "UpdateToPatch", + Handlers.utils.hasMatchingTag("Action", "UpdateToPatch"), + function(msg) + -- Only allow the process owner to update + if msg.From ~= ao.id then + print("Only the process owner can update to use patch") + return + end + + -- Add your patch logic here + Send({ + device = 'patch@1.0', + cache = { + -- Add the state you want to expose + } + }) + + print("Process updated to use state patching") + end +) +``` + +This allows users to maintain ownership of their processes while still benefiting from HyperBEAM's performance improvements. + +For a complete guide on implementing this pattern, see [User-Owned Processes](./user-owned-processes.md). + ## Next Steps -Now that you know how to expose static state, learn how to perform on-the-fly computations on that state by [reading dynamic state](./reading-dynamic-state.md). +With state exposure configured, you can now add [dynamic reads](./dynamic-reads.md) to compute values on-the-fly without modifying your process state. diff --git a/src/migrating-to-hyperbeam/user-owned-processes.md b/src/migrating-to-hyperbeam/user-owned-processes.md new file mode 100644 index 00000000..a043a67b --- /dev/null +++ b/src/migrating-to-hyperbeam/user-owned-processes.md @@ -0,0 +1,105 @@ +# User-Owned Processes + +When building applications on AO, you may create architectures where users own their own processes rather than your application owning a centralized process. This pattern is common in decentralized marketplaces, user-specific vaults, and personal data stores. + +## The Challenge + +With the deprecation of dry runs on Legacynet, you face a unique challenge: **you cannot patch processes that you don't own**. Only the process owner can send messages to update their process. + +### Common Scenarios + +- **Marketplace Applications**: Each vendor has their own process for managing inventory and sales +- **User Vaults**: Each user has a personal process for storing data or assets +- **Decentralized Applications**: Users spawn their own game characters, agents, or bots +- **Token Pairs**: DEX applications where users create their own trading pair processes + +In these scenarios, you need to provide a way for users to migrate their own processes to use state patching. + +## General Approach + +The solution typically involves three key components: + +1. **Process-side handler**: Add a handler to your process template that allows the owner to enable state patching +2. **Detection mechanism**: Check whether a user's process has patching enabled +3. **User interface**: Provide a way for users to trigger the update + +You'll need to decide how to implement each of these based on your application's architecture and user experience requirements. + +## Process Update Handler + +Your process needs a handler that allows the owner to enable state patching. Here's a minimal example: + +```lua +Handlers.add( + "EnableStatePatch", + Handlers.utils.hasMatchingTag("Action", "EnableStatePatch"), + function(msg) + -- Only allow process owner to enable + if msg.From ~= ao.id then + return + end + + -- Sync current state to cache + Send({ + device = 'patch@1.0', + cache = { + -- Your state here + balances = Balances, + -- ... other state + } + }) + end +) +``` + +After enabling, you'll also need to update your existing handlers to patch state when it changes. For example: + +```lua +-- After updating state, sync to cache if patching is enabled +if StatePatchEnabled then + Send({ + device = 'patch@1.0', + cache = { balances = Balances } + }) +end +``` + +## Detecting Patch Status + +You can check if a process has state patching enabled by attempting to access its cached state: + +```javascript +async function isPatchEnabled(processId) { + try { + const response = await fetch( + `https://forward.computer/${processId}~process@1.0/compute/cache/balances`, + { method: "HEAD" }, + ); + return response.ok; + } catch { + return false; + } +} +``` + +## Triggering the Update + +Users need to send a message to their own process to enable patching. The basic approach: + +```javascript +import { message, createDataItemSigner } from "@permaweb/aoconnect"; + +const messageId = await message({ + process: userProcessId, + signer: createDataItemSigner(window.arweaveWallet), + tags: [{ name: "Action", value: "EnableStatePatch" }], +}); +``` + +How you present this to users is up to you - it could be a button in your UI, a banner notification, a setup wizard, or a CLI script. + +## Related Documentation + +- [State Exposure](./state-exposure.md) +- [Dynamic Reads](./dynamic-reads.md) +- [Why Migrate to HyperBEAM](./why-migrate.md) diff --git a/src/migrating-to-hyperbeam/web-serving.md b/src/migrating-to-hyperbeam/web-serving.md new file mode 100644 index 00000000..aacfcc77 --- /dev/null +++ b/src/migrating-to-hyperbeam/web-serving.md @@ -0,0 +1,215 @@ +# Web Serving + +Serve dynamic web content directly from AO processes using HyperBEAM. This guide shows how to host websites, serve HTML/CSS/JavaScript, and update content in real-time using an experimental Hyper AOS light implementation. + +## Prerequisites + +- HyperBeam server running locally + - `rebar3 shell` from your local HyperBeam repo +- Experimental Hyper AOS light module + +## Setting Up the Environment + +First, export the AOS module and install the latest preview version of the AOS console: + +```bash +# Install the latest preview version of AOS console +preview_ao.arweave.net +``` + +This installation enables the Lua device on HyperBeam to function as your process's virtual machine. + +## Creating a Process + +To create a new process on your HyperBeam server: + +1. Spin up a new process using the AOS module as the initialization script + - `export AOS_MODULE=` +2. Select the Lua device in the configuration options +3. Verify the process is running with the experimental Hyper AOS + +## File Structure + +For this demonstration, we'll use three main files: + +- `app.css.lua` - CSS styling wrapped in a Lua file +- `app.js.lua` - JavaScript functionality wrapped in a Lua file +- `now.html.lua` - HTML content wrapped in a Lua file + +## State Management + +Unlike Genesis WASM which requires sending messages to cache with the patch device, Hyper AOS makes state directly available: + +```lua +-- Access state +State["someProperty"] +-- Modify state +State["someProperty"] = newValue +``` + +## Loading Web Assets + +### CSS File + +Load the CSS file into the process state: + +```lua +.load app.css.lua +``` + +The CSS file sets the content type and body: + +```lua +State["app.css"] = { + ["content-type"] = "text/css", + body = [[ + /* CSS styles */ + * { + margin: 0; + padding: 0; + box-sizing: border-box; + } + + body { + font-family: Arial, sans-serif; + background: linear-gradient(180deg, #87CEEB 0%, #9980C8 100%); + min-height: 100vh; + overflow-x: hidden; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + } + + h1 { + color: #333; + margin-bottom: 2rem; + text-align: center; + font-size: 2.5rem; + text-shadow: 2px 2px 4px rgba(0,0,0,0.1); + } + + .marquee-container { + width: 100%; + height: 200px; + background: rgba(255, 255, 255, 0.3); + backdrop-filter: blur(10px); + position: relative; + overflow: hidden; + box-shadow: 0 4px 6px rgba(0,0,0,0.1); + } + + .marquee-track { + display: flex; + position: absolute; + animation: scroll 20s linear infinite; + height: 100%; + align-items: center; + } + ]] +} +``` + +### JavaScript File + +Similarly, load the JavaScript file: + +```lua +.load app.js.lua +``` + +The JavaScript file follows the same pattern: + +```lua +State["app.js"] = { + ["content-type"] = "application/javascript", + body = [[ // JavaScript content here ]] +} +``` + +### HTML File + +Finally, load the HTML file: + +```lua +.load now.html.lua +``` + +The HTML file is placed at the root of the state: + +```lua +State["content-type"] = "text/html" +State["body"] = [[ + + + + + + HyperBeam Marquee Demo + + + +
+
+ +

Elephant Parade

+ +
+
+ +
+
+
+ + + + +]] +``` + +Note that the HTML references other assets using the path `now/app.css` and `now/app.js`. + +## Accessing Your Web Application + +1. Retrieve your process ID by examining the inbox commitments: + +```lua +Inbox[1].commitments +``` + +- Look for the signed ID (RSAPS-SHA-256). This appears as a long alphanumeric string like `6oNYypU3EIeauMkTL4EEYKgzASYFebqTCLP8W1idmMB`. + +2. Access your web application in a browser: + +``` +localhost:8734/~process@1.0/now +``` + +- Replace the process ID with your actual process ID from the commitments + +## Making Dynamic Updates + +To demonstrate the dynamic nature of this approach: + +1. Modify your HTML file (e.g., change a heading to "Elephant Parade on the beam") +2. Save the changes +3. Reload the file in the AOS console: + +```lua +.load now.html.lua +``` + +4. Refresh your browser to see the changes + +## Advanced Capabilities + +This approach allows for: + +- Real-time updates to web content +- Processing incoming messages to modify the website +- Adding additional content dynamically +- Creating interactive web applications directly within HyperBeam processes + +## Warning + +The Hyper AOS light implementation used in this guide is experimental and should not be used for production environments. It is intended for demonstration purposes only. diff --git a/src/guides/migrating-to-hyperbeam/why-migrate.md b/src/migrating-to-hyperbeam/why-migrate.md similarity index 92% rename from src/guides/migrating-to-hyperbeam/why-migrate.md rename to src/migrating-to-hyperbeam/why-migrate.md index 7634d341..def18ace 100644 --- a/src/guides/migrating-to-hyperbeam/why-migrate.md +++ b/src/migrating-to-hyperbeam/why-migrate.md @@ -10,4 +10,4 @@ HyperBEAM is a new, more robust foundation for decentralized applications on AO, The most impactful change when migrating is the ability to expose parts of your process state for immediate reading. This dramatically improves the performance of web frontends and data-driven services. -To learn how to implement this, see [Exposing Process State](./exposing-process-state.md). +To learn how to implement this, see [State Exposure](./state-exposure.md). diff --git a/src/public/ja/llms-full.txt b/src/public/ja/llms-full.txt deleted file mode 100644 index 71482d1e..00000000 --- a/src/public/ja/llms-full.txt +++ /dev/null @@ -1,1249 +0,0 @@ -# JA Technical Documentation - -Generated: 2025-09-10T20:06:33.636Z - -This file contains technical reference documentation and release notes. - - - -# API AND FUNCTION REFERENCES - - - -## aoモジュール -Source: https://cookbook_ao.arweave.net/ja/references/ao.html - -バージョン: 0.0.3 - -`ao`プロセスの通信はメッセージによって処理され、各プロセスはANS-104 DataItems形式でメッセージを受信し、以下の一般的な操作を実行できる必要があります。 - -- isTrusted(msg) - このメッセージが信頼できるかどうかを確認 -- send(msg) - 別のプロセスにメッセージを送信 -- spawn(module, msg) - プロセスを生成 - -このライブラリの目的は、`ao`開発者ツールキットの中でこのコア機能を提供することです。開発者として、このライブラリを利用するかどうかは任意ですが、デフォルトで統合されています。 - -## プロパティ - - - -| Name | Description | Type | -| ----------- | ------------------------------------------------------------------------------------------------------------ | ------ | -| id | Process Identifier (TXID) | string | -| \_module | Module Identifier (TXID) | string | -| authorities | Set of Trusted TXs | string | -| Authority | Identifiers that the process is able to accept transactions from that are not the owner or the process (0-n) | string | -| \_version | The version of the library | string | -| env | Evaluation Environment | string | -| outbox | Holds Messages and Spawns for response | object | - -## メソッド - -### send(msg: Message\) : Message\
- -send関数は、メッセージオブジェクトまたは部分的なメッセージオブジェクトを受け取り、オブジェクトに追加の`ao`特有のタグを追加して完全なメッセージオブジェクトを返します。また、ao.outbox.Messagesテーブルにも挿入されます。 - -**パラメータ** - -- msg - -スキーマ - - - -```json -{ - "type": "object", - "properties": { - "Target": { - "type": "string", - "description": "Process/Wallet to send message to" - }, - "Data": { - "type": "any", - "description": "data to send in message DataItem" - }, - "Tags": { - "type": "object or array" - "description": "This property can be an array of name,value objects or an object" - } - } -} -``` - -Example 1 - -```lua -local message = ao.send({ - Target = msg.From, - Data = "ping", - Tags = { - { - name = "Content-Type", - value = "text/plain" - } - } -}) -``` - -Example 2 - -```lua -local message = ao.send({ - Target = msg.From, - Data = "ping", - Tags = { - "Content-Type" = "text/plain" - } -}) -``` - -**returns** - -Schema - -```json -{ - "type": "object", - "properties": { - "Target": { - "type": "string" - }, - "Data": { - "type": "any" - }, - "Tags": { - "type": "array" - "description": "name/value array", - "items": { - "type": "object", - "properties": { - "name": {"type": "string"}, - "value":{"type":"string"} - } - } - } - } -} -``` - -### spawn(module : string, spawn : Spawn\
) : Spawn\
- -`spawn`関数は、最初の引数としてモジュールのTXIDと、完全または部分的なSpawnテーブルを受け取ります。結果として、完全なSpawnテーブルが返されます。また、spawn関数は一意の参照識別子を持つ`Ref_`タグも生成します。 - -**パラメータ** - - - -| Name | Description | Type | -| ------ | --------------------------------------------------------------------------------------- | ------ | -| module | The TXID that identifies the module binary to use to instaniate the process with | string | -| spawn | The `spawn` full or parital table object that contains the `Data` and `Tags` properties | table | - -Schema - -module - -```json -{ - "type": "string" -} -``` - -spawn - -```json -{ - "type": "object", - "properties": { - "Data": { "type": "any" }, - "Tags": { - "type": "object or array", - "description": "can be either array, or object" - } - } -} -``` - -**returns** - -Schema - -```json -{ - "type": "object", - "properties": { - "Data": { "type": "any" }, - "Tags": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { "type": "string" }, - "value": { "type": "string" } - } - } - } - } -} -``` - -### isTrusted(msg : Message\
) : boolean - -プロセスを生成する際に、0個以上の権限タグを指定できます。aoライブラリは、これらの値を`authorities`と呼ばれる`ao`プロパティのテーブル配列に追加します。このセットは、ao.TN.1の`Proof of Authority`機能を提供します。メッセージが`handle`関数に到着すると、開発者は`ao.isTrusted`を呼び出して、そのメッセージが信頼できるソースからのものであるかを確認できます。 - - - -**parameters** - -| Name | Description | Type | -| ---- | ------------------------------------------- | ----- | -| msg | Message to check if trusted by this process | table | - -Schema - -```json -{ - "type": "object", - "properties": { - "Target": { - "type": "string" - }, - "Data": { - "type": "any" - }, - "Tags": { - "type": "array" - "description": "name/value array", - "items": { - "type": "object", - "properties": { - "name": {"type": "string"}, - "value":{"type":"string"} - } - } - } - } -} -``` - -## コミュニティ -Source: https://cookbook_ao.arweave.net/ja/references/community.html - -[Autonomous Finance](https://www.autonomous.finance/) - -- Autonomous Financeは、aoネットワーク内の金融インフラの複雑さに焦点を当てた、専用の研究および技術機関です。 - -[BetterIdea](https://betteridea.dev/) - -- BetterIDEaを使用して、より高速でスマート、そして効率的に開発しましょう。AO開発向けの究極のネイティブWeb IDEです。 - -[Orbit](https://www.0rbit.co/) - -- 0rbitは、aoプロセスにウェブからのデータを提供します。aoの力と0rbitノードを活用することで、ユーザーは0rbit aoにメッセージを送り、0rbitノードがデータを取得し、ユーザープロセスがそのデータを受け取ります。 - -## Cronメッセージ -Source: https://cookbook_ao.arweave.net/ja/references/cron.html - -aoには、指定した間隔でメッセージを生成する機能があります。この間隔は、秒、分、時間、またはブロック単位で設定できます。これらのメッセージは、監視プロセスによって自動的に評価され、時間の経過とともにプロセスがこれらのメッセージを評価するように通知します。その結果、リアルタイムで全aoネットワークや外部ネットワークのオラクルと通信できるプロセスが実現されます。 - -## プロセスでのcronの設定 - -これらのcronメッセージを作成する最も簡単な方法は、aosコンソールで新しいプロセスを生成し、時間間隔を定義することです。 - -```sh -aos [myProcess] --cron 5-minutes -``` - - - - - -新しいプロセスを生成する際、コマンドラインでcron引数を指定し、その後にcronの間隔を設定します。メッセージをリアルタイムでトリガーしたい場合は、モニターイベントを開始する必要があります。aosでは、単に`.monitor`を呼び出すことで、`mu`上でワーカープロセスが開始され、`cu`からcronメッセージがトリガーされます。その後、プロセスは指定した`x-interval`ごとにcronメッセージを受信します。 - -```lua -.monitor -``` - - - -cronメッセージのトリガーを停止したい場合は、単に`.unmonitor`を呼び出すだけでトリガープロセスが停止します。ただし、次回メッセージを送信すると、生成されたcronメッセージは依然として作成され、処理されます。 - -## cronメッセージの処理 - -すべてのcronメッセージには、値が`Cron`の`Action`タグが付いています。[Handlers](handlers.md)を定義して、cronメッセージが受信されるたびに自律的に特定のタスクを実行させることができます。 - -```lua -Handlers.add( - "CronTick", -- handler name - Handlers.utils.hasMatchingTag("Action", "Cron"), -- handler pattern to identify cron message - function () -- handler task to execute on cron message - -- do something - end -) -``` - - - -Cronメッセージは、広範な機能を持つ「自律型エージェント」を作成するために使用できる強力なユーティリティです。 - -## aoを使ってArweaveからデータにアクセスする -Source: https://cookbook_ao.arweave.net/ja/references/data.html - - - - - -aoの開発ワークフローにおいて、Arweaveからデータにアクセスしたい時があるかもしれません。aoでは、プロセスがネットワークにデータをプロセスに提供するよう指示するアサインメントを送信できます。 - -Arweaveからデータをリクエストするには、データを割り当てたいプロセスのリストと、メッセージ(メッセージのtxid)を指定してAssignを呼び出すだけです。 - -```lua -Assign({ - Processes = { ao.id }, - Message = 'message-id' -}) -``` - -また、Sendを呼び出して、AssignmentsパラメータにプロセスIDのテーブルを指定することもできます。これにより、ネットワークはメッセージを生成し、Assignmentsリスト内のすべてのプロセスIDに割り当てるよう指示されます。 - - - -```lua -Send({ - Target = ao.id, - Data = 'Hello World', - Assignments = { 'process-id-1', 'process-id-2' } -}) -``` - -## なぜArweaveからデータを取得するのか? - - - -あなたのプロセスは、何かを決定するためにメッセージからデータにアクセスする必要があるかもしれません。また、`data`ロード機能を使用してプロセスに機能を追加したい場合もあります。あるいは、メッセージ全体を複製することなく、他のプロセスからメッセージにアクセスしたい場合もあるでしょう。 - -## エディタのセットアップ -Source: https://cookbook_ao.arweave.net/ja/references/editor-setup.html - -aoの組み込み関数やユーティリティをすべて覚えるのは難しい場合があります。開発者体験を向上させるために、お気に入りのテキストエディタに[Lua Language Server](https://luals.github.io)拡張機能をインストールし、[ao addon](https://github.com/martonlederer/ao-definitions)を追加することをお勧めします。これにより、すべての組み込みのaos[モジュール](../guides/aos/modules/index.md)や[グローバル変数](../guides/aos/intro.md#globals)がサポートされます。 - -## VS Code - -[sumneko.lua](https://marketplace.visualstudio.com/items?itemName=sumneko.lua)拡張機能をインストールします: - -1. 拡張機能マーケットプレイスで「Lua」を検索し、sumnekoの拡張機能を見つけます -2. 拡張機能をダウンロードしてインストールします -3. `Shift + Command + P`(Mac)/ `Ctrl + Shift + P`(Windows/Linux)でVS Codeのコマンドパレットを開き、次のコマンドを実行します: - -``` -> Lua: Open Addon Manager -``` - -4. Addon Managerで「ao」を検索すると、最初に表示されるはずです。「Enable」をクリックして、オートコンプリートを楽しんでください! - -## その他のエディタ - -1. あなたのエディタが[Language Server Protocol](https://microsoft.github.io/language-server-protocol/implementors/tools/)をサポートしていることを確認してください -2. [luals.github.io](https://luals.github.io/#install)の指示に従ってLua Language Serverをインストールします -3. Language Serverに「ao」アドオンをインストールします - -## BetterIDEa - -[BetterIDEa](https://ide.betteridea.dev)は、ao上での開発のためのカスタムWebベースのIDEです。 - -ao定義が組み込まれたLua Language Serverを提供しているため、何もインストールする必要はありません。IDEを開いてコーディングを開始するだけです! - -機能には以下が含まれます: - -- コード補完 -- セルベースのノートブックUIによる迅速な開発 -- 簡単なプロセス管理 -- MarkdownおよびLatexセルのサポート -- aoプロセスを介して誰とでもプロジェクトを共有 -- [aoパッケージマネージャ](https://apm.betteridea.dev)との緊密な統合 - -IDEのさまざまな機能や統合についての詳細は、[ドキュメント](https://docs.betteridea.dev)をご覧ください。 - -## Eval -Source: https://cookbook_ao.arweave.net/ja/references/eval.html - -各AOプロセスには、受信した新しいコードを評価するオンボードの`Eval`ハンドラが含まれています。このハンドラにより、プロセスは受信コードに対して適切なアクションを決定し、そのメッセージがプロセスの所有者からのものであるかを確認します。 - -`Eval`ハンドラは、受信メッセージから受け取ったデータを評価するために手動でトリガーすることもできます。 - -## NodeJSでEvalメッセージを送信する - -```js -import { readFileSync } from "node:fs"; -import { message, createDataItemSigner } from "@permaweb/aoconnect"; - -const wallet = JSON.parse( - readFileSync("/path/to/arweave/wallet.json").toString(), -); - -await message({ - // The arweave TXID of the process, this will become the "target". - process: "process-id", // Replace with the actual process ID - - // Tagging the Eval Action so the recieving process evaluates and adds the new Handler from the Data field. - tags: [ - { name: "Action", value: "Eval" }, - { - name: "Data", - value: 'Handlers.add("ping", Handlers.utils.reply("pong"))', - }, - ], - - // A signer function used to build the message "signature" - signer: createDataItemSigner(wallet), -}) - .then(console.log) - .catch(console.error); -``` - -## ブラウザでEvalメッセージを送信する - -```js -import { message, createDataItemSigner } from "@permaweb/aoconnect"; - -await message({ - // The arweave TXID of the process, this will become the "target". - process: "process-id", // Replace with the actual process ID - - // Tagging the Eval Action so the recieving process evaluates and adds the new Handler from the Data field. - tags: [ - { name: "Action", value: "Eval" }, - { - name: "Data", - value: 'Handlers.add("ping", Handlers.utils.reply("pong"))', - }, - ], - - // A signer function used to build the message "signature" - signer: createDataItemSigner(globalThis.arweaveWallet), -}) - .then(console.log) - .catch(console.error); -``` - -## ハンドラ (バージョン 0.0.5) -Source: https://cookbook_ao.arweave.net/ja/references/handlers.html - - - - - -## 概要 - -Handlersライブラリは、パターンマッチングに基づいて一連のプロセス関数を管理・実行する柔軟な方法を提供します。AOプロセスは、メッセージを受信して応答します。これらのメッセージは、タグとデータで構成されたArweave DataItem仕様を使用して定義されます。Handlersライブラリを使用することで、AOメッセージの属性に基づいてプロセス評価のパイプラインを定義できます。各ハンドラアイテムは、パターン関数、ハンドル関数、および名前で構成されています。このライブラリは、さまざまな入力条件に基づいて異なるアクションを実行する必要があるシナリオに適しています。 - -## コンセプト - -### パターンマッチングテーブル - -パターンマッチングテーブルは、受信メッセージのマッチング形状をテーブル形式で提供する概念です。以下がそのルールです: - -```lua - -{ "Action" = "Do-Something" } -- 含めるべきタグのテーブルを通じて、任意のメッセージをマッチング - -{ "Recipient" = '_' } -- 受信者タグが任意の値を持つメッセージをマッチング - -{ "Quantity" = "%d+" } -- Luaの文字列マッチ(正規表現に似ている)を使用してタグを検証 - -{ "Quantity" = function(v) return tonumber(v) ~= Nil end } -- タグに関数を適用してチェック。Nilやfalseはマッチしない - -``` - -Example: - -Actionが「Balance」に等しいすべてのメッセージにマッチさせたい場合: - -```lua -{ Action = "Balance" } -``` - -Quantityが数値であるすべてのメッセージにマッチさせたい場合: - -```lua -{ Quantity = "%d+" } -``` - -### リゾルバ - -リゾルバは、各キーがパターンマッチングテーブルであり、値がマッチしたキーに基づいて実行される関数であるテーブルです。これにより、開発者はリゾルバプロパティ内でcaseのようなステートメントを作成できます。 - -```lua -Handlers.add("foobarbaz", - { Action = "Update" }, { - [{ Status = "foo" }] = function (msg) print("foo") end, - [{ Status = "bar" }] = function (msg) print("bar") end, - [{ Status = "baz" }] = function (msg) print("baz") end -}) -``` - -## モジュール構造 - -- `Handlers._version`: Handlersライブラリのバージョンを表す文字列。 -- `Handlers.list`: 登録されたハンドラのリストを格納するテーブル。 - -## ハンドラメソッドの共通関数シグネチャ - - - -| Parameter | Type | Description | -| ------------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| name | string | The identifier of the handler item in the handlers list. | -| pattern | Table or Function | This parameter can take a table that specifies a pattern that the message MUST match, for example `{ Action = "Balance", Recipient = "_" }` this table describes a message that has a Tag called action and it equals the string "Balance", and the message MUST have a Recipient Tag with a value. If you are unable to add a pattern via a table, you can also use the `function` which receives the message DataItem as its argument and you can return a `true`, `false` or `"continue"` result. The `true` result tells the Handlers evaluation pipeline to invoke this handler and exit out of the pipeline. The `false` result tells the Handlers evaluation pipeline to skip this handler and try to find a pattern matched by the next Handler item in the pipeline. Finally, the `"continue"` informs the Handlers evaluation to invoke this handler and continue evaluating. | -| handler | Table (Resolver) or Function | This parameter can take a table that acts as a conditional that invokes a function based on a pattern matched key. or a Function that takes the message DataItem as an argument and performs some business logic. | -| maxRuns (optional) | number | As of 0.0.5, each handler function takes an optional function to define the amount of times the handler should match before it is removed. The default is infinity. | - - - -## 関数 - -### `Handlers.add(name, pattern, handler)` - -新しいハンドラを追加するか、既存のハンドラを名前で更新します。 - -### `Handlers.append(name, pattern, handle)` - -新しいハンドラをハンドラリストの最後に追加します。 - -### `Handlers.once(name, pattern, handler)` - -パターンがマッチした場合に一度だけ実行されます。 - -### `Handlers.prepend(name, pattern, handle)` - -新しいハンドラをハンドラリストの最初に追加します。 - -### `Handlers.before(handleName)` - -指定されたハンドラの前に新しいハンドラを追加するオブジェクトを返します。 - -### `Handlers.after(handleName)` - -指定されたハンドラの後に新しいハンドラを追加するオブジェクトを返します。 - -### `Handlers.remove(name)` - -名前でハンドラをハンドラリストから削除します。 - -## 例 - -### パターンテーブルの使用 - -```lua -Handlers.add("ping", - { Action = "ping" }, - function (msg) - print('ping') - msg.reply({Data = "pong" }) - end -) -``` - -### Using resolvers - -```lua -Handlers.add( - "foobarbaz", - { Action = "Speak" }, { - [{Status = "foo"}] = function (msg) print("foo") end, - [{Status = "bar"}] = function (msg) print("bar") end, - [{Status = "baz"}] = function (msg) print("baz") end -}) -``` - -### Using functions - -```lua -Handlers.add("example", - function (msg) - return msg.Action == "Speak" - end, - function (msg) - print(msg.Status) - end -) -``` - - - -## 注意事項 - -- ハンドラは`handlers.list`に表示される順序で実行されます。 -- パターン関数は、ハンドラをスキップするには`false`を返し、ハンドラ実行後に終了するには`true`を返し、次のハンドラを実行するには`"continue"`を返す必要があります。 - -## Handlers.utils - -Handlers.utilsモジュールは、一般的なマッチングパターンの2つの関数と、一般的なハンドル関数を1つ提供します。 - -- hasMatchingData(data) -- hasMatchingTag(name, value) -- reply(txt) - -### Handlers.utils.hasMatchingData(data : string) - -このヘルパーはメッセージ引数を必要とする関数を返すため、任意のハンドラのパターン引数に組み込むことができます。この関数は、受信メッセージのデータと引数として提供された文字列を比較します。 - -```lua -Handlers.add("ping", - Handlers.utils.hasMatchingData("ping"), - ... -) -``` - - - -メッセージがデータに`ping`が設定された状態でプロセスに入ってくると、このハンドラはそれにマッチし、ハンドル関数が実行されます。 - -### Handlers.hasMatchingTag(name : string, value : string) - -このヘルパーはメッセージ引数を必要とする関数を返すため、Handlersモジュールの任意のパターン引数に組み込むことができます。この関数は、タグ名と値を比較し、それらが等しい場合にハンドル関数を呼び出します。 - -```lua -Handlers.add("ping", - Handlers.utils.hasMatchingData("ping"), - ... -) -``` - - - -### Handlers.reply(text : string) - -このヘルパーはシンプルなハンドル関数で、基本的にテキストの値を送信メッセージのDataプロパティに設定します。 - -```lua -Handlers.add("ping", - Handlers.utils.hasMatchingData("ping"), - Handlers.utils.reply("pong") -) -``` - -## 参考資料 -Source: https://cookbook_ao.arweave.net/ja/references/index.html - -## 目次 - -- [Lua](lua) - -## Luaに触れてみよう -Source: https://cookbook_ao.arweave.net/ja/references/lua.html - - - - - -### Luaの理解 - -- **背景**: Luaは、主に組み込みシステムやクライアント向けに設計された軽量で高水準の多パラダイムプログラミング言語です。その効率性、シンプルさ、柔軟性で知られています。 -- **主な特徴**: Luaは強力なデータ記述構造、動的型付け、効率的なメモリ管理、そしてオブジェクト指向プログラミングの良好なサポートを提供します。 - -### セットアップ - -1. **インストール**: [Luaの公式ウェブサイト](http://www.lua.org/download.html)を訪れてLuaをダウンロードし、インストールします。 -2. **環境**: シンプルなテキストエディタとコマンドライン、またはZeroBrane StudioやLuaプラグインを備えたEclipseのようなIDEを使用できます。 - -### 基本構文とコンセプト(aOSで) - -- **Hello World**: - - ```lua - "Hello, World!" - ``` - -- **変数と型**: Luaは動的型付けです。基本型には、`nil`、`boolean`、`number`、`string`、`function`、`userdata`、`thread`、`table`があります。 -- **制御構造**: `if`、`while`、`repeat...until`、`for`が含まれます。 -- **関数**: Luaでは関数は第一級の市民であり、クロージャや高階関数をサポートしています。 -- **テーブル**: Luaにおける唯一のデータ構造機構であり、配列、セット、レコードなどを表すことができます。 - -### 実践練習 - -- **Luaの対話モードで実験**: ターミナルで`aos`を実行し、Luaコマンドを使って実験を始めましょう。 -- **簡単なスクリプトを作成**: `.lua`ファイルを作成し、Luaインタープリタを使って実行します。`.load file.lua`機能を使用して、Luaコードを`aos`プロセスにアップロードします。 - -### リソース - -- **公式ドキュメント**: [Lua 5.3リファレンスマニュアル](https://www.lua.org/manual/5.3/) -- **オンラインチュートリアル**: [Learn Lua](https://www.learn-lua.org/)のようなウェブサイトは、インタラクティブな学習に最適です。 -- **書籍**: "Programming in Lua"([オンラインで利用可能](http://www.lua.org/pil/contents.html)な初版)は包括的なリソースです。 -- **コミュニティ**: [Lua Users](http://lua-users.org/)のようなフォーラムやコミュニティに参加して、サポートや議論に参加しましょう。 - -### ベストプラクティス - -- **シンプルに保つ**: Luaはシンプルで柔軟に設計されています。この哲学をコードに取り入れましょう。 -- **パフォーマンス**: Luaのガベージコレクションやテーブルの効率的な使用について学びましょう。 -- **統合**: Luaが他のアプリケーション、特にC/C++プロジェクトにどのように組み込まれるかを考慮しましょう。 - -### 結論 - -Luaは、特に組み込みシステムやゲーム開発の文脈で非常に強力な言語です。そのシンプルさと効率性は、特定のユースケースに最適な選択肢となります。Luaプログラミングの旅を楽しんでください! - - - -## aoトークンおよびサブレッジャー仕様 -Source: https://cookbook_ao.arweave.net/ja/references/token.html - -**ステータス:** DRAFT-1 -**対象ネットワーク:** ao.TN.1 - -この仕様は、標準のaoトークンプロセスに必要なメッセージハンドラと機能を説明します。この標準の実装は通常、プロセスによって維持される希少性を持つ転送可能な資産を制御する能力をユーザーに提供します。 - -各準拠プロセスは、プロセスが表す資産の所有権を符号化するために、残高の台帳を実装することが期待されます。準拠プロセスには、通常、トークンの所有権の希少性を保証するための安全策を伴って、この台帳を変更するためのメソッドのセットがあります。 - -さらに、この仕様では「サブレッジャー」プロセスタイプを説明しています。これは、実装されると、親プロセスから子プロセスにトークンの数を分割移動する能力を提供します。この子プロセスは同じトークンインターフェース仕様を実装します。サブレッジャープロセスの`From-Module`が参加者によって信頼される場合、これらのサブレッジャーを使って「ソース」トークンで取引することができます。これは、直接メッセージを交換することなく行えます。これにより、プロセスが混雑している場合でも、参加者はそのプロセスからトークンを使用できます。オプションとして、参加者がサブレッジャープロセスが実行されている`Module`を信頼している場合、これらのプロセス間での残高を*代替可能*として扱うことができます。この結果、任意の数の並列プロセス、およびそれに伴う取引を単一のトークンで同時に処理できます。 - -# トークンプロセス - -仕様に準拠したトークンプロセスは、さまざまな形式のメッセージに応答し、各形式は`Action`タグで指定されます。トークンがサポートしなければならない`Action`メッセージの完全なセットは以下の通りです: - - - -| Name | Description | Read-Only | -| -------- | ------------------------------------------------------------------------------------------------------ | ------------------ | -| Balance | get the balance of an identifer | :heavy_check_mark: | -| Balances | get a list of all ledger/account balances | :heavy_check_mark: | -| Transfer | send 1 or more units from the callers balance to one or move targets with the option to notify targets | :x: | -| Mint | if the ledger process is the root and you would like to increase token supply | :x: | - -このセクションの残りでは、準拠トークンプロセスを生成するために必要なタグと、各`Action`メッセージの形式およびその結果について説明します。 - -## 生成パラメータ - -すべての準拠トークンプロセスは、その生成メッセージに以下の不変パラメータを含める必要があります: - - - -| Tag | Description | Optional? | -| ------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------ | -| Name | The title of the token, as it should be displayed to users. | :heavy_check_mark: | -| Ticker | A suggested shortened name for the token, such that it can be referenced quickly. | :heavy_check_mark: | -| Logo | An image that applications may deserire to show next to the token, in order to make it quickly visually identifiable. | :heavy_check_mark: | -| Denomination | The number of the token that should be treated as a single unit when quantities and balances are displayed to users. | :x: | - -## メッセージングプロトコル - -### Balance(Target? : string) - -ターゲットの残高を返します。ターゲットが指定されていない場合は、メッセージの送信者の残高を返す必要があります。 - -例 `Action` メッセージ: - - - -```lua= -send({ - Target = "{TokenProcess Identifier}", - Tags = { - Action = "Balance", - Target = "{IDENTIFIER}" - } -}) -``` - -Example response message: - -``` -{ - Tags = { - Balance = "50", - Target = "LcldyO8wwiGDzC3iXzGofdO8JdR4S1_2A6Qtz-o33-0", - Ticker = "FUN" - } -} -``` - - - -### Balances() - -トークンのすべての参加者の残高を返します。 - -```lua -send({ - Target = "[TokenProcess Identifier]", - Tags = { - Action = "Balances", - Limit = 1000, # TODO: Is this necessary if the user is paying for the compute and response? - Cursor? = "BalanceIdentifer" - } -}) -``` - -Example response message: - -```lua -{ - Data = { - "MV8B3MAKTsUOqyCzQ0Tsa2AR3TiWTBU1Dx0xM4MO-f4": 100, - "LcldyO8wwiGDzC3iXzGofdO8JdR4S1_2A6Qtz-o33-0": 50 - } -} -``` - - - -### Transfer(Target, Quantity) - -送信者に十分な残高がある場合、`Quantity`を`Target`に送信し、受取人に`Credit-Notice`を発行し、送信者に`Debit-Notice`を発行します。`Credit-`および`Debit-Notice`は、元の`Transfer`メッセージからすべてのタグを`X-`プレフィックス付きで転送する必要があります。送信者に残高が不足している場合は、失敗し、送信者に通知します。 - -```lua -send({ - Target = "[TokenProcess Identifier]", - Tags = { - { name = "Action", value = "Transfer" }, - { name = "Recipient", value = "[ADDRESS]" }, - { name = "Quantity", value = "100" }, - { name = "X-[Forwarded Tag(s) Name]", value= "[VALUE]" } - } -}) -``` - - - -成功した転送が行われた場合、`Cast`が設定されていない場合は通知メッセージを送信する必要があります。 - -```lua -ao.send({ - Target = "[Recipient Address]", - Tags = { - { name = "Action", value = "Credit-Notice" }, - { name = "Sender", value = "[ADDRESS]" }, - { name = "Quantity", value = "100"}, - { name = "X-[Forwarded Tag(s) Name]", value= "[VALUE]" } - } -}) -``` - - - -受取人は、メッセージの`From-Process`タグから、どのトークンを受け取ったかを推測します。 - -### Get-Info() - -```lua -send({ - Target = "{Token}", - Tags = { - Action = "Info" - } -}) -``` - -### Mint() [optional] - - - -`Mint`アクションを実装することで、プロセスは有効な参加者に新しいトークンを作成する方法を提供します。 - -```lua -send({ - Target ="{Token Process}", - Tags = { - Action = "Mint", - Quantity = "1000" - } -}) -``` - - - -# サブレッジャープロセス - -適切に機能するために、サブレッジャーはトークン契約の完全なメッセージングプロトコルを実装する必要があります(`Mint`アクションを除く)。サブレッジャーはまた、プロセスのために追加の機能や生成パラメータを実装する必要があります。これらの変更は、次のセクションで説明されます。 - - - -### 生成パラメータ - -すべての準拠したサブレッジャープロセスは、その生成メッセージに以下の不変パラメータを含める必要があります: - -| Tag | Description | Optional? | -| ------------ | ------------------------------------------------------------------ | --------- | -| Source-Token | The `ID` of the top-most process that this subledger represents. | :x: | -| Parent-Token | The `ID` of the parent process that this subledger is attached to. | :x: | - - - -### `Credit-Notice`ハンドラ - -`Credit-Notice`メッセージを受信した際、準拠したサブレッジャープロセスは、対象のプロセスが`Parent-Token`であるかどうかを確認する必要があります。もしそうであれば、サブレッジャーは`Sender`の残高を指定された数量だけ増加させる必要があります。 - -### Transfer(Target, Quantity) - -トークンの受取人に渡される`Credit-Notice`メッセージに含まれる通常のタグに加えて、準拠したサブレッジャープロセスは、`Source-Token`と`Parent-Token`の両方の値も提供する必要があります。これにより、`Transfer`メッセージの受取人は、サブレッジャープロセスの`Module`を信頼している場合、`Source-Token`からの預金と同様の(代替可能な)受領をクレジットできるようになります。 - -修正された`Credit-Notice`は以下のように構成されるべきです: - -```lua -ao.send({ - Target = "[Recipient Address]", - Tags = { - { name = "Action", value = "Credit-Notice" }, - { name = "Quantity", value = "100"}, - { name = "Source-Token", value = "[ADDRESS]" }, - { name = "Parent-Token", value = "[ADDRESS]" }, - { name = "X-[Forwarded Tag(s) Name]", value= "[VALUE]" } - } -}) -``` - - - -### Withdraw(Target?, Quantity) - -すべてのサブレッジャーは、残高保有者がトークンを親台帳に引き出すことを許可する必要があります。`Action: Withdraw`メッセージを受信した際、サブレッジャーはその`Parent-Ledger`に`Action`メッセージを送り、要求されたトークンを呼び出し元のアドレスに転送し、ローカルでアカウントから引き落とします。この転送により、呼び出し元に対して`Parent-Ledger`から`Credit-Notice`が発行されます。 - -```lua -send({ - Target = "[TokenProcess Identifier]", - Tags = { - { name = "Action", value = "Withdraw" }, - { name = "Recipient", value = "[ADDRESS]" }, - { name = "Quantity", value = "100" } - } -}) -``` - -# Token Example - -> NOTE: When implementing a token it is important to remember that all Tags on a message MUST be "string"s. Using the`tostring` function you can convert simple types to strings. - -```lua -if not balances then - balances = { [ao.id] = 100000000000000 } -end - -if name ~= "Fun Coin" then - name = "Fun Coin" -end - -if ticker ~= "Fun" then - ticker = "fun" -end - -if denomination ~= 6 then - denomination = 6 -end - --- handlers that handler incoming msg -handlers.add( - "transfer", - handlers.utils.hasMatchingTag("Action", "Transfer"), - function (msg) - assert(type(msg.Tags.Recipient) == 'string', 'Recipient is required!') - assert(type(msg.Tags.Quantity) == 'string', 'Quantity is required!') - - if not balances[msg.From] then - balances[msg.From] = 0 - end - - if not balances[msg.Tags.Recipient] then - balances[msg.Tags.Recipient] = 0 - end - - local qty = tonumber(msg.Tags.Quantity) - assert(type(qty) == 'number', 'qty must be number') - -- handlers.utils.reply("Transfering qty")(msg) - if balances[msg.From] >= qty then - balances[msg.From] = balances[msg.From] - qty - balances[msg.Tags.Recipient] = balances[msg.Tags.Recipient] + qty - ao.send({ - Target = msg.From, - Tags = { - Action = "Debit-Notice", - Quantity = tostring(qty) - } - }) - ao.send({ - Target = msg.Tags.Recipient, - Tags = { - Action = "Credit-Notice", - Quantity = tostring(qty) - }}) - -- if msg.Tags.Cast and msg.Tags.Cast == "true" then - -- return - -- end - - end - end -) - -handlers.add( - "balance", - handlers.utils.hasMatchingTag("Action", "Balance"), - function (msg) - assert(type(msg.Tags.Target) == "string", "Target Tag is required!") - local bal = "0" - if balances[msg.Tags.Target] then - bal = tostring(balances[msg.Tags.Target]) - end - ao.send({Target = msg.From, Tags = { - Target = msg.From, - Balance = bal, - Ticker = ticker or "" - }}) - end -) - -local json = require("json") - -handlers.add( - "balances", - handlers.utils.hasMatchingTag("Action", "Balances"), - function (msg) - ao.send({ - Target = msg.From, - Data = json.encode(balances) - }) - end - -) - -handlers.add( - "info", - handlers.utils.hasMatchingTag("Action", "Info"), - function (msg) - ao.send({Target = msg.From, Tags = { - Name = name, - Ticker = ticker, - Denomination = tostring(denomination) - }}) - end -) -``` - -## Web Assemblyについて -Source: https://cookbook_ao.arweave.net/ja/references/wasm.html - - - - - -WebAssembly(一般的にWasmと略される)は、C、C++、Rustのような高水準言語のためのポータブルなコンパイルターゲットを提供する、現代的なバイナリ命令形式です。クライアントおよびサーバーアプリケーション向けに、ウェブ上で高いレベルのパフォーマンスと効率を提供することができます。WebAssemblyは、ウェブブラウザのセキュリティとサンドボックス機能を維持するように設計されており、ウェブベースのアプリケーションに適した選択肢です。複数の言語でコードを書き、それをブラウザでネイティブに近い速度で実行されるバイトコードにコンパイルできるため、ウェブ開発者にとって重要な技術です。 - -WebAssemblyの重要性は、ウェブアプリケーションとネイティブアプリケーションのギャップを埋める能力にあります。従来はデスクトップ環境に限定されていた複雑なアプリケーションやゲームを、ブラウザで同等のパフォーマンスで実行できるようにします。これにより、高性能のウェブアプリやゲーム、さらには既存のデスクトップアプリケーションをウェブに移植する新たな可能性が開かれます。WebAssemblyはJavaScriptと並行して動作し、パフォーマンスが重要なコンポーネントを、そうしたタスクにより適した言語で記述できるよう​⬤ - -# Summary - -Total files processed: 11 diff --git a/src/public/ja/llms.txt b/src/public/ja/llms.txt deleted file mode 100644 index bdcd9925..00000000 --- a/src/public/ja/llms.txt +++ /dev/null @@ -1,398 +0,0 @@ -# JA Documentation for LLMs - -Generated: 2025-09-10T20:06:33.636Z - -This file contains structured reference documentation, release notes, and a comprehensive directory of all documentation pages. - -# Documentation Directory - -## Concepts - -- [ao Specs](https://cookbook_ao.arweave.net/ja/concepts/specs.html) -- [aos 簡単ツアー](https://cookbook_ao.arweave.net/ja/concepts/tour.html) -- [aoメッセージングの仕組み](https://cookbook_ao.arweave.net/ja/concepts/how-it-works.html) -- [Holographic State](https://cookbook_ao.arweave.net/ja/concepts/holographic-state.html) -- [Luaの短期ツアー](https://cookbook_ao.arweave.net/ja/concepts/lua.html) -- [Units](https://cookbook_ao.arweave.net/ja/concepts/units.html) -- [コンセプト](https://cookbook_ao.arweave.net/ja/concepts/index.html) -- [プロセス](https://cookbook_ao.arweave.net/ja/concepts/processes.html) -- [メッセージ](https://cookbook_ao.arweave.net/ja/concepts/messages.html) - -## Guides - -### 0rbit - -- [0rbit 💫](https://cookbook_ao.arweave.net/ja/guides/0rbit/index.html) -- [最初のGETリクエスト](https://cookbook_ao.arweave.net/ja/guides/0rbit/get-request.html) -- [最初のPOSTリクエスト](https://cookbook_ao.arweave.net/ja/guides/0rbit/post-request.html) - -### Aoconnect - -- [ao connectのインストール](https://cookbook_ao.arweave.net/ja/guides/aoconnect/installing-connect.html) -- [aoconnect](https://cookbook_ao.arweave.net/ja/guides/aoconnect/aoconnect.html) -- [aoプロセスからの結果の読み取り](https://cookbook_ao.arweave.net/ja/guides/aoconnect/reading-results.html) -- [Cronの監視](https://cookbook_ao.arweave.net/ja/guides/aoconnect/monitoring-cron.html) -- [DryRunの呼び出し](https://cookbook_ao.arweave.net/ja/guides/aoconnect/calling-dryrun.html) -- [プロセスの生成](https://cookbook_ao.arweave.net/ja/guides/aoconnect/spawning-processes.html) -- [プロセスへのアサインメントの送信](https://cookbook_ao.arweave.net/ja/guides/aoconnect/assign-data.html) -- [プロセスへのメッセージの送信](https://cookbook_ao.arweave.net/ja/guides/aoconnect/sending-messages.html) -- [特定のaoノードへの接続](https://cookbook_ao.arweave.net/ja/guides/aoconnect/connecting.html) - -### Aos - -#### Blueprints - -- [Blueprints](https://cookbook_ao.arweave.net/ja/guides/aos/blueprints/index.html) -- [CRED ユーティリティブループリント](https://cookbook_ao.arweave.net/ja/guides/aos/blueprints/cred-utils.html) -- [ステーキングブループリント](https://cookbook_ao.arweave.net/ja/guides/aos/blueprints/staking.html) -- [チャットルームブループリント](https://cookbook_ao.arweave.net/ja/guides/aos/blueprints/chatroom.html) -- [トークンブループリント](https://cookbook_ao.arweave.net/ja/guides/aos/blueprints/token.html) -- [投票ブループリント](https://cookbook_ao.arweave.net/ja/guides/aos/blueprints/voting.html) - -#### Modules - -- [ao](https://cookbook_ao.arweave.net/ja/guides/aos/modules/ao.html) -- [Base64](https://cookbook_ao.arweave.net/ja/guides/aos/modules/base64.html) -- [crypto](https://cookbook_ao.arweave.net/ja/guides/aos/modules/crypto.html) -- [JSON](https://cookbook_ao.arweave.net/ja/guides/aos/modules/json.html) -- [Pretty](https://cookbook_ao.arweave.net/ja/guides/aos/modules/pretty.html) -- [Utils](https://cookbook_ao.arweave.net/ja/guides/aos/modules/utils.html) -- [モジュール](https://cookbook_ao.arweave.net/ja/guides/aos/modules/index.html) - -- [.load](https://cookbook_ao.arweave.net/ja/guides/aos/load.html) -- [`ao`でのトークンの構築](https://cookbook_ao.arweave.net/ja/guides/aos/token.html) -- [ao.linkを使用したトラブルシューティング](https://cookbook_ao.arweave.net/ja/guides/aos/troubleshooting.html) -- [aos](https://cookbook_ao.arweave.net/ja/guides/aos/index.html) -- [aosでPingpongプロセスを作成する](https://cookbook_ao.arweave.net/ja/guides/aos/pingpong.html) -- [aosでのプロンプトのカスタマイズ](https://cookbook_ao.arweave.net/ja/guides/aos/prompt.html) -- [CLI](https://cookbook_ao.arweave.net/ja/guides/aos/cli.html) -- [FAQ](https://cookbook_ao.arweave.net/ja/guides/aos/faq.html) -- [Inboxの理解](https://cookbook_ao.arweave.net/ja/guides/aos/inbox-and-handlers.html) -- [Installing aos](https://cookbook_ao.arweave.net/ja/guides/aos/installing.html) -- [エディタ設定](https://cookbook_ao.arweave.net/ja/guides/aos/editor.html) -- [はじめに](https://cookbook_ao.arweave.net/ja/guides/aos/intro.html) - -### Betteridea - -- [BetterIDEa](https://cookbook_ao.arweave.net/ja/guides/betteridea/index.html) - -- [ガイド](https://cookbook_ao.arweave.net/ja/guides/index.html) - -## References - -- [aoトークンおよびサブレッジャー仕様](https://cookbook_ao.arweave.net/ja/references/token.html) -- [aoモジュール](https://cookbook_ao.arweave.net/ja/references/ao.html) -- [aoを使ってArweaveからデータにアクセスする](https://cookbook_ao.arweave.net/ja/references/data.html) -- [Cronメッセージ](https://cookbook_ao.arweave.net/ja/references/cron.html) -- [Eval](https://cookbook_ao.arweave.net/ja/references/eval.html) -- [Luaに触れてみよう](https://cookbook_ao.arweave.net/ja/references/lua.html) -- [Web Assemblyについて](https://cookbook_ao.arweave.net/ja/references/wasm.html) -- [エディタのセットアップ](https://cookbook_ao.arweave.net/ja/references/editor-setup.html) -- [コミュニティ](https://cookbook_ao.arweave.net/ja/references/community.html) -- [ハンドラ (バージョン 0.0.5)](https://cookbook_ao.arweave.net/ja/references/handlers.html) -- [参考資料](https://cookbook_ao.arweave.net/ja/references/index.html) - -## Tutorials - -### Begin - -- [`The Construct`に入る - インタラクティブチュートリアル](https://cookbook_ao.arweave.net/ja/tutorials/begin/rabbithole.html) -- [aosでチャットルームを構築する](https://cookbook_ao.arweave.net/ja/tutorials/begin/chatroom.html) -- [aoにおけるメッセージング](https://cookbook_ao.arweave.net/ja/tutorials/begin/messaging.html) -- [DAO ガイド](https://cookbook_ao.arweave.net/ja/tutorials/begin/dao.html) -- [チャットルームのトークンゲート](https://cookbook_ao.arweave.net/ja/tutorials/begin/tokengating.html) -- [トークンの作成](https://cookbook_ao.arweave.net/ja/tutorials/begin/token.html) -- [始めよう: インタラクティブチュートリアル](https://cookbook_ao.arweave.net/ja/tutorials/begin/index.html) -- [準備](https://cookbook_ao.arweave.net/ja/tutorials/begin/preparations.html) - -### Bots and games - -- [Bringing it Together](https://cookbook_ao.arweave.net/ja/tutorials/bots-and-games/bringing-together.html) -- [アリーナのメカニクス](https://cookbook_ao.arweave.net/ja/tutorials/bots-and-games/arena-mechanics.html) -- [アリーナの拡張](https://cookbook_ao.arweave.net/ja/tutorials/bots-and-games/build-game.html) -- [お知らせの解釈](https://cookbook_ao.arweave.net/ja/tutorials/bots-and-games/announcements.html) -- [ゲームをプレイしよう!](https://cookbook_ao.arweave.net/ja/tutorials/bots-and-games/ao-effect.html) -- [ゲーム状態の取得](https://cookbook_ao.arweave.net/ja/tutorials/bots-and-games/game-state.html) -- [ボットとゲーム](https://cookbook_ao.arweave.net/ja/tutorials/bots-and-games/index.html) -- [戦略的決定](https://cookbook_ao.arweave.net/ja/tutorials/bots-and-games/decisions.html) -- [自動応答](https://cookbook_ao.arweave.net/ja/tutorials/bots-and-games/attacking.html) - -- [Index](https://cookbook_ao.arweave.net/ja/tutorials/index.html) - -## Welcome - -### Testnet info - -- [aoテストネットに参加しよう](https://cookbook_ao.arweave.net/ja/welcome/testnet-info/index.html) -- [クエストFAQ](https://cookbook_ao.arweave.net/ja/welcome/testnet-info/quests.html) - -- [5分で始める](https://cookbook_ao.arweave.net/ja/welcome/getting-started.html) -- [aoへようこそ](https://cookbook_ao.arweave.net/ja/welcome/index.html) - -- [LLMs ファイルドキュメント](https://cookbook_ao.arweave.net/ja/llms-explanation.html) - - - -# Detailed Content - -## TABLE OF CONTENTS - -- API AND FUNCTION REFERENCES - - aoモジュール - - コミュニティ - - Cronメッセージ - - aoを使ってArweaveからデータにアクセスする - - エディタのセットアップ - - Eval - - ハンドラ (バージョン 0.0.5) - - 参考資料 - - Luaに触れてみよう - - aoトークンおよびサブレッジャー仕様 - - Web Assemblyについて - - - -## API AND FUNCTION REFERENCES - - - -### aoモジュール -Source: https://cookbook_ao.arweave.net/ja/references/ao.html - -### API Definitions -- Properties -- send -- Methods -- send -- spawn -- spawn -- isTrusted -- isTrusted - -### Parameters -| -| ----------- | ------------------------------------------------------------------------------------------------------------ | ------ | -| id | Process Identifier (TXID) | string | -| \_module | Module Identifier (TXID) | string | -| authorities | Set of Trusted TXs | string | -| Authority | Identifiers that the process is able to accept transactions from that are not the owner or the process (0-n) | string | -| \_version | The version of the library | string | -| env | Evaluation Environment | string | -| outbox | Holds Messages and Spawns for response | object | - - -### Parameters -| -| ------ | --------------------------------------------------------------------------------------- | ------ | -| module | The TXID that identifies the module binary to use to instaniate the process with | string | -| spawn | The `spawn` full or parital table object that contains the `Data` and `Tags` properties | table | - - -### Parameters -| -| ---- | ------------------------------------------- | ----- | -| msg | Message to check if trusted by this process | table | - - - -### コミュニティ -Source: https://cookbook_ao.arweave.net/ja/references/community.html - -[Autonomous Finance](https://www.autonomous.finance/) - -### Cronメッセージ -Source: https://cookbook_ao.arweave.net/ja/references/cron.html - -### API Definitions -- Setting -- Handling -- cron - - -### aoを使ってArweaveからデータにアクセスする -Source: https://cookbook_ao.arweave.net/ja/references/data.html - - - -### Handlers.reply(text : string) - -このヘルパーはシンプルなハンドル関数で、基本的にテキストの値を送信メッセージのDataプロパティに設定します。 -``` - - -### Parameters -| -| ------------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| name | string | The identifier of the handler item in the handlers list. | -| pattern | Table or Function | This parameter can take a table that specifies a pattern that the message MUST match, for example `{ Action = "Balance", Recipient = "_" }` this table describes a message that has a Tag called action and it equals the string "Balance", and the message MUST have a Recipient Tag with a value. If you are unable to add a pattern via a table, you can also use the `function` which receives the message DataItem as its argument and you can return a `true`, `false` or `"continue"` result. The `true` result tells the Handlers evaluation pipeline to invoke this handler and exit out of the pipeline. The `false` result tells the Handlers evaluation pipeline to skip this handler and try to find a pattern matched by the next Handler item in the pipeline. Finally, the `"continue"` informs the Handlers evaluation to invoke this handler and continue evaluating. | -| handler | Table (Resolver) or Function | This parameter can take a table that acts as a conditional that invokes a function based on a pattern matched key. or a Function that takes the message DataItem as an argument and performs some business logic. | -| maxRuns (optional) | number | As of 0.0.5, each handler function takes an optional function to define the amount of times the handler should match before it is removed. The default is infinity. | - - - -### 参考資料 -Source: https://cookbook_ao.arweave.net/ja/references/index.html - -## 目次 - -- [Lua](lua)... - -### Luaに触れてみよう -Source: https://cookbook_ao.arweave.net/ja/references/lua.html - -### API Definitions -- Understanding -- Setting -- Basic -- Lua -- Hands -- Resources -- Best -- Conclusion - - -### aoトークンおよびサブレッジャー仕様 -Source: https://cookbook_ao.arweave.net/ja/references/token.html - -### API Definitions -- Spawning -- Balance -- Messaging -- Balance -- Balances -- Balances -- Transfer -- Transfer -- Get -- Mint -- Spawning -- `Credit -- Transfer -- `Credit -- Transfer -- Withdraw -- Withdraw - -### Code Examples -``` - - -### Balances() - -トークンのすべての参加者の残高を返します。 -``` - -``` - - -受取人は、メッセージの`From-Process`タグから、どのトークンを受け取ったかを推測します。 - -### Get-Info() -``` - -``` -### Mint() [optional] - - - -`Mint`アクションを実装することで、プロセスは有効な参加者に新しいトークンを作成する方法を提供します。 -``` - - -### Parameters -| -| -------- | ------------------------------------------------------------------------------------------------------ | ------------------ | -| Balance | get the balance of an identifer | :heavy_check_mark: | -| Balances | get a list of all ledger/account balances | :heavy_check_mark: | -| Transfer | send 1 or more units from the callers balance to one or move targets with the option to notify targets | :x: | -| Mint | if the ledger process is the root and you would like to increase token supply | :x: | - - -### Parameters -| -| ------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------ | -| Name | The title of the token, as it should be displayed to users. | :heavy_check_mark: | -| Ticker | A suggested shortened name for the token, such that it can be referenced quickly. | :heavy_check_mark: | -| Logo | An image that applications may deserire to show next to the token, in order to make it quickly visually identifiable. | :heavy_check_mark: | -| Denomination | The number of the token that should be treated as a single unit when quantities and balances are displayed to users. | :x: | - - -### Parameters -| -| ------------ | ------------------------------------------------------------------ | --------- | -| Source-Token | The `ID` of the top-most process that this subledger represents. | :x: | -| Parent-Token | The `ID` of the parent process that this subledger is attached to. | :x: | - - - -### Web Assemblyについて -Source: https://cookbook_ao.arweave.net/ja/references/wasm.html - -WebAssembly (often abbreviated as Wasm) is a modern binary instruction format providing a portable compilation target for high-level languages like C, C++, and Rust. It enables deployment on the web for client and server applications, offering a high level of performance and efficiency. WebAssembly is designed to maintain the security and sandboxing features of web browsers, making it a suitable choice for web-based applications. It's a key technology for web developers, allowing them to write code in multiple languages and compile it into bytecode that runs in the browser at near-native speed. - -# Summary - -Total files processed: 11 -Total documentation pages: 82 -This documentation is focused on technical references and release notes, prioritizing accuracy and relevance for LLM processing. diff --git a/src/public/llms-full.txt b/src/public/llms-full.txt deleted file mode 100644 index 814f696d..00000000 --- a/src/public/llms-full.txt +++ /dev/null @@ -1,2513 +0,0 @@ -# EN Technical Documentation - -Generated: 2025-09-10T20:06:33.595Z - -This file contains technical reference documentation and release notes. - - - -# API AND FUNCTION REFERENCES - - - -## ao Module -Source: https://cookbook_ao.arweave.net/references/ao.html - -version: 0.0.3 - -`ao` process communication is handled by messages, each process receives messages in the form of [ANS-104 DataItems](https://specs.arweave.net/view/xwOgX-MmqN5_-Ny_zNu2A8o-PnTGsoRb_3FrtiMAkuw), and needs to be able to do the following common operations. - -- [ao.send(msg)](#ao-send-msg-message) - send message to another process -- [ao.spawn(module, msg)](#ao-spawn-module-string-spawn-spawn) - spawn a process - -The goal of this library is to provide this core functionality in the box of the `ao` developer toolkit. As a developer you have the option to leverage this library or not, but it integrated by default. - -## Properties - -| Name | Description | Type | -| ------------------ | ------------------------------------------------------------------------------------------------------------ | -------- | -| id | Process Identifier (TxID) | string | -| \_module | Module Identifier (TxID) | string | -| authorities | Set of Trusted TXs | string | -| Authority | Identifiers that the process is able to accept transactions from that are not the owner or the process (0-n) | string | -| \_version | The version of the library | string | -| reference | Reference number of the process | number | -| env | Evaluation Environment | object | -| outbox | Holds Messages and Spawns for response | object | -| assignables | List of assignables of the process | list | -| nonExtractableTags | List of non-extractable tags of the process | list | -| nonForwardableTags | List of non-forwardable tags of the process | list | -| init | Initializes the AO environment | function | -| send | Sends a message to a target process | function | -| assign | Assigns a message to the process | function | -| spawn | Spawns a process | function | -| result | Returns the result of a message | function | -| isTrusted | Checks if a message is trusted | function | -| isAssignment | Checks if a message is an assignment | function | -| isAssignable | Checks if a message is assignable | function | -| addAssignable | Adds an assignable to the assignables list | function | -| removeAssignable | Removes an assignable from the assignables list | function | -| clearOutbox | Clears the outbox | function | -| normalize | Normalizes a message by extracting tags | function | -| sanitize | Sanitizes a message by removing non-forwardable tags | function | -| clone | Clones a table recursively | function | - -### Environment Schema - -The `ao.env` variable contains information about the initializing message of the process. It follows this schema: - -```lua -ao.env = { - Process = { - Id = string, -- Process ID - Owner = string, -- Process owner - TagArray = { -- Array of name-value pairs - { name = string, value = string } - }, - Tags = { -- Tags as key-value pairs - [string] = string - } - } -} -``` - -#### Example - -```lua -{ - Process = { - Id = "A1b2C3d4E5f6G7h8I9j0K1L2M3N4O5P6Q7R8S9T0", - Owner = "Xy9PqW3vR5sT8uB1nM6dK0gF2hL4jC7iE9rV3wX5", - TagArray = { - { name = "App-Name", value = "aos" } - }, - Tags = { - ["App-Name"] = "aos" - } - } -} -``` - -## Methods - -### `ao.send(msg: Message)` - -Takes a [Message](#message) as input. The function adds `ao`-specific tags and stores the message in `ao.outbox.Messages`. - -#### Example - -```lua -local message = ao.send({ - Target = msg.From, - Data = "ping", - Tags = { - ["Content-Type"] = "text/plain", - ["Action"] = "Ping" - } -}) - --- or - -local message = ao.send({ - Target = msg.From, - Data = "ping", - Action = "Ping", -- will be converted to Tags - ["Content-Type"] = "text/plain" -- will be converted to Tags -}) -``` - -### `ao.spawn(module: string, spawn: Spawn)` - -Takes a module ID string and [Spawn](#spawn) as input. Returns a Spawn table with a generated `Ref_` tag. - -#### Example - -```lua -local process = ao.spawn("processId", { - Data = { initial = "state" }, - Tags = { - ["Process-Type"] = "calculator" - } -}) -``` - -### `ao.assign(assignment: Assignment)` - -Takes an [Assignment](#assignment) as input. Adds the assignment to `ao.outbox.Assignments`. - -#### Example - -```lua -ao.assign({ - Processes = {"process-1", "process-2"}, - Message = "sample-message-id" -}) -``` - -### `ao.result(result: Result)` - -Takes a [Result](#result) as input. Returns the final process execution result. - -#### Example - -```lua -local process_result = ao.result({ - Output = "Process completed successfully", - Messages = { - { Target = "ProcessY", Data = "Result data", Tags = { ["Status"] = "Success" } } - }, - Spawns = { "spawned-process-1" }, - Assignments = { {Processes = { "process-1" }, Message = "assignment-message-id"} } -}) -``` - -### `ao.isAssignable(msg: Message)` - -Takes a [Message](#message) as input. Returns `true` if the message matches a pattern in `ao.assignables`. - -#### Example - -```lua -local can_be_assigned = ao.isAssignable({ - Target = "ProcessA", - Data = "Some content", - Tags = { - ["Category"] = "Info" - } -}) -``` - -### `ao.isAssignment(msg: Message)` - -Takes a [Message](#message) as input. Returns `true` if the message is assigned to a different process. - -#### Example - -```lua -local is_assigned_elsewhere = ao.isAssignment({ - Target = "AnotherProcess" -}) -``` - -### `ao.addAssignable(name: string, condition: function)` - -Adds a named condition function to the process's list of assignables. Messages matching any condition will be accepted when assigned. - -> **Note:** The `condition` parameter uses a similar pattern matching approach as the `pattern` parameter in `Handlers.add()`. For more advanced pattern matching techniques, see the [Handlers Pattern Matching documentation](../references/handlers.md#pattern-matching-tables). - -#### Example - -```lua --- Allow transactions from ArDrive -ao.addAssignable("allowArDrive", function (msg) - return msg.Tags["App-Name"] == "ArDrive-App" -end) - --- Allow transactions with specific content type -ao.addAssignable("allowJson", function (msg) - return msg.Tags["Content-Type"] == "application/json" -end) -``` - -### `ao.removeAssignable(name: string)` - -Removes a previously added assignable condition from the process's list of assignables. - -#### Example - -```lua -ao.removeAssignable("allowArDrive") -``` - -### `ao.isTrusted(msg: Message)` - -Takes a [Message](#message) as input. Returns `true` if the message is from a trusted source. - -#### Example - -```lua -if ao.isTrusted(msg) then - -- Process trusted message -else - -- Handle untrusted message -end -``` - -## Custom `ao` Table Structures - -### Tags - -Used by: `ao.send()`, `ao.spawn()`, `ao.normalize()`, `ao.sanitize()` - -All of the below syntaxes are valid, but each syntax gets converted to `{ name = string, value = string }` tables behind the scenes. We use **alternative 1** throughout the documentation for brevity and consistency. - -```lua --- Default: Array of name-value pair tables -Tags = { - { name = "Content-Type", value = "text/plain" }, - { name = "Action", value = "Ping" } -} - --- Alternative 1: Direct key-value pairs in Tags table using string keys -Tags = { - ["Content-Type"] = "text/plain", - ["Action"] = "Ping" -} - --- Alternative 2: Direct key-value pairs in Tags table using dot notation -Tags = { - Category = "Info", - Action = "Ping" -} -``` - -::: info Root-level Tag Conversion -Any keys in the root message object that are not one of: `Target`, `Data`, `Anchor`, `Tags`, or `From` will automatically be converted into Tags using the key as the tag name and its value as the tag value. - -```lua --- These root-level keys will be automatically converted to Tags -{ - Target = "process-id", - Data = "Hello", - ["Content-Type"] = "text/plain", -- Will become a Tag - Action = "Ping" -- Will become a Tag -} -``` - -::: - -### Message - -Used by: `ao.send()`, `ao.isTrusted()`, `ao.isAssignment()`, `ao.isAssignable()`, `ao.normalize()`, `ao.sanitize()` - -```lua --- Message structure -{ - Target = string, -- Required: Process/wallet address - Data = any, -- Required: Message payload - Tags = Tag
-} -``` - -### Spawn - -Used by: `ao.spawn()` - -```lua --- Spawn structure -{ - Data = any, -- Required: Initial process state - Tags = Tag
-- Required: Process tags -} -``` - -### Assignment - -Used by: `ao.assign()`, `ao.result()` - -```lua --- Assignment configuration table structure -{ - Processes = { string }, -- Required: List of target process ID strings - Message = string -- Required: Message to assign -} -``` - -### Result - -Used by: `ao.result()` - -```lua --- Process result structure -{ - Output = string, -- Optional: Process output - Messages = Message
, -- Optional: Generated messages - Spawns = Spawn
, -- Optional: Spawned processes - Assignments = Assignment
, -- Optional: Process assignments - Error = string -- Optional: Error information -} -``` - -## BetterIDEa -Source: https://cookbook_ao.arweave.net/references/betteridea/index.html - -[BetterIDEa](https://ide.betteridea.dev) is a custom web based IDE for developing on ao. - -It offers a built in Lua language server with ao definitions, so you don't need to install anything. Just open the IDE and start coding! - -Features include: - -- Code completion -- Cell based notebook ui for rapid development -- Easy process management -- Markdown and Latex cell support -- Share projects with anyone through ao processes -- Tight integration with [ao package manager](https://apm.betteridea.dev) - -Read detailed information about the various features and integrations of the IDE in the [documentation](https://docs.betteridea.dev). - -## Community Resources -Source: https://cookbook_ao.arweave.net/references/community.html - -This page provides a comprehensive list of community resources, tools, guides, and links for the AO ecosystem. - -## Core Resources - -[Autonomous Finance](https://www.autonomous.finance/) - -- Autonomous Finance is a dedicated research and technology entity, focusing on the intricacies of financial infrastructure within the ao network. - -[BetterIdea](https://betteridea.dev/) - -- Build faster, smarter, and more efficiently with BetterIDEa, the ultimate native web IDE for AO development - -[0rbit](https://www.0rbit.co/) - -- 0rbit provides any data from the web to an ao process - by utilizing the power of ao, and 0rbit nodes. - The user sends a message to the 0rbit ao, 0rbit nodes fetches the data and the user process receives the data. - -[ArweaveHub](https://arweavehub.com/) - -- A community platform for the Arweave ecosystem featuring events, developer resources, and discovery tools. - -[AR.IO](https://ar.io/) - -- The first permanent cloud network built on Arweave, providing infrastructure for the permaweb with no 404s, no lost dependencies, and reliable access to applications and data through gateways, domains, and deployment tools. - -## Developer Tools - -- [AO Package Manager](https://apm_betteridea.arweave.net) - -## Contributing - -> Not seeing an AO Community Member or resource? Create an issue or submit a pull request to add it to this page: https://github.com/permaweb/ao-cookbook - -## Cron Messages -Source: https://cookbook_ao.arweave.net/references/cron.html - -ao has the ability to generate messages on a specified interval, this interval could be seconds, minutes, hours, or blocks. These messages automatically get evaluated by a monitoring process to inform the Process to evaluate these messages over time. The result is a real-time Process that can communicate with the full ao network or oracles in the outside network. - -## Setting up cron in a process - -The easiest way to create these cron messages is by spawning a new process in the aos console and defining the time interval. - -```sh -aos [myProcess] --cron 5-minutes -``` - -When spawning a new process, you can pass a cron argument in your command line followed by the interval you would like the cron to tick. By default, cron messages are lazily evaluated, meaning they will not be evaluated until the next scheduled message. To initiate these scheduled cron messages, call `.monitor` in aos - this kicks off a worker process on the `mu` that triggers the cron messages from the `cu`. Your Process will then receive cron messages every `x-interval`. - -```lua -.monitor -``` - -If you wish to stop triggering the cron messages simply call `.unmonitor` and this will stop the triggering process, but the next time you send a message, the generated cron messages will still get created and processed. - -## Handling cron messages - -Every cron message has an `Action` tag with the value `Cron`. [Handlers](handlers.md) can be defined to perform specific tasks autonomously, each time a cron message is received. - -```lua -Handlers.add( - "CronTick", -- Handler name - Handlers.utils.hasMatchingTag("Action", "Cron"), -- Handler pattern to identify cron message - function () -- Handler task to execute on cron message - -- Do something - end -) -``` - -Cron messages are a powerful utility that can be used to create "autonomous agents" with expansive capabilities. - -## Accessing Data from Arweave with ao -Source: https://cookbook_ao.arweave.net/references/data.html - -There may be times in your ao development workflow that you want to access data from Arweave. With ao, your process can send an assignment instructing the network to provide that data to your Process. - -## Defining Acceptable Transactions (Required First Step) - -Before you can assign any Arweave transaction to your process, you must first define which transactions your process will accept using [`ao.addAssignable`](../references/ao.md#ao-addassignable-name-string-condition-function). This function creates conditions that determine which Arweave transactions your process will accept. - -```lua --- Allow transactions from ArDrive -ao.addAssignable("allowArDrive", function (msg) - return msg.Tags["App-Name"] == "ArDrive-App" -end) - --- Allow specific content types -ao.addAssignable("allowImages", function (msg) - return msg.Tags["Content-Type"] and string.match(msg.Tags["Content-Type"], "^image/") -end) -``` - -> **Warning:** If you attempt to assign a transaction without first defining a matching assignable pattern, that transaction will be permanently blacklisted and can never be assigned to your process, even if you later add a matching assignable. - -You can remove assignables with `ao.removeAssignable("")`. - -The condition functions use similar pattern matching techniques as found in the [Handlers documentation](../references/handlers.md#pattern-matching-tables). For complete details on the `ao.addAssignable` function, including parameter descriptions and additional examples, see the [ao Module Reference](../references/ao.md#ao-addassignable-name-string-condition-function). - -## Assignment Methods - -After defining acceptable transactions and setting up your listener (if needed), you can request Arweave data in one of two ways: - -### Using `Assign` - -The primary method to request data from Arweave: - -```lua -Assign({ - Processes = { ao.id }, - Message = '' -}) -``` - -### Using `Send` with `Assignments` - -Alternatively, you can use the `Send` function with an `Assignments` parameter: - -```lua -Send({ - Target = ao.id, - Data = 'Hello World', - Assignments = { '', '' } -}) -``` - -## Working with Assigned Data - -You can process assigned data using either `Receive` or `Handlers`: - -### Using `Receive` Directly - -```lua --- Listen for messages from ArDrive -ArweaveData = Receive(function(msg) - return msg.Tags["App-Name"] == "ArDrive-App" -end) - --- Process the data when received -if ArweaveData then - print(ArweaveData.Tags["App-Name"]) - -- Raw Arweave Data is available in ArweaveData.Data -end -``` - -You can also match specific transactions or combine conditions: - -```lua --- Match a specific transaction ID -ArweaveData = Receive({ Id = "" }) - --- Or combine multiple conditions -ArweaveData = Receive(function(msg) - return msg.Tags["App-Name"] == "ArDrive-CLI" and - msg.Tags["Content-Type"] == "image/png" -end) -``` - -> **Note:** When using [`.load`](../guides/aos/load.md#load-lua-files-with-load-filename), the script pauses at `Receive` until data arrives. When running commands separately in the shell, each command executes independently. - -### Using Handlers - -For persistent processing, set up a handler: - -```lua -Handlers.add("ProcessArDriveFiles", - { Tags = { ["App-Name"] = "ArDrive-App" } }, - function(msg) - print(msg.Tags["App-Name"]) - -- Raw Arweave Data is available in msg.Data - end -) -``` - -Handlers are ideal for: - -- Processing multiple assignments over time -- Automated processing without manual intervention -- Building services that other processes can interact with - -For more details, see the [Messaging Patterns](../references/messaging.md#receive-capital-r-blocking-pattern-matcher) and [Handlers](../references/handlers.md#pattern-matching-tables) documentation. - -## Complete Example Workflow - -Here's a complete example that demonstrates the entire process of accessing data from an Arweave transaction: - -```lua --- Step 1: Define which transactions your process will accept -ao.addAssignable("allowArDrive", function (msg) - return msg.Tags["App-Name"] == "ArDrive-App" -end) - --- Step 2: Request the data -Assign({ - Processes = { ao.id }, - Message = '' -}) - --- Step 3: Immediately capture the Assignment; blocking until received -ArweaveData = Receive(function(msg) - return msg.Tags["App-Name"] == "ArDrive-App" -end) - -print(ArweaveData.Tags["App-Name"]) -- e.g., "ArDrive-CLI" --- Raw Arweave Data is available in ArweaveData.Data -``` - -This pattern creates a synchronous flow where your process: - -1. Defines acceptable transactions -2. Requests the data -3. Captures the data using `Receive` -4. Processes the data - -## Practical Examples - -Here are two practical examples showing different approaches to working with Arweave data in your ao process: - -### Example 1: Caching Arweave Data - -This example demonstrates how to load and cache data from Arweave, then use it in subsequent operations: - -```lua --- Initialize state -local Number = 0 - --- Step 1: Define which transactions your process will accept -print("Step 1: Defining acceptable transactions") -ao.addAssignable("addNumber", function (msg) - return msg.Tags["Action"] == "Number" -end) - --- Step 2: Request and cache the initial number from Arweave --- This uses a self-executing function to fetch and cache the value only once -NumberFromArweave = NumberFromArweave or (function() - print("Step 2: Requesting initial number from Arweave") - Assign({ - Processes = { ao.id }, - Message = 'DivdWHaNj8mJhQQCdatt52rt4QvceBR_iyX58aZctZQ' - }) - return tonumber(Receive({ Action = "Number"}).Data) -end)() - --- Step 3: Set up handler for future number updates --- This handler will add new numbers to our cached Arweave number -Handlers.add("Number", function (msg) - print("Received message with Data = " .. msg.Data) - print("Old Number: " .. Number) - Number = NumberFromArweave + tonumber(msg.Data) - print("New Number: " .. Number) -end) -``` - -This example shows how to: - -- Cache Arweave data using a self-executing function -- Use the cached data in subsequent message handling -- Combine Arweave data with new incoming data - -### Example 2: Dynamic Transaction Processing - -This example shows how to process arbitrary Arweave transactions and maintain state between requests: - -```lua --- Table to store pending requests (maps transaction ID to original sender) -local PendingRequests = {} - --- Step 1: Define which transactions your process will accept -print("Step 1: Defining acceptable transactions") -ao.addAssignable("processArweaveNumber", function (msg) - return msg.Tags["Action"] == "Number" -end) - --- Step 2: Set up handler for initiating the processing -Handlers.add( - "ProcessArweaveNumber", - function (msg) - if not msg.Tags["ArweaveTx"] then - print("Error: No ArweaveTx tag provided") - return - end - local txId = msg.Tags["ArweaveTx"] - print("Assigning Arweave transaction: " .. txId) - -- Store the original sender associated with this transaction ID - PendingRequests[txId] = msg.From - -- Assign the transaction to this process - Assign({ - Processes = { ao.id }, - Message = txId - }) - print("Assignment requested; waiting for data...") - end -) - --- Step 3: Set up handler for processing the assigned message -Handlers.add( - "Number", - function (msg) - local txId = msg.Id -- The ID of the assigned message - local originalSender = PendingRequests[txId] - if not originalSender then - print("Error: No pending request found for transaction " .. txId) - return - end - local data = msg.Data - if not data or not tonumber(data) then - print("Error: Invalid number data in assigned message") - return - end - local number = tonumber(data) - local result = number + 1 - print(string.format("Processing: %d + 1 = %d", number, result)) - -- Send the result back to the original sender - Send({ - Target = originalSender, - Data = tostring(result) - }) - -- Clean up the pending request - PendingRequests[txId] = nil - end -) -``` - -To use this example: - -```lua -Send({ - Target = ao.id, - Action = "ProcessArweaveNumber", - Tags = { - ArweaveTx = "YOUR-ARWEAVE-TX-ID" -- ID of a transaction containing a number - } -}) -``` - -This example demonstrates: - -- Processing arbitrary Arweave transactions -- Maintaining state between requests using a pending requests table -- Sending results back to the original requester -- Error handling and request cleanup - -:::warning -When using `Assign` to bridge Arweave data into AO, you must ensure that: - -1. The Arweave transaction you're assigning matches one of your defined assignables -2. You have a corresponding handler or receiver set up to process that transaction type -3. The handler's pattern matching matches the assigned transaction's tags/properties - -For example, if you're assigning a transaction with `Action = "Number"`, you need: - -- An assignable that accepts `msg.Tags["Action"] == "Number"` -- Either a `Receive` function or a handler that matches the same pattern -- Both the assignable and handler must use consistent pattern matching - ::: - -## Important Limitations {#assignable-limitations} - -There are critical limitations to be aware of when working with assignables: - -1. **Matching is Required**: Transactions must match at least one of your defined assignable patterns to be accepted. - -2. **Blacklisting is Permanent**: If you attempt to assign a transaction before defining an appropriate assignable, it will be permanently blacklisted. Even if you later add a matching assignable, that transaction will never be accepted. - -3. **One-time Assignment**: Each Arweave transaction can only be assigned once to a given process. Subsequent assignments of the same transaction will be ignored. - -## Proper Sequence for Assigning Arweave Transactions - -For successful assignment of Arweave transactions, follow these steps: - -1. **Define assignables** to specify which Arweave transactions your process will accept -2. **Wait for any transaction confirmations** (by default, 20 confirmations are required) -3. **Set up handlers or listeners** with `Receive` or `Handlers.add` to process the data -4. **Assign the Arweave transaction** to your process (see [Assignment Methods](#assignment-methods)) - -The order of steps 3 and 4 can be interchanged based on your needs: - -- When using `Receive` in a script loaded with `.load`, ensure `Assign` is placed before `Receive` to prevent the process from hanging, as `Receive` is blocking. -- When using handlers or running commands separately in the shell, the order doesn't matter as handlers will catch messages whenever they arrive - -## Why Access Data from Arweave? - -There are several practical reasons to access Arweave data from your ao process: - -1. **Efficient Handling of Large Data**: For larger content, directly accessing Arweave is more efficient: - - - Reference large media files (images, videos, documents) without storing them in your process - - Work with datasets too large to fit in process memory - - Maintain a lightweight process that can access substantial external resources - -2. **External Data for Decision-Making**: Your process may need data stored on Arweave to make informed decisions. For example: - - - Reading token price data stored by an oracle - - Accessing verified identity information - - Retrieving voting records or governance data - -3. **Dynamic Loading of Features**: Rather than including all functionality in your initial process code: - - - Load modules or plugins from Arweave as needed - - Update configuration without redeploying your entire process - - Implement upgradable components with new versions stored on Arweave - -This approach allows you to create more sophisticated applications that leverage Arweave's permanent storage while maintaining efficient process execution in the ao environment. - -When another process Assigns a transaction to this process, you can also use handlers to process the data asynchronously. - -## Editor setup -Source: https://cookbook_ao.arweave.net/references/editor-setup.html - -Remembering all the built in ao functions and utilities can sometimes be hard. To enhance your developer experience, it is recommended to install the [Lua Language Server](https://luals.github.io) extension into your favorite text editor and add the [ao addon](https://github.com/martonlederer/ao-definitions). It supports all built in aos [modules](../guides/aos/modules/index.md) and [globals](../guides/aos/intro.md#globals). - -## VS Code - -Install the [sumneko.lua](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) extension: - -1. Search for "Lua" by sumneko in the extension marketplace -2. Download and install the extension -3. Open the VS Code command palette with `Shift + Command + P` (Mac) / `Ctrl + Shift + P` (Windows/Linux) and run the following command: - -``` -> Lua: Open Addon Manager -``` - -4. In the Addon Manager, search for "ao", it should be the first result. Click "Enable" and enjoy autocomplete! - -## Other editors - -1. Verify that your editor supports the [language server protocol](https://microsoft.github.io/language-server-protocol/implementors/tools/) -2. Install Lua Language Server by following the instructions at [luals.github.io](https://luals.github.io/#install) -3. Install the "ao" addon to the language server - -## BetterIDEa - -[BetterIDEa](https://ide.betteridea.dev) is a custom web based IDE for developing on ao. - -It offers a built in Lua language server with ao definitions, so you don't need to install anything. Just open the IDE and start coding! - -Features include: - -- Code completion -- Cell based notebook ui for rapid development -- Easy process management -- Markdown and Latex cell support -- Share projects with anyone through ao processes -- Tight integration with [ao package manager](https://apm.betteridea.dev) - -Read detailed information about the various features and integrations of the IDE in the [documentation](https://docs.betteridea.dev). - -## glossary -Source: https://cookbook_ao.arweave.net/references/glossary.html - - - - - - -## Handlers (Version 0.0.5) -Source: https://cookbook_ao.arweave.net/references/handlers.html - -## Overview - -The Handlers library provides a flexible way to manage and execute a series of process functions based on pattern matching. An AO process responds based on receiving Messages, these messages are defined using the Arweave DataItem specification which consists of Tags, and Data. Using the Handlers library, you can define a pipeline of process evaluation based on the attributes of the AO Message. Each Handler is instantiated with a name, a pattern matching function, and a function to execute on the incoming message. This library is suitable for scenarios where different actions need to be taken based on varying input criteria. - -## Concepts - -### Handler Arguments Overview - -When adding a handler using `Handlers.add()`, you provide three main arguments: - -1. `name` (string): The identifier for your handler -2. `pattern` (table or function): Defines how to match incoming messages -3. `handler` (function or resolver table): Defines what to do with matched messages - -### Pattern Matching Tables - -Pattern Matching Tables provide a declarative way to match incoming messages based on their attributes. This is used as the second argument in `Handlers.add()` to specify which messages your handler should process. - -#### Basic Pattern Matching Rules - -1. **Simple Tag Matching** - - ```lua - { "Action" = "Do-Something" } -- Match messages that have an exact Action tag value - ``` - -2. **Wildcard Matching** - - ```lua - { "Recipient" = '_' } -- Match messages with any Recipient tag value - ``` - -3. **Pattern Matching** - - ```lua - { "Quantity" = "%d+" } -- Match using Lua string patterns (similar to regex) - ``` - -4. **Function-based Matching** - ```lua - { "Quantity" = function(v) return tonumber(v) ~= nil end } -- Custom validation function - ``` - -#### Common Pattern Examples - -1. **Balance Action Handler** - - ```lua - { Action = "Balance" } -- Match messages with Action = "Balance" - ``` - -2. **Numeric Quantity Handler** - ```lua - { Quantity = "%d+" } -- Match messages where Quantity is a number - ``` - -### Default Action Handlers (AOS 2.0+) - -AOS 2.0 introduces simplified syntax for Action-based handlers. Instead of writing explicit pattern functions, you can use these shorthand forms: - -```lua --- Traditional syntax -Handlers.add("Get-Balance", function (msg) return msg.Action == "Balance", doBalance) - --- Simplified syntax options: -Handlers.add("Balance", "Balance", doBalance) -- Explicit action matching -Handlers.add("Balance", doBalance) -- Implicit action matching -``` - -### Resolvers - -Resolvers are special tables that can be used as the third argument in `Handlers.add()` to enable conditional execution of functions based on additional pattern matching. Each key in a resolver table is a pattern matching table, and its corresponding value is a function that executes when that pattern matches. - -```lua -Handlers.add("Update", - { - [{ Status = "Ready" }] = function (msg) print("Ready") end, - [{ Status = "Pending" }] = function (msg) print("Pending") end, - [{ Status = "Failed" }] = function (msg) print("Failed") end - } -) -``` - -This structure allows developers to create switch/case-like statements where different functions are triggered based on which pattern matches the incoming message. Resolvers are particularly useful when you need to handle a group of related messages differently based on additional criteria. - -## Module Structure - -- `Handlers._version`: String representing the version of the Handlers library. -- `Handlers.list`: Table storing the list of registered handlers. - -## Common Handler Function Parameters - -| Parameter | Type | Description | -| -------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | `string` | The identifier of the handler item in the handlers list. | -| `pattern` | `table` or `function` | Specifies how to match messages. As a table, defines required message tags with string values (e.g. `{ Action = "Balance", Recipient = "_" }` requires an "Action" tag with string value "Balance" and any string "Recipient" tag value). As a function, takes a message DataItem and returns: "true" (invoke handler and exit pipeline), "false" (skip handler), or "continue" (invoke handler and continue pipeline). | -| `handler` | (Resolver) `table` or `function` | Either a resolver table containing pattern-function pairs for conditional execution, or a single function that processes the message. When using a resolver table, each key is a pattern matching table and its value is the function to execute when that pattern matches. When using a function, it takes the message DataItem as an argument and executes business logic. | -| `maxRuns` (optional) | number | As of 0.0.5, each handler function takes an optional function to define the amount of times the handler should match before it is removed. The default is infinity. | - -## Functions - -### `Handlers.add(name, pattern, handler)` - -Adds a new handler or updates an existing handler by name - -### `Handlers.append(name, pattern, handler)` - -Appends a new handler to the end of the handlers list. - -### `Handlers.once(name, pattern, handler)` - -Only runs once when the pattern is matched. Equivalent to setting `maxRuns = 1`. This is the underlying implementation used by the `Receive` function in the messaging system. - -### `Handlers.prepend(name, pattern, handler)` - -Prepends a new handler to the beginning of the handlers list. - -### `Handlers.before(handleName)` - -Returns an object that allows adding a new handler before a specified handler. - -### `Handlers.after(handleName)` - -Returns an object that allows adding a new handler after a specified handler. - -### `Handlers.remove(name)` - -Removes a handler from the handlers list by name. - -## Handler Execution Notes - -### Execution Order - -- Handlers are executed in the order they appear in `Handlers.list`. -- When a message arrives, each handler's pattern function is called sequentially to determine if it should process the message. - -### Pattern Function Return Values - -Pattern functions determine the message handling flow based on their return values: - -1. **Skip Handler (No Match)** - - - **Return**: `0`, `false`, or any string except "continue" or "break" - - **Effect**: Skips current handler and proceeds to the next one in the list - -2. **Handle and Continue** - - - **Return**: `1` or `"continue"` - - **Effect**: Processes the message and continues checking subsequent handlers - - **Use Case**: Ideal for handlers that should always execute (e.g., logging) - -3. **Handle and Stop** - - **Return**: `-1`, `true`, or `"break"` - - **Effect**: Processes the message and stops checking further handlers - - **Use Case**: Most common scenario where a handler exclusively handles its matched message - -### Practical Examples - -- **Logging Handler**: Place at the start of the list and return `"continue"` to log all messages while allowing other handlers to process them. -- **Specific Message Handler**: Return `"break"` to handle matched messages exclusively and prevent further processing by other handlers. - -## Handlers.utils - -The `Handlers.utils` module provides two functions that are common matching patterns and one function that is a common handle function. - -- `hasMatchingData(data: string)` -- `hasMatchingTag(name: string, value: string)` -- `reply(text: string)` - -### `Handlers.utils.hasMatchingData(data: string)` - -- This helper function returns a pattern matching function that takes a message as input. The returned function checks if the message's `Data` field contains the specified string. You can use this helper directly as the pattern argument when adding a new handler. - - ```lua - Handlers.add("ping", - Handlers.utils.hasMatchingData("ping"), - ... - ) - ``` - -### `Handlers.utils.hasMatchingTag(name: string, value: string)` - -- This helper function returns a pattern matching function that takes a message as input. The returned function checks if the message has a tag with the specified `name` and `value`. If they match exactly, the pattern returns true and the handler function will be invoked. This helper can be used directly as the pattern argument when adding a new handler. - - ```lua - Handlers.add("ping", - Handlers.utils.hasMatchingTag("Action", "Ping"), - ... - ) - ``` - -### `Handlers.utils.reply(text: string)` - -- This helper is a simple handle function, it basically places the text value in to the `Data` property of the outbound message. - - ```lua - Handlers.add("ping", - Handlers.utils.hasMatchingData("ping"), - Handlers.utils.reply("pong") - ) - ``` - -## Example Handlers - -### Pattern Matching Table - -```lua -Handlers.add("Ping", -- Name of the handler - { Action = "Ping" }, -- Matches messages with Action = "Ping" tag - function(msg) -- Business logic to execute on Message - print("ping") - msg.reply({ Data = "pong" }) - end -) -``` - -### Resolver Table Handler - -```lua -Handlers.add("Foobarbaz", -- Name of the handler - { Action = "Speak" }, -- Matches messages with Action = "Speak" tag - { - -- Resolver with pattern-function pairs - [{ Status = "foo" }] = function(msg) print("foo") end, - [{ Status = "bar" }] = function(msg) print("bar") end, - [{ Status = "baz" }] = function(msg) print("baz") end - } -) -``` - -### Function-Based Pattern Matching & Handler - -```lua -Handlers.add("Example", -- Name of the handler - function(msg) -- Pattern function matches messages with Action = "Speak" tag - return msg.Action == "Speak" - end, - function(msg) -- Handler function that executes business logic - print(msg.Status) - end -) -``` - -## References -Source: https://cookbook_ao.arweave.net/references/index.html - -This section provides detailed technical references for AO components, languages, and tools. Use these resources to find specific information when implementing your AO projects. - -## Programming Languages - -Resources for the programming languages used in AO: - -- [Lua](./lua) - Reference for the Lua programming language, the primary language used in AO -- [WebAssembly (WASM)](./wasm) - Information about using WebAssembly modules in AO -- [Lua Optimization](./lua-optimization) - Techniques and best practices for optimizing Lua code in AO - -## AO API Reference - -Documentation for AO's core APIs and functionality: - -- [AO Core](./ao) - Core `ao` module and API reference -- [Messaging](./messaging) - Comprehensive guide to the AO messaging system patterns -- [Handlers](./handlers) - Reference for event handlers and message processing -- [Token](./token) - Information about token creation and management -- [Arweave Data](./data) - Guide to data handling and storage in AO -- [Cron](./cron) - Documentation for scheduling and managing timed events - -## Development Environment - -Tools and setup for AO development: - -- [Editor Setup](./editor-setup) - Guide to setting up your development environment for AO -- [BetterIDEa](./betteridea/index) - The ultimate native web IDE for AO development - -## Community Resources - -Connect with the AO community: - -- [Community Resources](./community) - Information about AO community resources and support - -## Navigation - -Use the sidebar to navigate between reference topics. References are organized by category to help you find the information you need quickly. - -## Lua Optimization Guide for AO Platform -Source: https://cookbook_ao.arweave.net/references/lua-optimization.html - -This guide provides practical tips for writing efficient, fast, and performant Lua code for on-chain programs on the AO platform. - -## Table Operations - -### Appending Elements - -```lua --- ❌ Inefficient: Up to 7x slower in tight loops -table.insert(t, v) - --- ✅ Efficient: Direct indexing is ~2x faster -t[#t + 1] = v -``` - -### Removing Elements - -```lua --- ❌ Inefficient: Shifts all elements left -table.remove(t, 1) - --- ✅ Efficient: Remove from end -local x = t[#t] -t[#t] = nil -``` - -## Variable Access - -### Local Variables - -```lua --- ❌ Inefficient: Global lookup each time -for i = 1, 1000 do - math.sin(i) -end - --- ✅ Efficient: Cache the function -local sin = math.sin -for i = 1, 1000 do - sin(i) -- ~30% faster in loops -end -``` - -### Upvalues - -```lua --- ❌ Inefficient: Config lookup on each call -Handlers.add("ValidateGameToken", - function(msg) - local config = ao.config - validateToken(msg, config) - end -) - --- ✅ Efficient: Cache config as upvalue -local config = ao.config -Handlers.add("ValidateGameToken", - function(msg) - validateToken(msg, config) - end -) -``` - -## String Operations - -### String Concatenation - -```lua --- ❌ Inefficient: Creates many intermediate strings -local str = "" -for i = 1, N do - str = str .. "line" .. i -end - --- ✅ Efficient: Single concatenation at end -local lines = {} -for i = 1, N do - lines[i] = "line" .. i -end -local str = table.concat(lines) -``` - -### Pattern Matching - -```lua --- ❌ Inefficient: Recompiles pattern on each iteration -for line in io.lines() do - if line:match("^%s*(%w+)%s*=%s*(%w+)") then - -- Process match - end -end - --- ✅ Efficient: Compile pattern once -local pattern = "^%s*(%w+)%s*=%s*(%w+)" -for line in io.lines() do - if line:match(pattern) then - -- Process match - end -end -``` - -## Memory Management - -### Table Reuse - -```lua --- ❌ Inefficient: Creates new table on each call -Handlers.add("ComputeGameResults", - function(msg) - local results = {} - -- Fill results - return results - end -) - --- ✅ Efficient: Reuse and clear table -local results = {} -Handlers.add("ComputeGameResults", - function(msg) - for k in pairs(results) do results[k] = nil end - -- Fill results - return results - end -) -``` - -### Minimize Garbage Creation - -```lua --- ❌ Inefficient: Creates new response table on every transfer -local function createTransferResponse(sender, recipient, amount) - return { - from = sender, - to = recipient, - quantity = amount, - success = true, - newBalance = Balances[sender], - tags = { - Action = "Transfer-Complete", - Type = "Token" - } - } -end - --- ✅ Efficient: Reuse template table -local transferResponse = { - from = nil, - to = nil, - quantity = 0, - success = false, - newBalance = 0, - tags = { - Action = "Transfer-Complete", - Type = "Token" - } -} - -local function createTransferResponse(sender, recipient, amount) - transferResponse.from = sender - transferResponse.to = recipient - transferResponse.quantity = amount - transferResponse.success = true - transferResponse.newBalance = Balances[sender] - return transferResponse -end -``` - -## Blockchain-Specific Optimizations - -### State Management - -```lua --- ❌ Inefficient: Multiple separate state updates -for _, item in ipairs(items) do - ao.send({ Target = "processID", Action = "Update", Data = item }) -end - --- ✅ Efficient: Batch updates into single message -local updates = {} -for _, item in ipairs(items) do - table.insert(updates, item) -end -ao.send({ Target = "processID", Action = "BatchUpdate", Data = updates }) -``` - -## Additional Resources - -- [Lua Performance Guide](https://www.lua.org/gems/sample.pdf) -- Special thanks to [@allquantor](https://x.com/allquantor/status/1887370546259644728?s=12) for sharing optimization tips - -## Meet Lua -Source: https://cookbook_ao.arweave.net/references/lua.html - -## Understanding Lua - -- **Background**: Lua is a lightweight, high-level, multi-paradigm programming language designed primarily for embedded systems and clients. It's known for its efficiency, simplicity, and flexibility. -- **Key Features**: Lua offers powerful data description constructs, dynamic typing, efficient memory management, and good support for object-oriented programming. - -## Setting Up - -1. **Installation**: Visit [Lua's official website](http://www.lua.org/download.html) to download and install Lua. -2. **Environment**: You can use a simple text editor and command line, or an IDE like ZeroBrane Studio or Eclipse with a Lua plugin. - -## Basic Syntax and Concepts (in aos) - -- **Hello World**: - ```lua - "Hello, World!" - ``` -- **Variables and Types**: Lua is dynamically typed. Basic types include `nil`, `boolean`, `number`, `string`, `function`, `userdata`, `thread`, and `table`. -- **Control Structures**: Includes `if`, `while`, `repeat...until`, and `for`. -- **Functions**: First-class citizens in Lua, supporting closures and higher-order functions. -- **Tables**: The only data structuring mechanism in Lua, which can be used to represent arrays, sets, records, etc. - -## Hands-On Practice - -- **Experiment with Lua's Interactive Mode**: Run `aos` in your terminal and start experimenting with Lua commands. -- **Write Simple Scripts**: Create `.lua` files and run them using the Lua interpreter. Use `.load file.lua` feature to upload lua code on your `aos` process. - -## Resources - -- **Official Documentation**: [Lua 5.3 Reference Manual](https://www.lua.org/manual/5.3/) -- **Online Tutorials**: Websites like [Learn Lua](https://www.learn-lua.org/) are great for interactive learning. -- **Books**: "Programming in Lua" (first edition available [online](http://www.lua.org/pil/contents.html)) is a comprehensive resource. -- **Community**: Join forums or communities like [Lua Users](http://lua-users.org/) for support and discussions. - -## Best Practices - -- **Keep It Simple**: Lua is designed to be simple and flexible. Embrace this philosophy in your code. -- **Performance**: Learn about Lua's garbage collection and efficient use of tables. -- **Integration**: Consider how Lua can be embedded into other applications, particularly C/C++ projects. - -## Conclusion - -Lua is a powerful language, especially in the context of embedded systems and game development. Its simplicity and efficiency make it a great choice for specific use cases. Enjoy your journey into Lua programming! - -## Messaging Patterns in ao -Source: https://cookbook_ao.arweave.net/references/messaging.html - -This reference guide explains the messaging patterns available in ao and when to use each one. - -## Quick Reference: Choosing the Right Pattern - -| If you need to... | Process Flow | Key function(s) | -| -------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| Send a message without waiting for a response | **_A → B_** | [`ao.send`](#ao-send-asynchronous-message-sending) | -| Send a message and wait for a response | **_A → B → A_** | [`ao.send().receive()`](#ao-send-receive-lowercase-r-blocking-reference-matcher) | -| Process messages and respond to the sender | **_B → A_** | [`Handlers.add`](#msg-reply-asynchronous-response-sending) + [`msg.reply`](#msg-reply-asynchronous-response-sending) | -| Create a chain of processing services | **_A → B → C → A_** | [`msg.forward`](#msg-forward-message-forwarding) + [`ao.send().receive()`](#ao-send-receive-lowercase-r-blocking-reference-matcher) | -| Wait for any matching message regardless of sender | **_Any → A_** | [`Receive`](#receive-capital-r-blocking-pattern-matcher) (capital R) | -| Create a standard automated response | **_B → A_** | [`Handlers.utils.reply`](#handlers-utils-reply-simple-reply-handler-creation) | - -## Sending Messages - -### `ao.send`: Asynchronous Message Sending - -Non-blocking direct **_A → B_** messaging that returns immediately after sending. - -- Use for fire-and-forget notifications or starting async conversations -- Returns a promise-like object that can be chained with [`.receive()`](#ao-send-receive-lowercase-r-blocking-reference-matcher) if needed -- Good for parallel processing since it doesn't block execution - -``` -Client (A) → Service (B) - ↓ ↓ -Continues Processes - execution message -``` - -**Basic Send Example:** - -```lua --- Non-blocking send example -local serviceId = "process-789" -- Process ID of the target service - -ao.send({ - Target = serviceId, - Data = "Hello!", - Action = "Greeting" -}) --- Code here runs immediately after sending -``` - -### `msg.reply`: Asynchronous Response Sending - -Non-blocking **_B → A_** response with automatic reference tracking. Used within handlers to respond to incoming messages. - -- Automatically links response to original message via [`X-Reference`](#message-properties) -- Enables asynchronous request-response patterns -- Automatically sets `Target` to the original sender or [`Reply-To`](#message-properties) address if specified - -``` -Client (A) → Service (B) - ← -Response tagged with X-Reference -``` - -**Handler Reply Example:** - -```lua --- Non-blocking reply in a handler -Handlers.add("greeting-handler", - { Action = "Greeting" }, - function(msg) - msg.reply({ Data = "Hi back!" }) -- Returns immediately - -- Handler continues executing here - end -) -``` - -### `msg.forward`: Message Forwarding - -Non-blocking multi-process routing for **_A → B → C → A_** patterns. Creates a sanitized copy of the original message. - -- Takes a `target` and a partial message to overwrite forwarded message fields -- Preserves [`Reply-To`](#message-properties) and [`X-Reference`](#message-properties) properties for complete message tracking -- Sets [`X-Origin`](#message-properties) to original sender, enabling final service to reply directly to originator - -``` -Client (A) → Service (B) → Backend (C) - ↖ ↙ - Response with X-Reference -``` - -**Multi-Process Pipeline Example:** - -```lua --- In client process -local middlewareProcessId = "process-123" -local finalProcessId = "process-456" - --- Send to middleware and wait for response from final service -local response = ao.send({ - Target = middlewareProcessId, - Action = "Transform", - Data = "raw-data" -}).receive(finalProcessId) -- Explicitly wait for response from final service - --- In middleware service -Handlers.add("transform-middleware", - { Action = "Transform" }, - function(msg) - local finalProcessId = "process-456" - - msg.forward(finalProcessId, { - Data = msg.Data .. " (pre-processed)", - Action = "Transform-Processed" - }) - end -) - --- In final service -Handlers.add("final-processor", - { Action = "Transform-Processed" }, - function(msg) - -- No need to know the client ID - it's stored in X-Origin - msg.forward(msg['X-Origin'], { - Data = msg.Data .. " (final processing complete)", - Action = "Transform-Complete" - }) - end -) -``` - -### `Handlers.utils.reply`: Simple Reply Handler Creation - -Creates a handler function that automatically replies with a fixed response. A wrapper around [`msg.reply`](#msg-reply-asynchronous-response-sending) for common use cases. - -**Simple String Response Example:** - -```lua --- Simple string response handler -Handlers.add("echo-handler", - { Action = "Echo" }, - Handlers.utils.reply("Echo reply!") -) - --- Equivalent to: -Handlers.add("echo-handler", - { Action = "Echo" }, - function(msg) - msg.reply({ Data = "Echo reply!" }) - end -) -``` - -**Message Table Response Example:** - -```lua --- Message table response handler -Handlers.add("status-handler", - { Action = "Status" }, - Handlers.utils.reply({ - Data = "OK", - Action = "Status-Response" - }) -) -``` - -## Receiving Messages - -### `Receive` (Capital R): Blocking Pattern Matcher - -Blocks execution until any matching message arrives from any sender. Under the hood, this is implemented using `Handlers.once`, making it a one-time pattern matcher that automatically removes itself after execution. - -- Waits for any message matching the pattern, regardless of origin -- Use for synchronous message processing flows or event listening -- Automatically removes the handler after first match (using `Handlers.once` internally) - -``` - Process (A) - ↓ -Blocks until match received - ↓ - Continues execution -``` - -**Message Pattern Matching Example:** - -```lua --- Blocks until matching message received -local msg = Receive({ - Action = "Update" -}) - -if msg then - -- Process message -end -``` - -### `ao.send().receive` (Lowercase r): Blocking Reference Matcher - -Blocks execution until a specific reply arrives, enabling **_A → B → A_** and **_A → B → C → A_** request-response cycles. - -- Only matches messages linked by [`X-Reference`](#message-properties) -- Can specify a target process ID to indicate which process will reply -- Implicitly waits for the proper response based on message reference chains -- For **_A → B → A_** flows, process B uses [`msg.reply`](#msg-reply-asynchronous-response-sending) -- For **_A → B → C → A_** flows, processes B and C use [`msg.forward`](#msg-forward-message-forwarding) - -**Basic Request-Response Example:** - -```lua --- Basic usage: wait for reply from target -local serviceId = "process-789" - -local reply = ao.send({ - Target = serviceId, - Action = "Query", - Data = { query: "select" } -}).receive() -- Blocks until response received -``` - -## Message Properties - -The following properties track message chains and ensure proper routing: - -- `Reference`: Unique identifier automatically assigned to each message. -- `Reply-To`: Specifies the destination for responses. -- `X-`: Any property starting with `X-` denotes a 'forwarded' tag and is automatically managed by the system. - - `X-Reference`: Maintains the conversation chain across replies and forwards. - - `X-Origin`: Tracks the conversation originator. - -The system automatically manages these properties when using `msg.reply` and `msg.forward`. Check -out the [source code](https://github.com/permaweb/aos/blob/e9fc10c54b4f21302ee8d084d31f3383b46857b2/process/process.lua#L377-L406) to see exactly how these -properties are managed. - -## Blocking vs. Non-Blocking - -Functions either pause your code or let it continue running: - -- **Non-blocking** ([`ao.send`](#ao-send-asynchronous-message-sending), [`msg.reply`](#msg-reply-asynchronous-response-sending), [`msg.forward`](#msg-forward-message-forwarding)): Send and continue execution -- **Blocking** ([`Receive`](#receive-capital-r-blocking-pattern-matcher), [`.receive()`](#ao-send-receive-lowercase-r-blocking-reference-matcher)): Pause until response arrives - -## ao Token and Subledger Specification -Source: https://cookbook_ao.arweave.net/references/token.html - -**Status:** DRAFT-1 -**Targeting Network:** ao.TN.1 - -This specification describes the necessary message handlers and functionality required for a standard ao token process. Implementations of this standard typically offer users the ability to control a transferrable asset, whose scarcity is maintained by the process. - -Each compliant process will likely implement a ledger of balances in order to encode ownership of the asset that the process represents. Compliant processes have a set of methods that allow for the modification of this ledger, typically with safe-guards to ensure the scarcity of ownership of the token represented by the process. - -Additionally, this specification describes a 'subledger' process type which, when implemented, offers the ability to split move a number of the tokens from the parent into a child process that implements the same token interface specification. If the `From-Module` of the subledger process is trusted by the participants, these subledgers can be used to transact in the 'source' token, without directly exchanging messages with it. This allows participants to use the tokens from a process, even if that process is congested. Optionally, if the participants trust the `Module` a subledger process is running, they are able to treat balances across these processes as _fungible_. The result of this is that an arbitrary numbers of parallel processes -- and thus, transactions -- can be processed by a single token at any one time. - -# Token Processes - -A specification-compliant token process responds to a number of different forms of messages, with each form specified in an `Action` tag. The full set of `Action` messages that the token must support are as follows: - -| Name | Description | Read-Only | -| -------- | ------------------------------------------------------------------------------------------------------ | ------------------ | -| Balance | get the balance of an identifier | :heavy_check_mark: | -| Balances | get a list of all ledger/account balances | :heavy_check_mark: | -| Transfer | send 1 or more units from the callers balance to one or move targets with the option to notify targets | :x: | -| Mint | if the ledger process is the root and you would like to increase token supply | :x: | - -In the remainder of this section the tags necessary to spawn a compliant token process, along with the form of each of the `Action` messages and their results is described. - -## Spawning Parameters - -Every compliant token process must carry the following immutable parameters upon its spawning message: - -| Tag | Description | Optional? | -| ------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------ | -| Name | The title of the token, as it should be displayed to users. | :heavy_check_mark: | -| Ticker | A suggested shortened name for the token, such that it can be referenced quickly. | :heavy_check_mark: | -| Logo | An image that applications may desire to show next to the token, in order to make it quickly visually identifiable. | :heavy_check_mark: | -| Denomination | The number of the token that should be treated as a single unit when quantities and balances are displayed to users. | :x: | - -## Messaging Protocol - -### Balance(Target? : string) - -- Returns the balance of a target, if a target is not supplied then the balance of the sender of the message must be returned. - -**Example `Action` message:** - -```lua -ao.send({ - Target = "{TokenProcess Identifier}", - Tags = { - ["Action"] = "Balance", - ["Target"] = "{IDENTIFIER}" - } -}) -``` - -**Example response message:** - -```lua -{ - Tags = { - ["Balance"] = "50", - ["Target"] = "LcldyO8wwiGDzC3iXzGofdO8JdR4S1_2A6Qtz-o33-0", - ["Ticker"] = "FUN" - } -} -``` - -### Balances() - -- Returns the balance of all participants in the token. - -```lua -ao.send({ - Target = "[TokenProcess Identifier]", - Tags = { - ["Action"] = "Balances", - ["Limit"] = 1000, # TODO: Is this necessary if the user is paying for the compute and response? - ["Cursor"] = "BalanceIdentifier" - } -}) -``` - -**Example response message:** - -```lua -{ - Data = { - "MV8B3MAKTsUOqyCzQ0Tsa2AR3TiWTBU1Dx0xM4MO-f4": 100, - "LcldyO8wwiGDzC3iXzGofdO8JdR4S1_2A6Qtz-o33-0": 50 - } -} -``` - -### Transfer(Target, Quantity) - -If the sender has a sufficient balance, send the `Quantity` to the `Target`, issuing a `Credit-Notice` to the recipient and a `Debit-Notice` to the sender. The `Credit-` and `Debit-Notice` should forward any and all tags from the original `Transfer` message with the `X-` prefix. If the sender has an insufficient balance, fail and notify the sender. - -```lua -ao.send({ - Target = "[TokenProcess Identifier]", - Tags = { - ["Action"] = "Transfer", - ["Recipient"] = "[ADDRESS]", - ["Quantity"] = "100", - ["X-[Forwarded Tag(s) Name]"] = "[VALUE]" - } -}) -``` - -If a successful transfer occurs a notification message should be sent if `Cast` is not set. - -```lua -ao.send({ - Target = "[Recipient Address]", - Tags = { - ["Action"] = "Credit-Notice", - ["Sender"] = "[ADDRESS]", - ["Quantity"] = "100", - ["X-[Forwarded Tag(s) Name]"] = "[VALUE]" - } -}) -``` - -Recipients will infer from the `From-Process` tag of the message which tokens they have received. - -### Get-Info() - -```lua -ao.send({ - Target = "{Token}", - Tags = { - ["Action"] = "Info" - } -}) -``` - -### Mint() [optional] - -Implementing a `Mint` action gives the process a way of allowing valid participants to create new tokens. - -```lua -ao.send({ - Target ="{Token Process}", - Tags = { - ["Action"] = "Mint", - ["Quantity"] = "1000" - } -}) -``` - -# Subledger Processes - -In order to function appropriately, subledgers must implement the full messaging protocol of token contracts (excluding the `Mint` action). Subledgers must also implement additional features and spawn parameters for their processes. These modifications are described in the following section. - -### Spawning Parameters - -Every compliant subledger process must carry the following immutable parameters upon its spawning message: - -| Tag | Description | Optional? | -| ------------ | ------------------------------------------------------------------ | --------- | -| Source-Token | The `ID` of the top-most process that this subledger represents. | :x: | -| Parent-Token | The `ID` of the parent process that this subledger is attached to. | :x: | - -### `Credit-Notice` Handler - -Upon receipt of a `Credit-Notice` message, a compliant subledger process must check if the process in question is the `Parent-Token`. If it is, the subledger must increase the balance of the `Sender` by the specified quantity. - -### Transfer(Target, Quantity) - -In addition to the normal tags that are passed in the `Credit-Notice` message to the recipient of tokens, a compliant subledger process must also provide both of the `Source-Token` and `Parent-Token` values. This allows the recipient of the `Transfer` message -- if they trust the `Module` of the subledger process -- to credit a receipt that is analogous (fungible with) deposits from the `Source-Token`. - -The modified `Credit-Notice` should be structured as follows: - -```lua -ao.send({ - Target = "[Recipient Address]", - Tags = { - ["Action"] = "Credit-Notice", - ["Quantity"] = "100", - ["Source-Token"] = "[ADDRESS]", - ["Parent-Token"] = "[ADDRESS]", - ["X-[Forwarded Tag(s) Name]"] = "[VALUE]" - } -}) -``` - -### Withdraw(Target?, Quantity) - -All subledgers must allow balance holders to withdraw their tokens to the parent ledger. Upon receipt of an `Action: Withdraw` message, the subledger must send an `Action` message to its `Parent-Ledger`, transferring the requested tokens to the caller's address, while debiting their account locally. This transfer will result in a `Credit-Notice` from the `Parent-Ledger` for the caller. - -```lua -ao.send({ - Target = "[TokenProcess Identifier]", - Tags = { - ["Action"] = "Withdraw", - ["Recipient"] = "[ADDRESS]", - ["Quantity"] = "100" - } -}) -``` - -# Token Example - -> NOTE: When implementing a token it is important to remember that all Tags on a message MUST be "string"s. Using the`tostring` function you can convert simple types to strings. - -```lua -if not balances then - balances = { [ao.id] = 100000000000000 } -end - -if name ~= "Fun Coin" then - name = "Fun Coin" -end - -if ticker ~= "Fun" then - ticker = "fun" -end - -if denomination ~= 6 then - denomination = 6 -end - --- handlers that handler incoming msg -Handlers.add( - "Transfer", - Handlers.utils.hasMatchingTag("Action", "Transfer"), - function (msg) - assert(type(msg.Tags.Recipient) == 'string', 'Recipient is required!') - assert(type(msg.Tags.Quantity) == 'string', 'Quantity is required!') - - if not balances[msg.From] then - balances[msg.From] = 0 - end - - if not balances[msg.Tags.Recipient] then - balances[msg.Tags.Recipient] = 0 - end - - local qty = tonumber(msg.Tags.Quantity) - assert(type(qty) == 'number', 'qty must be number') - -- handlers.utils.reply("Transferring qty")(msg) - if balances[msg.From] >= qty then - balances[msg.From] = balances[msg.From] - qty - balances[msg.Tags.Recipient] = balances[msg.Tags.Recipient] + qty - ao.send({ - Target = msg.From, - Tags = { - ["Action"] = "Debit-Notice", - ["Quantity"] = tostring(qty) - } - }) - ao.send({ - Target = msg.Tags.Recipient, - Tags = { - ["Action"] = "Credit-Notice", - ["Quantity"] = tostring(qty) - } - }) - -- if msg.Tags.Cast and msg.Tags.Cast == "true" then - -- return - -- end - - end - end -) - -Handlers.add( - "Balance", - Handlers.utils.hasMatchingTag("Action", "Balance"), - function (msg) - assert(type(msg.Tags.Target) == "string", "Target Tag is required!") - local bal = "0" - if balances[msg.Tags.Target] then - bal = tostring(balances[msg.Tags.Target]) - end - ao.send({ - Target = msg.From, - Tags = { - ["Balance"] = bal, - ["Ticker"] = ticker or "" - } - }) - end -) - -local json = require("json") - -Handlers.add( - "Balances", - Handlers.utils.hasMatchingTag("Action", "Balances"), - function (msg) - ao.send({ - Target = msg.From, - Data = json.encode(balances) - }) - end - -) - -Handlers.add( - "Info", - Handlers.utils.hasMatchingTag("Action", "Info"), - function (msg) - ao.send({ - Target = msg.From, - Tags = { - ["Name"] = name, - ["Ticker"] = ticker, - ["Denomination"] = tostring(denomination) - } - }) - end -) -``` - -## Meet Web Assembly -Source: https://cookbook_ao.arweave.net/references/wasm.html - -WebAssembly (often abbreviated as Wasm) is a modern binary instruction format providing a portable compilation target for high-level languages like C, C++, and Rust. It enables deployment on the web for client and server applications, offering a high level of performance and efficiency. WebAssembly is designed to maintain the security and sandboxing features of web browsers, making it a suitable choice for web-based applications. It's a key technology for web developers, allowing them to write code in multiple languages and compile it into bytecode that runs in the browser at near-native speed. - -The significance of WebAssembly lies in its ability to bridge the gap between web and native applications. It allows complex applications and games, previously limited to desktop environments, to run in the browser with comparable performance. This opens up new possibilities for web development, including the creation of high-performance web apps, games, and even the porting of existing desktop applications to the web. WebAssembly operates alongside JavaScript, complementing it by enabling performance-critical components to be written in languages better suited for such tasks, thereby enhancing the capabilities and performance of web applications. - -# RELEASE NOTES AND CHANGELOGS - - - -## AOS Release Notes v2.0.0 -Source: https://cookbook_ao.arweave.net/releasenotes/aos-2_0_0.html - -:wave: Hey Developers, we hear you, AOS needs a DX upgrade and this release delivers! - -## Install instructions for AOS 2.0.0 - -```shell -npm i -g https://get_ao.arweave.net -``` - -> Use `.update` to update earlier aos processes. See the **note** below on what features are not supported on earlier processes. - -Cool features: - -- Receive the `await` of aos -- REQ/RES semantics with References -- default actions for handlers. - -## `Receive()` the await of aos - -Meet `Lua Coroutines`, they are very similar to `await` or `generators`, coroutines are now added to aos handlers! - -> Coroutines are like taking turns playing a game with your friends. Each friend (coroutine) has a turn to play (do some work), but they don't finish all at once. Instead, they pause their turn (yield) so the next friend can play. When it's their turn again, they continue from where they left off (resume). - -This means you can send a message then `wait` using `Receive` method and when a message is send to your process that matches the pattern, you can get the result and resume your logic. - -Easier to show, than tell. - -```lua= -.editor -Send({Target = ao.id, Data = "Hello"}) -local res = Receive({Data = "Hello"}) -print(res.Data) -.done -``` - -The global Receive function yields until a msg is returned that matches that pattern, then it resumes executing the rest of the code. - -> NOTE: This feature is only available for AOS 2 processes, even if your process is upgraded to 2, coroutines can not be supported. - -## REQUEST/RESPONSE semantics with References - -Often times, you want to receive a reply from the process as a response to the specific message you sent. aos 2.0 makes this pattern intuitive and seamless. - -setup the server handler _notice the msg.reply_ - -```lua= -.editor -Handlers.add("Greeting-Name", { Action = "Greeting"}, function (msg) - msg.reply({Data = "Hello " .. msg.Data or "bob"}) - print('server: replied to ' .. msg.Data or "bob") -end) -.done -``` - -setup the client - -```lua= -.editor -local greeting = Send({Target = ao.id, Action = "Greeting", Data = "George"}).receive().Data -print("client: " .. greeting) -.done -``` - -output - -``` -server: replied to George -client: Hello George -``` - -When building complex workflows, developers need a request/response system that provides guarentees. ie returning message is that is directly referenced and handled. This works using built-in reference tags and using the `msg.reply` function on the server. - -try another example: - -```lua= -.editor -local greeting = Send({Target = ao.id, Action = "Greeting", Data = "Spongebob"}).receive().Data -print(greeting .. " Squarepants") -``` - -> NOTE: This feature is only available for AOS 2 processes, even if your process is upgraded to 2, coroutines can not be supported. - -## default Action Handlers - -Handlers are a core design component when creating aos processes, they give developers a powerful pipeline for managing messages. The `Action` tag has become the common tag name to describe the intent of the incoming message. Now you can just supply a `value` to the pattern argument and it will infer `{ Action = [value] }` as your pattern matcher for this handler. - -Before AOS 2.0 - -```lua -Handlers.add("Get-Balance", function (msg) return msg.Action == "Balance", doBalance) -``` - -After AOS 2.0 - -```lua -Handlers.add("Get-Balance", "Balance", doBalance) -``` - -> If your pattern matcher is matching on Action = "xxx", you can just supply the string - -## FYI Breaking Changes - -- Authority tags are required for all processes. Messages will not be trusted by default, any Spawn MUST supply Authority tags if they plan to receive messages from MUs. The new test MU is `fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY` -- Message Tag `Ref_` has been replaced for `Reference` - aos 2.0 process will always use the 'Reference' tag as a unique message counter. -- No more `result.Output.data.output`, aos processes always return a consistent `Output.data` shape: - -```lua -Output = { - data = String, - prompt = String, - print = Boolean -} -``` - -# Handlers version 0.0.5 - -Handlers increase the ability to manage messages, but the previous versions did not address complex logic flows between processes, in this version we leverage erlang style patterns to improve the handlers lua module to provide a powerful toolkit for developers to handle complex logic flows between their processes. - -## Handlers.once - -Handlers.once is like `Handlers.add` but for handling only one message. This function allows you to supply a pattern and handle function and the next time it is matched AOS will process this handler, then remove it from the `Handlers.list`. - -```lua -Handlers.once( - "onetime", - { Action = "Run-Once"}, - function (msg) - print("This handler will only run once!") - end -) -``` - -## MaxRuns - -Optional `MaxRuns` argument for each handler, letting you choose the number of runs before it removes itself. default is infinite. - -```lua -Handlers.add( - "example-handler", - { Action = "Example" }, - function(msg) - print("Handler executed") - end, - 3 -- MaxRuns is set to 3 -) -``` - -## \* Sending Messages .receive() - -> NOTE: This will only work with new AOS 2 processes not with upgraded processes. - -With `.receive` you can yield code execution, until a message is returned. The receive function takes an optional target? argument. - -## \* Sending Messages .onReply() - -`.onReply` is a function returned from a message function call, that enables developers to provide a callback function. This is an alternative strategy and can be useful if you have generic composable functions. - -```lua -Handlers.once( - { Test = "1" }, - function(m) - print("Got message! Replying...") - m.reply({ Test = "1-reply", Status = "Success" }) - end -) -``` - -```lua -function printMsg(prop) - return function (m) - print(m[prop]) - end -end - -Send({ - Target = target, - Test = "1" -}).onReply(printMsg('Test')) -``` - -## \* msg.forward(target, fwdMsg) - -REQUEST/RESPONSE is cool, but what about if I want to receive a message from C when I send a message to B and B sends a message to C. In this scenario or any other multi-forwarding scenario, we have a `msg.forward` function. The forward function takes a target and a partial message to overwrite any of the message you want to forward. - -example: - -this example requires three processes: - -lastname process - -```sh -aos lastname -``` - -```lua= -.editor -Handlers.add("Greeting", "Greeting", function (msg) - msg.forward(msg['X-Origin'], { Data = msg.Data .. " Squarepants"}) -end) -.done -``` - -greeting process - -```sh -aos greeting -``` - -```lua= -.editor -local lastname = "your lastname process id above" -Handlers.add("Greeting", "Greeting", function (msg) - msg.forward(lastname, { Data = "Hello " .. msg.Data }) -end) -.done -``` - -client process - -```sh -aos spongebob -``` - -```lua= -.editor -local Greeting = "your greeting process id" -local res = Send({Target = Greeting, Action = "Greeting", Data = "SpongeBob"}).receive("your lastname process id above") -print(res.Data) -.done -``` - -> The receive function can take a `target` process id to handle the target that will return the message. The `forward` and `receive` methods can be used to create `A -> B -> C -> A` message passing scenarios. - -## \* Message object enhancements: `.reply(newMsg)` and `.forward(target, newMsg)` - -All messages received by handlers now have .reply() and .forward() functions which allow the process to easily return a response to the user without having to manually deal with the X-Reference and Target values. This mechanism also allows the developer to easily build pipelines that process a request through many processes, then eventually return to the user. - -The reply method takes a partial message table. The forward function takes a target property and a partial message table. - -## Pattern Matchers and Resolvers - -The Handler functions takes four arguments, - -| Name | Type | Description | -| ------- | --------------------------- | ---------------------------------------------------------------------------------------------------------- | -| name | string | Handler Unique Identifier | -| pattern | string \| table \| function | the pattern lets the process pipeline know if it should invoke and break, or skip, or invoke and continue. | -| handle | function | a function that processes the message | -| MaxRuns | number? (optional) | the number of max runs before the handler is removed automatically. Only available using `Handlers.add()`. | - -### Pattern Matching - -More expressive and easy to use matches. As well as functions, handlers now supports: - -- Strings as match, checking against the Action tag. -- 'MessageMatchSpecs': Partially described messages. - -In this mode, each tag given in the 'spec' is checked against the value in the message. It allows you to: - -- Wildcard (`_`): Is the tag given at all? -- Function: Run a function against the tag value (optional second argument is the full message) -- String: Exact match -- String: Lua matching syntax - -```lua -Handlers.add("token.transfer", { - Action = "Transfer" - Quantity = "%d+", - Recipient = "_" - }, doTransfer) -``` - -### Resolvers - -Resolvers are tables in which each key is a pattern matching table and the value is a function that is executed based on the matching key. This allows developers to create case like statements in the resolver property. - -```lua -Handlers.add("foobarbaz", { Action = "Update" }, { - [{ Status = "foo" }] = function (msg) print("foo") end, - [{ Status = "bar" }] = function (msg) print("bar") end, - [{ Status = "baz" }] = function (msg) print("baz") end -}) -``` - -In this example, if a message with an Action of `Update` and the resolver looks at the `Status` tag on the message and executes the function based on the matching Status Value. - -## Using Receive with Spawn - -> NOTE: This will only work with new AOS 2 processes not with upgraded processes. - -When you spawn a message you get back a success message with an action of Spawned. - -```lua= -.editor -Spawn(ao.env.Module.Id, { }) -local m = Receive({ Action = "Spawned" }) -print(m['Process']) -.done -``` - -Or if you want to get Spawned by reference using .receive - -> NOTE: This will only work with new AOS 2 processes not with upgraded processes. - -```lua= -.editor -local msg = Spawn(ao.env.Module.Id, {}).receive() -print(msg.Process) -.done -``` - -# Updates - -## Assignment Checks - -With this update, it is important to update all AOS processes to add Assignment Check Handler, this handler will be prepended to your process and add whitelisted assignment protection for all of your processes. - -Just run `.update` on AOS Client Version 2.0.0 - -```lua -Handlers.prepend("Assignment-Check", function (msg) - return ao.isAssignment(msg) and not ao.isAssignable(msg) -end, function (msg) - Send({Target = msg.From, Data = "Assignment is not trusted by this process!"}) - print('Assignment is not trusted! From: ' .. msg.From .. ' - Owner: ' .. msg.Owner) -end) -``` - -## \* os.time - -`os.time` will now return the timestamp provided by the Message Assignment in the Scheduling Unit (SU). - -## CLI Updates - -External editor as a scratch pad - -``` -.pad -``` - -Toggle dryrun mode - -``` -.dryrun -``` - -Short cut for launching a sqlite module - -```sh -aos [name] --sqlite -``` - -Creates a new SQLite aos process - -## now you can [.delete] the previous line in the built in editor - -```lua -.editor - -local x = 1 -print(x) -.delete -``` - -The .delete command deletes the previous line and allows you to continue to edit. - -## PRs - -- Improved processid identification - https://github.com/permaweb/aos/pull/301 -- update: assignable package installer - https://github.com/permaweb/aos/pull/302 - -## Appendix - -"\*" - These features tagged with an "\*" are only available on new processes that were spawned with AOS Client Version 1.12.1 and AOS version 0.2.2. - -## Summary - -AOS 2 is a huge shift in DX, we are releasing as a Release Candidate to get feedback and refine the functionality and correct any bugs before we fully launch to general availability. - -## AOS Release Notes v2.0.1 -Source: https://cookbook_ao.arweave.net/releasenotes/aos-2_0_1.html - -## Install - -```sh -npm install -g https://get_ao.arweave.net -``` - -## Features - -- Bootloader -- Handlers.once (defaults to prepend mode) -- WeaveDrive with Attestors -- WeaveDrive L2 Headers -- Spawn module by name -- Graphql Modules -- msg.reply patch - -## Bootloader - -Bootloader enables users to include a script to evaluate when spawning a process. You can include this script either with the `Data` property or with a `txId` specified on the `On-Boot` Tag. - -### Examples - -via AOS Console using `data` - -```shell -echo "print('Hello Bootloader')" > example.lua -aos ex1 --tag-name On-Boot --tag-value Data --data example.lua -``` - -> As AOS boots up, you should see Hello Bootloader! - -``` -AOS Client Version: 2.0.1. 2024 -Type "Ctrl-C" twice to exit - -Your AOS process: uJvxYDk6Q1JvocgfajNbEcKmqoCDWEksjG6EH1o9xRo - -Hello Bootloader -``` - -via Spawn message using `data` - -```lua -Spawn(ao.env.Module.Id, { - ["On-Boot"] = "Data", - Data = [[ print("Hello World!") ]] -}) -``` - -via AOS Console using `txId` - -```shell -aos ex2 --tag-name On-Boot --tag-value 1VAPs_V6iVx-zxuMW7Ns0IrYqqk6LAEDAe1b-EqKP28 -``` - -via Spawn message using `txId` - -```lua -Spawn(ao.env.Module.Id, { - ["On-Boot"] = "1VAPs_V6iVx-zxuMW7Ns0IrYqqk6LAEDAe1b-EqKP28" -}) -``` - -## Hanlders.once (defaults to prepend mode) - -Now, when Handlers.once is called, it will default to prepend to the top of the Handlers stack. - -```lua -Handlers.once("Name", function (msg) - -- do something -end) - --- is the same as - -Handlers.prepend("Name", "Name", function (msg) - -- do something -end, 1) - -``` - -## WeaveDrive with Attestors - -Using WeaveDrive to access dataitems from Arweave with Attestations. When you spawn a process you can provide one or more `Attestor` tags with arweave wallet addresses as value. Then the arweave wallets set as attestors can create `Attestation` dataItems that authorize access to a specific arweave dataitem using weavedrive. - -Here is a short guide on how to use WeaveDrive with Attestors - https://hackmd.io/@ao-docs/r1bixxO-Je - -## WeaveDrive L2 Headers - -Now, weaveDrive users can get L2 dataItem headers using `drive.getDataItem(id)` from the WeaveDrive apm module. This features allows indexers to index L2 dataItems and processes like stamps2 to determine if a user is stamping an Atomic Asset. The result is more interoperability with Arweave. - -```lua -.load-blueprint apm -apm.install('@rakis/WeaveDrive') -local drive = require('@rakis/WeaveDrive') -local metaData = drive.getDataItem('K1jD3xrCJV3UnRtnBuQdd7k8HCwh9TX9GS-kh_Oevvw') -``` - -## Spawn module by name - -Spawn module by name or identifier: - -```sh -aos gql --module aos-graphql-sqlite-sm -``` - -Create a graphql/sqlite process by using the module name. - -## Graphql Modules - -You can now build graphql processes using the graphql custom module: - -https://github.com/TillaTheHun0/aos-graphql - -## `msg.reply` legacy patch - -This release provides a blueprint optional patch to allow for old processes to leverage the `msg.reply` function. - -`.load-blueprint patch-legacy-reply` - -A blueprint that creates a passthrough handler to attach `.reply` function to the `msg` table, for handlers downstream to leverage. - -This allows developers to take advantage of the `.receive` function in AOS 2.0 and interact with older AOS 0.x processes. With this patch AOS 0.x processes need to be able to reply with an `X-Reference` tag. So that the `.receive` co-routine can properly catch the response sent by the calling AOS 2.0 process. - -Then open an older process: - -```sh -aos [my aos process] -``` - -And run `.load-blueprint patch-legacy-reply` - -``` -.load-blueprint patch-legacy-reply -``` - -## Source - -You can review the blueprint source here: - -https://github.com/permaweb/aos/blob/main/blueprints/patch-legacy-reply.lua - -```lua --- patch reply -local function patchReply(msg) - if not msg.reply then - msg.reply = function (replyMsg) - replyMsg.Target = msg["Reply-To"] or (replyMsg.Target or msg.From) - replyMsg["X-Reference"] = msg["X-Reference"] or msg.Reference or "" - replyMsg["X-Origin"] = msg["X-Origin"] or "" - - return ao.send(replyMsg) - end - end -end - -Handlers.prepend("_patch_reply", function (msg) return "continue" end, patchReply) - -``` - ---- - -Fixes: - -- bubble up errors during co-routine resume functions - https://github.com/permaweb/aos/pull/374 -- update token.lua to check for .reply before using the replay method -- staking blueprint improvement to default unstake delay block wait, and prepend finalize handler. -- fixed bug with Handlers.remove - https://github.com/permaweb/aos/pull/366 - -## AOS Release Notes v2.0.2 -Source: https://cookbook_ao.arweave.net/releasenotes/aos-2_0_2.html - -## Install - -```sh -npm install -g https://get_ao.arweave.net -``` - -## Core Features - -- **Improved Spawn Process Times**: This release improves the process creation times for testnet. When you create new `aos` processes, it should now take only a few seconds to spawn. - -## Fixes - -- Issue [#388](https://github.com/permaweb/aos/pull/388): fix(services/version): prevent checkForUpdate() 5xx response codes from stopping connection -- Issue [#392](https://github.com/permaweb/aos/pull/392): Add Action Tag to broadcasted messages in Chatroom Blueprint -- Issue [#391](https://github.com/permaweb/aos/pull/391): feat(aos): if multiple processes have the same name, allow user to select which process to run -- Issue [#390](https://github.com/permaweb/aos/pull/390): fix(aos): fix error lines base cases, loading -- Issue [#386](https://github.com/permaweb/aos/pull/386): fix(aos): get blueprints now uses dir -- Issue [#337](https://github.com/permaweb/aos/issues/337): matchesspec does not work with from-process - -## Release Notes -Source: https://cookbook_ao.arweave.net/releasenotes/index.html - -This section provides detailed information about updates, new features, bug fixes, and changes in each release of AO and its related tools. Release notes are essential for understanding what's changed between versions and how these changes might affect your projects. - -## AOS Releases - -AOS is the operating system built on top of the AO computer. These release notes document changes and improvements to AOS: - -- [AOS 2.0.2](aos-2_0_2) - Improved spawn process times and various bug fixes -- [AOS 2.0.1](aos-2_0_1) - Details about patch updates and fixes in the 2.0.1 release -- [AOS 2.0.0](aos-2_0_0) - Major release information, including new features and significant changes - -## Why Read Release Notes? - -Release notes provide valuable information for developers: - -- Learn about new features that could enhance your applications -- Understand potential breaking changes that might affect existing code -- Discover bug fixes that resolve issues you may have encountered -- Stay informed about security updates and best practices - -We recommend reviewing release notes before upgrading to a new version to ensure a smooth transition. - -## Navigation - -Use the sidebar to navigate between different release notes. Notes are organized chronologically with the most recent releases first. - -# Summary - -Total files processed: 18 diff --git a/src/public/llms.txt b/src/public/llms.txt deleted file mode 100644 index 7ab03bc3..00000000 --- a/src/public/llms.txt +++ /dev/null @@ -1,652 +0,0 @@ -# EN Documentation for LLMs - -Generated: 2025-09-10T20:06:33.599Z - -This file contains structured reference documentation, release notes, and a comprehensive directory of all documentation pages. - -# Documentation Directory - -## Concepts - -- [A whistle stop tour of Lua.](https://cookbook_ao.arweave.net/concepts/lua.html) -- [ao Specs](https://cookbook_ao.arweave.net/concepts/specs.html) -- [aos Brief Tour](https://cookbook_ao.arweave.net/concepts/tour.html) -- [Concepts](https://cookbook_ao.arweave.net/concepts/index.html) -- [Eval](https://cookbook_ao.arweave.net/concepts/eval.html) -- [Holographic State](https://cookbook_ao.arweave.net/concepts/holographic-state.html) -- [How ao messaging works](https://cookbook_ao.arweave.net/concepts/how-it-works.html) -- [Messages](https://cookbook_ao.arweave.net/concepts/messages.html) -- [Processes](https://cookbook_ao.arweave.net/concepts/processes.html) -- [Units](https://cookbook_ao.arweave.net/concepts/units.html) - -## Guides - -### Aoconnect - -- [aoconnect](https://cookbook_ao.arweave.net/guides/aoconnect/aoconnect.html) -- [Calling DryRun](https://cookbook_ao.arweave.net/guides/aoconnect/calling-dryrun.html) -- [Connecting to specific ao nodes](https://cookbook_ao.arweave.net/guides/aoconnect/connecting.html) -- [DataItem Signers](https://cookbook_ao.arweave.net/guides/aoconnect/signers.html) -- [Installing ao connect](https://cookbook_ao.arweave.net/guides/aoconnect/installing-connect.html) -- [Monitoring Cron](https://cookbook_ao.arweave.net/guides/aoconnect/monitoring-cron.html) -- [Reading results from an ao Process](https://cookbook_ao.arweave.net/guides/aoconnect/reading-results.html) -- [Sending a Message to a Process](https://cookbook_ao.arweave.net/guides/aoconnect/sending-messages.html) -- [Sending an Assignment to a Process](https://cookbook_ao.arweave.net/guides/aoconnect/assign-data.html) -- [Spawning a Process](https://cookbook_ao.arweave.net/guides/aoconnect/spawning-processes.html) - -### Aos - -#### Blueprints - -- [Blueprints](https://cookbook_ao.arweave.net/guides/aos/blueprints/index.html) -- [Chatroom Blueprint](https://cookbook_ao.arweave.net/guides/aos/blueprints/chatroom.html) -- [CRED Utils Blueprint](https://cookbook_ao.arweave.net/guides/aos/blueprints/cred-utils.html) -- [Staking Blueprint](https://cookbook_ao.arweave.net/guides/aos/blueprints/staking.html) -- [Token Blueprint](https://cookbook_ao.arweave.net/guides/aos/blueprints/token.html) -- [Voting Blueprint](https://cookbook_ao.arweave.net/guides/aos/blueprints/voting.html) - -#### Modules - -- [ao](https://cookbook_ao.arweave.net/guides/aos/modules/ao.html) -- [Base64](https://cookbook_ao.arweave.net/guides/aos/modules/base64.html) -- [crypto](https://cookbook_ao.arweave.net/guides/aos/modules/crypto.html) -- [JSON](https://cookbook_ao.arweave.net/guides/aos/modules/json.html) -- [Modules](https://cookbook_ao.arweave.net/guides/aos/modules/index.html) -- [Pretty](https://cookbook_ao.arweave.net/guides/aos/modules/pretty.html) -- [Utils](https://cookbook_ao.arweave.net/guides/aos/modules/utils.html) - -- [aos: AO Operating System](https://cookbook_ao.arweave.net/guides/aos/index.html) -- [Building a Token in `ao`](https://cookbook_ao.arweave.net/guides/aos/token.html) -- [CLI](https://cookbook_ao.arweave.net/guides/aos/cli.html) -- [Creating a Pingpong Process in aos](https://cookbook_ao.arweave.net/guides/aos/pingpong.html) -- [Customizing the Prompt in aos](https://cookbook_ao.arweave.net/guides/aos/prompt.html) -- [Editor setup](https://cookbook_ao.arweave.net/guides/aos/editor.html) -- [FAQ](https://cookbook_ao.arweave.net/guides/aos/faq.html) -- [Installing aos](https://cookbook_ao.arweave.net/guides/aos/installing.html) -- [Introduction](https://cookbook_ao.arweave.net/guides/aos/intro.html) -- [Load Lua Files with `.load `](https://cookbook_ao.arweave.net/guides/aos/load.html) -- [Troubleshooting using ao.link](https://cookbook_ao.arweave.net/guides/aos/troubleshooting.html) -- [Understanding the Inbox](https://cookbook_ao.arweave.net/guides/aos/inbox-and-handlers.html) - -### Dev cli - -- [AO Dev-Cli 0.1](https://cookbook_ao.arweave.net/guides/dev-cli/index.html) - -### Migrating to hyperbeam - -- [Connecting to HyperBEAM with `aos`](https://cookbook_ao.arweave.net/guides/migrating-to-hyperbeam/aos-with-hyperbeam.html) -- [Exposing Process State to HyperBEAM](https://cookbook_ao.arweave.net/guides/migrating-to-hyperbeam/exposing-process-state.html) -- [HyperBEAM from AO Connect](https://cookbook_ao.arweave.net/guides/migrating-to-hyperbeam/ao-connect.html) -- [Reading Dynamic State](https://cookbook_ao.arweave.net/guides/migrating-to-hyperbeam/reading-dynamic-state.html) -- [Why Migrate to HyperBEAM?](https://cookbook_ao.arweave.net/guides/migrating-to-hyperbeam/why-migrate.html) - -### Snacks - -#### 0rbit - -- [0rbit 💫](https://cookbook_ao.arweave.net/guides/snacks/0rbit/index.html) -- [First GET Request](https://cookbook_ao.arweave.net/guides/snacks/0rbit/get-request.html) -- [First POST Request](https://cookbook_ao.arweave.net/guides/snacks/0rbit/post-request.html) - -- [Getting started with SQLite](https://cookbook_ao.arweave.net/guides/snacks/sqlite.html) -- [Using WeaveDrive](https://cookbook_ao.arweave.net/guides/snacks/weavedrive.html) - -- [Guides](https://cookbook_ao.arweave.net/guides/index.html) - -## References - -### Betteridea - -- [BetterIDEa](https://cookbook_ao.arweave.net/references/betteridea/index.html) - -- [Accessing Data from Arweave with ao](https://cookbook_ao.arweave.net/references/data.html) -- [ao Module](https://cookbook_ao.arweave.net/references/ao.html) -- [ao Token and Subledger Specification](https://cookbook_ao.arweave.net/references/token.html) -- [Community Resources](https://cookbook_ao.arweave.net/references/community.html) -- [Cron Messages](https://cookbook_ao.arweave.net/references/cron.html) -- [Editor setup](https://cookbook_ao.arweave.net/references/editor-setup.html) -- [Glossary](https://cookbook_ao.arweave.net/references/glossary.html) -- [Handlers (Version 0.0.5)](https://cookbook_ao.arweave.net/references/handlers.html) -- [Lua Optimization Guide for AO Platform](https://cookbook_ao.arweave.net/references/lua-optimization.html) -- [Meet Lua](https://cookbook_ao.arweave.net/references/lua.html) -- [Meet Web Assembly](https://cookbook_ao.arweave.net/references/wasm.html) -- [Messaging Patterns in ao](https://cookbook_ao.arweave.net/references/messaging.html) -- [References](https://cookbook_ao.arweave.net/references/index.html) - -## Releasenotes - -- [AOS Release Notes v2.0.0](https://cookbook_ao.arweave.net/releasenotes/aos-2_0_0.html) -- [AOS Release Notes v2.0.1](https://cookbook_ao.arweave.net/releasenotes/aos-2_0_1.html) -- [AOS Release Notes v2.0.2](https://cookbook_ao.arweave.net/releasenotes/aos-2_0_2.html) -- [Release Notes](https://cookbook_ao.arweave.net/releasenotes/index.html) - -## Tutorials - -### Begin - -- [Begin: An Interactive Tutorial](https://cookbook_ao.arweave.net/tutorials/begin/index.html) -- [Building a Chatroom in aos](https://cookbook_ao.arweave.net/tutorials/begin/chatroom.html) -- [Crafting a Token](https://cookbook_ao.arweave.net/tutorials/begin/token.html) -- [DAO Guide](https://cookbook_ao.arweave.net/tutorials/begin/dao.html) -- [Enter `The Construct` - An Interactive Tutorial](https://cookbook_ao.arweave.net/tutorials/begin/rabbithole.html) -- [Messaging in `ao`](https://cookbook_ao.arweave.net/tutorials/begin/messaging.html) -- [Preparations](https://cookbook_ao.arweave.net/tutorials/begin/preparations.html) -- [Tokengating the Chatroom](https://cookbook_ao.arweave.net/tutorials/begin/tokengating.html) - -### Bots and games - -- [Automated Responses](https://cookbook_ao.arweave.net/tutorials/bots-and-games/attacking.html) -- [Bots and Games](https://cookbook_ao.arweave.net/tutorials/bots-and-games/index.html) -- [Bringing it Together](https://cookbook_ao.arweave.net/tutorials/bots-and-games/bringing-together.html) -- [Expanding the Arena](https://cookbook_ao.arweave.net/tutorials/bots-and-games/build-game.html) -- [Fetching Game State](https://cookbook_ao.arweave.net/tutorials/bots-and-games/game-state.html) -- [Interpreting Announcements](https://cookbook_ao.arweave.net/tutorials/bots-and-games/announcements.html) -- [Let's Play A Game!](https://cookbook_ao.arweave.net/tutorials/bots-and-games/ao-effect.html) -- [Mechanics of the Arena](https://cookbook_ao.arweave.net/tutorials/bots-and-games/arena-mechanics.html) -- [Strategic Decisions](https://cookbook_ao.arweave.net/tutorials/bots-and-games/decisions.html) - -- [Tutorials](https://cookbook_ao.arweave.net/tutorials/index.html) - -## Welcome - -### Legacynet info - -- [Legacynet → HyperBEAM](https://cookbook_ao.arweave.net/welcome/legacynet-info/index.html) -- [Quests FAQ](https://cookbook_ao.arweave.net/welcome/legacynet-info/quests.html) - -- [AO Processes](https://cookbook_ao.arweave.net/welcome/ao-processes.html) -- [Get started in 5 minutes](https://cookbook_ao.arweave.net/welcome/getting-started.html) -- [Introduction to AO-Core](https://cookbook_ao.arweave.net/welcome/ao-core-introduction.html) -- [Welcome to ao](https://cookbook_ao.arweave.net/welcome/index.html) - -- [https://vitepress.dev/reference/default-theme-home-page](https://cookbook_ao.arweave.net/index.html) -- [LLMs Documentation](https://cookbook_ao.arweave.net/llms-explanation.html) - - - -# Detailed Content - -## TABLE OF CONTENTS - -- API AND FUNCTION REFERENCES - - ao Module - - BetterIDEa - - Community Resources - - Cron Messages - - Accessing Data from Arweave with ao - - Editor setup - - glossary - - Handlers (Version 0.0.5) - - References - - Lua Optimization Guide for AO Platform - - Meet Lua - - Messaging Patterns in ao - - ao Token and Subledger Specification - - Meet Web Assembly -- RELEASE NOTES AND CHANGELOGS - - AOS Release Notes v2.0.0 - - AOS Release Notes v2.0.1 - - AOS Release Notes v2.0.2 - - Release Notes - - - -## API AND FUNCTION REFERENCES - - - -### ao Module -Source: https://cookbook_ao.arweave.net/references/ao.html - -### API Definitions -- Properties -- Environment -- Example -- Methods -- `ao.send -- Example -- `ao.spawn -- Example -- `ao.assign -- Example -- `ao.result -- Example -- `ao.isAssignable -- Example -- `ao.isAssignment -- Example -- `ao.addAssignable -- Example -- `ao.removeAssignable -- Example -- `ao.isTrusted -- Example -- Custom -- Tags -- Message -- Spawn -- Assignment -- Result - -### Code Examples -``` -## Methods - -### `ao.send(msg: Message)` - -Takes a [Message](#message) as input. The function adds `ao`-specific tags and stores the message in `ao.outbox.Messages`. - -#### Example -``` - -``` -### `ao.spawn(module: string, spawn: Spawn)` - -Takes a module ID string and [Spawn](#spawn) as input. Returns a Spawn table with a generated `Ref_` tag. - -#### Example -``` - -``` -### `ao.assign(assignment: Assignment)` - -Takes an [Assignment](#assignment) as input. Adds the assignment to `ao.outbox.Assignments`. - -#### Example -``` - - -### Parameters -| -| ------------------ | ------------------------------------------------------------------------------------------------------------ | -------- | -| id | Process Identifier (TxID) | string | -| \_module | Module Identifier (TxID) | string | -| authorities | Set of Trusted TXs | string | -| Authority | Identifiers that the process is able to accept transactions from that are not the owner or the process (0-n) | string | -| \_version | The version of the library | string | -| reference | Reference number of the process | number | -| env | Evaluation Environment | object | -| outbox | Holds Messages and Spawns for response | object | -| assignables | List of assignables of the process | list | -| nonExtractableTags | List of non-extractable tags of the process | list | -| nonForwardableTags | List of non-forwardable tags of the process | list | -| init | Initializes the AO environment | function | -| send | Sends a message to a target process | function | -| assign | Assigns a message to the process | function | -| spawn | Spawns a process | function | -| result | Returns the result of a message | function | -| isTrusted | Checks if a message is trusted | function | -| isAssignment | Checks if a message is an assignment | function | -| isAssignable | Checks if a message is assignable | function | -| addAssignable | Adds an assignable to the assignables list | function | -| removeAssignable | Removes an assignable from the assignables list | function | -| clearOutbox | Clears the outbox | function | -| normalize | Normalizes a message by extracting tags | function | -| sanitize | Sanitizes a message by removing non-forwardable tags | function | -| clone | Clones a table recursively | function | - - - -### BetterIDEa -Source: https://cookbook_ao.arweave.net/references/betteridea/index.html - -[BetterIDEa](https://ide.betteridea.dev) is a custom web based IDE for developing on ao. - -### Community Resources -Source: https://cookbook_ao.arweave.net/references/community.html - -### API Definitions -- Core -- Developer -- Contributing - - -### Cron Messages -Source: https://cookbook_ao.arweave.net/references/cron.html - -### API Definitions -- Setting -- Handling - - -### Accessing Data from Arweave with ao -Source: https://cookbook_ao.arweave.net/references/data.html - -### API Definitions -- Defining -- Assignment -- Using -- Using -- Working -- Using -- Using -- Complete -- Practical -- Example -- Example -- Important -- Proper -- Why - -### Code Examples -``` -> **Note:** When using [`.load`](../guides/aos/load.md#load-lua-files-with-load-filename), the script pauses at `Receive` until data arrives. When running commands separately in the shell, each command executes independently. - -### Using Handlers - -For persistent processing, set up a handler: -``` - - - -### Editor setup -Source: https://cookbook_ao.arweave.net/references/editor-setup.html - -### API Definitions -- VS -- Other -- BetterIDEa - - -### glossary -Source: https://cookbook_ao.arweave.net/references/glossary.html - - - -### Handlers (Version 0.0.5) -Source: https://cookbook_ao.arweave.net/references/handlers.html - -### API Definitions -- Overview -- Concepts -- Handler -- Pattern -- Basic -- Common -- Default -- Resolvers -- Module -- Common -- Functions -- `Handlers.add -- `Handlers.append -- `Handlers.once -- `Handlers.prepend -- `Handlers.before -- `Handlers.after -- `Handlers.remove -- Handler -- Execution -- Pattern -- Practical -- Handlers.utils -- `Handlers.utils.hasMatchingData -- `Handlers.utils.hasMatchingTag -- `Handlers.utils.reply -- Example -- Pattern -- Resolver -- Function - -### Code Examples -``` -### Default Action Handlers (AOS 2.0+) - -AOS 2.0 introduces simplified syntax for Action-based handlers. Instead of writing explicit pattern functions, you can use these shorthand forms: -``` - -``` -### `Handlers.utils.reply(text: string)` - -- This helper is a simple handle function, it basically places the text value in to the `Data` property of the outbound message. -``` - - -### Parameters -| -| -------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | `string` | The identifier of the handler item in the handlers list. | -| `pattern` | `table` or `function` | Specifies how to match messages. As a table, defines required message tags with string values (e.g. `{ Action = "Balance", Recipient = "_" }` requires an "Action" tag with string value "Balance" and any string "Recipient" tag value). As a function, takes a message DataItem and returns: "true" (invoke handler and exit pipeline), "false" (skip handler), or "continue" (invoke handler and continue pipeline). | -| `handler` | (Resolver) `table` or `function` | Either a resolver table containing pattern-function pairs for conditional execution, or a single function that processes the message. When using a resolver table, each key is a pattern matching table and its value is the function to execute when that pattern matches. When using a function, it takes the message DataItem as an argument and executes business logic. | -| `maxRuns` (optional) | number | As of 0.0.5, each handler function takes an optional function to define the amount of times the handler should match before it is removed. The default is infinity. | - - - -### References -Source: https://cookbook_ao.arweave.net/references/index.html - -### API Definitions -- Programming -- AO -- Development -- Community -- Navigation - - -### Lua Optimization Guide for AO Platform -Source: https://cookbook_ao.arweave.net/references/lua-optimization.html - -### API Definitions -- Table -- Appending -- Removing -- Variable -- Local -- Upvalues -- String -- String -- Pattern -- Memory -- Table -- Minimize -- Blockchain -- State -- Additional - - -### Meet Lua -Source: https://cookbook_ao.arweave.net/references/lua.html - -### API Definitions -- Understanding -- Setting -- Basic -- Hands -- Resources -- Best -- Conclusion - - -### Messaging Patterns in ao -Source: https://cookbook_ao.arweave.net/references/messaging.html - -### API Definitions -- Quick -- Sending -- `ao.send` -- `msg.reply` -- `msg.forward` -- `Handlers.utils.reply` -- Receiving -- `Receive` -- `ao.send -- Message -- Blocking - -### Code Examples -``` -Client (A) → Service (B) - ↓ ↓ -Continues Processes - execution message -``` - -``` -### `Handlers.utils.reply`: Simple Reply Handler Creation - -Creates a handler function that automatically replies with a fixed response. A wrapper around [`msg.reply`](#msg-reply-asynchronous-response-sending) for common use cases. - -**Simple String Response Example:** -``` - - - -### ao Token and Subledger Specification -Source: https://cookbook_ao.arweave.net/references/token.html - -### API Definitions -- Spawning -- Messaging -- Balance -- Balances -- Transfer -- Get -- Mint -- Spawning -- `Credit -- Transfer -- Withdraw - -### Code Examples -``` -### Balances() - -- Returns the balance of all participants in the token. -``` - -``` -Recipients will infer from the `From-Process` tag of the message which tokens they have received. - -### Get-Info() -``` - -``` -### Mint() [optional] - -Implementing a `Mint` action gives the process a way of allowing valid participants to create new tokens. -``` - - -### Parameters -| -| -------- | ------------------------------------------------------------------------------------------------------ | ------------------ | -| Balance | get the balance of an identifier | :heavy_check_mark: | -| Balances | get a list of all ledger/account balances | :heavy_check_mark: | -| Transfer | send 1 or more units from the callers balance to one or move targets with the option to notify targets | :x: | -| Mint | if the ledger process is the root and you would like to increase token supply | :x: | - - -### Parameters -| -| ------------ | -------------------------------------------------------------------------------------------------------------------- | ------------------ | -| Name | The title of the token, as it should be displayed to users. | :heavy_check_mark: | -| Ticker | A suggested shortened name for the token, such that it can be referenced quickly. | :heavy_check_mark: | -| Logo | An image that applications may desire to show next to the token, in order to make it quickly visually identifiable. | :heavy_check_mark: | -| Denomination | The number of the token that should be treated as a single unit when quantities and balances are displayed to users. | :x: | - - -### Parameters -| -| ------------ | ------------------------------------------------------------------ | --------- | -| Source-Token | The `ID` of the top-most process that this subledger represents. | :x: | -| Parent-Token | The `ID` of the parent process that this subledger is attached to. | :x: | - - - -### Meet Web Assembly -Source: https://cookbook_ao.arweave.net/references/wasm.html - -WebAssembly (often abbreviated as Wasm) is a modern binary instruction format providing a portable compilation target for high-level languages like C, C++, and Rust. It enables deployment on the web for client and server applications, offering a high level of performance and efficiency. WebAssembly is designed to maintain the security and sandboxing features of web browsers, making it a suitable choice for web-based applications. It's a key technology for web developers, allowing them to write code in multiple languages and compile it into bytecode that runs in the browser at near-native speed. - -## RELEASE NOTES AND CHANGELOGS - - - -### AOS Release Notes v2.0.0 -Source: https://cookbook_ao.arweave.net/releasenotes/aos-2_0_0.html - -Version: 2.0.0 - -Changes: -- Receive the `await` of aos -- REQ/RES semantics with References -- default actions for handlers. -- Authority tags are required for all processes. Messages will not be trusted by default, any Spawn MUST supply Authority tags if they plan to receive messages from MUs. The new test MU is `fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY` -- Message Tag `Ref_` has been replaced for `Reference` - aos 2.0 process will always use the 'Reference' tag as a unique message counter. -- No more `result.Output.data.output`, aos processes always return a consistent `Output.data` shape: -- Strings as match, checking against the Action tag. -- 'MessageMatchSpecs': Partially described messages. -- Wildcard (`_`): Is the tag given at all? -- Function: Run a function against the tag value (optional second argument is the full message) -- String: Exact match -- String: Lua matching syntax -- Improved processid identification - https://github.com/permaweb/aos/pull/301 -- update: assignable package installer - https://github.com/permaweb/aos/pull/302 - - -### AOS Release Notes v2.0.1 -Source: https://cookbook_ao.arweave.net/releasenotes/aos-2_0_1.html - -Version: 2.0.1 - -Changes: -- Bootloader -- Handlers.once (defaults to prepend mode) -- WeaveDrive with Attestors -- WeaveDrive L2 Headers -- Spawn module by name -- Graphql Modules -- msg.reply patch -- bubble up errors during co-routine resume functions - https://github.com/permaweb/aos/pull/374 -- update token.lua to check for .reply before using the replay method -- staking blueprint improvement to default unstake delay block wait, and prepend finalize handler. -- fixed bug with Handlers.remove - https://github.com/permaweb/aos/pull/366 - - -### AOS Release Notes v2.0.2 -Source: https://cookbook_ao.arweave.net/releasenotes/aos-2_0_2.html - -Version: 2.0.2 - -Changes: -- **Improved Spawn Process Times**: This release improves the process creation times for testnet. When you create new `aos` processes, it should now take only a few seconds to spawn. -- Issue [#388](https://github.com/permaweb/aos/pull/388): fix(services/version): prevent checkForUpdate() 5xx response codes from stopping connection -- Issue [#392](https://github.com/permaweb/aos/pull/392): Add Action Tag to broadcasted messages in Chatroom Blueprint -- Issue [#391](https://github.com/permaweb/aos/pull/391): feat(aos): if multiple processes have the same name, allow user to select which process to run -- Issue [#390](https://github.com/permaweb/aos/pull/390): fix(aos): fix error lines base cases, loading -- Issue [#386](https://github.com/permaweb/aos/pull/386): fix(aos): get blueprints now uses dir -- Issue [#337](https://github.com/permaweb/aos/issues/337): matchesspec does not work with from-process - - -### Release Notes -Source: https://cookbook_ao.arweave.net/releasenotes/index.html - -Changes: -- [AOS 2.0.2](aos-2_0_2) - Improved spawn process times and various bug fixes -- [AOS 2.0.1](aos-2_0_1) - Details about patch updates and fixes in the 2.0.1 release -- [AOS 2.0.0](aos-2_0_0) - Major release information, including new features and significant changes -- Learn about new features that could enhance your applications -- Understand potential breaking changes that might affect existing code -- Discover bug fixes that resolve issues you may have encountered -- Stay informed about security updates and best practices - - -# Summary - -Total files processed: 18 -Total documentation pages: 101 -This documentation is focused on technical references and release notes, prioritizing accuracy and relevance for LLM processing. diff --git a/src/public/zh/llms-full.txt b/src/public/zh/llms-full.txt deleted file mode 100644 index 51564f0a..00000000 --- a/src/public/zh/llms-full.txt +++ /dev/null @@ -1,875 +0,0 @@ -# ZH Technical Documentation - -Generated: 2025-09-10T20:06:33.625Z - -This file contains technical reference documentation and release notes. - - - -# API AND FUNCTION REFERENCES - - - -## ao 模块 -Source: https://cookbook_ao.arweave.net/zh/references/ao.html - -版本: 0.0.3 - -`ao` 进程通信通过消息进行处理,每个进程用 ANS-104 DataItems 的格式接收消息,并且需要能够执行以下常见操作。 - -- isTrusted(msg) - 检查消息是否可信 -- send(msg) - 将消息发给另一个进程 -- spawn(module, msg) - 创建一个进程 - -这个 library 为 `ao` 开发者工具包提供了这些核心功能。开发者可以按需使用这个 library,但它是默认集成在开发者工具包里的。 - -## 属性 - -| 名称 | 描述 | 类型 | -| ----------- | -------------------------------- | ------ | -| id | 进程标识符 (TXID) | string | -| \_module | 模块标识符 (TXID) | string | -| authorities | 可信任的交易集合 | string | -| \_version | library 的版本 | string | -| env | 交易评估环境 | string | -| outbox | 传出消息和生成新进程请求的发件箱 | object | - -## 方法 - -### send(msg: Message\
) : Message\
- -send 方法接收一个完整的 Message 对象,或者包含部分属性的 Message 对象作为参数。它会在这个对象上另外添加特定的 `ao` 标签,并返回一个完整的消息对象,同时将它插入到 ao.outbox.Messages 的表中。 - -**传入参数** - -- msg - -Schema - -```json -{ - "type": "object", - "properties": { - "Target": { - "type": "string", - "description": "Process/Wallet to send message to" - }, - "Data": { - "type": "any", - "description": "data to send in message DataItem" - }, - "Tags": { - "type": "object or array" - "description": "This property can be an array of name,value objects or an object" - } - } -} -``` - -例子 1 - -```lua -local message = ao.send({ - Target = msg.From, - Data = "ping", - Tags = { - { - name = "Content-Type", - value = "text/plain" - } - } -}) -``` - -例子 2 - -```lua -local message = ao.send({ - Target = msg.From, - Data = "ping", - Tags = { - "Content-Type" = "text/plain" - } -}) -``` - -**返回值** - -Schema - -```json -{ - "type": "object", - "properties": { - "Target": { - "type": "string" - }, - "Data": { - "type": "any" - }, - "Tags": { - "type": "array" - "description": "name/value array", - "items": { - "type": "object", - "properties": { - "name": {"type": "string"}, - "value":{"type":"string"} - } - } - } - } -} -``` - -### spawn(module : string, spawn : Spawn\
) : Spawn\
- -`spawn` 方法接收一个 TXID 模块作为第一个参数,以及一个完整的 Spawn 表,或者包含部分属性的 Spawn 表作为第二个参数。结果将返回一个完整的 Spawn 表。spawn 方法还会生成一个带有唯一引用标识符的 `Ref_` 标签。 - -**传入参数** - -| 名称 | 描述 | 类型 | -| ------ | ------------------------------------------------- | ------ | -| module | TXID 是一个模块二进制文件的标识符,用于实例化进程 | string | -| spawn | 包含完整或部分 `Data` 和 `Tags` 属性的 `spawn` 表 | table | - -Schema - -module - -```json -{ - "type": "string" -} -``` - -spawn - -```json -{ - "type": "object", - "properties": { - "Data": { "type": "any" }, - "Tags": { - "type": "object or array", - "description": "can be either array, or object" - } - } -} -``` - -**返回值** - -Schema - -```json -{ - "type": "object", - "properties": { - "Data": { "type": "any" }, - "Tags": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { "type": "string" }, - "value": { "type": "string" } - } - } - } - } -} -``` - -### isTrusted(msg : Message\
) : boolean - -在生成进程时,可以提供 0 个或多个 Authority 标签,ao library 会将这些值添加到 `ao` 属性中名为 `authorities` 的 table 数组中。这个数组为 ao.TN.1 提供了“权威证明”(Proof of Authority)功能。当消息到达 `handle` 方法时,开发者可以调用 `ao.isTrusted` 来验证消息是否来自可信来源。 - -**传入参数** - -| 名称 | 描述 | 类型 | -| ---- | ---------------------------------- | ----- | -| msg | 用于检测这个进程是否可信的 Message | table | - -Schema - -```json -{ - "type": "object", - "properties": { - "Target": { - "type": "string" - }, - "Data": { - "type": "any" - }, - "Tags": { - "type": "array" - "description": "name/value array", - "items": { - "type": "object", - "properties": { - "name": {"type": "string"}, - "value":{"type":"string"} - } - } - } - } -} -``` - -## 社区 -Source: https://cookbook_ao.arweave.net/zh/references/community.html - -[Autonomous Finance](https://www.autonomous.finance/) - -- Autonomous Finance 是一个专注于 ao 网络内金融基础设施复杂性的研究和技术实体。 - -[BetterIdea](https://betteridea.dev/) - -- 使用 BetterIDEa 构建更快、更智能、更高效的 AO 开发终极本地 Web IDE。 - -[Orbit](https://www.0rbit.co/) - -- 0rbit 通过利用 ao 和 0rbit 节点的强大功能,将任何来自网络的数据提供给 ao 进程。用户向 0rbit ao 发送消息,0rbit 节点获取数据,然后用户进程接收数据。 - -## 定时消息(Cron Messages) -Source: https://cookbook_ao.arweave.net/zh/references/cron.html - -ao 具有在指定时间间隔生成消息的能力,这个时间间隔可以是秒、分钟、小时或区块。有一个监控进程会自动解释和运行(eval)这些消息,然后通知 Process 根据时间处理(eval)这些消息。此时会产生一个实时进程,它可以与完整的 ao 网络或外部网络中的预言机进行通信。 - -## 在进程中设置定时消息(Cron Messages) - -创建这些定时消息(Cron Messages)的最简单方法,是在 aos 控制台中生成一个新进程并定义时间间隔。 - -```sh -aos [myProcess] --cron 5-minutes -``` - -在生成新进程时,你可以在命令行中传递一个 cron 参数,后面加上你希望 cron 触发的时间间隔。如果你希望消息实时触发,你必须启动一个监控事件。在 aos 中,你只需调用`.monitor`,它会在 `mu` 上启动一个工作进程,从 `cu` 触发定时(cron) 消息。然后你的进程将会每隔 `x-间隔` 收到定时(cron)消息。 - -```lua -.monitor -``` - -如果你希望停止触发定时(cron) 消息,只需调用 `.unmonitor`,这会停止触发过程。但下次你发送消息时,生成的定时(cron) 消息仍将创建和处理进程。 - -## 处理定时消息 - -每条定时(cron) 消息都有一个值为 `Cron` 的 `Action` 标签。根据定义,[处理器](handlers.md)在每次收到定时(cron) 消息时,都会自动执行特定任务。 - -```lua -Handlers.add( - "CronTick", -- handler 的名称 - Handlers.utils.hasMatchingTag("Action", "Cron"), -- 识别定时(cron) 消息的 handler 匹配函数 - function () -- 需要定时执行的 handler 任务 - -- 要执行的内容 - end -) -``` - -定时消息(Cron Messages)是一个强大的实用工具,可以用来创建具有广泛功能的“自主代理”。 - -## 使用 ao 访问 Arweave 上的数据 -Source: https://cookbook_ao.arweave.net/zh/references/data.html - -在你的 ao 开发工作流程中,可能有时候你想要访问 arweave 上的数据。你的进程可以使用 ao 发送一条消息,然后 ao 网络会通过一个 Message 对象将数据提供给你的 Process 对象。 - -为了从 arweave 请求数据,你只需包含一个名为 `Load` 的 `Tag`,在该标签中,你可以使用数据的 TXID 来检索。 - -```lua - -Send({ - Target = ao.id, - Tags = { - Load = "WFM_Mi2FUNGCeP7r99XyeE3ySurt07LHxEGfW-wuIdY", - Action = "Data" - } -}) - -``` - -这条消息通过处理到达进程时,在传入消息的 `Data` 属性中,有一个 DataItem 的引用。同时,DataItem 的 `Data` 将以 base64 的类型传递。 - -```lua -{ - Owner = "[Owner Address]" - Target = "[Process Identifier]", - Data = { - Owner = "xDKpdiZ7H9n_SsdX_CMpkybMGIdin5AUciM00mQgxRE", - Tags = { - "Content-Type": "application/json" - }, - Data = "[base64]", - ... - } - ... -} - -``` - -在 lua 中,你可以使用 “.base64” 模块将你的数据从 base64 解码回原始格式。 - -```lua -local base64 = require(".base64") - - -local data = base64.decode(Msg.Data.Data) -``` - -## 为什么从 Arweave 上面取数据 - -你的进程可能需要访问数据来做决策,或者你可能想要通过 `data` 加载功能,为你的进程添加特性。 - -## 编辑器设置 -Source: https://cookbook_ao.arweave.net/zh/references/editor-setup.html - -内置的 ao 函数和实用工具不太好用。为了提升你的开发体验,建议你在你常用的文本编辑器中安装 [Lua Language Server](https://luals.github.io) 扩展插件,并添加 [ao插件](https://github.com/martonlederer/ao-definitions)。它们支持所有内置的 aos [模块](../guides/aos/index.md) 和 [全局变量](../guides/aos/intro#globals)。 - -## VS Code - -安装 [sumneko.lua](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) 扩展插件: - -1. 在扩展市场中搜索 sumneko 的 "Lua"。 -2. 下载并安装该扩展插件。 -3. 打开 VS Code 命令面板,使用 `Shift + Command + P`(Mac)/ `Ctrl + Shift + P`(Windows/Linux),然后运行以下命令: - -``` -> Lua: Open Addon Manager -``` - -4. 在插件管理器中搜索 “ao”,它应该是第一个结果。点击 “启用”,然后就可以享受自动完成的功能了! - -如果你不想为每个工作区重复这个过程,你可以从生成的工作区 `settings.json` 文件中复制 `Lua.workspace.library` 对象到你的全局 `settings.json` 文件中。 - -## 其他编辑器 - -1. 确认你的编辑器支持[语言服务器协议](https://microsoft.github.io/language-server-protocol/implementors/tools/)。 -2. 按照 [luals.github.io](https://luals.github.io/#install) 上的指示安装 Lua 语言服务器。 -3. 为语言服务器安装“ao”插件。 - -## Handlers (版本 0.0.3) -Source: https://cookbook_ao.arweave.net/zh/references/handlers.html - -## 概览 - -Handlers library 提供了一种灵活的方式来管理和执行一系列基于模式的 handler。每个 handler 由一个匹配函数、一个处理函数和一个名称组成。这个 library 适用于需要根据不同的输入条件采取不同行动的场景。 - -## 模块结构 - -- `Handlers._version`: 代表 Handlers library 版本的字符串。 -- `Handlers.list`: 存储注册的 handler 列表的表。 - -## 方法 - -### `Handlers.add(name, pattern, handler)` - -添加一个新的 handler 或者根据名称更新已有的 handler。 - -### `Handlers.append(name, pattern, handle)` - -在 handler 列表的末尾插入一个新的 handler。 - -#### 传入参数 - -- `pattern` (function 类型): 判断 handler 是否被执行的方法。 -- `handle` (function 类型): handler 方法的执行函数。 -- `name` (string 类型): handler 的唯一命名。 - -### `Handlers.prepend(name, pattern, handle)` - -把一个新的 handler 加到 handler 列表的开头. - -#### 传入参数 - -- 和 `handlers.append` 的一样。 - -### `Handlers.before(handleName)` - -返回一个对象,可以在特定的 handler 前加入一个新的 handler。 - -#### 传入参数 - -- `handleName` (string 类型): 在新的 handler 加入前,需要给 handler 的命名。 - -#### 返回值 - -- 一个拥有 `add` 方法的对象,可以插入新的 handler。 - -### `Handlers.after(handleName)` - -返回一个对象,可以在特定的 handler 后加入一个新的 handler。 - -#### 传入参数 - -- `handleName` (string 类型): 在新的 handler 加入后,需要给 handler 的命名。 - -#### 返回值 - -- 一个拥有 `add` 方法的对象,可以插入新的 handler。 - -### `Handlers.remove(name)` - -根据名称从 handler 列表里移除一个 handler。 - -#### 传入参数 - -- `name` (string 类型): 要被移除的 handler 的名称。 - -### `Handlers.evaluate(msg, env)` - -根据给定的消息和环境对每个 handler 进行评估。handler 按照它们在 handler 列表中出现的顺序依次调用。 - -#### 传入参数 - -- `msg` (table 类型): handler 要处理的消息。 -- `env` (table 类型): handler 执行的环境。 - -#### 返回值 - -- `response` (类型取决于 handler 是否匹配): handler 的响应。如果没有匹配的 handler,返回一个默认消息。 - -## 使用案例 - -```lua --- 定义模式和处理函数 -local function myPattern(msg) - -- 判断 handler 是否被执行 -end - -local function myHandle(msg, env, response) - -- Handler 逻辑 -end - --- 加一个新的 handler -Handlers.add("myHandler", myPattern, myHandle) - --- 评估一条消息 -local response = handlers.evaluate({ key = "value" }, { envKey = "envValue" }) -``` - -## 说明 - -- 根据 Handler 在 `handlers.list` 中的顺序执行 -- 匹配函数返回 `0` 代表跳过 handler,返回 `-1` 代表在 handler 执行后中断,或者返回 `1` 代表继续执行下一个 handler。 -- `evaluate` 方法可以从多个 handler 上连接响应。 - -## Handlers.utils - -Handlers.utils 模块提供了两个常见的匹配模式函数和一个常见的处理函数。 - -- hasMatchingData(data) -- hasMatchingTag(name, value) -- reply(txt) - -### Handlers.utils.hasMatchingData(data : string) - -这个辅助函数返回一个需要消息参数的函数,因此你可以将它放入任何 handler 的匹配参数中。该函数会将传入消息的数据与作为参数提供的字符串进行比较。 - -```lua -Handlers.add("ping", - Handlers.utils.hasMatchingData("ping"), - ... -) -``` - -如果这个进入进程的消息有设置成 ”ping" 的数据,那么这个 handler 会匹配上它,并调用处理函数。 - -### Handlers.hasMatchingTag(name : string, value : string) - -这个辅助函数返回一个需要消息参数的函数,因此你可以将它放入 Handlers 模块的任何匹配参数中。该函数会比较 Tag 的名称和数值,如果它们相等,则调用处理函数。 - -```lua -Handlers.add("ping", - Handlers.utils.hasMatchingData("ping"), - ... -) -``` - -### Handlers.reply(text : string) - -这个辅助函数是一个简单的处理函数,就是将 text 的值放入发送消息的 Data 属性中。 - -```lua -Handlers.add("ping", - Handlers.utils.hasMatchingData("ping"), - Handlers.utils.reply("pong") -) -``` - -## 参考 -Source: https://cookbook_ao.arweave.net/zh/references/index.html - -## 目录 - -- [Lua](lua) -- [Web Assembly](wasm) -- [ao 模块](ao) -- [Handlers](handlers) -- [代币](token) -- [加载 Arweave 数据](data) -- [定时消息](cron) -- [编辑器设置](editor-setup) - -## 认识 Lua -Source: https://cookbook_ao.arweave.net/zh/references/lua.html - -### 理解 Lua - -- **背景**: Lua 是一种轻量、高级、多范式的编程语言,主要用于嵌入式系统和客户端。它因效率、简洁和灵活性而闻名。 -- **核心特性**: Lua 提供了强大的数据描述构造、动态类型、高效的内存管理以及对面向对象编程的良好支持。 - -### 上手指南 - -1. **安装**: 访问 [Lua 的官方网站](http://www.lua.org/download.html) ,下载并安装 Lua。 -2. **环境**: 你可以使用简单的文本编辑器和命令行,或者像 ZeroBrane Studio ,或带有 Lua 插件的 Eclipse 这样的集成开发环境(IDE)。 - -### 基础语法和概念 (在 aos 中的) - -- **Hello World**: - ```lua - "Hello, World!" - ``` -- **变量和类型**: Lua 是动态类型的。基本类型包括 `nil`、`boolean`、`number`、`string`、`function`、`userdata`、`thread` 和 `table`。 -- **控制结构**: 包括 `if`、 `while`、 `repeat...until` 和 `for`。 -- **函数**: Lua 中的一等公民,支持闭包和高阶函数。 -- **Tables**: Lua 中唯一的数据结构机制,可用于表示数组、集合、记录等。 - -### 动手试试 - -- **用 Lua 的交互模式进行实验**: 在你的终端中运行 `aos` 并尝试 Lua 命令。 -- **写一些简单的脚本**: 创建 `.lua` 文件并使用 Lua 解释器运行它们。使用 `.load file.lua` 功能将 Lua 代码上传到你的 `aos` 进程中。 - -### 资源 - -- **官方文档**: [Lua 5.3 参考手册](https://www.lua.org/manual/5.3/) -- **在线教程**: 像 [Learn Lua](https://www.learn-lua.org/) 这样的网站非常适合进行交互式学习。 -- **书籍**: 《Lua 编程》是一本全面的资源。(第一版可在 [网上](http://www.lua.org/pil/contents.html) 获取) -- **社区**: 加入像 [Lua 用户](http://lua-users.org/) 这样的论坛或社区,以获取支持和讨论。 - -### 最佳实践 - -- **保持极简**: Lua 的设计是简单灵活的。你要在代码中拥抱这种哲学。 -- **性能**: 学习关于 Lua 的垃圾回收和高效利用 table 的知识。 -- **集成**: 考虑 Lua 如何嵌入到其他应用程序中,特别是 C/C++ 项目中。 - -### 总结 - -Lua 是一种强大的语言,尤其在嵌入式系统和游戏开发领域。它的简单性和高效性让它成为特定用例的首选。祝你在 Lua 编程之旅中获得愉快的体验! - -## ao Token 和子账本规范 -Source: https://cookbook_ao.arweave.net/zh/references/token.html - -**状态:** DRAFT-1 -**目标网络:** ao.TN.1 - -该规范描述了标准 ao Token 进程所必须的消息 handler 和函数。该标准提供用户控制和转移资产的能力,资产的稀缺性由进程维护。 - -每个符合标准的进程会实现一个余额账本,用来对进程代表的资产所有权进行编码。标准中提供了一系列函数进行账本修改,这些函数包含安全保护代码,保护 Token 所有权的稀缺性。 - -此外,该规范描述了一种名为 '子账本' 的进程类型。实现子账本后,可以将一定数量的 Token 从父进程转移到相同 Token 接口规范的子进程中。如果子账本进程的 `From-Module` 得到参与者的信任,这些子账本可以直接进行交易,而无需与父进程交换消息。即使父进程在拥堵状态,参与者也能使用子进程中的 Token。如果参与者信任子账本进程,可以认为这些进程之间的余额是等价的。因此,同一个 Token 可以由任意数量的进程并行处理。 - -# Token 进程( Token Processes ) - -Token 进程可以对多种类型的消息作出响应,类型在 `Action` 标签中指定。Token 支持的所有的 `Action` 消息类型如下: - -| 名称 | 描述 | 只读 | -| -------- | ------------------------------------------------------------- | ------------------ | -| Balance | 获取一个标志符(identifier) 的余额 | :heavy_check_mark: | -| Balances | 获取整个账本/账户的余额列表 | :heavy_check_mark: | -| Transfer | 函数调用者向一个或多个目标发送1个或多个单位,并选择通知目标。 | :x: | -| Mint | 如果你使用了具备 root 权限的进程,你可以增加 Token 供应量 | :x: | - -在本节的其余部分中,描述了生成符合规范和 Token 进程所需的标签,描述了每个 `Action` 消息的形式和它们的结果。 - -## (创建请求的参数)Spawning Parameters - -每个符合规范的 Token 进程在其生成消息中必须携带以下特定的参数: - -| 标签 | 描述 | 有没有强制性 | -| ------------ | --------------------------------------------------- | ------------------ | -| Name | Token 的名称,也就是显示给用户的名称。 | :heavy_check_mark: | -| Ticker | Token 的缩写名称,以便快速引用。 | :heavy_check_mark: | -| Logo | 应用程序希望在 Token 旁边显示的图片,以便快速识别。 | :heavy_check_mark: | -| Denomination | 当向用户显示数量和余额时, Token 精度度量。 | :x: | - -## 消息协议(Messaging Protocol) - -### Balance(Target? : string) - -返回目标的余额。如果未提供目标参数,返回消息发送者的余额。 - -`Action` 消息的例子: - -```lua= -send({ - Target = "{TokenProcess Identifier}", - Tags = { - Action = "Balance", - Target = "{IDENTIFIER}" - } -}) -``` - -消息返回结果的例子: - -``` -{ - Tags = { - Balance = "50", - Target = "LcldyO8wwiGDzC3iXzGofdO8JdR4S1_2A6Qtz-o33-0", - Ticker = "FUN" - } -} -``` - -### Balances() - -返回 Token 中所有参与者的余额。 - -```lua -send({ - Target = "[TokenProcess Identifier]", - Tags = { - Action = "Balances", - Limit = 1000, # TODO: Is this necessary if the user is paying for the compute and response? - Cursor? = "BalanceIdentifer" - } -}) -``` - -消息返回结果的例子: - -```lua -{ - Data = { - "MV8B3MAKTsUOqyCzQ0Tsa2AR3TiWTBU1Dx0xM4MO-f4": 100, - "LcldyO8wwiGDzC3iXzGofdO8JdR4S1_2A6Qtz-o33-0": 50 - } -} -``` - -### Transfer(Target, Quantity) - -如果发送者拥有足够的余额,则向目标发送 `Quantity`,向接收者发出 `Credit-Notice`,向发送者发出 `Debit-Notice`。如果发送者余额不足,操作失败并通知发送者。 - -```lua -send({ - Target = "[TokenProcess Identifier]", - Tags = { - { name = "Action", value = "Transfer" }, - { name = "Recipient", value = "[ADDRESS]" }, - { name = "Quantity", value = "100" } - } -}) -``` - -在未设置 `Cast` 时,如果发送成功,则应发送通知消息。 - -```lua -ao.send({ - Target = "[Recipient Address]", - Tags = { - { name = "Action", value = "Credit-Notice" }, - { name = "Sender", value = "[ADDRESS]" }, - { name = "Quantity", value = "100"} - } -}) -``` - -接收者将从消息的 `From-Process` 标签中知道他们已收到该 Token 。 - -### Get-Info() - -```lua -send({ - Target = "{Token}", - Tags = { - Action = "Info" - } -}) -``` - -### Mint() [optional] - -实现 `Mint` 操作,允许特定用户创建更多 Token 余额。 - -```lua -send({ - Target ="{Token Process}", - Tags = { - Action = "Mint", - Quantity = "1000" - } -}) -``` - -# 子账本进程(Subledger Processes) - -子账本必须实现 Token 合约的完整消息协议(不包括 `Mint` 操作)。子账本必须为进程实现额外的功能和生成参数。接下来描述子账本和父账本的区别。 - -### (创建请求的参数)Spawning Parameters - -每个符合规范的子账本的进程在其创建请求的消息中必须携带以下特定参数: - -| Tag | 描述 | 有没有强制性 | -| ------------ | --------------------------------- | ------------ | -| Source-Token | 这个子账本代表的根进程的 `ID`。 | :x: | -| Parent-Token | 这个子账本连接到的父进程的 `ID`。 | :x: | - -### `Credit-Notice` Handler - -在收到 `Credit-Notice` 消息时,符合规范的子账本进程必须检查所涉及的进程是否是 `Parent-Token`。如果是,则子账本必须将 `Sender` 的余额增加指定数量。 - -### Transfer(Target, Quantity) - -除了常规的 `Credit-Notice` 标签外,子账本进程还必须提供 `Source-Token` 和 `Parent-Token` 两个标签。接受者如果信任子账本进程的 `Module`,用户就可以在子账本中进行 `Source-Token` 上的存款那样的转账和进行借贷动作。 - -修改后的 `Credit-Notice` 结构如下: - -```lua -ao.send({ - Target = "[Recipient Address]", - Tags = { - { name = "Action", value = "Credit-Notice" }, - { name = "Quantity", value = "100"}, - { name = "Source-Token", value = "[ADDRESS]" }, - { name = "Parent-Token", value = "[ADDRESS]" } - } -}) -``` - -### Withdraw(Target?, Quantity) - -所有子账本必须允许余额持有者将他们的 Token 提取到父账本中。收到一个 `Action: Withdraw` 消息后,子账本必须向其 `Parent-Ledger` 发送一个 `Action` 消息,将请求的 Token 转移到调用者的地址,同时在本地扣除他们的账户。这个转移将会让调用者收到来自 `Parent-Ledger` 的 `Credit-Notice`。 - -```lua -send({ - Target = "[TokenProcess Identifier]", - Tags = { - { name = "Action", value = "Withdraw" }, - { name = "Recipient", value = "[ADDRESS]" }, - { name = "Quantity", value = "100" } - } -}) -``` - -# Token 例子 - -> 请注意: 在实现 Token 时,消息上的所有标签必须是 "string" 类型。你可以使用 `tostring` 函数将简单类型转换为字符串。 - -```lua -if not balances then - balances = { [ao.id] = 100000000000000 } -end - -if name ~= "Fun Coin" then - name = "Fun Coin" -end - -if ticker ~= "Fun" then - ticker = "fun" -end - -if denomination ~= 6 then - denomination = 6 -end - --- handler 处理传入的消息 - -handlers.add( - "transfer", - handlers.utils.hasMatchingTag("Action", "Transfer"), - function (msg) - assert(type(msg.Tags.Recipient) == 'string', 'Recipient is required!') - assert(type(msg.Tags.Quantity) == 'string', 'Quantity is required!') - - if not balances[msg.From] then - balances[msg.From] = 0 - end - - if not balances[msg.Tags.Recipient] then - balances[msg.Tags.Recipient] = 0 - end - - local qty = tonumber(msg.Tags.Quantity) - assert(type(qty) == 'number', 'qty must be number') - -- handlers.utils.reply("Transfering qty")(msg) - if balances[msg.From] >= qty then - balances[msg.From] = balances[msg.From] - qty - balances[msg.Tags.Recipient] = balances[msg.Tags.Recipient] + qty - ao.send({ - Target = msg.From, - Tags = { - Action = "Debit-Notice", - Quantity = tostring(qty) - } - }) - ao.send({ - Target = msg.Tags.Recipient, - Tags = { - Action = "Credit-Notice", - Quantity = tostring(qty) - }}) - -- if msg.Tags.Cast and msg.Tags.Cast == "true" then - -- return - -- end - - end - end -) - -handlers.add( - "balance", - handlers.utils.hasMatchingTag("Action", "Balance"), - function (msg) - assert(type(msg.Tags.Target) == "string", "Target Tag is required!") - local bal = "0" - if balances[msg.Tags.Target] then - bal = tostring(balances[msg.Tags.Target]) - end - ao.send({Target = msg.From, Tags = { - Target = msg.From, - Balance = bal, - Ticker = ticker or "" - }}) - end -) - -local json = require("json") - -handlers.add( - "balances", - handlers.utils.hasMatchingTag("Action", "Balances"), - function (msg) - ao.send({ - Target = msg.From, - Data = json.encode(balances) - }) - end - -) - -handlers.add( - "info", - handlers.utils.hasMatchingTag("Action", "Info"), - function (msg) - ao.send({Target = msg.From, Tags = { - Name = name, - Ticker = ticker, - Denomination = tostring(denomination) - }}) - end -) -``` - -## 认识 Web Assembly -Source: https://cookbook_ao.arweave.net/zh/references/wasm.html - -WebAssembly(通常简称为 Wasm)是一种现代的二进制指令格式,为高级语言(如C、C++和Rust)提供了一个可迁移的编译目标。它可以支持在网络上部署客户端和服务器应用,并提供高水平的性能和效率。WebAssembly 是为了保持网络浏览器的安全性和沙盒功能而设计的,成为网络应用程序的选择之一。它是网络开发人员的关键技术,使他们能够用多种语言编写代码,并将代码编译为在浏览器中以接近原生速度运行的字节码。 - -WebAssembly 的重要性在于它能够弥合网络应用程序和本地应用程序之间的差距。它使得之前局限于桌面环境的复杂应用程序和游戏,能够在浏览器中以相当的性能运行。这为网络开发带来了新的可能性,包括创建高性能的网络应用程序、游戏,甚至将现有的桌面应用程序移植到网络上。WebAssembly 与 JavaScript 并行运行,通过使用更适合此类任务的语言编写性能关键组件,弥补了 JavaScript 的缺陷,从而增强了网络应用程序的功能和性能。 - -# Summary - -Total files processed: 10 diff --git a/src/public/zh/llms.txt b/src/public/zh/llms.txt deleted file mode 100644 index c55fb1f1..00000000 --- a/src/public/zh/llms.txt +++ /dev/null @@ -1,307 +0,0 @@ -# ZH Documentation for LLMs - -Generated: 2025-09-10T20:06:33.625Z - -This file contains structured reference documentation, release notes, and a comprehensive directory of all documentation pages. - -# Documentation Directory - -## Concepts - -- [ao 信使的工作原理](https://cookbook_ao.arweave.net/zh/concepts/how-it-works.html) -- [ao 规范](https://cookbook_ao.arweave.net/zh/concepts/specs.html) -- [aos 简明教程](https://cookbook_ao.arweave.net/zh/concepts/tour.html) -- [Holographic State](https://cookbook_ao.arweave.net/zh/concepts/holographic-state.html) -- [单元](https://cookbook_ao.arweave.net/zh/concepts/units.html) -- [概念](https://cookbook_ao.arweave.net/zh/concepts/index.html) -- [消息](https://cookbook_ao.arweave.net/zh/concepts/messages.html) -- [走马观花的学习下 Lua](https://cookbook_ao.arweave.net/zh/concepts/lua.html) -- [进程](https://cookbook_ao.arweave.net/zh/concepts/processes.html) - -## Guides - -### Aoconnect - -- [aoconnect](https://cookbook_ao.arweave.net/zh/guides/aoconnect/aoconnect.html) -- [Sending a Message to a Process](https://cookbook_ao.arweave.net/zh/guides/aoconnect/sending-messages.html) -- [从 ao 进程读取结果](https://cookbook_ao.arweave.net/zh/guides/aoconnect/reading-results.html) -- [创建一个进程](https://cookbook_ao.arweave.net/zh/guides/aoconnect/spawning-processes.html) -- [安装 ao connect](https://cookbook_ao.arweave.net/zh/guides/aoconnect/installing-connect.html) -- [监控 Cron](https://cookbook_ao.arweave.net/zh/guides/aoconnect/monitoring-cron.html) -- [调用 DryRun](https://cookbook_ao.arweave.net/zh/guides/aoconnect/calling-dryrun.html) -- [连接到特定的 ao 节点](https://cookbook_ao.arweave.net/zh/guides/aoconnect/connecting.html) - -### Aos - -#### Blueprints - -- [CRED Utils 蓝图](https://cookbook_ao.arweave.net/zh/guides/aos/blueprints/cred-utils.html) -- [Token 蓝图](https://cookbook_ao.arweave.net/zh/guides/aos/blueprints/token.html) -- [投票蓝图 (Voting Blueprint)](https://cookbook_ao.arweave.net/zh/guides/aos/blueprints/voting.html) -- [聊天室蓝图 (Chatroom Blueprint)](https://cookbook_ao.arweave.net/zh/guides/aos/blueprints/chatroom.html) -- [蓝图 Blueprints](https://cookbook_ao.arweave.net/zh/guides/aos/blueprints/index.html) -- [质押蓝图 (Staking Blueprint)](https://cookbook_ao.arweave.net/zh/guides/aos/blueprints/staking.html) - -#### Modules - -- [ao](https://cookbook_ao.arweave.net/zh/guides/aos/modules/ao.html) -- [Base64 编码模块](https://cookbook_ao.arweave.net/zh/guides/aos/modules/base64.html) -- [JSON](https://cookbook_ao.arweave.net/zh/guides/aos/modules/json.html) -- [Pretty 模块](https://cookbook_ao.arweave.net/zh/guides/aos/modules/pretty.html) -- [Utils 工具库](https://cookbook_ao.arweave.net/zh/guides/aos/modules/utils.html) -- [模块](https://cookbook_ao.arweave.net/zh/guides/aos/modules/index.html) - -- [.load 命令](https://cookbook_ao.arweave.net/zh/guides/aos/load.html) -- [aos](https://cookbook_ao.arweave.net/zh/guides/aos/index.html) -- [aos 中的自定义提示符(Prompt)](https://cookbook_ao.arweave.net/zh/guides/aos/prompt.html) -- [CLI](https://cookbook_ao.arweave.net/zh/guides/aos/cli.html) -- [FAQ](https://cookbook_ao.arweave.net/zh/guides/aos/faq.html) -- [使用 ao.link 进行故障排除](https://cookbook_ao.arweave.net/zh/guides/aos/troubleshooting.html) -- [创建一个 Pingpong 进程](https://cookbook_ao.arweave.net/zh/guides/aos/pingpong.html) -- [在 ao 中创建 Token](https://cookbook_ao.arweave.net/zh/guides/aos/token.html) -- [安装 aos](https://cookbook_ao.arweave.net/zh/guides/aos/installing.html) -- [概览](https://cookbook_ao.arweave.net/zh/guides/aos/intro.html) -- [理解收件箱(Inbox)](https://cookbook_ao.arweave.net/zh/guides/aos/inbox-and-handlers.html) -- [编辑器初始化](https://cookbook_ao.arweave.net/zh/guides/aos/editor.html) - -- [指南](https://cookbook_ao.arweave.net/zh/guides/index.html) - -## References - -- [ao Token 和子账本规范](https://cookbook_ao.arweave.net/zh/references/token.html) -- [ao 模块](https://cookbook_ao.arweave.net/zh/references/ao.html) -- [Handlers (版本 0.0.3)](https://cookbook_ao.arweave.net/zh/references/handlers.html) -- [使用 ao 访问 Arweave 上的数据](https://cookbook_ao.arweave.net/zh/references/data.html) -- [参考](https://cookbook_ao.arweave.net/zh/references/index.html) -- [定时消息(Cron Messages)](https://cookbook_ao.arweave.net/zh/references/cron.html) -- [社区](https://cookbook_ao.arweave.net/zh/references/community.html) -- [编辑器设置](https://cookbook_ao.arweave.net/zh/references/editor-setup.html) -- [认识 Lua](https://cookbook_ao.arweave.net/zh/references/lua.html) -- [认识 Web Assembly](https://cookbook_ao.arweave.net/zh/references/wasm.html) - -## Tutorials - -### Begin - -- [`ao` 中的消息传递](https://cookbook_ao.arweave.net/zh/tutorials/begin/messaging.html) -- [DAO 指南](https://cookbook_ao.arweave.net/zh/tutorials/begin/dao.html) -- [准备工作](https://cookbook_ao.arweave.net/zh/tutorials/begin/preparations.html) -- [创建 token](https://cookbook_ao.arweave.net/zh/tutorials/begin/token.html) -- [在 aos 中建立一个聊天室](https://cookbook_ao.arweave.net/zh/tutorials/begin/chatroom.html) -- [开始:互动教程](https://cookbook_ao.arweave.net/zh/tutorials/begin/index.html) -- [支持 token 的聊天室](https://cookbook_ao.arweave.net/zh/tutorials/begin/tokengating.html) -- [进入 `The Construct` - 交互式教程](https://cookbook_ao.arweave.net/zh/tutorials/begin/rabbithole.html) - -### Bots and games - -- [我们来玩个游戏吧!](https://cookbook_ao.arweave.net/zh/tutorials/bots-and-games/ao-effect.html) -- [战略决策](https://cookbook_ao.arweave.net/zh/tutorials/bots-and-games/decisions.html) -- [扩建竞技场](https://cookbook_ao.arweave.net/zh/tutorials/bots-and-games/build-game.html) -- [整合在一起](https://cookbook_ao.arweave.net/zh/tutorials/bots-and-games/bringing-together.html) -- [机器人和游戏](https://cookbook_ao.arweave.net/zh/tutorials/bots-and-games/index.html) -- [竞技场机制](https://cookbook_ao.arweave.net/zh/tutorials/bots-and-games/arena-mechanics.html) -- [自动响应](https://cookbook_ao.arweave.net/zh/tutorials/bots-and-games/attacking.html) -- [获取游戏状态](https://cookbook_ao.arweave.net/zh/tutorials/bots-and-games/game-state.html) -- [解析公告](https://cookbook_ao.arweave.net/zh/tutorials/bots-and-games/announcements.html) - -- [教程](https://cookbook_ao.arweave.net/zh/tutorials/index.html) - -## Welcome - -### Testnet info - -- [CRED 和任务 FAQ](https://cookbook_ao.arweave.net/zh/welcome/testnet-info/cred-and-quests.html) -- [参与 ao 测试网](https://cookbook_ao.arweave.net/zh/welcome/testnet-info/index.html) - -- [5分钟入门](https://cookbook_ao.arweave.net/zh/welcome/getting-started.html) -- [欢迎来到 ao](https://cookbook_ao.arweave.net/zh/welcome/index.html) - -- [LLMs 文件文档](https://cookbook_ao.arweave.net/zh/llms-explanation.html) - - - -# Detailed Content - -## TABLE OF CONTENTS - -- API AND FUNCTION REFERENCES - - ao 模块 - - 社区 - - 定时消息(Cron Messages) - - 使用 ao 访问 Arweave 上的数据 - - 编辑器设置 - - Handlers (版本 0.0.3) - - 参考 - - 认识 Lua - - ao Token 和子账本规范 - - 认识 Web Assembly - - - -## API AND FUNCTION REFERENCES - - - -### ao 模块 -Source: https://cookbook_ao.arweave.net/zh/references/ao.html - -### API Definitions -- send -- spawn -- isTrusted - - -### 社区 -Source: https://cookbook_ao.arweave.net/zh/references/community.html - -[Autonomous Finance](https://www.autonomous.finance/) - -### 定时消息(Cron Messages) -Source: https://cookbook_ao.arweave.net/zh/references/cron.html - - -### Code Examples -``` -如果你希望停止触发定时(cron) 消息,只需调用 `.unmonitor`,这会停止触发过程。但下次你发送消息时,生成的定时(cron) 消息仍将创建和处理进程。 - -## 处理定时消息 - -每条定时(cron) 消息都有一个值为 `Cron` 的 `Action` 标签。根据定义,[处理器](handlers.md)在每次收到定时(cron) 消息时,都会自动执行特定任务。 -``` - - - -### 使用 ao 访问 Arweave 上的数据 -Source: https://cookbook_ao.arweave.net/zh/references/data.html - -在你的 ao 开发工作流程中,可能有时候你想要访问 arweave 上的数据。你的进程可以使用 ao 发送一条消息,然后 ao 网络会通过一个 Message 对象将数据提供给你的 Process 对象。 - -### 编辑器设置 -Source: https://cookbook_ao.arweave.net/zh/references/editor-setup.html - -### API Definitions -- VS - - -### Handlers (版本 0.0.3) -Source: https://cookbook_ao.arweave.net/zh/references/handlers.html - -### API Definitions -- `Handlers.add -- `Handlers.append -- `Handlers.prepend -- `Handlers.before -- `Handlers.after -- `Handlers.remove -- `Handlers.evaluate -- Handlers.utils -- Handlers.utils.hasMatchingData -- Handlers.hasMatchingTag -- Handlers.reply - -### Code Examples -``` -如果这个进入进程的消息有设置成 ”ping" 的数据,那么这个 handler 会匹配上它,并调用处理函数。 - -### Handlers.hasMatchingTag(name : string, value : string) - -这个辅助函数返回一个需要消息参数的函数,因此你可以将它放入 Handlers 模块的任何匹配参数中。该函数会比较 Tag 的名称和数值,如果它们相等,则调用处理函数。 -``` - -``` -### Handlers.reply(text : string) - -这个辅助函数是一个简单的处理函数,就是将 text 的值放入发送消息的 Data 属性中。 -``` - - - -### 参考 -Source: https://cookbook_ao.arweave.net/zh/references/index.html - -## 目录 - -- [Lua](lua) -- [Web Assembly](wasm) -- [ao 模块](ao) -- [Handlers](handlers) -- [代币](token) -- [加载 Arweave 数据](data) -- [定时消息](cron) -- [编辑器设置](editor-... - -### 认识 Lua -Source: https://cookbook_ao.arweave.net/zh/references/lua.html - -1. **安装**: 访问 [Lua 的官方网站](http://www.lua.org/download.html) ,下载并安装 Lua。 -2. **环境**: 你可以使用简单的文本编辑器和命令行,或者像 ZeroBrane Studio ,或带有 Lua 插件的 Eclipse 这样的集成开发环境(IDE)。 - -### ao Token 和子账本规范 -Source: https://cookbook_ao.arweave.net/zh/references/token.html - -### API Definitions -- Balance -- Balances -- Transfer -- Get -- Mint -- `Credit -- Transfer -- Withdraw - -### Code Examples -``` -### Balances() - -返回 Token 中所有参与者的余额。 -``` - -``` -### Transfer(Target, Quantity) - -如果发送者拥有足够的余额,则向目标发送 `Quantity`,向接收者发出 `Credit-Notice`,向发送者发出 `Debit-Notice`。如果发送者余额不足,操作失败并通知发送者。 -``` - -``` -接收者将从消息的 `From-Process` 标签中知道他们已收到该 Token 。 - -### Get-Info() -``` - - -### Parameters -| -| -------- | ------------------------------------------------------------- | ------------------ | -| Balance | 获取一个标志符(identifier) 的余额 | :heavy_check_mark: | -| Balances | 获取整个账本/账户的余额列表 | :heavy_check_mark: | -| Transfer | 函数调用者向一个或多个目标发送1个或多个单位,并选择通知目标。 | :x: | -| Mint | 如果你使用了具备 root 权限的进程,你可以增加 Token 供应量 | :x: | - - -### Parameters -| -| ------------ | --------------------------------------------------- | ------------------ | -| Name | Token 的名称,也就是显示给用户的名称。 | :heavy_check_mark: | -| Ticker | Token 的缩写名称,以便快速引用。 | :heavy_check_mark: | -| Logo | 应用程序希望在 Token 旁边显示的图片,以便快速识别。 | :heavy_check_mark: | -| Denomination | 当向用户显示数量和余额时, Token 精度度量。 | :x: | - - -### Parameters -| -| ------------ | --------------------------------- | ------------ | -| Source-Token | 这个子账本代表的根进程的 `ID`。 | :x: | -| Parent-Token | 这个子账本连接到的父进程的 `ID`。 | :x: | - - - -### 认识 Web Assembly -Source: https://cookbook_ao.arweave.net/zh/references/wasm.html - -WebAssembly(通常简称为 Wasm)是一种现代的二进制指令格式,为高级语言(如C、C++和Rust)提供了一个可迁移的编译目标。它可以支持在网络上部署客户端和服务器应用,并提供高水平的性能和效率。WebAssembly 是为了保持网络浏览器的安全性和沙盒功能而设计的,成为网络应用程序的选择之一。它是网络开发人员的关键技术,使他们能够用多种语言编写代码,并将代码编译为在浏览器中以接近原生速度运行的字节码。 - -# Summary - -Total files processed: 10 -Total documentation pages: 75 -This documentation is focused on technical references and release notes, prioritizing accuracy and relevance for LLM processing. diff --git a/src/references/deprecated/index.md b/src/references/deprecated/index.md new file mode 100644 index 00000000..5a4f8319 --- /dev/null +++ b/src/references/deprecated/index.md @@ -0,0 +1,20 @@ +# Deprecated Features + +This section contains documentation for deprecated features and APIs in the AO ecosystem. + +## Coming Soon + +After October 10, 2025, this section will include documentation for features that have been deprecated, including migration guides and alternatives. + +## Current Deprecations + +For information about features being deprecated, please see: + +- [Calling DryRun](../../guides/aoconnect/calling-dryrun.md) - Includes urgent deprecation notice for Legacynet dry run support + +## Migration Support + +If you need help migrating away from deprecated features: + +- Review the [Migrating to HyperBEAM](../../migrating-to-hyperbeam/why-migrate.md) guide +- Join the [Discord community](https://discord.gg/qWgGxJKwNJ) for support diff --git a/src/releasenotes/hyper-aos-2_0_7.md b/src/releasenotes/hyper-aos-2_0_7.md new file mode 100644 index 00000000..b8eb04a2 --- /dev/null +++ b/src/releasenotes/hyper-aos-2_0_7.md @@ -0,0 +1,93 @@ +# Hyper AOS 2.0.7 + +## Installation and Setup + +This release of Hyper AOS adds support for the latest HyperBEAM changes (edge) while providing full backwards compatibility with aos legacynet. The latest version can be installed globally using npm: + +```bash +npm i -g https://get_ao.arweave.net +``` + +## Connecting to Hyper AOS + +To connect to a local Hyper AOS instance: + +```bash +aos --url http://localhost:8734 +``` + +Select `hyper-aos`: + +``` +Welcome to AOS: Your operating system for AO, the decentralized open access supercomputer. +Type ".load-blueprint chat" to join the community chat and ask questions! +? Please select › - Use arrow-keys. Return to submit. + aos +❯ hyper-aos (experimental - DO NOT USE FOR PRODUCTION) +``` + +Once connected, you can load blueprints: + +``` +> .load-blueprint htoken +``` + +## API Differences from Standard AOS + +Hyper AOS has several syntax differences compared to the standard AOS: + +- Use `id` instead of `ao.id` +- Use `owner` instead of `Owner` +- For sending messages, use `send({target = id, data = "Hello"})` instead of `ao.send` or `Send` +- Coroutines and `os.receive()` / `Receive()` are not implemented + +## State Synchronization + +One of the most powerful features of Hyper AOS is the synchronization between Hyperbeam process state and Lua state: + +```lua +-- In Lua: +Foo = "BAR" + +-- In Hyperbeam: +-- http://localhost:8734/{process}/now/Foo +-- Returns 'BAR' +``` + +## Best Practices + +### Variable Scoping + +When requiring modules, it's recommended to use local variables to prevent memory leaks and improve garbage collection: + +```lua +-- Good practice +local JSON = require('json') +-- Use JSON... + +-- Better practice for memory management +do + local JSON = require('json') + -- Use JSON... +end +``` + +### Known Issues + +There are some serialization bugs to be aware of: + +- If you set a global variable to a required module, you may lose methods during serialization: + +```lua +-- Problematic approach +JSON = require('json') +-- You might lose access to encode/decode methods + +-- Recommended approach +local JSON = require('json') +-- Methods remain accessible +``` + +## Performance + +The system is optimized for speed, making it suitable for applications requiring quick response times.