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,19 @@
+import type { Hex } from '../types';
+
+/**
+ * Creates terms for an ExactCalldata caveat that ensures the provided execution calldata
+ * matches exactly the expected calldata.
+ *
+ * @param callData.callData
+ * @param callData - The expected calldata to match against.
+ * @returns The terms as the calldata itself.
+ * @throws Error if the callData is invalid.
+ */
+export function createExactCalldataTerms({ callData }: { callData: Hex }): Hex {
+  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 callData;
+}

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,44 @@
+import type { Hex } from '../types';
+import { toHexString } from '../utils';
+
+/**
+ * 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 periodAmount.periodAmount
+ * @param periodAmount - The maximum amount of ETH (in wei) that can be transferred per period.
+ * @param periodDuration - The duration of each period in seconds.
+ * @param startDate - The timestamp when the first period begins.
+ * @param periodAmount.periodDuration
+ * @param periodAmount.startDate
+ * @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({
+  periodAmount,
+  periodDuration,
+  startDate,
+}: {
+  periodAmount: bigint;
+  periodDuration: number;
+  startDate: number;
+}): Hex {
+  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 });
+
+  return `0x${periodAmountHex}${periodDurationHex}${startDateHex}`;
+}

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

@@ -0,0 +1,78 @@
+import type { Hex } from '../types';
+import { toHexString } from '../utils';
+
+// Upper bound for timestamps (January 1, 10000 CE)
+const TIMESTAMP_UPPER_BOUND_SECONDS = 253402300799;
+
+/**
+ * Creates terms for the NativeTokenStreamingEnforcer caveat, configuring a linear
+ *  streaming allowance of native tokens.
+ *
+ * The native token streaming caveat allows streaming of native tokens with:
+ * - initialAmount: Amount available immediately at start time
+ * - maxAmount: Maximum total amount that can be transferred
+ * - amountPerSecond: Rate at which additional allowance accrues per second
+ * - startTime: Timestamp when streaming begins
+ *
+ * Available amount = min(initialAmount + amountPerSecond * (currentTime - startTime), maxAmount)
+ *
+ * @param initialAmount.initialAmount
+ * @param initialAmount - The initial amount available immediately (in wei).
+ * @param maxAmount - The maximum total amount that can be transferred (in wei).
+ * @param amountPerSecond - The rate at which allowance increases per second (in wei).
+ * @param startTime - Unix timestamp when streaming begins.
+ * @param initialAmount.maxAmount
+ * @param initialAmount.amountPerSecond
+ * @param initialAmount.startTime
+ * @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({
+  initialAmount,
+  maxAmount,
+  amountPerSecond,
+  startTime,
+}: {
+  initialAmount: bigint;
+  maxAmount: bigint;
+  amountPerSecond: bigint;
+  startTime: number;
+}): Hex {
+  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 });
+
+  return `0x${initialAmountHex}${maxAmountHex}${amountPerSecondHex}${startTimeHex}`;
+}

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

@@ -0,0 +1,67 @@
+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;
+
+/**
+ * Creates terms for a Timestamp caveat that enforces time-based constraints on delegation usage.
+ *
+ * @param timestampAfterThreshold.timestampAfterThreshold
+ * @param timestampAfterThreshold - The timestamp (in seconds) after which the delegation can be used.
+ * @param timestampBeforeThreshold - The timestamp (in seconds) before which the delegation can be used.
+ * @param timestampAfterThreshold.timestampBeforeThreshold
+ * @returns The terms as a 32-byte hex string (16 bytes for each timestamp).
+ * @throws Error if the timestamps are invalid.
+ */
+export function createTimestampTerms({
+  timestampAfterThreshold,
+  timestampBeforeThreshold,
+}: {
+  timestampAfterThreshold: number;
+  timestampBeforeThreshold: number;
+}): Hex {
+  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,
+  });
+
+  return `0x${afterThresholdHex}${beforeThresholdHex}`;
+}

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

@@ -0,0 +1,20 @@
+import type { Hex } from '../types';
+import { toHexString } from '../utils';
+
+/**
+ * Creates terms for a ValueLte caveat that limits the maximum value of native tokens that can be spent.
+ *
+ * @param maxValue.maxValue
+ * @param maxValue - The maximum value allowed for the transaction as a bigint.
+ * @returns The terms as a 32-byte hex string.
+ * @throws Error if the maxValue is negative.
+ */
+export function createValueLteTerms({ maxValue }: { maxValue: bigint }): Hex {
+  if (maxValue < 0n) {
+    throw new Error('Invalid maxValue: must be greater than or equal to zero');
+  }
+
+  const hexValue = toHexString({ value: maxValue, size: 32 });
+
+  return `0x${hexValue}`;
+}

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

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+
+import { createExactCalldataTerms } from '../../src/caveats/exactCalldata';
+import type { Hex } from '../../src/types';
+
+describe('createExactCalldataTerms', () => {
+  it('creates valid terms for simple calldata', () => {
+    const callData = '0x1234567890abcdef';
+    const result = createExactCalldataTerms({ callData });
+
+    expect(result).toStrictEqual(callData);
+  });
+
+  it('creates valid terms for empty calldata', () => {
+    const callData = '0x';
+    const result = createExactCalldataTerms({ callData });
+
+    expect(result).toStrictEqual('0x');
+  });
+
+  it('creates valid terms for function call with parameters', () => {
+    // Example: transfer(address,uint256) function call
+    const callData =
+      '0xa9059cbb000000000000000000000000742d35cc6634c0532925a3b8d40ec49b0e8baa5e0000000000000000000000000000000000000000000000000de0b6b3a7640000';
+    const result = createExactCalldataTerms({ callData });
+
+    expect(result).toStrictEqual(callData);
+  });
+
+  it('creates valid terms for complex calldata', () => {
+    const callData =
+      '0x23b872dd000000000000000000000000742d35cc6634c0532925a3b8d40ec49b0e8baa5e000000000000000000000000742d35cc6634c0532925a3b8d40ec49b0e8baa5f0000000000000000000000000000000000000000000000000de0b6b3a7640000';
+    const result = createExactCalldataTerms({ callData });
+
+    expect(result).toStrictEqual(callData);
+  });
+
+  it('creates valid terms for uppercase hex calldata', () => {
+    const callData = '0x1234567890ABCDEF';
+    const result = createExactCalldataTerms({ callData });
+
+    expect(result).toStrictEqual(callData);
+  });
+
+  it('creates valid terms for mixed case hex calldata', () => {
+    const callData = '0x1234567890AbCdEf';
+    const result = createExactCalldataTerms({ callData });
+
+    expect(result).toStrictEqual(callData);
+  });
+
+  it('creates valid terms for very long calldata', () => {
+    const longCalldata: Hex = `0x${'a'.repeat(1000)}`;
+    const result = createExactCalldataTerms({ callData: longCalldata });
+
+    expect(result).toStrictEqual(longCalldata);
+  });
+
+  it('throws an error for calldata without 0x prefix', () => {
+    const invalidCallData = '1234567890abcdef';
+
+    expect(() =>
+      createExactCalldataTerms({ callData: invalidCallData as Hex }),
+    ).toThrow('Invalid callData: must be a hex string starting with 0x');
+  });
+
+  it('throws an error for empty string', () => {
+    const invalidCallData = '';
+
+    expect(() =>
+      createExactCalldataTerms({ callData: invalidCallData as Hex }),
+    ).toThrow('Invalid callData: must be a hex string starting with 0x');
+  });
+
+  it('throws an error for malformed hex prefix', () => {
+    const invalidCallData = '0X1234'; // uppercase X
+
+    expect(() =>
+      createExactCalldataTerms({ callData: invalidCallData as Hex }),
+    ).toThrow('Invalid callData: must be a hex string starting with 0x');
+  });
+
+  it('handles single function selector', () => {
+    const functionSelector = '0xa9059cbb'; // transfer(address,uint256) selector
+    const result = createExactCalldataTerms({ callData: functionSelector });
+
+    expect(result).toStrictEqual(functionSelector);
+  });
+
+  it('handles calldata with odd length', () => {
+    const oddLengthCalldata = '0x123';
+    const result = createExactCalldataTerms({ callData: oddLengthCalldata });
+
+    expect(result).toStrictEqual(oddLengthCalldata);
+  });
+});