voltaire-effect 0.2.23 → 0.2.24

package/src/primitives/Opcode/OpcodeSchema.ts

@@ -6,7 +6,7 @@ import * as S from "effect/Schema";
  * Type representing an EVM opcode value (0x00-0xFF).
  * @since 0.0.1
  */
-type OpcodeType = ReturnType<typeof Opcode>;
+export type OpcodeType = ReturnType<typeof Opcode>;
 
 const OpcodeTypeSchema = S.declare<OpcodeType>(
 	(u): u is OpcodeType => typeof u === "number" && u >= 0x00 && u <= 0xff,

package/src/primitives/Opcode/disassemble.ts

@@ -0,0 +1,15 @@
+/**
+ * @module disassemble
+ * @description Disassemble bytecode to opcode instructions (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Disassemble bytecode into instructions
+ *
+ * @param bytecode - Bytecode to disassemble
+ * @returns Array of disassembled instructions
+ */
+export const disassemble = Opcode.disassemble;
+export const _disassemble = disassemble;

package/src/primitives/Opcode/dupPosition.ts

@@ -0,0 +1,15 @@
+/**
+ * @module dupPosition
+ * @description Get DUP instruction position (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Get the stack position for a DUP instruction
+ *
+ * @param opcode - DUP opcode (0x80-0x8f)
+ * @returns Stack position (1-16), or 0 if not a DUP
+ */
+export const dupPosition = Opcode.dupPosition;
+export const _dupPosition = dupPosition;

package/src/primitives/Opcode/format.ts

@@ -0,0 +1,15 @@
+/**
+ * @module format
+ * @description Format opcode to string (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Format an opcode to human-readable string
+ *
+ * @param opcode - Opcode to format
+ * @returns Formatted string (e.g., "PUSH1", "ADD")
+ */
+export const format = Opcode.format;
+export const _format = format;

package/src/primitives/Opcode/getters.ts

@@ -0,0 +1,54 @@
+/**
+ * @module getters
+ * @description Opcode metadata getters (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Get the category of an opcode
+ */
+export const getCategory = Opcode.getCategory;
+export const _getCategory = getCategory;
+
+/**
+ * Get the description of an opcode
+ */
+export const getDescription = Opcode.getDescription;
+export const _getDescription = getDescription;
+
+/**
+ * Get the base gas cost of an opcode
+ */
+export const getGasCost = Opcode.getGasCost;
+export const _getGasCost = getGasCost;
+
+/**
+ * Get the name of an opcode
+ */
+export const getName = Opcode.getName;
+export const _getName = getName;
+
+/**
+ * Get the push size for PUSH opcodes
+ */
+export const getPushSize = Opcode.getPushSize;
+export const _getPushSize = getPushSize;
+
+/**
+ * Get the stack effect (inputs - outputs) of an opcode
+ */
+export const getStackEffect = Opcode.getStackEffect;
+export const _getStackEffect = getStackEffect;
+
+/**
+ * Get the number of stack inputs for an opcode
+ */
+export const getStackInput = Opcode.getStackInput;
+export const _getStackInput = getStackInput;
+
+/**
+ * Get the number of stack outputs for an opcode
+ */
+export const getStackOutput = Opcode.getStackOutput;
+export const _getStackOutput = getStackOutput;

package/src/primitives/Opcode/index.ts

@@ -1,24 +1,314 @@
 /**
- * Opcode module for Effect-based EVM opcode handling.
+ * @module Opcode
+ * @description Effect-wrapped operations for EVM opcodes.
  *
- * Provides Effect-wrapped operations for working with EVM opcodes (0x00-0xFF).
+ * Provides functions for working with EVM opcodes (0x00-0xFF).
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as Opcode from 'voltaire-effect/primitives/Opcode'
+ *
+ * function executeOpcode(op: Opcode.OpcodeType) {
+ *   // ...
+ * }
+ * ```
+ *
+ * ## Constants
+ *
+ * All EVM opcodes are exported as constants:
+ * ```typescript
+ * Opcode.STOP, Opcode.ADD, Opcode.MUL, Opcode.SUB, ...
+ * Opcode.PUSH1, Opcode.PUSH2, ..., Opcode.PUSH32
+ * Opcode.DUP1, Opcode.DUP2, ..., Opcode.DUP16
+ * Opcode.SWAP1, Opcode.SWAP2, ..., Opcode.SWAP16
+ * Opcode.LOG0, Opcode.LOG1, ..., Opcode.LOG4
+ * Opcode.CREATE, Opcode.CALL, Opcode.RETURN, Opcode.REVERT, ...
+ * ```
+ *
+ * ## Pure Functions
+ *
+ * ```typescript
+ * // Disassembly
+ * Opcode.disassemble(bytecode)           // Instruction[]
+ * Opcode.format(opcode)                  // string
+ * Opcode.parse(value)                    // OpcodeType
+ *
+ * // Metadata
+ * Opcode.info(opcode)                    // Info
+ * Opcode.name(opcode)                    // string
+ * Opcode.getCategory(opcode)             // string
+ * Opcode.getDescription(opcode)          // string
+ * Opcode.getGasCost(opcode)              // number
+ * Opcode.getPushSize(opcode)             // number
+ * Opcode.getStackEffect(opcode)          // number
+ * Opcode.getStackInput(opcode)           // number
+ * Opcode.getStackOutput(opcode)          // number
+ *
+ * // Position helpers
+ * Opcode.dupPosition(opcode)             // number
+ * Opcode.swapPosition(opcode)            // number
+ * Opcode.pushBytes(opcode)               // number
+ * Opcode.pushOpcode(n)                   // OpcodeType
+ * Opcode.logTopics(opcode)               // number
+ *
+ * // Predicates
+ * Opcode.isDup(opcode)                   // boolean
+ * Opcode.isJump(opcode)                  // boolean
+ * Opcode.isJumpDestination(opcode)       // boolean
+ * Opcode.isLog(opcode)                   // boolean
+ * Opcode.isPush(opcode)                  // boolean
+ * Opcode.isSwap(opcode)                  // boolean
+ * Opcode.isTerminating(opcode)           // boolean
+ * Opcode.isTerminator(opcode)            // boolean
+ * Opcode.isValid(opcode)                 // boolean
+ * Opcode.isValidJumpDest(opcode)         // boolean
+ * Opcode.isValidOpcode(opcode)           // boolean
+ *
+ * // Analysis
+ * Opcode.jumpDests(bytecode)             // Set<number>
+ * ```
  *
  * @example
  * ```typescript
  * import * as Opcode from 'voltaire-effect/primitives/Opcode'
- * import * as Effect from 'effect/Effect'
  *
- * // Create opcode from number
- * const add = Opcode.from(0x01) // ADD
- * const stop = Opcode.from(0x00) // STOP
+ * const addInfo = Opcode.info(Opcode.ADD)
+ * console.log(addInfo?.name)     // "ADD"
+ * console.log(addInfo?.gasCost)  // 3
  *
- * // Use with schema validation
- * import * as S from 'effect/Schema'
- * const validated = S.decodeSync(Opcode.OpcodeSchema)(0x60) // PUSH1
+ * Opcode.isPush(0x60)            // true (PUSH1)
+ * Opcode.getPushSize(0x60)       // 1
  * ```
  *
- * @module
- * @since 0.0.1
+ * @since 0.1.0
  */
 
+// Re-export types
+export type { Instruction, Info } from "@tevm/voltaire/Opcode";
+
+// OpcodeType is number & { [brand]: "Opcode" } - re-export from OpcodeSchema
+export type { OpcodeType } from "./OpcodeSchema.js";
+
+// Schema
 export { OpcodeSchema } from "./OpcodeSchema.js";
+
+// Disassembly
+export { disassemble, _disassemble } from "./disassemble.js";
+export { format, _format } from "./format.js";
+export { parse, _parse } from "./parse.js";
+
+// Metadata getters
+export {
+	getCategory,
+	_getCategory,
+	getDescription,
+	_getDescription,
+	getGasCost,
+	_getGasCost,
+	getName,
+	_getName,
+	getPushSize,
+	_getPushSize,
+	getStackEffect,
+	_getStackEffect,
+	getStackInput,
+	_getStackInput,
+	getStackOutput,
+	_getStackOutput,
+} from "./getters.js";
+
+// Info
+export { info, _info } from "./info.js";
+
+// Position helpers
+export { dupPosition, _dupPosition } from "./dupPosition.js";
+export { swapPosition, _swapPosition } from "./swapPosition.js";
+export { pushBytes, _pushBytes } from "./pushBytes.js";
+export { pushOpcode, _pushOpcode } from "./pushOpcode.js";
+export { logTopics, _logTopics } from "./logTopics.js";
+export { name, _name } from "./name.js";
+
+// Predicates
+export {
+	isDup,
+	_isDup,
+	isJump,
+	_isJump,
+	isJumpDestination,
+	_isJumpDestination,
+	isLog,
+	_isLog,
+	isPush,
+	_isPush,
+	isSwap,
+	_isSwap,
+	isTerminating,
+	_isTerminating,
+	isTerminator,
+	_isTerminator,
+	isValid,
+	_isValid,
+	isValidJumpDest,
+	_isValidJumpDest,
+	isValidOpcode,
+	_isValidOpcode,
+} from "./predicates.js";
+
+// Analysis
+export { jumpDests, _jumpDests } from "./jumpDests.js";
+
+// Constants - re-export all opcode constants
+export {
+	STOP,
+	ADD,
+	MUL,
+	SUB,
+	DIV,
+	SDIV,
+	MOD,
+	SMOD,
+	ADDMOD,
+	MULMOD,
+	EXP,
+	SIGNEXTEND,
+	LT,
+	GT,
+	SLT,
+	SGT,
+	EQ,
+	ISZERO,
+	AND,
+	OR,
+	XOR,
+	NOT,
+	BYTE,
+	SHL,
+	SHR,
+	SAR,
+	KECCAK256,
+	ADDRESS,
+	BALANCE,
+	ORIGIN,
+	CALLER,
+	CALLVALUE,
+	CALLDATALOAD,
+	CALLDATASIZE,
+	CALLDATACOPY,
+	CODESIZE,
+	CODECOPY,
+	GASPRICE,
+	EXTCODESIZE,
+	EXTCODECOPY,
+	RETURNDATASIZE,
+	RETURNDATACOPY,
+	EXTCODEHASH,
+	BLOCKHASH,
+	COINBASE,
+	TIMESTAMP,
+	NUMBER,
+	DIFFICULTY,
+	GASLIMIT,
+	CHAINID,
+	SELFBALANCE,
+	BASEFEE,
+	BLOBHASH,
+	BLOBBASEFEE,
+	POP,
+	MLOAD,
+	MSTORE,
+	MSTORE8,
+	SLOAD,
+	SSTORE,
+	JUMP,
+	JUMPI,
+	PC,
+	MSIZE,
+	GAS,
+	JUMPDEST,
+	TLOAD,
+	TSTORE,
+	MCOPY,
+	PUSH0,
+	PUSH1,
+	PUSH2,
+	PUSH3,
+	PUSH4,
+	PUSH5,
+	PUSH6,
+	PUSH7,
+	PUSH8,
+	PUSH9,
+	PUSH10,
+	PUSH11,
+	PUSH12,
+	PUSH13,
+	PUSH14,
+	PUSH15,
+	PUSH16,
+	PUSH17,
+	PUSH18,
+	PUSH19,
+	PUSH20,
+	PUSH21,
+	PUSH22,
+	PUSH23,
+	PUSH24,
+	PUSH25,
+	PUSH26,
+	PUSH27,
+	PUSH28,
+	PUSH29,
+	PUSH30,
+	PUSH31,
+	PUSH32,
+	DUP1,
+	DUP2,
+	DUP3,
+	DUP4,
+	DUP5,
+	DUP6,
+	DUP7,
+	DUP8,
+	DUP9,
+	DUP10,
+	DUP11,
+	DUP12,
+	DUP13,
+	DUP14,
+	DUP15,
+	DUP16,
+	SWAP1,
+	SWAP2,
+	SWAP3,
+	SWAP4,
+	SWAP5,
+	SWAP6,
+	SWAP7,
+	SWAP8,
+	SWAP9,
+	SWAP10,
+	SWAP11,
+	SWAP12,
+	SWAP13,
+	SWAP14,
+	SWAP15,
+	SWAP16,
+	LOG0,
+	LOG1,
+	LOG2,
+	LOG3,
+	LOG4,
+	CREATE,
+	CALL,
+	CALLCODE,
+	RETURN,
+	DELEGATECALL,
+	CREATE2,
+	AUTH,
+	AUTHCALL,
+	STATICCALL,
+	REVERT,
+	INVALID,
+	SELFDESTRUCT,
+} from "@tevm/voltaire/Opcode";

package/src/primitives/Opcode/info.ts

@@ -0,0 +1,18 @@
+/**
+ * @module info
+ * @description Get full opcode metadata (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+import type { Info } from "@tevm/voltaire/Opcode";
+
+/**
+ * Get full metadata info for an opcode
+ *
+ * @param opcode - Opcode to look up
+ * @returns Info object with gas, stack effects, name
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const info = (opcode: number): Info | undefined =>
+	Opcode.info(opcode as any);
+export const _info = info;

package/src/primitives/Opcode/jumpDests.ts

@@ -0,0 +1,15 @@
+/**
+ * @module jumpDests
+ * @description Find jump destinations in bytecode (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Find all valid JUMPDEST positions in bytecode
+ *
+ * @param bytecode - Bytecode to analyze
+ * @returns Set of valid jump destination positions
+ */
+export const jumpDests = Opcode.jumpDests;
+export const _jumpDests = jumpDests;

package/src/primitives/Opcode/logTopics.ts

@@ -0,0 +1,15 @@
+/**
+ * @module logTopics
+ * @description Get number of topics for LOG opcode (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Get the number of topics for a LOG opcode
+ *
+ * @param opcode - LOG opcode (0xa0-0xa4)
+ * @returns Number of topics (0-4), or -1 if not a LOG
+ */
+export const logTopics = Opcode.logTopics;
+export const _logTopics = logTopics;

package/src/primitives/Opcode/name.ts

@@ -0,0 +1,15 @@
+/**
+ * @module name
+ * @description Get opcode name (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Get the mnemonic name for an opcode
+ *
+ * @param opcode - Opcode to look up
+ * @returns Opcode name (e.g., "ADD", "PUSH1")
+ */
+export const name = Opcode.name;
+export const _name = name;

package/src/primitives/Opcode/parse.ts

@@ -0,0 +1,15 @@
+/**
+ * @module parse
+ * @description Parse opcode from number or string (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Parse an opcode from number or name string
+ *
+ * @param value - Opcode number or name
+ * @returns Opcode value
+ */
+export const parse = Opcode.parse;
+export const _parse = parse;

package/src/primitives/Opcode/predicates.ts

@@ -0,0 +1,72 @@
+/**
+ * @module predicates
+ * @description Opcode type predicates (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Check if opcode is a DUP instruction
+ */
+export const isDup = Opcode.isDup;
+export const _isDup = isDup;
+
+/**
+ * Check if opcode is a JUMP instruction
+ */
+export const isJump = Opcode.isJump;
+export const _isJump = isJump;
+
+/**
+ * Check if opcode is JUMPDEST
+ */
+export const isJumpDestination = Opcode.isJumpDestination;
+export const _isJumpDestination = isJumpDestination;
+
+/**
+ * Check if opcode is a LOG instruction
+ */
+export const isLog = Opcode.isLog;
+export const _isLog = isLog;
+
+/**
+ * Check if opcode is a PUSH instruction
+ */
+export const isPush = Opcode.isPush;
+export const _isPush = isPush;
+
+/**
+ * Check if opcode is a SWAP instruction
+ */
+export const isSwap = Opcode.isSwap;
+export const _isSwap = isSwap;
+
+/**
+ * Check if opcode terminates execution
+ */
+export const isTerminating = Opcode.isTerminating;
+export const _isTerminating = isTerminating;
+
+/**
+ * Check if opcode is a block terminator
+ */
+export const isTerminator = Opcode.isTerminator;
+export const _isTerminator = isTerminator;
+
+/**
+ * Check if opcode is valid (known)
+ */
+export const isValid = Opcode.isValid;
+export const _isValid = isValid;
+
+/**
+ * Check if opcode is a valid jump destination
+ */
+export const isValidJumpDest = Opcode.isValidJumpDest;
+export const _isValidJumpDest = isValidJumpDest;
+
+/**
+ * Check if opcode value is a valid opcode
+ */
+export const isValidOpcode = Opcode.isValidOpcode;
+export const _isValidOpcode = isValidOpcode;

package/src/primitives/Opcode/pushBytes.ts

@@ -0,0 +1,15 @@
+/**
+ * @module pushBytes
+ * @description Get bytes pushed by PUSH opcode (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Get the number of bytes pushed by a PUSH opcode
+ *
+ * @param opcode - PUSH opcode (0x5f-0x7f)
+ * @returns Number of bytes (0-32)
+ */
+export const pushBytes = Opcode.pushBytes;
+export const _pushBytes = pushBytes;

package/src/primitives/Opcode/pushOpcode.ts

@@ -0,0 +1,15 @@
+/**
+ * @module pushOpcode
+ * @description Get PUSH opcode for given byte count (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Get the PUSH opcode for a given number of bytes
+ *
+ * @param n - Number of bytes (0-32)
+ * @returns PUSH opcode (PUSH0-PUSH32)
+ */
+export const pushOpcode = Opcode.pushOpcode;
+export const _pushOpcode = pushOpcode;

package/src/primitives/Opcode/swapPosition.ts

@@ -0,0 +1,15 @@
+/**
+ * @module swapPosition
+ * @description Get SWAP instruction position (pure)
+ * @since 0.1.0
+ */
+import { Opcode } from "@tevm/voltaire/Opcode";
+
+/**
+ * Get the stack position for a SWAP instruction
+ *
+ * @param opcode - SWAP opcode (0x90-0x9f)
+ * @returns Stack position (1-16), or 0 if not a SWAP
+ */
+export const swapPosition = Opcode.swapPosition;
+export const _swapPosition = swapPosition;

package/src/primitives/Rlp/decodeBatch.ts

@@ -0,0 +1,46 @@
+import {
+	type RlpDecodingError,
+	RlpDecodingError as RlpDecodingErrorClass,
+	Rlp as VoltaireRlp,
+} from "@tevm/voltaire/Rlp";
+import * as Effect from "effect/Effect";
+
+const isRlpDecodingError = (e: unknown): e is RlpDecodingError =>
+	e instanceof RlpDecodingErrorClass ||
+	(e !== null &&
+		typeof e === "object" &&
+		"name" in e &&
+		e.name === "RlpDecodingError");
+
+/**
+ * Decodes multiple RLP-encoded items.
+ *
+ * @param data - Array of RLP-encoded data
+ * @returns Effect that succeeds with array of decoded results or fails with RlpDecodingError
+ *
+ * @example
+ * ```typescript
+ * import * as Effect from 'effect/Effect'
+ * import { decodeBatch, encode } from 'voltaire-effect/primitives/Rlp'
+ *
+ * const items = [
+ *   Effect.runSync(encode([new Uint8Array([1, 2])])),
+ *   Effect.runSync(encode([new Uint8Array([3, 4])]))
+ * ]
+ * const decoded = Effect.runSync(decodeBatch(items))
+ * ```
+ *
+ * @since 0.0.1
+ */
+export const decodeBatch = (
+	data: Uint8Array[],
+): Effect.Effect<unknown[][], RlpDecodingError> =>
+	Effect.try({
+		try: () => VoltaireRlp.decodeBatch(data),
+		catch: (e) =>
+			isRlpDecodingError(e)
+				? e
+				: new RlpDecodingErrorClass("RLP batch decoding failed", {
+						cause: e instanceof Error ? e : undefined,
+					}),
+	});