@arkade-os/sdk 0.4.19 → 0.4.21

package/dist/esm/identity/index.js

@@ -4,4 +4,9 @@ export function isBatchSignable(identity) {
         typeof identity.signMultiple === "function");
 }
 export * from './singleKey.js';
-export * from './seedIdentity.js';
+export { SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, } from './seedIdentity.js';
+export * from './serialize.js';
+// Descriptor utilities
+export { isDescriptor, normalizeToDescriptor, extractPubKey, parseHDDescriptor, } from './descriptor.js';
+// Static descriptor provider (wrapper for legacy Identity)
+export { StaticDescriptorProvider } from './staticDescriptorProvider.js';

package/dist/esm/identity/seedIdentity.js

@@ -2,10 +2,24 @@ import { validateMnemonic, mnemonicToSeedSync } from "@scure/bip39";
 import { wordlist } from "@scure/bip39/wordlists/english.js";
 import { pubECDSA, pubSchnorr } from "@scure/btc-signer/utils.js";
 import { SigHash } from "@scure/btc-signer";
+import { hex } from "@scure/base";
 import { TreeSignerSession } from '../tree/signingSession.js';
 import { schnorr, signAsync } from "@noble/secp256k1";
 import { HDKey, expand, networks, scriptExpressions, } from "@bitcoinerlab/descriptors-scure";
 const ALL_SIGHASH = Object.values(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.
@@ -37,14 +51,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);
@@ -64,7 +78,11 @@ export 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
@@ -169,8 +187,9 @@ export class SeedIdentity {
  * ```
  */
 export 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.
@@ -190,7 +209,7 @@ export 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);
     }
 }
 /**
@@ -246,3 +265,67 @@ export class ReadonlyDescriptorIdentity {
         return this.compressedPubKey;
     }
 }
+/**
+ * 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
+ */
+export 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: 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
+ */
+export function serializeSeedOwnedReadonlyIdentity(identity) {
+    return { type: "readonly-descriptor", descriptor: identity.descriptor };
+}

package/dist/esm/identity/serialize.js

@@ -0,0 +1,159 @@
+import { hex } from "@scure/base";
+import { SingleKey, ReadonlySingleKey } from './singleKey.js';
+import { SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, serializeSeedOwnedSigningIdentity, serializeSeedOwnedReadonlyIdentity, } from './seedIdentity.js';
+/** Type guard — true for signing envelopes, false for readonly envelopes. */
+export 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.
+ */
+export 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) {
+        return serializeSeedOwnedSigningIdentity(identity);
+    }
+    if (identity instanceof 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}.
+ */
+export async function serializeReadonlyIdentity(identity) {
+    if (identity instanceof SeedIdentity ||
+        identity instanceof ReadonlyDescriptorIdentity) {
+        return serializeSeedOwnedReadonlyIdentity(identity);
+    }
+    return {
+        type: "readonly-single-key",
+        publicKey: 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.
+ */
+export function hydrateIdentity(s) {
+    switch (s.type) {
+        case "single-key":
+            return SingleKey.fromHex(s.privateKey);
+        case "readonly-single-key":
+            return ReadonlySingleKey.fromPublicKey(hex.decode(s.publicKey));
+        case "seed":
+            return SeedIdentity.fromSeed(hex.decode(s.seed), {
+                descriptor: s.descriptor,
+            });
+        case "mnemonic":
+            return MnemonicIdentity.fromMnemonic(s.mnemonic, {
+                descriptor: s.descriptor,
+                passphrase: s.passphrase,
+            });
+        case "readonly-descriptor":
+            return 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}.
+ */
+export 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)}`);
+    }
+}

package/dist/esm/identity/staticDescriptorProvider.js

@@ -0,0 +1,61 @@
+import { hex } from "@scure/base";
+import { isBatchSignable } from './index.js';
+import { normalizeToDescriptor, extractPubKey } from './descriptor.js';
+/**
+ * Wraps a legacy Identity (single-key) as a DescriptorProvider.
+ * The descriptor is always a simple tr(pubkey) format.
+ */
+export class StaticDescriptorProvider {
+    constructor(identity, pubKeyHex) {
+        this.identity = identity;
+        this.pubKeyHex = pubKeyHex;
+        this.descriptor = `tr(${pubKeyHex})`;
+    }
+    static async create(identity) {
+        const pubKey = await identity.xOnlyPublicKey();
+        return new StaticDescriptorProvider(identity, hex.encode(pubKey));
+    }
+    getSigningDescriptor() {
+        return this.descriptor;
+    }
+    isOurs(descriptor) {
+        try {
+            const normalized = normalizeToDescriptor(descriptor);
+            const pubKey = extractPubKey(normalized);
+            return pubKey.toLowerCase() === this.pubKeyHex.toLowerCase();
+        }
+        catch {
+            return false;
+        }
+    }
+    async signWithDescriptor(requests) {
+        for (const request of requests) {
+            if (!this.isOurs(request.descriptor)) {
+                throw new Error(`Descriptor ${request.descriptor} does not belong to this provider`);
+            }
+        }
+        // Use batch signing when the identity supports it (fewer confirmation popups)
+        if (isBatchSignable(this.identity)) {
+            const signed = await this.identity.signMultiple(requests.map((r) => ({
+                tx: r.tx,
+                inputIndexes: r.inputIndexes,
+            })));
+            if (signed.length !== requests.length) {
+                throw new Error(`signMultiple returned ${signed.length} transactions, expected ${requests.length}`);
+            }
+            return signed;
+        }
+        const results = [];
+        for (const request of requests) {
+            const signed = await this.identity.sign(request.tx, request.inputIndexes);
+            results.push(signed);
+        }
+        return results;
+    }
+    async signMessageWithDescriptor(descriptor, message, type = "schnorr") {
+        if (!this.isOurs(descriptor)) {
+            throw new Error(`Descriptor ${descriptor} does not belong to this provider`);
+        }
+        return this.identity.signMessage(message, type);
+    }
+}

package/dist/esm/index.js

@@ -18,6 +18,7 @@ import { ServiceWorkerWallet, ServiceWorkerReadonlyWallet, DEFAULT_MESSAGE_TIMEO
 import { OnchainWallet } from './wallet/onchain.js';
 import { setupServiceWorker } from './worker/browser/utils.js';
 import { ESPLORA_URL, EsploraProvider, } from './providers/onchain.js';
+import { ElectrumOnchainProvider, WsElectrumChainSource, } from './providers/electrum.js';
 import { RestArkProvider, SettlementEventType, } from './providers/ark.js';
 import { RestDelegatorProvider, } from './providers/delegator.js';
 import { CLTVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CSVMultisigTapscript, decodeTapscript, MultisigTapscript, } from './script/tapscript.js';
@@ -46,7 +47,7 @@ export {
 // Wallets
 Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, isBatchSignable, OnchainWallet, Ramps, VtxoManager, DelegatorManagerImpl, RestDelegatorProvider, 
 // Providers
-ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, 
+ESPLORA_URL, EsploraProvider, ElectrumOnchainProvider, WsElectrumChainSource, RestArkProvider, RestIndexerProvider, 
 // Script-related
 ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC, 
 // Enums

package/dist/esm/providers/ark.js

@@ -1,5 +1,5 @@
 import { hex } from "@scure/base";
-import { eventSourceIterator } from './utils.js';
+import { eventSourceIterator, isEventSourceError } from './utils.js';
 import { maybeArkError } from './errors.js';
 import { Intent } from '../intent/index.js';
 export var SettlementEventType;
@@ -232,18 +232,19 @@ export class RestArkProvider {
         // leak the underlying SSE connection. `return()` is overridden below
         // so that closing the generator also closes the connection even when
         // the body is currently suspended at an await point.
-        let eventSource = null;
+        let iterator = null;
+        const closeIterator = () => iterator?.close();
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const self = this;
         const gen = (async function* () {
-            const abortHandler = () => eventSource?.close();
+            const abortHandler = closeIterator;
             signal?.addEventListener("abort", abortHandler);
             try {
                 while (!signal?.aborted) {
-                    eventSource = new EventSource(url + queryParams);
-                    const iterator = eventSourceIterator(eventSource);
+                    const currentIterator = eventSourceIterator(new EventSource(url + queryParams));
+                    iterator = currentIterator;
                     try {
-                        for await (const event of iterator) {
+                        for await (const event of currentIterator) {
                             if (signal?.aborted)
                                 break;
                             try {
@@ -260,8 +261,9 @@ export class RestArkProvider {
                         }
                     }
                     catch (error) {
-                        if (error instanceof Error &&
-                            error.name === "AbortError") {
+                        if (signal?.aborted ||
+                            (error instanceof Error &&
+                                error.name === "AbortError")) {
                             break;
                         }
                         // ignore timeout errors, they're expected when the server is not sending anything for 5 min
@@ -269,71 +271,94 @@ export class RestArkProvider {
                             console.debug("Timeout error ignored");
                             continue;
                         }
+                        if (isEventSourceError(error)) {
+                            throw error;
+                        }
                         console.error("Event stream error:", error);
                         throw error;
                     }
                     finally {
-                        eventSource.close();
+                        currentIterator.close();
+                        iterator = null;
                     }
                 }
             }
             finally {
                 signal?.removeEventListener("abort", abortHandler);
-                eventSource?.close();
+                closeIterator();
             }
         })();
         const origReturn = gen.return.bind(gen);
         gen.return = (value) => {
-            eventSource?.close();
+            closeIterator();
             return origReturn(value);
         };
         return gen;
     }
-    async *getTransactionsStream(signal) {
+    getTransactionsStream(signal) {
         const url = `${this.serverUrl}/v1/txs`;
-        while (!signal?.aborted) {
+        let iterator = null;
+        const closeIterator = () => iterator?.close();
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        const gen = (async function* () {
+            const abortHandler = closeIterator;
+            signal?.addEventListener("abort", abortHandler);
             try {
-                const eventSource = new EventSource(url);
-                // Set up abort handling
-                const abortHandler = () => {
-                    eventSource.close();
-                };
-                signal?.addEventListener("abort", abortHandler);
-                try {
-                    for await (const event of eventSourceIterator(eventSource)) {
-                        if (signal?.aborted)
-                            break;
-                        try {
-                            const data = JSON.parse(event.data);
-                            const txNotification = this.parseTransactionNotification(data);
-                            if (txNotification) {
-                                yield txNotification;
+                while (!signal?.aborted) {
+                    try {
+                        const currentIterator = eventSourceIterator(new EventSource(url));
+                        iterator = currentIterator;
+                        for await (const event of currentIterator) {
+                            if (signal?.aborted)
+                                break;
+                            try {
+                                const data = JSON.parse(event.data);
+                                const txNotification = self.parseTransactionNotification(data);
+                                if (txNotification) {
+                                    yield txNotification;
+                                }
+                            }
+                            catch (err) {
+                                console.error("Failed to parse transaction notification:", err);
+                                throw err;
                             }
                         }
-                        catch (err) {
-                            console.error("Failed to parse transaction notification:", err);
-                            throw err;
+                    }
+                    catch (error) {
+                        if (signal?.aborted ||
+                            (error instanceof Error &&
+                                error.name === "AbortError")) {
+                            break;
+                        }
+                        // ignore timeout errors, they're expected when the server is not sending anything for 5 min
+                        if (isFetchTimeoutError(error)) {
+                            console.debug("Timeout error ignored");
+                            continue;
+                        }
+                        if (isEventSourceError(error)) {
+                            throw error;
                         }
+                        console.error("Transaction stream error:", error);
+                        throw error;
+                    }
+                    finally {
+                        closeIterator();
+                        iterator = null;
                     }
-                }
-                finally {
-                    signal?.removeEventListener("abort", abortHandler);
-                    eventSource.close();
                 }
             }
-            catch (error) {
-                if (error instanceof Error && error.name === "AbortError") {
-                    break;
-                }
-                // ignore timeout errors, they're expected when the server is not sending anything for 5 min
-                if (isFetchTimeoutError(error)) {
-                    console.debug("Timeout error ignored");
-                    continue;
-                }
-                console.error("Transaction stream error:", error);
-                throw error;
+            finally {
+                signal?.removeEventListener("abort", abortHandler);
+                closeIterator();
             }
-        }
+        })();
+        const origReturn = gen.return.bind(gen);
+        gen.return = (value) => {
+            closeIterator();
+            return origReturn(value);
+        };
+        return gen;
     }
     async getPendingTxs(intent) {
         const url = `${this.serverUrl}/v1/tx/pending`;