@d9-network/spec 0.0.12 → 0.0.14

package/dist/index.cjs

@@ -7463,7 +7463,7 @@ var getMetadata2 = async (codeHash) => {
 * @example
 * ```ts
 * const d9Client = createD9SdkClient({
-*   endpoint: "wss://mainnet.d9network.com:40300",
+*   endpoint: "wss://archiver.d9network.com:40300",
 * });
 *
 * // Query USDT balance
@@ -7584,8 +7584,392 @@ function createAccountFromPrivateKey(options) {
 	};
 }
 
+//#endregion
+//#region src/utils/balance.ts
+/**
+* Balance formatting utilities for D9 blockchain
+*/
+const D9_DECIMALS = 12;
+const D9_SYMBOL = "D9";
+const D9_SS58_PREFIX = 9;
+const USDT_DECIMALS = 2;
+const USDT_SYMBOL = "USDT";
+/**
+* Pre-configured D9 token
+*/
+const D9_TOKEN = {
+	decimals: D9_DECIMALS,
+	symbol: D9_SYMBOL
+};
+/**
+* Pre-configured USDT token
+*/
+const USDT_TOKEN = {
+	decimals: USDT_DECIMALS,
+	symbol: USDT_SYMBOL
+};
+/**
+* Format a raw planck value to a human-readable balance string
+*
+* @param planck - The raw balance in planck units (smallest unit)
+* @param options - Formatting options
+* @returns Formatted balance string
+*
+* @example
+* ```typescript
+* formatBalance(1_500_000_000_000n, { decimals: 12 }); // "1.5"
+* formatBalance(1_500_000_000_000n, { decimals: 12, maxDecimals: 2 }); // "1.50"
+* formatBalance(1_000_000_000_000_000n, { decimals: 12, thousandsSeparator: "," }); // "1,000"
+* ```
+*/
+function formatBalance(planck, options = {}) {
+	const { decimals = D9_DECIMALS, maxDecimals = 4, trimTrailingZeros = true, thousandsSeparator } = options;
+	if (decimals < 0 || decimals > 30) throw new Error("Decimals must be between 0 and 30");
+	const divisor = 10n ** BigInt(decimals);
+	const isNegative = planck < 0n;
+	const absolutePlanck = isNegative ? -planck : planck;
+	const wholePart = absolutePlanck / divisor;
+	const fractionalPart = absolutePlanck % divisor;
+	let wholeStr = wholePart.toString();
+	if (thousandsSeparator && wholeStr.length > 3) wholeStr = wholeStr.replace(/\B(?=(\d{3})+(?!\d))/g, thousandsSeparator);
+	if (decimals === 0 || maxDecimals === 0) return isNegative ? `-${wholeStr}` : wholeStr;
+	let fractionalStr = fractionalPart.toString().padStart(decimals, "0");
+	if (fractionalStr.length > maxDecimals) fractionalStr = fractionalStr.slice(0, maxDecimals);
+	if (trimTrailingZeros) fractionalStr = fractionalStr.replace(/0+$/, "");
+	const prefix = isNegative ? "-" : "";
+	if (fractionalStr === "") return `${prefix}${wholeStr}`;
+	return `${prefix}${wholeStr}.${fractionalStr}`;
+}
+/**
+* Parse a human-readable amount string to planck units
+*
+* @param amount - The amount as a string or number
+* @param options - Parse options
+* @returns The amount in planck units (bigint)
+*
+* @example
+* ```typescript
+* parseAmount("1.5", { decimals: 12 }); // 1_500_000_000_000n
+* parseAmount(1.5, { decimals: 12 }); // 1_500_000_000_000n
+* parseAmount("1,000.50", { decimals: 12 }); // 1_000_500_000_000_000n
+* ```
+*/
+function parseAmount(amount, options = {}) {
+	const { decimals = D9_DECIMALS } = options;
+	if (decimals < 0 || decimals > 30) throw new Error("Decimals must be between 0 and 30");
+	let amountStr = String(amount).replace(/,/g, "").trim();
+	const isNegative = amountStr.startsWith("-");
+	if (isNegative) amountStr = amountStr.slice(1);
+	if (!/^\d*\.?\d*$/.test(amountStr) || amountStr === "" || amountStr === ".") throw new Error(`Invalid amount format: ${amount}`);
+	const [wholePart = "0", fractionalPart = ""] = amountStr.split(".");
+	if (fractionalPart.length > decimals) throw new Error(`Amount has more decimal places (${fractionalPart.length}) than supported (${decimals})`);
+	const planckStr = wholePart + fractionalPart.padEnd(decimals, "0");
+	const planck = BigInt(planckStr);
+	return isNegative ? -planck : planck;
+}
+/**
+* Format a token amount with symbol
+*
+* @param planck - The raw balance in planck units
+* @param token - Token configuration
+* @param options - Additional formatting options
+* @returns Formatted string with token symbol
+*
+* @example
+* ```typescript
+* formatTokenAmount(1_500_000_000_000n, D9_TOKEN); // "1.5 D9"
+* formatTokenAmount(1000n, USDT_TOKEN); // "10 USDT"
+* ```
+*/
+function formatTokenAmount(planck, token, options = {}) {
+	return `${formatBalance(planck, {
+		...options,
+		decimals: token.decimals
+	})} ${token.symbol}`;
+}
+
+//#endregion
+//#region src/wallet/validation.ts
+/**
+* Address validation utilities for D9 blockchain
+*/
+/**
+* Check if a value is a valid SS58 address
+*
+* @param address - The value to check
+* @returns True if the value is a valid SS58 address
+*
+* @example
+* ```typescript
+* isValidAddress("5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"); // true
+* isValidAddress("invalid"); // false
+* isValidAddress(null); // false
+* ```
+*/
+function isValidAddress(address) {
+	if (typeof address !== "string" || address.length === 0) return false;
+	try {
+		(0, _polkadot_labs_hdkd_helpers.ss58Decode)(address);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Check if a value is a valid D9 address (SS58 prefix 9)
+*
+* @param address - The value to check
+* @returns True if the value is a valid D9 address
+*
+* @example
+* ```typescript
+* isValidD9Address("XYZd9..."); // true (if valid D9 prefix)
+* isValidD9Address("5GrwvaEF..."); // false (Polkadot prefix)
+* ```
+*/
+function isValidD9Address(address) {
+	return isValidAddressForNetwork(address, D9_SS58_PREFIX);
+}
+/**
+* Check if a value is a valid address for a specific network
+*
+* @param address - The value to check
+* @param expectedPrefix - The expected SS58 prefix
+* @returns True if the value is a valid address with the expected prefix
+*
+* @example
+* ```typescript
+* isValidAddressForNetwork(address, 0); // Polkadot
+* isValidAddressForNetwork(address, 2); // Kusama
+* isValidAddressForNetwork(address, 9); // D9
+* ```
+*/
+function isValidAddressForNetwork(address, expectedPrefix) {
+	if (typeof address !== "string" || address.length === 0) return false;
+	try {
+		const [, prefix] = (0, _polkadot_labs_hdkd_helpers.ss58Decode)(address);
+		return prefix === expectedPrefix;
+	} catch {
+		return false;
+	}
+}
+/**
+* Get the SS58 prefix of an address
+*
+* @param address - The SS58 address
+* @returns The SS58 prefix
+* @throws Error if the address is invalid
+*
+* @example
+* ```typescript
+* getAddressPrefix("5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"); // 42 (Substrate generic)
+* ```
+*/
+function getAddressPrefix(address) {
+	const [, prefix] = (0, _polkadot_labs_hdkd_helpers.ss58Decode)(address);
+	return prefix;
+}
+/**
+* Compare two addresses for equality (same public key)
+*
+* Addresses with different SS58 prefixes can represent the same account.
+* This function compares the underlying public keys.
+*
+* @param a - First address
+* @param b - Second address
+* @returns True if both addresses represent the same public key
+*
+* @example
+* ```typescript
+* // Same account, different network formats
+* const polkadotAddr = "15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5";
+* const genericAddr = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
+* addressesEqual(polkadotAddr, genericAddr); // true
+* ```
+*/
+function addressesEqual(a, b) {
+	try {
+		const [publicKeyA] = (0, _polkadot_labs_hdkd_helpers.ss58Decode)(a);
+		const [publicKeyB] = (0, _polkadot_labs_hdkd_helpers.ss58Decode)(b);
+		if (publicKeyA.length !== publicKeyB.length) return false;
+		for (let i = 0; i < publicKeyA.length; i++) if (publicKeyA[i] !== publicKeyB[i]) return false;
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Convert an address to a specific SS58 format
+*
+* @param address - The SS58 address
+* @param targetPrefix - The target SS58 prefix
+* @returns The address encoded with the target prefix
+* @throws Error if the address is invalid
+*
+* @example
+* ```typescript
+* const d9Address = toNetworkAddress("5GrwvaEF...", 9);
+* ```
+*/
+function toNetworkAddress(address, targetPrefix) {
+	const [publicKey] = (0, _polkadot_labs_hdkd_helpers.ss58Decode)(address);
+	return (0, _polkadot_labs_hdkd_helpers.ss58Encode)(publicKey, targetPrefix);
+}
+/**
+* Convert an address to D9 format
+*
+* @param address - The SS58 address
+* @returns The address encoded with D9 prefix (9)
+*
+* @example
+* ```typescript
+* const d9Address = toD9Address("5GrwvaEF...");
+* ```
+*/
+function toD9Address(address) {
+	return toNetworkAddress(address, D9_SS58_PREFIX);
+}
+
+//#endregion
+//#region src/utils/time.ts
+/**
+* Block time utilities for D9 blockchain
+*/
+const D9_BLOCK_TIME_MS = 3e3;
+const BLOCKS_PER_MINUTE = 20;
+const BLOCKS_PER_HOUR = 1200;
+const BLOCKS_PER_DAY = 28800;
+const BLOCKS_PER_WEEK = 201600;
+/**
+* Convert milliseconds to blocks
+*
+* @param ms - Duration in milliseconds
+* @returns Number of blocks (rounded down)
+*
+* @example
+* ```typescript
+* msToBlocks(60_000); // 20 blocks (1 minute)
+* msToBlocks(3_600_000); // 1200 blocks (1 hour)
+* ```
+*/
+function msToBlocks(ms) {
+	if (ms < 0) throw new Error("Duration cannot be negative");
+	return Math.floor(ms / D9_BLOCK_TIME_MS);
+}
+/**
+* Convert blocks to milliseconds
+*
+* @param blocks - Number of blocks
+* @returns Duration in milliseconds
+*
+* @example
+* ```typescript
+* blocksToMs(20); // 60_000 (1 minute)
+* blocksToMs(1200); // 3_600_000 (1 hour)
+* ```
+*/
+function blocksToMs(blocks) {
+	if (blocks < 0) throw new Error("Block count cannot be negative");
+	return blocks * D9_BLOCK_TIME_MS;
+}
+/**
+* Estimate the block number at a target time
+*
+* @param targetTime - The target time to estimate block for
+* @param currentBlock - The current block number
+* @param currentTime - The current time (default: now)
+* @returns Estimated block number at target time
+*
+* @example
+* ```typescript
+* const targetBlock = estimateBlockAtTime(
+*   new Date(Date.now() + 3_600_000), // 1 hour from now
+*   1000, // current block
+* ); // ~2200
+* ```
+*/
+function estimateBlockAtTime(targetTime, currentBlock, currentTime = /* @__PURE__ */ new Date()) {
+	const timeDiffMs = targetTime.getTime() - currentTime.getTime();
+	const blockDiff = Math.floor(timeDiffMs / D9_BLOCK_TIME_MS);
+	return Math.max(0, currentBlock + blockDiff);
+}
+/**
+* Estimate the time at a target block
+*
+* @param targetBlock - The target block number
+* @param currentBlock - The current block number
+* @param currentTime - The current time (default: now)
+* @returns Estimated time at target block
+*
+* @example
+* ```typescript
+* const unlockTime = estimateTimeAtBlock(
+*   2200, // target block
+*   1000, // current block
+* ); // ~1 hour from now
+* ```
+*/
+function estimateTimeAtBlock(targetBlock, currentBlock, currentTime = /* @__PURE__ */ new Date()) {
+	const timeDiffMs = (targetBlock - currentBlock) * D9_BLOCK_TIME_MS;
+	return new Date(currentTime.getTime() + timeDiffMs);
+}
+/**
+* Calculate the number of blocks until a target time
+*
+* @param targetTime - The target time
+* @param currentBlock - The current block number
+* @param currentTime - The current time (default: now)
+* @returns Number of blocks until target time (negative if in the past)
+*
+* @example
+* ```typescript
+* const blocksRemaining = blocksUntil(unlockTime, currentBlock);
+* if (blocksRemaining > 0) {
+*   console.log(`${blocksRemaining} blocks until unlock`);
+* }
+* ```
+*/
+function blocksUntil(targetTime, currentBlock, currentTime = /* @__PURE__ */ new Date()) {
+	return estimateBlockAtTime(targetTime, currentBlock, currentTime) - currentBlock;
+}
+/**
+* Format a block duration as a human-readable string
+*
+* @param blocks - Number of blocks
+* @param options - Formatting options
+* @returns Human-readable duration string
+*
+* @example
+* ```typescript
+* formatBlockDuration(20); // "1 minute"
+* formatBlockDuration(1200); // "1 hour"
+* formatBlockDuration(BLOCKS_PER_DAY); // "1 day"
+* formatBlockDuration(30000, { short: true }); // "1d 1h"
+* ```
+*/
+function formatBlockDuration(blocks, options = {}) {
+	const { short = false, maxUnits = 2 } = options;
+	if (blocks < 0) throw new Error("Block count cannot be negative");
+	if (blocks === 0) return short ? "0s" : "0 seconds";
+	const totalSeconds = Math.floor(blocks * D9_BLOCK_TIME_MS / 1e3);
+	const days = Math.floor(totalSeconds / 86400);
+	const hours = Math.floor(totalSeconds % 86400 / 3600);
+	const minutes = Math.floor(totalSeconds % 3600 / 60);
+	const seconds = totalSeconds % 60;
+	const parts = [];
+	if (days > 0) parts.push(short ? `${days}d` : `${days} ${days === 1 ? "day" : "days"}`);
+	if (hours > 0) parts.push(short ? `${hours}h` : `${hours} ${hours === 1 ? "hour" : "hours"}`);
+	if (minutes > 0) parts.push(short ? `${minutes}m` : `${minutes} ${minutes === 1 ? "minute" : "minutes"}`);
+	if (seconds > 0 && parts.length < maxUnits) parts.push(short ? `${seconds}s` : `${seconds} ${seconds === 1 ? "second" : "seconds"}`);
+	return parts.slice(0, maxUnits).join(short ? " " : ", ");
+}
+
 //#endregion
 exports.ArithmeticError = ArithmeticError;
+exports.BLOCKS_PER_DAY = BLOCKS_PER_DAY;
+exports.BLOCKS_PER_HOUR = BLOCKS_PER_HOUR;
+exports.BLOCKS_PER_MINUTE = BLOCKS_PER_MINUTE;
+exports.BLOCKS_PER_WEEK = BLOCKS_PER_WEEK;
 exports.BalanceStatus = BalanceStatus;
 exports.BalancesTypesReasons = BalancesTypesReasons;
 Object.defineProperty(exports, 'ContractEventParser', {
@@ -7594,6 +7978,11 @@ Object.defineProperty(exports, 'ContractEventParser', {
     return _d9_network_ink.ContractEventParser;
   }
 });
+exports.D9_BLOCK_TIME_MS = D9_BLOCK_TIME_MS;
+exports.D9_DECIMALS = D9_DECIMALS;
+exports.D9_SS58_PREFIX = D9_SS58_PREFIX;
+exports.D9_SYMBOL = D9_SYMBOL;
+exports.D9_TOKEN = D9_TOKEN;
 exports.DigestItem = DigestItem;
 exports.DispatchClass = DispatchClass;
 exports.GrandpaEquivocation = GrandpaEquivocation;
@@ -7605,6 +7994,12 @@ exports.SessionEvent = SessionEvent;
 exports.TransactionPaymentEvent = TransactionPaymentEvent;
 exports.TransactionPaymentReleases = TransactionPaymentReleases;
 exports.TransactionalError = TransactionalError;
+exports.USDT_DECIMALS = USDT_DECIMALS;
+exports.USDT_SYMBOL = USDT_SYMBOL;
+exports.USDT_TOKEN = USDT_TOKEN;
+exports.addressesEqual = addressesEqual;
+exports.blocksToMs = blocksToMs;
+exports.blocksUntil = blocksUntil;
 exports.bytesToHex = bytesToHex;
 exports.contracts = contracts_exports;
 exports.createAccountFromMnemonic = createAccountFromMnemonic;
@@ -7630,16 +8025,29 @@ Object.defineProperty(exports, 'createPSP22TransferStream', {
 });
 exports.createSr25519SignerFromKeypair = createSr25519SignerFromKeypair;
 exports.d9 = d9_default;
+exports.estimateBlockAtTime = estimateBlockAtTime;
+exports.estimateTimeAtBlock = estimateTimeAtBlock;
+exports.formatBalance = formatBalance;
+exports.formatBlockDuration = formatBlockDuration;
+exports.formatTokenAmount = formatTokenAmount;
 exports.generateMnemonic = generateMnemonic;
+exports.getAddressPrefix = getAddressPrefix;
 exports.getMetadata = getMetadata2;
 exports.hexToBytes = hexToBytes;
 exports.isHexString = isHexString;
+exports.isValidAddress = isValidAddress;
+exports.isValidAddressForNetwork = isValidAddressForNetwork;
+exports.isValidD9Address = isValidD9Address;
 exports.mnemonicToMiniSecret = mnemonicToMiniSecret;
+exports.msToBlocks = msToBlocks;
+exports.parseAmount = parseAmount;
 exports.sr25519AddressFromKeypair = sr25519AddressFromKeypair;
 exports.sr25519AddressFromSecretKeyHex = sr25519AddressFromSecretKeyHex;
 exports.sr25519DeriveFromMiniSecret = sr25519DeriveFromMiniSecret;
 exports.sr25519KeypairFromMiniSecret = sr25519KeypairFromMiniSecret;
 exports.ss58DecodePublicKey = ss58DecodePublicKey;
 exports.ss58Reencode = ss58Reencode;
+exports.toD9Address = toD9Address;
+exports.toNetworkAddress = toNetworkAddress;
 exports.validateMnemonic = validateMnemonic;
 //# sourceMappingURL=index.cjs.map