@boostxyz/sdk 7.1.0 → 7.3.0

package/src/Actions/EventAction.ts

@@ -576,18 +576,25 @@ export class EventAction extends DeployableTarget<
         throw new ValidationAbiMissingError(signature);
       }
 
-      let address: Address | undefined;
       if ('logs' in params) {
-        for (let log of params.logs) {
+        const signatureMatchingLogs = params.logs
+          .filter((log) => log.topics[0] === signature)
+          .map((log) => decodeAndReorderLogArgs(event, log));
+
+        for (const log of signatureMatchingLogs) {
           if (!isAddressEqual(log.address, claimant.targetContract)) continue;
-          let addressCandidate = this.validateClaimantAgainstArgs(
+          const addressCandidate = this.validateClaimantAgainstArgs(
             claimant,
             log,
           );
-          if (addressCandidate) address = addressCandidate;
+          if (addressCandidate) return addressCandidate;
         }
-        return address;
       }
+
+      if (!('hash' in params)) {
+        return undefined;
+      }
+
       const receipt = await getTransactionReceipt(this._config, {
         ...params,
         chainId: claimant.chainid,
@@ -611,9 +618,8 @@ 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;
     }
     if (claimant.signatureType === SignatureType.FUNC && 'hash' in params) {
       const transaction = await getTransaction(this._config, {
@@ -1252,6 +1258,139 @@ export class EventAction extends DeployableTarget<
     }
     return false;
   }
+
+  /**
+   * Retrieves logs that match the criteria for event-based action steps.
+   *
+   * @public
+   * @async
+   * @param {ValidateActionStepParams} params - Parameters for fetching and filtering logs.
+   * @returns {Promise<EventLog[]>} - A promise that resolves to an array of matching event logs.
+   */
+  public async getLogsForActionSteps(
+    params: ValidateActionStepParams,
+  ): Promise<EventLog[]> {
+    const actionSteps = await this.getActionSteps();
+    const actionStepLogs: EventLog[] = [];
+
+    for (const actionStep of actionSteps) {
+      if (actionStep.signatureType === SignatureType.EVENT) {
+        const logs = await this.getLogsForActionStep(actionStep, params);
+        actionStepLogs.push(...logs);
+      }
+    }
+    return actionStepLogs;
+  }
+
+  /**
+   * Finds logs that match the criteria for a specific action step.
+   *
+   * @public
+   * @async
+   * @param {ActionStep} actionStep - The action step to find logs for
+   * @param {ValidateActionStepParams} params - Parameters for validation
+   * @returns {Promise<EventLog[]>}
+   */
+  public async getLogsForActionStep(
+    actionStep: ActionStep,
+    params: ValidateActionStepParams,
+  ): Promise<EventLog[]> {
+    if (actionStep.signatureType !== SignatureType.EVENT) {
+      return [];
+    }
+
+    const signature = actionStep.signature;
+    let event: AbiEvent;
+    if (params.abiItem) event = params.abiItem as AbiEvent;
+    else {
+      const sigPool = params.knownSignatures as Record<Hex, AbiEvent>;
+      event = sigPool[signature] as AbiEvent;
+    }
+
+    if (!event) {
+      throw new ValidationAbiMissingError(signature);
+    }
+
+    if ('logs' in params) {
+      return this.filterLogsByActionStepCriteria(
+        actionStep,
+        params.logs,
+        event,
+      );
+    }
+
+    const receipt = await getTransactionReceipt(this._config, {
+      ...params,
+      chainId: actionStep.chainid,
+    });
+
+    if (
+      params.notBeforeBlockNumber &&
+      receipt.blockNumber < params.notBeforeBlockNumber
+    ) {
+      return [];
+    }
+
+    // Special handling for Transfer events
+    if (actionStep.signature === TRANSFER_SIGNATURE) {
+      const { decodedLogs, event } = await this.decodeTransferLogs(receipt);
+      return this.filterLogsByActionStepCriteria(
+        actionStep,
+        decodedLogs,
+        event,
+      );
+    }
+
+    const decodedLogs = receipt.logs
+      .filter((log) => log.topics[0] === toEventSelector(event))
+      .map((log) => decodeAndReorderLogArgs(event, log));
+
+    return this.filterLogsByActionStepCriteria(actionStep, decodedLogs, event);
+  }
+
+  /**
+   * Filters logs that meet the given action step criteria
+   *
+   * @private
+   * @param {ActionStep} actionStep
+   * @param {EventLogs} logs
+   * @param {AbiEvent} eventAbi
+   * @returns {EventLog[]}
+   */
+  private filterLogsByActionStepCriteria(
+    actionStep: ActionStep,
+    logs: EventLogs,
+    eventAbi: AbiEvent,
+  ): EventLog[] {
+    const criteria = actionStep.actionParameter;
+    const filteredLogs: EventLog[] = [];
+
+    if (!logs.length) return filteredLogs;
+
+    for (let log of logs) {
+      if (!isAddressEqual(log.address, actionStep.targetContract)) continue;
+
+      try {
+        if (!Array.isArray(log.args)) {
+          continue;
+        }
+        const { value, type } = this.parseFieldFromAbi(
+          log.args,
+          criteria.fieldIndex,
+          eventAbi.inputs || [],
+          criteria.fieldType,
+        );
+        criteria.fieldType = type;
+        if (this.validateFieldAgainstCriteria(criteria, value, { log })) {
+          filteredLogs.push(log as EventLog);
+        }
+      } catch {
+        // If there's an error on this log, keep trying with the next one
+      }
+    }
+
+    return filteredLogs;
+  }
 }
 
 /**
@@ -1781,3 +1920,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,12 @@ import {
   zeroHash,
 } from 'viem';
 import { ERC20PeggedVariableCriteriaIncentiveV2 as ERC20PeggedVariableCriteriaIncentiveV2Bases } from '../../dist/deployments.json';
-import { SignatureType } from '../Actions/EventAction';
+import {
+  SignatureType,
+  decodeAndReorderLogArgs,
+  getScalarValueFromTuple,
+  isCriteriaFieldIndexTuple,
+} from '../Actions/EventAction';
 import type {
   DeployableOptions,
   GenericDeployableParams,
@@ -231,25 +236,63 @@ export class ERC20PeggedVariableCriteriaIncentiveV2 extends DeployableTarget<
    * @throws {InvalidCriteriaTypeError | NoMatchingLogsError | DecodedArgsError}
    */
   public async getIncentiveScalar(
-    { chainId, hash, knownSignatures }: GetIncentiveScalarV2Params,
+    { chainId, hash, knownSignatures, logs }: GetIncentiveScalarV2Params,
     params?: ReadParams,
   ): Promise<bigint> {
     const criteria = await this.getIncentiveCriteria(params);
     if (criteria.criteriaType === SignatureType.EVENT) {
-      const transactionReceipt = await getTransactionReceipt(this._config, {
-        chainId,
-        hash,
-      });
+      const eventAbi = knownSignatures[criteria.signature] as AbiEvent;
+
       if (criteria.fieldIndex === CheatCodes.GAS_REBATE_INCENTIVE) {
+        const transactionReceipt = await getTransactionReceipt(this._config, {
+          chainId,
+          hash,
+        });
         const totalCost =
           transactionReceipt.gasUsed * transactionReceipt.effectiveGasPrice + // Normal gas cost
           (transactionReceipt.blobGasUsed ?? 0n) *
             (transactionReceipt.blobGasPrice ?? 0n); // Blob gas cost - account for potential undefined values
         return totalCost;
       }
-      const logs = transactionReceipt.logs;
 
-      if (logs.length === 0) {
+      // if logs are provided, use them to extract the scalar
+      if (logs && logs.length > 0) {
+        try {
+          // only check logs that match the criteria signature
+          const signatureMatchingLogs = logs
+            .filter((log) => log.topics && log.topics[0] === criteria.signature)
+            .map((log) => decodeAndReorderLogArgs(eventAbi, log));
+
+          if (signatureMatchingLogs.length > 0) {
+            for (const log of signatureMatchingLogs) {
+              if (isCriteriaFieldIndexTuple(criteria.fieldIndex)) {
+                return getScalarValueFromTuple(
+                  log.args as unknown[],
+                  criteria.fieldIndex,
+                );
+              }
+              const scalarValue = log.args
+                ? (log.args as string[])[criteria.fieldIndex]
+                : undefined;
+              if (scalarValue !== undefined) {
+                return BigInt(scalarValue);
+              }
+            }
+          }
+        } catch (e) {
+          throw new DecodedArgsError(
+            `An error occurred while extracting scalar from logs: ${(e as Error).message}`,
+          );
+        }
+      }
+
+      const transactionReceipt = await getTransactionReceipt(this._config, {
+        chainId,
+        hash,
+      });
+      const receiptLogs = transactionReceipt.logs;
+
+      if (receiptLogs.length === 0) {
         throw new NoMatchingLogsError(
           `No logs found for event signature ${criteria.signature}`,
         );
@@ -257,21 +300,28 @@ 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],
-          logs,
+          logs: receiptLogs,
         });
         if (decodedEvents == undefined || decodedEvents.length === 0) {
           throw new NoMatchingLogsError(
             `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 +346,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

@@ -9,6 +9,7 @@ import {
   type AbiEvent,
   type AbiFunction,
   type Address,
+  type GetLogsReturnType,
   type Hex,
   decodeAbiParameters,
   decodeFunctionData,
@@ -19,7 +20,13 @@ import {
   zeroHash,
 } from 'viem';
 import { ERC20VariableCriteriaIncentiveV2 as ERC20VariableCriteriaIncentiveV2Bases } from '../../dist/deployments.json';
-import { SignatureType, ValueType } from '../Actions/EventAction';
+import {
+  SignatureType,
+  ValueType,
+  decodeAndReorderLogArgs,
+  getScalarValueFromTuple,
+  isCriteriaFieldIndexTuple,
+} from '../Actions/EventAction';
 import type {
   DeployableOptions,
   GenericDeployableParams,
@@ -110,6 +117,7 @@ export interface GetIncentiveScalarV2Params {
   chainId: number;
   hash: Hex;
   knownSignatures: Record<Hex, AbiFunction | AbiEvent>;
+  logs?: GetLogsReturnType<AbiEvent, AbiEvent[], true>;
 }
 
 /**
@@ -242,25 +250,63 @@ export class ERC20VariableCriteriaIncentiveV2 extends ERC20VariableIncentive<
    * @throws {InvalidCriteriaTypeError | NoMatchingLogsError | DecodedArgsError}
    */
   public async getIncentiveScalar(
-    { chainId, hash, knownSignatures }: GetIncentiveScalarV2Params,
+    { chainId, hash, knownSignatures, logs }: GetIncentiveScalarV2Params,
     params?: ReadParams,
   ): Promise<bigint> {
     const criteria = await this.getIncentiveCriteria(params);
     if (criteria.criteriaType === SignatureType.EVENT) {
-      const transactionReceipt = await getTransactionReceipt(this._config, {
-        chainId,
-        hash,
-      });
+      const eventAbi = knownSignatures[criteria.signature] as AbiEvent;
+
       if (criteria.fieldIndex === CheatCodes.GAS_REBATE_INCENTIVE) {
+        const transactionReceipt = await getTransactionReceipt(this._config, {
+          chainId,
+          hash,
+        });
         const totalCost =
           transactionReceipt.gasUsed * transactionReceipt.effectiveGasPrice + // Normal gas cost
           (transactionReceipt.blobGasUsed ?? 0n) *
             (transactionReceipt.blobGasPrice ?? 0n); // Blob gas cost - account for potential undefined values
         return totalCost;
       }
-      const logs = transactionReceipt.logs;
 
-      if (logs.length === 0) {
+      // if logs are provided, use them to extract the scalar
+      if (logs && logs.length > 0) {
+        try {
+          // only check logs that match the criteria signature
+          const signatureMatchingLogs = logs
+            .filter((log) => log.topics && log.topics[0] === criteria.signature)
+            .map((log) => decodeAndReorderLogArgs(eventAbi, log));
+
+          if (signatureMatchingLogs.length > 0) {
+            for (const log of signatureMatchingLogs) {
+              if (isCriteriaFieldIndexTuple(criteria.fieldIndex)) {
+                return getScalarValueFromTuple(
+                  log.args as unknown[],
+                  criteria.fieldIndex,
+                );
+              }
+              const scalarValue = log.args
+                ? (log.args as string[])[criteria.fieldIndex]
+                : undefined;
+              if (scalarValue !== undefined) {
+                return BigInt(scalarValue);
+              }
+            }
+          }
+        } catch (e) {
+          throw new DecodedArgsError(
+            `An error occurred while extracting scalar from logs: ${(e as Error).message}`,
+          );
+        }
+      }
+
+      const transactionReceipt = await getTransactionReceipt(this._config, {
+        chainId,
+        hash,
+      });
+      const receiptLogs = transactionReceipt.logs;
+
+      if (receiptLogs.length === 0) {
         throw new NoMatchingLogsError(
           `No logs found for event signature ${criteria.signature}`,
         );
@@ -268,21 +314,28 @@ 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],
-          logs,
+          logs: receiptLogs,
         });
         if (decodedEvents == undefined || decodedEvents.length === 0) {
           throw new NoMatchingLogsError(
             `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 +360,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(