tiny-crypto-suite/dist/TinyChain/TinyChainBlock.d.mts

Tiny tools, big crypto — seamless encryption and certificate handling for modern web and Node apps.

export default TinyChainBlock;
export type NewTransaction = {
    /**
     * - The sender's address
     */
    from: string;
    /**
     * - The recipient's address
     */
    to: string;
    /**
     * - The amount of the transaction
     */
    amount: string | number | bigint;
};
export type Transaction = {
    /**
     * - The sender's address
     */
    from: string;
    /**
     * - The recipient's address
     */
    to: string;
    /**
     * - The amount of the transaction
     */
    amount: bigint;
};
export type NewTransactionData = {
    /**
     * - Max gas allowed for transactions.
     */
    gasLimit: bigint | number | string;
    /**
     * - Actual gas used.
     */
    gasUsed: bigint | number | string;
    /**
     * - Priority fee paid to the miner.
     */
    maxPriorityFeePerGas: bigint | number | string;
    /**
     * - Max total fee per gas unit allowed.
     */
    maxFeePerGas: bigint | number | string;
    /**
     * - Hex address that created the tx.
     */
    address: string;
    /**
     * - Address type that created the tx.
     */
    addressType: string;
    /**
     * - Payload content (usually a string).
     */
    payload: any;
    /**
     * - Transfer list.
     */
    transfers?: NewTransaction[] | undefined;
};
export type TransactionData = {
    /**
     * - Max gas allowed for transactions.
     */
    gasLimit: bigint;
    /**
     * - Actual gas used.
     */
    gasUsed: bigint;
    /**
     * - Priority fee paid to the miner.
     */
    maxPriorityFeePerGas: bigint;
    /**
     * - Max total fee per gas unit allowed.
     */
    maxFeePerGas: bigint;
    /**
     * - Hex address that created the block.
     */
    address: string;
    /**
     * - Address type that created the block.
     */
    addressType: string;
    /**
     * - Payload content (usually a string).
     */
    payload: any;
    /**
     * - Transfer list.
     */
    transfers: Array<NewTransaction>;
};
/**
 * - Configuration object.
 */
export type BlockInitData = {
    /**
     * - The first validation of the block must be performed.
     */
    firstValidation?: boolean | undefined;
    /**
     * - If true, payload must be a string.
     */
    payloadString?: boolean | undefined;
    /**
     * - Signer instance for cryptographic operations.
     */
    signer?: TinySecp256k1 | undefined;
    /**
     * - Parser instance used for deep serialization.
     */
    parser?: TinyCryptoParser | undefined;
    /**
     * - Block index.
     */
    index?: string | number | bigint | undefined;
    /**
     * - Hash of the previous block.
     */
    prevHash?: string | undefined;
    /**
     * - Mining difficulty.
     */
    diff?: string | number | bigint | undefined;
    /**
     * - Block reward.
     */
    reward?: string | number | bigint | undefined;
    /**
     * - Starting nonce.
     */
    nonce?: string | number | bigint | undefined;
    /**
     * - The chain ID.
     */
    chainId?: string | number | bigint | undefined;
    /**
     * - Base fee per gas unit.
     */
    baseFeePerGas?: string | number | bigint | undefined;
    /**
     * - A map where each key is a transaction index.
     */
    txs?: TxIndexMap | undefined;
    /**
     * - A map where each key is a transaction signature.
     */
    sigs?: SignIndexMap | undefined;
    /**
     * - Unix timestamp of the block.
     */
    time?: number | undefined;
    /**
     * - Optional precomputed hash.
     */
    hash?: string | null | undefined;
    /**
     * - Address of the miner.
     */
    miner?: string | null | undefined;
    /**
     * - Block data.
     */
    data?: NewTransactionData[] | undefined;
};
export type GetTransactionData = {
    index: bigint;
    time: number;
    data: TransactionData[];
    prevHash: string | null;
    diff: bigint;
    nonce: bigint;
    hash: string;
    reward: bigint;
    miner: string | null;
    chainId: bigint;
    baseFeePerGas: bigint;
    txs: TxIndexMap;
    sigs: SignIndexMap;
};
/**
 * A map where each key is a transaction index and the value is the transaction ID.
 */
export type TxIndexMap = Record<string, number>;
/**
 * A map where each key is a transaction index and the value is the signature in hex.
 */
export type SignIndexMap = Array<string>;
/**
 * @typedef {Object} NewTransaction
 * @property {string} from - The sender's address
 * @property {string} to - The recipient's address
 * @property {string | number | bigint} amount - The amount of the transaction
 */
/**
 * @typedef {Object} Transaction
 * @property {string} from - The sender's address
 * @property {string} to - The recipient's address
 * @property {bigint} amount - The amount of the transaction
 */
/**
 * @typedef {Object} NewTransactionData
 * @property {bigint | number | string} gasLimit - Max gas allowed for transactions.
 * @property {bigint | number | string} gasUsed - Actual gas used.
 * @property {bigint | number | string} maxPriorityFeePerGas - Priority fee paid to the miner.
 * @property {bigint | number | string} maxFeePerGas - Max total fee per gas unit allowed.
 * @property {string} address - Hex address that created the tx.
 * @property {string} addressType - Address type that created the tx.
 * @property {*} payload - Payload content (usually a string).
 * @property {Array<NewTransaction>} [transfers] - Transfer list.
 */
/**
 * @typedef {Object} TransactionData
 * @property {bigint} gasLimit - Max gas allowed for transactions.
 * @property {bigint} gasUsed - Actual gas used.
 * @property {bigint} maxPriorityFeePerGas - Priority fee paid to the miner.
 * @property {bigint} maxFeePerGas - Max total fee per gas unit allowed.
 * @property {string} address - Hex address that created the block.
 * @property {string} addressType - Address type that created the block.
 * @property {*} payload - Payload content (usually a string).
 * @property {Array<NewTransaction>} transfers - Transfer list.
 */
/**
 * Creates a new instance of a block with all necessary data and gas configuration.
 *
 * @typedef {Object} BlockInitData - Configuration object.
 * @property {boolean} [firstValidation=true] - The first validation of the block must be performed.
 * @property {boolean} [payloadString=true] - If true, payload must be a string.
 * @property {TinySecp256k1} [signer] - Signer instance for cryptographic operations.
 * @property {TinyCryptoParser} [parser] - Parser instance used for deep serialization.
 * @property {bigint | number | string} [index=0n] - Block index.
 * @property {string} [options.prevHash=''] - Hash of the previous block.
 * @property {bigint | number | string} [diff=1n] - Mining difficulty.
 * @property {bigint | number | string} [reward=0n] - Block reward.
 * @property {bigint | number | string} [nonce=0n] - Starting nonce.
 * @property {bigint | number | string} [chainId] - The chain ID.
 * @property {bigint | number | string} [baseFeePerGas] - Base fee per gas unit.
 * @property {TxIndexMap} [txs] - A map where each key is a transaction index.
 * @property {SignIndexMap} [sigs] - A map where each key is a transaction signature.
 * @property {number} [time=Date.now()] - Unix timestamp of the block.
 * @property {string|null} [hash=null] - Optional precomputed hash.
 * @property {string|null} [miner=null] - Address of the miner.
 * @property {NewTransactionData[]} [data=[]] - Block data.
 */
/**
 * @typedef {{
 *   index: bigint,
 *   time: number,
 *   data: TransactionData[],
 *   prevHash: string|null,
 *   diff: bigint,
 *   nonce: bigint,
 *   hash: string,
 *   reward: bigint,
 *   miner: string|null,
 *   chainId: bigint,
 *   baseFeePerGas: bigint,
 *   txs: TxIndexMap,
 *   sigs: SignIndexMap,
 * }} GetTransactionData
 */
/**
 * @typedef {Record.<string, number>} TxIndexMap
 * A map where each key is a transaction index and the value is the transaction ID.
 */
/**
 * @typedef {Array<string>} SignIndexMap
 * A map where each key is a transaction index and the value is the signature in hex.
 */
/**
 * Represents a single block within the TinyChain structure.
 *
 * A block stores a list of transaction data, gas metrics, and
 * metadata used for validation and mining. It includes fields
 * such as index, timestamp, nonce, miner address, and cryptographic
 * hashes. It is designed to be immutable after mining and stores
 * calculated fees used to incentivize miners.
 *
 * This class assumes values like `index`, `prevHash`, and `minerAddress`
 * are externally controlled and trusted when mining or constructing blocks.
 *
 * @class
 */
declare class TinyChainBlock {
    /**
     * Creates a new instance of a block with all necessary data and gas configuration.
     *
     * @param {BlockInitData} [options={}] - Configuration object.
     */
    constructor({ firstValidation, payloadString, signer, parser, time, chainId, txs, sigs, data, index, prevHash, diff, baseFeePerGas, reward, nonce, hash, miner, }?: BlockInitData);
    time: number;
    index: bigint;
    baseFeePerGas: bigint;
    prevHash: string;
    diff: bigint;
    nonce: bigint;
    reward: bigint;
    miner: string | null;
    chainId: bigint;
    data: TransactionData[];
    hash: string;
    txs: TxIndexMap;
    sigs: SignIndexMap;
    /** @type {Record<string, string>} */
    invalidAddress: Record<string, string>;
    /**
     * Validates the integrity of each transaction inside the block by verifying
     * its ECDSA signature using the associated address.
     *
     * It loops through all transactions, serializes the corresponding data,
     * and ensures that the signature is valid. If any signature is invalid,
     * it throws an error identifying the problematic transaction and its index.
     *
     * @throws {Error} If any transaction has an invalid ECDSA signature,
     * or if any transaction has an address equal to "0".
     */
    validateSig(): void;
    /**
     * Stops the mining process by setting the internal stop flag.
     * This allows asynchronous mining loops to exit gracefully.
     *
     * @returns {void}
     */
    stopMining(): void;
    /**
     * Returns a plain object representing all public data of the block.
     * @returns {GetTransactionData}
     */
    get(): GetTransactionData;
    /**
     * Serializes the block using the parser for export.
     * @returns {string}
     */
    export(): string;
    /**
     * Calculates the SHA-256 hash of the block based on its contents.
     * @returns {string}
     */
    calculateHash(): string;
    /**
     * Generates a unique transaction ID (TX ID) based on its contents.
     *
     * @param {number} index
     * @returns {string} SHA256 hash as the TX ID
     * @throws {Error} If this.data is not an array
     * @throws {Error} If the index is out of bounds
     */
    generateTxId(index: number): string;
    /**
     * Mines the block until a valid hash is found.
     * @param {string|null} [minerAddress] - Address of the miner.
     * @param {{ prevHash?: string, index?: bigint, onComplete?: function, onProgress?: function }} [options={}]
     * @returns {Promise<{ nonce: bigint, hash: string, success: boolean }>}
     * @throws {Error} If the address is invalid.
     */
    mine(minerAddress?: string | null, { prevHash, index, onComplete, onProgress }?: {
        prevHash?: string;
        index?: bigint;
        onComplete?: Function;
        onProgress?: Function;
    }): Promise<{
        nonce: bigint;
        hash: string;
        success: boolean;
    }>;
    /**
     * Returns a validated view of the internal transaction index map.
     *
     * @returns {TxIndexMap}
     * @throws {Error} If internal txs object is invalid.
     */
    getTxs(): TxIndexMap;
    /**
     * Retrieves a transaction's data by its transaction ID.
     *
     * @param {string} tx - The transaction ID used as key in the transaction index map.
     * @returns {TransactionData} The corresponding transaction data.
     * @throws {Error} If the transaction ID is not found in the data list.
     */
    getTx(tx: string): TransactionData;
    /**
     * Returns the parser instance responsible for cryptographic serialization and hashing.
     * @returns {TinyCryptoParser}
     */
    getParser(): TinyCryptoParser;
    /**
     * Returns the signer instance responsible for signing and verifying cryptographic data.
     * @returns {TinySecp256k1}
     */
    getSigner(): TinySecp256k1;
    /**
     * Returns the timestamp when the block was created.
     * @returns {number}
     */
    getTime(): number;
    /**
     * Returns the index of the block in the blockchain.
     * @returns {bigint}
     */
    getIndex(): bigint;
    /**
     * Returns the chain ID of the blockchain instance.
     * @returns {bigint}
     */
    getChainId(): bigint;
    /**
     * Returns the hash of the previous block.
     * @returns {string|null}
     */
    getPrevHash(): string | null;
    /**
     * Returns the difficulty level of the block.
     * @returns {bigint}
     */
    getDiff(): bigint;
    /**
     * Returns the reward for mining the block.
     * @returns {bigint}
     */
    getReward(): bigint;
    /**
     * Returns the nonce used for mining.
     * @returns {bigint}
     */
    getNonce(): bigint;
    /**
     * Returns the miner's address who mined the block.
     * @returns {string|null}
     */
    getMiner(): string | null;
    /**
     * Returns the block data.
     * @returns {TransactionData[]}
     */
    getData(): TransactionData[];
    /**
     * Returns the list of signatures attached to the block.
     * @returns {SignIndexMap}
     */
    getSigs(): SignIndexMap;
    /**
     * Returns the current hash of the block.
     * @returns {string}
     */
    getHash(): string;
    /**
     * Returns the base fee per gas (in gwei).
     * @returns {bigint}
     */
    getBaseFeePerGas(): bigint;
    #private;
}
import TinySecp256k1 from './Secp256k1/index.mjs';
import TinyCryptoParser from '../lib/TinyCryptoParser.mjs';
//# sourceMappingURL=TinyChainBlock.d.mts.map