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

- exactCalldata
- nativeTokenPeriodTransfer
- nativeTokenStreaming
- timestamp
- valueLte

Author: jeffsmale90

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

@@ -0,0 +1,54 @@
+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: Hex;
+};
+
+/**
+ * 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 (!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,5 @@
+export { createValueLteTerms } from './valueLte';
+export { createTimestampTerms } from './timestamp';
+export { createNativeTokenPeriodTransferTerms } from './nativeTokenPeriodTransfer';
+export { createExactCalldataTerms } from './exactCalldata';
+export { createNativeTokenStreamingTerms } from './nativeTokenStreaming';

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);
+}

packages/delegation-core/src/caveats/timestamp.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 (equivalent to January 1, 10000 CE)
+const TIMESTAMP_UPPER_BOUND_SECONDS = 253402300799;
+
+/**
+ * Terms for configuring a timestamp threshold for delegation usage.
+ */
+export type TimestampTerms = {
+  /** The timestamp (in seconds) after which the delegation can be used. */
+  timestampAfterThreshold: number;
+  /** The timestamp (in seconds) before which the delegation can be used. */
+  timestampBeforeThreshold: number;
+};
+
+/**
+ * Creates terms for a Timestamp caveat that enforces time-based constraints on delegation usage.
+ *
+ * @param terms - The terms for the Timestamp caveat.
+ * @param encodingOptions - The encoding options for the result.
+ * @returns The terms as a 32-byte hex string (16 bytes for each timestamp).
+ * @throws Error if the timestamps are invalid.
+ */
+export function createTimestampTerms(
+  terms: TimestampTerms,
+  encodingOptions?: EncodingOptions<'hex'>,
+): Hex;
+export function createTimestampTerms(
+  terms: TimestampTerms,
+  encodingOptions: EncodingOptions<'bytes'>,
+): Uint8Array;
+/**
+ * Creates terms for a Timestamp caveat that enforces time-based constraints on delegation usage.
+ *
+ * @param terms - The terms for the Timestamp caveat.
+ * @param encodingOptions - The encoding options for the result.
+ * @returns The terms as a 32-byte hex string (16 bytes for each timestamp).
+ * @throws Error if the timestamps are invalid.
+ */
+export function createTimestampTerms(
+  terms: TimestampTerms,
+  encodingOptions: EncodingOptions<ResultValue> = defaultOptions,
+): Hex | Uint8Array {
+  const { timestampAfterThreshold, timestampBeforeThreshold } = terms;
+
+  if (timestampAfterThreshold < 0) {
+    throw new Error(
+      'Invalid timestampAfterThreshold: must be zero or positive',
+    );
+  }
+
+  if (timestampBeforeThreshold < 0) {
+    throw new Error(
+      'Invalid timestampBeforeThreshold: must be zero or positive',
+    );
+  }
+
+  if (timestampBeforeThreshold > TIMESTAMP_UPPER_BOUND_SECONDS) {
+    throw new Error(
+      `Invalid timestampBeforeThreshold: must be less than or equal to ${TIMESTAMP_UPPER_BOUND_SECONDS}`,
+    );
+  }
+
+  if (timestampAfterThreshold > TIMESTAMP_UPPER_BOUND_SECONDS) {
+    throw new Error(
+      `Invalid timestampAfterThreshold: must be less than or equal to ${TIMESTAMP_UPPER_BOUND_SECONDS}`,
+    );
+  }
+
+  if (
+    timestampBeforeThreshold !== 0 &&
+    timestampAfterThreshold >= timestampBeforeThreshold
+  ) {
+    throw new Error(
+      'Invalid thresholds: timestampBeforeThreshold must be greater than timestampAfterThreshold when both are specified',
+    );
+  }
+
+  const afterThresholdHex = toHexString({
+    value: timestampAfterThreshold,
+    size: 16,
+  });
+  const beforeThresholdHex = toHexString({
+    value: timestampBeforeThreshold,
+    size: 16,
+  });
+
+  const hexValue = `0x${afterThresholdHex}${beforeThresholdHex}`;
+
+  return prepareResult(hexValue, encodingOptions);
+}

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

@@ -0,0 +1,54 @@
+import {
+  defaultOptions,
+  prepareResult,
+  type EncodingOptions,
+  type ResultValue,
+} from '../returns';
+import type { Hex } from '../types';
+import { toHexString } from '../utils';
+
+/**
+ * Terms for configuring a ValueLte caveat.
+ */
+export type ValueLteTerms = {
+  /** The maximum value allowed for the transaction as a bigint. */
+  maxValue: bigint;
+};
+
+/**
+ * Creates terms for a ValueLte caveat that limits the maximum value of native tokens that can be spent.
+ *
+ * @param terms - The terms for the ValueLte caveat.
+ * @param options - The encoding options for the result.
+ * @returns The terms as a 32-byte hex string.
+ * @throws Error if the maxValue is negative.
+ */
+export function createValueLteTerms(
+  terms: ValueLteTerms,
+  options?: EncodingOptions<'hex'>,
+): Hex;
+export function createValueLteTerms(
+  terms: ValueLteTerms,
+  options: EncodingOptions<'bytes'>,
+): Uint8Array;
+/**
+ * Creates terms for a ValueLte caveat that limits the maximum value of native tokens that can be spent.
+ *
+ * @param terms - The terms for the ValueLte caveat.
+ * @param options - The encoding options for the result.
+ * @returns The terms as a 32-byte hex string.
+ * @throws Error if the maxValue is negative.
+ */
+export function createValueLteTerms(
+  terms: ValueLteTerms,
+  options: EncodingOptions<ResultValue> = defaultOptions,
+): Hex | Uint8Array {
+  const { maxValue } = terms;
+
+  if (maxValue < 0n) {
+    throw new Error('Invalid maxValue: must be greater than or equal to zero');
+  }
+  const hexValue = toHexString({ value: maxValue, size: 32 });
+
+  return prepareResult(hexValue, options);
+}

packages/delegation-core/src/index.ts

@@ -0,0 +1,9 @@
+export type { Hex } from './types';
+
+export {
+  createValueLteTerms,
+  createTimestampTerms,
+  createNativeTokenPeriodTransferTerms,
+  createExactCalldataTerms,
+  createNativeTokenStreamingTerms,
+} from './caveats';