@nockchain/rose 0.1.4-nightly.5

package/extension/shared/address-encoding.ts

@@ -0,0 +1,69 @@
+/**
+ * Address encoding utilities for Nockchain V1
+ * Converts public keys to base58-encoded PKH addresses
+ */
+
+import { base58 } from '@scure/base';
+import { hashPublicKey } from '@nockchain/rose-wasm/rose_wasm.js';
+
+/**
+ * Converts a public key to a Nockchain V1 PKH (Public Key Hash) address
+ * Uses proper Noun representation before hashing (matches CLI wallet)
+ *
+ * @param publicKey - The 97-byte public key from WASM
+ * @returns A ~60-character base58-encoded PKH address
+ */
+export function publicKeyToPKH(publicKey: Uint8Array): string {
+  if (publicKey.length !== 97) {
+    throw new Error(`Invalid public key length: ${publicKey.length}, expected 97`);
+  }
+
+  // Use proper Noun representation before hashing
+  const address = hashPublicKey(publicKey);
+
+  return address;
+}
+
+/**
+ * Converts digest bytes (40 bytes) to a base58-encoded digest string
+ * Used for communicating with WASM API which uses string-based digests
+ *
+ * @param digestBytes - The 40-byte digest (TIP5 hash)
+ * @returns Base58-encoded digest string
+ */
+export function digestBytesToString(digestBytes: Uint8Array): string {
+  if (digestBytes.length !== 40) {
+    throw new Error(`Invalid digest length: ${digestBytes.length}, expected 40`);
+  }
+  return base58.encode(digestBytes);
+}
+
+/**
+ * Converts a base58-encoded digest string to bytes
+ * Used for communicating with WASM API which uses string-based digests
+ *
+ * @param digestString - Base58-encoded digest string
+ * @returns The 40-byte digest
+ */
+export function digestStringToBytes(digestString: string): Uint8Array {
+  const bytes = base58.decode(digestString);
+  if (bytes.length !== 40) {
+    throw new Error(`Decoded digest has invalid length: ${bytes.length}, expected 40`);
+  }
+  return bytes;
+}
+
+/**
+ * Converts a public key to a PKH digest string (for WASM API)
+ * Uses proper Noun representation before hashing (matches CLI wallet)
+ *
+ * @param publicKey - The 97-byte public key
+ * @returns Base58-encoded PKH digest string
+ */
+export function publicKeyToPKHDigest(publicKey: Uint8Array): string {
+  if (publicKey.length !== 97) {
+    throw new Error(`Invalid public key length: ${publicKey.length}, expected 97`);
+  }
+  // Use proper Noun representation before hashing
+  return hashPublicKey(publicKey);
+}

package/extension/shared/balance-query.ts

@@ -0,0 +1,123 @@
+/**
+ * High-level balance query functions for Nockchain v1 addresses
+ *
+ * This module provides functions to query the balance of v1 PKH addresses
+ * by deriving the expected first-names for standard lock types and querying
+ * the gRPC API.
+ */
+
+import { NockchainBrowserRPCClient } from './rpc-client-browser';
+import { getBothFirstNames } from './first-name-derivation';
+import { NOCK_TO_NICKS } from './constants';
+import type { Note } from './types';
+
+/**
+ * Result of a balance query
+ */
+export interface BalanceResult {
+  /** Total balance in nicks (1 NOCK = 65,536 nicks) */
+  totalNicks: bigint;
+  /** Total balance in NOCK (for display) */
+  totalNock: number;
+  /** Simple (non-coinbase) notes */
+  simpleNotes: Note[];
+  /** Coinbase (mining reward) notes */
+  coinbaseNotes: Note[];
+  /** Total number of UTXOs/notes */
+  utxoCount: number;
+}
+
+/**
+ * Query the balance for a v1 PKH address
+ *
+ * This function:
+ * 1. Derives the expected first-names for both simple and coinbase notes
+ * 2. Queries the gRPC API for notes with each first-name
+ * 3. Combines and sums the results
+ *
+ * @param pkhBase58 - The base58-encoded v1 PKH address (~55 chars)
+ * @param rpcClient - The gRPC client to use for queries
+ * @returns Balance information including notes and totals
+ *
+ * @example
+ * ```typescript
+ * import { createBrowserClient } from './rpc-client-browser';
+ * import { queryV1Balance } from './balance-query';
+ *
+ * const client = createBrowserClient();
+ * const myPKH = "2R7Z8p..."; // Your v1 PKH address
+ * const balance = await queryV1Balance(myPKH, client);
+ *
+ * console.log(`Balance: ${balance.totalNock} NOCK`);
+ * console.log(`UTXOs: ${balance.utxoCount}`);
+ * console.log(`Simple notes: ${balance.simpleNotes.length}`);
+ * console.log(`Mining rewards: ${balance.coinbaseNotes.length}`);
+ * ```
+ */
+export async function queryV1Balance(
+  pkhBase58: string,
+  rpcClient: NockchainBrowserRPCClient
+): Promise<BalanceResult> {
+  // Derive both first-names
+  const { simple, coinbase } = await getBothFirstNames(pkhBase58);
+
+  // Query both types of notes in parallel
+  const [simpleNotes, coinbaseNotes] = await Promise.all([
+    rpcClient.getNotesByFirstName(simple),
+    rpcClient.getNotesByFirstName(coinbase),
+  ]);
+
+  // Sum the total value in nicks
+  const totalNicks = [...simpleNotes, ...coinbaseNotes].reduce(
+    (sum, note) => sum + BigInt(note.assets),
+    0n
+  );
+
+  // Convert to NOCK for display (1 NOCK = 65,536 nicks)
+  const totalNock = Number(totalNicks) / NOCK_TO_NICKS;
+
+  return {
+    totalNicks,
+    totalNock,
+    simpleNotes,
+    coinbaseNotes,
+    utxoCount: simpleNotes.length + coinbaseNotes.length,
+  };
+}
+
+/**
+ * Query only simple (non-coinbase) notes for a v1 PKH address
+ *
+ * Use this if you only care about regular transaction outputs.
+ *
+ * @param pkhBase58 - The base58-encoded v1 PKH address (~55 chars)
+ * @param rpcClient - The gRPC client to use for queries
+ * @returns Array of simple notes
+ */
+export async function querySimpleNotes(
+  pkhBase58: string,
+  rpcClient: NockchainBrowserRPCClient
+): Promise<Note[]> {
+  const { simple } = await getBothFirstNames(pkhBase58);
+  return rpcClient.getNotesByFirstName(simple);
+}
+
+/**
+ * Query only coinbase (mining reward) notes for a v1 PKH address
+ *
+ * Use this if you only care about mining rewards.
+ *
+ * NOTE: The coinbase lock structure currently uses placeholder timelock parameters.
+ * This will need to be updated once we extract the exact coinbase timelock from Hoon.
+ *
+ * @param pkhBase58 - The base58-encoded v1 PKH address (~55 chars)
+ * @param rpcClient - The gRPC client to use for queries
+ * @returns Array of coinbase notes
+ */
+export async function queryCoinbaseNotes(
+  pkhBase58: string,
+  rpcClient: NockchainBrowserRPCClient
+): Promise<Note[]> {
+  const { coinbase } = await getBothFirstNames(pkhBase58);
+  return rpcClient.getNotesByFirstName(coinbase);
+}

package/extension/shared/constants.ts

@@ -0,0 +1,386 @@
+/**
+ * Application Constants
+ * Defines all method names, error codes, storage keys, and other constants
+ * for wallet provider API and internal extension communication
+ */
+
+// Import provider methods from SDK
+import { PROVIDER_METHODS } from '@nockchain/sdk';
+
+/**
+ * Internal Extension Methods - Called by popup UI and other extension components
+ * Use 'wallet:' prefix to distinguish from public provider methods
+ */
+export const INTERNAL_METHODS = {
+  /** Get current wallet state */
+  GET_STATE: 'wallet:getState',
+
+  /** Unlock the wallet with password */
+  UNLOCK: 'wallet:unlock',
+
+  /** Lock the wallet */
+  LOCK: 'wallet:lock',
+
+  /** Reset/delete the wallet (clears all data) */
+  RESET_WALLET: 'wallet:resetWallet',
+
+  /** Setup/create a new wallet */
+  SETUP: 'wallet:setup',
+
+  /** Set auto-lock timeout in minutes */
+  SET_AUTO_LOCK: 'wallet:setAutoLock',
+
+  /** Create a new account */
+  CREATE_ACCOUNT: 'wallet:createAccount',
+
+  /** Switch to a different account */
+  SWITCH_ACCOUNT: 'wallet:switchAccount',
+
+  /** Get all accounts */
+  GET_ACCOUNTS: 'wallet:getAccounts',
+
+  /** Rename an account */
+  RENAME_ACCOUNT: 'wallet:renameAccount',
+
+  /** Update account styling (icon and color) */
+  UPDATE_ACCOUNT_STYLING: 'wallet:updateAccountStyling',
+
+  /** Hide an account from the UI */
+  HIDE_ACCOUNT: 'wallet:hideAccount',
+
+  /** Get mnemonic phrase (requires password verification) */
+  GET_MNEMONIC: 'wallet:getMnemonic',
+
+  /** Returns whether a v0 mnemonic is stored (requires unlocked) */
+  HAS_V0_MNEMONIC: 'wallet:hasV0Mnemonic',
+
+  /** Returns whether a v0 mnemonic is stored (requires unlocked) */
+  CLEAR_V0_MNEMONIC: 'wallet:clearV0Mnemonic',
+
+  /** Remove v0 mnemonic (requires password verification) */
+  SET_V0_MNEMONIC: 'wallet:setV0Mnemonic',
+
+  /** Get auto-lock timeout setting */
+  GET_AUTO_LOCK: 'wallet:getAutoLock',
+
+  /** Get balance from UTXO store (excludes in-flight notes) */
+  GET_BALANCE_FROM_STORE: 'wallet:getBalanceFromStore',
+
+  /** Get RPC connection status */
+  GET_CONNECTION_STATUS: 'wallet:getConnectionStatus',
+
+  /** Report RPC connection status from popup (where gRPC calls happen) */
+  REPORT_RPC_STATUS: 'wallet:reportRpcStatus',
+
+  /** Report user activity (e.g., popup opened) - resets auto-lock timer */
+  REPORT_ACTIVITY: 'wallet:reportActivity',
+
+  /** Get pending transaction request for approval */
+  GET_PENDING_TRANSACTION: 'wallet:getPendingTransaction',
+
+  /** Approve pending transaction request */
+  APPROVE_TRANSACTION: 'wallet:approveTransaction',
+
+  /** Reject pending transaction request */
+  REJECT_TRANSACTION: 'wallet:rejectTransaction',
+
+  /** Get pending sign message request for approval */
+  GET_PENDING_SIGN_REQUEST: 'wallet:getPendingSignRequest',
+
+  /** Get pending sign raw transaction request for approval */
+  GET_PENDING_SIGN_RAW_TX_REQUEST: 'wallet:getPendingSignRawTxRequest',
+
+  /** Approve pending sign message request */
+  APPROVE_SIGN_MESSAGE: 'wallet:approveSignMessage',
+
+  /** Reject pending sign message request */
+  REJECT_SIGN_MESSAGE: 'wallet:rejectSignMessage',
+
+  /** Get pending connection request for approval */
+  GET_PENDING_CONNECTION: 'wallet:getPendingConnection',
+
+  /** Approve pending connection request */
+  APPROVE_CONNECTION: 'wallet:approveConnection',
+
+  /** Reject pending connection request */
+  REJECT_CONNECTION: 'wallet:rejectConnection',
+
+  /** Revoke origin permissions */
+  REVOKE_ORIGIN: 'wallet:revokeOrigin',
+
+  /** Sign a transaction (internal popup-initiated transactions) */
+  SIGN_TRANSACTION: 'wallet:signTransaction',
+
+  /** Estimate transaction fee for a given recipient and amount */
+  ESTIMATE_TRANSACTION_FEE: 'wallet:estimateTransactionFee',
+
+  /** Estimate max sendable amount (for "send max" feature) */
+  ESTIMATE_MAX_SEND: 'wallet:estimateMaxSend',
+
+  /** Send a transaction (internal popup-initiated transactions - builds, signs, and broadcasts) */
+  SEND_TRANSACTION: 'wallet:sendTransaction',
+
+  /** Send transaction using UTXO store (build, lock, broadcast atomically) */
+  SEND_TRANSACTION_V2: 'wallet:sendTransactionV2',
+
+  /** Approve pending sign raw transaction request */
+  APPROVE_SIGN_RAW_TX: 'wallet:approveSignRawTx',
+
+  /** Reject pending sign raw transaction request */
+  REJECT_SIGN_RAW_TX: 'wallet:rejectSignRawTx',
+
+  /** Get pending sign raw transaction request */
+  GET_PENDING_RAW_TX_REQUEST: 'wallet:getPendingRawTxRequest',
+} as const;
+
+// Re-export PROVIDER_METHODS for other files
+export { PROVIDER_METHODS };
+
+/**
+ * All RPC methods (combined)
+ */
+export const RPC_METHODS = {
+  ...PROVIDER_METHODS,
+  ...INTERNAL_METHODS,
+} as const;
+
+/**
+ * Error Codes - Used in API error responses
+ */
+export const ERROR_CODES = {
+  /** Wallet is locked, user needs to unlock */
+  LOCKED: 'LOCKED',
+
+  /** No vault exists, user needs to create wallet */
+  NO_VAULT: 'NO_VAULT',
+
+  /** Incorrect password provided */
+  BAD_PASSWORD: 'BAD_PASSWORD',
+
+  /** Invalid address format */
+  BAD_ADDRESS: 'BAD_ADDRESS',
+
+  /** Invalid mnemonic phrase provided */
+  INVALID_MNEMONIC: 'INVALID_MNEMONIC',
+  INVALID_V0_MNEMONIC: 'INVALID_V0_MNEMONIC',
+
+  /** Invalid account index provided */
+  INVALID_ACCOUNT_INDEX: 'INVALID_ACCOUNT_INDEX',
+
+  /** No account selected */
+  NO_ACCOUNT: 'NO_ACCOUNT',
+
+  /** Cannot hide the last visible account */
+  CANNOT_HIDE_LAST_ACCOUNT: 'CANNOT_HIDE_LAST_ACCOUNT',
+
+  /** Unsupported RPC method requested */
+  METHOD_NOT_SUPPORTED: 'METHOD_NOT_SUPPORTED',
+
+  /** Unauthorized: internal methods can only be called from popup/extension pages */
+  UNAUTHORIZED: 'UNAUTHORIZED',
+
+  /** Requested resource not found (e.g., pending approval request) */
+  NOT_FOUND: 'NOT_FOUND',
+
+  /** Invalid parameters provided to method */
+  INVALID_PARAMS: 'INVALID_PARAMS',
+} as const;
+
+/**
+ * Chrome Storage Keys - Keys used for chrome.storage.local
+ */
+export const STORAGE_KEYS = {
+  /** Encrypted mnemonic data (iv, ct, salt) */
+  ENCRYPTED_VAULT: 'enc',
+
+  /** Current active account index */
+  CURRENT_ACCOUNT_INDEX: 'currentAccountIndex',
+
+  /** Auto-lock timeout in minutes */
+  AUTO_LOCK_MINUTES: 'autoLockMinutes',
+
+  /** Whether balance is hidden (privacy mode) */
+  BALANCE_HIDDEN: 'balanceHidden',
+
+  /** Onboarding state - tracks whether secret phrase backup is complete */
+  ONBOARDING_STATE: 'onboardingState',
+
+  /** Array of approved origins (websites that can access wallet) */
+  APPROVED_ORIGINS: 'approvedOrigins',
+
+  /** Cached balances per account address (persisted for offline access) */
+  CACHED_BALANCES: 'cachedBalances',
+
+  /** UTXO store per account - tracks note state (available, in_flight, spent) */
+  UTXO_STORE: 'utxoStore',
+
+  /** Wallet transactions per account - separate from UTXO lifecycle */
+  WALLET_TX_STORE: 'walletTxStore',
+
+  /** Per-account sync state (last synced block height) */
+  ACCOUNT_SYNC_STATE: 'accountSyncState',
+
+  /** Storage schema version for migrations */
+  SCHEMA_VERSION: 'schemaVersion',
+
+  /** Last user activity timestamp for auto-lock (survives SW restarts) */
+  LAST_ACTIVITY: 'lastActivity',
+
+  /** Whether the user manually locked the wallet (survives SW restarts) */
+  MANUALLY_LOCKED: 'manuallyLocked',
+} as const;
+
+/**
+ * Chrome Session Storage Keys - ephemeral cache for unlocked session data
+ */
+export const SESSION_STORAGE_KEYS = {
+  /** Cached encryption key to restore unlock state after SW restarts */
+  UNLOCK_CACHE: 'unlockCache',
+} as const;
+
+/** Current storage schema version - increment when making breaking changes */
+export const CURRENT_SCHEMA_VERSION = 1;
+
+/**
+ * Chrome Alarm Names - Named alarms for scheduled tasks
+ */
+export const ALARM_NAMES = {
+  /** Auto-lock timeout alarm */
+  AUTO_LOCK: 'autoLock',
+} as const;
+
+/**
+ * Message Targets - Used for window.postMessage routing
+ */
+export const MESSAGE_TARGETS = {
+  /** Target identifier for wallet bridge messages */
+  WALLET_BRIDGE: 'ROSE',
+} as const;
+
+/**
+ * Configuration - Default settings
+ */
+/** Default auto-lock timeout in minutes (0 = never) */
+export const AUTOLOCK_MINUTES = 0;
+
+/** Default RPC endpoint URL */
+export const RPC_ENDPOINT = 'https://rpc.nockbox.org';
+
+/**
+ * Nockchain Currency Conversion
+ */
+/** Conversion rate: 1 NOCK = 65,536 nicks (2^16) */
+export const NOCK_TO_NICKS = 65_536;
+
+/** Default transaction fee in nicks (3,407,872 nicks = 52 NOCK)
+ * Used only for UI defaults in send form and approval screens.
+ * Actual fees are ALWAYS auto-calculated by WASM based on transaction size.
+ * This is just a reasonable starting point for the fee input field.
+ */
+export const DEFAULT_TRANSACTION_FEE = 3_407_872;
+
+/** Fee per word (8-byte unit) for transaction size calculation in nicks */
+export const DEFAULT_FEE_PER_WORD = 1 << 15; // 32,768 nicks = 0.5 NOCK per word
+
+/**
+ * User Activity Methods - Methods that count as user activity for auto-lock timer
+ * Only these methods reset the lastActivity timestamp. Passive/polling methods
+ * (like GET_STATE, GET_ACCOUNTS, etc.) do NOT reset the timer.
+ */
+export const USER_ACTIVITY_METHODS = new Set([
+  // Provider methods (user-initiated actions from dApps)
+  PROVIDER_METHODS.CONNECT,
+  PROVIDER_METHODS.SIGN_MESSAGE,
+  PROVIDER_METHODS.SEND_TRANSACTION,
+  PROVIDER_METHODS.SIGN_RAW_TX,
+
+  // Internal methods (user actions in the UI)
+  INTERNAL_METHODS.UNLOCK,
+  INTERNAL_METHODS.SWITCH_ACCOUNT,
+  INTERNAL_METHODS.CREATE_ACCOUNT,
+  INTERNAL_METHODS.RENAME_ACCOUNT,
+  INTERNAL_METHODS.UPDATE_ACCOUNT_STYLING,
+  INTERNAL_METHODS.HIDE_ACCOUNT,
+  INTERNAL_METHODS.SET_AUTO_LOCK,
+  INTERNAL_METHODS.GET_MNEMONIC, // Viewing secret phrase is user activity
+  INTERNAL_METHODS.SEND_TRANSACTION_V2,
+  INTERNAL_METHODS.ESTIMATE_TRANSACTION_FEE,
+  INTERNAL_METHODS.ESTIMATE_MAX_SEND,
+  INTERNAL_METHODS.REPORT_ACTIVITY,
+]);
+
+/**
+ * UI Constants - Dimensions and constraints
+ */
+export const UI_CONSTANTS = {
+  /** Extension popup width in pixels */
+  POPUP_WIDTH: 357,
+  /** Extension popup height in pixels */
+  POPUP_HEIGHT: 600,
+  /** Approval popup top offset in pixels */
+  POPUP_TOP_OFFSET: 40,
+  /** Approval popup right offset in pixels */
+  POPUP_RIGHT_OFFSET: 20,
+  /** Wallet state polling interval in milliseconds */
+  STATE_POLL_INTERVAL: 2000,
+  /** Minimum password length */
+  MIN_PASSWORD_LENGTH: 8,
+  /** Number of words in BIP-39 mnemonic */
+  MNEMONIC_WORD_COUNT: 24,
+} as const;
+
+/**
+ * Account Icon Colors - Available colors for account customization
+ */
+export const ACCOUNT_COLORS = [
+  '#2C9AEF', // blue
+  '#EF2C2F', // red
+  '#5968fb', // yellow (primary)
+  '#96B839', // green
+  '#3C2CEF', // purple
+  '#EF2CB1', // pink/magenta
+  '#2C6AEF', // darker blue
+] as const;
+
+/**
+ * Preset Wallet Styles - Predetermined icon/color combinations for first 21 wallets
+ * Ensures visual variety without repeating until all presets are used
+ * After preset limit, random combinations are used
+ */
+export const PRESET_WALLET_STYLES = [
+  { iconStyleId: 1, iconColor: '#5968fb' }, // Wallet 1: yellow, style 1
+  { iconStyleId: 5, iconColor: '#2C9AEF' }, // Wallet 2: blue, style 5
+  { iconStyleId: 9, iconColor: '#EF2C2F' }, // Wallet 3: red, style 9
+  { iconStyleId: 3, iconColor: '#96B839' }, // Wallet 4: green, style 3
+  { iconStyleId: 12, iconColor: '#3C2CEF' }, // Wallet 5: purple, style 12
+  { iconStyleId: 7, iconColor: '#EF2CB1' }, // Wallet 6: pink, style 7
+  { iconStyleId: 15, iconColor: '#2C6AEF' }, // Wallet 7: dark blue, style 15
+  { iconStyleId: 2, iconColor: '#EF2C2F' }, // Wallet 8: red, style 2
+  { iconStyleId: 6, iconColor: '#5968fb' }, // Wallet 9: yellow, style 6
+  { iconStyleId: 10, iconColor: '#96B839' }, // Wallet 10: green, style 10
+  { iconStyleId: 4, iconColor: '#2C9AEF' }, // Wallet 11: blue, style 4
+  { iconStyleId: 13, iconColor: '#EF2CB1' }, // Wallet 12: pink, style 13
+  { iconStyleId: 8, iconColor: '#3C2CEF' }, // Wallet 13: purple, style 8
+  { iconStyleId: 14, iconColor: '#2C6AEF' }, // Wallet 14: dark blue, style 14
+  { iconStyleId: 11, iconColor: '#EF2C2F' }, // Wallet 15: red, style 11
+  { iconStyleId: 1, iconColor: '#96B839' }, // Wallet 16: green, style 1
+  { iconStyleId: 5, iconColor: '#5968fb' }, // Wallet 17: yellow, style 5
+  { iconStyleId: 9, iconColor: '#2C9AEF' }, // Wallet 18: blue, style 9
+  { iconStyleId: 3, iconColor: '#3C2CEF' }, // Wallet 19: purple, style 3
+  { iconStyleId: 12, iconColor: '#EF2CB1' }, // Wallet 20: pink, style 12
+  { iconStyleId: 7, iconColor: '#2C6AEF' }, // Wallet 21: dark blue, style 7
+] as const;
+
+/**
+ * Approval Request Constants - URL hash prefixes for approval flows
+ */
+export const APPROVAL_CONSTANTS = {
+  /** Hash prefix for connection approval requests */
+  CONNECT_HASH_PREFIX: 'connect-approval-',
+  /** Hash prefix for transaction approval requests */
+  TRANSACTION_HASH_PREFIX: 'transaction-approval-',
+  /** Hash prefix for sign message approval requests */
+  SIGN_MESSAGE_HASH_PREFIX: 'sign-message-approval-',
+  /** Hash prefix for sign raw transaction approval requests */
+  SIGN_RAW_TX_HASH_PREFIX: 'sign-raw-tx-approval-',
+} as const;

package/extension/shared/currency.ts

@@ -0,0 +1,128 @@
+/**
+ * NOCK/NICK Currency Conversion Utilities
+ *
+ * NOCK = Display unit (supports decimals)
+ * NICK = Base unit (whole numbers only, what blockchain accepts)
+ *
+ * 1 NOCK = 65,536 NICK (2^16)
+ * 1 NICK = 0.0000152587890625 NOCK
+ */
+
+import { NOCK_TO_NICKS } from './constants';
+
+/**
+ * Convert NOCK to whole NICK with proper rounding
+ *
+ * Uses Math.round() to minimize cumulative rounding errors
+ *
+ * @param nockAmount - Amount in NOCK (can have decimals)
+ * @returns Whole number of NICKS (what blockchain accepts)
+ *
+ * @example
+ * nockToNick(1.5) // 98304 NICK
+ * nockToNick(100.12345) // 6561690 NICK
+ */
+export function nockToNick(nockAmount: number): number {
+  const exactNick = nockAmount * NOCK_TO_NICKS;
+  return Math.round(exactNick);
+}
+
+/**
+ * Convert NICK to NOCK
+ *
+ * @param nickAmount - Amount in NICK (whole number)
+ * @returns Amount in NOCK
+ *
+ * @example
+ * nickToNock(65536) // 1.0 NOCK
+ * nickToNock(98304) // 1.5 NOCK
+ */
+export function nickToNock(nickAmount: number): number {
+  return nickAmount / NOCK_TO_NICKS;
+}
+
+/**
+ * Round NOCK amount to actual sendable amount
+ *
+ * This is what the user will actually send after blockchain rounding.
+ * Use this on input blur to show users the exact amount.
+ *
+ * @param nockAmount - Amount user entered in NOCK
+ * @returns Actual NOCK amount that will be sent (after NICK rounding)
+ *
+ * @example
+ * roundNockToSendable(100.12345) // 100.12344360351562
+ * roundNockToSendable(1.23456789) // 1.2345886230468750
+ * roundNockToSendable(0.00001) // 0.0000152587890625 (1 NICK)
+ */
+export function roundNockToSendable(nockAmount: number): number {
+  if (nockAmount === 0) return 0;
+
+  const roundedNick = nockToNick(nockAmount);
+  return nickToNock(roundedNick);
+}
+
+/**
+ * Check if amount is too small to send (would round to 0 NICK)
+ *
+ * @param nockAmount - Amount in NOCK
+ * @returns true if amount rounds to 0 NICK (dust)
+ *
+ * @example
+ * isDustAmount(0.000001) // true (rounds to 0 NICK)
+ * isDustAmount(0.00001) // false (rounds to 1 NICK)
+ */
+export function isDustAmount(nockAmount: number): boolean {
+  if (nockAmount <= 0) return false; // Zero/negative handled separately
+  const roundedNick = nockToNick(nockAmount);
+  return roundedNick === 0;
+}
+
+/**
+ * Format NOCK for display with smart decimal precision and thousands separators
+ *
+ * Shows minimum decimals needed (up to 5 max) with commas for readability:
+ * - 2.5 → "2.5" (not "2.50000")
+ * - 1000.12345 → "1,000.12345"
+ * - 100.1234567 → "100.12346" (rounded to 5)
+ *
+ * @param nockAmount - Amount in NOCK
+ * @param maxDecimals - Maximum decimal places (default: 5)
+ * @returns Formatted NOCK string with minimal decimals and thousands separators
+ *
+ * @example
+ * formatNock(2.5) // "2.5"
+ * formatNock(1000.12345) // "1,000.12345"
+ * formatNock(100.00) // "100"
+ */
+export function formatNock(nockAmount: number, maxDecimals: number = 5): string {
+  // Round to max decimals first
+  const rounded = Number(nockAmount.toFixed(maxDecimals));
+
+  // Split into integer and decimal parts
+  const [integerPart, decimalPart] = rounded.toString().split('.');
+
+  // Add thousands separators to integer part
+  const formattedInteger = parseInt(integerPart).toLocaleString('en-US');
+
+  // Recombine with decimal part (if exists)
+  return decimalPart ? `${formattedInteger}.${decimalPart}` : formattedInteger;
+}
+
+/**
+ * Format NICK with thousands separators
+ *
+ * @param nickAmount - Amount in NICK
+ * @returns Formatted string with commas
+ *
+ * @example
+ * formatNick(6561690) // "6,561,690"
+ */
+export function formatNick(nickAmount: number): string {
+  return Math.round(nickAmount).toLocaleString('en-US');
+}
+
+/**
+ * Minimum sendable amount (1 NICK in NOCK)
+ */
+export const MIN_SENDABLE_NOCK = 1 / NOCK_TO_NICKS; // 0.0000152587890625