Merge pull request #33 from ar-io/PE-6979-set-logo-api

fix(PE-6979): set logo api

CHANGELOG.md

@@ -16,6 +16,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   - Allows for setting the description of the ANT
 - Set-Keywords Handler
   - Allows for setting keywords on the ANT
+- Set-Logo Handler
+  - Allows for setting the logo of the ANT
+
+### Changed
+
+- Refactored handlers to use a util that codifies responses on calls.
+- Added documentation with luadoc types for improved linting.
+
+### Fixed
+
+- Fixed the Remove-Record api to return appropriate notices on calls.
 
 <!-- eslint-disable-next-line -->
 

src/common/balances.lua

@@ -1,54 +1,89 @@
+--- Module for managing balances and transactions.
+-- @module balances
+
 local utils = require(".common.utils")
 local json = require(".common.json")
 
 local balances = {}
 
+--- Checks if a wallet has sufficient balance.
+---@param wallet string - The wallet address to check.
+---@return boolean - Returns true if the wallet has a balance greater than 0, otherwise false.
 function balances.walletHasSufficientBalance(wallet)
 	return Balances[wallet] ~= nil and Balances[wallet] > 0
 end
 
+--- Transfers the ANT to a specified wallet.
+---@param to string - The wallet address to transfer the balance to.
+---@return string - Returns the encoded JSON representation of the transferred balance.
 function balances.transfer(to)
 	utils.validateArweaveId(to)
 	Balances = { [to] = 1 }
+	--luacheck: ignore Owner Controllers
 	Owner = to
 	Controllers = {}
 	return json.encode({ [to] = 1 })
 end
 
+--- Retrieves the balance of a specified wallet.
+---@param address string - The wallet address to retrieve the balance from.
+---@return number - Returns the balance of the specified wallet.
 function balances.balance(address)
 	utils.validateArweaveId(address)
 	local balance = Balances[address] or 0
 	return balance
 end
 
+--- Retrieves all balances.
+---@return string - Returns the encoded JSON representation of all balances.
 function balances.balances()
 	return json.encode(Balances)
 end
 
+--- Sets the name of the ANT.
+---@param name string - The name to set.
+---@return string - Returns the encoded JSON representation of the updated name.
 function balances.setName(name)
 	assert(type(name) == "string", "Name must be a string")
 	Name = name
 	return json.encode({ name = Name })
 end
 
+--- Sets the ticker of the ANT.
+---@param ticker string - The ticker to set.
+---@return string - Returns the encoded JSON representation of the updated ticker.
 function balances.setTicker(ticker)
 	assert(type(ticker) == "string", "Ticker must be a string")
 	Ticker = ticker
 	return json.encode({ ticker = Ticker })
 end
 
+--- Sets the description of the ANT.
+---@param description string - The description to set.
+---@return string - Returns the encoded JSON representation of the updated description.
 function balances.setDescription(description)
 	assert(type(description) == "string", "Description must be a string")
 	assert(#description <= 512, "Description must not be longer than 512 characters")
 	Description = description
 	return json.encode({ description = Description })
 end
 
+--- Sets the keywords of the ANT.
+---@param keywords table - The keywords to set.
+---@return string - Returns the encoded JSON representation of the updated keywords.
 function balances.setKeywords(keywords)
 	utils.validateKeywords(keywords)
 
 	Keywords = keywords
 	return json.encode({ keywords = Keywords })
 end
 
+--- Sets the logo of the ANT.
+---@param logo string - The Arweave transaction ID that represents the logo.
+---@return string - Returns the encoded JSON representation of the updated logo.
+function balances.setLogo(logo)
+	Logo = logo
+	return json.encode({ logo = Logo })
+end
+
 return balances

src/common/controllers.lua

@@ -3,6 +3,9 @@ local utils = require(".common.utils")
 
 local controllers = {}
 
+--- Set a controller.
+---@param controller string The controller to set.
+---@return string The encoded JSON representation of the updated controllers.
 function controllers.setController(controller)
 	utils.validateArweaveId(controller)
 
@@ -14,6 +17,9 @@ function controllers.setController(controller)
 	return json.encode(Controllers)
 end
 
+--- Remove a controller.
+---@param controller string The controller to remove.
+---@return string The encoded JSON representation of the updated controllers.
 function controllers.removeController(controller)
 	utils.validateArweaveId(controller)
 	local controllerExists = false
@@ -30,6 +36,8 @@ function controllers.removeController(controller)
 	return json.encode(Controllers)
 end
 
+--- Get all controllers.
+---@return string The encoded JSON representation of the controllers.
 function controllers.getControllers()
 	return json.encode(Controllers)
 end

src/common/main.lua

@@ -14,20 +14,45 @@ function ant.init()
 	local records = require(".common.records")
 	local controllers = require(".common.controllers")
 
+	---@alias Owner string
+	---@description The owner of the ANT
 	Owner = Owner or ao.env.Process.Owner
+	---@alias Balances table<string, integer>
+	---@description The list of balances for the ANT
 	Balances = Balances or { [Owner] = 1 }
+	---@alias Controllers table<integer, string>
+	---@description The list of controllers for the ANT
 	Controllers = Controllers or { Owner }
 
+	---@alias Name string
+	---@description The name of the ANT
 	Name = Name or "Arweave Name Token"
+	---@alias Ticker string
+	---@description The ticker symbol of the ANT
 	Ticker = Ticker or "ANT"
+	---@alias Logo string
+	---@description Arweave transaction ID that is the logo of the ANT
 	Logo = Logo or "Sie_26dvgyok0PZD_-iQAFOhOd5YxDTkczOLoqTTL_A"
+	---@alias Description string
+	---@description A brief description of this ANT up to 255 characters
 	Description = Description or "A brief description of this ANT."
+	---@alias Keywords table<string>
+	---@description A list of keywords that describe this ANT. Each keyword must be a string, unique, and less than 32 characters. There can be up to 16 keywords
 	Keywords = Keywords or {}
+	---@alias Denomination integer
+	---@description The denomination of the ANT - this is set to 0 to denote integer values
 	Denomination = Denomination or 0
+	---@alias TotalSupply integer
+	---@description The total supply of the ANT - this is set to 1 to denote single ownership
 	TotalSupply = TotalSupply or 1
+	---@alias Initialized boolean
+	---@description Whether the ANT has been initialized with the
 	Initialized = Initialized or false
-	-- INSERT placeholder used by build script to inject the appropriate ID
+	---@alias SourceCodeTxId string
+	---@description The Arweave ID of the lua source the ANT currently uses. INSERT placeholder used by build script to inject the appropriate ID
 	SourceCodeTxId = SourceCodeTxId or "__INSERT_SOURCE_CODE_ID__"
+	---@alias AntRegistryId string
+	---@description The Arweave ID of the ANT Registry contract that this ANT is registered with
 	AntRegistryId = AntRegistryId or ao.env.Process.Tags["ANT-Registry-Id"] or nil
 
 	local ActionMap = {
@@ -40,6 +65,7 @@ function ant.init()
 		SetTicker = "Set-Ticker",
 		SetDescription = "Set-Description",
 		SetKeywords = "Set-Keywords",
+		SetLogo = "Set-Logo",
 		--- initialization method for bootstrapping the contract from other platforms ---
 		InitializeState = "Initialize-State",
 		-- read
@@ -145,7 +171,7 @@ function ant.init()
 		local tags = msg.Tags
 		local name, transactionId, ttlSeconds =
 			string.lower(tags["Sub-Domain"]), tags["Transaction-Id"], tonumber(tags["TTL-Seconds"])
-
+		assert(ttlSeconds, "Missing ttl seconds")
 		return records.setRecord(name, transactionId, ttlSeconds)
 	end)
 
@@ -185,6 +211,12 @@ function ant.init()
 		return balances.setKeywords(keywords)
 	end)
 
+	createActionHandler(ActionMap.SetLogo, function(msg)
+		utils.assertHasPermission(msg.From)
+		utils.validateArweaveId(msg.Logo)
+		return balances.setLogo(msg.Logo)
+	end)
+
 	createActionHandler(ActionMap.InitializeState, function(msg)
 		return initialize.initializeANTState(msg.Data)
 	end)

src/common/records.lua

@@ -4,13 +4,15 @@ local records = {}
 -- defaults to landing page txid
 Records = Records or { ["@"] = { transactionId = "-k7t8xMoB8hW482609Z9F4bTFMC3MnuW8bTvTyT8pFI", ttlSeconds = 3600 } }
 
+--- Set a record in the Records of the ANT.
+---@param name string The name of the record.
+---@param transactionId string The transaction ID of the record.
+---@param ttlSeconds number The time-to-live in seconds for the record.
+---@return string The encoded JSON representation of the record.
 function records.setRecord(name, transactionId, ttlSeconds)
-	local nameValidity, nameValidityError = pcall(utils.validateUndername, name)
-	assert(nameValidity ~= false, nameValidityError)
-	local targetIdValidity, targetValidityError = pcall(utils.validateArweaveId, transactionId)
-	assert(targetIdValidity ~= false, targetValidityError)
-	local ttlSecondsValidity, ttlValidityError = pcall(utils.validateTTLSeconds, ttlSeconds)
-	assert(ttlSecondsValidity ~= false, ttlValidityError)
+	utils.validateUndername(name)
+	utils.validateArweaveId(transactionId)
+	utils.validateTTLSeconds(ttlSeconds)
 
 	local recordsCount = #Records
 
@@ -29,20 +31,27 @@ function records.setRecord(name, transactionId, ttlSeconds)
 	})
 end
 
+--- Remove a record from the ANT.
+---@param name string The name of the record to remove.
+---@return string The encoded JSON representation of the deletion message.
 function records.removeRecord(name)
-	local nameValidity, nameValidityError = pcall(utils.validateUndername, name)
-	assert(nameValidity ~= false, nameValidityError)
+	utils.validateUndername(name)
 	Records[name] = nil
 	return json.encode({ message = "Record deleted" })
 end
 
+--- Get a record from the ANT.
+---@param name string The name of the record to retrieve.
+---@return string The encoded JSON representation of the record.
 function records.getRecord(name)
 	utils.validateUndername(name)
 	assert(Records[name] ~= nil, "Record does not exist")
 
 	return json.encode(Records[name])
 end
 
+--- Get all records from the ANT
+---@return string The encoded JSON representation of all records.
 function records.getRecords()
 	return json.encode(Records)
 end

src/common/types.lua

@@ -0,0 +1,49 @@
+-- need to specify this as a module so it can be imported
+---@alias AoMessage {
+--- Id: string,
+--- From: string,
+--- Target: string,
+--- Tags: table<string, string | number>,
+--- Owner: string,
+--- Data: string | number | nil,
+--- [string]: string | number,
+---}
+
+---@alias Handler {
+--- name: string,
+--- pattern: function|table<string, string|nil>,
+--- handle: function,
+---}
+---@alias HandlersList table<string, Handler>
+
+---@alias Handlers {
+--- list: HandlersList,
+--- add: function,
+--- before: function,
+--- after: function,
+--- remove: function,
+--- prepend: function,
+--- append: function,
+--- evaluate: function,
+---}
+
+---@alias Record {
+--- transactionId: string,
+--- ttlSeconds: integer,
+---}
+
+---@alias AntState {
+--- Name: string,
+--- Ticker: string,
+--- Description: string,
+--- Keywords: string,
+--- Logo: string,
+--- Balances: table<string, integer>,
+--- Owner: string,
+--- Controllers: table<string>,
+--- Denomination: integer,
+--- TotalSupply: integer,
+--- Initialized: boolean,
+--- ["Source-Code-TX-ID"|SourceCodeTxId]: string,
+--- Records: table<string, Record>,
+---}