@boostxyz/sdk 0.0.0-alpha.2 → 0.0.0-alpha.21

package/src/Deployable/Contract.ts

@@ -0,0 +1,228 @@
+import { type Config, watchContractEvent } from '@wagmi/core';
+import type { ExtractAbiEvent } from 'abitype';
+import {
+  type Abi,
+  type Address,
+  type ContractEventName,
+  type GetLogsReturnType,
+  type WaitForTransactionReceiptParameters,
+  type WatchContractEventOnLogsParameter,
+  getAbiItem,
+} from 'viem';
+import { getLogs } from 'viem/actions';
+import { ContractAddressRequiredError } from '../errors';
+import {
+  type GetLogsParams,
+  type HashAndSimulatedResult,
+  type WatchParams,
+  awaitResult,
+} from '../utils';
+
+/**
+ * A basic Contract class to encapsulate configuration and a potential address
+ *
+ * @export
+ * @class Contract
+ * @typedef {Contract}
+ * @template {Abi} [ContractAbi=[]]
+ * @template {ContractEventName<ContractAbi>} [ContractEvent=any]
+ */
+export class Contract<ContractAbi extends Abi> {
+  //@ts-expect-error this should always be set by implementing contract
+  public readonly abi: ContractAbi;
+  /**
+   * @see [Wagmi Configuration](https://wagmi.sh/core/api/createConfig)
+   * @protected
+   * @type {WagmiConfig}
+   */
+  protected _config: Config;
+  /**
+   * The internally managed address for this contract
+   *
+   * @protected
+   * @type {(Address | undefined)}
+   */
+  protected _address: Address | undefined;
+
+  /**
+   * Creates an instance of Contract.
+   *
+   * @constructor
+   * @param {Config} config
+   * @param {(Address | undefined)} address
+   */
+  constructor(config: Config, address: Address | undefined) {
+    this._config = config;
+    this._address = address;
+  }
+
+  /**
+   * A getter returning this contract's deployed address, if it exists.
+   *
+   * @public
+   * @readonly
+   * @type {Address | undefined}
+   */
+  public get address() {
+    return this._address;
+  }
+
+  /**
+   * Will set this contract's address and return the instance for chaining. Does not verify that provided address is valid.
+   *
+   * @public
+   * @param {Address} address
+   * @returns {this}
+   */
+  public at(address: Address) {
+    this._address = address;
+    return this;
+  }
+
+  /**
+   * Will set this contract's internal [Wagmi Configuration](https://en.wikipedia.org/wiki/Factorial) and return the instance for chaining.
+   *
+   * @public
+   * @param {Config} config
+   * @returns {this}
+   */
+  public withConfig(config: Config) {
+    this._config = config;
+    return this;
+  }
+
+  /**
+   * Utility function to validate the existence of an address on this Contract.
+   *
+   * @public
+   * @returns {Address}
+   * @throws {@link ContractAddressRequiredError} if no address exists on this Contract instance
+   */
+  public assertValidAddress() {
+    const address = this.address;
+    if (!address) throw new ContractAddressRequiredError();
+    return address;
+  }
+
+  /**
+   * A typed wrapper for (viem.getLogs)[https://viem.sh/docs/actions/public/getLogs#getlogs].
+   * Accepts `eventName` and `eventNames` as optional parameters to narrow the returned log types.
+   * @example
+   * ```ts
+   * const logs = contract.getLogs({ eventName: 'EventName' })
+   * const logs = contract.getLogs({ eventNames: ['EventName'] })
+   *
+   * @public
+   * @async
+   * @template {ContractEvent} event
+   * @template {ExtractAbiEvent<
+   *       ContractAbi,
+   *       event
+   *     >} [abiEvent=ExtractAbiEvent<ContractAbi, event>]
+   * @param {?Omit<
+   *       GetLogsParams<ContractAbi, event, abiEvent, abiEvent[]>,
+   *       'event' | 'events'
+   *     > & {
+   *       eventName?: event;
+   *       eventNames?: event[];
+   *     }} [params]
+   * @returns {Promise<GetLogsReturnType<abiEvent, abiEvent[]>>}
+   */
+  public async getLogs<
+    event extends ContractEventName<ContractAbi>,
+    const abiEvent extends ExtractAbiEvent<
+      ContractAbi,
+      event
+    > = ExtractAbiEvent<ContractAbi, event>,
+  >(
+    params?: Omit<
+      GetLogsParams<ContractAbi, event, abiEvent, abiEvent[]>,
+      'event' | 'events'
+    > & {
+      eventName?: event;
+      eventNames?: event[];
+    },
+  ): Promise<GetLogsReturnType<abiEvent, abiEvent[]>> {
+    return getLogs(this._config.getClient({ chainId: params?.chainId }), {
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wag
+      ...(params as any),
+      ...(params?.eventName
+        ? {
+            event: getAbiItem({
+              abi: this.abi,
+              name: params.eventName,
+              // biome-ignore lint/suspicious/noExplicitAny: awkward abi intersection issue
+            } as any),
+          }
+        : {}),
+      ...(params?.eventNames
+        ? {
+            events: params.eventNames.map((name) =>
+              getAbiItem({
+                abi: this.abi,
+                name,
+                // biome-ignore lint/suspicious/noExplicitAny: awkward abi intersection issue
+              } as any),
+            ),
+          }
+        : {}),
+      address: this.assertValidAddress(),
+    });
+  }
+
+  /**
+   * A typed wrapper for `wagmi.watchContractEvent`
+   *
+   * @public
+   * @template {ContractEvent} event
+   * @param {(
+   *       log: WatchContractEventOnLogsParameter<ContractAbi, event, true>[number],
+   *     ) => unknown} cb
+   * @param {?WatchParams<ContractAbi, event> & {
+   *       eventName?: event;
+   *     }} [params]
+   * @returns {() => void}
+   */
+  public subscribe<event extends ContractEventName<ContractAbi>>(
+    cb: (
+      log: WatchContractEventOnLogsParameter<ContractAbi, event, true>[number],
+    ) => unknown,
+    params?: WatchParams<ContractAbi, event> & {
+      eventName?: event;
+    },
+  ) {
+    return watchContractEvent<
+      typeof this._config,
+      (typeof this._config)['chains'][number]['id'],
+      ContractAbi,
+      event
+    >(this._config, {
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+      eventName: params?.eventName,
+      abi: this.abi,
+      address: this.assertValidAddress(),
+      onLogs: (logs) => {
+        for (let l of logs) {
+          cb(l);
+        }
+      },
+    });
+  }
+
+  /**
+   * @see {@link awaitResult}
+   * @protected
+   * @async
+   * @template [Result=unknown]
+   * @param {Promise<HashAndSimulatedResult<Result>>} hashPromise
+   * @param {?Omit<WaitForTransactionReceiptParameters, 'hash'>} [waitParams]
+   * @returns {Promise<Result>}
+   */
+  protected async awaitResult<Result = unknown>(
+    hashPromise: Promise<HashAndSimulatedResult<Result>>,
+    waitParams?: Omit<WaitForTransactionReceiptParameters, 'hash'>,
+  ) {
+    return await awaitResult(this._config, hashPromise, waitParams);
+  }
+}

package/src/Deployable/Deployable.ts

@@ -0,0 +1,250 @@
+import { type Config, deployContract } from '@wagmi/core';
+import type {
+  Abi,
+  Account,
+  Address,
+  ContractEventName,
+  Hash,
+  Hex,
+  WaitForTransactionReceiptParameters,
+} from 'viem';
+import {
+  DeployableAlreadyDeployedError,
+  DeployableBuildParametersUnspecifiedError,
+  DeployableMissingPayloadError,
+  DeployableWagmiConfigurationRequiredError,
+} from '../errors';
+import { getDeployedContractAddress } from '../utils';
+import { Contract } from './Contract';
+
+/**
+ * A base class representing a deployable contract, contains base implementations for deployment and initialization payload construction.
+ *
+ * @export
+ * @typedef {GenericDeployableParams}
+ */
+export type GenericDeployableParams = Omit<
+  Parameters<typeof deployContract>[1],
+  'args' | 'account'
+> & {
+  args: [Hex, ...Array<Hex>];
+  account?: Account;
+};
+
+/**
+ * A generic type that encapsulates either an initialization payload for a contract, or a valid address for a previously deployed contract.
+ *
+ * @export
+ * @typedef {DeployablePayloadOrAddress}
+ * @template [Payload=unknown]
+ */
+export type DeployablePayloadOrAddress<Payload = unknown> = Payload | Address;
+
+/**
+ * Instantion options for the base deployable.
+ *
+ * @export
+ * @interface DeployableOptions
+ * @typedef {DeployableOptions}
+ */
+export interface DeployableOptions {
+  /**
+   * [Wagmi Configuration](https://wagmi.sh/core/api/createConfig)
+   *
+   * @see {@link Config}
+   * @type {Config}
+   */
+  config: Config;
+  /**
+   * [Viem Local Account](https://viem.sh/docs/accounts/local), required if in a Node environment
+   *
+   * @see {@link Account}
+   * @type {?Account}
+   */
+  account?: Account;
+}
+
+/**
+ * A generic deployable contract that encapsulates common operations related to contract deployment
+ *
+ * @export
+ * @class Deployable
+ * @typedef {Deployable}
+ * @template [Payload=unknown]
+ * @template {Abi} [ContractAbi=[]]
+ * @template {ContractEventName<ContractAbi>} [ContractEvent=ContractEventName<ContractAbi>]
+ * @extends {Contract<ContractAbi, ContractEvent>}
+ */
+export class Deployable<
+  Payload,
+  ContractAbi extends Abi,
+> extends Contract<ContractAbi> {
+  /**
+   * The deployable payload used either for contract construction or initialization
+   *
+   * @protected
+   * @type {(Payload | undefined)}
+   */
+  protected _payload: Payload | undefined;
+  /**
+   * If it exists, [Viem Local Account](https://viem.sh/docs/accounts/local), if in a Node environment
+   *
+   * @protected
+   * @type {?Account}
+   */
+  protected _account?: Account;
+
+  /**
+   * Creates an instance of Deployable.
+   *
+   * @constructor
+   * @param {DeployableOptions} param0
+   * @param {?Account} [param0.account]
+   * @param {Config} param0.config
+   * @param {DeployablePayloadOrAddress<Payload>} payload
+   */
+  constructor(
+    { account, config }: DeployableOptions,
+    payload?: DeployablePayloadOrAddress<Payload>,
+  ) {
+    if (typeof payload === 'string') {
+      super(config, payload as Address);
+    } else {
+      super(config, undefined);
+      this._payload = payload as Payload;
+    }
+    if (account) this._account = account;
+  }
+
+  /**
+   * Returns the attached deployable payload, if it exists
+   *
+   * @readonly
+   * @type {Payload}
+   */
+  get payload() {
+    return this._payload;
+  }
+
+  /**
+   * Attaches a new payload for use with this deployable's initialization
+   *
+   * @public
+   * @param {Payload} payload
+   * @returns {this}
+   */
+  public withPayload(payload: Payload) {
+    this._payload = payload;
+    return this;
+  }
+
+  /**
+   * High level deployment function to deploy and await the contract address.
+   * This is mainly a convenience method to easily deploy a contract, but will not initialize a `Cloneable`,
+   * which makes it useless for Boost components.
+   * Obviously you can ignore the TS warnings and use this, but you shouldn't in most all cases.
+   *
+   * @public
+   * @async
+   * @param {?Payload} [_payload]
+   * @param {?DeployableOptions} [_options]
+   * @param {?Omit<WaitForTransactionReceiptParameters, 'hash'>} [waitParams] - See [viem.WaitForTransactionReceipt](https://v1.viem.sh/docs/actions/public/waitForTransactionReceipt.html#waitfortransactionreceipt)
+   * @returns {Promise<this>}
+   */
+  protected async deploy(
+    _payload?: Payload,
+    _options?: DeployableOptions,
+    waitParams?: Omit<WaitForTransactionReceiptParameters, 'hash'>,
+  ) {
+    const config = _options?.config || this._config;
+    const address = await getDeployedContractAddress(
+      config,
+      this.deployRaw(_payload, _options),
+      waitParams,
+    );
+    this._address = address;
+    return this;
+  }
+
+  /**
+   * The lower level contract deployment function that does not await for the transaction receipt.
+   * This is mainly a convenience method to easily deploy a contract, but will not initialize a `Cloneable`,
+   * which makes it useless for Boost components.
+   * Obviously you can ignore the TS warnings and use this, but you shouldn't in most all cases.
+   *
+   * @public
+   * @async
+   * @param {?Payload} [_payload]
+   * @param {?DeployableOptions} [_options]
+   * @returns {Promise<Hash>}
+   * @throws {@link DeployableAlreadyDeployedError}
+   * @throws {@link DeployableWagmiConfigurationRequiredError}
+   * @throws {@link DeployableMissingPayloadError}
+   */
+  protected async deployRaw(
+    _payload?: Payload,
+    _options?: DeployableOptions,
+  ): Promise<Hash> {
+    if (this.address) throw new DeployableAlreadyDeployedError(this.address);
+    const [payload, options] = this.validateDeploymentConfig(
+      _payload,
+      _options,
+    );
+    return await deployContract(options.config, {
+      ...this.buildParameters(payload),
+      ...this.optionallyAttachAccount(options.account),
+    });
+  }
+
+  /**
+   * Internal function to attach the connected account to write methods to avoid manually passing in an account each call.
+   *
+   * @protected
+   * @param {?Account} [account]
+   * @returns {({ account: Account; } | { account?: undefined; })}
+   */
+  protected optionallyAttachAccount(account?: Account) {
+    if (account) return { account };
+    return this._account ? { account: this._account } : {};
+  }
+
+  /**
+   * Base parameter constructor, should return a partial `viem.deployContract` parameters shape including abi, bytecode, and arguments, if any.
+   * Expected to be overridden by protocol contracts.
+   *
+   * @public
+   * @param {?Payload} [_payload]
+   * @param {?DeployableOptions} [_options]
+   * @returns {GenericDeployableParams}
+   */
+  public buildParameters(
+    _payload?: Payload,
+    _options?: DeployableOptions,
+  ): GenericDeployableParams {
+    throw new DeployableBuildParametersUnspecifiedError();
+  }
+
+  /**
+   * Internal method used to ensure that a Wagmi configuration and payload are always present when deploying.
+   *
+   * @protected
+   * @template [P=Payload]
+   * @param {?P} [_payload]
+   * @param {?DeployableOptions} [_options]
+   * @returns {[P, DeployableOptions]}
+   * @throws {@link DeployableWagmiConfigurationRequiredError}
+   * @throws {@link DeployableMissingPayloadError}
+   */
+  protected validateDeploymentConfig<P = Payload>(
+    _payload?: P,
+    _options?: DeployableOptions,
+  ) {
+    const options = _options || {
+      config: this._config,
+      account: this._account,
+    };
+    if (!options) throw new DeployableWagmiConfigurationRequiredError();
+    const payload = _payload || this._payload;
+    return [payload, options] as [P, DeployableOptions];
+  }
+}

package/src/Deployable/DeployableTarget.ts

@@ -0,0 +1,234 @@
+import {
+  type aCloneableAbi,
+  readACloneableGetComponentInterface,
+  readACloneableSupportsInterface,
+} from '@boostxyz/evm';
+import { deployContract } from '@wagmi/core';
+import {
+  type Abi,
+  type Address,
+  type Hash,
+  type Hex,
+  type WaitForTransactionReceiptParameters,
+  isAddress,
+  isAddressEqual,
+  zeroAddress,
+} from 'viem';
+import {
+  DeployableAlreadyDeployedError,
+  DeployableMissingPayloadError,
+} from '../errors';
+import { type ReadParams, RegistryType } from '../utils';
+import {
+  Deployable,
+  type DeployableOptions,
+  type DeployablePayloadOrAddress,
+} from './Deployable';
+
+/**
+ * A base class representing a generic base Boost Protocol target contract, extended by Actions, AllowLists, Budgets, Incentives, and Validators.
+ *
+ * @export
+ * @class DeployableTarget
+ * @typedef {DeployableTarget}
+ * @template [Payload=unknown]
+ * @extends {Deployable<Payload>}
+ */
+export class DeployableTarget<
+  Payload,
+  ContractAbi extends Abi,
+> extends Deployable<Payload, ContractAbi> {
+  /**
+   * A static property representing a map of stringified chain ID's to the address of the base implementation on chain, used when cloning base contracts.
+   *
+   * @static
+   * @readonly
+   * @type {Record<string, Address>}
+   */
+  static readonly bases: Record<number, Address> = {};
+  /**
+   * The target's registry type.
+   *
+   * @static
+   * @readonly
+   * @type {RegistryType}
+   */
+  static readonly registryType: RegistryType = RegistryType.ACTION;
+  /**
+   * A property asserting that the protocol should eiher clone and initialize a new target from the base implementation, or re-use an existing contract without initializing.
+   *
+   * @readonly
+   * @type {boolean}
+   */
+  readonly _isBase: boolean = true;
+  public get isBase() {
+    if (
+      !!this.address &&
+      Object.values(this.bases).some((base) =>
+        // biome-ignore lint/style/noNonNullAssertion: won't evaluate this if address checked and defined above
+        isAddressEqual(this.address!, base),
+      )
+    )
+      return true;
+    return this._isBase;
+  }
+
+  /**
+   * Creates an instance of DeployableTarget.
+   *
+   * @constructor
+   * @param {DeployableOptions} options
+   * @param {DeployablePayloadOrAddress<Payload>} payload - Either a given implementation's initialization payload, or an address to an existing on chain target.
+   * @param {?boolean} [isBase] - A property asserting that the protocol should eiher clone and initialize a new target from the base implementation, or re-use an existing contract without initializing.
+   */
+  constructor(
+    options: DeployableOptions,
+    payload?: DeployablePayloadOrAddress<Payload>,
+    isBase?: boolean,
+  ) {
+    super(options, payload);
+    // if supplying a custom address, safe enough to assume it is not a base address which makes reusing contracts like budgets easier
+    if (
+      typeof payload === 'string' &&
+      isAddress(payload) &&
+      payload !== zeroAddress &&
+      !Object.values(this.bases).some((base) => {
+        if (!payload || !base) return false;
+        return isAddressEqual(payload, base);
+      })
+    )
+      isBase = false;
+    if (isBase !== undefined) this._isBase = isBase;
+  }
+
+  /**
+   * A getter that will return the base implementation's static addresses by numerical chain ID
+   *
+   * @public
+   * @readonly
+   * @type {Record<number, Address>}
+   */
+  public get bases(): Record<number, Address> {
+    return (this.constructor as typeof DeployableTarget).bases;
+  }
+
+  /**
+   * A getter that returns the registry type of the base implementation
+   *
+   * @public
+   * @readonly
+   * @type {RegistryType}
+   */
+  public get registryType(): RegistryType {
+    return (this.constructor as typeof DeployableTarget).registryType;
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @async
+   * @param {?Payload} [payload]
+   * @param {?DeployableOptions} [options]
+   * @param {?Omit<WaitForTransactionReceiptParameters, 'hash'>} [waitParams]
+   * @returns {Promise<this>}
+   */
+  protected override async deploy(
+    payload?: Payload,
+    options?: DeployableOptions,
+    waitParams?: Omit<WaitForTransactionReceiptParameters, 'hash'>,
+  ) {
+    await super.deploy(payload, options, waitParams);
+    this.assertValidAddress();
+    return this;
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @async
+   * @param {?Payload} [_payload]
+   * @param {?DeployableOptions} [_options]
+   * @returns {Promise<Hash>}
+   */
+  protected override async deployRaw(
+    _payload?: Payload,
+    _options?: DeployableOptions,
+  ): Promise<Hash> {
+    if (this.address) throw new DeployableAlreadyDeployedError(this.address);
+    const payload = _payload || this._payload;
+    const config = _options?.config || this._config;
+    const { args, ...deployment } = this.buildParameters(payload);
+    return await deployContract(config, {
+      ...deployment,
+      ...this.optionallyAttachAccount(_options?.account),
+      // Deployable targets don't construct with arguments, they initialize with encoded payloads
+      args: [],
+    });
+  }
+
+  /**
+   * Check if the contract supports the given interface
+   *
+   * @public
+   * @async
+   * @param {Hex} interfaceId - The interface identifier
+   * @param {?ReadParams} [params]
+   * @returns {Promise<boolean>} - True if the contract supports the interface
+   */
+  public async supportsInterface(
+    interfaceId: Hex,
+    params?: ReadParams<typeof aCloneableAbi, 'supportsInterface'>,
+  ) {
+    return await readACloneableSupportsInterface(this._config, {
+      address: this.assertValidAddress(),
+      ...this.optionallyAttachAccount(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+      args: [interfaceId],
+    });
+  }
+
+  /**
+   *  Return a cloneable's unique identifier for downstream consumers to differentiate various targets
+   *  All implementations must override this function
+   *
+   * @public
+   * @async
+   * @param {?ReadParams} [params]
+   * @returns {Promise<Hex>}
+   */
+  public async getComponentInterface(
+    params?: ReadParams<typeof aCloneableAbi, 'getComponentInterface'>,
+  ) {
+    return await readACloneableGetComponentInterface(this._config, {
+      address: this.assertValidAddress(),
+      ...this.optionallyAttachAccount(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+      args: [],
+    });
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * @protected
+   * @template [P=Payload]
+   * @param {?P} [_payload]
+   * @param {?DeployableOptions} [_options]
+   * @returns {[P, DeployableOptions]}
+   */
+  protected override validateDeploymentConfig<P = Payload>(
+    _payload?: P,
+    _options?: DeployableOptions,
+  ) {
+    const payload = _payload || this._payload;
+    if (!payload) throw new DeployableMissingPayloadError();
+    return super.validateDeploymentConfig(payload, _options) as [
+      P,
+      DeployableOptions,
+    ];
+  }
+}