@tezos-x/octez.connect-core 5.0.0-beta.6 → 5.0.1

package/dist/esm/src/utils/assert-never.js

@@ -1,11 +1,28 @@
 /* eslint-disable prefer-arrow/prefer-arrow-functions */
 /**
- * A helper function to make sure if/elses and switch/cases are exhaustive
+ * Exhaustiveness guard for if/else chains and switch/cases.
  *
- * @param empty The data that has to be empty
+ * Compile time: passing anything but `never` is a type error, so adding a new
+ * union member without handling it fails to build. Runtime: an untrusted value
+ * (e.g. an unknown message or error type from the wire) can still reach the
+ * default branch, so throw an actionable error naming that value instead of
+ * silently returning — callers previously received `undefined` and failed
+ * later with no context.
+ *
+ * @param empty The value that should be unreachable
  */
 export function assertNever(empty) {
-    return empty;
+    let repr;
+    try {
+        repr = JSON.stringify(empty) ?? String(empty);
+    }
+    catch {
+        repr = String(empty);
+    }
+    if (repr.length > 200) {
+        repr = `${repr.slice(0, 200)}…`;
+    }
+    throw new Error(`assertNever: reached unreachable case with unexpected value: ${repr}`);
 }
 /* eslint-enable prefer-arrow/prefer-arrow-functions */
 //# sourceMappingURL=assert-never.js.map

package/dist/esm/src/utils/assert-never.js.map

@@ -1 +1 @@
-{"version":3,"file":"assert-never.js","sourceRoot":"","sources":["../../../../src/utils/assert-never.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAExD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,OAAO,KAAK,CAAA;AACd,CAAC;AAED,uDAAuD","sourcesContent":["/* eslint-disable prefer-arrow/prefer-arrow-functions */\n\n/**\n * A helper function to make sure if/elses and switch/cases are exhaustive\n *\n * @param empty The data that has to be empty\n */\nexport function assertNever(empty: never): never {\n  return empty\n}\n\n/* eslint-enable prefer-arrow/prefer-arrow-functions */\n"]}
+{"version":3,"file":"assert-never.js","sourceRoot":"","sources":["../../../../src/utils/assert-never.ts"],"names":[],"mappings":"AAAA,wDAAwD;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,IAAI,IAAY,CAAA;IAChB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAA;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACtB,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAA;IACjC,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,gEAAgE,IAAI,EAAE,CAAC,CAAA;AACzF,CAAC;AAED,uDAAuD","sourcesContent":["/* eslint-disable prefer-arrow/prefer-arrow-functions */\n\n/**\n * Exhaustiveness guard for if/else chains and switch/cases.\n *\n * Compile time: passing anything but `never` is a type error, so adding a new\n * union member without handling it fails to build. Runtime: an untrusted value\n * (e.g. an unknown message or error type from the wire) can still reach the\n * default branch, so throw an actionable error naming that value instead of\n * silently returning — callers previously received `undefined` and failed\n * later with no context.\n *\n * @param empty The value that should be unreachable\n */\nexport function assertNever(empty: never): never {\n  let repr: string\n  try {\n    repr = JSON.stringify(empty) ?? String(empty)\n  } catch {\n    repr = String(empty)\n  }\n  if (repr.length > 200) {\n    repr = `${repr.slice(0, 200)}…`\n  }\n\n  throw new Error(`assertNever: reached unreachable case with unexpected value: ${repr}`)\n}\n\n/* eslint-enable prefer-arrow/prefer-arrow-functions */\n"]}

package/dist/esm/src/utils/caip2.d.ts

@@ -0,0 +1,61 @@
+/**
+ * CAIP-2 chain id helpers, scoped to the Tezos namespace (`tezos:<reference>`).
+ *
+ * The wire format accepts both the bare reference (`NetXsqzbfFenSTS`) and the
+ * full CAIP-2 string (`tezos:NetXsqzbfFenSTS`); SDK code consistently stores
+ * and routes on the full form.
+ */
+import { Network, NetworkType } from '@tezos-x/octez.connect-types';
+/**
+ * Returns `chainId` with the `tezos:` prefix added if absent. No validation
+ * is performed; use `isValidTezosCaip2` at API boundaries.
+ */
+export declare const normalizeTezosCaip2: (chainId: string) => string;
+/**
+ * Whether `value` is a syntactically valid Tezos CAIP-2 chain id
+ * (`tezos:<alphanumeric reference>`).
+ */
+export declare const isValidTezosCaip2: (value: string) => boolean;
+/**
+ * Build the minimal `Network` for a Tezos CAIP-2 chain id. Single source of
+ * truth for the `{ type: CUSTOM, chainId, ... }` shape, so the network used
+ * to derive an account identifier is constructed identically everywhere
+ * (permission storage, operation-request lookup, stale-scheme scan). `name`
+ * defaults to the chain id when the wallet supplies no human label.
+ */
+export declare const networkFromTezosCaip2: (chainId: string, opts?: {
+    name?: string;
+    rpcUrl?: string;
+}) => Network;
+/**
+ * Canonical NetworkType → genesis chain id (CAIP-2 reference) table.
+ *
+ * Applied ONLY at boundaries that must translate between the named-network
+ * vocabulary (WalletConnect session namespaces use `tezos:<name>`) and the
+ * genesis-keyed CAIP-2 vocabulary of the beacon v4 multi-network protocol.
+ *
+ * Sourcing rule: ids are read from the network's own RPC
+ * (`/chains/main/chain_id`) and locked by unit test — never guessed. Networks
+ * without an entry are not statically mappable and multi-network requests for
+ * them can only travel over transports that pass chain ids through opaquely
+ * (P2P/postmessage):
+ * - WEEKLYNET / DAILYNET rotate their genesis on every reset.
+ * - CUSTOM has no fixed genesis by definition.
+ * - TALLINNNET / SEOULNET / TEZLINK_SHADOWNET / TEZOSX_PREVIEWNET /
+ *   TEZOSX_SHADOWNET currently publish no queryable RPC in the teztnets
+ *   registry; add their ids here (RPC-sourced) when available.
+ * If a long-running network relaunches with a new genesis, its entry must be
+ * updated in the same change that bumps the supported network.
+ */
+export declare const TEZOS_NETWORK_GENESIS_IDS: Partial<Record<NetworkType, string>>;
+/**
+ * Full CAIP-2 chain id (`tezos:NetX…`) for a named network, or `undefined`
+ * when the network has no statically known genesis (see
+ * {@link TEZOS_NETWORK_GENESIS_IDS}).
+ */
+export declare const tezosCaip2FromNetworkType: (type: NetworkType) => string | undefined;
+/**
+ * Named network for a CAIP-2 chain id (bare or `tezos:`-prefixed), or
+ * `undefined` when the id does not belong to a statically mapped network.
+ */
+export declare const networkTypeFromTezosCaip2: (chainId: string) => NetworkType | undefined;

package/dist/esm/src/utils/caip2.js

@@ -0,0 +1,82 @@
+/**
+ * CAIP-2 chain id helpers, scoped to the Tezos namespace (`tezos:<reference>`).
+ *
+ * The wire format accepts both the bare reference (`NetXsqzbfFenSTS`) and the
+ * full CAIP-2 string (`tezos:NetXsqzbfFenSTS`); SDK code consistently stores
+ * and routes on the full form.
+ */
+import { NetworkType } from '@tezos-x/octez.connect-types';
+const TEZOS_CAIP2_PREFIX = 'tezos:';
+const TEZOS_CAIP2_RE = /^tezos:[A-Za-z0-9]+$/;
+/**
+ * Returns `chainId` with the `tezos:` prefix added if absent. No validation
+ * is performed; use `isValidTezosCaip2` at API boundaries.
+ */
+export const normalizeTezosCaip2 = (chainId) => chainId.startsWith(TEZOS_CAIP2_PREFIX) ? chainId : `${TEZOS_CAIP2_PREFIX}${chainId}`;
+/**
+ * Whether `value` is a syntactically valid Tezos CAIP-2 chain id
+ * (`tezos:<alphanumeric reference>`).
+ */
+export const isValidTezosCaip2 = (value) => TEZOS_CAIP2_RE.test(value);
+/**
+ * Build the minimal `Network` for a Tezos CAIP-2 chain id. Single source of
+ * truth for the `{ type: CUSTOM, chainId, ... }` shape, so the network used
+ * to derive an account identifier is constructed identically everywhere
+ * (permission storage, operation-request lookup, stale-scheme scan). `name`
+ * defaults to the chain id when the wallet supplies no human label.
+ */
+export const networkFromTezosCaip2 = (chainId, opts) => ({
+    type: NetworkType.CUSTOM,
+    name: opts?.name ?? chainId,
+    rpcUrl: opts?.rpcUrl,
+    chainId
+});
+/**
+ * Canonical NetworkType → genesis chain id (CAIP-2 reference) table.
+ *
+ * Applied ONLY at boundaries that must translate between the named-network
+ * vocabulary (WalletConnect session namespaces use `tezos:<name>`) and the
+ * genesis-keyed CAIP-2 vocabulary of the beacon v4 multi-network protocol.
+ *
+ * Sourcing rule: ids are read from the network's own RPC
+ * (`/chains/main/chain_id`) and locked by unit test — never guessed. Networks
+ * without an entry are not statically mappable and multi-network requests for
+ * them can only travel over transports that pass chain ids through opaquely
+ * (P2P/postmessage):
+ * - WEEKLYNET / DAILYNET rotate their genesis on every reset.
+ * - CUSTOM has no fixed genesis by definition.
+ * - TALLINNNET / SEOULNET / TEZLINK_SHADOWNET / TEZOSX_PREVIEWNET /
+ *   TEZOSX_SHADOWNET currently publish no queryable RPC in the teztnets
+ *   registry; add their ids here (RPC-sourced) when available.
+ * If a long-running network relaunches with a new genesis, its entry must be
+ * updated in the same change that bumps the supported network.
+ */
+export const TEZOS_NETWORK_GENESIS_IDS = {
+    [NetworkType.MAINNET]: 'NetXdQprcVkpaWU',
+    [NetworkType.GHOSTNET]: 'NetXnHfVqm9iesp',
+    [NetworkType.SHADOWNET]: 'NetXsqzbfFenSTS',
+    // Tezos X L2 (Michelson runtime) mainnet. Maintainer-supplied id — no
+    // public RPC was reachable at the time of adding; re-verify against
+    // `/chains/main/chain_id` once one ships.
+    [NetworkType.TEZOSX_MAINNET]: 'NetXohUVN5QWR4f',
+    [NetworkType.USHUAIANET]: 'NetXpX8WSZkAZZA'
+};
+/**
+ * Full CAIP-2 chain id (`tezos:NetX…`) for a named network, or `undefined`
+ * when the network has no statically known genesis (see
+ * {@link TEZOS_NETWORK_GENESIS_IDS}).
+ */
+export const tezosCaip2FromNetworkType = (type) => {
+    const genesis = TEZOS_NETWORK_GENESIS_IDS[type];
+    return genesis === undefined ? undefined : `${TEZOS_CAIP2_PREFIX}${genesis}`;
+};
+/**
+ * Named network for a CAIP-2 chain id (bare or `tezos:`-prefixed), or
+ * `undefined` when the id does not belong to a statically mapped network.
+ */
+export const networkTypeFromTezosCaip2 = (chainId) => {
+    const normalized = normalizeTezosCaip2(chainId);
+    const reference = normalized.slice(TEZOS_CAIP2_PREFIX.length);
+    return Object.keys(TEZOS_NETWORK_GENESIS_IDS).find((type) => TEZOS_NETWORK_GENESIS_IDS[type] === reference);
+};
+//# sourceMappingURL=caip2.js.map

package/dist/esm/src/utils/caip2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caip2.js","sourceRoot":"","sources":["../../../../src/utils/caip2.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAW,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAEnE,MAAM,kBAAkB,GAAG,QAAQ,CAAA;AAEnC,MAAM,cAAc,GAAG,sBAAsB,CAAA;AAE7C;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAe,EAAU,EAAE,CAC7D,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,kBAAkB,GAAG,OAAO,EAAE,CAAA;AAEtF;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAa,EAAW,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAEvF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,OAAe,EACf,IAAyC,EAChC,EAAE,CAAC,CAAC;IACb,IAAI,EAAE,WAAW,CAAC,MAAM;IACxB,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,OAAO;IAC3B,MAAM,EAAE,IAAI,EAAE,MAAM;IACpB,OAAO;CACR,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAyC;IAC7E,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,iBAAiB;IACxC,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,iBAAiB;IACzC,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,iBAAiB;IAC1C,sEAAsE;IACtE,oEAAoE;IACpE,0CAA0C;IAC1C,CAAC,WAAW,CAAC,cAAc,CAAC,EAAE,iBAAiB;IAC/C,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,iBAAiB;CAC5C,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,IAAiB,EAAsB,EAAE;IACjF,MAAM,OAAO,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAA;IAE/C,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,kBAAkB,GAAG,OAAO,EAAE,CAAA;AAC9E,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,OAAe,EAA2B,EAAE;IACpF,MAAM,UAAU,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAA;IAC/C,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAA;IAE7D,OAAQ,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAmB,CAAC,IAAI,CACnE,CAAC,IAAI,EAAE,EAAE,CAAC,yBAAyB,CAAC,IAAI,CAAC,KAAK,SAAS,CACxD,CAAA;AACH,CAAC,CAAA","sourcesContent":["/**\n * CAIP-2 chain id helpers, scoped to the Tezos namespace (`tezos:<reference>`).\n *\n * The wire format accepts both the bare reference (`NetXsqzbfFenSTS`) and the\n * full CAIP-2 string (`tezos:NetXsqzbfFenSTS`); SDK code consistently stores\n * and routes on the full form.\n */\nimport { Network, NetworkType } from '@tezos-x/octez.connect-types'\n\nconst TEZOS_CAIP2_PREFIX = 'tezos:'\n\nconst TEZOS_CAIP2_RE = /^tezos:[A-Za-z0-9]+$/\n\n/**\n * Returns `chainId` with the `tezos:` prefix added if absent. No validation\n * is performed; use `isValidTezosCaip2` at API boundaries.\n */\nexport const normalizeTezosCaip2 = (chainId: string): string =>\n  chainId.startsWith(TEZOS_CAIP2_PREFIX) ? chainId : `${TEZOS_CAIP2_PREFIX}${chainId}`\n\n/**\n * Whether `value` is a syntactically valid Tezos CAIP-2 chain id\n * (`tezos:<alphanumeric reference>`).\n */\nexport const isValidTezosCaip2 = (value: string): boolean => TEZOS_CAIP2_RE.test(value)\n\n/**\n * Build the minimal `Network` for a Tezos CAIP-2 chain id. Single source of\n * truth for the `{ type: CUSTOM, chainId, ... }` shape, so the network used\n * to derive an account identifier is constructed identically everywhere\n * (permission storage, operation-request lookup, stale-scheme scan). `name`\n * defaults to the chain id when the wallet supplies no human label.\n */\nexport const networkFromTezosCaip2 = (\n  chainId: string,\n  opts?: { name?: string; rpcUrl?: string }\n): Network => ({\n  type: NetworkType.CUSTOM,\n  name: opts?.name ?? chainId,\n  rpcUrl: opts?.rpcUrl,\n  chainId\n})\n\n/**\n * Canonical NetworkType → genesis chain id (CAIP-2 reference) table.\n *\n * Applied ONLY at boundaries that must translate between the named-network\n * vocabulary (WalletConnect session namespaces use `tezos:<name>`) and the\n * genesis-keyed CAIP-2 vocabulary of the beacon v4 multi-network protocol.\n *\n * Sourcing rule: ids are read from the network's own RPC\n * (`/chains/main/chain_id`) and locked by unit test — never guessed. Networks\n * without an entry are not statically mappable and multi-network requests for\n * them can only travel over transports that pass chain ids through opaquely\n * (P2P/postmessage):\n * - WEEKLYNET / DAILYNET rotate their genesis on every reset.\n * - CUSTOM has no fixed genesis by definition.\n * - TALLINNNET / SEOULNET / TEZLINK_SHADOWNET / TEZOSX_PREVIEWNET /\n *   TEZOSX_SHADOWNET currently publish no queryable RPC in the teztnets\n *   registry; add their ids here (RPC-sourced) when available.\n * If a long-running network relaunches with a new genesis, its entry must be\n * updated in the same change that bumps the supported network.\n */\nexport const TEZOS_NETWORK_GENESIS_IDS: Partial<Record<NetworkType, string>> = {\n  [NetworkType.MAINNET]: 'NetXdQprcVkpaWU',\n  [NetworkType.GHOSTNET]: 'NetXnHfVqm9iesp',\n  [NetworkType.SHADOWNET]: 'NetXsqzbfFenSTS',\n  // Tezos X L2 (Michelson runtime) mainnet. Maintainer-supplied id — no\n  // public RPC was reachable at the time of adding; re-verify against\n  // `/chains/main/chain_id` once one ships.\n  [NetworkType.TEZOSX_MAINNET]: 'NetXohUVN5QWR4f',\n  [NetworkType.USHUAIANET]: 'NetXpX8WSZkAZZA'\n}\n\n/**\n * Full CAIP-2 chain id (`tezos:NetX…`) for a named network, or `undefined`\n * when the network has no statically known genesis (see\n * {@link TEZOS_NETWORK_GENESIS_IDS}).\n */\nexport const tezosCaip2FromNetworkType = (type: NetworkType): string | undefined => {\n  const genesis = TEZOS_NETWORK_GENESIS_IDS[type]\n\n  return genesis === undefined ? undefined : `${TEZOS_CAIP2_PREFIX}${genesis}`\n}\n\n/**\n * Named network for a CAIP-2 chain id (bare or `tezos:`-prefixed), or\n * `undefined` when the id does not belong to a statically mapped network.\n */\nexport const networkTypeFromTezosCaip2 = (chainId: string): NetworkType | undefined => {\n  const normalized = normalizeTezosCaip2(chainId)\n  const reference = normalized.slice(TEZOS_CAIP2_PREFIX.length)\n\n  return (Object.keys(TEZOS_NETWORK_GENESIS_IDS) as NetworkType[]).find(\n    (type) => TEZOS_NETWORK_GENESIS_IDS[type] === reference\n  )\n}\n"]}

package/dist/esm/src/utils/get-account-identifier.js

@@ -10,12 +10,26 @@ import { encode } from '@stablelib/utf8';
  * @param network
  */
 export const getAccountIdentifier = async (address, network) => {
-    const data = [address, network.type];
-    if (network.name) {
-        data.push(`name:${network.name}`);
+    // v4 multi-network accounts carry a CAIP-2 chainId. Key the identifier on
+    // (address, chainId) alone: chainId is the canonical, stable network key,
+    // whereas the human-facing `name`/`rpcUrl` differ between the wallet's
+    // permission response and the dApp's later operation requests. Including
+    // them would make the persisted identifier irreproducible at lookup time
+    // (and collapse distinct chains that happen to share a name). Legacy
+    // accounts (no chainId) keep the original scheme so their already-persisted
+    // identifiers are unchanged.
+    const data = [];
+    if (network.chainId) {
+        data.push(address, `chainId:${network.chainId}`);
     }
-    if (network.rpcUrl) {
-        data.push(`rpc:${network.rpcUrl}`);
+    else {
+        data.push(address, network.type);
+        if (network.name) {
+            data.push(`name:${network.name}`);
+        }
+        if (network.rpcUrl) {
+            data.push(`rpc:${network.rpcUrl}`);
+        }
     }
     const buffer = Buffer.from(hash(encode(data.join('-')), 10));
     return bs58check.encode(buffer);

package/dist/esm/src/utils/get-account-identifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-account-identifier.js","sourceRoot":"","sources":["../../../../src/utils/get-account-identifier.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,WAAW,CAAA;AAEjC,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,EAAE,OAAe,EAAE,OAAgB,EAAmB,EAAE;IAC/F,MAAM,IAAI,GAAa,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9C,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,IAAI,CAAC,IAAI,CAAC,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;IACnC,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACpC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;IAE5D,OAAO,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;AACjC,CAAC,CAAA","sourcesContent":["import bs58check from 'bs58check'\nimport { Network } from '@tezos-x/octez.connect-types'\nimport { hash } from '@stablelib/blake2b'\nimport { encode } from '@stablelib/utf8'\n\n/**\n * @internalapi\n *\n * Generate a deterministic account identifier based on an address and a network\n *\n * @param address\n * @param network\n */\nexport const getAccountIdentifier = async (address: string, network: Network): Promise<string> => {\n  const data: string[] = [address, network.type]\n  if (network.name) {\n    data.push(`name:${network.name}`)\n  }\n  if (network.rpcUrl) {\n    data.push(`rpc:${network.rpcUrl}`)\n  }\n\n  const buffer = Buffer.from(hash(encode(data.join('-')), 10))\n\n  return bs58check.encode(buffer)\n}\n"]}
+{"version":3,"file":"get-account-identifier.js","sourceRoot":"","sources":["../../../../src/utils/get-account-identifier.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,WAAW,CAAA;AAEjC,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,EAAE,OAAe,EAAE,OAAgB,EAAmB,EAAE;IAC/F,0EAA0E;IAC1E,0EAA0E;IAC1E,uEAAuE;IACvE,yEAAyE;IACzE,yEAAyE;IACzE,qEAAqE;IACrE,4EAA4E;IAC5E,6BAA6B;IAC7B,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IAClD,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;QAChC,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,CAAC,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;QACnC,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;QACpC,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;IAE5D,OAAO,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;AACjC,CAAC,CAAA","sourcesContent":["import bs58check from 'bs58check'\nimport { Network } from '@tezos-x/octez.connect-types'\nimport { hash } from '@stablelib/blake2b'\nimport { encode } from '@stablelib/utf8'\n\n/**\n * @internalapi\n *\n * Generate a deterministic account identifier based on an address and a network\n *\n * @param address\n * @param network\n */\nexport const getAccountIdentifier = async (address: string, network: Network): Promise<string> => {\n  // v4 multi-network accounts carry a CAIP-2 chainId. Key the identifier on\n  // (address, chainId) alone: chainId is the canonical, stable network key,\n  // whereas the human-facing `name`/`rpcUrl` differ between the wallet's\n  // permission response and the dApp's later operation requests. Including\n  // them would make the persisted identifier irreproducible at lookup time\n  // (and collapse distinct chains that happen to share a name). Legacy\n  // accounts (no chainId) keep the original scheme so their already-persisted\n  // identifiers are unchanged.\n  const data: string[] = []\n  if (network.chainId) {\n    data.push(address, `chainId:${network.chainId}`)\n  } else {\n    data.push(address, network.type)\n    if (network.name) {\n      data.push(`name:${network.name}`)\n    }\n    if (network.rpcUrl) {\n      data.push(`rpc:${network.rpcUrl}`)\n    }\n  }\n\n  const buffer = Buffer.from(hash(encode(data.join('-')), 10))\n\n  return bs58check.encode(buffer)\n}\n"]}

package/dist/esm/src/utils/message-utils.d.ts

@@ -1,2 +1,96 @@
+import { BeaconMessageType, BeaconMessageWrapper, DisconnectMessage } from '@tezos-x/octez.connect-types';
+interface WrappedPayload {
+    type: unknown;
+}
 export declare const MESSAGE_WRAPPED_FROM_VERSION = 3;
+export declare const MULTI_NETWORK_FROM_VERSION = "4";
+export declare const parseStrictDecimalInteger: (value: unknown) => number | null;
+/**
+ * Compare two `peer.version` strings as strict decimal integers.
+ *
+ * Returns < 0 if `a < b`, 0 if equal, > 0 if `a > b` — same convention as
+ * `Array.prototype.sort` comparators.
+ *
+ * Throws `InvalidBeaconVersionError` if either operand is not a decimal-
+ * integer string in `[0, Number.MAX_SAFE_INTEGER]`. Leading signs, leading
+ * zeros, decimal points, exponent notation, hex, whitespace, `'NaN'` and
+ * `'Infinity'` all reject.
+ *
+ * @category Utility
+ */
+export declare const compareBeaconVersion: (a: unknown, b: unknown) => number;
+/**
+ * Whether `version` is a valid peer.version at or above `threshold`.
+ *
+ * Single source of truth for the "is this peer at least version X" decision.
+ * Returns `false` for an absent version and for any value that fails the
+ * strict decimal-integer contract of `compareBeaconVersion` — i.e. malformed
+ * or untrusted input is always treated as below the threshold, so a hostile
+ * peer cannot trip a higher-version code path.
+ *
+ * @category Utility
+ */
+export declare const isAtLeastVersion: (version: string | undefined, threshold: string) => boolean;
+/**
+ * Whether `version` is at or above the multi-network (v4) threshold.
+ *
+ * @category Utility
+ */
+export declare const isMultiNetworkVersion: (version: string | undefined) => boolean;
 export declare const usesWrappedMessages: (version?: string) => boolean;
+/** The flat legacy wire dialect served to peers below the wrapped baseline. */
+export declare const LEGACY_ENVELOPE_VERSION = "2";
+/**
+ * The envelope version to stamp on an outgoing message for a peer that
+ * declared `peerVersion` at pairing: `min(peerVersion, BEACON_VERSION)` with
+ * a floor at the flat legacy dialect ('2').
+ *
+ * This is the backward-compatibility pivot: a peer that declared '2' — or
+ * never declared a version at all (legacy pairings, WalletConnect peers,
+ * malformed values) — is served the flat v2 dialect it has always spoken; a
+ * v3 peer receives '3' wrapped envelopes and never sees v4 payload fields;
+ * a v4 peer gets the full wrapped v4 wire. Callers pick the message SHAPE
+ * with `usesWrappedMessages(negotiated)` and gate v4 fields (`networks`/
+ * `accounts`) on `isMultiNetworkVersion(negotiated)`.
+ *
+ * @category Utility
+ */
+export declare const negotiateEnvelopeVersion: (peerVersion: string | undefined) => string;
+/**
+ * Build a wrapped beacon envelope. Single source of truth for the
+ * `{ id, version, senderId, message }` wire shape so senders cannot drift.
+ *
+ * @category Utility
+ */
+export declare const wrapBeaconMessage: <T extends WrappedPayload>(envelope: {
+    id: string;
+    version: string;
+    senderId: string;
+}, message: T) => BeaconMessageWrapper<T>;
+/**
+ * Extract the inner payload of a wrapped beacon envelope, or `undefined`
+ * when the candidate's version does not follow the wrapped (v3+) contract.
+ * Callers must treat `undefined` as "not a wrapped message" and drop or
+ * tombstone it — never fall back to reading flat fields.
+ *
+ * @category Utility
+ */
+export declare const unwrapBeaconMessage: <T extends WrappedPayload>(candidate: {
+    version?: string;
+    message?: T;
+}) => T | undefined;
+/**
+ * Build a disconnect message in the peer's negotiated dialect: a wrapped
+ * envelope for v3+ peers, the flat legacy shape for v2 peers. A legacy peer
+ * routes on the top-level `type` and would silently ignore a wrapped
+ * envelope — the goodbye must be spoken in the dialect the peer parses.
+ *
+ * @category Utility
+ */
+export declare const buildDisconnectMessage: (envelope: {
+    id: string;
+    senderId: string;
+}, peerVersion: string | undefined) => DisconnectMessage | BeaconMessageWrapper<{
+    type: BeaconMessageType.Disconnect;
+}>;
+export {};

package/dist/esm/src/utils/message-utils.js

@@ -1,9 +1,144 @@
+import { BeaconMessageType } from '@tezos-x/octez.connect-types';
+import { BEACON_VERSION } from '../constants';
+import { InvalidBeaconVersionError } from '../errors/InvalidBeaconVersionError';
 export const MESSAGE_WRAPPED_FROM_VERSION = 3;
-export const usesWrappedMessages = (version) => {
-    if (!version) {
+// peer.version at or above which the multi-network (v4) protocol applies.
+export const MULTI_NETWORK_FROM_VERSION = '4';
+// Strict decimal-integer: a lone `0` or non-zero digit followed by digits.
+// Rejects leading zeros on multi-digit values (e.g. `'04'`). A lone `0` is
+// kept valid so legacy compat paths can use it as a fallback/unknown version.
+const DECIMAL_INTEGER_RE = /^(0|[1-9]\d*)$/;
+export const parseStrictDecimalInteger = (value) => {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    if (!DECIMAL_INTEGER_RE.test(value)) {
+        return null;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed > Number.MAX_SAFE_INTEGER) {
+        return null;
+    }
+    return parsed;
+};
+/**
+ * Compare two `peer.version` strings as strict decimal integers.
+ *
+ * Returns < 0 if `a < b`, 0 if equal, > 0 if `a > b` — same convention as
+ * `Array.prototype.sort` comparators.
+ *
+ * Throws `InvalidBeaconVersionError` if either operand is not a decimal-
+ * integer string in `[0, Number.MAX_SAFE_INTEGER]`. Leading signs, leading
+ * zeros, decimal points, exponent notation, hex, whitespace, `'NaN'` and
+ * `'Infinity'` all reject.
+ *
+ * @category Utility
+ */
+export const compareBeaconVersion = (a, b) => {
+    const na = parseStrictDecimalInteger(a);
+    const nb = parseStrictDecimalInteger(b);
+    if (na === null || nb === null) {
+        throw new InvalidBeaconVersionError(a, b);
+    }
+    return na - nb;
+};
+/**
+ * Whether `version` is a valid peer.version at or above `threshold`.
+ *
+ * Single source of truth for the "is this peer at least version X" decision.
+ * Returns `false` for an absent version and for any value that fails the
+ * strict decimal-integer contract of `compareBeaconVersion` — i.e. malformed
+ * or untrusted input is always treated as below the threshold, so a hostile
+ * peer cannot trip a higher-version code path.
+ *
+ * @category Utility
+ */
+export const isAtLeastVersion = (version, threshold) => {
+    if (version === undefined) {
         return false;
     }
-    const parsed = Number(version);
-    return Number.isFinite(parsed) && parsed >= MESSAGE_WRAPPED_FROM_VERSION;
+    try {
+        return compareBeaconVersion(version, threshold) >= 0;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Whether `version` is at or above the multi-network (v4) threshold.
+ *
+ * @category Utility
+ */
+export const isMultiNetworkVersion = (version) => isAtLeastVersion(version, MULTI_NETWORK_FROM_VERSION);
+export const usesWrappedMessages = (version) => {
+    // Use the same strict decimal-integer contract as compareBeaconVersion so
+    // wrapped-message routing agrees with the v4/multi-network routing: a loose
+    // value like '3.0', ' 3 ' or '03' (which Number() would accept) is treated
+    // as malformed and routed as non-wrapped rather than inconsistently.
+    const parsed = parseStrictDecimalInteger(version);
+    return parsed !== null && parsed >= MESSAGE_WRAPPED_FROM_VERSION;
+};
+/** The flat legacy wire dialect served to peers below the wrapped baseline. */
+export const LEGACY_ENVELOPE_VERSION = '2';
+/**
+ * The envelope version to stamp on an outgoing message for a peer that
+ * declared `peerVersion` at pairing: `min(peerVersion, BEACON_VERSION)` with
+ * a floor at the flat legacy dialect ('2').
+ *
+ * This is the backward-compatibility pivot: a peer that declared '2' — or
+ * never declared a version at all (legacy pairings, WalletConnect peers,
+ * malformed values) — is served the flat v2 dialect it has always spoken; a
+ * v3 peer receives '3' wrapped envelopes and never sees v4 payload fields;
+ * a v4 peer gets the full wrapped v4 wire. Callers pick the message SHAPE
+ * with `usesWrappedMessages(negotiated)` and gate v4 fields (`networks`/
+ * `accounts`) on `isMultiNetworkVersion(negotiated)`.
+ *
+ * @category Utility
+ */
+export const negotiateEnvelopeVersion = (peerVersion) => {
+    if (!isAtLeastVersion(peerVersion, String(MESSAGE_WRAPPED_FROM_VERSION))) {
+        return LEGACY_ENVELOPE_VERSION;
+    }
+    return isAtLeastVersion(peerVersion, BEACON_VERSION) ? BEACON_VERSION : peerVersion;
+};
+/**
+ * Build a wrapped beacon envelope. Single source of truth for the
+ * `{ id, version, senderId, message }` wire shape so senders cannot drift.
+ *
+ * @category Utility
+ */
+export const wrapBeaconMessage = (envelope, message) => ({
+    id: envelope.id,
+    version: envelope.version,
+    senderId: envelope.senderId,
+    message
+});
+/**
+ * Extract the inner payload of a wrapped beacon envelope, or `undefined`
+ * when the candidate's version does not follow the wrapped (v3+) contract.
+ * Callers must treat `undefined` as "not a wrapped message" and drop or
+ * tombstone it — never fall back to reading flat fields.
+ *
+ * @category Utility
+ */
+export const unwrapBeaconMessage = (candidate) => (usesWrappedMessages(candidate.version) ? candidate.message : undefined);
+/**
+ * Build a disconnect message in the peer's negotiated dialect: a wrapped
+ * envelope for v3+ peers, the flat legacy shape for v2 peers. A legacy peer
+ * routes on the top-level `type` and would silently ignore a wrapped
+ * envelope — the goodbye must be spoken in the dialect the peer parses.
+ *
+ * @category Utility
+ */
+export const buildDisconnectMessage = (envelope, peerVersion) => {
+    const version = negotiateEnvelopeVersion(peerVersion);
+    return usesWrappedMessages(version)
+        ? wrapBeaconMessage({ id: envelope.id, version, senderId: envelope.senderId }, { type: BeaconMessageType.Disconnect })
+        : {
+            id: envelope.id,
+            version,
+            senderId: envelope.senderId,
+            type: BeaconMessageType.Disconnect
+        };
 };
 //# sourceMappingURL=message-utils.js.map

package/dist/esm/src/utils/message-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"message-utils.js","sourceRoot":"","sources":["../../../../src/utils/message-utils.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAA;AAE7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAgB,EAAW,EAAE;IAC/D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;IAE9B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,4BAA4B,CAAA;AAC1E,CAAC,CAAA","sourcesContent":["export const MESSAGE_WRAPPED_FROM_VERSION = 3\n\nexport const usesWrappedMessages = (version?: string): boolean => {\n  if (!version) {\n    return false\n  }\n\n  const parsed = Number(version)\n\n  return Number.isFinite(parsed) && parsed >= MESSAGE_WRAPPED_FROM_VERSION\n}\n\n"]}
+{"version":3,"file":"message-utils.js","sourceRoot":"","sources":["../../../../src/utils/message-utils.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  BeaconMessageType,\n  BeaconMessageWrapper,\n  DisconnectMessage\n} from '@tezos-x/octez.connect-types'\nimport { BEACON_VERSION } from '../constants'\n\n// Structural stand-in for the beaconV3 BeaconBaseMessage ({ type: unknown }).\n// The types barrel re-exports the flat BeaconBaseMessage (which also carries\n// id/version/senderId) under the same name, so constraining on the barrel\n// type would wrongly require envelope fields on the inner payload.\ninterface WrappedPayload { type: unknown }\nimport { InvalidBeaconVersionError } from '../errors/InvalidBeaconVersionError'\n\nexport const MESSAGE_WRAPPED_FROM_VERSION = 3\n\n// peer.version at or above which the multi-network (v4) protocol applies.\nexport const MULTI_NETWORK_FROM_VERSION = '4'\n\n// Strict decimal-integer: a lone `0` or non-zero digit followed by digits.\n// Rejects leading zeros on multi-digit values (e.g. `'04'`). A lone `0` is\n// kept valid so legacy compat paths can use it as a fallback/unknown version.\nconst DECIMAL_INTEGER_RE = /^(0|[1-9]\\d*)$/\n\nexport const parseStrictDecimalInteger = (value: unknown): number | null => {\n  if (typeof value !== 'string') {\n    return null\n  }\n  if (!DECIMAL_INTEGER_RE.test(value)) {\n    return null\n  }\n  const parsed = Number(value)\n  if (!Number.isFinite(parsed) || parsed > Number.MAX_SAFE_INTEGER) {\n    return null\n  }\n\n  return parsed\n}\n\n/**\n * Compare two `peer.version` strings as strict decimal integers.\n *\n * Returns < 0 if `a < b`, 0 if equal, > 0 if `a > b` — same convention as\n * `Array.prototype.sort` comparators.\n *\n * Throws `InvalidBeaconVersionError` if either operand is not a decimal-\n * integer string in `[0, Number.MAX_SAFE_INTEGER]`. Leading signs, leading\n * zeros, decimal points, exponent notation, hex, whitespace, `'NaN'` and\n * `'Infinity'` all reject.\n *\n * @category Utility\n */\nexport const compareBeaconVersion = (a: unknown, b: unknown): number => {\n  const na = parseStrictDecimalInteger(a)\n  const nb = parseStrictDecimalInteger(b)\n\n  if (na === null || nb === null) {\n    throw new InvalidBeaconVersionError(a, b)\n  }\n\n  return na - nb\n}\n\n/**\n * Whether `version` is a valid peer.version at or above `threshold`.\n *\n * Single source of truth for the \"is this peer at least version X\" decision.\n * Returns `false` for an absent version and for any value that fails the\n * strict decimal-integer contract of `compareBeaconVersion` — i.e. malformed\n * or untrusted input is always treated as below the threshold, so a hostile\n * peer cannot trip a higher-version code path.\n *\n * @category Utility\n */\nexport const isAtLeastVersion = (version: string | undefined, threshold: string): boolean => {\n  if (version === undefined) {\n    return false\n  }\n  try {\n    return compareBeaconVersion(version, threshold) >= 0\n  } catch {\n    return false\n  }\n}\n\n/**\n * Whether `version` is at or above the multi-network (v4) threshold.\n *\n * @category Utility\n */\nexport const isMultiNetworkVersion = (version: string | undefined): boolean =>\n  isAtLeastVersion(version, MULTI_NETWORK_FROM_VERSION)\n\nexport const usesWrappedMessages = (version?: string): boolean => {\n  // Use the same strict decimal-integer contract as compareBeaconVersion so\n  // wrapped-message routing agrees with the v4/multi-network routing: a loose\n  // value like '3.0', ' 3 ' or '03' (which Number() would accept) is treated\n  // as malformed and routed as non-wrapped rather than inconsistently.\n  const parsed = parseStrictDecimalInteger(version)\n\n  return parsed !== null && parsed >= MESSAGE_WRAPPED_FROM_VERSION\n}\n\n/** The flat legacy wire dialect served to peers below the wrapped baseline. */\nexport const LEGACY_ENVELOPE_VERSION = '2'\n\n/**\n * The envelope version to stamp on an outgoing message for a peer that\n * declared `peerVersion` at pairing: `min(peerVersion, BEACON_VERSION)` with\n * a floor at the flat legacy dialect ('2').\n *\n * This is the backward-compatibility pivot: a peer that declared '2' — or\n * never declared a version at all (legacy pairings, WalletConnect peers,\n * malformed values) — is served the flat v2 dialect it has always spoken; a\n * v3 peer receives '3' wrapped envelopes and never sees v4 payload fields;\n * a v4 peer gets the full wrapped v4 wire. Callers pick the message SHAPE\n * with `usesWrappedMessages(negotiated)` and gate v4 fields (`networks`/\n * `accounts`) on `isMultiNetworkVersion(negotiated)`.\n *\n * @category Utility\n */\nexport const negotiateEnvelopeVersion = (peerVersion: string | undefined): string => {\n  if (!isAtLeastVersion(peerVersion, String(MESSAGE_WRAPPED_FROM_VERSION))) {\n    return LEGACY_ENVELOPE_VERSION\n  }\n\n  return isAtLeastVersion(peerVersion, BEACON_VERSION) ? BEACON_VERSION : (peerVersion as string)\n}\n\n/**\n * Build a wrapped beacon envelope. Single source of truth for the\n * `{ id, version, senderId, message }` wire shape so senders cannot drift.\n *\n * @category Utility\n */\nexport const wrapBeaconMessage = <T extends WrappedPayload>(\n  envelope: { id: string; version: string; senderId: string },\n  message: T\n): BeaconMessageWrapper<T> => ({\n  id: envelope.id,\n  version: envelope.version,\n  senderId: envelope.senderId,\n  message\n})\n\n/**\n * Extract the inner payload of a wrapped beacon envelope, or `undefined`\n * when the candidate's version does not follow the wrapped (v3+) contract.\n * Callers must treat `undefined` as \"not a wrapped message\" and drop or\n * tombstone it — never fall back to reading flat fields.\n *\n * @category Utility\n */\nexport const unwrapBeaconMessage = <T extends WrappedPayload>(candidate: {\n  version?: string\n  message?: T\n}): T | undefined => (usesWrappedMessages(candidate.version) ? candidate.message : undefined)\n\n/**\n * Build a disconnect message in the peer's negotiated dialect: a wrapped\n * envelope for v3+ peers, the flat legacy shape for v2 peers. A legacy peer\n * routes on the top-level `type` and would silently ignore a wrapped\n * envelope — the goodbye must be spoken in the dialect the peer parses.\n *\n * @category Utility\n */\nexport const buildDisconnectMessage = (\n  envelope: { id: string; senderId: string },\n  peerVersion: string | undefined\n): DisconnectMessage | BeaconMessageWrapper<{ type: BeaconMessageType.Disconnect }> => {\n  const version = negotiateEnvelopeVersion(peerVersion)\n\n  return usesWrappedMessages(version)\n    ? wrapBeaconMessage(\n        { id: envelope.id, version, senderId: envelope.senderId },\n        { type: BeaconMessageType.Disconnect }\n      )\n    : {\n        id: envelope.id,\n        version,\n        senderId: envelope.senderId,\n        type: BeaconMessageType.Disconnect\n      }\n}\n"]}

package/dist/esm/src/utils/required-minimum-version.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Default minimum wallet version the dApp accepts when the option is omitted.
+ *
+ * Deliberately the lowest protocol version still supported, so the gate is
+ * effectively opt-in: by default every wallet the SDK can talk to (v2/v3/v4)
+ * is accepted, preserving backward compatibility. A dApp that needs the v4
+ * multi-network protocol sets `requiredMinimumVersion: '4'` explicitly.
+ */
+export declare const DEFAULT_REQUIRED_MINIMUM_VERSION = "2";
+/**
+ * Resolve a dApp's `requiredMinimumVersion` option against the SDK's
+ * `BEACON_VERSION`. Returns {@link DEFAULT_REQUIRED_MINIMUM_VERSION} when
+ * undefined; otherwise validates the supplied value is a decimal-integer
+ * string in `[1, BEACON_VERSION]` and returns it unchanged.
+ *
+ * Throws `InvalidRequiredMinimumVersionError` for any malformed,
+ * out-of-range, or future-version input.
+ */
+export declare const resolveRequiredMinimumVersion: (providedValue: string | undefined) => string;

package/dist/esm/src/utils/required-minimum-version.js

@@ -0,0 +1,43 @@
+import { BEACON_VERSION } from '../constants';
+import { InvalidRequiredMinimumVersionError } from '../errors/InvalidRequiredMinimumVersionError';
+import { compareBeaconVersion, parseStrictDecimalInteger } from './message-utils';
+/**
+ * Default minimum wallet version the dApp accepts when the option is omitted.
+ *
+ * Deliberately the lowest protocol version still supported, so the gate is
+ * effectively opt-in: by default every wallet the SDK can talk to (v2/v3/v4)
+ * is accepted, preserving backward compatibility. A dApp that needs the v4
+ * multi-network protocol sets `requiredMinimumVersion: '4'` explicitly.
+ */
+export const DEFAULT_REQUIRED_MINIMUM_VERSION = '2';
+/**
+ * Resolve a dApp's `requiredMinimumVersion` option against the SDK's
+ * `BEACON_VERSION`. Returns {@link DEFAULT_REQUIRED_MINIMUM_VERSION} when
+ * undefined; otherwise validates the supplied value is a decimal-integer
+ * string in `[1, BEACON_VERSION]` and returns it unchanged.
+ *
+ * Throws `InvalidRequiredMinimumVersionError` for any malformed,
+ * out-of-range, or future-version input.
+ */
+export const resolveRequiredMinimumVersion = (providedValue) => {
+    if (providedValue === undefined) {
+        return DEFAULT_REQUIRED_MINIMUM_VERSION;
+    }
+    // Validate against the SAME strict contract compareBeaconVersion enforces,
+    // up front, so every rejection here is an InvalidRequiredMinimumVersionError
+    // rather than a leaked InvalidBeaconVersionError from the comparison below.
+    // Reuse parseStrictDecimalInteger (the single owner of that contract) instead
+    // of re-declaring the regex + MAX_SAFE_INTEGER bound here.
+    const parsed = parseStrictDecimalInteger(providedValue);
+    if (parsed === null) {
+        throw new InvalidRequiredMinimumVersionError(providedValue, BEACON_VERSION, 'value must be a decimal-integer string (e.g. "3", "4")');
+    }
+    if (parsed < 1) {
+        throw new InvalidRequiredMinimumVersionError(providedValue, BEACON_VERSION, 'value must be >= 1');
+    }
+    if (compareBeaconVersion(providedValue, BEACON_VERSION) > 0) {
+        throw new InvalidRequiredMinimumVersionError(providedValue, BEACON_VERSION, `value cannot exceed the SDK's own BEACON_VERSION (${BEACON_VERSION})`);
+    }
+    return providedValue;
+};
+//# sourceMappingURL=required-minimum-version.js.map

package/dist/esm/src/utils/required-minimum-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-minimum-version.js","sourceRoot":"","sources":["../../../../src/utils/required-minimum-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,kCAAkC,EAAE,MAAM,8CAA8C,CAAA;AACjG,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAA;AAEjF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,GAAG,CAAA;AAEnD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAC3C,aAAiC,EACzB,EAAE;IACV,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,gCAAgC,CAAA;IACzC,CAAC;IAED,2EAA2E;IAC3E,6EAA6E;IAC7E,4EAA4E;IAC5E,8EAA8E;IAC9E,2DAA2D;IAC3D,MAAM,MAAM,GAAG,yBAAyB,CAAC,aAAa,CAAC,CAAA;IACvD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,kCAAkC,CAC1C,aAAa,EACb,cAAc,EACd,wDAAwD,CACzD,CAAA;IACH,CAAC;IAED,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,kCAAkC,CAC1C,aAAa,EACb,cAAc,EACd,oBAAoB,CACrB,CAAA;IACH,CAAC;IAED,IAAI,oBAAoB,CAAC,aAAa,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,kCAAkC,CAC1C,aAAa,EACb,cAAc,EACd,qDAAqD,cAAc,GAAG,CACvE,CAAA;IACH,CAAC;IAED,OAAO,aAAa,CAAA;AACtB,CAAC,CAAA","sourcesContent":["import { BEACON_VERSION } from '../constants'\nimport { InvalidRequiredMinimumVersionError } from '../errors/InvalidRequiredMinimumVersionError'\nimport { compareBeaconVersion, parseStrictDecimalInteger } from './message-utils'\n\n/**\n * Default minimum wallet version the dApp accepts when the option is omitted.\n *\n * Deliberately the lowest protocol version still supported, so the gate is\n * effectively opt-in: by default every wallet the SDK can talk to (v2/v3/v4)\n * is accepted, preserving backward compatibility. A dApp that needs the v4\n * multi-network protocol sets `requiredMinimumVersion: '4'` explicitly.\n */\nexport const DEFAULT_REQUIRED_MINIMUM_VERSION = '2'\n\n/**\n * Resolve a dApp's `requiredMinimumVersion` option against the SDK's\n * `BEACON_VERSION`. Returns {@link DEFAULT_REQUIRED_MINIMUM_VERSION} when\n * undefined; otherwise validates the supplied value is a decimal-integer\n * string in `[1, BEACON_VERSION]` and returns it unchanged.\n *\n * Throws `InvalidRequiredMinimumVersionError` for any malformed,\n * out-of-range, or future-version input.\n */\nexport const resolveRequiredMinimumVersion = (\n  providedValue: string | undefined\n): string => {\n  if (providedValue === undefined) {\n    return DEFAULT_REQUIRED_MINIMUM_VERSION\n  }\n\n  // Validate against the SAME strict contract compareBeaconVersion enforces,\n  // up front, so every rejection here is an InvalidRequiredMinimumVersionError\n  // rather than a leaked InvalidBeaconVersionError from the comparison below.\n  // Reuse parseStrictDecimalInteger (the single owner of that contract) instead\n  // of re-declaring the regex + MAX_SAFE_INTEGER bound here.\n  const parsed = parseStrictDecimalInteger(providedValue)\n  if (parsed === null) {\n    throw new InvalidRequiredMinimumVersionError(\n      providedValue,\n      BEACON_VERSION,\n      'value must be a decimal-integer string (e.g. \"3\", \"4\")'\n    )\n  }\n\n  if (parsed < 1) {\n    throw new InvalidRequiredMinimumVersionError(\n      providedValue,\n      BEACON_VERSION,\n      'value must be >= 1'\n    )\n  }\n\n  if (compareBeaconVersion(providedValue, BEACON_VERSION) > 0) {\n    throw new InvalidRequiredMinimumVersionError(\n      providedValue,\n      BEACON_VERSION,\n      `value cannot exceed the SDK's own BEACON_VERSION (${BEACON_VERSION})`\n    )\n  }\n\n  return providedValue\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tezos-x/octez.connect-core",
-  "version": "5.0.0-beta.6",
+  "version": "5.0.1",
   "description": "This package contains internal methods that are used by both the dApp and wallet client.",
   "author": "Blockchain Infra <blockchain.infra@trili.tech>",
   "homepage": "https://octez-connect.tezos.com",
@@ -38,8 +38,8 @@
     "@stablelib/nacl": "^2.0.1",
     "@stablelib/utf8": "^2.1.0",
     "@stablelib/x25519-session": "^2.0.1",
-    "@tezos-x/octez.connect-types": "5.0.0-beta.6",
-    "@tezos-x/octez.connect-utils": "5.0.0-beta.6",
+    "@tezos-x/octez.connect-types": "5.0.1",
+    "@tezos-x/octez.connect-utils": "5.0.1",
     "broadcast-channel": "^7.3.0",
     "bs58check": "4.0.0"
   }