Arweave Name Token process on AO

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
    • Publish
    • Load
    • Spawn
• Handler Methods
  • 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 (MacOS)
  • LuaRocks Setup
  • aos
  • Code Formatting
  • Testing
  • Dependencies

Setup

Install

First install the npm dependencies

yarn

Then install the ao cli - read the docs here Below is latest version as of writing, refer to the docs for the latest version.

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

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

Testing

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

busted .

Building the AOS code

Build

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

Publish

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

yarn aos:publish

Load

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

Spawn

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

yarn aos:spawn

This will deploy the bundled lua file to arweave as an L1 transaction, so your wallet will need AR to pay the gas.

Handler Methods

For interacting with handlers please refer to the AO Cookbook

Read Methods

Info

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

Tag Name	Type	Pattern	Required	Description
Action	string	"Info"	true	Action tag for triggering handler

Total-Supply

Retrieves total supply of the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Total-Supply"	true	Action tag for triggering handler

State

Retrieves the entire state of the ANT, which includes:

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

Tag Name	Type	Pattern	Required	Description
Action	string	"State"	true	Action tag for triggering handler

Records

Retrieves all the records configured on the ANT

Tag Name	Type	Pattern	Required	Description
Action	string	"Records"	true	Action tag for triggering handler

Record

Retrieves and individual record by name.

Tag Name	Type	Pattern	Required	Description
Action	string	"Record"	true	Action tag for triggering handler
Sub-Domain	string	"^(?:[a-zA-Z0-9_-]+|@)$"	true	Subdomain you which to read

Controllers

Retrieves all the controllers on the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Controllers"	true	Action tag for triggering handler

Balance

Retrieves the balance of a target address.

Tag Name	Type	Pattern	Required	Description
Action	string	"Balance"	true	Action tag for triggering handler
Recipient	string	"^[a-zA-Z0-9_-]{43}$"	false	Address to retrieve balance for.

Balances

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.

Tag Name	Type	Pattern	Required	Description
Action	string	"Balances"	true	Action tag for triggering handler

Write methods

Transfer

Transfers the ownership of the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Transfer"	true	Action tag for triggering handler
Recipient	string	"^[a-zA-Z0-9_-]{43}$"	true	Address to transfer ANT to.

Set-Record

Sets a record for a given subdomain.

Tag Name	Type	Pattern	Required	Description
Action	string	"Set-Record"	true	Action tag for triggering handler
Sub-Domain	string	"^(?:[a-zA-Z0-9_-]+|@)$"	true	Subdomain to set the record for.
Transaction-Id	string	"^[a-zA-Z0-9_-]{43}$"	true	Transaction ID for the record.
TTL-Seconds	number	Min: 900, Max: 2,592,000	true	Time-to-live in seconds for record.

Set-Name

Sets the name of the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Set-Name"	true	Action tag for triggering handler
Name	string	N/A	true	New name for the ANT.

Set-Ticker

Sets the ticker symbol for the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Set-Ticker"	true	Action tag for triggering handler
Ticker	string	N/A	true	New ticker symbol for ANT.

Set-Description

Sets the description for the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Set-Description"	true	Action tag for triggering handler
Description	string	Max 512 characters	true	New description for ANT.

Set-Logo

Sets the logo for the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Set-Logo"	true	Action tag for triggering handler
Logo	string	"^[a-zA-Z0-9_-]{43}$"	true	ID of new logo for ANT.

Set-Keywords

Sets the keywords for the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Set-Keywords"	true	Action tag for triggering handler
Keywords	table	"^[%w-_#@]+$", max 32 characters, max 16 keywords, min 1 keyword	true	New keywords for ANT.

Add-Controller

Adds a new controller to the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Add-Controller"	true	Action tag for triggering handler
Controller	string	"^[a-zA-Z0-9_-]{43}$"	true	Address of the new controller.

Remove-Controller

Removes a controller from the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Remove-Controller"	true	Action tag for triggering handler
Controller	string	"^[a-zA-Z0-9_-]{43}$"	true	Address of the controller to remove.

Remove-Record

Removes a record from the ANT.

Tag Name	Type	Pattern	Required	Description
Action	string	"Remove-Record"	true	Action tag for triggering handler
Sub-Domain	string	"^(?:[a-zA-Z0-9_-]+|@)$"	true	Subdomain of the record to remove.

Release-Name

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

Tag Name	Type	Pattern	Required	Description
Action	string	"Release-Name"	true	Action tag for triggering handler
Name	string	"^([a-zA-Z0-9_-])$"	true	ArNS name to release

Reassign-Name

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

Tag Name	Type	Pattern	Required	Description
Action	string	"Reassign-Name"	true	Action tag for triggering handler
IO-Process-Id	string	"^[a-zA-Z0-9_-]{43}$"	true	ID of the IO Network Process to reassign the name on
Process-Id	string	"^[a-zA-Z0-9_-]{43}$"	true	ID of the new ANT to assign to the ArNS name
Name	string	"^([a-zA-Z0-9_-])$"	true	Subdomain of the record to remove.

Developers

Requirements

• Lua 5.3 - Download
• Luarocks - Download

Lua Setup (MacOS)

1. Clone the repository and navigate to the project directory.

2. Install lua

   • brew install [email protected]

3. Add the following to your .zshrc or .bashrc file:

   echo 'export LDFLAGS="-L/usr/local/opt/[email protected]/lib"' >> ~/.zshrc
   echo 'export CPPFLAGS="-I/usr/local/opt/[email protected]/include"' >> ~/.zshrc
   echo 'export PKG_CONFIG_PATH="/usr/local/opt/[email protected]/lib/pkgconfig"' >> ~/.zshrc
   echo 'export PATH="/usr/local/opt/[email protected]/bin:$PATH"' >> ~/.zshrc

4. Run source ~/.zshrc or source ~/.bashrc to apply the changes.

5. Run lua -v to verify the installation.

LuaRocks Setup

1. Install luarocks

   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/opt/[email protected] --with-lua-include=/usr/local/opt/[email protected]/include
   make build
   sudo make install

2. Check the installation by running luarocks --version.

3. Check the LuaRocks configuration by running luarocks config | grep LUA

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

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

aos

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

aos --load src/main.lua

Code Formatting

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

cargo install stylua
stylua contract

Testing

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

Dependencies

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>"
}

Additional Resources

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