@matterlabs/zksync-js 0.0.2 → 0.0.3

package/dist/core/index.d.ts

@@ -16,4 +16,5 @@ export type * from './types/flows/base';
 export type * from './types/flows/deposits';
 export type * from './types/flows/withdrawals';
 export type * from './types/flows/route';
+export type * from './types/flows/token';
 export type * from './types/primitives';

package/dist/core/index.js

@@ -1,4 +1,5 @@
-export { findL1MessageSentLog, isAddressEq, isETH, isHash66, messengerLogIndex, normalizeAddrEq, pickDepositRoute, pickWithdrawRoute } from '../chunk-HLUANWGN.js';
+export { pickDepositRoute } from '../chunk-NTEIA5KA.js';
+export { findL1MessageSentLog, hexEq, isAddressEq, isETH, isHash66, messengerLogIndex, normalizeAddrEq, normalizeL1Token, pickWithdrawRoute } from '../chunk-NEC2ZKHI.js';
 export { makeTransportFromEthers, makeTransportFromViem, zks_exports as zksRpc } from '../chunk-6K6VJQAL.js';
 export { abi_exports as abi, factory_exports as errors, formatEnvelopePretty } from '../chunk-M5J2MM2U.js';
 export { ETH_ADDRESS, FORMAL_ETH_ADDRESS, L1_MESSENGER_ADDRESS, L1_SOPH_TOKEN_ADDRESS, L2_ASSET_ROUTER_ADDRESS, L2_BASE_TOKEN_ADDRESS, L2_NATIVE_TOKEN_VAULT_ADDRESS } from '../chunk-F2ENUV3A.js';

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

@@ -1,6 +1,6 @@
 export type ErrorType = 'VALIDATION' | 'STATE' | 'EXECUTION' | 'RPC' | 'INTERNAL' | 'VERIFICATION' | 'CONTRACT';
 /** Resource surface */
-export type Resource = 'deposits' | 'withdrawals' | 'withdrawal-finalization' | 'helpers' | 'zksrpc' | 'client';
+export type Resource = 'deposits' | 'withdrawals' | 'withdrawal-finalization' | 'tokens' | 'contracts' | 'helpers' | 'zksrpc' | 'client';
 /** Envelope we throw only for SDK-domain errors. */
 export interface ErrorEnvelope {
     /** Resource surface that raised the error. */

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

@@ -0,0 +1,192 @@
+import type { Address, Hex } from '../primitives';
+/**
+ * Token kind classification.
+ * - 'eth': Ethereum / native ETH token
+ * - 'base': The base token of the target L2 chain
+ * - 'erc20': ERC-20 token
+ */
+export type TokenKind = 'eth' | 'base' | 'erc20';
+/**
+ * Reference to a token on a specific chain.
+ * Used as input to identify a token for resolution.
+ */
+export type TokenRef = {
+    chain: 'l1';
+    address: Address;
+} | {
+    chain: 'l2';
+    address: Address;
+};
+/**
+ * Fully resolved token information including L1/L2 addresses,
+ * bridge identity, and chain-specific facts.
+ */
+export interface ResolvedToken {
+    /**
+     * Token kind: 'eth', 'base', or 'erc20'
+     */
+    kind: TokenKind;
+    /**
+     * Canonical L1 token address
+     */
+    l1: Address;
+    /**
+     * Canonical L2 token address
+     */
+    l2: Address;
+    /**
+     * Bridge asset ID (bytes32)
+     */
+    assetId: Hex;
+    /**
+     * Chain ID where this token originates
+     */
+    originChainId: bigint;
+    /**
+     * Whether the L2 chain is ETH-based (i.e., base token is ETH)
+     */
+    isChainEthBased: boolean;
+    /**
+     * Asset ID of the chain's base token
+     */
+    baseTokenAssetId: Hex;
+    /**
+     * WETH address on L1
+     */
+    wethL1: Address;
+    /**
+     * WETH address on L2
+     */
+    wethL2: Address;
+}
+/**
+ * Tokens resource interface providing token identity, L1/L2 mapping,
+ * and bridge assetId primitives.
+ */
+export interface TokensResource {
+    /**
+     * Resolves a token reference into a complete `ResolvedToken` with all
+     * L1/L2 addresses, assetId, origin chain, and chain facts.
+     *
+     * @param ref - Token address or TokenRef object
+     * @param opts - Optional chain specification when ref is an Address
+     * @returns Fully resolved token information
+     *
+     * @example
+     * ```typescript
+     * // Resolve by L1 address (default)
+     * const token = await sdk.tokens.resolve('0x...');
+     *
+     * // Explicitly specify chain
+     * const token = await sdk.tokens.resolve('0x...', { chain: 'l2' });
+     *
+     * // Use TokenRef object
+     * const token = await sdk.tokens.resolve({ chain: 'l1', address: '0x...' });
+     * ```
+     */
+    resolve(ref: Address | TokenRef, opts?: {
+        chain?: 'l1' | 'l2';
+    }): Promise<ResolvedToken>;
+    /**
+     * Maps an L1 token address to its corresponding L2 token address.
+     *
+     * @param l1Token - L1 token address
+     * @returns Corresponding L2 token address
+     *
+     * @example
+     * ```typescript
+     * const l2Token = await sdk.tokens.toL2Address('0x...L1Address');
+     * ```
+     */
+    toL2Address(l1Token: Address): Promise<Address>;
+    /**
+     * Maps an L2 token address to its corresponding L1 token address.
+     *
+     * @param l2Token - L2 token address
+     * @returns Corresponding L1 token address
+     *
+     * @example
+     * ```typescript
+     * const l1Token = await sdk.tokens.toL1Address('0x...L2Address');
+     * ```
+     */
+    toL1Address(l2Token: Address): Promise<Address>;
+    /**
+     * Computes the bridge assetId for a given L1 token address.
+     *
+     * @param l1Token - L1 token address
+     * @returns AssetId (bytes32)
+     */
+    assetIdOfL1(l1Token: Address): Promise<Hex>;
+    /**
+     * Computes the bridge assetId for a given L2 token address.
+     *
+     * @param l2Token - L2 token address
+     * @returns AssetId (bytes32)
+     */
+    assetIdOfL2(l2Token: Address): Promise<Hex>;
+    /**
+     * Retrieves the L2 token address for a given assetId.
+     *
+     * @param assetId - Bridge asset ID (bytes32)
+     * @returns L2 token address
+     */
+    l2TokenFromAssetId(assetId: Hex): Promise<Address>;
+    /**
+     * Retrieves the L1 token address for a given assetId.
+     *
+     * @param assetId - Bridge asset ID (bytes32)
+     * @returns L1 token address
+     */
+    l1TokenFromAssetId(assetId: Hex): Promise<Address>;
+    /**
+     * Retrieves the origin chain ID for a given assetId.
+     *
+     * @param assetId - Bridge asset ID (bytes32)
+     * @returns Origin chain ID
+     */
+    originChainId(assetId: Hex): Promise<bigint>;
+    /**
+     * Returns the assetId of the base token for the L2 chain.
+     *
+     * @returns Base token assetId (bytes32)
+     */
+    baseTokenAssetId(): Promise<Hex>;
+    /**
+     * Determines whether the L2 chain is ETH-based (i.e., base token is ETH).
+     *
+     * @returns True if the chain is ETH-based, false otherwise
+     */
+    isChainEthBased(): Promise<boolean>;
+    /**
+     * Returns the WETH token address on L1.
+     *
+     * @returns WETH L1 address
+     */
+    wethL1(): Promise<Address>;
+    /**
+     * Returns the WETH token address on L2.
+     *
+     * @returns WETH L2 address
+     */
+    wethL2(): Promise<Address>;
+    /**
+     * Predicts the L2 address for a bridged token given its origin chain and L1 address.
+     * This uses the CREATE2 deterministic deployment address calculation.
+     *
+     * @param args - Origin chain ID and L1 token address
+     * @returns Predicted L2 token address
+     *
+     * @example
+     * ```typescript
+     * const predictedL2Addr = await sdk.tokens.computeL2BridgedAddress({
+     *   originChainId: 1n,
+     *   l1Token: '0x...'
+     * });
+     * ```
+     */
+    computeL2BridgedAddress(args: {
+        originChainId: bigint;
+        l1Token: Address;
+    }): Promise<Address>;
+}

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

@@ -3,3 +3,5 @@ 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;
+export declare const hexEq: (a: Hex, b: Hex) => boolean;
+export declare const normalizeL1Token: (token: Address) => Address;

package/dist/index.cjs

@@ -5011,6 +5011,8 @@ function normalizeAddrEq(a, b) {
   };
   return normalize(a) === normalize(b);
 }
+var hexEq = (a, b) => a.toLowerCase() === b.toLowerCase();
+var normalizeL1Token = (token) => isAddressEq(token, FORMAL_ETH_ADDRESS) ? ETH_ADDRESS : token;
 
 // src/core/resources/deposits/route.ts
 async function pickDepositRoute(client, chainIdL2, token) {
@@ -5072,6 +5074,7 @@ exports.constants = constants_exports;
 exports.errors = factory_exports;
 exports.findL1MessageSentLog = findL1MessageSentLog;
 exports.formatEnvelopePretty = formatEnvelopePretty;
+exports.hexEq = hexEq;
 exports.isAddressEq = isAddressEq;
 exports.isETH = isETH;
 exports.isHash66 = isHash66;
@@ -5079,6 +5082,7 @@ exports.makeTransportFromEthers = makeTransportFromEthers;
 exports.makeTransportFromViem = makeTransportFromViem;
 exports.messengerLogIndex = messengerLogIndex;
 exports.normalizeAddrEq = normalizeAddrEq;
+exports.normalizeL1Token = normalizeL1Token;
 exports.pickDepositRoute = pickDepositRoute;
 exports.pickWithdrawRoute = pickWithdrawRoute;
 exports.zksRpc = zks_exports;