ox 0.0.1 → 0.1.0

package/P256.ts

@@ -0,0 +1,230 @@
+import { secp256r1 } from '@noble/curves/p256'
+import * as Bytes from './Bytes.js'
+import type * as Errors from './Errors.js'
+import * as Hex from './Hex.js'
+import * as PublicKey from './PublicKey.js'
+import type * as Signature from './Signature.js'
+
+/** Re-export of noble/curves P256 utilities. */
+export const noble = secp256r1
+
+/**
+ * Computes the P256 ECDSA public key from a provided private key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { P256 } from 'ox'
+ *
+ * const publicKey = P256.getPublicKey({ privateKey: '0x...' })
+ * ```
+ *
+ * @param options - The options to compute the public key.
+ * @returns The computed public key.
+ */
+export function getPublicKey(
+  options: getPublicKey.Options,
+): PublicKey.PublicKey {
+  const { privateKey } = options
+  const point = secp256r1.ProjectivePoint.fromPrivateKey(
+    typeof privateKey === 'string'
+      ? privateKey.slice(2)
+      : Hex.fromBytes(privateKey).slice(2),
+  )
+  return PublicKey.from(point)
+}
+
+export declare namespace getPublicKey {
+  type Options = {
+    /**
+     * Private key to compute the public key from.
+     */
+    privateKey: Hex.Hex | Bytes.Bytes
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/**
+ * Generates a random P256 ECDSA private key.
+ *
+ * @example
+ * ```ts twoslash
+ * import { P256 } from 'ox'
+ *
+ * const privateKey = P256.randomPrivateKey()
+ * ```
+ *
+ * @param options - The options to generate the private key.
+ * @returns The generated private key.
+ */
+export function randomPrivateKey<as extends 'Hex' | 'Bytes' = 'Hex'>(
+  options: randomPrivateKey.Options<as> = {},
+): randomPrivateKey.ReturnType<as> {
+  const { as = 'Hex' } = options
+  const bytes = secp256r1.utils.randomPrivateKey()
+  if (as === 'Hex') return Hex.fromBytes(bytes) as never
+  return bytes as never
+}
+
+export declare namespace randomPrivateKey {
+  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 = Hex.fromBytes.ErrorType | Errors.GlobalErrorType
+}
+
+/**
+ * Recovers the signing public key from the signed payload and signature.
+ *
+ * @example
+ * ```ts twoslash
+ * import { P256 } from 'ox'
+ *
+ * const signature = P256.sign({ payload: '0xdeadbeef', privateKey: '0x...' })
+ *
+ * const publicKey = P256.recoverPublicKey({ // [!code focus]
+ *   payload: '0xdeadbeef', // [!code focus]
+ *   signature, // [!code focus]
+ * }) // [!code focus]
+ * ```
+ *
+ * @param options - The recovery options.
+ * @returns The recovered public key.
+ */
+export function recoverPublicKey(
+  options: recoverPublicKey.Options,
+): PublicKey.PublicKey {
+  const { payload, signature } = options
+  const { r, s, yParity } = signature
+  const signature_ = new secp256r1.Signature(
+    BigInt(r),
+    BigInt(s),
+  ).addRecoveryBit(yParity)
+  const payload_ =
+    payload instanceof Uint8Array ? Hex.fromBytes(payload) : payload
+  const point = signature_.recoverPublicKey(payload_.substring(2))
+  return PublicKey.from(point)
+}
+
+export declare namespace recoverPublicKey {
+  type Options = {
+    /** Payload that was signed. */
+    payload: Hex.Hex | Bytes.Bytes
+    /** Signature of the payload. */
+    signature: Signature.Signature
+  }
+
+  type ErrorType =
+    | PublicKey.from.ErrorType
+    | Hex.fromBytes.ErrorType
+    | Errors.GlobalErrorType
+}
+
+recoverPublicKey.parseError = (error: unknown) =>
+  /* v8 ignore next */
+  error as recoverPublicKey.ErrorType
+
+/**
+ * Signs the payload with the provided private key and returns a P256 signature.
+ *
+ * @example
+ * ```ts twoslash
+ * import { P256 } from 'ox'
+ *
+ * const signature = P256.sign({ // [!code focus]
+ *   payload: '0xdeadbeef', // [!code focus]
+ *   privateKey: '0x...' // [!code focus]
+ * }) // [!code focus]
+ * ```
+ *
+ * @param options - The signing options.
+ * @returns The ECDSA {@link ox#Signature.Signature}.
+ */
+export function sign(options: sign.Options): Signature.Signature {
+  const { hash, payload, privateKey } = options
+  const { r, s, recovery } = secp256r1.sign(
+    payload instanceof Uint8Array ? payload : Bytes.fromHex(payload),
+    privateKey instanceof Uint8Array ? privateKey : Bytes.fromHex(privateKey),
+    ...(hash ? [{ prehash: true, lowS: true }] : []),
+  )
+  return {
+    r,
+    s,
+    yParity: recovery,
+  }
+}
+
+export declare namespace sign {
+  type Options = {
+    /** If set to `true`, the payload will be hashed (sha256) before being signed. */
+    hash?: boolean | undefined
+    /** Payload to sign. */
+    payload: Hex.Hex | Bytes.Bytes
+    /** ECDSA private key. */
+    privateKey: Hex.Hex | Bytes.Bytes
+  }
+
+  type ErrorType = Bytes.fromHex.ErrorType | Errors.GlobalErrorType
+}
+
+/* v8 ignore next */
+sign.parseError = (error: unknown) => error as sign.ErrorType
+
+/**
+ * Verifies a payload was signed by the provided public key.
+ *
+ * @example
+ *
+ * ```ts twoslash
+ * import { P256 } from 'ox'
+ *
+ * const privateKey = P256.randomPrivateKey()
+ * const publicKey = P256.getPublicKey({ privateKey })
+ * const signature = P256.sign({ payload: '0xdeadbeef', privateKey })
+ *
+ * const verified = P256.verify({ // [!code focus]
+ *   publicKey, // [!code focus]
+ *   payload: '0xdeadbeef', // [!code focus]
+ *   signature, // [!code focus]
+ * }) // [!code focus]
+ * ```
+ *
+ * @param options - The verification options.
+ * @returns Whether the payload was signed by the provided public key.
+ */
+export function verify(options: verify.Options): boolean {
+  const { hash, payload, publicKey, signature } = options
+  return secp256r1.verify(
+    signature,
+    payload instanceof Uint8Array ? payload : Bytes.fromHex(payload),
+    PublicKey.toHex(publicKey).substring(2),
+    ...(hash ? [{ prehash: true, lowS: true }] : []),
+  )
+}
+
+export declare namespace verify {
+  type Options = {
+    /** If set to `true`, the payload will be hashed (sha256) before being verified. */
+    hash?: boolean | undefined
+    /** Payload that was signed. */
+    payload: Hex.Hex | Bytes.Bytes
+    /** Public key that signed the payload. */
+    publicKey: PublicKey.PublicKey<boolean>
+    /** Signature of the payload. */
+    signature: Signature.Signature<boolean>
+  }
+
+  type ErrorType = Errors.GlobalErrorType
+}
+
+/* v8 ignore next */
+verify.parseError = (error: unknown) => error as verify.ErrorType

package/PersonalMessage/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../_types/PersonalMessage.d.ts",
+  "main": "../_cjs/PersonalMessage.js",
+  "module": "../_esm/PersonalMessage.js"
+}

package/PersonalMessage.ts

@@ -0,0 +1,70 @@
+import type * as Bytes from './Bytes.js'
+import type * as Errors from './Errors.js'
+import * as Hash from './Hash.js'
+import * as Hex from './Hex.js'
+
+/**
+ * Encodes a personal sign message in [ERC-191 format](https://eips.ethereum.org/EIPS/eip-191#version-0x45-e): `0x19 ‖ "Ethereum Signed Message:\n" + message.length ‖ message`.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hex, PersonalMessage } from 'ox'
+ *
+ * const data = PersonalMessage.encode(Hex.fromString('hello world'))
+ * // @log: '0x19457468657265756d205369676e6564204d6573736167653a0a313168656c6c6f20776f726c64'
+ * // @log: (0x19 ‖ 'Ethereum Signed Message:\n11' ‖ 'hello world')
+ * ```
+ *
+ * @param data - The data to encode.
+ * @returns The encoded personal sign message.
+ */
+export function encode(data: Hex.Hex | Bytes.Bytes): Hex.Hex {
+  const message = Hex.from(data)
+  return Hex.concat(
+    // Personal Sign Format: `0x19 ‖ "Ethereum Signed Message:\n" ‖ message.length ‖ message`
+    '0x19',
+    Hex.fromString('Ethereum Signed Message:\n' + Hex.size(message)),
+    message,
+  )
+}
+
+export declare namespace encode {
+  type ErrorType =
+    | Hex.concat.ErrorType
+    | Hex.from.ErrorType
+    | Hex.fromString.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/* v8 ignore next */
+encode.parseError = (error: unknown) => error as encode.ErrorType
+
+/**
+ * Gets the payload to use for signing an [ERC-191 formatted](https://eips.ethereum.org/EIPS/eip-191#version-0x45-e) personal message.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Hex, PersonalMessage, Secp256k1 } from 'ox'
+ *
+ * const payload = PersonalMessage.getSignPayload(Hex.fromString('hello world')) // [!code focus]
+ *
+ * const signature = Secp256k1.sign({ payload, privateKey: '0x...' })
+ * ```
+ *
+ * @param data - The data to get the sign payload for.
+ * @returns The payload to use for signing.
+ */
+export function getSignPayload(data: Hex.Hex | Bytes.Bytes): Hex.Hex {
+  return Hash.keccak256(encode(data))
+}
+
+export declare namespace getSignPayload {
+  type ErrorType =
+    | Hash.keccak256.ErrorType
+    | encode.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/* v8 ignore next */
+getSignPayload.parseError = (error: unknown) =>
+  error as getSignPayload.ErrorType

package/Provider/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../_types/Provider.d.ts",
+  "main": "../_cjs/Provider.js",
+  "module": "../_esm/Provider.js"
+}

package/Provider.ts

@@ -0,0 +1,354 @@
+import { EventEmitter } from 'eventemitter3'
+import type * as Address from './Address.js'
+import * as Errors from './Errors.js'
+import * as RpcResponse from './RpcResponse.js'
+import type * as RpcSchema from './RpcSchema.js'
+import type * as RpcSchema_internal from './internal/rpcSchema.js'
+import type { Compute } from './internal/types.js'
+
+/** Options for a {@link ox#Provider.Provider}. */
+export type Options = {
+  /**
+   * Whether to include event functions (`on`, `removeListener`) on the Provider.
+   *
+   * @default true
+   */
+  includeEvents?: boolean | undefined
+  /**
+   * RPC Schema to use for the Provider's `request` function.
+   * See {@link ox#RpcSchema.(from:function)} for more.
+   *
+   * @default `RpcSchema.Generic`
+   */
+  schema?: RpcSchema.Generic | undefined
+}
+
+/** Root type for an EIP-1193 Provider. */
+export type Provider<
+  options extends Options | undefined = undefined,
+  ///
+  _schema extends RpcSchema.Generic = options extends {
+    schema: infer schema extends RpcSchema.Generic
+  }
+    ? schema
+    : RpcSchema.Default,
+> = Compute<
+  {
+    request: RequestFn<_schema>
+  } & (options extends { includeEvents: true } | undefined
+    ? {
+        on: EventListenerFn
+        removeListener: EventListenerFn
+      }
+    : {})
+>
+
+/** Type for an EIP-1193 Provider's event emitter. */
+export type Emitter = Compute<EventEmitter<EventMap>>
+
+/** EIP-1193 Provider's `request` function. */
+export type RequestFn<schema extends RpcSchema.Generic = RpcSchema.Generic> = <
+  methodName extends RpcSchema.MethodNameGeneric,
+>(
+  parameters: RpcSchema_internal.ExtractRequestOpaque<schema, methodName>,
+) => Promise<RpcSchema.ExtractReturnType<schema, methodName>>
+
+/** Type for an EIP-1193 Provider's event listener functions (`on`, `removeListener`, etc). */
+export type EventListenerFn = <event extends keyof EventMap>(
+  event: event,
+  listener: EventMap[event],
+) => void
+
+export type ConnectInfo = {
+  chainId: string
+}
+
+export type Message = {
+  type: string
+  data: unknown
+}
+
+export class ProviderRpcError extends Error {
+  override readonly name = 'ProviderRpcError'
+
+  code: number
+  details: string
+
+  constructor(code: number, message: string) {
+    super(message)
+    this.code = code
+    this.details = message
+  }
+}
+
+export type EventMap = {
+  accountsChanged: (accounts: Address.Address[]) => void
+  chainChanged: (chainId: string) => void
+  connect: (connectInfo: ConnectInfo) => void
+  disconnect: (error: ProviderRpcError) => void
+  message: (message: Message) => void
+}
+
+/**
+ * Creates an EIP-1193 flavored event emitter to be injected onto a Provider.
+ *
+ * @example
+ * ```ts twoslash
+ * import { Provider, RpcRequest, RpcResponse } from 'ox' // [!code focus]
+ *
+ * // 1. Instantiate a Provider Emitter. // [!code focus]
+ * const emitter = Provider.createEmitter() // [!code focus]
+ *
+ * const store = RpcRequest.createStore()
+ *
+ * const provider = Provider.from({
+ *   // 2. Pass the Emitter to the Provider. // [!code focus]
+ *   ...emitter, // [!code focus]
+ *   async request(args) {
+ *     return await fetch('https://1.rpc.thirdweb.com', {
+ *       body: JSON.stringify(store.prepare(args)),
+ *       method: 'POST',
+ *       headers: {
+ *         'Content-Type': 'application/json',
+ *       },
+ *     })
+ *       .then((res) => res.json())
+ *       .then(RpcResponse.parse)
+ *   },
+ * })
+ *
+ * // 3. Emit Provider Events. // [!code focus]
+ * emitter.emit('accountsChanged', ['0x...']) // [!code focus]
+ * ```
+ *
+ * @returns An event emitter.
+ */
+export function createEmitter(): Emitter {
+  const emitter = new EventEmitter<EventMap>()
+
+  return {
+    get eventNames() {
+      return emitter.eventNames.bind(emitter)
+    },
+    get listenerCount() {
+      return emitter.listenerCount.bind(emitter)
+    },
+    get listeners() {
+      return emitter.listeners.bind(emitter)
+    },
+    addListener: emitter.addListener.bind(emitter),
+    emit: emitter.emit.bind(emitter),
+    off: emitter.off.bind(emitter),
+    on: emitter.on.bind(emitter),
+    once: emitter.once.bind(emitter),
+    removeAllListeners: emitter.removeAllListeners.bind(emitter),
+    removeListener: emitter.removeListener.bind(emitter),
+  }
+}
+
+export declare namespace createEmitter {
+  type ErrorType = Errors.GlobalErrorType
+}
+
+createEmitter.parseError = (error: unknown) =>
+  /* v8 ignore next */
+  error as createEmitter.ErrorType
+
+/**
+ * Instantiates an [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) {@link ox#Provider.Provider}
+ * from an arbitrary [EIP-1193 Provider](https://eips.ethereum.org/EIPS/eip-1193) interface.
+ *
+ * @example
+ * ### Instantiating with RPC Transport
+ *
+ * Ox's {@link ox#RpcTransport} is EIP-1193 compliant, and can be used to instantiate an EIP-1193 Provider. This means you can use any HTTP RPC endpoint as an EIP-1193 Provider.
+ *
+ * ```ts twoslash
+ * import { Provider, RpcTransport } from 'ox'
+ *
+ * const transport = RpcTransport.fromHttp('https://1.rpc.thirdweb.com')
+ * const provider = Provider.from(transport)
+ * ```
+ *
+ * @example
+ * ### Instantiating with External Providers
+ *
+ * The example below demonstrates how we can instantiate a typed EIP-1193 Provider from an
+ * external EIP-1193 Provider like `window.ethereum`.
+ *
+ * ```ts twoslash
+ * import 'ox/window'
+ * import { Provider } from 'ox'
+ *
+ * const provider = Provider.from(window.ethereum)
+ *
+ * const blockNumber = await provider.request({ method: 'eth_blockNumber' })
+ * ```
+ *
+ * :::tip
+ *
+ * There are also libraries that distribute EIP-1193 Provider objects that you can use with `Provider.from`:
+ *
+ * - [`@walletconnect/ethereum-provider`](https://www.npmjs.com/package/\@walletconnect/ethereum-provider)
+ *
+ * - [`@coinbase/wallet-sdk`](https://www.npmjs.com/package/\@coinbase/wallet-sdk)
+ *
+ * - [`@metamask/detect-provider`](https://www.npmjs.com/package/\@metamask/detect-provider)
+ *
+ * - [`@safe-global/safe-apps-provider`](https://github.com/safe-global/safe-apps-sdk/tree/main/packages/safe-apps-provider)
+ *
+ * - [`mipd`](https://github.com/wevm/mipd): EIP-6963 Multi Injected Providers
+ *
+ * :::
+ *
+ * @example
+ * ### Instantiating a Custom Provider
+ *
+ * The example below demonstrates how we can instantiate a typed EIP-1193 Provider from a
+ * HTTP `fetch` JSON-RPC request. You can use this pattern to integrate with any asynchronous JSON-RPC
+ * transport, including WebSockets and IPC.
+ *
+ * ```ts twoslash
+ * import { Provider, RpcRequest, RpcResponse } from 'ox'
+ *
+ * const store = RpcRequest.createStore()
+ *
+ * const provider = Provider.from({
+ *   async request(args) {
+ *     return await fetch('https://1.rpc.thirdweb.com', {
+ *       body: JSON.stringify(store.prepare(args)),
+ *       method: 'POST',
+ *       headers: {
+ *         'Content-Type': 'application/json',
+ *       },
+ *     })
+ *       .then((res) => res.json())
+ *       .then(RpcResponse.parse)
+ *   },
+ * })
+ *
+ * const blockNumber = await provider.request({ method: 'eth_blockNumber' })
+ * ```
+ *
+ * @example
+ * ### Type-safe Custom Schemas
+ *
+ * It is possible to define your own type-safe schema by using the {@link ox#RpcSchema.(from:function)} type.
+ *
+ * ```ts twoslash
+ * // @noErrors
+ * import 'ox/window'
+ * import { Provider, RpcSchema } from 'ox'
+ *
+ * const schema = RpcSchema.from<
+ *   | RpcSchema.Default
+ *   | {
+ *       Request: {
+ *         method: 'abe_foo',
+ *         params: [id: number],
+ *       }
+ *       ReturnType: string
+ *     }
+ *   | {
+ *       Request: {
+ *         method: 'abe_bar',
+ *         params: [id: string],
+ *       }
+ *       ReturnType: string
+ *     }
+ * >()
+ *
+ * const provider = Provider.from(window.ethereum, { schema })
+ *
+ * const blockNumber = await provider.request({ method: 'e' })
+ * //                                                    ^|
+ *
+ *
+ *
+ *
+ *
+ * ```
+ *
+ * @example
+ * ### Instantiating a Provider with Events
+ *
+ * The example below demonstrates how to instantiate a Provider with your own EIP-1193 flavored event emitter.
+ *
+ * This example is useful for Wallets that distribute an EIP-1193 Provider (e.g. webpage injection via `window.ethereum`).
+ *
+ * ```ts twoslash
+ * import { Provider, RpcRequest, RpcResponse } from 'ox'
+ *
+ * // 1. Instantiate a Provider Emitter.
+ * const emitter = Provider.createEmitter() // [!code ++]
+ *
+ * const store = RpcRequest.createStore()
+ *
+ * const provider = Provider.from({
+ *   // 2. Pass the Emitter to the Provider.
+ *   ...emitter, // [!code ++]
+ *   async request(args) {
+ *     return await fetch('https://1.rpc.thirdweb.com', {
+ *       body: JSON.stringify(store.prepare(args)),
+ *       method: 'POST',
+ *       headers: {
+ *         'Content-Type': 'application/json',
+ *       },
+ *     })
+ *       .then((res) => res.json())
+ *       .then(RpcResponse.parse)
+ *   },
+ * })
+ *
+ * // 3. Emit Provider Events.
+ * emitter.emit('accountsChanged', ['0x...']) // [!code ++]
+ * ```
+ *
+ * @param provider - The EIP-1193 provider to convert.
+ * @returns An typed EIP-1193 Provider.
+ */
+export function from<
+  const provider extends Provider | unknown,
+  options extends Options | undefined = undefined,
+>(
+  provider: provider | Provider<{ schema: RpcSchema.Generic }>,
+  options?: options | Options,
+): Provider<options>
+// eslint-disable-next-line jsdoc/require-jsdoc
+export function from(provider: any, options: Options = {}): Provider<Options> {
+  const { includeEvents = true } = options
+  if (!provider) throw new IsUndefinedError()
+  return {
+    ...(includeEvents
+      ? {
+          on: provider.on?.bind(provider),
+          removeListener: provider.removeListener?.bind(provider),
+        }
+      : {}),
+    async request(args) {
+      const result = await provider.request(args)
+      if (
+        typeof result === 'object' &&
+        'jsonrpc' in (result as { jsonrpc?: unknown })
+      )
+        return RpcResponse.parse(result) as never
+      return result
+    },
+  }
+}
+
+export declare namespace from {
+  type ErrorType = IsUndefinedError | Errors.GlobalErrorType
+}
+
+/* v8 ignore next */
+from.parseError = (error: unknown) => error as from.ErrorType
+
+/** Thrown when the provider is undefined. */
+export class IsUndefinedError extends Errors.BaseError {
+  override readonly name = 'Provider.IsUndefinedError'
+
+  constructor() {
+    super('`provider` is undefined.')
+  }
+}

package/PublicKey/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../_types/PublicKey.d.ts",
+  "main": "../_cjs/PublicKey.js",
+  "module": "../_esm/PublicKey.js"
+}