@tezos-x/octez.connect-dapp 5.0.0-beta.7 → 5.0.2

package/dist/cjs/dapp-client/DAppClientOptions.d.ts

@@ -130,16 +130,24 @@ export interface DAppClientOptions {
      */
     enableMetrics?: boolean;
     /**
-     * Minimum `peer.version` the dApp will accept from a wallet. The gate is
-     * opt-in: it defaults to the lowest supported protocol version, so every
-     * wallet the SDK can talk to is accepted and upgrading the SDK never
-     * rejects existing v2/v3 wallets. Set `'4'` to require the v4
-     * multi-network protocol. Must be a decimal-integer string in
-     * `[1, BEACON_VERSION]`; otherwise `InvalidRequiredMinimumVersionError` is
-     * thrown at construction. A wallet that reports a version below this minimum
-     * is rejected with `VersionUnsupportedBeaconError` when a request is sent
-     * (a wallet that reports no version at all is treated as unknown and
-     * allowed, so legacy pairings keep working).
+     * Minimum wallet version the dApp will accept. The gate is opt-in: it
+     * defaults to the lowest supported protocol version, so every wallet the
+     * SDK can talk to is accepted and upgrading the SDK never rejects existing
+     * v2/v3 wallets. Set `'4'` to require the v4 multi-network protocol. Must
+     * be a decimal-integer string in `[1, BEACON_VERSION]`; otherwise
+     * `InvalidRequiredMinimumVersionError` is thrown at construction. A wallet
+     * below this minimum is rejected with `VersionUnsupportedBeaconError` when
+     * a request is sent.
+     *
+     * The version compared against this minimum is the wallet's EFFECTIVE
+     * version, not the raw `peer.version`: legacy wallets echo the dApp's own
+     * version at pairing, so a declared version is only trusted when the
+     * pairing response carried the v5 `protocolVersion` capability marker —
+     * marker-less wallets that declared a version count as `'2'` (and are
+     * therefore rejected by a minimum of `'3'` or `'4'`, even though their
+     * echoed `peer.version` may read higher). A wallet that reports no version
+     * at all (WalletConnect pairings) is still treated as unknown and allowed,
+     * so those pairings keep working.
      */
     requiredMinimumVersion?: string;
 }

package/dist/cjs/dapp-client/DAppClientOptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"DAppClientOptions.js","sourceRoot":"","sources":["../../../src/dapp-client/DAppClientOptions.ts"],"names":[],"mappings":"","sourcesContent":["import { BeaconEvent, BeaconEventType, BeaconEventHandlerFunction } from '../events'\nimport { BlockExplorer } from '../utils/block-explorer'\nimport {\n  Storage,\n  NetworkType,\n  ColorMode,\n  NodeDistributions,\n  AnalyticsInterface,\n  Network\n} from '@tezos-x/octez.connect-types'\n\ntype RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> &\n  {\n    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>\n  }[Keys]\n\n/**\n * @category DApp\n */\nexport interface DAppClientOptions {\n  /**\n   * Name of the application\n   */\n  name: string\n\n  /**\n   * Description of the application\n   */\n  description?: string\n\n  /**\n   * A URL to the icon of the application\n   */\n  iconUrl?: string\n\n  /**\n   * A URL to the website of the application\n   */\n  appUrl?: string\n\n  /**\n   * The storage that will be used by the SDK\n   */\n  storage?: Storage\n\n  /**\n   * An object that will be used to overwrite default event handler behaviour.\n   *\n   * If you plan to overwrite all default events, use \"disableDefaultEvents\" instead.\n   *\n   * This will overwrite the default event handler, so this can lead to unexpected behavior in some cases.\n   * We recommend that you overwrite all handlers if you want to use your own UI.\n   *\n   * If you simply want to be notified of events happening, but do not want to overwrite the default behavior,\n   * please use `subscribeToEvent()` on the DAppClient instead.\n   */\n  eventHandlers?: {\n    [key in BeaconEvent]?: {\n      handler: BeaconEventHandlerFunction<BeaconEventType[key]>\n    }\n  }\n\n  /**\n   * Disable all default Events and UI elements. If passed together with \"eventHandlers\",\n   * the default eventHandlers will be removed, and the ones passed by the user will be added.\n   */\n  disableDefaultEvents?: boolean\n\n  /**\n   * A list of matrix nodes to connect to. If a non-empty array is passed, the default options will be overwritten.\n   * One node will be randomly selected based on the local keypair and the other nodes will be used as a fallback in case the primary node goes down.\n   *\n   * Only provide the hostname, no https:// prefix. Eg. { [Regions.EU1]: ['matrix.example.com'] }\n   */\n  matrixNodes?: NodeDistributions\n\n  /**\n   * The block explorer used by the SDK\n   */\n  blockExplorer?: BlockExplorer\n\n  /**\n   * Indicates on which network the DApp is running on.\n   */\n  network?: Network\n\n  /**\n   * @deprecated Please use \"network\" instead.\n   * Indicates on which network the DApp is planning to run. This is currently used to adjust the URLs of web-wallets in the pairing alert if they use different URLs for testnets.\n   * You will still have to define the network you intend to use during the permission request.\n   */\n  preferredNetwork?: NetworkType\n\n  /**\n   * Set the color mode for the UI elements (alerts and toasts)\n   */\n  colorMode?: ColorMode\n\n  /**\n   * A URL to the Terms & Conditions page that will be displayed in the pairing modal\n   */\n  termsAndConditionsUrl?: string\n\n  /**\n   * A URL to the Privacy Policy page that will be displayed in the pairing modal\n   */\n  privacyPolicyUrl?: string\n\n  /**\n   * A list of contracts that the DApp is using. Allows to attach human readable error messages for to error codes\n   */\n  errorMessages?: Record<string, Record<string | number, string>>\n\n  /**\n   * Configuration that is passed to the WalletConnect transport.\n   *\n   * This is required to enable WalletConnect connections.\n   */\n  walletConnectOptions?: RequireAtLeastOne<{\n    /**\n     * The projectId of the application. Has to be obtained from https://cloud.walletconnect.com/\n     */\n    projectId?: string\n\n    /**\n     * The relay server to connect to\n     */\n    relayUrl?: string\n  }>\n\n  /**\n   * Explicitly disable the WalletConnect transport.\n   *\n   * WalletConnect is opt-in (it is only built when `walletConnectOptions` is\n   * provided). This additive flag lets a DApp that does provide\n   * `walletConnectOptions` still turn the transport off without removing that\n   * configuration. When `true`, no WalletConnect transport is constructed or\n   * listened to. Absence preserves current behavior. Use it for environments\n   * where the WalletConnect provider cannot run (e.g. a Firefox MV3\n   * content-script compartment).\n   */\n  disableWalletConnect?: boolean\n\n  /**\n   * The analytics instance that will be used by the SDK\n   */\n  analytics?: AnalyticsInterface\n\n  /**\n   * The wallets that will be featured in the UI.\n   */\n  featuredWallets?: string[]\n\n  /**\n   * Automatically switch between apps on Mobile Devices (Enabled by Default)\n   */\n  enableAppSwitching?: boolean\n\n  /**\n   * Enable metrics tracking (Disabled by Default)\n   */\n  enableMetrics?: boolean\n\n  /**\n   * Minimum `peer.version` the dApp will accept from a wallet. The gate is\n   * opt-in: it defaults to the lowest supported protocol version, so every\n   * wallet the SDK can talk to is accepted and upgrading the SDK never\n   * rejects existing v2/v3 wallets. Set `'4'` to require the v4\n   * multi-network protocol. Must be a decimal-integer string in\n   * `[1, BEACON_VERSION]`; otherwise `InvalidRequiredMinimumVersionError` is\n   * thrown at construction. A wallet that reports a version below this minimum\n   * is rejected with `VersionUnsupportedBeaconError` when a request is sent\n   * (a wallet that reports no version at all is treated as unknown and\n   * allowed, so legacy pairings keep working).\n   */\n  requiredMinimumVersion?: string\n}\n"]}
+{"version":3,"file":"DAppClientOptions.js","sourceRoot":"","sources":["../../../src/dapp-client/DAppClientOptions.ts"],"names":[],"mappings":"","sourcesContent":["import { BeaconEvent, BeaconEventType, BeaconEventHandlerFunction } from '../events'\nimport { BlockExplorer } from '../utils/block-explorer'\nimport {\n  Storage,\n  NetworkType,\n  ColorMode,\n  NodeDistributions,\n  AnalyticsInterface,\n  Network\n} from '@tezos-x/octez.connect-types'\n\ntype RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> &\n  {\n    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>\n  }[Keys]\n\n/**\n * @category DApp\n */\nexport interface DAppClientOptions {\n  /**\n   * Name of the application\n   */\n  name: string\n\n  /**\n   * Description of the application\n   */\n  description?: string\n\n  /**\n   * A URL to the icon of the application\n   */\n  iconUrl?: string\n\n  /**\n   * A URL to the website of the application\n   */\n  appUrl?: string\n\n  /**\n   * The storage that will be used by the SDK\n   */\n  storage?: Storage\n\n  /**\n   * An object that will be used to overwrite default event handler behaviour.\n   *\n   * If you plan to overwrite all default events, use \"disableDefaultEvents\" instead.\n   *\n   * This will overwrite the default event handler, so this can lead to unexpected behavior in some cases.\n   * We recommend that you overwrite all handlers if you want to use your own UI.\n   *\n   * If you simply want to be notified of events happening, but do not want to overwrite the default behavior,\n   * please use `subscribeToEvent()` on the DAppClient instead.\n   */\n  eventHandlers?: {\n    [key in BeaconEvent]?: {\n      handler: BeaconEventHandlerFunction<BeaconEventType[key]>\n    }\n  }\n\n  /**\n   * Disable all default Events and UI elements. If passed together with \"eventHandlers\",\n   * the default eventHandlers will be removed, and the ones passed by the user will be added.\n   */\n  disableDefaultEvents?: boolean\n\n  /**\n   * A list of matrix nodes to connect to. If a non-empty array is passed, the default options will be overwritten.\n   * One node will be randomly selected based on the local keypair and the other nodes will be used as a fallback in case the primary node goes down.\n   *\n   * Only provide the hostname, no https:// prefix. Eg. { [Regions.EU1]: ['matrix.example.com'] }\n   */\n  matrixNodes?: NodeDistributions\n\n  /**\n   * The block explorer used by the SDK\n   */\n  blockExplorer?: BlockExplorer\n\n  /**\n   * Indicates on which network the DApp is running on.\n   */\n  network?: Network\n\n  /**\n   * @deprecated Please use \"network\" instead.\n   * Indicates on which network the DApp is planning to run. This is currently used to adjust the URLs of web-wallets in the pairing alert if they use different URLs for testnets.\n   * You will still have to define the network you intend to use during the permission request.\n   */\n  preferredNetwork?: NetworkType\n\n  /**\n   * Set the color mode for the UI elements (alerts and toasts)\n   */\n  colorMode?: ColorMode\n\n  /**\n   * A URL to the Terms & Conditions page that will be displayed in the pairing modal\n   */\n  termsAndConditionsUrl?: string\n\n  /**\n   * A URL to the Privacy Policy page that will be displayed in the pairing modal\n   */\n  privacyPolicyUrl?: string\n\n  /**\n   * A list of contracts that the DApp is using. Allows to attach human readable error messages for to error codes\n   */\n  errorMessages?: Record<string, Record<string | number, string>>\n\n  /**\n   * Configuration that is passed to the WalletConnect transport.\n   *\n   * This is required to enable WalletConnect connections.\n   */\n  walletConnectOptions?: RequireAtLeastOne<{\n    /**\n     * The projectId of the application. Has to be obtained from https://cloud.walletconnect.com/\n     */\n    projectId?: string\n\n    /**\n     * The relay server to connect to\n     */\n    relayUrl?: string\n  }>\n\n  /**\n   * Explicitly disable the WalletConnect transport.\n   *\n   * WalletConnect is opt-in (it is only built when `walletConnectOptions` is\n   * provided). This additive flag lets a DApp that does provide\n   * `walletConnectOptions` still turn the transport off without removing that\n   * configuration. When `true`, no WalletConnect transport is constructed or\n   * listened to. Absence preserves current behavior. Use it for environments\n   * where the WalletConnect provider cannot run (e.g. a Firefox MV3\n   * content-script compartment).\n   */\n  disableWalletConnect?: boolean\n\n  /**\n   * The analytics instance that will be used by the SDK\n   */\n  analytics?: AnalyticsInterface\n\n  /**\n   * The wallets that will be featured in the UI.\n   */\n  featuredWallets?: string[]\n\n  /**\n   * Automatically switch between apps on Mobile Devices (Enabled by Default)\n   */\n  enableAppSwitching?: boolean\n\n  /**\n   * Enable metrics tracking (Disabled by Default)\n   */\n  enableMetrics?: boolean\n\n  /**\n   * Minimum wallet version the dApp will accept. The gate is opt-in: it\n   * defaults to the lowest supported protocol version, so every wallet the\n   * SDK can talk to is accepted and upgrading the SDK never rejects existing\n   * v2/v3 wallets. Set `'4'` to require the v4 multi-network protocol. Must\n   * be a decimal-integer string in `[1, BEACON_VERSION]`; otherwise\n   * `InvalidRequiredMinimumVersionError` is thrown at construction. A wallet\n   * below this minimum is rejected with `VersionUnsupportedBeaconError` when\n   * a request is sent.\n   *\n   * The version compared against this minimum is the wallet's EFFECTIVE\n   * version, not the raw `peer.version`: legacy wallets echo the dApp's own\n   * version at pairing, so a declared version is only trusted when the\n   * pairing response carried the v5 `protocolVersion` capability marker —\n   * marker-less wallets that declared a version count as `'2'` (and are\n   * therefore rejected by a minimum of `'3'` or `'4'`, even though their\n   * echoed `peer.version` may read higher). A wallet that reports no version\n   * at all (WalletConnect pairings) is still treated as unknown and allowed,\n   * so those pairings keep working.\n   */\n  requiredMinimumVersion?: string\n}\n"]}

package/dist/esm/dapp-client/DAppClient.js

@@ -1,6 +1,6 @@
 import bs58check from 'bs58check';
 import { TransportType, StorageKey, BeaconMessageType, PermissionScope, NetworkType, Origin, BeaconErrorType, SigningType, ColorMode, TransportStatus } from '@tezos-x/octez.connect-types';
-import { Client, AppMetadataManager, Serializer, LocalStorage, getAccountIdentifier, getSenderId, Logger, StorageValidator, SDK_VERSION, IndexedDBStorage, MultiTabChannel, BACKEND_URL, getError, usesWrappedMessages, buildErrorContext, UnknownBeaconError, AbortedBeaconError, compareBeaconVersion, isMultiNetworkVersion, VersionUnsupportedBeaconError, NetworksUnsupportedBeaconError, normalizeTezosCaip2, isValidTezosCaip2, networkFromTezosCaip2, networkTypeFromTezosCaip2, resolveRequiredMinimumVersion, negotiateEnvelopeVersion, wrapBeaconMessage } from '@tezos-x/octez.connect-core';
+import { Client, AppMetadataManager, Serializer, LocalStorage, getAccountIdentifier, getSenderId, Logger, StorageValidator, SDK_VERSION, IndexedDBStorage, MultiTabChannel, BACKEND_URL, getError, usesWrappedMessages, buildErrorContext, UnknownBeaconError, AbortedBeaconError, compareBeaconVersion, isMultiNetworkVersion, VersionUnsupportedBeaconError, NetworksUnsupportedBeaconError, normalizeTezosCaip2, isValidTezosCaip2, networkFromTezosCaip2, networkTypeFromTezosCaip2, resolveRequiredMinimumVersion, negotiateEnvelopeVersion, effectivePeerVersion, MESSAGE_WRAPPED_FROM_VERSION, wrapBeaconMessage } from '@tezos-x/octez.connect-core';
 import { TezosBlockchain } from '@tezos-x/octez.connect-blockchain-tezos';
 import { getAddressFromPublicKey, ExposedPromise, generateGUID, toHex, signMessage, CONTRACT_PREFIX, prefixPublicKey, isValidAddress, getKeypairFromSeed } from '@tezos-x/octez.connect-utils';
 import { PostMessageTransport } from '@tezos-x/octez.connect-transport-postmessage';
@@ -1121,7 +1121,7 @@ export class DAppClient extends Client {
         // reading response.message.version would always miss and collapse to '0',
         // misrouting v4 responses when no peer is persisted yet.
         const walletPeerV3 = await this.getPeer();
-        const walletPeerVersionV3 = walletPeerV3?.version ?? response.version;
+        const walletPeerVersionV3 = effectivePeerVersion(walletPeerV3) ?? response.version;
         const partialAccountInfos = await blockchain.getAccountInfosFromPermissionResponse(response.message, walletPeerVersionV3);
         const blockchainDataScopes = response.message.blockchainData.scopes;
         const accountInfos = partialAccountInfos.map((p) => ({
@@ -1268,10 +1268,11 @@ export class DAppClient extends Client {
         this.sendMetrics('performance-metrics/save', await this.buildPayload('connect', 'success'));
         logger.log('requestPermissions', '######## MESSAGE #######');
         logger.log('requestPermissions', message);
-        // walletPeer.version is the negotiated pairing version; fall back to the
-        // response envelope version when no peer is persisted yet.
+        // Capability-aware peer version (legacy wallets echo the dApp's version
+        // at pairing — see effectivePeerVersion); fall back to the response
+        // envelope version when no peer is persisted yet.
         const walletPeer = await this.getPeer();
-        const walletPeerVersion = walletPeer?.version ?? message.version;
+        const walletPeerVersion = effectivePeerVersion(walletPeer) ?? message.version;
         // Gate the freshly-paired wallet against the dApp's required minimum (a
         // no-op under the default, permissive minimum). Throws
         // VersionUnsupportedBeaconError when the wallet is too old.
@@ -1861,10 +1862,15 @@ export class DAppClient extends Client {
         return walletInfo;
     }
     // Throws VersionUnsupportedBeaconError when a wallet that reported a version
-    // is below requiredMinimumVersion (or reports a malformed one). A peer that
-    // never reported a version (legacy pairing predating versioning) is treated
-    // as unknown and allowed through, so raising the minimum never retroactively
-    // breaks an already-paired session on a pure read.
+    // is below requiredMinimumVersion (or reports a malformed one). Callers pass
+    // the EFFECTIVE version (see effectivePeerVersion): a declared version is
+    // only trusted alongside the v5 `protocolVersion` pairing marker; a
+    // marker-less wallet that declared one counts as '2' (legacy wallets echo
+    // the dApp's version, so the raw peer.version may read deceptively high).
+    // A peer that never reported a version (WalletConnect pairings, legacy
+    // pairings predating versioning) is treated as unknown and allowed through,
+    // so raising the minimum never retroactively breaks an already-paired
+    // session on a pure read.
     assertWalletVersionMeetsMinimum(walletVersion) {
         if (walletVersion === undefined) {
             return;
@@ -2107,13 +2113,16 @@ export class DAppClient extends Client {
         // Enforce the dApp's required minimum before a request leaves the SDK.
         // No-op under the default (permissive) minimum; otherwise rejects an
         // under-minimum wallet with VersionUnsupportedBeaconError.
-        this.assertWalletVersionMeetsMinimum(peer?.version);
-        // The wire dialect is negotiated per peer — min(peer.version,
-        // BEACON_VERSION), floor '2'. A wrapped-capable peer (>= 3) receives the
-        // flat requestInput (the unchanged public shape) mapped onto the wrapped
-        // Tezos payload; a legacy peer receives the flat v2 message it has
-        // always spoken. Integrators never see either dialect.
-        const negotiatedVersion = negotiateEnvelopeVersion(peer?.version);
+        this.assertWalletVersionMeetsMinimum(effectivePeerVersion(peer));
+        // The wire dialect is negotiated per peer — min(effective peer version,
+        // BEACON_VERSION), floor '2'. The effective version is capability-aware:
+        // legacy wallets ECHO the dApp's version in their pairing response, so
+        // peer.version alone would misread a 4.8.x wallet as v4; only peers that
+        // sent the v5 `protocolVersion` marker are trusted. A wrapped-capable
+        // peer receives the flat requestInput (the unchanged public shape)
+        // mapped onto the wrapped Tezos payload; a legacy peer receives the flat
+        // v2 message it has always spoken. Integrators never see either dialect.
+        const negotiatedVersion = negotiateEnvelopeVersion(effectivePeerVersion(peer));
         const requestSenderId = await getSenderId(await this.beaconId);
         let request;
         if (usesWrappedMessages(negotiatedVersion)) {
@@ -2223,14 +2232,21 @@ export class DAppClient extends Client {
         const account = await this.getActiveAccount();
         const peer = await this.getPeer(account);
         // Enforce the dApp's required minimum before a request leaves the SDK.
-        this.assertWalletVersionMeetsMinimum(peer?.version);
+        this.assertWalletVersionMeetsMinimum(effectivePeerVersion(peer));
+        // The envelope carries the version negotiated against the effective
+        // (capability-aware) peer version — see effectivePeerVersion: legacy
+        // wallets echo the dApp's version, so only peers that sent the v5
+        // `protocolVersion` marker are trusted with the v4 dialect. Unlike
+        // makeRequest, this path is wrapper-only (the v3 blockchainData shape
+        // has no flat equivalent), so it floors at '3' instead of '2': a legacy
+        // wallet routes a version-'3' wrapper through its v3 branch, whereas a
+        // '2'-stamped wrapper would be misrouted as flat and silently dropped.
+        const negotiatedVersion = negotiateEnvelopeVersion(effectivePeerVersion(peer));
         const request = {
             id: messageId,
-            // The envelope carries the version negotiated against the peer:
-            // min(peer.version, BEACON_VERSION), floor '3'. A v3 wallet treats any
-            // version >= 3 as a wrapped message; a v4 wallet reaches its
-            // multi-network branch only when it declared v4 at pairing.
-            version: negotiateEnvelopeVersion(peer?.version),
+            version: usesWrappedMessages(negotiatedVersion)
+                ? negotiatedVersion
+                : String(MESSAGE_WRAPPED_FROM_VERSION),
             senderId: await getSenderId(await this.beaconId),
             message: requestInput
         };