@mem-cash/types 0.0.1

package/README.md

@@ -0,0 +1,12 @@
+# @mem-cash/types
+
+Shared primitives, data types, and interfaces for the mem-cash monorepo.
+
+## Contents
+
+- **Primitives** -- `ScriptHash`, `Txid`, `BlockHash`, `OutpointKey` type aliases; `parseOutpointKey` validates vout as an integer in `[0, 0xFFFFFFFF]`
+- **Data types** -- `BlockHeader`, `UtxoEntry`, `HistoryEntry`, `MempoolTx`, `TransactionRecord`, `Balance`, `TokenData`
+- **Storage interfaces** -- `StorageReader`, `StorageWriter`, `Storage` for pluggable backends
+- **Merkle utilities** -- `computeTxMerkleBranch`, `computeHeaderMerkleBranch` for SPV proofs; input validation rejects empty hash lists, out-of-bounds indices, and non-32-byte hashes
+- **MTP** -- `computeMedianTimePast` (BIP113)
+- **Reject codes** -- BCHN-compatible `REJECT_INVALID`, `REJECT_NONSTANDARD`, etc.

package/dist/block.d.ts

@@ -0,0 +1,38 @@
+import type { BlockHeader, Outpoint, UtxoEntry } from "./data.js";
+import type { BlockHash, BlockHeight, OutpointKey, ScriptHash, Txid } from "./primitives.js";
+/** A single input in a processed block transaction. */
+export interface ProcessedBlockInput {
+    readonly prevOutpoint: Outpoint;
+}
+/** A single output in a processed block transaction. */
+export interface ProcessedBlockOutput {
+    readonly outpointKey: OutpointKey;
+    readonly utxo: UtxoEntry;
+}
+/** A transaction within a processed block. */
+export interface ProcessedBlockTx {
+    readonly txid: Txid;
+    readonly inputs: readonly ProcessedBlockInput[];
+    readonly outputs: readonly ProcessedBlockOutput[];
+    readonly rawHex?: string;
+    readonly fee?: bigint;
+}
+/** A fully processed block ready to be applied to storage. */
+export interface ProcessedBlock {
+    readonly height: BlockHeight;
+    readonly hash: BlockHash;
+    readonly header: BlockHeader;
+    readonly transactions: readonly ProcessedBlockTx[];
+}
+/** Info needed to undo (revert) a block. */
+export interface UndoInfo {
+    readonly height: BlockHeight;
+    readonly hash: BlockHash;
+    /** UTXOs that were created by this block (to remove on undo). */
+    readonly addedUtxos: readonly OutpointKey[];
+    /** UTXOs that were spent by this block (to restore on undo). */
+    readonly removedUtxos: readonly UtxoEntry[];
+    /** All scripthashes affected by this block. */
+    readonly affectedScriptHashes: ReadonlySet<ScriptHash>;
+}
+//# sourceMappingURL=block.d.ts.map

package/dist/block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../src/block.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE7F,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;CAChC;AAED,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CACzB;AAED,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD;AAED,4CAA4C;AAC5C,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC;IAC5C,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,SAAS,SAAS,EAAE,CAAC;IAC5C,+CAA+C;IAC/C,QAAQ,CAAC,oBAAoB,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;CACvD"}

package/dist/block.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=block.js.map

package/dist/block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block.js","sourceRoot":"","sources":["../src/block.ts"],"names":[],"mappings":""}

package/dist/data.d.ts

@@ -0,0 +1,88 @@
+import type { BlockHash, BlockHeight, OutpointKey, ScriptHash, Txid } from "./primitives.js";
+/** A specific transaction output (txid + index). */
+export interface Outpoint {
+    readonly txid: Txid;
+    readonly vout: number;
+}
+/** CashToken data attached to a UTXO. */
+export interface TokenData {
+    /** Token category (32-byte hex token id). */
+    readonly category: string;
+    /** Fungible token amount. */
+    readonly amount: bigint;
+    /** Non-fungible token data, if present. */
+    readonly nft?: {
+        readonly commitment: string;
+        readonly capability: "none" | "mutable" | "minting";
+    };
+}
+/** A confirmed or unconfirmed UTXO. */
+export interface UtxoEntry {
+    readonly outpoint: Outpoint;
+    readonly satoshis: bigint;
+    readonly scriptHash: ScriptHash;
+    /** Block height where this UTXO was created. 0 = mempool/unconfirmed. */
+    readonly height: BlockHeight;
+    /** The full locking script (scriptPubKey) for VM evaluation. */
+    readonly lockingBytecode: Uint8Array;
+    /** Whether this UTXO was created by a coinbase transaction. */
+    readonly isCoinbase?: boolean;
+    readonly tokenData?: TokenData;
+}
+/** An entry in a scripthash's transaction history. */
+export interface HistoryEntry {
+    /** Transaction hash (hex). */
+    readonly txHash: Txid;
+    /** Block height. 0 = mempool, -1 = mempool with unconfirmed parents. */
+    readonly height: number;
+    /** Fee in satoshis (only present for mempool entries). */
+    readonly fee?: bigint;
+}
+/** Confirmed + unconfirmed balance for a scripthash. */
+export interface Balance {
+    readonly confirmed: bigint;
+    readonly unconfirmed: bigint;
+}
+/** Stored transaction record. */
+export interface TransactionRecord {
+    readonly txid: Txid;
+    /** Block height. 0 = unconfirmed. */
+    readonly height: BlockHeight;
+    readonly rawHex?: string;
+    readonly fee?: bigint;
+}
+/** A block header with all standard fields. */
+export interface BlockHeader {
+    readonly hash: BlockHash;
+    readonly height: BlockHeight;
+    readonly version: number;
+    readonly prevHash: BlockHash;
+    readonly merkleRoot: string;
+    readonly timestamp: number;
+    readonly bits: number;
+    readonly nonce: number;
+    /** Raw 80-byte header as hex. */
+    readonly hex: string;
+}
+/** Per-scripthash bookkeeping within a mempool transaction. */
+export interface MempoolTxScriptHashEntry {
+    /** Outpoints spent from confirmed UTXOs. */
+    readonly confirmedSpends: readonly OutpointKey[];
+    /** Outpoints spent from other mempool UTXOs. */
+    readonly unconfirmedSpends: readonly OutpointKey[];
+    /** Outpoint keys for new outputs to this scripthash. */
+    readonly outputs: readonly OutpointKey[];
+}
+/** A transaction currently in the mempool. */
+export interface MempoolTx {
+    readonly txid: Txid;
+    readonly fee: bigint;
+    readonly size: number;
+    /** Scripthash → spend/output info for this tx. */
+    readonly entries: ReadonlyMap<ScriptHash, MempoolTxScriptHashEntry>;
+    /** Txids of mempool parents (unconfirmed inputs). */
+    readonly parents: ReadonlySet<Txid>;
+    /** Txids of mempool children (txs that spend our outputs). */
+    readonly children: ReadonlySet<Txid>;
+}
+//# sourceMappingURL=data.d.ts.map

package/dist/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":"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"}

package/dist/data.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data.js.map

package/dist/data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.js","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { ProcessedBlock, ProcessedBlockInput, ProcessedBlockOutput, ProcessedBlockTx, UndoInfo, } from "./block.js";
+export type { Balance, BlockHeader, HistoryEntry, MempoolTx, MempoolTxScriptHashEntry, Outpoint, TokenData, TransactionRecord, UtxoEntry, } from "./data.js";
+export { computeHeaderMerkleBranch, computeMerkleBranchAndRoot, computeTxMerkleBranch, } from "./merkle.js";
+export { computeMedianTimePast } from "./mtp.js";
+export { type BlockHash, type BlockHeight, makeOutpointKey, type OutpointKey, parseOutpointKey, type ScriptHash, type Txid, } from "./primitives.js";
+export { REJECT_CHECKPOINT, REJECT_DUPLICATE, REJECT_HIGHFEE, REJECT_INSUFFICIENTFEE, REJECT_INVALID, REJECT_MALFORMED, REJECT_NONSTANDARD, REJECT_OBSOLETE, } from "./rejectCodes.js";
+export type { Storage, StorageReader, StorageWriter } from "./storageInterface.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,QAAQ,GACR,MAAM,YAAY,CAAC;AAEpB,YAAY,EACX,OAAO,EACP,WAAW,EACX,YAAY,EACZ,SAAS,EACT,wBAAwB,EACxB,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,SAAS,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EACN,yBAAyB,EACzB,0BAA0B,EAC1B,qBAAqB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EACN,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,eAAe,EACf,KAAK,WAAW,EAChB,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,IAAI,GACT,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACN,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { computeHeaderMerkleBranch, computeMerkleBranchAndRoot, computeTxMerkleBranch, } from "./merkle.js";
+export { computeMedianTimePast } from "./mtp.js";
+export { makeOutpointKey, parseOutpointKey, } from "./primitives.js";
+export { REJECT_CHECKPOINT, REJECT_DUPLICATE, REJECT_HIGHFEE, REJECT_INSUFFICIENTFEE, REJECT_INVALID, REJECT_MALFORMED, REJECT_NONSTANDARD, REJECT_OBSOLETE, } from "./rejectCodes.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EACN,yBAAyB,EACzB,0BAA0B,EAC1B,qBAAqB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAGN,eAAe,EAEf,gBAAgB,GAGhB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACN,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,GACf,MAAM,kBAAkB,CAAC"}

package/dist/merkle.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Compute the merkle branch and root for a given index in a list of hashes.
+ *
+ * Hashes should be in internal byte order (little-endian, as used in Bitcoin's
+ * merkle tree computation). The returned branch and root are also in internal order.
+ *
+ * @param hashes - Array of 32-byte hashes in internal byte order
+ * @param index - Position of the target hash
+ * @returns branch (sibling hashes) and root
+ */
+export declare function computeMerkleBranchAndRoot(hashes: Uint8Array[], index: number): {
+    branch: Uint8Array[];
+    root: Uint8Array;
+};
+/**
+ * Compute the merkle branch for a transaction in a block.
+ *
+ * Takes txid hex strings in display order (big-endian, as shown in block explorers),
+ * converts to internal byte order for tree computation, then converts the branch
+ * back to display order hex strings for the protocol response.
+ *
+ * @param txids - Ordered txid hex strings (display order)
+ * @param targetTxid - The txid to compute the branch for
+ * @returns branch hashes in display-order hex and the position, or null if txid not found
+ */
+export declare function computeTxMerkleBranch(txids: string[], targetTxid: string): {
+    merkle: string[];
+    pos: number;
+} | null;
+/**
+ * Compute a merkle branch for a block header within a checkpoint range.
+ *
+ * Used by `blockchain.block.header` with cp_height parameter.
+ * Computes a merkle tree over block hashes from height 0 to cp_height (inclusive),
+ * then returns the branch proving the header at `height` is included.
+ *
+ * @param headerHashes - Block hashes (display-order hex) for heights 0..cp_height
+ * @param height - The height of the header to prove
+ * @returns branch hashes in display-order hex and the merkle root
+ */
+export declare function computeHeaderMerkleBranch(headerHashes: string[], height: number): {
+    branch: string[];
+    root: string;
+};
+//# sourceMappingURL=merkle.d.ts.map

package/dist/merkle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle.d.ts","sourceRoot":"","sources":["../src/merkle.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,UAAU,EAAE,EACpB,KAAK,EAAE,MAAM,GACX;IAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CA+C5C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,EAAE,MAAM,GAChB;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAa1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACxC,YAAY,EAAE,MAAM,EAAE,EACtB,MAAM,EAAE,MAAM,GACZ;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAUpC"}

package/dist/merkle.js

@@ -0,0 +1,114 @@
+import { binToHex, hexToBin, sha256 } from "@bitauth/libauth";
+/** Reverse a Uint8Array (returns new array). */
+function reverseBytes(bytes) {
+    const reversed = new Uint8Array(bytes.length);
+    reversed.set(bytes);
+    reversed.reverse();
+    return reversed;
+}
+/** Double-SHA256 of a Uint8Array. */
+function hash256(data) {
+    return sha256.hash(sha256.hash(data));
+}
+/** Hash a pair of 32-byte values for the merkle tree (double-SHA256 of concatenation). */
+function hashPair(a, b) {
+    const combined = new Uint8Array(64);
+    combined.set(a, 0);
+    combined.set(b, 32);
+    return hash256(combined);
+}
+/**
+ * Compute the merkle branch and root for a given index in a list of hashes.
+ *
+ * Hashes should be in internal byte order (little-endian, as used in Bitcoin's
+ * merkle tree computation). The returned branch and root are also in internal order.
+ *
+ * @param hashes - Array of 32-byte hashes in internal byte order
+ * @param index - Position of the target hash
+ * @returns branch (sibling hashes) and root
+ */
+export function computeMerkleBranchAndRoot(hashes, index) {
+    if (hashes.length === 0) {
+        throw new Error("Cannot compute merkle root for empty hash list");
+    }
+    if (index < 0 || index >= hashes.length) {
+        throw new Error(`Merkle index ${index} out of bounds for ${hashes.length} hashes`);
+    }
+    for (const hash of hashes) {
+        if (hash.length !== 32) {
+            throw new Error(`Invalid hash length: ${hash.length}, expected 32`);
+        }
+    }
+    const branch = [];
+    let level = [...hashes];
+    let idx = index;
+    while (level.length > 1) {
+        // If odd number of elements, duplicate the last one
+        if (level.length % 2 !== 0) {
+            const last = level[level.length - 1];
+            if (last)
+                level.push(last);
+        }
+        // Record the sibling of the target
+        const siblingIdx = idx ^ 1;
+        const sibling = level[siblingIdx];
+        if (sibling && siblingIdx < level.length) {
+            branch.push(sibling);
+        }
+        // Build next level
+        const nextLevel = [];
+        for (let i = 0; i < level.length; i += 2) {
+            const left = level[i];
+            const right = level[i + 1];
+            if (left && right) {
+                nextLevel.push(hashPair(left, right));
+            }
+        }
+        idx = Math.floor(idx / 2);
+        level = nextLevel;
+    }
+    return { branch, root: level[0] ?? new Uint8Array(32) };
+}
+/**
+ * Compute the merkle branch for a transaction in a block.
+ *
+ * Takes txid hex strings in display order (big-endian, as shown in block explorers),
+ * converts to internal byte order for tree computation, then converts the branch
+ * back to display order hex strings for the protocol response.
+ *
+ * @param txids - Ordered txid hex strings (display order)
+ * @param targetTxid - The txid to compute the branch for
+ * @returns branch hashes in display-order hex and the position, or null if txid not found
+ */
+export function computeTxMerkleBranch(txids, targetTxid) {
+    const index = txids.indexOf(targetTxid);
+    if (index === -1)
+        return null;
+    // Convert display-order txids to internal byte order
+    const internalHashes = txids.map((txid) => reverseBytes(hexToBin(txid)));
+    const { branch } = computeMerkleBranchAndRoot(internalHashes, index);
+    // Convert branch back to display order hex
+    const merkle = branch.map((h) => binToHex(reverseBytes(h)));
+    return { merkle, pos: index };
+}
+/**
+ * Compute a merkle branch for a block header within a checkpoint range.
+ *
+ * Used by `blockchain.block.header` with cp_height parameter.
+ * Computes a merkle tree over block hashes from height 0 to cp_height (inclusive),
+ * then returns the branch proving the header at `height` is included.
+ *
+ * @param headerHashes - Block hashes (display-order hex) for heights 0..cp_height
+ * @param height - The height of the header to prove
+ * @returns branch hashes in display-order hex and the merkle root
+ */
+export function computeHeaderMerkleBranch(headerHashes, height) {
+    // Convert display-order hashes to internal byte order
+    const internalHashes = headerHashes.map((h) => reverseBytes(hexToBin(h)));
+    const { branch, root } = computeMerkleBranchAndRoot(internalHashes, height);
+    return {
+        branch: branch.map((h) => binToHex(reverseBytes(h))),
+        root: binToHex(reverseBytes(root)),
+    };
+}
+//# sourceMappingURL=merkle.js.map

package/dist/merkle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle.js","sourceRoot":"","sources":["../src/merkle.ts"],"names":[],"mappings":"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"}

package/dist/mtp.d.ts

@@ -0,0 +1,8 @@
+import type { StorageReader } from "./storageInterface.js";
+/**
+ * Compute BIP113 Median Time Past for a given height.
+ * Returns the median of up to 11 block timestamps ending at `height`.
+ * Returns 0 if no headers are available.
+ */
+export declare function computeMedianTimePast(storage: StorageReader, height: number): number;
+//# sourceMappingURL=mtp.d.ts.map

package/dist/mtp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mtp.d.ts","sourceRoot":"","sources":["../src/mtp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAK3D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAWpF"}

package/dist/mtp.js

@@ -0,0 +1,21 @@
+/** BIP113: number of previous blocks used to compute Median Time Past. */
+const MTP_BLOCK_COUNT = 11;
+/**
+ * Compute BIP113 Median Time Past for a given height.
+ * Returns the median of up to 11 block timestamps ending at `height`.
+ * Returns 0 if no headers are available.
+ */
+export function computeMedianTimePast(storage, height) {
+    const timestamps = [];
+    for (let i = 0; i < MTP_BLOCK_COUNT && height - i >= 0; i++) {
+        const header = storage.getHeader(height - i);
+        if (header) {
+            timestamps.push(header.timestamp);
+        }
+    }
+    if (timestamps.length === 0)
+        return 0;
+    timestamps.sort((a, b) => a - b);
+    return timestamps[Math.floor(timestamps.length / 2)] ?? 0;
+}
+//# sourceMappingURL=mtp.js.map

package/dist/mtp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mtp.js","sourceRoot":"","sources":["../src/mtp.ts"],"names":[],"mappings":"AAEA,0EAA0E;AAC1E,MAAM,eAAe,GAAG,EAAE,CAAC;AAE3B;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAsB,EAAE,MAAc;IAC3E,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,IAAI,MAAM,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC7C,IAAI,MAAM,EAAE,CAAC;YACZ,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACnC,CAAC;IACF,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,OAAO,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAC3D,CAAC"}

package/dist/primitives.d.ts

@@ -0,0 +1,18 @@
+/** 64-char lowercase hex scripthash (SHA256 of output script). */
+export type ScriptHash = string;
+/** 64-char lowercase hex transaction id. */
+export type Txid = string;
+/** 64-char lowercase hex block hash. */
+export type BlockHash = string;
+/** Block height (non-negative integer). */
+export type BlockHeight = number;
+/** Canonical outpoint key: `"${txid}:${vout}"`. */
+export type OutpointKey = `${string}:${number}`;
+/** Build a canonical outpoint key from txid and output index. */
+export declare function makeOutpointKey(txid: Txid, vout: number): OutpointKey;
+/** Parse a canonical outpoint key back into txid and vout. */
+export declare function parseOutpointKey(key: OutpointKey): {
+    txid: Txid;
+    vout: number;
+};
+//# sourceMappingURL=primitives.d.ts.map

package/dist/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC,4CAA4C;AAC5C,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC;AAE1B,wCAAwC;AACxC,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,2CAA2C;AAC3C,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;AAEhD,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAErE;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAW/E"}

package/dist/primitives.js

@@ -0,0 +1,18 @@
+/** Build a canonical outpoint key from txid and output index. */
+export function makeOutpointKey(txid, vout) {
+    return `${txid}:${vout}`;
+}
+/** Parse a canonical outpoint key back into txid and vout. */
+export function parseOutpointKey(key) {
+    const lastColon = key.lastIndexOf(":");
+    const voutStr = key.slice(lastColon + 1);
+    const vout = Number(voutStr);
+    if (!Number.isInteger(vout) || vout < 0 || vout > 0xffffffff) {
+        throw new Error(`Invalid vout in outpoint key: ${voutStr}`);
+    }
+    return {
+        txid: key.slice(0, lastColon),
+        vout,
+    };
+}
+//# sourceMappingURL=primitives.js.map

package/dist/primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.js","sourceRoot":"","sources":["../src/primitives.ts"],"names":[],"mappings":"AAeA,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,IAAU,EAAE,IAAY;IACvD,OAAO,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAAC,GAAgB;IAChD,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,UAAU,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,iCAAiC,OAAO,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO;QACN,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC;QAC7B,IAAI;KACJ,CAAC;AACH,CAAC"}

package/dist/rejectCodes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * BCHN P2P reject codes (consensus/validation.h).
+ * Used to classify validation failures by severity and category.
+ */
+/** Malformed data structure. */
+export declare const REJECT_MALFORMED = 1;
+/** Network rule violation (consensus failure). */
+export declare const REJECT_INVALID = 16;
+/** Obsolete version. */
+export declare const REJECT_OBSOLETE = 17;
+/** Already known (duplicate tx/block). */
+export declare const REJECT_DUPLICATE = 18;
+/** Standard policy violation. */
+export declare const REJECT_NONSTANDARD = 64;
+/** Fee too low for relay. */
+export declare const REJECT_INSUFFICIENTFEE = 66;
+/** Conflicts with checkpoint. */
+export declare const REJECT_CHECKPOINT = 67;
+/** Absurdly high fee (internal-only, not sent over P2P). */
+export declare const REJECT_HIGHFEE = 256;
+//# sourceMappingURL=rejectCodes.d.ts.map

package/dist/rejectCodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rejectCodes.d.ts","sourceRoot":"","sources":["../src/rejectCodes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gCAAgC;AAChC,eAAO,MAAM,gBAAgB,IAAO,CAAC;AAErC,kDAAkD;AAClD,eAAO,MAAM,cAAc,KAAO,CAAC;AAEnC,wBAAwB;AACxB,eAAO,MAAM,eAAe,KAAO,CAAC;AAEpC,0CAA0C;AAC1C,eAAO,MAAM,gBAAgB,KAAO,CAAC;AAErC,iCAAiC;AACjC,eAAO,MAAM,kBAAkB,KAAO,CAAC;AAEvC,6BAA6B;AAC7B,eAAO,MAAM,sBAAsB,KAAO,CAAC;AAE3C,iCAAiC;AACjC,eAAO,MAAM,iBAAiB,KAAO,CAAC;AAEtC,4DAA4D;AAC5D,eAAO,MAAM,cAAc,MAAQ,CAAC"}

package/dist/rejectCodes.js

@@ -0,0 +1,21 @@
+/**
+ * BCHN P2P reject codes (consensus/validation.h).
+ * Used to classify validation failures by severity and category.
+ */
+/** Malformed data structure. */
+export const REJECT_MALFORMED = 0x01;
+/** Network rule violation (consensus failure). */
+export const REJECT_INVALID = 0x10;
+/** Obsolete version. */
+export const REJECT_OBSOLETE = 0x11;
+/** Already known (duplicate tx/block). */
+export const REJECT_DUPLICATE = 0x12;
+/** Standard policy violation. */
+export const REJECT_NONSTANDARD = 0x40;
+/** Fee too low for relay. */
+export const REJECT_INSUFFICIENTFEE = 0x42;
+/** Conflicts with checkpoint. */
+export const REJECT_CHECKPOINT = 0x43;
+/** Absurdly high fee (internal-only, not sent over P2P). */
+export const REJECT_HIGHFEE = 0x100;
+//# sourceMappingURL=rejectCodes.js.map

package/dist/rejectCodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rejectCodes.js","sourceRoot":"","sources":["../src/rejectCodes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gCAAgC;AAChC,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,kDAAkD;AAClD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAEnC,wBAAwB;AACxB,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC,0CAA0C;AAC1C,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,iCAAiC;AACjC,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC,6BAA6B;AAC7B,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAE3C,iCAAiC;AACjC,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAEtC,4DAA4D;AAC5D,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC"}

package/dist/storageInterface.d.ts

@@ -0,0 +1,56 @@
+import type { ProcessedBlock } from "./block.js";
+import type { Balance, BlockHeader, HistoryEntry, MempoolTx, TransactionRecord, UtxoEntry } from "./data.js";
+import type { OutpointKey, ScriptHash, Txid } from "./primitives.js";
+/** Read-only view into the chain + mempool state. */
+export interface StorageReader {
+    /** Get the block header at a given height. */
+    getHeader(height: number): BlockHeader | undefined;
+    /** Get the block header by block hash. */
+    getHeaderByHash(hash: string): BlockHeader | undefined;
+    /** Get the current chain tip (highest header), or undefined if empty. */
+    getTip(): BlockHeader | undefined;
+    /** Get confirmed transaction history for a scripthash. */
+    getHistory(scriptHash: ScriptHash, fromHeight?: number, toHeight?: number): HistoryEntry[];
+    /** Get mempool history entries for a scripthash. */
+    getMempoolHistory(scriptHash: ScriptHash): HistoryEntry[];
+    /** Get confirmed + unconfirmed balance for a scripthash. */
+    getBalance(scriptHash: ScriptHash): Balance;
+    /** Get unspent outputs for a scripthash (confirmed minus mempool-spent, plus mempool outputs). */
+    getUtxos(scriptHash: ScriptHash): UtxoEntry[];
+    /** Get a transaction record by txid. */
+    getTx(txid: Txid): TransactionRecord | undefined;
+    /** Get raw transaction hex by txid. */
+    getRawTx(txid: Txid): string | undefined;
+    /** Compute the Electrum status hash for a scripthash. Null if no history. */
+    getScriptHashStatus(scriptHash: ScriptHash): string | null;
+    /** Get a mempool transaction entry. */
+    getMempoolTx(txid: Txid): MempoolTx | undefined;
+    /** Get the ordered list of txids in a block at the given height. */
+    getTxidsAtHeight(height: number): Txid[] | undefined;
+    /** Get a single UTXO by outpoint key (confirmed or mempool, undefined if spent in mempool). */
+    getUtxoByOutpoint(key: OutpointKey): UtxoEntry | undefined;
+    /** Get all mempool transaction IDs. */
+    getMempoolTxids(): Txid[];
+    /** Get a mempool UTXO by outpoint key. */
+    getMempoolUtxo(key: OutpointKey): UtxoEntry | undefined;
+}
+/** Mutating operations on the chain + mempool state. */
+export interface StorageWriter {
+    /** Apply a processed block to the confirmed state. Returns affected scripthashes. */
+    applyBlock(block: ProcessedBlock): Set<ScriptHash>;
+    /** Undo (revert) the block at the given height. Returns affected scripthashes. */
+    undoBlock(height: number): Set<ScriptHash>;
+    /** Add a transaction to the mempool. Returns affected scripthashes. */
+    addMempoolTx(tx: MempoolTx): Set<ScriptHash>;
+    /** Remove a mempool transaction (cascading to descendants). Returns affected scripthashes. */
+    removeMempoolTx(txid: Txid): Set<ScriptHash>;
+    /** Clear all mempool state. Returns all scripthashes that had mempool activity. */
+    clearMempool(): Set<ScriptHash>;
+    /** Pre-register a mempool UTXO before calling addMempoolTx. */
+    addMempoolUtxo(key: OutpointKey, utxo: UtxoEntry): void;
+    /** Store raw transaction hex so getRawTx works for mempool txs. */
+    storeRawTx(txid: Txid, rawHex: string): void;
+}
+/** Combined read + write storage. */
+export type Storage = StorageReader & StorageWriter;
+//# sourceMappingURL=storageInterface.d.ts.map

package/dist/storageInterface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageInterface.d.ts","sourceRoot":"","sources":["../src/storageInterface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EACX,OAAO,EACP,WAAW,EACX,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,SAAS,EACT,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAErE,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC7B,8CAA8C;IAC9C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAEnD,0CAA0C;IAC1C,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAEvD,yEAAyE;IACzE,MAAM,IAAI,WAAW,GAAG,SAAS,CAAC;IAElC,0DAA0D;IAC1D,UAAU,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAE3F,oDAAoD;IACpD,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,YAAY,EAAE,CAAC;IAE1D,4DAA4D;IAC5D,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC;IAE5C,kGAAkG;IAClG,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,EAAE,CAAC;IAE9C,wCAAwC;IACxC,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,iBAAiB,GAAG,SAAS,CAAC;IAEjD,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;IAEzC,6EAA6E;IAC7E,mBAAmB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IAE3D,uCAAuC;IACvC,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,GAAG,SAAS,CAAC;IAEhD,oEAAoE;IACpE,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,SAAS,CAAC;IAErD,+FAA+F;IAC/F,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;IAE3D,uCAAuC;IACvC,eAAe,IAAI,IAAI,EAAE,CAAC;IAE1B,0CAA0C;IAC1C,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;CACxD;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC7B,qFAAqF;IACrF,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;IAEnD,kFAAkF;IAClF,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;IAE3C,uEAAuE;IACvE,YAAY,CAAC,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;IAE7C,8FAA8F;IAC9F,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;IAE7C,mFAAmF;IACnF,YAAY,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IAEhC,+DAA+D;IAC/D,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IAExD,mEAAmE;IACnE,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AAED,qCAAqC;AACrC,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,aAAa,CAAC"}

package/dist/storageInterface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storageInterface.js.map

package/dist/storageInterface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageInterface.js","sourceRoot":"","sources":["../src/storageInterface.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@mem-cash/types",
+	"version": "0.0.1",
+	"description": "Shared primitives, data types, and storage interfaces for mem-cash",
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist/",
+		"README.md",
+		"LICENSE"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/mainnet-pat/mem-cash.git",
+		"directory": "packages/types"
+	},
+	"keywords": [
+		"bitcoin-cash",
+		"electrum",
+		"types",
+		"utxo",
+		"scripthash"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"prepublishOnly": "tsc -b"
+	},
+	"dependencies": {
+		"@bitauth/libauth": "^3.1.0-next.8"
+	}
+}