ox 0.14.34 → 0.14.35

package/core/Ed25519.ts

@@ -4,8 +4,10 @@ import {
   edwardsToMontgomeryPub,
 } from '@noble/curves/ed25519'
 import * as Bytes from './Bytes.js'
-import type * as Errors from './Errors.js'
+import * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
+import * as keyDerivation from './internal/keyDerivation.js'
+import * as Mnemonic from './Mnemonic.js'
 
 /** Re-export of noble/curves Ed25519 utilities. */
 export const noble = ed25519
@@ -61,6 +63,115 @@ export declare namespace createKeyPair {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Derives an Ed25519 private key from a BIP-39 mnemonic.
+ *
+ * This is equivalent to passing `Mnemonic.toSeed(mnemonic, { passphrase })`
+ * to `Ed25519.fromSeed`.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Ed25519 } from 'ox'
+ *
+ * const privateKey = Ed25519.fromMnemonic(
+ *   'test test test test test test test test test test test junk'
+ * )
+ * ```
+ *
+ * @param mnemonic - BIP-39 mnemonic phrase.
+ * @param options - Options.
+ * @returns An Ed25519 private key.
+ */
+export function fromMnemonic<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  mnemonic: string,
+  options: fromMnemonic.Options<as> = {},
+): fromMnemonic.ReturnType<as> {
+  const { passphrase } = options
+  const seed = Mnemonic.toSeed(mnemonic, { passphrase })
+  try {
+    return fromSeed(seed, options)
+  } finally {
+    seed.fill(0)
+  }
+}
+
+export declare namespace fromMnemonic {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+    /** Optional BIP-39 passphrase. */
+    passphrase?: string | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> = fromSeed.ReturnType<as>
+
+  type ErrorType = fromSeed.ErrorType
+}
+
+/**
+ * Derives an Ed25519 private key from a seed.
+ *
+ * The seed must contain at least 32 bytes of cryptographically strong key
+ * material. Do not pass a password directly; use a password KDF first.
+ *
+ * The permanent derivation contract uses the seed as the HMAC-SHA256
+ * key. The HMAC message uses the `ox.ed25519.fromSeed.v1` domain followed by a
+ * 32-bit big-endian counter set to zero.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Ed25519 } from 'ox'
+ *
+ * const privateKey = Ed25519.fromSeed(
+ *   '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+ * )
+ * ```
+ *
+ * @param seed - Seed containing at least 32 bytes of cryptographically strong key material.
+ * @param options - Options.
+ * @returns An Ed25519 private key.
+ */
+export function fromSeed<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  seed: Hex.Hex | Bytes.Bytes,
+  options: fromSeed.Options<as> = {},
+): fromSeed.ReturnType<as> {
+  const { as = 'Hex' } = options
+  const bytes = Bytes.from(seed)
+  if (bytes.length < 32) throw new InvalidSeedSizeError({ size: bytes.length })
+
+  const privateKey = keyDerivation.derive(bytes, fromSeedDomain)
+  if (as === 'Hex') {
+    const value = Hex.fromBytes(privateKey)
+    privateKey.fill(0)
+    return value as never
+  }
+  return privateKey as never
+}
+
+export declare namespace fromSeed {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | keyDerivation.derive.ErrorType
+    | InvalidSeedSizeError
+    | Errors.GlobalErrorType
+}
+
 /**
  * Computes the Ed25519 public key from a provided private key.
  *
@@ -337,3 +448,24 @@ export declare namespace toX25519PrivateKey {
     | Hex.fromBytes.ErrorType
     | Errors.GlobalErrorType
 }
+
+/** Thrown when a seed contains fewer than 32 bytes. */
+export class InvalidSeedSizeError extends Errors.BaseError {
+  override readonly name = 'Ed25519.InvalidSeedSizeError'
+
+  constructor(options: InvalidSeedSizeError.Options) {
+    super(
+      `Seed must contain at least 32 bytes. Received ${options.size} bytes.`,
+    )
+  }
+}
+
+export declare namespace InvalidSeedSizeError {
+  /** Options for `Ed25519.InvalidSeedSizeError`. */
+  type Options = {
+    /** Received seed size. */
+    size: number
+  }
+}
+
+const fromSeedDomain = Bytes.fromString('ox.ed25519.fromSeed.v1')

package/core/P256.ts

@@ -1,8 +1,10 @@
 import { secp256r1 } from '@noble/curves/p256'
 import * as Bytes from './Bytes.js'
-import type * as Errors from './Errors.js'
+import * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
 import * as Entropy from './internal/entropy.js'
+import * as keyDerivation from './internal/keyDerivation.js'
+import * as Mnemonic from './Mnemonic.js'
 import * as PublicKey from './PublicKey.js'
 import type * as Signature from './Signature.js'
 
@@ -57,6 +59,117 @@ export declare namespace createKeyPair {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Derives a valid P256 private key from a BIP-39 mnemonic.
+ *
+ * This is equivalent to passing `Mnemonic.toSeed(mnemonic, { passphrase })`
+ * to `P256.fromSeed`.
+ *
+ * @example
+ * ```ts twoslash
+ * import { P256 } from 'ox'
+ *
+ * const privateKey = P256.fromMnemonic(
+ *   'test test test test test test test test test test test junk'
+ * )
+ * ```
+ *
+ * @param mnemonic - BIP-39 mnemonic phrase.
+ * @param options - Options.
+ * @returns A valid P256 private key.
+ */
+export function fromMnemonic<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  mnemonic: string,
+  options: fromMnemonic.Options<as> = {},
+): fromMnemonic.ReturnType<as> {
+  const { passphrase } = options
+  const seed = Mnemonic.toSeed(mnemonic, { passphrase })
+  try {
+    return fromSeed(seed, options)
+  } finally {
+    seed.fill(0)
+  }
+}
+
+export declare namespace fromMnemonic {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+    /** Optional BIP-39 passphrase. */
+    passphrase?: string | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> = fromSeed.ReturnType<as>
+
+  type ErrorType = fromSeed.ErrorType
+}
+
+/**
+ * Derives a valid P256 private key from a seed.
+ *
+ * The seed must contain at least 32 bytes of cryptographically strong key
+ * material. Do not pass a password directly; use a password KDF first.
+ *
+ * The permanent derivation contract uses the seed as the HMAC-SHA256
+ * key. The HMAC message uses the `ox.p256.fromSeed.v1` domain followed by a
+ * 32-bit big-endian counter starting at zero. Invalid scalars are skipped.
+ *
+ * @example
+ * ```ts twoslash
+ * import { P256 } from 'ox'
+ *
+ * const privateKey = P256.fromSeed(
+ *   '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+ * )
+ * ```
+ *
+ * @param seed - Seed containing at least 32 bytes of cryptographically strong key material.
+ * @param options - Options.
+ * @returns A valid P256 private key.
+ */
+export function fromSeed<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  seed: Hex.Hex | Bytes.Bytes,
+  options: fromSeed.Options<as> = {},
+): fromSeed.ReturnType<as> {
+  const { as = 'Hex' } = options
+  const bytes = Bytes.from(seed)
+  if (bytes.length < 32) throw new InvalidSeedSizeError({ size: bytes.length })
+
+  const privateKey = keyDerivation.derive(bytes, fromSeedDomain, {
+    validate: noble.utils.isValidPrivateKey,
+  })
+  if (as === 'Hex') {
+    const value = Hex.fromBytes(privateKey)
+    privateKey.fill(0)
+    return value as never
+  }
+  return privateKey as never
+}
+
+export declare namespace fromSeed {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | keyDerivation.derive.ErrorType
+    | InvalidSeedSizeError
+    | Errors.GlobalErrorType
+}
+
 /**
  * Computes the P256 ECDSA public key from a provided private key.
  *
@@ -354,3 +467,24 @@ export declare namespace verify {
 
   type ErrorType = Errors.GlobalErrorType
 }
+
+/** Thrown when a seed contains fewer than 32 bytes. */
+export class InvalidSeedSizeError extends Errors.BaseError {
+  override readonly name = 'P256.InvalidSeedSizeError'
+
+  constructor(options: InvalidSeedSizeError.Options) {
+    super(
+      `Seed must contain at least 32 bytes. Received ${options.size} bytes.`,
+    )
+  }
+}
+
+export declare namespace InvalidSeedSizeError {
+  /** Options for `P256.InvalidSeedSizeError`. */
+  type Options = {
+    /** Received seed size. */
+    size: number
+  }
+}
+
+const fromSeedDomain = Bytes.fromString('ox.p256.fromSeed.v1')

package/core/Secp256k1.ts

@@ -1,10 +1,12 @@
 import { secp256k1 } from '@noble/curves/secp256k1'
 import * as Address from './Address.js'
 import * as Bytes from './Bytes.js'
-import type * as Errors from './Errors.js'
+import * as Errors from './Errors.js'
 import * as Hex from './Hex.js'
 import * as Entropy from './internal/entropy.js'
+import * as keyDerivation from './internal/keyDerivation.js'
 import type { OneOf } from './internal/types.js'
+import * as Mnemonic from './Mnemonic.js'
 import * as PublicKey from './PublicKey.js'
 import type * as Signature from './Signature.js'
 
@@ -59,6 +61,115 @@ export declare namespace createKeyPair {
     | Errors.GlobalErrorType
 }
 
+/**
+ * Derives a valid secp256k1 private key from a BIP-39 mnemonic.
+ *
+ * This is equivalent to `Mnemonic.toPrivateKey`, and derives the
+ * private key at `m/44'/60'/0'/0/0` by default.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ *
+ * const privateKey = Secp256k1.fromMnemonic(
+ *   'test test test test test test test test test test test junk'
+ * )
+ * ```
+ *
+ * @param mnemonic - BIP-39 mnemonic phrase.
+ * @param options - Options.
+ * @returns A valid secp256k1 private key.
+ */
+export function fromMnemonic<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  mnemonic: string,
+  options: fromMnemonic.Options<as> = {},
+): fromMnemonic.ReturnType<as> {
+  const { as = 'Hex', passphrase, path } = options
+  return Mnemonic.toPrivateKey(mnemonic, { as, passphrase, path }) as never
+}
+
+export declare namespace fromMnemonic {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+    /** Derivation path. @default `m/44'/60'/0'/0/0` */
+    path?: string | undefined
+    /** Optional BIP-39 passphrase. */
+    passphrase?: string | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    Mnemonic.toPrivateKey.ReturnType<as>
+
+  type ErrorType = Mnemonic.toPrivateKey.ErrorType
+}
+
+/**
+ * Derives a valid secp256k1 private key from a seed.
+ *
+ * The seed must contain at least 32 bytes of cryptographically strong key
+ * material. Do not pass a password directly; use a password KDF first.
+ *
+ * The permanent derivation contract uses the seed as the HMAC-SHA256
+ * key. The HMAC message uses the `ox.secp256k1.fromSeed.v1` domain followed by
+ * a 32-bit big-endian counter starting at zero. Invalid scalars are skipped.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Secp256k1 } from 'ox'
+ *
+ * const privateKey = Secp256k1.fromSeed(
+ *   '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f'
+ * )
+ * ```
+ *
+ * @param seed - Seed containing at least 32 bytes of cryptographically strong key material.
+ * @param options - Options.
+ * @returns A valid secp256k1 private key.
+ */
+export function fromSeed<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  seed: Hex.Hex | Bytes.Bytes,
+  options: fromSeed.Options<as> = {},
+): fromSeed.ReturnType<as> {
+  const { as = 'Hex' } = options
+  const bytes = Bytes.from(seed)
+  if (bytes.length < 32) throw new InvalidSeedSizeError({ size: bytes.length })
+
+  const privateKey = keyDerivation.derive(bytes, fromSeedDomain, {
+    validate: noble.utils.isValidPrivateKey,
+  })
+  if (as === 'Hex') {
+    const value = Hex.fromBytes(privateKey)
+    privateKey.fill(0)
+    return value as never
+  }
+  return privateKey as never
+}
+
+export declare namespace fromSeed {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex'> = {
+    /**
+     * Format of the returned private key.
+     * @default 'Hex'
+     */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes'> =
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+    | (as extends 'Hex' ? Hex.Hex : never)
+
+  type ErrorType =
+    | Bytes.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | keyDerivation.derive.ErrorType
+    | InvalidSeedSizeError
+    | Errors.GlobalErrorType
+}
+
 /**
  * Computes the secp256k1 ECDSA public key from a provided private key.
  *
@@ -423,3 +534,24 @@ export declare namespace verify {
 
   type ErrorType = Errors.GlobalErrorType
 }
+
+/** Thrown when a seed contains fewer than 32 bytes. */
+export class InvalidSeedSizeError extends Errors.BaseError {
+  override readonly name = 'Secp256k1.InvalidSeedSizeError'
+
+  constructor(options: InvalidSeedSizeError.Options) {
+    super(
+      `Seed must contain at least 32 bytes. Received ${options.size} bytes.`,
+    )
+  }
+}
+
+export declare namespace InvalidSeedSizeError {
+  /** Options for `Secp256k1.InvalidSeedSizeError`. */
+  type Options = {
+    /** Received seed size. */
+    size: number
+  }
+}
+
+const fromSeedDomain = Bytes.fromString('ox.secp256k1.fromSeed.v1')

package/core/internal/keyDerivation.ts

@@ -0,0 +1,33 @@
+import * as Bytes from '../Bytes.js'
+import type * as Errors from '../Errors.js'
+import * as Hash from '../Hash.js'
+
+/** @internal */
+export function derive(
+  seed: Bytes.Bytes,
+  domain: Bytes.Bytes,
+  options: derive.Options = {},
+): Bytes.Bytes {
+  const { validate } = options
+  for (let counter = 0; ; counter++) {
+    const key = Hash.hmac256(
+      seed,
+      Bytes.concat(domain, Bytes.fromNumber(counter, { size: 4 })),
+      { as: 'Bytes' },
+    )
+    if (!validate || validate(key)) return key
+    key.fill(0)
+  }
+}
+
+export declare namespace derive {
+  type Options = {
+    validate?: ((key: Bytes.Bytes) => boolean) | undefined
+  }
+
+  type ErrorType =
+    | Bytes.concat.ErrorType
+    | Bytes.fromNumber.ErrorType
+    | Hash.hmac256.ErrorType
+    | Errors.GlobalErrorType
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ox",
   "description": "Ethereum Standard Library",
-  "version": "0.14.34",
+  "version": "0.14.35",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",

package/tempo/MultisigConfig.test.ts

@@ -169,21 +169,21 @@ describe('assert / validate', () => {
     expect(MultisigConfig.validate({ threshold: 1, owners: [] })).toBe(false)
   })
 
-  test('accepts 50 owners', () => {
-    const owners = Array.from({ length: 50 }, (_, i) => ({
+  test('accepts 48 owners', () => {
+    const owners = Array.from({ length: 48 }, (_, i) => ({
       owner: `0x${(i + 1).toString(16).padStart(40, '0')}` as `0x${string}`,
       weight: 1,
     }))
     expect(
       MultisigConfig.validate({
-        threshold: MultisigConfig.maxThreshold,
+        threshold: MultisigConfig.maxSignatures,
         owners,
       }),
     ).toBe(true)
   })
 
   test('too many owners', () => {
-    const owners = Array.from({ length: 51 }, (_, i) => ({
+    const owners = Array.from({ length: 49 }, (_, i) => ({
       owner: `0x${(i + 1).toString(16).padStart(40, '0')}` as `0x${string}`,
       weight: 1,
     }))
@@ -199,11 +199,29 @@ describe('assert / validate', () => {
     ).toBe(false)
   })
 
-  test('threshold exceeds protocol maximum', () => {
+  test('accepts a uint8 threshold above the signature limit', () => {
+    expect(
+      MultisigConfig.validate({
+        threshold: 9,
+        owners: [{ owner: owner1, weight: 9 }],
+      }),
+    ).toBe(true)
+  })
+
+  test('accepts the maximum uint8 threshold', () => {
+    expect(
+      MultisigConfig.validate({
+        threshold: MultisigConfig.maxThreshold,
+        owners: [{ owner: owner1, weight: MultisigConfig.maxThreshold }],
+      }),
+    ).toBe(true)
+  })
+
+  test('threshold exceeds uint8 maximum', () => {
     expect(
       MultisigConfig.validate({
         threshold: MultisigConfig.maxThreshold + 1,
-        owners: [{ owner: owner1, weight: MultisigConfig.maxThreshold + 1 }],
+        owners: [{ owner: owner1, weight: MultisigConfig.maxThreshold }],
       }),
     ).toBe(false)
   })
@@ -226,6 +244,22 @@ describe('assert / validate', () => {
     ).toBe(false)
   })
 
+  test('threshold cannot require more than eight owners', () => {
+    const owners = Array.from({ length: 9 }, (_, i) => ({
+      owner: `0x${(i + 1).toString(16).padStart(40, '0')}` as `0x${string}`,
+      weight: 1,
+    }))
+    expect(MultisigConfig.validate({ threshold: 9, owners })).toBe(false)
+  })
+
+  test('threshold can be reached by eight of more than eight owners', () => {
+    const owners = Array.from({ length: 9 }, (_, i) => ({
+      owner: `0x${(i + 1).toString(16).padStart(40, '0')}` as `0x${string}`,
+      weight: i === 0 ? 2 : 1,
+    }))
+    expect(MultisigConfig.validate({ threshold: 9, owners })).toBe(true)
+  })
+
   test('total weight exceeds u8 max', () => {
     expect(
       MultisigConfig.validate({

package/tempo/MultisigConfig.ts

@@ -6,13 +6,13 @@ import * as Hex from '../core/Hex.js'
 import type { Compute, OneOf } from '../core/internal/types.js'
 
 /** Maximum number of owners allowed in a native multisig config. */
-export const maxOwners = 50
+export const maxOwners = 48
 
 /** Maximum threshold accepted by a native multisig config. */
-export const maxThreshold = 8
+export const maxThreshold = 0xff
 
 /** Maximum number of owner approvals in a native multisig signature. */
-export const maxSignatures = maxThreshold
+export const maxSignatures = 8
 
 /**
  * Maximum number of native multisig signatures in one nested authorization
@@ -72,7 +72,8 @@ export type Tuple = readonly [
  * Mirrors the Tempo `InitMultisig::validate` rules: owners non-empty and
  * `<= maxOwners`, strictly ascending unique nonzero owner addresses, nonzero
  * integer owner weights, integer `threshold` between `1` and `maxThreshold`,
- * total weight `<= 255` (u8 max), and `threshold <= total weight`.
+ * total weight `<= 255` (u8 max), and a threshold reachable by at most
+ * `maxSignatures` owners.
  *
  * @example
  * ```ts twoslash
@@ -105,6 +106,7 @@ export function assert<numberType = number>(config: Config<numberType>): void {
     throw new InvalidConfigError({ reason: 'threshold exceeds max threshold' })
 
   let totalWeight = 0
+  const weights: number[] = []
   let previous: bigint | undefined
   for (const owner of owners) {
     if (!Address.validate(owner.owner) || Hex.toBigInt(owner.owner) === 0n)
@@ -123,7 +125,9 @@ export function assert<numberType = number>(config: Config<numberType>): void {
       })
     previous = current
 
-    totalWeight += Number(owner.weight)
+    const weight = Number(owner.weight)
+    totalWeight += weight
+    weights.push(weight)
   }
 
   if (totalWeight > 0xff)
@@ -134,6 +138,15 @@ export function assert<numberType = number>(config: Config<numberType>): void {
     throw new InvalidConfigError({
       reason: 'threshold exceeds total owner weight',
     })
+
+  const reachableWeight = weights
+    .sort((a, b) => b - a)
+    .slice(0, maxSignatures)
+    .reduce((sum, weight) => sum + weight, 0)
+  if (Number(threshold) > reachableWeight)
+    throw new InvalidConfigError({
+      reason: `threshold exceeds weight reachable by ${maxSignatures} owner signatures`,
+    })
 }
 
 export declare namespace assert {

package/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '0.14.34'
+export const version = '0.14.35'