@boostxyz/sdk 0.0.0-alpha.8 → 0.0.0-alpha.9

package/src/Actions/EventAction.ts

@@ -14,6 +14,7 @@ import {
   type ContractEventName,
   type Hex,
   type Log,
+  encodeAbiParameters,
   isAddressEqual,
 } from 'viem';
 import { getLogs } from 'viem/actions';
@@ -31,31 +32,253 @@ import {
   UnrecognizedFilterTypeError,
 } from '../errors';
 import {
-  type ActionClaimant,
-  type ActionStep,
-  type Criteria,
-  type EventActionPayload,
-  type EventActionPayloadRaw,
-  FilterType,
   type GetLogsParams,
-  PrimitiveType,
+  type Overwrite,
   type ReadParams,
   RegistryType,
   type WriteParams,
-  dedupeActionSteps,
-  isEventActionPayloadSimple,
-  prepareEventActionPayload,
 } from '../utils';
-import type { SignatureType } from './../utils';
 
-export type {
-  EventActionPayload,
-  ActionStep,
-  ActionClaimant,
-  SignatureType,
-  FilterType,
-  PrimitiveType,
-};
+/*
+ * 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
@@ -127,8 +350,8 @@ export class EventAction extends DeployableTarget<
       ...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 ActionStep[];
-    return dedupeActionSteps(steps);
+    })) as RawActionStep[];
+    return _dedupeActionSteps(steps.map(_fromRawActionStep));
   }
 
   /**
@@ -157,12 +380,13 @@ export class EventAction extends DeployableTarget<
   public async getActionClaimant(
     params?: ReadParams<typeof eventActionAbi, 'getActionClaimant'>,
   ) {
-    return readEventActionGetActionClaimant(this._config, {
+    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 Promise<ActionClaimant>;
+    })) as RawActionClaimant;
+    return _fromRawActionStep(result);
   }
 
   /**
@@ -178,7 +402,7 @@ export class EventAction extends DeployableTarget<
     data: Hex,
     params?: WriteParams<typeof eventActionAbi, 'execute'>,
   ) {
-    return this.awaitResult(this.executeRaw(data, params));
+    return await this.awaitResult(this.executeRaw(data, params));
   }
 
   /**
@@ -278,7 +502,7 @@ export class EventAction extends DeployableTarget<
       }));
     if (!logs.length) return false;
     for (let log of logs) {
-      if (!(await this.validateLogAgainstCriteria(criteria, log))) {
+      if (!this.validateLogAgainstCriteria(criteria, log)) {
         return false;
       }
     }
@@ -290,9 +514,9 @@ export class EventAction extends DeployableTarget<
    *
    * @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.
+   * @returns {boolean} - Returns true if the log passes the criteria, false otherwise.
    */
-  public async validateLogAgainstCriteria(criteria: Criteria, log: Log) {
+  public validateLogAgainstCriteria(criteria: Criteria, log: Log) {
     const fieldValue = log.topics.at(criteria.fieldIndex);
     if (fieldValue === undefined) {
       throw new FieldValueUndefinedError({ log, criteria, fieldValue });
@@ -356,24 +580,24 @@ export class EventAction extends DeployableTarget<
     let rawPayload: EventActionPayloadRaw;
     if (isEventActionPayloadSimple(payload)) {
       // filter out any falsy potential values
-      let tmpSteps = payload.actionSteps.filter((step) => !!step);
+      let tmpSteps: ActionStep[] = payload.actionSteps.filter((step) => !!step);
       if (tmpSteps.length === 0) {
         throw new NoEventActionStepsProvidedError();
       }
       if (tmpSteps.length > 4) {
         throw new TooManyEventActionStepsProvidedError();
       }
-      let steps: ActionStep[] = Array.from({ length: 4 }, (_, i) => {
+      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.slice(0, i).at(-1)!;
-      });
+        return tmpSteps.at(i) || tmpSteps.at(-1);
+      }) as ActionStepTuple;
       rawPayload = {
         actionClaimant: payload.actionClaimant,
-        actionStepOne: steps.at(0)!,
-        actionStepTwo: steps.at(1)!,
-        actionStepThree: steps.at(2)!,
-        actionStepFour: steps.at(3)!,
+        actionStepOne: steps[0],
+        actionStepTwo: steps[1],
+        actionStepThree: steps[2],
+        actionStepFour: steps[3],
       };
     } else {
       rawPayload = payload;
@@ -386,3 +610,196 @@ export class EventAction extends DeployableTarget<
     };
   }
 }
+
+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,
+        },
+      },
+    ],
+  );
+}

package/src/AllowLists/SimpleAllowList.ts

@@ -12,6 +12,7 @@ import {
   type Address,
   type ContractEventName,
   type Hex,
+  encodeAbiParameters,
   zeroAddress,
   zeroHash,
 } from 'viem';
@@ -25,13 +26,32 @@ import {
   type GenericLog,
   type ReadParams,
   RegistryType,
-  type SimpleAllowListPayload,
   type WriteParams,
-  prepareSimpleAllowListPayload,
 } from '../utils';
 
 export { simpleAllowListAbi };
-export type { SimpleAllowListPayload };
+
+/**
+ * Object representation of a {@link SimpleAllowList} initialization payload.
+ *
+ * @export
+ * @interface SimpleAllowListPayload
+ * @typedef {SimpleAllowListPayload}
+ */
+export interface SimpleAllowListPayload {
+  /**
+   * The allow list's owner, given the {@link LIST_MANAGER_ROLE} role.
+   *
+   * @type {Address}
+   */
+  owner: Address;
+  /**
+   * List of allowed addresses.
+   *
+   * @type {Address[]}
+   */
+  allowed: Address[];
+}
 
 /**
  * A generic `viem.Log` event with support for `SimpleAllowList` event types.
@@ -123,7 +143,9 @@ export class SimpleAllowList extends DeployableTarget<
     allowed: boolean[],
     params?: WriteParams<typeof simpleAllowListAbi, 'setAllowed'>,
   ) {
-    return this.awaitResult(this.setAllowedRaw(addresses, allowed, params));
+    return await this.awaitResult(
+      this.setAllowedRaw(addresses, allowed, params),
+    );
   }
 
   /**
@@ -171,7 +193,7 @@ export class SimpleAllowList extends DeployableTarget<
     role: bigint,
     params?: WriteParams<typeof simpleAllowListAbi, 'grantRoles'>,
   ) {
-    return this.awaitResult(this.grantRolesRaw(address, role, params));
+    return await this.awaitResult(this.grantRolesRaw(address, role, params));
   }
 
   /**
@@ -239,3 +261,24 @@ export class SimpleAllowList extends DeployableTarget<
     };
   }
 }
+
+/**
+ * Given a {@link SimpleAllowListPayload}, properly encode the initialization payload.
+ *
+ * @param {SimpleAllowListPayload} param0
+ * @param {Address} param0.owner - The allow list's owner, given the {@link LIST_MANAGER_ROLE} role.
+ * @param {Address[]} param0.allowed - List of allowed addresses.
+ * @returns {Hex}
+ */
+export function prepareSimpleAllowListPayload({
+  owner,
+  allowed,
+}: SimpleAllowListPayload) {
+  return encodeAbiParameters(
+    [
+      { type: 'address', name: 'owner' },
+      { type: 'address[]', name: 'allowed' },
+    ],
+    [owner, allowed],
+  );
+}