@neuraiproject/neurai-assets 1.6.1 → 1.6.2

package/README.md

@@ -1100,3 +1100,34 @@ Canonical `createTransactionBuild` quantities and changes remain bigint.
 XNA string outputs are preserved during output ordering. Exact selection totals
 remain available as `totalSats` / raw methods; never use a rounded display value
 as a new transaction input.
+
+
+## Exact amounts and legacy converter migration
+
+In 1.6.2, insufficient-funds errors preserve `required` and `available` as
+`number | string`. Large fractional amounts are returned as exact decimal text;
+consumers must not convert them to `Number` before computing or displaying funds.
+`BuildInput.satoshis` accepts exact raw integers and `changeAmount` may be text.
+
+```js
+import { utils } from '@neuraiproject/neurai-assets';
+const { assetAmountToRaw, rawToDisplayAmount, formatRawAsDecimal } = utils.AssetAmount;
+const raw = assetAmountToRaw('100000000.00000001', 8);
+const compatibleDisplay = rawToDisplayAmount(raw); // '100000000.00000001'
+const decimalText = formatRawAsDecimal(raw); // Always plain decimal text
+```
+
+`utils.AmountConverter` is deprecated but retains its existing behavior in 1.x.
+It may round even when its result is a safe integer. Its scale is `10^units`;
+protocol XNA and asset amounts always use `10^8`, with `units` only restricting
+asset divisibility. For example, legacy `toSatoshis(1.23, 2)` returns `123`, while
+`assetAmountToRaw('1.23', 2)` returns `123000000n`. Check the unit of stored values
+before migrating: for a valid legacy integer with units 2, multiplying that exact
+integer by `1000000n` converts it to protocol raw units. Already rounded digits
+cannot be recovered. Prefer the original decimal text whenever available.
+
+Replace protocol decimal-to-raw conversion with `assetAmountToRaw`, and raw-to-display
+conversion with `rawToDisplayAmount` or `formatRawAsDecimal`. These are not drop-in
+replacements for legacy formatting or deliberate rounding. Keep user input as
+text; validate divisibility instead of silently rounding it. A display number can
+use exponent notation for tiny values, so use `formatRawAsDecimal` for plain text.

package/dist/NeuraiAssets.global.js

@@ -129,7 +129,13 @@ var NeuraiAssetsBundle = (function (exports) {
 		  }
 		}
 
+		/** Required and available are exact display amounts, before any funding buffer. */
 		class InsufficientFundsError extends ValidationError {
+		  /**
+		   * @param {string} message
+		   * @param {number|string} required
+		   * @param {number|string} available
+		   */
 		  constructor(message, required, available) {
 		    super(message);
 		    this.name = 'InsufficientFundsError';
@@ -4670,26 +4676,9 @@ var NeuraiAssetsBundle = (function (exports) {
 	 * **through text**: scaling the decimal string keeps every digit the caller
 	 * wrote, and refuses the ones it cannot keep.
 	 *
-	 * The alternative — `BigInt(Math.round(value * 1e8))`, which is what
-	 * `assetUnitsToRaw` in neurai-create-transaction does — is correct for
-	 * ordinary magnitudes. `4.35 * 1e8` is `434999999.99999994`, but `Math.round`
-	 * recovers `435000000`; that example shows binary representation, not a wrong
-	 * result. For a finite, non-negative number it has two silent failure modes:
-	 *
-	 *   - more than eight decimals are rounded away instead of rejected, so an
-	 *     amount can vanish (`1e-9` becomes `0n`) or shift (`1.123456789` becomes
-	 *     `112345679`);
-	 *   - past `Number.MAX_SAFE_INTEGER` a double can no longer represent every
-	 *     integer, so the product may or may not survive — and nothing says which.
-	 *     `184467440.73709551` comes back as `18446744073709552n`, one unit off,
-	 *     while `21000000000` scales to `2100000000000000000n` exactly. The risk
-	 *     is that the two cases are indistinguishable from the outside.
-	 *
-	 * Outside that range its `Number(amount || 0)` also turns `NaN`, `null` and
-	 * `''` into `0n`, accepts negatives, and coerces other types — `true` yields a
-	 * whole unit. Every one of these is reachable with values a wallet can hold,
-	 * and none announces itself. Hence: convert by text, validate, and fail closed
-	 * rather than delegate.
+	 * neurai-create-transaction also converts through exact decimal parsing.
+	 * This adapter retains the assets API policies: plain decimal strings,
+	 * divisibility checks, monetary limits and asset-specific validation errors.
 	 */
 
 	var assetAmount;
@@ -4991,18 +4980,10 @@ var NeuraiAssetsBundle = (function (exports) {
 		}
 
 		/**
-		 * Render a protocol integer as a JS number for the legacy display envelopes.
-		 *
-		 * Fails closed rather than returning a value the caller cannot trust: a
-		 * quantity whose display form is not exactly representable would otherwise
-		 * travel on as a plausible-looking wrong number.
-		 *
-		 * @param {bigint} raw - Protocol integer (10^8-scaled)
-		 * @param {string} [label] - Prefix for error messages
-		 * @returns {number} Display amount
-		 * @throws {InvalidAmountError} If the display value is not exactly representable
+		 * Render a protocol integer as a compatible display amount.
+		 * @param {bigint|string|number} raw - Exact protocol integer
+		 * @returns {number|string} Number only when a decimal round-trip retains every unit
 		 */
-		/** Compatibility display: numbers where monetary precision is safe, text otherwise. */
 		function rawToDisplayAmount(raw) {
 		  const value = toProtocolInteger(raw);
 		  const abs = value < 0n ? -value : value;
@@ -5015,6 +4996,11 @@ var NeuraiAssetsBundle = (function (exports) {
 		  return formatRawAsDecimal(value);
 		}
 
+		/**
+		 * @param {bigint} raw - Protocol integer
+		 * @param {string} [label] - Error context
+		 * @returns {number} Display number, or throws if the decimal round-trip loses units
+		 */
 		function rawToDisplayNumber(raw, label = 'amount') {
 		  const text = formatRawAsDecimal(raw);
 		  const asNumber = Number(text);
@@ -5116,6 +5102,9 @@ var NeuraiAssetsBundle = (function (exports) {
 		hasRequiredAmountConverter = 1;
 		const { assetAmountToRaw } = requireAssetAmount();
 		/**
+		 * @deprecated Use utils.AssetAmount for exact protocol amounts.
+		 * Legacy scaling is 10^units, not the protocol scale of 10^8.
+		 * These methods may round; retained only for backward compatibility.
 		 * Amount Converter
 		 * Converts between user amounts and satoshis (protocol internal format)
 		 */
@@ -6564,8 +6553,8 @@ var NeuraiAssetsBundle = (function (exports) {
 		      throw new InsufficientFundsError(
 		        `Insufficient XNA balance. Required: ${required} XNA (+ ${(buffer * 100).toFixed(0)}% buffer), ` +
 		        `Available: ${available} XNA`,
-		        Number(required),
-		        Number(available)
+		        rawToDisplayAmount(requiredSats),
+		        rawToDisplayAmount(totalSatoshis)
 		      );
 		    }
 
@@ -6633,8 +6622,8 @@ var NeuraiAssetsBundle = (function (exports) {
 		      const required = formatRawAsDecimal(requiredRaw);
 		      throw new InsufficientFundsError(
 		        `Insufficient ${assetName} balance. Required: ${required}, Available: ${available}`,
-		        Number(required),
-		        Number(available)
+		        rawToDisplayAmount(requiredRaw),
+		        rawToDisplayAmount(totalSatoshis)
 		      );
 		    }
 
@@ -8906,7 +8895,7 @@ var NeuraiAssetsBundle = (function (exports) {
 		   * Extract XNA change metadata from outputs
 		   * @param {Array<{address: string, value: unknown}>} entries - Output entries
 		   * @param {string|null} burnAddress - Burn address if present
-		   * @returns {{ changeAddress: string|null, changeAmount: number|null }}
+		   * @returns {{ changeAddress: string|null, changeAmount: number|string|null }}
 		   */
 		  extractChangeMetadata(entries, burnAddress = null) {
 		    const xnaOutputs = entries.filter(({ address, value }) => {