@autonomys/auto-consensus 1.5.1 → 1.5.3

package/dist/info.js

@@ -16,32 +16,280 @@ exports.solutionRangeToPieces = solutionRangeToPieces;
 const parse_1 = require("./utils/parse");
 const query_1 = require("./utils/query");
 const PIECE_SIZE = BigInt(1048576);
+/**
+ * Executes an RPC call on the blockchain API.
+ *
+ * This is a generic function that allows calling any RPC method available on the blockchain API.
+ * RPC calls are remote procedure calls that interact with the blockchain node.
+ *
+ * @param api - The connected API instance
+ * @param methodPath - The RPC method path (e.g., 'chain.getHeader', 'system.health')
+ * @param params - Array of parameters to pass to the RPC method
+ * @returns Promise that resolves to the RPC call result
+ * @throws Error if the RPC call fails or method path is invalid
+ *
+ * @example
+ * ```typescript
+ * import { rpc } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const header = await rpc(api, 'chain.getHeader', [])
+ * const health = await rpc(api, 'system.health', [])
+ * ```
+ */
 const rpc = (api_1, methodPath_1, ...args_1) => __awaiter(void 0, [api_1, methodPath_1, ...args_1], void 0, function* (api, methodPath, params = []) { return yield (0, query_1.queryMethodPath)(api, `rpc.${methodPath}`, params); });
 exports.rpc = rpc;
+/**
+ * Executes a storage query on the blockchain API.
+ *
+ * This is a generic function that allows querying any storage item available on the blockchain.
+ * Storage queries retrieve data that is stored on-chain in the blockchain's state.
+ *
+ * @param api - The connected API instance
+ * @param methodPath - The storage query path (e.g., 'system.account', 'balances.totalIssuance')
+ * @param params - Array of parameters to pass to the storage query
+ * @returns Promise that resolves to the storage query result
+ * @throws Error if the storage query fails or method path is invalid
+ *
+ * @example
+ * ```typescript
+ * import { query } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const totalIssuance = await query(api, 'balances.totalIssuance', [])
+ * const accountData = await query(api, 'system.account', ['5GrwvaEF5z...'])
+ * ```
+ */
 const query = (api_1, methodPath_1, ...args_1) => __awaiter(void 0, [api_1, methodPath_1, ...args_1], void 0, function* (api, methodPath, params = []) { return yield (0, query_1.queryMethodPath)(api, `query.${methodPath}`, params); });
 exports.query = query;
+/**
+ * Retrieves the header information of the latest block.
+ *
+ * The block header contains metadata about a block including its number, parent hash,
+ * state root, and extrinsics root. This function gets the header of the current latest block.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to the block Header
+ * @throws Error if the header query fails
+ *
+ * @example
+ * ```typescript
+ * import { header } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const blockHeader = await header(api)
+ * console.log(`Block number: ${blockHeader.number}`)
+ * console.log(`Parent hash: ${blockHeader.parentHash}`)
+ * ```
+ */
 const header = (api) => __awaiter(void 0, void 0, void 0, function* () { return yield (0, exports.rpc)(api, 'chain.getHeader', []); });
 exports.header = header;
+/**
+ * Retrieves a complete block including its extrinsics.
+ *
+ * This function fetches a full block with all its transaction data (extrinsics).
+ * If no block hash is provided, it returns the latest block.
+ *
+ * @param api - The connected API instance
+ * @param blockHash - Optional block hash to fetch a specific block
+ * @returns Promise that resolves to a SignedBlock containing all block data
+ * @throws Error if the block query fails
+ *
+ * @example
+ * ```typescript
+ * import { block } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get latest block
+ * const latestBlock = await block(api)
+ *
+ * // Get specific block by hash
+ * const specificBlock = await block(api, '0x1234...')
+ * ```
+ */
 const block = (api, blockHash) => __awaiter(void 0, void 0, void 0, function* () { return yield (0, exports.rpc)(api, 'chain.getBlock', [blockHash]); });
 exports.block = block;
+/**
+ * Retrieves and parses all extrinsics from a block.
+ *
+ * Extrinsics are transactions or operations that modify the blockchain state.
+ * This function fetches a block and extracts all extrinsics in a parsed format
+ * for easier consumption.
+ *
+ * @param api - The connected API instance
+ * @param blockHash - Optional block hash to fetch extrinsics from a specific block
+ * @returns Promise that resolves to an array of parsed Extrinsic objects
+ * @throws Error if the block query or parsing fails
+ *
+ * @example
+ * ```typescript
+ * import { blockExtrinsics } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const extrinsics = await blockExtrinsics(api)
+ *
+ * extrinsics.forEach(ext => {
+ *   console.log(`${ext.section}.${ext.method} by ${ext.signer}`)
+ * })
+ * ```
+ */
 const blockExtrinsics = (api, blockHash) => __awaiter(void 0, void 0, void 0, function* () { return yield (0, exports.block)(api, blockHash).then((block) => (0, parse_1.parseBlockExtrinsics)(block)); });
 exports.blockExtrinsics = blockExtrinsics;
+/**
+ * Retrieves and parses all transfer-related extrinsics from a block.
+ *
+ * This function filters extrinsics to only include those related to token transfers,
+ * such as balance transfers and cross-chain transfers. It's useful for tracking
+ * token movement within a specific block.
+ *
+ * @param api - The connected API instance
+ * @param blockHash - Optional block hash to fetch transfers from a specific block
+ * @returns Promise that resolves to an array of transfer Extrinsic objects
+ * @throws Error if the block query or parsing fails
+ *
+ * @example
+ * ```typescript
+ * import { blockTransfers } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const transfers = await blockTransfers(api)
+ *
+ * console.log(`Found ${transfers.length} transfers in latest block`)
+ * ```
+ */
 const blockTransfers = (api, blockHash) => __awaiter(void 0, void 0, void 0, function* () { return yield (0, exports.block)(api, blockHash).then((block) => (0, parse_1.parseBlockTransfers)(block)); });
 exports.blockTransfers = blockTransfers;
+/**
+ * Retrieves the current block number.
+ *
+ * This function gets the block number of the latest block on the blockchain.
+ * Block numbers increment sequentially as new blocks are produced.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to the current block number as a number
+ * @throws Error if the block query fails
+ *
+ * @example
+ * ```typescript
+ * import { blockNumber } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const currentBlock = await blockNumber(api)
+ * console.log(`Current block: ${currentBlock}`)
+ * ```
+ */
 const blockNumber = (api) => __awaiter(void 0, void 0, void 0, function* () {
     const _block = yield (0, exports.block)(api);
     return parseInt(_block.block.header.number.toString());
 });
 exports.blockNumber = blockNumber;
+/**
+ * Retrieves the hash of a block.
+ *
+ * This function gets the hash of a specific block by its number, or the latest
+ * block hash if no block number is provided. Block hashes are unique identifiers
+ * for each block.
+ *
+ * @param api - The connected API instance
+ * @param blockNumber - Optional block number to get hash for specific block
+ * @returns Promise that resolves to the block hash as a hex string
+ * @throws Error if the block hash query fails
+ *
+ * @example
+ * ```typescript
+ * import { blockHash } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get latest block hash
+ * const latestHash = await blockHash(api)
+ *
+ * // Get hash of specific block
+ * const specificHash = await blockHash(api, 1000)
+ * ```
+ */
 const blockHash = (api, blockNumber) => __awaiter(void 0, void 0, void 0, function* () {
     const _blockHash = yield (0, exports.rpc)(api, 'chain.getBlockHash', [blockNumber]);
     return _blockHash.toString();
 });
 exports.blockHash = blockHash;
+/**
+ * Retrieves the hash of the finalized head block.
+ *
+ * The finalized head is the latest block that has been finalized by the consensus
+ * mechanism and is considered irreversible. This provides the hash of that block.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to the finalized head block hash
+ * @throws Error if the finalized head query fails
+ *
+ * @example
+ * ```typescript
+ * import { finalizedHead } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const finalizedHash = await finalizedHead(api)
+ * console.log(`Finalized block hash: ${finalizedHash}`)
+ * ```
+ */
 const finalizedHead = (api) => __awaiter(void 0, void 0, void 0, function* () { return yield (0, exports.rpc)(api, 'chain.getFinalizedHead', []); });
 exports.finalizedHead = finalizedHead;
+/**
+ * Retrieves the current network timestamp.
+ *
+ * This function gets the timestamp of the current block, which represents
+ * the time when the block was produced. The timestamp is set by block producers
+ * and represents network time.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to the network timestamp as a Codec
+ * @throws Error if the timestamp query fails
+ *
+ * @example
+ * ```typescript
+ * import { networkTimestamp } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const timestamp = await networkTimestamp(api)
+ * const networkTime = new Date(Number(timestamp.toString()))
+ * console.log(`Network time: ${networkTime}`)
+ * ```
+ */
 const networkTimestamp = (api) => __awaiter(void 0, void 0, void 0, function* () { return yield (0, exports.query)(api, 'timestamp.now', []); });
 exports.networkTimestamp = networkTimestamp;
+/**
+ * Retrieves the current solution ranges for the consensus mechanism.
+ *
+ * Solution ranges are used in the Proof of Archival Storage consensus to determine
+ * the difficulty of finding valid solutions. This includes current and next solution
+ * ranges for both regular consensus and voting.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to solution ranges object with current/next values
+ * @throws Error if the solution ranges query fails
+ *
+ * @example
+ * ```typescript
+ * import { solutionRanges } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const ranges = await solutionRanges(api)
+ * console.log(`Current solution range: ${ranges.current}`)
+ * console.log(`Next solution range: ${ranges.next}`)
+ * ```
+ */
 const solutionRanges = (api) => __awaiter(void 0, void 0, void 0, function* () {
     const _solutionRanges = yield (0, exports.query)(api, 'subspace.solutionRanges', []);
     const solution = _solutionRanges.toPrimitive();
@@ -53,8 +301,49 @@ const solutionRanges = (api) => __awaiter(void 0, void 0, void 0, function* () {
     };
 });
 exports.solutionRanges = solutionRanges;
+/**
+ * Checks if the solution range should be adjusted.
+ *
+ * This function queries whether the consensus mechanism has determined that
+ * the solution range needs to be adjusted based on network conditions.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to boolean indicating if adjustment is needed
+ * @throws Error if the query fails
+ *
+ * @example
+ * ```typescript
+ * import { shouldAdjustSolutionRange } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const shouldAdjust = await shouldAdjustSolutionRange(api)
+ * console.log(`Solution range adjustment needed: ${shouldAdjust}`)
+ * ```
+ */
 const shouldAdjustSolutionRange = (api) => __awaiter(void 0, void 0, void 0, function* () { return yield (0, exports.query)(api, 'subspace.shouldAdjustSolutionRange', []); });
 exports.shouldAdjustSolutionRange = shouldAdjustSolutionRange;
+/**
+ * Retrieves segment commitment information.
+ *
+ * Segment commitments are cryptographic commitments to data segments in the
+ * Autonomys network's decentralized storage system. This function retrieves
+ * all current segment commitments.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to array of segment commitment entries
+ * @throws Error if the segment commitment query fails
+ *
+ * @example
+ * ```typescript
+ * import { segmentCommitment } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const commitments = await segmentCommitment(api)
+ * console.log(`Found ${commitments.length} segment commitments`)
+ * ```
+ */
 const segmentCommitment = (api) => __awaiter(void 0, void 0, void 0, function* () {
     if (api.at) {
         const { parentHash } = yield (0, exports.header)(api);
@@ -63,10 +352,75 @@ const segmentCommitment = (api) => __awaiter(void 0, void 0, void 0, function* (
     return yield (0, exports.query)(api, 'subspace.segmentCommitment.entries', []);
 });
 exports.segmentCommitment = segmentCommitment;
+/**
+ * Retrieves the slot probability configuration.
+ *
+ * Slot probability defines the likelihood that a farmer will be able to produce
+ * a block in any given slot. It's returned as a fraction [numerator, denominator].
+ *
+ * @param api - The connected API instance
+ * @returns Tuple representing slot probability as [numerator, denominator]
+ *
+ * @example
+ * ```typescript
+ * import { slotProbability } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const [num, den] = slotProbability(api)
+ * console.log(`Slot probability: ${num}/${den} = ${num/den}`)
+ * ```
+ */
 const slotProbability = (api) => api.consts.subspace.slotProbability.toPrimitive();
 exports.slotProbability = slotProbability;
+/**
+ * Retrieves the maximum number of pieces that can fit in a sector.
+ *
+ * In the Autonomys storage system, data is organized into pieces and sectors.
+ * This function returns the maximum number of pieces that can be stored in
+ * a single sector.
+ *
+ * @param api - The connected API instance
+ * @returns Maximum pieces per sector as a bigint
+ *
+ * @example
+ * ```typescript
+ * import { maxPiecesInSector } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const maxPieces = maxPiecesInSector(api)
+ * console.log(`Max pieces per sector: ${maxPieces}`)
+ * ```
+ */
 const maxPiecesInSector = (api) => BigInt(api.consts.subspace.maxPiecesInSector.toPrimitive());
 exports.maxPiecesInSector = maxPiecesInSector;
+/**
+ * Converts solution range to the equivalent number of pieces.
+ *
+ * This utility function converts a solution range value to the equivalent
+ * number of pieces that would need to be stored to achieve that solution range,
+ * taking into account the slot probability.
+ *
+ * @param solutionRange - The solution range value to convert
+ * @param slotProbability - Slot probability as [numerator, denominator] tuple
+ * @returns Number of pieces equivalent to the solution range
+ *
+ * @example
+ * ```typescript
+ * import { solutionRangeToPieces, solutionRanges, slotProbability } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const ranges = await solutionRanges(api)
+ * const slotProb = slotProbability(api)
+ *
+ * if (ranges.current) {
+ *   const pieces = solutionRangeToPieces(ranges.current, [BigInt(slotProb[0]), BigInt(slotProb[1])])
+ *   console.log(`Current solution range equals ${pieces} pieces`)
+ * }
+ * ```
+ */
 function solutionRangeToPieces(solutionRange, slotProbability) {
     const MAX_U64 = BigInt(Math.pow(2, 64) - 1);
     const RECORD_NUM_CHUNKS = BigInt(32768);
@@ -75,6 +429,28 @@ function solutionRangeToPieces(solutionRange, slotProbability) {
         RECORD_NUM_S_BUCKETS;
     return pieces / solutionRange;
 }
+/**
+ * Calculates the total space pledged to the network.
+ *
+ * This function calculates the total amount of storage space that has been
+ * pledged to the Autonomys network by farmers, based on the current solution
+ * range and slot probability.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to total pledged space in bytes as bigint
+ * @throws Error if unable to retrieve solution ranges or calculate space
+ *
+ * @example
+ * ```typescript
+ * import { spacePledged } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const pledgedSpace = await spacePledged(api)
+ * const pledgedGB = Number(pledgedSpace) / (1024 ** 3)
+ * console.log(`Total pledged space: ${pledgedGB.toFixed(2)} GB`)
+ * ```
+ */
 const spacePledged = (api) => __awaiter(void 0, void 0, void 0, function* () {
     const _solutionRanges = yield (0, exports.solutionRanges)(api);
     const _slotProbability = (0, exports.slotProbability)(api);
@@ -88,12 +464,42 @@ const spacePledged = (api) => __awaiter(void 0, void 0, void 0, function* () {
     return totalSpacePledged;
 });
 exports.spacePledged = spacePledged;
+/**
+ * @deprecated Use spacePledged instead. This function will be removed in a future major release.
+ *
+ * Calculates the total space pledged to the network.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to total pledged space in bytes as bigint
+ */
 // This function is deprecated (use spacePledged instead) and will be removed in a future major release
 const spacePledge = (api) => __awaiter(void 0, void 0, void 0, function* () {
     console.warn('spacePledge is deprecated (use spacePledged instead) and will be removed in a future major release');
     return (0, exports.spacePledged)(api);
 });
 exports.spacePledge = spacePledge;
+/**
+ * Calculates the total blockchain size.
+ *
+ * This function calculates the total size of the blockchain by counting
+ * the number of segment commitments and multiplying by the size per segment.
+ * This represents the total amount of data stored in the blockchain.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to total blockchain size in bytes as bigint
+ * @throws Error if unable to retrieve segment commitments
+ *
+ * @example
+ * ```typescript
+ * import { blockchainSize } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const totalSize = await blockchainSize(api)
+ * const sizeGB = Number(totalSize) / (1024 ** 3)
+ * console.log(`Blockchain size: ${sizeGB.toFixed(2)} GB`)
+ * ```
+ */
 const blockchainSize = (api) => __awaiter(void 0, void 0, void 0, function* () {
     const _segmentCommitment = yield (0, exports.segmentCommitment)(api);
     const segmentsCount = BigInt(_segmentCommitment.length);

package/dist/position/index.d.ts

@@ -0,0 +1,42 @@
+import type { Api } from '@autonomys/auto-utils';
+import type { NominatorPosition } from '../types/position';
+/**
+ * Retrieves the complete staking position of a nominator for a specific operator.
+ *
+ * This function calculates the comprehensive staking position of a nominator including
+ * current value, pending deposits, pending withdrawals, and storage fee deposits.
+ * It handles complex calculations involving share prices across different epochs
+ * and provides a complete view of the nominator's stake position.
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to query position for
+ * @param nominatorAccountId - The account ID of the nominator
+ * @returns Promise that resolves to NominatorPosition with complete position details
+ * @throws Error if operator not found, domain staking summary unavailable, or calculation fails
+ *
+ * @example
+ * ```typescript
+ * import { nominatorPosition } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const position = await nominatorPosition(api, '1', 'nominator_account_address')
+ *
+ * console.log(`Current Value: ${position.knownValue}`)
+ * console.log(`Storage Fee Deposit: ${position.storageFeeDeposit}`)
+ * console.log(`Pending Deposits: ${position.pendingDeposits.length}`)
+ * console.log(`Pending Withdrawals: ${position.pendingWithdrawals.length}`)
+ *
+ * // Check pending deposits
+ * position.pendingDeposits.forEach(deposit => {
+ *   console.log(`Pending: ${deposit.amount} at epoch ${deposit.effectiveEpoch}`)
+ * })
+ *
+ * // Check pending withdrawals
+ * position.pendingWithdrawals.forEach(withdrawal => {
+ *   console.log(`Withdrawal: ${withdrawal.amount} unlocks at block ${withdrawal.unlockAtBlock}`)
+ * })
+ * ```
+ */
+export declare const nominatorPosition: (api: Api, operatorId: string | number | bigint, nominatorAccountId: string) => Promise<NominatorPosition>;
+//# sourceMappingURL=index.d.ts.map

package/dist/position/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/position/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAA;AAGhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAkH1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,iBAAiB,GAC5B,KAAK,GAAG,EACR,YAAY,MAAM,GAAG,MAAM,GAAG,MAAM,EACpC,oBAAoB,MAAM,KACzB,OAAO,CAAC,iBAAiB,CAkE3B,CAAA"}