@feelyourprotocol/util 8141.0.0

package/src/constants.ts

@@ -0,0 +1,125 @@
+import { secp256k1 } from '@noble/curves/secp256k1.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+
+import { hexToBytes } from './bytes.ts'
+
+/**
+ * 2^64-1
+ */
+export const MAX_UINT64 = BigInt('0xffffffffffffffff')
+
+/**
+ * The max integer that the evm can handle (2^256-1)
+ */
+export const MAX_INTEGER = BigInt(
+  '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff',
+)
+
+/**
+ * The max integer that the evm can handle (2^256-1) as a bigint
+ * 2^256-1 equals to 340282366920938463463374607431768211455
+ * We use literal value instead of calculated value for compatibility issue.
+ */
+export const MAX_INTEGER_BIGINT = BigInt(
+  '115792089237316195423570985008687907853269984665640564039457584007913129639935',
+)
+
+export const SECP256K1_ORDER = secp256k1.Point.CURVE().n
+export const SECP256K1_ORDER_DIV_2 = SECP256K1_ORDER / BigInt(2)
+
+/**
+ * 2^256
+ */
+export const TWO_POW256 = BigInt(
+  '0x10000000000000000000000000000000000000000000000000000000000000000',
+)
+
+/**
+ * Keccak-256 hash of null
+ */
+export const KECCAK256_NULL_S = '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470'
+
+/**
+ * Keccak-256 hash of null
+ */
+export const KECCAK256_NULL = hexToBytes(KECCAK256_NULL_S)
+
+/**
+ * Keccak-256 of an RLP of an empty array
+ */
+export const KECCAK256_RLP_ARRAY_S =
+  '0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347'
+
+/**
+ * Keccak-256 of an RLP of an empty array
+ */
+export const KECCAK256_RLP_ARRAY = hexToBytes(KECCAK256_RLP_ARRAY_S)
+
+/**
+ * Keccak-256 hash of the RLP of null
+ */
+export const KECCAK256_RLP_S = '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421'
+
+/**
+ * Keccak-256 hash of the RLP of null
+ */
+export const KECCAK256_RLP = hexToBytes(KECCAK256_RLP_S)
+
+export const SHA256_NULL = sha256(new Uint8Array())
+
+/**
+ *  RLP encoded empty string
+ */
+export const RLP_EMPTY_STRING = Uint8Array.from([0x80])
+
+export const MAX_WITHDRAWALS_PER_PAYLOAD = 16
+
+export const RIPEMD160_ADDRESS_STRING = '0000000000000000000000000000000000000003'
+
+/**
+ * System address used by various EIPs (EIP-2935, EIP-7002, EIP-7251, EIP-7708, BAL).
+ * Single canonical definition to avoid duplication across packages.
+ */
+export const SYSTEM_ADDRESS = '0xfffffffffffffffffffffffffffffffffffffffe'
+export const SYSTEM_ADDRESS_BYTES = hexToBytes(SYSTEM_ADDRESS)
+
+/**
+ * EIP-7934: RLP Execution Block Size Limit constants
+ * Maximum RLP-encoded block size to 10 MiB, with a 2 MiB margin for beacon block sizes
+ */
+export const MAX_BLOCK_SIZE = 10_485_760 // 10 MiB
+export const SAFETY_MARGIN = 2_097_152 // 2 MiB
+export const MAX_RLP_BLOCK_SIZE = MAX_BLOCK_SIZE - SAFETY_MARGIN // 8 MiB
+
+/**
+ * BigInt constants
+ */
+
+export const BIGINT_NEG1 = BigInt(-1)
+
+export const BIGINT_0 = BigInt(0)
+export const BIGINT_1 = BigInt(1)
+export const BIGINT_2 = BigInt(2)
+export const BIGINT_3 = BigInt(3)
+export const BIGINT_7 = BigInt(7)
+export const BIGINT_8 = BigInt(8)
+
+export const BIGINT_27 = BigInt(27)
+export const BIGINT_28 = BigInt(28)
+export const BIGINT_31 = BigInt(31)
+export const BIGINT_32 = BigInt(32)
+export const BIGINT_64 = BigInt(64)
+
+export const BIGINT_128 = BigInt(128)
+export const BIGINT_255 = BigInt(255)
+export const BIGINT_256 = BigInt(256)
+
+export const BIGINT_96 = BigInt(96)
+export const BIGINT_100 = BigInt(100)
+export const BIGINT_160 = BigInt(160)
+export const BIGINT_224 = BigInt(224)
+export const BIGINT_2EXP96 = BigInt(79228162514264337593543950336)
+export const BIGINT_2EXP160 = BigInt(1461501637330902918203684832716283019655932542976)
+export const BIGINT_2EXP224 =
+  BigInt(26959946667150639794667015087019630673637144422540572481103610249216)
+export const BIGINT_2EXP256 = BIGINT_2 ** BIGINT_256

package/src/db.ts

@@ -0,0 +1,86 @@
+export type DBObject = {
+  [key: string]: string | string[] | number
+}
+export type BatchDBOp<
+  TKey extends Uint8Array | string | number = Uint8Array,
+  TValue extends Uint8Array | string | DBObject = Uint8Array,
+> = PutBatch<TKey, TValue> | DelBatch<TKey>
+
+export type KeyEncoding = (typeof KeyEncoding)[keyof typeof KeyEncoding]
+
+export const KeyEncoding = {
+  String: 'string',
+  Bytes: 'view',
+  Number: 'number',
+} as const
+
+export type ValueEncoding = (typeof ValueEncoding)[keyof typeof ValueEncoding]
+
+export const ValueEncoding = {
+  String: 'string',
+  Bytes: 'view',
+  JSON: 'json',
+} as const
+
+export type EncodingOpts = {
+  keyEncoding?: KeyEncoding
+  valueEncoding?: ValueEncoding
+}
+export interface PutBatch<
+  TKey extends Uint8Array | string | number = Uint8Array,
+  TValue extends Uint8Array | string | DBObject = Uint8Array,
+> {
+  type: 'put'
+  key: TKey
+  value: TValue
+  opts?: EncodingOpts
+}
+
+export interface DelBatch<TKey extends Uint8Array | string | number = Uint8Array> {
+  type: 'del'
+  key: TKey
+  opts?: EncodingOpts
+}
+
+export interface DB<
+  TKey extends Uint8Array | string | number = Uint8Array,
+  TValue extends Uint8Array | string | DBObject = Uint8Array,
+> {
+  /**
+   * Retrieves a raw value from db.
+   * @param key
+   * @returns A Promise that resolves to `Uint8Array` if a value is found or `undefined` if no value is found.
+   */
+  get(key: TKey, opts?: EncodingOpts): Promise<TValue | undefined>
+
+  /**
+   * Writes a value directly to db.
+   * @param key The key as a `TValue`
+   * @param value The value to be stored
+   */
+  put(key: TKey, val: TValue, opts?: EncodingOpts): Promise<void>
+
+  /**
+   * Removes a raw value in the underlying db.
+   * @param keys
+   */
+  del(key: TKey, opts?: EncodingOpts): Promise<void>
+
+  /**
+   * Performs a batch operation on db.
+   * @param opStack A stack of levelup operations
+   */
+  batch(opStack: BatchDBOp<TKey, TValue>[]): Promise<void>
+
+  /**
+   * Returns a copy of the DB instance, with a reference
+   * to the **same** underlying db instance.
+   */
+  shallowCopy(): DB<TKey, TValue>
+
+  /**
+   * Opens the database -- if applicable
+   */
+  open(): Promise<void>
+  // TODO - decide if we actually need open/close - it's not required for maps and Level automatically opens the DB when you instantiate it
+}

package/src/env.ts

@@ -0,0 +1,9 @@
+/**
+ * Safely checks if debug logging is enabled for the given namespace string.
+ * Works in Node.js, browser main thread, web workers, and service workers.
+ *
+ * Uses `globalThis.process` to avoid ReferenceError in environments where
+ * `process` is not a declared global (e.g., web workers, service workers).
+ */
+export const isDebugEnabled = (namespace: string): boolean =>
+  globalThis.process?.env?.DEBUG?.includes(namespace) ?? false

package/src/errors.ts

@@ -0,0 +1,28 @@
+import {
+  DEFAULT_ERROR_CODE,
+  EthereumJSError,
+  type EthereumJSErrorMetaData,
+  type EthereumJSErrorObject,
+  EthereumJSErrorWithoutCode,
+} from '@feelyourprotocol/rlp'
+
+export {
+  DEFAULT_ERROR_CODE,
+  EthereumJSError,
+  EthereumJSErrorWithoutCode,
+  type EthereumJSErrorMetaData,
+  type EthereumJSErrorObject,
+}
+
+// Below here: specific monorepo-wide errors (examples and commented out)
+
+/*export enum UsageErrorType {
+  UNSUPPORTED_FEATURE = 'unsupported feature',
+}*
+
+/**
+ * Error along API Usage
+ *
+ * Use directly or in a subclassed context for error comparison (`e instanceof UsageError`)
+ */
+//export class UsageError extends EthereumJSError<{ code: UsageErrorType }> {}

package/src/helpers.ts

@@ -0,0 +1,46 @@
+import { EthereumJSErrorWithoutCode } from './errors.ts'
+import { isHexString } from './internal.ts'
+
+/**
+ * Throws if a string is not hex prefixed
+ * @param {string} input string to check hex prefix of
+ */
+export const assertIsHexString = function (input: string): void {
+  if (!isHexString(input)) {
+    const msg = `This method only supports 0x-prefixed hex strings but input was: ${input}`
+    throw EthereumJSErrorWithoutCode(msg)
+  }
+}
+
+/**
+ * Throws if input is not a buffer
+ * @param {Buffer} input value to check
+ */
+export const assertIsBytes = function (input: Uint8Array): void {
+  if (!(input instanceof Uint8Array)) {
+    const msg = `This method only supports Uint8Array but input was: ${input}`
+    throw EthereumJSErrorWithoutCode(msg)
+  }
+}
+
+/**
+ * Throws if input is not an array
+ * @param {number[]} input value to check
+ */
+export const assertIsArray = function (input: number[]): void {
+  if (!Array.isArray(input)) {
+    const msg = `This method only supports number arrays but input was: ${input}`
+    throw EthereumJSErrorWithoutCode(msg)
+  }
+}
+
+/**
+ * Throws if input is not a string
+ * @param {string} input value to check
+ */
+export const assertIsString = function (input: string): void {
+  if (typeof input !== 'string') {
+    const msg = `This method only supports strings but input was: ${input}`
+    throw EthereumJSErrorWithoutCode(msg)
+  }
+}

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * Constants
+ */
+export * from './constants.ts'
+
+/**
+ * Errors
+ */
+export * from './errors.ts'
+
+/**
+ * Units helpers
+ */
+export * from './units.ts'
+
+/**
+ * Account class and helper functions
+ */
+export * from './account.ts'
+
+/**
+ * Block level access list
+ *
+ * EXPERIMENTAL: DO NOT USE IN PRODUCTION!
+ */
+export * from './bal.ts'
+
+/**
+ * Address type
+ */
+export * from './address.ts'
+
+/**
+ * DB type
+ */
+export * from './db.ts'
+
+/**
+ * Withdrawal type
+ */
+export * from './withdrawal.ts'
+
+/**
+ * ECDSA signature
+ */
+export * from './signature.ts'
+
+/**
+ * Utilities for manipulating bytes, Uint8Arrays, etc.
+ */
+export * from './bytes.ts'
+
+/**
+ * Helpful TypeScript types
+ */
+export * from './types.ts'
+
+/**
+ * Block level access list
+ *
+ * EXPERIMENTAL: DO NOT USE IN PRODUCTION!
+ */
+export * from './bal.ts'
+
+/**
+ * Export ethjs-util methods
+ */
+export * from './authorization.ts'
+export * from './env.ts'
+export * from './binaryTree.ts'
+export * from './blobs.ts'
+export {
+  arrayContainsArray,
+  fromAscii,
+  fromUtf8,
+  getBinarySize,
+  getKeys,
+  isHexString,
+  padToEven,
+  stripHexPrefix,
+  toAscii,
+} from './internal.ts'
+export * from './kzg.ts'
+export * from './lock.ts'
+export * from './mapDB.ts'
+export * from './provider.ts'
+export * from './request.ts'
+export * from './tasks.ts'

package/src/internal.ts

@@ -0,0 +1,212 @@
+/*
+The MIT License
+
+Copyright (c) 2016 Nick Dodson. nickdodson.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE
+ */
+
+import { bytesToUnprefixedHex, utf8ToBytes } from './bytes.ts'
+import { EthereumJSErrorWithoutCode } from './errors.ts'
+
+import type { PrefixedHexString } from './types.ts'
+
+/**
+ * Returns a boolean on whether or not the the input starts with '0x' and matches the optional length
+ * @param {string} value the string input value
+ * @param {number|undefined} length the optional length of the hex string in bytes
+ * @returns {boolean} Whether or not the string is a valid PrefixedHexString matching the optional length
+ */
+export function isHexString(value: string, length?: number): value is PrefixedHexString {
+  if (typeof value !== 'string' || !value.match(/^0x[0-9A-Fa-f]*$/)) return false
+
+  if (typeof length !== 'undefined' && length > 0 && value.length !== 2 + 2 * length) return false
+
+  return true
+}
+
+/**
+ * Removes '0x' from a given `String` if present
+ * @param str the string value
+ * @returns the string without 0x prefix
+ */
+export const stripHexPrefix = (str: string): string => {
+  if (typeof str !== 'string')
+    throw EthereumJSErrorWithoutCode(
+      `[stripHexPrefix] input must be type 'string', received ${typeof str}`,
+    )
+
+  return isHexString(str) ? str.slice(2) : str
+}
+
+/**
+ * Pads a `String` to have an even length
+ * @param value
+ * @return output
+ */
+export function padToEven(value: string): string {
+  let a = value
+
+  if (typeof a !== 'string') {
+    throw EthereumJSErrorWithoutCode(
+      `[padToEven] value must be type 'string', received ${typeof a}`,
+    )
+  }
+
+  if (a.length % 2) a = `0${a}`
+
+  return a
+}
+
+/**
+ * Get the binary size of a string
+ * @param str
+ * @returns the number of bytes contained within the string
+ */
+export function getBinarySize(str: string) {
+  if (typeof str !== 'string') {
+    throw EthereumJSErrorWithoutCode(
+      `[getBinarySize] method requires input type 'string', received ${typeof str}`,
+    )
+  }
+
+  return utf8ToBytes(str).byteLength
+}
+
+/**
+ * Returns TRUE if the first specified array contains all elements
+ * from the second one. FALSE otherwise.
+ *
+ * @param superset
+ * @param subset
+ *
+ */
+export function arrayContainsArray(
+  superset: unknown[],
+  subset: unknown[],
+  some?: boolean,
+): boolean {
+  if (Array.isArray(superset) !== true) {
+    throw EthereumJSErrorWithoutCode(
+      `[arrayContainsArray] method requires input 'superset' to be an array, got type '${typeof superset}'`,
+    )
+  }
+  if (Array.isArray(subset) !== true) {
+    throw EthereumJSErrorWithoutCode(
+      `[arrayContainsArray] method requires input 'subset' to be an array, got type '${typeof subset}'`,
+    )
+  }
+
+  return subset[some === true ? 'some' : 'every']((value) => superset.indexOf(value) >= 0)
+}
+
+/**
+ * Should be called to get ascii from its hex representation
+ *
+ * @param string in hex
+ * @returns ascii string representation of hex value
+ */
+export function toAscii(hex: string): string {
+  let str = ''
+  let i = 0
+  const l = hex.length
+
+  if (hex.substring(0, 2) === '0x') i = 2
+
+  for (; i < l; i += 2) {
+    const code = parseInt(hex.substr(i, 2), 16)
+    str += String.fromCharCode(code)
+  }
+
+  return str
+}
+
+/**
+ * Should be called to get hex representation (prefixed by 0x) of utf8 string.
+ * Strips leading and trailing 0's.
+ *
+ * @param string
+ * @param optional padding
+ * @returns hex representation of input string
+ */
+export function fromUtf8(stringValue: string) {
+  const str = utf8ToBytes(stringValue)
+
+  // Using deprecated bytesToUnprefixedHex for performance: we're building a hex string with 0x prefix,
+  // so using bytesToUnprefixedHex avoids creating an intermediate prefixed string and then stripping it.
+  return `0x${padToEven(bytesToUnprefixedHex(str)).replace(/^0+|0+$/g, '')}`
+}
+
+/**
+ * Should be called to get hex representation (prefixed by 0x) of ascii string
+ *
+ * @param  string
+ * @param  optional padding
+ * @returns  hex representation of input string
+ */
+export function fromAscii(stringValue: string) {
+  let hex = ''
+  for (let i = 0; i < stringValue.length; i++) {
+    const code = stringValue.charCodeAt(i)
+    const n = code.toString(16)
+    hex += n.length < 2 ? `0${n}` : n
+  }
+
+  return `0x${hex}`
+}
+
+/**
+ * Returns the keys from an array of objects.
+ * @example
+ * ```js
+ * getKeys([{a: '1', b: '2'}, {a: '3', b: '4'}], 'a') => ['1', '3']
+ *````
+ * @param  params
+ * @param  key
+ * @param  allowEmpty
+ * @returns output just a simple array of output keys
+ */
+export function getKeys(params: Record<string, string>[], key: string, allowEmpty?: boolean) {
+  if (!Array.isArray(params)) {
+    throw EthereumJSErrorWithoutCode(
+      `[getKeys] method expects input 'params' to be an array, got ${typeof params}`,
+    )
+  }
+  if (typeof key !== 'string') {
+    throw EthereumJSErrorWithoutCode(
+      `[getKeys] method expects input 'key' to be type 'string', got ${typeof params}`,
+    )
+  }
+
+  const result = []
+
+  for (let i = 0; i < params.length; i++) {
+    let value = params[i][key]
+    if (allowEmpty === true && !value) {
+      value = ''
+    } else if (typeof value !== 'string') {
+      throw EthereumJSErrorWithoutCode(
+        `invalid abi - expected type 'string', received ${typeof value}`,
+      )
+    }
+    result.push(value)
+  }
+
+  return result
+}

package/src/kzg.ts

@@ -0,0 +1,24 @@
+/**
+ * Interface for an externally provided kzg library used when creating blob transactions
+ */
+export interface KZG {
+  // eip-4844
+  blobToKzgCommitment(blob: string): string
+  computeBlobProof(blob: string, commitment: string): string
+  verifyProof(polynomialKZG: string, z: string, y: string, KZGProof: string): boolean
+  verifyBlobProofBatch(
+    blobs: string[],
+    expectedKZGCommitments: string[],
+    KZGProofs: string[],
+  ): boolean
+  // eip-7594
+  computeCells(blob: string): string[]
+  computeCellsAndProofs(blob: string): [string[], string[]]
+  recoverCellsAndProofs(indices: number[], cells: string[]): [string[], string[]]
+  verifyCellKzgProofBatch(
+    commitments: string[],
+    indices: number[],
+    cells: string[],
+    proofs: string[],
+  ): boolean
+}

package/src/lock.ts

@@ -0,0 +1,42 @@
+// Based on https://github.com/jsoendermann/semaphore-async-await/blob/master/src/Semaphore.ts
+export class Lock {
+  private permits: number = 1
+  private promiseResolverQueue: Array<(v: boolean) => void> = []
+
+  /**
+   * Returns a promise used to wait for a permit to become available. This method should be awaited on.
+   * @returns  A promise that gets resolved when execution is allowed to proceed.
+   */
+  public async acquire(): Promise<boolean> {
+    if (this.permits > 0) {
+      this.permits -= 1
+      return Promise.resolve(true)
+    }
+
+    // If there is no permit available, we return a promise that resolves once the semaphore gets
+    // signaled enough times that permits is equal to one.
+    return new Promise<boolean>((resolver) => this.promiseResolverQueue.push(resolver))
+  }
+
+  /**
+   * Increases the number of permits by one. If there are other functions waiting, one of them will
+   * continue to execute in a future iteration of the event loop.
+   */
+  public release(): void {
+    this.permits += 1
+
+    if (this.permits > 1 && this.promiseResolverQueue.length > 0) {
+      // eslint-disable-next-line no-console
+      console.warn('Lock.permits should never be > 0 when there is someone waiting.')
+    } else if (this.permits === 1 && this.promiseResolverQueue.length > 0) {
+      // If there is someone else waiting, immediately consume the permit that was released
+      // at the beginning of this function and let the waiting function resume.
+      this.permits -= 1
+
+      const nextResolver = this.promiseResolverQueue.shift()
+      if (nextResolver) {
+        nextResolver(true)
+      }
+    }
+  }
+}