xpi-ts 0.2.23 → 0.2.24

package/dist/types/lib/bitcore/block/blockheader.d.ts

@@ -1,80 +1,300 @@
+/**
+ * BlockHeader implementation for the Lotus blockchain
+ *
+ * Represents the header portion of a Lotus block (CBlockHeader in lotusd).
+ * Implements the Lotus-specific 3-layer hashing algorithm and custom field
+ * sizes for time (6 bytes), size (7 bytes), nonce (8 bytes), etc.
+ *
+ * Serialization order (160 bytes total):
+ *   prevHash(32) + bits(4) + time(6) + reserved(2) + nonce(8) +
+ *   version(1) + size(7) + height(4) + epochBlock(32) +
+ *   merkleRoot(32) + extendedMetadata(32)
+ *
+ * Hash algorithm (3-layer SHA256):
+ *   Layer 3: SHA256(version || size || height || epochBlock || merkleRoot || extendedMetadata)
+ *   Layer 2: SHA256(bits || time || reserved || nonce || layer3Hash)
+ *   Layer 1: SHA256(prevHash || layer2Hash)
+ *
+ * @see lotusd: src/primitives/block.h, src/primitives/block.cpp
+ */
 import { Buffer } from 'buffer/';
 import { BufferReader } from '../encoding/bufferreader.js';
 import { BufferWriter } from '../encoding/bufferwriter.js';
 import { BN } from '../crypto/bn.js';
+/**
+ * Block header data interface for internal/deserialized format.
+ * Uses native types: Buffer for hashes, BN for large numbers.
+ */
 export interface BlockHeaderData {
+    /** Hash of the previous block (32 bytes, little-endian) */
     prevHash?: Buffer;
+    /** Compact representation of the target difficulty */
     bits?: number;
+    /** Block timestamp in seconds since Unix epoch */
     time?: number;
+    /** Reserved field for future use (always 0) */
     reserved?: number;
+    /** Nonce used for proof of work (8 bytes) */
     nonce?: BN;
+    /** Block header version number (1 byte, always 0x01) */
     version?: number;
+    /** Advertised block size (7 bytes) */
     size?: BN;
+    /** Block height in the chain */
     height?: number;
+    /** Hash of the epoch block (32 bytes, little-endian) */
     epochBlock?: Buffer;
+    /** Merkle root of all transactions (32 bytes, little-endian) */
     merkleRoot?: Buffer;
+    /** Extended metadata hash (32 bytes, little-endian) */
     extendedMetadata?: Buffer;
+    /** Precomputed block hash for validation (display format, big-endian hex) */
     hash?: string;
 }
+/**
+ * Block header object interface for serialization/JSON.
+ * All values are converted to serializable formats (strings and numbers).
+ * Hash fields are in display format (big-endian hex).
+ */
 export interface BlockHeaderObject {
+    /** Computed block hash (big-endian hex) */
     hash: string;
+    /** Hash of the previous block (big-endian hex) */
     prevHash: string;
+    /** Compact representation of the target difficulty */
     bits: number;
+    /** Block timestamp in seconds since Unix epoch */
     time: number;
+    /** Reserved field for future use */
     reserved: number;
+    /** Nonce as decimal string */
     nonce: string;
+    /** Block header version number */
     version: number;
+    /** Advertised block size as number */
     size: number;
+    /** Block height in the chain */
     height: number;
+    /** Hash of the epoch block (big-endian hex) */
     epochBlock: string;
+    /** Merkle root of all transactions (big-endian hex) */
     merkleRoot: string;
+    /** Extended metadata hash (big-endian hex) */
     extendedMetadata: string;
 }
+/**
+ * Represents a Lotus blockchain block header.
+ *
+ * Implements the CBlockHeader structure from lotusd with Lotus-specific
+ * features including 3-layer SHA256 hashing, 6-byte timestamps, 7-byte
+ * block sizes, and epoch block references.
+ *
+ * @example
+ * ```typescript
+ * // Create from buffer
+ * const header = BlockHeader.fromBuffer(headerBuffer)
+ *
+ * // Get block hash
+ * console.log(header.id)
+ *
+ * // Validate proof of work
+ * if (header.validProofOfWork()) {
+ *   console.log('Valid PoW')
+ * }
+ *
+ * // Serialize to buffer
+ * const buffer = header.toBuffer()
+ * ```
+ */
 export declare class BlockHeader {
+    /** Start buffer position in raw block data */
     static readonly START_OF_HEADER = 0;
+    /** Maximum time offset (2 hours) a block timestamp can be ahead of current time */
     static readonly MAX_TIME_OFFSET: number;
+    /** Largest possible hash value (2^256) for difficulty calculations */
     static readonly LARGEST_HASH: BN;
+    /** Total serialized size of a block header */
     static readonly HEADER_SIZE = 160;
+    /** Number of blocks per epoch */
     static readonly EPOCH_NUM_BLOCKS = 5040;
+    /** Constants structure for backward compatibility */
     static readonly Constants: {
         START_OF_HEADER: number;
         MAX_TIME_OFFSET: number;
         LARGEST_HASH: BN;
     };
+    /** Hash of the previous block (32 bytes, little-endian) */
     readonly prevHash: Buffer;
+    /** Compact target difficulty */
     readonly bits: number;
+    /** Block timestamp in seconds since Unix epoch */
     readonly time: number;
+    /** Alias for time (backward compatibility) */
     readonly timestamp: number;
+    /** Reserved field (always 0) */
     readonly reserved: number;
+    /** Nonce used for proof of work */
     readonly nonce: BN;
+    /** Header version (always 0x01) */
     readonly version: number;
+    /** Advertised block size */
     readonly size: BN;
+    /** Block height in the chain */
     readonly height: number;
+    /** Hash of the epoch block (32 bytes, little-endian) */
     readonly epochBlock: Buffer;
+    /** Merkle root of transactions (32 bytes, little-endian) */
     readonly merkleRoot: Buffer;
+    /** Extended metadata hash (32 bytes, little-endian) */
     readonly extendedMetadata: Buffer;
+    /** Cached block hash (big-endian hex, display format) */
     private _id?;
+    /**
+     * Create a new BlockHeader
+     *
+     * @param arg - BlockHeaderData object or existing BlockHeader instance
+     *
+     * @example
+     * ```typescript
+     * // Empty header with defaults
+     * const header = new BlockHeader()
+     *
+     * // From deserialized data
+     * const header = new BlockHeader({ prevHash: buf, bits: 0x1d00ffff, ... })
+     * ```
+     */
     constructor(arg?: BlockHeaderData | BlockHeader);
+    /**
+     * Create from a BlockHeaderObject (serialized/JSON format).
+     * Hash fields are expected in display format (big-endian hex strings).
+     *
+     * @param obj - BlockHeaderObject with display-format hashes
+     * @returns New BlockHeader instance
+     */
     static fromObject(obj: BlockHeaderObject): BlockHeader;
+    /**
+     * Create from raw block data (binary string or Buffer)
+     *
+     * @param data - Raw block data
+     * @returns New BlockHeader instance
+     */
     static fromRawBlock(data: Buffer | string): BlockHeader;
+    /**
+     * Create from a Buffer containing a serialized block header
+     *
+     * @param buf - Buffer with serialized header data
+     * @returns New BlockHeader instance
+     */
     static fromBuffer(buf: Buffer): BlockHeader;
+    /**
+     * Create from a hex string
+     *
+     * @param str - Hex-encoded serialized block header
+     * @returns New BlockHeader instance
+     */
     static fromString(str: string): BlockHeader;
+    /**
+     * Create from a BufferReader
+     *
+     * @param br - BufferReader positioned at the start of header data
+     * @returns New BlockHeader instance
+     */
     static fromBufferReader(br: BufferReader): BlockHeader;
+    /**
+     * Convert to a plain JavaScript object (serializable format).
+     * Hash fields are in display format (big-endian hex).
+     *
+     * @returns BlockHeaderObject with all values as strings/numbers
+     */
     toObject(): BlockHeaderObject;
+    /**
+     * Convert to JSON (alias for toObject)
+     */
     toJSON(): BlockHeaderObject;
+    /**
+     * Serialize to a Buffer (160 bytes)
+     *
+     * @returns Buffer containing the serialized block header
+     */
     toBuffer(): Buffer;
+    /**
+     * Serialize to a hex string
+     *
+     * @returns Hex-encoded serialized block header
+     */
     toString(): string;
+    /**
+     * Write header fields to a BufferWriter.
+     *
+     * Serialization order matches lotusd CBlockHeader::SERIALIZE_METHODS:
+     *   prevHash(32) + bits(4) + time(6) + reserved(2) + nonce(8) +
+     *   version(1) + size(7) + height(4) + epochBlock(32) +
+     *   merkleRoot(32) + extendedMetadata(32)
+     *
+     * @param bw - Optional BufferWriter to reuse
+     * @returns BufferWriter containing the serialized data
+     */
     toBufferWriter(bw?: BufferWriter): BufferWriter;
+    /**
+     * Block hash in display format (big-endian hex).
+     * Computed using the Lotus 3-layer SHA256 algorithm.
+     */
     get hash(): string;
+    /**
+     * Block ID (alias for hash)
+     */
     get id(): string;
+    /**
+     * Calculate the target difficulty from compact bits encoding.
+     *
+     * @param bits - Optional compact bits value (defaults to this.bits)
+     * @returns Target as a BN value
+     */
     getTargetDifficulty(bits?: number): BN;
+    /**
+     * Calculate the human-readable difficulty value.
+     *
+     * @returns Difficulty as a floating-point number
+     */
     getDifficulty(): number;
+    /**
+     * Check if the block timestamp is not too far in the future.
+     *
+     * @returns True if the timestamp is within the acceptable range
+     */
     validTimestamp(): boolean;
+    /**
+     * Check if the proof-of-work hash satisfies the target difficulty.
+     *
+     * @returns True if the block hash is below the target
+     */
     validProofOfWork(): boolean;
+    /**
+     * String representation for console/debugging
+     */
     inspect(): string;
+    /**
+     * Compute the block hash using the Lotus 3-layer SHA256 algorithm.
+     *
+     * Layer 3: SHA256(nHeaderVersion || vSize || nHeight || hashEpochBlock || hashMerkleRoot || hashExtendedMetadata)
+     * Layer 2: SHA256(nBits || vTime || nReserved || nNonce || layer3Hash)
+     * Layer 1: SHA256(hashPrevBlock || layer2Hash)
+     *
+     * @returns 32-byte hash buffer (little-endian)
+     */
     private _computeHash;
+    /**
+     * Normalize BlockHeaderData input, filling in defaults for missing fields.
+     */
     private static _normalizeData;
+    /**
+     * Create default header data (all zeroes).
+     */
     private static _defaultData;
+    /**
+     * Read header fields from a BufferReader.
+     * Order matches lotusd CBlockHeader serialization.
+     */
     private static _readFromBuffer;
 }
 //# sourceMappingURL=blockheader.d.ts.map

package/dist/types/lib/bitcore/block/blockheader.d.ts.map

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

package/dist/types/lib/bitcore/block/merkleblock.d.ts

@@ -1,53 +1,259 @@
+/**
+ * MerkleBlock implementation for SPV (Simplified Payment Verification)
+ *
+ * Represents a CMerkleBlock from lotusd: a block header paired with a
+ * CPartialMerkleTree that proves inclusion of specific transactions
+ * without requiring the full block.
+ *
+ * Lotus-specific: each transaction contributes two leaves to the merkle
+ * tree (txhash + txid), so nLeaves = numTransactions * 2.
+ *
+ * Serialization format:
+ *   BlockHeader(160) + uint32(numTransactions) + varint(numHashes) +
+ *   uint256[](hashes) + varint(numFlagBytes) + byte[](flags)
+ *
+ * The partial merkle tree traversal algorithm matches lotusd's
+ * CPartialMerkleTree::TraverseAndExtract exactly.
+ *
+ * @see lotusd: src/merkleblock.h, src/merkleblock.cpp
+ * @see BIP37: https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki
+ */
 import { Buffer } from 'buffer/';
 import { BlockHeader, type BlockHeaderData, type BlockHeaderObject } from './blockheader.js';
 import { BufferReader } from '../encoding/bufferreader.js';
 import { BufferWriter } from '../encoding/bufferwriter.js';
 import { Transaction } from '../transaction/index.js';
+/**
+ * Error thrown when a MerkleBlock is invalid (e.g., missing data, wrong format).
+ */
 export declare class InvalidMerkleBlockError extends Error {
     readonly code: string;
     readonly context: Record<string, unknown>;
     constructor(message: string, context?: Record<string, unknown>);
 }
+/**
+ * Error thrown when MerkleBlock validation fails (e.g., invalid field values).
+ */
 export declare class MerkleBlockValidationError extends Error {
     readonly code: string;
     readonly context: Record<string, unknown>;
     constructor(message: string, context?: Record<string, unknown>);
 }
+/**
+ * MerkleBlock data interface for construction (internal format).
+ * Uses BlockHeader instance or BlockHeaderData (Buffer/BN types).
+ */
 export interface MerkleBlockData {
+    /** Block header */
     header: BlockHeader | BlockHeaderData;
+    /** Total number of transactions in the original block */
     numTransactions: number;
+    /** Array of merkle node hashes (hex strings, little-endian) */
     hashes: string[];
+    /** Bit flags for partial merkle tree traversal */
     flags: number[];
 }
+/**
+ * MerkleBlock object interface for serialization/JSON.
+ * Header is in BlockHeaderObject format with display-format hashes.
+ */
 export interface MerkleBlockObject {
+    /** Block header in serialized format */
     header: BlockHeaderObject;
+    /** Total number of transactions in the original block */
     numTransactions: number;
+    /** Array of merkle node hashes (hex strings) */
     hashes: string[];
+    /** Bit flags for partial merkle tree traversal */
     flags: number[];
 }
+/**
+ * A MerkleBlock is a block header with a partial merkle tree that proves
+ * inclusion of specific transactions without requiring the full block.
+ *
+ * This is essential for SPV clients that need to verify transaction
+ * inclusion while downloading minimal data.
+ *
+ * @example
+ * ```typescript
+ * // Create from buffer (e.g., from network)
+ * const merkleBlock = MerkleBlock.fromBuffer(buffer)
+ *
+ * // Validate the merkle tree
+ * if (merkleBlock.validMerkleTree()) {
+ *   console.log('Valid merkle proof')
+ * }
+ *
+ * // Check if a transaction is included
+ * if (merkleBlock.hasTransaction(txid)) {
+ *   console.log('Transaction is in the block')
+ * }
+ *
+ * // Get all matched transaction hashes
+ * const matched = merkleBlock.filteredTxsHash()
+ * ```
+ */
 export declare class MerkleBlock {
+    /** 32-byte zero hash for merkle tree padding */
     static readonly NULL_HASH: Buffer;
+    /** Block header containing proof-of-work and metadata */
     readonly header: BlockHeader;
+    /** Total number of transactions in the original block */
     readonly numTransactions: number;
+    /** Merkle node hashes (hex strings, little-endian byte order) */
     readonly hashes: string[];
+    /** Bit flags for partial merkle tree traversal */
     readonly flags: number[];
+    /**
+     * Create a new MerkleBlock
+     *
+     * @param arg - Buffer or MerkleBlockData object
+     *
+     * @throws {Error} If input is invalid or missing
+     *
+     * @example
+     * ```typescript
+     * // From buffer
+     * const mb = new MerkleBlock(buffer)
+     *
+     * // From data object
+     * const mb = new MerkleBlock({
+     *   header: blockHeader,
+     *   numTransactions: 5,
+     *   hashes: ['abc...', 'def...'],
+     *   flags: [1, 0, 1]
+     * })
+     * ```
+     */
     constructor(arg?: Buffer | MerkleBlockData);
+    /**
+     * Create from a MerkleBlockObject (serialized/JSON format).
+     *
+     * @param obj - Object with header in BlockHeaderObject format
+     * @returns New MerkleBlock instance
+     *
+     * @throws {TypeError} If required fields are missing or invalid
+     */
     static fromObject(obj: MerkleBlockObject): MerkleBlock;
+    /**
+     * Create from a Buffer.
+     *
+     * @param buf - Buffer containing serialized MerkleBlock data
+     * @returns New MerkleBlock instance
+     *
+     * @throws {TypeError} If buffer is invalid or empty
+     */
     static fromBuffer(buf: Buffer): MerkleBlock;
+    /**
+     * Create from a BufferReader.
+     *
+     * @param br - BufferReader positioned at MerkleBlock data
+     * @returns New MerkleBlock instance
+     */
     static fromBufferReader(br: BufferReader): MerkleBlock;
+    /**
+     * Create from a hex string.
+     *
+     * @param str - Hex-encoded serialized MerkleBlock
+     * @returns New MerkleBlock instance
+     *
+     * @throws {TypeError} If string is empty or invalid
+     */
     static fromString(str: string): MerkleBlock;
+    /**
+     * Serialize to a Buffer.
+     *
+     * Format: header + uint32(numTransactions) + varint(numHashes) +
+     *         hashes + varint(numFlagBytes) + flagBytes
+     *
+     * @returns Buffer containing serialized MerkleBlock
+     */
     toBuffer(): Buffer;
+    /**
+     * Write MerkleBlock data to a BufferWriter.
+     *
+     * @param bw - Optional BufferWriter to reuse
+     * @returns BufferWriter containing serialized data
+     */
     toBufferWriter(bw?: BufferWriter): BufferWriter;
+    /**
+     * Convert to a plain JavaScript object.
+     *
+     * @returns MerkleBlockObject with header in display format
+     */
     toObject(): MerkleBlockObject;
+    /**
+     * Convert to JSON (alias for toObject)
+     */
     toJSON(): MerkleBlockObject;
+    /**
+     * Verify that the partial merkle tree is valid and produces the
+     * expected merkle root stored in the block header.
+     *
+     * Performs the same validation as lotusd CPartialMerkleTree::ExtractMatches:
+     * - Checks hash/flag array consistency
+     * - Traverses the tree and verifies all hashes are consumed
+     * - Compares computed root against header merkle root
+     *
+     * @returns True if the merkle tree is valid
+     */
     validMerkleTree(): boolean;
+    /**
+     * Extract and return transaction hashes that match the filter criteria.
+     *
+     * @returns Array of matched transaction hash strings (little-endian hex)
+     *
+     * @throws {BitcoreError.MerkleBlock.InvalidMerkleTree} If the tree is invalid
+     */
     filteredTxsHash(): string[];
+    /**
+     * Check if a specific transaction is included in this MerkleBlock.
+     *
+     * @param tx - Transaction object or transaction ID string
+     * @returns True if the transaction is found in the partial merkle tree
+     *
+     * @throws {BitcoreError} If tx is undefined or invalid format
+     *
+     * @remarks
+     * In Lotus, txid and hash are different values. SPV verification
+     * uses txid for transaction identification.
+     */
     hasTransaction(tx: Transaction | string): boolean;
+    /**
+     * Dispatch construction from Buffer or object.
+     */
     private static _from;
+    /**
+     * Validate and normalize MerkleBlockData input.
+     */
     private static _validateData;
+    /**
+     * Read MerkleBlock data from a BufferReader.
+     *
+     * Format: header + uint32(numTransactions) + varint(numHashes) +
+     *         hashes + varint(numFlagBytes) + flagBytes
+     */
     private static _readFromBuffer;
+    /**
+     * Calculate the width of the merkle tree at a given height.
+     * Lotus uses 2 leaves per transaction (hash + txid).
+     */
     private _calcTreeWidth;
+    /**
+     * Calculate the total height of the merkle tree.
+     */
     private _calcTreeHeight;
+    /**
+     * Traverse the partial merkle tree and extract matched transaction hashes.
+     *
+     * This is a faithful port of lotusd CPartialMerkleTree::TraverseAndExtract.
+     * It reconstructs the merkle root while collecting matched leaf hashes.
+     *
+     * @param depth - Current depth in the tree
+     * @param pos - Current position at this depth
+     * @param state - Mutable traversal state
+     * @returns 32-byte hash buffer for this node
+     */
     private _traverseAndExtract;
 }
 //# sourceMappingURL=merkleblock.d.ts.map

package/dist/types/lib/bitcore/block/merkleblock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merkleblock.d.ts","sourceRoot":"","sources":["../../../../../lib/bitcore/block/merkleblock.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAG1D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AASrD,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAE7B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAMnE;AAKD,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAE7B,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAMnE;AAoBD,MAAM,WAAW,eAAe;IAE9B,MAAM,EAAE,WAAW,GAAG,eAAe,CAAA;IAErC,eAAe,EAAE,MAAM,CAAA;IAEvB,MAAM,EAAE,MAAM,EAAE,CAAA;IAEhB,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAMD,MAAM,WAAW,iBAAiB;IAEhC,MAAM,EAAE,iBAAiB,CAAA;IAEzB,eAAe,EAAE,MAAM,CAAA;IAEvB,MAAM,EAAE,MAAM,EAAE,CAAA;IAEhB,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AA4BD,qBAAa,WAAW;IAEtB,MAAM,CAAC,QAAQ,CAAC,SAAS,SAAY;IAErC,QAAQ,CAAC,MAAM,EAAG,WAAW,CAAA;IAE7B,QAAQ,CAAC,eAAe,EAAG,MAAM,CAAA;IAEjC,QAAQ,CAAC,MAAM,EAAG,MAAM,EAAE,CAAA;IAE1B,QAAQ,CAAC,KAAK,EAAG,MAAM,EAAE,CAAA;gBAuBb,GAAG,CAAC,EAAE,MAAM,GAAG,eAAe;IAsC1C,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,WAAW;IAsBtD,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;IAgB3C,MAAM,CAAC,gBAAgB,CAAC,EAAE,EAAE,YAAY,GAAG,WAAW;IAatD,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;IAqB3C,QAAQ,IAAI,MAAM;IAUlB,cAAc,CAAC,EAAE,CAAC,EAAE,YAAY,GAAG,YAAY;IA4B/C,QAAQ,IAAI,iBAAiB;IAY7B,MAAM,IAAI,iBAAiB;IAmB3B,eAAe,IAAI,OAAO;IAqC1B,eAAe,IAAI,MAAM,EAAE;IA6C3B,cAAc,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO;IAmDjD,OAAO,CAAC,MAAM,CAAC,KAAK;IAepB,OAAO,CAAC,MAAM,CAAC,aAAa;IA+C5B,OAAO,CAAC,MAAM,CAAC,eAAe;IA+B9B,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,mBAAmB;CA0C5B"}
+{"version":3,"file":"merkleblock.d.ts","sourceRoot":"","sources":["../../../../../lib/bitcore/block/merkleblock.ts"],"names":[],"mappings":"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"}