fix(PE-8643): setup patch for balances and primary names in hb patch system

src/globals.lua

@@ -2,6 +2,26 @@ local constants = require(".src.constants")
 local utils = require(".src.utils")
 local globals = {}
 
+--[[
+	HyperbeamSync is a table that is used to track changes to our lua state that need to be synced to the Hyperbeam.
+	the principle 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, number> 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 = {},
+		},
+	}
+
 --[[
     Constants
 ]]

src/hb.lua

@@ -1,41 +1,126 @@
 -- hb.lua needs to be in its own file and not in balances.lua to avoid circular dependencies
 local hb = {}
 
----@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)
-	assert(type(oldBalances) == "table", "Old balances must be a table")
+---@return table<string, string>|nil affectedBalancesAddresses table of addresses and their balance values as strings
+function hb.createBalancesPatch()
 	local affectedBalancesAddresses = {}
-	for address, _ in pairs(oldBalances) do
-		if Balances[address] ~= oldBalances[address] then
+	for address, _ in pairs(Balances) do
+		if HyperbeamSync.balances[address] ~= Balances[address] then
 			affectedBalancesAddresses[address] = true
 		end
 	end
-	for address, _ in pairs(Balances) do
-		if oldBalances[address] ~= Balances[address] then
+
+	for address, _ in pairs(HyperbeamSync.balances) do
+		if Balances[address] ~= HyperbeamSync.balances[address] then
 			affectedBalancesAddresses[address] = true
 		end
 	end
 
-	--- For simplicity we always include the protocol balance in the patch message
-	--- this also prevents us from sending an empty patch message and deleting the entire hyperbeam balances table\
+	-- Convert all affected addresses from boolean flags to actual balance values
+	local balancesPatch = {}
+	for address, _ in pairs(affectedBalancesAddresses) do
+		balancesPatch[address] = tostring(Balances[address] or 0)
+	end
+
+	if next(balancesPatch) == nil then
+		return nil
+	end
 
-	local patchMessage = {
-		device = "[email protected]",
-		balances = { [ao.id] = tostring(Balances[ao.id] or 0) },
+	return balancesPatch
+end
+
+---@return PrimaryNames|nil affectedPrimaryNamesAddresses
+function hb.createPrimaryNamesPatch()
+	---@type PrimaryNames
+	local affectedPrimaryNamesAddresses = {
+		names = {},
+		owners = {},
+		requests = {},
 	}
-	for address, _ in pairs(affectedBalancesAddresses) do
-		patchMessage.balances[address] = tostring(Balances[address] or 0)
+
+	-- if no changes, return early. This will allow downstream code to not send the patch state for this key ('primary-names')
+	if
+		next(_G.HyperbeamSync.primaryNames.names) == nil
+		and next(_G.HyperbeamSync.primaryNames.owners) == nil
+		and next(_G.HyperbeamSync.primaryNames.requests) == nil
+	then
+		return nil
+	end
+
+	-- build the affected primary names addresses table for the patch message
+	for name, _ in pairs(_G.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(_G.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(_G.HyperbeamSync.primaryNames.requests) do
+		-- we need to send an empty table to remove the request
+		affectedPrimaryNamesAddresses.requests[address] = PrimaryNames.requests[address] or {}
+	end
+
+	-- Setting the property to {} will nuke the entire table from patch device state
+	-- We do this because we want to remove the entire table from patch device state if it's empty
+	if next(PrimaryNames.names) == nil then
+		affectedPrimaryNamesAddresses.names = {}
+	-- setting the property to nil will remove it from the patch message entirely to avoid sending an empty table and nuking patch device state
+	-- We do this to AVOID sending an empty table and nuking patch device state if our lua state is not empty.
+	elseif next(affectedPrimaryNamesAddresses.names) == nil then
+		affectedPrimaryNamesAddresses.names = nil
+	end
+
+	if next(PrimaryNames.owners) == nil then
+		affectedPrimaryNamesAddresses.owners = {}
+	elseif next(affectedPrimaryNamesAddresses.owners) == nil then
+		affectedPrimaryNamesAddresses.owners = nil
+	end
+
+	if next(PrimaryNames.requests) == nil then
+		affectedPrimaryNamesAddresses.requests = {}
+	elseif next(affectedPrimaryNamesAddresses.requests) == nil then
+		affectedPrimaryNamesAddresses.requests = nil
+	end
+
+	-- if we're not sending any data, return nil which will allow downstream code to not send the patch message
+	-- We do this to AVOID sending an empty table and nuking patch device state if our lua state is not empty.
+	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()
+	-- Only add patches that have data
+	local primaryNamesPatch = hb.createPrimaryNamesPatch()
+	if primaryNamesPatch then
+		ao.send({ device = "[email protected]", ["primary-names"] = primaryNamesPatch })
 	end
 
-	-- only send the patch message if there are affected balances, otherwise we'll end up deleting the entire hyperbeam balances table
-	if next(patchMessage.balances) == nil then
-		return {}
-	else
-		ao.send(patchMessage)
+	local balancesPatch = hb.createBalancesPatch()
+	if balancesPatch then
+		ao.send({ device = "[email protected]", balances = balancesPatch })
 	end
 
-	return affectedBalancesAddresses
+	hb.resetHyperbeamSync()
 end
 
 return hb

src/main.lua

@@ -476,9 +476,10 @@ local function addEventingHandler(handlerName, pattern, handleFn, critical, prin
 	Handlers.add(handlerName, pattern, function(msg)
 		-- 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)
@@ -503,9 +504,8 @@ local function addEventingHandler(handlerName, pattern, handleFn, critical, prin
 			error(errorWithEvent, 0) -- 0 ensures not to include this line number in the error message
 		end
 
-		-- Send patch message to HB
-		if oldBalances then
-			hb.patchBalances(oldBalances)
+		if shouldPatchHbState then
+			hb.patchHyperbeamState()
 		end
 
 		msg.ioEvent:addField("Handler-Memory-KiB-Used", collectgarbage("count"), false)
@@ -529,6 +529,9 @@ end, CRITICAL, false)
 addEventingHandler("prune", function()
 	return "continue" -- continue is a pattern that matches every message and continues to the next handler that matches the tags
 end, function(msg)
+	-- We copy the balances here and put them in HyperbeamSync so that in subsequent handlers we can compare the previous and new balances and send a patch message if there are any changes
+	HyperbeamSync.balances = utils.deepCopy(Balances)
+
 	local epochIndex = epochs.getEpochIndexForTimestamp(msg.Timestamp)
 	msg.ioEvent:addField("Epoch-Index", epochIndex)
 

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[removedPrimaryNameAndOwner.owner] = 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

tests/gar.test.mjs

@@ -980,7 +980,7 @@ describe('GatewayRegistry', async () => {
         delete decreaseDelegateStakeResult.Messages[0].Data;
         assert.deepStrictEqual(decreaseDelegateStakeResult.Messages[0], {
           Target: delegatorAddress,
-          Anchor: '00000000000000000000000000000013',
+          Anchor: '00000000000000000000000000000012',
           Tags: [
             {
               name: 'Action',
@@ -1020,7 +1020,7 @@ describe('GatewayRegistry', async () => {
             },
             {
               name: 'Ref_',
-              value: '13',
+              value: '12',
             },
             {
               name: 'Type',
@@ -1754,7 +1754,7 @@ describe('GatewayRegistry', async () => {
         memory: gatewayMemory,
       });
 
-      assert.equal(result.Messages.length, 2);
+      assert.equal(result.Messages.length, 1);
       assert.equal(result.Messages[0].Target, observerAddress);
       assert.deepEqual(JSON.parse(result.Messages[0].Data), {
         reports: {
@@ -1776,7 +1776,7 @@ describe('GatewayRegistry', async () => {
         shouldAssertNoResultError: false,
       });
 
-      assert.equal(result.Messages.length, 2);
+      assert.equal(result.Messages.length, 1);
       assert.equal(result.Messages[0].Target, invalidObserver);
       assert.ok(
         result.Messages[0].Data.includes(
@@ -1795,7 +1795,7 @@ describe('GatewayRegistry', async () => {
         memory: gatewayMemory,
         shouldAssertNoResultError: false,
       });
-      assert.equal(result.Messages.length, 2);
+      assert.equal(result.Messages.length, 1);
       assert.ok(
         result.Messages[0].Data.includes(
           'Invalid report tx id. Must be a valid Arweave address.',
@@ -1814,7 +1814,7 @@ describe('GatewayRegistry', async () => {
         shouldAssertNoResultError: false,
       });
 
-      assert.equal(result.Messages?.length, 2);
+      assert.equal(result.Messages?.length, 1);
       assert.ok(
         result.Messages[0].Data.includes('Invalid failed gateway address:'),
       );
@@ -1831,7 +1831,7 @@ describe('GatewayRegistry', async () => {
         shouldAssertNoResultError: false,
       });
 
-      assert.equal(result.Messages.length, 2);
+      assert.equal(result.Messages.length, 1);
       assert.ok(
         result.Messages[0].Data.includes(
           `Observations for epoch 0 must be submitted after ${epochSettings.epochZeroStartTimestamp}`,
@@ -1851,7 +1851,7 @@ describe('GatewayRegistry', async () => {
         shouldAssertNoResultError: false,
       });
 
-      assert.equal(result.Messages.length, 2);
+      assert.equal(result.Messages.length, 1);
       assert.ok(
         result.Messages[0].Data.includes(
           `Observations for epoch 0 must be submitted before ${epochSettings.epochZeroStartTimestamp + epochSettings.durationMs}`,