zerc20-client-sdk 0.1.15 → 0.2.1

package/README.md

@@ -23,6 +23,27 @@ npm install zerc20-client-sdk
 - Node.js >= 18
 - Browser with WebAssembly support
 
+## Compatibility Notes
+
+- This package is **ESM-only** (`"type": "module"`). CommonJS (`require`) is not supported.
+- HTTP-based modules (e.g. Decider client, LayerZero Scan) rely on `fetch`.
+  - Node.js 18+ includes `fetch` globally.
+  - In custom runtimes, provide a compatible `fetch` implementation where needed.
+
+## Provider Abstraction (Library/Framework Agnostic)
+
+The SDK public API is designed to be wallet/provider agnostic:
+
+- Read paths accept `EvmReadProvider`
+- Write paths accept `EvmWriteProvider`
+- UI frameworks are not part of the SDK surface
+
+This lets integrators use viem, ethers, web3.js, or custom adapters without depending on React/Vue internals.
+
+```typescript
+import type { EvmReadProvider, EvmWriteProvider } from "zerc20-client-sdk";
+```
+
 ## Quick Start
 
 ```typescript
@@ -73,35 +94,31 @@ src/
 │   ├── invoice.ts      # Invoice creation
 │   ├── teleport.ts     # Single teleport proof
 │   ├── teleportProof.ts # Batch teleport proof (Nova + Decider)
-│   └── liquidityManager/ # Wrap/unwrap with slippage protection
+│   ├── liquidityManager/ # Wrap/unwrap with slippage protection
+│   └── layerzeroScan/   # LayerZero message tracking & decoding
 ├── wasm/         # WASM runtime & bindings
 │   ├── index.ts        # WasmRuntime class
 │   ├── loader.ts       # WASM bindings loader (browser/Node.js)
 │   └── serialization.ts # Type conversion utilities
 ├── zkp/          # Zero-knowledge proof orchestration
 ├── decider/      # Decider proof generation (HTTP client)
+├── chain/        # Chain metadata (names, explorers, aliases)
 ├── registry/     # Token & hub configuration
-├── onchain/      # Viem contract bindings
+├── onchain/      # Contract interaction (ABI decoding, token reads)
 └── utils/        # Shared utilities
 ```
 
 ## Key Modules
 
-### WasmRuntime
+### WASM Configuration
 
-Manages WASM module loading with dual runtime support (Browser/Node.js):
+Configure the WASM runtime for cryptographic operations:
 
 ```typescript
-import { WasmRuntime, getDefaultWasmRuntime } from "zerc20-client-sdk";
+import { configureWasmLocator } from "zerc20-client-sdk";
 
-// Use default singleton
-const runtime = getDefaultWasmRuntime();
-await runtime.ready();
-
-// Or create a custom instance
-const customRuntime = new WasmRuntime({
-  url: "https://example.com/zerc20_wasm_bg.wasm",
-});
+// Point to your hosted WASM binary
+configureWasmLocator({ url: "/zerc20_wasm_bg.wasm" });
 ```
 
 ### StealthCanisterClient
@@ -133,7 +150,8 @@ import {
 
 // Local unwrap with slippage protection
 await unwrapWithLiquidityManager({
-  walletClient,
+  writeProvider,
+  readProvider,
   liquidityManagerAddress,
   zerc20TokenAddress,
   amount: 1000n,
@@ -146,33 +164,265 @@ const quote = await buildCrossUnwrapQuote({
   destinationToken,
   amount: 1000n,
   account,
+  readProviderSource: sourceReadProvider,
+  readProviderDestination: destReadProvider,
   slippageBps: 50, // 0.5% slippage tolerance
 });
 ```
 
-### Proof Generation
+### Adaptor Withdraw (Stuck Fund Recovery)
+
+When a cross-chain unwrap fails (e.g. due to Stargate liquidity shortage), user funds may remain in the destination chain's Adaptor contract. The SDK provides functions to detect and recover these stuck funds:
+
+```typescript
+import {
+  fetchAdaptorBalances,
+  hasStuckFunds,
+  withdrawFromAdaptor,
+  NATIVE_TOKEN_ADDRESS,
+} from "zerc20-client-sdk";
+
+// Check if a user has stuck funds in an adaptor
+const stuck = await hasStuckFunds({
+  provider: readProvider,
+  account: "0xUser...",
+  adaptorAddress: "0xAdaptor...",
+});
+
+// Fetch detailed balances
+const balances = await fetchAdaptorBalances({
+  provider: readProvider,
+  account: "0xUser...",
+  adaptorAddress: "0xAdaptor...",
+});
+// balances.underlyingTokenBalance, balances.zerc20Balance, balances.nativeBalance
+
+// Withdraw stuck funds
+const result = await withdrawFromAdaptor({
+  writeProvider,
+  adaptorAddress: "0xAdaptor...",
+  token: balances.underlyingTokenAddress, // or zerc20TokenAddress, or NATIVE_TOKEN_ADDRESS
+  amount: balances.underlyingTokenBalance,
+});
+```
+
+### LayerZero Scan
+
+Track and decode LayerZero cross-chain messages. Configuration and providers are injected as parameters, making this module framework-agnostic:
+
+```typescript
+import {
+  fetchWalletStatus,
+  type FetchWalletStatusParams,
+  type LayerZeroScanConfig,
+} from "zerc20-client-sdk";
+
+const scanConfig: LayerZeroScanConfig = {
+  baseUrl: "https://scan.layerzero-api.com/v1/",
+  apiKey: "your-api-key", // optional
+};
+
+const result = await fetchWalletStatus({
+  address: "0xuser",
+  tokens,
+  scanConfig,
+  createReadProvider: (token) => createPublicClient({ chain: ... }),
+  limit: 10,
+  filterByToken: true,
+});
+
+// result.items: LayerZeroMessageSummary[]
+// result.walletUrl: string (link to LZ Scan)
+// result.nextToken: string | undefined (pagination cursor)
+```
+
+Notes:
+- `fetchWalletStatus` can use transaction input (`getTransaction`) and receipt logs (`getTransactionReceipt`) when available.
+- If those methods are unavailable, decoding still falls back to payload-based paths where possible.
+
+### Seed Derivation
+
+Derive a seed from a wallet signature. The SDK handles the message retrieval, signature validation, and keccak256 hashing internally, while accepting a wallet-agnostic sign function:
+
+```typescript
+import { deriveSeed } from "zerc20-client-sdk";
+
+// Works with any wallet library (wagmi, ethers.js, web3.js, etc.)
+const seed = await deriveSeed(async (message) => {
+  // Return the signature as a 0x-prefixed hex string (65 bytes for personal_sign)
+  return wallet.signMessage(message);
+});
+```
+
+The function validates that the returned signature is a valid hex string of exactly 65 bytes before hashing. Invalid signatures throw descriptive errors to prevent silent seed misderivation.
+
+### Chain Metadata
+
+Look up chain display names, short labels, block explorer URLs, and resolve chain name aliases — all from a single source of truth shared across products:
+
+```typescript
+import {
+  getChainMetadata,
+  getChainDisplayName,
+  getExplorerTxUrl,
+  resolveChainId,
+  resolveNetworkDisplayName,
+} from "zerc20-client-sdk";
+
+getChainDisplayName(42161);                 // "Arbitrum"
+getChainDisplayName(999999);                // "Chain 999999"
+
+getExplorerTxUrl(42161, "0xabc...");        // "https://arbiscan.io/tx/0xabc..."
+
+resolveChainId("arb-sepolia");              // 421614
+resolveNetworkDisplayName("arb-sepolia");   // "Arbitrum Sepolia"
+```
+
+### Token Loading with RPC Overrides
+
+Load and normalize token configuration with runtime RPC URL overrides (e.g. environment-specific Alchemy/Infura endpoints):
+
+```typescript
+import { normalizeTokensWithOverrides } from "zerc20-client-sdk";
+import tokensJson from "./tokens.json";
+
+const tokens = normalizeTokensWithOverrides(
+  tokensJson as TokensFile, // snake_case JSON is accepted as-is
+  {
+    tokens: {
+      "arb-mainnet": ["https://arb-mainnet.g.alchemy.com/v2/KEY"],
+      "base-mainnet": ["https://base-mainnet.g.alchemy.com/v2/KEY"],
+    },
+    hub: ["https://base-mainnet.g.alchemy.com/v2/KEY"],
+  },
+);
+```
+
+Without overrides, `normalizeTokensWithOverrides(file)` behaves identically to `normalizeTokens(file)`.
+
+### Redeem Flow
+
+Prepare a redeem transaction from a collected redeem context. The SDK handles single vs batch proof selection, `GeneralRecipient` construction, and contract call parameter assembly internally:
 
 ```typescript
 import {
+  collectRedeemContext,
+  prepareRedeemTransaction,
+  createTeleportProofClient,
   HttpDeciderClient,
+} from "zerc20-client-sdk";
+
+// Initialize proof client and decider
+const teleportProofClient = createTeleportProofClient();
+const decider = new HttpDeciderClient("https://decider.example.com");
+
+// 1. Collect redeem context (eligible events, proofs, etc.)
+const redeemContext = await collectRedeemContext({ burn, tokens, hub, verifierContract, indexerUrl });
+
+// 2. Prepare the transaction (SDK picks single vs batch automatically)
+const tx = await prepareRedeemTransaction({
+  redeemContext,
+  burn,
+  teleportProofClient,
+  decider, // required only when eligible.length > 1
+});
+
+// 3. Submit via your wallet library
+const hash = await walletClient.writeContract({
+  address: tx.address as `0x${string}`,
+  abi: tx.abi,
+  functionName: tx.functionName,
+  args: tx.args,
+  account,
+  chain,
+});
+```
+
+The returned `RedeemTransaction` is pure data (`{ address, abi, functionName, args, mode }`) with no wallet dependency.
+
+#### Manual batch flow with UI progress
+
+For batch redeems, callers can use the 2-step proof API to insert UI updates between Nova and Decider steps:
+
+```typescript
+import {
+  collectRedeemContext,
+  buildBatchRedeemTransaction,
   createTeleportProofClient,
-  getDefaultWasmRuntime,
+  HttpDeciderClient,
 } from "zerc20-client-sdk";
 
-const runtime = getDefaultWasmRuntime();
-await runtime.ready();
+const teleportProofClient = createTeleportProofClient();
+const decider = new HttpDeciderClient("https://decider.example.com");
+const redeemContext = await collectRedeemContext({ burn, tokens, hub, verifierContract, indexerUrl });
+
+// Step 1: Nova proof
+const novaResult = await teleportProofClient.createNovaProof({
+  aggregationState: redeemContext.aggregationState,
+  recipientFr: burn.generalRecipient.fr,
+  secretHex: burn.secret,
+  events: redeemContext.events.eligible,
+  proofs: redeemContext.globalProofs,
+});
 
-const proofClient = createTeleportProofClient({ wasm: runtime });
+updateUI("Requesting decider proof…"); // ← insert UI update here
+
+// Step 2: Decider proof
+const deciderProof = await teleportProofClient.requestDeciderProof(decider, novaResult.ivcProof);
+
+// Step 3: Build transaction
+const tx = buildBatchRedeemTransaction({ redeemContext, burn, deciderProof });
+```
+
+### LayerZero Decode Utilities
+
+Decode LayerZero OFT transaction data — `send()` calldata, `OFTSent` event logs, and BridgeRequest compose messages:
+
+```typescript
+import {
+  decodeSendPayload,
+  extractOftSentAmount,
+  decodeBridgeRequest,
+} from "zerc20-client-sdk";
+
+// Decode send() transaction input
+const payload = decodeSendPayload(txData);
+// → { dstEid, to, amountLD, minAmountLD, composeMsg }
+
+// Extract amountReceivedLD from OFTSent event logs
+const amount = extractOftSentAmount(receipt.logs);
+
+// Decode a BridgeRequest compose message (returns null on failure)
+const bridgeReq = decodeBridgeRequest(payload.composeMsg);
+// → { dstEid, to, refundAddress, minAmountOut } | null
+```
+
+### Proof Generation
+
+```typescript
+import {
+  HttpDeciderClient,
+  createTeleportProofClient,
+} from "zerc20-client-sdk";
+
+const proofClient = createTeleportProofClient();
 
 // Single teleport proof (Groth16)
 const singleProof = await proofClient.createSingleTeleportProof(/* ... */);
 
-// Batch teleport proof (Nova + Decider)
-const decider = new HttpDeciderClient("https://decider.example.com");
-const batchProof = await proofClient.createBatchTeleportProof({
-  decider,
-  // ... other inputs
+// Batch teleport proof (Nova + Decider) — two-step API
+const novaResult = await proofClient.createNovaProof({
+  aggregationState,
+  recipientFr,
+  secretHex,
+  events,
+  proofs,
 });
+
+// Callers can update UI between steps (e.g. progress indicators)
+
+const decider = new HttpDeciderClient("https://decider.example.com");
+const deciderProof = await proofClient.requestDeciderProof(decider, novaResult.ivcProof);
 ```
 
 ## Development
@@ -201,7 +451,7 @@ npm run typecheck
 npm test
 ```
 
-**Current (as of 2026-02-06): 755 passed, 2 skipped**  
+**Current (as of 2026-03-05): 943 passed, 2 skipped**
 Note: This number will drift over time; treat `npm test` output as the source of truth.
 
 ### Skipped Tests

package/dist/chain/__tests__/metadata.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metadata.test.d.ts.map

package/dist/chain/__tests__/metadata.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.test.d.ts","sourceRoot":"","sources":["../../../src/chain/__tests__/metadata.test.ts"],"names":[],"mappings":""}

package/dist/chain/__tests__/metadata.test.js

@@ -0,0 +1,162 @@
+import { describe, expect, it } from "vitest";
+import { getChainMetadata, getChainDisplayName, getChainShortName, getExplorerTxUrl, resolveChainId, resolveNetworkDisplayName, } from "../metadata.js";
+// ── getChainMetadata ────────────────────────────────────────────────
+describe("getChainMetadata", () => {
+    it.each([
+        [1, "Ethereum"],
+        [42161, "Arbitrum"],
+        [10, "Optimism"],
+        [8453, "Base"],
+        [56, "BNB Chain"],
+        [11155111, "Ethereum Sepolia"],
+        [421614, "Arbitrum Sepolia"],
+        [11155420, "Optimism Sepolia"],
+        [84532, "Base Sepolia"],
+        [97, "BNB Testnet"],
+    ])("returns metadata for chain %i (%s)", (chainId, expectedName) => {
+        const meta = getChainMetadata(chainId);
+        expect(meta).toBeDefined();
+        expect(meta.name).toBe(expectedName);
+        expect(meta.shortName).toBeTruthy();
+        expect(meta.explorerUrl).toMatch(/^https:\/\//);
+    });
+    it("returns undefined for an unknown chain", () => {
+        expect(getChainMetadata(999999)).toBeUndefined();
+    });
+    it("accepts bigint chain IDs", () => {
+        expect(getChainMetadata(42161n)?.name).toBe("Arbitrum");
+        expect(getChainMetadata(999999n)).toBeUndefined();
+    });
+});
+// ── getChainDisplayName ─────────────────────────────────────────────
+describe("getChainDisplayName", () => {
+    it("returns the display name for known chains", () => {
+        expect(getChainDisplayName(42161)).toBe("Arbitrum");
+        expect(getChainDisplayName(11155111)).toBe("Ethereum Sepolia");
+    });
+    it("falls back to 'Chain {id}' for unknown chains", () => {
+        expect(getChainDisplayName(123456)).toBe("Chain 123456");
+    });
+    it("accepts bigint chain IDs", () => {
+        expect(getChainDisplayName(42161n)).toBe("Arbitrum");
+        expect(getChainDisplayName(123456n)).toBe("Chain 123456");
+    });
+});
+// ── getChainShortName ───────────────────────────────────────────────
+describe("getChainShortName", () => {
+    it("returns short name for known chains", () => {
+        expect(getChainShortName(42161)).toBe("ARB");
+        expect(getChainShortName(10)).toBe("OP");
+        expect(getChainShortName(8453)).toBe("BASE");
+    });
+    it("returns undefined for unknown chains", () => {
+        expect(getChainShortName(999999)).toBeUndefined();
+    });
+});
+// ── getExplorerTxUrl ────────────────────────────────────────────────
+describe("getExplorerTxUrl", () => {
+    const txHash = "0xabc123";
+    it.each([
+        [1, "https://etherscan.io/tx/0xabc123"],
+        [42161, "https://arbiscan.io/tx/0xabc123"],
+        [10, "https://optimistic.etherscan.io/tx/0xabc123"],
+        [8453, "https://basescan.org/tx/0xabc123"],
+        [56, "https://bscscan.com/tx/0xabc123"],
+        [11155111, "https://sepolia.etherscan.io/tx/0xabc123"],
+        [421614, "https://sepolia.arbiscan.io/tx/0xabc123"],
+        [11155420, "https://sepolia-optimism.etherscan.io/tx/0xabc123"],
+        [84532, "https://sepolia.basescan.org/tx/0xabc123"],
+        [97, "https://testnet.bscscan.com/tx/0xabc123"],
+    ])("builds correct URL for chain %i", (chainId, expectedUrl) => {
+        expect(getExplorerTxUrl(chainId, txHash)).toBe(expectedUrl);
+    });
+    it("returns undefined for unknown chain", () => {
+        expect(getExplorerTxUrl(999999, txHash)).toBeUndefined();
+    });
+    it("accepts bigint chain IDs", () => {
+        expect(getExplorerTxUrl(42161n, txHash)).toBe("https://arbiscan.io/tx/0xabc123");
+    });
+});
+// ── resolveChainId ──────────────────────────────────────────────────
+describe("resolveChainId", () => {
+    it.each([
+        // mainnet names
+        ["ethereum", 1],
+        ["eth", 1],
+        ["eth-mainnet", 1],
+        ["arbitrum", 42161],
+        ["arb", 42161],
+        ["arb-mainnet", 42161],
+        ["optimism", 10],
+        ["op", 10],
+        ["op-mainnet", 10],
+        ["base", 8453],
+        ["base-mainnet", 8453],
+        ["bnb", 56],
+        ["bsc", 56],
+        // testnet names
+        ["sepolia", 11155111],
+        ["ethereum-sepolia", 11155111],
+        ["arb-sepolia", 421614],
+        ["arbitrum-sepolia", 421614],
+        ["op-sepolia", 11155420],
+        ["optimism-sepolia", 11155420],
+        ["base-sepolia", 84532],
+        ["bnb-testnet", 97],
+        ["bsc-testnet", 97],
+    ])("resolves '%s' → %i", (name, expectedId) => {
+        expect(resolveChainId(name)).toBe(expectedId);
+    });
+    it("is case-insensitive", () => {
+        expect(resolveChainId("Ethereum")).toBe(1);
+        expect(resolveChainId("ARB-SEPOLIA")).toBe(421614);
+        expect(resolveChainId("  Base  ")).toBe(8453);
+    });
+    it("returns undefined for unknown names", () => {
+        expect(resolveChainId("solana")).toBeUndefined();
+        expect(resolveChainId("")).toBeUndefined();
+    });
+});
+// ── resolveNetworkDisplayName ───────────────────────────────────────
+describe("resolveNetworkDisplayName", () => {
+    it.each([
+        ["sepolia", "Ethereum Sepolia"],
+        ["arb-sepolia", "Arbitrum Sepolia"],
+        ["op-sepolia", "Optimism Sepolia"],
+        ["base-sepolia", "Base Sepolia"],
+        ["bnb-testnet", "BNB Testnet"],
+        ["bsc-testnet", "BNB Testnet"],
+        ["ethereum-sepolia", "Ethereum Sepolia"],
+        ["arbitrum-sepolia", "Arbitrum Sepolia"],
+        ["optimism-sepolia", "Optimism Sepolia"],
+        ["eth-mainnet", "Ethereum"],
+        ["arb-mainnet", "Arbitrum"],
+        ["op-mainnet", "Optimism"],
+        ["base-mainnet", "Base"],
+        ["ethereum", "Ethereum"],
+        ["arbitrum", "Arbitrum"],
+        ["optimism", "Optimism"],
+        ["base", "Base"],
+        ["bsc", "BNB Chain"],
+        ["arb", "Arbitrum"],
+        ["op", "Optimism"],
+        ["bnb", "BNB Chain"],
+    ])("resolves '%s' → '%s'", (label, expected) => {
+        expect(resolveNetworkDisplayName(label)).toBe(expected);
+    });
+    it("is case-insensitive", () => {
+        expect(resolveNetworkDisplayName("ETHEREUM")).toBe("Ethereum");
+        expect(resolveNetworkDisplayName("Arb-Sepolia")).toBe("Arbitrum Sepolia");
+    });
+    it("capitalizes unknown labels as fallback", () => {
+        expect(resolveNetworkDisplayName("polygon")).toBe("Polygon");
+        expect(resolveNetworkDisplayName("mychain")).toBe("Mychain");
+    });
+    it("trims whitespace and preserves original casing in fallback", () => {
+        expect(resolveNetworkDisplayName("  polygon  ")).toBe("Polygon");
+        expect(resolveNetworkDisplayName("POLYGON")).toBe("POLYGON");
+        expect(resolveNetworkDisplayName("  MYCHAIN  ")).toBe("MYCHAIN");
+        expect(resolveNetworkDisplayName("FOOBar")).toBe("FOOBar");
+    });
+});
+//# sourceMappingURL=metadata.test.js.map

package/dist/chain/__tests__/metadata.test.js.map

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

package/dist/chain/index.d.ts

@@ -0,0 +1,3 @@
+export type { ChainMetadata } from "./types.js";
+export { getChainMetadata, getChainDisplayName, getChainShortName, getExplorerTxUrl, resolveChainId, resolveNetworkDisplayName, } from "./metadata.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/chain/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/chain/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,yBAAyB,GAC1B,MAAM,eAAe,CAAC"}

package/dist/chain/index.js

@@ -0,0 +1,2 @@
+export { getChainMetadata, getChainDisplayName, getChainShortName, getExplorerTxUrl, resolveChainId, resolveNetworkDisplayName, } from "./metadata.js";
+//# sourceMappingURL=index.js.map

package/dist/chain/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/chain/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,yBAAyB,GAC1B,MAAM,eAAe,CAAC"}

package/dist/chain/metadata.d.ts

@@ -0,0 +1,38 @@
+import type { ChainMetadata } from "./types.js";
+/**
+ * Returns chain metadata for the given chain ID, or `undefined` if unknown.
+ * Accepts both `number` and `bigint` to align with SDK's `TokenEntry.chainId`.
+ */
+export declare function getChainMetadata(chainId: number | bigint): ChainMetadata | undefined;
+/**
+ * Returns a human-readable chain name.
+ * Falls back to `"Chain {chainId}"` when the chain is not recognised.
+ */
+export declare function getChainDisplayName(chainId: number | bigint): string;
+/**
+ * Returns the short label for a chain (e.g. "ARB", "ETH").
+ * Falls back to `undefined` when the chain is not recognised.
+ */
+export declare function getChainShortName(chainId: number | bigint): string | undefined;
+/**
+ * Builds a block-explorer transaction URL.
+ * Returns `undefined` when the chain is not recognised.
+ */
+export declare function getExplorerTxUrl(chainId: number | bigint, txHash: string): string | undefined;
+/**
+ * Resolves a chain name or token label to an EVM chain ID.
+ * The lookup is case-insensitive.
+ * Returns `undefined` when the name is not recognised.
+ */
+export declare function resolveChainId(name: string): number | undefined;
+/**
+ * Converts a token / network label (e.g. "arb-sepolia", "ethereum")
+ * to a user-friendly display name (e.g. "Arbitrum Sepolia", "Ethereum").
+ *
+ * Resolution order:
+ * 1. Override table ({@link LABEL_DISPLAY_OVERRIDES})
+ * 2. Resolve label → chainId → metadata name
+ * 3. Capitalize the first letter of the label as a last resort
+ */
+export declare function resolveNetworkDisplayName(label: string): string;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/chain/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/chain/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAmGhD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,SAAS,CAEpF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAGpE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAE9E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI7F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgB/D"}