Add caveat terms builders to core package, and use them in the caveatBuilders.

- exactCalldata
- nativeTokenPeriodTransfer
- nativeTokenStreaming
- timestamp
- valueLte
- erc20TokenStreaming

Author: jeffsmale90

packages/delegation-core/src/caveats/erc20Streaming.ts

@@ -0,0 +1,122 @@
+import { type BytesLike, bytesToHex, isHexString } from '@metamask/utils';
+
+import {
+  defaultOptions,
+  prepareResult,
+  type EncodingOptions,
+  type ResultValue,
+} from '../returns';
+import type { Hex } from '../types';
+import { toHexString } from '../utils';
+
+// Upper bound for timestamps (January 1, 10000 CE)
+const TIMESTAMP_UPPER_BOUND_SECONDS = 253402300799;
+
+/**
+ * Terms for configuring a linear streaming allowance of ERC20 tokens.
+ */
+export type ERC20StreamingTerms = {
+  /** The address of the ERC20 token contract. */
+  tokenAddress: BytesLike;
+  /** The initial amount available immediately. */
+  initialAmount: bigint;
+  /** The maximum total amount that can be transferred. */
+  maxAmount: bigint;
+  /** The rate at which allowance increases per second. */
+  amountPerSecond: bigint;
+  /** Unix timestamp when streaming begins. */
+  startTime: number;
+};
+
+/**
+ * Creates terms for the ERC20Streaming caveat, configuring a linear
+ * streaming allowance of ERC20 tokens.
+ *
+ * @param terms - The terms for the ERC20Streaming caveat.
+ * @param encodingOptions - The encoding options for the result.
+ * @returns Hex-encoded terms for the caveat (160 bytes).
+ * @throws Error if tokenAddress is invalid.
+ * @throws Error if initialAmount is negative.
+ * @throws Error if maxAmount is not positive.
+ * @throws Error if maxAmount is less than initialAmount.
+ * @throws Error if amountPerSecond is not positive.
+ * @throws Error if startTime is not positive.
+ * @throws Error if startTime exceeds upper bound.
+ */
+export function createERC20StreamingTerms(
+  terms: ERC20StreamingTerms,
+  encodingOptions?: EncodingOptions<'hex'>,
+): Hex;
+export function createERC20StreamingTerms(
+  terms: ERC20StreamingTerms,
+  encodingOptions: EncodingOptions<'bytes'>,
+): Uint8Array;
+/**
+ * Creates terms for the ERC20Streaming caveat, configuring a linear
+ * streaming allowance of ERC20 tokens.
+ *
+ * @param terms - The terms for the ERC20Streaming caveat.
+ * @param encodingOptions - The encoding options for the result.
+ * @returns The terms as a 160-byte hex string.
+ * @throws Error if any of the parameters are invalid.
+ */
+export function createERC20StreamingTerms(
+  terms: ERC20StreamingTerms,
+  encodingOptions: EncodingOptions<ResultValue> = defaultOptions,
+): Hex | Uint8Array {
+  const { tokenAddress, initialAmount, maxAmount, amountPerSecond, startTime } =
+    terms;
+
+  if (!tokenAddress) {
+    throw new Error('Invalid tokenAddress: must be a valid address');
+  }
+
+  let tokenAddressHex: string;
+
+  if (typeof tokenAddress === 'string') {
+    if (!isHexString(tokenAddress) || tokenAddress.length !== 42) {
+      throw new Error('Invalid tokenAddress: must be a valid address');
+    }
+    tokenAddressHex = tokenAddress.slice(2);
+  } else {
+    if (tokenAddress.length !== 20) {
+      throw new Error('Invalid tokenAddress: must be a valid address');
+    }
+    tokenAddressHex = bytesToHex(tokenAddress).slice(2);
+  }
+
+  if (initialAmount < 0n) {
+    throw new Error('Invalid initialAmount: must be greater than zero');
+  }
+
+  if (maxAmount <= 0n) {
+    throw new Error('Invalid maxAmount: must be a positive number');
+  }
+
+  if (maxAmount < initialAmount) {
+    throw new Error('Invalid maxAmount: must be greater than initialAmount');
+  }
+
+  if (amountPerSecond <= 0n) {
+    throw new Error('Invalid amountPerSecond: must be a positive number');
+  }
+
+  if (startTime <= 0) {
+    throw new Error('Invalid startTime: must be a positive number');
+  }
+
+  if (startTime > TIMESTAMP_UPPER_BOUND_SECONDS) {
+    throw new Error(
+      'Invalid startTime: must be less than or equal to 253402300799',
+    );
+  }
+
+  const initialAmountHex = toHexString({ value: initialAmount, size: 32 });
+  const maxAmountHex = toHexString({ value: maxAmount, size: 32 });
+  const amountPerSecondHex = toHexString({ value: amountPerSecond, size: 32 });
+  const startTimeHex = toHexString({ value: startTime, size: 32 });
+
+  const hexValue = `0x${tokenAddressHex}${initialAmountHex}${maxAmountHex}${amountPerSecondHex}${startTimeHex}`;
+
+  return prepareResult(hexValue, encodingOptions);
+}

packages/delegation-core/src/caveats/exactCalldata.ts

@@ -0,0 +1,56 @@
+import type { BytesLike } from '@metamask/utils';
+
+import {
+  defaultOptions,
+  prepareResult,
+  type EncodingOptions,
+  type ResultValue,
+} from '../returns';
+import type { Hex } from '../types';
+
+/**
+ * Terms for configuring an ExactCalldata caveat.
+ */
+export type ExactCalldataTerms = {
+  /** The expected calldata to match against. */
+  callData: BytesLike;
+};
+
+/**
+ * Creates terms for an ExactCalldata caveat that ensures the provided execution calldata
+ * matches exactly the expected calldata.
+ *
+ * @param terms - The terms for the ExactCalldata caveat.
+ * @param encodingOptions - The encoding options for the result.
+ * @returns The terms as the calldata itself.
+ * @throws Error if the `callData` is invalid.
+ */
+export function createExactCalldataTerms(
+  terms: ExactCalldataTerms,
+  encodingOptions?: EncodingOptions<'hex'>,
+): Hex;
+export function createExactCalldataTerms(
+  terms: ExactCalldataTerms,
+  encodingOptions: EncodingOptions<'bytes'>,
+): Uint8Array;
+/**
+ * Creates terms for an ExactCalldata caveat that ensures the provided execution calldata
+ * matches exactly the expected calldata.
+ * @param terms - The terms for the ExactCalldata caveat.
+ * @param encodingOptions - The encoding options for the result.
+ * @returns The terms as the calldata itself.
+ * @throws Error if the `callData` is invalid.
+ */
+export function createExactCalldataTerms(
+  terms: ExactCalldataTerms,
+  encodingOptions: EncodingOptions<ResultValue> = defaultOptions,
+): Hex | Uint8Array {
+  const { callData } = terms;
+
+  if (typeof callData === 'string' && !callData.startsWith('0x')) {
+    throw new Error('Invalid callData: must be a hex string starting with 0x');
+  }
+
+  // For exact calldata, the terms are simply the expected calldata
+  return prepareResult(callData, encodingOptions);
+}

packages/delegation-core/src/caveats/index.ts

@@ -0,0 +1,6 @@
+export { createValueLteTerms } from './valueLte';
+export { createTimestampTerms } from './timestamp';
+export { createNativeTokenPeriodTransferTerms } from './nativeTokenPeriodTransfer';
+export { createExactCalldataTerms } from './exactCalldata';
+export { createNativeTokenStreamingTerms } from './nativeTokenStreaming';
+export { createERC20StreamingTerms } from './erc20Streaming';

packages/delegation-core/src/caveats/nativeTokenPeriodTransfer.ts

@@ -0,0 +1,74 @@
+import {
+  defaultOptions,
+  prepareResult,
+  type EncodingOptions,
+  type ResultValue,
+} from '../returns';
+import type { Hex } from '../types';
+import { toHexString } from '../utils';
+
+/**
+ * Terms for configuring a periodic transfer allowance of native tokens.
+ */
+export type NativeTokenPeriodTransferTerms = {
+  /** The maximum amount that can be transferred within each period (in wei). */
+  periodAmount: bigint;
+  /** The duration of each period in seconds. */
+  periodDuration: number;
+  /** Unix timestamp when the first period begins. */
+  startDate: number;
+};
+
+/**
+ * Creates terms for a NativeTokenPeriodTransfer caveat that validates that native token (ETH) transfers
+ * do not exceed a specified amount within a given time period. The transferable amount resets at the
+ * beginning of each period, and any unused ETH is forfeited once the period ends.
+ *
+ * @param terms - The terms for the NativeTokenPeriodTransfer caveat.
+ * @param encodingOptions - The encoding options for the result.
+ * @returns The terms as a 96-byte hex string (32 bytes for each parameter).
+ * @throws Error if any of the numeric parameters are invalid.
+ */
+export function createNativeTokenPeriodTransferTerms(
+  terms: NativeTokenPeriodTransferTerms,
+  encodingOptions?: EncodingOptions<'hex'>,
+): Hex;
+export function createNativeTokenPeriodTransferTerms(
+  terms: NativeTokenPeriodTransferTerms,
+  encodingOptions: EncodingOptions<'bytes'>,
+): Uint8Array;
+/**
+ * Creates terms for a NativeTokenPeriodTransfer caveat that validates that native token (ETH) transfers
+ * do not exceed a specified amount within a given time period.
+ *
+ * @param terms - The terms for the NativeTokenPeriodTransfer caveat.
+ * @param encodingOptions - The encoding options for the result.
+ * @returns The terms as a 96-byte hex string (32 bytes for each parameter).
+ * @throws Error if any of the numeric parameters are invalid.
+ */
+export function createNativeTokenPeriodTransferTerms(
+  terms: NativeTokenPeriodTransferTerms,
+  encodingOptions: EncodingOptions<ResultValue> = defaultOptions,
+): Hex | Uint8Array {
+  const { periodAmount, periodDuration, startDate } = terms;
+
+  if (periodAmount <= 0n) {
+    throw new Error('Invalid periodAmount: must be a positive number');
+  }
+
+  if (periodDuration <= 0) {
+    throw new Error('Invalid periodDuration: must be a positive number');
+  }
+
+  if (startDate <= 0) {
+    throw new Error('Invalid startDate: must be a positive number');
+  }
+
+  const periodAmountHex = toHexString({ value: periodAmount, size: 32 });
+  const periodDurationHex = toHexString({ value: periodDuration, size: 32 });
+  const startDateHex = toHexString({ value: startDate, size: 32 });
+
+  const hexValue = `0x${periodAmountHex}${periodDurationHex}${startDateHex}`;
+
+  return prepareResult(hexValue, encodingOptions);
+}

packages/delegation-core/src/caveats/nativeTokenStreaming.ts

@@ -0,0 +1,98 @@
+import {
+  defaultOptions,
+  prepareResult,
+  type EncodingOptions,
+  type ResultValue,
+} from '../returns';
+import type { Hex } from '../types';
+import { toHexString } from '../utils';
+
+// Upper bound for timestamps (January 1, 10000 CE)
+const TIMESTAMP_UPPER_BOUND_SECONDS = 253402300799;
+
+/**
+ * Terms for configuring a linear streaming allowance of native tokens.
+ */
+export type NativeTokenStreamingTerms = {
+  /** The initial amount available immediately (in wei). */
+  initialAmount: bigint;
+  /** The maximum total amount that can be transferred (in wei). */
+  maxAmount: bigint;
+  /** The rate at which allowance increases per second (in wei). */
+  amountPerSecond: bigint;
+  /** Unix timestamp when streaming begins. */
+  startTime: number;
+};
+
+/**
+ * Creates terms for the NativeTokenStreaming caveat, configuring a linear
+ * streaming allowance of native tokens.
+ *
+ * @param terms - The terms for the NativeTokenStreaming caveat.
+ * @param encodingOptions - The encoding options for the result.
+ * @returns Hex-encoded terms for the caveat (128 bytes).
+ * @throws Error if initialAmount is negative.
+ * @throws Error if maxAmount is not positive.
+ * @throws Error if maxAmount is less than initialAmount.
+ * @throws Error if amountPerSecond is not positive.
+ * @throws Error if startTime is not positive.
+ * @throws Error if startTime exceeds upper bound.
+ */
+export function createNativeTokenStreamingTerms(
+  terms: NativeTokenStreamingTerms,
+  encodingOptions?: EncodingOptions<'hex'>,
+): Hex;
+export function createNativeTokenStreamingTerms(
+  terms: NativeTokenStreamingTerms,
+  encodingOptions: EncodingOptions<'bytes'>,
+): Uint8Array;
+/**
+ * Creates terms for the NativeTokenStreaming caveat, configuring a linear
+ * streaming allowance of native tokens.
+ *
+ * @param terms - The terms for the NativeTokenStreaming caveat.
+ * @param encodingOptions - The encoding options for the result.
+ * @returns The terms as a 128-byte hex string.
+ * @throws Error if any of the numeric parameters are invalid.
+ */
+export function createNativeTokenStreamingTerms(
+  terms: NativeTokenStreamingTerms,
+  encodingOptions: EncodingOptions<ResultValue> = defaultOptions,
+): Hex | Uint8Array {
+  const { initialAmount, maxAmount, amountPerSecond, startTime } = terms;
+
+  if (initialAmount < 0n) {
+    throw new Error('Invalid initialAmount: must be greater than zero');
+  }
+
+  if (maxAmount <= 0n) {
+    throw new Error('Invalid maxAmount: must be a positive number');
+  }
+
+  if (maxAmount < initialAmount) {
+    throw new Error('Invalid maxAmount: must be greater than initialAmount');
+  }
+
+  if (amountPerSecond <= 0n) {
+    throw new Error('Invalid amountPerSecond: must be a positive number');
+  }
+
+  if (startTime <= 0) {
+    throw new Error('Invalid startTime: must be a positive number');
+  }
+
+  if (startTime > TIMESTAMP_UPPER_BOUND_SECONDS) {
+    throw new Error(
+      'Invalid startTime: must be less than or equal to 253402300799',
+    );
+  }
+
+  const initialAmountHex = toHexString({ value: initialAmount, size: 32 });
+  const maxAmountHex = toHexString({ value: maxAmount, size: 32 });
+  const amountPerSecondHex = toHexString({ value: amountPerSecond, size: 32 });
+  const startTimeHex = toHexString({ value: startTime, size: 32 });
+
+  const hexValue = `0x${initialAmountHex}${maxAmountHex}${amountPerSecondHex}${startTimeHex}`;
+
+  return prepareResult(hexValue, encodingOptions);
+}