nano-pow/dist/types.d.ts

Proof-of-work generation and validation with WebGPU/WebGL/WASM for Nano cryptocurrency.

//! SPDX-FileCopyrightText: 2025 Chris Duncan <chris@zoso.dev>
//! SPDX-License-Identifier: GPL-3.0-or-later

declare global {
	interface Window {
		NanoPow: typeof NanoPow
	}
}

export declare class NanoPow {
	/**
	* Finds a nonce that satisfies the Nano proof-of-work requirements.
	*
	* @param {bigint | string} hash - Hexadecimal hash of previous block, or public key for new accounts
	* @param {object} [options] - Used to configure execution
	* @param {string} [options.api] - Specifies how work is generated. Default: best available
	* @param {boolean} [options.debug=false] - Enables additional debug logging to the console. Default: false
	* @param {number} [options.effort=0x4] - GPU load when generating work. Larger values are not necessarily better since they can quickly overwhelm the GPU. Default: 0x4
	* @param {bigint} [options.difficulty=0xfffffff800000000] - Minimum value result of `BLAKE2b(nonce||blockhash)`. Default: 0xFFFFFFF800000000
	*/
	static work_generate (hash: bigint | string, options?: NanoPowOptions): Promise<WorkGenerateResponse | WorkErrorResponse>
	/**
	* Validates that a nonce satisfies Nano proof-of-work requirements.
	*
	* @param {(bigint|string)} work - Value to validate against hash and difficulty
	* @param {(bigint|string)} hash - Hash of previous block, or public key for new accounts
	* @param {object} [options] - Used to configure execution
	* @param {boolean} [options.debug=false] - Enables additional debug logging to the console. Default: false
	* @param {bigint} [options.difficulty=0xfffffff800000000] - Minimum value result of `BLAKE2b(nonce||blockhash)`. Default: 0xFFFFFFF800000000
	*/
	static work_validate (work: bigint | string, hash: bigint | string, options?: NanoPowOptions): Promise<WorkValidateResponse | WorkErrorResponse>
}
export { NanoPow as default }

/**
* Input for configuring NanoPow. Must be validated prior to usage, so types are
* `unknown`, but JSDoc indicates expected data types.
*
* @param {string} [api=cpu] - Specifies how work is generated. Default: cpu
* @param {boolean} [debug=false] - Enables additional debug logging to the console. Default: false
* @param {(bigint|string)} [difficulty=0xFFFFFFF800000000] - Minimum value result of `BLAKE2b(nonce||blockhash)`. Default: 0xFFFFFFF800000000
* @param {number} [effort=0x4] - GPU load when generating work. Larger values are not necessarily better since they can quickly overwhelm the GPU. Default: 0x4
*/
export type NanoPowOptions = {
	api?: unknown
	debug?: unknown
	difficulty?: unknown
	effort?: unknown
}

/**
* Usee to provide consumer with error information in response to request.
*
* @param {string} error - Informative message about error.
*/
export type WorkErrorResponse = {
	error: string
}

/**
* Structure of response to `work_generate` call.
*
* @param {string} hash - Hash from generate request
* @param {string} work - Valid proof-of-work nonce generated for input hash
* @param {string} difficulty - BLAKE2b output which met or exceeded specified minimum threshold
*/
export type WorkGenerateResponse = {
	hash: string
	work: string
	difficulty: string
}

/**
* Structure of response to `work_validate` call.
*
* @param {string} hash - Hash from validate request
* @param {string} work - Nonce from validate request
* @param {string} difficulty - BLAKE2b output of `work` + `hash` which is compared to specified minimum threshold to determine validity
* @param {string} valid_all - 1 for true if nonce is valid for send blocks, else 0 for false
* @param {string} valid_receive - 1 for true if nonce is valid for receive blocks, else 0 for false
* @param {string} [valid] - Excluded if optional difficulty was not included in the request. 1 for true if nonce is valid for requested difficulty, else 0 for false
*/
export type WorkValidateResponse = {
	hash: string
	work: string
	difficulty: string
	valid_all: '0' | '1'
	valid_receive: '0' | '1'
	valid?: '0' | '1'
}