phantasma-sdk-ts 0.9.2 → 0.10.0

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

@@ -0,0 +1,320 @@
+// 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.
+import { LinkMethod, LinkEvent } from './protocol.js';
+import { LinkSessionClient, } from './transport.js';
+import { LoopbackTransport } from './loopback-transport.js';
+import { DeeplinkTransport, DEEPLINK_REQUEST_TIMEOUT_MS, } from './deeplink.js';
+import { RelayTransport, DEFAULT_RELAY_URL } from './relay-transport.js';
+import { LinkError, LinkErrorCode } from './errors.js';
+import { buildPairingUri } from './pairing.js';
+import { base64UrlToBytes } from './encoding.js';
+import { resolveWebDeeplinkHooks, loadWebDeeplinkRecord, saveWebDeeplinkRecord, createWebDeeplinkRecord, stripUrlFragment, } from './web-deeplink.js';
+import { deriveSessionKey, generateEphemeralKeyPair, randomToken, } from './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}.
+ */
+export 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 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 === 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 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 LinkError(LinkErrorCode.InvalidParams, 'Deeplink requires the 32-byte pairing session key');
+        }
+        return new PhantasmaLink5(new DeeplinkTransport(options), {
+            sessionKey: options.sessionKey,
+            // Deeplink round-trips include an app switch + human consent; see the constant.
+            requestTimeoutMs: options.requestTimeoutMs ?? 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 LinkError(LinkErrorCode.InvalidParams, 'Relay requires the 32-byte pairing session key');
+        }
+        return new PhantasmaLink5(new RelayTransport(options), {
+            sessionKey: options.sessionKey,
+            // Relay round-trips include human consents too; same generous default.
+            requestTimeoutMs: options.requestTimeoutMs ?? 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 ?? randomToken(32);
+        const pair = options.keyPair ?? generateEphemeralKeyPair();
+        const relayUrl = options.url ?? DEFAULT_RELAY_URL;
+        const transport = new RelayTransport({
+            ...options,
+            topic,
+            url: relayUrl,
+            onWalletKey: (publicKeyB64Url) => {
+                // Fires only when the wallet's hop arrives, long after `client` below exists.
+                const walletPublicKey = base64UrlToBytes(publicKeyB64Url);
+                client.session.setSessionKey(deriveSessionKey(walletPublicKey, pair.secretKey));
+            },
+        });
+        const client = new PhantasmaLink5(transport, {
+            dapp: options.dapp,
+            requireSessionKey: true,
+            requestTimeoutMs: options.requestTimeoutMs ?? DEEPLINK_REQUEST_TIMEOUT_MS,
+        });
+        client.pairingUriValue = 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 = resolveWebDeeplinkHooks(options);
+        let record = 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 = createWebDeeplinkRecord(options.callback ?? stripUrlFragment(hooks.pageUrl()));
+            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 = base64UrlToBytes(stored.key);
+        const client = new PhantasmaLink5(new DeeplinkTransport({
+            topic: stored.topic,
+            opener: hooks.opener,
+            walletBase: options.walletBase,
+        }), {
+            dapp: options.dapp,
+            sessionKey,
+            sessionId: stored.sessionId,
+            requestTimeoutMs: options.requestTimeoutMs ?? DEEPLINK_REQUEST_TIMEOUT_MS,
+            onSessionChange: (connect) => {
+                // Session layer only - the pairing material stays valid across disconnects.
+                stored.sessionId = connect?.session.id;
+                stored.lastConnect = connect;
+                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 = 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?.(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 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 LinkError(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(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(LinkMethod.GetAccounts);
+    }
+    getChains() {
+        return this.request(LinkMethod.GetChains);
+    }
+    getWalletInfo() {
+        return this.request(LinkMethod.GetWalletInfo);
+    }
+    signMessage(params) {
+        return this.request(LinkMethod.SignMessage, params);
+    }
+    /** Sign a transaction without broadcasting; the dApp submits the returned signed tx. */
+    signTransaction(params) {
+        return this.request(LinkMethod.SignTransaction, params);
+    }
+    /** Sign AND broadcast a transaction via the format's RPC endpoint. */
+    sendTransaction(params) {
+        return this.request(LinkMethod.SendTransaction, params);
+    }
+    /** Read-only VM invoke (no keys, no approval). */
+    invokeScript(params) {
+        return this.request(LinkMethod.InvokeScript, params);
+    }
+    async disconnect() {
+        const result = await this.request(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);
+    }
+}
+/** 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/esm/link/v5/deeplink.js

@@ -0,0 +1,115 @@
+// 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).
+import { LinkError, LinkErrorCode } from './errors.js';
+import { bytesToBase64Url, base64UrlToBytes, utf8ToBytes, bytesToUtf8 } from './encoding.js';
+/** Default custom-scheme base of the wallet ("phantasma://v5/req"). */
+export const 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. */
+export const 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. */
+export function buildRequestUrl(walletBase, topic, frame) {
+    const base = walletBase.endsWith('/') ? walletBase : `${walletBase}/`;
+    return `${base}v5/req#t=${encodeURIComponent(topic)}&f=${bytesToBase64Url(utf8ToBytes(frame))}`;
+}
+/** Parse a dApp->wallet request URL; null when the URL is not a v5 request deeplink. */
+export 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. */
+export 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=${bytesToBase64Url(utf8ToBytes(frame))}`;
+}
+/** Parse a wallet->dApp response URL; null when the URL is not a v5 response deeplink. */
+export 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: bytesToUtf8(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.
+ */
+export class DeeplinkTransport {
+    constructor(options) {
+        this.closed = false;
+        if (!options.topic) {
+            throw new LinkError(LinkErrorCode.InvalidParams, 'Deeplink transport requires a topic');
+        }
+        this.topic = options.topic;
+        this.opener = options.opener;
+        this.walletBase = options.walletBase ?? WALLET_SCHEME_BASE;
+    }
+    send(frame) {
+        if (this.closed) {
+            throw new LinkError(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');
+    }
+}

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

@@ -0,0 +1,87 @@
+// 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.
+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). */
+export 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. */
+export 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). */
+export 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. */
+export function base64UrlToBytes(input) {
+    return base64ToBytes(input);
+}
+/** UTF-8 encode a string to bytes (uses TextEncoder, present in all supported runtimes). */
+export function utf8ToBytes(text) {
+    return new TextEncoder().encode(text);
+}
+/** UTF-8 decode bytes to a string. */
+export function bytesToUtf8(bytes) {
+    return new TextDecoder('utf-8', { fatal: false }).decode(bytes);
+}

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

@@ -0,0 +1,65 @@
+// 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.
+import { PLV } from './protocol.js';
+import { LinkError, LinkErrorCode } from './errors.js';
+export function isLinkRequest(msg) {
+    return 'method' in msg && typeof msg.method === 'string';
+}
+export function isLinkEvent(msg) {
+    return msg.type === 'event';
+}
+export function isLinkErrorResponse(msg) {
+    return 'error' in msg && !!msg.error;
+}
+export function isLinkSuccessResponse(msg) {
+    return 'result' in msg;
+}
+/** Serialize an envelope to its on-the-wire JSON text. */
+export 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.
+ */
+export function decodeEnvelope(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new LinkError(LinkErrorCode.ParseError, 'Phantasma Link message is not valid JSON');
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new LinkError(LinkErrorCode.InvalidRequest, 'Phantasma Link message must be an object');
+    }
+    const record = parsed;
+    if (record.plv !== PLV) {
+        throw new LinkError(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 LinkError(LinkErrorCode.InvalidRequest, 'Event envelope is missing `event`');
+        }
+        return parsed;
+    }
+    if (typeof record.id !== 'string' || record.id.length === 0) {
+        throw new LinkError(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 LinkError(LinkErrorCode.InvalidRequest, 'Envelope is neither a request, response, nor event');
+}

package/dist/esm/link/v5/errors.js

@@ -0,0 +1,56 @@
+// Phantasma Link v5 - structured error taxonomy (spec §10). Replaces the v1-v4 free-text
+// error strings that callers had to substring-match.
+/** Numeric error codes. JSON-RPC reserved range + EIP-1193-aligned app codes + Phantasma
+ * specific codes. Carried in {@link LinkErrorObject.code}. */
+export const LinkErrorCode = {
+    // JSON-RPC reserved.
+    ParseError: -32700,
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InvalidParams: -32602,
+    InternalError: -32603,
+    // App-level (EIP-1193-aligned where sensible).
+    UserRejected: 4001,
+    Unauthorized: 4100,
+    Disconnected: 4900,
+    UnsupportedChain: 4902,
+    // Phantasma-specific.
+    PayloadTooLarge: 5001,
+    NexusMismatch: 5002,
+    UnsupportedSignatureKind: 5003,
+    CapabilityNotSupported: 5004,
+    SessionExpired: 5100,
+    SessionRevoked: 5101,
+};
+/** Error thrown by the v5 client and carried over the wire as {@link LinkErrorObject}.
+ * Keeping a dedicated class lets callers branch on the numeric `code` instead of parsing
+ * message text. */
+export class LinkError extends Error {
+    constructor(code, message, data) {
+        super(message);
+        this.name = 'LinkError';
+        this.code = code;
+        this.data = data;
+        // Preserve `instanceof LinkError` across the transpiled-to-ES2020 target.
+        Object.setPrototypeOf(this, LinkError.prototype);
+    }
+    toObject() {
+        // `data` is omitted entirely when undefined so the serialized shape stays minimal.
+        return this.data === undefined
+            ? { code: this.code, message: this.message }
+            : { code: this.code, message: this.message, data: this.data };
+    }
+    /** Reconstruct a {@link LinkError} from a received error object, tolerating malformed
+     * inputs (a peer may send a non-conforming shape). */
+    static fromObject(obj) {
+        if (obj && typeof obj === 'object') {
+            const record = obj;
+            const code = typeof record.code === 'number' ? record.code : LinkErrorCode.InternalError;
+            const message = typeof record.message === 'string' && record.message.length > 0
+                ? record.message
+                : 'Phantasma Link error';
+            return new LinkError(code, message, record.data);
+        }
+        return new LinkError(LinkErrorCode.InternalError, 'Phantasma Link error');
+    }
+}

package/dist/esm/link/v5/index.js

@@ -0,0 +1,17 @@
+// Phantasma Link v5 - public barrel for the new protocol generation. Import via
+// `phantasma-sdk-ts/link/v5` or the `PhantasmaLinkV5` namespace from the package root.
+// The legacy v1-v4 client (`PhantasmaLink`) remains available and unchanged.
+export * from './protocol.js';
+export * from './errors.js';
+export * from './encoding.js';
+export * from './envelope.js';
+export * from './capabilities.js';
+export * from './methods.js';
+export * from './session-crypto.js';
+export * from './pairing.js';
+export * from './transport.js';
+export * from './loopback-transport.js';
+export * from './deeplink.js';
+export * from './relay-transport.js';
+export * from './web-deeplink.js';
+export * from './client.js';