README.md

AO/IO Contract

The implementation of the ar.io network contract is written in lua and deployed as an AO process on Arweave. The contract is responsible for managing the network state, handling transactions, and enforcing the network rules. Refer to the contract whitepaper for more details on the network rules and the contract design.

Contract Spec

General Structure

Each handler is identified by an action name and it has required and optional tags for its input. The handlers can be categorized into "read" and "write" operations.

Handlers

Balances

Action	Required Tags	Optional Tags	Result (the -Notice)
Transfer	Recipient: Valid Arweave address Quantity: Integer greater than 0	X-*: Tags beginning with "X-"	Debit-Notice, Credit-Notice
Create-Vault'	Lock-Length: Integer greater than 0 Quantity: Integer greater than 0		Vault-Created-Notice
Vaulted-Transfer	Recipient: Valid Arweave address Lock-Length: Integer greater than 0 Quantity: Integer greater than 0		Debit-Notice, Vaulted-Credit-Notice
Extend-Vault	Vault-Id: Valid Arweave address Extend-Length: Integer greater than 0		Vault-Extended-Notice
Increase-Vault	Vault-Id: Valid Arweave address Quantity: Integer greater than 0		Vault-Increased-Notice
Balances			Balances-Notice
Balance			Balance-Notice

ArNS Registry

Action	Required Tags	Optional Tags	Result
Buy-Record	Name: String Purchase-Type: String Process-Id: Valid Arweave address Years: Integer between 1 and 5		Buy-Record-Notice
Extend-Lease	Name: String Years: Integer between 1 and 5		Extend-Lease-Notice
Increase-Undername-Limit	Name: String Quantity: Integer between 1 and 9990		Increase-Undername-Limit-Notice
Token-Cost	Intent: Must be valid registry interaction (e.g., BuyRecord, ExtendLease, IncreaseUndernameLimit)	Years: Integer between 1 and 5 Quantity: Integer greater than 0	Token-Cost-Notice
Demand-Factor-Settings			Demand-Factor-Settings-Notice
Demand-Factor			Demand-Factor-Notice
Record			Record-Notice
Records			Records-Notice
Reserved-Names			Reserved-Names-Notice
Reserved-Name			Reserved-Name-Notice

Gateway Registry

Action	Required Tags	Optional Tags	Result (the -Notice)
Join-Network	Operator-Stake: Quantity	Label, Note, FQDN, Port, Protocol, Allow-Delegated-Staking, Min-Delegated-Stake, Delegate-Reward-Share-Ratio, Properties, Auto-Stake, Observer-Address	Join-Network-Notice
Leave-Network			Leave-Network-Notice
Increase-Operator-Stake	Quantity: Integer greater than 0		Increase-Operator-Stake-Notice
Decrease-Operator-Stake	Quantity: Integer greater than 0		Decrease-Operator-Stake-Notice
Delegate-Stake	Target: Valid Arweave address Quantity: Integer greater than 0		Delegate-Stake-Notice
Decrease-Delegate-Stake	Target: Valid Arweave address Quantity: Integer greater than 0		Decrease-Delegate-Stake-Notice
Update-Gateway-Settings		Label, Note, FQDN, Port, Protocol, Allow-Delegated-Staking, Min-Delegated-Stake, Delegate-Reward-Share-Ratio, Properties, Auto-Stake, Observer-Address	Update-Gateway-Settings-Notice
Save-Observations	Report-Tx-Id: Valid Arweave address Failed-Gateways: Comma-separated string of valid Arweave addresses		Save-Observations-Notice
Gateway-Registry-Settings			Gateway-Registry-Settings-Notice
Gateways			Gateways-Notice
Gateway		Address: Valid Arweave address, Target: Valid Arweave address	Gateway-Notice

Epochs

Action	Required Tags	Optional Tags	Result (the -Notice)
Epoch-Settings			Epoch-Settings-Notice
Epoch	Epoch-Index or Timestamp		Epoch-Notice
Epochs			Epochs-Notice
Epoch-Prescribe-dObservers	Epoch-Index or Timestamp		Prescribed-Observers-Notice
Epoch-Observations	Epoch-Index or Timestamp		Observations-Notice
Epoch-Prescribed-Names	Epoch-Index or Timestamp		Prescribed-Names-Notice
Epoch-Distributions	Epoch-Index or Timestamp		Distributions-Notice

State

Action	Required Tags	Optional Tags	Result (the -Notice)
Info			Info-Notice
State			State-Notice
Tick	Hash-Chain, Timestamp, Block-Height		Tick-Notice, Invalid-Tick_Notice

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/lua5.3"' >> ~/.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

1. Run source ~/.zshrc or source ~/.bashrc to apply the changes.
2. 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/lua5.3
make build
sudo make install

2. Ensure that the luarocks binary is in your path by running echo $PATH. Otherwise, add it to your path and reload your shell:

echo 'export PATH=$HOME/.luarocks/bin:$PATH' >> ~/.zshrc

3. Check the installation by running luarocks --version.
4. 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

Get aos:

yarn global add https://get_ao.g8way.io

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

aos --load src/main.lua

Code Formatting

To get the code formatter, we'll need to install rust to access cargo. To install rust on MacOS, run the following command:

brew install rust

If not already added, include cargo binary in your path so that packages installed using cargo can be accessed globally:

echo 'export PATH=$HOME/.cargo/bin:$PATH' >> ~/.zshrc

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, get luacov:

luarocks install luacov

With luacov installed, 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>"
}

Deployment

TODO: