phantasma-sdk-ts 0.9.2 → 0.10.0

package/README.md

@@ -41,6 +41,12 @@ import { Transaction } from 'phantasma-sdk-ts/core/tx/Transaction';
 
 Those compatibility paths are deprecated. New code should use `/public` or the lowercase module paths shown above.
 
+## Phantasma Link v5 protocol
+
+The dApp↔wallet connection protocol (envelope, transports, pairing, sessions, encryption)
+is specified in [`spec/phantasma-link-v5.md`](spec/phantasma-link-v5.md). This package is
+its reference implementation, exposed under the `phantasma-sdk-ts/link/v5` entry point.
+
 ## RPC Example
 
 ```ts

package/dist/cjs/index.js

@@ -36,11 +36,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EasyConnect = exports.PhantasmaLink = exports.PhantasmaTS = void 0;
+exports.PhantasmaLinkV5 = exports.EasyConnect = exports.PhantasmaLink = exports.PhantasmaTS = void 0;
 __exportStar(require("./core/index.js"), exports);
 exports.PhantasmaTS = __importStar(require("./core/index.js"));
 var phantasma_link_js_1 = require("./link/phantasma-link.js");
 Object.defineProperty(exports, "PhantasmaLink", { enumerable: true, get: function () { return phantasma_link_js_1.PhantasmaLink; } });
 var easy_connect_js_1 = require("./link/easy-connect.js");
 Object.defineProperty(exports, "EasyConnect", { enumerable: true, get: function () { return easy_connect_js_1.EasyConnect; } });
+// Phantasma Link v5 (new generation), namespaced to avoid flat-name collisions.
+exports.PhantasmaLinkV5 = __importStar(require("./link/v5/index.js"));
 //const TransportWebUSB = require('@ledgerhq/hw-transport-webusb').default;

package/dist/cjs/link/index.js

@@ -15,3 +15,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./interfaces/index.js"), exports);
+// Phantasma Link v5 (new generation; parallel to the legacy v1–v4 `PhantasmaLink`).
+// NOT re-exported flatly here: v5 defines its own `SignatureKind` (string union) that
+// would clash with the contract `SignatureKind` enum aggregated by `src/core/index.ts`.
+// Import v5 via the `phantasma-sdk-ts/link/v5` subpath or the `PhantasmaLinkV5` namespace
+// (exported from the package root and `phantasma-sdk-ts/public`).

package/dist/cjs/link/v5/capabilities.js

@@ -0,0 +1,6 @@
+"use strict";
+// Phantasma Link v5 - capability handshake + session/account/chain types (spec §5, §7, §9).
+// Capability negotiation replaces the v1-v4 "magic version int": a dApp learns up front
+// which methods, chains, tx formats, signature kinds, and payload sizes the wallet
+// supports, instead of guessing from a single number.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/link/v5/client.js

@@ -0,0 +1,324 @@
+"use strict";
+// Phantasma Link v5 - the cohesive client (spec §6/§9). This IS the v5 entry point: there is
+// NO separate "EasyConnect"-style wrapper. Transport selection, the connect handshake, and the
+// typed `pha_*` methods are all part of this one client. Build it directly with any transport,
+// or use the `loopback()` factory for the desktop case.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PhantasmaLink5 = void 0;
+const protocol_js_1 = require("./protocol.js");
+const transport_js_1 = require("./transport.js");
+const loopback_transport_js_1 = require("./loopback-transport.js");
+const deeplink_js_1 = require("./deeplink.js");
+const relay_transport_js_1 = require("./relay-transport.js");
+const errors_js_1 = require("./errors.js");
+const pairing_js_1 = require("./pairing.js");
+const encoding_js_1 = require("./encoding.js");
+const web_deeplink_js_1 = require("./web-deeplink.js");
+const session_crypto_js_1 = require("./session-crypto.js");
+/**
+ * The v5 client. `connect()` runs the capability handshake and stores the session; the typed
+ * methods then forward to the wallet and return validated-by-contract results. Events
+ * (account/chain/session changes) are delivered via {@link onEvent}.
+ */
+class PhantasmaLink5 {
+    constructor(transport, options = {}) {
+        // Cleanup callbacks registered by factories (e.g. the web-deeplink URL listener);
+        // run once on close() so a discarded client does not keep page hooks alive.
+        this.disposers = [];
+        this.transport = transport;
+        // Capture responses that arrive with no in-flight request (the deeplink page reloaded
+        // mid-flow). The web-deeplink factory delivers any such response during construction, so a
+        // caller can recover it via takeUnmatchedResponse() right after building the client.
+        this.session = new transport_js_1.LinkSessionClient(transport, {
+            ...options,
+            onUnmatchedResponse: (response) => {
+                this.lastUnmatched = response;
+            },
+        });
+        this.defaultDapp = options.dapp;
+        this.onSessionChange = options.onSessionChange;
+        // One-tap pairing (spec §15 step 3): the wallet may push the connect result as an
+        // unsolicited event right after the pairing approval, instead of waiting for an
+        // explicit pha_connect. Adopt it exactly like a connect result so the session is
+        // live (and persisted via onSessionChange) the moment the event arrives.
+        this.session.onEvent((event, data) => {
+            if (event === protocol_js_1.LinkEvent.SessionEstablished && isConnectResult(data)) {
+                this.adoptConnectResult(data);
+            }
+        });
+    }
+    /** Build a client over the desktop loopback transport (plaintext, trusted-local). */
+    static loopback(options = {}) {
+        return new PhantasmaLink5(new loopback_transport_js_1.LoopbackTransport(options));
+    }
+    /** Build a client over the deeplink transport (spec §17). The channel key from pairing is
+     * MANDATORY here: deeplink URLs are interceptable, so plaintext frames are never allowed. */
+    static deeplink(options) {
+        if (!options.sessionKey || options.sessionKey.length !== 32) {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidParams, 'Deeplink requires the 32-byte pairing session key');
+        }
+        return new PhantasmaLink5(new deeplink_js_1.DeeplinkTransport(options), {
+            sessionKey: options.sessionKey,
+            // Deeplink round-trips include an app switch + human consent; see the constant.
+            requestTimeoutMs: options.requestTimeoutMs ?? deeplink_js_1.DEEPLINK_REQUEST_TIMEOUT_MS,
+        });
+    }
+    /** Build a client over the relay transport (spec §6.4/§16). The channel key from
+     * pairing is MANDATORY: relay payloads are ALWAYS encrypted (spec §8) - the relay is
+     * E2E-blind and must stay that way. */
+    static relay(options) {
+        if (!options.sessionKey || options.sessionKey.length !== 32) {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidParams, 'Relay requires the 32-byte pairing session key');
+        }
+        return new PhantasmaLink5(new relay_transport_js_1.RelayTransport(options), {
+            sessionKey: options.sessionKey,
+            // Relay round-trips include human consents too; same generous default.
+            requestTimeoutMs: options.requestTimeoutMs ?? deeplink_js_1.DEEPLINK_REQUEST_TIMEOUT_MS,
+        });
+    }
+    /**
+     * Build a client for the ecdh pairing fallback (spec §15/§18.1): the custom-scheme
+     * channel is hijackable, so NO secret rides the pairing URI - only the dApp's
+     * ephemeral X25519 PUBLIC key. The wallet answers over the relay with its own public
+     * key plus the sealed connect result; the session key is derived on arrival and the
+     * client refuses to send (or accept) anything before that. Show {@link pairingUri}
+     * (a phantasma:// URI) to start; the session then arrives one-tap.
+     */
+    static relayEcdh(options) {
+        const topic = options.topic ?? (0, session_crypto_js_1.randomToken)(32);
+        const pair = options.keyPair ?? (0, session_crypto_js_1.generateEphemeralKeyPair)();
+        const relayUrl = options.url ?? relay_transport_js_1.DEFAULT_RELAY_URL;
+        const transport = new relay_transport_js_1.RelayTransport({
+            ...options,
+            topic,
+            url: relayUrl,
+            onWalletKey: (publicKeyB64Url) => {
+                // Fires only when the wallet's hop arrives, long after `client` below exists.
+                const walletPublicKey = (0, encoding_js_1.base64UrlToBytes)(publicKeyB64Url);
+                client.session.setSessionKey((0, session_crypto_js_1.deriveSessionKey)(walletPublicKey, pair.secretKey));
+            },
+        });
+        const client = new PhantasmaLink5(transport, {
+            dapp: options.dapp,
+            requireSessionKey: true,
+            requestTimeoutMs: options.requestTimeoutMs ?? deeplink_js_1.DEEPLINK_REQUEST_TIMEOUT_MS,
+        });
+        client.pairingUriValue = (0, pairing_js_1.buildPairingUri)({
+            topic,
+            mode: 'ecdh',
+            dappPublicKey: pair.publicKey,
+            relay: relayUrl,
+            meta: options.dapp,
+            // The whole point of ecdh is the hijackable custom scheme; a safe channel
+            // (universal link / QR) should use the simpler sym mode instead.
+            scheme: 'scheme',
+        });
+        return client;
+    }
+    /**
+     * Build a ready-to-use client for a WEB dApp over the deeplink transport (spec §17),
+     * bundling the per-dApp glue: pairing material generation, the pairing URI, persistence
+     * (localStorage by default), restore + session resume across page loads, and intake of
+     * the response URLs the wallet opens back at the page (initial URL + `hashchange`).
+     *
+     * The factory itself never opens a URL: mobile browsers only allow app-opening
+     * navigation from a user gesture. The dApp drives the hops - show {@link pairingUri}
+     * (link/QR) for the one-time pairing consent, then call {@link connect} and the typed
+     * methods from click handlers; an established session resumes promptlessly (spec §7).
+     */
+    static async webDeeplink(options) {
+        const hooks = (0, web_deeplink_js_1.resolveWebDeeplinkHooks)(options);
+        let record = (0, web_deeplink_js_1.loadWebDeeplinkRecord)(hooks.storage, hooks.storageKey);
+        if (!record) {
+            // Persist BEFORE any URL hop: opening the wallet may unload this page, and the
+            // pairing key must already be on disk to decrypt responses after it comes back.
+            record = (0, web_deeplink_js_1.createWebDeeplinkRecord)(options.callback ?? (0, web_deeplink_js_1.stripUrlFragment)(hooks.pageUrl()));
+            (0, web_deeplink_js_1.saveWebDeeplinkRecord)(hooks.storage, hooks.storageKey, record);
+        }
+        // The record is the source of truth from here on (a snapshot for the closures below).
+        const stored = record;
+        const sessionKey = (0, encoding_js_1.base64UrlToBytes)(stored.key);
+        const client = new PhantasmaLink5(new deeplink_js_1.DeeplinkTransport({
+            topic: stored.topic,
+            opener: hooks.opener,
+            walletBase: options.walletBase,
+        }), {
+            dapp: options.dapp,
+            sessionKey,
+            sessionId: stored.sessionId,
+            requestTimeoutMs: options.requestTimeoutMs ?? deeplink_js_1.DEEPLINK_REQUEST_TIMEOUT_MS,
+            onSessionChange: (connect) => {
+                // Session layer only - the pairing material stays valid across disconnects.
+                stored.sessionId = connect?.session.id;
+                stored.lastConnect = connect;
+                (0, web_deeplink_js_1.saveWebDeeplinkRecord)(hooks.storage, hooks.storageKey, stored);
+            },
+        });
+        // The pairing URI is always available (idempotent to re-show); `sym` requires the
+        // domain-verified universal link - a symmetric key never rides a custom scheme (§15).
+        client.pairingUriValue = (0, pairing_js_1.buildPairingUri)({
+            topic: stored.topic,
+            mode: 'sym',
+            symKey: sessionKey,
+            callback: stored.callback,
+            meta: options.dapp,
+            scheme: 'universal',
+            host: options.host,
+        });
+        // Hop-free hydration: a reloaded page shows the cached account immediately; the next
+        // real request (or a connect()) proves liveness and refreshes it.
+        client.lastConnect = stored.lastConnect;
+        const consumePageUrl = () => {
+            const href = hooks.pageUrl();
+            if (client.deliverUrl(href)) {
+                // Drop the consumed fragment so reload/back cannot re-deliver it and the
+                // ciphertext does not linger in the address bar (or get copied with the URL).
+                hooks.replaceUrl?.((0, web_deeplink_js_1.stripUrlFragment)(href));
+            }
+        };
+        // A response may already sit in the page URL (the wallet's callback navigation
+        // cold-loaded this page); consume it before subscribing to changes.
+        consumePageUrl();
+        const unsubscribe = hooks.onUrlChange?.(consumePageUrl);
+        if (unsubscribe) {
+            client.disposers.push(unsubscribe);
+        }
+        return client;
+    }
+    /** Feed an OS-delivered URL into a deeplink-backed client; see DeeplinkTransport.deliverUrl.
+     * The web-deeplink factory wires this automatically; SPAs whose routing swallows
+     * `hashchange` call it explicitly on route events. */
+    deliverUrl(url) {
+        return this.transport instanceof deeplink_js_1.DeeplinkTransport && this.transport.deliverUrl(url);
+    }
+    /** Take (and clear) a wallet response that arrived with no in-flight request to match it -
+     * the deeplink reload case, where the page that issued the request was discarded before the
+     * answer returned. The web-deeplink factory delivers it during construction, so read it right
+     * after building the client. Returns undefined when there is nothing to recover. */
+    takeUnmatchedResponse() {
+        const response = this.lastUnmatched;
+        this.lastUnmatched = undefined;
+        return response;
+    }
+    /** The pairing URI for this client's channel (set by pairing-capable factories such as
+     * {@link webDeeplink}); render it as a link/QR for the one-time wallet pairing consent. */
+    get pairingUri() {
+        return this.pairingUriValue;
+    }
+    /** The account from the last successful {@link connect}, if any. */
+    get account() {
+        return this.lastConnect?.account;
+    }
+    /** The capabilities granted at the last successful {@link connect}, if any. */
+    get capabilities() {
+        return this.lastConnect?.capabilities;
+    }
+    /** Pair/resume and run the capability handshake. The wallet MAY grant a subset of the
+     * requested capabilities; inspect the returned {@link ConnectResult}. `dapp` falls back
+     * to `options.dapp` (factories set it), so a configured client connects with no args. */
+    async connect(dapp, extra = {}) {
+        const identity = dapp ?? this.defaultDapp;
+        if (!identity) {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidParams, 'connect() needs dApp metadata: pass it here or set options.dapp');
+        }
+        const params = { dapp: identity, ...extra };
+        // Default to resuming the current session (spec §7). Always safe: a matching wallet
+        // resumes promptlessly, any mismatch silently falls back to a fresh consent prompt.
+        if (params.session === undefined && this.session.getSessionId() !== undefined) {
+            params.session = this.session.getSessionId();
+        }
+        const result = await this.request(protocol_js_1.LinkMethod.Connect, params);
+        this.adoptConnectResult(result);
+        return result;
+    }
+    /** Make a connect result the live session state (used by both the explicit connect and
+     * the wallet-pushed {@link LinkEvent.SessionEstablished} one-tap pairing path). */
+    adoptConnectResult(result) {
+        this.lastConnect = result;
+        this.session.setSessionId(result.session.id);
+        this.onSessionChange?.(result);
+    }
+    getAccounts() {
+        return this.request(protocol_js_1.LinkMethod.GetAccounts);
+    }
+    getChains() {
+        return this.request(protocol_js_1.LinkMethod.GetChains);
+    }
+    getWalletInfo() {
+        return this.request(protocol_js_1.LinkMethod.GetWalletInfo);
+    }
+    signMessage(params) {
+        return this.request(protocol_js_1.LinkMethod.SignMessage, params);
+    }
+    /** Sign a transaction without broadcasting; the dApp submits the returned signed tx. */
+    signTransaction(params) {
+        return this.request(protocol_js_1.LinkMethod.SignTransaction, params);
+    }
+    /** Sign AND broadcast a transaction via the format's RPC endpoint. */
+    sendTransaction(params) {
+        return this.request(protocol_js_1.LinkMethod.SendTransaction, params);
+    }
+    /** Read-only VM invoke (no keys, no approval). */
+    invokeScript(params) {
+        return this.request(protocol_js_1.LinkMethod.InvokeScript, params);
+    }
+    async disconnect() {
+        const result = await this.request(protocol_js_1.LinkMethod.Disconnect);
+        // The wallet dropped the session; clear local state so later requests do not carry a
+        // dead session id (and embedders can erase their persisted copy).
+        this.lastConnect = undefined;
+        this.session.setSessionId(undefined);
+        this.onSessionChange?.(undefined);
+        return result;
+    }
+    /** Drop the local (and persisted) session WITHOUT notifying the wallet. Use when a wallet
+     * round-trip is undesirable - notably deeplink, where pha_disconnect would navigate to the
+     * wallet and reload this page, so the cleanup after the request never runs and the session
+     * would resume on the next load. The wallet's side lapses on its own session TTL (spec §7). */
+    forgetSession() {
+        this.lastConnect = undefined;
+        this.session.setSessionId(undefined);
+        this.onSessionChange?.(undefined);
+    }
+    /** Subscribe to wallet->dApp events; returns an unsubscribe function. */
+    onEvent(handler) {
+        return this.session.onEvent(handler);
+    }
+    /** Close the underlying transport and reject any in-flight requests. */
+    close() {
+        // Release factory-registered hooks first (e.g. the web page-URL listener) so nothing
+        // can deliver into a closing client; disposers must never block the close itself.
+        for (const dispose of this.disposers.splice(0)) {
+            try {
+                dispose();
+            }
+            catch {
+                // A failing disposer must not prevent the transport from closing.
+            }
+        }
+        this.session.close();
+    }
+    // The wallet's result is `unknown` on the wire; we cast to the method's contract type. The
+    // shapes are validated structurally at the envelope layer (§4); per-field validation can be
+    // layered on later without changing call sites. `params` is `object` so typed param
+    // interfaces (which lack an index signature) are accepted, then forwarded as a plain record.
+    request(method, params) {
+        return this.session.request(method, params);
+    }
+}
+exports.PhantasmaLink5 = PhantasmaLink5;
+/** Structural check for a wallet-pushed connect result before adopting it as session state.
+ * The frame already authenticated via the channel key, so this guards against a malformed
+ * wallet payload, not an attacker; only the fields the client dereferences are checked. */
+function isConnectResult(data) {
+    if (!data || typeof data !== 'object') {
+        return false;
+    }
+    const record = data;
+    return (typeof record.session === 'object' &&
+        record.session !== null &&
+        typeof record.session.id === 'string' &&
+        record.session.id.length > 0 &&
+        typeof record.account === 'object' &&
+        record.account !== null);
+}

package/dist/cjs/link/v5/deeplink.js

@@ -0,0 +1,123 @@
+"use strict";
+// Phantasma Link v5 - deeplink transport (spec §17). dApp and wallet live in separate apps on
+// the SAME device and talk by opening URLs at each other:
+//   request:  {walletBase}/v5/req#t=<topic>&f=<base64url(frame)>   (dApp opens the wallet)
+//   response: {callback}#plv=5&t=<topic>&f=<base64url(frame)>      (wallet opens the dApp back)
+// One request = one URL hop each way ("ping-pong"), sized for SMALL operations; big payloads go
+// over the relay (spec §16). Frames on this transport are ALWAYS the encrypted envelope
+// {nonce, ct} sealed with the pairing session key - custom-scheme URLs are interceptable, so
+// plaintext is never allowed here (enforced by PhantasmaLink5.deeplink()).
+//
+// The transport cannot "listen": responses arrive when the OS (re)opens the dApp with a new
+// URL. The dApp wires that OS event into deliverUrl() (page load / visibilitychange /
+// appUrlOpen, depending on platform).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeeplinkTransport = exports.DEEPLINK_REQUEST_TIMEOUT_MS = exports.WALLET_SCHEME_BASE = void 0;
+exports.buildRequestUrl = buildRequestUrl;
+exports.parseRequestUrl = parseRequestUrl;
+exports.buildResponseUrl = buildResponseUrl;
+exports.parseResponseUrl = parseResponseUrl;
+const errors_js_1 = require("./errors.js");
+const encoding_js_1 = require("./encoding.js");
+/** Default custom-scheme base of the wallet ("phantasma://v5/req"). */
+exports.WALLET_SCHEME_BASE = 'phantasma://';
+/** Default per-request timeout on deeplink transports. A round-trip spans an app switch
+ * plus a human consent, so the generic 60 s session default is far too tight here - it
+ * would expire the money path while the user is still reading the wallet's Send screen. */
+exports.DEEPLINK_REQUEST_TIMEOUT_MS = 300000;
+/** Build the dApp->wallet request URL. `walletBase` is e.g. `phantasma:/` (custom scheme) or
+ * `https://link.phantasma.info` (universal link); the path is fixed to /v5/req. */
+function buildRequestUrl(walletBase, topic, frame) {
+    const base = walletBase.endsWith('/') ? walletBase : `${walletBase}/`;
+    return `${base}v5/req#t=${encodeURIComponent(topic)}&f=${(0, encoding_js_1.bytesToBase64Url)((0, encoding_js_1.utf8ToBytes)(frame))}`;
+}
+/** Parse a dApp->wallet request URL; null when the URL is not a v5 request deeplink. */
+function parseRequestUrl(url) {
+    const hashIndex = url.indexOf('#');
+    if (hashIndex < 0 || !url.slice(0, hashIndex).endsWith('/v5/req')) {
+        return null;
+    }
+    return parseFragment(url.slice(hashIndex + 1), false);
+}
+/** Build the wallet->dApp response URL onto the dApp's pairing callback. */
+function buildResponseUrl(callback, topic, frame) {
+    const hashIndex = callback.indexOf('#');
+    const base = hashIndex < 0 ? callback : callback.slice(0, hashIndex);
+    return `${base}#plv=5&t=${encodeURIComponent(topic)}&f=${(0, encoding_js_1.bytesToBase64Url)((0, encoding_js_1.utf8ToBytes)(frame))}`;
+}
+/** Parse a wallet->dApp response URL; null when the URL is not a v5 response deeplink. */
+function parseResponseUrl(url) {
+    const hashIndex = url.indexOf('#');
+    if (hashIndex < 0) {
+        return null;
+    }
+    return parseFragment(url.slice(hashIndex + 1), true);
+}
+function parseFragment(fragment, requirePlvMarker) {
+    const params = new URLSearchParams(fragment);
+    if (requirePlvMarker && params.get('plv') !== '5') {
+        return null;
+    }
+    const topic = params.get('t');
+    const f = params.get('f');
+    if (!topic || !f) {
+        return null;
+    }
+    try {
+        return { topic, frame: (0, encoding_js_1.bytesToUtf8)((0, encoding_js_1.base64UrlToBytes)(f)) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * {@link LinkTransport} over deeplink ping-pong. `send` opens a wallet URL carrying the frame;
+ * the dApp feeds OS-delivered URLs into {@link deliverUrl}, which dispatches frames for this
+ * transport's topic to the session client.
+ */
+class DeeplinkTransport {
+    constructor(options) {
+        this.closed = false;
+        if (!options.topic) {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidParams, 'Deeplink transport requires a topic');
+        }
+        this.topic = options.topic;
+        this.opener = options.opener;
+        this.walletBase = options.walletBase ?? exports.WALLET_SCHEME_BASE;
+    }
+    send(frame) {
+        if (this.closed) {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.Disconnected, 'Deeplink transport is closed');
+        }
+        this.opener(buildRequestUrl(this.walletBase, this.topic, frame));
+    }
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    onClose(handler) {
+        this.closeHandler = handler;
+    }
+    /**
+     * Feed an OS-delivered URL into the transport. Returns true when the URL was a v5 response
+     * for THIS transport's topic and was dispatched; false lets the caller try other handlers.
+     */
+    deliverUrl(url) {
+        if (this.closed) {
+            return false;
+        }
+        const parsed = parseResponseUrl(url);
+        if (!parsed || parsed.topic !== this.topic) {
+            return false;
+        }
+        this.messageHandler?.(parsed.frame);
+        return true;
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.closeHandler?.('Deeplink transport closed');
+    }
+}
+exports.DeeplinkTransport = DeeplinkTransport;

package/dist/cjs/link/v5/encoding.js

@@ -0,0 +1,95 @@
+"use strict";
+// Phantasma Link v5 - encoding helpers. The transport carries binary (ciphertext, nonces,
+// keys, serialized txs) as base64 (spec §4 / §18), which halves the wire size vs the
+// v1-v4 hex. Implemented dependency-free and environment-agnostic (browser + Node), since
+// the SDK ships to both and `Buffer`/`btoa` are not uniformly available.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bytesToBase64 = bytesToBase64;
+exports.base64ToBytes = base64ToBytes;
+exports.bytesToBase64Url = bytesToBase64Url;
+exports.base64UrlToBytes = base64UrlToBytes;
+exports.utf8ToBytes = utf8ToBytes;
+exports.bytesToUtf8 = bytesToUtf8;
+const B64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+// Reverse lookup table: byte value of each base64 character, or -1 if not a base64 char.
+const B64_LOOKUP = (() => {
+    const table = new Int8Array(256).fill(-1);
+    for (let i = 0; i < B64_ALPHABET.length; i++) {
+        table[B64_ALPHABET.charCodeAt(i)] = i;
+    }
+    return table;
+})();
+/** Encode bytes as standard base64 (with `=` padding). */
+function bytesToBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const hasB1 = i + 1 < bytes.length;
+        const hasB2 = i + 2 < bytes.length;
+        const b1 = hasB1 ? bytes[i + 1] : 0;
+        const b2 = hasB2 ? bytes[i + 2] : 0;
+        out += B64_ALPHABET[b0 >> 2];
+        out += B64_ALPHABET[((b0 & 0x03) << 4) | (b1 >> 4)];
+        out += hasB1 ? B64_ALPHABET[((b1 & 0x0f) << 2) | (b2 >> 6)] : '=';
+        out += hasB2 ? B64_ALPHABET[b2 & 0x3f] : '=';
+    }
+    return out;
+}
+/** Decode standard or url-safe base64 (padding optional) to bytes. Throws on invalid input
+ * so a malformed frame fails loudly rather than silently producing garbage. */
+function base64ToBytes(input) {
+    // Normalize url-safe alphabet and drop padding; we recompute length from content.
+    let clean = '';
+    for (let i = 0; i < input.length; i++) {
+        const c = input[i];
+        if (c === '-') {
+            clean += '+';
+        }
+        else if (c === '_') {
+            clean += '/';
+        }
+        else if (c !== '=') {
+            clean += c;
+        }
+    }
+    const fullGroups = Math.floor(clean.length / 4);
+    const remainder = clean.length % 4;
+    if (remainder === 1) {
+        throw new Error('Invalid base64 string: dangling character');
+    }
+    const outLength = fullGroups * 3 + (remainder === 0 ? 0 : remainder - 1);
+    const out = new Uint8Array(outLength);
+    let o = 0;
+    let acc = 0;
+    let accBits = 0;
+    for (let i = 0; i < clean.length; i++) {
+        const v = B64_LOOKUP[clean.charCodeAt(i)];
+        if (v < 0) {
+            throw new Error('Invalid base64 character');
+        }
+        acc = (acc << 6) | v;
+        accBits += 6;
+        if (accBits >= 8) {
+            accBits -= 8;
+            out[o++] = (acc >> accBits) & 0xff;
+        }
+    }
+    return out;
+}
+/** Encode bytes as url-safe base64 without padding (for use in URL fragments, spec §15). */
+function bytesToBase64Url(bytes) {
+    return bytesToBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** Decode url-safe (or standard) base64 to bytes; alias of {@link base64ToBytes}, which
+ * already accepts both alphabets. */
+function base64UrlToBytes(input) {
+    return base64ToBytes(input);
+}
+/** UTF-8 encode a string to bytes (uses TextEncoder, present in all supported runtimes). */
+function utf8ToBytes(text) {
+    return new TextEncoder().encode(text);
+}
+/** UTF-8 decode bytes to a string. */
+function bytesToUtf8(bytes) {
+    return new TextDecoder('utf-8', { fatal: false }).decode(bytes);
+}

package/dist/cjs/link/v5/envelope.js

@@ -0,0 +1,73 @@
+"use strict";
+// Phantasma Link v5 - message envelope (spec §4). A JSON-RPC-2.0 profile that replaces the
+// v1-v4 delimiter-joined string: typed named params, numeric error codes, and request
+// correlation by `id`. One logical message = one envelope.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLinkRequest = isLinkRequest;
+exports.isLinkEvent = isLinkEvent;
+exports.isLinkErrorResponse = isLinkErrorResponse;
+exports.isLinkSuccessResponse = isLinkSuccessResponse;
+exports.encodeEnvelope = encodeEnvelope;
+exports.decodeEnvelope = decodeEnvelope;
+const protocol_js_1 = require("./protocol.js");
+const errors_js_1 = require("./errors.js");
+function isLinkRequest(msg) {
+    return 'method' in msg && typeof msg.method === 'string';
+}
+function isLinkEvent(msg) {
+    return msg.type === 'event';
+}
+function isLinkErrorResponse(msg) {
+    return 'error' in msg && !!msg.error;
+}
+function isLinkSuccessResponse(msg) {
+    return 'result' in msg;
+}
+/** Serialize an envelope to its on-the-wire JSON text. */
+function encodeEnvelope(message) {
+    return JSON.stringify(message);
+}
+/**
+ * Parse and validate an on-the-wire JSON text into a {@link LinkMessage}.
+ *
+ * Throws {@link LinkError} with `ParseError` for non-JSON and `InvalidRequest` for a JSON
+ * value that is not a well-formed v5 envelope (wrong `plv`, missing `id`, or a shape that
+ * is neither request, response, nor event). Validation happens here, once, so every
+ * downstream consumer can trust the structure.
+ */
+function decodeEnvelope(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.ParseError, 'Phantasma Link message is not valid JSON');
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidRequest, 'Phantasma Link message must be an object');
+    }
+    const record = parsed;
+    if (record.plv !== protocol_js_1.PLV) {
+        throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidRequest, `Unsupported Phantasma Link protocol version: ${String(record.plv)}`);
+    }
+    // Event messages have no `id` and are matched by the `type` discriminator first.
+    if (record.type === 'event') {
+        if (typeof record.event !== 'string') {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidRequest, 'Event envelope is missing `event`');
+        }
+        return parsed;
+    }
+    if (typeof record.id !== 'string' || record.id.length === 0) {
+        throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidRequest, 'Envelope is missing a string `id`');
+    }
+    if (typeof record.method === 'string') {
+        return parsed;
+    }
+    if ('result' in record) {
+        return parsed;
+    }
+    if (record.error && typeof record.error === 'object') {
+        return parsed;
+    }
+    throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidRequest, 'Envelope is neither a request, response, nor event');
+}