Merge branch 'xo-engine-support' into add-article-vision-to-reality-4

Merge branch 'development' into add-article-vision-to-reality-4
Merge branch 'fix-pipeline-replacing-mermaid' into 'development'
2026-10-12 03:43:06 +00:00 · 2026-08-08 15:57:29 +00:00 · 2026-08-08 11:06:50 +00:00 · 2026-08-08 11:06:49 +00:00 · 2026-08-07 09:09:42 +00:00 · 2026-08-07 15:56:52 +09:00
19 changed files with 5764 additions and 6013 deletions
@@ -1,4 +1,4 @@
-image: node:22
+image: node:24

 # We use stages for clarity of intent, and "needs" for dependencies and sequencing.
 # "needs" should work in parallel where acceptable, and get any artifacts directly from the source step.
@@ -97,8 +97,10 @@ publish:development:
    - git config --global user.email "${GITLAB_USER_EMAIL}"
    - git config --global user.name "${GITLAB_USER_NAME}"

-    # Configure git to push with CI token
-    - git remote set-url origin "https://gitlab-ci-token:$GL_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git"
+    # Configure git to push with CI token.
+    # CI_REPOSITORY_URL uses the CI_JOB_TOKEN to form the repository URL, in the format "https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.example.com/my-group/my-project.git"
+    # The CI_JOB_TOKEN is short lived and only valid for the duration of the CI/CD job.
+    - git remote set-url origin "${CI_REPOSITORY_URL}"

    # Ensure full Git history so Lerna can detect changes
    - git fetch --unshallow
@@ -54,25 +54,26 @@
  "devDependencies": {
    "@eslint/js": "^9.10.0",
    "@types/eslint__js": "^8.42.3",
-    "@typescript-eslint/eslint-plugin": "^8.5.0",
-    "@typescript-eslint/parser": "^8.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.66.0",
+    "@typescript-eslint/parser": "^8.66.0",
    "@vitest/coverage-v8": "^3.2.4",
    "eslint": "^9.10.0",
    "eslint-config-prettier": "^8.10.0",
    "eslint-plugin-prettier": "^5.2.1",
-    "lerna": "^9.0.3",
+    "lerna": "^10.0.0",
    "madge": "^8.0.0",
    "prettier": "^3.3.3",
-    "typescript": "5.7.2",
-    "typescript-eslint": "^8.6.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.66.0",
    "vitest": "^3.2.4"
  },
  "overrides": {
-    "vitepress": {
-      "vite": "^7.1.10"
+    "nx": {
+      "brace-expansion": "5.0.9"
    },
-    "vitepress-plugin-mermaid": {
-      "vite": "^7.1.10"
+    "lerna": {
+      "js-yaml": "4.3.1",
+      "tar": "7.5.22"
    }
  }
 }
@@ -17,13 +17,13 @@
    "@monaco-editor/loader": "^1.5.0",
    "@xocash/primitives": "*",
    "@xocash/stack": "*",
-    "monaco-editor": "^0.52.2"
+    "monaco-editor": "^0.52.2",
+    "vitepress-mermaid-renderer": "^1.2.0"
  },
  "devDependencies": {
    "typedoc": "^0.28.14",
    "typedoc-plugin-markdown": "^4.3.2",
    "typedoc-vitepress-theme": "^1.1.1",
-    "vitepress": "^1.6.4",
-    "vitepress-plugin-mermaid": "^2.0.17"
+    "vitepress": "2.0.0-alpha.18"
  }
 }
@@ -1,5 +1,4 @@
 import { defineConfig } from 'vitepress';
-import { withMermaid } from 'vitepress-plugin-mermaid';
 import typedocSidebar from '../api/typedoc-sidebar.json';

 // Node imports for auto blog sidebar (works at docs/src/.vitepress)
@@ -39,8 +38,8 @@ function toPascalCase(str: string) {
    .map((word) => {
      if (word.length === 0) return '';

-      if (SPECIAL_CASES[word]) {
-        return SPECIAL_CASES[word];
+      if (word in SPECIAL_CASES) {
+        return SPECIAL_CASES[word as keyof typeof SPECIAL_CASES];
      }

      // Capitalize first letter, lowercase rest
@@ -114,210 +113,208 @@ function blogSidebar() {
 }

 // https://vitepress.dev/reference/site-config
-export default withMermaid(
-  defineConfig({
-    outDir: '../dist',
-    title: 'XO Stack',
-    description:
-      'XO Stack: Building smart applications on the Bitcoin Cash Network',
-    head: [
-      // Favicon.
-      ['link', { rel: 'icon', href: '/favicon.png' }],
-      // Basic OpenGraph tags
-      ['meta', { property: 'og:type', content: 'website' }],
-      ['meta', { property: 'og:title', content: 'XO Stack' }],
-      [
-        'meta',
-        {
-          property: 'og:description',
-          content:
-            'XO Stack: Building smart applications on the Bitcoin Cash Network',
-        },
-      ],
-      [
-        'meta',
-        {
-          property: 'og:image',
-          content: 'https://stack.xo.cash/stack-opengraph.jpg',
-        },
-      ],
-      ['meta', { property: 'og:url', content: 'https://stack.xo.cash/' }],
-
-      // Optional additional tags
-      ['meta', { property: 'og:site_name', content: 'XO Stack' }],
-
-      // Twitter Card tags (optional but recommended)
-      ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
-      ['meta', { name: 'twitter:site', content: '@yourtwitterhandle' }],
-    ],
-    themeConfig: {
-      // Set the logo
-      logo: {
-        light: '/logo-light.svg',
-        dark: '/logo-dark.svg',
+export default defineConfig({
+  outDir: '../dist',
+  title: 'XO Stack',
+  description:
+    'XO Stack: Building smart applications on the Bitcoin Cash Network',
+  head: [
+    // Favicon.
+    ['link', { rel: 'icon', href: '/favicon.png' }],
+    // Basic OpenGraph tags
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:title', content: 'XO Stack' }],
+    [
+      'meta',
+      {
+        property: 'og:description',
+        content:
+          'XO Stack: Building smart applications on the Bitcoin Cash Network',
      },
+    ],
+    [
+      'meta',
+      {
+        property: 'og:image',
+        content: 'https://stack.xo.cash/stack-opengraph.jpg',
+      },
+    ],
+    ['meta', { property: 'og:url', content: 'https://stack.xo.cash/' }],

-      // Enable search functionality.
-      // TODO: Re-enable once we release documentation.
-      /*
+    // Optional additional tags
+    ['meta', { property: 'og:site_name', content: 'XO Stack' }],
+
+    // Twitter Card tags (optional but recommended)
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+    ['meta', { name: 'twitter:site', content: '@yourtwitterhandle' }],
+  ],
+  themeConfig: {
+    // Set the logo
+    logo: {
+      light: '/logo-light.svg',
+      dark: '/logo-dark.svg',
+    },
+
+    // Enable search functionality.
+    // TODO: Re-enable once we release documentation.
+    /*
    search: {
      provider: 'local',
    },
    */

-      // https://vitepress.dev/reference/default-theme-config
-      nav: [
-        { text: 'Home', link: '/' },
-        // TODO: Re-enable once we release documentation
-        // { text: 'Documentation', link: '/quick-start' },
-        { text: 'Blog', link: '/blog' },
-        { text: 'Tools', link: '/tools/primitives' },
-        { text: 'Playground', link: '/playground' },
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      // TODO: Re-enable once we release documentation
+      // { text: 'Documentation', link: '/quick-start' },
+      { text: 'Blog', link: '/blog' },
+      { text: 'Tools', link: '/tools/primitives' },
+      { text: 'Playground', link: '/playground' },
+    ],
+
+    sidebar: {
+      // Default Side Menu.
+      '/': [
+        {
+          text: 'Guide',
+          items: [
+            { text: 'Quick Start', link: '/quick-start' },
+            { text: 'Architecture', link: '/architecture' },
+            { text: 'Best Practices', link: '/api-examples' },
+            { text: 'Contributing', link: '/contributing' },
+          ],
+        },
+        {
+          text: 'Frameworks',
+          items: [
+            { text: 'Vue', link: '/frameworks/vue' },
+            { text: 'React', link: '/frameworks/react' },
+            { text: 'Svelte', link: '/frameworks/svelte' },
+          ],
+        },
+        {
+          text: 'API',
+          items: convertNavToPascalCase(typedocSidebar),
+        },
      ],
-
-      sidebar: {
-        // Default Side Menu.
-        '/': [
-          {
-            text: 'Guide',
-            items: [
-              { text: 'Quick Start', link: '/quick-start' },
-              { text: 'Architecture', link: '/architecture' },
-              { text: 'Best Practices', link: '/api-examples' },
-              { text: 'Contributing', link: '/contributing' },
-            ],
-          },
-          {
-            text: 'Frameworks',
-            items: [
-              { text: 'Vue', link: '/frameworks/vue' },
-              { text: 'React', link: '/frameworks/react' },
-              { text: 'Svelte', link: '/frameworks/svelte' },
-            ],
-          },
-          {
-            text: 'API',
-            items: convertNavToPascalCase(typedocSidebar),
-          },
-        ],
-        // Side-menu for all routes under /tools/
-        '/tools/': [
-          {
-            text: 'XO Tools',
-            items: [
-              {
-                text: 'Primitives',
-                link: '/tools/primitives',
-                collapsed: false,
-                items: [
-                  { text: 'Address', link: '/tools/primitives#address' },
-                  {
-                    text: 'Block Header',
-                    link: '/tools/primitives#block-header',
-                  },
-                  { text: 'Bytes', link: '/tools/primitives#bytes' },
-                  {
-                    text: 'Encrypter',
-                    link: '/tools/primitives#encrypter',
-                  },
-                  {
-                    text: 'Hasher',
-                    link: '/tools/primitives#hasher',
-                  },
-                  {
-                    text: 'HD Private Node',
-                    link: '/tools/primitives#hd-private-node',
-                  },
-                  {
-                    text: 'HD Public Node',
-                    link: '/tools/primitives#hd-public-node',
-                  },
-                  {
-                    text: 'Mnemonic',
-                    link: '/tools/primitives#mnemonic',
-                  },
-                  {
-                    text: 'Private Key',
-                    link: '/tools/primitives#private-key',
-                  },
-                  {
-                    text: 'Public Key',
-                    link: '/tools/primitives#public-key',
-                  },
-                  {
-                    text: 'Satoshis',
-                    link: '/tools/primitives#satoshis',
-                  },
-                  {
-                    text: 'Script',
-                    link: '/tools/primitives#script',
-                  },
-                  {
-                    text: 'Transaction',
-                    link: '/tools/primitives#transaction',
-                  },
-                ],
-              },
-              {
-                text: 'Stack',
-                collapsed: false,
-                items: [
-                  {
-                    text: 'Blockchain',
-                    link: '/tools/stack/blockchain',
-                    items: [
-                      {
-                        text: 'Electrum',
-                        link: '/tools/stack/blockchain#electrum',
-                      },
-                    ],
-                  },
-                ],
-              },
-            ],
-          },
-        ],
-        // Blog sidebar (auto-generated)
-        '/blog/': blogSidebar(),
-      },
-
-      socialLinks: [
-        // { icon: 'github', link: 'https://gitlab.com/GeneralProtocols/xo/stack' },
-        { icon: 'x', link: 'https://x.com/xo_bitcoincash' },
+      // Side-menu for all routes under /tools/
+      '/tools/': [
+        {
+          text: 'XO Tools',
+          items: [
+            {
+              text: 'Primitives',
+              link: '/tools/primitives',
+              collapsed: false,
+              items: [
+                { text: 'Address', link: '/tools/primitives#address' },
+                {
+                  text: 'Block Header',
+                  link: '/tools/primitives#block-header',
+                },
+                { text: 'Bytes', link: '/tools/primitives#bytes' },
+                {
+                  text: 'Encrypter',
+                  link: '/tools/primitives#encrypter',
+                },
+                {
+                  text: 'Hasher',
+                  link: '/tools/primitives#hasher',
+                },
+                {
+                  text: 'HD Private Node',
+                  link: '/tools/primitives#hd-private-node',
+                },
+                {
+                  text: 'HD Public Node',
+                  link: '/tools/primitives#hd-public-node',
+                },
+                {
+                  text: 'Mnemonic',
+                  link: '/tools/primitives#mnemonic',
+                },
+                {
+                  text: 'Private Key',
+                  link: '/tools/primitives#private-key',
+                },
+                {
+                  text: 'Public Key',
+                  link: '/tools/primitives#public-key',
+                },
+                {
+                  text: 'Satoshis',
+                  link: '/tools/primitives#satoshis',
+                },
+                {
+                  text: 'Script',
+                  link: '/tools/primitives#script',
+                },
+                {
+                  text: 'Transaction',
+                  link: '/tools/primitives#transaction',
+                },
+              ],
+            },
+            {
+              text: 'Stack',
+              collapsed: false,
+              items: [
+                {
+                  text: 'Blockchain',
+                  link: '/tools/stack/blockchain',
+                  items: [
+                    {
+                      text: 'Electrum',
+                      link: '/tools/stack/blockchain#electrum',
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
      ],
-
-      // This is the outline on the right-hand side of the page.
-      outline: {
-        level: [2, 4],
-        label: 'On this page',
-      },
+      // Blog sidebar (auto-generated)
+      '/blog/': blogSidebar(),
    },

-    // Set the dev and build targets to "esnext"
-    // NOTE: We do this so that we can support top-level-await.
-    vite: {
-      esbuild: {
+    socialLinks: [
+      // { icon: 'github', link: 'https://gitlab.com/GeneralProtocols/xo/stack' },
+      { icon: 'x', link: 'https://x.com/xo_bitcoincash' },
+    ],
+
+    // This is the outline on the right-hand side of the page.
+    outline: {
+      level: [2, 4],
+      label: 'On this page',
+    },
+  },
+
+  // Set the dev and build targets to "esnext"
+  // NOTE: We do this so that we can support top-level-await.
+  vite: {
+    esbuild: {
+      target: 'esnext',
+    },
+    build: {
+      target: 'esnext',
+    },
+    optimizeDeps: {
+      esbuildOptions: {
        target: 'esnext',
      },
-      build: {
-        target: 'esnext',
-      },
-      optimizeDeps: {
-        esbuildOptions: {
-          target: 'esnext',
-        },
-      },
+    },
+    resolve: {
+      // Configure to use browser version of @xocash/stack
+      conditions: ['browser', 'import', 'module', 'default'],
+    },
+    // SSR has its own separate ssr.resolve.conditions that must be explicitly set since not follow global resolve conditions.
+    ssr: {
      resolve: {
        // Configure to use browser version of @xocash/stack
        conditions: ['browser', 'import', 'module', 'default'],
      },
-      // SSR has its own separate ssr.resolve.conditions that must be explicitly set since not follow global resolve conditions.
-      ssr: {
-        resolve: {
-          // Configure to use browser version of @xocash/stack
-          conditions: ['browser', 'import', 'module', 'default'],
-        },
-      },
    },
-  }),
-);
+  },
+});
@@ -1,15 +1,61 @@
-// https://vitepress.dev/guide/custom-theme
+import { h, nextTick, watch } from 'vue';
 import type { Theme } from 'vitepress';
+import { useData } from 'vitepress';
 import DefaultTheme from 'vitepress/theme';
 import Layout from './Layout.vue';
+
 import './style.css';
 import './custom.css';
 import './tools.css';
 import './mermaid-overrides.css';
-import './mermaid-lightbox.client';
+
+import { createMermaidRenderer } from 'vitepress-mermaid-renderer';

 export default {
  extends: DefaultTheme,
-  Layout,
-  enhanceApp({ _app, _router, _siteData }) {},
+
+  Layout: () => {
+    const { isDark, localeIndex } = useData();
+
+    const initMermaid = () => {
+      const mermaidRenderer = createMermaidRenderer({
+        theme: isDark.value ? 'dark' : 'forest',
+      });
+
+      mermaidRenderer.setToolbar({
+        showLanguageLabel: false,
+        downloadFormat: 'svg',
+        fullscreenMode: 'browser',
+        desktop: {
+          copyCode: 'enabled',
+          toggleFullscreen: 'enabled',
+          resetView: 'enabled',
+          zoomOut: 'enabled',
+          zoomIn: 'enabled',
+          zoomLevel: 'enabled',
+          download: 'enabled',
+        },
+        fullscreen: {
+          copyCode: 'disabled',
+          toggleFullscreen: 'enabled',
+          resetView: 'disabled',
+          zoomLevel: 'disabled',
+          download: 'enabled',
+        },
+      });
+    };
+
+    nextTick(initMermaid);
+
+    watch(
+      () => [isDark.value, localeIndex.value] as const,
+      () => {
+        initMermaid();
+      },
+    );
+
+    return h(Layout);
+  },
+
+  enhanceApp() {},
 } satisfies Theme;
@@ -0,0 +1,191 @@
+---
+title: 'What Makes the XO Wallet Different'
+date: 2025-12-20
+description: A big picture look at how the XO Wallet aims to change the way people interact with Bitcoin Cash apps, focusing on safety, clarity, and user control.
+author: Saqib Noor
+tags: [wallet, general audience]
+---
+
+# What Makes the XO Wallet Different?
+
+## Introduction
+
+Wallets are the primary way people interact with crypto ecosystems, from everyday value transfers to more complex decentralised applications. For Bitcoin Cash, a peer to peer electronic cash system, wallets are how people directly send, receive, and understand value without intermediaries. They are the bridge between users, apps, and the blockchain itself. Yet for all their importance, wallets have changed very little in how they help users understand what is actually happening when they interact with an app.
+
+This article explains what makes the **XO Wallet** different. It does not dive deep into technical details or code. Instead, it looks at the bigger picture: how wallets can move beyond simply signing transactions, how understanding and safety can be improved, and why this matters as Bitcoin Cash applications become more powerful and more complex.
+
+## A wallet that understands what you are doing!
+
+Most crypto wallets today are very good at one thing: signing transactions. They are much less good at understanding *why* you are signing them.
+
+When you interact with an app, a DeFi protocol, or even a simple token transfer, the wallet often shows you raw data, script hashes, or vague warnings. Users are expected to trust the app, trust the website, and hope nothing goes wrong.
+
+The XO Wallet is built around a different idea.
+
+Instead of being blind, the wallet is designed to **understand the intent of an action**, not just the bytes of a transaction.
+
+---
+
+## From Signing Transactions to Understanding Intent
+
+The key difference comes from **templates**, which act as a cornerstone of how the XO Wallet understands and verifies actions.
+
+A template is a shared description of:
+- What kind of actions are available
+- Who is involved
+- What funds or tokens are at stake
+- What rules apply
+- What state must be tracked over time
+
+Templates are not arbitrary or hidden. They are designed to be visible, reviewable, and trusted over time through auditing, reputation, and community scrutiny. This gives the wallet a reliable basis for understanding what an action is meant to do.
+
+With templates, the wallet is no longer guessing. It knows whether you are:
+- Receiving tokens
+- Locking funds into a specific contract and understanding what that contract allows
+- Opening or closing a position
+- Signing a message
+- Transferring ownership
+
+That means the wallet can explain actions in **human terms**, before you approve them, and verify that what is happening matches the intent you were shown.
+
+### Trust Once, Not Every Time
+
+A key difference between templates and traditional decentralised apps is **how often trust is required**.
+
+In today's DeFi models, users implicitly trust every website, interface update, and transaction request they interact with. This trust is granted repeatedly, often by habit rather than careful review.
+
+Templates change this dynamic.
+
+A template is something that needs to be trusted **once**, not at every interaction. Once a template has been reviewed, audited, and understood, the wallet can rely on it consistently to interpret actions, and enforce rules.
+
+This mirrors how people already think about wallets themselves. You choose a wallet carefully, then rely on it repeatedly without re-evaluating it on every transaction.
+
+Templates extend this trust model to application logic, concentrating trust into fewer, more stable components. This gives users and the community more room for scrutiny, stronger incentives for correctness, and a safer foundation than repeatedly trusting changing front ends or opaque transaction requests.
+
+---
+
+## How This Changes the Flow
+
+Instead of apps directly asking wallets to sign opaque transactions, the flow becomes structured and understandable.
+
+```mermaid
+flowchart LR
+    App --> Template
+
+    subgraph XO Wallet-Template interaction
+        Template -->|human readable intent| Wallet
+        Wallet -->|trusted source| Template
+    end
+
+    User --> Wallet
+
+    App[Application]
+    Template[Template]
+    Wallet[XO Wallet]
+    User[User]
+```
+
+The wallet is no longer a passive signer.
+It becomes an active interpreter between apps and users.
+
+---
+
+## State That Does Not Disappear
+
+A common pain point in crypto is lost context.
+
+You open a position, receive a token, or lock funds, then later:
+- Change wallets
+- Reinstall an app
+- Lose track of where the funds came from
+
+In much of today’s crypto ecosystem, users implicitly trust applications to track this state for them. The app remembers what a position represents, which coins belong to which protocol, and how everything fits together. If that app disappears, changes direction, or is no longer maintained, having the raw on chain data alone may not be enough to continue using the protocol in a meaningful way.
+
+To function properly, they often need visibility into a user’s coins, balances, and activity so they can decide what to spend, what to lock, and how to construct transactions. This requirement also pushes apps to be deeply invasive.
+
+XO approaches this differently.
+
+XO treats **state as a first class concept**, managed by the wallet itself.
+
+The wallet tracks which outputs belong to which templates, and what they represent. This allows it to:
+- Show meaningful balances
+- Restore context after a restart
+- Understand ownership over time
+- Avoid accidental loss of access
+
+Managing and preserving this state is a significant responsibility, arguably as important as private key management itself. Losing state can mean losing understanding, control, or even access, even if the underlying funds still exist.
+
+In the XO model, applications can still manage state if they choose to, but users are no longer forced to rely on them. By default, users remain self custodial not only of their keys, but of their wallet state as well, with options for secure backup, recovery, and continuity built into the wallet rather than delegated elsewhere.
+
+For users, this feels simple. For wallets, it is a major step forward.
+
+---
+
+## Clear Ownership, Clear Responsibility
+
+XO templates define ownership explicitly.
+
+Instead of vague ideas of “this UTXO belongs to you”, the wallet knows:
+- Which conditions control which output
+- What actions that ownership enables
+- What value is associated with that ownership
+
+A simple example helps make this clearer.
+
+Imagine you participate in a liquidity pool. The funds you contribute are locked into a shared pool, and the UTXO representing your position is clearly of interest to you. However, its value is not obvious in the same way as a simple coin balance. It depends on pool size, relative contributions, fees, and changing conditions over time.
+
+With templates, this ambiguity is addressed directly. The template defines what ownership means in this context. It can include built in calculations that estimate your share of the pool’s value at any given moment. The wallet can then present this information clearly, without guessing or relying on external apps to explain it.
+
+This clarity allows the wallet to:
+- Estimate balances more accurately
+- Show expected outcomes before actions
+- Prevent actions that would violate the ownership model defined by the template
+
+It also lays the groundwork for better privacy and smarter coin selection in the future, since the wallet understands not just which coins exist, but what they represent and how they should be treated.
+
+---
+
+## Designed for Normal People, Not Just Developers
+
+Although the XO wallet is powerful under the hood, the goal is not to expose complexity to the everyday user.
+
+The XO Wallet aims to:
+- Explain actions in plain language
+- Show only what matters at the right time
+- Reduce scary jargon and warnings, replace them with clarity and guides
+- Make advanced Bitcoin Cash applications feel natural to use
+
+This requires more than good engineering. It requires a thoughtful, empowering user interface that helps people feel confident, informed, and in control. To succeed, wallets must compete not only with other crypto products, but with the best experiences people already expect and demand from modern, traditional financial applications.
+
+You should not need to understand raw transaction data, unfamiliar warnings, or confusing approval screens to feel confident. A well designed wallet should feel as intuitive and dependable as any trusted financial tool, while preserving the openness and self custody that make peer to peer systems truly valuable and loved.
+
+---
+
+## A Foundation, Not Just a Product
+
+The XO Wallet is not just another wallet.
+
+It is a reference implementation of a broader idea:
+- Wallets should be active interpreters, not passive signers
+- Wallets should be smart enough to help users understand transactions in an intuitive, human way
+- Trust should be placed in well-vetted, stable templates rather than in websites, domains, or opaque front ends
+- Safety should come from clear structure and shared rules, not from blind trust in external applications
+
+In this model, decentralisation is strengthened rather than weakened. Users are less dependent on specific apps continuing to exist, and more reliant on open, reviewable definitions of intent that wallets can understand and enforce.
+
+This is how the XO Stack moves from vision to reality, one layer at a time.
+
+---
+
+## What Comes Next
+
+This post focuses on the *why*.
+
+Future articles will explore:
+- How wallets choose which templates to trust
+- How the wallet handles state
+- How different apps can interoperate safely
+- How this model supports more complex use cases without sacrificing user control
+
+The goal is simple:
+make powerful Bitcoin Cash applications usable, understandable, and safe for everyone.
@@ -0,0 +1,295 @@
+---
+title: 'Vision to Reality 4: Revving the Engine'
+date: 2026-08-05
+description: Realization of the XO vision, part 4 covering recent improvements to the XO stack and a short roadmap.
+author: Jonathan Silverblood
+tags: [templates, engine, technical audience]
+---
+
+# Vision to Reality 4: Revving the Engine
+
+This article draws up a short roadmap to set expectations for the upcoming BCH Blaze hackathon in November 2026 and covers recent improvements to the XO stack.
+
+----
+
+```mermaid
+mindmap
+  root )Responsibilities(
+
+    [INVITATIONS]
+      (Connects)
+        📱 Apps
+        👛 Wallets
+        👥 Users
+      (Coordinates)
+        ⚡ Actions
+        🧩 Variables
+        📥 Inputs
+        📤 Outputs
+
+    [TEMPLATES]
+      (Describes)
+        🧩 Variables
+        💸 Transactions
+        📥 Inputs
+        📤 Outputs
+        🏷️ Lockscripts
+      (Defines)
+          ⚡ Actions
+          💸 Transactions
+          💾 Data
+
+    [ENGINE]
+      (Generates)
+        🔑 Keys
+        🪪 Identities
+        ✉️ Invitations
+        💸 Transactions
+      (Manages)
+          🤫 Secrets
+          🧩 Variables
+          📤 Outputs
+          🏷️ Lockscripts
+```
+
+----
+
+## Roadmap
+
+### Tools and tutorials
+
+In preparation for the Blaze hackathon we are planning to release additional articles and tooling to help participants build on XO.
+
+- Publish article on high-level XO concepts
+- Publish article on best practices when making templates
+- Publish article on current tools and limitations
+- Release alpha version of a command-line or text interface wallet
+- Release alpha version of graphical XO interactive debug tool
+
+### Token Support
+
+Currently, the XO engine is only capable of working with tokens in a very limited capacity. For example, while it is possible to define token balance estimations in templates, they are currently not being used.
+
+Full token support is a target goal and is one of the key area for improvement leading up to the hackathon, with explicit support for token genesis, token minting, coin selection, balance estimation and much more.
+
+
+### Improved Naming
+
+In templates today, the words `locking script` and `locking bytecode` are mixed and the result is vagueness and inconsistency.
+
+All uses that directly refer to actual underlying bytecode will be renamed to either `lockingBytecode` or `unlockingBytecode`. Similarly, all references to `lockingScript` or `unlockingScript` will refer to named and documented entities that uses `lockingBytecode` or `unlockingBytecode` respectively in their definitions.
+
+As a result, we will also introduce an `unlockingScripts` section similar to the `lockingScripts`. Here unlocking scripts can be described properly with names, descriptions and other metadata.
+
+### Default Outputs Instead of Inheritance
+
+One of the many goals of the XO stack is to ensure that no funds are lost. To this end, we previously added data to locking scripts that allowed the engine to classify and handle unknown transactions, when those transactions have outputs to monitored locking scripts in the engine.
+
+Previously, any output to a known locking script that lacked classification by the engine, would inherit properties of the locking script and become an implicit default output.
+
+Going forward, we are making this explicit by adding a reference to an explicit default output in locking scripts and moving all related functionality to this definition.
+
+This has two big impacts. First, it makes it more explicit that a template is responsible for handling default outputs on locking scripts. Second, it encourages template authors to provide explicit names and descriptions for the default locking script and for any uncoordinated outputs that spend to it.
+
+### Events
+
+Currently, users of the XO stack have to poll for data when they need it. Going forward, we will implement proper event emission so that applications can know when new data is available. This will include all blockchain triggered changes, but also information on when the engine starts and completes state synchronization, when wallet balance estimations are updated and much more.
+
+### Improved Documentation
+
+While we are still doing early alpha releases and breaking changes are still to be expected, we will make a concentrated effort to improve the technical package documentation ahead of the BCH Blaze hackathon.
+
+This includes tutorials on how to get started, better structure on the available documentation and more practical examples.
+
+## Recent Changes
+
+A lot has happened since our last article and we have been hard at work making template, engine and tooling updates, as well as presenting at the [BCH Bliss](https://www.bliss.cash) conference.
+
+Here is a short summary of what has improved:
+
+- new BIP43 compliant derivation scheme
+- improved reservation handling
+- added expiration date on invitations and resources
+- introduce intents as a concept
+- cleared up and isolated state better
+- dynamic template roles instances
+- added simple automated coin selection
+- improved change handling with policies
+- implemented a large number of new primitive data types
+- various quality-of-life and developer experience improvements
+
+### Derivation
+
+Under the hood, a lot has changed with regards to how XO derives cryptographic keys. Previously, we used a scheme that was a variation of [BIP 44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) but that was **not** BIP44 compliant.
+
+The new derivation paths are shorter and simpler and are instead based on [BIP 43](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki):
+
+> `m/XO'/ACCOUNT_OR_TEMPLATE'/USE_CASE'/INDEX`
+
+Where `XO = 2415` and each template has its own hardened keyspace. Keys are further separated within each keyspace by a hardened `USE_CASE`.
+
+This setup isolates keys that a template author might be able to influence from keys associated with other templates, or used by the engine in various ways.
+
+For account-wide usage, the `ACCOUNT_OR_TEMPLATE` is set to 0, allowing for a non-templated keyspace, which also has hardened `USE_CASE` isolation.
+
+### Reservations
+
+When preparing to take action, the engine reserves resources that will be used by the action. This part of the code has been improved with better error reporting and more clear naming, and it is now possible for applications to reserve resources manually.
+
+Technically, the reservation has changed from being a boolean, to being `reservedBy` with a reference. Requesting a reservation for an already reserved resource returns an error.
+
+### Expirations
+
+Participation in invitations now come with expiration dates, so that reserved resources can be restored when actions are not completed within expected timeframes.
+
+Note that the expiration dates are advisory rather than enforced, and serve only to prevent permanent reservation of resources. If an action is attempted after an expiration has happened and the resources are still available, the action will still succeed.
+
+### Intents
+
+We have added a concept of reuseable intents which define the preconditions to creating resources in the engine.
+
+This allowed some work to be specified upfront with the new `generate:` keyword, rather than being inferred by the engine after a requirement has been encountered.
+
+For example, here is an intent to create a P2PKH change output:
+```ts
+{
+  output: 'changeOutput',
+  role: 'receiver',
+  generate: [ 'ownerKey' ],
+}
+```
+
+Further, this reconciles all differences between starting actions and follow-up actions, and serves as the framework for creating various structures such as locking scripts, outputs and other data.
+
+### State
+
+We have moved all state representations to only exist in outputs or locking scripts, whereas some were defined in requirements previously.
+
+Note that we are further planning to move the inherited output handling for uncoordinated outputs from the locking scripts into a referenced `defaultOutput`, which will fully move **all** templated state representation to exist only in outputs as originally intended.
+
+### Slots
+
+Templates can now specify a minimum and maximum number of instances each role requires via the `slots:` keyword.
+
+This removes the need for fixed roles and allows for arbitrary and fungible role takers, such as pledgers in fundraising campaigns or signers in multisig wallets.
+
+### Coin Selection
+
+Before automated coin selection, applications had to provide their inputs manually and the engine was only able to unlock inputs from the same template.
+
+With the initial implementation of naive coin selection, the engine can now pick coins that are selectable from any template to satisfy requirements for satoshis when performing an action.
+
+### Change
+
+In previous versions of the engine, change was not handled automatically and instead implementations had to provide the change output by hand.
+
+Note that change is a difficult concept to get right, as there are usecases that have conflicting requirements. It is easy to break user expectation when doing naive coin selection:
+
+- Spending from a multisig template and generating a singlesig change.
+- Spending from a privacy focused template and generating a non-private change.
+
+The long-term solution for this is introduction of a change policy which controls how the engine automates creation of change outputs.
+
+As a result, templates can now define a change policy if they have specific needs:
+
+```ts
+// Sets optional default values to be used with this template.
+defaults:
+{
+    change:
+    {
+        output: 'changeOutput',
+        role: 'receiver',
+    },
+}
+```
+
+The engine follows a strict order when choosing what change policy to apply, allowing for fine-grained control by the application:
+
+- `override` policy if manually provided by the application
+- `default` policy in the template linked to the spent input
+- `fallback` policy previously configured by the application
+
+*If no change policy is available, the engine will refuse to take action when change is required.*
+
+With this policy framework in place, a privacy focused wallet can guarantee that change will never go to a non-private output, either by setting an `override` policy, or by only allowing templates with acceptable privacy.
+
+At the same time, if a wallet does not have strict change requirements they can set a `fallback` policy instead, and will then use `default` policies from the templates they are spending from when available.
+
+Currently, the engine only supports the template `default` and engine `fallback` policies. The manual `override` policy will be supported soon.
+
+### Primitives
+
+A number of new primitives have been added, and all primitives are validated on construction, including new run-time validation.
+
+**New primitive: Satoshis**
+
+In various places in XO code, we used to have **bigints** for satoshi values, but this has been changed in favor of a dedicated `satoshis` primitive which additionally validates that the amount falls in reasonable ranges representable by the **CashVM**.
+
+**New primitive: Transaction Hash**
+
+We used to represent transaction hashes as strings, but this has been changed in favor of a dedicated `transaction hash` primitive.
+
+This change makes it less likely that another string is used in a place where we should be using a transaction hash, and the primitive further validates the length and format of transaction hashes.
+
+**New primitive: Extended Public Keys**
+
+Previously we used to have a single public key for each participant in an invitation, which resulted in key re-use and potential for adversaries to control what data to sign with a key, risking cryptographic information leak.
+
+By adding an `extended public key` primitive and using that in invitations, each update to an invitation now signs with a unique key. This reduces possible attack surface by removing key re-use in invitations.
+
+**New primitive: Timestamps**
+
+Representing time in script has long been a solved problem and well defined by the **CashVM**, but representing time to end-users in templates required better tooling on the engine side.
+
+By adding an `timestamp` primitive we can extend support for end-user presentation of time, starting with the `iso8601` standard formatting.
+
+```ts
+// Example CashASM demonstrating timestamp usage.
+description: 'Last seen: <myTimestamp.iso8601>',
+```
+
+## Other improvements
+
+### Passing Identifiers
+
+Previously it was required that developers pass full objects for things like `invitations` every time they needed to interact with them. This has been changed so that only identifiers are needed for items that are cached by default.
+
+```ts
+const { invitationIdentifier } = await engine.createInvitation();
+
+// Later, when signing the invitation
+await engine.signInvitiation(invitationIdentifier);
+```
+
+### Isolated Database Per-Seed.
+
+To avoid conflicts when using the same application loaded with multiple seeds, we have added database isolation on a per-seed basis.
+
+This also makes it possible to run multiple instances of the engine with different seeds, allowing multiple accounts within the same application.
+
+### Improved Invitation Handling
+
+Invitations can now be easily shared with import and export functionality, creating a flexible starting point for building transport protocols and standards for sending invitations between different wallets.
+
+To prevent possible leakage of cryptographic entropy, each step of an invitation is now signed by a unique key, rather than a shared key per-invitation.
+
+After executing an action from an invitation, the resulting `data` or `transaction` data structures are returned to the caller.
+
+### Template Validation
+
+We have improved validation prior to importing templates with both syntax and range checks, and ensured that all errors are properly reported with actionable error messages.
+
+### Applicaton State
+
+In additional to templated state, we have added support for engine and application state.
+
+This is used by the engine to remember things like how to create default receiving addresses, and can be used by applications to store things like wallet settings.
+
+### Rigorous Testing
+
+Many parts of the XO stack have significantly improved their automated testing for additional quality assurance.
+
+### P2PKH
+
+P2PKH is the current industry standard for wallets. We have continued to improve the P2PKH template with better documentation, more human language and more explicit handling.
@@ -36,20 +36,26 @@ export class Encrypter {
      ...opts,
    };

+    // Something about the browser crypto API. It needs a "clean" Uint8Array, where TS could see the construction or something
+    const cleanKey = new Uint8Array(key);
+
    // Create a key derivation key
    const keyMaterialBase = await crypto.subtle.importKey(
      'raw',
-      key,
+      cleanKey,
      'PBKDF2',
      false,
      ['deriveBits', 'deriveKey'],
    );

+    // Something about the browser crypto API. It needs a "clean" Uint8Array, where TS could see the construction or something
+    const cleanSalt = new Uint8Array(encryptionOpts.salt);
+
    // Derive the actual encryption key
    const derivedKey = await crypto.subtle.deriveKey(
      {
        name: 'PBKDF2',
-        salt: encryptionOpts.salt,
+        salt: cleanSalt,
        iterations: encryptionOpts.iterations,
        hash: 'SHA-256',
      },
@@ -87,6 +93,9 @@ export class Encrypter {
    // Generate random IV
    const iv = crypto.getRandomValues(new Uint8Array(this.opts.ivLength));

+    // Something about the browser crypto API. It needs a "clean" Uint8Array, where TS could see the construction or something
+    const cleanData = new Uint8Array(data);
+
    // Encrypt the data
    const encryptedData = await crypto.subtle.encrypt(
      {
@@ -94,7 +103,7 @@ export class Encrypter {
        iv,
      },
      this.key,
-      data,
+      cleanData,
    );

    // Combine IV and encrypted data
@@ -41,7 +41,7 @@
    "@generalprotocols/oracle-client": "^0.0.1-development.11878773826",
    "@xocash/primitives": "*",
    "async-mutex": "^0.5.0",
-    "better-sqlite3": "^11.8.1",
+    "better-sqlite3": "^13.0.3",
    "idb": "8.0.3",
    "json-to-graphql-query": "^2.3.0",
    "msgpackr": "^1.11.2",
@@ -6,10 +6,9 @@ export const MetadataRegistrySchema = z
    description: z.string().optional(),
    uris: z
      .object({
-        // Since 'icon' and 'web' are strongly recommended uri identifiers(https://github.com/bitjson/chip-bcmr?tab=readme-ov-file#recommended-uri-identifiers)
-        // We require it as non optional.
+        // 'icon' and 'web' are strongly recommended uri identifiers(https://github.com/bitjson/chip-bcmr?tab=readme-ov-file#recommended-uri-identifiers)
        icon: z.url(),
-        web: z.url(),
+        web: z.url().optional(),
      })
      // Allows any other keys with any values.
      .catchall(z.unknown()),
@@ -192,17 +192,17 @@ export class BlockchainElectrum extends BaseBlockchain<
  }

  async fetchUnspents(address: string) {
-    // Wait for connection to be established before attempting to subscribe.
-    // TODO: Consider doing this at a higher level.
-    if (!this.isConnected) {
-      await this.waitFor('isConnectedUpdated', (isConnected) => isConnected);
-    }
-
    // Define the cache key.
    const cacheKey = `addressUnspents.${address}`;

    // Attempt to get the address unspents from the cache or fetch them if not available.
    const addressUnspents = await this.store.getOrSet(cacheKey, async () => {
+      // Wait for connection to be established before attempting to subscribe.
+      // TODO: Consider doing this at a higher level.
+      if (!this.isConnected) {
+        await this.waitFor('isConnectedUpdated', (isConnected) => isConnected);
+      }
+
      return await fetchUnspentTransactionOutputs(
        this.electrumClient,
        address,
@@ -249,17 +249,17 @@ export class BlockchainElectrum extends BaseBlockchain<
  }

  async fetchTransaction(txHash: string) {
-    // Wait for connection to be established before attempting to subscribe.
-    // TODO: Consider doing this at a higher level.
-    if (!this.isConnected) {
-      await this.waitFor('isConnectedUpdated', (isConnected) => isConnected);
-    }
-
    // Define the cache key.
    const cacheKey = `transactions.${txHash}`;

    // Attempt to get the transaction hex from the cache or fetch it if not available.
    const transactionRaw = await this.store.getOrSet(cacheKey, async () => {
+      // Wait for connection to be established before attempting to subscribe.
+      // TODO: Consider doing this at a higher level.
+      if (!this.isConnected) {
+        await this.waitFor('isConnectedUpdated', (isConnected) => isConnected);
+      }
+
      const txHex = await fetchTransaction(this.electrumClient, txHash);
      return Transaction.fromHex(txHex).toRaw();
    });
@@ -272,17 +272,17 @@ export class BlockchainElectrum extends BaseBlockchain<
  }

  async fetchAddressHistory(address: string) {
-    // Wait for connection to be established before attempting to subscribe.
-    // TODO: Consider doing this at a higher level.
-    if (!this.isConnected) {
-      await this.waitFor('isConnectedUpdated', (isConnected) => isConnected);
-    }
-
    // Define the cache key.
    const cacheKey = `addressHistory.${address}`;

    // Attempt to get the transaction history from the cache or fetch them if not available.
    const addressHistory = await this.store.getOrSet(cacheKey, async () => {
+      // Wait for connection to be established before attempting to subscribe.
+      // TODO: Consider doing this at a higher level.
+      if (!this.isConnected) {
+        await this.waitFor('isConnectedUpdated', (isConnected) => isConnected);
+      }
+
      return await fetchHistory(this.electrumClient, address);
    });

@@ -305,17 +305,17 @@ export class BlockchainElectrum extends BaseBlockchain<
  }

  async fetchBlockHeader(blockHeight: number) {
-    // Wait for connection to be established before attempting to subscribe.
-    // TODO: Consider doing this at a higher level.
-    if (!this.isConnected) {
-      await this.waitFor('isConnectedUpdated', (isConnected) => isConnected);
-    }
-
    // Define the cache key.
    const cacheKey = `blockHeader.${blockHeight}`;

    // Attempt to get the transaction history from the cache or fetch them if not available.
    const blockHeaderRaw = await this.store.getOrSet(cacheKey, async () => {
+      // Wait for connection to be established before attempting to subscribe.
+      // TODO: Consider doing this at a higher level.
+      if (!this.isConnected) {
+        await this.waitFor('isConnectedUpdated', (isConnected) => isConnected);
+      }
+
      const headerHex = await fetchBlockHeaderFromBlockHeight(
        this.electrumClient,
        blockHeight,
@@ -333,15 +333,15 @@ export class BlockchainElectrum extends BaseBlockchain<
  // TODO: ElectrumClient provides a chainHeight property that is populated after a `blockchain.headers.subscribe` call.
  //       We may be able to leverage this side-effect to avoid fetching the chain tip.
  async fetchChainTip() {
-    // Wait for connection to be established before attempting to subscribe.
-    // TODO: Consider doing this at a higher level.
-    if (!this.isConnected) {
-      await this.waitFor('isConnectedUpdated', (isConnected) => isConnected);
-    }
-
    // If we don't currently have a block height, fetch the current chain tip.
    // NOTE: We don't use our cache here because the key will be the same and so on-boot, we will have a stale value.
    if (!this.blockHeight) {
+      // Wait for connection to be established before attempting to subscribe.
+      // TODO: Consider doing this at a higher level.
+      if (!this.isConnected) {
+        await this.waitFor('isConnectedUpdated', (isConnected) => isConnected);
+      }
+
      const chainTip = await fetchCurrentChainTip(this.electrumClient);

      this.blockHeight = chainTip.height;
@@ -15,6 +15,7 @@ export * from './wallet/index.js';
 //       For node-only providers, export these from index.node.ts.
 export * from './bcmr/bcmr-composite.js';
 export * from './bcmr/bcmr-http.js';
+export * from './bcmr/bcmr-helpers.js';
 export * from './blockchain/blockchain-electrum.js';
 export * from './blockchain/blockchain-chaingraph.js';
 export * from './storage/store-remote-http.js';
@@ -1,6 +1,11 @@
 import { BaseRates } from './base-rates.js';
 import { UUIDV7 } from '../utils/uuid.js';

+export type CachedRate = {
+  price: number;
+  timestamp: number;
+};
+
 /**
 * A composite rate adapter that combines rates from multiple rate sources
 * using a configurable policy.
@@ -13,7 +18,16 @@ export class RatesComposite extends BaseRates {
  private availablePairs: Set<string> = new Set();

  // Cache of the latest rates from each adapter
-  private rateCache: Map<string, Map<string, Map<string, number>>> = new Map();
+  /**
+   * Cache of the latest rates from each adapter
+   *
+   * The cache is a nested map of:
+   * - denominatorCode -> numeratorCode -> adapterId -> CachedRate
+   *
+   * Eg: BCH -> USD -> 1 (Oracles) -> { price: 100, timestamp: 1714857600 }
+   */
+  private rateCache: Map<string, Map<string, Map<string, CachedRate>>> =
+    new Map();

  // Off callbacks for unsubscribing from events
  private unsubscribeFunctions: Map<string, () => void> = new Map();
@@ -210,7 +224,7 @@ export class RatesComposite extends BaseRates {

    // Store the rate in the cache
    const rateMap = denomMap.get(numeratorUnitCode)!;
-    rateMap.set(adapterId, price);
+    rateMap.set(adapterId, { price, timestamp: Date.now() });

    // Add pair to available pairs
    this.availablePairs.add(`${numeratorUnitCode}/${denominatorUnitCode}`);
@@ -225,12 +239,19 @@ export class RatesComposite extends BaseRates {
      // Process each numerator currency
      for (const [numerator, rateMap] of numeratorMap.entries()) {
        // Go through our adapters in order, plucking the rate for each adapter
-        const rates = this.adapters
+        const cachedRates = this.adapters
+          // First, get the Cached rate for each adapter
          .map(({ id }) => rateMap.get(id))
-          .filter((rate) => rate !== undefined);
+          // Then, filter out any undefined rates (service is down, rate limit, etc.)
+          .filter((rate) => rate !== undefined)
+          // Then, filter out any rates that are older than the refresh interval so we don't emit stale rates
+          // it's up to the client to hold onto "stale" rates if they need them, rather than us mixing old and new rates without disclosing it.
+          .filter(
+            (rate) => rate.timestamp > Date.now() - this.refreshIntervalMs,
+          );

        // Apply policy to get combined rate
-        const combinedRate = this.policy(rates);
+        const combinedRate = this.policy(cachedRates.map(({ price }) => price));

        // Only emit if we have a valid rate
        if (combinedRate !== null) {
@@ -244,7 +265,6 @@ export class RatesComposite extends BaseRates {
    }
  }
 }
-
 export type RatesCompositePolicy = (rates: number[]) => number | null;

 /**
@@ -15,20 +15,27 @@ export type StoreEvents = {
  clear: undefined;
 };

-export abstract class BaseStorage {
+/**
+ * Abstract base class for storage implementations.
+ *
+ * @template E The events type for stores created by this storage.
+ *             Must extend StoreEvents (at least includes base events).
+ *             Defaults to StoreEvents for base type hints.
+ */
+export abstract class BaseStorage<E extends StoreEvents = StoreEvents> {
  abstract listStores(): Promise<Array<string>>;
-  abstract createStore(
+  abstract createStore<T = unknown>(
    storeName: string,
    opts: StorageOpts,
-  ): Promise<BaseStore>;
-  abstract getStore(
+  ): Promise<BaseStore<T, E>>;
+  abstract getStore<T = unknown>(
+    storeName: string,
+    opts?: StorageOpts,
+  ): Promise<BaseStore<T, E> | null>;
+  abstract createOrGetStore<T = unknown>(
    storeName: string,
    opts: StorageOpts,
-  ): Promise<BaseStore | null>;
-  abstract createOrGetStore(
-    storeName: string,
-    opts: StorageOpts,
-  ): Promise<BaseStore>;
+  ): Promise<BaseStore<T, E>>;
  abstract deleteStore(storeName: string): Promise<void>;
  abstract deleteDatabase(): Promise<void>;
 }
@@ -79,7 +86,10 @@ export type StoreValueProxy<T> = {
 * }
 * ```
 */
-export abstract class BaseStore<K = unknown> extends EventEmitter<StoreEvents> {
+export abstract class BaseStore<
+  K = unknown,
+  E extends StoreEvents = StoreEvents,
+> extends EventEmitter<E> {
  /**
   * Returns an array of all keys in the store.
   */
@@ -1,4 +1,9 @@
-import { BaseStorage, BaseStore, StorageOpts } from './base-store.js';
+import {
+  BaseStorage,
+  BaseStore,
+  StorageOpts,
+  StoreEvents,
+} from './base-store.js';
 import { SSESession } from '../utils/index.js';
 import {
  Bytes,
@@ -15,13 +20,18 @@ export type EncrptedStoreOpts = StorageOpts & {
  encrypter: Encrypter;
 };

+export type StoreRemoteHTTPEvents = StoreEvents & {
+  connected: undefined;
+  disconnected: undefined;
+};
+
 /**
 * A storage adapter for a remote storage server.
 *
 * All data sent to the server is first packed using MessagePack and then encrypted using the provided encrypter and then packed again using MessagePack.
 * The requests are signed using the provided private key and the timestamp of the request to mitigate replay attacks and to authenticate the request.
 */
-export class StorageRemoteHTTP extends BaseStorage {
+export class StorageRemoteHTTP extends BaseStorage<StoreRemoteHTTPEvents> {
  /**
   * Creates a new StorageRemoteHTTP instance.
   *
@@ -33,7 +43,7 @@ export class StorageRemoteHTTP extends BaseStorage {
    return storage;
  }

-  private stores: Map<string, StoreRemoteHTTP> = new Map();
+  private stores: Map<string, StoreRemoteHTTP<any>> = new Map();

  constructor(protected baseURL: string) {
    super();
@@ -45,7 +55,9 @@ export class StorageRemoteHTTP extends BaseStorage {
   * @param storeName The name of the store to get.
   * @returns The store or null if it does not exist.
   */
-  async getStore(storeName: string): Promise<StoreRemoteHTTP | null> {
+  async getStore<T = unknown>(
+    storeName: string,
+  ): Promise<StoreRemoteHTTP<T> | null> {
    return this.stores.get(storeName) || null;
  }

@@ -56,8 +68,11 @@ export class StorageRemoteHTTP extends BaseStorage {
   * @param opts The options for the store. This includes the private key and encrypter.
   * @returns The created store.
   */
-  async createStore(storeName: string, opts: EncrptedStoreOpts): Promise<StoreRemoteHTTP> {
-    const store = await StoreRemoteHTTP.from(
+  async createStore<T = unknown>(
+    storeName: string,
+    opts: EncrptedStoreOpts,
+  ): Promise<StoreRemoteHTTP<T>> {
+    const store = await StoreRemoteHTTP.from<T>(
      this.baseURL,
      opts.privateKey,
      opts.encrypter,
@@ -73,7 +88,10 @@ export class StorageRemoteHTTP extends BaseStorage {
   * @param opts The options for the store. This includes the private key and encrypter.
   * @returns The created or existing store.
   */
-  async createOrGetStore(storeName: string, opts: EncrptedStoreOpts): Promise<StoreRemoteHTTP> {
+  async createOrGetStore<T = unknown>(
+    storeName: string,
+    opts: EncrptedStoreOpts,
+  ): Promise<StoreRemoteHTTP<T>> {
    const store = await this.getStore(storeName);
    if (store) {
      return store;
@@ -110,12 +128,15 @@ export class StorageRemoteHTTP extends BaseStorage {
  }
 }

-export class StoreRemoteHTTP extends BaseStore {
-  static async from(
+export class StoreRemoteHTTP<T = unknown> extends BaseStore<
+  T,
+  StoreRemoteHTTPEvents
+> {
+  static async from<T = unknown>(
    baseURL: string,
    privateKey: PrivateKey,
    encrypter: Encrypter,
-  ) {
+  ): Promise<StoreRemoteHTTP<T>> {
    const store = new this(baseURL, privateKey, encrypter);

    await store.subscribeEvents();
@@ -235,6 +256,12 @@ export class StoreRemoteHTTP extends BaseStore {
        });
      },
      onReconnect: createSSESessionOptions,
+      onConnected: () => {
+        this.emit('connected', undefined);
+      },
+      onDisconnected: () => {
+        this.emit('disconnected', undefined);
+      },
      ...options,
    });
  }
@@ -270,10 +297,16 @@ export class StoreRemoteHTTP extends BaseStore {
      'X-Timestamp': timestamp.toString(),
    };

-    const requestOptions = {
+    const body = payload ? pack(payload) : pack({});
+    const bodyBuffer = new Uint8Array(body.buffer);
+
+    const requestOptions: RequestInit = {
      method: 'POST',
      headers,
-      body: payload ? pack(payload) : pack({}),
+      // Because we support the DOM types, it doesnt register this UInt8Array as an acceptable BodyInit, so we need to cast it to unknown.
+      // Could be fixed in a later version of typescript, but there are build issues atm.
+      // TODO: (not really, unless we intend to use this code) Remove the type cast.
+      body: bodyBuffer as unknown as BodyInit,
    };

    // Use the URL class to compile the full path.
@@ -0,0 +1,699 @@
+import { BaseWallet } from './base-wallet.js';
+import {
+  type TransactionTemplate,
+  type WalletBlockchain,
+  type WalletDependencies,
+} from './types.js';
+import { TransactionBuilder } from './transaction-builder.js';
+import { WalletP2PKH } from './wallet-p2pkh.js';
+
+import { type BaseStore, Activities, StoreInMemory } from '../storage/index.js';
+import { type DistributiveOmit } from '../utils/index.js';
+
+import {
+  type TokenBalances,
+  HDPrivateNode,
+  ExtMap,
+  Mnemonic,
+  calculateBalanceSats,
+  calculateBalanceTokens,
+} from '@xocash/primitives';
+
+import { binToNumberUint32LE, hexToBin } from '@bitauth/libauth';
+
+//-----------------------------------------------------------------------------
+// Constants
+//-----------------------------------------------------------------------------
+
+/**
+ * XO derivation purpose path. All XO key derivation starts from this BIP43 purpose node.
+ * This matches engine/crypto's `XO_BASE_PATH = m/2415'`.
+ */
+export const XO_PURPOSE_PATH = "m/2415'";
+
+/**
+ * Default number of consecutive empty addresses before stopping the address gap scan.
+ * If this many sequential child indexes produce addresses with no on-chain activity,
+ * we assume there are no more used keys beyond this point.
+ */
+export const XO_ADDRESS_GAP = 100;
+
+/**
+ * Template key use case index for signing and spending (e.g. Schnorr signatures, P2PKH).
+ * Matches engine/crypto's `TemplateKeyUseCase.SigningAndSpending = 0`.
+ */
+export const XO_USE_CASE_SIGNING_AND_SPENDING = 0;
+
+/**
+ * Template key use case index for encryption.
+ * Not yet implemented in engine/crypto, but we scan it for forward-compatibility.
+ * Matches engine/crypto's `AccountKeyUseCase.Encryption = 1`.
+ */
+export const XO_USE_CASE_ENCRYPTION = 1;
+
+/**
+ * All use case indexes to scan for each template.
+ * We check both so that keys derived under either use case are discovered.
+ */
+export const XO_USE_CASES = [
+  XO_USE_CASE_SIGNING_AND_SPENDING,
+  XO_USE_CASE_ENCRYPTION,
+];
+
+/**
+ * Maximum valid non-hardened BIP32 child index (2^31 - 1).
+ * Matches engine/crypto's `NON_HARDENED_INDEX_MAX`.
+ */
+const NON_HARDENED_INDEX_MAX = 0x7fffffff;
+
+/**
+ * Expected length of a template identifier hex string (32 bytes = 64 hex chars).
+ * Template identifiers are SHA-256 hashes represented as hex.
+ */
+const TEMPLATE_IDENTIFIER_HEX_LENGTH = 64;
+
+//-----------------------------------------------------------------------------
+// Types
+//-----------------------------------------------------------------------------
+
+/**
+ * Entropy sources for WalletXO. Accepts the same formats as WalletHD:
+ * a hex seed string, an extended private key, or a Mnemonic instance.
+ */
+export type WalletXOEntropy =
+  | { seed: string }
+  | { xpriv: string }
+  | { mnemonic: Mnemonic };
+
+/**
+ * Genesis data for constructing a WalletXO instance.
+ * Contains the entropy source, the list of template identifiers to scan,
+ * and an optional address gap override.
+ */
+export type WalletXOGenesisData = {
+  type: 'WalletXO';
+  templateIdentifiers: string[];
+  addressGap?: number;
+} & WalletXOEntropy;
+
+//-----------------------------------------------------------------------------
+// Utilities
+//-----------------------------------------------------------------------------
+
+/**
+ * Creates a 31-bit BIP32 non-hardened child index from a template identifier hex string.
+ * This mirrors the engine/crypto `createPathIndexFromHash` function but operates on
+ * the raw template identifier bytes directly (template identifiers are already 32-byte hashes).
+ *
+ * The algorithm reads the first 4 bytes as a little-endian uint32, then masks to 31 bits
+ * to guarantee a valid non-hardened index (0 to 2,147,483,647).
+ *
+ * @see engine/crypto/source/utils.ts - createPathIndexFromHash
+ * @param templateIdentifier - A 64-character hex string representing a 32-byte template identifier
+ * @returns Path index (31-bit unsigned integer, 0 to 2,147,483,647)
+ */
+const createPathIndexFromTemplateIdentifier = (
+  templateIdentifier: string,
+): number => {
+  // Convert the hex template identifier to raw bytes.
+  const hashBytes = hexToBin(templateIdentifier);
+
+  // Read the first 4 bytes as a little-endian uint32.
+  const uint32FirstFourBytes = binToNumberUint32LE(hashBytes.slice(0, 4));
+
+  // Mask to 31 bits to stay within the valid non-hardened index range.
+  // eslint-disable-next-line no-bitwise
+  return uint32FirstFourBytes & NON_HARDENED_INDEX_MAX;
+};
+
+//-----------------------------------------------------------------------------
+// WalletXO
+//-----------------------------------------------------------------------------
+
+/**
+ * A wallet that implements the same HD key derivation as the XO Crypto package.
+ * This allows a user to import the mnemonic used with an XO Templates wallet
+ * and then derive keys based on a template identifier.
+ *
+ * Crypto Package Reference: engine/crypto/source/derivation.ts
+ *
+ * Derivation Path: m/2415'/{templateIndex}'/{useCaseIndex}'/{childIndex}
+ *
+ * - templateIndex: derived from the first 4 bytes of the template identifier
+ *   (little-endian uint32, masked to 31 bits). This is computed via the same
+ *   algorithm as engine/crypto's `createPathIndexFromHash`.
+ * - useCaseIndex: 0 (SigningAndSpending) or 1 (Encryption). Both are scanned.
+ * - childIndex: 0..N, scanned using address gap logic to discover used keys.
+ *
+ * @example
+ *
+ * ```ts
+ * // Create a WalletXO from a mnemonic and template identifiers.
+ * const walletXO = await WalletXO.from(
+ *   { blockchain },
+ *   {
+ *     mnemonic: Mnemonic.from('abandon abandon abandon ... about'),
+ *     templateIdentifiers: ['aabb...64hexchars...'],
+ *   },
+ * );
+ *
+ * // Scan for transactions and start monitoring.
+ * await walletXO.start();
+ *
+ * // Dynamically add a new template later.
+ * await walletXO.addTemplate('ccdd...64hexchars...');
+ * ```
+ */
+export class WalletXO extends BaseWallet {
+  /**
+   * Factory method to create a new WalletXO instance with default dependencies.
+   * Fills in optional dependencies (activities, cache) with defaults if not provided.
+   *
+   * @param deps - Wallet dependencies (blockchain required, activities/cache optional)
+   * @param genesisData - Entropy source + template identifiers + optional address gap
+   * @returns A new WalletXO instance
+   */
+  static async from<T extends typeof WalletXO>(
+    this: T,
+    deps: WalletDependencies,
+    genesisData: DistributiveOmit<WalletXOGenesisData, 'type'>,
+  ) {
+    // Assign defaults if not otherwise provided.
+    const activities = deps.activities
+      ? deps.activities
+      : await Activities.from();
+    const cache = deps.cache ? deps.cache : StoreInMemory.from();
+
+    // Assemble the final dependencies with all required fields.
+    const depsFinal = {
+      activities,
+      cache,
+      blockchain: deps.blockchain,
+    };
+
+    // Return a new instance of WalletXO.
+    return new this(depsFinal, genesisData) as InstanceType<T>;
+  }
+
+  // Dependencies.
+  public readonly activities: Activities;
+  public readonly blockchain: WalletBlockchain;
+  public readonly cache: BaseStore;
+
+  // Genesis Data.
+  public readonly genesisData: WalletXOGenesisData;
+
+  /** The root HD node derived from the provided entropy source. */
+  public readonly hdPrivateNode: HDPrivateNode;
+
+  /**
+   * The XO purpose HD node at m/2415'.
+   * All template key derivations are relative to this node, matching
+   * the engine/crypto package's `derivePurposeHDNodeFromSeed` output.
+   */
+  public readonly purposeNode: HDPrivateNode;
+
+  /**
+   * Child wallets grouped by template identifier and use case index.
+   * Structure: Map<templateIdentifier, { [useCaseIndex]: WalletP2PKH[] }>
+   */
+  public wallets: Map<string, { [useCaseIndex: number]: WalletP2PKH[] }> =
+    new Map();
+
+  constructor(
+    dependencies: Required<WalletDependencies>,
+    genesisData: DistributiveOmit<WalletXOGenesisData, 'type'>,
+  ) {
+    super();
+
+    // Assign our dependencies.
+    this.activities = dependencies.activities;
+    this.blockchain = dependencies.blockchain;
+    this.cache = dependencies.cache;
+
+    // Assign our genesis data with the type discriminator.
+    this.genesisData = {
+      type: 'WalletXO',
+      ...genesisData,
+    };
+
+    // Instantiate the HDPrivateNode from the entropy source provided in genesis data.
+    if ('seed' in genesisData) {
+      this.hdPrivateNode = HDPrivateNode.fromSeed(genesisData.seed);
+    } else if ('mnemonic' in genesisData) {
+      this.hdPrivateNode = HDPrivateNode.fromMnemonic(genesisData.mnemonic);
+    } else {
+      this.hdPrivateNode = HDPrivateNode.fromXPriv(genesisData.xpriv);
+    }
+
+    // Derive the XO purpose node at m/2415'.
+    // This is the root for all template key derivations and matches the
+    // engine/crypto purposeHDNode exactly.
+    this.purposeNode = this.hdPrivateNode.derivePath(XO_PURPOSE_PATH);
+  }
+
+  /**
+   * Start the wallet by scanning all template identifiers from genesis data
+   * for used keys and then starting all derived child wallets for monitoring.
+   */
+  async start() {
+    // Get the address gap from genesis data or use the default.
+    const addressGap = this.genesisData.addressGap || XO_ADDRESS_GAP;
+
+    // Scan all templates provided in genesis data for used keys.
+    for (const templateIdentifier of this.genesisData.templateIdentifiers) {
+      await this.scanTemplate(templateIdentifier, 0, addressGap);
+    }
+
+    // Start all derived child wallets.
+    // Child wallets may already be started from deriveWalletsForUseCase,
+    // but WalletP2PKH.start() is idempotent (checks isStarted flag).
+    const startPromises: Promise<void>[] = [];
+    for (const wallet of this.getAllChildWallets()) {
+      startPromises.push(wallet.start());
+    }
+    await Promise.all(startPromises);
+  }
+
+  /**
+   * Stop monitoring all child wallets for transaction activity.
+   */
+  async stop() {
+    const stopPromises: Promise<void>[] = [];
+    for (const wallet of this.getAllChildWallets()) {
+      stopPromises.push(wallet.stop());
+    }
+    await Promise.all(stopPromises);
+  }
+
+  /**
+   * Destroy all child wallets and remove all event listeners from this wallet.
+   */
+  async destroy() {
+    const destroyPromises: Promise<void>[] = [];
+    for (const wallet of this.getAllChildWallets()) {
+      destroyPromises.push(wallet.destroy());
+    }
+    await Promise.all(destroyPromises);
+
+    this.removeAllListeners();
+  }
+
+  /**
+   * Dynamically add a new template identifier and scan for derived keys.
+   * If the template has already been added, this is a no-op.
+   *
+   * @param templateIdentifier - A 64-character hex string template identifier
+   * @throws {Error} If the template identifier is not 64 hex characters
+   */
+  async addTemplate(templateIdentifier: string) {
+    // Validate the template identifier length.
+    if (templateIdentifier.length !== TEMPLATE_IDENTIFIER_HEX_LENGTH) {
+      console.error('Template identifier must be ${TEMPLATE_IDENTIFIER_HEX_LENGTH} hex characters, got ${templateIdentifier.length}');
+      throw new Error(
+        `Template identifier must be ${TEMPLATE_IDENTIFIER_HEX_LENGTH} hex characters, got ${templateIdentifier.length}`,
+      );
+    }
+
+    // Skip if this template has already been added.
+    if (this.wallets.has(templateIdentifier)) {
+      console.error('Template ${templateIdentifier} has already been added');
+      return;
+    }
+
+    // Determine the address gap to use for scanning.
+    const addressGap = this.genesisData.addressGap || XO_ADDRESS_GAP;
+    console.log('addressGap', addressGap);
+
+    // Scan the template for derived keys across all use cases.
+    console.log('scanning template');
+    await this.scanTemplate(templateIdentifier, 0, addressGap);
+    console.log('scanTemplate complete');
+
+    // Start all newly derived child wallets for this template.
+    const templateWallets = this.wallets.get(templateIdentifier);
+    if (templateWallets) {
+      const startPromises: Promise<void>[] = [];
+      for (const useCaseWallets of Object.values(templateWallets)) {
+        for (const wallet of useCaseWallets) {
+          startPromises.push(wallet.start());
+        }
+      }
+      await Promise.all(startPromises);
+    }
+
+    this.emit('stateUpdated', null);
+  }
+
+  /**
+   * Fetch all transactions from the blockchain involving any child wallet.
+   * Results are flattened and deduplicated across all templates and use cases.
+   */
+  async getTransactions() {
+    const fetchPromises = [];
+
+    for (const wallet of this.getAllChildWallets()) {
+      fetchPromises.push(wallet.getTransactions());
+    }
+
+    const txs = await Promise.all(fetchPromises);
+
+    // Flatten and deduplicate transactions across all child wallets.
+    const txsFlattened = ExtMap.flatten(txs);
+
+    // Emit an event to notify that transactions have been updated.
+    this.emit('transactionsUpdated', txsFlattened);
+
+    return txsFlattened;
+  }
+
+  /**
+   * Fetch all unspent outputs from the blockchain across all child wallets.
+   */
+  async getUnspents() {
+    const fetchPromises = [];
+
+    for (const wallet of this.getAllChildWallets()) {
+      fetchPromises.push(wallet.getUnspents());
+    }
+
+    const unspents = await Promise.all(fetchPromises);
+
+    return ExtMap.flatten(unspents);
+  }
+
+  /**
+   * Fetch all unspent output directives (with unlocking bytecode) across all child wallets.
+   */
+  async getUnspentDirectives() {
+    const fetchPromises = [];
+
+    for (const wallet of this.getAllChildWallets()) {
+      fetchPromises.push(wallet.getUnspentDirectives());
+    }
+
+    const unspentDirectives = await Promise.all(fetchPromises);
+
+    return ExtMap.flatten(unspentDirectives);
+  }
+
+  /**
+   * Get the total satoshi balance across all child wallets.
+   */
+  async getBalanceSats() {
+    const unspents = await this.getUnspents();
+
+    const utxos = unspents
+      .map((blockchainUTXO) => blockchainUTXO.utxo)
+      .toArray();
+
+    return calculateBalanceSats(utxos);
+  }
+
+  /**
+   * Get the total token balances across all child wallets.
+   */
+  async getBalanceTokens(): Promise<TokenBalances> {
+    const unspents = await this.getUnspents();
+
+    const utxos = unspents
+      .map((blockchainUTXO) => blockchainUTXO.utxo)
+      .toArray();
+
+    return calculateBalanceTokens(utxos);
+  }
+
+  /**
+   * Get all addresses belonging to this wallet across all templates and use cases.
+   */
+  async getAddresses() {
+    const addressPromises = [];
+
+    for (const wallet of this.getAllChildWallets()) {
+      addressPromises.push(wallet.getReceivingAddress());
+    }
+
+    const addresses = await Promise.all(addressPromises);
+
+    return ExtMap.fromArray(addresses, (address) => address.toLockscriptHex());
+  }
+
+  /**
+   * Get the default receiving address for this wallet.
+   * Returns the address of the first derived child wallet.
+   *
+   * @throws {Error} If no child wallets have been derived yet
+   */
+  async getReceivingAddress() {
+    const allWallets = this.getAllChildWallets();
+
+    if (allWallets.length === 0) {
+      throw new Error(
+        'No child wallets available. Add a template and start the wallet first.',
+      );
+    }
+
+    // Return the first child wallet's receiving address.
+    return allWallets[0].privateKey.derivePublicKey().deriveAddress();
+  }
+
+  /**
+   * Build a signed transaction using UTXOs from all child wallets.
+   * The change output is sent to the first child wallet's address.
+   *
+   * @param txTemplate - Partial transaction template with desired outputs
+   * @returns A TransactionBuilder with the compiled transaction
+   */
+  async signTransaction(
+    txTemplate: Partial<TransactionTemplate>,
+  ): Promise<TransactionBuilder> {
+    // Use the first child wallet's address as the change address.
+    const changeAddress = await this.getReceivingAddress();
+    const changeLockingBytecode = changeAddress.toLockscriptBytes();
+
+    // Gather unspent directives from all child wallets.
+    const unspents = await this.getUnspentDirectives();
+
+    // Build the transaction.
+    return TransactionBuilder.build(
+      txTemplate,
+      unspents.toArray(),
+      changeLockingBytecode,
+    );
+  }
+
+  /**
+   * Build, sign, and broadcast a transaction using UTXOs from all child wallets.
+   *
+   * @param txTemplate - Partial transaction template with desired outputs
+   * @returns The raw transaction bytes that were broadcast
+   */
+  async sendTransaction(txTemplate: Partial<TransactionTemplate>) {
+    // Generate the transaction.
+    const generatedTx = await this.signTransaction(txTemplate);
+
+    // Convert the transaction to bytes.
+    const generatedTxBytes = generatedTx.toBytes();
+
+    // Broadcast the transaction to the blockchain.
+    await this.blockchain.broadcastTransaction(generatedTxBytes);
+
+    return generatedTxBytes;
+  }
+
+  /**
+   * Derive a batch of WalletP2PKH child wallets for a specific template + use case combination.
+   * Each child wallet monitors its own address on the blockchain.
+   *
+   * The derivation path relative to the purpose node is:
+   * {templateIndex}'/{useCaseIndex}'/{childIndex}
+   *
+   * This produces identical keys to engine/crypto's `deriveUseCaseChildNode` when given
+   * the same purpose node, template index, use case index, and child index.
+   *
+   * @param templateIdentifier - The 64-char hex template identifier (used as storage key)
+   * @param templateIndex - The BIP32-compatible template index derived from the identifier
+   * @param useCaseIndex - The use case index (0 = SigningAndSpending, 1 = Encryption)
+   * @param count - Number of child wallets to derive
+   * @param startIndex - Starting child index (default 0)
+   * @returns Array of newly derived WalletP2PKH instances
+   */
+  async deriveWalletsForUseCase(
+    templateIdentifier: string,
+    templateIndex: number,
+    useCaseIndex: number,
+    count: number,
+    startIndex = 0,
+  ): Promise<WalletP2PKH[]> {
+    const newWallets: WalletP2PKH[] = [];
+
+    // Ensure the wallet storage structure exists for this template and all use cases.
+    if (!this.wallets.has(templateIdentifier)) {
+      const useCases: { [useCaseIndex: number]: WalletP2PKH[] } = {};
+      for (const uc of XO_USE_CASES) {
+        useCases[uc] = [];
+      }
+      this.wallets.set(templateIdentifier, useCases);
+    }
+
+    for (let i = 0; i < count; i++) {
+      const childIndex = startIndex + i;
+
+      // Build the relative derivation path from the purpose node.
+      // This matches engine/crypto's deriveUseCaseChildNode relative path construction:
+      // `${accountOrTemplateIndex}'/${accountOrTemplateUseCaseIndex}'/${useCaseChildIndex}`
+      const relativePath = `${templateIndex}'/${useCaseIndex}'/${childIndex}`;
+
+      // Use the full absolute path as the cache key to avoid collisions.
+      const fullPath = `${XO_PURPOSE_PATH}/${relativePath}`;
+
+      // Derive the private key at this path. The cache avoids re-deriving the same key.
+      const privateKeyHex = await this.cache.getOrSet(fullPath, () => {
+        const childNode = this.purposeNode.deriveRelativePath(relativePath);
+        return childNode.toPrivateKey().toHex();
+      });
+
+      // Create a child P2PKH wallet for this derived private key.
+      const wallet = await WalletP2PKH.from(
+        {
+          activities: this.activities,
+          blockchain: this.blockchain,
+          cache: this.cache,
+        },
+        { privateKey: privateKeyHex },
+      );
+
+      // Bubble up state-update events from child wallets to this parent wallet.
+      wallet.on('stateUpdated', async () => {
+        this.emit('stateUpdated', null);
+      });
+
+      // Start monitoring the child wallet's address on the blockchain.
+      await wallet.start();
+
+      newWallets.push(wallet);
+    }
+
+    // Append the newly derived wallets to the storage for this template + use case.
+    const templateWallets = this.wallets.get(templateIdentifier)!;
+    templateWallets[useCaseIndex] = [
+      ...templateWallets[useCaseIndex],
+      ...newWallets,
+    ];
+
+    return newWallets;
+  }
+
+  /**
+   * Scan a single template across all use cases using address gap logic.
+   * For each use case, derives batches of child wallets and checks their transaction
+   * history. Scanning stops for a use case when `addressGap` consecutive child indexes
+   * produce addresses with no on-chain activity.
+   *
+   * @param templateIdentifier - The 64-char hex template identifier
+   * @param startIndex - Starting child index for scanning (default 0)
+   * @param addressGap - Number of consecutive empty addresses before stopping (default XO_ADDRESS_GAP)
+   */
+  async scanTemplate(
+    templateIdentifier: string,
+    startIndex = 0,
+    addressGap = XO_ADDRESS_GAP,
+  ) {
+    // Validate the template identifier length (must be a 32-byte hex string).
+    if (templateIdentifier.length !== TEMPLATE_IDENTIFIER_HEX_LENGTH) {
+      throw new Error(
+        `Template identifier must be ${TEMPLATE_IDENTIFIER_HEX_LENGTH} hex characters, got ${templateIdentifier.length}`,
+      );
+    }
+
+    // Compute the BIP32-compatible template index from the identifier.
+    // This uses the same algorithm as engine/crypto's createPathIndexFromHash.
+    console.log('creating path index from template identifier');
+    const templateIndex =
+      createPathIndexFromTemplateIdentifier(templateIdentifier);
+    console.log('path index created');
+
+    // Scan each use case for this template (SigningAndSpending + Encryption).
+    for (const useCaseIndex of XO_USE_CASES) {
+      console.log('scanning use case', useCaseIndex);
+      let currentIndex = startIndex;
+      let emptyAddressCount = 0;
+
+      // Continue scanning until we find 'addressGap' consecutive empty addresses.
+      while (emptyAddressCount < addressGap) {
+        console.log('deriving wallets for use case', useCaseIndex);
+
+        // Derive a batch of wallets for this use case.
+        const batch = await this.deriveWalletsForUseCase(
+          templateIdentifier,
+          templateIndex,
+          useCaseIndex,
+          addressGap,
+          currentIndex,
+        );
+        console.log('batch derived', typeof batch, batch.length);
+
+        // Check the transaction history of each wallet in the batch.
+        const results = await Promise.all(
+          batch.map((wallet) => wallet.getTransactions()),
+        );
+        console.log('results', typeof results, results.length);
+
+        // Process results: reset empty count on activity, increment on empty.
+        for (let i = 0; i < results.length; i++) {
+          if (results[i].size > 0) {
+            // This address has transactions; reset the empty address counter.
+            emptyAddressCount = 0;
+          } else {
+            // This address is empty; increment the consecutive empty counter.
+            emptyAddressCount++;
+          }
+
+          currentIndex++;
+
+          // If we've hit the address gap threshold, stop scanning this use case.
+          if (emptyAddressCount >= addressGap) {
+            break;
+          }
+        }
+      }
+    }
+
+    this.emit('stateUpdated', null);
+  }
+
+  /**
+   * Collects all child WalletP2PKH instances across all templates and use cases
+   * into a single flat array. Used by aggregate methods to operate over every
+   * derived wallet uniformly.
+   *
+   * @returns Flat array of all child WalletP2PKH instances
+   */
+  private getAllChildWallets(): WalletP2PKH[] {
+    const allWallets: WalletP2PKH[] = [];
+
+    for (const templateWallets of this.wallets.values()) {
+      for (const useCaseWallets of Object.values(templateWallets)) {
+        allWallets.push(...useCaseWallets);
+      }
+    }
+
+    return allWallets;
+  }
+}
+
+//-----------------------------------------------------------------------------
+// Factory Types/Functions
+//-----------------------------------------------------------------------------
+
+export type WalletXOFactory<T extends WalletXO = WalletXO> = (
+  services: WalletDependencies,
+  genesisData: WalletXOGenesisData,
+) => Promise<T>;
+
+export async function useWalletXO<T extends WalletXO = WalletXO>(
+  services: WalletDependencies,
+  genesisData: WalletXOGenesisData,
+): Promise<T> {
+  return (await WalletXO.from(services, genesisData)) as T;
+}
@@ -4,19 +4,18 @@
 //       However, Chaingraph backend is currently broken for many queries, so let's not do this yet.

 import { beforeAll, describe, it, expect } from 'vitest';
-import {
-  BaseBlockchain,
-  BlockchainChaingraph,
-  BlockchainElectrum,
-} from '../../src/index.js';
+import { BaseBlockchain, BlockchainElectrum } from '../../src/index.js';

 const adapters: Record<
  string,
  () => Promise<BaseBlockchain<unknown, unknown>>
 > = {
-  chaingraph: async () => {
-    return await BlockchainChaingraph.from();
-  },
+  // Commenting out since the chaingraph endopoints we are hitting are currently broken.
+  // demo won't allow non-browser clients
+  // Pat's server isn't responding to block height requests correctly (or we are using an old version, which the demo server is also running).
+  // chaingraph: async () => {
+  //   return await BlockchainChaingraph.from();
+  // },
  electrum: async () => {
    return await BlockchainElectrum.from();
  },
@@ -59,7 +58,7 @@ describe.each(Object.entries(adapters))('%s Adapter', (name, createAdapter) => {
  });

  it(`${name}.fetchBlockHeader() `, async () => {
-    const result = await blockchain.fetchBlockHeader(testBlockHeight);
+    const result = await blockchain.fetchBlockHeader(1);

    expect(result).toBeDefined();
    expect(result.toHex()).toBeTypeOf('string');
@@ -6,7 +6,7 @@ import {
  monitorSyncTipsSchema,
 } from '../../src/blockchain/blockchain-chaingraph-helpers.js';

-const chaingraphServer = 'https://demo.chaingraph.cash/v1/graphql';
+const chaingraphServer = 'https://gql.chaingraph.pat.mn/v1/graphql';

 describe('GraphQLClient', () => {
  const graphQLClient = new GraphQLClient(chaingraphServer);
Author	SHA1	Message	Date
Harvmaster	8dbf98c2bc	Merge branch 'xo-engine-support' into add-article-vision-to-reality-4	2026-10-12 03:43:06 +00:00
Harvmaster	949c5df2d8	Merge branch 'development' into add-article-vision-to-reality-4	2026-08-08 15:57:29 +00:00
Emergent Reasons	e39d6508cc	Merge branch 'fix-pipeline-replacing-mermaid' into 'development' Update pipeline to Node 24. Update Lerna. Update Vitepress to Beta. Replace... See merge request GeneralProtocols/xo/stack!149	2026-08-08 11:06:50 +00:00
HarvmasterandEmergent Reasons	1c3e920c85	Update pipeline to Node 24. Update Lerna. Update Vitepress to Beta. Replace...	2026-08-08 11:06:49 +00:00
Harvmaster	c87ad46a48	Add XO Engine support	2026-08-07 09:09:42 +00:00
emergent-reasons	8875e3f5ff	recommended fixups	2026-08-07 15:56:52 +09:00
emergent-reasons	cbb223cbda	base material	2026-08-07 15:09:11 +09:00
Emergent Reasons	53b7fb3aef	Merge branch '105-fix-ci-using-expired-gitlab-token' into 'development' Resolve "Fix CI using expired Gitlab token" Closes #105 See merge request GeneralProtocols/xo/stack!147	2026-01-15 08:50:57 +00:00
HarvmasterandEmergent Reasons	a029b43fc4	Resolve "Fix CI using expired Gitlab token"	2026-01-15 08:50:57 +00:00
Emergent Reasons	f009cd31da	Merge branch '103-support-wallet-offline-mode' into 'development' Resolve "Support Wallet Offline Mode" Closes #103 See merge request GeneralProtocols/xo/stack!146	2026-01-05 12:26:11 +00:00
HarvmasterandEmergent Reasons	38dc5be0f4	Resolve "Support Wallet Offline Mode"	2026-01-05 12:26:10 +00:00
Emergent Reasons	b47a7c43ad	Merge branch 'add-high-level-xo-article' into 'development' Add high level xo article See merge request GeneralProtocols/xo/stack!145	2025-12-21 16:45:08 +00:00
Emergent Reasons	3341340933	Add high level xo article	2025-12-21 16:45:08 +00:00
Jonathan Silverblood	2ed7002ebf	Merge branch 'remote-js-yaml-as-top-level-depencency' into 'development' Remove js-yaml as a dependency of stack but keep it as child dev-dependency See merge request GeneralProtocols/xo/stack!144	2025-12-16 18:41:14 +00:00
Harvmaster	5057eb3421	Remove js-yaml as a dependency of stack but keep it as child dev-dependency	2025-12-16 22:02:23 +11:00