campus-rating/services/node_modules/ox/core/Block.ts

import type * as Address from './Address.js'
import type * as Errors from './Errors.js'
import * as Hex from './Hex.js'
import type { Compute, OneOf } from './internal/types.js'
import * as Transaction from './Transaction.js'
import * as Withdrawal from './Withdrawal.js'

/** A Block as defined in the [Execution API specification](https://github.com/ethereum/execution-apis/blob/main/src/schemas/block.yaml). */
export type Block<
  includeTransactions extends boolean = false,
  blockTag extends Tag = 'latest',
  bigintType = bigint,
  numberType = number,
  transaction = Transaction.Transaction<
    blockTag extends 'pending' ? true : false,
    bigintType,
    numberType
  >,
> = Compute<{
  /** Base fee per gas */
  baseFeePerGas?: bigintType | undefined
  /** Total used blob gas by all transactions in this block */
  blobGasUsed?: bigintType | undefined
  /** Difficulty for this block */
  difficulty?: bigintType | undefined
  /** Excess blob gas */
  excessBlobGas?: bigintType | undefined
  /** "Extra data" field of this block */
  extraData?: Hex.Hex | undefined
  /** Maximum gas allowed in this block */
  gasLimit: bigintType
  /** Total used gas by all transactions in this block */
  gasUsed: bigintType
  /** Block hash or `null` if pending */
  hash: blockTag extends 'pending' ? null : Hex.Hex
  /** Logs bloom filter or `null` if pending */
  logsBloom: blockTag extends 'pending' ? null : Hex.Hex
  /** Address that received this block’s mining rewards */
  miner: Address.Address
  /** Unique identifier for the block. */
  mixHash: Hex.Hex
  /** Proof-of-work hash or `null` if pending */
  nonce: blockTag extends 'pending' ? null : Hex.Hex
  /** Block number or `null` if pending */
  number: blockTag extends 'pending' ? null : bigintType
  parentBeaconBlockRoot?: Hex.Hex | undefined
  /** Parent block hash */
  parentHash: Hex.Hex
  /** Root of the this block’s receipts trie */
  receiptsRoot: Hex.Hex
  sealFields?: readonly Hex.Hex[] | undefined
  /** SHA3 of the uncles data in this block */
  sha3Uncles: Hex.Hex
  /** Size of this block in bytes */
  size: bigintType
  /** Root of this block’s final state trie */
  stateRoot: Hex.Hex
  /** Unix timestamp of when this block was collated */
  timestamp: bigintType
  /** Total difficulty of the chain until this block */
  totalDifficulty?: bigintType | undefined
  /** List of transaction objects or hashes */
  transactions: includeTransactions extends true
    ? readonly transaction[]
    : readonly Hex.Hex[]
  /** Root of this block’s transaction trie */
  transactionsRoot: Hex.Hex
  /** List of uncle hashes */
  uncles: readonly Hex.Hex[]
  /** List of withdrawal objects */
  withdrawals?:
    | readonly Withdrawal.Withdrawal<bigintType, numberType>[]
    | undefined
  /** Root of the this block’s withdrawals trie */
  withdrawalsRoot?: Hex.Hex | undefined
}>

/** A Block hash. */
export type Hash = Hex.Hex

/** A Block identifier. */
export type Identifier<bigintType = bigint> = {
  /** Whether or not to throw an error if the block is not in the canonical chain as described below. Only allowed in conjunction with the blockHash tag. Defaults to false. */
  requireCanonical?: boolean | undefined
} & OneOf<
  | {
      /** The block in the canonical chain with this number */
      blockNumber: Number<bigintType>
    }
  | {
      /** The block uniquely identified by this hash. The `blockNumber` and `blockHash` properties are mutually exclusive; exactly one of them must be set. */
      blockHash: Hash
    }
>

/** A Block number. */
export type Number<bigintType = bigint> = bigintType

/** An RPC Block as defined in the [Execution API specification](https://github.com/ethereum/execution-apis/blob/main/src/schemas/block.yaml). */
export type Rpc<
  includeTransactions extends boolean = boolean,
  blockTag extends Tag = 'latest',
  transaction = Transaction.Rpc<blockTag extends 'pending' ? true : false>,
> = Block<includeTransactions, blockTag, Hex.Hex, Hex.Hex, transaction>

/**
 * A Block Tag as defined in the [Execution API specification](https://github.com/ethereum/execution-apis/blob/main/src/schemas/block.yaml).
 *
 * - `earliest`: The lowest numbered block the client has available;
 * - `finalized`: The most recent crypto-economically secure block, cannot be re-orged outside of manual intervention driven by community coordination;
 * - `safe`: The most recent block that is safe from re-orgs under honest majority and certain synchronicity assumptions;
 * - `latest`: The most recent block in the canonical chain observed by the client, this block may be re-orged out of the canonical chain even under healthy/normal conditions;
 * - `pending`: A sample next block built by the client on top of `latest` and containing the set of transactions usually taken from local mempool.
 */
export type Tag = 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'

/**
 * Converts a {@link ox#Block.Block} to an {@link ox#Block.Rpc}.
 *
 * @example
 * ```ts twoslash
 * // @noErrors
 * import { Block } from 'ox'
 *
 * const block = Block.toRpc({
 *   // ...
 *   hash: '0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd',
 *   number: 19868020n,
 *   size: 520n
 *   timestamp: 1662222222n,
 *   // ...
 * })
 * // @log: {
 * // @log:   // ...
 * // @log:   hash: '0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd',
 * // @log:   number: '0xec6fc6',
 * // @log:   size: '0x208',
 * // @log:   timestamp: '0x63198f6f',
 * // @log:   // ...
 * // @log: }
 * ```
 *
 * @param block - The Block to convert.
 * @returns An RPC Block.
 */
export function toRpc<
  includeTransactions extends boolean = false,
  blockTag extends Tag = 'latest',
>(
  block: Block<includeTransactions, blockTag>,
  _options: toRpc.Options<includeTransactions, blockTag> = {},
): Rpc<boolean, blockTag> {
  const transactions = block.transactions.map((transaction) => {
    if (typeof transaction === 'string') return transaction
    return Transaction.toRpc(transaction as any) as any
  })
  return {
    baseFeePerGas:
      typeof block.baseFeePerGas === 'bigint'
        ? Hex.fromNumber(block.baseFeePerGas)
        : undefined,
    blobGasUsed:
      typeof block.blobGasUsed === 'bigint'
        ? Hex.fromNumber(block.blobGasUsed)
        : undefined,
    excessBlobGas:
      typeof block.excessBlobGas === 'bigint'
        ? Hex.fromNumber(block.excessBlobGas)
        : undefined,
    extraData: block.extraData,
    difficulty:
      typeof block.difficulty === 'bigint'
        ? Hex.fromNumber(block.difficulty)
        : undefined,
    gasLimit: Hex.fromNumber(block.gasLimit),
    gasUsed: Hex.fromNumber(block.gasUsed),
    hash: block.hash,
    logsBloom: block.logsBloom,
    miner: block.miner,
    mixHash: block.mixHash,
    nonce: block.nonce,
    number: (typeof block.number === 'bigint'
      ? Hex.fromNumber(block.number)
      : null) as never,
    parentBeaconBlockRoot: block.parentBeaconBlockRoot,
    parentHash: block.parentHash,
    receiptsRoot: block.receiptsRoot,
    sealFields: block.sealFields,
    sha3Uncles: block.sha3Uncles,
    size: Hex.fromNumber(block.size),
    stateRoot: block.stateRoot,
    timestamp: Hex.fromNumber(block.timestamp),
    totalDifficulty:
      typeof block.totalDifficulty === 'bigint'
        ? Hex.fromNumber(block.totalDifficulty)
        : undefined,
    transactions,
    transactionsRoot: block.transactionsRoot,
    uncles: block.uncles,
    withdrawals: block.withdrawals?.map(Withdrawal.toRpc),
    withdrawalsRoot: block.withdrawalsRoot,
  }
}

export declare namespace toRpc {
  type Options<
    includeTransactions extends boolean = false,
    blockTag extends Tag = 'latest',
  > = {
    blockTag?: blockTag | Tag | undefined
    includeTransactions?: includeTransactions | boolean | undefined
  }

  type ErrorType = Errors.GlobalErrorType
}

/**
 * Converts a {@link ox#Block.Rpc} to an {@link ox#Block.Block}.
 *
 * @example
 * ```ts twoslash
 * // @noErrors
 * import { Block } from 'ox'
 *
 * const block = Block.fromRpc({
 *   // ...
 *   hash: '0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd',
 *   number: '0xec6fc6',
 *   size: '0x208',
 *   timestamp: '0x63198f6f',
 *   // ...
 * })
 * // @log: {
 * // @log:   // ...
 * // @log:   hash: '0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd',
 * // @log:   number: 19868020n,
 * // @log:   size: 520n,
 * // @log:   timestamp: 1662222222n,
 * // @log:   // ...
 * // @log: }
 * ```
 *
 * @example
 * ### End-to-end
 *
 * Below is an end-to-end example of using `Block.fromRpc` to fetch a block from the network and convert it to an {@link ox#Block.Block}.
 *
 * ```ts twoslash
 * import 'ox/window'
 * import { Block } from 'ox'
 *
 * const block = await window.ethereum!
 *   .request({
 *     method: 'eth_getBlockByNumber',
 *     params: ['latest', false],
 *   })
 *   .then(Block.fromRpc) // [!code hl]
 * // @log: {
 * // @log:   // ...
 * // @log:   hash: '0xebc3644804e4040c0a74c5a5bbbc6b46a71a5d4010fe0c92ebb2fdf4a43ea5dd',
 * // @log:   number: 19868020n,
 * // @log:   size: 520n,
 * // @log:   timestamp: 1662222222n,
 * // @log:   // ...
 * // @log: }
 * ```
 *
 * :::note
 *
 * For simplicity, the above example uses `window.ethereum.request`, but you can use any
 * type of JSON-RPC interface.
 *
 * :::
 *
 * @param block - The RPC block to convert.
 * @returns An instantiated {@link ox#Block.Block}.
 */
export function fromRpc<
  const block extends Rpc | null,
  includeTransactions extends boolean = false,
  blockTag extends Tag = 'latest',
>(
  block: block | Rpc | null,
  _options: fromRpc.Options<includeTransactions, blockTag> = {},
): block extends Rpc ? Block<includeTransactions, blockTag> : null {
  if (!block) return null as never

  const transactions = block.transactions.map((transaction) => {
    if (typeof transaction === 'string') return transaction
    return Transaction.fromRpc(transaction) as any
  })
  return {
    ...block,
    baseFeePerGas: block.baseFeePerGas
      ? BigInt(block.baseFeePerGas)
      : undefined,
    blobGasUsed: block.blobGasUsed ? BigInt(block.blobGasUsed) : undefined,
    difficulty: block.difficulty ? BigInt(block.difficulty) : undefined,
    excessBlobGas: block.excessBlobGas
      ? BigInt(block.excessBlobGas)
      : undefined,
    gasLimit: BigInt(block.gasLimit ?? 0n),
    gasUsed: BigInt(block.gasUsed ?? 0n),
    number: block.number ? BigInt(block.number) : null,
    size: BigInt(block.size ?? 0n),
    stateRoot: block.stateRoot,
    timestamp: BigInt(block.timestamp ?? 0n),
    totalDifficulty: BigInt(block.totalDifficulty ?? 0n),
    transactions,
    withdrawals: block.withdrawals?.map(Withdrawal.fromRpc),
  } as Block as never
}

export declare namespace fromRpc {
  type Options<
    includeTransactions extends boolean = false,
    blockTag extends Tag = 'latest',
  > = {
    blockTag?: blockTag | Tag | undefined
    includeTransactions?: includeTransactions | boolean | undefined
  }

  type ErrorType = Errors.GlobalErrorType
}