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

package/src/errors.ts

@@ -1,12 +1,15 @@
 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';
-import type { Criteria } from './utils';
 
 /**
  * This error is thrown during Boost creation if no `BoostCreated` event was emitted.
@@ -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;
+  }
+}

package/src/index.test.ts

@@ -1,40 +1,122 @@
-import { describe, expect, test } from 'vitest';
-import * as SDK from './index';
+import { describe, expect, test } from "vitest";
+import * as SDK from "./index";
 
-describe('sdk exports', () => {
-  test(`should export all public API`, () => {
-    expect(SDK.BoostRegistry).toBeDefined();
-    expect(SDK.BoostCore).toBeDefined();
-    expect(SDK.Boost).toBeDefined();
-
-    // interfaces
-    expect(SDK.PassthroughAuth).toBeDefined();
-    // expect(SDK.ContractAction).toBeDefined();
-    // expect(SDK.ERC721MintAction).toBeDefined();
-    expect(SDK.SimpleAllowList).toBeDefined();
-    expect(SDK.SimpleDenyList).toBeDefined();
-    expect(SDK.ManagedBudget).toBeDefined();
-    // expect(SDK.SimpleBudget).toBeDefined();
-    // expect(SDK.VestingBudget).toBeDefined();
-    expect(SDK.AllowListIncentive).toBeDefined();
-    expect(SDK.CGDAIncentive).toBeDefined();
-    expect(SDK.ERC20Incentive).toBeDefined();
-    // expect(SDK.ERC1155Incentive).toBeDefined();
-    expect(SDK.PointsIncentive).toBeDefined();
-    expect(SDK.SignerValidator).toBeDefined();
+// Please add any public interface you'd like to verify exists on the root export here
+// Types don't exist in .js so only list objects, constants, classes, etc, no interfaces
+const allExports = [
+  "BoostRegistry",
+  "BoostCore",
+  "Boost",
+  "EventAction",
+  "OpenAllowList",
+  "SimpleAllowList",
+  "SimpleDenyList",
+  "ManagedBudget",
+  "Deployable",
+  "Contract",
+  "DeployableTarget",
+  "DeployableTargetWithRBAC",
+  "AllowListIncentive",
+  "CGDAIncentive",
+  "ERC20Incentive",
+  "ERC20VariableIncentive",
+  "ERC20VariableCriteriaIncentive",
+  "PointsIncentive",
+  "SignerValidator",
+  "BoostCoreNoIdentifierEmitted",
+  "ContractAddressRequiredError",
+  "DeployableAlreadyDeployedError",
+  "DeployableBuildParametersUnspecifiedError",
+  "DeployableUnknownOwnerProvidedError",
+  "DeployableWagmiConfigurationRequiredError",
+  "DeployableMissingPayloadError",
+  "NoContractAddressUponReceiptError",
+  "InvalidComponentInterfaceError",
+  "UnparseableAbiParamError",
+  "UnknownTransferPayloadSupplied",
+  "BudgetMustAuthorizeBoostCore",
+  "MustInitializeBudgetError",
+  "IncentiveNotCloneableError",
+  "NoEventActionStepsProvidedError",
+  "TooManyEventActionStepsProvidedError",
+  "ValidationAbiMissingError",
+  "FieldActionValidationError",
+  "DecodedArgsMalformedError",
+  "FieldValueUndefinedError",
+  "InvalidNumericalCriteriaError",
+  "FunctionDataDecodeError",
+  "FieldValueNotComparableError",
+  "UnrecognizedFilterTypeError",
+  "NoConnectedChainIdError",
+  "InvalidProtocolChainIdError",
+  "IncentiveCriteriaNotFoundError",
+  "NoMatchingLogsError",
+  "InvalidCriteriaTypeError",
+  "DecodedArgsError",
+  "PassthroughAuth",
+  "prepareBoostPayload",
+  "actionFromAddress",
+  "isEventActionPayloadSimple",
+  "prepareEventActionPayload",
+  "allowListFromAddress",
+  "prepareSimpleAllowListPayload",
+  "prepareSimpleDenyListPayload",
+  "budgetFromAddress",
+  "isFungibleTransfer",
+  "isERC1155TransferPayload",
+  "prepareTransfer",
+  "prepareManagedBudgetPayload",
+  "prepareAllowListIncentivePayload",
+  "prepareCGDAIncentivePayload",
+  "prepareERC20IncentivePayload",
+  "prepareERC20VariableIncentivePayload",
+  "prepareERC20VariableCriteriaIncentivePayload",
+  "incentiveFromAddress",
+  "preparePointsIncentivePayload",
+  "prepareSignerValidatorClaimDataPayload",
+  "prepareSignerValidatorInputParams",
+  "prepareSignerValidatorPayload",
+  "validatorFromAddress",
+  "bytes4",
+  "getDeployedContractAddress",
+  "awaitResult",
+  "assertValidAddressByChainId",
+  "prepareClaimPayload",
+  "prepareERC1155Payload",
+  "prepareERC1155Transfer",
+  "prepareFungiblePayload",
+  "prepareFungibleTransfer",
+  "prepareTransferPayload",
+  "BOOST_REGISTRY_ADDRESS",
+  "BOOST_REGISTRY_ADDRESSES",
+  "boostCoreAbi",
+  "boostRegistryAbi",
+  "BOOST_CORE_CLAIM_FEE",
+  "BOOST_CORE_ADDRESS",
+  "BOOST_CORE_ADDRESSES",
+  "ActionByComponentInterface",
+  "AllowListByComponentInterface",
+  "simpleAllowListAbi",
+  "LIST_MANAGER_ROLE",
+  "simpleDenyListAbi",
+  "BudgetByComponentInterface",
+  "managedBudgetAbi",
+  "rbacAbi",
+  "allowListIncentiveAbi",
+  "cgdaIncentiveAbi",
+  "erc20IncentiveAbi",
+  "erc20VariableIncentiveAbi",
+  "IncentiveByComponentInterface",
+  "pointsIncentiveAbi",
+  "signerValidatorAbi",
+  "ValidatorByComponentInterface",
+  "passthroughAuthAbi"
+]
 
-    // errors
-    expect(SDK.BoostCoreNoIdentifierEmitted).toBeDefined();
-    expect(SDK.ContractAddressRequiredError).toBeDefined();
-    expect(SDK.DeployableAlreadyDeployedError).toBeDefined();
-    expect(SDK.DeployableBuildParametersUnspecifiedError).toBeDefined();
-    expect(SDK.DeployableUnknownOwnerProvidedError).toBeDefined();
-    expect(SDK.DeployableWagmiConfigurationRequiredError).toBeDefined();
-    expect(SDK.DeployableMissingPayloadError).toBeDefined();
-    expect(SDK.NoContractAddressUponReceiptError).toBeDefined();
-    expect(SDK.InvalidComponentInterfaceError).toBeDefined();
-    expect(SDK.UnknownTransferPayloadSupplied).toBeDefined();
-    expect(SDK.BudgetMustAuthorizeBoostCore).toBeDefined();
-    expect(SDK.IncentiveNotCloneableError).toBeDefined();
+describe("SDK exports", () => {
+  test(`should export all public API`, () => {
+    for(let exp of allExports) {
+      expect((SDK as any)[exp]).toBeDefined()
+    }
   });
 });

package/src/index.ts

@@ -1,13 +1,6 @@
 export * from './BoostRegistry';
 export * from './BoostCore';
 export * from './Boost';
-export * from './errors';
-export * from './utils';
-
-// Auth
-
-export * from './Auth/Auth';
-export * from './Auth/PassthroughAuth';
 
 // Actions
 
@@ -34,12 +27,15 @@ export * from './Budgets/ManagedBudget';
 export * from './Deployable/Deployable';
 export * from './Deployable/Contract';
 export * from './Deployable/DeployableTarget';
+export * from './Deployable/DeployableTargetWithRBAC';
 
 // Incentives
 
 export * from './Incentives/AllowListIncentive';
 export * from './Incentives/CGDAIncentive';
 export * from './Incentives/ERC20Incentive';
+export * from './Incentives/ERC20VariableIncentive';
+export * from './Incentives/ERC20VariableCriteriaIncentive';
 // export * from './Incentives/ERC1155Incentive';
 export * from './Incentives/Incentive';
 export * from './Incentives/PointsIncentive';
@@ -48,3 +44,15 @@ export * from './Incentives/PointsIncentive';
 
 export * from './Validators/SignerValidator';
 export * from './Validators/Validator';
+
+// Extra
+
+export * from './errors';
+export * from './utils';
+export * from './claiming';
+export * from './transfers';
+
+// Auth
+
+export * from './Auth/Auth';
+export * from './Auth/PassthroughAuth';