@boostxyz/sdk 5.3.1 → 6.0.0

package/src/BoostCore.test.ts

@@ -765,8 +765,8 @@ describe("BoostCore", () => {
     await new Promise((resolve) => {
       setTimeout(resolve, 500);
     });
-
-    expect(subscription).toHaveBeenCalledTimes(1);
+    // This should be called once for each event
+    expect(subscription).toHaveBeenCalledTimes(2);
   });
 
   test("can set a passthrough auth scheme", async () => {
@@ -953,3 +953,125 @@ describe("BoostCore", () => {
     expect(feesInfo.asset.toLowerCase()).toBe(erc20.assertValidAddress());
   });
 });
+
+describe("Top-Up Incentives", () => {
+  let incentive: ReturnType<typeof fixtures.core.ERC20Incentive>;
+  let boostId: bigint;
+
+  beforeAll(async () => {
+    const { core } = fixtures;
+    const { budget, erc20 } = budgets;
+
+    incentive = core.ERC20Incentive({
+      asset: erc20.assertValidAddress(),
+      strategy: StrategyType.POOL,
+      reward: parseEther("1"),
+      limit: 5n,
+      manager: budget.assertValidAddress(),
+    });
+    await erc20.mint(defaultOptions.account.address, parseEther("110"));
+    await erc20.approve(budget.assertValidAddress(), parseEther("110"));
+    await budget.allocate({
+      amount: parseEther("110"),
+      asset: erc20.assertValidAddress(),
+      target: defaultOptions.account.address,
+    });
+    
+
+    const createdBoost = await core.createBoost({
+      protocolFee: 0n,
+      maxParticipants: 5n,
+      budget,
+      action: core.EventAction(
+        makeMockEventActionPayload(
+          core.assertValidAddress(),
+          erc20.assertValidAddress(),
+        ),
+      ),
+      validator: core.SignerValidator({
+        signers: [defaultOptions.account.address],
+        validatorCaller: defaultOptions.account.address,
+      }),
+      allowList: core.SimpleAllowList({
+        owner: defaultOptions.account.address,
+        allowed: [defaultOptions.account.address],
+      }),
+      incentives: [incentive],
+    });
+    boostId = createdBoost.id;
+  });
+
+  test("can top up from a budget (pre-fee)", async () => {
+    const { core } = fixtures;
+    const { budget, erc20 } = budgets;
+
+    console.log("budget", budget.assertValidAddress());
+
+    const netTopup = parseEther("5");
+
+    await core.topupIncentiveFromBudgetPreFee(boostId, 0n, netTopup, budget.assertValidAddress());
+    console.log("topup done");
+
+    expect(await incentive.limit()).toBe(5n + 5n); // original limit 5 + topup 5
+  });
+
+  test("can top up from a budget (post-fee)", async () => {
+    const { core } = fixtures;
+    const { budget } = budgets;
+
+    const total = parseEther("5.5");
+    await core.topupIncentiveFromBudgetPostFee(boostId, 0n, total, budget.assertValidAddress());
+
+    expect(await incentive.limit()).toBe(10n + 5n);
+  });
+
+  test("pre-fee and post-fee top-ups lead to the same net top-up", async () => {
+    const { core } = fixtures;
+    const { budget } = budgets;
+
+    const net = parseEther("2");
+    const netPlusFee = parseEther("2.2");
+
+    await core.topupIncentiveFromBudgetPreFee(boostId, 0n, net, budget.assertValidAddress());
+
+    await core.topupIncentiveFromBudgetPostFee(boostId, 0n, netPlusFee, budget.assertValidAddress());
+
+    expect(await incentive.limit()).toBe(15n + 4n);
+  });
+
+  test("can top up from sender (pre-fee)", async () => {
+    const { core } = fixtures;
+    const { erc20 } = budgets;
+
+    const netTopup = parseEther("10");
+    const netPlusFee = parseEther("11");
+    await erc20.mint(defaultOptions.account.address, netPlusFee);
+    await erc20.approve(core.assertValidAddress(), netPlusFee);
+
+    await core.topupIncentiveFromSenderPreFee(boostId, 0n, netTopup);
+
+    expect(await incentive.limit()).toBe(19n + 10n);
+  });
+
+  test("can top up from sender (post-fee)", async () => {
+    const { core } = fixtures;
+    const { erc20 } = budgets;
+
+    const totalWithFee = parseEther("5.5");
+    await erc20.mint(defaultOptions.account.address, totalWithFee);
+    await erc20.approve(core.assertValidAddress(), totalWithFee);
+
+    await core.topupIncentiveFromSenderPostFee(boostId, 0n, totalWithFee);
+
+    expect(await incentive.limit()).toBe(29n + 5n);
+  });
+
+  test("throws if net top-up is zero", async () => {
+    const { core } = fixtures;
+    const { budget } = budgets;
+
+    await expect(async () => {
+      await core.topupIncentiveFromBudgetPreFee(boostId, 0n, 0n, budget.assertValidAddress());
+    }).rejects.toThrowError();
+  });
+});

package/src/BoostCore.ts

@@ -12,11 +12,15 @@ import {
   simulateBoostCoreCreateBoost,
   simulateBoostCoreSetCreateBoostAuth,
   simulateBoostCoreSetProtocolFeeReceiver,
+  simulateBoostCoreTopupIncentiveFromBudget,
+  simulateBoostCoreTopupIncentiveFromSender,
   writeBoostCoreClaimIncentive,
   writeBoostCoreClaimIncentiveFor,
   writeBoostCoreCreateBoost,
   writeBoostCoreSetCreateBoostAuth,
   writeBoostCoreSetProtocolFeeReceiver,
+  writeBoostCoreTopupIncentiveFromBudget,
+  writeBoostCoreTopupIncentiveFromSender,
 } from '@boostxyz/evm';
 import { bytecode } from '@boostxyz/evm/artifacts/contracts/BoostCore.sol/BoostCore.json';
 import {
@@ -24,6 +28,7 @@ import {
   getAccount,
   getChains,
   getTransactionReceipt,
+  readContract,
   waitForTransactionReceipt,
 } from '@wagmi/core';
 import { createWriteContract } from '@wagmi/core/codegen';
@@ -31,6 +36,8 @@ import {
   type Address,
   type ContractEventName,
   type Hex,
+  decodeAbiParameters,
+  encodeAbiParameters,
   encodePacked,
   keccak256,
   parseEventLogs,
@@ -1654,4 +1661,224 @@ export class BoostCore extends Deployable<
       ...this.optionallyAttachAccount(options.account),
     };
   }
+  /**
+   * Prepares and executes a top-up from a Budget, specifying the net top-up amount
+   * that should land in the incentive (the protocol fee is added automatically).
+   *
+   * @public
+   * @async
+   * @param {bigint} boostId The ID of the Boost
+   * @param {bigint} incentiveId The ID of the incentive within that Boost
+   * @param {any} topupPayload A typed struct for the incentive’s top-up parameters
+   * @param {Address} [budget] Optional override budget address (otherwise uses the Boost’s budget)
+   * @param {?WriteParams} [params] Additional transaction overrides
+   * @returns {Promise<{ hash: Hex; result: void }>} The transaction hash and simulation result
+   */
+  public async topupIncentiveFromBudgetPreFee(
+    boostId: bigint,
+    incentiveId: bigint,
+    topupAmount: bigint,
+    budget?: Address,
+    params?: WriteParams,
+  ) {
+    const boost = await this.getBoost(boostId, params);
+    if (incentiveId >= boost.incentives.length) {
+      throw new Error(`Incentive ID ${incentiveId} out of range`);
+    }
+    const incentive = boost.incentives[Number(incentiveId)];
+    if (!incentive) {
+      throw new Error(`Incentive with ID ${incentiveId} not found`);
+    }
+
+    const incentiveData = await incentive.getTopupPayload(topupAmount);
+
+    if (!(topupAmount > 0)) {
+      throw new Error('Top-up amount must be greater than zero');
+    }
+
+    return await this.topupIncentiveFromBudgetRaw(
+      boostId,
+      incentiveId,
+      incentiveData,
+      budget,
+      params,
+    );
+  }
+
+  /**
+   * Prepares and executes a top-up from a Budget, specifying the entire total tokens
+   * (incentive + fee) you want to disburse. We'll back-calculate how many tokens land
+   * in the incentive.
+   *
+   * @public
+   * @async
+   * @param {bigint} boostId The ID of the Boost
+   * @param {bigint} incentiveId The ID of the incentive within that Boost
+   * @param {any} topupPayload A typed struct for the incentive’s top-up parameters
+   * @param {bigint} totalAmount The total tokens to disburse
+   * @param {Address} [budget] Optional override budget address
+   * @param {?WriteParams} [params] Additional transaction overrides
+   * @returns {Promise<{ hash: Hex; result: void }>}
+   */
+  public async topupIncentiveFromBudgetPostFee(
+    boostId: bigint,
+    incentiveId: bigint,
+    totalAmount: bigint,
+    budget?: Address,
+    params?: WriteParams,
+  ) {
+    const feeBps = await this.protocolFee(params);
+    const topupAmount =
+      (totalAmount * FEE_DENOMINATOR) / (FEE_DENOMINATOR + feeBps);
+    return this.topupIncentiveFromBudgetPreFee(
+      boostId,
+      incentiveId,
+      topupAmount,
+      budget,
+      params,
+    );
+  }
+
+  /**
+   * Prepares and executes a top-up from the caller (msg.sender), specifying the net top-up
+   * to land in the incentive. We'll add the protocol fee on top automatically.
+   *
+   * @public
+   * @async
+   * @param {bigint} boostId The ID of the Boost
+   * @param {bigint} incentiveId The ID of the incentive within that Boost
+   * @param {any} topupPayload A typed struct for the incentive’s top-up parameters
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: Hex; result: void }>}
+   */
+  public async topupIncentiveFromSenderPreFee(
+    boostId: bigint,
+    incentiveId: bigint,
+    topupAmount: bigint,
+    params?: WriteParams,
+  ) {
+    const boost = await this.getBoost(boostId, params);
+    if (incentiveId >= boost.incentives.length) {
+      throw new Error(`Incentive ID ${incentiveId} out of range`);
+    }
+    const incentive = boost.incentives[Number(incentiveId)];
+    if (!incentive) {
+      throw new Error(`Incentive with ID ${incentiveId} not found`);
+    }
+
+    if (!(topupAmount > 0)) {
+      throw new Error('Top-up amount must be greater than zero');
+    }
+
+    const incentiveData = await incentive.getTopupPayload(topupAmount);
+
+    return await this.topupIncentiveFromSenderRaw(
+      boostId,
+      incentiveId,
+      incentiveData,
+      params,
+    );
+  }
+
+  /**
+   * Prepares and executes a top-up from the caller (msg.sender), specifying the total
+   * tokens you’re willing to provide (including fee). We'll back-calculate the net
+   * top-up for the incentive.
+   *
+   * @public
+   * @async
+   * @param {bigint} boostId The ID of the Boost
+   * @param {bigint} incentiveId The ID of the incentive within that Boost
+   * @param {any} topupPayload A typed struct for the incentive’s top-up parameters
+   * @param {bigint} totalAmount The entire tokens (top-up + fee)
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: Hex; result: void }>}
+   */
+  public async topupIncentiveFromSenderPostFee(
+    boostId: bigint,
+    incentiveId: bigint,
+    totalAmount: bigint,
+    params?: WriteParams,
+  ) {
+    const feeBps = await this.protocolFee(params);
+    const topupAmount =
+      (totalAmount * FEE_DENOMINATOR) / (FEE_DENOMINATOR + feeBps);
+
+    return this.topupIncentiveFromSenderPreFee(
+      boostId,
+      incentiveId,
+      topupAmount,
+      params,
+    );
+  }
+
+  /**
+   * A lower-level function that actually calls `topupIncentiveFromSender` on-chain,
+   * passing the final total. The contract modifies its internal logic to split net top-up vs. fee.
+   *
+   * @private
+   * @param {bigint} boostId
+   * @param {bigint} incentiveId
+   * @param {Hex} preflightData The raw ABudget.Transfer data from preflight
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: Hex; result: void }>}
+   */
+  private async topupIncentiveFromSenderRaw(
+    boostId: bigint,
+    incentiveId: bigint,
+    preflightData: Hex,
+    params?: WriteParams,
+  ) {
+    const { request, result } = await simulateBoostCoreTopupIncentiveFromSender(
+      this._config,
+      {
+        ...this.optionallyAttachAccount(),
+        ...(params as object),
+        address: this.assertValidAddress(),
+        args: [boostId, incentiveId, preflightData],
+      },
+    );
+    const hash = await writeBoostCoreTopupIncentiveFromSender(
+      this._config,
+      request,
+    );
+    return { hash, result };
+  }
+
+  /**
+   * A lower-level function that actually calls `topupIncentiveFromBudget` on-chain,
+   * passing the preflight data plus the final total. The contract itself modifies
+   * the amount to (topup + fee).
+   *
+   * @private
+   * @param {bigint} boostId
+   * @param {bigint} incentiveId
+   * @param {Hex} preflightData The raw ABudget.Transfer (encoded) from preflight
+   * @param {Address} [budget] Optional override for the budget
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: Hex; result: void }>}
+   */
+  private async topupIncentiveFromBudgetRaw(
+    boostId: bigint,
+    incentiveId: bigint,
+    preflightData: Hex,
+    budget?: Address,
+    params?: WriteParams,
+  ) {
+    // e.g. run "simulate + write" pattern
+    const { request, result } = await simulateBoostCoreTopupIncentiveFromBudget(
+      this._config,
+      {
+        ...this.optionallyAttachAccount(),
+        ...(params as object),
+        address: this.assertValidAddress(),
+        args: [boostId, incentiveId, preflightData, budget ?? zeroAddress],
+      },
+    );
+    const hash = await writeBoostCoreTopupIncentiveFromBudget(
+      this._config,
+      request,
+    );
+    return { hash, result };
+  }
 }

package/src/Incentives/AllowListIncentive.ts

@@ -330,6 +330,23 @@ export class AllowListIncentive extends DeployableTarget<
     };
   }
 
+  /**
+   * Generates a top-up payload for the AllowListIncentive contract.
+   *
+   * @public
+   * @param {bigint} netAmount The net number of slots to be added to the allowlist.
+   * @returns {Hex} The ABI-encoded top-up payload.
+   */
+  public getTopupPayload(netAmount: bigint): Hex {
+    return encodeAbiParameters(
+      [
+        { type: 'address', name: 'allowList' },
+        { type: 'uint256', name: 'limit' },
+      ],
+      [this.payload?.allowList ?? zeroHash, netAmount],
+    );
+  }
+
   /**
    * Builds the claim data for the AllowListIncentive.
    *

package/src/Incentives/CGDAIncentive.ts

@@ -482,6 +482,37 @@ export class CGDAIncentive extends DeployableTarget<
     return encodeAbiParameters([{ type: 'uint256' }], [amount]);
   }
 
+  /**
+   * Generates a top-up payload for the CGDAIncentive contract.
+   *
+   * In this approach, we treat a "top-up" as incrementing the existing `totalBudget`
+   * in the incentive by `netAmount`. The entire payload is re-encoded with the updated budget.
+   *
+   * @public
+   * @param {bigint} netAmount The additional tokens to add to `totalBudget`.
+   * @returns {Hex} The ABI-encoded, updated CGDAIncentive payload.
+   */
+  public async getTopupPayload(netAmount: bigint): Promise<Hex> {
+    return encodeAbiParameters(
+      [
+        { type: 'address', name: 'asset' },
+        { type: 'uint256', name: 'initialReward' },
+        { type: 'uint256', name: 'rewardDecay' },
+        { type: 'uint256', name: 'rewardBoost' },
+        { type: 'uint256', name: 'totalBudget' },
+        { type: 'address', name: 'manager' },
+      ],
+      [
+        (await this.asset()) ?? zeroHash,
+        this.payload?.initialReward ?? 0n,
+        this.payload?.rewardDecay ?? 0n,
+        this.payload?.rewardBoost ?? 0n,
+        netAmount,
+        this.payload?.manager ?? zeroHash,
+      ],
+    );
+  }
+
   /**
    * Builds the claim data for the CGDAIncentive.
    *

package/src/Incentives/ERC20Incentive.ts

@@ -502,6 +502,33 @@ export class ERC20Incentive extends DeployableTarget<
     return encodeAbiParameters([{ type: 'uint256' }], [amount]);
   }
 
+  /**
+   * A helper that composes a typed "top-up" parameter object
+   * given a net top-up amount. You can name it whatever you like
+   * (e.g. topupParamsFromNetAmount, getTopupPayload, etc.).
+   *
+   * @public
+   * @param {bigint} netAmount The net top-up tokens the user wants to add
+   * @param {?WriteParams} [params] (optional) if you need them
+   * @returns {Hex} the ABI-encoded data for top-up
+   */
+  public async getTopupPayload(netAmount: bigint): Promise<Hex> {
+    // 1. Build a typed object matching your `ERC20IncentivePayload`.
+    //    For example, you might want to increment `limit` by `netAmount`,
+    //    or set `reward = netAmount`. That’s up to your logic:
+    const asset = await this.asset();
+    const typed: ERC20IncentivePayload = {
+      asset: asset || zeroAddress,
+      strategy: StrategyType.POOL, // e.g. StrategyType.POOL
+      reward: 1n, // store net top-up as the "reward"
+      limit: netAmount, // or maybe add netAmount to existing limit
+      manager: this.payload?.manager || zeroAddress,
+    };
+
+    // 2. Encode it with your existing `prepareERC20IncentivePayload(...)`.
+    return prepareERC20IncentivePayload(typed);
+  }
+
   /**
    * Builds the claim data for the ERC20Incentive.
    *

package/src/Incentives/ERC20PeggedIncentive.ts

@@ -478,6 +478,24 @@ export class ERC20PeggedIncentive extends DeployableTarget<
       [rewardAmount],
     );
   }
+  /**
+   * Generates a top-up payload for the ERC20PeggedIncentive contract by incrementing
+   * the existing `limit` field by `netAmount`. The entire payload is then re-encoded
+   * via `prepareERC20PeggedIncentivePayload(...)`.
+   *
+   * @public
+   * @param {bigint} netAmount - The additional limit to add to this incentive.
+   * @returns {Hex} The ABI-encoded payload with the updated `limit`.
+   */
+  public async getTopupPayload(netAmount: bigint): Promise<Hex> {
+    return prepareERC20PeggedIncentivePayload({
+      asset: (await this.asset()) ?? zeroAddress,
+      peg: this.payload?.peg ?? zeroAddress,
+      reward: this.payload?.reward ?? 0n,
+      limit: netAmount,
+      manager: this.payload?.manager ?? zeroAddress,
+    });
+  }
 
   /**
    * Decodes claim data for the ERC20PeggedIncentive, returning the claim amount.

package/src/Incentives/ERC20PeggedVariableCriteriaIncentive.ts

@@ -613,6 +613,32 @@ export class ERC20PeggedVariableCriteriaIncentive extends DeployableTarget<
     }
   }
 
+  /**
+   * Generates a top-up payload for the ERC20PeggedIncentive contract by incrementing
+   * the existing `limit` field by `netAmount`. The entire payload is then re-encoded
+   * via `prepareERC20PeggedIncentivePayload(...)`.
+   *
+   * @public
+   * @param {bigint} netAmount - The additional limit to add to this incentive.
+   * @returns {Hex} The ABI-encoded payload with the updated `limit`.
+   */
+  public async getTopupPayload(netAmount: bigint): Promise<Hex> {
+    return prepareERC20PeggedVariableCriteriaIncentivePayload({
+      asset: (await this.asset()) ?? zeroAddress,
+      peg: this.payload?.peg ?? zeroAddress,
+      reward: this.payload?.reward ?? 0n,
+      limit: netAmount,
+      maxReward: this.payload?.maxReward ?? 0n,
+      manager: this.payload?.manager ?? zeroAddress,
+      criteria: this.payload?.criteria ?? {
+        criteriaType: 0,
+        signature: zeroAddress,
+        fieldIndex: 0,
+        targetContract: zeroAddress,
+      },
+    });
+  }
+
   /**
    * @inheritdoc
    *

package/src/Incentives/ERC20VariableIncentive.ts

@@ -22,6 +22,7 @@ import {
   type Hex,
   decodeAbiParameters,
   encodeAbiParameters,
+  zeroAddress,
 } from 'viem';
 import { ERC20VariableIncentive as ERC20VariableIncentiveBases } from '../../dist/deployments.json';
 import type {
@@ -394,6 +395,23 @@ export class ERC20VariableIncentive<
     ]);
     return limit - totalClaimed;
   }
+  /**
+   * Generates a top-up payload for the ERC20PeggedIncentive contract by incrementing
+   * the existing `limit` field by `netAmount`. The entire payload is then re-encoded
+   * via `prepareERC20PeggedIncentivePayload(...)`.
+   *
+   * @public
+   * @param {bigint} netAmount - The additional limit to add to this incentive.
+   * @returns {Hex} The ABI-encoded payload with the updated `limit`.
+   */
+  public async getTopupPayload(netAmount: bigint): Promise<Hex> {
+    return prepareERC20VariableIncentivePayload({
+      asset: (await this.asset()) as Address,
+      reward: netAmount,
+      manager: zeroAddress,
+      limit: 1n,
+    });
+  }
 
   /**
    * Builds the claim data for the ERC20VariableIncentive.

package/src/Incentives/PointsIncentive.ts

@@ -348,6 +348,28 @@ export class PointsIncentive extends DeployableTarget<
     };
   }
 
+  /**
+   * Generates a top-up payload for the PointsIncentive contract.
+   *
+   * @public
+   * @param {bigint} netAmount The net reward amount to be added to the incentive.
+   * @returns {Hex} The ABI-encoded top-up payload.
+   */
+  public getTopupPayload(netAmount: bigint): Hex {
+    return encodeAbiParameters(
+      [
+        { type: 'address', name: 'venue' },
+        { type: 'bytes4', name: 'selector' },
+        { type: 'uint256', name: 'amount' },
+      ],
+      [
+        this.payload?.venue ?? zeroHash,
+        this.payload?.selector ?? zeroHash,
+        netAmount,
+      ],
+    );
+  }
+
   /**
    * Builds the claim data for the PointsIncentive.
    *