chore(PE-8643): hb patch system for primary names

src/hb.lua

@@ -1,6 +1,27 @@
 -- hb.lua needs to be in its own file and not in balances.lua to avoid circular dependencies
 local hb = {}
 
+--[[
+	HyperbeamSync is a table that is used to track changes to our lua state that need to be synced to the Hyperbeam.
+	the principal of using it is to set the key:value pairs that need to be synced, then
+		the patch function will pull that from the global state to build the patch message.
+
+	After, the HyperbeamSync table is cleared and the next message run will start fresh.
+]]
+HyperbeamSync = HyperbeamSync
+	or {
+		---@type table<string, boolean> addresses that have had balance changes
+		balances = {},
+		primaryNames = {
+			---@type table<string, boolean> addresses that have had name changes
+			names = {},
+			---@type table<string, boolean> addresses that have had owner changes
+			owners = {},
+			---@type table<string, boolean> addresses that have had request changes
+			requests = {},
+		},
+	}
+
 ---@param oldBalances table<string, number> A table of addresses and their balances
 ---@return table<string, boolean> affectedBalancesAddresses table of addresses that have had balance changes
 function hb.patchBalances(oldBalances)
@@ -38,4 +59,100 @@ function hb.patchBalances(oldBalances)
 	return affectedBalancesAddresses
 end
 
+---@return PrimaryNames|nil affectedPrimaryNamesAddresses
+function hb.createPrimaryNamesPatch()
+	---@type PrimaryNames
+	local affectedPrimaryNamesAddresses = {
+		names = {},
+		owners = {},
+		requests = {},
+	}
+
+	-- if no changes, return early. This will allow downstream code to not send the patch state for this key ('primary-names')
+	if
+		next(HyperbeamSync.primaryNames.names) == nil
+		and next(HyperbeamSync.primaryNames.owners) == nil
+		and next(HyperbeamSync.primaryNames.requests) == nil
+	then
+		return nil
+	end
+
+	-- build the affected primary names addresses table for the patch message
+	for name, _ in pairs(HyperbeamSync.primaryNames.names) do
+		-- we need to send an empty string to remove the name
+		affectedPrimaryNamesAddresses.names[name] = PrimaryNames.names[name] or ""
+	end
+	for owner, _ in pairs(HyperbeamSync.primaryNames.owners) do
+		-- we need to send an empty table to remove the owner primary name data
+		affectedPrimaryNamesAddresses.owners[owner] = PrimaryNames.owners[owner] or {}
+	end
+	for address, _ in pairs(HyperbeamSync.primaryNames.requests) do
+		-- we need to send an empty table to remove the request
+		affectedPrimaryNamesAddresses.requests[address] = PrimaryNames.requests[address] or {}
+	end
+
+	local shouldSendEmptyNames = next(PrimaryNames.names) == nil
+	local shouldSendEmptyOwners = next(PrimaryNames.owners) == nil
+	local shouldSendEmptyRequests = next(PrimaryNames.requests) == nil
+
+	-- if we're not sending any data, we need to remove the table from the patch message to not delete the entire primary names table
+	--- with this ifelse pattern we are saying that if the global state for that key is empty, we can remove the data from the hyperbeam state
+	--- by sending the empty table.
+	---
+	--- unlikely case for names and owners, but possible for requests
+	if not shouldSendEmptyNames then
+		affectedPrimaryNamesAddresses.names = nil
+	else
+		affectedPrimaryNamesAddresses.names = {}
+	end
+	if not shouldSendEmptyOwners then
+		affectedPrimaryNamesAddresses.owners = nil
+	else
+		affectedPrimaryNamesAddresses.owners = {}
+	end
+
+	if not shouldSendEmptyRequests then
+		affectedPrimaryNamesAddresses.requests = nil
+	else
+		affectedPrimaryNamesAddresses.requests = {}
+	end
+
+	-- if we're not sending any data, return nil which will allow downstream code to not send the patch message
+	if next(affectedPrimaryNamesAddresses) == nil then
+		return nil
+	end
+
+	return affectedPrimaryNamesAddresses
+end
+
+function hb.resetHyperbeamSync()
+	HyperbeamSync = {
+		balances = {},
+		primaryNames = {
+			names = {},
+			owners = {},
+			requests = {},
+		},
+	}
+end
+
+--[[
+	1. Create the data patches
+	2. Send the patch message if there are any data patches
+	3. Reset the hyperbeam sync
+]]
+function hb.patchHyperbeamState()
+	local patchMessageFields = {
+		["primary-names"] = hb.createPrimaryNamesPatch(),
+	}
+
+	--- just seperating out the device field to make it easier to predicate on
+	if next(patchMessageFields) ~= nil then
+		patchMessageFields.device = "[email protected]"
+		ao.send(patchMessageFields)
+	end
+
+	hb.resetHyperbeamSync()
+end
+
 return hb

src/main.lua

@@ -477,8 +477,10 @@ local function addEventingHandler(handlerName, pattern, handleFn, critical, prin
 		-- Store the old balances to compare after the handler has run for patching state
 		-- Only do this for the last handler to avoid unnecessary copying
 		local oldBalances = nil
+		local shouldPatchHbState = false
 		if pattern(msg) ~= "continue" then
 			oldBalances = utils.deepCopy(Balances)
+			shouldPatchHbState = true
 		end
 		-- add an ARIOEvent to the message if it doesn't exist
 		msg.ioEvent = msg.ioEvent or ARIOEvent(msg)
@@ -508,6 +510,10 @@ local function addEventingHandler(handlerName, pattern, handleFn, critical, prin
 			hb.patchBalances(oldBalances)
 		end
 
+		if shouldPatchHbState then
+			hb.patchHbState()
+		end
+
 		msg.ioEvent:addField("Handler-Memory-KiB-Used", collectgarbage("count"), false)
 		collectgarbage("collect")
 		msg.ioEvent:addField("Final-Memory-KiB-Used", collectgarbage("count"), false)

src/primary_names.lua

@@ -146,6 +146,8 @@ function primaryNames.createPrimaryNameRequest(name, initiator, timestamp, msgId
 	else
 		-- otherwise store the request for asynchronous approval
 		PrimaryNames.requests[initiator] = request
+		-- track the changes in the hyperbeam sync
+		HyperbeamSync.primaryNames.requests[initiator] = true
 		primaryNames.scheduleNextPrimaryNamesPruning(request.endTimestamp)
 	end
 
@@ -205,6 +207,7 @@ function primaryNames.approvePrimaryNameRequest(recipient, name, from, timestamp
 
 	-- set the primary name
 	local newPrimaryName = primaryNames.setPrimaryNameFromRequest(recipient, request, timestamp)
+
 	return {
 		newPrimaryName = newPrimaryName,
 		request = request,
@@ -228,6 +231,12 @@ function primaryNames.setPrimaryNameFromRequest(recipient, request, startTimesta
 		startTimestamp = startTimestamp,
 	}
 	PrimaryNames.requests[recipient] = nil
+
+	-- track the changes in the hyperbeam sync
+	HyperbeamSync.primaryNames.names[request.name] = true
+	HyperbeamSync.primaryNames.owners[recipient] = true
+	HyperbeamSync.primaryNames.requests[recipient] = true
+
 	return {
 		name = request.name,
 		owner = recipient,
@@ -247,6 +256,10 @@ function primaryNames.removePrimaryNames(names, from)
 	local removedPrimaryNamesAndOwners = {}
 	for _, name in pairs(names) do
 		local removedPrimaryNameAndOwner = primaryNames.removePrimaryName(name, from)
+		-- track the changes in the hyperbeam sync
+		HyperbeamSync.primaryNames.names[name] = true
+		HyperbeamSync.primaryNames.owners[from] = true
+
 		table.insert(removedPrimaryNamesAndOwners, removedPrimaryNameAndOwner)
 	end
 	return removedPrimaryNamesAndOwners
@@ -272,6 +285,12 @@ function primaryNames.removePrimaryName(name, from)
 	if PrimaryNames.requests[primaryName.owner] and PrimaryNames.requests[primaryName.owner].name == name then
 		PrimaryNames.requests[primaryName.owner] = nil
 	end
+
+	-- track the changes in the hyperbeam sync
+	HyperbeamSync.primaryNames.names[name] = true
+	HyperbeamSync.primaryNames.owners[primaryName.owner] = true
+	HyperbeamSync.primaryNames.requests[primaryName.owner] = true
+
 	return {
 		name = name,
 		owner = primaryName.owner,
@@ -348,6 +367,9 @@ function primaryNames.removePrimaryNamesForBaseName(baseName)
 	local primaryNamesForBaseName = primaryNames.getPrimaryNamesForBaseName(baseName)
 	for _, nameData in pairs(primaryNamesForBaseName) do
 		local removedName = primaryNames.removePrimaryName(nameData.name, nameData.owner)
+		-- track the changes in the hyperbeam sync
+		HyperbeamSync.primaryNames.names[nameData.name] = true
+		HyperbeamSync.primaryNames.owners[nameData.owner] = true
 		table.insert(removedNames, removedName)
 	end
 	return removedNames
@@ -410,6 +432,9 @@ function primaryNames.prunePrimaryNameRequests(timestamp)
 		if request.endTimestamp <= timestamp then
 			PrimaryNames.requests[initiator] = nil
 			prunedNameRequests[initiator] = request
+
+			-- track the changes in the hyperbeam sync
+			HyperbeamSync.primaryNames.requests[initiator] = true
 		else
 			primaryNames.scheduleNextPrimaryNamesPruning(request.endTimestamp)
 		end