ox 1.7.5 → 1.8.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # ox
 
+## 1.8.1
+
+### Patch Changes
+
+- [#462](https://github.com/wevm/ox/pull/462) [`16c3378`](https://github.com/wevm/ox/commit/16c33788e1b82a66222ff437f4e1814bda092a47) Thanks [@jxom](https://github.com/jxom)! - Renamed the decoded frame destination from `target` to `to`.
+
+  ```ts
+  Frame.from({ to: recipient });
+  ```
+
+## 1.8.0
+
+### Minor Changes
+
+- [#457](https://github.com/wevm/ox/pull/457) [`bcda555`](https://github.com/wevm/ox/commit/bcda5558e8dd601425b3ddbf469a892c8bae3248) Thanks [@jxom](https://github.com/jxom)! - Added Frame Transactions
+
 ## 1.7.5
 
 ### Patch Changes

package/dist/core/Frame.d.ts

@@ -0,0 +1,290 @@
+import * as Address from './Address.js';
+import * as Bytes from './Bytes.js';
+import * as Errors from './Errors.js';
+import * as Hex from './Hex.js';
+/** An EIP-8141 call frame. */
+export type Frame<bigintType = bigint> = {
+    /**
+     * Frame calldata.
+     * @default '0x'
+     */
+    data?: Hex.Hex | undefined;
+    /**
+     * Approval scope and atomic batching bits.
+     * @default 0
+     */
+    flags?: Flags | undefined;
+    /**
+     * Execution gas budget.
+     * @default 0n
+     */
+    gas?: bigintType | undefined;
+    /**
+     * Execution context: default, verify, or sender.
+     * @default 0
+     */
+    mode?: Mode | undefined;
+    /**
+     * State gas budget.
+     * @default 0n
+     */
+    stateGas?: bigintType | undefined;
+    /** Target address. Omit to target the transaction sender. */
+    to?: Address.Address | undefined;
+    /**
+     * Value transferred by a sender frame, in wei.
+     * @default 0n
+     */
+    value?: bigintType | undefined;
+};
+/** JSON-RPC representation of a frame. */
+export type Rpc = {
+    /** Frame calldata. */
+    data: Hex.Hex;
+    /** Execution gas budget. */
+    executionGasLimit: Hex.Hex;
+    /** Approval scope and batching bits. */
+    flags: number;
+    /** Execution mode. */
+    mode: number;
+    /** State gas budget. */
+    stateGasLimit: Hex.Hex;
+    /** Target address; absent for the transaction sender. */
+    target?: Address.Address | null | undefined;
+    /** Value transferred in wei. */
+    value: Hex.Hex;
+};
+/** Frame execution modes. */
+export declare const modes: {
+    readonly default: 0;
+    readonly sender: 2;
+    readonly verify: 1;
+};
+/** A numeric or named frame execution mode. */
+export type Mode = number | keyof typeof modes;
+/** Approval and atomic batching flags. */
+export declare const flags: {
+    readonly approveExecution: 2;
+    readonly approveExecutionAndPayment: 3;
+    readonly approvePayment: 1;
+    readonly atomicBatch: 4;
+    readonly none: 0;
+};
+/** Numeric approval and batching bits, or a named flag value. */
+export type Flags = number | keyof typeof flags;
+/** RLP-ready frame tuple. Empty target bytes refer to the transaction sender. */
+export type Tuple = readonly [
+    mode: Hex.Hex,
+    flags: Hex.Hex,
+    target: Hex.Hex,
+    limits: readonly [execution: Hex.Hex, state: Hex.Hex],
+    value: Hex.Hex,
+    data: Hex.Hex
+];
+/**
+ * Asserts that a {@link ox#Frame.Frame} satisfies frame-local constraints.
+ *
+ * Sender-dependent approval, batch adjacency, expiry, and transaction-wide gas
+ * constraints require the enclosing transaction.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * Check a verification frame before including it in a transaction.
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * Frame.assert({
+ *   flags: 'approveExecutionAndPayment',
+ *   gas: 50_000n,
+ *   mode: 'verify'
+ * })
+ * ```
+ *
+ * @param frame - The frame to assert.
+ */
+export declare function assert(frame: Frame): void;
+export declare namespace assert {
+    type ErrorType = InvalidError | Address.assert.ErrorType | Hex.assert.ErrorType | Errors.GlobalErrorType;
+}
+/**
+ * Coerces a frame object into a {@link ox#Frame.Frame}.
+ *
+ * Validates the frame and returns a copy, preserving literal types and the supplied
+ * numeric or named mode and flags. Omitted fields stay omitted;
+ * {@link ox#Frame.(toTuple:function)} supplies their defaults when encoding.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * Construct a verification frame that approves execution and payment.
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const frame = Frame.from({
+ *   flags: 'approveExecutionAndPayment',
+ *   gas: 50_000n,
+ *   mode: 'verify'
+ * })
+ * ```
+ *
+ * @param frame - The frame object to convert.
+ * @returns The validated frame.
+ */
+export declare function from<const frame extends Frame>(frame: frame | Frame): frame;
+export declare namespace from {
+    type ErrorType = assert.ErrorType;
+}
+/**
+ * Converts an RPC frame to a frame.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const frame = Frame.fromRpc({
+ *   data: '0x',
+ *   executionGasLimit: '0xc350',
+ *   flags: 3,
+ *   mode: 1,
+ *   stateGasLimit: '0x0',
+ *   value: '0x0'
+ * })
+ * ```
+ *
+ * @param frame - The value to convert.
+ * @returns The converted value.
+ */
+export declare function fromRpc(frame: Rpc): Frame;
+export declare namespace fromRpc {
+    type ErrorType = from.ErrorType | Hex.toBigInt.ErrorType;
+}
+/**
+ * Converts a frame to its JSON-RPC representation.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const frame = Frame.from({ gas: 50_000n, mode: 'verify' })
+ * const rpc = Frame.toRpc(frame)
+ * ```
+ *
+ * @param frame - The value to convert.
+ * @returns The converted value.
+ */
+export declare function toRpc(frame: toRpc.Input): Rpc;
+export declare namespace toRpc {
+    type Input = Frame<Hex.Hex | bigint | number>;
+    type ErrorType = Hex.fromNumber.ErrorType | Errors.GlobalErrorType;
+}
+/**
+ * Converts a {@link ox#Frame.Tuple} to a {@link ox#Frame.Frame}.
+ *
+ * Returns numeric mode and flags. An empty target becomes an omitted `to`.
+ * Integer fields must use minimal whole-byte encodings, with empty bytes for zero.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * Decode a frame tuple with separate execution and state gas limits.
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const frame = Frame.fromTuple([
+ *   '0x01',
+ *   '0x03',
+ *   '0x',
+ *   ['0xc350', '0x'],
+ *   '0x',
+ *   '0x'
+ * ])
+ * // @log: {
+ * // @log:   data: '0x',
+ * // @log:   flags: 3,
+ * // @log:   gas: 50000n,
+ * // @log:   mode: 1,
+ * // @log:   stateGas: 0n,
+ * // @log:   value: 0n
+ * // @log: }
+ * ```
+ *
+ * @param tuple - The frame tuple to convert.
+ * @returns The decoded frame.
+ */
+export declare function fromTuple(tuple: Tuple): Frame;
+export declare namespace fromTuple {
+    type ErrorType = assert.ErrorType | Hex.toNumber.ErrorType | Hex.toBigInt.ErrorType;
+}
+/**
+ * Converts a {@link ox#Frame.Frame} to its RLP-ready {@link ox#Frame.Tuple}.
+ *
+ * Named mode and flags are encoded as integers. An omitted target and zero integer
+ * fields are encoded as empty bytes. Omitted mode and flags default to zero;
+ * omitted gas limits and value default to `0n`, and data defaults to `'0x'`.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * Encode a verification frame in the field order required by EIP-8141.
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const tuple = Frame.toTuple({
+ *   flags: 'approveExecutionAndPayment',
+ *   gas: 50_000n,
+ *   mode: 'verify'
+ * })
+ * // @log: ['0x01', '0x03', '0x', ['0xc350', '0x'], '0x', '0x']
+ * ```
+ *
+ * @param frame - The frame to convert.
+ * @returns The encoded frame tuple.
+ */
+export declare function toTuple(frame: Frame): Tuple;
+export declare namespace toTuple {
+    type ErrorType = assert.ErrorType | Bytes.fromNumber.ErrorType | Hex.fromBytes.ErrorType;
+}
+/**
+ * Returns whether a {@link ox#Frame.Frame} satisfies frame-local constraints.
+ *
+ * Performs the same checks as {@link ox#Frame.(assert:function)}, returning `false`
+ * instead of throwing when the frame is invalid.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * Check whether a frame is structurally valid.
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const valid = Frame.validate({
+ *   flags: 'approveExecutionAndPayment',
+ *   gas: 50_000n,
+ *   mode: 'verify'
+ * })
+ * // @log: true
+ * ```
+ *
+ * @param frame - The frame to validate.
+ * @returns Whether the frame satisfies frame-local constraints.
+ */
+export declare function validate(frame: Frame): boolean;
+export declare namespace validate {
+    type ErrorType = Errors.GlobalErrorType;
+}
+/** Thrown when an EIP-8141 frame is structurally invalid. */
+export declare class InvalidError extends Errors.BaseError {
+    readonly name = "Frame.InvalidError";
+    constructor(details: string);
+}
+//# sourceMappingURL=Frame.d.ts.map

package/dist/core/Frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Frame.d.ts","sourceRoot":"","sources":["../../src/core/Frame.ts"],"names":[],"mappings":"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"}

package/dist/core/Frame.js

@@ -0,0 +1,306 @@
+import * as Address from './Address.js';
+import * as Bytes from './Bytes.js';
+import * as Errors from './Errors.js';
+import * as Hex from './Hex.js';
+import * as Quantity from './internal/quantity.js';
+/** Frame execution modes. */
+export const modes = { default: 0, sender: 2, verify: 1 };
+/** Approval and atomic batching flags. */
+export const flags = {
+    approveExecution: 2,
+    approveExecutionAndPayment: 3,
+    approvePayment: 1,
+    atomicBatch: 4,
+    none: 0,
+};
+/**
+ * Asserts that a {@link ox#Frame.Frame} satisfies frame-local constraints.
+ *
+ * Sender-dependent approval, batch adjacency, expiry, and transaction-wide gas
+ * constraints require the enclosing transaction.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * Check a verification frame before including it in a transaction.
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * Frame.assert({
+ *   flags: 'approveExecutionAndPayment',
+ *   gas: 50_000n,
+ *   mode: 'verify'
+ * })
+ * ```
+ *
+ * @param frame - The frame to assert.
+ */
+export function assert(frame) {
+    const { data = '0x', flags: flagsValue = 0, gas = 0n, mode: modeValue = 0, stateGas = 0n, value = 0n, } = frame;
+    const mode = typeof modeValue === 'string' ? modes[modeValue] : modeValue;
+    if (!Number.isInteger(mode) || mode < 0 || mode > 2)
+        throw new InvalidError('mode must be a supported name or 0, 1, or 2.');
+    const flags_ = typeof flagsValue === 'string' ? flags[flagsValue] : flagsValue;
+    if (!Number.isInteger(flags_) || flags_ < 0 || flags_ > 7)
+        throw new InvalidError('flags must be a supported name or an integer from 0 to 7.');
+    if (flags_ & flags.atomicBatch) {
+        if (mode === modes.verify)
+            throw new InvalidError('VERIFY frames cannot belong to an atomic batch.');
+        if (flags_ & flags.approveExecutionAndPayment)
+            throw new InvalidError('Atomic batch frames cannot approve execution or payment.');
+    }
+    if (frame.to !== undefined)
+        Address.assert(frame.to, { strict: false });
+    for (const [field, limit] of [
+        ['gas', gas],
+        ['stateGas', stateGas],
+    ])
+        if (typeof limit !== 'bigint' || limit < 0n || limit >= 2n ** 64n)
+            throw new InvalidError(`${field} must be an unsigned 64-bit integer.`);
+    if (gas + stateGas >= 2n ** 64n)
+        throw new InvalidError('Combined frame gas must be less than 2^64.');
+    if (typeof value !== 'bigint' || value < 0n || value >= 2n ** 256n)
+        throw new InvalidError('value must be an unsigned 256-bit integer.');
+    if (mode !== modes.sender && value !== 0n)
+        throw new InvalidError('Only SENDER frames can transfer value.');
+    Hex.assert(data, { strict: true });
+    if (data.length % 2 !== 0)
+        throw new InvalidError('data must contain whole bytes.');
+}
+/**
+ * Coerces a frame object into a {@link ox#Frame.Frame}.
+ *
+ * Validates the frame and returns a copy, preserving literal types and the supplied
+ * numeric or named mode and flags. Omitted fields stay omitted;
+ * {@link ox#Frame.(toTuple:function)} supplies their defaults when encoding.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * Construct a verification frame that approves execution and payment.
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const frame = Frame.from({
+ *   flags: 'approveExecutionAndPayment',
+ *   gas: 50_000n,
+ *   mode: 'verify'
+ * })
+ * ```
+ *
+ * @param frame - The frame object to convert.
+ * @returns The validated frame.
+ */
+export function from(frame) {
+    assert(frame);
+    return { ...frame };
+}
+/**
+ * Converts an RPC frame to a frame.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const frame = Frame.fromRpc({
+ *   data: '0x',
+ *   executionGasLimit: '0xc350',
+ *   flags: 3,
+ *   mode: 1,
+ *   stateGasLimit: '0x0',
+ *   value: '0x0'
+ * })
+ * ```
+ *
+ * @param frame - The value to convert.
+ * @returns The converted value.
+ */
+export function fromRpc(frame) {
+    return from({
+        data: frame.data,
+        flags: frame.flags,
+        gas: Hex.toBigInt(frame.executionGasLimit),
+        mode: frame.mode,
+        stateGas: Hex.toBigInt(frame.stateGasLimit),
+        ...(frame.target == null ? {} : { to: frame.target }),
+        value: Hex.toBigInt(frame.value),
+    });
+}
+/**
+ * Converts a frame to its JSON-RPC representation.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const frame = Frame.from({ gas: 50_000n, mode: 'verify' })
+ * const rpc = Frame.toRpc(frame)
+ * ```
+ *
+ * @param frame - The value to convert.
+ * @returns The converted value.
+ */
+export function toRpc(frame) {
+    const { flags: flags_ = 0, mode = 0 } = frame;
+    return {
+        data: frame.data ?? '0x',
+        executionGasLimit: Quantity.fromNumberish(frame.gas ?? 0n),
+        flags: typeof flags_ === 'string' ? flags[flags_] : flags_,
+        mode: typeof mode === 'string' ? modes[mode] : mode,
+        stateGasLimit: Quantity.fromNumberish(frame.stateGas ?? 0n),
+        ...(frame.to === undefined ? {} : { target: frame.to }),
+        value: Quantity.fromNumberish(frame.value ?? 0n),
+    };
+}
+/**
+ * Converts a {@link ox#Frame.Tuple} to a {@link ox#Frame.Frame}.
+ *
+ * Returns numeric mode and flags. An empty target becomes an omitted `to`.
+ * Integer fields must use minimal whole-byte encodings, with empty bytes for zero.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * Decode a frame tuple with separate execution and state gas limits.
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const frame = Frame.fromTuple([
+ *   '0x01',
+ *   '0x03',
+ *   '0x',
+ *   ['0xc350', '0x'],
+ *   '0x',
+ *   '0x'
+ * ])
+ * // @log: {
+ * // @log:   data: '0x',
+ * // @log:   flags: 3,
+ * // @log:   gas: 50000n,
+ * // @log:   mode: 1,
+ * // @log:   stateGas: 0n,
+ * // @log:   value: 0n
+ * // @log: }
+ * ```
+ *
+ * @param tuple - The frame tuple to convert.
+ * @returns The decoded frame.
+ */
+export function fromTuple(tuple) {
+    if (!Array.isArray(tuple) ||
+        tuple.length !== 6 ||
+        !Array.isArray(tuple[3]) ||
+        tuple[3].length !== 2)
+        throw new InvalidError('Expected [mode, flags, target, [execution, state], value, data].');
+    const [mode, flags, target, [execution, state], value, data] = tuple;
+    Hex.assert(target, { strict: true });
+    Hex.assert(data, { strict: true });
+    const quantities = [mode, flags, execution, state, value];
+    for (const quantity of quantities) {
+        Hex.assert(quantity, { strict: true });
+        if (quantity.length % 2 !== 0 || quantity.startsWith('0x00'))
+            throw new InvalidError('Integers must use minimal whole-byte encodings, with empty bytes for zero.');
+    }
+    const frame = {
+        ...(target === '0x' ? {} : { to: target }),
+        data,
+        flags: flags === '0x' ? 0 : Hex.toNumber(flags),
+        gas: execution === '0x' ? 0n : Hex.toBigInt(execution),
+        mode: mode === '0x' ? 0 : Hex.toNumber(mode),
+        stateGas: state === '0x' ? 0n : Hex.toBigInt(state),
+        value: value === '0x' ? 0n : Hex.toBigInt(value),
+    };
+    assert(frame);
+    return frame;
+}
+/**
+ * Converts a {@link ox#Frame.Frame} to its RLP-ready {@link ox#Frame.Tuple}.
+ *
+ * Named mode and flags are encoded as integers. An omitted target and zero integer
+ * fields are encoded as empty bytes. Omitted mode and flags default to zero;
+ * omitted gas limits and value default to `0n`, and data defaults to `'0x'`.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * Encode a verification frame in the field order required by EIP-8141.
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const tuple = Frame.toTuple({
+ *   flags: 'approveExecutionAndPayment',
+ *   gas: 50_000n,
+ *   mode: 'verify'
+ * })
+ * // @log: ['0x01', '0x03', '0x', ['0xc350', '0x'], '0x', '0x']
+ * ```
+ *
+ * @param frame - The frame to convert.
+ * @returns The encoded frame tuple.
+ */
+export function toTuple(frame) {
+    assert(frame);
+    const mode = typeof frame.mode === 'string' ? modes[frame.mode] : (frame.mode ?? 0);
+    const flags_ = typeof frame.flags === 'string' ? flags[frame.flags] : (frame.flags ?? 0);
+    return [
+        mode ? Hex.fromBytes(Bytes.fromNumber(mode)) : '0x',
+        flags_ ? Hex.fromBytes(Bytes.fromNumber(flags_)) : '0x',
+        frame.to ?? '0x',
+        [
+            frame.gas ? Hex.fromBytes(Bytes.fromNumber(frame.gas)) : '0x',
+            frame.stateGas ? Hex.fromBytes(Bytes.fromNumber(frame.stateGas)) : '0x',
+        ],
+        frame.value ? Hex.fromBytes(Bytes.fromNumber(frame.value)) : '0x',
+        frame.data ?? '0x',
+    ];
+}
+/**
+ * Returns whether a {@link ox#Frame.Frame} satisfies frame-local constraints.
+ *
+ * Performs the same checks as {@link ox#Frame.(assert:function)}, returning `false`
+ * instead of throwing when the frame is invalid.
+ *
+ * @example
+ * ### Basic Usage
+ *
+ * Check whether a frame is structurally valid.
+ *
+ * ```ts twoslash
+ * import { Frame } from 'ox'
+ *
+ * const valid = Frame.validate({
+ *   flags: 'approveExecutionAndPayment',
+ *   gas: 50_000n,
+ *   mode: 'verify'
+ * })
+ * // @log: true
+ * ```
+ *
+ * @param frame - The frame to validate.
+ * @returns Whether the frame satisfies frame-local constraints.
+ */
+export function validate(frame) {
+    try {
+        assert(frame);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Thrown when an EIP-8141 frame is structurally invalid. */
+export class InvalidError extends Errors.BaseError {
+    name = 'Frame.InvalidError';
+    constructor(details) {
+        super('Invalid frame.', { details });
+    }
+}
+//# sourceMappingURL=Frame.js.map

package/dist/core/Frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Frame.js","sourceRoot":"","sources":["../../src/core/Frame.ts"],"names":[],"mappings":"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"}