ox 0.6.12 → 0.7.1

package/core/Keystore.ts

@@ -0,0 +1,414 @@
+import { ctr } from '@noble/ciphers/aes'
+import {
+  pbkdf2Async as pbkdf2Async_noble,
+  pbkdf2 as pbkdf2_noble,
+} from '@noble/hashes/pbkdf2'
+import {
+  scryptAsync as scryptAsync_noble,
+  scrypt as scrypt_noble,
+} from '@noble/hashes/scrypt'
+import { sha256 } from '@noble/hashes/sha2'
+import * as Bytes from './Bytes.js'
+import type * as Errors from './Errors.js'
+import * as Hash from './Hash.js'
+import type * as Hex from './Hex.js'
+
+/** Base Key. */
+type BaseKey<
+  kdf extends string = string,
+  kdfparams extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  iv: Bytes.Bytes
+  key: () => string
+  kdfparams: kdfparams
+  kdf: kdf
+}
+
+/** Keystore. */
+export type Keystore = {
+  crypto: {
+    cipher: 'aes-128-ctr'
+    ciphertext: string
+    cipherparams: {
+      iv: string
+    }
+    mac: string
+  } & Pick<Key, 'kdf' | 'kdfparams'>
+  id: string
+  version: 3
+}
+
+/** Key. */
+export type Key = Pbkdf2Key | ScryptKey
+
+/** PBKDF2 Key. */
+export type Pbkdf2Key = BaseKey<
+  'pbkdf2',
+  {
+    c: number
+    dklen: number
+    prf: 'hmac-sha256'
+    salt: string
+  }
+>
+
+/** Scrypt Key. */
+export type ScryptKey = BaseKey<
+  'scrypt',
+  {
+    dklen: number
+    n: number
+    p: number
+    r: number
+    salt: string
+  }
+>
+
+/**
+ * Decrypts a [JSON keystore](https://ethereum.org/en/developers/docs/data-structures-and-encoding/web3-secret-storage/)
+ * into a private key.
+ *
+ * Supports the following key derivation functions (KDFs):
+ * - {@link ox#Keystore.(pbkdf2:function)}
+ * - {@link ox#Keystore.(scrypt:function)}
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { Keystore, Secp256k1 } from 'ox'
+ *
+ * // JSON keystore.
+ * const keystore = { crypto: { ... }, id: '...', version: 3 }
+ *
+ * // Derive key from password.
+ * const key = Keystore.pbkdf2({ password: 'testpassword' })
+ *
+ * // Decrypt the private key.
+ * const privateKey = await Keystore.decrypt(keystore, key)
+ * // @log: "0x..."
+ * ```
+ *
+ * @param keystore - JSON keystore.
+ * @param key - Key to use for decryption.
+ * @param options - Decryption options.
+ * @returns Decrypted private key.
+ */
+export async function decrypt<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  keystore: Keystore,
+  key: Key,
+  options: decrypt.Options<as> = {},
+): Promise<decrypt.ReturnType<as>> {
+  const { as = 'Hex' } = options
+  const key_ = Bytes.from(`0x${key.key()}`)
+
+  const encKey = Bytes.slice(key_, 0, 16)
+  const macKey = Bytes.slice(key_, 16, 32)
+
+  const ciphertext = Bytes.from(`0x${keystore.crypto.ciphertext}`)
+  const mac = Hash.keccak256(Bytes.concat(macKey, ciphertext))
+
+  if (!Bytes.isEqual(mac, Bytes.from(`0x${keystore.crypto.mac}`)))
+    throw new Error('corrupt keystore')
+
+  const data = ctr(encKey, key.iv).decrypt(ciphertext)
+
+  if (as === 'Hex') return Bytes.toHex(data) as never
+  return data as never
+}
+
+export declare namespace decrypt {
+  type Options<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> = {
+    /** Output format. @default 'Hex' */
+    as?: as | 'Hex' | 'Bytes' | undefined
+  }
+
+  type ReturnType<as extends 'Hex' | 'Bytes' = 'Hex' | 'Bytes'> =
+    | (as extends 'Hex' ? Hex.Hex : never)
+    | (as extends 'Bytes' ? Bytes.Bytes : never)
+}
+
+/**
+ * Encrypts a private key as a [JSON keystore](https://ethereum.org/en/developers/docs/data-structures-and-encoding/web3-secret-storage/)
+ * using a derived key.
+ *
+ * Supports the following key derivation functions (KDFs):
+ * - {@link ox#Keystore.(pbkdf2:function)}
+ * - {@link ox#Keystore.(scrypt:function)}
+ *
+ * @example
+ * ```ts twoslash
+ * import { Keystore, Secp256k1 } from 'ox'
+ *
+ * // Generate a random private key.
+ * const privateKey = Secp256k1.randomPrivateKey()
+ *
+ * // Derive key from password.
+ * const key = Keystore.pbkdf2({ password: 'testpassword' })
+ *
+ * // Encrypt the private key.
+ * const encrypted = await Keystore.encrypt(privateKey, key)
+ * // @log: {
+ * // @log:   "crypto": {
+ * // @log:     "cipher": "aes-128-ctr",
+ * // @log:     "ciphertext": "...",
+ * // @log:     "cipherparams": {
+ * // @log:       "iv": "...",
+ * // @log:     },
+ * // @log:     "kdf": "pbkdf2",
+ * // @log:     "kdfparams": {
+ * // @log:       "salt": "...",
+ * // @log:       "dklen": 32,
+ * // @log:       "prf": "hmac-sha256",
+ * // @log:       "c": 262144,
+ * // @log:     },
+ * // @log:     "mac": "...",
+ * // @log:   },
+ * // @log:   "id": "...",
+ * // @log:   "version": 3,
+ * // @log: }
+ * ```
+ *
+ * @param privateKey - Private key to encrypt.
+ * @param key - Key to use for encryption.
+ * @param options - Encryption options.
+ * @returns Encrypted keystore.
+ */
+export async function encrypt(
+  privateKey: Bytes.Bytes | Hex.Hex,
+  key: Key,
+  options: encrypt.Options = {},
+): Promise<Keystore> {
+  const { id = crypto.randomUUID() } = options
+
+  const key_ = Bytes.from(`0x${key.key()}`)
+  const value_ = Bytes.from(privateKey)
+
+  const encKey = Bytes.slice(key_, 0, 16)
+  const macKey = Bytes.slice(key_, 16, 32)
+
+  const ciphertext = ctr(encKey, key.iv).encrypt(value_)
+  const mac = Hash.keccak256(Bytes.concat(macKey, ciphertext))
+
+  return {
+    crypto: {
+      cipher: 'aes-128-ctr',
+      ciphertext: Bytes.toHex(ciphertext).slice(2),
+      cipherparams: { iv: Bytes.toHex(key.iv).slice(2) },
+      kdf: key.kdf,
+      kdfparams: key.kdfparams,
+      mac: Bytes.toHex(mac).slice(2),
+    } as Keystore['crypto'],
+    id,
+    version: 3,
+  }
+}
+
+export declare namespace encrypt {
+  type Options = {
+    /** UUID. */
+    id?: string | undefined
+  }
+}
+
+/**
+ * Derives a key from a password using [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2).
+ *
+ * @example
+ * ```ts twoslash
+ * import { Keystore } from 'ox'
+ *
+ * const key = Keystore.pbkdf2({ password: 'testpassword' })
+ * ```
+ *
+ * @param options - PBKDF2 options.
+ * @returns PBKDF2 key.
+ */
+export function pbkdf2(options: pbkdf2.Options) {
+  const { iv, iterations = 262_144, password } = options
+
+  const salt = options.salt ? Bytes.from(options.salt) : Bytes.random(32)
+  const key = Bytes.toHex(
+    pbkdf2_noble(sha256, password, salt, { c: iterations, dkLen: 32 }),
+  ).slice(2)
+
+  return defineKey({
+    iv,
+    key: () => key,
+    kdfparams: {
+      c: iterations,
+      dklen: 32,
+      prf: 'hmac-sha256',
+      salt: Bytes.toHex(salt).slice(2),
+    },
+    kdf: 'pbkdf2',
+  }) satisfies Pbkdf2Key
+}
+
+export declare namespace pbkdf2 {
+  type Options = {
+    /** The counter to use for the AES-CTR encryption. */
+    iv?: Bytes.Bytes | Hex.Hex | undefined
+    /** The number of iterations to use. @default 262_144 */
+    iterations?: number | undefined
+    /** Password to derive key from. */
+    password: string
+    /** Salt to use for key derivation. @default `Bytes.random(32)` */
+    salt?: Bytes.Bytes | Hex.Hex | undefined
+  }
+}
+
+/**
+ * Derives a key from a password using [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2).
+ *
+ * @example
+ * ```ts twoslash
+ * import { Keystore } from 'ox'
+ *
+ * const key = await Keystore.pbkdf2Async({ password: 'testpassword' })
+ * ```
+ *
+ * @param options - PBKDF2 options.
+ * @returns PBKDF2 key.
+ */
+export async function pbkdf2Async(options: pbkdf2.Options) {
+  const { iv, iterations = 262_144, password } = options
+
+  const salt = options.salt ? Bytes.from(options.salt) : Bytes.random(32)
+  const key = Bytes.toHex(
+    await pbkdf2Async_noble(sha256, password, salt, {
+      c: iterations,
+      dkLen: 32,
+    }),
+  ).slice(2)
+
+  return defineKey({
+    iv,
+    key: () => key,
+    kdfparams: {
+      c: iterations,
+      dklen: 32,
+      prf: 'hmac-sha256',
+      salt: Bytes.toHex(salt).slice(2),
+    },
+    kdf: 'pbkdf2',
+  }) satisfies Pbkdf2Key
+}
+
+export declare namespace pbkdf2Async {
+  type Options = pbkdf2.Options
+}
+
+/**
+ * Derives a key from a password using [scrypt](https://en.wikipedia.org/wiki/Scrypt).
+ *
+ * @example
+ * ```ts twoslash
+ * import { Keystore } from 'ox'
+ *
+ * const key = Keystore.scrypt({ password: 'testpassword' })
+ * ```
+ *
+ * @param options - Scrypt options.
+ * @returns Scrypt key.
+ */
+export function scrypt(options: scrypt.Options) {
+  const { iv, n = 262_144, password } = options
+
+  const p = 8
+  const r = 1
+
+  const salt = options.salt ? Bytes.from(options.salt) : Bytes.random(32)
+  const key = Bytes.toHex(
+    scrypt_noble(password, salt, { N: n, dkLen: 32, r, p }),
+  ).slice(2)
+
+  return defineKey({
+    iv,
+    key: () => key,
+    kdfparams: {
+      dklen: 32,
+      n,
+      p,
+      r,
+      salt: Bytes.toHex(salt).slice(2),
+    },
+    kdf: 'scrypt',
+  }) satisfies ScryptKey
+}
+
+export declare namespace scrypt {
+  type Options = {
+    /** The counter to use for the AES-CTR encryption. */
+    iv?: Bytes.Bytes | Hex.Hex | undefined
+    /** Cost factor. @default 262_144 */
+    n?: number | undefined
+    /** Password to derive key from. */
+    password: string
+    /** Salt to use for key derivation. @default `Bytes.random(32)` */
+    salt?: Bytes.Bytes | Hex.Hex | undefined
+  }
+}
+
+/**
+ * Derives a key from a password using [scrypt](https://en.wikipedia.org/wiki/Scrypt).
+ *
+ * @example
+ * ```ts twoslash
+ * import { Keystore } from 'ox'
+ *
+ * const key = await Keystore.scryptAsync({ password: 'testpassword' })
+ * ```
+ *
+ * @param options - Scrypt options.
+ * @returns Scrypt key.
+ */
+export async function scryptAsync(options: scrypt.Options) {
+  const { iv, n = 262_144, password } = options
+
+  const p = 8
+  const r = 1
+
+  const salt = options.salt ? Bytes.from(options.salt) : Bytes.random(32)
+  const key = Bytes.toHex(
+    await scryptAsync_noble(password, salt, { N: n, dkLen: 32, r, p }),
+  ).slice(2)
+
+  return defineKey({
+    iv,
+    key: () => key,
+    kdfparams: {
+      dklen: 32,
+      n,
+      p,
+      r,
+      salt: Bytes.toHex(salt).slice(2),
+    },
+    kdf: 'scrypt',
+  }) satisfies ScryptKey
+}
+
+export declare namespace scryptAsync {
+  type Options = scrypt.Options
+}
+
+///////////////////////////////////////////////////////////////////////////
+
+/** @internal */
+function defineKey<const key extends defineKey.Value>(
+  key: key,
+): key & { iv: Bytes.Bytes } {
+  const iv = key.iv ? Bytes.from(key.iv) : Bytes.random(16)
+  return { ...key, iv }
+}
+
+/** @internal */
+declare namespace defineKey {
+  type Value<
+    kdf extends string = string,
+    kdfparams extends Record<string, unknown> = Record<string, unknown>,
+  > = Omit<BaseKey<kdf, kdfparams>, 'iv'> & {
+    iv?: Bytes.Bytes | Hex.Hex | undefined
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}

package/core/Provider.ts

@@ -154,6 +154,110 @@ export class ChainDisconnectedError extends ProviderRpcError {
   }
 }
 
+/** An error occurred when attempting to switch chain. */
+export class SwitchChainError extends ProviderRpcError {
+  static readonly code = 4902
+  override readonly code = 4902
+  override readonly name = 'Provider.SwitchChainError'
+
+  constructor({
+    message = 'An error occurred when attempting to switch chain.',
+  }: { message?: string | undefined } = {}) {
+    super(4902, message)
+  }
+}
+
+/** This Wallet does not support a capability that was not marked as optional. */
+export class UnsupportedNonOptionalCapabilityError extends ProviderRpcError {
+  static readonly code = 5700
+  override readonly code = 5700
+  override readonly name = 'Provider.UnsupportedNonOptionalCapabilityError'
+
+  constructor({
+    message = 'This Wallet does not support a capability that was not marked as optional.',
+  }: { message?: string | undefined } = {}) {
+    super(5700, message)
+  }
+}
+
+/** This Wallet does not support the requested chain ID. */
+export class UnsupportedChainIdError extends ProviderRpcError {
+  static readonly code = 5710
+  override readonly code = 5710
+  override readonly name = 'Provider.UnsupportedChainIdError'
+
+  constructor({
+    message = 'This Wallet does not support the requested chain ID.',
+  }: { message?: string | undefined } = {}) {
+    super(5710, message)
+  }
+}
+
+/** There is already a bundle submitted with this ID. */
+export class DuplicateIdError extends ProviderRpcError {
+  static readonly code = 5720
+  override readonly code = 5720
+  override readonly name = 'Provider.DuplicateIdError'
+
+  constructor({
+    message = 'There is already a bundle submitted with this ID.',
+  }: { message?: string | undefined } = {}) {
+    super(5720, message)
+  }
+}
+
+/** This bundle id is unknown / has not been submitted. */
+export class UnknownBundleIdError extends ProviderRpcError {
+  static readonly code = 5730
+  override readonly code = 5730
+  override readonly name = 'Provider.UnknownBundleIdError'
+
+  constructor({
+    message = 'This bundle id is unknown / has not been submitted.',
+  }: { message?: string | undefined } = {}) {
+    super(5730, message)
+  }
+}
+
+/** The call bundle is too large for the Wallet to process. */
+export class BundleTooLargeError extends ProviderRpcError {
+  static readonly code = 5740
+  override readonly code = 5740
+  override readonly name = 'Provider.BundleTooLargeError'
+
+  constructor({
+    message = 'The call bundle is too large for the Wallet to process.',
+  }: { message?: string | undefined } = {}) {
+    super(5740, message)
+  }
+}
+
+/** The Wallet can support atomicity after an upgrade, but the user rejected the upgrade. */
+export class AtomicReadyWalletRejectedUpgradeError extends ProviderRpcError {
+  static readonly code = 5750
+  override readonly code = 5750
+  override readonly name = 'Provider.AtomicReadyWalletRejectedUpgradeError'
+
+  constructor({
+    message = 'The Wallet can support atomicity after an upgrade, but the user rejected the upgrade.',
+  }: { message?: string | undefined } = {}) {
+    super(5750, message)
+  }
+}
+
+/** The wallet does not support atomic execution but the request requires it. */
+export class AtomicityNotSupportedError extends ProviderRpcError {
+  static readonly code = 5760
+  override readonly code = 5760
+  override readonly name = 'Provider.AtomicityNotSupportedError'
+
+  constructor({
+    message = 'The wallet does not support atomic execution but the request requires it.',
+  }: { message?: string | undefined } = {}) {
+    super(5760, message)
+  }
+}
+
 /**
  * Creates an EIP-1193 flavored event emitter to be injected onto a Provider.
  *
@@ -447,6 +551,22 @@ export function parseError<
       return new UnauthorizedError(error_) as never
     if (code === UnsupportedMethodError.code)
       return new UnsupportedMethodError(error_) as never
+    if (code === SwitchChainError.code)
+      return new SwitchChainError(error_) as never
+    if (code === AtomicReadyWalletRejectedUpgradeError.code)
+      return new AtomicReadyWalletRejectedUpgradeError(error_) as never
+    if (code === AtomicityNotSupportedError.code)
+      return new AtomicityNotSupportedError(error_) as never
+    if (code === BundleTooLargeError.code)
+      return new BundleTooLargeError(error_) as never
+    if (code === UnknownBundleIdError.code)
+      return new UnknownBundleIdError(error_) as never
+    if (code === DuplicateIdError.code)
+      return new DuplicateIdError(error_) as never
+    if (code === UnsupportedChainIdError.code)
+      return new UnsupportedChainIdError(error_) as never
+    if (code === UnsupportedNonOptionalCapabilityError.code)
+      return new UnsupportedNonOptionalCapabilityError(error_) as never
   }
   return error_ as never
 }
@@ -487,6 +607,54 @@ export declare namespace parseError {
           | (IsNarrowable<errorObject['code'], number> extends false
               ? UnsupportedMethodError
               : never)
+          | (errorObject['code'] extends SwitchChainError['code']
+              ? SwitchChainError
+              : never)
+          | (IsNarrowable<errorObject['code'], number> extends false
+              ? SwitchChainError
+              : never)
+          | (errorObject['code'] extends AtomicReadyWalletRejectedUpgradeError['code']
+              ? AtomicReadyWalletRejectedUpgradeError
+              : never)
+          | (IsNarrowable<errorObject['code'], number> extends false
+              ? AtomicReadyWalletRejectedUpgradeError
+              : never)
+          | (errorObject['code'] extends AtomicityNotSupportedError['code']
+              ? AtomicityNotSupportedError
+              : never)
+          | (IsNarrowable<errorObject['code'], number> extends false
+              ? AtomicityNotSupportedError
+              : never)
+          | (errorObject['code'] extends BundleTooLargeError['code']
+              ? BundleTooLargeError
+              : never)
+          | (IsNarrowable<errorObject['code'], number> extends false
+              ? BundleTooLargeError
+              : never)
+          | (errorObject['code'] extends UnknownBundleIdError['code']
+              ? UnknownBundleIdError
+              : never)
+          | (IsNarrowable<errorObject['code'], number> extends false
+              ? UnknownBundleIdError
+              : never)
+          | (errorObject['code'] extends DuplicateIdError['code']
+              ? DuplicateIdError
+              : never)
+          | (IsNarrowable<errorObject['code'], number> extends false
+              ? DuplicateIdError
+              : never)
+          | (errorObject['code'] extends UnsupportedChainIdError['code']
+              ? UnsupportedChainIdError
+              : never)
+          | (IsNarrowable<errorObject['code'], number> extends false
+              ? UnsupportedChainIdError
+              : never)
+          | (errorObject['code'] extends UnsupportedNonOptionalCapabilityError['code']
+              ? UnsupportedNonOptionalCapabilityError
+              : never)
+          | (IsNarrowable<errorObject['code'], number> extends false
+              ? UnsupportedNonOptionalCapabilityError
+              : never)
       : RpcResponse.parseError.ReturnType<RpcResponse.ErrorObject>,
   > = IsNever<error> extends true
     ? RpcResponse.parseError.ReturnType<errorObject>

package/core/internal/rpcSchemas/wallet.ts

@@ -157,7 +157,14 @@ export type Wallet = RpcSchema.From<
   | {
       Request: {
         method: 'wallet_getCapabilities'
-        params?: [Address.Address]
+        params?:
+          | readonly []
+          | readonly [Address.Address | undefined]
+          | readonly [
+              Address.Address | undefined,
+              readonly Hex.Hex[] | undefined,
+            ]
+          | undefined
       }
       ReturnType: Compute<WalletCapabilitiesMap>
     }
@@ -219,7 +226,7 @@ export type Wallet = RpcSchema.From<
         method: 'wallet_sendCalls'
         params: Compute<WalletSendCallsParameters>
       }
-      ReturnType: string
+      ReturnType: WalletSendCallsReturnType
     }
   /**
    * Requests for the wallet to show information about a call batch
@@ -303,7 +310,10 @@ type WalletCapabilitiesMap = {
  * @internal
  */
 type WalletGetCallsStatusReturnType = {
-  status: 'PENDING' | 'CONFIRMED'
+  atomic: boolean
+  capabilities?: WalletCapabilities | undefined
+  chainId: Hex.Hex
+  id: string
   receipts?:
     | readonly {
         logs: {
@@ -318,6 +328,8 @@ type WalletGetCallsStatusReturnType = {
         transactionHash: Hex.Hex
       }[]
     | undefined
+  status: number
+  version: string
 }
 
 /**
@@ -396,18 +408,30 @@ type WalletGrantPermissionsReturnType = {
  */
 type WalletSendCallsParameters = [
   {
+    atomicRequired: boolean
     calls: readonly {
+      capabilities?: WalletCapabilities | undefined
       to?: Address.Address | undefined
       data?: Hex.Hex | undefined
       value?: Hex.Hex | undefined
     }[]
     capabilities?: WalletCapabilities | undefined
     chainId?: Hex.Hex | undefined
-    from: Address.Address
+    id?: string | undefined
+    from?: Address.Address | undefined
     version: string
   },
 ]
 
+/**
+ * Return type for `wallet_sendCalls`. [See more](https://eips.ethereum.org/EIPS/eip-5792#wallet_sendcalls).
+ * @internal
+ */
+type WalletSendCallsReturnType = {
+  capabilities?: WalletCapabilities | undefined
+  id: string
+}
+
 /**
  * Parameters for `wallet_watchAsset`. [See more](https://eips.ethereum.org/EIPS/eip-747).
  * @internal