@arkade-os/sdk 0.4.22 → 0.4.23

package/README.md

@@ -146,19 +146,19 @@ import { mnemonicToSeedSync } from '@scure/bip39'
 const seed = mnemonicToSeedSync(mnemonic)
 const identity = SeedIdentity.fromSeed(seed)
 
-// Or with a custom output descriptor
-const identityWithDescriptor = SeedIdentity.fromSeed(seed, { descriptor })
+// Or with a custom account-descriptor template (must end in "/*)")
+const identityWithDescriptor = SeedIdentity.fromSeed(seed, { descriptor: template })
 
-// Or with a custom descriptor and passphrase (MnemonicIdentity)
+// Or with a custom template and passphrase (MnemonicIdentity)
 const identityWithDescriptorAndPassphrase = MnemonicIdentity.fromMnemonic(mnemonic, {
-  descriptor,
+  descriptor: template,
   passphrase: 'my secret passphrase'
 })
 ```
 
 #### Watch-Only with ReadonlyDescriptorIdentity
 
-Create watch-only wallets from an output descriptor:
+Create watch-only wallets from an account-descriptor template:
 
 ```typescript
 import { MnemonicIdentity, ReadonlyDescriptorIdentity, ReadonlyWallet } from '@arkade-os/sdk'
@@ -170,9 +170,9 @@ const mnemonic = generateMnemonic(wordlist)
 const identity = MnemonicIdentity.fromMnemonic(mnemonic)
 const readonly = await identity.toReadonly()
 
-// Or directly from a descriptor (e.g., from another wallet)
-const descriptor = "tr([12345678/86'/0'/0']xpub.../0/0)"
-const readonlyFromDescriptor = ReadonlyDescriptorIdentity.fromDescriptor(descriptor)
+// Or directly from a wildcard template (e.g., exported from another wallet)
+const template = "tr([12345678/86'/0'/0']xpub.../0/*)"
+const readonlyFromTemplate = ReadonlyDescriptorIdentity.fromDescriptor(template)
 
 // Use in a watch-only wallet
 const readonlyWallet = await ReadonlyWallet.create({
@@ -184,12 +184,10 @@ const readonlyWallet = await ReadonlyWallet.create({
 const balance = await readonlyWallet.getBalance()
 ```
 
-**Derivation Path:** `m/86'/{coinType}'/0'/0/0`
+**Derivation Path:** `m/86'/{coinType}'/0'/0/*`
 - BIP86 (Taproot) purpose
 - Coin type 0 for mainnet, 1 for testnet
-- Account 0, external chain, first address
-
-The descriptor format (`tr([fingerprint/path']xpub.../0/0)`) is HD-ready — future versions will support deriving multiple addresses and change outputs from the same seed.
+- Account 0, external chain, wildcard index — `identity.descriptor` is the wildcard template that drives HD rotation; consumers materialize a concrete descriptor at a specific index when they need one.
 
 ### Batch Signing for Browser Wallets
 
@@ -227,6 +225,91 @@ await wallet.send({ address: 'ark1q...', amount: 1000 })
 
 Identities without `signMultiple` continue to work unchanged — each checkpoint is signed individually via `sign()`.
 
+### Onchain Providers
+
+Wallets read onchain state (UTXOs, transactions, fee rates, chain tip) through an `OnchainProvider`. The SDK ships with two implementations and a single transport-agnostic interface so you can swap them without touching wallet code.
+
+| Provider | Transport | When to use |
+|---|---|---|
+| `EsploraProvider` | REST/HTTP (mempool.space-compatible) | Default for browser wallets, public mempool deployments, simple integrations. Both atomic 1P1C package broadcast and outspends are first-class. |
+| `ElectrumOnchainProvider` | WebSocket (Electrum protocol) | Self-hosted nodes (Fulcrum, electrs), low-latency subscriptions, environments where you control the backend. Required if you need to talk to an Electrum server directly. |
+
+If you don't pass a provider explicitly, `OnchainWallet` and `Wallet.create({ ... })` both default to `EsploraProvider` pointing at the URL in `ESPLORA_URL[networkName]`.
+
+#### Default URLs
+
+The SDK ships with reachable defaults for each network — bitcoin, signet, and mutinynet point at Ark Labs–operated deployments; testnet falls back to mempool.space; regtest assumes a local nigiri stack.
+
+```typescript
+import {
+  ESPLORA_URL,        // Record<NetworkName, string>
+  ELECTRUM_WS_URL,    // Record<NetworkName, string>
+  ELECTRUM_TCP_HOST,  // Record<NetworkName, string | null> — informational
+} from '@arkade-os/sdk'
+
+ESPLORA_URL.bitcoin       // "https://mempool.arkade.sh/api"
+ESPLORA_URL.signet        // "https://mempool.signet.arkade.sh/api"
+ESPLORA_URL.mutinynet     // "https://mempool.mutinynet.arkade.sh/api"
+
+ELECTRUM_WS_URL.bitcoin   // "wss://electrum.arkade.sh"
+ELECTRUM_WS_URL.signet    // "wss://electrum.signet.arkade.sh"
+ELECTRUM_WS_URL.mutinynet // "wss://electrum.mutinynet.arkade.sh"
+```
+
+#### Using Esplora (default)
+
+```typescript
+import { EsploraProvider, ESPLORA_URL, OnchainWallet } from '@arkade-os/sdk'
+
+// Use the default URL for the network
+const provider = new EsploraProvider(ESPLORA_URL.bitcoin)
+
+// Or pass nothing — OnchainWallet picks the default for you
+const wallet = await OnchainWallet.create(identity, 'bitcoin')
+
+// Or override with your own mempool/esplora instance
+const customProvider = new EsploraProvider('https://my-esplora.example/api')
+```
+
+#### Using Electrum (WebSocket)
+
+```typescript
+import { ElectrumWS } from 'ws-electrumx-client'
+import {
+  ElectrumOnchainProvider,
+  ELECTRUM_WS_URL,
+  OnchainWallet,
+  networks,
+} from '@arkade-os/sdk'
+
+const ws = new ElectrumWS(ELECTRUM_WS_URL.bitcoin)
+const provider = new ElectrumOnchainProvider(ws, networks.bitcoin)
+
+const wallet = await OnchainWallet.create(identity, 'bitcoin', provider)
+
+// Remember to close the connection when you're done
+await provider.close()
+```
+
+#### Atomic 1P1C package broadcast (TRUC / BIP 431)
+
+Both providers expose `broadcastTransaction(...txs)` that accepts either a single tx or a 1P1C package (parent first, child last). The package path is **atomic** — the parent doesn't have to independently meet mempool minfee, which is the point of TRUC relay.
+
+The Electrum provider implements this via `blockchain.transaction.broadcast_package` (Fulcrum ≥ 1.10 backed by bitcoind ≥ v28). **There is no fallback to sequential broadcast**: if the server doesn't support `broadcast_package`, the call surfaces a clear error so you can route through a different provider rather than have TRUC packages silently fail at the parent step. Ark Labs Fulcrum deployments at `electrum.arkade.sh` (and the `*.signet` / `*.mutinynet` variants) all support it.
+
+#### Server compatibility notes
+
+`ElectrumOnchainProvider` is built around methods supported by both **Fulcrum** and **electrs** (the two main Electrum server implementations):
+
+- ✅ `blockchain.scripthash.{listunspent, get_history, subscribe}`
+- ✅ `blockchain.transaction.{get, get_merkle, broadcast}`
+- ✅ `blockchain.block.header`, `blockchain.headers.subscribe`
+- ✅ `blockchain.estimatefee`, `blockchain.relayfee`
+- ⚠️ `blockchain.transaction.broadcast_package` — **Fulcrum-only**. Required for atomic 1P1C; the provider throws a descriptive error against electrs.
+- ❌ The provider does **not** call `blockchain.transaction.get` with `verbose=true` (Fulcrum-only and rejected by electrs); confirmation status is derived from `transaction.get_merkle` + raw block headers instead.
+
+Output amounts are derived from parsed raw transaction bytes (exact bigints), never from floating-point `value` fields — protocol-level money handling shouldn't depend on `Math.round(value * 1e8)`.
+
 ### Receiving Bitcoin
 
 ```typescript

package/dist/cjs/contracts/arkcontract.js

@@ -7,6 +7,7 @@ exports.contractFromArkContractWithAddress = contractFromArkContractWithAddress;
 exports.isArkContract = isArkContract;
 const base_1 = require("@scure/base");
 const handlers_1 = require("./handlers");
+const wallet_1 = require("../wallet");
 /**
  * Prefix for arkcontract strings.
  */
@@ -122,7 +123,7 @@ function contractFromArkContract(encoded, options = {}) {
  * @param options - Additional options
  * @returns A complete Contract object
  */
-function contractFromArkContractWithAddress(encoded, serverPubKey, addressPrefix, options = {}) {
+function contractFromArkContractWithAddress(encoded, serverPubKey, addressPrefix = wallet_1.DEFAULT_ARKADE_HRP, options = {}) {
     const parsed = decodeArkContract(encoded);
     const handler = handlers_1.contractHandlers.getOrThrow(parsed.type);
     const params = parsed.data;

package/dist/cjs/identity/descriptor.js

@@ -1,13 +1,80 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isMainnetDescriptor = isMainnetDescriptor;
+exports.descriptorIsOurs = descriptorIsOurs;
 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;
+/**
+ * True iff `descriptor` is a Bitcoin mainnet descriptor (xpub-prefixed
+ * BIP32 key).
+ *
+ * Note: testnet, signet, regtest, mutinynet, and other non-mainnet
+ * networks all share the same `tpub` BIP32 version bytes — they cannot
+ * be distinguished from one another at the descriptor level. Callers
+ * that need a `Network` constants object for `expand()` pick
+ * `networks.bitcoin` vs `networks.testnet` themselves; callers that
+ * need the *actual* network the wallet is on must track that
+ * out-of-band.
+ */
+function isMainnetDescriptor(descriptor) {
+    return !descriptor.includes("tpub");
+}
+/**
+ * Shared "does `candidate` belong to the identity backed by
+ * `ourDescriptor`?" predicate.
+ *
+ * - HD descriptors (expanding to a `bip32` key) match by account xpub
+ *   on both sides — index-agnostic, so a wildcard template and any
+ *   concrete index under it all collapse to the same xpub.
+ * - Bare `tr(pubkey)` candidates fall back to comparing the candidate
+ *   pubkey against `ourXOnlyPubkey` (the cached pubkey on the identity
+ *   side, since pulling it from `ourDescriptor` would require an index
+ *   substitution the caller already performed).
+ */
+function descriptorIsOurs(candidate, ourDescriptor, ourXOnlyPubkey) {
+    if (!isDescriptor(candidate))
+        return false;
+    try {
+        const candidateInfo = (0, descriptors_scure_1.expand)({
+            descriptor: candidate,
+            network: isMainnetDescriptor(candidate)
+                ? descriptors_scure_1.networks.bitcoin
+                : descriptors_scure_1.networks.testnet,
+        }).expansionMap?.["@0"];
+        if (!candidateInfo)
+            return false;
+        if (candidateInfo.bip32) {
+            const ourBip32 = (0, descriptors_scure_1.expand)({
+                descriptor: ourDescriptor,
+                network: isMainnetDescriptor(ourDescriptor)
+                    ? descriptors_scure_1.networks.bitcoin
+                    : descriptors_scure_1.networks.testnet,
+            }).expansionMap?.["@0"]?.bip32;
+            if (!ourBip32)
+                return false;
+            return ourBip32.toBase58() === candidateInfo.bip32.toBase58();
+        }
+        if (candidateInfo.pubkey) {
+            // For tr() the library hands back a 32-byte x-only key, but
+            // strip a leading parity byte defensively so a 33-byte
+            // compressed key (mismatched length) doesn't silently
+            // false-negative against our 32-byte x-only side.
+            const candidatePub = candidateInfo.pubkey.length === 33
+                ? candidateInfo.pubkey.subarray(1)
+                : candidateInfo.pubkey;
+            if (candidatePub.length !== ourXOnlyPubkey.length)
+                return false;
+            return base_1.hex.encode(candidatePub) === base_1.hex.encode(ourXOnlyPubkey);
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Check if a string is a descriptor of the shape `tr(...)`.
@@ -49,7 +116,9 @@ function extractPubKey(descriptor) {
     if (!isDescriptor(descriptor)) {
         return descriptor;
     }
-    const network = inferNetwork(descriptor);
+    const network = isMainnetDescriptor(descriptor)
+        ? descriptors_scure_1.networks.bitcoin
+        : descriptors_scure_1.networks.testnet;
     const expansion = (0, descriptors_scure_1.expand)({ descriptor, network });
     if (!expansion.expansionMap) {
         throw new Error("Cannot extract pubkey from descriptor: expansion failed.");
@@ -76,7 +145,9 @@ function parseHDDescriptor(descriptor) {
     }
     let expansion;
     try {
-        const network = inferNetwork(descriptor);
+        const network = isMainnetDescriptor(descriptor)
+            ? descriptors_scure_1.networks.bitcoin
+            : descriptors_scure_1.networks.testnet;
         expansion = (0, descriptors_scure_1.expand)({ descriptor, network });
     }
     catch {

package/dist/cjs/identity/hdCapableIdentity.js

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