@boostxyz/sdk 0.0.0-alpha.10

package/src/index.ts

@@ -0,0 +1,53 @@
+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';
+
+// Incentives
+
+export * from './Incentives/AllowListIncentive';
+export * from './Incentives/CGDAIncentive';
+export * from './Incentives/ERC20Incentive';
+// 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';
+
+// 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 {*}
+ */
+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 '../test/MockERC20';
+import { defaultOptions } from '../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);
+  });
+});

package/src/utils.ts

@@ -0,0 +1,198 @@
+import {
+  type Config,
+  type ReadContractParameters,
+  type WatchContractEventParameters,
+  type WriteContractParameters,
+  waitForTransactionReceipt,
+} from '@wagmi/core';
+import type { ExtractAbiEvent } from 'abitype';
+import type {
+  Abi,
+  AbiEvent,
+  ContractEventName,
+  ContractFunctionName,
+  GetLogsParameters,
+  Hash,
+  Hex,
+  Log,
+  WaitForTransactionReceiptParameters,
+} from 'viem';
+import { isHex, keccak256, slice, toHex } from 'viem';
+import { NoContractAddressUponReceiptError } from './errors';
+
+export type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U;
+
+/**
+ * Helper type that encapsulates common writeContract parameters without fields like `abi`, `args`, `functionName`, `address` that are expected to be provided the SDK.
+ * See (writeContract)[https://viem.sh/docs/contract/writeContract]
+ *
+ * @export
+ * @typedef {WriteParams}
+ * @template {Abi} abi
+ * @template {ContractFunctionName<abi>} functionName
+ */
+export type WriteParams<
+  abi extends Abi,
+  functionName extends ContractFunctionName<abi>,
+> = Partial<
+  Omit<
+    WriteContractParameters<abi, functionName>,
+    'address' | 'args' | 'functionName' | 'abi'
+  >
+>;
+
+/**
+ * Helper type that encapsulates common readContract parameters without fields like `abi`, `args`, `functionName`, `address` that are expected to be provided the SDK.
+ * See (readContract)[https://viem.sh/docs/contract/readContract]
+ *
+ * @export
+ * @typedef {ReadParams}
+ * @template {Abi} abi
+ * @template {ContractFunctionName<abi>} functionName
+ */
+export type ReadParams<
+  abi extends Abi,
+  functionName extends ContractFunctionName<abi>,
+> = Partial<
+  Omit<
+    ReadContractParameters<abi, functionName>,
+    'address' | 'args' | 'functionName' | 'abi'
+  >
+>;
+
+/**
+ * Helper type that encapsulates common `watchContractEvent` parameters without fields like `address`, and `abi` that are expected to be provided the SDK.
+ * See (watchContractEvent)[https://wagmi.sh/core/api/actions/watchContractEvent]
+ *
+ * @export
+ * @typedef {WatchParams}
+ * @template {Abi} abi
+ * @template {ContractEventName<abi> | undefined} [eventName=undefined]
+ */
+export type WatchParams<
+  abi extends Abi,
+  eventName extends ContractEventName<abi> | undefined = undefined,
+> = Partial<
+  Omit<WatchContractEventParameters<abi, eventName>, 'address' | 'abi'>
+>;
+
+/**
+ * Helper type that encapsulates common `getLogs` parameters without fields like `address` that are expected to be provided the SDK.
+ * See (getLogs)[https://viem.sh/docs/actions/public/getLogs#getlogs]
+ *
+ * @export
+ * @typedef {GetLogsParams}
+ * @template {Abi} abi
+ * @template {ContractEventName<abi>} event
+ * @template {ExtractAbiEvent<abi, event>} [abiEvent=ExtractAbiEvent<abi, event>]
+ * @template {| readonly AbiEvent[]
+ *     | readonly unknown[]
+ *     | undefined} [abiEvents=abiEvent extends AbiEvent ? [abiEvent] : undefined]
+ */
+export type GetLogsParams<
+  abi extends Abi,
+  event extends ContractEventName<abi>,
+  abiEvent extends ExtractAbiEvent<abi, event> = ExtractAbiEvent<abi, event>,
+  abiEvents extends
+    | readonly AbiEvent[]
+    | readonly unknown[]
+    | undefined = abiEvent extends AbiEvent ? [abiEvent] : undefined,
+> = Partial<Omit<GetLogsParameters<abiEvent, abiEvents>, 'address'>> & {
+  chainId?: number | undefined;
+};
+
+/**
+ * A generic `viem.Log` event with typed `args` support via a given `Abi` and `ContractEventName`
+ *
+ * @export
+ * @typedef {GenericLog}
+ * @template {Abi} abi
+ * @template {ContractEventName<abi>} [event=ContractEventName<abi>]
+ */
+export type GenericLog<
+  abi extends Abi,
+  event extends ContractEventName<abi> = ContractEventName<abi>,
+> = Log<bigint, number, false, ExtractAbiEvent<abi, event>, false>;
+
+/**
+ * Helper utility to convert a string to a `bytes4` type
+ *
+ * @export
+ * @param {string} input
+ * @returns {Hex}
+ */
+export function bytes4(input: string) {
+  return slice(isHex(input) ? keccak256(input) : keccak256(toHex(input)), 0, 4);
+}
+
+/**
+ * Utility function to wait for a transaction receipt, and extract the contractAddress
+ *
+ * @export
+ * @async
+ * @param {WagmiConfig} config - [Wagmi Configuration](https://wagmi.sh/core/api/createConfig)
+ * @param {Promise<Hash>} hash - A transaction hash promise
+ * @param {?Omit<WaitForTransactionReceiptParameters, 'hash'>} [waitParams] - @see {@link WaitForTransactionReceiptParameters}
+ * @returns {unknown}
+ * @throws {@link NoContractAddressUponReceiptError} if no `contractAddress` exists after the transaction has been received
+ */
+export async function getDeployedContractAddress(
+  config: Config,
+  hash: Promise<Hash>,
+  waitParams?: Omit<WaitForTransactionReceiptParameters, 'hash'>,
+) {
+  const receipt = await waitForTransactionReceipt(config, {
+    ...waitParams,
+    hash: await hash,
+  });
+  if (!receipt.contractAddress)
+    throw new NoContractAddressUponReceiptError(receipt);
+  return receipt.contractAddress;
+}
+
+/**
+ * Utility type to encapsulate a transaction hash, and the simulated result prior to submitting the transaction.
+ *
+ * @export
+ * @typedef {HashAndSimulatedResult}
+ * @template [T=unknown]
+ */
+export type HashAndSimulatedResult<T = unknown> = { hash: Hash; result: T };
+
+/**
+ * Helper function to wait for a transaction receipt given a hash promise.
+ *
+ * @export
+ * @async
+ * @template [Result=unknown]
+ * @param {WagmiConfig} config
+ * @param {Promise<HashAndSimulatedResult<Result>>} hashPromise
+ * @param {?Omit<WaitForTransactionReceiptParameters, 'hash'>} [waitParams]
+ * @returns {Promise<Result>}
+ */
+export async function awaitResult<Result = unknown>(
+  config: Config,
+  hashPromise: Promise<HashAndSimulatedResult<Result>>,
+  waitParams?: Omit<WaitForTransactionReceiptParameters, 'hash'>,
+): Promise<Result> {
+  const { hash, result } = await hashPromise;
+  await waitForTransactionReceipt(config, {
+    ...waitParams,
+    hash,
+  });
+  return result;
+}
+
+/**
+ * Enum encapsulating all the different types of targets used in the Boost V2 Protocol.
+ *
+ * @export
+ * @enum {number}
+ */
+export enum RegistryType {
+  ACTION = 0,
+  ALLOW_LIST = 1,
+  BUDGET = 2,
+  INCENTIVE = 3,
+  VALIDATOR = 4,
+}