Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(PE-6228): ant module #1

Merged
merged 15 commits into from
Jun 21, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .busted
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
print("Loading .busted configuration...")
return {
_all = {
verbose = true,
coverage = true,
output = "utfTerminal",
jobs = 4,
},
default = {
ROOT = {"ant"},
pattern = "**/*_spec.lua$",
helper = "spec/setup.lua",
}
}
46 changes: 46 additions & 0 deletions .github/workflows/ant.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: Arweave Name Token

on: [push, workflow_dispatch]

jobs:
busted:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
name: Check out repository code

- name: Setup Lua
uses: leafo/gh-actions-lua@v10
with:
luaVersion: '5.3' # Specify the Lua version you need

- name: Setup LuaRocks

uses: leafo/[email protected]

- name: Install Busted
run: luarocks install ar-io-ao-0.1-1.rockspec

- name: Run Busted Tests
working-directory: ant
run: busted .

- name: Upload coverage reports to Codecov
uses: codecov/[email protected]
with:
token: ${{ secrets.CODECOV_TOKEN }}

build:
runs-on: ubuntu-latest
strategy:
matrix:
step: [build:aos, test]
steps:
- uses: actions/checkout@v4
- uses: actions/[email protected]
with:
node-version-file: '.nvmrc'
cache: 'yarn'

- run: yarn --frozen-lockfile
- run: yarn ${{ matrix.step }}
17 changes: 17 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
key.json
node_modules
.luarocks
**/coverage/*
!.gitkeep
/luarocks
/lua
/lua_modules
/.luarocks
wallet.json
.DS_Store
luacov-html
.luacov
*.gz
luacov.stats.out
process.wasm
dist
1 change: 1 addition & 0 deletions .nvmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
20.11.1
7 changes: 7 additions & 0 deletions .prettierrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"plugins": [],
"semi": true,
"printWidth": 80,
"singleQuote": true,
"trailingComma": "all"
}
25 changes: 25 additions & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,
"editor.formatOnPaste": true,
"editor.formatOnSaveMode": "file",
"prettier.configPath": ".prettierrc",
"prettier.prettierPath": "./node_modules/prettier/index.cjs",
"[typescript]": {
"editor.formatOnSave": true
},
"[markdown]": {
"editor.formatOnSave": true
},
"search.exclude": {
"**/node_modules": true,
"**/lib": true,
"**/dist": true,
"**/coverage": true
},
"Lua.workspace.checkThirdParty": true,
"[lua]": {
"editor.defaultFormatter": "JohnnyMorganz.stylua",
"editor.formatOnSave": true
}
dtfiedler marked this conversation as resolved.
Show resolved Hide resolved
}
242 changes: 242 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,242 @@
# 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

First install the npm dependencies

```bash
yarn
```

Then install the ao cli - read the docs [here](https://github.com/permaweb/ao/tree/main/dev-cli)
Below is latest version as of writing, refer to the docs for the latest version.

```sh
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](https://lunarmodules.github.io/busted/)

```sh
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.

```bash
yarn aos:build
```

#### Publish

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

```bash
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.

```bash
yarn aos:load
```

#### Spawn

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

```bash
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.

### Building the custom module

Using the ao-dev-cli.

#### Build

This will compile the standalone ANT module to wasm, as a file named `process.wasm` and loads the module in [AO Loader](https://github.com/permaweb/ao/tree/main/loader) to validate the WASM program is valid.

```bash
yarn module:build
```

#### Publish

Publishes the custom ANT module to arweave - requires you placed your JWK in the `tools` directory. May require AR in the wallet to pay gas.

```sh
yarn module:publish
```

#### Load

Loads the module in [AO Loader](https://github.com/permaweb/ao/tree/main/loader) to validate the WASM program is valid.

```bash
yarn module:load
```

Requires `module:build` to have been called so that `process.wasm` exists.

#### Spawn

Spawns a process with the `process.wasm` file.

```bash
yarn module:spawn
```

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

#### `Get-Records`

Retrieves all the records configured on the ANT

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

#### `Get-Record`

Retrieves and individual record by name.

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

#### `Get-Controllers`

Retrieves all the controllers on the ANT.

| Tag Name | Type | Pattern | Required | Description |
| -------- | ------ | ----------------- | -------- | --------------------------------- |
| Action | string | "Get-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-Controller`

Adds a new controller to the ANT.

| Tag Name | Type | Pattern | Required | Description |
| ---------- | ------ | --------------------- | -------- | --------------------------------- |
| Action | string | "Set-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. |

# Additional Resources

- [AR.IO Gateways]
- [ArNS Docs]
- [ArNS Portal]
- [AO Cookbook]

[AR.IO Gateways]: https://ar.io/docs/gateway-network/#overview
[ArNS Docs]: https://ar.io/docs/arns/
[ArNS ANT Docs]: https://ar.io/docs/arns/#arweave-name-token-ant
[ArNS Portal]: https://arns.app
[AO Cookbook]: https://cookbook_ao.arweave.dev
19 changes: 19 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"scripts": {
"module:build": "cd src && ao build && cd .. && yarn module:load",
"module:publish": "cd src && ao publish process.wasm -w ../tools/key.json --tag=\"Memory-Limit\" --value=\"1-gb\" --tag=\"Compute-Limit\" --value=\"9000000000000\" && cd ..",
"module:load": "node tools/load-module.js",
"module:spawn": "node tools/spawn-module.js",
"aos:build": "node tools/bundle-aos.js",
"aos:publish": "node tools/bundle-aos.js && node tools/publish-aos.js",
"aos:load": "node tools/bundle-aos.js && node tools/load-aos.js",
"aos:spawn": "node tools/spawn-aos.js",
"test": "node --test --test-concurrency 1 **/*.test.js"
},
"devDependencies": {
"prettier": "^3.3.2",
"@permaweb/ao-loader": "^0.0.35",
"@permaweb/aoconnect": "^0.0.55",
"arweave": "^1.15.1"
dtfiedler marked this conversation as resolved.
Show resolved Hide resolved
}
}
Loading