@autonomys/auto-consensus 1.5.1 → 1.5.3

package/dist/position/index.js

@@ -0,0 +1,170 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nominatorPosition = void 0;
+const domain_1 = require("../domain");
+const staking_1 = require("../staking");
+const price_1 = require("./price");
+const utils_1 = require("./utils");
+/**
+ * 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* () {
+    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([
+            (0, staking_1.deposits)(api, operatorId, nominatorAccountId),
+            (0, staking_1.withdrawals)(api, operatorId, nominatorAccountId),
+            (0, domain_1.domainStakingSummary)(api, operatorData.currentDomainId),
+        ]);
+        if (!stakingSummary) {
+            throw new Error('Domain staking summary not found');
+        }
+        // Find the deposit data for the operator
+        const depositData = depositsData.find((d) => String(d.operatorId) === String(operatorId));
+        if (!depositData) {
+            return {
+                knownValue: BigInt(0),
+                pendingDeposits: [],
+                pendingWithdrawals: [],
+                storageFeeDeposit: BigInt(0),
+            };
+        }
+        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);
+        // Process pending withdrawals
+        const pendingWithdrawals = yield processPendingWithdrawals(api, operatorId, withdrawalsData, currentEpochIndex);
+        return {
+            knownValue,
+            pendingDeposits,
+            pendingWithdrawals,
+            storageFeeDeposit: totalStorageFeeDeposit,
+        };
+    }
+    catch (error) {
+        console.error('Error calculating nominator position:', error);
+        throw new Error(`Error calculating position for nominator ${nominatorAccountId} in operator ${operatorId}: ${error}`);
+    }
+});
+exports.nominatorPosition = nominatorPosition;

package/dist/position/price.d.ts

@@ -0,0 +1,69 @@
+import type { Api } from '@autonomys/auto-utils';
+/**
+ * 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>;
+/**
+ * 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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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

@@ -0,0 +1,137 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instantSharePrice = exports.operatorEpochSharePrice = void 0;
+const domain_1 = require("../domain");
+const staking_1 = require("../staking");
+const parse_1 = require("../utils/parse");
+/**
+ * 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 {
+        // Create domain epoch tuple [domainId, epochIndex]
+        const domainEpochTuple = [(0, parse_1.parseString)(domainId), (0, parse_1.parseString)(domainEpoch)];
+        const sharePrice = yield api.query.domains.operatorEpochSharePrice((0, parse_1.parseString)(operatorId), domainEpochTuple);
+        if (sharePrice.isEmpty) {
+            return undefined;
+        }
+        // The response is a direct Perbill value, not an object
+        const priceValue = sharePrice.toJSON();
+        if (priceValue === null || priceValue === undefined) {
+            return undefined;
+        }
+        // Convert to bigint - the value is already in Perbill format but needs to be scaled to 18 decimals
+        // The raw value from chain is in parts per billion (9 decimals), we need 18 decimals
+        const perbillValue = BigInt(priceValue.toString());
+        const scaledPrice = perbillValue * BigInt(Math.pow(10, 9)); // Scale from 9 to 18 decimals
+        // Invert the share price: if API returns 0.5601 (shares worth 56% of original),
+        // we need 1/0.5601 ≈ 1.785 for stakeToShare conversion
+        const oneInPerbill = BigInt(Math.pow(10, 18));
+        return (oneInPerbill * oneInPerbill) / scaledPrice;
+    }
+    catch (error) {
+        console.error('Error fetching operator epoch share price:', error);
+        throw new Error(`Error fetching share price for operator ${operatorId} at epoch ${domainEpoch}: ${error}`);
+    }
+});
+exports.operatorEpochSharePrice = operatorEpochSharePrice;
+/**
+ * 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 {
+        // Get operator details
+        const operatorDetails = yield (0, staking_1.operator)(api, operatorId);
+        const { currentTotalStake, currentTotalShares, nominationTax, currentDomainId } = operatorDetails;
+        // Get domain staking summary to find current epoch rewards
+        const domainSummary = yield (0, domain_1.domainStakingSummary)(api, currentDomainId);
+        if (!domainSummary) {
+            throw new Error(`No staking summary found for domain ${currentDomainId}`);
+        }
+        // Get current epoch reward for this operator
+        const currentEpochReward = domainSummary.currentEpochRewards[(0, parse_1.parseString)(operatorId)];
+        const rewardBigInt = currentEpochReward ? BigInt(currentEpochReward) : BigInt(0);
+        // Calculate effective stake: currentTotalStake + currentEpochReward * (1 - nominationTax)
+        const rewardAfterTax = (rewardBigInt * BigInt(100 - nominationTax)) / BigInt(100);
+        const effectiveStake = currentTotalStake + rewardAfterTax;
+        // Avoid division by zero
+        if (currentTotalShares === BigInt(0)) {
+            return BigInt(Math.pow(10, 18)); // Return 1.0 in Perbill format
+        }
+        // Return price in 18-decimal Perbill format
+        return (effectiveStake * BigInt(Math.pow(10, 18))) / currentTotalShares;
+    }
+    catch (error) {
+        console.error('Error computing instant share price:', error);
+        throw new Error(`Error computing instant share price for operator ${operatorId}: ${error}`);
+    }
+});
+exports.instantSharePrice = instantSharePrice;

package/dist/position/utils.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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;
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stakeToShare = exports.shareToStake = void 0;
+/**
+ * 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;
+/**
+ * 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)) {
+        throw new Error('Price cannot be zero for stake to share conversion');
+    }
+    return (stake * BigInt(Math.pow(10, 18))) / price;
+};
+exports.stakeToShare = stakeToShare;

package/dist/position.d.ts

@@ -0,0 +1,4 @@
+export * from './position/index';
+export * from './position/price';
+export * from './position/utils';
+//# sourceMappingURL=position.d.ts.map

package/dist/position.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../src/position.ts"],"names":[],"mappings":"AAEA,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA"}

package/dist/position.js

@@ -0,0 +1,20 @@
+"use strict";
+// file: src/position.ts
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./position/index"), exports);
+__exportStar(require("./position/price"), exports);
+__exportStar(require("./position/utils"), exports);

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;