@matterlabs/zksync-js 0.0.1

package/dist/core/resources/deposits/route.d.ts

@@ -0,0 +1,6 @@
+import type { Address } from '../../types/primitives';
+import type { DepositRoute } from '../../types/flows/deposits';
+export interface BaseTokenLookup {
+    baseToken(chainId: bigint): Promise<Address>;
+}
+export declare function pickDepositRoute(client: BaseTokenLookup, chainIdL2: bigint, token: Address): Promise<DepositRoute>;

package/dist/core/resources/withdrawals/events.d.ts

@@ -0,0 +1,9 @@
+import type { ParsedLog, ParsedReceipt } from '../../types/flows/withdrawals';
+type Prefer = 'messenger' | 'assetRouter' | {
+    address: string;
+};
+export declare function findL1MessageSentLog(receipt: ParsedReceipt, opts?: {
+    prefer?: Prefer;
+    index?: number;
+}): ParsedLog;
+export {};

package/dist/core/resources/withdrawals/logs.d.ts

@@ -0,0 +1,5 @@
+import type { ReceiptWithL2ToL1 } from '../../rpc/types';
+export declare function messengerLogIndex(raw: ReceiptWithL2ToL1, opts?: {
+    index?: number;
+    messenger?: string;
+}): number;

package/dist/core/resources/withdrawals/route.d.ts

@@ -0,0 +1,6 @@
+import type { WithdrawRoute } from '../../types/flows/withdrawals';
+import type { Address } from '../../types/primitives';
+export declare function pickWithdrawRoute(args: {
+    token: Address;
+    baseIsEth: boolean;
+}): WithdrawRoute;

package/dist/core/rpc/transport.d.ts

@@ -0,0 +1,10 @@
+import type { RpcTransport } from './types';
+export declare function makeTransportFromEthers(provider: {
+    send: (m: string, p: unknown[]) => Promise<unknown>;
+}): RpcTransport;
+export declare function makeTransportFromViem(client: {
+    request: (args: {
+        method: string;
+        params?: unknown[];
+    }) => Promise<unknown>;
+}): RpcTransport;

package/dist/core/rpc/types.d.ts

@@ -0,0 +1,40 @@
+import type { Hex, Address } from '../types/primitives';
+export type L2ToL1Log = {
+    l2_shard_id: number;
+    is_service: boolean;
+    tx_number_in_block: number;
+    sender: Address;
+    key: Hex;
+    value: Hex;
+};
+export type ReceiptWithL2ToL1 = {
+    transactionHash?: Hex;
+    status?: string | number;
+    blockNumber?: string | number;
+    logs?: Array<{
+        address: Address;
+        topics: Hex[];
+        data: Hex;
+    }>;
+    l2ToL1Logs?: L2ToL1Log[];
+};
+export type ProofNormalized = {
+    id: bigint;
+    batchNumber: bigint;
+    proof: Hex[];
+};
+export type GenesisContractDeployment = {
+    address: Address;
+    bytecode: Hex;
+};
+export type GenesisStorageEntry = {
+    key: Hex;
+    value: Hex;
+};
+export type GenesisInput = {
+    initialContracts: GenesisContractDeployment[];
+    additionalStorage: GenesisStorageEntry[];
+    executionVersion: number;
+    genesisRoot: Hex;
+};
+export type RpcTransport = (method: string, params?: unknown[]) => Promise<any>;

package/dist/core/rpc/zks.d.ts

@@ -0,0 +1,12 @@
+import type { RpcTransport, ReceiptWithL2ToL1, ProofNormalized, GenesisInput } from './types';
+import type { Hex, Address } from '../types/primitives';
+/** ZKsync-specific RPC methods. */
+export interface ZksRpc {
+    getBridgehubAddress(): Promise<Address>;
+    getL2ToL1LogProof(txHash: Hex, index: number): Promise<ProofNormalized>;
+    getReceiptWithL2ToL1(txHash: Hex): Promise<ReceiptWithL2ToL1 | null>;
+    getGenesis(): Promise<GenesisInput>;
+}
+export declare function normalizeProof(p: unknown): ProofNormalized;
+export declare function normalizeGenesis(raw: unknown): GenesisInput;
+export declare function createZksRpc(transport: RpcTransport): ZksRpc;

package/dist/core/types/errors.d.ts

@@ -0,0 +1,177 @@
+export type ErrorType = 'VALIDATION' | 'STATE' | 'EXECUTION' | 'RPC' | 'INTERNAL' | 'VERIFICATION' | 'CONTRACT';
+/** Resource surface */
+export type Resource = 'deposits' | 'withdrawals' | 'withdrawal-finalization' | 'helpers' | 'zksrpc';
+/** Envelope we throw only for SDK-domain errors. */
+export interface ErrorEnvelope {
+    /** Resource surface that raised the error. */
+    resource: Resource;
+    /** SDK operation, e.g. 'withdrawals.finalize' */
+    operation: string;
+    /** Broad category */
+    type: ErrorType;
+    /** Human-readable, stable message for developers. */
+    message: string;
+    /** Optional detail that adapters may enrich (reverts, extra context) */
+    context?: Record<string, unknown>;
+    /** If the error is a contract revert, adapters add decoded info here. */
+    revert?: {
+        /** 4-byte selector as 0x…8 hex */
+        selector: `0x${string}`;
+        /** Decoded error name when available (e.g. 'InvalidProof') */
+        name?: string;
+        /** Decoded args (ethers/viem output), when available */
+        args?: unknown[];
+        /** Optional adapter-known labels */
+        contract?: string;
+        /** Optional adapter-known function name */
+        fn?: string;
+    };
+    /** Original thrown error  */
+    cause?: unknown;
+}
+/** Error class.
+ * Represents an error that occurs within the ZKsync SDK.
+ * It encapsulates an ErrorEnvelope which provides detailed information about the error,
+ *
+ */
+export declare class ZKsyncError extends Error {
+    readonly envelope: ErrorEnvelope;
+    constructor(envelope: ErrorEnvelope);
+    toJSON(): {
+        /** Resource surface that raised the error. */
+        resource: Resource;
+        /** SDK operation, e.g. 'withdrawals.finalize' */
+        operation: string;
+        /** Broad category */
+        type: ErrorType;
+        /** Human-readable, stable message for developers. */
+        message: string;
+        /** Optional detail that adapters may enrich (reverts, extra context) */
+        context?: Record<string, unknown>;
+        /** If the error is a contract revert, adapters add decoded info here. */
+        revert?: {
+            /** 4-byte selector as 0x…8 hex */
+            selector: `0x${string}`;
+            /** Decoded error name when available (e.g. 'InvalidProof') */
+            name?: string;
+            /** Decoded args (ethers/viem output), when available */
+            args?: unknown[];
+            /** Optional adapter-known labels */
+            contract?: string;
+            /** Optional adapter-known function name */
+            fn?: string;
+        };
+        /** Original thrown error  */
+        cause?: unknown;
+        name: string;
+    };
+}
+export declare function isZKsyncError(e: unknown): e is ZKsyncError;
+export declare function isReceiptNotFound(e: unknown): boolean;
+export type TryResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: ZKsyncError;
+};
+export declare const OP_DEPOSITS: {
+    readonly quote: "deposits.quote";
+    readonly tryQuote: "deposits.tryQuote";
+    readonly prepare: "deposits.prepare";
+    readonly tryPrepare: "deposits.tryPrepare";
+    readonly create: "deposits.create";
+    readonly tryCreate: "deposits.tryCreate";
+    readonly status: "deposits.status";
+    readonly wait: "deposits.wait";
+    readonly tryWait: "deposits.tryWait";
+    readonly base: {
+        readonly assertErc20Asset: "deposits.erc20-base:assertErc20Asset";
+        readonly assertMatchesBase: "deposits.erc20-base:assertMatchesBase";
+        readonly baseToken: "deposits.erc20-base:baseToken";
+        readonly allowance: "deposits.erc20-base:allowance";
+        readonly baseCost: "deposits.erc20-base:l2TransactionBaseCost";
+        readonly estGas: "deposits.erc20-base:estimateGas";
+    };
+    readonly nonbase: {
+        readonly baseToken: "deposits.erc20-nonbase:baseToken";
+        readonly assertNotEthAsset: "deposits.erc20-nonbase:assertNotEthAsset";
+        readonly allowance: "deposits.erc20-nonbase:allowance";
+        readonly allowanceFees: "deposits.erc20-nonbase:allowanceFeesBaseToken";
+        readonly baseCost: "deposits.erc20-nonbase:l2TransactionBaseCost";
+        readonly encodeCalldata: "deposits.erc20-nonbase:encodeSecondBridgeErc20Args";
+        readonly estGas: "deposits.erc20-nonbase:estimateGas";
+        readonly assertBaseIsEth: "deposits.erc20-nonbase:assertBaseIsEth";
+        readonly assertBaseIsErc20: "deposits.erc20-nonbase:assertBaseIsErc20";
+        readonly assertNonBaseToken: "deposits.erc20-nonbase:assertNonBaseToken";
+        readonly allowanceToken: "deposits.erc20-nonbase:allowanceToken";
+        readonly allowanceBase: "deposits.erc20-nonbase:allowanceBase";
+    };
+    readonly eth: {
+        readonly baseCost: "deposits.eth:l2TransactionBaseCost";
+        readonly estGas: "deposits.eth:estimateGas";
+    };
+    readonly ethNonBase: {
+        readonly baseToken: "deposits.eth-nonbase:baseToken";
+        readonly baseCost: "deposits.eth-nonbase:l2TransactionBaseCost";
+        readonly allowanceBase: "deposits.eth-nonbase:allowanceBaseToken";
+        readonly ethBalance: "deposits.eth-nonbase:getEthBalance";
+        readonly encodeCalldata: "deposits.eth-nonbase:encodeSecondBridgeEthArgs";
+        readonly estGas: "deposits.eth-nonbase:estimateGas";
+        readonly assertEthAsset: "deposits.eth-nonbase:assertEthAsset";
+        readonly assertNonEthBase: "deposits.eth-nonbase:assertNonEthBase";
+        readonly assertEthBalance: "deposits.eth-nonbase:assertEthBalance";
+    };
+};
+export declare const OP_WITHDRAWALS: {
+    readonly quote: "withdrawals.quote";
+    readonly tryQuote: "withdrawals.tryQuote";
+    readonly prepare: "withdrawals.prepare";
+    readonly tryPrepare: "withdrawals.tryPrepare";
+    readonly create: "withdrawals.create";
+    readonly tryCreate: "withdrawals.tryCreate";
+    readonly status: "withdrawals.status";
+    readonly wait: "withdrawals.wait";
+    readonly tryWait: "withdrawals.tryWait";
+    readonly erc20: {
+        readonly allowance: "withdrawals.erc20:allowance";
+        readonly ensureRegistered: "withdrawals.erc20:ensureTokenIsRegistered";
+        readonly encodeAssetData: "withdrawals.erc20:encodeAssetData";
+        readonly encodeWithdraw: "withdrawals.erc20:encodeWithdraw";
+        readonly estGas: "withdrawals.erc20:estimateGas";
+    };
+    readonly eth: {
+        readonly encodeWithdraw: "withdrawals.eth:encodeWithdraw";
+        readonly estGas: "withdrawals.eth:estimateGas";
+    };
+    readonly ethNonBase: {
+        readonly allowance: "withdrawals.eth-nonbase:allowance";
+        readonly ensureRegistered: "withdrawals.eth-nonbase:ensureTokenIsRegistered";
+        readonly encodeAssetData: "withdrawals.eth-nonbase:encodeAssetData";
+        readonly encodeWithdraw: "withdrawals.eth-nonbase:encodeWithdraw";
+        readonly estGas: "withdrawals.eth-nonbase:estimateGas";
+        readonly baseToken: "withdrawals.eth-nonbase:baseToken";
+        readonly assertNonEthBase: "withdrawals.eth-nonbase:assertNonEthBase";
+    };
+    readonly finalize: {
+        readonly fetchParams: {
+            readonly receipt: "withdrawals.finalize.fetchParams:receipt";
+            readonly findMessage: "withdrawals.finalize.fetchParams:findMessage";
+            readonly decodeMessage: "withdrawals.finalize.fetchParams:decodeMessage";
+            readonly rawReceipt: "withdrawals.finalize.fetchParams:rawReceipt";
+            readonly messengerIndex: "withdrawals.finalize.fetchParams:messengerIndex";
+            readonly proof: "withdrawals.finalize.fetchParams:proof";
+            readonly network: "withdrawals.finalize.fetchParams:network";
+            readonly ensureAddresses: "withdrawals.finalize.fetchParams:ensureAddresses";
+        };
+        readonly readiness: {
+            readonly ensureAddresses: "withdrawals.finalize.readiness:ensureAddresses";
+            readonly isFinalized: "withdrawals.finalize.readiness:isWithdrawalFinalized";
+            readonly simulate: "withdrawals.finalize.readiness:simulate";
+        };
+        readonly isFinalized: "withdrawals.finalize.isWithdrawalFinalized";
+        readonly send: "withdrawals.finalize.finalizeDeposit:send";
+        readonly wait: "withdrawals.finalize.finalizeDeposit:wait";
+        readonly estimate: "withdrawals.finalize.estimateFinalizationFees";
+    };
+};

package/dist/core/types/flows/base.d.ts

@@ -0,0 +1,51 @@
+import type { Address, Hex } from '../primitives';
+export interface Eip1559GasOverrides {
+    gasLimit?: bigint;
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+}
+export interface ResolvedEip1559Fees {
+    gasLimit?: bigint;
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+}
+/** Generic approval requirement */
+export interface ApprovalNeed {
+    token: Address;
+    spender: Address;
+    amount: bigint;
+}
+/** Generic step (adapter injects Tx type) */
+export interface PlanStep<Tx, Preview = undefined> {
+    key: string;
+    kind: string;
+    description: string;
+    /** Adapter-specific request (ethers TransactionRequest, viem WriteContractParameters, etc.) */
+    tx: Tx;
+    /** Optional compact, human-friendly view for logging/UI */
+    preview?: Preview;
+}
+/** Generic plan */
+export interface Plan<Tx, Route, Quote> {
+    route: Route;
+    summary: Quote;
+    steps: Array<PlanStep<Tx>>;
+}
+/** Generic handle (returned by create()) */
+export interface Handle<TxHashMap extends Record<string, Hex>, Route, PlanT> {
+    kind: 'deposit' | 'withdrawal';
+    route?: Route;
+    stepHashes: TxHashMap;
+    plan: PlanT;
+}
+/** Waitable inputs */
+export type Waitable<HashKey extends string = 'txHash'> = Hex | Record<HashKey, Hex> | {
+    [k in HashKey]?: Hex;
+} | {
+    stepHashes?: Record<string, Hex>;
+};
+export interface CommonCtx {
+    sender: Address;
+    chainIdL2: bigint;
+    bridgehub: Address;
+}

package/dist/core/types/flows/deposits.d.ts

@@ -0,0 +1,43 @@
+import type { Address, Hex } from '../primitives';
+import type { ApprovalNeed, Plan, Handle, Eip1559GasOverrides, ResolvedEip1559Fees } from './base';
+/** Input */
+export interface DepositParams {
+    token: Address;
+    amount: bigint;
+    to?: Address;
+    refundRecipient?: Address;
+    l2GasLimit?: bigint;
+    gasPerPubdata?: bigint;
+    operatorTip?: bigint;
+    l1TxOverrides?: Eip1559GasOverrides;
+}
+/** Routes */
+export type DepositRoute = 'eth-base' | 'eth-nonbase' | 'erc20-base' | 'erc20-nonbase';
+/** Quote */
+export interface DepositQuote {
+    route: DepositRoute;
+    approvalsNeeded: readonly ApprovalNeed[];
+    baseCost: bigint;
+    mintValue: bigint;
+    gasPerPubdata: bigint;
+    fees: ResolvedEip1559Fees;
+}
+/** Plan (Tx generic) */
+export type DepositPlan<Tx> = Plan<Tx, DepositRoute, DepositQuote>;
+/** Handle */
+export interface DepositHandle<Tx> extends Handle<Record<string, Hex>, DepositRoute, DepositPlan<Tx>> {
+    kind: 'deposit';
+    l1TxHash: Hex;
+    l2ChainId?: number;
+    l2TxHash?: Hex;
+}
+/** Waitable */
+export type DepositWaitable = Hex | {
+    l1TxHash: Hex;
+} | DepositHandle<unknown>;
+export type DepositPhase = 'L1_PENDING' | 'L1_INCLUDED' | 'L2_PENDING' | 'L2_EXECUTED' | 'L2_FAILED' | 'UNKNOWN';
+export type DepositStatus = {
+    phase: DepositPhase;
+    l1TxHash: Hex;
+    l2TxHash?: Hex;
+};

package/dist/core/types/flows/route.d.ts

@@ -0,0 +1,12 @@
+import type { ApprovalNeed, PlanStep } from './base';
+export interface RouteStrategy<P, Tx, QuoteExtras = unknown, Ctx = unknown> {
+    /** Optional preflight to refine route / sanity checks. */
+    preflight?(p: P, ctx: Ctx): Promise<void>;
+    /** Build plan (tx steps + approvals). */
+    build(p: P, ctx: Ctx): Promise<{
+        steps: Array<PlanStep<Tx>>;
+        approvals: ApprovalNeed[];
+        /** Optional per-route add-ons used by the resource to compose the Quote. */
+        quoteExtras: QuoteExtras;
+    }>;
+}

package/dist/core/types/flows/withdrawals.d.ts

@@ -0,0 +1,83 @@
+import type { Address, Hex } from '../primitives';
+import type { ApprovalNeed, Plan, Handle, Eip1559GasOverrides, ResolvedEip1559Fees } from './base';
+/** Input */
+export interface WithdrawParams {
+    token: Address;
+    amount: bigint;
+    to?: Address;
+    l2GasLimit?: bigint;
+    l2TxOverrides?: Eip1559GasOverrides;
+}
+/** Routes */
+export type WithdrawRoute = 'eth-base' | 'erc20-nonbase' | 'eth-nonbase';
+/** Quote */
+export interface WithdrawQuote {
+    route: WithdrawRoute;
+    approvalsNeeded: readonly ApprovalNeed[];
+    suggestedL2GasLimit: bigint;
+    fees: ResolvedEip1559Fees;
+}
+/** Plan (Tx generic) */
+export type WithdrawPlan<Tx> = Plan<Tx, WithdrawRoute, WithdrawQuote>;
+/** Handle */
+export interface WithdrawHandle<Tx> extends Handle<Record<string, Hex>, WithdrawRoute, WithdrawPlan<Tx>> {
+    kind: 'withdrawal';
+    l2TxHash: Hex;
+    l1TxHash?: Hex;
+    l2BatchNumber?: number;
+    l2MessageIndex?: number;
+    l2TxNumberInBatch?: number;
+}
+/** Waitable */
+export type WithdrawalWaitable = Hex | {
+    l2TxHash?: Hex;
+    l1TxHash?: Hex;
+} | WithdrawHandle<unknown>;
+export interface FinalizeDepositParams {
+    chainId: bigint;
+    l2BatchNumber: bigint;
+    l2MessageIndex: bigint;
+    l2Sender: Address;
+    l2TxNumberInBatch: number;
+    message: Hex;
+    merkleProof: Hex[];
+}
+export type WithdrawalKey = {
+    chainIdL2: bigint;
+    l2BatchNumber: bigint;
+    l2MessageIndex: bigint;
+};
+type WithdrawalPhase = 'L2_PENDING' | 'L2_INCLUDED' | 'PENDING' | 'READY_TO_FINALIZE' | 'FINALIZING' | 'FINALIZED' | 'FINALIZE_FAILED' | 'UNKNOWN';
+export type WithdrawalStatus = {
+    phase: WithdrawalPhase;
+    l2TxHash: Hex;
+    l1FinalizeTxHash?: Hex;
+    key?: WithdrawalKey;
+};
+export type FinalizeReadiness = {
+    kind: 'READY';
+} | {
+    kind: 'FINALIZED';
+} | {
+    kind: 'NOT_READY';
+    reason: 'paused' | 'batch-not-executed' | 'root-missing' | 'unknown';
+    detail?: string;
+} | {
+    kind: 'UNFINALIZABLE';
+    reason: 'message-invalid' | 'invalid-chain' | 'settlement-layer' | 'unsupported';
+    detail?: string;
+};
+export interface FinalizationEstimate {
+    gasLimit: bigint;
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+}
+export type ParsedLog = {
+    address: string;
+    topics: Hex[];
+    data: Hex;
+};
+export type ParsedReceipt = {
+    logs: ParsedLog[];
+};
+export {};

package/dist/core/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './primitives';
+export * from './errors';

package/dist/core/types/primitives.d.ts

@@ -0,0 +1,3 @@
+export type Address = `0x${string}`;
+export type Hex = `0x${string}`;
+export type Hash = Hex;

package/dist/core/utils/addr.d.ts

@@ -0,0 +1,5 @@
+import type { Address, Hex } from '../types/primitives.ts';
+export declare const isHash66: (x?: string) => x is Hex;
+export declare function isAddressEq(a: Address, b: Address): boolean;
+export declare function isETH(token: Address): boolean;
+export declare function normalizeAddrEq(a?: string, b?: string): boolean;

package/dist/core/utils/gas.d.ts

@@ -0,0 +1,13 @@
+import type { Eip1559GasOverrides } from '../types/flows/base';
+/**
+ * Ensures a user-supplied override does not include legacy gas properties.
+ * Throws if `gasPrice` is present.
+ */
+export declare function assertNoLegacyGas(overrides: Eip1559GasOverrides | (Eip1559GasOverrides & Record<string, unknown>) | undefined): void;
+/**
+ * Validates that maxPriorityFeePerGas does not exceed maxFeePerGas.
+ */
+export declare function assertPriorityFeeBounds(fees: {
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+}): void;