@boostxyz/sdk 7.1.0 → 7.2.0

package/src/Actions/EventAction.test.ts

@@ -41,6 +41,9 @@ import {
   transactionSenderClaimant,
   packFieldIndexes,
   unpackFieldIndexes,
+  packCriteriaFieldIndexes,
+  unpackCriteriaFieldIndexes,
+  isCriteriaFieldIndexTuple,
   decodeAndReorderLogArgs
 } from "./EventAction";
 import { allKnownSignatures } from "@boostxyz/test/allKnownSignatures";
@@ -1512,3 +1515,90 @@ describe('decodeAndReorderLogArgs', () => {
     expect(result.args[3]).toBe(5284n);
   });
 }); 
+
+describe("criteria field index tuple support", () => {
+  describe("packCriteriaFieldIndexes", () => {
+    test("packs two indices into a single value", () => {
+      const packed = packCriteriaFieldIndexes([3, 5])
+      expect(packed).toBeGreaterThanOrEqual(32);
+      expect(packed).toBeLessThanOrEqual(253);
+    });
+
+    test("throws error if any index exceeds the allowed range (0-13)", () => {
+      expect(() => packCriteriaFieldIndexes([14, 5])).toThrowError(
+        "Tuple indices must be between 0-13"
+      );
+
+      expect(() => packCriteriaFieldIndexes([5, 14])).toThrowError(
+        "Tuple indices must be between 0-13"
+      );
+
+      expect(() => packCriteriaFieldIndexes([-1, 5])).toThrowError(
+        "Tuple indices must be between 0-13"
+      );
+    });
+
+    test("different input pairs result in different packed values", () => {
+      const packed1 = packCriteriaFieldIndexes([1, 2]);
+      const packed2 = packCriteriaFieldIndexes([2, 1]);
+      const packed3 = packCriteriaFieldIndexes([1, 3]);
+
+      expect(packed1).not.toBe(packed2);
+      expect(packed1).not.toBe(packed3);
+      expect(packed2).not.toBe(packed3);
+    });
+  });
+
+  describe("unpackCriteriaFieldIndexes", () => {
+    test("unpacks tuple index values (>= 32) correctly", () => {
+      const packed = packCriteriaFieldIndexes([4, 7]);
+
+      const result = unpackCriteriaFieldIndexes(packed);
+      expect(result.length).toBe(2);
+      expect(result).toEqual([4, 7]);
+    });
+
+    test("throws error if packed value is out of valid range", () => {
+      expect(() => unpackCriteriaFieldIndexes(15)).toThrowError(
+        "Field index must be between 32-253"
+      );
+      
+      expect(() => unpackCriteriaFieldIndexes(254)).toThrowError(
+        "Field index must be between 32-253"
+      );
+
+      expect(() => unpackCriteriaFieldIndexes(-1)).toThrowError(
+        "Field index must be between 32-253"
+      );
+    });
+  });
+
+  describe("isCriteriaFieldIndexTuple", () => {
+    test("correctly identifies tuple indices vs simple indices", () => {
+      // Test with simple index (< 32)
+      expect(isCriteriaFieldIndexTuple(15)).toBe(false);
+
+      // Test with tuple index (>= 32)
+      const packed = packCriteriaFieldIndexes([2, 3]);
+      expect(isCriteriaFieldIndexTuple(packed)).toBe(true);
+
+      // Test edge cases
+      expect(isCriteriaFieldIndexTuple(0)).toBe(false);
+      expect(isCriteriaFieldIndexTuple(31)).toBe(false);
+      expect(isCriteriaFieldIndexTuple(32)).toBe(true);
+    });
+  });
+
+  describe("criteria field index functions in practice", () => {
+    test("round-trip packing and unpacking preserves the original values", () => {
+      for (let i = 0; i <= 13; i++) {
+        for (let j = 0; j <= 13; j++) {
+          const original: [number, number] = [i, j];
+          const packed = packCriteriaFieldIndexes(original);
+          const unpacked = unpackCriteriaFieldIndexes(packed);
+          expect(unpacked).toEqual(original);
+        }
+      }
+    });
+  });
+});

package/src/Actions/EventAction.ts

@@ -584,7 +584,7 @@ export class EventAction extends DeployableTarget<
             claimant,
             log,
           );
-          if (addressCandidate) address = addressCandidate;
+          if (addressCandidate) return addressCandidate;
         }
         return address;
       }
@@ -611,7 +611,7 @@ export class EventAction extends DeployableTarget<
       for (let log of decodedLogs) {
         if (!isAddressEqual(log.address, claimant.targetContract)) continue;
         let addressCandidate = this.validateClaimantAgainstArgs(claimant, log);
-        if (addressCandidate) address = addressCandidate;
+        if (addressCandidate) return addressCandidate;
       }
       return address;
     }
@@ -1781,3 +1781,120 @@ export function decodeAndReorderLogArgs(event: AbiEvent, log: Log) {
     args: reorderedArgs,
   } as EventLog;
 }
+
+/**
+ * IMPORTANT: For variable incentive criteria use only.
+ * Do NOT use for action steps - use {@link packFieldIndexes} instead.
+ *
+ * Packs two field indices into a single uint8 value for criteria tuple access.
+ * Both indices must be between 0-13 to fit in the packed format.
+ *
+ * Uses an offset of 32 to avoid collision with normal field indices (which are 0-31),
+ * allowing the system to distinguish between direct field access and tuple access.
+ *
+ * @export
+ * @param {[number, number]} param0 - A tuple of [firstIndex, secondIndex]
+ * @returns {number} - Packed uint8 value with base offset of 32
+ * @throws {InvalidTupleEncodingError} - If either index is outside the valid range (0-13)
+ */
+export function packCriteriaFieldIndexes([firstIndex, secondIndex]: [
+  number,
+  number,
+]): number {
+  if (
+    firstIndex < 0 ||
+    firstIndex > 13 ||
+    secondIndex < 0 ||
+    secondIndex > 13
+  ) {
+    throw new InvalidTupleEncodingError(
+      `Tuple indices must be between 0-13, got: [${firstIndex}, ${secondIndex}]`,
+    );
+  }
+  return 32 + (firstIndex << 4) + secondIndex;
+}
+
+/**
+ * Unpacks a uint8 packed index value into an array of indices.
+ *
+ * @export
+ * @param {number} packed - Packed index value
+ * @returns {[number, number]} - [firstIndex, secondIndex]
+ */
+export function unpackCriteriaFieldIndexes(packed: number): [number, number] {
+  if (packed < 32 || packed > 253) {
+    throw new InvalidTupleEncodingError(
+      `Field index must be between 32-253, got: ${packed}`,
+    );
+  }
+
+  const tupleValue = packed - 32;
+  const firstIndex = (tupleValue >> 4) & 0xf;
+  const secondIndex = tupleValue & 0xf;
+  return [firstIndex, secondIndex];
+}
+
+/**
+ * Determines if a fieldIndex represents a tuple index (value >= 32) or a normal field index.
+ *
+ * @export
+ * @param {number} fieldIndex - The field index to check
+ * @returns {boolean} - True if it's a tuple index, false if it's a normal field index
+ */
+export function isCriteriaFieldIndexTuple(fieldIndex: number): boolean {
+  return fieldIndex >= 32;
+}
+
+/**
+ * Extracts a scalar value from a tuple within event or function arguments.
+ * This is used for incentive criteria when determining reward amounts.
+ *
+ * @export
+ * @param {unknown[]} args - The decoded arguments from an event or function call
+ * @param {number} fieldIndex - The tuple-encoded index
+ * @returns {bigint} The extracted scalar value as a bigint
+ * @throws {DecodedArgsError} If arguments are missing or cannot be converted to bigint
+ */
+export function getScalarValueFromTuple(
+  args: unknown[],
+  fieldIndex: number,
+): bigint {
+  if (!isCriteriaFieldIndexTuple(fieldIndex)) {
+    throw new DecodedArgsError(
+      `Field index ${fieldIndex} is invalid. Expected index >= 32`,
+    );
+  }
+
+  const [index0, index1] = unpackCriteriaFieldIndexes(fieldIndex);
+
+  if (index0 === undefined || index1 === undefined) {
+    throw new DecodedArgsError(
+      `Failed to unpack field indexes from ${fieldIndex}`,
+    );
+  }
+
+  if (!args || args.length <= index0) {
+    throw new DecodedArgsError(`Decoded args missing item at index ${index0}`);
+  }
+
+  const tuple = args[index0];
+  if (!tuple || !Array.isArray(tuple)) {
+    throw new DecodedArgsError(
+      `Expected array at index ${index0}, but got ${typeof tuple}`,
+    );
+  }
+  if (tuple.length <= index1) {
+    throw new DecodedArgsError(
+      `index ${index1} is out of bounds. tuple length is ${tuple.length}`,
+    );
+  }
+
+  const scalarValue = tuple[index1] as unknown;
+  if (typeof scalarValue !== 'bigint') {
+    throw new DecodedArgsError(
+      `Expected bigint at tuple index ${index1}, but got ${typeof scalarValue}`,
+    );
+  }
+
+  return scalarValue;
+}

package/src/Incentives/ERC20PeggedVariableCriteriaIncentiveV2.ts

@@ -35,7 +35,11 @@ import {
   zeroHash,
 } from 'viem';
 import { ERC20PeggedVariableCriteriaIncentiveV2 as ERC20PeggedVariableCriteriaIncentiveV2Bases } from '../../dist/deployments.json';
-import { SignatureType } from '../Actions/EventAction';
+import {
+  SignatureType,
+  getScalarValueFromTuple,
+  isCriteriaFieldIndexTuple,
+} from '../Actions/EventAction';
 import type {
   DeployableOptions,
   GenericDeployableParams,
@@ -257,7 +261,6 @@ export class ERC20PeggedVariableCriteriaIncentiveV2 extends DeployableTarget<
 
       // Decode the event log
       try {
-        // Decode function data
         const eventAbi = knownSignatures[criteria.signature] as AbiEvent;
         const decodedEvents = parseEventLogs({
           abi: [eventAbi],
@@ -268,10 +271,18 @@ export class ERC20PeggedVariableCriteriaIncentiveV2 extends DeployableTarget<
             `No logs found for event signature ${criteria.signature}`,
           );
         }
-        const scalarValue = (decodedEvents[0]?.args as string[])[
-          criteria.fieldIndex
-        ];
 
+        if (isCriteriaFieldIndexTuple(criteria.fieldIndex)) {
+          return getScalarValueFromTuple(
+            decodedEvents[0]?.args as unknown[],
+            criteria.fieldIndex,
+          );
+        }
+
+        const scalarValue =
+          decodedEvents[0] && decodedEvents[0].args
+            ? (decodedEvents[0].args as string[])[criteria.fieldIndex]
+            : undefined;
         if (scalarValue === undefined) {
           throw new DecodedArgsError(
             `Decoded argument at index ${criteria.fieldIndex} is undefined`,
@@ -296,6 +307,14 @@ export class ERC20PeggedVariableCriteriaIncentiveV2 extends DeployableTarget<
           abi: [func],
           data: transaction.input,
         });
+
+        if (isCriteriaFieldIndexTuple(criteria.fieldIndex)) {
+          return getScalarValueFromTuple(
+            decodedFunction.args as unknown[],
+            criteria.fieldIndex,
+          );
+        }
+
         const scalarValue = decodedFunction.args[criteria.fieldIndex] as string;
         if (scalarValue === undefined || scalarValue === null) {
           throw new DecodedArgsError(

package/src/Incentives/ERC20VariableCriteriaIncentiveV2.ts

@@ -19,7 +19,12 @@ import {
   zeroHash,
 } from 'viem';
 import { ERC20VariableCriteriaIncentiveV2 as ERC20VariableCriteriaIncentiveV2Bases } from '../../dist/deployments.json';
-import { SignatureType, ValueType } from '../Actions/EventAction';
+import {
+  SignatureType,
+  ValueType,
+  getScalarValueFromTuple,
+  isCriteriaFieldIndexTuple,
+} from '../Actions/EventAction';
 import type {
   DeployableOptions,
   GenericDeployableParams,
@@ -268,7 +273,6 @@ export class ERC20VariableCriteriaIncentiveV2 extends ERC20VariableIncentive<
 
       // Decode the event log
       try {
-        // Decode function data
         const eventAbi = knownSignatures[criteria.signature] as AbiEvent;
         const decodedEvents = parseEventLogs({
           abi: [eventAbi],
@@ -279,10 +283,18 @@ export class ERC20VariableCriteriaIncentiveV2 extends ERC20VariableIncentive<
             `No logs found for event signature ${criteria.signature}`,
           );
         }
-        const scalarValue = (decodedEvents[0]?.args as string[])[
-          criteria.fieldIndex
-        ];
 
+        if (isCriteriaFieldIndexTuple(criteria.fieldIndex)) {
+          return getScalarValueFromTuple(
+            decodedEvents[0]?.args as unknown[],
+            criteria.fieldIndex,
+          );
+        }
+
+        const scalarValue =
+          decodedEvents[0] && decodedEvents[0].args
+            ? (decodedEvents[0].args as string[])[criteria.fieldIndex]
+            : undefined;
         if (scalarValue === undefined) {
           throw new DecodedArgsError(
             `Decoded argument at index ${criteria.fieldIndex} is undefined`,
@@ -307,6 +319,14 @@ export class ERC20VariableCriteriaIncentiveV2 extends ERC20VariableIncentive<
           abi: [func],
           data: transaction.input,
         });
+
+        if (isCriteriaFieldIndexTuple(criteria.fieldIndex)) {
+          return getScalarValueFromTuple(
+            decodedFunction.args as unknown[],
+            criteria.fieldIndex,
+          );
+        }
+
         const scalarValue = decodedFunction.args[criteria.fieldIndex] as string;
         if (scalarValue === undefined || scalarValue === null) {
           throw new DecodedArgsError(