@boostxyz/sdk 8.0.0-canary.0 → 8.0.0-canary.2

package/src/Actions/EventAction.test.ts

@@ -41,12 +41,10 @@ import {
   transactionSenderClaimant,
   packFieldIndexes,
   unpackFieldIndexes,
-  packCriteriaFieldIndexes,
-  unpackCriteriaFieldIndexes,
-  isCriteriaFieldIndexTuple,
   packClaimantFieldIndexes,
   decodeAndReorderLogArgs,
-  ActionClaimant
+  ActionClaimant,
+  getScalarValue,
 } from "./EventAction";
 import { allKnownSignatures } from "@boostxyz/test/allKnownSignatures";
 import { getTransactionReceipt } from "@wagmi/core";
@@ -1519,89 +1517,120 @@ describe('decodeAndReorderLogArgs', () => {
 }); 
 
 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("extracts scalar value from single-level tuple", () => {
+    const args = [123n, [456n, 789n], 999n];
+    const fieldIndex = packFieldIndexes([1, 0]);
+    const result = getScalarValue(args, fieldIndex);
+    expect(result).toBe(456n);
+  });
 
-    test("throws error if any index exceeds the allowed range (0-13)", () => {
-      expect(() => packCriteriaFieldIndexes([14, 5])).toThrowError(
-        "Tuple indices must be between 0-13"
-      );
+  test("extracts scalar value from two-level nested tuple", () => {
+    const args = [
+      100n,
+      [
+        200n,
+        [300n, 400n, 500n],
+        600n
+      ],
+      700n
+    ];
+    const fieldIndex = packFieldIndexes([1, 1, 2]);
 
-      expect(() => packCriteriaFieldIndexes([5, 14])).toThrowError(
-        "Tuple indices must be between 0-13"
-      );
+    const result = getScalarValue(args, fieldIndex);
+    expect(result).toBe(500n);
+  });
 
-      expect(() => packCriteriaFieldIndexes([-1, 5])).toThrowError(
-        "Tuple indices must be between 0-13"
-      );
-    });
+  test("extracts scalar value from three-level nested tuple", () => {
+    const args = [
+      [
+        [
+          [111n, 222n],
+          [333n, 444n]
+        ],
+        555n
+      ],
+      666n
+    ];
+    const fieldIndex = packFieldIndexes([0, 0, 1, 1]);
 
-    test("different input pairs result in different packed values", () => {
-      const packed1 = packCriteriaFieldIndexes([1, 2]);
-      const packed2 = packCriteriaFieldIndexes([2, 1]);
-      const packed3 = packCriteriaFieldIndexes([1, 3]);
+    const result = getScalarValue(args, fieldIndex);
+    expect(result).toBe(444n);
+  });
 
-      expect(packed1).not.toBe(packed2);
-      expect(packed1).not.toBe(packed3);
-      expect(packed2).not.toBe(packed3);
-    });
+  test("extracts scalar value from four-level nested tuple (max depth)", () => {
+    const args = [
+      [
+        [
+          [
+            [1n, 2n, 3n],
+            [4n, 5n, 6n]
+          ],
+          [[7n, 8n], [9n, 10n]]
+        ]
+      ]
+    ];
+    const fieldIndex = packFieldIndexes([0, 0, 0, 1, 2]);
+
+    const result = getScalarValue(args, fieldIndex);
+    expect(result).toBe(6n);
   });
 
-  describe("unpackCriteriaFieldIndexes", () => {
-    test("unpacks tuple index values (>= 32) correctly", () => {
-      const packed = packCriteriaFieldIndexes([4, 7]);
+  test("throws error when field index unpacks to empty array", () => {
+    const args = [123n, 456n];
+    const fieldIndex = 0xFFFFFFF;
 
-      const result = unpackCriteriaFieldIndexes(packed);
-      expect(result.length).toBe(2);
-      expect(result).toEqual([4, 7]);
-    });
+    expect(() => getScalarValue(args, fieldIndex)).toThrowError(
+      "Failed to unpack any indexes from fieldIndex"
+    );
+  });
 
-    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"
-      );
+  test("throws error when accessing non-array at intermediate level", () => {
+    const args = [123n, 'not-an-array', 789n];
+    const fieldIndex = packFieldIndexes([1, 0]);
 
-      expect(() => unpackCriteriaFieldIndexes(-1)).toThrowError(
-        "Field index must be between 32-253"
-      );
-    });
+    expect(() => getScalarValue(args, fieldIndex)).toThrowError(
+      "Expected array at level 1, but got string"
+    );
   });
 
-  describe("isCriteriaFieldIndexTuple", () => {
-    test("correctly identifies tuple indices vs simple indices", () => {
-      // Test with simple index (< 32)
-      expect(isCriteriaFieldIndexTuple(15)).toBe(false);
+  test("returns early if bigint is found at intermediate level", () => {
+    const args = [123n, 456n, 789n];
+    const fieldIndex = packFieldIndexes([1, 0]);
 
-      // Test with tuple index (>= 32)
-      const packed = packCriteriaFieldIndexes([2, 3]);
-      expect(isCriteriaFieldIndexTuple(packed)).toBe(true);
+    const result = getScalarValue(args, fieldIndex);
+    expect(result).toBe(456n);
+  });
 
-      // Test edge cases
-      expect(isCriteriaFieldIndexTuple(0)).toBe(false);
-      expect(isCriteriaFieldIndexTuple(31)).toBe(false);
-      expect(isCriteriaFieldIndexTuple(32)).toBe(true);
-    });
+  test("throws error when index is out of bounds", () => {
+    const args = [[100n, 200n], [300n]];
+    const fieldIndex = packFieldIndexes([1, 5]);
+
+    expect(() => getScalarValue(args, fieldIndex)).toThrowError(
+      "Index 5 is out of bounds at level 1. Array length is 1"
+    );
   });
 
-  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);
-        }
-      }
-    });
+  test("throws error when final value is not a bigint", () => {
+    const args = [["hello", "world"], [123n, 456n]];
+    const fieldIndex = packFieldIndexes([0, 0]);
+
+    expect(() => getScalarValue(args, fieldIndex)).toThrowError(
+      "Expected bigint at final position, but got string"
+    );
+  });
+
+  test("handles direct field access (single index)", () => {
+    const args = [111n, 222n, 333n];
+    const fieldIndex = packFieldIndexes([2]);
+
+    const result = getScalarValue(args, fieldIndex);
+    expect(result).toBe(333n);
+  });
+
+  test("throws error for index exceeding max field index", () => {
+    expect(() => packFieldIndexes([0, 64])).toThrowError(
+      "Index 64 exceeds the maximum allowed value"
+    );
   });
 });
 

package/src/Actions/EventAction.ts

@@ -1945,6 +1945,8 @@ export function decodeAndReorderLogArgs(event: AbiEvent, log: Log) {
 }
 
 /**
+ * @deprecated Do not use CriteriaFieldIndex methods. Use {@link packFieldIndexes} instead.
+ *
  * IMPORTANT: For variable incentive criteria use only.
  * Do NOT use for action steps - use {@link packFieldIndexes} instead.
  *
@@ -1977,6 +1979,8 @@ export function packCriteriaFieldIndexes([firstIndex, secondIndex]: [
 }
 
 /**
+ * @deprecated Do not use CriteriaFieldIndex methods. Use {@link unpackFieldIndexes} instead.
+ *
  * Unpacks a uint8 packed index value into an array of indices.
  *
  * @export
@@ -1997,6 +2001,8 @@ export function unpackCriteriaFieldIndexes(packed: number): [number, number] {
 }
 
 /**
+ * @deprecated Do not use CriteriaFieldIndex methods. Use {@link packFieldIndexes} instead.
+ *
  * Determines if a fieldIndex represents a tuple index (value >= 32) or a normal field index.
  *
  * @export
@@ -2038,55 +2044,76 @@ export function unpackClaimantFieldIndexes(packed: number): [number, number] {
 }
 
 /**
- * Extracts a scalar value from a tuple within event or function arguments.
- * This is used for incentive criteria when determining reward amounts.
+ * Extracts a scalar value from event or function arguments using a field index.
+ * Supports both direct field access and nested tuple access (up to 4 levels).
  *
  * @export
  * @param {unknown[]} args - The decoded arguments from an event or function call
- * @param {number} fieldIndex - The tuple-encoded index
+ * @param {number} fieldIndex - The packed field index (supports both direct and nested access)
  * @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)) {
+export function getScalarValue(args: unknown[], fieldIndex: number): bigint {
+  const indexes = unpackFieldIndexes(fieldIndex);
+
+  if (indexes.length === 0) {
     throw new DecodedArgsError(
-      `Field index ${fieldIndex} is invalid. Expected index >= 32`,
+      `Failed to unpack any indexes from fieldIndex ${fieldIndex}`,
     );
   }
 
-  const [index0, index1] = unpackCriteriaFieldIndexes(fieldIndex);
+  let scalarValue: unknown = args;
 
-  if (index0 === undefined || index1 === undefined) {
-    throw new DecodedArgsError(
-      `Failed to unpack field indexes from ${fieldIndex}`,
-    );
-  }
+  for (let level = 0; level < indexes.length; level++) {
+    const idx = indexes[level];
 
-  if (!args || args.length <= index0) {
-    throw new DecodedArgsError(`Decoded args missing item at index ${index0}`);
-  }
+    if (idx === undefined) {
+      throw new DecodedArgsError(`Undefined index at level ${level}`);
+    }
 
-  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}`,
-    );
+    if (typeof scalarValue === 'bigint') {
+      return scalarValue;
+    }
+
+    if (!Array.isArray(scalarValue)) {
+      throw new DecodedArgsError(
+        `Expected array at level ${level}, but got ${typeof scalarValue}`,
+      );
+    }
+
+    if (idx >= scalarValue.length) {
+      throw new DecodedArgsError(
+        `Index ${idx} is out of bounds at level ${level}. Array length is ${scalarValue.length}`,
+      );
+    }
+
+    scalarValue = scalarValue[idx];
   }
 
-  const scalarValue = tuple[index1] as unknown;
   if (typeof scalarValue !== 'bigint') {
     throw new DecodedArgsError(
-      `Expected bigint at tuple index ${index1}, but got ${typeof scalarValue}`,
+      `Expected bigint at final position, but got ${typeof scalarValue}`,
     );
   }
 
   return scalarValue;
 }
+
+/**
+ * @deprecated Use {@link getScalarValue} instead.
+ *
+ * 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 {
+  return getScalarValue(args, fieldIndex);
+}

package/src/Incentives/ERC20PeggedVariableCriteriaIncentiveV2.ts

@@ -38,8 +38,7 @@ import { ERC20PeggedVariableCriteriaIncentiveV2 as ERC20PeggedVariableCriteriaIn
 import {
   SignatureType,
   decodeAndReorderLogArgs,
-  getScalarValueFromTuple,
-  isCriteriaFieldIndexTuple,
+  getScalarValue,
 } from '../Actions/EventAction';
 import type {
   DeployableOptions,
@@ -269,17 +268,13 @@ export class ERC20PeggedVariableCriteriaIncentiveV2 extends DeployableTarget<
 
           if (signatureMatchingLogs.length > 0) {
             for (const log of signatureMatchingLogs) {
-              if (isCriteriaFieldIndexTuple(criteria.fieldIndex)) {
-                return getScalarValueFromTuple(
+              try {
+                return getScalarValue(
                   log.args as unknown[],
                   criteria.fieldIndex,
                 );
-              }
-              const scalarValue = log.args
-                ? (log.args as string[])[criteria.fieldIndex]
-                : undefined;
-              if (scalarValue !== undefined) {
-                return BigInt(scalarValue);
+              } catch {
+                continue;
               }
             }
           }
@@ -315,23 +310,10 @@ export class ERC20PeggedVariableCriteriaIncentiveV2 extends DeployableTarget<
           );
         }
 
-        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`,
-          );
-        }
-        return BigInt(scalarValue);
+        return getScalarValue(
+          decodedEvents[0]?.args as unknown[],
+          criteria.fieldIndex,
+        );
       } catch (e) {
         throw new DecodedArgsError(
           `Failed to decode event log for signature ${criteria.signature}: ${(e as Error).message}`,
@@ -351,20 +333,10 @@ export class ERC20PeggedVariableCriteriaIncentiveV2 extends DeployableTarget<
           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(
-            `Decoded argument at index ${criteria.fieldIndex} is undefined`,
-          );
-        }
-        return BigInt(scalarValue);
+        return getScalarValue(
+          decodedFunction.args as unknown[],
+          criteria.fieldIndex,
+        );
       } catch (e) {
         throw new DecodedArgsError(
           `Failed to decode function data for signature ${criteria.signature}: ${(e as Error).message}`,

package/src/Incentives/ERC20VariableCriteriaIncentiveV2.ts

@@ -24,8 +24,7 @@ import {
   SignatureType,
   ValueType,
   decodeAndReorderLogArgs,
-  getScalarValueFromTuple,
-  isCriteriaFieldIndexTuple,
+  getScalarValue,
 } from '../Actions/EventAction';
 import type {
   DeployableOptions,
@@ -283,17 +282,13 @@ export class ERC20VariableCriteriaIncentiveV2 extends ERC20VariableIncentive<
 
           if (signatureMatchingLogs.length > 0) {
             for (const log of signatureMatchingLogs) {
-              if (isCriteriaFieldIndexTuple(criteria.fieldIndex)) {
-                return getScalarValueFromTuple(
+              try {
+                return getScalarValue(
                   log.args as unknown[],
                   criteria.fieldIndex,
                 );
-              }
-              const scalarValue = log.args
-                ? (log.args as string[])[criteria.fieldIndex]
-                : undefined;
-              if (scalarValue !== undefined) {
-                return BigInt(scalarValue);
+              } catch {
+                continue;
               }
             }
           }
@@ -329,23 +324,10 @@ export class ERC20VariableCriteriaIncentiveV2 extends ERC20VariableIncentive<
           );
         }
 
-        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`,
-          );
-        }
-        return BigInt(scalarValue);
+        return getScalarValue(
+          decodedEvents[0]?.args as unknown[],
+          criteria.fieldIndex,
+        );
       } catch (e) {
         throw new DecodedArgsError(
           `Failed to decode event log for signature ${criteria.signature}: ${(e as Error).message}`,
@@ -365,20 +347,10 @@ export class ERC20VariableCriteriaIncentiveV2 extends ERC20VariableIncentive<
           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(
-            `Decoded argument at index ${criteria.fieldIndex} is undefined`,
-          );
-        }
-        return BigInt(scalarValue);
+        return getScalarValue(
+          decodedFunction.args as unknown[],
+          criteria.fieldIndex,
+        );
       } catch (e) {
         throw new DecodedArgsError(
           `Failed to decode function data for signature ${criteria.signature}: ${(e as Error).message}`,