@boostxyz/sdk 0.0.0-alpha.9 → 1.1.0-alpha.22

package/src/Actions/EventAction.ts

@@ -7,29 +7,52 @@ import {
 } from '@boostxyz/evm';
 import { bytecode } from '@boostxyz/evm/artifacts/contracts/actions/EventAction.sol/EventAction.json';
 import events from '@boostxyz/signatures/events';
+import functions from '@boostxyz/signatures/functions';
+import {
+  GetTransactionReceiptParameters,
+  getTransaction,
+  getTransactionReceipt,
+} from '@wagmi/core';
+import { match } from 'ts-pattern';
 import {
   type Abi,
   type AbiEvent,
+  type AbiFunction,
+  AbiItem,
   type Address,
   type ContractEventName,
+  type ContractFunctionName,
+  type GetLogsReturnType,
+  type GetTransactionParameters,
   type Hex,
   type Log,
+  type PublicClient,
+  type Transaction,
+  decodeEventLog,
+  decodeFunctionData,
   encodeAbiParameters,
+  fromHex,
+  isAddress,
   isAddressEqual,
+  zeroHash,
 } from 'viem';
-import { getLogs } from 'viem/actions';
+import { EventAction as EventActionBases } from '../../dist/deployments.json';
 import type {
   DeployableOptions,
   GenericDeployableParams,
 } from '../Deployable/Deployable';
 import { DeployableTarget } from '../Deployable/DeployableTarget';
 import {
+  DecodedArgsMalformedError,
   FieldValueNotComparableError,
   FieldValueUndefinedError,
+  FunctionDataDecodeError,
   InvalidNumericalCriteriaError,
   NoEventActionStepsProvidedError,
   TooManyEventActionStepsProvidedError,
+  UnparseableAbiParamError,
   UnrecognizedFilterTypeError,
+  ValidationAbiMissingError,
 } from '../errors';
 import {
   type GetLogsParams,
@@ -55,6 +78,7 @@ export enum FilterType {
   GREATER_THAN = 2,
   LESS_THAN = 3,
   CONTAINS = 4,
+  REGEX = 5,
 }
 
 /**
@@ -198,6 +222,22 @@ export interface ActionStep {
    */
   actionParameter: Criteria;
 }
+
+/**
+ * Parameters for validating an action step.
+ *
+ * @typedef {Object} ValidateActionStepParams
+ * @property {Record<Hex, AbiEvent | AbiFunction>} [knownSignatures] - Optional record of known events, keyed by 32 byte selectors.
+ * @property {AbiEvent | AbiFunction} [abiItem] - Optional ABI item definition.
+ * @property {EventLogs} [logs] - Event logs to validate against. Required if 'hash' is not provided.
+ * @property {Hex} [hash] - Transaction hash to validate against. Required if 'logs' is not provided.
+ * @property {number} [chainId] - Chain ID for the transaction. Required if 'hash' is provided.
+ */
+export type ValidateActionStepParams = {
+  knownSignatures?: Record<Hex, AbiEvent | AbiFunction>;
+  abiItem?: AbiEvent | AbiFunction;
+} & ({ logs: EventLogs } | { hash: Hex; chainId: number });
+
 /**
  * You can either supply a simplified version of the payload, or one that explicitly declares action steps.
  *
@@ -280,6 +320,24 @@ export interface EventActionPayloadRaw {
   actionStepFour: ActionStep;
 }
 
+/**
+ * Array of event logs to pass into TxParams
+ * @export
+ * @typedef {EventLogs}
+ */
+export type EventLogs = GetLogsReturnType<AbiEvent, AbiEvent[], true>;
+
+/**
+ * Getter params from the event action contract
+ *
+ * @export
+ * @typedef {ReadEventActionParams}
+ * @param {fnName} fnName - The getter function name
+ */
+export type ReadEventActionParams<
+  fnName extends ContractFunctionName<typeof eventActionAbi, 'pure' | 'view'>,
+> = ReadParams<typeof eventActionAbi, fnName>;
+
 /**
  * A generic event action
  *
@@ -305,9 +363,11 @@ export class EventAction extends DeployableTarget<
    *
    * @public
    * @static
-   * @type {Address}
+   * @type {Record<number, Address>}
    */
-  public static override base: Address = import.meta.env.VITE_EVENT_ACTION_BASE;
+  public static override bases: Record<number, Address> = {
+    ...(EventActionBases as Record<number, Address>),
+  };
   /**
    * @inheritdoc
    *
@@ -323,12 +383,12 @@ export class EventAction extends DeployableTarget<
    * @public
    * @async
    * @param {number} index The index of the action event to retrieve
-   * @param {?ReadParams<typeof eventActionAbi, 'getActionStep'>} [params]
+   * @param {?ReadEventActionParams<'getActionStep'>} [params]
    * @returns {Promise<ActionStep>}
    */
   public async getActionStep(
     index: number,
-    params?: ReadParams<typeof eventActionAbi, 'getActionStep'>,
+    params?: ReadEventActionParams<'getActionStep'>,
   ) {
     const steps = await this.getActionSteps(params);
     return steps.at(index);
@@ -339,11 +399,11 @@ export class EventAction extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof eventActionAbi, 'getActionSteps'>} [params]
+   * @param {?ReadEventActionParams<'getActionSteps'>} [params]
    * @returns {Promise<ActionStep[]>}
    */
   public async getActionSteps(
-    params?: ReadParams<typeof eventActionAbi, 'getActionSteps'>,
+    params?: ReadEventActionParams<'getActionSteps'>,
   ) {
     const steps = (await readEventActionGetActionSteps(this._config, {
       address: this.assertValidAddress(),
@@ -359,11 +419,11 @@ export class EventAction extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof eventActionAbi, 'getActionStepsCount'>} [params]
+   * @param {?ReadEventActionParams<'getActionStepsCount'>} [params]
    * @returns {Promise<bigint>}
    */
   public async getActionStepsCount(
-    params?: ReadParams<typeof eventActionAbi, 'getActionStepsCount'>,
+    params?: ReadEventActionParams<'getActionStepsCount'>,
   ) {
     const steps = await this.getActionSteps(params);
     return steps.length;
@@ -374,17 +434,16 @@ export class EventAction extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof eventActionAbi, 'getActionClaimant'>} [params]
+   * @param {?ReadEventActionParams<'getActionClaimant'>} [params]
    * @returns {Promise<ActionClaimant>}
    */
   public async getActionClaimant(
-    params?: ReadParams<typeof eventActionAbi, 'getActionClaimant'>,
-  ) {
+    params?: ReadEventActionParams<'getActionClaimant'>,
+  ): Promise<ActionClaimant> {
     const result = (await readEventActionGetActionClaimant(this._config, {
       address: this.assertValidAddress(),
       ...this.optionallyAttachAccount(),
-      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
-      ...(params as any),
+      ...params,
     })) as RawActionClaimant;
     return _fromRawActionStep(result);
   }
@@ -395,7 +454,7 @@ export class EventAction extends DeployableTarget<
    * @public
    * @async
    * @param {Hex} data
-   * @param {?WriteParams<typeof eventActionAbi, 'execute'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<readonly [boolean, `0x${string}`]>}
    */
   public async execute(
@@ -411,8 +470,8 @@ export class EventAction extends DeployableTarget<
    * @public
    * @async
    * @param {Hex} data
-   * @param {?WriteParams<typeof eventActionAbi, 'execute'>} [params]
-   * @returns {unknown}
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: readonly [boolean, `0x${string}`]; }>}
    */
   public async executeRaw(
     data: Hex,
@@ -429,27 +488,154 @@ export class EventAction extends DeployableTarget<
     return { hash, result };
   }
 
+  /**
+   * Derives the action claimant address from a transaction based on the provided ActionClaimant configuration.
+   * This method supports both event-based and function-based claimant derivation.
+   *
+   ** @example
+   * // Example usage
+   * const eventAction = boost.action as EventAction
+   * const claimant = await eventAction.getActionClaimant() // {
+   *   signatureType: SignatureType.EVENT,
+   *   signature: '0x1234...',
+   *   fieldIndex: 2,
+   *   targetContract: '0xabcd...',
+   *   chainid: 1
+   * };
+   * const params: ValidateActionStepParams = {
+   *   hash: '0x5678...',
+   *   chainId: 1,
+   *   knownSignatures?: {
+   *     '0x1234...': {}
+   *   }
+   * };
+   * const claimantAddress = await eventAction.deriveActionClaimantFromTransaction(claimant, params);
+   *
+   * @param {ActionClaimant} claimant - The configuration specifying how to derive the claimant.
+   * @param {ValidateActionStepParams} params - Parameters for validation, including transaction hash, known signatures, logs, and chain ID.
+   * @returns {Promise<Address | undefined>} The derived claimant address if found, undefined otherwise.
+   * @throws {ValidationAbiMissingError} If the ABI for the specified signature is not found.
+   * @throws {FunctionDataDecodeError} If there's an error decoding function data (for function-based derivation).
+   */
+  public async deriveActionClaimantFromTransaction(
+    claimant: ActionClaimant,
+    params: ValidateActionStepParams,
+  ): Promise<Address | undefined> {
+    const signature = claimant.signature;
+    if (claimant.signatureType === SignatureType.EVENT) {
+      let event: AbiEvent;
+      if (params.abiItem) event = params.abiItem as AbiEvent;
+      else {
+        const sigPool: Record<Hex, AbiEvent> = {
+          ...(events.abi as Record<Hex, AbiEvent>),
+          ...((params.knownSignatures as Record<Hex, AbiEvent>) || {}),
+        };
+        event = sigPool[signature] as AbiEvent;
+      }
+
+      if (!event) {
+        throw new ValidationAbiMissingError(signature);
+      }
+
+      let address: Address | undefined;
+      if ('logs' in params) {
+        for (let log of params.logs) {
+          if (!isAddressEqual(log.address, claimant.targetContract)) continue;
+          let addressCandidate = this.validateClaimantAgainstArgs(
+            claimant,
+            log,
+          );
+          if (addressCandidate) address = addressCandidate;
+        }
+        return address;
+      }
+      const receipt = await getTransactionReceipt(this._config, params);
+      const decodedLogs = receipt.logs.map((log) => {
+        const { eventName, args } = decodeEventLog({
+          abi: [event],
+          data: log.data,
+          topics: log.topics,
+        });
+        return { ...log, eventName, args };
+      });
+
+      for (let log of decodedLogs) {
+        if (!isAddressEqual(log.address, claimant.targetContract)) continue;
+        let addressCandidate = this.validateClaimantAgainstArgs(claimant, log);
+        if (addressCandidate) address = addressCandidate;
+      }
+      return address;
+    }
+    if (
+      claimant.signatureType === SignatureType.FUNC &&
+      'hash' in params &&
+      'chainId' in params
+    ) {
+      const transaction = await getTransaction(this._config, {
+        hash: params.hash,
+      });
+      if (!isAddressEqual(transaction.to!, claimant.targetContract)) return;
+      let func: AbiFunction;
+      if (params.abiItem) func = params.abiItem as AbiFunction;
+      else {
+        const sigPool: Record<Hex, AbiFunction> = {
+          ...(functions.abi as Record<Hex, AbiFunction>),
+          ...((params.knownSignatures as Record<Hex, AbiFunction>) || {}),
+        };
+        func = sigPool[signature] as AbiFunction;
+      }
+      if (!func) {
+        throw new ValidationAbiMissingError(claimant.signature);
+      }
+      let decodedData;
+      try {
+        decodedData = decodeFunctionData({
+          abi: [func],
+          data: transaction.input,
+        });
+      } catch (e) {
+        throw new FunctionDataDecodeError([func], e as Error);
+      }
+      return this.validateClaimantAgainstArgs(claimant, decodedData);
+    }
+  }
+
+  /**
+   * Validates the action claimant against the arguments of a log or function data.
+   *
+   * @param {ActionClaimant} claimant - The action claimant to validate.
+   * @param {Object} [logOrFnData] - Optional object containing the arguments to validate against.
+   * @param {Array<any> | readonly unknown[] | Record<string, unknown>} [logOrFnData.args] - The arguments from the log or function data.
+   * @returns {Address | undefined} The validated address if found and valid, otherwise undefined.
+   */
+  public validateClaimantAgainstArgs(
+    claimant: ActionClaimant,
+    logOrFnData?: {
+      args: Array<unknown> | readonly unknown[] | Record<string, unknown>;
+    },
+  ): Address | undefined {
+    if (
+      !logOrFnData ||
+      !Array.isArray(logOrFnData?.args) ||
+      logOrFnData?.args.length <= claimant.fieldIndex
+    ) {
+      return;
+    }
+    const maybeAddress = logOrFnData.args.at(claimant.fieldIndex);
+    if (isAddress(maybeAddress)) return maybeAddress;
+  }
+
   /**
    * Retrieves action steps, and uses them to validate against, and optionally fetch logs that match the step's signature.
    * If logs are provided in the optional `params` argument, then those logs will be used instead of fetched with the configured client.
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof eventActionAbi, 'getActionSteps'> &
-   *       GetLogsParams<Abi, ContractEventName<Abi>> & {
-   *         knownEvents?: Record<Hex, AbiEvent>;
-   *         logs?: Log[];
-   *       }} [params]
+   * @param ValidateActionStepParams params
    * @returns {Promise<boolean>}
    */
-  public async validateActionSteps(
-    params?: ReadParams<typeof eventActionAbi, 'getActionSteps'> &
-      GetLogsParams<Abi, ContractEventName<Abi>> & {
-        knownEvents?: Record<Hex, AbiEvent>;
-        logs?: Log[];
-      },
-  ) {
-    const actionSteps = await this.getActionSteps(params);
+  public async validateActionSteps(params: ValidateActionStepParams) {
+    const actionSteps = await this.getActionSteps();
     for (const actionStep of actionSteps) {
       if (!(await this.isActionStepValid(actionStep, params))) {
         return false;
@@ -459,108 +645,341 @@ export class EventAction extends DeployableTarget<
   }
 
   /**
-   * Validates a single action step with a given criteria against logs.
-   * If logs are provided in the optional `params` argument, then those logs will be used instead of fetched with the configured client.
+   * Validates a single action step with a given criteria against logs or function calls.
+   * If logs are provided in the optional `params` argument, then those logs will be used instead of being fetched with the configured client.
+   * For functions a hash is required.
    *
    * @public
    * @async
-   * @param {ActionStep} actionStep
-   * @param {?GetLogsParams<Abi, ContractEventName<Abi>> & {
-   *       knownEvents?: Record<Hex, AbiEvent>;
-   *       logs?: Log[];
-   *     }} [params]
+   * @param {ActionStep} actionStep - The action step to validate. Can be a function of event step.
+   * @param {ValidateActionStepParams} params - Additional parameters for validation, including hash, known events, logs, and chain ID.
    * @returns {Promise<boolean>}
    */
   public async isActionStepValid(
     actionStep: ActionStep,
-    params?: GetLogsParams<Abi, ContractEventName<Abi>> & {
-      knownEvents?: Record<Hex, AbiEvent>;
-      logs?: Log[];
-    },
+    params: ValidateActionStepParams,
   ) {
-    const criteria = actionStep.actionParameter;
-    const signature = actionStep.signature;
-    let event: AbiEvent;
-    // Lookup ABI based on event signature
-    if (params?.knownEvents) {
-      event = params.knownEvents[signature] as AbiEvent;
-    } else {
-      event = (events.abi as Record<Hex, AbiEvent>)[signature] as AbiEvent;
+    if (actionStep.signatureType === SignatureType.EVENT) {
+      const signature = actionStep.signature;
+      let event: AbiEvent;
+      if (params.abiItem) event = params.abiItem as AbiEvent;
+      else {
+        const sigPool: Record<Hex, AbiEvent> = {
+          ...(events.abi as Record<Hex, AbiEvent>),
+          ...((params.knownSignatures as Record<Hex, AbiEvent>) || {}),
+        };
+        event = sigPool[signature] as AbiEvent;
+      }
+
+      if (!event) {
+        throw new ValidationAbiMissingError(signature);
+      }
+
+      if (this.isArraylikeIndexed(actionStep, event)) {
+        // If the field is indexed, we can't filter on it
+        throw new UnparseableAbiParamError(
+          actionStep.actionParameter.fieldIndex,
+          event,
+        );
+      }
+
+      // Use the provided logs, no need to fetch receipt
+      if ('logs' in params) {
+        return this.isActionEventValid(actionStep, params.logs);
+      }
+
+      const client = this._config.getClient({
+        chainId: params.chainId,
+      }) as PublicClient;
+      const receipt = await client.getTransactionReceipt({
+        hash: params.hash,
+      });
+      const decodedLogs = receipt.logs.map((log) => {
+        const { eventName, args } = decodeEventLog({
+          abi: [event],
+          data: log.data,
+          topics: log.topics,
+        });
+
+        return { ...log, eventName, args };
+      });
+
+      return this.isActionEventValid(actionStep, decodedLogs);
     }
-    if (!event) {
-      throw new Error(`No known ABI for given event signature: ${signature}`);
+    if (actionStep.signatureType === SignatureType.FUNC) {
+      if ('hash' in params && 'chainId' in params) {
+        const client = this._config.getClient({
+          chainId: params.chainId,
+        }) as PublicClient;
+        const transaction = await client.getTransaction({
+          hash: params.hash,
+        });
+        return this.isActionFunctionValid(actionStep, transaction, params);
+      }
     }
-    const targetContract = actionStep.targetContract;
-    // Get all logs matching the event signature from the target contract
-    const logs =
-      params?.logs ||
-      (await getLogs(this._config.getClient({ chainId: params?.chainId }), {
-        // biome-ignore lint/suspicious/noExplicitAny: <explanation>
-        ...(params as any),
-        address: targetContract,
-        event,
-      }));
+    return false;
+  }
+
+  /**
+   * Validates a single action event with a given criteria against logs.
+   * If logs are provided in the optional `params` argument, then those logs will be used instead of being fetched with the configured client.
+   *
+   * @public
+   * @async
+   * @param {ActionStep} actionStep - The action step containing the event to validate.
+   * @param {EventLogs} logs - Event logs to validate the given step against
+   * @returns {Promise<boolean>} Resolves to true if the action event is valid, throws if input is invalid, otherwise false.
+   */
+  public isActionEventValid(actionStep: ActionStep, logs: EventLogs) {
+    const criteria = actionStep.actionParameter;
     if (!logs.length) return false;
     for (let log of logs) {
-      if (!this.validateLogAgainstCriteria(criteria, log)) {
-        return false;
+      if (this.validateLogAgainstCriteria(criteria, log)) {
+        return true;
       }
     }
-    return true;
+    return false;
   }
 
   /**
-   * Validates a {@link Log} against a given criteria.
+   * Validates a single action function with a given criteria against the transaction input.
+   *
+   * @public
+   * @param {ActionStep} actionStep - The action step containing the function to validate.
+   * @param {Transaction} transaction - The transaction that will be validated against.
+   * @param {Object} [params] - Optional parameters for validation.
+   * @param {AbiItem} [params.abiItem] - The ABI item for the function, if known.
+   * @param {Record<Hex, AbiEvent | AbiFunction>} [params.knownSignatures] - A record of known signatures.
+   * @returns {boolean} Returns true if the action function is valid, false otherwise.
+   * @throws {ValidationAbiMissingError} Throws if the ABI for the function signature is not found.
+   * @throws {FunctionDataDecodeError} Throws if there's an error decoding the function data.
+   */
+  public isActionFunctionValid(
+    actionStep: ActionStep,
+    transaction: Transaction,
+    params?: Pick<ValidateActionStepParams, 'abiItem' | 'knownSignatures'>,
+  ) {
+    const criteria = actionStep.actionParameter;
+    let signature = actionStep.signature;
+
+    let func: AbiFunction;
+    if (params?.abiItem) func = params?.abiItem as AbiFunction;
+    else {
+      const sigPool: Record<Hex, AbiFunction> = {
+        ...(functions.abi as Record<Hex, AbiFunction>),
+        ...((params?.knownSignatures as Record<Hex, AbiFunction>) || {}),
+      };
+      func = sigPool[signature] as AbiFunction;
+    }
+    if (!func) {
+      throw new ValidationAbiMissingError(signature);
+    }
+
+    let decodedData;
+    try {
+      decodedData = decodeFunctionData({
+        abi: [func],
+        data: transaction.input,
+      });
+    } catch (e) {
+      throw new FunctionDataDecodeError([func], e as Error);
+    }
+
+    // Validate the criteria against decoded arguments using fieldIndex
+    const decodedArgs = decodedData.args;
+
+    if (!decodedArgs || !decodedData) return false;
+
+    if (
+      !this.validateFunctionAgainstCriteria(
+        criteria,
+        decodedArgs as (string | bigint)[],
+      )
+    ) {
+      return false;
+    }
+
+    return true;
+  }
+  /**
+   * Validates a field against a given criteria.
    *
    * @param {Criteria} criteria - The criteria to validate against.
-   * @param {Log} log - The Viem event log.
-   * @returns {boolean} - Returns true if the log passes the criteria, false otherwise.
+   * @param {string | bigint | Hex} fieldValue - The field value to validate.
+   * @param {Object} input - Additional context for validation.
+   * @param {EventLogs[0]} [input.log] - The event log, if validating an event.
+   * @param {readonly (string | bigint)[]} [input.decodedArgs] - The decoded function arguments, if validating a function call.
+   * @returns {Promise<boolean>} - Returns true if the field passes the criteria, false otherwise.
    */
-  public validateLogAgainstCriteria(criteria: Criteria, log: Log) {
-    const fieldValue = log.topics.at(criteria.fieldIndex);
-    if (fieldValue === undefined) {
-      throw new FieldValueUndefinedError({ log, criteria, fieldValue });
+  public validateFieldAgainstCriteria(
+    criteria: Criteria,
+    fieldValue: string | bigint | Hex,
+    input:
+      | { log: EventLogs[0] }
+      | { decodedArgs: readonly (string | bigint)[] },
+  ): boolean {
+    if (
+      criteria.filterType === FilterType.EQUAL &&
+      criteria.fieldType === PrimitiveType.BYTES &&
+      criteria.fieldIndex === 255
+    ) {
+      return true;
     }
+
     // Type narrow based on criteria.filterType
     switch (criteria.filterType) {
       case FilterType.EQUAL:
-        if (criteria.fieldType === PrimitiveType.ADDRESS) {
-          return isAddressEqual(
-            criteria.filterData,
-            `0x${fieldValue.slice(-40)}`,
-          );
-        }
-        return fieldValue === criteria.filterData;
+        return match(criteria.fieldType)
+          .with(PrimitiveType.ADDRESS, () =>
+            isAddressEqual(criteria.filterData, fieldValue as Address),
+          )
+          .with(
+            PrimitiveType.UINT,
+            () => BigInt(fieldValue) === BigInt(criteria.filterData),
+          )
+          .with(
+            PrimitiveType.STRING,
+            () => fieldValue === fromHex(criteria.filterData, 'string'),
+          )
+          .otherwise(() => fieldValue === criteria.filterData);
 
       case FilterType.NOT_EQUAL:
-        return fieldValue !== criteria.filterData;
+        return match(criteria.fieldType)
+          .with(
+            PrimitiveType.ADDRESS,
+            () => !isAddressEqual(criteria.filterData, fieldValue as Address),
+          )
+          .with(
+            PrimitiveType.UINT,
+            () => BigInt(fieldValue) !== BigInt(criteria.filterData),
+          )
+          .with(
+            PrimitiveType.STRING,
+            () => fieldValue !== fromHex(criteria.filterData, 'string'),
+          )
+          .otherwise(() => fieldValue !== criteria.filterData);
 
       case FilterType.GREATER_THAN:
         if (criteria.fieldType === PrimitiveType.UINT) {
           return BigInt(fieldValue) > BigInt(criteria.filterData);
         }
-        throw new InvalidNumericalCriteriaError({ log, criteria, fieldValue });
+        throw new InvalidNumericalCriteriaError({
+          ...input,
+          criteria,
+          fieldValue,
+        });
 
       case FilterType.LESS_THAN:
         if (criteria.fieldType === PrimitiveType.UINT) {
           return BigInt(fieldValue) < BigInt(criteria.filterData);
         }
-        throw new InvalidNumericalCriteriaError({ log, criteria, fieldValue });
+        throw new InvalidNumericalCriteriaError({
+          ...input,
+          criteria,
+          fieldValue,
+        });
 
       case FilterType.CONTAINS:
         if (
           criteria.fieldType === PrimitiveType.BYTES ||
           criteria.fieldType === PrimitiveType.STRING
         ) {
-          return fieldValue.includes(criteria.filterData);
+          let substring;
+          if (criteria.fieldType === PrimitiveType.STRING) {
+            substring = fromHex(criteria.filterData, 'string');
+          } else {
+            // truncate the `0x` prefix
+            substring = criteria.filterData.slice(2);
+          }
+          return (fieldValue as string).includes(substring);
+        }
+        throw new FieldValueNotComparableError({
+          ...input,
+          criteria,
+          fieldValue,
+        });
+
+      case FilterType.REGEX:
+        if (typeof fieldValue !== 'string') {
+          throw new FieldValueNotComparableError({
+            ...input,
+            criteria,
+            fieldValue,
+          });
+        }
+
+        if (criteria.fieldType === PrimitiveType.STRING) {
+          // fieldValue is decoded by the ABI
+          const regexString = fromHex(criteria.filterData, 'string');
+          return new RegExp(regexString).test(fieldValue);
         }
-        throw new FieldValueNotComparableError({ log, criteria, fieldValue });
 
       default:
-        throw new UnrecognizedFilterTypeError({ log, criteria, fieldValue });
+        throw new UnrecognizedFilterTypeError({
+          ...input,
+          criteria,
+          fieldValue,
+        });
     }
   }
 
+  /**
+   * Validates a {@link Log} against a given criteria.
+   * If the criteria's fieldIndex is 255, it is reserved for anyValidation
+   *
+   * @param {Criteria} criteria - The criteria to validate against.
+   * @param {Log} log - The Viem event log.
+   * @returns {boolean} - Returns true if the log passes the criteria, false otherwise.
+   */
+  public validateLogAgainstCriteria(
+    criteria: Criteria,
+    log: EventLogs[0],
+  ): boolean {
+    if (
+      !Array.isArray(log.args) ||
+      (log.args.length <= criteria.fieldIndex && criteria.fieldIndex !== 255)
+    ) {
+      throw new DecodedArgsMalformedError({
+        log,
+        criteria,
+        fieldValue: undefined,
+      });
+    }
+
+    const fieldValue =
+      criteria.fieldIndex === 255 ? zeroHash : log.args.at(criteria.fieldIndex);
+
+    if (fieldValue === undefined) {
+      throw new FieldValueUndefinedError({ log, criteria, fieldValue });
+    }
+    return this.validateFieldAgainstCriteria(criteria, fieldValue, { log });
+  }
+
+  /**
+   * Validates a function's decoded arguments against a given criteria.
+   * If the criteria's fieldIndex is 255, it is reserved for anyValidation
+   *
+   * @param {Criteria} criteria - The criteria to validate against.
+   * @param {unknown[]} decodedArgs - The decoded arguments of the function call.
+   * @returns {Promise<boolean>} - Returns true if the decoded argument passes the criteria, false otherwise.
+   */
+  public validateFunctionAgainstCriteria(
+    criteria: Criteria,
+    decodedArgs: readonly (string | bigint)[],
+  ): boolean {
+    const fieldValue =
+      criteria.fieldIndex === 255 ? zeroHash : decodedArgs[criteria.fieldIndex];
+    if (fieldValue === undefined) {
+      throw new FieldValueUndefinedError({
+        criteria,
+        fieldValue,
+      });
+    }
+    return this.validateFieldAgainstCriteria(criteria, fieldValue, {
+      decodedArgs,
+    });
+  }
+
   /**
    * @inheritdoc
    *
@@ -609,6 +1028,17 @@ export class EventAction extends DeployableTarget<
       ...this.optionallyAttachAccount(options.account),
     };
   }
+
+  public isArraylikeIndexed(step: ActionStep, event: AbiEvent) {
+    if (
+      (step.actionParameter.fieldType === PrimitiveType.STRING ||
+        step.actionParameter.fieldType === PrimitiveType.BYTES) &&
+      event.inputs[step.actionParameter.fieldIndex]?.indexed
+    ) {
+      return true;
+    }
+    return false;
+  }
 }
 
 function _dedupeActionSteps(_steps: ActionStep[]): ActionStep[] {
@@ -803,3 +1233,31 @@ export function prepareEventActionPayload({
     ],
   );
 }
+
+/**
+ * Creates a default Criteria object that allows validation to pass. This is used if you don't care about targeting specific parameters in the action step.
+ *
+ * This function returns a Criteria object with the following properties:
+ * - filterType: Set to EQUAL for exact matching
+ * - fieldType: Set to BYTES to handle any data type
+ * - fieldIndex: Set to 255, which is typically used to indicate "any" or "all" in this context
+ * - filterData: Set to zeroHash (0x0000...0000)
+ *
+ * @returns {Criteria} A Criteria object that can be used to match any action parameter
+ *
+ * @example
+ * const anyCriteria = anyActionParameter();
+ * // Use this criteria in an ActionStep to match any parameter
+ * const actionStep = {
+ *   // ... other properties ...
+ *   actionParameter: anyCriteria
+ * };
+ */
+export function anyActionParameter(): Criteria {
+  return {
+    filterType: FilterType.EQUAL,
+    fieldType: PrimitiveType.BYTES,
+    fieldIndex: 255,
+    filterData: zeroHash,
+  };
+}