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

package/src/Validators/SignerValidator.ts

@@ -10,7 +10,15 @@ import {
   writeSignerValidatorValidate,
 } from '@boostxyz/evm';
 import { bytecode } from '@boostxyz/evm/artifacts/contracts/validators/SignerValidator.sol/SignerValidator.json';
-import type { Address, ContractEventName, Hex } from 'viem';
+import {
+  type Address,
+  type ContractEventName,
+  type Hex,
+  type PrivateKeyAccount,
+  encodeAbiParameters,
+} from 'viem';
+import { signTypedData } from 'viem/accounts';
+import { SignerValidator as SignerValidatorBases } from '../../dist/deployments.json';
 import type {
   DeployableOptions,
   GenericDeployableParams,
@@ -20,15 +28,244 @@ import {
   type GenericLog,
   type ReadParams,
   RegistryType,
-  type SignerValidatorPayload,
-  type SignerValidatorSignaturePayload,
-  type SignerValidatorValidatePayload,
   type WriteParams,
-  prepareSignerValidatorPayload,
 } from '../utils';
 
 export { signerValidatorAbi };
-export type { SignerValidatorPayload };
+
+/**
+ * Object reprentation of a {@link SignerValidator} initialization payload
+ *
+ * @export
+ * @interface SignerValidatorPayload
+ * @typedef {SignerValidatorPayload}
+ */
+export interface SignerValidatorPayload {
+  /**
+   * The list of authorized signers. The first address in the list will be the initial owner of the contract.
+   *
+   * @type {Address[]}
+   */
+  signers: Address[];
+  /**
+   * The authorized caller of the {@link prepareSignerValidator} function
+   * @type {Address}
+   */
+  validatorCaller: Address;
+}
+
+/**
+ * Description placeholder
+ *
+ * @export
+ * @interface SignerValidatorValidatePayload
+ * @typedef {SignerValidatorValidatePayload}
+ */
+export interface SignerValidatorValidatePayload {
+  /**
+   * The ID of the boost.
+   *
+   * @type {bigint}
+   */
+  boostId: bigint;
+  /**
+   * The ID of the incentive.
+   *
+   * @type {bigint}
+   */
+  incentiveId: bigint;
+  /**
+   * The address of the claimant.
+   *
+   * @type {Address}
+   */
+  claimant: Address;
+  /**
+   * The claim data.
+   *
+   * @type {Hex}
+   */
+  claimData: Hex;
+}
+
+/**
+ * Object reprentation of a {@link SignerValidator} initialization payload
+ *
+ * @export
+ * @interface SignerValidatorPayload
+ * @typedef {SignerValidatorPayload}
+ */
+export interface SignerValidatorPayload {
+  /**
+   * The list of authorized signers. The first address in the list will be the initial owner of the contract.
+   *
+   * @type {Address[]}
+   */
+  signers: Address[];
+  /**
+   * The authorized caller of the {@link prepareSignerValidator} function
+   * @type {Address}
+   */
+  validatorCaller: Address;
+}
+
+/**
+ * Description placeholder
+ *
+ * @export
+ * @interface SignerValidatorValidatePayload
+ * @typedef {SignerValidatorValidatePayload}
+ */
+export interface SignerValidatorValidatePayload {
+  /**
+   * The ID of the boost.
+   *
+   * @type {bigint}
+   */
+  boostId: bigint;
+  /**
+   * The ID of the incentive.
+   *
+   * @type {bigint}
+   */
+  incentiveId: bigint;
+  /**
+   * The address of the claimant.
+   *
+   * @type {Address}
+   */
+  claimant: Address;
+  /**
+   * The claim data.
+   *
+   * @type {Hex}
+   */
+  claimData: Hex;
+}
+
+/**
+ * Signer Validator Claim Data Payload
+ *
+ * @export
+ * @interface SignerValidatorClaimDataParams
+ * @typedef {SignerValidatorClaimDataParams}
+ */
+export interface SignerValidatorClaimDataParams {
+  /**
+   * The signer with which to sign the input
+   *
+   * @type {{
+   *     account: Address;
+   *     key: Hex;
+   *     privateKey: PrivateKeyAccount;
+   *   }}
+   */
+  signer: {
+    account: Address;
+    key: Hex;
+    privateKey: PrivateKeyAccount;
+  };
+  /**
+   * The encoded data to provide the underlying incentive. You can use {@link prepareAllowListIncentivePayload}, {@link prepareCGDAIncentivePayload}, {@link prepareERC20IncentivePayload}, {@link prepareERC1155IncentivePayload}, or {@link preparePointsIncentivePayload}
+   *
+   * @type {Hex}
+   */
+  incentiveData: Hex;
+  /**
+   * The chain id to target
+   *
+   * @type {number}
+   */
+  chainId: number;
+  /**
+   * The address of the validator
+   *
+   * @type {Address}
+   */
+  validator: Address;
+  /**
+   * The incentive quantity.
+   *
+   * @type {number}
+   */
+  incentiveQuantity: number;
+  /**
+   * The address of the claimant
+   *
+   * @type {Address}
+   */
+  claimant: Address;
+  /**
+   * The ID of the boost
+   *
+   * @type {bigint}
+   */
+  boostId: bigint;
+}
+
+/**
+ * Object representation of a {@link SignerValidatorInputParams} initialization payload
+ *
+ * @export
+ * @interface SignerValidatorInputParams
+ * @typedef {SignerValidatorInputParams}
+ */
+export interface SignerValidatorInputParams {
+  /**
+   * The signer address.
+   *
+   * @type {Address}
+   */
+  signer: Address;
+
+  /**
+   * The signature data.
+   *
+   * @type {string}
+   */
+  signature: Hex;
+
+  /**
+   * The incentive quantity.
+   *
+   * @type {number}
+   */
+  incentiveQuantity: number;
+}
+
+/**
+ * Object representing the payload for signing before validaton.
+ *
+ * @export
+ * @interface SignerValidatorSignaturePayload
+ * @typedef {SignerValidatorSignaturePayload}
+ */
+export interface SignerValidatorSignaturePayload {
+  /**
+   * The ID of the boost.
+   *
+   * @type {bigint}
+   */
+  boostId: bigint;
+  /**
+   * The ID of the incentive.
+   *
+   * @type {number}
+   */
+  incentiveQuantity: number;
+  /**
+   * The address of the claimant.
+   *
+   * @type {Address}
+   */
+  claimant: Address;
+  /**
+   * The claim data.
+   *
+   * @type {Hex}
+   */
+  incentiveData: Hex;
+}
 
 /**
  * A generic `viem.Log` event with support for `BoostCore` event types.
@@ -57,16 +294,24 @@ export class SignerValidator extends DeployableTarget<
   SignerValidatorPayload,
   typeof signerValidatorAbi
 > {
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @readonly
+   * @type {*}
+   */
   public override readonly abi = signerValidatorAbi;
   /**
    * @inheritdoc
    *
    * @public
    * @static
-   * @type {Address}
+   * @type {Record<number, Address>}
    */
-  public static override base: Address = import.meta.env
-    .VITE_SIGNER_VALIDATOR_BASE;
+  public static override bases: Record<number, Address> = {
+    ...(SignerValidatorBases as Record<number, Address>),
+  };
   /**
    * @inheritdoc
    *
@@ -82,14 +327,14 @@ 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,
     params?: ReadParams<typeof signerValidatorAbi, 'signers'>,
   ) {
-    return readSignerValidatorSigners(this._config, {
+    return await readSignerValidatorSigners(this._config, {
       address: this.assertValidAddress(),
       args: [address],
       // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
@@ -103,14 +348,14 @@ 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,
     params?: ReadParams<typeof signerValidatorAbi, 'hashSignerData'>,
   ) {
-    return readSignerValidatorHashSignerData(this._config, {
+    return await readSignerValidatorHashSignerData(this._config, {
       address: this.assertValidAddress(),
       args: [
         payload.boostId,
@@ -129,14 +374,14 @@ 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
    */
-  public async validate(
+  protected async validate(
     payload: SignerValidatorValidatePayload,
     params?: WriteParams<typeof signerValidatorAbi, 'validate'>,
   ) {
-    return this.awaitResult(this.validateRaw(payload, params));
+    return await this.awaitResult(this.validateRaw(payload, params));
   }
 
   /**
@@ -145,10 +390,10 @@ 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
    */
-  public async validateRaw(
+  protected async validateRaw(
     payload: SignerValidatorValidatePayload,
     params?: ReadParams<typeof signerValidatorAbi, 'validate'>,
   ) {
@@ -178,15 +423,17 @@ 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[],
     allowed: boolean[],
     params?: WriteParams<typeof signerValidatorAbi, 'setAuthorized'>,
   ) {
-    return this.awaitResult(this.setAuthorizedRaw(addresses, allowed, params));
+    return await this.awaitResult(
+      this.setAuthorizedRaw(addresses, allowed, params),
+    );
   }
 
   /**
@@ -196,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[],
@@ -218,6 +465,15 @@ export class SignerValidator extends DeployableTarget<
     return { hash, result };
   }
 
+  /**
+   * Update the authorized caller of the validator function
+   *
+   * @public
+   * @async
+   * @param {Address} address
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: void; }>}
+   */
   public async setValidatorCallerRaw(
     address: Address,
     params?: WriteParams<typeof signerValidatorAbi, 'setValidatorCaller'>,
@@ -239,11 +495,37 @@ export class SignerValidator extends DeployableTarget<
     return { hash, result };
   }
 
+  /**
+   * Update the authorized caller of the validator function
+   *
+   * @public
+   * @async
+   * @param {Address} address
+   * @param {?WriteParams} [params]
+   * @returns {Promise<void>}
+   */
   public async setValidatorCaller(
     address: Address,
     params?: WriteParams<typeof signerValidatorAbi, 'setValidatorCaller'>,
   ) {
-    return this.awaitResult(this.setValidatorCallerRaw(address, params));
+    return await this.awaitResult(this.setValidatorCallerRaw(address, params));
+  }
+
+  /**
+   * Properly encodes the data needed to claim
+   *
+   * @public
+   * @async
+   * @param {SignerValidatorClaimDataParams} params
+   * @returns {Promise<Hex>}
+   */
+  public async encodeClaimData(
+    params: Omit<SignerValidatorClaimDataParams, 'validator'>,
+  ): Promise<Hex> {
+    return await prepareSignerValidatorClaimDataPayload({
+      ...params,
+      validator: this.assertValidAddress(),
+    });
   }
 
   /**
@@ -270,3 +552,132 @@ export class SignerValidator extends DeployableTarget<
     };
   }
 }
+
+/**
+ * Signer Validator Claim Data Payload Preparation
+ *
+ * @export
+ * @async
+ * @param {SignerValidatorClaimDataParams} param0
+ * @param {{ account: Address; key: Hex; privateKey: PrivateKeyAccount; }} param0.signer
+ * @param {Hex} param0.incentiveData
+ * @param {number} param0.chainId
+ * @param {Address} param0.validator
+ * @param {number} param0.incentiveQuantity
+ * @param {Address} param0.claimant
+ * @param {bigint} param0.boostId
+ * @returns {Promise<Hex>}
+ */
+export async function prepareSignerValidatorClaimDataPayload({
+  signer,
+  incentiveData,
+  chainId,
+  validator,
+  incentiveQuantity,
+  claimant,
+  boostId,
+}: SignerValidatorClaimDataParams): Promise<Hex> {
+  const domain = {
+    name: 'SignerValidator',
+    version: '1',
+    chainId: chainId,
+    verifyingContract: validator,
+  };
+  const typedData = {
+    domain,
+    types: {
+      SignerValidatorData: [
+        { name: 'boostId', type: 'uint256' },
+        { name: 'incentiveQuantity', type: 'uint8' },
+        { name: 'claimant', type: 'address' },
+        { name: 'incentiveData', type: 'bytes' },
+      ],
+    },
+    primaryType: 'SignerValidatorData' as const,
+    message: {
+      boostId,
+      incentiveQuantity,
+      claimant,
+      incentiveData: incentiveData,
+    },
+  };
+
+  const trustedSignature = await signTypedData({
+    ...typedData,
+    privateKey: signer.key,
+  });
+
+  // Prepare the claim data payload using the new helper
+  const validatorData = prepareSignerValidatorInputParams({
+    signer: signer.account,
+    signature: trustedSignature,
+    incentiveQuantity, // Adjust incentive quantity as necessary
+  });
+
+  const boostClaimDataPayload = encodeAbiParameters(
+    [
+      {
+        type: 'tuple',
+        name: 'BoostClaimData',
+        components: [
+          { type: 'bytes', name: 'validatorData' },
+          { type: 'bytes', name: 'incentiveData' },
+        ],
+      },
+    ],
+    [{ validatorData, incentiveData }],
+  );
+
+  return boostClaimDataPayload;
+}
+
+/**
+ * Given a {@link SignerValidatorInputParams}, properly encode the initialization payload.
+ *
+ * @param {SignerValidatorInputParams} param0
+ * @param {Address} param0.signer
+ * @param {Hex} param0.signature
+ * @param {number} param0.incentiveQuantity
+ * @returns {Hex}
+ */
+export function prepareSignerValidatorInputParams({
+  signer,
+  signature,
+  incentiveQuantity,
+}: SignerValidatorInputParams) {
+  return encodeAbiParameters(
+    [
+      {
+        type: 'tuple',
+        name: 'SignerValidatorInputParams',
+        components: [
+          { type: 'address', name: 'signer' },
+          { type: 'bytes', name: 'signature' },
+          { type: 'uint8', name: 'incentiveQuantity' },
+        ],
+      },
+    ],
+    [{ signer, signature, incentiveQuantity }],
+  );
+}
+
+/**
+ * Given a {@link SignerValidatorPayload}, properly encode the initialization payload.
+ *
+ * @param {SignerValidatorPayload} param0
+ * @param {Address[]} param0.signers
+ * @param {Address} param0.validatorCaller
+ * @returns {Hex}
+ */
+export function prepareSignerValidatorPayload({
+  signers,
+  validatorCaller,
+}: SignerValidatorPayload) {
+  return encodeAbiParameters(
+    [
+      { type: 'address[]', name: 'signers' },
+      { type: 'address', name: 'validatorCaller' },
+    ],
+    [signers, validatorCaller],
+  );
+}

package/src/Validators/Validator.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'vitest';
-import { defaultOptions } from '../../test/helpers';
-import { testAccount } from '../../test/viem';
+import { defaultOptions } from '@boostxyz/test/helpers';
+import { testAccount } from '@boostxyz/test/viem';
 import { SignerValidator } from './SignerValidator';
 import { validatorFromAddress } from './Validator';
 

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

@@ -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 {Hex}
+ */
+export const prepareClaimPayload = ({
+  target,
+  data = zeroHash,
+}: ClaimPayload) => {
+  return encodeAbiParameters(
+    [
+      { type: 'address', name: 'target' },
+      { type: 'bytes', name: 'data' },
+    ],
+    [target, data],
+  );
+};