phantasma-sdk-ts 0.9.2 → 0.10.0

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

@@ -0,0 +1,60 @@
+"use strict";
+// Phantasma Link v5 - structured error taxonomy (spec §10). Replaces the v1-v4 free-text
+// error strings that callers had to substring-match.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinkError = exports.LinkErrorCode = void 0;
+/** Numeric error codes. JSON-RPC reserved range + EIP-1193-aligned app codes + Phantasma
+ * specific codes. Carried in {@link LinkErrorObject.code}. */
+exports.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. */
+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 : exports.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(exports.LinkErrorCode.InternalError, 'Phantasma Link error');
+    }
+}
+exports.LinkError = LinkError;

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

@@ -0,0 +1,33 @@
+"use strict";
+// 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.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./protocol.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./encoding.js"), exports);
+__exportStar(require("./envelope.js"), exports);
+__exportStar(require("./capabilities.js"), exports);
+__exportStar(require("./methods.js"), exports);
+__exportStar(require("./session-crypto.js"), exports);
+__exportStar(require("./pairing.js"), exports);
+__exportStar(require("./transport.js"), exports);
+__exportStar(require("./loopback-transport.js"), exports);
+__exportStar(require("./deeplink.js"), exports);
+__exportStar(require("./relay-transport.js"), exports);
+__exportStar(require("./web-deeplink.js"), exports);
+__exportStar(require("./client.js"), exports);

package/dist/cjs/link/v5/loopback-transport.js

@@ -0,0 +1,70 @@
+"use strict";
+// Phantasma Link v5 - loopback transport (spec §6.2). Desktop browser/app -> the wallet's
+// local WebSocket server. This is the TRUSTED-LOCAL path: frames are plaintext v5 envelopes
+// (no channel encryption needed; see LinkSessionClient with no session key). Default host is
+// `localhost` (never the literal `127.0.0.1`).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopbackTransport = void 0;
+const errors_js_1 = require("./errors.js");
+function defaultWebSocketFactory(url) {
+    const globalWithWs = globalThis;
+    if (!globalWithWs.WebSocket) {
+        throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.Disconnected, 'No WebSocket implementation available; pass options.webSocketFactory');
+    }
+    return new globalWithWs.WebSocket(url);
+}
+/** A {@link LinkTransport} over a local WebSocket to the wallet. Sends are buffered until the
+ * socket opens, then flushed, so callers can issue requests immediately after construction. */
+class LoopbackTransport {
+    constructor(options = {}) {
+        this.outbox = [];
+        this.isOpen = false;
+        const host = options.host ?? 'localhost';
+        const port = options.port ?? 7090;
+        const path = options.path ?? '/phantasma/v5';
+        const url = `ws://${host}:${port}${path}`;
+        const factory = options.webSocketFactory ?? defaultWebSocketFactory;
+        this.socket = factory(url);
+        this.socket.onopen = () => {
+            this.isOpen = true;
+            for (const frame of this.outbox) {
+                this.socket.send(frame);
+            }
+            this.outbox.length = 0;
+        };
+        this.socket.onmessage = (event) => {
+            if (typeof event.data === 'string') {
+                this.messageHandler?.(event.data);
+            }
+        };
+        this.socket.onclose = (event) => {
+            this.isOpen = false;
+            this.closeHandler?.(event?.reason);
+        };
+        // Errors surface as a subsequent close; nothing actionable to do here.
+        this.socket.onerror = () => { };
+    }
+    send(frame) {
+        if (this.isOpen) {
+            this.socket.send(frame);
+        }
+        else {
+            this.outbox.push(frame);
+        }
+    }
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    onClose(handler) {
+        this.closeHandler = handler;
+    }
+    close() {
+        try {
+            this.socket.close();
+        }
+        catch {
+            // Closing an already-closed socket is harmless.
+        }
+    }
+}
+exports.LoopbackTransport = LoopbackTransport;

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

@@ -0,0 +1,4 @@
+"use strict";
+// Phantasma Link v5 - typed params/results for every `pha_*` method and event (spec §9.5).
+// Binary fields (tx bytes, scripts, signatures, messages) are base64 strings.
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,95 @@
+"use strict";
+// Phantasma Link v5 - pairing URI build/parse (spec §15). The pairing material rides in the
+// URL FRAGMENT (never sent to the server). Two channels decide the key-establishment mode:
+//   - `sym`  : a 32-byte session key in the fragment - ONLY for safe channels (a
+//              domain-verified universal link, or a QR). Simplest + MITM-proof.
+//   - `ecdh` : only the dApp's ephemeral X25519 PUBLIC key - for the hijackable
+//              custom-scheme fallback, where no secret may appear.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPairingUri = buildPairingUri;
+exports.parsePairingUri = parsePairingUri;
+const protocol_js_1 = require("./protocol.js");
+const errors_js_1 = require("./errors.js");
+const encoding_js_1 = require("./encoding.js");
+/** Build a pairing URI. Enforces the security rule that a symmetric key (a secret) must
+ * NOT be placed in a hijackable custom-scheme URL (spec §15/§18). */
+function buildPairingUri(input) {
+    const scheme = input.scheme ?? 'universal';
+    const params = new URLSearchParams();
+    params.set('v', String(protocol_js_1.PLV));
+    params.set('t', input.topic);
+    if (input.relay) {
+        params.set('relay', input.relay);
+    }
+    if (input.callback) {
+        params.set('cb', input.callback);
+    }
+    if (input.mode === 'sym') {
+        if (!input.symKey) {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidParams, 'sym pairing requires symKey');
+        }
+        if (scheme === 'scheme') {
+            // A scheme-squatting app could read this URL; never expose a secret there.
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidParams, 'A symmetric key must not be placed in a custom-scheme URL; use a universal link or QR');
+        }
+        params.set('sk', (0, encoding_js_1.bytesToBase64Url)(input.symKey));
+    }
+    else {
+        if (!input.dappPublicKey) {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidParams, 'ecdh pairing requires dappPublicKey');
+        }
+        params.set('pk', (0, encoding_js_1.bytesToBase64Url)(input.dappPublicKey));
+    }
+    if (input.meta) {
+        params.set('meta', (0, encoding_js_1.bytesToBase64Url)((0, encoding_js_1.utf8ToBytes)(JSON.stringify(input.meta))));
+    }
+    const base = scheme === 'scheme'
+        ? 'phantasma://v5/pair'
+        : `https://${input.host ?? protocol_js_1.DEFAULT_LINK_HOST}/v5/pair`;
+    return `${base}#${params.toString()}`;
+}
+/** Parse a pairing URI (universal-link or custom-scheme) into {@link PairingParams}. */
+function parsePairingUri(uri) {
+    const hashIndex = uri.indexOf('#');
+    if (hashIndex < 0) {
+        throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidRequest, 'Pairing URI has no fragment');
+    }
+    const params = new URLSearchParams(uri.slice(hashIndex + 1));
+    const version = Number(params.get('v'));
+    if (version !== protocol_js_1.PLV) {
+        throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidRequest, `Unsupported pairing version: ${params.get('v')}`);
+    }
+    const topic = params.get('t');
+    if (!topic) {
+        throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidRequest, 'Pairing URI is missing topic');
+    }
+    const relay = params.get('relay') ?? undefined;
+    const callback = params.get('cb') ?? undefined;
+    let meta;
+    const metaRaw = params.get('meta');
+    if (metaRaw) {
+        try {
+            meta = JSON.parse((0, encoding_js_1.bytesToUtf8)((0, encoding_js_1.base64UrlToBytes)(metaRaw)));
+        }
+        catch {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidRequest, 'Pairing URI has malformed meta');
+        }
+    }
+    const sk = params.get('sk');
+    const pk = params.get('pk');
+    if (sk) {
+        return { version, topic, relay, callback, mode: 'sym', symKey: (0, encoding_js_1.base64UrlToBytes)(sk), meta };
+    }
+    if (pk) {
+        return {
+            version,
+            topic,
+            relay,
+            callback,
+            mode: 'ecdh',
+            dappPublicKey: (0, encoding_js_1.base64UrlToBytes)(pk),
+            meta,
+        };
+    }
+    throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidRequest, 'Pairing URI carries neither sk nor pk');
+}

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

@@ -0,0 +1,61 @@
+"use strict";
+// Phantasma Link v5 - protocol constants (the new generation; runs in parallel with the
+// legacy v1-v4 string protocol in `../phantasma-link.ts`). See the design spec:
+// codex-pha `.codex/context/link/phantasma-link-v5-spec.md`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignatureKind = exports.TxFormat = exports.LinkEvent = exports.LinkMethod = exports.DEFAULT_LINK_HOST = exports.PLV = void 0;
+/** Protocol version carried in every v5 envelope (`plv`). A peer that does not recognize
+ * this value rejects the message with {@link LinkErrorCode.InvalidRequest}. */
+exports.PLV = 5;
+/** Default subdomain that hosts the universal links + AASA/assetlinks + relay (spec §17).
+ * NEVER `phantasma.io` (hostile). */
+exports.DEFAULT_LINK_HOST = 'link.phantasma.info';
+/** Request methods (dApp -> wallet). Namespaced `pha_*`, EIP-1193-aligned (spec §9). */
+exports.LinkMethod = {
+    /** Pair or resume a session; returns the capability handshake + account + session. */
+    Connect: 'pha_connect',
+    /** End the session. */
+    Disconnect: 'pha_disconnect',
+    /** Account(s) authorized for this session. */
+    GetAccounts: 'pha_getAccounts',
+    /** Supported chains (CAIP-2) + current; `nexus` as a field. */
+    GetChains: 'pha_getChains',
+    /** Wallet name/version/capabilities/rpc. */
+    GetWalletInfo: 'pha_getWalletInfo',
+    /** Sign an arbitrary, non-transaction-forgeable message. */
+    SignMessage: 'pha_signMessage',
+    /** Sign a transaction only (do NOT broadcast); the dApp submits it. */
+    SignTransaction: 'pha_signTransaction',
+    /** Sign AND broadcast a transaction via the format's RPC endpoint. */
+    SendTransaction: 'pha_sendTransaction',
+    /** Read-only VM invoke (no keys, no approval). */
+    InvokeScript: 'pha_invokeScript',
+};
+/** Event names pushed wallet -> dApp on a persistent transport (spec §9.5 events caveat). */
+exports.LinkEvent = {
+    AccountsChanged: 'pha_accountsChanged',
+    ChainChanged: 'pha_chainChanged',
+    SessionDeleted: 'pha_sessionDeleted',
+    SessionExpired: 'pha_sessionExpired',
+    /** Unsolicited connect result pushed right after a pairing approval (spec §15 step 3),
+     * letting the first connection complete in one user gesture. Unlike the other events it
+     * also rides the deeplink transport: the wallet is foreground at the approval moment, so
+     * it CAN open the callback (this is a reply to the pairing, not a spontaneous push).
+     * `data` carries the same shape as a `pha_connect` result. */
+    SessionEstablished: 'pha_sessionEstablished',
+};
+/** Transaction serialization format. Selects which RPC submission endpoint the wallet uses
+ * (spec §9.4): `script` -> SendRawTransaction (classic `Transaction`), `carbon` ->
+ * SendCarbonTransaction (Carbon `SignedTxMsg`). Routing is by serialization envelope, NOT
+ * by "contains a script" (a Carbon tx may also wrap a script). */
+exports.TxFormat = {
+    Script: 'script',
+    Carbon: 'carbon',
+};
+/** Signature scheme used to sign a Phantasma payload (spec §9.7). Selects the key:
+ * `Ed25519` = the Phantasma key, `ECDSA` = the secp256k1 (ETH/BSC-interop) key. This is
+ * NOT native foreign-chain signing - the wallet always targets Phantasma. */
+exports.SignatureKind = {
+    Ed25519: 'Ed25519',
+    ECDSA: 'ECDSA',
+};

package/dist/cjs/link/v5/relay-transport.js

@@ -0,0 +1,303 @@
+"use strict";
+// Phantasma Link v5 - relay transport (spec §6.4/§16). dApp and wallet meet on an
+// E2E-blind pub/sub server: both subscribe to the pairing topic; every frame is
+// published as OPAQUE payload (the NaCl-sealed envelope text - the relay never sees
+// plaintext, enforced by PhantasmaLink5.relay() requiring the session key). Unlike
+// deeplink this transport is persistent and bidirectional, so it carries big payloads,
+// cross-device sessions, and wallet->dApp events.
+//
+// Mobile-network reality shapes this file: the socket reconnects with backoff and
+// re-subscribes; publishes are tracked until the relay acks them and are re-sent after
+// a reconnect (the wallet de-duplicates by envelope id, spec §18.2, so at-least-once
+// is safe); frames above the relay's per-frame cap are chunked as
+// {msgId, seq, total, chunk} and reassembled before the session layer ever sees them
+// (spec §16). Keepalive needs nothing here: the relay SERVER pings, browsers auto-pong.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayTransport = exports.RELAY_CHUNK_BYTES = exports.DEFAULT_RELAY_URL = void 0;
+const errors_js_1 = require("./errors.js");
+const protocol_js_1 = require("./protocol.js");
+const session_crypto_js_1 = require("./session-crypto.js");
+/** Default relay endpoint on the universal-link host (spec §17). */
+exports.DEFAULT_RELAY_URL = `wss://${protocol_js_1.DEFAULT_LINK_HOST}/relay`;
+/** Outgoing chunk threshold. The relay caps a whole frame at 1 MiB; this leaves room
+ * for the publish envelope around the payload. */
+exports.RELAY_CHUNK_BYTES = 900000;
+// Reassembly bounds (spec §16: enforce total and per-message ceilings so a peer cannot
+// balloon our memory). 64 chunks x 900 KB covers the 32 MiB chain ceiling after base64.
+const MAX_CHUNKS_PER_MESSAGE = 64;
+const MAX_CONCURRENT_PARTIALS = 8;
+const PARTIAL_STALE_MS = 120000;
+function defaultWebSocketFactory(url) {
+    const globalWithWs = globalThis;
+    if (!globalWithWs.WebSocket) {
+        throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.Disconnected, 'No WebSocket implementation available; pass options.webSocketFactory');
+    }
+    return new globalWithWs.WebSocket(url);
+}
+/**
+ * {@link LinkTransport} over the Phantasma Link relay. `send` resolves once the relay
+ * acknowledged the publish (or rejects on timeout/close); incoming `deliver` frames are
+ * surfaced to the session client after chunk reassembly. Transient socket drops are
+ * absorbed by reconnection - the session layer only learns about an explicit close().
+ */
+class RelayTransport {
+    constructor(options) {
+        this.walletKeySeen = false;
+        this.pending = new Map();
+        this.partials = new Map();
+        this.publishSeq = 0;
+        this.reconnectAttempt = 0;
+        this.closed = false;
+        if (!options.topic) {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidParams, 'Relay transport requires a topic');
+        }
+        this.topic = options.topic;
+        this.url = options.url ?? exports.DEFAULT_RELAY_URL;
+        this.factory = options.webSocketFactory ?? defaultWebSocketFactory;
+        this.maxPayloadBytes = options.maxPayloadBytes ?? exports.RELAY_CHUNK_BYTES;
+        this.maxAssembledBytes = options.maxAssembledBytes ?? 64 * 1024 * 1024;
+        this.publishAckTimeoutMs = options.publishAckTimeoutMs ?? 15000;
+        this.reconnectDelaysMs = options.reconnectDelaysMs ?? [500, 1000, 2000, 5000, 15000];
+        this.onWalletKey = options.onWalletKey;
+        this.log = options.log;
+        this.connect();
+    }
+    async send(frame) {
+        if (this.closed) {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.Disconnected, 'Relay transport is closed');
+        }
+        if (frame.length <= this.maxPayloadBytes) {
+            await this.publish(frame);
+            return;
+        }
+        // Chunked send: split the opaque frame TEXT; the chunks travel as ordinary
+        // publishes and only the receiver reassembles (the relay stays blind).
+        const total = Math.ceil(frame.length / this.maxPayloadBytes);
+        if (total > MAX_CHUNKS_PER_MESSAGE) {
+            throw new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InvalidParams, 'Frame exceeds the relay transport size ceiling');
+        }
+        const msgId = (0, session_crypto_js_1.randomToken)();
+        const publishes = [];
+        for (let seq = 0; seq < total; seq++) {
+            const chunk = frame.slice(seq * this.maxPayloadBytes, (seq + 1) * this.maxPayloadBytes);
+            publishes.push(this.publish({ msgId, seq, total, chunk }));
+        }
+        await Promise.all(publishes);
+    }
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    onClose(handler) {
+        this.closeHandler = handler;
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+        }
+        this.rejectAllPending('Relay transport closed');
+        try {
+            this.socket?.close();
+        }
+        catch {
+            // Closing an already-closed socket is harmless.
+        }
+        // The session layer learns about closure exactly once, and only for an explicit
+        // close - transient drops are hidden behind reconnection.
+        this.closeHandler?.('Relay transport closed');
+    }
+    // --- connection lifecycle -------------------------------------------------------
+    connect() {
+        const socket = this.factory(this.url);
+        this.socket = socket;
+        socket.onopen = () => {
+            if (this.closed) {
+                socket.close();
+                return;
+            }
+            this.reconnectAttempt = 0;
+            socket.send(JSON.stringify({ op: 'subscribe', topic: this.topic }));
+            // Re-send publishes the previous socket never got acked for (at-least-once;
+            // the wallet de-duplicates by envelope id). Order by publish sequence so a
+            // chunked message keeps its relative order.
+            const texts = [...this.pending.entries()]
+                .sort((a, b) => Number(a[0].slice(1)) - Number(b[0].slice(1)))
+                .map(([, entry]) => entry.text);
+            for (const text of texts) {
+                socket.send(text);
+            }
+        };
+        socket.onmessage = (event) => {
+            if (typeof event.data === 'string') {
+                this.handleRaw(event.data);
+            }
+        };
+        socket.onclose = () => {
+            if (!this.closed) {
+                this.scheduleReconnect();
+            }
+        };
+        // Errors surface as a subsequent close; nothing actionable here.
+        socket.onerror = () => { };
+    }
+    scheduleReconnect() {
+        const ladder = this.reconnectDelaysMs;
+        const delay = ladder[Math.min(this.reconnectAttempt, ladder.length - 1)];
+        this.reconnectAttempt += 1;
+        this.reconnectTimer = setTimeout(() => this.connect(), delay);
+    }
+    // --- outgoing -------------------------------------------------------------------
+    publish(payload) {
+        const id = `p${++this.publishSeq}`;
+        const text = JSON.stringify({ op: 'publish', topic: this.topic, id, payload });
+        return new Promise((resolve, reject) => {
+            // The ack timeout is the delivery guarantee's outer bound: it spans reconnect
+            // attempts (the entry survives them), so it must comfortably exceed the ladder.
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new errors_js_1.LinkError(errors_js_1.LinkErrorCode.Disconnected, 'Relay did not acknowledge the publish'));
+            }, this.publishAckTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer, text });
+            if (this.socket && this.socket.readyState === 1) {
+                this.socket.send(text);
+            }
+            // Not open: the publish stays pending and goes out in onopen's re-send pass.
+        });
+    }
+    rejectAllPending(reason) {
+        for (const [id, entry] of this.pending) {
+            clearTimeout(entry.timer);
+            entry.reject(new errors_js_1.LinkError(errors_js_1.LinkErrorCode.Disconnected, reason));
+            this.pending.delete(id);
+        }
+    }
+    // --- incoming -------------------------------------------------------------------
+    handleRaw(text) {
+        let frame;
+        try {
+            frame = JSON.parse(text);
+        }
+        catch {
+            return; // not a relay frame; ignore
+        }
+        switch (frame.op) {
+            case 'deliver': {
+                if (frame.topic !== this.topic) {
+                    return;
+                }
+                const payload = frame.payload;
+                if (typeof payload === 'string') {
+                    this.messageHandler?.(payload);
+                }
+                else if (payload && typeof payload === 'object') {
+                    const record = payload;
+                    // ecdh key hop (spec §18.1): the wallet's public key plus the first sealed
+                    // envelope in one payload. The key callback runs FIRST so the session layer
+                    // can already open the embedded frame; repeats are ignored (one hop per
+                    // pairing - a second wpk on a live channel is noise or forgery).
+                    if (typeof record.wpk === 'string') {
+                        if (this.onWalletKey && !this.walletKeySeen) {
+                            this.walletKeySeen = true;
+                            this.onWalletKey(record.wpk);
+                            if (typeof record.nonce === 'string' && typeof record.ct === 'string') {
+                                this.messageHandler?.(JSON.stringify({ nonce: record.nonce, ct: record.ct }));
+                            }
+                        }
+                        return;
+                    }
+                    this.acceptChunk(record);
+                }
+                return;
+            }
+            case 'ack': {
+                const entry = typeof frame.id === 'string' ? this.pending.get(frame.id) : undefined;
+                if (entry) {
+                    this.pending.delete(frame.id);
+                    clearTimeout(entry.timer);
+                    entry.resolve();
+                }
+                return;
+            }
+            case 'error': {
+                const entry = typeof frame.id === 'string' ? this.pending.get(frame.id) : undefined;
+                const message = frame.message;
+                if (entry) {
+                    // A publish-scoped error settles that one publish.
+                    this.pending.delete(frame.id);
+                    clearTimeout(entry.timer);
+                    entry.reject(new errors_js_1.LinkError(errors_js_1.LinkErrorCode.InternalError, typeof message === 'string' ? message : 'Relay rejected the publish'));
+                    return;
+                }
+                // No publish matches this error (e.g. a subscribe refusal like topic_limit, which carries
+                // no publish id). Spec §16 requires clients to surface error frames, not drop them - a
+                // silent drop is exactly what let a refused subscribe hang. We do NOT force a close here
+                // (a fatal error is followed by the server closing, which the reconnect path handles);
+                // surfacing keeps the failure visible instead of invisible.
+                const code = frame.code;
+                const detail = `relay error${typeof code !== 'undefined' ? ` code=${String(code)}` : ''}${typeof message === 'string' ? `: ${message}` : ''}`;
+                (this.log ?? ((m) => console.warn(`[phantasma-link relay] ${m}`)))(detail);
+                return;
+            }
+            default:
+                return; // unknown server op; ignore for forward compatibility
+        }
+    }
+    /** Collect one chunk; emit the reassembled frame when complete. Bounds: chunk count,
+     * total bytes, concurrent partial messages, and a staleness GC - a hostile peer can
+     * waste its own topic, but not this client's memory (spec §16). */
+    acceptChunk(raw) {
+        const msgId = raw.msgId;
+        const seq = raw.seq;
+        const total = raw.total;
+        const chunk = raw.chunk;
+        if (typeof msgId !== 'string' ||
+            typeof seq !== 'number' ||
+            typeof total !== 'number' ||
+            typeof chunk !== 'string' ||
+            !Number.isInteger(seq) ||
+            !Number.isInteger(total) ||
+            total < 1 ||
+            total > MAX_CHUNKS_PER_MESSAGE ||
+            seq < 0 ||
+            seq >= total) {
+            return;
+        }
+        // Staleness GC runs lazily on arrival; an abandoned partial cannot linger forever.
+        const now = Date.now();
+        for (const [key, partial] of this.partials) {
+            if (now - partial.touchedAt > PARTIAL_STALE_MS) {
+                this.partials.delete(key);
+            }
+        }
+        let partial = this.partials.get(msgId);
+        if (!partial) {
+            if (this.partials.size >= MAX_CONCURRENT_PARTIALS) {
+                return; // refuse new assemblies rather than grow without bound
+            }
+            partial = { total, received: new Map(), bytes: 0, touchedAt: now };
+            this.partials.set(msgId, partial);
+        }
+        if (partial.total !== total || partial.received.has(seq)) {
+            return; // inconsistent or duplicate chunk; ignore
+        }
+        partial.bytes += chunk.length;
+        if (partial.bytes > this.maxAssembledBytes) {
+            this.partials.delete(msgId);
+            return;
+        }
+        partial.received.set(seq, chunk);
+        partial.touchedAt = now;
+        if (partial.received.size === total) {
+            this.partials.delete(msgId);
+            let joined = '';
+            for (let i = 0; i < total; i++) {
+                joined += partial.received.get(i);
+            }
+            this.messageHandler?.(joined);
+        }
+    }
+}
+exports.RelayTransport = RelayTransport;