@neuraiproject/neurai-assets 1.6.0 → 1.6.2

package/README.md

@@ -1089,3 +1089,45 @@ The estimator assumes the most common spend layout for every input:
 - PQ inputs → AuthScript v1 with the **default** `OP_TRUE` `witnessScript` and **no** `functionalArgs`
 
 That covers all standard asset operations. If you build transactions whose PQ inputs use covenant `witnessScript`s, NoAuth (`authType=0x00`) or Legacy AuthScript (`authType=0x02`) witnesses, compute the witness size yourself and add it to the result of `estimateTransactionVbytes` (or use `estimateVirtualSize` from `@neuraiproject/neurai-sign-transaction` after building the raw transaction, which fills dummy witnesses of the worst-case size and returns the exact post-signing vsize).
+
+### Large amounts and exact result envelopes
+
+Pass large fractional quantities as decimal strings and RPC raw `satoshis` as
+bigint or integer strings. Build envelopes retain numeric display fields for
+safe monetary values; large fractional values are returned as decimal strings
+instead of rounding or preventing a valid build. Consumers must accept both.
+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.