@boostxyz/sdk 0.0.0-alpha.3 → 0.0.0-alpha.6

package/src/errors.ts

@@ -0,0 +1,524 @@
+import {
+  type Hex,
+  type Log,
+  type WaitForTransactionReceiptReturnType,
+  zeroHash,
+} from 'viem';
+import type { Incentive } from './Incentives/Incentive';
+import type { Criteria } from './utils';
+
+/**
+ * This error is thrown during Boost creation if no `BoostCreated` event was emitted.
+ *
+ * @export
+ * @class BoostCoreNoIdentifierEmitted
+ * @typedef {BoostCoreNoIdentifierEmitted}
+ * @extends {Error}
+ * @example
+ * ```ts
+ * try {
+ *   await boostCore.createBoost(...)
+ * } catch(e) {
+ *   if(e instanceof BoostCoreNoIdentifierEmitted) {}
+ * }
+ * ```
+ */
+export class BoostCoreNoIdentifierEmitted extends Error {
+  /**
+   * Creates an instance of BoostCoreNoIdentifierEmitted.
+   *
+   * @constructor
+   */
+  constructor() {
+    super(`No "BoostCreated" log was emitted from which to extract boostId`);
+  }
+}
+
+/**
+ * This error is thrown when `assertValidAddress` is called, usually because a contract call expects the class to have a valid address attached.
+ *
+ * @export
+ * @class ContractAddressRequiredError
+ * @typedef {ContractAddressRequiredError}
+ * @extends {Error}
+ * @example
+ * ```ts
+ * try {
+ *   target.assertValidAddress()
+ * } catch(e) {
+ *   if(e instanceof ContractAddressRequiredError) {}
+ * }
+ */
+export class ContractAddressRequiredError extends Error {
+  /**
+   * Creates an instance of ContractAddressRequiredError.
+   *
+   * @constructor
+   */
+  constructor() {
+    super('Attempted to call contract method without providing an address');
+  }
+}
+
+/**
+ * This error is thrown when attempting to deploy a contract that has already been deployed, or has an address attached.
+ *
+ * @export
+ * @class DeployableAlreadyDeployedError
+ * @typedef {DeployableAlreadyDeployedError}
+ * @extends {Error}
+ */
+export class DeployableAlreadyDeployedError extends Error {
+  /**
+   * The address already attached to the target.
+   *
+   * @type {string}
+   */
+  address: string;
+  /**
+   * Creates an instance of DeployableAlreadyDeployedError.
+   *
+   * @constructor
+   * @param {string} address
+   */
+  constructor(address: string) {
+    super(
+      `Attempted to deploy a contract that already has an address configured`,
+    );
+    this.address = address;
+  }
+}
+
+/**
+ * You should never see this error if we did our jobs and every target overrides the `buildParameters` method.
+ *
+ * @export
+ * @class DeployableBuildParametersUnspecifiedError
+ * @typedef {DeployableBuildParametersUnspecifiedError}
+ * @extends {Error}
+ */
+export class DeployableBuildParametersUnspecifiedError extends Error {
+  /**
+   * Creates an instance of DeployableBuildParametersUnspecifiedError.
+   *
+   * @constructor
+   */
+  constructor() {
+    super(
+      'Implementing class did not properly override the `buildParameters` method',
+    );
+  }
+}
+
+/**
+ * This error is thrown when attempting to deploy an `ownable` contract and the owner cannot be ascertained from the initialization payload or configured account.
+ *
+ * @export
+ * @class DeployableUnknownOwnerProvidedError
+ * @typedef {DeployableUnknownOwnerProvidedError}
+ * @extends {Error}
+ */
+export class DeployableUnknownOwnerProvidedError extends Error {
+  /**
+   * Creates an instance of DeployableUnknownOwnerProvidedError.
+   *
+   * @constructor
+   */
+  constructor() {
+    super(
+      'Expected an an owner to be provided in configuration or an account to exist on Wagmi config.',
+    );
+  }
+}
+
+/**
+ * This error is thrown when deploying a contract with no valid Wagmi configuration on the instance.
+ *
+ * @export
+ * @class DeployableWagmiConfigurationRequiredError
+ * @typedef {DeployableWagmiConfigurationRequiredError}
+ * @extends {Error}
+ */
+export class DeployableWagmiConfigurationRequiredError extends Error {
+  /**
+   * Creates an instance of DeployableWagmiConfigurationRequiredError.
+   *
+   * @constructor
+   */
+  constructor() {
+    super(
+      'Expected a valid Wagmi configuration to be available either on Deployable, or as argument to deploy.',
+    );
+  }
+}
+
+/**
+ * This error is thrown when deploying a contract with no valid initialization payload.
+ *
+ * @export
+ * @class DeployableMissingPayloadError
+ * @typedef {DeployableMissingPayloadError}
+ * @extends {Error}
+ */
+export class DeployableMissingPayloadError extends Error {
+  /**
+   * Creates an instance of DeployableMissingPayloadError.
+   *
+   * @constructor
+   */
+  constructor() {
+    super(
+      'Expected a valid payload to be available either on Deployable or as argument to deploy.',
+    );
+  }
+}
+
+/**
+ * This error is thrown when we receive a transaction receipt for a contract deployment without a contract address on it.
+ *
+ * @export
+ * @class NoContractAddressUponReceiptError
+ * @typedef {NoContractAddressUponReceiptError}
+ * @extends {Error}
+ */
+export class NoContractAddressUponReceiptError extends Error {
+  /**
+   * The raw receipt we receive from [waitForTransactionReceipt](https://v1.viem.sh/docs/actions/public/waitForTransactionReceipt.html#waitfortransactionreceipt)
+   *
+   * @public
+   * @readonly
+   * @type {WaitForTransactionReceiptReturnType}
+   */
+  public readonly receipt: WaitForTransactionReceiptReturnType;
+  /**
+   * Creates an instance of NoContractAddressUponReceiptError.
+   *
+   * @constructor
+   * @param {WaitForTransactionReceiptReturnType} receipt
+   */
+  constructor(receipt: WaitForTransactionReceiptReturnType) {
+    super(`Expected a contract address to exist on receipt.`, {
+      cause: receipt,
+    });
+    this.receipt = receipt;
+  }
+}
+
+/**
+ * This error is thrown when a target address was provided that doesn't match any supported interface for the given registry type.
+ * For example, if you try to do `incentiveFromAddress()` with the address of a deployed `SimpleBudget`
+ *
+ * @export
+ * @class InvalidComponentInterfaceError
+ * @typedef {InvalidComponentInterfaceError}
+ * @extends {Error}
+ */
+export class InvalidComponentInterfaceError extends Error {
+  /**
+   * Expected interface hashes.
+   *
+   * @public
+   * @readonly
+   * @type {Hex[]}
+   */
+  public readonly expected: Hex[] = [];
+  /**
+   * The actual interface hash.
+   *
+   * @public
+   * @readonly
+   * @type {Hex}
+   */
+  public readonly received: Hex = zeroHash;
+
+  /**
+   * Creates an instance of InvalidComponentInterfaceError.
+   *
+   * @constructor
+   * @param {Hex[]} expected
+   * @param {Hex} received
+   */
+  constructor(expected: Hex[], received: Hex) {
+    super(`Address provided does not match any expected protocol interface`, {
+      cause: { expected, received },
+    });
+    this.expected = expected;
+    this.received = received;
+  }
+}
+
+/**
+ * This error is thrown when attempting a Budget transfer and arguments aren't of the type `FungibleTransferPayload` or `ERC1155TransferPayload`
+ *
+ * @see {@link FungibleTransferPayload}
+ * @see {@link ERC1155TransferPayload}
+ * @export
+ * @class UnknownTransferPayloadSupplied
+ * @typedef {UnknownTransferPayloadSupplied}
+ * @extends {Error}
+ */
+export class UnknownTransferPayloadSupplied extends Error {
+  /**
+   * The given payload that does not conform to the correct payload shape.
+   *
+   * @type {unknown}
+   */
+  received: unknown;
+  /**
+   * Creates an instance of UnknownTransferPayloadSupplied.
+   *
+   * @constructor
+   * @param {unknown} received
+   */
+  constructor(received: unknown) {
+    super(
+      `Did not provide a valid FungibleTransferPayload or ERC1155 transfer payload.`,
+      { cause: received },
+    );
+    this.received = received;
+  }
+}
+
+/**
+ * This error is thrown during Boost creation when the budget doesn't authorize the Boost Core address.
+ *
+ * @export
+ * @class BudgetMustAuthorizeBoostCore
+ * @typedef {BudgetMustAuthorizeBoostCore}
+ * @extends {Error}
+ */
+export class BudgetMustAuthorizeBoostCore extends Error {
+  /**
+   * Creates an instance of BudgetMustAuthorizeBoostCore.
+   *
+   * @constructor
+   * @param {string} boostCoreAddress
+   */
+  constructor(boostCoreAddress: string) {
+    super(
+      `Budget needs to explicitly authorize ${boostCoreAddress}. You can retrieve this value from BoostCore.address`,
+    );
+  }
+}
+
+/**
+ * The error is thrown when trying to reuse an existing deployed Incentive that isn't a base implementation.
+ * The protocol doesn't allow this.
+ *
+ * @export
+ * @class IncentiveNotCloneableError
+ * @typedef {IncentiveNotCloneableError}
+ * @extends {Error}
+ */
+export class IncentiveNotCloneableError extends Error {
+  /**
+   * Creates an instance of IncentiveNotCloneableError.
+   *
+   * @constructor
+   * @param {Incentive} incentive
+   */
+  constructor(incentive: Incentive) {
+    super(`Incentive not cloneable: ${incentive.constructor.name}`);
+  }
+}
+
+/**
+ * Thrown when encoding an EventAction payload and no action steps are provided
+ *
+ * @export
+ * @class NoEventActionStepsProvidedError
+ * @typedef {NoEventActionStepsProvidedError}
+ * @extends {Error}
+ */
+export class NoEventActionStepsProvidedError extends Error {
+  /**
+   * Creates an instance of NoEventActionStepsProvidedError.
+   *
+   * @constructor
+   */
+  constructor() {
+    super('Must supply at least one action step');
+  }
+}
+
+/**
+ * Thrown when encoding an EventAction payload and > 4 steps are provided
+ *
+ * @export
+ * @class TooManyEventActionStepsProvidedError
+ * @typedef {TooManyEventActionStepsProvidedError}
+ * @extends {Error}
+ */
+export class TooManyEventActionStepsProvidedError extends Error {
+  /**
+   * Creates an instance of TooManyEventActionStepsProvidedError.
+   *
+   * @constructor
+   */
+  constructor() {
+    super(
+      'Cannot supply more than 4 action steps with current protocol version',
+    );
+  }
+}
+
+/**
+ * Event action validation context to help debug other validation errors
+ *
+ * @interface EventActionValidationMeta
+ * @typedef {EventActionValidationMeta}
+ */
+interface EventActionValidationMeta {
+  /**
+   * The viem log being validated against
+   *
+   * @type {Log}
+   */
+  log: Log;
+  /**
+   * 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;
+}
+
+/**
+ * The base error thrown during event action validation extended by more specific validation errors.
+ * Instantiated with relevent context data for more in depth debugging.
+ *
+ * @export
+ * @class EventActionValidationError
+ * @typedef {EventActionValidationError}
+ * @extends {Error}
+ */
+export class EventActionValidationError extends Error {
+  /**
+   * The viem log being validated against
+   *
+   * @type {Log}
+   */
+  log: Log;
+  /**
+   * 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;
+  /**
+   * Creates an instance of EventActionValidationError.
+   *
+   * @constructor
+   * @param {string} message
+   * @param {EventActionValidationMeta} param0
+   * @param {*} param0.fieldValue
+   * @param {Criteria} param0.criteria
+   * @param {Log} param0.log
+   */
+  constructor(
+    message: string,
+    { fieldValue, criteria, log }: EventActionValidationMeta,
+  ) {
+    super(message);
+    this.fieldValue = fieldValue;
+    this.criteria = criteria;
+    this.log = log;
+  }
+}
+
+/**
+ * Thrown when field value on log is undefined
+ *
+ * @export
+ * @class FieldValueUndefinedError
+ * @typedef {FieldValueUndefinedError}
+ * @extends {EventActionValidationError}
+ */
+export class FieldValueUndefinedError extends EventActionValidationError {
+  /**
+   * Creates an instance of FieldValueUndefinedError.
+   *
+   * @constructor
+   * @param {EventActionValidationMeta} metadata
+   */
+  constructor(metadata: EventActionValidationMeta) {
+    super('Field value is undefined', metadata);
+  }
+}
+
+/**
+ * Thrown when a filter type is using a numerical operator but field type is not numerical
+ *
+ * @export
+ * @class InvalidNumericalCriteriaError
+ * @typedef {InvalidNumericalCriteriaError}
+ * @extends {EventActionValidationError}
+ */
+export class InvalidNumericalCriteriaError extends EventActionValidationError {
+  /**
+   * Creates an instance of InvalidNumericalCriteria.
+   *
+   * @constructor
+   * @param {EventActionValidationMeta} metadata
+   */
+  constructor(metadata: EventActionValidationMeta) {
+    super(
+      'Numerical comparisons cannot be used with non-numerical criteria',
+      metadata,
+    );
+  }
+}
+
+/**
+ * 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}
+ */
+export class FieldValueNotComparableError extends EventActionValidationError {
+  /**
+   * Creates an instance of FieldValueNotComparableError.
+   *
+   * @constructor
+   * @param {EventActionValidationMeta} metadata
+   */
+  constructor(metadata: EventActionValidationMeta) {
+    super('Filter can only be used with bytes or string field type', metadata);
+  }
+}
+
+/**
+ * Thrown when an invalid filter type enum was provided event action validation.
+ *
+ * @export
+ * @class UnrecognizedFilterTypeError
+ * @typedef {UnrecognizedFilterTypeError}
+ * @extends {EventActionValidationError}
+ */
+export class UnrecognizedFilterTypeError extends EventActionValidationError {
+  /**
+   * Creates an instance of UnrecognizedFilterTypeError.
+   *
+   * @constructor
+   * @param {EventActionValidationMeta} metadata
+   */
+  constructor(metadata: EventActionValidationMeta) {
+    super('Invalid FilterType provided', metadata);
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,40 @@
+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();
+
+    // 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();
+  });
+});

package/src/index.ts

@@ -0,0 +1,50 @@
+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
+
+export * from './Actions/Action';
+// export * from './Actions/ContractAction';
+// export * from './Actions/ERC721MintAction';
+export * from './Actions/EventAction';
+
+// AllowLists
+
+export * from './AllowLists/AllowList';
+export * from './AllowLists/SimpleAllowList';
+export * from './AllowLists/SimpleDenyList';
+
+// Budgets
+
+export * from './Budgets/Budget';
+// export * from './Budgets/SimpleBudget';
+// export * from './Budgets/VestingBudget';
+export * from './Budgets/ManagedBudget';
+
+// Deployable
+
+export * from './Deployable/Deployable';
+export * from './Deployable/Contract';
+export * from './Deployable/DeployableTarget';
+
+// Incentives
+
+export * from './Incentives/AllowListIncentive';
+export * from './Incentives/CGDAIncentive';
+export * from './Incentives/ERC20Incentive';
+// export * from './Incentives/ERC1155Incentive';
+export * from './Incentives/Incentive';
+export * from './Incentives/PointsIncentive';
+
+// Validators
+
+export * from './Validators/SignerValidator';
+export * from './Validators/Validator';

package/src/utils.test.ts

@@ -0,0 +1,44 @@
+import { simulateMockErc20Mint, writeMockErc20Mint } from '@boostxyz/evm';
+import { isAddress } from 'viem';
+import { describe, expect, test } from 'vitest';
+import { MockERC20 } from '../test/MockERC20';
+import { defaultOptions } from '../test/helpers';
+import { awaitResult, bytes4, getDeployedContractAddress } from './utils';
+
+describe('bytes4', () => {
+  test('should return the bytes4 representation of a string', () => {
+    expect(bytes4('0xdeadbeef')).toBe('0xd4fd4e18');
+    expect(bytes4('deadbeef')).toBe('0x9f24c52e');
+  });
+});
+
+describe('getDeployedContractAddress', () => {
+  test('should return the address of a contract given a tx hash promise', async () => {
+    const hash = new MockERC20(defaultOptions, {}).deployRaw();
+    expect(
+      isAddress(await getDeployedContractAddress(defaultOptions.config, hash)),
+    ).toBe(true);
+  });
+});
+
+describe('awaitResult', () => {
+  test('should wait for a transaction receipt and return the simulated result', async () => {
+    const erc20 = new MockERC20(defaultOptions, {});
+    await erc20.deploy();
+    const { request, result } = await simulateMockErc20Mint(
+      defaultOptions.config,
+      {
+        address: erc20.assertValidAddress(),
+        args: [defaultOptions.account.address, 100n],
+        account: defaultOptions.account,
+      },
+    );
+    const hash = await writeMockErc20Mint(defaultOptions.config, request);
+    expect(
+      await awaitResult(
+        defaultOptions.config,
+        Promise.resolve({ hash, result }),
+      ),
+    ).toBe(undefined);
+  });
+});