@autonomys/auto-consensus 1.5.2 → 1.5.3

package/dist/position/index.js

@@ -15,11 +15,114 @@ const staking_1 = require("../staking");
 const price_1 = require("./price");
 const utils_1 = require("./utils");
 /**
- * High-level helper that returns the staking/storage position of a nominator inside an operator pool
+ * Processes pending deposits to calculate additional shares and storage fees
+ */
+const processPendingDeposits = (api, operatorId, depositData, currentEpochIndex) => __awaiter(void 0, void 0, void 0, function* () {
+    const zeroAmounts = {
+        additionalShares: BigInt(0),
+        pendingStorageFee: BigInt(0),
+        pendingDeposits: [],
+    };
+    if (!depositData.pending)
+        return zeroAmounts;
+    const { effectiveDomainEpoch, amount, storageFeeDeposit: pendingStorageFee } = depositData.pending;
+    // If epoch hasn't passed yet, keep as pending
+    if (effectiveDomainEpoch >= currentEpochIndex) {
+        return Object.assign(Object.assign({}, zeroAmounts), { pendingStorageFee, pendingDeposits: [{ amount, effectiveEpoch: effectiveDomainEpoch }] });
+    }
+    // Epoch has passed - convert pending amount to shares
+    try {
+        const epochSharePrice = yield (0, price_1.operatorEpochSharePrice)(api, operatorId, effectiveDomainEpoch, 0);
+        const additionalShares = epochSharePrice !== undefined ? (0, utils_1.stakeToShare)(amount, epochSharePrice) : amount; // Fallback: assume 1:1 conversion
+        if (epochSharePrice === undefined) {
+            console.warn(`No epoch share price found for epoch ${effectiveDomainEpoch}, using pending amount as is`);
+        }
+        return {
+            additionalShares,
+            pendingStorageFee, // Storage fee from processed pending deposit
+            pendingDeposits: [], // Empty array indicates pending deposit was processed
+        };
+    }
+    catch (error) {
+        console.warn(`Error getting epoch share price for epoch ${effectiveDomainEpoch}, treating as still pending:`, error);
+        return Object.assign(Object.assign({}, zeroAmounts), { pendingStorageFee, pendingDeposits: [{ amount, effectiveEpoch: effectiveDomainEpoch }] });
+    }
+});
+/**
+ * Processes pending withdrawals to calculate withdrawal amounts and unlock blocks
+ */
+const processPendingWithdrawals = (api, operatorId, withdrawalsData, currentEpochIndex) => __awaiter(void 0, void 0, void 0, function* () {
+    const pendingWithdrawals = [];
+    if (withdrawalsData.length === 0)
+        return pendingWithdrawals;
+    for (const withdrawal of withdrawalsData) {
+        const { withdrawalInShares } = withdrawal;
+        // Skip if no withdrawalInShares
+        if (!withdrawalInShares)
+            continue;
+        const { domainEpoch, shares, unlockAtConfirmedDomainBlockNumber } = withdrawalInShares;
+        // Process regular withdrawals
+        for (const w of withdrawal.withdrawals) {
+            pendingWithdrawals.push({
+                amount: w.amountToUnlock,
+                unlockAtDomainBlock: w.unlockAtConfirmedDomainBlockNumber,
+            });
+        }
+        const sharePrice = 
+        // If withdrawal epoch has passed, use its share price, otherwise use instant share price
+        domainEpoch[1] < currentEpochIndex
+            ? yield (0, price_1.operatorEpochSharePrice)(api, operatorId, domainEpoch[1], // epoch index
+            domainEpoch[0])
+            : yield (0, price_1.instantSharePrice)(api, operatorId);
+        const withdrawalAmount = sharePrice ? (0, utils_1.shareToStake)(shares, sharePrice) : BigInt(0); // fallback to 0 if no price available
+        pendingWithdrawals.push({
+            amount: withdrawalAmount,
+            unlockAtDomainBlock: unlockAtConfirmedDomainBlockNumber,
+        });
+    }
+    return pendingWithdrawals;
+});
+/**
+ * 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}`)
+ * })
+ * ```
  */
 const nominatorPosition = (api, operatorId, nominatorAccountId) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b;
     try {
+        // TODO: handle when operator is not found
         const operatorData = yield (0, staking_1.operator)(api, operatorId);
         // Step 1: Get deposits, withdrawals, and domain staking summary
         const [depositsData, withdrawalsData, stakingSummary] = yield Promise.all([
@@ -30,7 +133,8 @@ const nominatorPosition = (api, operatorId, nominatorAccountId) => __awaiter(voi
         if (!stakingSummary) {
             throw new Error('Domain staking summary not found');
         }
-        const depositData = depositsData.length > 0 ? depositsData[0] : null;
+        // Find the deposit data for the operator
+        const depositData = depositsData.find((d) => String(d.operatorId) === String(operatorId));
         if (!depositData) {
             return {
                 knownValue: BigInt(0),
@@ -39,75 +143,18 @@ const nominatorPosition = (api, operatorId, nominatorAccountId) => __awaiter(voi
                 storageFeeDeposit: BigInt(0),
             };
         }
-        const currentEpochIndex = stakingSummary.currentEpochIndex;
-        let totalShares = depositData.known.shares;
-        let totalStorageFeeDeposit = depositData.known.storageFeeDeposit + ((_b = (_a = depositData.pending) === null || _a === void 0 ? void 0 : _a.storageFeeDeposit) !== null && _b !== void 0 ? _b : BigInt(0));
-        const pendingDeposits = [];
-        if (depositData.pending) {
-            const { effectiveDomainEpoch, amount, storageFeeDeposit: pendingStorageFee, } = depositData.pending;
-            if (effectiveDomainEpoch <= currentEpochIndex) {
-                // Epoch has passed - convert pending amount to shares using epoch share price
-                try {
-                    const epochSharePrice = yield (0, price_1.operatorEpochSharePrice)(api, operatorId, effectiveDomainEpoch, 0);
-                    if (epochSharePrice !== undefined) {
-                        // Convert pending amount to shares and add to total
-                        const pendingShares = (0, utils_1.stakeToShare)(amount, epochSharePrice);
-                        totalShares += pendingShares;
-                        console.log(`Converted pending deposit: ${amount} tokens at epoch ${effectiveDomainEpoch} (price: ${epochSharePrice}) = ${pendingShares} shares`);
-                    }
-                    else {
-                        // Fallback: if no epoch price available, assume 1:1 conversion
-                        console.warn(`No epoch share price found for epoch ${effectiveDomainEpoch}, using pending amount as shares`);
-                        totalShares += amount;
-                    }
-                    // Add pending storage fee to total
-                    totalStorageFeeDeposit += pendingStorageFee;
-                }
-                catch (error) {
-                    console.warn(`Error getting epoch share price for epoch ${effectiveDomainEpoch}, treating as still pending:`, error);
-                    // Keep as pending if we can't get the epoch price
-                    pendingDeposits.push({
-                        amount: amount,
-                        effectiveEpoch: effectiveDomainEpoch,
-                    });
-                }
-            }
-            else {
-                // Epoch hasn't passed yet - keep as pending
-                pendingDeposits.push({
-                    amount: amount,
-                    effectiveEpoch: effectiveDomainEpoch,
-                });
-            }
-        }
-        // Step 3: Calculate current position value using instant share price
+        const { currentEpochIndex } = stakingSummary;
+        // Process pending deposits
+        const { additionalShares, pendingStorageFee, pendingDeposits } = yield processPendingDeposits(api, operatorId, depositData, currentEpochIndex);
+        // Calculate final totals
+        const totalShares = depositData.known.shares + additionalShares;
+        // Calculate total storage fee deposit: known + pending (handled by processPendingDeposits)
+        const totalStorageFeeDeposit = depositData.known.storageFeeDeposit + pendingStorageFee;
+        // Calculate current position value
         const currentSharePrice = yield (0, price_1.instantSharePrice)(api, operatorId);
         const knownValue = (0, utils_1.shareToStake)(totalShares, currentSharePrice);
-        // Step 4: Process pending withdrawals
-        const pendingWithdrawals = [];
-        if (withdrawalsData.length > 0) {
-            for (const withdrawal of withdrawalsData) {
-                // Process regular withdrawals
-                for (const w of withdrawal.withdrawals) {
-                    pendingWithdrawals.push({
-                        amount: w.amountToUnlock,
-                        unlockAtBlock: w.unlockAtConfirmedDomainBlockNumber,
-                    });
-                }
-                // Process withdrawal in shares
-                if (withdrawal.withdrawalInShares) {
-                    const sharePrice = yield (0, price_1.operatorEpochSharePrice)(api, operatorId, withdrawal.withdrawalInShares.domainEpoch[1], // epoch index
-                    withdrawal.withdrawalInShares.domainEpoch[0]);
-                    const withdrawalAmount = sharePrice
-                        ? (0, utils_1.shareToStake)(withdrawal.withdrawalInShares.shares, sharePrice)
-                        : BigInt(0); // fallback to 0 if no price available
-                    pendingWithdrawals.push({
-                        amount: withdrawalAmount,
-                        unlockAtBlock: withdrawal.withdrawalInShares.unlockAtConfirmedDomainBlockNumber,
-                    });
-                }
-            }
-        }
+        // Process pending withdrawals
+        const pendingWithdrawals = yield processPendingWithdrawals(api, operatorId, withdrawalsData, currentEpochIndex);
         return {
             knownValue,
             pendingDeposits,

package/dist/position/price.d.ts

@@ -1,12 +1,69 @@
 import type { Api } from '@autonomys/auto-utils';
 /**
- * Fetch the stored share price (18-dec Perbill) for a given (operatorId, domainEpoch) tuple
- * Returns undefined if no price is stored for that epoch (i.e. no staking activity)
+ * Retrieves the stored share price for a specific operator at a given domain epoch.
+ *
+ * This function fetches the historical share price that was recorded for an operator
+ * at a specific domain epoch. Share prices are stored when staking activity occurs
+ * and are used to convert between stake amounts and shares at different points in time.
+ * The price is returned in 18-decimal Perbill format.
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to query price for
+ * @param domainEpoch - The domain epoch index to query price for
+ * @param domainId - The domain ID (default: 0)
+ * @returns Promise that resolves to share price in 18-decimal Perbill format, or undefined if no price stored
+ * @throws Error if the query fails or operator/epoch not found
+ *
+ * @example
+ * ```typescript
+ * import { operatorEpochSharePrice } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get share price for operator 1 at epoch 100
+ * const sharePrice = await operatorEpochSharePrice(api, '1', 100, 0)
+ *
+ * if (sharePrice) {
+ *   console.log(`Share price at epoch 100: ${sharePrice}`)
+ *   // Use for stake/share conversions at that epoch
+ * } else {
+ *   console.log('No share price recorded for that epoch')
+ * }
+ * ```
  */
 export declare const operatorEpochSharePrice: (api: Api, operatorId: string | number | bigint, domainEpoch: string | number | bigint, domainId?: string | number | bigint) => Promise<bigint | undefined>;
 /**
- * Compute the on-the-fly share price for the operator in the current domain epoch
+ * Calculates the current real-time share price for an operator.
+ *
+ * This function computes the current share price by considering the operator's
+ * total stake, current epoch rewards (after nomination tax), and total shares.
+ * The calculation provides an up-to-date price that reflects recent staking
+ * activity and rewards distribution.
+ *
  * Formula: (currentTotalStake + currentEpochReward * (1 - nominationTax)) / currentTotalShares
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to calculate price for
+ * @returns Promise that resolves to current share price in 18-decimal Perbill format
+ * @throws Error if operator not found, domain staking summary unavailable, or calculation fails
+ *
+ * @example
+ * ```typescript
+ * import { instantSharePrice } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get current share price for operator 1
+ * const currentPrice = await instantSharePrice(api, '1')
+ * console.log(`Current share price: ${currentPrice}`)
+ *
+ * // Use for real-time stake/share conversions
+ * const stakeAmount = BigInt('1000000000000000000') // 1 AI3
+ * const sharesEquivalent = (stakeAmount * BigInt(10 ** 18)) / currentPrice
+ * console.log(`${stakeAmount} stake = ${sharesEquivalent} shares`)
+ * ```
  */
 export declare const instantSharePrice: (api: Api, operatorId: string | number | bigint) => Promise<bigint>;
 //# sourceMappingURL=price.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"price.d.ts","sourceRoot":"","sources":["../../src/position/price.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAA;AAKhD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,KAAK,GAAG,EACR,YAAY,MAAM,GAAG,MAAM,GAAG,MAAM,EACpC,aAAa,MAAM,GAAG,MAAM,GAAG,MAAM,EACrC,WAAU,MAAM,GAAG,MAAM,GAAG,MAAU,KACrC,OAAO,CAAC,MAAM,GAAG,SAAS,CAmC5B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,KAAK,GAAG,EACR,YAAY,MAAM,GAAG,MAAM,GAAG,MAAM,KACnC,OAAO,CAAC,MAAM,CAiChB,CAAA"}
+{"version":3,"file":"price.d.ts","sourceRoot":"","sources":["../../src/position/price.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAA;AAKhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,uBAAuB,GAClC,KAAK,GAAG,EACR,YAAY,MAAM,GAAG,MAAM,GAAG,MAAM,EACpC,aAAa,MAAM,GAAG,MAAM,GAAG,MAAM,EACrC,WAAU,MAAM,GAAG,MAAM,GAAG,MAAU,KACrC,OAAO,CAAC,MAAM,GAAG,SAAS,CAmC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,iBAAiB,GAC5B,KAAK,GAAG,EACR,YAAY,MAAM,GAAG,MAAM,GAAG,MAAM,KACnC,OAAO,CAAC,MAAM,CAiChB,CAAA"}

package/dist/position/price.js

@@ -14,8 +14,37 @@ const domain_1 = require("../domain");
 const staking_1 = require("../staking");
 const parse_1 = require("../utils/parse");
 /**
- * Fetch the stored share price (18-dec Perbill) for a given (operatorId, domainEpoch) tuple
- * Returns undefined if no price is stored for that epoch (i.e. no staking activity)
+ * Retrieves the stored share price for a specific operator at a given domain epoch.
+ *
+ * This function fetches the historical share price that was recorded for an operator
+ * at a specific domain epoch. Share prices are stored when staking activity occurs
+ * and are used to convert between stake amounts and shares at different points in time.
+ * The price is returned in 18-decimal Perbill format.
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to query price for
+ * @param domainEpoch - The domain epoch index to query price for
+ * @param domainId - The domain ID (default: 0)
+ * @returns Promise that resolves to share price in 18-decimal Perbill format, or undefined if no price stored
+ * @throws Error if the query fails or operator/epoch not found
+ *
+ * @example
+ * ```typescript
+ * import { operatorEpochSharePrice } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get share price for operator 1 at epoch 100
+ * const sharePrice = await operatorEpochSharePrice(api, '1', 100, 0)
+ *
+ * if (sharePrice) {
+ *   console.log(`Share price at epoch 100: ${sharePrice}`)
+ *   // Use for stake/share conversions at that epoch
+ * } else {
+ *   console.log('No share price recorded for that epoch')
+ * }
+ * ```
  */
 const operatorEpochSharePrice = (api_1, operatorId_1, domainEpoch_1, ...args_1) => __awaiter(void 0, [api_1, operatorId_1, domainEpoch_1, ...args_1], void 0, function* (api, operatorId, domainEpoch, domainId = 0) {
     try {
@@ -46,8 +75,36 @@ const operatorEpochSharePrice = (api_1, operatorId_1, domainEpoch_1, ...args_1)
 });
 exports.operatorEpochSharePrice = operatorEpochSharePrice;
 /**
- * Compute the on-the-fly share price for the operator in the current domain epoch
+ * Calculates the current real-time share price for an operator.
+ *
+ * This function computes the current share price by considering the operator's
+ * total stake, current epoch rewards (after nomination tax), and total shares.
+ * The calculation provides an up-to-date price that reflects recent staking
+ * activity and rewards distribution.
+ *
  * Formula: (currentTotalStake + currentEpochReward * (1 - nominationTax)) / currentTotalShares
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to calculate price for
+ * @returns Promise that resolves to current share price in 18-decimal Perbill format
+ * @throws Error if operator not found, domain staking summary unavailable, or calculation fails
+ *
+ * @example
+ * ```typescript
+ * import { instantSharePrice } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get current share price for operator 1
+ * const currentPrice = await instantSharePrice(api, '1')
+ * console.log(`Current share price: ${currentPrice}`)
+ *
+ * // Use for real-time stake/share conversions
+ * const stakeAmount = BigInt('1000000000000000000') // 1 AI3
+ * const sharesEquivalent = (stakeAmount * BigInt(10 ** 18)) / currentPrice
+ * console.log(`${stakeAmount} stake = ${sharesEquivalent} shares`)
+ * ```
  */
 const instantSharePrice = (api, operatorId) => __awaiter(void 0, void 0, void 0, function* () {
     try {

package/dist/position/utils.d.ts

@@ -1,11 +1,62 @@
 /**
- * Convert shares to stake using an 18-decimal Perbill price
+ * Converts operator shares to stake amount using a given share price.
+ *
+ * This utility function converts a number of operator shares to the equivalent
+ * stake amount using the provided share price. The share price should be in
+ * 18-decimal Perbill format as returned by the price functions.
+ *
  * Formula: shares * price / 10^18
+ *
+ * @param shares - Number of shares to convert
+ * @param price - Share price in 18-decimal Perbill format
+ * @returns Equivalent stake amount in smallest token units
+ *
+ * @example
+ * ```typescript
+ * import { shareToStake, instantSharePrice } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get current share price
+ * const sharePrice = await instantSharePrice(api, '1')
+ *
+ * // Convert 1000 shares to stake amount
+ * const shares = BigInt(1000)
+ * const stakeAmount = shareToStake(shares, sharePrice)
+ * console.log(`${shares} shares = ${stakeAmount} tokens`)
+ * ```
  */
 export declare const shareToStake: (shares: bigint, price: bigint) => bigint;
 /**
- * Convert stake to shares using an 18-decimal Perbill price
+ * Converts stake amount to operator shares using a given share price.
+ *
+ * This utility function converts a stake amount to the equivalent number
+ * of operator shares using the provided share price. The share price should
+ * be in 18-decimal Perbill format as returned by the price functions.
+ *
  * Formula: stake * 10^18 / price
+ *
+ * @param stake - Stake amount in smallest token units to convert
+ * @param price - Share price in 18-decimal Perbill format
+ * @returns Equivalent number of shares
+ * @throws Error if price is zero (division by zero)
+ *
+ * @example
+ * ```typescript
+ * import { stakeToShare, instantSharePrice } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get current share price
+ * const sharePrice = await instantSharePrice(api, '1')
+ *
+ * // Convert 1 AI3 to shares
+ * const stakeAmount = BigInt('1000000000000000000') // 1 AI3
+ * const shares = stakeToShare(stakeAmount, sharePrice)
+ * console.log(`${stakeAmount} tokens = ${shares} shares`)
+ * ```
  */
 export declare const stakeToShare: (stake: bigint, price: bigint) => bigint;
 //# sourceMappingURL=utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/position/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,OAAO,MAAM,KAAG,MAE5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,EAAE,OAAO,MAAM,KAAG,MAK3D,CAAA"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/position/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,OAAO,MAAM,KAAG,MAE5D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,EAAE,OAAO,MAAM,KAAG,MAK3D,CAAA"}

package/dist/position/utils.js

@@ -2,16 +2,67 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stakeToShare = exports.shareToStake = void 0;
 /**
- * Convert shares to stake using an 18-decimal Perbill price
+ * Converts operator shares to stake amount using a given share price.
+ *
+ * This utility function converts a number of operator shares to the equivalent
+ * stake amount using the provided share price. The share price should be in
+ * 18-decimal Perbill format as returned by the price functions.
+ *
  * Formula: shares * price / 10^18
+ *
+ * @param shares - Number of shares to convert
+ * @param price - Share price in 18-decimal Perbill format
+ * @returns Equivalent stake amount in smallest token units
+ *
+ * @example
+ * ```typescript
+ * import { shareToStake, instantSharePrice } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get current share price
+ * const sharePrice = await instantSharePrice(api, '1')
+ *
+ * // Convert 1000 shares to stake amount
+ * const shares = BigInt(1000)
+ * const stakeAmount = shareToStake(shares, sharePrice)
+ * console.log(`${shares} shares = ${stakeAmount} tokens`)
+ * ```
  */
 const shareToStake = (shares, price) => {
     return (shares * price) / BigInt(Math.pow(10, 18));
 };
 exports.shareToStake = shareToStake;
 /**
- * Convert stake to shares using an 18-decimal Perbill price
+ * Converts stake amount to operator shares using a given share price.
+ *
+ * This utility function converts a stake amount to the equivalent number
+ * of operator shares using the provided share price. The share price should
+ * be in 18-decimal Perbill format as returned by the price functions.
+ *
  * Formula: stake * 10^18 / price
+ *
+ * @param stake - Stake amount in smallest token units to convert
+ * @param price - Share price in 18-decimal Perbill format
+ * @returns Equivalent number of shares
+ * @throws Error if price is zero (division by zero)
+ *
+ * @example
+ * ```typescript
+ * import { stakeToShare, instantSharePrice } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get current share price
+ * const sharePrice = await instantSharePrice(api, '1')
+ *
+ * // Convert 1 AI3 to shares
+ * const stakeAmount = BigInt('1000000000000000000') // 1 AI3
+ * const shares = stakeToShare(stakeAmount, sharePrice)
+ * console.log(`${stakeAmount} tokens = ${shares} shares`)
+ * ```
  */
 const stakeToShare = (stake, price) => {
     if (price === BigInt(0)) {

package/dist/remark.d.ts

@@ -1,3 +1,32 @@
 import type { ApiPromise } from '@autonomys/auto-utils';
+/**
+ * Creates a remark transaction for adding arbitrary data to the blockchain.
+ *
+ * Remark transactions allow you to include arbitrary data in the blockchain without
+ * affecting the state. This is useful for timestamping data, adding metadata,
+ * or including custom information that needs to be permanently recorded.
+ *
+ * @param api - The connected API promise instance
+ * @param remark - The remark data to include in the transaction (as string or bytes)
+ * @param withEvent - Whether to emit an event for this remark (default: false)
+ * @returns A submittable remark transaction
+ *
+ * @example
+ * ```typescript
+ * import { remark } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Create a simple remark
+ * const remarkTx = remark(api, 'Hello, blockchain!')
+ *
+ * // Create a remark with event
+ * const remarkWithEventTx = remark(api, JSON.stringify({ timestamp: Date.now() }), true)
+ *
+ * // Sign and send the transaction
+ * await signAndSendTx(sender, remarkTx)
+ * ```
+ */
 export declare const remark: (api: ApiPromise, remark: string, withEvent?: boolean) => import("@autonomys/auto-utils").SubmittableExtrinsic<"promise", import("@autonomys/auto-utils").ISubmittableResult>;
 //# sourceMappingURL=remark.d.ts.map

package/dist/remark.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remark.d.ts","sourceRoot":"","sources":["../src/remark.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAEvD,eAAO,MAAM,MAAM,GAAI,KAAK,UAAU,EAAE,QAAQ,MAAM,EAAE,YAAY,OAAO,wHACQ,CAAA"}
+{"version":3,"file":"remark.d.ts","sourceRoot":"","sources":["../src/remark.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,MAAM,GAAI,KAAK,UAAU,EAAE,QAAQ,MAAM,EAAE,YAAY,OAAO,wHACQ,CAAA"}

package/dist/remark.js

@@ -1,5 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.remark = void 0;
+/**
+ * Creates a remark transaction for adding arbitrary data to the blockchain.
+ *
+ * Remark transactions allow you to include arbitrary data in the blockchain without
+ * affecting the state. This is useful for timestamping data, adding metadata,
+ * or including custom information that needs to be permanently recorded.
+ *
+ * @param api - The connected API promise instance
+ * @param remark - The remark data to include in the transaction (as string or bytes)
+ * @param withEvent - Whether to emit an event for this remark (default: false)
+ * @returns A submittable remark transaction
+ *
+ * @example
+ * ```typescript
+ * import { remark } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Create a simple remark
+ * const remarkTx = remark(api, 'Hello, blockchain!')
+ *
+ * // Create a remark with event
+ * const remarkWithEventTx = remark(api, JSON.stringify({ timestamp: Date.now() }), true)
+ *
+ * // Sign and send the transaction
+ * await signAndSendTx(sender, remarkTx)
+ * ```
+ */
 const remark = (api, remark, withEvent) => !withEvent ? api.tx.system.remark(remark) : api.tx.system.remarkWithEvent(remark);
 exports.remark = remark;