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

package/src/Actions/ContractAction.ts

@@ -0,0 +1,300 @@
+import {
+  contractActionAbi,
+  readContractActionChainId,
+  readContractActionPrepare,
+  readContractActionSelector,
+  readContractActionTarget,
+  readContractActionValue,
+  simulateContractActionExecute,
+  writeContractActionExecute,
+} from '@boostxyz/evm';
+import { bytecode } from '@boostxyz/evm/artifacts/contracts/actions/ContractAction.sol/ContractAction.json';
+import {
+  type Abi,
+  type Address,
+  type ContractEventName,
+  type Hex,
+  encodeAbiParameters,
+  parseAbiParameters,
+} from 'viem';
+import type {
+  DeployableOptions,
+  GenericDeployableParams,
+} from '../Deployable/Deployable';
+import { DeployableTarget } from '../Deployable/DeployableTarget';
+import {
+  type GenericLog,
+  type ReadParams,
+  RegistryType,
+  type WriteParams,
+} from '../utils';
+
+export { contractActionAbi };
+
+/**
+ * The object representation of a `ContractAction.InitPayload`
+ *
+ * @export
+ * @interface ContractActionPayload
+ * @typedef {ContractActionPayload}
+ */
+export interface ContractActionPayload {
+  /**
+   * The chain ID on which the target exists
+   *
+   * @type {bigint}
+   */
+  chainId: bigint;
+  /**
+   * The target contract address
+   *
+   * @type {Address}
+   */
+  target: Address;
+  /**
+   * The selector for the function to be called
+   *
+   * @type {Hex}
+   */
+  selector: Hex;
+  /**
+   * The native token value to send with the function call
+   *
+   * @type {bigint}
+   */
+  value: bigint;
+}
+
+/**
+ * A generic `viem.Log` event with support for `ContractAction` event types.
+ *
+ * @export
+ * @typedef {ContractActionLog}
+ * @template {ContractEventName<typeof contractActionAbi>} [event=ContractEventName<
+ *     typeof contractActionAbi
+ *   >]
+ */
+export type ContractActionLog<
+  event extends ContractEventName<typeof contractActionAbi> = ContractEventName<
+    typeof contractActionAbi
+  >,
+> = GenericLog<typeof contractActionAbi, event>;
+
+/**
+ * A generic contract action
+ *
+ * @export
+ * @class ContractAction
+ * @typedef {ContractAction}
+ * @extends {DeployableTarget<ContractActionPayload>}
+ */
+export class ContractAction<
+  ContractActionAbi extends Abi = typeof contractActionAbi,
+> extends DeployableTarget<ContractActionPayload, ContractActionAbi> {
+  //@ts-expect-error should never be constructed with variant typ
+  public override readonly abi = contractActionAbi;
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @static
+   * @type {Record<number, Address>}
+   */
+  public static override bases: Record<number, Address> = {};
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @static
+   * @type {RegistryType}
+   */
+  public static override registryType: RegistryType = RegistryType.ACTION;
+
+  /**
+   * The target chain ID
+   *
+   * @public
+   * @async
+   * @param {?ReadParams} [params]
+   * @returns {Promise<bigint>}
+   */
+  public async chainId(
+    params?: ReadParams<typeof contractActionAbi, 'chainId'>,
+  ) {
+    return await readContractActionChainId(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),
+    });
+  }
+
+  /**
+   * The target contract
+   *
+   * @public
+   * @async
+   * @param {?ReadParams} [params]
+   * @returns {Promise<`0x${string}`>}
+   */
+  public async target(params?: ReadParams<typeof contractActionAbi, 'target'>) {
+    return await readContractActionTarget(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),
+    });
+  }
+
+  /**
+   * The selector for the function to be called
+   *
+   * @example `function mint(address to, uint256 amount)`
+   * @public
+   * @async
+   * @param {?ReadParams} [params]
+   * @returns {Promise<`0x${string}`>}
+   */
+  public async selector(
+    params?: ReadParams<typeof contractActionAbi, 'selector'>,
+  ) {
+    return await readContractActionSelector(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),
+    });
+  }
+
+  /**
+   * The native token value to send with the function call
+   *
+   * @public
+   * @async
+   * @param {?ReadParams} [params]
+   * @returns {Promise<bigint>}
+   */
+  public async value(params?: ReadParams<typeof contractActionAbi, 'value'>) {
+    return await readContractActionValue(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),
+    });
+  }
+
+  /**
+   * Executes a prepared contract action
+   *
+   * @public
+   * @async
+   * @param {Hex} data
+   * @param {?WriteParams} [params]
+   * @returns {Promise<readonly [boolean, `0x${string}`]>}
+   */
+  public async execute(
+    data: Hex,
+    params?: WriteParams<typeof contractActionAbi, 'execute'>,
+  ) {
+    return await this.awaitResult(this.executeRaw(data, params));
+  }
+
+  /**
+   * Executes a prepared contract action
+   *
+   * @public
+   * @async
+   * @param {Hex} data
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: readonly [boolean, `0x${string}`]; }>}
+   */
+  public async executeRaw(
+    data: Hex,
+    params?: WriteParams<typeof contractActionAbi, 'execute'>,
+  ) {
+    const { request, result } = await simulateContractActionExecute(
+      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),
+        args: [data],
+      },
+    );
+    const hash = await writeContractActionExecute(this._config, request);
+    return { hash, result };
+  }
+
+  /**
+   * The encoded execution payload
+   *
+   * @public
+   * @async
+   * @param {Hex} calldata
+   * @param {?ReadParams} [params]
+   * @returns {Promise<`0x${string}`>}
+   */
+  public async prepare(
+    calldata: Hex,
+    params?: ReadParams<typeof contractActionAbi, 'prepare'>,
+  ) {
+    return await readContractActionPrepare(this._config, {
+      address: this.assertValidAddress(),
+      args: [calldata],
+      ...this.optionallyAttachAccount(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @param {?ContractActionPayload} [_payload]
+   * @param {?DeployableOptions} [_options]
+   * @returns {GenericDeployableParams}
+   */
+  public override buildParameters(
+    _payload?: ContractActionPayload,
+    _options?: DeployableOptions,
+  ): GenericDeployableParams {
+    const [payload, options] = this.validateDeploymentConfig(
+      _payload,
+      _options,
+    );
+    return {
+      abi: contractActionAbi,
+      bytecode: bytecode as Hex,
+      args: [prepareContractActionPayload(payload)],
+      ...this.optionallyAttachAccount(options.account),
+    };
+  }
+}
+
+/**
+ * Given a {@link ContractActionPayload}, properly encode a `ContractAction.InitPayload` for use with {@link ContractAction} initialization.
+ *
+ * @param {ContractActionPayload} param0
+ * @param {bigint} param0.chainId - The chain ID on which the target exists
+ * @param {Address} param0.target - The target contract address
+ * @param {Hex} param0.selector - The selector for the function to be called
+ * @param {bigint} param0.value - The native token value to send with the function call
+ * @returns {Hex}
+ */
+export function prepareContractActionPayload({
+  chainId,
+  target,
+  selector,
+  value,
+}: ContractActionPayload) {
+  return encodeAbiParameters(
+    parseAbiParameters([
+      'ContractActionPayload payload',
+      'struct ContractActionPayload { uint256 chainId; address target; bytes4 selector; uint256 value; }',
+    ]),
+    [{ chainId, target, selector, value }],
+  );
+}

package/src/Actions/ERC721MintAction.test.ts

@@ -0,0 +1,112 @@
+import { mockErc721Abi } from '@boostxyz/evm';
+import { loadFixture } from '@nomicfoundation/hardhat-network-helpers';
+import {
+  encodeAbiParameters,
+  encodeFunctionData,
+  isAddress,
+  parseEther,
+  toFunctionSelector,
+  zeroAddress,
+} from 'viem';
+import { beforeAll, beforeEach, describe, expect, test } from 'vitest';
+import type { MockERC721 } from '@boostxyz/test/MockERC721';
+import { accounts } from '@boostxyz/test/accounts';
+import {
+  type Fixtures,
+  defaultOptions,
+  deployFixtures,
+  fundErc721,
+} from '@boostxyz/test/helpers';
+import { ERC721MintAction } from './ERC721MintAction';
+
+let fixtures: Fixtures, erc721: MockERC721;
+
+beforeAll(async () => {
+  fixtures = await loadFixture(deployFixtures(defaultOptions));
+});
+
+const mintSelector = toFunctionSelector('function mint(address to)');
+
+function nonPayableAction(fixtures: Fixtures, erc721: MockERC721) {
+  return function nonPayableAction() {
+    return fixtures.registry.initialize(
+      crypto.randomUUID(),
+      fixtures.core.ERC721MintAction({
+        chainId: BigInt(31_337),
+        target: erc721.assertValidAddress(),
+        selector: mintSelector,
+        value: 0n,
+      }),
+    );
+  };
+}
+
+describe.skip('ERC721MintAction', () => {
+  beforeEach(async () => {
+    erc721 = await loadFixture(fundErc721(defaultOptions));
+  });
+
+  test('can successfully be deployed', async () => {
+    const action = new ERC721MintAction(defaultOptions, {
+      chainId: BigInt(31_337),
+      target: zeroAddress,
+      selector: '0xdeadbeef',
+      value: 2n,
+    });
+    await action.deploy();
+    expect(isAddress(action.assertValidAddress())).toBe(true);
+  });
+
+  test('can read chain id', async () => {
+    const action = await loadFixture(nonPayableAction(fixtures, erc721));
+    expect(await action.chainId()).toBe(BigInt(31_337));
+  });
+
+  test('can read target', async () => {
+    const action = await loadFixture(nonPayableAction(fixtures, erc721));
+    expect((await action.target()).toLowerCase()).toBe(
+      erc721.assertValidAddress().toLowerCase(),
+    );
+  });
+
+  test('can read selector', async () => {
+    const action = await loadFixture(nonPayableAction(fixtures, erc721));
+    expect(await action.selector()).toBe(mintSelector);
+  });
+
+  test('can read value', async () => {
+    const action = await loadFixture(nonPayableAction(fixtures, erc721));
+    expect(await action.value()).toBe(0n);
+  });
+
+  test('prepare will properly encode execution payload', async () => {
+    const action = await loadFixture(nonPayableAction(fixtures, erc721));
+    const { account } = accounts[1];
+    const payload = await action.prepare(
+      encodeAbiParameters([{ type: 'address', name: 'address' }], [account]),
+    );
+    expect(payload).toBe(
+      encodeFunctionData({
+        abi: mockErc721Abi,
+        functionName: 'mint',
+        args: [account],
+      }),
+    );
+  });
+
+  // TODO implement execute
+  test.skip('nonpayable execute', async () => {
+    const action = await loadFixture(nonPayableAction(fixtures, erc721));
+    const { account } = accounts[1];
+    const [success] = await action.execute(
+      encodeAbiParameters(
+        [
+          { type: 'address', name: 'to' },
+          { type: 'uint256', name: 'amount' },
+        ],
+        [account, parseEther('100')],
+      ),
+    );
+    expect(success).toBe(true);
+  });
+});

package/src/Actions/ERC721MintAction.ts

@@ -0,0 +1,291 @@
+import {
+  erc721MintActionAbi,
+  readErc721MintActionPrepare,
+  readErc721MintActionValidated,
+  simulateErc721MintActionExecute,
+  simulateErc721MintActionValidate,
+  writeErc721MintActionExecute,
+  writeErc721MintActionValidate,
+} from '@boostxyz/evm';
+import { bytecode } from '@boostxyz/evm/artifacts/contracts/actions/ERC721MintAction.sol/ERC721MintAction.json';
+import {
+  type Address,
+  type ContractEventName,
+  type Hex,
+  encodeAbiParameters,
+  toHex,
+} from 'viem';
+import type {
+  DeployableOptions,
+  GenericDeployableParams,
+} from '../Deployable/Deployable';
+import {
+  type GenericLog,
+  type ReadParams,
+  RegistryType,
+  type WriteParams,
+} from '../utils';
+import {
+  ContractAction,
+  type ContractActionPayload,
+  prepareContractActionPayload,
+} from './ContractAction';
+
+export { erc721MintActionAbi };
+/**
+ * `ERC721MintActionPayload` is a re-exported `ContractActionPayload`
+ *
+ * @export
+ * @typedef {ERC721MintActionPayload}
+ */
+export type ERC721MintActionPayload = ContractActionPayload;
+
+/**
+ * A generic `viem.Log` event with support for `ERC721MintAction` event types.
+ *
+ * @export
+ * @typedef {ERC721MintActionLog}
+ * @template {ContractEventName<
+ *     typeof erc721MintActionAbi
+ *   >} [event=ContractEventName<typeof erc721MintActionAbi>]
+ */
+export type ERC721MintActionLog<
+  event extends ContractEventName<
+    typeof erc721MintActionAbi
+  > = ContractEventName<typeof erc721MintActionAbi>,
+> = GenericLog<typeof erc721MintActionAbi, event>;
+
+/**
+ * A primitive action to mint and/or validate that an ERC721 token has been minted
+ * The action is expected to be prepared with the data payload for the minting of the token
+ * This a minimal generic implementation that should be extended if additional functionality or customizations are required
+ * It is expected that the target contract has an externally accessible mint function whose selector
+ *
+ * @export
+ * @class ERC721MintAction
+ * @typedef {ERC721MintAction}
+ * @extends {ContractAction}
+ */
+export class ERC721MintAction extends ContractAction<
+  typeof erc721MintActionAbi
+> {
+  //@ts-expect-error should never be constructed with variant typ
+  public override readonly abi = erc721MintActionAbi;
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @static
+   * @type {Record<number, Address>}
+   */
+  public static override bases: Record<number, Address> = {};
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @static
+   * @type {RegistryType}
+   */
+  public static override registryType: RegistryType = RegistryType.ACTION;
+
+  /**
+   * The set of validated tokens
+   * This is intended to prevent multiple validations against the same token ID
+   *
+   * @public
+   * @async
+   * @param {bigint} token
+   * @param {?ReadParams} [params]
+   * @returns {Promise<boolean>}
+   */
+  public async validated(
+    token: bigint,
+    params?: ReadParams<typeof erc721MintActionAbi, 'validated'>,
+  ) {
+    return await readErc721MintActionValidated(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),
+      args: [token],
+    });
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @async
+   * @param {Hex} data
+   * @param {?WriteParams} [params]
+   * @returns {Promise<readonly [boolean, `0x${string}`]>}
+   */
+  public override async execute(
+    data: Hex,
+    params?: WriteParams<typeof erc721MintActionAbi, 'execute'>,
+  ) {
+    return await this.awaitResult(this.executeRaw(data, params));
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @async
+   * @param {Hex} data
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: readonly [boolean, `0x${string}`]; }>}
+   */
+  public override async executeRaw(
+    data: Hex,
+    params?: WriteParams<typeof erc721MintActionAbi, 'execute'>,
+  ) {
+    const { request, result } = await simulateErc721MintActionExecute(
+      this._config,
+      {
+        address: this.assertValidAddress(),
+        args: [data],
+        ...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 writeErc721MintActionExecute(this._config, request);
+    return { hash, result };
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @async
+   * @param {Hex} data
+   * @param {?ReadParams} [params]
+   * @returns {Promise<`0x${string}`>}
+   */
+  public override async prepare(
+    data: Hex,
+    params?: ReadParams<typeof erc721MintActionAbi, 'prepare'>,
+  ) {
+    return await readErc721MintActionPrepare(this._config, {
+      address: this.assertValidAddress(),
+      args: [data],
+      ...this.optionallyAttachAccount(),
+      // biome-ignore lint/suspicious/noExplicitAny: Accept any shape of valid wagmi/viem parameters, wagmi does the same thing internally
+      ...(params as any),
+    });
+  }
+
+  /**
+   * Validate that the action has been completed successfully. This API is protected to prevent accidental signature burning.
+   *
+   * @protected
+   * @async
+   * @param {Address} holder - The holder
+   * @param {BigInt} tokenId - The token ID
+   * @param {?WriteParams} [params]
+   * @returns {Promise<boolean>} - True if the action has been validated for the user
+   */
+  protected async validate(
+    holder: Address,
+    tokenId: bigint,
+    params?: WriteParams<typeof erc721MintActionAbi, 'validate'>,
+  ) {
+    return await this.awaitResult(this.validateRaw(holder, tokenId, params));
+  }
+
+  /**
+   * Validate that the action has been completed successfully
+   *
+   * @protected
+   * @async
+   * @param {Address} holder - The holder
+   * @param {BigInt} tokenId - The token ID
+   * @param {?WriteParams} [params]
+   * @returns {Promise<{ hash: `0x${string}`; result: boolean; }>} - True if the action has been validated for the user
+   */
+  protected async validateRaw(
+    holder: Address,
+    tokenId: bigint,
+    params?: WriteParams<typeof erc721MintActionAbi, 'validate'>,
+  ) {
+    const { request, result } = await simulateErc721MintActionValidate(
+      this._config,
+      {
+        address: this.assertValidAddress(),
+        args: [prepareERC721MintActionValidate(holder, tokenId)],
+        ...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 writeErc721MintActionValidate(this._config, request);
+    return { hash, result };
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * @public
+   * @param {?ERC721MintActionPayload} [_payload]
+   * @param {?DeployableOptions} [_options]
+   * @returns {GenericDeployableParams}
+   */
+  public override buildParameters(
+    _payload?: ERC721MintActionPayload,
+    _options?: DeployableOptions,
+  ): GenericDeployableParams {
+    const [payload, options] = this.validateDeploymentConfig(
+      _payload,
+      _options,
+    );
+    return {
+      abi: erc721MintActionAbi,
+      bytecode: bytecode as Hex,
+      args: [prepareERC721MintActionPayload(payload)],
+      ...this.optionallyAttachAccount(options.account),
+    };
+  }
+}
+
+/**
+ * Encodes a payload to validate that an action has been completed successfully.
+ *
+ *
+ * @export
+ * @param {Address} holder - The holder address
+ * @param {bigint} payload - The token ID
+ * @returns {Hex} - The first 20 bytes of the payload will be the holder address and the remaining bytes must be an encoded token ID (uint256)
+ */
+export function prepareERC721MintActionValidate(
+  holder: Address,
+  payload: bigint,
+) {
+  return encodeAbiParameters(
+    [
+      { type: 'address', name: 'holder' },
+      { type: 'bytes', name: 'payload' },
+    ],
+    [holder, toHex(payload)],
+  );
+}
+
+/**
+ * Given a {@link ContractActionPayload}, properly encode a `ContractAction.InitPayload` for use with {@link ERC721MintAction} initialization.
+ *
+ * @param {ContractActionPayload} param0
+ * @param {bigint} param0.chainId - The chain ID on which the target exists
+ * @param {Address} param0.target - The target contract address
+ * @param {Hex} param0.selector - The selector for the function to be called
+ * @param {bigint} param0.value - The native token value to send with the function call
+ * @returns {Hex}
+ */
+export function prepareERC721MintActionPayload({
+  chainId,
+  target,
+  selector,
+  value,
+}: ContractActionPayload) {
+  return prepareContractActionPayload({ chainId, target, selector, value });
+}