@autonomys/auto-utils 1.5.16 → 1.5.17

package/dist/api.js

@@ -1,24 +1,4 @@
 "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());
-    });
-};
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.disconnect = exports.activateDomain = exports.activate = exports.createConnection = void 0;
 const api_1 = require("@polkadot/api");
@@ -63,15 +43,19 @@ const network_2 = require("./types/network");
  *
  * @throws {Error} When connection fails or API initialization fails.
  */
-const createConnection = (endpoint, options) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a;
+const createConnection = async (endpoint, options) => {
     // Create the provider
     const provider = new api_1.WsProvider(endpoint);
     // Create the API instance
-    const api = yield api_1.ApiPromise.create(Object.assign(Object.assign({}, options), { types: Object.assign(Object.assign({}, network_2.CHAIN_TYPES), options === null || options === void 0 ? void 0 : options.types), noInitWarn: (_a = options === null || options === void 0 ? void 0 : options.noInitWarn) !== null && _a !== void 0 ? _a : true, provider }));
-    yield api.isReady;
+    const api = await api_1.ApiPromise.create({
+        ...options,
+        types: { ...network_2.CHAIN_TYPES, ...options?.types },
+        noInitWarn: options?.noInitWarn ?? true,
+        provider,
+    });
+    await api.isReady;
     return api;
-});
+};
 exports.createConnection = createConnection;
 /**
  * Activates a connection to the Autonomys Network consensus layer.
@@ -110,14 +94,14 @@ exports.createConnection = createConnection;
  *
  * @throws {Error} When the specified network is not found or connection fails.
  */
-const activate = (params) => __awaiter(void 0, void 0, void 0, function* () {
+const activate = async (params) => {
     // Get the first rpc urls for the network
     const endpoint = (0, network_1.getNetworkRpcUrls)(params);
     // Remove the networkId from the input
     if (params)
         delete params.networkId;
-    return yield (0, exports.createConnection)(endpoint, params);
-});
+    return await (0, exports.createConnection)(endpoint, params);
+};
 exports.activate = activate;
 /**
  * Activates a connection to a specific domain within the Autonomys Network.
@@ -164,14 +148,14 @@ exports.activate = activate;
  *
  * @throws {Error} When the specified network or domain is not found, or connection fails.
  */
-const activateDomain = (params) => __awaiter(void 0, void 0, void 0, function* () {
+const activateDomain = async (params) => {
     // Get the first rpc urls for the network
     const endpoint = (0, network_1.getNetworkDomainRpcUrls)(params);
     // Remove the domainId from the input
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const { domainId } = params, rest = __rest(params, ["domainId"]);
-    return yield (0, exports.createConnection)(endpoint, rest);
-});
+    const { domainId, ...rest } = params;
+    return await (0, exports.createConnection)(endpoint, rest);
+};
 exports.activateDomain = activateDomain;
 /**
  * Disconnects an active API connection and cleans up resources.
@@ -200,8 +184,8 @@ exports.activateDomain = activateDomain;
  * // Or use the API instance method directly
  * // await api.disconnect()
  */
-const disconnect = (api) => __awaiter(void 0, void 0, void 0, function* () {
+const disconnect = async (api) => {
     // Disconnect the API instance and the provider
-    yield api.disconnect();
-});
+    await api.disconnect();
+};
 exports.disconnect = disconnect;

package/dist/constants/network.js

@@ -38,7 +38,11 @@ exports.networks = [
             },
         ],
         domains: [
-            Object.assign(Object.assign({ domainId: '0' }, domain_1.domains[domain_1.DomainRuntime.AUTO_EVM]), { rpcUrls: ['wss://auto-evm.mainnet.autonomys.xyz/ws'] }),
+            {
+                domainId: '0',
+                ...domain_1.domains[domain_1.DomainRuntime.AUTO_EVM],
+                rpcUrls: ['wss://auto-evm.mainnet.autonomys.xyz/ws'],
+            },
         ],
         token: token_1.DEFAULT_TOKEN,
     },
@@ -53,7 +57,11 @@ exports.networks = [
             },
         ],
         domains: [
-            Object.assign(Object.assign({ domainId: '0' }, domain_1.domains[domain_1.DomainRuntime.AUTO_EVM]), { rpcUrls: ['wss://auto-evm.chronos.autonomys.xyz/ws'] }),
+            {
+                domainId: '0',
+                ...domain_1.domains[domain_1.DomainRuntime.AUTO_EVM],
+                rpcUrls: ['wss://auto-evm.chronos.autonomys.xyz/ws'],
+            },
         ],
         token: token_1.TESTNET_TOKEN,
         isTestnet: true,
@@ -64,7 +72,11 @@ exports.networks = [
         rpcUrls: ['wss://rpc-0.taurus.autonomys.xyz/ws'],
         explorer: [],
         domains: [
-            Object.assign(Object.assign({ domainId: '0' }, domain_1.domains[domain_1.DomainRuntime.AUTO_EVM]), { rpcUrls: ['wss://auto-evm.taurus.autonomys.xyz/ws'] }),
+            {
+                domainId: '0',
+                ...domain_1.domains[domain_1.DomainRuntime.AUTO_EVM],
+                rpcUrls: ['wss://auto-evm.taurus.autonomys.xyz/ws'],
+            },
         ],
         token: token_1.TESTNET_TOKEN,
         isTestnet: true,
@@ -76,8 +88,16 @@ exports.networks = [
         rpcUrls: ['ws://rpc.devnet.autonomys.xyz/ws'],
         explorer: [],
         domains: [
-            Object.assign(Object.assign({ domainId: '0' }, domain_1.domains[domain_1.DomainRuntime.AUTO_EVM]), { rpcUrls: ['wss://auto-evm.devnet.autonomys.xyz/ws'] }),
-            Object.assign(Object.assign({ domainId: '1' }, domain_1.domains[domain_1.DomainRuntime.AUTO_ID]), { rpcUrls: ['wss://autoid.devnet.autonomys.xyz/ws'] }),
+            {
+                domainId: '0',
+                ...domain_1.domains[domain_1.DomainRuntime.AUTO_EVM],
+                rpcUrls: ['wss://auto-evm.devnet.autonomys.xyz/ws'],
+            },
+            {
+                domainId: '1',
+                ...domain_1.domains[domain_1.DomainRuntime.AUTO_ID],
+                rpcUrls: ['wss://autoid.devnet.autonomys.xyz/ws'],
+            },
         ],
         token: token_1.TESTNET_TOKEN,
         isTestnet: true,
@@ -89,8 +109,16 @@ exports.networks = [
         rpcUrls: ['ws://127.0.0.1:9944/ws'],
         explorer: [],
         domains: [
-            Object.assign(Object.assign({ domainId: '0' }, domain_1.domains[domain_1.DomainRuntime.AUTO_EVM]), { rpcUrls: ['ws://127.0.0.1:9945/ws'] }),
-            Object.assign(Object.assign({ domainId: '1' }, domain_1.domains[domain_1.DomainRuntime.AUTO_ID]), { rpcUrls: ['ws://127.0.0.1:9946/ws'] }),
+            {
+                domainId: '0',
+                ...domain_1.domains[domain_1.DomainRuntime.AUTO_EVM],
+                rpcUrls: ['ws://127.0.0.1:9945/ws'],
+            },
+            {
+                domainId: '1',
+                ...domain_1.domains[domain_1.DomainRuntime.AUTO_ID],
+                rpcUrls: ['ws://127.0.0.1:9946/ws'],
+            },
         ],
         token: token_1.TESTNET_TOKEN,
         isTestnet: true,

package/dist/constants/token.js

@@ -9,4 +9,8 @@ exports.DEFAULT_TOKEN = {
     symbol: exports.DEFAULT_TOKEN_SYMBOL,
     name: exports.DEFAULT_TOKEN_NAME,
 };
-exports.TESTNET_TOKEN = Object.assign(Object.assign({}, exports.DEFAULT_TOKEN), { symbol: 't' + exports.DEFAULT_TOKEN_SYMBOL, name: 'Testnet ' + exports.DEFAULT_TOKEN_NAME });
+exports.TESTNET_TOKEN = {
+    ...exports.DEFAULT_TOKEN,
+    symbol: 't' + exports.DEFAULT_TOKEN_SYMBOL,
+    name: 'Testnet ' + exports.DEFAULT_TOKEN_NAME,
+};

package/dist/number.d.ts

@@ -3,59 +3,64 @@
  *
  * This function converts token amounts stored in their smallest unit (with decimal places)
  * back to their standard decimal representation. It handles both string and BigInt inputs
- * and is essential for displaying token balances in user interfaces.
+ * and is useful for displaying token balances in user interfaces.
+ *
+ * This function uses floating-point arithmetic and may lose precision
+ * for large values or high-precision decimals. For precise calculations, consider using
+ * `formatUnits` or `shannonsToAi3` instead.
  *
  * @param amount - The token amount in smallest units (string or BigInt).
  * @param decimals - Number of decimal places the token uses. Defaults to 18 for AI3 tokens.
- * @returns The parsed amount as a number with decimal places applied.
+ * @returns The parsed amount as a number (for string input) or bigint (for BigInt input).
  *
  * @example
  * import { parseTokenAmount } from '@autonomys/auto-utils'
  *
- * // Parse AI3 token amount (18 decimals)
+ * // Parse AI3 token amount (18 decimals) - string input returns number
  * const balance = '1000000000000000000' // 1 AI3 in smallest units
  * const readable = parseTokenAmount(balance)
- * console.log(readable) // Output: 1
+ * console.log(readable) // Output: 1 (number)
  *
- * // Parse with custom decimals
+ * // Parse with BigInt input - returns bigint
  * const customBalance = BigInt('1000000') // 1 token with 6 decimals
  * const customReadable = parseTokenAmount(customBalance, 6)
- * console.log(customReadable) // Output: 1
+ * console.log(customReadable) // Output: 1n (bigint)
  *
  * // Parse fractional amounts
  * const fractional = '500000000000000000' // 0.5 AI3
  * const fractionalReadable = parseTokenAmount(fractional)
- * console.log(fractionalReadable) // Output: 0.5
+ * console.log(fractionalReadable) // Output: 0.5 (number)
  */
 export declare const parseTokenAmount: (amount: string | bigint, decimals?: number) => number | bigint;
 /**
  * Formats a human-readable token amount to its smallest unit representation.
  *
- * This function converts user-friendly decimal token amounts into the format required
- * for blockchain transactions. It multiplies the amount by the appropriate power of 10
- * based on the token's decimal places.
+ *
+ * This function uses floating-point arithmetic for number inputs
+ * and may lose precision for large values or high-precision decimals. For precise calculations,
+ * consider using `parseUnits` or `ai3ToShannons` instead.
  *
  * @param amount - The token amount in human-readable format (number or BigInt).
  * @param decimals - Number of decimal places the token uses. Defaults to 18 for AI3 tokens.
- * @returns The formatted amount in smallest units (BigInt for BigInt input, number for number input).
+ * @returns The formatted amount in smallest units (number for number input, BigInt for BigInt input).
  *
  * @example
  * import { formatTokenAmount } from '@autonomys/auto-utils'
  *
- * // Format AI3 token amount (18 decimals)
+ * // Format AI3 token amount (18 decimals) - number input returns number
  * const userAmount = 1.5 // 1.5 AI3
  * const formatted = formatTokenAmount(userAmount)
- * console.log(formatted) // Output: 1500000000000000000
+ * console.log(formatted) // Output: 1500000000000000000 (number)
  *
- * // Format with BigInt input
+ * // Format with BigInt input - returns BigInt
  * const bigAmount = BigInt(10)
  * const bigFormatted = formatTokenAmount(bigAmount)
- * console.log(bigFormatted) // Output: 10000000000000000000n
+ * console.log(bigFormatted) // Output: 10000000000000000000n (BigInt)
  *
  * // Format with custom decimals
  * const customAmount = 100
  * const customFormatted = formatTokenAmount(customAmount, 6)
- * console.log(customFormatted) // Output: 100000000
+ * console.log(customFormatted) // Output: 100000000 (number)
  */
 export declare const formatTokenAmount: (amount: number | bigint, decimals?: number) => number | bigint;
 /**
@@ -92,4 +97,78 @@ export declare const formatTokenAmount: (amount: number | bigint, decimals?: num
  * console.log(formatSpacePledged(hugeSpace)) // Output: "1.00 EiB"
  */
 export declare const formatSpacePledged: (value: bigint, decimals?: number) => string;
+/**
+ * Parse a human-readable decimal string into smallest units as a bigint.
+ *
+ * - Accepts optional leading sign and a single decimal point
+ * - Disallows scientific notation
+ * - If fractional digits exceed `decimals`, defaults to throwing; caller can opt into truncation or rounding
+ * - If `options.rounding` is `'round'`, rounds half up based on the first discarded digit (i.e., if the first omitted digit is 5 or greater, rounds up)
+ * - If `options.rounding` is `'ceil'`, always rounds up if there are any excess fractional digits (ceiling function)
+ * - This is not banker's rounding (half to even) or round away from zero
+ */
+export declare const parseUnits: (value: string, decimals?: number, options?: {
+    rounding?: "error" | "truncate" | "round" | "ceil";
+}) => bigint;
+/**
+ * Format smallest units bigint into a human-readable decimal string.
+ *
+ * - No floating point used
+ * - Trims trailing zeros by default and removes decimal point if fractional becomes zero
+ */
+export declare const formatUnits: (value: bigint | string, decimals?: number, options?: {
+    trimTrailingZeros?: boolean;
+}) => string;
+/**
+ * Convert AI3 token amount to Shannon units (smallest units).
+ *
+ * Converts a human-readable AI3 amount (like "1.5") to its exact representation
+ * in Shannon units as a BigInt. This ensures perfect precision for financial calculations.
+ *
+ * @param ai3Amount - AI3 amount as a decimal string (e.g., "1.5", "0.000000000000000001")
+ * @param options - Rounding behavior for excess decimal places
+ * @returns Shannon amount as BigInt (e.g., 1500000000000000000n for "1.5" AI3)
+ *
+ * @example
+ * import { ai3ToShannons } from '@autonomys/auto-utils'
+ *
+ * // Convert 1.5 AI3 to Shannon
+ * const shannons = ai3ToShannons("1.5")
+ * console.log(shannons) // 1500000000000000000n
+ *
+ * // Convert tiny amount
+ * const tinyShannons = ai3ToShannons("0.000000000000000001")
+ * console.log(tinyShannons) // 1n
+ *
+ * // Always round up with excess decimals
+ * const ceilShannons = ai3ToShannons("1.0000000000000000001", { rounding: 'ceil' })
+ * console.log(shannonsToAi3(ceilShannons)) // "1.000000000000000001"
+ */
+export declare const ai3ToShannons: (ai3Amount: string, options?: {
+    rounding?: "error" | "truncate" | "round" | "ceil";
+}) => bigint;
+/**
+ * Convert Shannon units to AI3 token amount.
+ *
+ * Converts Shannon units (smallest units) back to a human-readable AI3 amount.
+ * Uses exact BigInt arithmetic to avoid any precision loss.
+ *
+ * @param shannons - Shannon amount as BigInt or string
+ * @param options - Formatting options (trailing zero trimming)
+ * @returns AI3 amount as decimal string (e.g., "1.5" for 1500000000000000000n Shannon)
+ *
+ * @example
+ * import { shannonsToAi3 } from '@autonomys/auto-utils'
+ *
+ * // Convert Shannon back to AI3
+ * const ai3Amount = shannonsToAi3(1500000000000000000n)
+ * console.log(ai3Amount) // "1.5"
+ *
+ * // Convert single Shannon
+ * const tinyAi3 = shannonsToAi3(1n)
+ * console.log(tinyAi3) // "0.000000000000000001"
+ */
+export declare const shannonsToAi3: (shannons: bigint | string, options?: {
+    trimTrailingZeros?: boolean;
+}) => string;
 //# sourceMappingURL=number.d.ts.map

package/dist/number.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"number.d.ts","sourceRoot":"","sources":["../src/number.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,MAAM,GAAG,MAAM,EACvB,WAAU,MAA+B,oBAI1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,MAAM,GAAG,MAAM,EACvB,WAAU,MAA+B,oBAI1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,iBAAY,WAU7D,CAAA"}
+{"version":3,"file":"number.d.ts","sourceRoot":"","sources":["../src/number.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,MAAM,GAAG,MAAM,EACvB,WAAU,MAA+B,oBAI1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,MAAM,GAAG,MAAM,EACvB,WAAU,MAA+B,oBAI1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,iBAAY,WAU7D,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,MAAM,EACb,WAAU,MAA+B,EACzC,UAAS;IAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAA;CAAO,KACnE,MA2DF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GACtB,OAAO,MAAM,GAAG,MAAM,EACtB,WAAU,MAA+B,EACzC,UAAS;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAO,KAC5C,MAkBF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa,GACxB,WAAW,MAAM,EACjB,UAAS;IAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAA;CAAO,KACnE,MAAgE,CAAA;AAEnE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,GACxB,UAAU,MAAM,GAAG,MAAM,EACzB,UAAS;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAO,KAC5C,MAAgE,CAAA"}

package/dist/number.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatSpacePledged = exports.formatTokenAmount = exports.parseTokenAmount = void 0;
+exports.shannonsToAi3 = exports.ai3ToShannons = exports.formatUnits = exports.parseUnits = exports.formatSpacePledged = exports.formatTokenAmount = exports.parseTokenAmount = void 0;
 const number_1 = require("./constants/number");
 const token_1 = require("./constants/token");
 /**
@@ -8,29 +8,33 @@ const token_1 = require("./constants/token");
  *
  * This function converts token amounts stored in their smallest unit (with decimal places)
  * back to their standard decimal representation. It handles both string and BigInt inputs
- * and is essential for displaying token balances in user interfaces.
+ * and is useful for displaying token balances in user interfaces.
+ *
+ * This function uses floating-point arithmetic and may lose precision
+ * for large values or high-precision decimals. For precise calculations, consider using
+ * `formatUnits` or `shannonsToAi3` instead.
  *
  * @param amount - The token amount in smallest units (string or BigInt).
  * @param decimals - Number of decimal places the token uses. Defaults to 18 for AI3 tokens.
- * @returns The parsed amount as a number with decimal places applied.
+ * @returns The parsed amount as a number (for string input) or bigint (for BigInt input).
  *
  * @example
  * import { parseTokenAmount } from '@autonomys/auto-utils'
  *
- * // Parse AI3 token amount (18 decimals)
+ * // Parse AI3 token amount (18 decimals) - string input returns number
  * const balance = '1000000000000000000' // 1 AI3 in smallest units
  * const readable = parseTokenAmount(balance)
- * console.log(readable) // Output: 1
+ * console.log(readable) // Output: 1 (number)
  *
- * // Parse with custom decimals
+ * // Parse with BigInt input - returns bigint
  * const customBalance = BigInt('1000000') // 1 token with 6 decimals
  * const customReadable = parseTokenAmount(customBalance, 6)
- * console.log(customReadable) // Output: 1
+ * console.log(customReadable) // Output: 1n (bigint)
  *
  * // Parse fractional amounts
  * const fractional = '500000000000000000' // 0.5 AI3
  * const fractionalReadable = parseTokenAmount(fractional)
- * console.log(fractionalReadable) // Output: 0.5
+ * console.log(fractionalReadable) // Output: 0.5 (number)
  */
 const parseTokenAmount = (amount, decimals = token_1.DEFAULT_TOKEN_DECIMALS) => {
     if (typeof amount === 'bigint')
@@ -41,31 +45,32 @@ exports.parseTokenAmount = parseTokenAmount;
 /**
  * Formats a human-readable token amount to its smallest unit representation.
  *
- * This function converts user-friendly decimal token amounts into the format required
- * for blockchain transactions. It multiplies the amount by the appropriate power of 10
- * based on the token's decimal places.
+ *
+ * This function uses floating-point arithmetic for number inputs
+ * and may lose precision for large values or high-precision decimals. For precise calculations,
+ * consider using `parseUnits` or `ai3ToShannons` instead.
  *
  * @param amount - The token amount in human-readable format (number or BigInt).
  * @param decimals - Number of decimal places the token uses. Defaults to 18 for AI3 tokens.
- * @returns The formatted amount in smallest units (BigInt for BigInt input, number for number input).
+ * @returns The formatted amount in smallest units (number for number input, BigInt for BigInt input).
  *
  * @example
  * import { formatTokenAmount } from '@autonomys/auto-utils'
  *
- * // Format AI3 token amount (18 decimals)
+ * // Format AI3 token amount (18 decimals) - number input returns number
  * const userAmount = 1.5 // 1.5 AI3
  * const formatted = formatTokenAmount(userAmount)
- * console.log(formatted) // Output: 1500000000000000000
+ * console.log(formatted) // Output: 1500000000000000000 (number)
  *
- * // Format with BigInt input
+ * // Format with BigInt input - returns BigInt
  * const bigAmount = BigInt(10)
  * const bigFormatted = formatTokenAmount(bigAmount)
- * console.log(bigFormatted) // Output: 10000000000000000000n
+ * console.log(bigFormatted) // Output: 10000000000000000000n (BigInt)
  *
  * // Format with custom decimals
  * const customAmount = 100
  * const customFormatted = formatTokenAmount(customAmount, 6)
- * console.log(customFormatted) // Output: 100000000
+ * console.log(customFormatted) // Output: 100000000 (number)
  */
 const formatTokenAmount = (amount, decimals = token_1.DEFAULT_TOKEN_DECIMALS) => {
     if (typeof amount === 'bigint')
@@ -116,3 +121,145 @@ const formatSpacePledged = (value, decimals = 2) => {
     return (Number(value) / Math.pow(k, i)).toFixed(dm) + ' ' + sizes[i];
 };
 exports.formatSpacePledged = formatSpacePledged;
+/**
+ * Parse a human-readable decimal string into smallest units as a bigint.
+ *
+ * - Accepts optional leading sign and a single decimal point
+ * - Disallows scientific notation
+ * - If fractional digits exceed `decimals`, defaults to throwing; caller can opt into truncation or rounding
+ * - If `options.rounding` is `'round'`, rounds half up based on the first discarded digit (i.e., if the first omitted digit is 5 or greater, rounds up)
+ * - If `options.rounding` is `'ceil'`, always rounds up if there are any excess fractional digits (ceiling function)
+ * - This is not banker's rounding (half to even) or round away from zero
+ */
+const parseUnits = (value, decimals = token_1.DEFAULT_TOKEN_DECIMALS, options = {}) => {
+    const { rounding = 'error' } = options;
+    if (typeof value !== 'string')
+        throw new Error('parseUnits: value must be a string');
+    if (!Number.isInteger(decimals) || decimals < 0) {
+        throw new Error('parseUnits: decimals must be a non-negative integer');
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        throw new Error('parseUnits: empty string');
+    const signIsNegative = trimmed.startsWith('-');
+    const unsigned = trimmed.replace(/^[+-]/, '');
+    if (!/^\d+(?:\.\d+)?$/.test(unsigned))
+        throw new Error(`parseUnits: invalid numeric string "${value}"`);
+    const [wholePartRaw, fractionalRaw = ''] = unsigned.split('.');
+    const wholePart = wholePartRaw || '0';
+    const fractional = fractionalRaw.slice(0, decimals);
+    const extra = fractionalRaw.slice(decimals);
+    const base = BigInt(10) ** BigInt(decimals);
+    const whole = BigInt(wholePart) * base;
+    let frac = BigInt((fractional || '0').padEnd(decimals, '0'));
+    if (extra.length > 0) {
+        switch (rounding) {
+            case 'error':
+                throw new Error(`parseUnits: too many decimal places for ${decimals} decimals`);
+            case 'round': {
+                const roundUp = extra[0] >= '5';
+                if (roundUp) {
+                    frac = frac + BigInt(1);
+                    // handle carry into whole if frac rolls over
+                    if (frac === base) {
+                        frac = BigInt(0);
+                        return (signIsNegative ? BigInt(-1) : BigInt(1)) * (whole + base);
+                    }
+                }
+                break;
+            }
+            case 'ceil':
+                // Always round up if there are any excess digits (ceiling function)
+                frac = frac + BigInt(1);
+                // handle carry into whole if frac rolls over
+                if (frac === base) {
+                    frac = BigInt(0);
+                    return (signIsNegative ? BigInt(-1) : BigInt(1)) * (whole + base);
+                }
+                break;
+            case 'truncate':
+            default:
+                // truncate (no-op; we already sliced)
+                break;
+        }
+    }
+    const result = whole + frac;
+    return signIsNegative ? -result : result;
+};
+exports.parseUnits = parseUnits;
+/**
+ * Format smallest units bigint into a human-readable decimal string.
+ *
+ * - No floating point used
+ * - Trims trailing zeros by default and removes decimal point if fractional becomes zero
+ */
+const formatUnits = (value, decimals = token_1.DEFAULT_TOKEN_DECIMALS, options = {}) => {
+    const { trimTrailingZeros = true } = options;
+    if (!Number.isInteger(decimals) || decimals < 0) {
+        throw new Error('formatUnits: decimals must be a non-negative integer');
+    }
+    const v = typeof value === 'bigint' ? value : BigInt(value);
+    const negative = v < BigInt(0);
+    const abs = negative ? -v : v;
+    const base = BigInt(10) ** BigInt(decimals);
+    const whole = abs / base;
+    const fractional = abs % base;
+    if (fractional === BigInt(0))
+        return `${negative ? '-' : ''}${whole.toString()}`;
+    let fracStr = fractional.toString().padStart(decimals, '0');
+    if (trimTrailingZeros)
+        fracStr = fracStr.replace(/0+$/, '');
+    const sign = negative ? '-' : '';
+    return fracStr.length ? `${sign}${whole.toString()}.${fracStr}` : `${sign}${whole.toString()}`;
+};
+exports.formatUnits = formatUnits;
+/**
+ * Convert AI3 token amount to Shannon units (smallest units).
+ *
+ * Converts a human-readable AI3 amount (like "1.5") to its exact representation
+ * in Shannon units as a BigInt. This ensures perfect precision for financial calculations.
+ *
+ * @param ai3Amount - AI3 amount as a decimal string (e.g., "1.5", "0.000000000000000001")
+ * @param options - Rounding behavior for excess decimal places
+ * @returns Shannon amount as BigInt (e.g., 1500000000000000000n for "1.5" AI3)
+ *
+ * @example
+ * import { ai3ToShannons } from '@autonomys/auto-utils'
+ *
+ * // Convert 1.5 AI3 to Shannon
+ * const shannons = ai3ToShannons("1.5")
+ * console.log(shannons) // 1500000000000000000n
+ *
+ * // Convert tiny amount
+ * const tinyShannons = ai3ToShannons("0.000000000000000001")
+ * console.log(tinyShannons) // 1n
+ *
+ * // Always round up with excess decimals
+ * const ceilShannons = ai3ToShannons("1.0000000000000000001", { rounding: 'ceil' })
+ * console.log(shannonsToAi3(ceilShannons)) // "1.000000000000000001"
+ */
+const ai3ToShannons = (ai3Amount, options = {}) => (0, exports.parseUnits)(ai3Amount, token_1.DEFAULT_TOKEN_DECIMALS, options);
+exports.ai3ToShannons = ai3ToShannons;
+/**
+ * Convert Shannon units to AI3 token amount.
+ *
+ * Converts Shannon units (smallest units) back to a human-readable AI3 amount.
+ * Uses exact BigInt arithmetic to avoid any precision loss.
+ *
+ * @param shannons - Shannon amount as BigInt or string
+ * @param options - Formatting options (trailing zero trimming)
+ * @returns AI3 amount as decimal string (e.g., "1.5" for 1500000000000000000n Shannon)
+ *
+ * @example
+ * import { shannonsToAi3 } from '@autonomys/auto-utils'
+ *
+ * // Convert Shannon back to AI3
+ * const ai3Amount = shannonsToAi3(1500000000000000000n)
+ * console.log(ai3Amount) // "1.5"
+ *
+ * // Convert single Shannon
+ * const tinyAi3 = shannonsToAi3(1n)
+ * console.log(tinyAi3) // "0.000000000000000001"
+ */
+const shannonsToAi3 = (shannons, options = {}) => (0, exports.formatUnits)(shannons, token_1.DEFAULT_TOKEN_DECIMALS, options);
+exports.shannonsToAi3 = shannonsToAi3;

package/dist/utils/sign.js

@@ -1,13 +1,4 @@
 "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.signatureVerify = exports.signingKey = exports.signMessage = void 0;
 const util_crypto_1 = require("@polkadot/util-crypto");
@@ -49,15 +40,15 @@ const format_1 = require("./format");
  *
  * @throws {Error} When the signer doesn't support raw signing or signing fails.
  */
-const signMessage = (signer, address, data) => __awaiter(void 0, void 0, void 0, function* () {
+const signMessage = async (signer, address, data) => {
     if (!signer.signRaw)
         throw new Error('signRaw not available on the signer');
-    return yield signer.signRaw({
+    return await signer.signRaw({
         address,
         type: 'bytes',
         data,
     });
-});
+};
 exports.signMessage = signMessage;
 /**
  * Converts a public key to a hexadecimal string representation.

package/dist/utils/signAndSendTx.js

@@ -1,14 +1,5 @@
 "use strict";
 // file: src/utils/signAndSendTx.ts
-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.signAndSendTx = void 0;
 const detectTxSuccess_1 = require("./detectTxSuccess");
@@ -85,14 +76,14 @@ const validateEvents_1 = require("./validateEvents");
  * @throws {Error} When the transaction is retracted, dropped, or invalid.
  * @throws {Error} When custom error mapping indicates a specific error condition.
  */
-const signAndSendTx = (sender_1, tx_1, ...args_1) => __awaiter(void 0, [sender_1, tx_1, ...args_1], void 0, function* (sender, tx, options = {}, eventsExpected = events_1.expectSuccessfulTxEvent, log = false, mapErrorCodeToEnum) {
+const signAndSendTx = async (sender, tx, options = {}, eventsExpected = events_1.expectSuccessfulTxEvent, log = false, mapErrorCodeToEnum) => {
     let success = false;
     let txHashHex = undefined;
     let blockHash = undefined;
     const eventsValidated = { expected: [], found: [] };
     let identifier = null;
-    const receipt = yield new Promise((resolve, reject) => {
-        tx.signAndSend(sender, options, (result) => __awaiter(void 0, void 0, void 0, function* () {
+    const receipt = await new Promise((resolve, reject) => {
+        tx.signAndSend(sender, options, async (result) => {
             const { events = [], status, dispatchError } = result;
             if (status.isInBlock || status.isFinalized) {
                 txHashHex = result.txHash.toHex();
@@ -112,7 +103,7 @@ const signAndSendTx = (sender_1, tx_1, ...args_1) => __awaiter(void 0, [sender_1
                         events.forEach(({ event: { section, method, data } }) => {
                             if (section === 'system' && method === 'ExtrinsicFailed') {
                                 const dispatchErrorJson = JSON.parse(dispatchError.toString());
-                                const errorEnum = mapErrorCodeToEnum === null || mapErrorCodeToEnum === void 0 ? void 0 : mapErrorCodeToEnum(dispatchErrorJson.module.error);
+                                const errorEnum = mapErrorCodeToEnum?.(dispatchErrorJson.module.error);
                                 reject(new Error(`Extrinsic failed: ${errorEnum} in block #${blockHash} with error: ${dispatchErrorJson}`));
                             }
                             if (section === 'autoId' && method === 'NewAutoIdRegistered') {
@@ -134,8 +125,8 @@ const signAndSendTx = (sender_1, tx_1, ...args_1) => __awaiter(void 0, [sender_1
                     console.error('Transaction failed');
                 reject(new Error('Transaction failed'));
             }
-        }));
+        });
     });
     return { success, txHash: txHashHex, blockHash, events: eventsValidated, receipt, identifier };
-});
+};
 exports.signAndSendTx = signAndSendTx;

package/dist/wallet.js

@@ -33,15 +33,6 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-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.getMockWallet = exports.mockWallets = exports.activateWallet = exports.generateWallet = exports.setupWallet = void 0;
 const api_1 = require("@polkadot/api");
@@ -203,13 +194,13 @@ exports.generateWallet = generateWallet;
  *
  * @throws {Error} When no wallet credentials are provided or connection fails.
  */
-const activateWallet = (params) => __awaiter(void 0, void 0, void 0, function* () {
+const activateWallet = async (params) => {
     if (!params.api) {
         // Create the API instance if not provided
         params.api =
             params.domainId === undefined
-                ? yield (0, api_2.activate)(params)
-                : yield (0, api_2.activateDomain)(params);
+                ? await (0, api_2.activate)(params)
+                : await (0, api_2.activateDomain)(params);
     }
     const accounts = [];
     if (params.mnemonic || params.uri) {
@@ -219,11 +210,11 @@ const activateWallet = (params) => __awaiter(void 0, void 0, void 0, function* (
             accounts.push(keyringPair);
     }
     else if (typeof window !== 'undefined') {
-        const { web3Enable, web3Accounts } = yield Promise.resolve().then(() => __importStar(require('@polkadot/extension-dapp')));
+        const { web3Enable, web3Accounts } = await Promise.resolve().then(() => __importStar(require('@polkadot/extension-dapp')));
         // Enable Polkadot.js extension in the browser
-        yield web3Enable(params.appName || 'Auto');
+        await web3Enable(params.appName || 'Auto');
         // Get the list of accounts from the extension
-        const allAccounts = yield web3Accounts();
+        const allAccounts = await web3Accounts();
         accounts.push(...allAccounts);
         if (allAccounts.length === 0)
             console.warn('No accounts found in the Polkadot.js extension');
@@ -237,7 +228,7 @@ const activateWallet = (params) => __awaiter(void 0, void 0, void 0, function* (
             ? accounts[0].address
             : (0, address_1.address)(accounts[0].address),
     };
-});
+};
 exports.activateWallet = activateWallet;
 /**
  * Creates a collection of mock wallets for testing and development purposes.
@@ -285,18 +276,21 @@ exports.activateWallet = activateWallet;
  *   await wallet.api.disconnect()
  * }
  */
-const mockWallets = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (network = { networkId: network_1.defaultNetwork.id }, api, type) {
+const mockWallets = async (network = { networkId: network_1.defaultNetwork.id }, api, type) => {
     if (!type)
         type = 'sr25519';
     const wallets = [];
     for (const uri of wallet_1.mockURIs) {
-        const wallet = yield (0, exports.activateWallet)(Object.assign(Object.assign({}, network), { uri,
+        const wallet = await (0, exports.activateWallet)({
+            ...network,
+            uri,
             api,
-            type }));
+            type,
+        });
         wallets.push(wallet);
     }
     return wallets;
-});
+};
 exports.mockWallets = mockWallets;
 /**
  * Retrieves a specific mock wallet by name from a collection of mock wallets.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autonomys/auto-utils",
-  "version": "1.5.16",
+  "version": "1.5.17",
   "license": "MIT",
   "main": "dist/index.js",
   "repository": {
@@ -39,5 +39,5 @@
     "ts-jest": "^29.3.1",
     "typescript": "^5.8.3"
   },
-  "gitHead": "7242b27a7d9e095399c3d87209767f012355340b"
+  "gitHead": "890e12b9cc437f3f4409b74663a77b854bf048aa"
 }