phantasma-sdk-ts 0.9.2 → 0.10.1

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');
+}

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',
+};