@boostxyz/sdk 0.0.0-alpha.10

package/src/Validators/Validator.ts

@@ -0,0 +1,55 @@
+import { aValidatorAbi } from '@boostxyz/evm';
+import { ASignerValidator } from '@boostxyz/evm/deploys/componentInterfaces.json';
+import { readContract } from '@wagmi/core';
+import type { Address, Hex } from 'viem';
+import type { DeployableOptions } from '../Deployable/Deployable';
+import { InvalidComponentInterfaceError } from '../errors';
+import { SignerValidator } from './SignerValidator';
+
+export { SignerValidator };
+
+/**
+ * A union type representing all valid protocol Validator implementations
+ *
+ * @export
+ * @typedef {Validator}
+ */
+export type Validator = SignerValidator;
+
+/**
+ * A map of Validator component interfaces to their constructors.
+ *
+ * @type {{ "0xd8725ea2": typeof SignerValidator; }}
+ */
+export const ValidatorByComponentInterface = {
+  [ASignerValidator as Hex]: SignerValidator,
+};
+
+/**
+ * A function that will read a contract's component interface using `getComponentInterface` and return the correct instantiated instance.
+ *
+ * @export
+ * @async
+ * @param {DeployableOptions} options
+ * @param {Address} address
+ * @returns {unknown}
+ * @throws {@link InvalidComponentInterfaceError}
+ */
+export async function validatorFromAddress(
+  options: DeployableOptions,
+  address: Address,
+) {
+  const interfaceId = (await readContract(options.config, {
+    abi: aValidatorAbi,
+    functionName: 'getComponentInterface',
+    address,
+  })) as keyof typeof ValidatorByComponentInterface;
+  const Ctor = ValidatorByComponentInterface[interfaceId];
+  if (!Ctor) {
+    throw new InvalidComponentInterfaceError(
+      Object.keys(ValidatorByComponentInterface) as Hex[],
+      interfaceId as Hex,
+    );
+  }
+  return new Ctor(options, address);
+}

package/src/claiming.ts

@@ -0,0 +1,56 @@
+import { type Address, type Hex, encodeAbiParameters, zeroHash } from 'viem';
+
+/**
+ * Enum representing incentive disbursement strategies.
+ *
+ * @export
+ * @enum {number}
+ */
+export enum StrategyType {
+  POOL = 0,
+  MINT = 1,
+  RAFFLE = 2,
+}
+
+/**
+ * The object representation of an `Incentive.ClaimPayload`
+ *
+ * @export
+ * @interface ClaimPayload
+ * @typedef {ClaimPayload}
+ */
+export interface ClaimPayload {
+  /**
+   * The address of the recipient
+   *
+   * @type {Address}
+   */
+  target: Address;
+  /**
+   * The implementation-specific data for the claim, if needed
+   *
+   * @type {?Hex}
+   */
+  data?: Hex;
+}
+
+/**
+ * Given a valid {@link ClaimPayload}, encode the payload for use with Incentive operations.
+ *
+ * @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 {*}
+ */
+export const prepareClaimPayload = ({
+  target,
+  data = zeroHash,
+}: ClaimPayload) => {
+  return encodeAbiParameters(
+    [
+      { type: 'address', name: 'target' },
+      { type: 'bytes', name: 'data' },
+    ],
+    [target, data],
+  );
+};

package/src/errors.ts

@@ -0,0 +1,542 @@
+import {
+  type Hex,
+  type Log,
+  type WaitForTransactionReceiptReturnType,
+  zeroHash,
+} from 'viem';
+import type { Criteria } from './Actions/EventAction';
+import type { BoostRegistry } from './BoostRegistry';
+import type { Incentive } from './Incentives/Incentive';
+
+/**
+ * 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`,
+    );
+  }
+}
+
+/**
+ * Because this contract is a base implementation, it should not be initialized through the constructor. Instead, it should be cloned and initialized using the {@link BoostRegistry}
+ *
+ * @export
+ * @class MustInitializeBudgetError
+ * @typedef {MustInitializeBudgetError}
+ * @extends {Error}
+ */
+export class MustInitializeBudgetError extends Error {
+  /**
+   * Creates an instance of MustInitializeBudgetError.
+   */
+  constructor() {
+    super(`Budgets must be preinitialized before being used with a new Boost`);
+  }
+}
+
+/**
+ * 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();
+  });
+});