@arkade-os/sdk 0.4.19 → 0.4.21

package/dist/cjs/contracts/contractWatcher.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContractWatcher = void 0;
+const utils_1 = require("../providers/utils");
 /**
  * Watches multiple contracts for virtual output state changes with resilient connection handling.
  *
@@ -253,13 +254,18 @@ class ContractWatcher {
     }
     /**
      * Connect to the subscription.
+     *
+     * @param skipUpdate - Skip the leading `updateSubscription` call when
+     *   the caller has already established `subscriptionId`.
      */
-    async connect() {
+    async connect(skipUpdate = false) {
         if (!this.isWatching)
             return;
         this.connectionState = "connecting";
         try {
-            await this.updateSubscription();
+            if (!skipUpdate) {
+                await this.updateSubscription();
+            }
             // Poll immediately after connection to sync state
             await this.pollAllContracts();
             this.connectionState = "connected";
@@ -270,7 +276,12 @@ class ContractWatcher {
                 // indefinitely and block the caller.
                 // Error management must be implemented to ensure the connection
                 // is restored and events are fired.
-                console.error(e);
+                if ((0, utils_1.isEventSourceError)(e)) {
+                    console.debug("ContractWatcher subscription disconnected; reconnecting");
+                }
+                else {
+                    console.error(e);
+                }
                 this.connectionState = "disconnected";
                 this.eventCallback?.({
                     type: "connection_reset",
@@ -385,11 +396,30 @@ class ContractWatcher {
         }
     }
     async tryUpdateSubscription() {
+        const hadSubscription = this.subscriptionId !== undefined;
         try {
             await this.updateSubscription();
         }
         catch (error) {
             // nothing, the connection will be retried later
+            return;
+        }
+        // Cold start: `startWatching` may have run with zero scripts,
+        // leaving `listenLoop` parked behind the reconnect timer. Kick
+        // `connect` now so streaming resumes without waiting on the
+        // backoff. `skipUpdate` avoids re-issuing `subscribeForScripts`.
+        const justGotSubscription = !hadSubscription && this.subscriptionId !== undefined;
+        const listenerParked = this.connectionState === "disconnected" ||
+            this.connectionState === "reconnecting";
+        if (this.isWatching && justGotSubscription && listenerParked) {
+            if (this.reconnectTimeoutId) {
+                clearTimeout(this.reconnectTimeoutId);
+                this.reconnectTimeoutId = undefined;
+            }
+            this.reconnectAttempts = 0;
+            this.connect(true).catch((error) => {
+                console.warn("ContractWatcher cold-start connect failed:", error);
+            });
         }
     }
     /**

package/dist/cjs/contracts/handlers/default.js

@@ -4,8 +4,15 @@ exports.DefaultContractHandler = void 0;
 const base_1 = require("@scure/base");
 const default_1 = require("../../script/default");
 const helpers_1 = require("./helpers");
+const descriptor_1 = require("../../identity/descriptor");
 /**
- * Handler for default wallet virtual outputs.
+ * Extract pubkey bytes from a descriptor or hex string.
+ */
+function extractPubKeyBytes(value) {
+    return base_1.hex.decode((0, descriptor_1.extractPubKey)((0, descriptor_1.normalizeToDescriptor)(value)));
+}
+/**
+ * Handler for default wallet VTXOs.
  *
  * Default contracts use the standard forfeit + exit tapscript:
  * - forfeit: (Alice + Server) multisig for collaborative spending
@@ -29,8 +36,8 @@ exports.DefaultContractHandler = {
             ? (0, helpers_1.sequenceToTimelock)(Number(params.csvTimelock))
             : default_1.DefaultVtxo.Script.DEFAULT_TIMELOCK;
         return {
-            pubKey: base_1.hex.decode(params.pubKey),
-            serverPubKey: base_1.hex.decode(params.serverPubKey),
+            pubKey: extractPubKeyBytes(params.pubKey),
+            serverPubKey: extractPubKeyBytes(params.serverPubKey),
             csvTimelock,
         };
     },

package/dist/cjs/contracts/handlers/helpers.js

@@ -39,6 +39,23 @@ exports.resolveRole = resolveRole;
 exports.isCltvSatisfied = isCltvSatisfied;
 exports.isCsvSpendable = isCsvSpendable;
 const bip68 = __importStar(require("bip68"));
+const descriptor_1 = require("../../identity/descriptor");
+/**
+ * Extract raw hex pubkey from a value that may be a descriptor or raw hex.
+ * Returns undefined for HD descriptors or unparseable values so role
+ * resolution stays best-effort and never throws.
+ */
+function extractRawPubKey(value) {
+    if (!(0, descriptor_1.isDescriptor)(value)) {
+        return value.toLowerCase();
+    }
+    try {
+        return (0, descriptor_1.extractPubKey)(value).toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Convert RelativeTimelock to BIP68 sequence number.
  */
@@ -61,21 +78,46 @@ function sequenceToTimelock(sequence) {
     throw new Error(`Invalid BIP68 sequence: ${sequence}`);
 }
 /**
- * Resolve wallet's role from explicit role or by matching pubkey.
+ * Resolve wallet's role from explicit role or by matching descriptor/pubkey.
  */
 function resolveRole(contract, context) {
     // Explicit role takes precedence
     if (context.role === "sender" || context.role === "receiver") {
         return context.role;
     }
-    // Try to match wallet pubkey against contract params
-    if (context.walletPubKey) {
-        if (context.walletPubKey === contract.params.sender) {
+    const senderKey = contract.params.sender
+        ? extractRawPubKey(contract.params.sender)
+        : undefined;
+    const receiverKey = contract.params.receiver
+        ? extractRawPubKey(contract.params.receiver)
+        : undefined;
+    const matchRole = (rawWalletKey) => {
+        if (!rawWalletKey)
+            return undefined;
+        if (senderKey && rawWalletKey === senderKey) {
             return "sender";
         }
-        if (context.walletPubKey === contract.params.receiver) {
+        if (receiverKey && rawWalletKey === receiverKey) {
             return "receiver";
         }
+        return undefined;
+    };
+    // Try the preferred descriptor first. If it cannot be resolved
+    // (for example an HD descriptor without derivation support), fall back
+    // to walletPubKey for backward compatibility.
+    if (context.walletDescriptor) {
+        const walletDescriptorKey = extractRawPubKey(context.walletDescriptor);
+        const matchedRole = matchRole(walletDescriptorKey);
+        if (matchedRole) {
+            return matchedRole;
+        }
+        if (!walletDescriptorKey && context.walletPubKey) {
+            return matchRole(extractRawPubKey(context.walletPubKey));
+        }
+        return undefined;
+    }
+    if (context.walletPubKey) {
+        return matchRole(extractRawPubKey(context.walletPubKey));
     }
     return undefined;
 }

package/dist/cjs/contracts/handlers/vhtlc.js

@@ -52,7 +52,8 @@ exports.VHTLCContractHandler = {
     /**
      * Select spending path based on context.
      *
-     * Role is determined from `context.role` or by matching `context.walletPubKey`
+     * Role is determined from `context.role` or by matching
+     * `context.walletDescriptor` (preferred) / `context.walletPubKey`
      * against sender/receiver in contract params.
      */
     selectPath(script, contract, context) {
@@ -101,7 +102,8 @@ exports.VHTLCContractHandler = {
     /**
      * Get all possible spending paths (no timelock checks).
      *
-     * Role is determined from `context.role` or by matching `context.walletPubKey`
+     * Role is determined from `context.role` or by matching
+     * `context.walletDescriptor` (preferred) / `context.walletPubKey`
      * against sender/receiver in contract params.
      */
     getAllSpendingPaths(script, contract, context) {

package/dist/cjs/identity/descriptor.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDescriptor = isDescriptor;
+exports.normalizeToDescriptor = normalizeToDescriptor;
+exports.extractPubKey = extractPubKey;
+exports.parseHDDescriptor = parseHDDescriptor;
+const descriptors_scure_1 = require("@bitcoinerlab/descriptors-scure");
+const base_1 = require("@scure/base");
+function inferNetwork(descriptor) {
+    return descriptor.includes("tpub") ? descriptors_scure_1.networks.testnet : descriptors_scure_1.networks.bitcoin;
+}
+/**
+ * Check if a string is a descriptor of the shape `tr(...)`.
+ *
+ * This is a shape check only — it does not validate the inner key material.
+ * Use {@link expand} (via {@link extractPubKey} / {@link parseHDDescriptor})
+ * for full parsing. The guard rejects empty bodies and missing/trailing
+ * parentheses so callers can safely branch on descriptor vs. raw pubkey.
+ */
+function isDescriptor(value) {
+    if (typeof value !== "string")
+        return false;
+    if (!value.startsWith("tr(") || !value.endsWith(")"))
+        return false;
+    // body length > 0 after stripping "tr(" and ")"
+    return value.length > "tr()".length;
+}
+/**
+ * Normalize a value to descriptor format.
+ * If already a descriptor, return as-is. If hex pubkey, wrap as tr(pubkey).
+ * Throws when the value is empty or not a string so we never produce
+ * malformed descriptors like `tr()` that downstream parsers would reject.
+ */
+function normalizeToDescriptor(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error("normalizeToDescriptor: expected a non-empty string value");
+    }
+    if (isDescriptor(value)) {
+        return value;
+    }
+    return `tr(${value})`;
+}
+/**
+ * Extract the public key from a simple descriptor.
+ * For simple descriptors (tr(pubkey)), extracts the pubkey using the library.
+ * For HD descriptors, throws — use DescriptorProvider to derive the key.
+ */
+function extractPubKey(descriptor) {
+    if (!isDescriptor(descriptor)) {
+        return descriptor;
+    }
+    const network = inferNetwork(descriptor);
+    const expansion = (0, descriptors_scure_1.expand)({ descriptor, network });
+    if (!expansion.expansionMap) {
+        throw new Error("Cannot extract pubkey from descriptor: expansion failed.");
+    }
+    const key = expansion.expansionMap["@0"];
+    // HD descriptors (have a bip32 key) require DescriptorProvider for derivation
+    if (key?.bip32) {
+        throw new Error("Cannot extract pubkey from HD descriptor without derivation. " +
+            "Use DescriptorProvider to derive the key from the xpub.");
+    }
+    if (!key?.pubkey) {
+        throw new Error("Cannot extract pubkey from descriptor: no key found.");
+    }
+    return base_1.hex.encode(key.pubkey);
+}
+/**
+ * Parse an HD descriptor into its components.
+ * HD descriptors have the format: tr([fingerprint/path']xpub/derivation)
+ * Returns null if the descriptor is not in HD format.
+ */
+function parseHDDescriptor(descriptor) {
+    if (!isDescriptor(descriptor)) {
+        return null;
+    }
+    let expansion;
+    try {
+        const network = inferNetwork(descriptor);
+        expansion = (0, descriptors_scure_1.expand)({ descriptor, network });
+    }
+    catch {
+        return null;
+    }
+    const key = expansion.expansionMap?.["@0"];
+    if (!key?.masterFingerprint ||
+        !key.originPath ||
+        !key.keyPath ||
+        !key.bip32) {
+        return null;
+    }
+    return {
+        fingerprint: base_1.hex.encode(key.masterFingerprint),
+        basePath: key.originPath.replace(/^\//, ""),
+        xpub: key.bip32.toBase58(),
+        derivationPath: key.keyPath.replace(/^\//, ""),
+    };
+}

package/dist/cjs/identity/descriptorProvider.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/identity/index.js

@@ -14,6 +14,7 @@ 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 });
+exports.StaticDescriptorProvider = exports.parseHDDescriptor = exports.extractPubKey = exports.normalizeToDescriptor = exports.isDescriptor = exports.ReadonlyDescriptorIdentity = exports.MnemonicIdentity = exports.SeedIdentity = void 0;
 exports.isBatchSignable = isBatchSignable;
 /** Type guard for identities that support batch signing. */
 function isBatchSignable(identity) {
@@ -21,4 +22,17 @@ function isBatchSignable(identity) {
         typeof identity.signMultiple === "function");
 }
 __exportStar(require("./singleKey"), exports);
-__exportStar(require("./seedIdentity"), exports);
+var seedIdentity_1 = require("./seedIdentity");
+Object.defineProperty(exports, "SeedIdentity", { enumerable: true, get: function () { return seedIdentity_1.SeedIdentity; } });
+Object.defineProperty(exports, "MnemonicIdentity", { enumerable: true, get: function () { return seedIdentity_1.MnemonicIdentity; } });
+Object.defineProperty(exports, "ReadonlyDescriptorIdentity", { enumerable: true, get: function () { return seedIdentity_1.ReadonlyDescriptorIdentity; } });
+__exportStar(require("./serialize"), exports);
+// Descriptor utilities
+var descriptor_1 = require("./descriptor");
+Object.defineProperty(exports, "isDescriptor", { enumerable: true, get: function () { return descriptor_1.isDescriptor; } });
+Object.defineProperty(exports, "normalizeToDescriptor", { enumerable: true, get: function () { return descriptor_1.normalizeToDescriptor; } });
+Object.defineProperty(exports, "extractPubKey", { enumerable: true, get: function () { return descriptor_1.extractPubKey; } });
+Object.defineProperty(exports, "parseHDDescriptor", { enumerable: true, get: function () { return descriptor_1.parseHDDescriptor; } });
+// Static descriptor provider (wrapper for legacy Identity)
+var staticDescriptorProvider_1 = require("./staticDescriptorProvider");
+Object.defineProperty(exports, "StaticDescriptorProvider", { enumerable: true, get: function () { return staticDescriptorProvider_1.StaticDescriptorProvider; } });

package/dist/cjs/identity/seedIdentity.js

@@ -1,14 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReadonlyDescriptorIdentity = exports.MnemonicIdentity = exports.SeedIdentity = void 0;
+exports.serializeSeedOwnedSigningIdentity = serializeSeedOwnedSigningIdentity;
+exports.serializeSeedOwnedReadonlyIdentity = serializeSeedOwnedReadonlyIdentity;
 const bip39_1 = require("@scure/bip39");
 const english_js_1 = require("@scure/bip39/wordlists/english.js");
 const utils_js_1 = require("@scure/btc-signer/utils.js");
 const btc_signer_1 = require("@scure/btc-signer");
+const base_1 = require("@scure/base");
 const signingSession_1 = require("../tree/signingSession");
 const secp256k1_1 = require("@noble/secp256k1");
 const descriptors_scure_1 = require("@bitcoinerlab/descriptors-scure");
 const ALL_SIGHASH = Object.values(btc_signer_1.SigHash).filter((x) => typeof x === "number");
+/**
+ * Secret-bearing state for seed-backed identities, held off the public
+ * instance surface. Accessed only by the SDK-internal serializer helpers
+ * below; application code cannot read these via ordinary field access.
+ *
+ * Using a module-private WeakMap (rather than `private` / `protected`)
+ * matters because TypeScript visibility is a compile-time boundary only:
+ * JavaScript consumers could still read public fields. A WeakMap removes
+ * that enumeration path entirely.
+ */
+const seedBytes = new WeakMap();
+const mnemonicMeta = new WeakMap();
+// ── Helpers ──────────────────────────────────────────────────────
 /**
  * Detects the network from a descriptor string by checking for tpub (testnet)
  * vs xpub (mainnet) key prefix.
@@ -40,14 +56,14 @@ function buildDescriptor(seed, isMainnet) {
  *
  * This is the recommended identity type for most applications. It uses
  * standard BIP86 (Taproot) derivation by default and stores an output
- * descriptor for interoperability with other wallets. The descriptor
- * format is HD-ready, allowing future support for multiple addresses
- * and change derivation.
+ * descriptor for interoperability with other wallets.
  *
  * Prefer this (or @see MnemonicIdentity) over `SingleKey` for new
  * integrations — `SingleKey` exists for backward compatibility with
  * raw nsec-style keys.
  *
+ * For descriptor-based signing, wrap with {@link StaticDescriptorProvider}.
+ *
  * @example
  * ```typescript
  * const seed = mnemonicToSeedSync(mnemonic);
@@ -67,7 +83,11 @@ class SeedIdentity {
         if (seed.length !== 64) {
             throw new Error("Seed must be 64 bytes");
         }
-        this.seed = seed;
+        // Defensive copy: `derivedKey` and `descriptor` are computed eagerly
+        // from the bytes we're about to stash, so a later mutation of the
+        // caller's buffer must not drift the serialized `seed` out of sync
+        // with the live identity state.
+        seedBytes.set(this, new Uint8Array(seed));
         this.descriptor = descriptor;
         const network = detectNetwork(descriptor);
         // Parse and validate the descriptor using the library
@@ -173,8 +193,9 @@ exports.SeedIdentity = SeedIdentity;
  * ```
  */
 class MnemonicIdentity extends SeedIdentity {
-    constructor(seed, descriptor) {
+    constructor(seed, descriptor, mnemonic, passphrase) {
         super(seed, descriptor);
+        mnemonicMeta.set(this, { mnemonic, passphrase });
     }
     /**
      * Creates a MnemonicIdentity from a BIP39 mnemonic phrase.
@@ -194,7 +215,7 @@ class MnemonicIdentity extends SeedIdentity {
         const descriptor = hasDescriptor(opts)
             ? opts.descriptor
             : buildDescriptor(seed, opts.isMainnet ?? true);
-        return new MnemonicIdentity(seed, descriptor);
+        return new MnemonicIdentity(seed, descriptor, phrase, passphrase);
     }
 }
 exports.MnemonicIdentity = MnemonicIdentity;
@@ -252,3 +273,67 @@ class ReadonlyDescriptorIdentity {
     }
 }
 exports.ReadonlyDescriptorIdentity = ReadonlyDescriptorIdentity;
+/**
+ * Serialize a seed-backed signing identity into a
+ * {@link SerializedSigningIdentity} envelope without exposing the
+ * underlying secret material on the public instance surface.
+ *
+ * Called by {@link serializeSigningIdentity}; application code should
+ * prefer that public dispatcher instead of calling this directly. This
+ * helper is deliberately kept out of the `src/identity` barrel so it is
+ * not part of the package's public export surface.
+ *
+ * Secret-surface trade-off: the resulting envelope carries master-seed
+ * material — the BIP39 mnemonic (+ optional passphrase) for
+ * `MnemonicIdentity` or the raw 64-byte seed for `SeedIdentity`. A party
+ * that reads this envelope can derive any key under the HD tree, not
+ * just the key currently in use. The pre-change `SingleKey` flow only
+ * shipped one derived private key and therefore had a smaller blast
+ * radius. This is an intentional design trade to preserve class and
+ * descriptor identity across the page / service-worker boundary; the
+ * page already holds the same material so that it can re-initialize a
+ * killed worker. Transport is same-origin `postMessage` only. See the
+ * threat-model note in `src/worker/browser/README.md`.
+ *
+ * @internal
+ */
+function serializeSeedOwnedSigningIdentity(identity) {
+    if (identity instanceof MnemonicIdentity) {
+        const meta = mnemonicMeta.get(identity);
+        if (!meta) {
+            throw new Error("MnemonicIdentity is missing internal secret state; was it constructed via MnemonicIdentity.fromMnemonic()?");
+        }
+        const envelope = {
+            type: "mnemonic",
+            mnemonic: meta.mnemonic,
+            descriptor: identity.descriptor,
+        };
+        if (meta.passphrase !== undefined) {
+            envelope.passphrase = meta.passphrase;
+        }
+        return envelope;
+    }
+    const seed = seedBytes.get(identity);
+    if (!seed) {
+        throw new Error("SeedIdentity is missing internal secret state; was it constructed via SeedIdentity.fromSeed() or the class constructor?");
+    }
+    return {
+        type: "seed",
+        seed: base_1.hex.encode(seed),
+        descriptor: identity.descriptor,
+    };
+}
+/**
+ * Downgrade a seed-backed or descriptor-backed identity into a readonly
+ * descriptor envelope. Always produces a descriptor-only shape — secret
+ * material never crosses this path, even if the input is a signing
+ * identity.
+ *
+ * Deliberately kept out of the `src/identity` barrel; consumers should go
+ * through {@link serializeReadonlyIdentity}.
+ *
+ * @internal
+ */
+function serializeSeedOwnedReadonlyIdentity(identity) {
+    return { type: "readonly-descriptor", descriptor: identity.descriptor };
+}

package/dist/cjs/identity/serialize.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSigningSerialized = isSigningSerialized;
+exports.serializeSigningIdentity = serializeSigningIdentity;
+exports.serializeReadonlyIdentity = serializeReadonlyIdentity;
+exports.hydrateIdentity = hydrateIdentity;
+exports.normalizeSerializedIdentity = normalizeSerializedIdentity;
+const base_1 = require("@scure/base");
+const singleKey_1 = require("./singleKey");
+const seedIdentity_1 = require("./seedIdentity");
+/** Type guard — true for signing envelopes, false for readonly envelopes. */
+function isSigningSerialized(s) {
+    return (s.type === "single-key" || s.type === "seed" || s.type === "mnemonic");
+}
+function hasToHex(identity) {
+    return typeof identity.toHex === "function";
+}
+/**
+ * Serialize a signing identity into a structured-clone safe envelope for
+ * transport across the service-worker boundary.
+ *
+ * Supports SDK-owned signing identities directly. For custom identities, a
+ * duck-typed `toHex()` fallback preserves compatibility with existing
+ * `SingleKey`-like implementations.
+ */
+function serializeSigningIdentity(identity) {
+    // Seed-backed identities (including MnemonicIdentity, which extends
+    // SeedIdentity) delegate to the colocated helper so secret material
+    // stays behind the WeakMap-backed internal state in seedIdentity.ts.
+    if (identity instanceof seedIdentity_1.SeedIdentity) {
+        return (0, seedIdentity_1.serializeSeedOwnedSigningIdentity)(identity);
+    }
+    if (identity instanceof singleKey_1.SingleKey) {
+        return { type: "single-key", privateKey: identity.toHex() };
+    }
+    if (hasToHex(identity)) {
+        return { type: "single-key", privateKey: identity.toHex() };
+    }
+    throw new Error("Unsupported signing identity: cannot serialize for service-worker transport");
+}
+/**
+ * Serialize a readonly identity into a structured-clone safe envelope.
+ *
+ * Works for any `ReadonlyIdentity` via `compressedPublicKey()`. When called
+ * with a signing identity, produces a readonly envelope (never ships signing
+ * material) — callers that need to preserve signing capability across the
+ * boundary must use {@link serializeSigningIdentity}.
+ */
+async function serializeReadonlyIdentity(identity) {
+    if (identity instanceof seedIdentity_1.SeedIdentity ||
+        identity instanceof seedIdentity_1.ReadonlyDescriptorIdentity) {
+        return (0, seedIdentity_1.serializeSeedOwnedReadonlyIdentity)(identity);
+    }
+    return {
+        type: "readonly-single-key",
+        publicKey: base_1.hex.encode(await identity.compressedPublicKey()),
+    };
+}
+/**
+ * Rehydrate a serialized identity envelope back into an identity instance.
+ * The return type is the union of signing and readonly; use
+ * {@link isSigningSerialized} on the envelope before hydration if the caller
+ * needs to know which side it ends up on.
+ */
+function hydrateIdentity(s) {
+    switch (s.type) {
+        case "single-key":
+            return singleKey_1.SingleKey.fromHex(s.privateKey);
+        case "readonly-single-key":
+            return singleKey_1.ReadonlySingleKey.fromPublicKey(base_1.hex.decode(s.publicKey));
+        case "seed":
+            return seedIdentity_1.SeedIdentity.fromSeed(base_1.hex.decode(s.seed), {
+                descriptor: s.descriptor,
+            });
+        case "mnemonic":
+            return seedIdentity_1.MnemonicIdentity.fromMnemonic(s.mnemonic, {
+                descriptor: s.descriptor,
+                passphrase: s.passphrase,
+            });
+        case "readonly-descriptor":
+            return seedIdentity_1.ReadonlyDescriptorIdentity.fromDescriptor(s.descriptor);
+        default:
+            // Belt-and-suspenders: `normalizeSerializedIdentity` already
+            // rejects unknown `type` values at the wire boundary. Without
+            // this throw, an unknown type would fall through and return
+            // undefined, which callers would then cast to Identity and
+            // crash downstream with an opaque error.
+            throw new Error(`Unknown serialized identity type: ${String(s.type)}`);
+    }
+}
+let warnedLegacyShape = false;
+/**
+ * Accept either a modern {@link SerializedIdentity} envelope or a legacy
+ * `{ privateKey }` / `{ publicKey }` shape and normalize to a
+ * {@link SerializedIdentity}. Emits a one-time deprecation warning when a
+ * legacy shape is seen.
+ *
+ * Intended for the worker-side boundary; new page builds always emit tagged
+ * envelopes via {@link serializeSigningIdentity} /
+ * {@link serializeReadonlyIdentity}.
+ */
+function normalizeSerializedIdentity(shape) {
+    if ("type" in shape) {
+        assertValidSerializedIdentity(shape);
+        return shape;
+    }
+    if (!warnedLegacyShape) {
+        warnedLegacyShape = true;
+        console.warn("[ts-sdk] Received legacy serialized identity shape " +
+            "(privateKey/publicKey). Upgrade the page build to the latest " +
+            "@arkade-os/sdk — this compatibility path will be removed in " +
+            "the next major.");
+    }
+    if ("privateKey" in shape && typeof shape.privateKey === "string") {
+        return { type: "single-key", privateKey: shape.privateKey };
+    }
+    if ("publicKey" in shape && typeof shape.publicKey === "string") {
+        return { type: "readonly-single-key", publicKey: shape.publicKey };
+    }
+    throw new Error("Unrecognized serialized identity shape");
+}
+/**
+ * Runtime-validate that a tagged envelope carries the fields its variant
+ * requires. The SDK's own serializer produces well-formed envelopes; this
+ * guard exists so a malformed message (older SDK version mismatch,
+ * hand-built config, etc.) fails loudly at the wire boundary rather than
+ * with an opaque `"Cannot read properties of undefined"` deep inside a
+ * hydrator.
+ */
+function assertValidSerializedIdentity(s) {
+    const kind = s.type;
+    const bad = (field, expected) => {
+        throw new Error(`Malformed serialized identity ({ type: ${JSON.stringify(kind)} }): ` +
+            `missing or invalid "${field}" (expected ${expected})`);
+    };
+    const asStr = (key) => {
+        const v = s[key];
+        return typeof v === "string" ? v : bad(key, "string");
+    };
+    switch (kind) {
+        case "single-key":
+            asStr("privateKey");
+            return;
+        case "readonly-single-key":
+            asStr("publicKey");
+            return;
+        case "seed":
+            asStr("seed");
+            asStr("descriptor");
+            return;
+        case "mnemonic": {
+            asStr("mnemonic");
+            asStr("descriptor");
+            const passphrase = s.passphrase;
+            if (passphrase !== undefined && typeof passphrase !== "string") {
+                bad("passphrase", "string | undefined");
+            }
+            return;
+        }
+        case "readonly-descriptor":
+            asStr("descriptor");
+            return;
+        default:
+            throw new Error(`Unknown serialized identity type: ${String(kind)}`);
+    }
+}