@autonomys/auto-utils 1.5.2 → 1.5.4

package/dist/string.js

@@ -2,13 +2,123 @@
 // file: src/string.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fixLengthEntryId = exports.capitalizeFirstLetter = exports.shortString = exports.stringify = void 0;
+/**
+ * Converts any value to a JSON string with BigInt support.
+ *
+ * This function extends JSON.stringify to handle BigInt values by converting them to strings.
+ * It's particularly useful when working with blockchain data that often includes large numbers
+ * represented as BigInt values.
+ *
+ * @param value - Any value to be stringified, including objects with BigInt properties.
+ * @returns A JSON string representation of the value with BigInt values converted to strings.
+ *
+ * @example
+ * import { stringify } from '@autonomys/auto-utils'
+ *
+ * // Stringify object with BigInt values
+ * const data = {
+ *   balance: BigInt('1000000000000000000'),
+ *   timestamp: Date.now(),
+ *   address: '5GmS1wtCfR4tK5SSgnZbVT4kYw5W8NmxmijcsxCQE6oLW6A8'
+ * }
+ *
+ * const jsonString = stringify(data)
+ * console.log(jsonString)
+ * // Output: {"balance":"1000000000000000000","timestamp":1672531200000,"address":"5G..."}
+ *
+ * // Compare with regular JSON.stringify which would throw an error
+ * // JSON.stringify(data) // TypeError: Do not know how to serialize a BigInt
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const stringify = (value) => JSON.stringify(value, (_, value) => (typeof value === 'bigint' ? value.toString() : value));
 exports.stringify = stringify;
+/**
+ * Truncates a string by keeping the beginning and end characters with ellipsis in the middle.
+ *
+ * This function is commonly used to display long addresses, transaction hashes, or other
+ * identifiers in a compact format while preserving recognizable parts of the original string.
+ *
+ * @param value - The string to truncate.
+ * @param initialLength - Number of characters to keep from the beginning. Defaults to 6.
+ * @param endLength - Number of characters to keep from the end (negative number). Defaults to -4.
+ * @returns The truncated string with ellipsis in the middle.
+ *
+ * @example
+ * import { shortString } from '@autonomys/auto-utils'
+ *
+ * // Truncate a long address
+ * const address = '5GmS1wtCfR4tK5SSgnZbVT4kYw5W8NmxmijcsxCQE6oLW6A8'
+ * const short = shortString(address)
+ * console.log(short) // Output: "5GmS1w...W6A8"
+ *
+ * // Custom truncation lengths
+ * const customShort = shortString(address, 8, -6)
+ * console.log(customShort) // Output: "5GmS1wtC...oLW6A8"
+ *
+ * // Truncate transaction hash
+ * const txHash = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+ * const shortHash = shortString(txHash, 10, -8)
+ * console.log(shortHash) // Output: "0x12345678...90abcdef"
+ */
 const shortString = (value, initialLength = 6, endLength = -4) => `${value.slice(0, initialLength)}...${value.slice(endLength)}`;
 exports.shortString = shortString;
+/**
+ * Capitalizes the first letter of a string.
+ *
+ * This utility function converts the first character of a string to uppercase while
+ * leaving the rest of the string unchanged. It handles empty strings gracefully.
+ *
+ * @param string - The string to capitalize.
+ * @returns The string with the first letter capitalized, or empty string if input is empty.
+ *
+ * @example
+ * import { capitalizeFirstLetter } from '@autonomys/auto-utils'
+ *
+ * // Capitalize network names
+ * console.log(capitalizeFirstLetter('mainnet')) // Output: "Mainnet"
+ * console.log(capitalizeFirstLetter('gemini-3h')) // Output: "Gemini-3h"
+ *
+ * // Handle edge cases
+ * console.log(capitalizeFirstLetter('')) // Output: ""
+ * console.log(capitalizeFirstLetter('a')) // Output: "A"
+ * console.log(capitalizeFirstLetter('UPPERCASE')) // Output: "UPPERCASE"
+ */
 const capitalizeFirstLetter = (string) => string ? string.charAt(0).toUpperCase() + string.slice(1) : '';
 exports.capitalizeFirstLetter = capitalizeFirstLetter;
+/**
+ * Creates a fixed-length entry identifier for blockchain events or transactions.
+ *
+ * This function generates a standardized identifier format used for indexing blockchain
+ * entries, combining block height with optional transaction index. Both values are
+ * zero-padded to ensure consistent string length for sorting and indexing.
+ *
+ * @param blockHeight - The block height as a BigInt.
+ * @param indexInBlock - Optional transaction index within the block as a BigInt.
+ * @returns A zero-padded string identifier, either "blockHeight" or "blockHeight-indexInBlock".
+ *
+ * @example
+ * import { fixLengthEntryId } from '@autonomys/auto-utils'
+ *
+ * // Create block identifier
+ * const blockId = fixLengthEntryId(BigInt(12345))
+ * console.log(blockId) // Output: "00000000000000000000000000012345"
+ *
+ * // Create transaction identifier
+ * const txId = fixLengthEntryId(BigInt(12345), BigInt(7))
+ * console.log(txId) // Output: "00000000000000000000000000012345-00000000000000000000000000000007"
+ *
+ * // Use with large numbers
+ * const largeBlockId = fixLengthEntryId(BigInt('1000000000000000000'))
+ * console.log(largeBlockId) // Output: "00000000000001000000000000000000"
+ *
+ * // Useful for creating sortable identifiers
+ * const ids = [
+ *   fixLengthEntryId(BigInt(100)),
+ *   fixLengthEntryId(BigInt(50)),
+ *   fixLengthEntryId(BigInt(200))
+ * ]
+ * ids.sort() // Will sort correctly due to zero-padding
+ */
 const fixLengthEntryId = (blockHeight, indexInBlock) => {
     const totalLength = 32;
     const str1 = blockHeight.toString().padStart(totalLength, '0');

package/dist/utils/detectTxSuccess.d.ts

@@ -1,3 +1,34 @@
 import type { EventRecord } from '../types/event';
+/**
+ * Detects if a transaction was successful by checking for success events.
+ *
+ * This function examines the events emitted by a transaction to determine
+ * if it was successful. It looks for events that are known to indicate
+ * successful transaction execution, such as 'system.ExtrinsicSuccess'.
+ *
+ * @param events - Array of EventRecord objects emitted by the transaction.
+ * @returns True if the transaction was successful, false otherwise.
+ *
+ * @example
+ * import { detectTxSuccess } from '@autonomys/auto-utils'
+ *
+ * // Check transaction success from events
+ * const events = [] // events from transaction result
+ * const isSuccessful = detectTxSuccess(events)
+ *
+ * if (isSuccessful) {
+ *   console.log('Transaction completed successfully')
+ * } else {
+ *   console.log('Transaction failed or had no success events')
+ * }
+ *
+ * // Use with signAndSend result
+ * tx.signAndSend(sender, (result) => {
+ *   if (result.status.isInBlock) {
+ *     const success = detectTxSuccess(result.events)
+ *     console.log('Transaction success:', success)
+ *   }
+ * })
+ */
 export declare const detectTxSuccess: (events: EventRecord[]) => boolean;
 //# sourceMappingURL=detectTxSuccess.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"detectTxSuccess.d.ts","sourceRoot":"","sources":["../../src/utils/detectTxSuccess.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAGjD,eAAO,MAAM,eAAe,GAAI,QAAQ,WAAW,EAAE,KAAG,OAMvD,CAAA"}
+{"version":3,"file":"detectTxSuccess.d.ts","sourceRoot":"","sources":["../../src/utils/detectTxSuccess.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAGjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,WAAW,EAAE,KAAG,OAMvD,CAAA"}

package/dist/utils/detectTxSuccess.js

@@ -3,6 +3,37 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectTxSuccess = void 0;
 const events_1 = require("./events");
+/**
+ * Detects if a transaction was successful by checking for success events.
+ *
+ * This function examines the events emitted by a transaction to determine
+ * if it was successful. It looks for events that are known to indicate
+ * successful transaction execution, such as 'system.ExtrinsicSuccess'.
+ *
+ * @param events - Array of EventRecord objects emitted by the transaction.
+ * @returns True if the transaction was successful, false otherwise.
+ *
+ * @example
+ * import { detectTxSuccess } from '@autonomys/auto-utils'
+ *
+ * // Check transaction success from events
+ * const events = [] // events from transaction result
+ * const isSuccessful = detectTxSuccess(events)
+ *
+ * if (isSuccessful) {
+ *   console.log('Transaction completed successfully')
+ * } else {
+ *   console.log('Transaction failed or had no success events')
+ * }
+ *
+ * // Use with signAndSend result
+ * tx.signAndSend(sender, (result) => {
+ *   if (result.status.isInBlock) {
+ *     const success = detectTxSuccess(result.events)
+ *     console.log('Transaction success:', success)
+ *   }
+ * })
+ */
 const detectTxSuccess = (events) => {
     events.forEach(({ event: { method, section } }) => {
         if (events_1.expectSuccessfulTxEvent.indexOf(`${section}.${method}`) > -1)

package/dist/utils/events.d.ts

@@ -1,11 +1,86 @@
+/**
+ * Enumeration of blockchain event types for categorizing events.
+ *
+ * This enum provides a structured way to reference different categories of
+ * blockchain events, making event handling more organized and type-safe.
+ */
 export declare const enum Type {
     system = "system"
 }
+/**
+ * Creates a standardized event name by combining type and event name.
+ *
+ * This utility function creates consistent event names following the pattern
+ * "type.eventName", which matches the format used by Polkadot.js for blockchain events.
+ *
+ * @param type - The event type category from the Type enum.
+ * @param event - The specific event name within that category.
+ * @returns A formatted event name string in the format "type.event".
+ *
+ * @example
+ * import { eventName, Type } from '@autonomys/auto-utils'
+ *
+ * // Create system event names
+ * const successEvent = eventName(Type.system, 'ExtrinsicSuccess')
+ * console.log(successEvent) // Output: "system.ExtrinsicSuccess"
+ *
+ * const failureEvent = eventName(Type.system, 'ExtrinsicFailed')
+ * console.log(failureEvent) // Output: "system.ExtrinsicFailed"
+ *
+ * // Use in event validation
+ * const expectedEvents = [
+ *   eventName(Type.system, 'ExtrinsicSuccess'),
+ *   'balances.Transfer' // Can also use direct strings
+ * ]
+ */
 export declare const eventName: (type: Type, event: string) => string;
+/**
+ * Organized collection of event groups by category.
+ *
+ * This object provides structured access to different categories of blockchain
+ * events, making it easier to reference and validate specific event types
+ * in transaction monitoring and testing scenarios.
+ *
+ * @example
+ * import { eventsGroup } from '@autonomys/auto-utils'
+ *
+ * // Access system events
+ * console.log(eventsGroup.system.success) // Output: "system.ExtrinsicSuccess"
+ * console.log(eventsGroup.system.failure) // Output: "system.ExtrinsicFailed"
+ *
+ * // Use in transaction validation
+ * const expectedSystemEvents = [
+ *   eventsGroup.system.success,
+ *   eventsGroup.system.newAccount
+ * ]
+ */
 export declare const eventsGroup: {
     system: {
         [key: string]: string;
     };
 };
+/**
+ * Default array of events expected for successful transactions.
+ *
+ * This array contains the standard events that indicate a transaction was
+ * successfully executed. It's used as the default expected events list
+ * in transaction signing and validation functions.
+ *
+ * @example
+ * import { expectSuccessfulTxEvent, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * // Use as default expected events (this is automatic)
+ * const result = await signAndSendTx(sender, tx)
+ *
+ * // Or explicitly specify (same as default)
+ * const result2 = await signAndSendTx(sender, tx, {}, expectSuccessfulTxEvent)
+ *
+ * // Combine with custom events
+ * const customExpectedEvents = [
+ *   ...expectSuccessfulTxEvent,
+ *   'balances.Transfer',
+ *   'domains.OperatorNominated'
+ * ]
+ */
 export declare const expectSuccessfulTxEvent: string[];
 //# sourceMappingURL=events.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAGA,0BAAkB,IAAI;IACpB,MAAM,WAAW;CAClB;AAGD,eAAO,MAAM,SAAS,GAAI,MAAM,IAAI,EAAE,OAAO,MAAM,WAAuB,CAAA;AAY1E,eAAO,MAAM,WAAW;;;;CAEvB,CAAA;AAGD,eAAO,MAAM,uBAAuB,UAAmB,CAAA"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,0BAAkB,IAAI;IACpB,MAAM,WAAW;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,eAAO,MAAM,SAAS,GAAI,MAAM,IAAI,EAAE,OAAO,MAAM,WAAuB,CAAA;AAkB1E;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,WAAW;;;;CAEvB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,eAAO,MAAM,uBAAuB,UAAmB,CAAA"}

package/dist/utils/events.js

@@ -2,18 +2,94 @@
 // file: src/utils/events.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.expectSuccessfulTxEvent = exports.eventsGroup = exports.eventName = void 0;
+/**
+ * Creates a standardized event name by combining type and event name.
+ *
+ * This utility function creates consistent event names following the pattern
+ * "type.eventName", which matches the format used by Polkadot.js for blockchain events.
+ *
+ * @param type - The event type category from the Type enum.
+ * @param event - The specific event name within that category.
+ * @returns A formatted event name string in the format "type.event".
+ *
+ * @example
+ * import { eventName, Type } from '@autonomys/auto-utils'
+ *
+ * // Create system event names
+ * const successEvent = eventName(Type.system, 'ExtrinsicSuccess')
+ * console.log(successEvent) // Output: "system.ExtrinsicSuccess"
+ *
+ * const failureEvent = eventName(Type.system, 'ExtrinsicFailed')
+ * console.log(failureEvent) // Output: "system.ExtrinsicFailed"
+ *
+ * // Use in event validation
+ * const expectedEvents = [
+ *   eventName(Type.system, 'ExtrinsicSuccess'),
+ *   'balances.Transfer' // Can also use direct strings
+ * ]
+ */
 // Utility Function for Event Names
 const eventName = (type, event) => `${type}.${event}`;
 exports.eventName = eventName;
+/**
+ * Collection of system-level blockchain events.
+ *
+ * This object contains standardized names for system events that are common
+ * across all Polkadot-based blockchains, providing easy access to frequently
+ * used event names for transaction monitoring and validation.
+ */
 // System Events
 const system = {
     failure: (0, exports.eventName)("system" /* Type.system */, 'ExtrinsicFailed'),
     newAccount: (0, exports.eventName)("system" /* Type.system */, 'NewAccount'),
     success: (0, exports.eventName)("system" /* Type.system */, 'ExtrinsicSuccess'),
 };
+/**
+ * Organized collection of event groups by category.
+ *
+ * This object provides structured access to different categories of blockchain
+ * events, making it easier to reference and validate specific event types
+ * in transaction monitoring and testing scenarios.
+ *
+ * @example
+ * import { eventsGroup } from '@autonomys/auto-utils'
+ *
+ * // Access system events
+ * console.log(eventsGroup.system.success) // Output: "system.ExtrinsicSuccess"
+ * console.log(eventsGroup.system.failure) // Output: "system.ExtrinsicFailed"
+ *
+ * // Use in transaction validation
+ * const expectedSystemEvents = [
+ *   eventsGroup.system.success,
+ *   eventsGroup.system.newAccount
+ * ]
+ */
 // Group of Events
 exports.eventsGroup = {
     system,
 };
+/**
+ * Default array of events expected for successful transactions.
+ *
+ * This array contains the standard events that indicate a transaction was
+ * successfully executed. It's used as the default expected events list
+ * in transaction signing and validation functions.
+ *
+ * @example
+ * import { expectSuccessfulTxEvent, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * // Use as default expected events (this is automatic)
+ * const result = await signAndSendTx(sender, tx)
+ *
+ * // Or explicitly specify (same as default)
+ * const result2 = await signAndSendTx(sender, tx, {}, expectSuccessfulTxEvent)
+ *
+ * // Combine with custom events
+ * const customExpectedEvents = [
+ *   ...expectSuccessfulTxEvent,
+ *   'balances.Transfer',
+ *   'domains.OperatorNominated'
+ * ]
+ */
 // Export a default success event
 exports.expectSuccessfulTxEvent = [system.success];

package/dist/utils/format.d.ts

@@ -1,3 +1,11 @@
 import { stringToU8a, u8aToHex } from '@polkadot/util';
+/**
+ * Essential data format conversion utilities re-exported from Polkadot.js for convenience.
+ *
+ * These functions provide conversion capabilities between different data formats
+ * commonly used in Autonomys Network applications.
+ *
+ * @see {@link https://polkadot.js.org/docs/ | Polkadot.js Documentation} for complete API details.
+ */
 export { stringToU8a, u8aToHex };
 //# sourceMappingURL=format.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEtD,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAA"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEtD;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAA"}

package/dist/utils/ready.d.ts

@@ -1,3 +1,11 @@
 import { cryptoWaitReady } from '@polkadot/util-crypto';
+/**
+ * Cryptographic initialization utility re-exported from Polkadot.js for convenience.
+ *
+ * Ensures that all cryptographic operations are ready before use. Essential to call
+ * before performing any cryptographic operations in WebAssembly environments.
+ *
+ * @see {@link https://polkadot.js.org/docs/ | Polkadot.js Documentation} for complete API details.
+ */
 export { cryptoWaitReady };
 //# sourceMappingURL=ready.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../../src/utils/ready.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,OAAO,EAAE,eAAe,EAAE,CAAA"}
+{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../../src/utils/ready.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD;;;;;;;GAOG;AACH,OAAO,EAAE,eAAe,EAAE,CAAA"}

package/dist/utils/sign.d.ts

@@ -1,6 +1,72 @@
 import { signatureVerify } from '@polkadot/util-crypto';
 import type { Signer } from '../types/wallet';
+/**
+ * Signs arbitrary data using a Polkadot.js extension signer.
+ *
+ * This function uses the raw signing capability of a Polkadot.js extension to sign
+ * arbitrary byte data. It's commonly used for authentication, message signing,
+ * or creating signatures for off-chain verification.
+ *
+ * @param signer - The Polkadot.js extension signer interface.
+ * @param address - The address of the account to sign with.
+ * @param data - The data to sign as a string (will be encoded as bytes).
+ * @returns Promise resolving to the signature result containing the signature and other metadata.
+ *
+ * @example
+ * import { signMessage } from '@autonomys/auto-utils'
+ * import { web3FromAddress } from '@polkadot/extension-dapp'
+ *
+ * // Sign a message with extension wallet
+ * const address = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'
+ * const injector = await web3FromAddress(address)
+ *
+ * const message = 'Hello, Autonomys Network!'
+ * const signature = await signMessage(injector.signer, address, message)
+ *
+ * console.log('Signature:', signature.signature)
+ * console.log('Signed by:', signature.id)
+ *
+ * // Sign authentication challenge
+ * const challenge = `Login to dApp at ${Date.now()}`
+ * const authSignature = await signMessage(injector.signer, address, challenge)
+ *
+ * // Use signature for verification later
+ * const isValid = signatureVerify(challenge, authSignature.signature, address)
+ * console.log('Signature valid:', isValid.isValid)
+ *
+ * @throws {Error} When the signer doesn't support raw signing or signing fails.
+ */
 export declare const signMessage: (signer: Signer, address: string, data: string) => Promise<import("@polkadot/types/types/extrinsic").SignerResult>;
+/**
+ * Converts a public key to a hexadecimal string representation.
+ *
+ * This utility function converts a Uint8Array public key into its hexadecimal
+ * string representation, which is useful for display, logging, or storage purposes.
+ *
+ * @param publicKey - The public key as a Uint8Array.
+ * @returns The public key as a hexadecimal string with '0x' prefix.
+ *
+ * @example
+ * import { signingKey } from '@autonomys/auto-utils'
+ *
+ * // Convert KeyringPair public key to hex
+ * const wallet = setupWallet({ uri: '//Alice' })
+ * const publicKeyHex = signingKey(wallet.keyringPair.publicKey)
+ * console.log('Public key:', publicKeyHex) // Output: "0x..."
+ *
+ * // Use with signature verification
+ * const publicKeyBytes = new Uint8Array(32) // 32-byte public key
+ * const hexKey = signingKey(publicKeyBytes)
+ * console.log('Hex public key:', hexKey)
+ */
 export declare const signingKey: (publicKey: Uint8Array) => `0x${string}`;
+/**
+ * Signature verification utility re-exported from Polkadot.js for convenience.
+ *
+ * Verifies that a signature was created by a specific public key for the given data.
+ * Essential for validating signatures in authentication flows and off-chain verification.
+ *
+ * @see {@link https://polkadot.js.org/docs/ | Polkadot.js Documentation} for complete API details.
+ */
 export { signatureVerify };
 //# sourceMappingURL=sign.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../../src/utils/sign.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAG7C,eAAO,MAAM,WAAW,GAAU,QAAQ,MAAM,EAAE,SAAS,MAAM,EAAE,MAAM,MAAM,oEAQ9E,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,WAAW,UAAU,kBAAwB,CAAA;AAExE,OAAO,EAAE,eAAe,EAAE,CAAA"}
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../../src/utils/sign.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAG7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,WAAW,GAAU,QAAQ,MAAM,EAAE,SAAS,MAAM,EAAE,MAAM,MAAM,oEAQ9E,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,UAAU,GAAI,WAAW,UAAU,kBAAwB,CAAA;AAExE;;;;;;;GAOG;AACH,OAAO,EAAE,eAAe,EAAE,CAAA"}

package/dist/utils/sign.js

@@ -13,6 +13,42 @@ exports.signatureVerify = exports.signingKey = exports.signMessage = void 0;
 const util_crypto_1 = require("@polkadot/util-crypto");
 Object.defineProperty(exports, "signatureVerify", { enumerable: true, get: function () { return util_crypto_1.signatureVerify; } });
 const format_1 = require("./format");
+/**
+ * Signs arbitrary data using a Polkadot.js extension signer.
+ *
+ * This function uses the raw signing capability of a Polkadot.js extension to sign
+ * arbitrary byte data. It's commonly used for authentication, message signing,
+ * or creating signatures for off-chain verification.
+ *
+ * @param signer - The Polkadot.js extension signer interface.
+ * @param address - The address of the account to sign with.
+ * @param data - The data to sign as a string (will be encoded as bytes).
+ * @returns Promise resolving to the signature result containing the signature and other metadata.
+ *
+ * @example
+ * import { signMessage } from '@autonomys/auto-utils'
+ * import { web3FromAddress } from '@polkadot/extension-dapp'
+ *
+ * // Sign a message with extension wallet
+ * const address = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY'
+ * const injector = await web3FromAddress(address)
+ *
+ * const message = 'Hello, Autonomys Network!'
+ * const signature = await signMessage(injector.signer, address, message)
+ *
+ * console.log('Signature:', signature.signature)
+ * console.log('Signed by:', signature.id)
+ *
+ * // Sign authentication challenge
+ * const challenge = `Login to dApp at ${Date.now()}`
+ * const authSignature = await signMessage(injector.signer, address, challenge)
+ *
+ * // Use signature for verification later
+ * const isValid = signatureVerify(challenge, authSignature.signature, address)
+ * console.log('Signature valid:', isValid.isValid)
+ *
+ * @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* () {
     if (!signer.signRaw)
         throw new Error('signRaw not available on the signer');
@@ -23,5 +59,27 @@ const signMessage = (signer, address, data) => __awaiter(void 0, void 0, void 0,
     });
 });
 exports.signMessage = signMessage;
+/**
+ * Converts a public key to a hexadecimal string representation.
+ *
+ * This utility function converts a Uint8Array public key into its hexadecimal
+ * string representation, which is useful for display, logging, or storage purposes.
+ *
+ * @param publicKey - The public key as a Uint8Array.
+ * @returns The public key as a hexadecimal string with '0x' prefix.
+ *
+ * @example
+ * import { signingKey } from '@autonomys/auto-utils'
+ *
+ * // Convert KeyringPair public key to hex
+ * const wallet = setupWallet({ uri: '//Alice' })
+ * const publicKeyHex = signingKey(wallet.keyringPair.publicKey)
+ * console.log('Public key:', publicKeyHex) // Output: "0x..."
+ *
+ * // Use with signature verification
+ * const publicKeyBytes = new Uint8Array(32) // 32-byte public key
+ * const hexKey = signingKey(publicKeyBytes)
+ * console.log('Hex public key:', hexKey)
+ */
 const signingKey = (publicKey) => (0, format_1.u8aToHex)(publicKey);
 exports.signingKey = signingKey;

package/dist/utils/signAndSendTx.d.ts

@@ -1,6 +1,77 @@
 import type { SubmittableResult } from '@polkadot/api';
 import { KeyringPair } from '@polkadot/keyring/types';
 import type { AddressOrPair, Events, ISubmittableResult, SignerOptions, SubmittableExtrinsic, TransactionSignedAndSend } from '../types';
+/**
+ * Signs and sends a transaction to the Autonomys Network, with comprehensive error handling and event validation.
+ *
+ * This function handles the complete transaction lifecycle: signing, sending, monitoring for inclusion,
+ * and validating expected events. It provides detailed error handling and supports custom error mapping
+ * for domain-specific error handling. The function waits for the transaction to be included in a block
+ * and validates that expected events were emitted.
+ *
+ * @param sender - The account to sign and send the transaction. Can be a KeyringPair, address string, or AddressOrPair.
+ * @param tx - The submittable extrinsic to sign and send.
+ * @param options - Optional signer options including nonce, tip, and other transaction parameters.
+ * @param eventsExpected - Array of expected event names to validate. Defaults to successful transaction events.
+ * @param log - Whether to log transaction progress to console. Defaults to false.
+ * @param mapErrorCodeToEnum - Optional function to map error codes to custom error enums for better error handling.
+ * @returns Promise resolving to transaction results including success status, hashes, events, and receipt.
+ *
+ * @example
+ * import { signAndSendTx, activate, setupWallet } from '@autonomys/auto-utils'
+ *
+ * // Basic transaction signing and sending
+ * const api = await activate({ networkId: 'taurus' })
+ * const wallet = setupWallet({ uri: '//Alice' })
+ *
+ * const tx = api.tx.balances.transfer('5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY', 1000000000000000000n)
+ *
+ * const result = await signAndSendTx(wallet.keyringPair, tx)
+ * if (result.success) {
+ *   console.log('Transaction successful')
+ *   console.log('Transaction hash:', result.txHash)
+ *   console.log('Block hash:', result.blockHash)
+ * }
+ *
+ * // With custom options and event validation
+ * const transferTx = api.tx.balances.transfer(receiverAddress, amount)
+ * const transferResult = await signAndSendTx(
+ *   senderKeyringPair,
+ *   transferTx,
+ *   { tip: 1000000000000000n }, // Custom tip
+ *   ['balances.Transfer'], // Expected events
+ *   true // Enable logging
+ * )
+ *
+ * // With error mapping for custom error handling
+ * const stakingTx = api.tx.domains.nominateOperator(operatorId, amount)
+ * const stakingResult = await signAndSendTx(
+ *   nominatorKeyringPair,
+ *   stakingTx,
+ *   {},
+ *   ['domains.OperatorNominated'],
+ *   false,
+ *   (errorCode) => {
+ *     // Map error codes to custom error types
+ *     switch (errorCode) {
+ *       case '0': return 'InsufficientBalance'
+ *       case '1': return 'OperatorNotFound'
+ *       default: return undefined
+ *     }
+ *   }
+ * )
+ *
+ * // Handle Auto-ID registration with identifier extraction
+ * const autoIdTx = api.tx.autoId.registerAutoId(autoIdData)
+ * const autoIdResult = await signAndSendTx(sender, autoIdTx)
+ * if (autoIdResult.identifier) {
+ *   console.log('Auto-ID registered with identifier:', autoIdResult.identifier)
+ * }
+ *
+ * @throws {Error} When the transaction fails, times out, or expected events are not found.
+ * @throws {Error} When the transaction is retracted, dropped, or invalid.
+ * @throws {Error} When custom error mapping indicates a specific error condition.
+ */
 export declare const signAndSendTx: <TError>(sender: AddressOrPair | KeyringPair, tx: SubmittableExtrinsic<"promise", ISubmittableResult>, options?: Partial<SignerOptions>, eventsExpected?: Events, log?: boolean, mapErrorCodeToEnum?: (errorCode: string) => TError | undefined) => Promise<TransactionSignedAndSend & {
     receipt: SubmittableResult;
     identifier?: string | null;

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

@@ -1 +1 @@
-{"version":3,"file":"signAndSendTx.d.ts","sourceRoot":"","sources":["../../src/utils/signAndSendTx.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,KAAK,EACV,aAAa,EACb,MAAM,EAEN,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,UAAU,CAAA;AAKjB,eAAO,MAAM,aAAa,GAAU,MAAM,EACxC,QAAQ,aAAa,GAAG,WAAW,EACnC,IAAI,oBAAoB,CAAC,SAAS,EAAE,kBAAkB,CAAC,EACvD,UAAS,OAAO,CAAC,aAAa,CAAM,EACpC,iBAAgB,MAAgC,EAChD,MAAK,OAAe,EACpB,qBAAqB,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,KAC7D,OAAO,CACR,wBAAwB,GAAG;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CA6DtF,CAAA"}
+{"version":3,"file":"signAndSendTx.d.ts","sourceRoot":"","sources":["../../src/utils/signAndSendTx.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,KAAK,EACV,aAAa,EACb,MAAM,EAEN,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,UAAU,CAAA;AAKjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,eAAO,MAAM,aAAa,GAAU,MAAM,EACxC,QAAQ,aAAa,GAAG,WAAW,EACnC,IAAI,oBAAoB,CAAC,SAAS,EAAE,kBAAkB,CAAC,EACvD,UAAS,OAAO,CAAC,aAAa,CAAM,EACpC,iBAAgB,MAAgC,EAChD,MAAK,OAAe,EACpB,qBAAqB,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,KAC7D,OAAO,CACR,wBAAwB,GAAG;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CA6DtF,CAAA"}