@boostxyz/sdk 0.0.0-alpha.10

package/src/Actions/EventAction.ts

@@ -0,0 +1,811 @@
+import {
+  eventActionAbi,
+  readEventActionGetActionClaimant,
+  readEventActionGetActionSteps,
+  simulateEventActionExecute,
+  writeEventActionExecute,
+} from '@boostxyz/evm';
+import { bytecode } from '@boostxyz/evm/artifacts/contracts/actions/EventAction.sol/EventAction.json';
+import events from '@boostxyz/signatures/events';
+import {
+  type Abi,
+  type AbiEvent,
+  type Address,
+  type ContractEventName,
+  type Hex,
+  type Log,
+  encodeAbiParameters,
+  isAddressEqual,
+} from 'viem';
+import { getLogs } from 'viem/actions';
+import type {
+  DeployableOptions,
+  GenericDeployableParams,
+} from '../Deployable/Deployable';
+import { DeployableTarget } from '../Deployable/DeployableTarget';
+import {
+  FieldValueNotComparableError,
+  FieldValueUndefinedError,
+  InvalidNumericalCriteriaError,
+  NoEventActionStepsProvidedError,
+  TooManyEventActionStepsProvidedError,
+  UnrecognizedFilterTypeError,
+} from '../errors';
+import {
+  type GetLogsParams,
+  type Overwrite,
+  type ReadParams,
+  RegistryType,
+  type WriteParams,
+} from '../utils';
+
+/*
+ * Action Event Payloads
+ */
+
+/**
+ * Filter types used to determine how criteria are evaluated.
+ *
+ * @export
+ * @enum {number}
+ */
+export enum FilterType {
+  EQUAL = 0,
+  NOT_EQUAL = 1,
+  GREATER_THAN = 2,
+  LESS_THAN = 3,
+  CONTAINS = 4,
+}
+
+/**
+ * The primitive types supported for filtering.
+ *
+ * @export
+ * @enum {number}
+ */
+export enum PrimitiveType {
+  UINT = 0,
+  ADDRESS = 1,
+  BYTES = 2,
+  STRING = 3,
+}
+
+/**
+ * Object representation of a `Criteria` struct used in event actions.
+ *
+ * @export
+ * @interface Criteria
+ * @typedef {Criteria}
+ */
+export interface Criteria {
+  /**
+   * The filter type used in this criteria.
+   *
+   * @type {FilterType}
+   */
+  filterType: FilterType;
+  /**
+   * The primitive type of the field being filtered.
+   *
+   * @type {PrimitiveType}
+   */
+  fieldType: PrimitiveType;
+  /**
+   * The index in the logs argument array where the field is located.
+   *
+   * @type {number}
+   */
+  fieldIndex: number;
+  /**
+   * The filter data used for complex filtering.
+   *
+   * @type {Hex}
+   */
+  filterData: Hex;
+}
+
+/**
+ * Whether a given signature is an event or function
+ *
+ * @export
+ * @enum {number}
+ */
+export enum SignatureType {
+  EVENT = 0,
+  FUNC = 1,
+}
+
+/**
+ *  The payload describing how claimants are identified
+ *
+ * @export
+ * @interface ActionClaimant
+ * @typedef {ActionClaimant}
+ */
+export interface ActionClaimant {
+  /**
+   * Whether claimaint is inferred from event or function
+   *
+   * @type {SignatureType}
+   */
+  signatureType: SignatureType;
+  /**
+   * The 4 byte signature of the event or function
+   *
+   * @type {Hex}
+   */
+  signature: Hex;
+  /**
+   * The index corresponding to claimant.
+   *
+   * @type {number}
+   */
+  fieldIndex: number;
+  /**
+   * The address of the target contract
+   *
+   * @type {Address}
+   */
+  targetContract: Address;
+  /**
+   * The chain id of the target contract.
+   * @type {number}
+   */
+  chainid: number;
+}
+
+/**
+ * Object representation of an `ActionStep` struct used in event actions.
+ *
+ * @export
+ * @interface ActionStep
+ * @typedef {ActionStep}
+ */
+export interface ActionStep {
+  /**
+   * The signature of the event.
+   *
+   * @type {Hex}
+   */
+  signature: Hex;
+  /**
+   * Whether claimaint is inferred from event or function
+   *
+   * @type {SignatureType}
+   */
+  signatureType: SignatureType;
+  /**
+   * The type of action being performed.
+   *
+   * @type {number}
+   */
+  actionType?: number;
+  /**
+   * The address of the target contract.
+   *
+   * @type {Address}
+   */
+  targetContract: Address;
+  /**
+   * The chain id of the target contract.
+   * @type {number}
+   */
+  chainid: number;
+  /**
+   * The criteria used for this action step.
+   *
+   * @type {Criteria}
+   */
+  actionParameter: Criteria;
+}
+/**
+ * You can either supply a simplified version of the payload, or one that explicitly declares action steps.
+ *
+ * @export
+ * @typedef {EventActionPayload}
+ */
+export type EventActionPayload =
+  | EventActionPayloadSimple
+  | EventActionPayloadRaw;
+
+export interface EventActionPayloadSimple {
+  /**
+   *  The payload describing how claimants are identified
+   *
+   * @type {ActionClaimant}
+   */
+  actionClaimant: ActionClaimant;
+
+  /**
+   * Up to 4 action steps.
+   * If you supply less than 4, then the last step will be reused to satisfy the EventAction.InitPayload
+   * Any more than 4 will throw an error.
+   *
+   * @type {ActionStep[]}
+   */
+  actionSteps: ActionStep[];
+}
+
+export type ActionStepTuple = [ActionStep, ActionStep, ActionStep, ActionStep];
+
+/**
+ * Typeguard to determine if a user is supplying a simple or raw EventActionPayload
+ *
+ * @param {*} opts
+ * @returns {opts is EventActionPayloadSimple}
+ */
+export function isEventActionPayloadSimple(
+  opts: EventActionPayload,
+): opts is EventActionPayloadSimple {
+  return Array.isArray((opts as EventActionPayloadSimple).actionSteps);
+}
+
+/**
+ * Object representation of an `InitPayload` struct used to initialize event actions.
+ *
+ * @export
+ * @interface EventActionPayloadRaw
+ * @typedef {EventActionPayloadRaw}
+ */
+export interface EventActionPayloadRaw {
+  /**
+   *  The payload describing how claimants are identified
+   *
+   * @type {ActionClaimant}
+   */
+  actionClaimant: ActionClaimant;
+  /**
+   * The first action step.
+   *
+   * @type {ActionStep}
+   */
+  actionStepOne: ActionStep;
+  /**
+   * The second action step.
+   *
+   * @type {ActionStep}
+   */
+  actionStepTwo: ActionStep;
+  /**
+   * The third action step.
+   *
+   * @type {ActionStep}
+   */
+  actionStepThree: ActionStep;
+  /**
+   * The fourth action step.
+   *
+   * @type {ActionStep}
+   */
+  actionStepFour: ActionStep;
+}
+
+/**
+ * A generic event action
+ *
+ * @export
+ * @class EventAction
+ * @typedef {EventAction}
+ * @extends {DeployableTarget<EventActionPayload>}
+ */
+export class EventAction extends DeployableTarget<
+  EventActionPayload,
+  typeof eventActionAbi
+> {
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @readonly
+   * @type {*}
+   */
+  public override readonly abi = eventActionAbi;
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @static
+   * @type {Address}
+   */
+  public static override base: Address = import.meta.env.VITE_EVENT_ACTION_BASE;
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @static
+   * @type {RegistryType}
+   */
+  public static override registryType: RegistryType = RegistryType.ACTION;
+
+  /**
+   * Gets a specific action event by index
+   *
+   * @public
+   * @async
+   * @param {number} index The index of the action event to retrieve
+   * @param {?ReadParams<typeof eventActionAbi, 'getActionStep'>} [params]
+   * @returns {Promise<ActionStep>}
+   */
+  public async getActionStep(
+    index: number,
+    params?: ReadParams<typeof eventActionAbi, 'getActionStep'>,
+  ) {
+    const steps = await this.getActionSteps(params);
+    return steps.at(index);
+  }
+
+  /**
+   * Gets all action events
+   *
+   * @public
+   * @async
+   * @param {?ReadParams<typeof eventActionAbi, 'getActionSteps'>} [params]
+   * @returns {Promise<ActionStep[]>}
+   */
+  public async getActionSteps(
+    params?: ReadParams<typeof eventActionAbi, 'getActionSteps'>,
+  ) {
+    const steps = (await readEventActionGetActionSteps(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),
+    })) as RawActionStep[];
+    return _dedupeActionSteps(steps.map(_fromRawActionStep));
+  }
+
+  /**
+   * Gets the count of action events
+   *
+   * @public
+   * @async
+   * @param {?ReadParams<typeof eventActionAbi, 'getActionStepsCount'>} [params]
+   * @returns {Promise<bigint>}
+   */
+  public async getActionStepsCount(
+    params?: ReadParams<typeof eventActionAbi, 'getActionStepsCount'>,
+  ) {
+    const steps = await this.getActionSteps(params);
+    return steps.length;
+  }
+
+  /**
+   * Retrieves the payload describing how claimants can be identified from logs or function calls.
+   *
+   * @public
+   * @async
+   * @param {?ReadParams<typeof eventActionAbi, 'getActionClaimant'>} [params]
+   * @returns {Promise<ActionClaimant>}
+   */
+  public async getActionClaimant(
+    params?: ReadParams<typeof eventActionAbi, '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),
+    })) as RawActionClaimant;
+    return _fromRawActionStep(result);
+  }
+
+  /**
+   * Executes a prepared event action
+   *
+   * @public
+   * @async
+   * @param {Hex} data
+   * @param {?WriteParams<typeof eventActionAbi, 'execute'>} [params]
+   * @returns {Promise<readonly [boolean, `0x${string}`]>}
+   */
+  public async execute(
+    data: Hex,
+    params?: WriteParams<typeof eventActionAbi, 'execute'>,
+  ) {
+    return await this.awaitResult(this.executeRaw(data, params));
+  }
+
+  /**
+   * Executes a prepared event action
+   *
+   * @public
+   * @async
+   * @param {Hex} data
+   * @param {?WriteParams<typeof eventActionAbi, 'execute'>} [params]
+   * @returns {unknown}
+   */
+  public async executeRaw(
+    data: Hex,
+    params?: WriteParams<typeof eventActionAbi, 'execute'>,
+  ) {
+    const { request, result } = await simulateEventActionExecute(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),
+      args: [data],
+    });
+    const hash = await writeEventActionExecute(this._config, request);
+    return { hash, result };
+  }
+
+  /**
+   * 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]
+   * @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);
+    for (const actionStep of actionSteps) {
+      if (!(await this.isActionStepValid(actionStep, params))) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * 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.
+   *
+   * @public
+   * @async
+   * @param {ActionStep} actionStep
+   * @param {?GetLogsParams<Abi, ContractEventName<Abi>> & {
+   *       knownEvents?: Record<Hex, AbiEvent>;
+   *       logs?: Log[];
+   *     }} [params]
+   * @returns {Promise<boolean>}
+   */
+  public async isActionStepValid(
+    actionStep: ActionStep,
+    params?: GetLogsParams<Abi, ContractEventName<Abi>> & {
+      knownEvents?: Record<Hex, AbiEvent>;
+      logs?: Log[];
+    },
+  ) {
+    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 (!event) {
+      throw new Error(`No known ABI for given event signature: ${signature}`);
+    }
+    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,
+      }));
+    if (!logs.length) return false;
+    for (let log of logs) {
+      if (!this.validateLogAgainstCriteria(criteria, log)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Validates a {@link Log} 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.
+   */
+  public validateLogAgainstCriteria(criteria: Criteria, log: Log) {
+    const fieldValue = log.topics.at(criteria.fieldIndex);
+    if (fieldValue === undefined) {
+      throw new FieldValueUndefinedError({ log, criteria, fieldValue });
+    }
+    // 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;
+
+      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 });
+
+      case FilterType.LESS_THAN:
+        if (criteria.fieldType === PrimitiveType.UINT) {
+          return BigInt(fieldValue) < BigInt(criteria.filterData);
+        }
+        throw new InvalidNumericalCriteriaError({ log, criteria, fieldValue });
+
+      case FilterType.CONTAINS:
+        if (
+          criteria.fieldType === PrimitiveType.BYTES ||
+          criteria.fieldType === PrimitiveType.STRING
+        ) {
+          return fieldValue.includes(criteria.filterData);
+        }
+        throw new FieldValueNotComparableError({ log, criteria, fieldValue });
+
+      default:
+        throw new UnrecognizedFilterTypeError({ log, criteria, fieldValue });
+    }
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @param {?EventActionPayload} [_payload]
+   * @param {?DeployableOptions} [_options]
+   * @returns {GenericDeployableParams}
+   */
+  public override buildParameters(
+    _payload?: EventActionPayload,
+    _options?: DeployableOptions,
+  ): GenericDeployableParams {
+    const [payload, options] = this.validateDeploymentConfig(
+      _payload,
+      _options,
+    );
+    let rawPayload: EventActionPayloadRaw;
+    if (isEventActionPayloadSimple(payload)) {
+      // filter out any falsy potential values
+      let tmpSteps: ActionStep[] = payload.actionSteps.filter((step) => !!step);
+      if (tmpSteps.length === 0) {
+        throw new NoEventActionStepsProvidedError();
+      }
+      if (tmpSteps.length > 4) {
+        throw new TooManyEventActionStepsProvidedError();
+      }
+      let steps: ActionStepTuple = Array.from({ length: 4 }, (_, i) => {
+        // use either the provided step at the given index, or reuse the previous step
+        // should aways exist
+        return tmpSteps.at(i) || tmpSteps.at(-1);
+      }) as ActionStepTuple;
+      rawPayload = {
+        actionClaimant: payload.actionClaimant,
+        actionStepOne: steps[0],
+        actionStepTwo: steps[1],
+        actionStepThree: steps[2],
+        actionStepFour: steps[3],
+      };
+    } else {
+      rawPayload = payload;
+    }
+    return {
+      abi: eventActionAbi,
+      bytecode: bytecode as Hex,
+      args: [prepareEventActionPayload(rawPayload)],
+      ...this.optionallyAttachAccount(options.account),
+    };
+  }
+}
+
+function _dedupeActionSteps(_steps: ActionStep[]): ActionStep[] {
+  const steps: ActionStep[] = [],
+    signatures: Record<string, boolean> = {};
+  for (let step of _steps) {
+    const signature = JSON.stringify(step);
+    if (signatures[signature]) continue;
+    steps.push(step);
+    signatures[signature] = true;
+  }
+  return steps;
+}
+type RawActionStep = Overwrite<ActionStep, { chainid: bigint }>;
+type RawActionClaimant = Overwrite<ActionClaimant, { chainid: bigint }>;
+
+function _toRawActionStep<T extends ActionStep | ActionClaimant>(obj: T) {
+  return {
+    ...obj,
+    chainid: BigInt(obj.chainid),
+  };
+}
+
+function _fromRawActionStep<T extends RawActionStep | RawActionClaimant>(
+  obj: T,
+) {
+  if (obj.chainid > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error('Chain ID exceeds max safe integer');
+  }
+
+  return {
+    ...obj,
+    chainid: Number(obj.chainid),
+  };
+}
+
+/**
+ * Typeguard to determine if a user is supplying a simple or raw EventActionPayload
+ *
+ * @param {*} opts
+ * @returns {opts is EventActionPayloadSimple}
+ */
+function _isEventActionPayloadSimple(
+  opts: EventActionPayload,
+): opts is EventActionPayloadSimple {
+  return Array.isArray((opts as EventActionPayloadSimple).actionSteps);
+}
+
+/**
+ * Function to properly encode an event action payload.
+ *
+ * @param {InitPayload} param0
+ * @param {ActionStep} param0.actionStepOne - The first action step to initialize.
+ * @param {ActionStep} param0.actionStepTwo - The second action step to initialize.
+ * @param {ActionStep} param0.actionStepThree - The third action step to initialize.
+ * @param {ActionStep} param0.actionStepFour - The fourth action step to initialize.
+ * @returns {Hex}
+ */
+export function prepareEventActionPayload({
+  actionClaimant,
+  actionStepOne,
+  actionStepTwo,
+  actionStepThree,
+  actionStepFour,
+}: EventActionPayloadRaw) {
+  // note chainIds are technically uint256 but viem treats them (safely) as numbers,
+  // so we encode them as uint32 here to avoid downcast issues
+  return encodeAbiParameters(
+    [
+      {
+        type: 'tuple',
+        name: 'initPayload',
+        components: [
+          {
+            type: 'tuple',
+            name: 'actionClaimant',
+            components: [
+              { type: 'uint8', name: 'signatureType' },
+              { type: 'bytes32', name: 'signature' },
+              { type: 'uint8', name: 'fieldIndex' },
+              { type: 'address', name: 'targetContract' },
+              { type: 'uint256', name: 'chainid' },
+            ],
+          },
+          {
+            type: 'tuple',
+            name: 'actionStepOne',
+            components: [
+              { type: 'bytes32', name: 'signature' },
+              { type: 'uint8', name: 'signatureType' },
+              { type: 'uint8', name: 'actionType' },
+              { type: 'address', name: 'targetContract' },
+              { type: 'uint256', name: 'chainid' },
+              {
+                type: 'tuple',
+                name: 'actionParameter',
+                components: [
+                  { type: 'uint8', name: 'filterType' },
+                  { type: 'uint8', name: 'fieldType' },
+                  { type: 'uint8', name: 'fieldIndex' },
+                  { type: 'bytes', name: 'filterData' },
+                ],
+              },
+            ],
+          },
+          {
+            type: 'tuple',
+            name: 'actionStepTwo',
+            components: [
+              { type: 'bytes32', name: 'signature' },
+              { type: 'uint8', name: 'signatureType' },
+              { type: 'uint8', name: 'actionType' },
+              { type: 'address', name: 'targetContract' },
+              { type: 'uint256', name: 'chainid' },
+              {
+                type: 'tuple',
+                name: 'actionParameter',
+                components: [
+                  { type: 'uint8', name: 'filterType' },
+                  { type: 'uint8', name: 'fieldType' },
+                  { type: 'uint8', name: 'fieldIndex' },
+                  { type: 'bytes', name: 'filterData' },
+                ],
+              },
+            ],
+          },
+          {
+            type: 'tuple',
+            name: 'actionStepThree',
+            components: [
+              { type: 'bytes32', name: 'signature' },
+              { type: 'uint8', name: 'signatureType' },
+              { type: 'uint8', name: 'actionType' },
+              { type: 'address', name: 'targetContract' },
+              { type: 'uint256', name: 'chainid' },
+              {
+                type: 'tuple',
+                name: 'actionParameter',
+                components: [
+                  { type: 'uint8', name: 'filterType' },
+                  { type: 'uint8', name: 'fieldType' },
+                  { type: 'uint8', name: 'fieldIndex' },
+                  { type: 'bytes', name: 'filterData' },
+                ],
+              },
+            ],
+          },
+          {
+            type: 'tuple',
+            name: 'actionStepFour',
+            components: [
+              { type: 'bytes32', name: 'signature' },
+              { type: 'uint8', name: 'signatureType' },
+              { type: 'uint8', name: 'actionType' },
+              { type: 'address', name: 'targetContract' },
+              { type: 'uint256', name: 'chainid' },
+              {
+                type: 'tuple',
+                name: 'actionParameter',
+                components: [
+                  { type: 'uint8', name: 'filterType' },
+                  { type: 'uint8', name: 'fieldType' },
+                  { type: 'uint8', name: 'fieldIndex' },
+                  { type: 'bytes', name: 'filterData' },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+    [
+      {
+        actionClaimant: _toRawActionStep(actionClaimant),
+        actionStepOne: {
+          ..._toRawActionStep(actionStepOne),
+          actionType: actionStepOne.actionType || 0,
+        },
+        actionStepTwo: {
+          ..._toRawActionStep(actionStepTwo),
+          actionType: actionStepTwo.actionType || 0,
+        },
+        actionStepThree: {
+          ..._toRawActionStep(actionStepThree),
+          actionType: actionStepThree.actionType || 0,
+        },
+        actionStepFour: {
+          ..._toRawActionStep(actionStepFour),
+          actionType: actionStepFour.actionType || 0,
+        },
+      },
+    ],
+  );
+}