UNPKG

ox

Version:

Ethereum Standard Library

467 lines 21.9 kB
import type * as Address from './Address.js'; import * as Errors from './Errors.js'; import type * as Hash from './Hash.js'; import * as Hex from './Hex.js'; import type { Compute, UnionPartialBy } from './internal/types.js'; import type * as Signature from './Signature.js'; import type * as TransactionRequest from './TransactionRequest.js'; import * as TxEnvelopeEip1559 from './TxEnvelopeEip1559.js'; import * as TxEnvelopeEip2930 from './TxEnvelopeEip2930.js'; import * as TxEnvelopeEip4844 from './TxEnvelopeEip4844.js'; import * as TxEnvelopeEip7702 from './TxEnvelopeEip7702.js'; import * as TxEnvelopeLegacy from './TxEnvelopeLegacy.js'; /** Base type for a Transaction Envelope. Transaction Envelopes inherit this type. */ export type Base<type extends string = string, signed extends boolean = boolean, bigintType = bigint, numberType = number> = Compute<{ /** EIP-155 Chain ID. */ chainId: numberType; /** Contract code or a hashed method call with encoded args */ data?: Hex.Hex | undefined; /** @alias `data` – added for TransactionEnvelope - Transaction compatibility. */ input?: Hex.Hex | undefined; /** * Sender of the transaction. RPC-only metadata; not part of the * serialized envelope. Carried here for parity with * {@link ox#TransactionRequest.TransactionRequest} and * {@link ox#Transaction.Transaction}. */ from?: Address.Address | undefined; /** Gas provided for transaction execution */ gas?: bigintType | undefined; /** Unique number identifying this transaction */ nonce?: bigintType | undefined; /** Transaction recipient */ to?: Address.Address | null | undefined; /** Transaction type */ type: type; /** Value in wei sent with this transaction */ value?: bigintType | undefined; /** ECDSA signature r. */ r?: Hex.Hex | undefined; /** ECDSA signature s. */ s?: Hex.Hex | undefined; /** ECDSA signature yParity. */ yParity?: numberType | undefined; /** @deprecated ECDSA signature v (for backwards compatibility). */ v?: numberType | undefined; } & (signed extends true ? { r: Hex.Hex; s: Hex.Hex; } : {})>; /** RPC representation of a {@link ox#(TransactionEnvelope:namespace).Base}. */ export type BaseRpc<type extends string = string, signed extends boolean = boolean> = Base<type, signed, Hex.Hex, Hex.Hex>; /** Signed representation of a {@link ox#(TransactionEnvelope:namespace).Base}. */ export type BaseSigned<type extends string = string> = Base<type, true>; /** Transaction Envelope. */ export type TxEnvelope<signed extends boolean = false, bigintType = bigint, numberType = number> = UnionPartialBy<TxEnvelopeLegacy.TxEnvelopeLegacy<signed, bigintType, numberType> | TxEnvelopeEip2930.TxEnvelopeEip2930<signed, bigintType, numberType> | TxEnvelopeEip1559.TxEnvelopeEip1559<signed, bigintType, numberType> | TxEnvelopeEip4844.TxEnvelopeEip4844<signed, bigintType, numberType> | TxEnvelopeEip7702.TxEnvelopeEip7702<signed, bigintType, numberType>, 'type'>; /** RPC representation of a {@link ox#(TransactionEnvelope:namespace).TxEnvelope}. */ export type Rpc<signed extends boolean = false> = TxEnvelopeLegacy.Rpc<signed> | TxEnvelopeEip2930.Rpc<signed> | TxEnvelopeEip1559.Rpc<signed> | TxEnvelopeEip4844.Rpc<signed> | TxEnvelopeEip7702.Rpc<signed>; /** Serialized Transaction Envelope. */ export type Serialized = TxEnvelopeLegacy.Serialized | TxEnvelopeEip2930.Serialized | TxEnvelopeEip1559.Serialized | TxEnvelopeEip4844.Serialized | TxEnvelopeEip7702.Serialized; /** Transaction Envelope type. */ export type Type = TxEnvelopeLegacy.Type | TxEnvelopeEip2930.Type | TxEnvelopeEip1559.Type | TxEnvelopeEip4844.Type | TxEnvelopeEip7702.Type; type Typeable = TxEnvelope | { readonly [key: string]: unknown; readonly type?: string | undefined; }; type HasDefined<envelope, key extends string> = envelope extends { [_ in key]: infer value; } ? [Exclude<value, undefined>] extends [never] ? false : true : false; /** * Asserts a {@link ox#(TransactionEnvelope:namespace).TxEnvelope} is valid. * * @example * ```ts twoslash * import { TransactionEnvelope } from 'ox' * * TransactionEnvelope.assert({ * chainId: 1, * maxFeePerGas: 1n, * type: 'eip1559' * }) * ``` * * @param envelope - The transaction envelope to assert. */ export declare function assert(envelope: TxEnvelope): void; export declare namespace assert { type ErrorType = TxEnvelopeLegacy.assert.ErrorType | TxEnvelopeEip2930.assert.ErrorType | TxEnvelopeEip1559.assert.ErrorType | TxEnvelopeEip4844.assert.ErrorType | TxEnvelopeEip7702.assert.ErrorType | InvalidTypeError | Errors.GlobalErrorType; } /** * Deserializes a {@link ox#(TransactionEnvelope:namespace).TxEnvelope} from its serialized form. * * @example * ```ts twoslash * import { TransactionEnvelope } from 'ox' * * const envelope = TransactionEnvelope.deserialize( * '0x02df0180808080808080c0' as TransactionEnvelope.Serialized * ) * ``` * * @param serialized - The serialized transaction envelope. * @returns Deserialized Transaction Envelope. */ export declare function deserialize<const serialized extends Serialized | Hex.Hex>(serialized: serialized | Serialized | Hex.Hex): deserialize.ReturnType<serialized>; export declare namespace deserialize { type ReturnType<serialized extends Serialized | Hex.Hex = Serialized> = serialized extends TxEnvelopeLegacy.Serialized ? TxEnvelopeLegacy.TxEnvelopeLegacy : serialized extends TxEnvelopeEip2930.Serialized ? TxEnvelopeEip2930.TxEnvelopeEip2930 : serialized extends TxEnvelopeEip1559.Serialized ? TxEnvelopeEip1559.TxEnvelopeEip1559 : serialized extends TxEnvelopeEip4844.Serialized ? TxEnvelopeEip4844.TxEnvelopeEip4844 : serialized extends TxEnvelopeEip7702.Serialized ? TxEnvelopeEip7702.TxEnvelopeEip7702 : TxEnvelope; type ErrorType = getSerializedType.ErrorType | TxEnvelopeLegacy.deserialize.ErrorType | TxEnvelopeEip2930.deserialize.ErrorType | TxEnvelopeEip1559.deserialize.ErrorType | TxEnvelopeEip4844.deserialize.ErrorType | TxEnvelopeEip7702.deserialize.ErrorType | Errors.GlobalErrorType; } /** * Converts an arbitrary transaction object or serialized transaction into a Transaction Envelope. * * @example * ```ts twoslash * import { TransactionEnvelope } from 'ox' * * const envelope = TransactionEnvelope.from({ * chainId: 1, * maxFeePerGas: 1n, * type: 'eip1559' * }) * ``` * * @param envelope - The transaction envelope. * @param options - Options. * @returns Transaction Envelope. */ export declare function from<const envelope extends Typeable | Hex.Hex, const signature extends Signature.Signature | undefined = undefined>(envelope: envelope | Typeable | Hex.Hex, options?: from.Options<signature>): from.ReturnType<envelope>; export declare namespace from { type Options<signature extends Signature.Signature | undefined = undefined> = { /** Signature to append to the Transaction Envelope. */ signature?: signature | Signature.Signature | undefined; }; type ReturnType<envelope extends Typeable | Hex.Hex = TxEnvelope | Hex.Hex, signature extends Signature.Signature | undefined = undefined> = envelope extends Hex.Hex ? deserialize.ReturnType<envelope> : ReturnType_object<Extract<envelope, Typeable>, signature>; type ReturnType_object<envelope extends Typeable, signature extends Signature.Signature | undefined = undefined> = getType.ReturnType<envelope> extends 'legacy' ? TxEnvelopeLegacy.from.ReturnType<envelope & TxEnvelopeLegacy.TxEnvelopeLegacy, signature> : getType.ReturnType<envelope> extends 'eip2930' ? TxEnvelopeEip2930.from.ReturnType<envelope & TxEnvelopeEip2930.TxEnvelopeEip2930, signature> : getType.ReturnType<envelope> extends 'eip4844' ? TxEnvelopeEip4844.from.ReturnType<envelope & TxEnvelopeEip4844.TxEnvelopeEip4844, signature> : getType.ReturnType<envelope> extends 'eip7702' ? TxEnvelopeEip7702.from.ReturnType<envelope & TxEnvelopeEip7702.TxEnvelopeEip7702, signature> : TxEnvelopeEip1559.from.ReturnType<Omit<envelope, 'type'> & TxEnvelopeEip1559.TxEnvelopeEip1559, signature>; type ErrorType = deserialize.ErrorType | TxEnvelopeLegacy.from.ErrorType | TxEnvelopeEip2930.from.ErrorType | TxEnvelopeEip1559.from.ErrorType | TxEnvelopeEip4844.from.ErrorType | TxEnvelopeEip7702.from.ErrorType | InvalidTypeError | Errors.GlobalErrorType; } /** * Returns the payload to sign for a {@link ox#(TransactionEnvelope:namespace).TxEnvelope}. * * @example * ```ts twoslash * import { TransactionEnvelope } from 'ox' * * const payload = TransactionEnvelope.getSignPayload({ * chainId: 1, * maxFeePerGas: 1n, * type: 'eip1559' * }) * ``` * * @param envelope - The transaction envelope. * @returns The sign payload. */ export declare function getSignPayload(envelope: TxEnvelope<false>): Hex.Hex; export declare namespace getSignPayload { type ReturnType = Hex.Hex; type ErrorType = TxEnvelopeLegacy.getSignPayload.ErrorType | TxEnvelopeEip2930.getSignPayload.ErrorType | TxEnvelopeEip1559.getSignPayload.ErrorType | TxEnvelopeEip4844.getSignPayload.ErrorType | TxEnvelopeEip7702.getSignPayload.ErrorType | InvalidTypeError | Errors.GlobalErrorType; } /** * Returns the type of a Transaction Envelope. * * @example * ```ts twoslash * import { TransactionEnvelope } from 'ox' * * const type = TransactionEnvelope.getType({ * maxFeePerGas: 1n * }) * // @log: 'eip1559' * ``` * * @param envelope - The transaction envelope. * @returns Transaction Envelope type. */ export declare function getType<const envelope extends Typeable>(envelope: envelope | Typeable): getType.ReturnType<envelope>; export declare namespace getType { type ReturnType<envelope extends Typeable> = envelope extends { type: infer type extends string; } ? type : HasDefined<envelope, 'authorizationList'> extends true ? TxEnvelopeEip7702.Type : HasDefined<envelope, 'blobs'> extends true ? TxEnvelopeEip4844.Type : HasDefined<envelope, 'blobVersionedHashes'> extends true ? TxEnvelopeEip4844.Type : HasDefined<envelope, 'sidecars'> extends true ? TxEnvelopeEip4844.Type : HasDefined<envelope, 'maxFeePerBlobGas'> extends true ? TxEnvelopeEip4844.Type : HasDefined<envelope, 'maxFeePerGas'> extends true ? TxEnvelopeEip1559.Type : HasDefined<envelope, 'maxPriorityFeePerGas'> extends true ? TxEnvelopeEip1559.Type : HasDefined<envelope, 'gasPrice'> extends true ? HasDefined<envelope, 'accessList'> extends true ? TxEnvelopeEip2930.Type : TxEnvelopeLegacy.Type : TxEnvelopeEip1559.Type; type ErrorType = InvalidTypeError | Errors.GlobalErrorType; } /** * Returns the type of a serialized Transaction Envelope. * * @example * ```ts twoslash * import { TransactionEnvelope } from 'ox' * * const type = TransactionEnvelope.getSerializedType( * '0x02df0180808080808080c0' * ) * // @log: 'eip1559' * ``` * * @param serialized - The serialized transaction envelope. * @returns Transaction Envelope type. */ export declare function getSerializedType<const serialized extends Serialized | Hex.Hex>(serialized: serialized | Serialized | Hex.Hex): getSerializedType.ReturnType<serialized>; export declare namespace getSerializedType { type ReturnType<serialized extends Serialized | Hex.Hex = Serialized> = serialized extends TxEnvelopeEip2930.Serialized ? TxEnvelopeEip2930.Type : serialized extends TxEnvelopeEip1559.Serialized ? TxEnvelopeEip1559.Type : serialized extends TxEnvelopeEip4844.Serialized ? TxEnvelopeEip4844.Type : serialized extends TxEnvelopeEip7702.Serialized ? TxEnvelopeEip7702.Type : serialized extends TxEnvelopeLegacy.Serialized ? TxEnvelopeLegacy.Type : Type; type ErrorType = Hex.size.ErrorType | Hex.slice.ErrorType | Hex.toNumber.ErrorType | InvalidSerializedTypeError | Errors.GlobalErrorType; } /** * Hashes a {@link ox#(TransactionEnvelope:namespace).TxEnvelope}. This is the "transaction hash". * * @example * ```ts twoslash * import { TransactionEnvelope } from 'ox' * * const hash = TransactionEnvelope.hash( * { * chainId: 1, * maxFeePerGas: 1n, * type: 'eip1559' * }, * { presign: true } * ) * ``` * * @param envelope - The transaction envelope to hash. * @param options - Options. * @returns The hash of the transaction envelope. */ export declare function hash<presign extends boolean = false>(envelope: TxEnvelope<presign extends true ? false : true>, options?: hash.Options<presign>): hash.ReturnType; export declare namespace hash { type Options<presign extends boolean = false> = { /** Whether to hash this transaction for signing. @default false */ presign?: presign | boolean | undefined; }; type ReturnType = Hex.Hex; type ErrorType = Hash.keccak256.ErrorType | serialize.ErrorType | InvalidTypeError | Errors.GlobalErrorType; } /** * Serializes a {@link ox#(TransactionEnvelope:namespace).TxEnvelope}. * * @example * ```ts twoslash * import { TransactionEnvelope } from 'ox' * * const serialized = TransactionEnvelope.serialize({ * chainId: 1, * maxFeePerGas: 1n, * type: 'eip1559' * }) * ``` * * @param envelope - The transaction envelope to serialize. * @param options - Options. * @returns Serialized transaction envelope. */ export declare function serialize<const envelope extends Typeable>(envelope: envelope | Typeable, options?: serialize.Options): serialize.ReturnType<envelope>; export declare namespace serialize { type Options = { /** Signature to append to the serialized Transaction Envelope. */ signature?: Signature.Signature | undefined; /** PeerDAS sidecars to append, producing the 5-element network wrapper. */ sidecars?: TxEnvelopeEip4844.Sidecars<Hex.Hex> | undefined; }; type ReturnType<envelope extends Typeable = TxEnvelope> = getType.ReturnType<envelope> extends 'legacy' ? TxEnvelopeLegacy.Serialized : getType.ReturnType<envelope> extends 'eip2930' ? TxEnvelopeEip2930.Serialized : getType.ReturnType<envelope> extends 'eip4844' ? TxEnvelopeEip4844.Serialized : getType.ReturnType<envelope> extends 'eip7702' ? TxEnvelopeEip7702.Serialized : TxEnvelopeEip1559.Serialized; type ErrorType = TxEnvelopeLegacy.serialize.ErrorType | TxEnvelopeEip2930.serialize.ErrorType | TxEnvelopeEip1559.serialize.ErrorType | TxEnvelopeEip4844.serialize.ErrorType | TxEnvelopeEip7702.serialize.ErrorType | InvalidTypeError | Errors.GlobalErrorType; } /** * Converts a {@link ox#(TransactionEnvelope:namespace).TxEnvelope} to an {@link ox#(TransactionEnvelope:namespace).Rpc}. * * @example * ```ts twoslash * import { TransactionEnvelope } from 'ox' * * const envelope_rpc = TransactionEnvelope.toRpc({ * chainId: 1, * maxFeePerGas: 1n, * type: 'eip1559' * }) * ``` * * @param envelope - The transaction envelope. * @returns RPC representation. */ export declare function toRpc<const envelope extends toRpc.Input>(envelope: envelope | toRpc.Input): toRpc.ReturnType<envelope>; export declare namespace toRpc { /** Numberish input accepted by {@link ox#(TransactionEnvelope:namespace).(toRpc:function)}. */ type Input = TxEnvelope<boolean, Hex.Hex | bigint | number, Hex.Hex | number>; type ReturnType<envelope extends Typeable = TxEnvelope> = getType.ReturnType<envelope> extends 'legacy' ? TxEnvelopeLegacy.Rpc : getType.ReturnType<envelope> extends 'eip2930' ? TxEnvelopeEip2930.Rpc : getType.ReturnType<envelope> extends 'eip4844' ? TxEnvelopeEip4844.Rpc : getType.ReturnType<envelope> extends 'eip7702' ? TxEnvelopeEip7702.Rpc : TxEnvelopeEip1559.Rpc; type ErrorType = TxEnvelopeLegacy.toRpc.ErrorType | TxEnvelopeEip2930.toRpc.ErrorType | TxEnvelopeEip1559.toRpc.ErrorType | TxEnvelopeEip4844.toRpc.ErrorType | TxEnvelopeEip7702.toRpc.ErrorType | InvalidTypeError | Errors.GlobalErrorType; } /** * Converts a {@link ox#(TransactionEnvelope:namespace).TxEnvelope} to a {@link ox#TransactionRequest.TransactionRequest}. * * Flattens any EIP-7594 `sidecars` back into the top-level `blobs` field. * Signature fields (`r`, `s`, `yParity`, `v`) are preserved — Ox's * `TransactionRequest` extends the Execution API `GenericTransaction` * shape to optionally carry signed payloads. Pair with * {@link ox#TransactionRequest.(toRpc:function)} to produce an * `eth_sendTransaction`-shaped payload. * * Note: the 4844 round-trip * `TxEnvelope → TransactionRequest → TxEnvelope` is **lossy** — * `sidecars.commitments` and `sidecars.cellProofs` are not preserved on * the `TransactionRequest` shape. Callers that need full round-trip * parity must carry sidecars out of band. * * @example * ```ts twoslash * import { TransactionEnvelope, TxEnvelopeEip1559 } from 'ox' * * const envelope = TxEnvelopeEip1559.from({ * chainId: 1, * maxFeePerGas: 1n, * to: '0x0000000000000000000000000000000000000000', * value: 1n * }) * * const request = * TransactionEnvelope.toTransactionRequest(envelope) * // @log: { * // @log: chainId: 1, * // @log: maxFeePerGas: 1n, * // @log: to: '0x0000000000000000000000000000000000000000', * // @log: type: 'eip1559', * // @log: value: 1n, * // @log: } * ``` * * @param envelope - The transaction envelope to convert. * @returns A transaction request. */ export declare function toTransactionRequest(envelope: TxEnvelope): TransactionRequest.TransactionRequest; export declare namespace toTransactionRequest { type ErrorType = Errors.GlobalErrorType; } /** * Validates a {@link ox#(TransactionEnvelope:namespace).TxEnvelope}. Returns `true` if the envelope is valid, `false` otherwise. * * @example * ```ts twoslash * import { TransactionEnvelope } from 'ox' * * const valid = TransactionEnvelope.validate({ * chainId: 1, * maxFeePerGas: 1n, * type: 'eip1559' * }) * // @log: true * ``` * * @param envelope - The transaction envelope to validate. */ export declare function validate(envelope: TxEnvelope): boolean; export declare namespace validate { type ErrorType = Errors.GlobalErrorType; } /** * Thrown when a fee cap is too high. * * @example * ```ts twoslash * import { TxEnvelopeEip1559 } from 'ox' * * TxEnvelopeEip1559.assert({ * maxFeePerGas: 2n ** 256n - 1n + 1n, * chainId: 1 * }) * // @error: TransactionEnvelope.FeeCapTooHighError: The fee cap (`maxFeePerGas`/`maxPriorityFeePerGas` = 115792089237316195423570985008687907853269984665640564039457584007913.129639936 gwei) cannot be higher than the maximum allowed value (2^256-1). * ``` */ export declare class FeeCapTooHighError extends Errors.BaseError { readonly name = "TransactionEnvelope.FeeCapTooHighError"; constructor({ feeCap, }?: { feeCap?: bigint | undefined; }); } /** * Thrown when a gas price is too high. * * @example * ```ts twoslash * import { TxEnvelopeLegacy } from 'ox' * * TxEnvelopeLegacy.assert({ * gasPrice: 2n ** 256n - 1n + 1n, * chainId: 1 * }) * // @error: TransactionEnvelope.GasPriceTooHighError: The gas price (`gasPrice` = 115792089237316195423570985008687907853269984665640564039457584007913.129639936 gwei) cannot be higher than the maximum allowed value (2^256-1). * ``` */ export declare class GasPriceTooHighError extends Errors.BaseError { readonly name = "TransactionEnvelope.GasPriceTooHighError"; constructor({ gasPrice, }?: { gasPrice?: bigint | undefined; }); } /** * Thrown when a chain ID is invalid. * * @example * ```ts twoslash * import { TxEnvelopeEip1559 } from 'ox' * * TxEnvelopeEip1559.assert({ chainId: 0 }) * // @error: TransactionEnvelope.InvalidChainIdError: Chain ID "0" is invalid. * ``` */ export declare class InvalidChainIdError extends Errors.BaseError { readonly name = "TransactionEnvelope.InvalidChainIdError"; constructor({ chainId }: { chainId?: number | undefined; }); } /** * Thrown when a serialized transaction is invalid. * * @example * ```ts twoslash * import { TxEnvelopeEip1559 } from 'ox' * * TxEnvelopeEip1559.deserialize('0x02c0') * // @error: TransactionEnvelope.InvalidSerializedError: Invalid serialized transaction of type "eip1559" was provided. * // @error: Serialized Transaction: "0x02c0" * // @error: Missing Attributes: chainId, nonce, maxPriorityFeePerGas, maxFeePerGas, gas, to, value, data, accessList * ``` */ export declare class InvalidSerializedError extends Errors.BaseError { readonly name = "TransactionEnvelope.InvalidSerializedError"; constructor({ attributes, serialized, type, }: { attributes: Record<string, unknown>; serialized: Hex.Hex; type: string; }); } /** Thrown when a serialized transaction type cannot be resolved. */ export declare class InvalidSerializedTypeError extends Errors.BaseError { readonly name = "TransactionEnvelope.InvalidSerializedTypeError"; constructor({ serialized }: { serialized: Hex.Hex; }); } /** Thrown when a transaction envelope type cannot be resolved. */ export declare class InvalidTypeError extends Errors.BaseError { readonly name = "TransactionEnvelope.InvalidTypeError"; constructor({ type }?: { type?: string | undefined; }); } /** * Thrown when a tip is higher than a fee cap. * * @example * ```ts twoslash * import { TxEnvelopeEip1559 } from 'ox' * * TxEnvelopeEip1559.assert({ * chainId: 1, * maxFeePerGas: 10n, * maxPriorityFeePerGas: 11n * }) * // @error: TransactionEnvelope.TipAboveFeeCapError: The provided tip (`maxPriorityFeePerGas` = 11 gwei) cannot be higher than the fee cap (`maxFeePerGas` = 10 gwei). * ``` */ export declare class TipAboveFeeCapError extends Errors.BaseError { readonly name = "TransactionEnvelope.TipAboveFeeCapError"; constructor({ maxPriorityFeePerGas, maxFeePerGas, }?: { maxPriorityFeePerGas?: bigint | undefined; maxFeePerGas?: bigint | undefined; }); } export {}; //# sourceMappingURL=TxEnvelope.d.ts.map