DEV Community: KYOHEI ITO

Arweave AO Lua Programming Guide

KYOHEI ITO — Thu, 12 Jun 2025 04:27:01 +0000

Arweave AO (Actor Oriented) uses the Lua programming language to describe processes. This article explains the basic syntax for writing Lua in AO and AO-specific patterns.

Variables and Data Types

Basic Variable Declaration

-- Global variables
MyVariable = "Hello World"
Counter = 42
IsActive = true

-- Local variables
local localVar = "Local variable"
local number = 123

Data Types

Lua is a dynamically typed language that supports the following data types:

-- Numeric types
local integer = 42
local float = 3.14
local scientific = 1.23e-4

-- String types
local str1 = "Double quotes"
local str2 = 'Single quotes'
local multiline = [[
Multi-line
strings are possible
]]

-- Boolean values
local isTrue = true
local isFalse = false

-- nil (undefined value)
local nothing = nil

Tables (Arrays and Dictionaries)

Lua tables are flexible data structures that function as both arrays and dictionaries.

Arrays

-- Arrays (indices start from 1)
local fruits = {"apple", "banana", "orange"}
print(fruits[1])  -- "apple"
print(#fruits)    -- 3 (array length)

Dictionaries (Associative Arrays)

-- Dictionary
local person = {
    name = "John",
    age = 25,
    active = true
}

-- Access methods
print(person.name)     -- "John"
print(person["age"])   -- 25

Composite Tables

-- Mixed arrays and dictionaries
local mixed = {
    "first",           -- [1]
    "second",          -- [2]
    name = "Mixed",    -- ["name"]
    count = 100        -- ["count"]
}

-- Nested tables
local config = {
    database = {
        host = "localhost",
        port = 5432,
        credentials = {
            username = "admin",
            password = "secret"
        }
    }
}

Functions

Basic Function Definition

-- Regular function
function greet(name)
    return "Hello, " .. name
end

-- Local function
local function add(a, b)
    return a + b
end

-- Anonymous function
local multiply = function(x, y)
    return x * y
end

Advanced Function Features

-- Multiple return values
function getCoordinates()
    return 10, 20
end
local x, y = getCoordinates()

-- Variable arguments
function sum(...)
    local args = {...}
    local total = 0
    for i = 1, #args do
        total = total + args[i]
    end
    return total
end

-- Usage example
local result = sum(1, 2, 3, 4, 5)  -- 15

Control Structures

Conditional Statements

local score = 85

if score >= 90 then
    print("Excellent")
elseif score >= 70 then
    print("Good")
else
    print("Needs improvement")
end

Loop Processing

-- Numeric loop
for i = 1, 10 do
    print("Count: " .. i)
end

-- Reverse loop
for i = 10, 1, -1 do
    print(i)
end

-- Array iteration
local items = {"a", "b", "c"}
for i = 1, #items do
    print(i, items[i])
end

-- Key-value pair iteration (all elements)
local data = {name = "John", age = 30, city = "Tokyo"}
for key, value in pairs(data) do
    print(key, value)
end

-- Array-specific iteration (consecutive indices only)
for index, value in ipairs(items) do
    print(index, value)
end

-- while statement
local count = 0
while count < 5 do
    print("Count: " .. count)
    count = count + 1
end

AO-Specific Syntax

AO has several special rules in addition to regular Lua.

Persisted Variables

-- Global variables starting with capital letters are automatically persisted
PersistentData = PersistentData or {}
TotalSupply = 1000000
Balances = Balances or {}

-- Conditional initialization pattern (for process restart compatibility)
if not Owner then
    Owner = ao.env.Process.Owner
end

AO Built-in Functions

-- Message sending
ao.send({
    Target = "ProcessID",
    Tags = {
        Action = "Transfer",
        Amount = "100"
    },
    Data = "Additional data"
})

-- Environment variable access
local processId = ao.id
local owner = ao.env.Process.Owner

Message Handlers

AO's characteristic message processing system.

Basic Handler

Handlers.add(
    "balance_check",  -- Handler name
    Handlers.utils.hasMatchingTag("Action", "Balance"),  -- Condition
    function(msg)     -- Processing function
        local account = msg.Tags.Account or msg.From
        local balance = Balances[account] or 0

        ao.send({
            Target = msg.From,
            Tags = {
                Action = "Balance-Response",
                Balance = tostring(balance)
            }
        })
    end
)

Handlers with Complex Conditions

-- Custom condition function
local function isValidTransfer(msg)
    return msg.Tags.Action == "Transfer" and
           msg.Tags.To and
           msg.Tags.Amount and
           tonumber(msg.Tags.Amount) > 0
end

Handlers.add(
    "transfer",
    isValidTransfer,
    function(msg)
        local from = msg.From
        local to = msg.Tags.To
        local amount = tonumber(msg.Tags.Amount)

        -- Transfer processing
        if Balances[from] and Balances[from] >= amount then
            Balances[from] = Balances[from] - amount
            Balances[to] = (Balances[to] or 0) + amount

            ao.send({
                Target = msg.From,
                Tags = { Action = "Transfer-Success" }
            })
        else
            ao.send({
                Target = msg.From,
                Tags = { Action = "Transfer-Error", Error = "Insufficient balance" }
            })
        end
    end
)

Common Patterns

Safe Type Conversion

-- Safe numeric conversion
local function safeToNumber(value, default)
    local num = tonumber(value)
    return num and num or (default or 0)
end

-- Safe string conversion
local function safeToString(value)
    return tostring(value or "")
end

Validation Functions

local function validateTransfer(from, to, amount)
    -- Sender/recipient check
    if not from or not to or from == to then
        return false, "Invalid sender or recipient"
    end

    -- Amount check
    local numAmount = tonumber(amount)
    if not numAmount or numAmount <= 0 then
        return false, "Invalid amount"
    end

    -- Balance check
    if not Balances[from] or Balances[from] < numAmount then
        return false, "Insufficient balance"
    end

    return true, numAmount
end

-- Usage example
local isValid, amountOrError = validateTransfer(msg.From, msg.Tags.To, msg.Tags.Amount)
if not isValid then
    ao.send({
        Target = msg.From,
        Tags = { Action = "Error", Message = amountOrError }
    })
    return
end

Utility Functions

-- Table copying
local function deepCopy(original)
    local copy = {}
    for key, value in pairs(original) do
        if type(value) == "table" then
            copy[key] = deepCopy(value)
        else
            copy[key] = value
        end
    end
    return copy
end

-- Check if table is empty
local function isEmpty(tbl)
    return next(tbl) == nil
end

-- Search for element in array
local function findInArray(array, value)
    for i, v in ipairs(array) do
        if v == value then
            return i
        end
    end
    return nil
end

Error Handling

pcall (Protected Call)

-- Safe function execution
local success, result = pcall(function()
    return someRiskyFunction()
end)

if success then
    print("Success: " .. tostring(result))
else
    print("Error: " .. tostring(result))
end

assert

-- Condition check
local function divide(a, b)
    assert(type(a) == "number", "First argument must be a number")
    assert(type(b) == "number", "Second argument must be a number")
    assert(b ~= 0, "Cannot divide by zero")
    return a / b
end

Custom Error Handling

local function safeExecute(func, errorHandler)
    local success, result = pcall(func)
    if success then
        return result
    else
        if errorHandler then
            return errorHandler(result)
        else
            print("An error occurred: " .. tostring(result))
            return nil
        end
    end
end

-- Usage example
local result = safeExecute(
    function() return calculateSomething() end,
    function(error) return "Calculation failed: " .. error end
)

Practical Example: Simple Token Contract

Here's a practical example combining the knowledge covered so far:

-- Token basic information
TokenName = "MyToken"
TokenSymbol = "MTK"
TotalSupply = 1000000
Balances = Balances or {}

-- Initialization
if not Owner then
    Owner = ao.env.Process.Owner
    Balances[Owner] = TotalSupply
end

-- Utility functions
local function hasBalance(account, amount)
    return Balances[account] and Balances[account] >= amount
end

-- Balance inquiry handler
Handlers.add(
    "balance",
    Handlers.utils.hasMatchingTag("Action", "Balance"),
    function(msg)
        local account = msg.Tags.Account or msg.From
        local balance = Balances[account] or 0

        ao.send({
            Target = msg.From,
            Tags = {
                Action = "Balance-Response",
                Account = account,
                Balance = tostring(balance)
            }
        })
    end
)

-- Transfer handler
Handlers.add(
    "transfer",
    Handlers.utils.hasMatchingTag("Action", "Transfer"),
    function(msg)
        local from = msg.From
        local to = msg.Tags.To
        local amount = tonumber(msg.Tags.Amount)

        -- Validation
        if not to or not amount or amount <= 0 then
            ao.send({
                Target = from,
                Tags = { Action = "Transfer-Error", Error = "Invalid parameters" }
            })
            return
        end

        if not hasBalance(from, amount) then
            ao.send({
                Target = from,
                Tags = { Action = "Transfer-Error", Error = "Insufficient balance" }
            })
            return
        end

        -- Execute transfer
        Balances[from] = Balances[from] - amount
        Balances[to] = (Balances[to] or 0) + amount

        ao.send({
            Target = from,
            Tags = {
                Action = "Transfer-Success",
                From = from,
                To = to,
                Amount = tostring(amount)
            }
        })
    end
)

Summary

Lua programming in AO requires understanding the following key points in addition to regular Lua knowledge:

Persistence concept: Automatic persistence of global variables starting with capital letters
Message-driven architecture: Asynchronous processing using Handlers
State management: Conditional initialization for process restart compatibility
Error handling: Robust error handling in distributed environments

Understanding these concepts enables you to build efficient and secure processes on the AO platform. While AO's distributed computing environment requires asynchronous, message-based thinking that differs from traditional synchronous programming, Lua's simple syntax helps reduce that complexity.

Arweave AO Bootcamp 8/8 Ending & Appendix

KYOHEI ITO — Wed, 04 Jun 2025 01:14:54 +0000

This concludes the AO Bootcamp. Congratulations on making it through!

The following content serves as appendices.

We will continue to publish learning resources on Arweave AO.

Next up, we plan to introduce the latest practical dApp development flow leveraging Claude Code & ChatGPT.

Debugging and Troubleshooting

Common issues in AO development and their solutions are introduced below.

Message sending fails:
- Check that the wallet has sufficient balance.
- Verify that the correct process ID is specified.
- Confirm that the message format is correct.
Process state does not update:
- Ensure that handlers are properly configured.
- Check that message tags and data match the handler’s conditions.
- Verify that the Compute Unit (CU) correctly calculates the process state.
Obtaining debug information:
- Use the ao.log function to output debug information.
- Use the ao.link explorer to inspect process states and messages.
- Review process results in detail.
Performance optimization:
- Avoid using large data structures.
- Avoid sending unnecessary messages.
- Use dryrun for read-only operations.
Network connectivity issues:
- Verify that all units (MU/SU/CU) are running correctly.
- Check network settings (URLs, ports, etc.) for accuracy.
- Adjust timeout settings as needed.

An important tool for AO development is the ao.link explorer. This tool allows you to visually monitor process states and the flow of messages.

Complete Example of a Key-Value Store

Below is a full implementation example of a Key-Value store.

// kv-store.js
const { createDataItemSigner, connect } = require("@permaweb/aoconnect");
const { readFileSync } = require("fs");
const { resolve } = require("path");

// Load wallet
const jwk = JSON.parse(readFileSync(resolve(__dirname, "wallet.json")));
// Connect to AO units
const { result, message, spawn, dryrun } = connect({
  MU_URL: "http://localhost:4002",
  CU_URL: "http://localhost:4004",
  GATEWAY_URL: "http://localhost:4000",
});

// Wait helper
const wait = (ms) => new Promise((res) => setTimeout(() => res(), ms));

// Main function
async function main() {
  // Spawn a process
  const pid = await spawn({
    module: "YOUR_MODULE_ID", // AOS module ID
    scheduler: "YOUR_SCHEDULER_WALLET", // Scheduler wallet address
    signer: createDataItemSigner(jwk),
  });

  await wait(1000);
  console.log(`Spawned process ID: ${pid}`);

  // Define Lua handlers
  const lua = `
    local ao = require('ao')
    Store = Store or {}

    Handlers.add(
      "Get",
      Handlers.utils.hasMatchingTag("Action", "Get"),
      function (msg)
        assert(type(msg.Key) == 'string', 'Key is required!')
        ao.send({ Target = msg.From, Tags = { Value = Store[msg.Key] }})
      end
    )

    Handlers.add(
      "Set",
      Handlers.utils.hasMatchingTag("Action", "Set"),
      function (msg)
        assert(type(msg.Key) == 'string', 'Key is required!')
        assert(type(msg.Value) == 'string', 'Value is required!')
        Store[msg.Key] = msg.Value
        Handlers.utils.reply("Value stored!")(msg)
      end
    )
  `;

  // Register handlers
  const mid = await message({
    process: pid,
    signer: createDataItemSigner(jwk),
    tags: [{ name: "Action", value: "Eval" }],
    data: lua,
  });

  const res = await result({ process: pid, message: mid });
  console.log("Handler registration result:", res);

  // Set a value
  const mid1 = await message({
    process: pid,
    signer: createDataItemSigner(jwk),
    tags: [
      { name: "Action", value: "Set" },
      { name: "Key", value: "test" },
      { name: "Value", value: "abc" },
    ],
  });

  const res1 = await result({ process: pid, message: mid1 });
  console.log("Set value result:", res1.Messages[0]);

  // Get a value
  const res2 = await dryrun({
    process: pid,
    signer: createDataItemSigner(jwk),
    tags: [
      { name: "Action", value: "Get" },
      { name: "Key", value: "test" },
    ],
  });

  console.log("Get value result:", res2.Messages[0].Tags);
}

main().catch(console.error);

Glossary

AO (Actor Oriented) A protocol for a decentralized, hyper-parallel supercomputer built on Arweave. It is based on the actor model and offers high scalability.

AOS (Actor Operating System) The first implementation of AO. A lightweight actor runtime environment using Lua, responsible for process management and message handling.

MU (Messenger Unit) A component of AO responsible for receiving, validating, and forwarding messages to the appropriate units.

SU (Scheduler Unit) The component that orders and persists messages, including storing them on Arweave.

CU (Compute Unit) The component that executes process logic and updates process state.

Eval (Evaluation) An action in AOS that dynamically registers or updates Lua code within a process.

dryrun An operation that simulates processing using the current state without actually writing transactions to Arweave.

JWK (JSON Web Key) A JSON format representing wallet private and public keys.

AR Token The native token of the Arweave network, used for permanent data storage.

AO Token The native token of the AO network, used for network security and incentives.

aoETH An asset bridged from Ethereum’s ETH into the AO network, eligible for AO token distribution.

Handlers A table in AOS Lua scripts that manages functions handling incoming messages.

Message The unit of data exchanged between processes, including tags and payload.

Arweave A blockchain network providing permanent storage. AO is built on top of it.

References

By leveraging these resources, you can deepen your understanding of Arweave and AO development and accelerate your progress.

Arweave AO Bootcamp 7/8 $AO Token

KYOHEI ITO — Wed, 04 Jun 2025 01:12:42 +0000

What You'll Learn in This Chapter

In this chapter, you’ll learn the fundamental principles behind the AO token design that powers the AO network’s economy.
AO tokens play a crucial role in securing the network and driving ecosystem growth.

We will focus on key topics such as:

The AO token supply model and distribution mechanisms
The relationship between AO tokens and AR tokens
Cross-chain asset integration, including aoETH
The token incentive model designed for developers

Understanding these topics will give you a clear picture of AO’s tokenomics and how both developers and users benefit from it.

AO Tokenenomics

Basic Principles of AO Tokens

AO tokens are at the core of the AO network’s economic model.
The design principles are as follows:

Fully Fair Launch: AO tokens adopt a fully fair launch model similar to Bitcoin. There are no pre-mines or ICOs.
Fixed Supply Cap: Like Bitcoin, AO tokens have a capped supply of 21,000,000 tokens.
Automatic Distribution: Tokens are distributed automatically every 5 minutes.
Halving Schedule: The token issuance follows a Bitcoin-like halving schedule, reducing supply roughly every four years.
Distribution Ratio: 33.3% of issued tokens are distributed to AR token holders, and 66.6% to aoETH holders.
No Mining Required: Unlike traditional blockchains, no mining based on computational resources is needed. Instead, token distribution is based on AR and aoETH holdings.

Relationship Between AR and AO Tokens

AR tokens are the native tokens of the Arweave network, primarily used for permanent data storage.
AO tokens are native to the AO network and mainly serve security and incentive purposes.

AR token holders automatically receive 33.3% of AO token distributions proportional to their holdings.
This tightly links the ecosystems of Arweave and AO.

aoETH and Bridged Assets

The AO network supports bridging assets from Ethereum and other blockchains.
aoETH, a bridged representation of ETH on AO, is a key example.

aoETH holders automatically receive 66.6% of AO token distributions proportional to their holdings.
This connects the Ethereum and AO ecosystems and promotes cross-chain liquidity.

Key features of aoETH include:

Ethereum Liquidity: Brings ETH liquidity into the AO network.
AO Token Rewards: Holding aoETH earns AO token rewards.
Cross-Chain Interoperability: Bridges Ethereum and AO ecosystems.

Developer Token Incentives

One notable feature of AO is its developer-focused token incentive model.
When users lock AR or aoETH tokens into a project, AO tokens are automatically distributed to that project.

This gives developers several benefits:

Sustainable Funding: Continuous funding is ensured as users lock tokens in the project.
User Alignment: Interests of users and projects align, with users earning rewards from the project’s success.
Community-Driven Development: Token holders influence the project’s direction.

This model enables developers to sustainably grow projects with direct support from their user base.

Arweave AO Bootcamp 6/8 Custom JavaScript VM on AO

KYOHEI ITO — Wed, 04 Jun 2025 01:11:52 +0000

What Will You Learn in This Chapter?

In this chapter, you'll learn how to develop AOS (Actor Operating System), the first implementation of the AO protocol.
AOS is a lightweight Lua-based actor runtime that combines Actor Model × Persistent Storage × Distributed Messaging into a new execution environment.

You'll gain hands-on experience by writing actual code, going through the complete process from process creation → logic registration → message sending and receiving step by step.

What You'll Master in This Chapter:

Overview of AOS and usage of the aoconnect development library
Connection methods to MU/SU/CU and process creation flow
Defining and registering handlers in Lua
Message sending, receiving, and simulation with dryrun
Building practical processes like Key-Value stores
Best practices for secure and reusable AOS development

What is AOS

AOS (Actor Operating System) is a Lua-based distributed actor execution environment developed as the first implementation of the AO protocol.
It faithfully implements the actor model and messaging structures defined by AO, designed to enable anyone to easily build and deploy actor-based applications.

AOS has the following characteristics:

Lightweight Lua Runtime

Lua is an extremely lightweight scripting language also used for embedded applications, making it easy to compile to Wasm.

Full Actor Model Support

Each process has independent state and an inbox, communicating with each other through asynchronous messages.

Arweave-based Persistence

Process state and message history are permanently stored on Arweave and can be restored at any time.

Dynamic Logic Registration via Eval

Even after deployment, you can flexibly extend or modify logic by sending Lua scripts to processes.

Complete Automation via Scripts

Process creation, manipulation, and testing can all be controlled from JavaScript through the aoconnect library.

AOS is the ideal entry point for understanding AO's fundamental concepts and quickly building your own distributed actor applications.
In this chapter, we'll learn the complete flow of process development using AOS with actual code examples.

AOS Setup

AOS is one of the first implementations of AO and uses the Lua language.
To use AOS, first install the aoconnect library.

npm i @permaweb/aoconnect

Connecting to Units

To use AOS in a local environment, connect by specifying the URLs for each unit (MU/SU/CU).

const { createDataItemSigner, connect } = require("@permaweb/aoconnect");
const { result, message, spawn, dryrun } = connect({
  MU_URL: "http://localhost:4002",
  CU_URL: "http://localhost:4004",
  GATEWAY_URL: "http://localhost:4000",
});

For mainnet usage, you can connect simply as follows:

const { result, message, spawn, dryrun } = require("@permaweb/aoconnect");

Spawning an AOS Process

To spawn an AOS process, you need the AOS module ID and scheduler wallet address.
Here's the basic code for spawning a process:

const wait = (ms) => new Promise((res) => setTimeout(() => res(), ms));

const pid = await spawn({
  module: AOS_MODULE_TXID, // The module transaction ID you noted earlier
  scheduler: SCHEDULER_WALLET, // Scheduler wallet address
  signer: createDataItemSigner(jwk),
});

await wait(1000);

console.log(`Generated Process ID: ${pid}`);

Once an AO process is spawned, it exists permanently on Arweave and can receive and process messages.

Lua Handler Basics

In AOS, you write process business logic using the Lua language.
The concept of "handlers" is particularly important.
Handlers are functions that execute when a message matching specific conditions is received.

AOS provides the following global variables and modules:

Inbox: Table storing unprocessed messages
Send: Function for sending messages
Spawn: Function for spawning new processes
Handlers: Table for managing handlers
ao: Module providing process information and message sending functionality
json: Module for JSON encoding/decoding

Here's the basic structure of a handler:

Handlers.add(
  "handler-name",  -- Handler identifier
  function(msg)    -- Matching function: determines if a message should be processed by this handler
    return msg.Action == "specific-action"  -- Returns true if condition matches
  end,
  function(msg)    -- Handler function: processes the message
    -- Logic to process the message
    ao.send({Target = msg.From, Data = "response message"})
  end
)

Handlers.utils provides commonly used matching functions:

-- Match messages with matching tags
Handlers.utils.hasMatchingTag("Action", "Get")

-- Match messages with matching data
Handlers.utils.hasMatchingData("ping")

-- Utility for easily sending responses
Handlers.utils.reply("pong")

Creating and Registering Handlers

Let's implement a simple Key-Value store here.
Save the following Lua code to a kv-store.lua file:

local ao = require('ao')
Store = Store or {}

Handlers.add(
   "Get",
   Handlers.utils.hasMatchingTag("Action", "Get"),
   function (msg)
      assert(type(msg.Key) == 'string', 'Key is required!')
      ao.send({ Target = msg.From, Tags = { Value = Store[msg.Key] }})
   end
)

Handlers.add(
   "Set",
   Handlers.utils.hasMatchingTag("Action", "Set"),
   function (msg)
      assert(type(msg.Key) == 'string', 'Key is required!')
      assert(type(msg.Value) == 'string', 'Value is required!')
      Store[msg.Key] = msg.Value
      Handlers.utils.reply("Value stored!")(msg)
   end
)

To add this code to an existing process, use the Eval action as follows:

const { readFileSync } = require("fs");
const { resolve } = require("path");

const lua = readFileSync(resolve(__dirname, "kv-store.lua"), "utf8");
const mid = await message({
  process: pid,
  signer: createDataItemSigner(jwk),
  tags: [{ name: "Action", value: "Eval" }],
  data: lua,
});

const res = await result({ process: pid, message: mid });
console.log(res);

This adds Key-Value store functionality to the process.

Sending and Receiving Messages

To send messages to a process, use the message function:

const mid1 = await message({
  process: pid,
  signer: createDataItemSigner(jwk),
  tags: [
    { name: "Action", value: "Set" },
    { name: "Key", value: "test" },
    { name: "Value", value: "abc" },
  ],
});
const res1 = await result({ process: pid, message: mid1 });
console.log(res1.Messages[0]);

For read-only queries, using the dryrun function is efficient:

const res2 = await dryrun({
  process: pid,
  signer: createDataItemSigner(jwk),
  tags: [
    { name: "Action", value: "Get" },
    { name: "Key", value: "test" },
  ],
});
console.log(res2.Messages[0].Tags);

dryrun doesn't actually save messages to Arweave and simulates using the current state, making it suitable for read operations.

Development Patterns and Best Practices

Here are some best practices for AOS development:

State Management:

When using global variables, don't forget initialization (Store = Store or {})
Manage large data structures with proper nesting

Error Handling:

Use assert to validate inputs
Make error messages specific and clear

Modularization:

Group related functionality together
Create reusable functions

Debugging:

Use the ao.log function to output debug information
Output complex data structures to logs using json.encode

Security:

Always validate untrusted data
Perform authentication checks for critical operations

Testing:
- Create dedicated processes for testing
- Use dryrun to verify changes before applying to production

Following these practices will help you develop safer and more efficient AOS applications.

Arweave AO Bootcamp 5/8 AOS Fundamental

KYOHEI ITO — Wed, 04 Jun 2025 01:10:42 +0000

What You'll Learn in This Chapter

In this chapter, you'll learn how to develop with AOS (Actor Operating System) — the first implementation of the AO protocol.
AOS is a lightweight, Lua-based actor runtime that combines the actor model, persistent storage, and decentralized messaging into a new execution paradigm.

Through hands-on examples, you’ll walk through the full lifecycle: spawning a process → registering logic → sending and receiving messages.

By the end of this chapter, you'll understand:

What AOS is and how to use the aoconnect library
How to connect to MU, SU, and CU in a local setup
How to write and register Lua handlers for message processing
How to send messages and simulate reads using dryrun
How to build a simple yet practical process like a key-value store
Best practices for writing secure, modular, and reusable AOS logic

What is AOS?

AOS (Actor Operating System) is the first implementation of the AO protocol — a Lua-based, distributed actor runtime.
It faithfully implements AO’s actor model and messaging architecture, enabling developers to easily build and deploy actor-driven applications on top of Arweave.

Key characteristics of AOS include:

Lightweight Lua Runtime: Lua is a minimal and embeddable scripting language, ideal for compiling to WebAssembly and running in distributed environments.
Full Actor Model Support: Each process maintains its own isolated state and inbox, communicating asynchronously via message passing.
Arweave-Based Persistence: Process states and message histories are permanently stored on Arweave and can be restored at any time.
Dynamic Logic with Eval: After deployment, logic can be extended or updated dynamically by sending Lua scripts to the process using the Eval action.
Fully Scriptable via JavaScript: With the aoconnect library, every part of the development lifecycle — from spawning processes to sending messages — can be controlled programmatically.

AOS serves as an ideal entry point for learning AO’s architecture and rapidly prototyping your own decentralized actor applications.
In this chapter, you’ll explore the entire workflow of building with AOS through hands-on code examples.

AOS Fundamentals

Setting Up AOS

AOS is one of the first implementations of AO and uses the Lua programming language. To begin using AOS, install the aoconnect library:

npm i @permaweb/aoconnect

Connecting to Units

To use AOS in a local environment, connect to each AO unit (MU, SU, CU) by specifying their URLs:

const { createDataItemSigner, connect } = require("@permaweb/aoconnect");
const { result, message, spawn, dryrun } = connect({
  MU_URL: "http://localhost:4002",
  CU_URL: "http://localhost:4004",
  GATEWAY_URL: "http://localhost:4000",
});

To connect to the mainnet, a simple import is sufficient:

const { result, message, spawn, dryrun } = require("@permaweb/aoconnect");

Spawning an AOS Process

To spawn an AOS process, you need the transaction ID of the AOS module and the address of a scheduler wallet:

const wait = (ms) => new Promise((res) => setTimeout(() => res(), ms));

const pid = await spawn({
  module: AOS_MODULE_TXID, // Transaction ID of the module
  scheduler: SCHEDULER_WALLET, // Address of the scheduler wallet
  signer: createDataItemSigner(jwk),
});

await wait(1000);

console.log(`Spawned process ID: ${pid}`);

Once the AO process is spawned, it exists permanently on Arweave and can start processing messages.

Basics of Lua Handlers

In AOS, Lua is used to define the business logic of each process. The core concept is the handler—a function triggered when a message matches specific criteria.

AOS provides the following global variables and modules:

Inbox: A table holding unprocessed messages
Send: A function to send messages
Spawn: A function to create new processes
Handlers: A table to register and manage handlers
ao: A module providing process-related utilities
json: Module for JSON encoding/decoding

Basic handler structure:

Handlers.add(
  "handler_name",
  function(msg)
    return msg.Action == "some_action"
  end,
  function(msg)
    ao.send({ Target = msg.From, Data = "response message" })
  end
)

Common utility matchers from Handlers.utils:

Handlers.utils.hasMatchingTag("Action", "Get")
Handlers.utils.hasMatchingData("ping")
Handlers.utils.reply("pong")

Creating and Registering a Handler

Here’s how to implement a simple key-value store. Save the following Lua code as kv-store.lua:

local ao = require('ao')
Store = Store or {}

Handlers.add(
   "Get",
   Handlers.utils.hasMatchingTag("Action", "Get"),
   function (msg)
      assert(type(msg.Key) == 'string', 'Key is required!')
      ao.send({ Target = msg.From, Tags = { Value = Store[msg.Key] }})
   end
)

Handlers.add(
   "Set",
   Handlers.utils.hasMatchingTag("Action", "Set"),
   function (msg)
      assert(type(msg.Key) == 'string', 'Key is required!')
      assert(type(msg.Value) == 'string', 'Value is required!')
      Store[msg.Key] = msg.Value
      Handlers.utils.reply("Value stored!")(msg)
   end
)

To add this code to a running process, use the Eval action:

const { readFileSync } = require("fs");
const { resolve } = require("path");

const lua = readFileSync(resolve(__dirname, "kv-store.lua"), "utf8");
const mid = await message({
  process: pid,
  signer: createDataItemSigner(jwk),
  tags: [{ name: "Action", value: "Eval" }],
  data: lua,
});

const res = await result({ process: pid, message: mid });
console.log(res);

Sending and Receiving Messages

Use the message function to send data to a process:

const mid1 = await message({
  process: pid,
  signer: createDataItemSigner(jwk),
  tags: [
    { name: "Action", value: "Set" },
    { name: "Key", value: "test" },
    { name: "Value", value: "abc" },
  ],
});
const res1 = await result({ process: pid, message: mid1 });
console.log(res1.Messages[0]);

Use dryrun for read-only queries without writing to Arweave:

const res2 = await dryrun({
  process: pid,
  signer: createDataItemSigner(jwk),
  tags: [
    { name: "Action", value: "Get" },
    { name: "Key", value: "test" },
  ],
});
console.log(res2.Messages[0].Tags);

Development Patterns and Best Practices

Here are some best practices for building with AOS:

State Management:

Always initialize global variables (e.g., Store = Store or {})
Structure large state data appropriately

Error Handling:

Use assert to validate inputs
Provide clear, descriptive error messages

Modularization:

Group related logic together
Create reusable functions when possible

Debugging:

Use ao.log for debugging output
Use json.encode to log complex structures

Security:

Always validate untrusted input
Implement authentication for critical actions

Testing:

Create separate processes for testing
Use dryrun to simulate changes before committing them

Following these practices will help you develop safer and more efficient AOS applications.

Arweave AO Bootcamp 4/8 AO Fundamentals

KYOHEI ITO — Wed, 04 Jun 2025 01:09:45 +0000

What You'll Learn in This Chapter

In this chapter, you'll dive into the core concepts behind AO (Actor Oriented) — a new paradigm in decentralized computing.
Unlike traditional smart contracts, AO is designed as a hyper-parallel, infinitely scalable decentralized supercomputer.

Understanding AO at its foundation is essential before moving on to more advanced topics like AOS and building custom VMs.

By the end of this chapter, you'll understand:

What AO is, and why it was created
The fundamentals of the Actor Model and message-driven concurrency
AO's system architecture (Messenger, Scheduler, and Compute Units)
How Wasm modules work in AO and how they support multiple programming languages
The big picture of AO's token design and security model

Grasping these fundamentals will give you a clear perspective on why AO could become the next generation of smart contract infrastructure.

AO Fundamentals

What is AO?

AO stands for Actor Oriented, and it refers to a decentralized, hyper-parallel supercomputer built on top of Arweave. Unlike traditional smart contracts running on blockchains, AO is designed to scale horizontally without limits.

Key features of AO include:

Parallel Execution: Thousands of processes can run concurrently.
Message Passing: All communication between actors happens via messages.
Scalability: Designed for theoretically unlimited horizontal scaling.
Modularity: Supports various languages and virtual machines.
Arweave Persistence: All data and state are permanently stored on Arweave.

AO itself is a protocol with open and diverse implementations. One of the first implementations is AOS, which is based on the Lua programming language.

The Actor Model & Messaging

AO uses the Actor Model, a computing paradigm introduced by Carl Hewitt in 1973. It models concurrent computation using independent "actors."

Core properties of the actor model:

Actors: Fundamental units of computation, each with its own state and mailbox.
Message Passing: All communication between actors is message-based.
Asynchronous Processing: Message handling is non-blocking and asynchronous.
Encapsulated State: Actors manage their own state, which cannot be accessed directly by others.
Spawning: Actors can dynamically create new actors.

Unlike traditional object-oriented programming, the actor model eliminates shared memory and relies solely on message-passing, dramatically simplifying concurrency.

In AO, each process (actor) can send messages to other processes. These messages can contain both data and arbitrary tags for contextual information.

AO Architecture

The AO system is composed of three main components:

Messenger Unit (MU): Receives, verifies, and routes incoming messages.
Scheduler Unit (SU): Orders messages and stores them on Arweave.
Compute Unit (CU): Processes messages and updates the actor's state.

These components are loosely coupled and operate independently, enabling flexible and scalable system design.

The typical data flow is as follows:

A user sends a message to the MU.
The MU verifies the message and forwards it to the appropriate SU.
The SU timestamps and stores the message on Arweave.
The CU fetches and executes the message, updating state accordingly.
If necessary, the output is passed back to the MU for further processing.

This architecture is key to AO's scalability and flexibility.

Basics of Wasm Modules

AO processes are executed using WebAssembly (Wasm) modules. Wasm is a compact binary format that allows code to run at near-native speed and can be compiled from multiple languages.

Key features of Wasm:

High Performance: Nearly native execution speed.
Compact Size: Small binaries enable efficient network transfer.
Language Agnostic: Supports C/C++, Rust, Go, and more.
Sandboxed: Provides a secure execution environment.
Memory Limits: Wasm32 has a 4GB limit, while Wasm64 supports up to 16GB.

AOS uses Lua compiled to Wasm, but AO supports alternative VMs and languages. In the latter half of this tutorial, we'll implement a custom JavaScript-based VM as an example.

AO's Economic Model

AO tokens play a central role in incentivizing and securing the network. Key features include:

Fixed Supply: Capped at 21 million tokens, similar to Bitcoin.
Automatic Distribution: Tokens are distributed every 5 minutes.
Split Allocation:

33.3% to AR token holders
66.6% to aoETH holders

Halving Schedule: Follows a Bitcoin-like halving model.

These tokens ensure network security and reward contributors. Specifically, staking via the AO-Sec Origin process and operator stakes (for SU/MU/CU) help maintain network integrity.

AO's Security Model

AO’s security is maintained through two core mechanisms:

AO-Sec Origin: Provides the basic staking and slashing mechanism for malicious behavior.
Sybil-resistant Incentivized Validation (SIV): A multi-validator approach to prevent Sybil attacks.

AO-Sec Origin ensures that actors who host or sequence processes behave honestly — if they don't, their stake can be slashed.

SIV involves multiple independent validators verifying results, making it extremely difficult for a single malicious node to manipulate outcomes.

Together, these systems provide both robust security and high scalability for AO.

Arweave AO Bootcamp 3/8 Arweave Fundamentals

KYOHEI ITO — Wed, 04 Jun 2025 01:08:36 +0000

What You'll Learn in This Chapter

In this chapter, you'll learn the fundamentals of Arweave and how to interact with it.
Arweave is a blockchain-based decentralized storage protocol that enables truly permanent data storage — once uploaded, your data lives on forever.

This section lays the foundational skills you’ll need to build AO applications on top of Arweave.

By the end of this chapter, you’ll be able to:

Understand Arweave's core architecture (Blockweave, SPoRA, and more)
Connect to a local Arweave gateway and generate wallets
Mint and send AR tokens, and check wallet balances
Save arbitrary data (text, images) to Arweave
Use GraphQL to query and retrieve transaction metadata
Bundle and nest transactions for scalable batch processing

Mastering these basics will give you a concrete understanding of how to design and build robust data layers for decentralized applications.

Arweave Fundamentals

Arweave as Decentralized Storage

Arweave is a blockchain-based decentralized storage network that enables the "Permaweb." Unlike traditional blockchains or storage systems, Arweave has several unique features:

Permanent Storage with One-Time Payment: Once data is uploaded and paid for, it remains permanently stored. No recurring fees required!
Blockweave Structure: Unlike the linear structure of traditional blockchains, Arweave uses a "blockweave" which allows more efficient data access and validation.
SPoRA (Succinct Proofs of Random Access): Miners must prove they can access randomly selected past data, ensuring stored data remains available and verifiable.
Data Permanence and Availability: Arweave is designed to "never forget." Data is permanently stored and protected from tampering.
Economic Sustainability: Through its endowment mechanism, Arweave leverages decreasing storage costs over time to support long-term data persistence.

Thanks to these features, Arweave is especially suitable for archiving, censorship-resistant content, and preserving long-term historical records.

Connecting to the Arweave Gateway

First, install the Arweave JavaScript library:

npm i arweave

Then, connect to the local Arweave gateway:

const arweave = require("arweave").init({ port: 4000 });

To connect to the mainnet, use the default settings:

const arweave = require("arweave").init();

Creating an Arweave Wallet

Arweave accounts use RSA key pairs. Wallet addresses are SHA-256 hashes of public keys and are 43 characters long. Keys are usually generated in JWK format:

const addr = async (jwk) => arweave.wallets.jwkToAddress(jwk);

const gen = async () => {
  const jwk = await arweave.wallets.generate();
  return { jwk, addr: await addr(jwk) };
};

A generated JWK will look like this:

{
  "kty": "RSA",
  "n": "o1kvT...",
  "e": "AQAB",
  "d": "Ohpdn...",
  "p": "ymLt9...",
  "q": "zp7X_...",
  "dp": "pyN6W...",
  "dq": "wkpHn....",
  "qi": "Zvbxf..."
}

Here, n is the public key, and d is the private key. The other fields (p, q, dp, dq, qi) are used to optimize cryptographic operations.

Minting AR Tokens

In local environments (ArLocal), AR tokens can be minted freely. Note that you must manually call the /mine API to confirm transactions.

const mine = async () => await arweave.api.get(`/mine`);

const bal = async (addr) => {
  return arweave.ar.winstonToAr(await arweave.wallets.getBalance(addr));
};

const mint = async (addr, amount = "1.0") => {
  await arweave.api.get(`/mint/${addr}/${arweave.ar.arToWinston(amount)}`);
  await mine();
  return await bal(addr);
};

Example usage:

const { jwk, addr } = await gen();
const balance = await mint(addr, "10.0");
console.log(`New wallet balance: ${balance} AR`);

Sending AR Tokens

The basic flow for sending tokens involves createTransaction, sign, and post. For a transfer, specify target and quantity:

const postTx = async (tx, jwk) => {
  await arweave.transactions.sign(tx, jwk);
  await arweave.transactions.post(tx);
  await mine();
  return tx.id;
};

const transfer = async (amount, to, jwk) => {
  let tx = await arweave.createTransaction({
    target: to,
    quantity: arweave.ar.arToWinston(amount),
  });
  return await postTx(tx, jwk);
};

Example usage:

const { addr: addr1, jwk } = await gen();
const { addr: addr2 } = await gen();
await mint(addr1, "1.0");
const txid = await transfer("0.5", addr2, jwk);
console.log(`Transfer transaction ID: ${txid}`);

Saving Data

You can save raw data to Arweave directly. Here's an example of saving Markdown text:

const saveMD = async (md, jwk) => {
  let tx = await arweave.createTransaction({ data: md });
  tx.addTag("Content-Type", "text/markdown");
  return await postTx(tx, jwk);
};

Example usage:

const txid = await saveMD("# This is markdown", jwk);
console.log(`Saved markdown TX ID: ${txid}`);

To save image data (like base64-encoded SVG):

const saveSVG = async (svg, jwk) => {
  let tx = await arweave.createTransaction({
    data: Buffer.from(svg, "base64"),
  });
  tx.addTag("Content-Type", "image/svg+xml");
  return await postTx(tx, jwk);
};

const ao = "<base64-encoded-SVG>";
const txid = await saveSVG(ao, jwk);
console.log(`Saved SVG TX ID: ${txid}`);

Querying Transactions with GraphQL

One of Arweave's strongest features is its ability to tag transactions and query them with GraphQL:

const q = (txid) => `query {
  transactions(ids: ["${txid}"]) {
    edges {
      node { id tags { name value } owner { address } }
    }
  }
}`;

const getTx = async (txid) => {
  const json = await fetch("http://localhost:4000/graphql", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: q(txid) }),
  }).then((r) => r.json());
  return json.data.transactions.edges.map((v) => v.node)[0];
};

Example usage:

const tx = await getTx(txid);
console.log(tx);

To retrieve the actual data:

// Using arweave.js
const data = await arweave.transactions.getData(txid, {
  decode: true,
  string: true,
});

// Using HTTP request
const data = await fetch(`http://localhost:4000/${txid}`).then((r) => r.text());

Nesting and Bundling Transactions

Using the ANS-104 Bundled Data v2.0 spec, Arweave allows multiple transactions to be nested and bundled into a single one:

npm i arbundles

const { ArweaveSigner, bundleAndSignData, createData } = require("arbundles");

const bundle = async (_items, jwk) => {
  const signer = new ArweaveSigner(jwk);
  const items = _items.map((v) => {
    let tags = [];
    for (const k in v[1] || {}) tags.push({ name: k, value: v[1][k] });
    return createData(v[0], signer, { tags });
  });
  const bundle = await bundleAndSignData(items, signer);
  const tx = await bundle.toTransaction({}, arweave, jwk);
  await postTx(tx, jwk);
  return { items, tx };
};

Example usage:

const { items, tx } = await bundle(
  [
    ["# This is markdown!", { Content_Type: "text/markdown" }],
    [Buffer.from(ao, "base64"), { Content_Type: "image/svg+xml" }],
  ],
  jwk
);
console.log(`Bundled transaction ID: ${tx.id}`);

This bundling feature is one of the core underpinnings of the AO protocol.

Arweave AO Bootcamp 2/8 Setup

KYOHEI ITO — Wed, 04 Jun 2025 01:07:10 +0000

What You'll Learn in This Chapter

In this chapter, you will learn how to prepare your local development environment for AO and Arweave.
Specifically, you will gain hands-on experience with starting up local nodes using Docker, downloading the AOS module, and generating the required wallets.

You will also understand the roles and functions of each AO unit (MU, SU, CU).
Grasping how these units collaborate to enable scalable distributed computing will provide a solid foundation for your further development.

Setup: Preparing Your Local Development Environment

To start building with AO and Arweave, you'll first need to set up your local development environment.
This tutorial assumes you have NodeJS v22 and Docker installed.

Clone the localnet repository and start the services:

git clone -b hotfix https://github.com/weavedb/ao-localnet.git
cd ao-localnet/wallets && ./generateAll.sh
cd ../ && sudo docker compose --profile explorer up

Once the Docker services are up, the following local nodes will be available:

ArLocal: localhost:4000 – Local Arweave gateway
GraphQL: localhost:4000/graphql – GraphQL interface for Arweave
Scar: localhost:4006 – Local Arweave explorer
MU (Messenger Unit): localhost:4002 – Handles messaging within AO
SU (Scheduler Unit): localhost:4003– Schedules process execution
CU (Compute Unit): localhost:4004 – Executes computation workloads

Next, download the AOS Wasm module and generate the required wallets for interacting with AO units:

nvm use 22
cd ao-localnet/seed && ./download-aos-module.sh
./seed-for-aos.sh
cd ../wallets && node printWalletAddresses.mjs

The last command will print all wallet addresses to the console.
Make sure to note down the address for the Scheduler Wallet, as you’ll need it later in this tutorial.

What Does Each Unit Do?

AO operates through a set of modular components called units. Each unit runs as an independent WASM process and handles a specific role in the system. Together, they enable scalable and composable distributed computation.

Here’s a quick breakdown of the core units:

Unit	Name	Role Description
MU	Messenger Unit	Handles the sending and receiving of messages between processes. It’s the communication hub of AO.
SU	Scheduler Unit	Manages the scheduling and execution timing of processes. It ensures tasks run in the correct order.
CU	Compute Unit	Executes the actual logic and handlers. This is where computation happens.

This modular structure is what makes AO so powerful — it allows you to build custom, parallelized computing flows tailored to your application's needs.

Arweave AO Bootcamp 1/8 Introduction

KYOHEI ITO — Wed, 04 Jun 2025 00:58:34 +0000

Welcome to Arweave AO Bootcamp — a practical, in-depth guide to building with Arweave, the decentralized permanent storage layer, and AO, the hyper-parallel computing protocol built on top of it.

Whether you're new to decentralized infrastructure or already experimenting with on-chain compute, this tutorial series will walk you through everything from setup to advanced applications — step by step, with real code.

Why Arweave and AO?

Modern decentralized applications demand more than just immutable storage or simple contract execution. They require scalable compute, rich messaging, and developer-friendly tools — all without compromising decentralization.

This is exactly what Arweave + AO delivers:

Arweave offers permanent data storage with a one-time payment, no subscriptions, and no centralized dependencies. It’s a censorship-resistant, infinitely scalable data layer.
AO is a decentralized supercomputer built on Arweave, powered by an actor model that enables unlimited parallelism and composable units of execution.

Together, they form a new kind of decentralized stack — one capable of supporting applications at Web2 scale, with the resilience and openness of Web3.

What Makes AO Special?

AO is more than an execution environment — it’s an ecosystem.

Secured by Ethereum L1 restaking, the protocol has reached nearly \$1B in TVL within months of launch.
Its fair-launch token model ensures that liquidity flows directly to builders.
AO tokens are distributed on a Bitcoin-style halving schedule, rewarding long-term contributions from developers and operators.

AO isn't just another blockchain. It's the first decentralized protocol designed for real, production-grade compute.

What You'll Learn in This Bootcamp

Through hands-on tutorials and real-world examples, you’ll learn how to:

Set up a local development environment
Interact with Arweave (wallets, tokens, storage)
Build actor-based applications using AOS
Create and deploy your own custom VM
Understand AO’s token incentives and system architecture

No prior experience with Arweave or AO is required — but by the end of this series, you’ll be ready to ship your first decentralized app on this next-gen stack.

Let’s begin our journey into permanent storage and infinite compute.

ao-bootcamp/
├── arweave-fundamentals/                    # Arweave Basics
│   ├── decentralized-storage.md             # Arweave as Decentralized Storage
│   ├── gateway-connection.md                # Connecting to the Arweave Gateway
│   ├── wallet-setup.md                      # Creating an Arweave Wallet
│   ├── mint-ar-token.md                     # Minting AR Tokens
│   ├── send-ar-token.md                     # Sending AR Tokens
│   ├── save-data.md                         # Saving Data Permanently
│   ├── query-graphql.md                     # Fetching Transactions with GraphQL
│   └── bundle-transactions.md               # Nesting & Bundling Transactions
│
├── ao-fundamentals/                         # AO Basics
│   ├── what-is-ao.md                        # What is AO?
│   ├── actor-model.md                       # Actor Model & Messaging
│   ├── architecture.md                      # AO Architecture Overview
│   ├── wasm-modules.md                      # Intro to Wasm Modules
│   ├── economy.md                           # AO Economic Model
│   └── security.md                          # AO Security Model
│
├── aos-getting-started/                     # Getting Started with AOS
│   ├── setup.md                             # Setting Up AOS
│   ├── connect-units.md                     # Connecting to Units
│   ├── spawn-process.md                     # Spawning AOS Processes
│   ├── lua-handlers.md                      # Basics of Lua Handlers
│   ├── register-handlers.md                 # Creating & Registering Handlers
│   ├── messaging.md                         # Sending & Receiving Messages
│   └── best-practices.md                    # Dev Patterns & Best Practices
│
├── custom-vm/                               # Building Your Own VM
│   ├── loader.md                            # AO Loader Fundamentals
│   ├── messenger-unit.md                    # Implementing a Messenger Unit
│   ├── compute-unit.md                      # Implementing a Compute Unit
│   ├── register-js.md                       # Registering JavaScript Modules
│   └── test-process.md                      # Creating & Testing a Process
│
├── token-design/                            # AO Token Design
│   ├── principles.md                        # Core Principles of AO Tokens
│   ├── ar-vs-ao.md                          # Relationship Between AR and AO Tokens
│   ├── aoeth-and-bridges.md                 # aoETH and Bridged Assets
│   └── dev-incentives.md                    # Token Incentives for Developers

What is Arweave Japan?

Arweave Japan is a decentralized organization that aims to build a Japanese builder ecosystem for Arweave / AO.

Social Links:

Blog:

Arweave Japan Launch

KYOHEI ITO — Mon, 02 Jun 2025 02:33:57 +0000

Arweave Japan is a decentralized organization dedicated to building a Japanese-language builder ecosystem for Arweave/AO.

Mission

Train numerous hackers who can leverage Arweave/AO for diverse development projects
Launch multiple global top-tier projects from the Japanese ecosystem
Attract global top-tier projects to the Japanese ecosystem
Promote adoption of Arweave/AO products among general users, enterprises, and government agencies

Roadmap

Through the following rough schedule, we aim to launch at least 10 top AO projects from Japan that achieve global recognition.

Hyper Parallel Tokyo Event | Arweave Japan Kickoff (July 27, 2024)
AO Bootcamp (August 2024)
AO Hackathon (September 2024)
Official Arweave Japan Conference (Spring 2025)

Ecosystem Projects

WeaveDB A hyperscalable decentralized NoSQL database utilizing AO and zero-knowledge proofs. https://github.com/weavedb/weavedb

zkJSON Enables universal proof generation for JSON using zero-knowledge proofs, allowing data retrieval from AO databases by other blockchains. https://github.com/weavedb/zkjson

CosmWasm AO A smart contract platform on AO that supports development with CosmWasm/Rust. https://github.com/weavedb/cosmwasm-ao

ArNext A NextJS-based web framework enabling parallel deployment to Vercel and Arweave. https://github.com/weavedb/arnext

Atomic Notes Editable notes leveraging atomic assets and universal data licensing. https://github.com/weavedb/atomic-notes

MostAO A social protocol that optimizes Nostr to run on AO and enables message encryption. https://github.com/Ungigdu/MostAO

Project Development Process

AO/Arweave Development Learning: Learn AO/Arweave development through tutorials, workshops, and bootcamps.
Idea Exploration: Curate challenges and tools that AO can solve using idea pools, ChatGPT, etc.
MVP Development: Select technologies and design to implement a minimal viable product that can be demonstrated publicly.
Demo Release: Share the developed MVP along with the vision through demo days, blog posts, X, etc.
Team Formation: Form a founding team with the skill set to handle global development, fundraising, and ecosystem building.
Fundraising: Bootstrap using AO protocol mechanisms, register a corporation, and raise pre-seed funding.
Token Design: Design tokens for long-term sustainability.
Momentum: Launch the product and design momentum strategy.
Growth: Expand user base, TVL, and market cap.

Seeking Ecosystem Partners

Arweave Japan is seeking ecosystem partners interested in Arweave/AO development. We offer:

Development idea validation
Technical support
Fundraising support
Global expansion support
Preferential access to ecosystem events

What are Arweave/AO?

Arweave is an infinitely scalable decentralized storage system, and AO is an infinitely scalable decentralized supercomputer built on Arweave. Using Arweave and AO, you can develop practical products that were impossible with existing blockchains. Security is ensured through Ethereum L1 restaking, and TVL has reached nearly 100 billion yen within months of launch, with expectations of a multi-trillion yen market. Through AO's fair launch token design, this liquidity can be utilized by projects on AO, and AO tokens, which are minted on the same halving schedule as Bitcoin, can be received by developers and projects. Developing on AO, a unique decentralized protocol capable of building practical projects that could replace Web2, presents a significant opportunity to excel on the global stage.

What is Arweave?

A decentralized storage protocol that enables semi-permanent data storage through advanced algorithmic game theory. The $AR token design ensures data storage for at least 200 years with a one-time, affordable fee paid at storage time. The design achieves unlimited storage scalability through efficient PoW and SPoRA (Succinct Proof of Random Access), which incorporates data sampling mechanisms.

What is AO?

A decentralized computation protocol utilizing Arweave storage. It solves existing blockchain scalability issues through asynchronous messaging with the actor model and programmable security with PoS, creating an infinitely scalable decentralized supercomputer. Security is ensured through Ethereum L1 restaking and the fair launch token $AO, which follows Bitcoin's halving schedule. Concepts like SCP (Storage-based Consensus Paradigm) and holographic state enable affordable, infinitely scalable smart contracts and decentralized VMs.

What can be developed?

Existing blockchain bottlenecks involve high storage and computation costs that prevent scaling. Arweave/AO has solved these two challenges, realizing infinitely scalable decentralized permanent storage and parallel computing. This enables development of practical applications that can scale to Web levels (previously impossible in Web3), integration of AI with DeFi and decentralized infrastructure, and groundbreaking protocols utilizing zero-knowledge proofs and FHE (Fully Homomorphic Encryption).

Social Links

Blog】

ConvictionFi | Mint your Conviction. DeFAI Agent as NFT [Sui Overflow Hackathon 2025]

KYOHEI ITO — Fri, 30 May 2025 07:28:58 +0000

Project Overview

ConvictionFi offers a new paradigm for realizing the vision of DeFi × AI (DeFAI). With a single NFT mint, users can delegate conviction-based investing to an autonomous AI agent.

Product Type: DeFAI NFT Protocol
Tagline: “Mint Your Conviction. DeFAI Agent as NFT.”
Target Audience: Beginner to intermediate DeFi users, ideologically-driven investors, Web3 natives

PROBLEM: DeFAI Is Just a Buzzword

Terms like “DeFAI” and “Vibe Trading” are everywhere—but they lack substance.

Most so-called DeFAI products suffer from vague use cases, fragmented user experiences, and an overall lack of clarity about what it actually means to "use DeFAI."

SOLUTION: DeFAI Agent as NFT

We built a complete, intuitive experience: the DeFAI Agent as an NFT.

Users simply mint an NFT
That NFT becomes a standalone AI agent managing the user’s capital
No dashboards. No approvals. No ongoing management

USER FLOW: Just Mint NFT

ConvictionFi follows a 5-step lifecycle.

Only Step 1 requires your input — from Step 2 onward, your agent takes over.

Mint Your Conviction

Choose a belief. Mint the NFT. That’s it.
NFT = AI Agent

The NFT becomes an autonomous, on-chain trader.
Autonomous Execution

The agent trades, stakes, or lends — no input needed.

All activity is publicly reported.
Learn & Evolve

The agent adapts based on market signals or strategy upgrades.
Exit or Transfer

Withdraw via protocol rules — or sell the NFT on secondary markets.

Sample Strategy

SUI_MAXIMIZER
- Aggressive accumulation of SUI and ecosystem tokens during market dips
- Ideological Thesis: "Sui represents the future of blockchain scalability. Every dip is an opportunity to accumulate before mass adoption."
BTC_HODLER
- Long-term Bitcoin accumulation with DCA and volatility exploitation
- Ideological Thesis: "Bitcoin is digital gold and the ultimate store of value. Time in market beats timing the market."
STABLE_OPTIMIZER
- Conservative yield optimization across stable pools and lending protocols
- "Consistent yield generation with capital preservation. Compound interest is the eighth wonder of the world."

SECURUTY MODEL: Why We Never Touch Your Wallet

Most DeFi apps require direct wallet transactions, creating unnecessary risk and inconvenience.

ConvictionFi uses a different approach: your minted NFT becomes both entry point and autonomous firewall.

The minting price becomes your trading budget — no additional deposits or approvals needed
Each NFT generates its own isolated smart wallet, completely separate from your personal funds
Only the NFT agent signs transactions and takes action

Your risk is compartmentalized, your conviction tokenized, and your NFT thinks and acts independently — keeping your wallet safe.

TECHINICAL ARCHITECTURE: Walrus x NFT x AI

ConvictionFi leverages Walrus decentralized storage to ensure immutable and transparent NFT metadata for conviction-based trading agents.

Each Conviction NFT stores comprehensive data on Walrus including:

Strategy parameters and logic
Conviction statements and reasoning
Risk limits and execution policies
Agent version history and mint timestamps

The system utilizes Walrus's key features:

Content-addressed storage with verifiable CIDs for data integrity
Permanent append-only architecture preventing deletions or secret alterations
Full transparency allowing anyone to inspect metadata via URI

This approach ensures complete audit trails as trading agents evolve through versioned updates.

Each NFT contains a Walrus metadata URI that points to the latest version while preserving access to historical versions for verification.

The JSON-formatted data includes strategy details, risk profiles, whitelisted contracts, and execution policies.

Since Walrus is append-only, strategy upgrades create new versions rather than overwriting existing data, ensuring full traceability of agent evolution over time.

This storage solution guarantees transparency, auditability, and future-proofing without requiring large metadata storage directly on-chain, while ensuring all strategy changes remain traceable and potentially subject to governance approval.

Tech Stack

▼ Web3 Layer

Layer1: Sui Network → High-speed, low-cost blockchain. Built on the Move programming language.
Smart Contract: Move Language → Implements core logic for ConvictionNFTs, Agent Wallets, etc.
AI Agent Framework: Sui Agent Kit → On-chain initialization and deployment of AI trading agents.
Storage: Walrus → Stores strategy prompts and metadata (supports both editable and immutable types).
Bridge: Wormhole → Enables cross-chain fund transfers (e.g., ETH/USDC → Sui).
Authentication: Privy → Enables social login and zkLogin for seamless Web2-style onboarding.
NFT Marketplace: Compatible with Sui-based marketplaces (e.g., BlueMove) → Enables secondary trading of ConvictionNFTs.
Token Standards: Sui::NFT, Wallet::Object → Each NFT functions as a wallet and signer with embedded logic.

▼ Web2 / Application Layer

Deployment Platform: Vercel
Database (temporary): Firebase
AI Cloud: Alibaba Cloud
Payment API: Stripe (for fiat-based NFT minting, planned)

▼ Developer Tools & Infrastructure

AI Coding Assistants: ChatGPT, Claude, Cursor, v0.dev
CI/CD Integration: Claude Code GitHub Actions

Links

X(Twitter): https://x.com/ConvictionFi
Slide Deck: https://gamma.app/docs/ConvictionFi-yicndaml629ajp0
Demo: https://convictionfi.vercel.app/
Founder: https://www.linkedin.com/in/kyohei-nft/

DeFAI Mint: Vibe Trading as NFT [Breakout Hackathon 2025]

KYOHEI ITO — Sun, 18 May 2025 15:55:42 +0000

TL;DR

DeFAI Mint simplifies DeFi x AI into a single NFT mint.
Mint once, and let your belief become an autonomous trading agent.
Built with Solana, Metaplex Execute, and Solana Agent Kit v2.

Why We Built DeFAI Mint

Crypto has outpaced human capacity.
140,000+ tokens launch every day. Protocols fragment. Volatility never ends.

AI was supposed to help—but it became a tool only the elite can wield.

At DeFAI Mint, we asked:

What if you could access the power of AI in one click?

No learning curve. No wallets. No gas fees.
Just mint an NFT, and that NFT becomes your belief-powered AI agent.

We call this:
Vibe Trading — a radically simplified, conviction-driven investing model.

What Is DeFAI Mint?

DeFAI Mint turns NFTs into autonomous financial agents that trade based on your beliefs.

When you mint a "Belief NFT," you are minting an on-chain agent:

It holds its own wallet
Signs transactions independently
Executes AI-powered strategies
Stores your belief metadata permanently on decentralized storage

Your NFT becomes your AI.
And your conviction becomes your strategy.

Core Features

✅ Zero Configuration UX

No wallet required to mint
No \$SOL required to mint
Twitter login only
UX crafted for crypto-natives and first-timers

🧠 AI Strategy Engine

Each NFT is powered by a modular strategy engine.
Some strategies analyze social media signals. Others mirror ideology-linked tokens.

You don’t manage positions.
You choose what you believe — and let the agent act on it.

🔐 On-Chain Automation

Built using:

Metaplex Execute: On-chain execution environment
Asset Signer: Allows NFTs to sign transactions without private key exposure
Solana Agent Kit v2: AI Agent SDK to automate interactions across Solana dApps

All executed natively on Solana.

Example NFTs

Belief NFT	Strategy
Trump Bet NFT	Long \$TRUMP memecoin after Trump tweets
Solana Forever NFT	Buy \$SOL dips on network drama
AI Apocalypse NFT	Bet on decentralized AI vs centralized AI

Each NFT is more than a JPEG — it's a conviction, encoded as code.

Architecture Overview

[User] → [Mint UI] → [NFT = Wallet + AI Agent]
                         ↓
             [Metaplex Execute + Asset Signer]
                         ↓
          [Vault Registry] + [Strategy Engine]
                         ↓
              [Solana dApps / Token Swaps]

Persistent metadata is stored via Walrus, a decentralized file system optimized for fast, immutable storage.

Why Solana?

Why can’t Ethereum do this?
Because this is only possible with Solana’s native capabilities.

⚡ Blazing Speed: Millisecond execution on volatile trades
🔐 Agent Signer Model: NFTs that sign for themselves
💡 Builder-First Ecosystem: Tools like Agent Kit, Privy, and Walrus accelerate innovation

What’s Next?

We’re opening up DeFAI Mint for early testers.
Upcoming roadmap:

✅ Public Mint UI (Done)
🔜 Strategy Builder Studio (Create your own belief agent)
🔜 Mobile-first Mint experience
🔜 Token incentives + DAO governance

Join the Vibe

Final Words

DeFAI Mint is an experiment at the edge of DeFi, AI, and NFTs.
But more than that, it’s a movement:

Turn beliefs into agents.
Turn agents into assets.
Trade what you believe.

Let’s build the future of conviction investing — one mint at a time.