@boostxyz/sdk 0.0.0-alpha.10

package/src/Incentives/ERC20Incentive.ts

@@ -0,0 +1,482 @@
+import {
+  erc20IncentiveAbi,
+  readErc20IncentiveAsset,
+  readErc20IncentiveClaimed,
+  readErc20IncentiveClaims,
+  readErc20IncentiveCurrentReward,
+  readErc20IncentiveEntries,
+  readErc20IncentiveIsClaimable,
+  readErc20IncentiveLimit,
+  readErc20IncentiveOwner,
+  readErc20IncentiveReward,
+  readErc20IncentiveStrategy,
+  simulateErc20IncentiveClaim,
+  simulateErc20IncentiveClawback,
+  simulateErc20IncentiveDrawRaffle,
+  writeErc20IncentiveClaim,
+  writeErc20IncentiveClawback,
+  writeErc20IncentiveDrawRaffle,
+} from '@boostxyz/evm';
+import { bytecode } from '@boostxyz/evm/artifacts/contracts/incentives/ERC20Incentive.sol/ERC20Incentive.json';
+import {
+  type Address,
+  type ContractEventName,
+  type Hex,
+  encodeAbiParameters,
+} from 'viem';
+import type {
+  DeployableOptions,
+  GenericDeployableParams,
+} from '../Deployable/Deployable';
+import { DeployableTarget } from '../Deployable/DeployableTarget';
+import {
+  type ClaimPayload,
+  type StrategyType,
+  prepareClaimPayload,
+} from '../claiming';
+import {
+  type GenericLog,
+  type ReadParams,
+  RegistryType,
+  type WriteParams,
+} from '../utils';
+
+export { erc20IncentiveAbi };
+
+/**
+ * The object representation of a `ERC20Incentive.InitPayload`
+ *
+ * @export
+ * @interface ERC20IncentivePayload
+ * @typedef {ERC20IncentivePayload}
+ */
+export interface ERC20IncentivePayload {
+  /**
+   * The address of the incentivized asset.
+   *
+   * @type {Address}
+   */
+  asset: Address;
+  /**
+   * The type of disbursement strategy for the incentive. `StrategyType.MINT` is not supported for `ERC20Incentives`
+   *
+   * @type {StrategyType}
+   */
+  strategy: StrategyType;
+  /**
+   * The amount of the asset to distribute.
+   *
+   * @type {bigint}
+   */
+  reward: bigint;
+  /**
+   * How many times can this incentive be claimed.
+   *
+   * @type {bigint}
+   */
+  limit: bigint;
+}
+
+/**
+ * A generic `viem.Log` event with support for `ERC20Incentive` event types.
+ *
+ * @export
+ * @typedef {ERC20IncentiveLog}
+ * @template {ContractEventName<typeof erc20IncentiveAbi>} [event=ContractEventName<
+ *     typeof erc20IncentiveAbi
+ *   >]
+ */
+export type ERC20IncentiveLog<
+  event extends ContractEventName<typeof erc20IncentiveAbi> = ContractEventName<
+    typeof erc20IncentiveAbi
+  >,
+> = GenericLog<typeof erc20IncentiveAbi, event>;
+
+/**
+ * A simple ERC20 incentive implementation that allows claiming of tokens
+ *
+ * @export
+ * @class ERC20Incentive
+ * @typedef {ERC20Incentive}
+ * @extends {DeployableTarget<ERC20IncentivePayload>}
+ */
+export class ERC20Incentive extends DeployableTarget<
+  ERC20IncentivePayload,
+  typeof erc20IncentiveAbi
+> {
+  public override readonly abi = erc20IncentiveAbi;
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @static
+   * @type {Address}
+   */
+  public static override base: Address = import.meta.env
+    .VITE_ERC20_INCENTIVE_BASE;
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @static
+   * @type {RegistryType}
+   */
+  public static override registryType: RegistryType = RegistryType.INCENTIVE;
+
+  /**
+   * The owner of the incentive
+   *
+   * @public
+   * @async
+   * @param {?ReadParams<typeof erc20IncentiveAbi, 'owner'>} [params]
+   * @returns {unknown}
+   */
+  public async owner(params?: ReadParams<typeof erc20IncentiveAbi, 'owner'>) {
+    return await readErc20IncentiveOwner(this._config, {
+      address: this.assertValidAddress(),
+      args: [],
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * Calculates the current reward based on the time since the last claim. The reward is calculated based on the time since the last claim, the available budget, and the reward parameters. It increases linearly over time in the absence of claims, with each hour adding `rewardBoost` to the current reward, up to the available budget. For example, if there is one claim in the first hour, then no claims for three hours, the claimable reward would be `initialReward - rewardDecay + (rewardBoost * 3)`
+   *
+   * @public
+   * @async
+   * @param {?ReadParams<typeof erc20IncentiveAbi, 'currentReward'>} [params]
+   * @returns {Promise<bigint>} - The current reward
+   */
+  public async currentReward(
+    params?: ReadParams<typeof erc20IncentiveAbi, 'currentReward'>,
+  ) {
+    return await readErc20IncentiveCurrentReward(this._config, {
+      address: this.assertValidAddress(),
+      args: [],
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * The number of claims that have been made
+   *
+   * @public
+   * @async
+   * @param {?ReadParams<typeof erc20IncentiveAbi, 'claims'>} [params]
+   * @returns {Promise<bigint>}
+   */
+  public async claims(params?: ReadParams<typeof erc20IncentiveAbi, 'claims'>) {
+    return await readErc20IncentiveClaims(this._config, {
+      address: this.assertValidAddress(),
+      args: [],
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * A mapping of address to claim status
+   *
+   * @public
+   * @async
+   * @param {Address} address
+   * @param {?ReadParams<typeof erc20IncentiveAbi, 'claimed'>} [params]
+   * @returns {Promise<boolean>}
+   */
+  public async claimed(
+    address: Address,
+    params?: ReadParams<typeof erc20IncentiveAbi, 'claimed'>,
+  ) {
+    return await readErc20IncentiveClaimed(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
+      ...(params as any),
+    });
+  }
+
+  /**
+   * The address of the ERC20-like token
+   *
+   * @public
+   * @async
+   * @param {?ReadParams<typeof erc20IncentiveAbi, 'asset'>} [params]
+   * @returns {Promise<Address>}
+   */
+  public async asset(params?: ReadParams<typeof erc20IncentiveAbi, 'asset'>) {
+    return await readErc20IncentiveAsset(this._config, {
+      address: this.assertValidAddress(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * The strategy for the incentive (MINT or POOL)
+   *
+   * @public
+   * @async
+   * @param {?ReadParams<typeof erc20IncentiveAbi, 'strategy'>} [params]
+   * @returns {Promise<StrategyType>}
+   */
+  public strategy(
+    params?: ReadParams<typeof erc20IncentiveAbi, 'strategy'>,
+  ): Promise<StrategyType> {
+    return readErc20IncentiveStrategy(this._config, {
+      address: this.assertValidAddress(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    }) as Promise<StrategyType>;
+  }
+
+  /**
+   * The reward amount issued for each claim
+   *
+   * @public
+   * @async
+   * @param {?ReadParams<typeof erc20IncentiveAbi, 'reward'>} [params]
+   * @returns {Promise<bigint>}
+   */
+  public async reward(params?: ReadParams<typeof erc20IncentiveAbi, 'reward'>) {
+    return await readErc20IncentiveReward(this._config, {
+      address: this.assertValidAddress(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * The limit (max claims, or max entries for raffles)
+   *
+   * @public
+   * @async
+   * @param {?ReadParams<typeof erc20IncentiveAbi, 'limit'>} [params]
+   * @returns {unknown}
+   */
+  public async limit(params?: ReadParams<typeof erc20IncentiveAbi, 'limit'>) {
+    return await readErc20IncentiveLimit(this._config, {
+      address: this.assertValidAddress(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * The set of addresses that have claimed a slot in the incentive raffle, accessed by bigint index.
+   *
+   * @public
+   * @async
+   * @param {bigint} i - Index of address
+   * @param {?ReadParams<typeof erc20IncentiveAbi, 'entries'>} [params]
+   * @returns {Promise<Address>}
+   */
+  public async entries(
+    i: bigint,
+    params?: ReadParams<typeof erc20IncentiveAbi, 'entries'>,
+  ) {
+    return await readErc20IncentiveEntries(this._config, {
+      address: this.assertValidAddress(),
+      args: [i],
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * Claim the incentive
+   *
+   * @public
+   * @async
+   * @param {ClaimPayload} payload
+   * @param {?WriteParams<typeof erc20IncentiveAbi, 'claim'>} [params]
+   * @returns {Promise<boolean>} - Returns true if successfully claimed
+   */
+  protected async claim(
+    payload: ClaimPayload,
+    params?: WriteParams<typeof erc20IncentiveAbi, 'claim'>,
+  ) {
+    return await this.awaitResult(this.claimRaw(payload, params));
+  }
+
+  /**
+   * Claim the incentive
+   *
+   * @public
+   * @async
+   * @param {ClaimPayload} payload
+   * @param {?WriteParams<typeof erc20IncentiveAbi, 'claim'>} [params]
+   * @returns {Promise<boolean>} - Returns true if successfully claimed
+   */
+  protected async claimRaw(
+    payload: ClaimPayload,
+    params?: WriteParams<typeof erc20IncentiveAbi, 'claim'>,
+  ) {
+    const { request, result } = await simulateErc20IncentiveClaim(
+      this._config,
+      {
+        address: this.assertValidAddress(),
+        args: [prepareClaimPayload(payload)],
+        ...this.optionallyAttachAccount(),
+        // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+        ...(params as any),
+      },
+    );
+    const hash = await writeErc20IncentiveClaim(this._config, request);
+    return { hash, result };
+  }
+
+  /**
+   * Clawback assets from the incentive
+   *
+   * @public
+   * @async
+   * @param {ClaimPayload} payload
+   * @param {?WriteParams<typeof erc20IncentiveAbi, 'clawback'>} [params]
+   * @returns {Promise<boolean>} -  True if the assets were successfully clawbacked
+   */
+  public async clawback(
+    payload: ClaimPayload,
+    params?: WriteParams<typeof erc20IncentiveAbi, 'clawback'>,
+  ) {
+    return await this.awaitResult(this.clawbackRaw(payload, params));
+  }
+
+  /**
+   * Clawback assets from the incentive
+   *
+   * @public
+   * @async
+   * @param {ClaimPayload} payload
+   * @param {?WriteParams<typeof erc20IncentiveAbi, 'clawback'>} [params]
+   * @returns {Promise<boolean>} -  True if the assets were successfully clawbacked
+   */
+  public async clawbackRaw(
+    payload: ClaimPayload,
+    params?: WriteParams<typeof erc20IncentiveAbi, 'clawback'>,
+  ) {
+    const { request, result } = await simulateErc20IncentiveClawback(
+      this._config,
+      {
+        address: this.assertValidAddress(),
+        args: [prepareClaimPayload(payload)],
+        ...this.optionallyAttachAccount(),
+        // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+        ...(params as any),
+      },
+    );
+    const hash = await writeErc20IncentiveClawback(this._config, request);
+    return { hash, result };
+  }
+
+  /**
+   * Check if an incentive is claimable. For the POOL strategy, the `bytes data` portion of the payload ignored. The recipient must not have already claimed the incentive.
+   *
+   * @public
+   * @async
+   * @param {ClaimPayload} payload
+   * @param {?ReadParams<typeof erc20IncentiveAbi, 'isClaimable'>} [params]
+   * @returns {unknown} = True if the incentive is claimable based on the data payload
+   */
+  public async isClaimable(
+    payload: ClaimPayload,
+    params?: ReadParams<typeof erc20IncentiveAbi, 'isClaimable'>,
+  ) {
+    return await readErc20IncentiveIsClaimable(this._config, {
+      address: this.assertValidAddress(),
+      args: [prepareClaimPayload(payload)],
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * Draw a winner from the raffle. Only callable by owner. Only valid when the strategy is set to `Strategy.RAFFLE`
+   *
+   * @public
+   * @async
+   * @param {?WriteParams<typeof erc20IncentiveAbi, 'drawRaffle'>} [params]
+   * @returns {Promise<void>}
+   */
+  public async drawRaffle(
+    params?: WriteParams<typeof erc20IncentiveAbi, 'drawRaffle'>,
+  ) {
+    return await this.awaitResult(this.drawRaffleRaw(params));
+  }
+
+  /**
+   * Draw a winner from the raffle. Only callable by owner. Only valid when the strategy is set to `Strategy.RAFFLE`
+   *
+   * @public
+   * @async
+   * @param {?WriteParams<typeof erc20IncentiveAbi, 'drawRaffle'>} [params]
+   * @returns {Promise<void>}
+   */
+  public async drawRaffleRaw(
+    params?: WriteParams<typeof erc20IncentiveAbi, 'drawRaffle'>,
+  ) {
+    const { request, result } = await simulateErc20IncentiveDrawRaffle(
+      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),
+      },
+    );
+    const hash = await writeErc20IncentiveDrawRaffle(this._config, request);
+    return { hash, result };
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @param {?ERC20IncentivePayload} [_payload]
+   * @param {?DeployableOptions} [_options]
+   * @returns {GenericDeployableParams}
+   */
+  public override buildParameters(
+    _payload?: ERC20IncentivePayload,
+    _options?: DeployableOptions,
+  ): GenericDeployableParams {
+    const [payload, options] = this.validateDeploymentConfig(
+      _payload,
+      _options,
+    );
+    return {
+      abi: erc20IncentiveAbi,
+      bytecode: bytecode as Hex,
+      args: [prepareERC20IncentivePayload(payload)],
+      ...this.optionallyAttachAccount(options.account),
+    };
+  }
+}
+
+/**
+ * Given a {@link ERC20IncentivePayload}, properly encode a `ERC20Incentive.InitPayload` for use with {@link ERC20Incentive} initialization.
+ *
+ * @param {ERC20IncentivePayload} param0
+ * @param {Address} param0.asset - The address of the incentivized asset.
+ * @param {StrategyType} param0.strategy - The type of disbursement strategy for the incentive. `StrategyType.MINT` is not supported for `ERC20Incentives`
+ * @param {bigint} param0.reward - The amount of the asset to distribute.
+ * @param {bigint} param0.limit - How many times can this incentive be claimed.
+ * @returns {*}
+ */
+export function prepareERC20IncentivePayload({
+  asset,
+  strategy,
+  reward,
+  limit,
+}: ERC20IncentivePayload) {
+  return encodeAbiParameters(
+    [
+      { type: 'address', name: 'asset' },
+      { type: 'uint8', name: 'strategy' },
+      { type: 'uint256', name: 'reward' },
+      { type: 'uint256', name: 'limit' },
+    ],
+    [asset, strategy, reward, limit],
+  );
+}

package/src/Incentives/ERC20VariableIncentive.test.ts

@@ -0,0 +1,136 @@
+import { readMockErc20BalanceOf } from '@boostxyz/evm';
+import { loadFixture } from '@nomicfoundation/hardhat-network-helpers';
+import { encodeAbiParameters, isAddress, parseEther, zeroAddress } from 'viem';
+import { beforeAll, beforeEach, describe, expect, test } from 'vitest';
+import { accounts } from '../../test/accounts';
+import {
+  type BudgetFixtures,
+  type Fixtures,
+  defaultOptions,
+  deployFixtures,
+  freshBoost,
+  fundBudget,
+} from '../../test/helpers';
+import { ERC20VariableIncentive } from './ERC20VariableIncentive';
+
+const BOOST_CORE_CLAIM_FEE = parseEther('0.000075');
+
+let fixtures: Fixtures, budgets: BudgetFixtures;
+
+describe('ERC20VariableIncentive', () => {
+  beforeAll(async () => {
+    fixtures = await loadFixture(deployFixtures);
+  });
+
+  beforeEach(async () => {
+    budgets = await loadFixture(fundBudget(defaultOptions, fixtures));
+  });
+
+  test('can successfully be deployed', async () => {
+    const action = new ERC20VariableIncentive(defaultOptions, {
+      asset: zeroAddress,
+      reward: 1n,
+      limit: 1n,
+    });
+    await action.deploy();
+    expect(isAddress(action.assertValidAddress())).toBe(true);
+  });
+
+  test('can claim', async () => {
+    // biome-ignore lint/style/noNonNullAssertion: we know this is defined
+    const referrer = accounts.at(1)!.account!,
+      // biome-ignore lint/style/noNonNullAssertion: we know this is defined
+      trustedSigner = accounts.at(0)!;
+    const erc20VariableIncentive = new fixtures.bases.ERC20VariableIncentive(
+      defaultOptions,
+      {
+        asset: budgets.erc20.assertValidAddress(),
+        reward: 1n,
+        limit: 1n,
+      },
+    );
+    const boost = await freshBoost(fixtures, {
+      budget: budgets.budget,
+      incentives: [erc20VariableIncentive],
+    });
+
+    const claimant = trustedSigner.account;
+    const incentiveQuantity = 1;
+    const claimDataPayload = await boost.validator.encodeClaimData({
+      signer: trustedSigner,
+      incentiveData: encodeAbiParameters(
+        [{ name: '', type: 'uint256' }],
+        [parseEther('1')],
+      ),
+      chainId: defaultOptions.config.chains[0].id,
+      incentiveQuantity,
+      claimant,
+      boostId: boost.id,
+    });
+    await fixtures.core.claimIncentive(
+      boost.id,
+      0n,
+      referrer,
+      claimDataPayload,
+      { value: BOOST_CORE_CLAIM_FEE },
+    );
+    expect(
+      await readMockErc20BalanceOf(defaultOptions.config, {
+        address: budgets.erc20.assertValidAddress(),
+        args: [claimant],
+      }),
+    ).toBe(1n);
+  });
+
+  test('cannot claim twice', async () => {
+    // biome-ignore lint/style/noNonNullAssertion: we know this is defined
+    const referrer = accounts.at(1)!.account!;
+    // biome-ignore lint/style/noNonNullAssertion: we know this is defined
+    const trustedSigner = accounts.at(0)!;
+    const erc20VariableIncentive = new fixtures.bases.ERC20VariableIncentive(
+      defaultOptions,
+      {
+        asset: budgets.erc20.assertValidAddress(),
+        reward: 1n,
+        limit: 1n,
+      },
+    );
+    const boost = await freshBoost(fixtures, {
+      budget: budgets.budget,
+      incentives: [erc20VariableIncentive],
+    });
+
+    const claimant = trustedSigner.account;
+    const incentiveQuantity = 1;
+    const claimDataPayload = await boost.validator.encodeClaimData({
+      signer: trustedSigner,
+      incentiveData: encodeAbiParameters(
+        [{ name: '', type: 'uint256' }],
+        [parseEther('1')],
+      ),
+      chainId: defaultOptions.config.chains[0].id,
+      incentiveQuantity,
+      claimant,
+      boostId: boost.id,
+    });
+
+    await fixtures.core.claimIncentive(
+      boost.id,
+      0n,
+      referrer,
+      claimDataPayload,
+      { value: BOOST_CORE_CLAIM_FEE },
+    );
+    try {
+      await fixtures.core.claimIncentive(
+        boost.id,
+        0n,
+        referrer,
+        claimDataPayload,
+        { value: BOOST_CORE_CLAIM_FEE },
+      );
+    } catch (e) {
+      expect(e).toBeInstanceOf(Error);
+    }
+  });
+});