@boostxyz/sdk 0.0.0-alpha.17 → 0.0.0-alpha.18

package/src/Incentives/ERC20VariableIncentive.ts

@@ -116,8 +116,8 @@ export class ERC20VariableIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof erc20VariableIncentiveAbi, 'owner'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<Address>}
    */
   public async owner(
     params?: ReadParams<typeof erc20VariableIncentiveAbi, 'owner'>,
@@ -135,7 +135,7 @@ export class ERC20VariableIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof erc20VariableIncentiveAbi, 'totalClaimed'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public async totalClaimed(
@@ -154,7 +154,7 @@ export class ERC20VariableIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof erc20VariableIncentiveAbi, 'currentReward'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>} - The current reward
    */
   public async currentReward(
@@ -173,7 +173,7 @@ export class ERC20VariableIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof erc20VariableIncentiveAbi, 'claims'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public async claims(
@@ -193,7 +193,7 @@ export class ERC20VariableIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {Address} address
-   * @param {?ReadParams<typeof erc20VariableIncentiveAbi, 'claimed'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<boolean>}
    */
   public async claimed(
@@ -213,7 +213,7 @@ export class ERC20VariableIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof erc20VariableIncentiveAbi, 'asset'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<Address>}
    */
   public async asset(
@@ -231,7 +231,7 @@ export class ERC20VariableIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof erc20VariableIncentiveAbi, 'reward'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public async reward(
@@ -249,8 +249,8 @@ export class ERC20VariableIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof erc20VariableIncentiveAbi, 'limit'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<bigint>}
    */
   public async limit(
     params?: ReadParams<typeof erc20VariableIncentiveAbi, 'limit'>,
@@ -268,7 +268,7 @@ export class ERC20VariableIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?WriteParams<typeof erc20VariableIncentiveAbi, 'claim'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} - Returns true if successfully claimed
    */
   protected async claim(
@@ -284,8 +284,8 @@ export class ERC20VariableIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?WriteParams<typeof erc20VariableIncentiveAbi, 'claim'>} [params]
-   * @returns {Promise<boolean>} - Returns true if successfully claimed
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: boolean; }>} - Returns true if successfully claimed
    */
   protected async claimRaw(
     payload: ClaimPayload,
@@ -311,7 +311,7 @@ export class ERC20VariableIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?WriteParams<typeof erc20VariableIncentiveAbi, 'clawback'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} -  True if the assets were successfully clawbacked
    */
   public async clawback(
@@ -327,8 +327,8 @@ export class ERC20VariableIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?WriteParams<typeof erc20VariableIncentiveAbi, 'clawback'>} [params]
-   * @returns {Promise<boolean>} -  True if the assets were successfully clawbacked
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: boolean; }>} -  True if the assets were successfully clawbacked
    */
   public async clawbackRaw(
     payload: ClaimPayload,
@@ -357,8 +357,8 @@ export class ERC20VariableIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?ReadParams<typeof erc20VariableIncentiveAbi, 'isClaimable'>} [params]
-   * @returns {unknown} = True if the incentive is claimable based on the data payload
+   * @param {?ReadParams} [params]
+   * @returns {Promise<boolean>} = True if the incentive is claimable based on the data payload
    */
   public async isClaimable(
     payload: ClaimPayload,
@@ -404,7 +404,7 @@ export class ERC20VariableIncentive extends DeployableTarget<
  * @param {Address} param0.asset - The address of the incentivized asset.
  * @param {bigint} param0.reward - The amount of the asset to distribute.
  * @param {bigint} param0.limit - How many times can this incentive be claimed.
- * @returns {*}
+ * @returns {Hex}
  */
 export function prepareERC20VariableIncentivePayload({
   asset,

package/src/Incentives/Incentive.ts

@@ -13,6 +13,7 @@ import { InvalidComponentInterfaceError } from '../errors';
 import { AllowListIncentive } from './AllowListIncentive';
 import { CGDAIncentive } from './CGDAIncentive';
 import { ERC20Incentive } from './ERC20Incentive';
+import type { ERC20VariableCriteriaIncentive } from './ERC20VariableCriteriaIncentive';
 import { ERC20VariableIncentive } from './ERC20VariableIncentive';
 // import { ERC1155Incentive } from './ERC1155Incentive';
 import { PointsIncentive } from './PointsIncentive';
@@ -38,7 +39,8 @@ export type Incentive =
   | ERC20Incentive
   // | ERC1155Incentive
   | PointsIncentive
-  | ERC20VariableIncentive;
+  | ERC20VariableIncentive
+  | ERC20VariableCriteriaIncentive;
 
 /**
  * A map of Incentive component interfaces to their constructors.
@@ -48,9 +50,8 @@ export type Incentive =
 export const IncentiveByComponentInterface = {
   [APointsIncentive as Hex]: PointsIncentive,
   [AERC20Incentive as Hex]: ERC20Incentive,
-  // TODO: figure out why evm generates bad bytes4 here
-  ['0x0a466e6f']: AllowListIncentive,
-  // [APointsIncentive as Hex]: ERC1155Incentive,
+  [AAllowListIncentive]: AllowListIncentive,
+  // [AERC1155Incentive as Hex]: ERC1155Incentive,
   [ACGDAIncentive as Hex]: CGDAIncentive,
   [AERC20VariableIncentive as Hex]: ERC20VariableIncentive,
 };
@@ -62,7 +63,7 @@ export const IncentiveByComponentInterface = {
  * @async
  * @param {DeployableOptions} options
  * @param {Address} address
- * @returns {unknown}
+ * @returns {Incentive}
  * @throws {@link InvalidComponentInterfaceError}
  */
 export async function incentiveFromAddress(

package/src/Incentives/PointsIncentive.test.ts

@@ -1,22 +1,22 @@
-import { readPointsBalanceOf, writePointsGrantRoles } from '@boostxyz/evm';
-import { loadFixture } from '@nomicfoundation/hardhat-network-helpers';
-import { isAddress, pad, parseEther, zeroAddress } from 'viem';
-import { beforeAll, beforeEach, describe, expect, test } from 'vitest';
-import type { MockPoints } from '@boostxyz/test/MockPoints';
-import { accounts } from '@boostxyz/test/accounts';
+import { readPointsBalanceOf, writePointsGrantRoles } from "@boostxyz/evm";
+import { loadFixture } from "@nomicfoundation/hardhat-network-helpers";
+import { isAddress, pad, parseEther, zeroAddress } from "viem";
+import { beforeAll, beforeEach, describe, expect, test } from "vitest";
+import type { MockPoints } from "@boostxyz/test/MockPoints";
+import { accounts } from "@boostxyz/test/accounts";
 import {
   type Fixtures,
   defaultOptions,
   deployFixtures,
   freshBoost,
   freshPoints,
-} from '@boostxyz/test/helpers';
-import { bytes4 } from '../utils';
-import { PointsIncentive } from './PointsIncentive';
+} from "@boostxyz/test/helpers";
+import { bytes4 } from "../utils";
+import { PointsIncentive } from "./PointsIncentive";
 
 let fixtures: Fixtures, points: MockPoints;
 
-describe('PointsIncentive', () => {
+describe("PointsIncentive", () => {
   beforeAll(async () => {
     fixtures = await loadFixture(deployFixtures(defaultOptions));
   });
@@ -25,10 +25,10 @@ describe('PointsIncentive', () => {
     points = await loadFixture(freshPoints);
   });
 
-  test('can successfully be deployed', async () => {
+  test("can successfully be deployed", async () => {
     const action = new PointsIncentive(defaultOptions, {
       venue: zeroAddress,
-      selector: '0xdeadb33f',
+      selector: "0xdeadb33f",
       reward: 1n,
       limit: 1n,
     });
@@ -36,14 +36,14 @@ describe('PointsIncentive', () => {
     expect(isAddress(action.assertValidAddress())).toBe(true);
   });
 
-  test('can claim', async () => {
+  test("can claim", async () => {
     // biome-ignore lint/style/noNonNullAssertion: we know this is defined
     const referrer = accounts.at(1)!.account!;
     // biome-ignore lint/style/noNonNullAssertion: we know this is defined
     const trustedSigner = accounts.at(0)!;
     const pointsIncentive = fixtures.core.PointsIncentive({
       venue: points.assertValidAddress(),
-      selector: bytes4('issue(address,uint256)'),
+      selector: bytes4("issue(address,uint256)"),
       reward: 1n,
       limit: 10n,
     });
@@ -52,7 +52,7 @@ describe('PointsIncentive', () => {
     });
 
     const claimant = trustedSigner.account;
-    const incentiveData = pad('0xdef456232173821931823712381232131391321934');
+    const incentiveData = pad("0xdef456232173821931823712381232131391321934");
     const incentiveQuantity = 1;
     const claimDataPayload = await boost.validator.encodeClaimData({
       signer: trustedSigner,
@@ -73,7 +73,7 @@ describe('PointsIncentive', () => {
       0n,
       referrer,
       claimDataPayload,
-      { value: parseEther('0.000075') },
+      { value: parseEther("0.000075") },
     );
     expect(
       await readPointsBalanceOf(defaultOptions.config, {
@@ -83,7 +83,7 @@ describe('PointsIncentive', () => {
     ).toBe(1n);
   });
 
-  test('cannot claim twice', async () => {
+  test("cannot claim twice", async () => {
     const reward = 1n;
     // biome-ignore lint/style/noNonNullAssertion: we know this is defined
     const referrer = accounts.at(1)!.account!;
@@ -92,7 +92,7 @@ describe('PointsIncentive', () => {
 
     const pointsIncentive = fixtures.core.PointsIncentive({
       venue: points.assertValidAddress(),
-      selector: bytes4('issue(address,uint256)'),
+      selector: bytes4("issue(address,uint256)"),
       reward,
       limit: 10n,
     });
@@ -101,7 +101,7 @@ describe('PointsIncentive', () => {
     });
 
     const claimant = trustedSigner.account;
-    const incentiveData = pad('0xdef456232173821931823712381232131391321934');
+    const incentiveData = pad("0xdef456232173821931823712381232131391321934");
     const incentiveQuantity = 1;
     const claimDataPayload = await boost.validator.encodeClaimData({
       signer: trustedSigner,
@@ -122,7 +122,7 @@ describe('PointsIncentive', () => {
       0n,
       referrer,
       claimDataPayload,
-      { value: parseEther('0.000075') },
+      { value: parseEther("0.000075") },
     );
     try {
       await fixtures.core.claimIncentive(
@@ -130,7 +130,7 @@ describe('PointsIncentive', () => {
         0n,
         referrer,
         claimDataPayload,
-        { value: parseEther('0.000075') },
+        { value: parseEther("0.000075") },
       );
     } catch (e) {
       expect(e).toBeInstanceOf(Error);

package/src/Incentives/PointsIncentive.ts

@@ -125,7 +125,7 @@ export class PointsIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof erc20IncentiveAbi, 'claims'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public async claims(
@@ -144,7 +144,7 @@ export class PointsIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof erc20IncentiveAbi, 'currentReward'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>} - The current reward
    */
   public async currentReward(
@@ -163,8 +163,8 @@ export class PointsIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof pointsIncentiveAbi, 'reward'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<bigint>} The reward amount issued for each claim
    */
   public async reward(
     params?: ReadParams<typeof pointsIncentiveAbi, 'reward'>,
@@ -183,8 +183,8 @@ export class PointsIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {Address} address
-   * @param {?ReadParams<typeof pointsIncentiveAbi, 'claimed'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<boolean>}
    */
   public async claimed(
     address: Address,
@@ -203,8 +203,8 @@ export class PointsIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof pointsIncentiveAbi, 'venue'>} [params]
-   * @returns {unknown}
+   * @param {?ReadParams} [params]
+   * @returns {Promise<Address>}
    */
   public async venue(params?: ReadParams<typeof pointsIncentiveAbi, 'venue'>) {
     return await readPointsIncentiveVenue(this._config, {
@@ -219,7 +219,7 @@ export class PointsIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof pointsIncentiveAbi, 'limit'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<bigint>}
    */
   public async limit(params?: ReadParams<typeof pointsIncentiveAbi, 'limit'>) {
@@ -235,7 +235,7 @@ export class PointsIncentive extends DeployableTarget<
    *
    * @public
    * @async
-   * @param {?ReadParams<typeof pointsIncentiveAbi, 'selector'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<Hex>}
    */
   public async selector(
@@ -254,7 +254,7 @@ export class PointsIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?WriteParams<typeof pointsIncentiveAbi, 'claim'>} [params]
+   * @param {?WriteParams} [params]
    * @returns {Promise<boolean>} -  True if the incentive was successfully claimed
    */
   protected async claim(
@@ -270,8 +270,8 @@ export class PointsIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?WriteParams<typeof pointsIncentiveAbi, 'claim'>} [params]
-   * @returns {Promise<boolean>} -  True if the incentive was successfully claimed
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: boolean; }>} -  True if the incentive was successfully claimed
    */
   protected async claimRaw(
     payload: ClaimPayload,
@@ -299,7 +299,7 @@ export class PointsIncentive extends DeployableTarget<
    * @public
    * @async
    * @param {ClaimPayload} payload
-   * @param {?ReadParams<typeof pointsIncentiveAbi, 'isClaimable'>} [params]
+   * @param {?ReadParams} [params]
    * @returns {Promise<boolean>} -  True if the incentive is claimable based on the data payload
    */
   public async isClaimable(

package/src/Validators/SignerValidator.ts

@@ -327,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,
@@ -348,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,
@@ -374,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(
@@ -390,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(
@@ -423,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[],
@@ -443,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[],
@@ -471,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,
@@ -501,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.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

@@ -421,6 +421,45 @@ 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}`);
+  }
+}
+
+/**
+ * Thrown when missing logs for validating action steps.
+ *
+ * @export
+ * @class ValidationLogsMissingError
+ * @typedef {ValidationLogsMissingError}
+ * @extends {Error}
+ */
+export class ValidationLogsMissingError extends Error {
+  /**
+   * Creates an instance of ValidationLogsMissingError.
+   *
+   * @constructor
+   */
+  constructor() {
+    super('Logs are required for validation');
+  }
+}
+
 /**
  * Function action validation context to help debug other validation errors
  *
@@ -681,18 +720,144 @@ export class UnrecognizedFilterTypeError extends FieldActionValidationError {
   }
 }
 
+/**
+ * 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';
   }
 }