@partylayer/core 0.3.1 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PartyLayer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -193,6 +193,15 @@ interface Session {
     capabilitiesSnapshot: CapabilityKey[];
     /** Additional metadata (encrypted in storage) */
     metadata?: Record<string, string>;
+    /**
+     * Set when the wallet's reported network differs from the dApp's configured
+     * network (CAIP-2 normalized). Absent when the networks match or no confident
+     * mismatch was detected. See `networkEnforcement` for blocking behavior.
+     */
+    networkMismatch?: {
+        expected: string;
+        actual: string;
+    };
 }
 /**
  * Persisted session (for restoration)
@@ -292,7 +301,7 @@ declare function toSignature(sig: string): Signature;
 /**
  * Error code union - stable string literals for telemetry and UI
  */
-type ErrorCode = 'WALLET_NOT_FOUND' | 'WALLET_NOT_INSTALLED' | 'USER_REJECTED' | 'ORIGIN_NOT_ALLOWED' | 'SESSION_EXPIRED' | 'CAPABILITY_NOT_SUPPORTED' | 'TRANSPORT_ERROR' | 'REGISTRY_FETCH_FAILED' | 'REGISTRY_VERIFICATION_FAILED' | 'REGISTRY_SCHEMA_INVALID' | 'INTERNAL_ERROR' | 'TIMEOUT';
+type ErrorCode = 'WALLET_NOT_FOUND' | 'WALLET_NOT_INSTALLED' | 'USER_REJECTED' | 'ORIGIN_NOT_ALLOWED' | 'SESSION_EXPIRED' | 'CAPABILITY_NOT_SUPPORTED' | 'TRANSPORT_ERROR' | 'REGISTRY_FETCH_FAILED' | 'REGISTRY_VERIFICATION_FAILED' | 'REGISTRY_SCHEMA_INVALID' | 'INTERNAL_ERROR' | 'NETWORK_MISMATCH' | 'TIMEOUT';
 /**
  * Error mapping context
  */
@@ -356,6 +365,18 @@ declare class OriginNotAllowedError extends PartyLayerError {
 declare class SessionExpiredError extends PartyLayerError {
     constructor(sessionId: string);
 }
+/**
+ * Network mismatch error — the connected wallet's effective network differs
+ * from the dApp's configured network. Thrown to block wrong-network connects
+ * (policy 'strict') and wrong-network transactions (policy 'guard' | 'strict').
+ */
+declare class NetworkMismatchError extends PartyLayerError {
+    /** The dApp's configured (expected) network, CAIP-2 normalized. */
+    readonly expected: string;
+    /** The wallet's reported (actual) network, CAIP-2 normalized. */
+    readonly actual: string;
+    constructor(expected: string, actual: string);
+}
 /**
  * Capability not supported error
  */
@@ -613,6 +634,13 @@ interface WalletAdapter {
         partyId?: PartyId;
         /** When false, prefer remote/mobile transport over installed extension */
         preferInstalled?: boolean;
+        /**
+         * Called with a pairing/display URI (e.g. a WalletConnect `wc:` URI) as
+         * soon as the adapter produces one, before the user approves. Lets the
+         * connect UI render a QR / deep-link itself. Adapters that have no such
+         * URI (their own SDK shows the QR) simply never call it.
+         */
+        onDisplayUri?: (uri: string) => void;
     }): Promise<AdapterConnectResult>;
     /**
      * Disconnect from wallet
@@ -1132,6 +1160,49 @@ declare const CIP0103_EVENTS: {
 };
 type CIP0103Event = (typeof CIP0103_EVENTS)[keyof typeof CIP0103_EVENTS];
 
+/**
+ * CAIP-2 Network Identity Utilities
+ *
+ * All CIP-0103 network identifiers use CAIP-2 format: "namespace:reference"
+ * e.g. "canton:da-mainnet", "canton:da-devnet"
+ *
+ * Reference: https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md
+ */
+
+declare const CANTON_NETWORKS: Record<string, string>;
+/**
+ * Convert a legacy PartyLayer NetworkId (e.g. "devnet") or already-CAIP-2
+ * string to a CIP-0103 Network object.
+ *
+ * @throws {Error} if the resulting network ID is not valid CAIP-2
+ */
+declare function toCAIP2Network(networkId: string): CIP0103Network;
+/**
+ * Extract the short network name from a CAIP-2 ID.
+ * Returns the original string if no reverse mapping exists.
+ */
+declare function fromCAIP2Network(caip2: string): string;
+/**
+ * Validate that a string conforms to CAIP-2 format.
+ *
+ * CAIP-2 format: namespace:reference
+ * - namespace: [-a-z0-9]{3,8}
+ * - reference: [-_a-zA-Z0-9]{1,32}
+ */
+declare function isValidCAIP2(networkId: string): boolean;
+/**
+ * Detect a confident, recognized, DIFFERENT-network mismatch between an
+ * `expected` (dApp-configured) and `actual` (wallet-reported) network.
+ *
+ * Conservative by design — returns `null` (no mismatch) unless BOTH networks
+ * normalize to recognized well-known Canton CAIP-2 ids AND differ. Unparseable
+ * or unrecognized/custom networks → `null` (never a false positive).
+ */
+declare function detectNetworkMismatch(expected: string, actual: string): {
+    expected: string;
+    actual: string;
+} | null;
+
 /**
  * Deep Link Transport
  *
@@ -1354,4 +1425,4 @@ interface Transport {
     disconnect(): Promise<void>;
 }
 
-export { type AdapterConnectResult, type AdapterContext, type AdapterDetectResult, type AdapterEventName, type AdapterMetadata, type CIP0103Account, type CIP0103AccountStatus, type CIP0103ConnectResult, type CIP0103Event, type CIP0103EventListener, type CIP0103LedgerApiRequest, type CIP0103LedgerApiResponse, type CIP0103Method, type CIP0103Network, type CIP0103Provider, type CIP0103ProviderInfo, type CIP0103ProviderRpcError, type CIP0103ProviderType, type CIP0103RequestParams, type CIP0103RequestPayload, type CIP0103SignMessageRequest, type CIP0103StatusEvent, type CIP0103TxChangedEvent, type CIP0103TxExecutedPayload, type CIP0103TxFailedPayload, type CIP0103TxPendingPayload, type CIP0103TxSignedPayload, type CIP0103TxStatus, CIP0103_EVENTS, CIP0103_MANDATORY_METHODS, CIP0103_METHODS, type CapabilityKey, CapabilityNotSupportedError, type Cip0103StatusForDetection, type Cip0103Support, type ConnectRequest, type ConnectResponse, type CryptoAdapter, DeepLinkTransport, ENABLEMENT_METRICS, ERROR_METRICS, type ErrorCode, type ErrorMappingContext, type InstallHints, InternalError, type JobStatus, type LedgerApiParams, type LedgerApiResult, type LoggerAdapter, METRICS, type MetricName, type MetricsPayload, MockTransport, type NetworkId, OriginNotAllowedError, type PartyId, PartyLayerError, type PersistedSession, PopupTransport, PostMessageTransport, type ProviderDetection, type ProviderMatcher, REGISTRY_METRICS, type RegistryClientAdapter, RegistryFetchFailedError, RegistrySchemaInvalidError, RegistryVerificationFailedError, type Session, SessionExpiredError, type SessionId, type SignMessageParams, type SignRequest, type SignResponse, type SignTransactionParams, type Signature, type SignedMessage, type SignedTransaction, type StorageAdapter, type SubmitTransactionParams, type TelemetryAdapter, TimeoutError, type TransactionHash, type TransactionStatus, type Transport, TransportError, type TransportOptions, type TransportType, type TxReceipt, type TxStatusUpdate, UserRejectedError, type WalletAdapter, type WalletId, type WalletInfo, WalletNotFoundError, WalletNotInstalledError, capabilityGuard, createMetricsPayload, createSession, deriveGenericWalletName, errorMetricName, findMatchingWallet, findMatchingWalletInfo, generateSessionId, hashForPrivacy, installGuard, isCip0103Native, isSessionExpired, mapUnknownErrorToPartyLayerError, matchesProviderDetection, toPartyId, toSessionId, toSignature, toTransactionHash, toWalletId, validatePayload, validateSession };
+export { type AdapterConnectResult, type AdapterContext, type AdapterDetectResult, type AdapterEventName, type AdapterMetadata, CANTON_NETWORKS, type CIP0103Account, type CIP0103AccountStatus, type CIP0103ConnectResult, type CIP0103Event, type CIP0103EventListener, type CIP0103LedgerApiRequest, type CIP0103LedgerApiResponse, type CIP0103Method, type CIP0103Network, type CIP0103Provider, type CIP0103ProviderInfo, type CIP0103ProviderRpcError, type CIP0103ProviderType, type CIP0103RequestParams, type CIP0103RequestPayload, type CIP0103SignMessageRequest, type CIP0103StatusEvent, type CIP0103TxChangedEvent, type CIP0103TxExecutedPayload, type CIP0103TxFailedPayload, type CIP0103TxPendingPayload, type CIP0103TxSignedPayload, type CIP0103TxStatus, CIP0103_EVENTS, CIP0103_MANDATORY_METHODS, CIP0103_METHODS, type CapabilityKey, CapabilityNotSupportedError, type Cip0103StatusForDetection, type Cip0103Support, type ConnectRequest, type ConnectResponse, type CryptoAdapter, DeepLinkTransport, ENABLEMENT_METRICS, ERROR_METRICS, type ErrorCode, type ErrorMappingContext, type InstallHints, InternalError, type JobStatus, type LedgerApiParams, type LedgerApiResult, type LoggerAdapter, METRICS, type MetricName, type MetricsPayload, MockTransport, type NetworkId, NetworkMismatchError, OriginNotAllowedError, type PartyId, PartyLayerError, type PersistedSession, PopupTransport, PostMessageTransport, type ProviderDetection, type ProviderMatcher, REGISTRY_METRICS, type RegistryClientAdapter, RegistryFetchFailedError, RegistrySchemaInvalidError, RegistryVerificationFailedError, type Session, SessionExpiredError, type SessionId, type SignMessageParams, type SignRequest, type SignResponse, type SignTransactionParams, type Signature, type SignedMessage, type SignedTransaction, type StorageAdapter, type SubmitTransactionParams, type TelemetryAdapter, TimeoutError, type TransactionHash, type TransactionStatus, type Transport, TransportError, type TransportOptions, type TransportType, type TxReceipt, type TxStatusUpdate, UserRejectedError, type WalletAdapter, type WalletId, type WalletInfo, WalletNotFoundError, WalletNotInstalledError, capabilityGuard, createMetricsPayload, createSession, deriveGenericWalletName, detectNetworkMismatch, errorMetricName, findMatchingWallet, findMatchingWalletInfo, fromCAIP2Network, generateSessionId, hashForPrivacy, installGuard, isCip0103Native, isSessionExpired, isValidCAIP2, mapUnknownErrorToPartyLayerError, matchesProviderDetection, toCAIP2Network, toPartyId, toSessionId, toSignature, toTransactionHash, toWalletId, validatePayload, validateSession };

package/dist/index.d.ts

@@ -193,6 +193,15 @@ interface Session {
     capabilitiesSnapshot: CapabilityKey[];
     /** Additional metadata (encrypted in storage) */
     metadata?: Record<string, string>;
+    /**
+     * Set when the wallet's reported network differs from the dApp's configured
+     * network (CAIP-2 normalized). Absent when the networks match or no confident
+     * mismatch was detected. See `networkEnforcement` for blocking behavior.
+     */
+    networkMismatch?: {
+        expected: string;
+        actual: string;
+    };
 }
 /**
  * Persisted session (for restoration)
@@ -292,7 +301,7 @@ declare function toSignature(sig: string): Signature;
 /**
  * Error code union - stable string literals for telemetry and UI
  */
-type ErrorCode = 'WALLET_NOT_FOUND' | 'WALLET_NOT_INSTALLED' | 'USER_REJECTED' | 'ORIGIN_NOT_ALLOWED' | 'SESSION_EXPIRED' | 'CAPABILITY_NOT_SUPPORTED' | 'TRANSPORT_ERROR' | 'REGISTRY_FETCH_FAILED' | 'REGISTRY_VERIFICATION_FAILED' | 'REGISTRY_SCHEMA_INVALID' | 'INTERNAL_ERROR' | 'TIMEOUT';
+type ErrorCode = 'WALLET_NOT_FOUND' | 'WALLET_NOT_INSTALLED' | 'USER_REJECTED' | 'ORIGIN_NOT_ALLOWED' | 'SESSION_EXPIRED' | 'CAPABILITY_NOT_SUPPORTED' | 'TRANSPORT_ERROR' | 'REGISTRY_FETCH_FAILED' | 'REGISTRY_VERIFICATION_FAILED' | 'REGISTRY_SCHEMA_INVALID' | 'INTERNAL_ERROR' | 'NETWORK_MISMATCH' | 'TIMEOUT';
 /**
  * Error mapping context
  */
@@ -356,6 +365,18 @@ declare class OriginNotAllowedError extends PartyLayerError {
 declare class SessionExpiredError extends PartyLayerError {
     constructor(sessionId: string);
 }
+/**
+ * Network mismatch error — the connected wallet's effective network differs
+ * from the dApp's configured network. Thrown to block wrong-network connects
+ * (policy 'strict') and wrong-network transactions (policy 'guard' | 'strict').
+ */
+declare class NetworkMismatchError extends PartyLayerError {
+    /** The dApp's configured (expected) network, CAIP-2 normalized. */
+    readonly expected: string;
+    /** The wallet's reported (actual) network, CAIP-2 normalized. */
+    readonly actual: string;
+    constructor(expected: string, actual: string);
+}
 /**
  * Capability not supported error
  */
@@ -613,6 +634,13 @@ interface WalletAdapter {
         partyId?: PartyId;
         /** When false, prefer remote/mobile transport over installed extension */
         preferInstalled?: boolean;
+        /**
+         * Called with a pairing/display URI (e.g. a WalletConnect `wc:` URI) as
+         * soon as the adapter produces one, before the user approves. Lets the
+         * connect UI render a QR / deep-link itself. Adapters that have no such
+         * URI (their own SDK shows the QR) simply never call it.
+         */
+        onDisplayUri?: (uri: string) => void;
     }): Promise<AdapterConnectResult>;
     /**
      * Disconnect from wallet
@@ -1132,6 +1160,49 @@ declare const CIP0103_EVENTS: {
 };
 type CIP0103Event = (typeof CIP0103_EVENTS)[keyof typeof CIP0103_EVENTS];
 
+/**
+ * CAIP-2 Network Identity Utilities
+ *
+ * All CIP-0103 network identifiers use CAIP-2 format: "namespace:reference"
+ * e.g. "canton:da-mainnet", "canton:da-devnet"
+ *
+ * Reference: https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md
+ */
+
+declare const CANTON_NETWORKS: Record<string, string>;
+/**
+ * Convert a legacy PartyLayer NetworkId (e.g. "devnet") or already-CAIP-2
+ * string to a CIP-0103 Network object.
+ *
+ * @throws {Error} if the resulting network ID is not valid CAIP-2
+ */
+declare function toCAIP2Network(networkId: string): CIP0103Network;
+/**
+ * Extract the short network name from a CAIP-2 ID.
+ * Returns the original string if no reverse mapping exists.
+ */
+declare function fromCAIP2Network(caip2: string): string;
+/**
+ * Validate that a string conforms to CAIP-2 format.
+ *
+ * CAIP-2 format: namespace:reference
+ * - namespace: [-a-z0-9]{3,8}
+ * - reference: [-_a-zA-Z0-9]{1,32}
+ */
+declare function isValidCAIP2(networkId: string): boolean;
+/**
+ * Detect a confident, recognized, DIFFERENT-network mismatch between an
+ * `expected` (dApp-configured) and `actual` (wallet-reported) network.
+ *
+ * Conservative by design — returns `null` (no mismatch) unless BOTH networks
+ * normalize to recognized well-known Canton CAIP-2 ids AND differ. Unparseable
+ * or unrecognized/custom networks → `null` (never a false positive).
+ */
+declare function detectNetworkMismatch(expected: string, actual: string): {
+    expected: string;
+    actual: string;
+} | null;
+
 /**
  * Deep Link Transport
  *
@@ -1354,4 +1425,4 @@ interface Transport {
     disconnect(): Promise<void>;
 }
 
-export { type AdapterConnectResult, type AdapterContext, type AdapterDetectResult, type AdapterEventName, type AdapterMetadata, type CIP0103Account, type CIP0103AccountStatus, type CIP0103ConnectResult, type CIP0103Event, type CIP0103EventListener, type CIP0103LedgerApiRequest, type CIP0103LedgerApiResponse, type CIP0103Method, type CIP0103Network, type CIP0103Provider, type CIP0103ProviderInfo, type CIP0103ProviderRpcError, type CIP0103ProviderType, type CIP0103RequestParams, type CIP0103RequestPayload, type CIP0103SignMessageRequest, type CIP0103StatusEvent, type CIP0103TxChangedEvent, type CIP0103TxExecutedPayload, type CIP0103TxFailedPayload, type CIP0103TxPendingPayload, type CIP0103TxSignedPayload, type CIP0103TxStatus, CIP0103_EVENTS, CIP0103_MANDATORY_METHODS, CIP0103_METHODS, type CapabilityKey, CapabilityNotSupportedError, type Cip0103StatusForDetection, type Cip0103Support, type ConnectRequest, type ConnectResponse, type CryptoAdapter, DeepLinkTransport, ENABLEMENT_METRICS, ERROR_METRICS, type ErrorCode, type ErrorMappingContext, type InstallHints, InternalError, type JobStatus, type LedgerApiParams, type LedgerApiResult, type LoggerAdapter, METRICS, type MetricName, type MetricsPayload, MockTransport, type NetworkId, OriginNotAllowedError, type PartyId, PartyLayerError, type PersistedSession, PopupTransport, PostMessageTransport, type ProviderDetection, type ProviderMatcher, REGISTRY_METRICS, type RegistryClientAdapter, RegistryFetchFailedError, RegistrySchemaInvalidError, RegistryVerificationFailedError, type Session, SessionExpiredError, type SessionId, type SignMessageParams, type SignRequest, type SignResponse, type SignTransactionParams, type Signature, type SignedMessage, type SignedTransaction, type StorageAdapter, type SubmitTransactionParams, type TelemetryAdapter, TimeoutError, type TransactionHash, type TransactionStatus, type Transport, TransportError, type TransportOptions, type TransportType, type TxReceipt, type TxStatusUpdate, UserRejectedError, type WalletAdapter, type WalletId, type WalletInfo, WalletNotFoundError, WalletNotInstalledError, capabilityGuard, createMetricsPayload, createSession, deriveGenericWalletName, errorMetricName, findMatchingWallet, findMatchingWalletInfo, generateSessionId, hashForPrivacy, installGuard, isCip0103Native, isSessionExpired, mapUnknownErrorToPartyLayerError, matchesProviderDetection, toPartyId, toSessionId, toSignature, toTransactionHash, toWalletId, validatePayload, validateSession };
+export { type AdapterConnectResult, type AdapterContext, type AdapterDetectResult, type AdapterEventName, type AdapterMetadata, CANTON_NETWORKS, type CIP0103Account, type CIP0103AccountStatus, type CIP0103ConnectResult, type CIP0103Event, type CIP0103EventListener, type CIP0103LedgerApiRequest, type CIP0103LedgerApiResponse, type CIP0103Method, type CIP0103Network, type CIP0103Provider, type CIP0103ProviderInfo, type CIP0103ProviderRpcError, type CIP0103ProviderType, type CIP0103RequestParams, type CIP0103RequestPayload, type CIP0103SignMessageRequest, type CIP0103StatusEvent, type CIP0103TxChangedEvent, type CIP0103TxExecutedPayload, type CIP0103TxFailedPayload, type CIP0103TxPendingPayload, type CIP0103TxSignedPayload, type CIP0103TxStatus, CIP0103_EVENTS, CIP0103_MANDATORY_METHODS, CIP0103_METHODS, type CapabilityKey, CapabilityNotSupportedError, type Cip0103StatusForDetection, type Cip0103Support, type ConnectRequest, type ConnectResponse, type CryptoAdapter, DeepLinkTransport, ENABLEMENT_METRICS, ERROR_METRICS, type ErrorCode, type ErrorMappingContext, type InstallHints, InternalError, type JobStatus, type LedgerApiParams, type LedgerApiResult, type LoggerAdapter, METRICS, type MetricName, type MetricsPayload, MockTransport, type NetworkId, NetworkMismatchError, OriginNotAllowedError, type PartyId, PartyLayerError, type PersistedSession, PopupTransport, PostMessageTransport, type ProviderDetection, type ProviderMatcher, REGISTRY_METRICS, type RegistryClientAdapter, RegistryFetchFailedError, RegistrySchemaInvalidError, RegistryVerificationFailedError, type Session, SessionExpiredError, type SessionId, type SignMessageParams, type SignRequest, type SignResponse, type SignTransactionParams, type Signature, type SignedMessage, type SignedTransaction, type StorageAdapter, type SubmitTransactionParams, type TelemetryAdapter, TimeoutError, type TransactionHash, type TransactionStatus, type Transport, TransportError, type TransportOptions, type TransportType, type TxReceipt, type TxStatusUpdate, UserRejectedError, type WalletAdapter, type WalletId, type WalletInfo, WalletNotFoundError, WalletNotInstalledError, capabilityGuard, createMetricsPayload, createSession, deriveGenericWalletName, detectNetworkMismatch, errorMetricName, findMatchingWallet, findMatchingWalletInfo, fromCAIP2Network, generateSessionId, hashForPrivacy, installGuard, isCip0103Native, isSessionExpired, isValidCAIP2, mapUnknownErrorToPartyLayerError, matchesProviderDetection, toCAIP2Network, toPartyId, toSessionId, toSignature, toTransactionHash, toWalletId, validatePayload, validateSession };

package/dist/index.js

@@ -103,6 +103,22 @@ var SessionExpiredError = class extends PartyLayerError {
     this.name = "SessionExpiredError";
   }
 };
+var NetworkMismatchError = class extends PartyLayerError {
+  /** The dApp's configured (expected) network, CAIP-2 normalized. */
+  expected;
+  /** The wallet's reported (actual) network, CAIP-2 normalized. */
+  actual;
+  constructor(expected, actual) {
+    super(
+      `Wallet is on network "${actual}" but this app requires "${expected}". Switch your wallet's network, then reconnect.`,
+      "NETWORK_MISMATCH",
+      { details: { expected, actual } }
+    );
+    this.name = "NetworkMismatchError";
+    this.expected = expected;
+    this.actual = actual;
+  }
+};
 var CapabilityNotSupportedError = class extends PartyLayerError {
   constructor(walletId, capability) {
     super(
@@ -493,6 +509,54 @@ var CIP0103_EVENTS = {
   CONNECTED: "connected"
 };
 
+// src/network.ts
+var CANTON_NETWORKS = {
+  mainnet: "canton:da-mainnet",
+  testnet: "canton:da-testnet",
+  devnet: "canton:da-devnet",
+  local: "canton:da-local"
+};
+var CAIP2_TO_SHORT = Object.fromEntries(
+  Object.entries(CANTON_NETWORKS).map(([short, full]) => [full, short])
+);
+function toCAIP2Network(networkId) {
+  let result;
+  if (networkId.includes(":")) {
+    result = networkId;
+  } else {
+    const caip2 = CANTON_NETWORKS[networkId];
+    result = caip2 ?? `canton:${networkId}`;
+  }
+  if (!isValidCAIP2(result)) {
+    throw new Error(
+      `Invalid CAIP-2 network identifier: "${result}". Expected format: "namespace:reference"`
+    );
+  }
+  return { networkId: result };
+}
+function fromCAIP2Network(caip2) {
+  const short = CAIP2_TO_SHORT[caip2];
+  if (short) return short;
+  const colonIndex = caip2.indexOf(":");
+  return colonIndex >= 0 ? caip2.slice(colonIndex + 1) : caip2;
+}
+function isValidCAIP2(networkId) {
+  return /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$/.test(networkId);
+}
+var KNOWN_CAIP2 = new Set(Object.values(CANTON_NETWORKS));
+function detectNetworkMismatch(expected, actual) {
+  let ne;
+  let na;
+  try {
+    ne = toCAIP2Network(expected).networkId;
+    na = toCAIP2Network(actual).networkId;
+  } catch {
+    return null;
+  }
+  if (!KNOWN_CAIP2.has(ne) || !KNOWN_CAIP2.has(na)) return null;
+  return ne === na ? null : { expected: ne, actual: na };
+}
+
 // src/transport/deeplink.ts
 var DeepLinkTransport = class {
   /**
@@ -971,6 +1035,7 @@ var MockTransport = class {
   }
 };
 
+exports.CANTON_NETWORKS = CANTON_NETWORKS;
 exports.CIP0103_EVENTS = CIP0103_EVENTS;
 exports.CIP0103_MANDATORY_METHODS = CIP0103_MANDATORY_METHODS;
 exports.CIP0103_METHODS = CIP0103_METHODS;
@@ -981,6 +1046,7 @@ exports.ERROR_METRICS = ERROR_METRICS;
 exports.InternalError = InternalError;
 exports.METRICS = METRICS;
 exports.MockTransport = MockTransport;
+exports.NetworkMismatchError = NetworkMismatchError;
 exports.OriginNotAllowedError = OriginNotAllowedError;
 exports.PartyLayerError = PartyLayerError;
 exports.PopupTransport = PopupTransport;
@@ -999,16 +1065,20 @@ exports.capabilityGuard = capabilityGuard;
 exports.createMetricsPayload = createMetricsPayload;
 exports.createSession = createSession;
 exports.deriveGenericWalletName = deriveGenericWalletName;
+exports.detectNetworkMismatch = detectNetworkMismatch;
 exports.errorMetricName = errorMetricName;
 exports.findMatchingWallet = findMatchingWallet;
 exports.findMatchingWalletInfo = findMatchingWalletInfo;
+exports.fromCAIP2Network = fromCAIP2Network;
 exports.generateSessionId = generateSessionId;
 exports.hashForPrivacy = hashForPrivacy;
 exports.installGuard = installGuard;
 exports.isCip0103Native = isCip0103Native;
 exports.isSessionExpired = isSessionExpired;
+exports.isValidCAIP2 = isValidCAIP2;
 exports.mapUnknownErrorToPartyLayerError = mapUnknownErrorToPartyLayerError;
 exports.matchesProviderDetection = matchesProviderDetection;
+exports.toCAIP2Network = toCAIP2Network;
 exports.toPartyId = toPartyId;
 exports.toSessionId = toSessionId;
 exports.toSignature = toSignature;