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

package/src/index.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "vitest";
+import * as SDK from "./index";
+
+// Please add any public interface you'd like to verify exists on the root export here
+// Types don't exist in .js so only list objects, constants, classes, etc, no interfaces
+const allExports = [
+  "BoostRegistry",
+  "BoostCore",
+  "Boost",
+  "EventAction",
+  "OpenAllowList",
+  "SimpleAllowList",
+  "SimpleDenyList",
+  "ManagedBudget",
+  "Deployable",
+  "Contract",
+  "DeployableTarget",
+  "DeployableTargetWithRBAC",
+  "AllowListIncentive",
+  "CGDAIncentive",
+  "ERC20Incentive",
+  "ERC20VariableIncentive",
+  "ERC20VariableCriteriaIncentive",
+  "PointsIncentive",
+  "SignerValidator",
+  "BoostCoreNoIdentifierEmitted",
+  "ContractAddressRequiredError",
+  "DeployableAlreadyDeployedError",
+  "DeployableBuildParametersUnspecifiedError",
+  "DeployableUnknownOwnerProvidedError",
+  "DeployableWagmiConfigurationRequiredError",
+  "DeployableMissingPayloadError",
+  "NoContractAddressUponReceiptError",
+  "InvalidComponentInterfaceError",
+  "UnparseableAbiParamError",
+  "UnknownTransferPayloadSupplied",
+  "BudgetMustAuthorizeBoostCore",
+  "MustInitializeBudgetError",
+  "IncentiveNotCloneableError",
+  "NoEventActionStepsProvidedError",
+  "TooManyEventActionStepsProvidedError",
+  "ValidationAbiMissingError",
+  "FieldActionValidationError",
+  "DecodedArgsMalformedError",
+  "FieldValueUndefinedError",
+  "InvalidNumericalCriteriaError",
+  "FunctionDataDecodeError",
+  "FieldValueNotComparableError",
+  "UnrecognizedFilterTypeError",
+  "NoConnectedChainIdError",
+  "InvalidProtocolChainIdError",
+  "IncentiveCriteriaNotFoundError",
+  "NoMatchingLogsError",
+  "InvalidCriteriaTypeError",
+  "DecodedArgsError",
+  "PassthroughAuth",
+  "prepareBoostPayload",
+  "actionFromAddress",
+  "isEventActionPayloadSimple",
+  "prepareEventActionPayload",
+  "allowListFromAddress",
+  "prepareSimpleAllowListPayload",
+  "prepareSimpleDenyListPayload",
+  "budgetFromAddress",
+  "isFungibleTransfer",
+  "isERC1155TransferPayload",
+  "prepareTransfer",
+  "prepareManagedBudgetPayload",
+  "prepareAllowListIncentivePayload",
+  "prepareCGDAIncentivePayload",
+  "prepareERC20IncentivePayload",
+  "prepareERC20VariableIncentivePayload",
+  "prepareERC20VariableCriteriaIncentivePayload",
+  "incentiveFromAddress",
+  "preparePointsIncentivePayload",
+  "prepareSignerValidatorClaimDataPayload",
+  "prepareSignerValidatorInputParams",
+  "prepareSignerValidatorPayload",
+  "validatorFromAddress",
+  "bytes4",
+  "getDeployedContractAddress",
+  "awaitResult",
+  "assertValidAddressByChainId",
+  "prepareClaimPayload",
+  "prepareERC1155Payload",
+  "prepareERC1155Transfer",
+  "prepareFungiblePayload",
+  "prepareFungibleTransfer",
+  "prepareTransferPayload",
+  "BOOST_REGISTRY_ADDRESS",
+  "BOOST_REGISTRY_ADDRESSES",
+  "boostCoreAbi",
+  "boostRegistryAbi",
+  "BOOST_CORE_CLAIM_FEE",
+  "BOOST_CORE_ADDRESS",
+  "BOOST_CORE_ADDRESSES",
+  "ActionByComponentInterface",
+  "AllowListByComponentInterface",
+  "simpleAllowListAbi",
+  "LIST_MANAGER_ROLE",
+  "simpleDenyListAbi",
+  "BudgetByComponentInterface",
+  "managedBudgetAbi",
+  "rbacAbi",
+  "allowListIncentiveAbi",
+  "cgdaIncentiveAbi",
+  "erc20IncentiveAbi",
+  "erc20VariableIncentiveAbi",
+  "IncentiveByComponentInterface",
+  "pointsIncentiveAbi",
+  "signerValidatorAbi",
+  "ValidatorByComponentInterface",
+  "passthroughAuthAbi"
+]
+
+describe("SDK exports", () => {
+  test(`should export all public API`, () => {
+    for(let exp of allExports) {
+      expect((SDK as any)[exp]).toBeDefined()
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,58 @@
+export * from './BoostRegistry';
+export * from './BoostCore';
+export * from './Boost';
+
+// Actions
+
+export * from './Actions/Action';
+// export * from './Actions/ContractAction';
+// export * from './Actions/ERC721MintAction';
+export * from './Actions/EventAction';
+
+// AllowLists
+
+export * from './AllowLists/AllowList';
+export * from './AllowLists/SimpleAllowList';
+export * from './AllowLists/SimpleDenyList';
+
+// Budgets
+
+export * from './Budgets/Budget';
+// export * from './Budgets/SimpleBudget';
+// export * from './Budgets/VestingBudget';
+export * from './Budgets/ManagedBudget';
+
+// Deployable
+
+export * from './Deployable/Deployable';
+export * from './Deployable/Contract';
+export * from './Deployable/DeployableTarget';
+export * from './Deployable/DeployableTargetWithRBAC';
+
+// Incentives
+
+export * from './Incentives/AllowListIncentive';
+export * from './Incentives/CGDAIncentive';
+export * from './Incentives/ERC20Incentive';
+export * from './Incentives/ERC20VariableIncentive';
+export * from './Incentives/ERC20VariableCriteriaIncentive';
+// export * from './Incentives/ERC1155Incentive';
+export * from './Incentives/Incentive';
+export * from './Incentives/PointsIncentive';
+
+// Validators
+
+export * from './Validators/SignerValidator';
+export * from './Validators/Validator';
+
+// Extra
+
+export * from './errors';
+export * from './utils';
+export * from './claiming';
+export * from './transfers';
+
+// Auth
+
+export * from './Auth/Auth';
+export * from './Auth/PassthroughAuth';

package/src/transfers.ts

@@ -0,0 +1,284 @@
+import {
+  type Address,
+  type Hex,
+  encodeAbiParameters,
+  parseAbiParameters,
+  zeroAddress,
+} from 'viem';
+
+/**
+ * The various types of assets supported in Budgets and Incentives.
+ *
+ * @export
+ * @enum {number}
+ */
+export enum AssetType {
+  ETH,
+  ERC20,
+  ERC1155,
+}
+
+/**
+ * Object representation of a generic `Transfer` struct.
+ *
+ * @export
+ * @interface TransferPayload
+ * @typedef {TransferPayload}
+ */
+export interface TransferPayload {
+  /**
+   * The type of the asset being transferred.
+   *
+   * @type {AssetType}
+   */
+  assetType: AssetType;
+  /**
+   * The address of the asset to transfer, zero address for ETH.
+   *
+   * @type {Address}
+   */
+  address: Address;
+  /**
+   * The account from which to transfer the assets.
+   *
+   * @type {Address}
+   */
+  target: Address;
+  /**
+   * An encoded {@link FungiblePayload}, use {@link prepareFungiblePayload} to construct.
+   *
+   * @type {Hex}
+   */
+  data: Hex;
+}
+
+/**
+ * Encodes parameters for transferring the transfer of Fungible and ERC1155 assets, used for {@link Budget} operations.
+ * Typically you'd use {@link prepareFungibleTransfer} or {@link prepareERC1155Transfer}
+ *
+ * @param {TransferPayload} param0
+ * @param {AssetType} param0.assetType - The asset type being transferred.
+ * @param {Address} param0.address - The address of the asset, use zero address for ETH transfers.
+ * @param {Address} param0.target - The address of the account being transferred from
+ * @param {Hex} param0.data - Use {@link prepareFungiblePayload} to properly encode an amount to transfer
+ * @returns {Hex}
+ */
+export const prepareTransferPayload = ({
+  assetType,
+  address,
+  target,
+  data,
+}: TransferPayload) => {
+  return encodeAbiParameters(
+    [
+      { type: 'uint8', name: 'assetType' },
+      { type: 'address', name: 'asset' },
+      { type: 'address', name: 'target' },
+      { type: 'bytes', name: 'data' },
+    ],
+    [assetType, address, target, data],
+  );
+};
+
+/**
+ * Object representation of
+ *
+ * @export
+ * @interface ERC1155Payload
+ * @typedef {ERC1155Payload}
+ */
+export interface ERC1155Payload {
+  /**
+   * The ERC1155 token ID for the incentive
+   *
+   * @type {bigint}
+   */
+  tokenId: bigint;
+  /**
+   * The amount to transfer
+   *
+   * @type {bigint}
+   */
+  amount: bigint;
+}
+
+/**
+ * Given a token ID and amount, properly encode a `ERC1155Incentive.ERC1155Payload` for use with {@link ERC1155Incentive} initialization.
+ *
+ * @export
+ * @param {ERC1155Payload} param0
+ * @param {bigint} param0.tokenId - The ERC1155 token ID for the incentive
+ * @param {bigint} param0.amount - The amount to transfer
+ * @returns {Hex}
+ */
+export function prepareERC1155Payload({ tokenId, amount }: ERC1155Payload) {
+  return encodeAbiParameters(
+    parseAbiParameters([
+      'ERC1155Payload payload',
+      'struct ERC1155Payload { uint256 tokenId; uint256 amount; bytes data; }',
+    ]),
+    [{ tokenId, amount, data: '0x' }],
+  );
+}
+
+/**
+ * An object representation of the `Budget.Transfer` contract struct for transfers of ERC1155 assets.
+ *
+ * @export
+ * @interface ERC1155TransferPayload
+ * @typedef {ERC1155TransferPayload}
+ */
+export interface ERC1155TransferPayload {
+  /**
+   * The token ID to transfer
+   *
+   * @type {bigint}
+   */
+  tokenId: bigint;
+  /**
+   * The amount to transfer
+   *
+   * @type {bigint}
+   */
+  amount: bigint;
+  /**
+   * The address of the asset to target
+   *
+   * @type {Address}
+   */
+  asset: Address;
+  /**
+   * The account to transfer from
+   *
+   * @type {Address}
+   */
+  target: Address;
+}
+
+/**
+ * Encodes parameters for transferring the transfer of ERC1155 assets, used for {@link Budget} operations.
+ * The caller must have already approved the contract to transfer the asset.
+ *
+ * @export
+ * @param {ERC1155TransferPayload} param0
+ * @param {bigint} param0.tokenId - The token ID to transfer
+ * @param {bigint} param0.amount - The amount to transfer
+ * @param {Address} param0.asset - The address of the asset to target
+ * @param {Address} param0.target - The account to transfer from
+ * @returns {Hex}
+ */
+export function prepareERC1155Transfer({
+  tokenId,
+  amount,
+  asset,
+  target,
+}: ERC1155TransferPayload) {
+  return encodeAbiParameters(
+    parseAbiParameters([
+      'Transfer request',
+      'struct Transfer { uint8 assetType; address asset; address target; bytes data; }',
+    ]),
+    [
+      {
+        assetType: AssetType.ERC1155,
+        asset,
+        data: prepareERC1155Payload({ tokenId, amount }),
+        target,
+      },
+    ],
+  );
+}
+
+/**
+ * An object representation of the `FungiblePayload` struct
+ *
+ * @export
+ * @interface FungiblePayload
+ * @typedef {FungiblePayload}
+ */
+export interface FungiblePayload {
+  /**
+   * The amount being transferred
+   *
+   * @type {bigint}
+   */
+  amount: bigint;
+}
+
+/**
+ * Encodes an amount for the `FungiblePayload` struct
+ *
+ * @export
+ * @param {FungiblePayload} param0
+ * @param {bigint} param0.amount - The amount being transferred
+ * @returns {Hex}
+ */
+export function prepareFungiblePayload({ amount }: FungiblePayload) {
+  return encodeAbiParameters(
+    parseAbiParameters([
+      'FungiblePayload payload',
+      'struct FungiblePayload { uint256 amount; }',
+    ]),
+    [{ amount }],
+  );
+}
+
+/**
+ * An object representation of the `Budget.Transfer` contract struct for transfers of fungible assets.
+ *
+ * @export
+ * @interface FungibleTransferPayload
+ * @typedef {FungibleTransferPayload}
+ */
+export interface FungibleTransferPayload {
+  /**
+   * The amount to transfer
+   *
+   * @type {bigint}
+   */
+  amount: bigint;
+  /**
+   * The address of the asset. Use zero address for ETH transfers.
+   *
+   * @type {Address}
+   */
+  asset: Address;
+  /**
+   * The account to transfer from
+   *
+   * @type {Address}
+   */
+  target: Address;
+}
+
+/**
+ * Encodes parameters for a Fungible transfer, used for Budget allocations.
+ * The caller must have already approved the contract to transfer the asset.
+ *
+ * @export
+ * @param {FungibleTransferPayload} param0
+ * @param {bigint} param0.amount - The amount to transfer
+ * @param {Address} param0.asset - The address of the asset. Use zero address for ETH transfers.
+ * @param {Address} param0.target - The account to transfer from
+ * @returns {Hex}
+ */
+export function prepareFungibleTransfer({
+  amount,
+  asset,
+  target,
+}: FungibleTransferPayload) {
+  return encodeAbiParameters(
+    parseAbiParameters([
+      'Transfer request',
+      'struct Transfer { uint8 assetType; address asset; address target; bytes data; }',
+    ]),
+    [
+      {
+        assetType: asset == zeroAddress ? AssetType.ETH : AssetType.ERC20,
+        asset,
+        data: prepareFungiblePayload({ amount }),
+        target,
+      },
+    ],
+  );
+}

package/src/utils.test.ts

@@ -0,0 +1,44 @@
+import { simulateMockErc20Mint, writeMockErc20Mint } from '@boostxyz/evm';
+import { isAddress } from 'viem';
+import { describe, expect, test } from 'vitest';
+import { MockERC20 } from '@boostxyz/test/MockERC20';
+import { defaultOptions } from '@boostxyz/test/helpers';
+import { awaitResult, bytes4, getDeployedContractAddress } from './utils';
+
+describe('bytes4', () => {
+  test('should return the bytes4 representation of a string', () => {
+    expect(bytes4('0xdeadbeef')).toBe('0xd4fd4e18');
+    expect(bytes4('deadbeef')).toBe('0x9f24c52e');
+  });
+});
+
+describe('getDeployedContractAddress', () => {
+  test('should return the address of a contract given a tx hash promise', async () => {
+    const hash = new MockERC20(defaultOptions, {}).deployRaw();
+    expect(
+      isAddress(await getDeployedContractAddress(defaultOptions.config, hash)),
+    ).toBe(true);
+  });
+});
+
+describe('awaitResult', () => {
+  test('should wait for a transaction receipt and return the simulated result', async () => {
+    const erc20 = new MockERC20(defaultOptions, {});
+    await erc20.deploy();
+    const { request, result } = await simulateMockErc20Mint(
+      defaultOptions.config,
+      {
+        address: erc20.assertValidAddress(),
+        args: [defaultOptions.account.address, 100n],
+        account: defaultOptions.account,
+      },
+    );
+    const hash = await writeMockErc20Mint(defaultOptions.config, request);
+    expect(
+      await awaitResult(
+        defaultOptions.config,
+        Promise.resolve({ hash, result }),
+      ),
+    ).toBe(undefined);
+  });
+});