@did-btcr2/method 0.13.1

package/dist/types/utils/general.d.ts

@@ -0,0 +1,85 @@
+import { KeyBytes, HdWallet } from '@did-btcr2/common';
+import { HDKey } from '@scure/bip32';
+/**
+ * Static class of general utility functions for the did-btcr2 spec implementation
+ * @class GeneralUtils
+ * @type {GeneralUtils}
+ */
+export declare class GeneralUtils {
+    /**
+     * Helper function to encode a secp256k1 key in SchnorrSecp256k1 Multikey Format
+     * @param {KeyBytes} xOnlyKeyBytes
+     * @returns {PublicKeyMultibase}
+     */
+    static encode(xOnlyKeyBytes: KeyBytes): string;
+    /**
+     * Converts a bigint to a buffer
+     * @param {bigint} value The bigint to convert
+     * @returns {Buffer} The buffer representation of the bigint
+     */
+    static bigintToBuffer(value: bigint): Buffer;
+    /**
+     * Generates a new mnemonic phrase and HD wallet
+     * @returns {HdWallet} Promise resolving to a new hdwallet object w/ mnemonic and hdkey
+     * @throws {Error} if the public key bytes cannot be derived
+     */
+    static generateHdWallet(): Promise<HdWallet>;
+    static generateCompressedSecp256k1KeyPair(): {
+        privateKey: import("@noble/secp256k1").Bytes;
+        publicKey: import("@noble/secp256k1").Bytes;
+    };
+    /**
+     * Recovers an HDKey from a mnemonic phrase
+     * @param {string} mnemonic The mnemonic phrase to recover the HDKey from
+     * @param {Uint8Array} seed Optional seed to recover the HDKey from
+     * @returns {HDKey} Promise resolving to the recovered HDKey
+     * @throws Error if the HDKey cannot be recovered
+     */
+    static recoverHdWallet(mnemonic: string, seed?: Uint8Array): Promise<HDKey>;
+    /**
+     * Recovers a secp256k1 privateKey from its original entropy
+     * @param {Uint8Array} xorEntropy The original entropy to recover the privateKey from
+     * @param {Uint8Array} salt The salt used to tweak the privateKey
+     * @returns {Uint8Array} The recovered privateKey
+     * @throws {Error} if the privateKey cannot be recovered
+     */
+    static recoverTweakedRawPrivateKey(xorEntropy: Uint8Array, salt: Uint8Array): Uint8Array;
+    /**
+     * Recovers a secp256k1 privateKey from its original entropy
+     * @param {Uint8Array} entropy The entropy to recover the privateKey from
+     * @returns {Uint8Array} The recovered privateKey
+     * @throws {Error} if the privateKey cannot be recovered
+     */
+    static recoverRawPrivateKey(entropy: Uint8Array): Uint8Array;
+    /**
+     * Tweak the entropy with a salt using XOR
+     * @param {Uint8Array} entropy The entropy to tweak
+     * @param {Uint8Array} salt The salt to tweak the entropy with
+     * @returns {Uint8Array} The tweaked entropy
+     */
+    static XOR(entropy: Uint8Array, salt: Uint8Array): Uint8Array;
+    /**
+     * Untweak the entropy with a salt using XNOR
+     *
+     * @param {Uint8Array} tweakedEntropy The tweaked entropy to untweak
+     * @param {Uint8Array} salt The salt to untweak the entropy with
+     * @returns {Uint8Array} The original entropy
+     */
+    static XNOR(tweakedEntropy: Uint8Array, salt: Uint8Array): Uint8Array;
+    /**
+     * Recovers an HDKey from a mnemonic phrase
+     * @param {string} mnemonic The mnemonic phrase to recover the HDKey from
+     * @param {string} path The path to derive the child key from
+     * @returns {Uint8Array} Promise resolving to the recovered private key bytes
+     * @throws {Error} if the HDKey cannot be recovered
+     */
+    static recoverHdChildFromMnemonic(mnemonic: string, path: string): Promise<Uint8Array>;
+    /**
+     * Derives a child key from an HDKey
+     * @param {HDKey} hdkey The HDKey to derive the child key from
+     * @param {string} path The path to derive the child key from
+     * @returns {HDKey} A Promise resolving to the child key
+     * @throws {Error} Error if the child key cannot be derived
+     */
+    static deriveChildKey(hdkey: HDKey, path: string): HDKey;
+}

package/dist/types/utils/general.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"general.d.ts","sourceRoot":"","sources":["../../../src/utils/general.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAsC,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG3F,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAKrC;;;;GAIG;AACH,qBAAa,YAAY;IACvB;;;;OAIG;WACW,MAAM,CAAC,aAAa,EAAE,QAAQ,GAAG,MAAM;IAYrD;;;;OAIG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAK5C;;;;OAIG;WACU,gBAAgB,IAAI,OAAO,CAAC,QAAQ,CAAC;IAclD,MAAM,CAAC,kCAAkC;;;;IAQzC;;;;;;OAMG;WACU,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC;IAYjF;;;;;;OAMG;IACH,MAAM,CAAC,2BAA2B,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU;IAkBxF;;;;;OAKG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU;IAiB5D;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU;IAQ7D;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU;IAQrE;;;;;;OAMG;WACU,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAe5F;;;;;;OAMG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK;CAUzD"}

package/dist/types/utils/identifier.d.ts

@@ -0,0 +1,59 @@
+import { Bytes } from '@did-btcr2/common';
+import { SchnorrKeyPair } from '@did-btcr2/keypair';
+import { DidComponents } from './appendix.js';
+/**
+ * Implements {@link https://dcdpr.github.io/did-btcr2/#syntax | 3 Syntax}.
+ * A did:btcr2 DID consists of a did:btcr2 prefix, followed by an id-bech32 value, which is a Bech32m encoding of:
+ *    - the specification version;
+ *    - the Bitcoin network identifier; and
+ *    - either:
+ *      - a key-value representing a secp256k1 public key; or
+ *      - a hash-value representing the hash of an initiating external DID document.
+ * @class Btc1Identifier
+ * @type {Btc1Identifier}
+ */
+export declare class Btc1Identifier {
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#didbtc1-identifier-encoding | 3.2 did:btcr2 Identifier Encoding}.
+     *
+     * A did:btcr2 DID consists of a did:btcr2 prefix, followed by an id-bech32 value, which is a Bech32m encoding of:
+     *  - the specification version;
+     *  - the Bitcoin network identifier; and
+     *  - either:
+     *    - a key-value representing a secp256k1 public key; or
+     *    - a hash-value representing the hash of an initiating external DID document.
+     *
+     * @param {CreateIdentifierParams} params See {@link CreateIdentifierParams} for details.
+     * @param {Btcr2IdentifierTypes} params.idType Identifier type (key or external).
+     * @param {string} params.network Bitcoin network name.
+     * @param {number} params.version Identifier version.
+     * @param {KeyBytes | DocumentBytes} params.genesisBytes Public key or an intermediate document bytes.
+     * @returns {string} The new did:btcr2 identifier.
+     */
+    static encode({ idType, version, network, genesisBytes }: {
+        idType: string;
+        version: number;
+        network: string | number;
+        genesisBytes: Bytes;
+    }): string;
+    /**
+     * Implements {@link https://dcdpr.github.io/did-btcr2/#didbtc1-identifier-decoding | 3.3 did:btcr2 Identifier Decoding}.
+     * @param {string} identifier The BTCR2 DID to be parsed
+     * @returns {DidComponents} The parsed identifier components. See {@link DidComponents} for details.
+     * @throws {DidError} if an error occurs while parsing the identifier
+     * @throws {DidErrorCode.InvalidDid} if identifier is invalid
+     * @throws {DidErrorCode.MethodNotSupported} if the method is not supported
+     */
+    static decode(identifier: string): DidComponents;
+    /**
+     * Generates a new did:btcr2 identifier based on a newly generated key pair.
+     * @returns {string} The new did:btcr2 identifier.
+     */
+    static generate(): {
+        keys: SchnorrKeyPair;
+        identifier: {
+            controller: string;
+            id: string;
+        };
+    };
+}

package/dist/types/utils/identifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifier.d.ts","sourceRoot":"","sources":["../../../src/utils/identifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyD,KAAK,EAAqC,MAAM,mBAAmB,CAAC;AACpI,OAAO,EAAa,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;;;OAgBG;WACW,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE;QAC/D,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;QACzB,YAAY,EAAE,KAAK,CAAC;KACrB,GAAG,MAAM;IAuFV;;;;;;;OAOG;WACW,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa;IA8HvD;;;OAGG;WACW,QAAQ,IAAI;QAAE,IAAI,EAAE,cAAc,CAAC;QAAC,UAAU,EAAE;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE;CAWnG"}

package/package.json

@@ -0,0 +1,137 @@
+{
+  "name": "@did-btcr2/method",
+  "version": "0.13.1",
+  "type": "module",
+  "description": "Javascript/TypeScript reference implementation of did:btcr2 method, a censorship resistant DID Method using the Bitcoin blockchain as a Verifiable Data Registry to announce changes to the DID document. Core package of the did-btcr2-js monorepo.",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./browser": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/browser.mjs",
+      "require": "./dist/browser.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "license": "MPL-2.0",
+  "contributors": [
+    {
+      "name": "dcdpr",
+      "url": "https://github.com/dcdpr"
+    },
+    {
+      "name": "jintekc",
+      "url": "https://github.com/jintekc",
+      "email": "github@jintek.consulting"
+    }
+  ],
+  "homepage": "https://github.com/dcdpr/did-btcr2-js/tree/main/packages/method",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:dcdpr/did-btcr2-js.git",
+    "directory": "packages/method"
+  },
+  "bugs": "https://github.com/dcdpr/did-btcr2-js/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "did",
+    "dids",
+    "decentralized identity",
+    "decentralized identifiers",
+    "did method",
+    "did:btcr2",
+    "bitcoin"
+  ],
+  "dependencies": {
+    "@helia/strings": "^4.0.2",
+    "@noble/curves": "^1.8.1",
+    "@noble/hashes": "^1.5.0",
+    "@noble/secp256k1": "^2.1.0",
+    "@scure/base": "^1.1.9",
+    "@scure/bip32": "^1.5.0",
+    "@scure/bip39": "^1.4.0",
+    "@scure/btc-signer": "^1.8.1",
+    "@web5/common": "^1.1.0",
+    "@web5/crypto": "^1.0.6",
+    "@web5/dids": "^1.2.0",
+    "bitcoin-core": "^5.0.0",
+    "bitcoinjs-lib": "7.0.0-rc.0",
+    "canonicalize": "^2.1.0",
+    "dotenv": "^16.5.0",
+    "helia": "^5.2.1",
+    "multiformats": "^13.3.1",
+    "nostr-tools": "^2.15.0",
+    "tiny-secp256k1": "^2.2.3",
+    "@did-btcr2/common": "2.0.0",
+    "@did-btcr2/keypair": "0.5.1",
+    "@did-btcr2/cryptosuite": "3.0.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.22.0",
+    "@types/chai": "^5.0.1",
+    "@types/chai-as-promised": "^8.0.1",
+    "@types/eslint": "^9.6.1",
+    "@types/mocha": "^10.0.9",
+    "@types/node": "^22.5.4",
+    "@typescript-eslint/eslint-plugin": "^8.5.0",
+    "@typescript-eslint/parser": "^8.5.0",
+    "c8": "^10.1.2",
+    "chai": "^5.1.2",
+    "chai-as-promised": "^8.0.0",
+    "esbuild": "^0.24.2",
+    "eslint": "^9.14.0",
+    "eslint-plugin-mocha": "^10.5.0",
+    "globals": "^15.11.0",
+    "mocha": "^10.8.2",
+    "mocha-junit-reporter": "^2.2.1",
+    "node-stdlib-browser": "^1.3.1",
+    "rimraf": "^6.0.1",
+    "typedoc-plugin-markdown": "^4.7.0",
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.19.1"
+  },
+  "scripts": {
+    "clean": "rimraf dist coverage tests/compiled",
+    "clean:build": "rimraf dist",
+    "clean:tests": "rimraf coverage tests/compiled",
+    "wipe": "rimraf node_modules pnpm-lock.json",
+    "wipe:clean": "pnpm wipe && pnpm clean",
+    "wipe:install": "pnpm wipe && pnpm install",
+    "clean:install": "pnpm clean && pnpm install",
+    "wipe:clean:install": "pnpm wipe:clean && pnpm install",
+    "reinstall": "pnpm install --force",
+    "build": "pnpm clean:build && pnpm build:esm && pnpm build:cjs && pnpm build:browser",
+    "build:esm": "rimraf dist/esm dist/types && pnpm tsc -p tsconfig.json",
+    "build:cjs": "rimraf dist/cjs && tsc -p tsconfig.cjs.json && echo '{\"type\": \"commonjs\"}' > ./dist/cjs/package.json",
+    "build:browser": "rimraf dist/browser.mjs dist/browser.js && node build/bundles.js",
+    "build:tests": "pnpm clean:tests && pnpm tsc -p tests/tsconfig.json",
+    "build:docs": "typedoc --options typedoc.json",
+    "build:all": "pnpm build && pnpm build:tests && pnpm build:docs",
+    "release": "pnpm build && pnpm pack && mv *.tgz ../../release/method",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "test": "pnpm c8 mocha",
+    "test:unit": "[ -z \"$FILE_NAME\" ] && echo 'ERROR: FILE_NAME is not set' || pnpm tsx lib/test-$FILE_NAME.ts",
+    "build:test": "pnpm build && pnpm build:tests && pnpm c8 mocha",
+    "build:lint:test": "pnpm build && pnpm build:tests && pnpm lint:fix",
+    "prepublish": "pnpm build",
+    "do": "pnpm tsx",
+    "do:lib": "${PWD}/lib/run-lib.sh",
+    "do:lib:btc": "${PWD}/lib/do-lib.sh bitcoin",
+    "do:lib:btcr2": "${PWD}/lib/do-lib.sh btcr2"
+  }
+}

package/src/bitcoin/constants.ts

@@ -0,0 +1,19 @@
+export const INITIAL_BLOCK_REWARD = 50;
+export const HALVING_INTERVAL = 150;
+export const COINBASE_MATURITY_DELAY = 100;
+export const DEFAULT_RPC_CLIENT_CONFIG = {
+  network            : 'regtest',
+  host               : 'http://localhost:18443',
+  port               : 18443,
+  username           : 'polaruser',
+  password           : 'polarpass',
+  allowDefaultWallet : true,
+  version            : '28.1.0',
+};
+export const DEFAULT_REST_CLIENT_CONFIG = {
+  network : 'regtest',
+  host    : 'http://localhost:3000'
+};
+export const DEFAULT_BLOCK_CONFIRMATIONS = 7;
+export const TXIN_WITNESS_COINBASE = '0000000000000000000000000000000000000000000000000000000000000000';
+export const GENESIS_TX_ID = '4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b';

package/src/bitcoin/errors.ts

@@ -0,0 +1,10 @@
+export class BitcoinRpcError extends Error {
+  public readonly code: number | string;
+  public readonly data?: any;
+  constructor(code: number | string, message: string, data?: any) {
+    super(message);
+    this.code = code;
+    this.data = data;
+    this.name = 'BitcoinRpcError';
+  }
+}

package/src/bitcoin/index.ts

@@ -0,0 +1,154 @@
+import { Btcr2Error } from '@did-btcr2/common';
+import { networks } from 'bitcoinjs-lib';
+import { DEFAULT_REST_CLIENT_CONFIG, DEFAULT_RPC_CLIENT_CONFIG } from './constants.js';
+import { getNetwork } from './network.js';
+import BitcoinRest from './rest-client.js';
+import BitcoinRpc from './rpc-client.js';
+
+type BitcoinClientConfig = {
+  rpc: {
+    username: string;
+    password: string;
+    host: string;
+    version: string;
+    allowDefaultWallet: boolean;
+  },
+  rest?: {
+    host: string;
+    username?: string;
+    password?: string;
+  }
+};
+
+type BitcoinNetworkConfig = {
+  name: keyof AvailableNetworks;
+  rpc: BitcoinRpc;
+  rest: BitcoinRest;
+  config: BitcoinClientConfig;
+  data: networks.Network;
+};
+
+type BitcoinNetworkConfigMap = {
+  [key in keyof AvailableNetworks]?: BitcoinNetworkConfig;
+};
+
+export type AvailableNetworks = {
+  mainnet: true;
+  testnet: true;
+  signet: true;
+  mutinynet: true;
+  regtest: true;
+};
+
+/**
+ * General class to house the Bitcoin client connections, client config and various utility methods.
+ * @name Bitcoin
+ * @type {Bitcoin}
+ */
+export class Bitcoin {
+  public network: BitcoinNetworkConfig;
+  public mainnet?: BitcoinNetworkConfig;
+  public testnet?: BitcoinNetworkConfig;
+  public signet?: BitcoinNetworkConfig;
+  public mutinynet?: BitcoinNetworkConfig;
+  public regtest?: BitcoinNetworkConfig;
+
+  /**
+   * Creates an instance of the Bitcoin class.
+   * @param {BitcoinNetworkConfigMap} configs Optional configuration object for the Bitcoin client. If not provided, it will
+   * be loaded from the BITCOIN_CLIENT_CONFIG environment variables.
+   * @throws {Btcr2Error} If no configs is passed and BITCOIN_NETWORK_CONFIG is missing or invalid.
+   */
+  constructor(configs?: BitcoinNetworkConfigMap) {
+    const BITCOIN_NETWORK_CONFIG = process.env.BITCOIN_NETWORK_CONFIG ?? JSON.stringify(configs ?? {
+      regtest : {
+        rpc  : DEFAULT_RPC_CLIENT_CONFIG,
+        rest : DEFAULT_REST_CLIENT_CONFIG
+      }
+    });
+
+    if(!BITCOIN_NETWORK_CONFIG) {
+      throw new Btcr2Error(
+        'No BITCOIN_NETWORK_CONFIG available: must pass `configs` to constructor or set `BITCOIN_NETWORK_CONFIG` in env',
+        'MISSING_BITCOIN_NETWORK_CONFIG',
+        { BITCOIN_NETWORK_CONFIG }
+      );
+    }
+
+    // Check if BITCOIN_NETWORK_CONFIG is parsable JSON string
+    if (!JSON.parsable(BITCOIN_NETWORK_CONFIG)) {
+      throw new Btcr2Error(
+        'Parsing failed: malformed BITCOIN_NETWORK_CONFIG',
+        'MISSING_MALFORMED_BITCOIN_NETWORK_CONFIG',
+        { BITCOIN_NETWORK_CONFIG }
+      );
+    }
+
+    // Parse the BITCOIN_NETWORK_CONFIG
+    const networkConfigs: Record<string, BitcoinClientConfig> = JSON.parse(BITCOIN_NETWORK_CONFIG);
+
+    // Set a list of available networks
+    const networks: (keyof AvailableNetworks)[] = ['mainnet', 'testnet', 'signet', 'mutinynet', 'regtest'];
+
+    // Iterate over the networks and create the client connections
+    for (const network of networks) {
+      const networkConfig: BitcoinClientConfig = (configs?.[network] ?? networkConfigs[network]) as BitcoinClientConfig;
+      if (networkConfig) {
+        this[network] = {
+          name   : network,
+          config : networkConfig,
+          rpc    : new BitcoinRpc(networkConfig.rpc ?? DEFAULT_RPC_CLIENT_CONFIG),
+          rest   : new BitcoinRest(networkConfig.rest ?? DEFAULT_REST_CLIENT_CONFIG) ,
+          data   : getNetwork(network),
+        };
+      }
+    }
+
+    // Load and check the ACTIVE_NETWORK variable
+    const ACTIVE_NETWORK = (process.env.ACTIVE_NETWORK?.toLowerCase() ?? 'regtest') as keyof AvailableNetworks;
+    if (!ACTIVE_NETWORK) {
+      throw new Btcr2Error('Missing ACTIVE_NETWORK environment variable', 'MISSING_ACTIVE_NETWORK', { ACTIVE_NETWORK });
+    }
+
+
+    if (!this[ACTIVE_NETWORK]) {
+      throw new Btcr2Error(
+        `No configuration found for ACTIVE_NETWORK='${ACTIVE_NETWORK}'`,
+        'MISSING_CONFIG_FOR_NETWORK'
+      );
+    }
+
+    this.network = this[ACTIVE_NETWORK];
+  }
+
+  /**
+   * Converts Bitcoin (BTC) to satoshis (SAT).
+   * @param {number} btc - The amount in BTC.
+   * @returns {number} The amount in SAT.
+   */
+  public static btcToSats (btc: number): number {
+    return Math.round(btc * 1e8);
+  };
+
+  /**
+   * Converts satoshis (SAT) to Bitcoin (BTC).
+   * @param {number} sats - The amount in SAT.
+   * @returns {number} The amount in BTC.
+   */
+  public static satsToBtc (sats: number): number {
+    return sats / 1e8;
+  };
+}
+
+const connection = new Bitcoin();
+const network = connection.network;
+const bitcoin = {
+  network,
+  rest    :  {
+    transaction : network.rest.transaction,
+    block       : network.rest.block,
+    address     : network.rest.address,
+  }
+};
+
+export default bitcoin;

package/src/bitcoin/interface.ts

@@ -0,0 +1,160 @@
+import {
+  AddMultiSigAddressParams,
+  BatchOption,
+  BlockResponse,
+  BumpFeeOption,
+  BumpFeeResult,
+  ChainInfo,
+  CreateMultiSigResult,
+  CreateRawTxInputs,
+  CreateRawTxOutputs,
+  CreateWalletParams,
+  CreateWalletResult,
+  DecodedRawTransaction,
+  FeeEstimateMode,
+  FundRawTxOptions,
+  GetBlockParams,
+  MempoolInfo,
+  MiningInfo,
+  PeerInfo,
+  RawTransactionResponse,
+  ScriptDecoded,
+  ValidateAddressResult
+} from '../types/bitcoin.js';
+
+/**
+ * Interface for the Bitcoin Core RPC client.
+ */
+export interface IBitcoinRpc {
+    /** Executes multiple commands in a batch request. */
+    command?<R extends ReturnType<any>>(methods: BatchOption[]): Promise<ReadonlyArray<R>>;
+
+    /** Marks a transaction and its in-wallet descendants as abandoned, allowing their inputs to be respent. */
+    abandonTransaction(txid: string): Promise<void>;
+
+    /** Stops the current wallet rescan triggered by an RPC call, such as by an importprivkey call. */
+    abortRescan(): Promise<void>;
+
+    /** Adds a multi-signature address with n required signatures and a set of keys. */
+    addMultiSigAddress({ nrequired, keys, account }: AddMultiSigAddressParams): Promise<string>;
+
+    /** Adds a witness address for SegWit compatibility. */
+    addWitnessAddress(address: string): Promise<void>;
+
+    /** Backs up the wallet file to a specified destination. */
+    backupWallet(destination: string): Promise<void>;
+
+    /** Increases the fee of an unconfirmed transaction to improve its confirmation time. */
+    bumpFee(txid: string, options?: BumpFeeOption): Promise<BumpFeeResult>;
+
+    /** Removes all banned nodes from the ban list. */
+    clearBanned(): Promise<void>;
+
+    /** Combines multiple raw transactions into a single transaction. */
+    combineRawTransaction(txs: string[]): Promise<string>;
+
+    /** Creates a multi-signature address with n required signatures and a set of keys. */
+    createMultiSig(nrequired: number, keys: string[]): Promise<CreateMultiSigResult>;
+
+    /** Creates a raw transaction spending specified inputs to specified outputs. */
+    createRawTransaction(inputs: CreateRawTxInputs[], outputs: CreateRawTxOutputs[], locktime?: number, replacable?: boolean): Promise<string>;
+
+    /** Creates a new wallet with various optional parameters. */
+    createWallet({
+      wallet_name,
+      disable_private_keys,
+      blank,
+      passphrase,
+      avoid_reuse,
+      descriptors,
+      load_on_startup,
+    }: CreateWalletParams): Promise<CreateWalletResult>;
+
+    /** Decodes a raw transaction hex string. */
+    decodeRawTransaction(hexstring: string): Promise<DecodedRawTransaction>;
+
+    /** Decodes a hex-encoded script. */
+    decodeScript(hexstring: string): Promise<ScriptDecoded>;
+
+    /** Disconnects a node by address or node ID. */
+    disconnectNode(address?: string, nodeid?: number): Promise<void>;
+
+    /** Reveals the private key corresponding to an address. */
+    dumpPrivKey(address: string): Promise<string>;
+
+    /** Dumps all wallet keys and metadata to a file. */
+    dumpWallet(filename: string): Promise<{ filename: string }>;
+
+    /** Encrypts the wallet with a passphrase. */
+    encryptWallet(passphrase: string): Promise<void>;
+
+    /** Estimates the fee rate for a given confirmation target. */
+    estimateSmartFee(
+        conf_target: number,
+        estimate_mode?: FeeEstimateMode,
+    ): Promise<{ feerate?: number; errors?: string[]; blocks?: number }>;
+
+    /** Funds a raw transaction by adding necessary inputs and change. */
+    fundRawTransaction(
+        hexstring: string,
+        options: FundRawTxOptions,
+    ): Promise<{ hex: string; fee: number; changepos: number }>;
+
+    /** Returns the number of blocks in the longest blockchain. */
+    getBlockCount(): Promise<number>;
+
+    /** Gets the hash of a block at a given height. */
+    getBlockHash(height: number): Promise<string>;
+
+    /** Gets detailed information about a specific block. */
+    getBlock({ blockhash, height, verbosity }: GetBlockParams): Promise<BlockResponse | undefined>
+
+    /** Retrieves general blockchain state info. */
+    getBlockchainInfo(): Promise<ChainInfo>;
+
+    /** Gets the number of active connections to other nodes. */
+    getConnectionCount(): Promise<number>;
+
+    /** Gets the estimated network difficulty. */
+    getDifficulty(): Promise<number>;
+
+    /** Retrieves memory pool statistics. */
+    getMempoolInfo(): Promise<MempoolInfo>;
+
+    /** Retrieves mining statistics. */
+    getMiningInfo(): Promise<MiningInfo>;
+
+    /** Gets a new Bitcoin address for receiving payments. */
+    getNewAddress(account?: string): Promise<string>;
+
+    /** Gets detailed peer connection information. */
+    getPeerInfo(): Promise<PeerInfo[]>;
+
+    /** Sends raw transaction hex to the Bitcoin network. */
+    sendRawTransaction(
+      hexstring: string,
+      maxfeerate?: number | string,
+      maxBurnAmount?: number | string
+    ): Promise<string>;
+
+    /** Sends bitcoins to a specified address. */
+    sendToAddress(
+        address: string,
+        amount: number,
+        comment?: string,
+        comment_to?: string,
+        subtreactfeefromamount?: boolean,
+        replaceable?: boolean,
+        conf_target?: number,
+        estimate_mode?: FeeEstimateMode,
+    ): Promise<RawTransactionResponse>;
+
+    /** Validates a Bitcoin address. */
+    validateAddress(address: string): Promise<ValidateAddressResult>;
+
+    /** Verifies a signed message. */
+    verifyMessage(address: string, signature: string, message: string): Promise<boolean>;
+
+    /** Locks the wallet, requiring a passphrase to unlock. */
+    walletLock(passphrase: string, timeout: number): Promise<void>;
+}

package/src/bitcoin/network.ts

@@ -0,0 +1,17 @@
+import { networks } from 'bitcoinjs-lib';
+
+export function getNetwork(network: string): networks.Network {
+  switch (network) {
+    case 'bitcoin':
+      return networks.bitcoin;
+    case 'testnet3':
+    case 'testnet4':
+    case 'signet':
+    case 'mutinynet':
+      return networks.testnet;
+    case 'regtest':
+      return networks.regtest;
+    default:
+      throw new Error(`Unknown network "${network}"`);
+  }
+}