@fhevm/sdk 0.0.1 → 1.0.0-alpha.1

package/core/base/object.ts

@@ -0,0 +1,41 @@
+/** Wraps a single value in an array, or returns the array as-is. */
+export function toArray<T>(value: T | readonly T[]): readonly T[] {
+  if (Array.isArray(value)) {
+    return value as readonly T[];
+  }
+  return [value as T];
+}
+
+export function simpleDeepFreeze<T extends object>(obj: T): Readonly<T> {
+  Object.freeze(obj);
+  for (const value of Object.values(obj)) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value) && !Object.isFrozen(value)) {
+      simpleDeepFreeze(value);
+    }
+  }
+  return obj;
+}
+
+/**
+ * Defines a non-enumerable, non-writable, non-configurable property on the target object.
+ * The property is hidden from `Object.keys()` / `Object.entries()` and cannot be
+ * overwritten or reconfigured after creation.
+ *
+ * @param target - The object to define the property on.
+ * @param fnName - The property name.
+ * @param fn - The value to assign.
+ * @returns The target object, typed with the added property.
+ */
+export function addInternalFunction<T extends object, FnName extends string, Fn extends (...args: never[]) => unknown>(
+  target: T,
+  fnName: FnName,
+  fn: Fn,
+): T & Readonly<Record<FnName, Fn>> {
+  Object.defineProperty(target, fnName, {
+    value: fn,
+    writable: false,
+    configurable: false,
+    enumerable: false,
+  });
+  return target as T & Readonly<Record<FnName, Fn>>;
+}

package/core/base/promise.ts

@@ -0,0 +1,31 @@
+/**
+ * Executes promise factories with control over batching behavior.
+ * @param factories - Array of functions that create promises (not promises themselves)
+ * @param parallel - If true, executes all concurrently. If false, executes one at a time (default `false`).
+ *
+ * @example
+ * ```typescript
+ *  const rpcCalls = [
+ *    () => contract.balanceOf(address1),
+ *    () => contract.balanceOf(address2),
+ *    () => contract.totalSupply(),
+ *. ];
+ *
+ *  // Sequential: one RPC call at a time
+ *  const resultsSeq = await executeWithBatching(rpcCalls, false);
+ *
+ *  // Concurrent: all fire together (lets ethers batch them)
+ *  const resultsConcurrent = await executeWithBatching(rpcCalls, true);
+ * ```
+ */
+export async function executeWithBatching<T>(factories: Array<() => Promise<T>>, parallel?: boolean): Promise<T[]> {
+  if (parallel === true) {
+    return Promise.all(factories.map((f) => f()));
+  }
+
+  const results: T[] = [];
+  for (const factory of factories) {
+    results.push(await factory());
+  }
+  return results;
+}

package/core/base/record.ts

@@ -0,0 +1,201 @@
+import type {
+  RecordArrayPropertyType,
+  RecordBooleanPropertyType,
+  RecordNonNullablePropertyType,
+} from '../types/record-p.js';
+import type { ErrorMetadataParams } from './errors/ErrorBase.js';
+import { InvalidPropertyError } from './errors/InvalidPropertyError.js';
+
+/**
+ * Type guard that checks if a property exists on an object and is non-null/non-undefined.
+ *
+ * @template K - The property key type (string literal)
+ * @param o - The value to check (can be any type)
+ * @param property - The property name to check for
+ * @returns True if `o` is an object with the specified property that is not null or undefined
+ *
+ * @example
+ * ```typescript
+ * const data: unknown = { name: "Alice", age: 30 };
+ * if (isRecordNonNullableProperty(data, 'name')) {
+ *   console.log(data.name); // OK
+ * }
+ * ```
+ */
+export function isRecordNonNullableProperty<K extends string>(
+  o: unknown,
+  property: K,
+): o is RecordNonNullablePropertyType<K> {
+  if (
+    o === undefined ||
+    o === null ||
+    typeof o !== 'object' ||
+    !(property in o) ||
+    (o as Record<string, unknown>)[property] === undefined ||
+    (o as Record<string, unknown>)[property] === null
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Assertion function that validates a property exists on an object and is non-null/non-undefined.
+ * Throws an `InvalidPropertyError` if validation fails.
+ *
+ * @template K - The property key type (string literal)
+ * @param record - The value to validate (can be any type)
+ * @param property - The property name to check for
+ * @param recordName - The name of the object being validated (used in error messages)
+ * @throws {InvalidPropertyError} When the property is missing, null, or undefined
+ * @throws {never} No other errors are thrown
+ *
+ * @example
+ * ```typescript
+ * function processUser(data: unknown) {
+ *   assertRecordNonNullableProperty(data, 'userId', 'user');
+ *   console.log(data.userId);
+ * }
+ * ```
+ */
+export function assertRecordNonNullableProperty<K extends string>(
+  record: unknown,
+  property: K,
+  recordName: string,
+  options: { expectedType?: string } & ErrorMetadataParams,
+): asserts record is RecordNonNullablePropertyType<K> {
+  if (!isRecordNonNullableProperty(record, property)) {
+    throw new InvalidPropertyError(
+      {
+        subject: recordName,
+        property,
+        expectedType: options.expectedType ?? 'non-nullable',
+        type: typeofProperty(record, property),
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * Type guard that checks if a property exists on an object and is an array.
+ *
+ * @template K - The property key type (string literal)
+ * @param record - The value to check (can be any type)
+ * @param property - The property name to check for
+ * @returns True if `o` is an object with the specified property that is a non-null array
+ *
+ * @example
+ * ```typescript
+ * const data: unknown = { items: [1, 2, 3], count: 42 };
+ * if (isRecordArrayProperty(data, 'items')) {
+ *   console.log(data.items.length); // OK
+ *   data.items.forEach(item => console.log(item)); // OK
+ * }
+ * ```
+ */
+export function isRecordArrayProperty<K extends string>(
+  record: unknown,
+  property: K,
+): record is RecordArrayPropertyType<K> {
+  if (!isRecordNonNullableProperty(record, property)) {
+    return false;
+  }
+  return Array.isArray(record[property]);
+}
+
+/**
+ * Assertion function that validates a property exists on an object and is an array.
+ * Throws an `InvalidPropertyError` if validation fails.
+ *
+ * @template K - The property key type (string literal)
+ * @param record - The value to validate (can be any type)
+ * @param property - The property name to check for
+ * @param recordName - The name of the object being validated (used in error messages)
+ * @throws {InvalidPropertyError} When the property is missing, null, or not an array
+ * @throws {never} No other errors are thrown
+ *
+ * @example
+ * ```typescript
+ * function processResults(data: unknown) {
+ *   assertRecordArrayProperty(data, 'results', 'response');
+ *   console.log(`Found ${data.results.length} results`);
+ *   data.results.forEach(result => processResult(result));
+ * }
+ * ```
+ */
+export function assertRecordArrayProperty<K extends string>(
+  record: unknown,
+  property: K,
+  recordName: string,
+  options: { expectedType?: string } & ErrorMetadataParams,
+): asserts record is RecordArrayPropertyType<K> {
+  if (!isRecordArrayProperty(record, property)) {
+    throw new InvalidPropertyError(
+      {
+        subject: recordName,
+        property,
+        expectedType: options.expectedType ?? 'Array',
+        type: typeofProperty(record, property),
+      },
+      options,
+    );
+  }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+// - isRecordBooleanProperty
+// - assertRecordBooleanProperty
+////////////////////////////////////////////////////////////////////////////////
+
+export function isRecordBooleanProperty<K extends string>(
+  record: unknown,
+  property: K,
+): record is RecordBooleanPropertyType<K> {
+  if (!isRecordNonNullableProperty(record, property)) {
+    return false;
+  }
+  return typeof record[property] === 'boolean';
+}
+
+export function assertRecordBooleanProperty<K extends string>(
+  record: unknown,
+  property: K,
+  recordName: string,
+  options: { expectedValue?: boolean } & ErrorMetadataParams,
+): asserts record is RecordBooleanPropertyType<K> {
+  if (!isRecordBooleanProperty(record, property))
+    throw new InvalidPropertyError(
+      {
+        subject: recordName,
+        property,
+        expectedType: 'boolean',
+        type: typeofProperty(record, property),
+      },
+      options,
+    );
+  if (options.expectedValue !== undefined) {
+    if (record[property] !== options.expectedValue) {
+      throw new InvalidPropertyError(
+        {
+          subject: recordName,
+          property,
+          expectedType: 'boolean',
+          expectedValue: String(options.expectedValue),
+          type: typeof record[property],
+          value: String(record[property]),
+        },
+        options,
+      );
+    }
+  }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+export function typeofProperty(o: unknown, property: string): string {
+  if (isRecordNonNullableProperty(o, property)) {
+    return typeof o[property];
+  }
+  return 'undefined';
+}

package/core/base/string.ts

@@ -0,0 +1,214 @@
+import type { RecordStringArrayPropertyType, RecordStringPropertyType } from '../types/record-p.js';
+import type { BytesHex, BytesHexNo0x } from '../types/primitives.js';
+import type { ErrorMetadataParams } from './errors/ErrorBase.js';
+import { assertRecordArrayProperty, isRecordNonNullableProperty, typeofProperty } from './record.js';
+import { InternalError } from './errors/InternalError.js';
+import { InvalidPropertyError } from './errors/InvalidPropertyError.js';
+
+export function removeSuffix(s: string | undefined, suffix: string): string {
+  if (s === undefined) {
+    return '';
+  }
+  if (suffix.length === 0) {
+    return s;
+  }
+  return s.endsWith(suffix) ? s.slice(0, -suffix.length) : s;
+}
+
+export function is0x(s: unknown): s is `0x${string}` {
+  return typeof s === 'string' && s.startsWith('0x');
+}
+
+export function isNo0x(s: unknown): s is string {
+  return typeof s === 'string' && !s.startsWith('0x');
+}
+
+/**
+ * Prepends `0x` prefix. When the input is a branded `BytesHexNo0x` (or a sized
+ * variant like `Bytes65HexNo0x`), the return type preserves the size brand via
+ * generic inference — no per-size overload needed.
+ */
+export function ensure0x<T extends BytesHexNo0x>(s: T): BytesHex & Omit<T, keyof BytesHexNo0x>;
+export function ensure0x(s: string): `0x${string}`;
+export function ensure0x(s: string): `0x${string}` {
+  return !s.startsWith('0x') ? `0x${s}` : (s as `0x${string}`);
+}
+
+/**
+ * Strips `0x` prefix. When the input is a branded `BytesHex` (or a sized
+ * variant like `Bytes65Hex`), the return type preserves the size brand via
+ * generic inference — no per-size overload needed.
+ */
+export function remove0x<T extends BytesHex>(s: T): BytesHexNo0x & Omit<T, keyof BytesHex>;
+export function remove0x(s: string): string;
+export function remove0x(s: string): string {
+  return s.startsWith('0x') ? s.substring(2) : s;
+}
+
+export function assertIs0xString(s: unknown): asserts s is `0x${string}` {
+  if (!(typeof s === 'string' && s.startsWith('0x'))) {
+    throw new InternalError({ message: 'value is not a `0x${string}`' });
+  }
+}
+
+export function isNonEmptyString(s: unknown): s is string {
+  if (s === undefined || s === null || typeof s !== 'string') {
+    return false;
+  }
+  return s.length > 0;
+}
+
+export function assertIsNonEmptyString(s: unknown): asserts s is string {
+  if (!isNonEmptyString(s)) {
+    throw new InternalError({
+      message: `Expected a non-empty string, got ${typeof s === 'string' ? 'an empty string' : typeof s}`,
+    });
+  }
+}
+
+/**
+ * Type guard that checks if a property exists on an object and is a string.
+ *
+ * @template K - The property key type (string literal)
+ * @param o - The value to check (can be any type)
+ * @param property - The property name to check for
+ * @returns True if `o` is an object with the specified property that is a non-null string
+ *
+ * @example
+ * ```typescript
+ * const data: unknown = { status: "active", count: 42 };
+ * if (isRecordStringProperty(data, 'status')) {
+ *   console.log(data.status.toUpperCase()); // OK
+ * }
+ * ```
+ */
+export function isRecordStringProperty<K extends string>(o: unknown, property: K): o is RecordStringPropertyType<K> {
+  if (!isRecordNonNullableProperty(o, property)) {
+    return false;
+  }
+  return typeof o[property] === 'string';
+}
+
+/**
+ * Assertion function that validates a property exists on an object, is a string,
+ * and optionally matches specific expected value(s).
+ * Throws an `InvalidPropertyError` if validation fails.
+ *
+ * @template K - The property key type (string literal)
+ * @param record - The value to validate (can be any type)
+ * @param property - The property name to check for
+ * @param recordName - The name of the object being validated (used in error messages)
+ * @param expectedValue - Optional specific string value or array of allowed values to match against
+ * @throws {InvalidPropertyError} When the property is missing, not a string, or doesn't match expectedValue
+ * @throws {never} No other errors are thrown
+ *
+ * @example
+ * ```typescript
+ * // Check property is a string (any value)
+ * assertRecordStringProperty(data, 'name', 'user');
+ *
+ * // Check property equals a specific value
+ * assertRecordStringProperty(data, 'status', 'response', 'active');
+ *
+ * // Check property is one of multiple allowed values
+ * assertRecordStringProperty(data, 'status', 'response', ['queued', 'processing', 'completed']);
+ * ```
+ */
+export function assertRecordStringProperty<K extends string>(
+  record: unknown,
+  property: K,
+  recordName: string,
+  options: { expectedValue?: string | string[] } & ErrorMetadataParams,
+): asserts record is RecordStringPropertyType<K> {
+  if (!isRecordStringProperty(record, property)) {
+    throw new InvalidPropertyError(
+      {
+        subject: recordName,
+        property,
+        expectedType: 'string',
+        expectedValue: options.expectedValue,
+        type: typeofProperty(record, property),
+      },
+      options,
+    );
+  }
+
+  if (options.expectedValue !== undefined) {
+    if (Array.isArray(options.expectedValue)) {
+      // Check if value matches any of the allowed values
+      for (let i = 0; i < options.expectedValue.length; ++i) {
+        if (record[property] === options.expectedValue[i]) {
+          return;
+        }
+      }
+
+      throw new InvalidPropertyError(
+        {
+          subject: recordName,
+          property,
+          expectedType: 'string',
+          expectedValue: options.expectedValue,
+          type: typeof record[property], // === "string"
+          value: record[property],
+        },
+        options,
+      );
+    } else {
+      if (record[property] !== options.expectedValue) {
+        throw new InvalidPropertyError(
+          {
+            subject: recordName,
+            property,
+            expectedType: 'string',
+            expectedValue: options.expectedValue,
+            type: typeof record[property], // === "string"
+            value: record[property],
+          },
+          options,
+        );
+      }
+    }
+  }
+}
+
+export function assertRecordStringArrayProperty<K extends string>(
+  record: unknown,
+  property: K,
+  recordName: string,
+  options: ErrorMetadataParams,
+): asserts record is RecordStringArrayPropertyType<K> {
+  assertRecordArrayProperty(record, property, recordName, options);
+  const arr = record[property];
+  for (let i = 0; i < arr.length; ++i) {
+    if (typeof arr[i] !== 'string') {
+      throw new InvalidPropertyError(
+        {
+          subject: recordName,
+          index: i,
+          property,
+          expectedType: 'string',
+          type: typeof arr[i],
+        },
+        options,
+      );
+    }
+  }
+}
+
+/**
+ * Capitalizes the first letter of a string.
+ */
+export function capitalizeFirstLetter(s: string): string {
+  if (s.length === 0) {
+    return s;
+  }
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+export function safeJSONstringify(o: unknown, space?: string | number): string {
+  try {
+    return JSON.stringify(o, (_, v: unknown) => (typeof v === 'bigint' ? v.toString() : v), space);
+  } catch {
+    return '';
+  }
+}

package/core/base/timeout.ts

@@ -0,0 +1,32 @@
+/**
+ * Creates an Error with name 'AbortError' for consistency with fetch abort behavior.
+ * Preserves the original abort reason as the error's cause.
+ */
+function createAbortError(reason?: unknown): Error {
+  const error = new Error('Aborted', { cause: reason });
+  error.name = 'AbortError';
+  return error;
+}
+
+/**
+ * Returns a Promise that resolves after the specified delay, but can be aborted.
+ *
+ * @throws {Error} An error with name 'AbortError' if the signal is aborted
+ */
+export function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  // Check if already aborted before creating the Promise
+  signal?.throwIfAborted();
+
+  return new Promise((resolve, reject) => {
+    const timeoutId = setTimeout(resolve, ms);
+
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timeoutId);
+        reject(createAbortError(signal.reason));
+      },
+      { once: true },
+    );
+  });
+}

package/core/base/trustedValue.ts

@@ -0,0 +1,110 @@
+// eslint-disable-next-line @typescript-eslint/naming-convention
+declare const __trustedValue: unique symbol;
+
+/**
+ * An opaque, tamper-proof container for a value of type `T`.
+ *
+ * ## Authenticity model
+ *
+ * A `TrustedValue` guarantees that:
+ * 1. **Origin authenticity** — only code that holds the original `symbol` token
+ *    can verify the value, proving it was created by a trusted origin.
+ * 2. **Tamper resistance** — the inner value cannot be read, modified, or
+ *    replaced by external code (enforced by `#private` fields and
+ *    `Object.freeze`).
+ * 3. **Forgery resistance** — external code cannot construct a valid instance
+ *    (the implementation class is not exported).
+ *
+ * ## Typical flow
+ *
+ * 1. A library creates a trusted value with a private token:
+ *    `const trusted = createTrustedValue(secret, myToken)`
+ * 2. The trusted value is passed to external code, which can hold and forward
+ *    it but cannot inspect or alter its contents.
+ * 3. When the trusted value is returned, the library verifies authenticity and
+ *    extracts the inner value: `const secret = verifyTrustedValue(trusted, myToken)`
+ *
+ * @typeParam T - The type of the inner value. Defaults to `unknown`.
+ */
+export type TrustedValue<T = unknown> = {
+  readonly [__trustedValue]: T;
+};
+
+/**
+ * Internal implementation. Not exported — external code cannot instantiate.
+ *
+ * Security relies on:
+ * - Class not being exported (no `new` from outside)
+ * - `Object.freeze` on every instance (immutability)
+ * - Private fields (`#value`, `#originToken`) inaccessible from outside
+ * - `Object.freeze` on prototype (no prototype pollution)
+ */
+class TrustedValueImpl<T> implements TrustedValue<T> {
+  declare readonly [__trustedValue]: T;
+
+  readonly #value: unknown;
+  readonly #originToken: symbol;
+
+  constructor(value: unknown, originToken: symbol) {
+    this.#value = value;
+    this.#originToken = originToken;
+    Object.freeze(this);
+  }
+
+  public static verify<T>(trustedValue: TrustedValue<T>, token: symbol): T {
+    if (!(trustedValue instanceof TrustedValueImpl)) {
+      throw new Error('Invalid TrustedValue');
+    }
+    if (token !== trustedValue.#originToken) {
+      throw new Error('Token mismatch');
+    }
+    return trustedValue.#value as T;
+  }
+
+  /**
+   * Safe string representation that does not expose the value.
+   */
+  public toString(): string {
+    return 'TrustedValue';
+  }
+
+  /**
+   * Safe JSON serialization that does not expose the value.
+   */
+  public toJSON(): string {
+    return 'TrustedValue';
+  }
+}
+
+Object.freeze(TrustedValueImpl.prototype);
+Object.freeze(TrustedValueImpl);
+
+/**
+ * Creates a new {@link TrustedValue} bound to the given token.
+ *
+ * Only the holder of `token` can later extract the inner value
+ * via {@link verifyTrustedValue}.
+ *
+ * @param value - The value to wrap.
+ * @param token - A `symbol` that acts as the authenticity key.
+ * @returns A frozen, opaque {@link TrustedValue} instance.
+ */
+export function createTrustedValue<T>(value: T, token: symbol): TrustedValue<T> {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+  return new TrustedValueImpl<T>(value, token);
+}
+
+/**
+ * Verifies authenticity and extracts the inner value from a {@link TrustedValue}.
+ *
+ * @param trustedValue - The trusted value to verify.
+ * @param token - The same `symbol` used at creation time.
+ * @returns The original inner value of type `T`.
+ * @throws {Error} `"Invalid TrustedValue"` if the argument is not a genuine
+ *   {@link TrustedValue} instance.
+ * @throws {Error} `"Token mismatch"` if the token does not match the one
+ *   used at creation time.
+ */
+export function verifyTrustedValue<T>(trustedValue: TrustedValue<T>, token: symbol): T {
+  return TrustedValueImpl.verify(trustedValue, token);
+}