Bitcoin indexing sample

.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep -n \"5b747eb0-b193-427b-8be8-929650171ad0\" /Users/pbroadhurst/Downloads/logs_r_8zwjuiyhqv_2026-05-12T22_33_37Z_2026-05-12T22_38_37Z.log | head -60)",
+      "Read(//Users/pbroadhurst/Downloads/**)",
+      "Bash(find /Users/pbroadhurst/dev/ffe/firefly-enterprise/btconnect -type f -name \"*.ts\" -o -name \"*.js\" -o -name \"*.json\" | head -100)",
+      "Read(//Users/pbroadhurst/dev/ffe/firefly-enterprise/**)",
+      "Bash(ls -la /Users/pbroadhurst/dev/ffe/)",
+      "Read(//Users/pbroadhurst/dev/ffe/**)"
+    ]
+  }
+}

.github/workflows/ci.yaml

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  pull_request:
+    paths:
+      - 'packages/workflow-engine-sdk/**'
+      - '.github/workflows/ci.yaml'
+
+permissions:
+  contents: read
+
+jobs:
+  sdk:
+    name: Lint, Build & Test (SDK)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/workflow-engine-sdk
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - run: npm install
+
+      - run: npm run lint
+
+      - run: npm run build
+
+      - run: npm test
+
+  template-erc20-indexer:
+    name: Build & Test (erc20-indexer template)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/workflow-engine-sdk/templates/erc20-indexer
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - name: Install SDK (local)
+        working-directory: packages/workflow-engine-sdk
+        run: npm install && npm run build
+
+      - run: npm install
+
+      - run: npm run build
+
+      - run: npm test
+
+  template-getting-started:
+    name: Build & Test (getting-started template)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/workflow-engine-sdk/templates/getting-started
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - name: Install SDK (local)
+        working-directory: packages/workflow-engine-sdk
+        run: npm install && npm run build
+
+      - run: npm install
+
+      - run: npm run build
+
+      - run: npm test

.gitignore

@@ -1,2 +1,3 @@
 **/node_modules/**
 .DS_Store
+.claude

packages/workflow-engine-sdk/eslint.config.mjs

@@ -15,7 +15,7 @@ export default [
     ignores: [
       "dist/**",
       "dist-esm/**",
-      "template/dist/**",
+      "templates/**", // separate builds
       "coverage/**",
       "node_modules/**",
       "copyright.js",

packages/workflow-engine-sdk/package.json

@@ -37,6 +37,7 @@
   "author": "Kaleido",
   "license": "Apache-2.0",
   "dependencies": {
+    "@kaleido-io/workflow-engine-sdk": "^0.9.7",
     "exponential-backoff": "^3.1.1",
     "fast-json-patch": "^3.1.1",
     "js-yaml": "^4.1.1",
@@ -90,6 +91,11 @@
       "import": "./dist-esm/src/types/evm/index.js",
       "require": "./dist/src/types/evm/index.js",
       "types": "./dist/src/types/evm/index.d.ts"
+    },
+    "./types/btc": {
+      "import": "./dist-esm/src/types/btc/index.js",
+      "require": "./dist/src/types/btc/index.js",
+      "types": "./dist/src/types/btc/index.d.ts"
     }
   }
-}
+}

packages/workflow-engine-sdk/src/client/rest-client.ts

@@ -182,9 +182,9 @@ export class WorkflowEngineRestClient {
       this.baseUrl = `https://${process.env.ACCOUNT}/endpoint/${process.env.ENVIRONMENT}/${process.env.WORKFLOW_ENGINE}/rest`;
     } else {
       let restUrl = config.url.replace(/\/ws$/, '');
-      if (!restUrl.endsWith('/rest')) {
-        restUrl += '/rest';
-      }
+      // if (!restUrl.endsWith('/rest')) {
+      //   restUrl += '/rest';
+      // }
       if (restUrl.startsWith('ws://')) {
         restUrl = restUrl.replace('ws://', 'http://');
       } else if (config.url.startsWith('wss://')) {

packages/workflow-engine-sdk/src/config/config.ts

@@ -23,6 +23,7 @@ import {
   cfgNumField,
   cfgObjField,
   parseInboundServerAddressPort,
+  cfgStringMapField,
 } from "./config_helpers";
 import { newLogger } from "../log/logger";
 import { SDKErrors, newError } from "../i18n/errors";
@@ -42,6 +43,7 @@ export const ConfigWorkflowEngineAuth = "auth";
 export const ConfigWorkflowEngineMaxRetries = "maxRetries";
 export const ConfigWorkflowEngineRetryDelay = "retryDelay";
 export const ConfigWorkflowEngineServer = "server";
+export const ConfigWorkflowEngineHeaders = "headers";
 
 /**
  * Config key names for server subsection
@@ -139,6 +141,7 @@ export interface WorkflowEngineConfig {
   workflowEngine: {
     url: string;
     auth: AuthConfig;
+    headers?: Record<string, string>;
     maxRetries?: number;
     retryDelay?: string;
   };
@@ -192,6 +195,7 @@ export class ConfigLoader {
 
     return {
       url: ConfigLoader.httpUrlToWsUrl(config.workflowEngine.url),
+      headers: config.workflowEngine.headers,
       providerName,
       options: {
         headers: {
@@ -283,6 +287,8 @@ export class ConfigLoader {
 
     const url =
       cfgStrField(section, ConfigWorkflowEngineUrl) || undefined;
+    const headers =
+      cfgStringMapField(section, ConfigWorkflowEngineHeaders) || undefined;
     const auth = section[ConfigWorkflowEngineAuth] as
       | WorkflowEngineConfig["workflowEngine"]["auth"]
       | undefined;
@@ -306,6 +312,7 @@ export class ConfigLoader {
         }
         const clientConfig: WorkflowEngineClientConfig = {
           server: serverConfig,
+          headers,
           providerName,
           maxAttempts: cfgNumField(
             section,
@@ -328,6 +335,7 @@ export class ConfigLoader {
         workflowEngine: {
           url,
           auth,
+          headers,
           maxRetries: cfgNumField(
             section,
             ConfigWorkflowEngineMaxRetries,

packages/workflow-engine-sdk/src/config/config_helpers.ts

@@ -99,6 +99,18 @@ export function cfgObjField(
   return undefined;
 }
 
+/** Plain object (not array) at record[key], or undefined. */
+export function cfgStringMapField(
+  rec: Record<string, unknown>,
+  key: string,
+): Record<string, string> | undefined {
+  const v = rec[key];
+  if (v != null && typeof v === "object" && !Array.isArray(v)) {
+    return v as Record<string, string>;
+  }
+  return undefined;
+}
+
 /** Parsed server address + port for inbound mode; undefined if invalid. */
 export function parseInboundServerAddressPort(
   server: Record<string, unknown>,

packages/workflow-engine-sdk/src/types/btc/index.ts

@@ -0,0 +1,82 @@
+// Copyright © 2026 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * TypeScript types for the event data produced by the `btcTransactions`
+ * event source handler in the Kaleido EVM Connector.
+ *
+ * Import via:
+ *   import type { BTCTransactionEvent } from '@kaleido-io/workflow-engine-sdk/types/btc';
+ */
+
+export type BlockIdentity = {
+  height: number;
+  hash: string;
+  previousblockhash?: string;
+};
+
+export type TxSummaryScriptSig = {
+  hex: string;
+  type?: string;
+  address?: string;
+};
+
+export type TxSummaryVIn = {
+  txid: string;
+  vout: number;
+  value?: number;
+  valueSat?: number;
+  scriptSig: TxSummaryScriptSig;
+  txinwitness?: string[];
+  sequence: number;
+};
+
+export type TxSummaryScriptPubKey = {
+  hex: string;
+  address?: string;
+  type: string;
+};
+
+export type TxSummaryVOut = {
+  value?: number;
+  valueSat?: number;
+  n: number;
+  scriptPubKey?: TxSummaryScriptPubKey;
+  redeemScript?: string;
+};
+
+export type TxSummary = {
+  txid: string;
+  hash: string;
+  version: number;
+  size?: number;
+  vsize?: number;
+  weight?: number;
+  locktime: number;
+  vin: TxSummaryVIn[];
+  vout: TxSummaryVOut[];
+};
+
+export type NetworkInfo = {
+  name: string;
+  net: number;
+}
+
+export type BTCTransactionEvent = {
+  network: NetworkInfo;
+  block: BlockIdentity;
+  tx: TxSummary;
+};

packages/workflow-engine-sdk/templates/btc-indexer/.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.env
+*.log