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

package/src/Validators/SignerValidator.ts

@@ -18,6 +18,7 @@ import {
   encodeAbiParameters,
 } from 'viem';
 import { signTypedData } from 'viem/accounts';
+import { SignerValidator as SignerValidatorBases } from '../../dist/deployments.json';
 import type {
   DeployableOptions,
   GenericDeployableParams,
@@ -306,10 +307,11 @@ export class SignerValidator extends DeployableTarget<
    *
    * @public
    * @static
-   * @type {Address}
+   * @type {Record<number, Address>}
    */
-  public static override base: Address = import.meta.env
-    .VITE_SIGNER_VALIDATOR_BASE;
+  public static override bases: Record<number, Address> = {
+    ...(SignerValidatorBases as Record<number, Address>),
+  };
   /**
    * @inheritdoc
    *
@@ -325,8 +327,8 @@ export class SignerValidator extends DeployableTarget<
    * @public
    * @async
    * @param {Address} address
-   * @param {?ReadParams<typeof signerValidatorAbi, 'signers'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<boolean>}
    */
   public async signers(
     address: Address,
@@ -346,8 +348,8 @@ export class SignerValidator extends DeployableTarget<
    * @public
    * @async
    * @param {SignerValidatorSignaturePayload} payload
-   * @param {?ReadParams<typeof signerValidatorAbi, 'hashSignerData'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<Hex>}
    */
   public async hashSignerData(
     payload: SignerValidatorSignaturePayload,
@@ -372,7 +374,7 @@ export class SignerValidator extends DeployableTarget<
    * @public
    * @async
    * @param {SignerValidatorValidatePayload} payload
-   * @param {?WriteParams<typeof signerValidatorAbi, 'validate'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} - True if the action has been validated based on the data payload
    */
   protected async validate(
@@ -388,7 +390,7 @@ export class SignerValidator extends DeployableTarget<
    * @public
    * @async
    * @param {SignerValidatorValidatePayload} payload
-   * @param {?WriteParams<typeof signerValidatorAbi, 'validate'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} - True if the action has been validated based on the data payload
    */
   protected async validateRaw(
@@ -421,8 +423,8 @@ export class SignerValidator extends DeployableTarget<
    * @async
    * @param {Address[]} addresses - The list of signers to update
    * @param {boolean[]} allowed - The authorized status of each signer
-   * @param {?WriteParams<typeof signerValidatorAbi, 'setAuthorized'>} [params]
-   * @returns {unknown}
+   * @param {?WriteParams} [params]
+   * @returns {Promise<void>}
    */
   public async setAuthorized(
     addresses: Address[],
@@ -441,8 +443,8 @@ export class SignerValidator extends DeployableTarget<
    * @async
    * @param {Address[]} addresses - The list of signers to update
    * @param {boolean[]} allowed - The authorized status of each signer
-   * @param {?WriteParams<typeof signerValidatorAbi, 'setAuthorized'>} [params]
-   * @returns {unknown}
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: void; }>}
    */
   public async setAuthorizedRaw(
     addresses: Address[],
@@ -469,8 +471,8 @@ export class SignerValidator extends DeployableTarget<
    * @public
    * @async
    * @param {Address} address
-   * @param {?WriteParams<typeof signerValidatorAbi, 'setValidatorCaller'>} [params]
-   * @returns {unknown}
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: void; }>}
    */
   public async setValidatorCallerRaw(
     address: Address,
@@ -499,8 +501,8 @@ export class SignerValidator extends DeployableTarget<
    * @public
    * @async
    * @param {Address} address
-   * @param {?WriteParams<typeof signerValidatorAbi, 'setValidatorCaller'>} [params]
-   * @returns {unknown}
+   * @param {?WriteParams} [params]
+   * @returns {Promise<void>}
    */
   public async setValidatorCaller(
     address: Address,

package/src/Validators/Validator.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'vitest';
-import { defaultOptions } from '../../test/helpers';
-import { testAccount } from '../../test/viem';
+import { defaultOptions } from '@boostxyz/test/helpers';
+import { testAccount } from '@boostxyz/test/viem';
 import { SignerValidator } from './SignerValidator';
 import { validatorFromAddress } from './Validator';
 

package/src/Validators/Validator.ts

@@ -32,7 +32,7 @@ export const ValidatorByComponentInterface = {
  * @async
  * @param {DeployableOptions} options
  * @param {Address} address
- * @returns {unknown}
+ * @returns {Promise<Validator>}
  * @throws {@link InvalidComponentInterfaceError}
  */
 export async function validatorFromAddress(

package/src/claiming.ts

@@ -40,7 +40,7 @@ export interface ClaimPayload {
  * @param {ClaimPayload} param0
  * @param {Address} param0.target - The address of the recipient
  * @param {Hex} [param0.data=zeroHash] - The implementation-specific data for the claim, if needed
- * @returns {*}
+ * @returns {Hex}
  */
 export const prepareClaimPayload = ({
   target,

package/src/errors.ts

@@ -1,10 +1,13 @@
 import {
+  type AbiEvent,
+  type AbiFunction,
   type Hex,
   type Log,
   type WaitForTransactionReceiptReturnType,
   zeroHash,
 } from 'viem';
 import type { Criteria } from './Actions/EventAction';
+import type { EventLogs } from './Actions/EventAction';
 import type { BoostRegistry } from './BoostRegistry';
 import type { Incentive } from './Incentives/Incentive';
 
@@ -84,7 +87,7 @@ export class DeployableAlreadyDeployedError extends Error {
    */
   constructor(address: string) {
     super(
-      `Attempted to deploy a contract that already has an address configured`,
+      'Attempted to deploy a contract that already has an address configured',
     );
     this.address = address;
   }
@@ -248,6 +251,44 @@ export class InvalidComponentInterfaceError extends Error {
   }
 }
 
+/**
+ * This error is thrown when a param is not transparently stored onchain
+ *
+ * @export
+ * @class UnparseableAbiParamError
+ * @typedef {UnparseableAbiParamError}
+ * @extends {Error}
+ */
+export class UnparseableAbiParamError extends Error {
+  /**
+   * the param index that is unparseable
+   *
+   * @type {number}
+   */
+  input_param_idx: number;
+  /**
+   * The given event that contains the unparseable param
+   *
+   * @type {AbiEvent}
+   */
+  event: AbiEvent;
+  /**
+   * Creates an instance of UnknownTransferPayloadSupplied.
+   *
+   * @constructor
+   * @param {number} input_param_idx
+   * @param {AbiEvent} event
+   */
+  constructor(input_param_idx: number, event: AbiEvent) {
+    super(
+      `Parameter is not transparently stored onchain. Parameter ${input_param_idx} in event ${event.name} cannot be used in an action`,
+      { cause: event },
+    );
+    this.event = event;
+    this.input_param_idx = input_param_idx;
+  }
+}
+
 /**
  * This error is thrown when attempting a Budget transfer and arguments aren't of the type `FungibleTransferPayload` or `ERC1155TransferPayload`
  *
@@ -380,6 +421,48 @@ export class TooManyEventActionStepsProvidedError extends Error {
   }
 }
 
+/**
+ * The error is thrown when trying to reuse an existing deployed Incentive that isn't a base implementation.
+ *
+ * @export
+ * @class ValidationAbiMissingError
+ * @typedef {ValidationAbiMissingError}
+ * @extends {Error}
+ */
+export class ValidationAbiMissingError extends Error {
+  /**
+   * Creates an instance of ValidationAbiMissingError.
+   *
+   * @constructor
+   * @param {Hex} signature
+   */
+  constructor(signature: Hex) {
+    super(`No known ABI for given signature: ${signature}`);
+  }
+}
+
+/**
+ * Function action validation context to help debug other validation errors
+ *
+ * @interface FunctionActionValidationMeta
+ * @typedef {FunctionActionValidationMeta}
+ */
+interface FunctionActionValidationMeta {
+  decodedArgs: readonly (string | bigint)[];
+  /**
+   * The value pulled off the log being validated against
+   *
+   * @type {*}
+   * biome-ignore lint/suspicious/noExplicitAny: this can be a few different types based on what the log emits
+   */
+  fieldValue: any;
+  /**
+   * The criteria being used to compare during validation
+   *
+   * @type {Criteria}
+   */
+  criteria: Criteria;
+}
 /**
  * Event action validation context to help debug other validation errors
  *
@@ -392,7 +475,7 @@ interface EventActionValidationMeta {
    *
    * @type {Log}
    */
-  log: Log;
+  log?: EventLogs[0];
   /**
    * The value pulled off the log being validated against
    *
@@ -413,17 +496,23 @@ interface EventActionValidationMeta {
  * Instantiated with relevent context data for more in depth debugging.
  *
  * @export
- * @class EventActionValidationError
- * @typedef {EventActionValidationError}
+ * @class FieldActionValidationError
+ * @typedef {FieldActionValidationError}
  * @extends {Error}
  */
-export class EventActionValidationError extends Error {
+export class FieldActionValidationError extends Error {
+  /**
+   * The function input arguments being validated against
+   *
+   * @type {decodedArgs}
+   */
+  decodedArgs?: readonly (string | bigint)[];
   /**
    * The viem log being validated against
    *
    * @type {Log}
    */
-  log: Log;
+  log?: EventLogs[0];
   /**
    * The value pulled off the log being validated against
    *
@@ -438,7 +527,7 @@ export class EventActionValidationError extends Error {
    */
   criteria: Criteria;
   /**
-   * Creates an instance of EventActionValidationError.
+   * Creates an instance of FieldActionValidationError.
    *
    * @constructor
    * @param {string} message
@@ -449,12 +538,48 @@ export class EventActionValidationError extends Error {
    */
   constructor(
     message: string,
-    { fieldValue, criteria, log }: EventActionValidationMeta,
+    {
+      fieldValue,
+      criteria,
+      ...args
+    }: EventActionValidationMeta | FunctionActionValidationMeta,
   ) {
     super(message);
     this.fieldValue = fieldValue;
     this.criteria = criteria;
-    this.log = log;
+
+    switch (true) {
+      case 'log' in args:
+        this.log = args.log;
+        break;
+      case 'decodedArgs' in args:
+        this.decodedArgs = args.decodedArgs;
+    }
+  }
+}
+
+/**
+ * Thrown when abi-decoded args on log is undefined
+ *
+ * @export
+ * @class FieldValueUndefinedError
+ * @typedef {FieldValueUndefinedError}
+ * @extends {FieldActionValidationError}
+ */
+export class DecodedArgsMalformedError extends FieldActionValidationError {
+  /**
+   * Creates an instance of DecodedArgsUndefinedError.
+   *
+   * @constructor
+   * @param {DecodedArgsMalformedError} metadata
+   */
+  constructor(
+    metadata: EventActionValidationMeta | FunctionActionValidationMeta,
+  ) {
+    super(
+      'Decoded Args are malformed; Check which params are indexed',
+      metadata,
+    );
   }
 }
 
@@ -464,16 +589,18 @@ export class EventActionValidationError extends Error {
  * @export
  * @class FieldValueUndefinedError
  * @typedef {FieldValueUndefinedError}
- * @extends {EventActionValidationError}
+ * @extends {FieldActionValidationError}
  */
-export class FieldValueUndefinedError extends EventActionValidationError {
+export class FieldValueUndefinedError extends FieldActionValidationError {
   /**
    * Creates an instance of FieldValueUndefinedError.
    *
    * @constructor
    * @param {EventActionValidationMeta} metadata
    */
-  constructor(metadata: EventActionValidationMeta) {
+  constructor(
+    metadata: EventActionValidationMeta | FunctionActionValidationMeta,
+  ) {
     super('Field value is undefined', metadata);
   }
 }
@@ -484,16 +611,18 @@ export class FieldValueUndefinedError extends EventActionValidationError {
  * @export
  * @class InvalidNumericalCriteriaError
  * @typedef {InvalidNumericalCriteriaError}
- * @extends {EventActionValidationError}
+ * @extends {FieldActionValidationError}
  */
-export class InvalidNumericalCriteriaError extends EventActionValidationError {
+export class InvalidNumericalCriteriaError extends FieldActionValidationError {
   /**
    * Creates an instance of InvalidNumericalCriteria.
    *
    * @constructor
    * @param {EventActionValidationMeta} metadata
    */
-  constructor(metadata: EventActionValidationMeta) {
+  constructor(
+    metadata: EventActionValidationMeta | FunctionActionValidationMeta,
+  ) {
     super(
       'Numerical comparisons cannot be used with non-numerical criteria',
       metadata,
@@ -501,22 +630,51 @@ export class InvalidNumericalCriteriaError extends EventActionValidationError {
   }
 }
 
+/**
+ * Thrown when decoding function data fails.
+ *
+ * @export
+ * @class FunctionDataDecodeError
+ * @typedef {FunctionDataDecodeError}
+ * @extends {Error}
+ */
+export class FunctionDataDecodeError extends Error {
+  public abi: AbiFunction[];
+  public originalError: Error;
+
+  /**
+   * Creates an instance of FunctionDataDecodeError.
+   *
+   * @constructor
+   * @param {AbiFunction[]} abi - The ABI of the function.
+   * @param {Error} originalError - The original error that was thrown.
+   */
+  constructor(abi: AbiFunction[], originalError: Error) {
+    super(`Failed to decode function data: ${originalError.message}`);
+    this.name = 'FunctionDataDecodeError';
+    this.abi = abi;
+    this.originalError = originalError;
+  }
+}
+
 /**
  * Thrown when an the log's field value is being compared a field type that isn't bytes or string during event action validation
  *
  * @export
  * @class FieldValueNotComparableError
  * @typedef {FieldValueNotComparableError}
- * @extends {EventActionValidationError}
+ * @extends {FieldActionValidationError}
  */
-export class FieldValueNotComparableError extends EventActionValidationError {
+export class FieldValueNotComparableError extends FieldActionValidationError {
   /**
    * Creates an instance of FieldValueNotComparableError.
    *
    * @constructor
    * @param {EventActionValidationMeta} metadata
    */
-  constructor(metadata: EventActionValidationMeta) {
+  constructor(
+    metadata: EventActionValidationMeta | FunctionActionValidationMeta,
+  ) {
     super('Filter can only be used with bytes or string field type', metadata);
   }
 }
@@ -527,16 +685,182 @@ export class FieldValueNotComparableError extends EventActionValidationError {
  * @export
  * @class UnrecognizedFilterTypeError
  * @typedef {UnrecognizedFilterTypeError}
- * @extends {EventActionValidationError}
+ * @extends {FieldActionValidationError}
  */
-export class UnrecognizedFilterTypeError extends EventActionValidationError {
+export class UnrecognizedFilterTypeError extends FieldActionValidationError {
   /**
    * Creates an instance of UnrecognizedFilterTypeError.
    *
    * @constructor
    * @param {EventActionValidationMeta} metadata
    */
-  constructor(metadata: EventActionValidationMeta) {
+  constructor(
+    metadata: EventActionValidationMeta | FunctionActionValidationMeta,
+  ) {
     super('Invalid FilterType provided', metadata);
   }
 }
+
+/**
+ * Thrown when no chain ID is provided in the Wagmi configuration.
+ *
+ * @export
+ * @class NoConnectedChainIdError
+ * @typedef {NoConnectedChainIdError}
+ * @extends {Error}
+ */
+export class NoConnectedChainIdError extends Error {
+  /**
+   * Creates an instance of NoConnectedChainIdError.
+   *
+   * @constructor
+   */
+  constructor() {
+    super(
+      'Provided Wagmi configuration does not define `chainId` property with which to target protocol contracts',
+    );
+    this.name = 'NoConnectedChainIdError';
+  }
+}
+
+/**
+ * Thrown when an invalid chain ID is provided that doesn't match any deployed protocol.
+ *
+ * @export
+ * @class InvalidProtocolChainIdError
+ * @typedef {InvalidProtocolChainIdError}
+ * @extends {Error}
+ */
+export class InvalidProtocolChainIdError extends Error {
+  /**
+   * Creates an instance of InvalidProtocolChainIdError.
+   *
+   * @constructor
+   * @param {number} chainId - The chain ID provided in the configuration.
+   * @param {number[]} validChainIds - A list of valid chain IDs where the protocol is deployed.
+   */
+  constructor(chainId: number, validChainIds: number[]) {
+    super(
+      `Provided Wagmi configuration supplied a "chainId" where protocol is not deployed, provided: ${chainId}, but valid chains are: ${validChainIds}`,
+    );
+    this.name = 'InvalidProtocolChainIdError';
+  }
+}
+
+/**
+ * Thrown when the incentive criteria cannot be fetched from the contract.
+ *
+ * @export
+ * @class IncentiveCriteriaNotFoundError
+ * @typedef {IncentiveCriteriaNotFoundError}
+ * @extends {Error}
+ */
+export class IncentiveCriteriaNotFoundError extends Error {
+  /**
+   * Creates an instance of IncentiveCriteriaNotFoundError.
+   *
+   * @constructor
+   * @param {Error} [e] - Optional error object for further context.
+   * @param {string} [message='Unable to fetch Incentive Criteria from contract'] - Custom error message.
+   */
+  constructor(
+    e?: Error,
+    message = 'Unable to fetch Incentive Criteria from contract',
+  ) {
+    super(message + (e ? `: ${e.message}` : ''));
+    this.name = 'IncentiveCriteriaNotFoundError';
+  }
+}
+
+/**
+ * Thrown when no matching logs are found for a given event signature.
+ *
+ * @export
+ * @class NoMatchingLogsError
+ * @typedef {NoMatchingLogsError}
+ * @extends {Error}
+ */
+export class NoMatchingLogsError extends Error {
+  /**
+   * Creates an instance of NoMatchingLogsError.
+   *
+   * @constructor
+   * @param {string} signature - The event signature for which logs are being searched.
+   * @param {string} [message] - Optional custom error message.
+   */
+  constructor(
+    signature: string,
+    message = `No logs found for event signature ${signature}`,
+  ) {
+    super(message);
+    this.name = 'NoMatchingLogsError';
+  }
+}
+
+/**
+ * Thrown when an invalid criteria type is provided.
+ *
+ * @export
+ * @class InvalidCriteriaTypeError
+ * @typedef {InvalidCriteriaTypeError}
+ * @extends {Error}
+ */
+export class InvalidCriteriaTypeError extends Error {
+  /**
+   * Creates an instance of InvalidCriteriaTypeError.
+   *
+   * @constructor
+   * @param {string} [criteriaType='unknown'] - The invalid criteria type that was provided.
+   * @param {string} [message] - Optional custom error message.
+   */
+  constructor(
+    criteriaType = 'unknown',
+    message = `Invalid criteria type ${criteriaType}`,
+  ) {
+    super(message);
+    this.name = 'InvalidCriteriaTypeError';
+  }
+}
+
+/**
+ * Thrown when decoding function arguments fails.
+ *
+ * @export
+ * @class DecodedArgsError
+ * @typedef {DecodedArgsError}
+ * @extends {Error}
+ */
+export class DecodedArgsError extends Error {
+  /**
+   * Creates an instance of DecodedArgsError.
+   *
+   * @constructor
+   * @param {string} [message='Issue decoding args'] - Custom error message.
+   */
+  constructor(message = 'Issue decoding args') {
+    super(message);
+    this.name = 'DecodedArgsError';
+  }
+}
+
+/**
+ * Thrown when reading a Boost that does not exist
+ *
+ * @export
+ * @class BoostNotFoundError
+ * @typedef {BoostNotFoundError}
+ * @extends {Error}
+ */
+export class BoostNotFoundError extends Error {
+  public readonly id: string;
+  /**
+   * Creates an instance of BoostNotFoundError.
+   *
+   * @constructor
+   * @param {string} [id] - stringified boost id that does not exist
+   */
+  constructor(id: string) {
+    super(`Boost with not found with id: ${id}`);
+    this.id = id;
+  }
+}