@arkade-os/sdk 0.4.18 → 0.4.20

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

@@ -1,4 +1,21 @@
 import * as bip68 from "bip68";
+import { isDescriptor, extractPubKey } from '../../identity/descriptor.js';
+/**
+ * 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 (!isDescriptor(value)) {
+        return value.toLowerCase();
+    }
+    try {
+        return extractPubKey(value).toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Convert RelativeTimelock to BIP68 sequence number.
  */
@@ -21,21 +38,46 @@ export 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.
  */
 export 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/esm/contracts/handlers/vhtlc.js

@@ -49,7 +49,8 @@ export const 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) {
@@ -98,7 +99,8 @@ export const 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/esm/identity/descriptor.js

@@ -0,0 +1,92 @@
+import { expand, networks, } from "@bitcoinerlab/descriptors-scure";
+import { hex } from "@scure/base";
+function inferNetwork(descriptor) {
+    return descriptor.includes("tpub") ? networks.testnet : 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export function extractPubKey(descriptor) {
+    if (!isDescriptor(descriptor)) {
+        return descriptor;
+    }
+    const network = inferNetwork(descriptor);
+    const expansion = 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 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.
+ */
+export function parseHDDescriptor(descriptor) {
+    if (!isDescriptor(descriptor)) {
+        return null;
+    }
+    let expansion;
+    try {
+        const network = inferNetwork(descriptor);
+        expansion = expand({ descriptor, network });
+    }
+    catch {
+        return null;
+    }
+    const key = expansion.expansionMap?.["@0"];
+    if (!key?.masterFingerprint ||
+        !key.originPath ||
+        !key.keyPath ||
+        !key.bip32) {
+        return null;
+    }
+    return {
+        fingerprint: hex.encode(key.masterFingerprint),
+        basePath: key.originPath.replace(/^\//, ""),
+        xpub: key.bip32.toBase58(),
+        derivationPath: key.keyPath.replace(/^\//, ""),
+    };
+}

package/dist/esm/identity/descriptorProvider.js

@@ -0,0 +1 @@
+export {};

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