This repository contains the source code used for Arweave Name Tokens used to resolve ArNS names on AR.IO Gateways. For official documentation on ANT's refer to the ArNS ANT Docs. For official documentation on ArNS refer to the ArNS Docs.

This repository provides two flavours of ANT process module, AOS and a custom module.

• Setup
  • Install
  • Testing
  • Building the AOS code
    • Build
      • Lua code
      • Module WASM Binary
    • Publish
      • Lua code
      • Module WASM Binary
    • Load
      • Lua code
      • Module WASM Binary
    • Spawn
      • Lua code
      • Module WASM Binary
• Handler Methods
  • Boot Methods
    • _boot (WASM Binary only)
  • Read Methods
    • Info
    • Total-Supply
    • State
    • Records
    • Record
    • Controllers
    • Balance
    • Balances
  • Write methods
    • Transfer
    • Set-Record
    • Set-Name
    • Set-Ticker
    • Set-Description
    • Set-Logo
    • Set-Keywords
    • Add-Controller
    • Remove-Controller
    • Remove-Record
    • Release-Name
    • Reassign-Name
• Developers
  • Requirements
  • Lua Setup
    • With local script (MacOS and Linux only)
    • Manually
  • aos
  • Code Formatting
  • Testing
  • Dependencies

First install the npm dependencies

yarn

Then install the ao cli - read the docs here Refer to the docs for installing different versions.

curl -L https://install_ao.arweave.net | bash

You may need to follow the instructions in the cli to add the program to your PATH.

To test the module, you can use the following command to run busted

busted .

This bundles the ant-aos code and outputs it to dist folder. This can then be used to send to the Eval method on AOS to load the ANT source code.

yarn aos:build

yarn module:build

Ensure that in the tools directory you place you Arweave JWK as key.json

yarn aos:publish

yarn module:publish

This will load an AOS module into the loader, followed by the bundled aos Lua file to verify that it is a valid build.

yarn aos:load

yarn module:load

This will spawn an aos process and load the bundled lua code into it.

yarn aos:spawn

yarn module:spawn

This will deploy the bundled lua file or WASM module to arweave as an L2 ([ANS-104]) transaction, so your wallet will need Turbo Credits to pay the gas.

For interacting with handlers please refer to the AR.IO SDK or the AO Cookbook

When compiled as a WASM Module Binary the ANT provides a boot method to initialize the state of the ANT.

This will send a Credit-Notice to the initialized Owner (if applicable) and a State-Notice to the ANT Registry.

If a valid JSON string state is provided, it will be used to set the initial state of the ANT.

Example:

{
  "name": "Test Process",
  "ticker": "TEST",
  "description": "TEST DESCRIPTION",
  "keywords": ["KEYWORD-1", "KEYWORD-2", "KEYWORD-3"],
  "owner": "STUB_ADDRESS",
  "controllers": ["STUB_ADDRESS"],
  "balances": {
    "STUB_ADDRESS": 1
  },
  "records": {
    "@": {
      "transactionId": "3333333333333333333333333333333333333333333",
      "ttlSeconds": 900
    }
  }
}

Retrieves the Name, Ticker, Total supply, Logo, Denomination, and Owner of the ANT.

Retrieves total supply of the ANT.

Retrieves the entire state of the ANT, which includes:

• Records
• Controllers
• Balances
• Owner
• Name
• Ticker
• Logo
• Description
• Keywords
• Denomination
• TotalSupply
• Initialized

Retrieves all the records configured on the ANT

Retrieves and individual record by name.

Retrieves all the controllers on the ANT.

Retrieves the balance of a target address.

Retrieves all the balances of the ANT - with the standard implementation this will only contain the Owner of the ant with a balance of 1.

Transfers the ownership of the ANT. By default, all controllers are removed during the transfer unless explicitly set to preserve them.

Sets a record for a given subdomain.

Sets the name of the ANT.

Sets the ticker symbol for the ANT.

Sets the description for the ANT.

Sets the logo for the ANT.

Sets the keywords for the ANT.

Adds a new controller to the ANT.

Removes a controller from the ANT.

Removes a record from the ANT.

Calls the IO Network process to release the given ArNS name if that name is associated with the ANT.

Calls the IO Network process to reassign the given ArNS name to a new ANT ID if that name is associated with the ANT.

• Lua 5.3 - Download
• Luarocks - Download

Note that we use lua 5.3 because that is what the ao-dev-cli uses

1. Clone the repository and navigate to the project directory.
2. run the following:

yarn install-lua-deps

1. Build and install lua

curl -R -O https://lua.org/ftp/lua-5.3.1.tar.gz
tar -xzvf lua-5.3.1.tar.gz
cd lua-5.3.1
make
make install

2. Build and install LuaRocks

Note that we do not specify the lua version, it will discover it.

curl -R -O http://luarocks.github.io/luarocks/releases/luarocks-3.9.1.tar.gz
tar zxpf luarocks-3.9.1.tar.gz
cd luarocks-3.9.1
./configure --with-lua=/usr/local --with-lua-include=/usr/local/include
make build
sudo make install

If you ever need to refresh .luarocks, run the following command:

luarocks purge && luarocks install ar-io-ao-0.1-1.rockspec

To load the module into the aos REPL, run the following command:

aos --load src/main.lua

The code is formatted using stylua. To install stylua, run the following command:

cargo install stylua
stylua contract

To run the tests, execute the following command:

busted .

To see the test coverage, run the following command:

luacov --reporter html && open luacov-html/index.html

To add new dependencies, install using luarocks to the local directory

luarocks install <package>

And add the package to the dependencies table in the ar-io-ao-0.1-1.rockspec file.

-- rest of the file
dependencies = {
    "lua >= 5.3",
    "luaunit >= 3.3.0",
    "<package>"
}

• AR.IO Gateways
• ArNS Docs
• ArNS Portal
• AO Cookbook
• AR.IO SDK