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
Handler Methods
Developers

Setup

Install

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.g8way.io | 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.

Lua code

yarn aos:build

Module WASM Binary

yarn module:build

Publish

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

Lua code

yarn aos:publish

Module WASM Binary

yarn module: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.

Lua code

yarn aos:load

Module WASM Binary

yarn module:load

Spawn

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

Lua code

yarn aos:spawn

Module WASM Binary

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.

Handler Methods

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

Boot Methods

`_boot` (WASM Binary only)

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

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

With local script (MacOS and Linux only)

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

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

yarn install-lua-deps

Manually

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

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 273 Commits
.github/workflows		.github/workflows
.husky		.husky
.vscode		.vscode
spec		spec
src		src
test		test
tools		tools
.busted		.busted
.gitignore		.gitignore
.luacheckrc		.luacheckrc
.luacov		.luacov
.nvmrc		.nvmrc
.prettierrc		.prettierrc
.styluaignore		.styluaignore
.yarnrc		.yarnrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
ao-build-config.yml		ao-build-config.yml
ar-io-ao-0.1-1.rockspec		ar-io-ao-0.1-1.rockspec
package.json		package.json
version.mjs		version.mjs
yarn.lock		yarn.lock

License

ar-io/ar-io-ant-process

Folders and files

Latest commit

History

Repository files navigation

Arweave Name Token process on AO

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

Additional Resources

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 5

Languages

`_boot` (WASM Binary only)

`Info`

`Total-Supply`

`State`

`Records`

`Record`

`Controllers`

`Balance`

`Balances`

`Transfer`

`Set-Record`

`Set-Name`

`Set-Ticker`

`Set-Description`

`Set-Logo`

`Set-Keywords`

`Add-Controller`

`Remove-Controller`

`Remove-Record`

`Release-Name`

`Reassign-Name`

Packages