@boostxyz/sdk 0.0.0-alpha.11 → 0.0.0-alpha.12

package/src/Actions/EventAction.ts

@@ -7,15 +7,24 @@ 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 {
   type Abi,
   type AbiEvent,
+  type AbiFunction,
   type Address,
   type ContractEventName,
+  type ContractFunctionName,
+  type GetLogsReturnType,
+  type GetTransactionParameters,
   type Hex,
   type Log,
+  type PublicClient,
+  decodeFunctionData,
   encodeAbiParameters,
+  fromHex,
   isAddressEqual,
+  trim,
 } from 'viem';
 import { getLogs } from 'viem/actions';
 import type {
@@ -24,11 +33,14 @@ import type {
 } from '../Deployable/Deployable';
 import { DeployableTarget } from '../Deployable/DeployableTarget';
 import {
+  DecodedArgsMalformedError,
   FieldValueNotComparableError,
   FieldValueUndefinedError,
+  FunctionDataDecodeError,
   InvalidNumericalCriteriaError,
   NoEventActionStepsProvidedError,
   TooManyEventActionStepsProvidedError,
+  UnparseableAbiParamError,
   UnrecognizedFilterTypeError,
 } from '../errors';
 import {
@@ -55,6 +67,7 @@ export enum FilterType {
   GREATER_THAN = 2,
   LESS_THAN = 3,
   CONTAINS = 4,
+  REGEX = 5,
 }
 
 /**
@@ -198,6 +211,41 @@ export interface ActionStep {
    */
   actionParameter: Criteria;
 }
+
+/**
+ * Parameters for validating an event step.
+ *
+ * This type omits the 'address' field from GetLogsParams and adds optional fields
+ * for logs and known events.
+ *
+ * @typedef {Object} ValidateEventStepParams
+ * @property {Log[]} [logs]
+ * @property {Record<Hex, AbiEvent>} [knownEvents]
+ * @property {number} [fromBlock]
+ * @property {number} [toBlock]
+ * @property {Hex} [blockHash]
+ * @property {Abi} abi
+ * @property {ContractEventName<Abi>} eventName
+ */
+export type ValidateEventStepParams = Omit<
+  GetLogsParams<Abi, ContractEventName<Abi>> & {
+    logs?: Log[];
+    knownEvents?: Record<Hex, AbiEvent>;
+  },
+  'address'
+>;
+
+/**
+ * Parameters for validating a function step.
+ *
+ * This type includes all parameters required to get a transaction.
+ *
+ * @typedef {Object} ValidateFunctionStepParams
+ * @property {Hex} hash
+ * @property {number} [chainId]
+ */
+export type ValidateFunctionStepParams = GetTransactionParameters;
+
 /**
  * You can either supply a simplified version of the payload, or one that explicitly declares action steps.
  *
@@ -280,6 +328,26 @@ 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>;
+
+type TxParams = ValidateEventStepParams | ValidateFunctionStepParams;
+
 /**
  * A generic event action
  *
@@ -323,12 +391,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 +407,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 +427,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 +442,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'>,
   ) {
     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);
   }
@@ -435,21 +502,11 @@ export class EventAction extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof eventActionAbi, 'getActionSteps'> &
-   *       GetLogsParams<Abi, ContractEventName<Abi>> & {
-   *         knownEvents?: Record<Hex, AbiEvent>;
-   *         logs?: Log[];
-   *       }} [params]
+   * @param {?TxParams} [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?: TxParams) {
+    const actionSteps = await this.getActionSteps();
     for (const actionStep of actionSteps) {
       if (!(await this.isActionStepValid(actionStep, params))) {
         return false;
@@ -459,24 +516,45 @@ 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 {?TxParams & { chainId?: number }} [params] - Additional parameters for validation, including 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?: TxParams & { chainId?: number },
+  ) {
+    if (actionStep.signatureType === SignatureType.EVENT) {
+      return await this.isActionEventValid(actionStep, params);
+    }
+    if (actionStep.signatureType === SignatureType.FUNC) {
+      return await this.isActionFunctionValid(
+        actionStep,
+        params as ValidateFunctionStepParams,
+      );
+    }
+    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 {?ValidateEventStepParams & { chainId?: number }} [params] - Additional parameters for validation, including known events, logs, and chain ID.
+   * @returns {Promise<boolean>} Resolves to true if the action event is valid, throws if input is invalid, otherwise false.
+   */
+  public async isActionEventValid(
+    actionStep: ActionStep,
+    params?: ValidateEventStepParams & { chainId?: number },
   ) {
     const criteria = actionStep.actionParameter;
     const signature = actionStep.signature;
@@ -487,9 +565,18 @@ export class EventAction extends DeployableTarget<
     } else {
       event = (events.abi as Record<Hex, AbiEvent>)[signature] as AbiEvent;
     }
+
     if (!event) {
       throw new Error(`No known ABI for given event signature: ${signature}`);
     }
+
+    if (this.isArraylikeIndexed(actionStep, event)) {
+      // If the field is indexed, we can't filter on it
+      throw new UnparseableAbiParamError(
+        actionStep.actionParameter.fieldIndex,
+        event,
+      );
+    }
     const targetContract = actionStep.targetContract;
     // Get all logs matching the event signature from the target contract
     const logs =
@@ -502,71 +589,211 @@ export class EventAction extends DeployableTarget<
       }));
     if (!logs.length) return false;
     for (let log of logs) {
-      if (!this.validateLogAgainstCriteria(criteria, log)) {
+      if (!this.validateLogAgainstCriteria(criteria, log as EventLogs[0])) {
         return false;
       }
     }
     return true;
   }
+  /**
+   * Validates a single action function with a given criteria against the transaction input.
+   * If a transaction hash is provided in the optional `params` argument, then the transaction
+   * will be fetched and decoded using the configured client.
+   *
+   * @public
+   * @async
+   * @param {ActionStep} actionStep - The action step containing the function to validate.
+   * @param {?ValidateFunctionStepParams & { chainId?: number }} [params] - Additional parameters for validation, including known events, transaction hash, and chain ID.
+   * @returns {Promise<boolean>} Resolves to true if the action function is valid, throws if the inputs are invalid, otherwise false.
+   */
+  public async isActionFunctionValid(
+    actionStep: ActionStep,
+    params?: ValidateFunctionStepParams & { chainId?: number },
+  ) {
+    const criteria = actionStep.actionParameter;
+    const signature = trim(actionStep.signature);
+    if (!params || !params?.hash) {
+      // Should we return false in this case?
+      throw new Error('Hash is required for function validation');
+    }
+    const client = this._config.getClient({
+      chainId: params?.chainId,
+    }) as PublicClient;
+    // Fetch the transaction receipt and decode the function input using `viem` utilities
+    const transaction = await client.getTransaction({ hash: params.hash });
+    const func = (functions.abi as Record<Hex, AbiFunction>)[
+      signature
+    ] as AbiFunction;
+
+    if (!func) {
+      throw new Error(
+        `No known ABI for given function signature: ${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 {@link Log} against a given criteria.
+   * 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} fieldValue - The field value to validate.
+   * @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 {
     // 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 isAddressEqual(criteria.filterData, fieldValue as Address);
         }
         return fieldValue === criteria.filterData;
 
       case FilterType.NOT_EQUAL:
-        if (criteria.fieldType === PrimitiveType.ADDRESS) {
-          return !isAddressEqual(
-            criteria.filterData,
-            `0x${fieldValue.slice(-40)}`,
-          );
-        }
         return 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.
+   *
+   * @param {Criteria} criteria - The criteria to validate against.
+   * @param {Log} log - The Viem event log.
+   * @returns {Promise<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) {
+      throw new DecodedArgsMalformedError({
+        log,
+        criteria,
+        fieldValue: undefined,
+      });
+    }
+
+    const fieldValue = 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.
+   *
+   * @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 = decodedArgs[criteria.fieldIndex];
+    if (fieldValue === undefined) {
+      throw new FieldValueUndefinedError({
+        criteria,
+        fieldValue,
+      });
+    }
+    return this.validateFieldAgainstCriteria(criteria, fieldValue, {
+      decodedArgs,
+    });
+  }
+
   /**
    * @inheritdoc
    *
@@ -615,6 +842,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[] {