@neuraiproject/neurai-assets 1.3.0 → 1.3.2

package/README.md

@@ -24,6 +24,31 @@ Complete asset management library for Neurai blockchain. Supports creation, reis
 | **RESTRICTED** | `$SECURITY` | 3000 XNA | Security token with compliance |
 | **DEPIN** | `&DEVICE` or `&DEVICE/ROUTER001` | 10 XNA | Soulbound asset with holder validity controls |
 
+## Quantities and asset units
+
+Every `quantity` / `asset_quantity` parameter accepted by this library is a
+**user-facing display amount** — the same number a human would write to mean
+"this many tokens". For an asset with `units = 2`, `quantity: 10.50` means
+ten and a half tokens; for an asset with `units = 0`, `quantity: 1` means
+one whole token.
+
+Internally the daemon parses the JSON `asset_quantity` field with
+`AmountFromValue` ([Bitcoin-style decimal → 10⁸ sats][amount-from-value])
+and validates that the resulting CAmount is a multiple of `10^(8 − units)`
+via `CheckAmountWithUnits`. Because the chain already does the ×10⁸ scaling
+itself, **the library must NOT pre-multiply** the value. Sending the raw
+display number is the only correct behavior; any extra factor on the wire
+either silently inflates the minted supply (`× 10⁸ → 100,000,000` tokens
+where the user asked for 1) or trips the daemon's
+`ParseFixedPoint` cap with `Invalid amount (3): …`.
+
+This was regressed in `1.2.2`/`1.3.x` (a hardcoded `× 10⁸` was added to
+`BaseAssetTransactionBuilder.toSatoshis`) and fixed in the version after
+`1.3.1`. If you write a custom builder, follow the same convention: pass
+the user amount through unchanged, let the daemon scale.
+
+[amount-from-value]: https://github.com/NeuraiProject/Neurai-DePIN/blob/main/src/rpc/server.cpp
+
 ## Installation
 
 ```bash
@@ -105,8 +130,9 @@ const assetsPQ = new NeuraiAssets(rpc, {
 ```javascript
 const result = await assets.createRootAsset({
   assetName: 'MYTOKEN',
-  quantity: 1000000,      // Total supply
-  units: 2,                // Decimals (0-8)
+  quantity: 1000000,      // Total supply, in display units (1,000,000 tokens)
+  units: 2,                // Decimal precision (0–8). With units=2, fractional
+                           // values down to 0.01 are allowed.
   reissuable: true,        // Allow reissuance
   hasIpfs: true,
   ipfsHash: 'QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG'
@@ -131,12 +157,18 @@ const result = await assets.createSubAsset({
 // Requires the asset's owner token (MYTOKEN!)
 const result = await assets.reissueAsset({
   assetName: 'MYTOKEN',
-  quantity: 500000,        // Additional amount to mint
+  quantity: 500000,        // Additional amount to mint, in display units.
+                           // For an asset with units=0, `quantity: 1`
+                           // mints exactly 1 token (NOT 100,000,000).
   reissuable: true,        // false = lock supply permanently
-  newIpfs: 'Qm...'        // Update IPFS (optional)
+  newIpfs: 'Qm...'         // Update IPFS (optional)
 });
 ```
 
+> **Note**: `units` cannot be passed to `reissueAsset` — the chain inherits
+> the asset's existing precision (use `new_units` in the raw output if you
+> ever need to change it, but this library doesn't expose that today).
+
 ### Create DEPIN Asset
 
 ```javascript
@@ -465,7 +497,7 @@ The library automatically validates that the owner token is returned in each ope
 | Reissue ROOT/SUB | 200 |
 | Reissue DEPIN | 200 |
 | Reissue RESTRICTED | 200 |
-| Tag/Untag address | 0.1 (per address) |
+| Tag/Untag address | 0 (network fee only; spends 1 unit of the qualifier per address) |
 | Freeze/Unfreeze address | 0 (network fee only) |
 | Freeze/Unfreeze global | 0 (network fee only) |
 
@@ -476,7 +508,7 @@ The library automatically validates that the owner token is returned in each ope
 The library validates client-side:
 
 ✅ Asset names (format, length, allowed characters)
-✅ Amounts (not exceeding max supply of 21 billion)
+✅ Amounts (not exceeding max supply of 21 billion display tokens)
 ✅ Decimals (0-8)
 ✅ IPFS hashes (valid format)
 ✅ Verifier strings (boolean logic syntax)
@@ -485,6 +517,11 @@ The library validates client-side:
 ✅ Owner tokens returned (prevents loss)
 ✅ Address prefixes by network
 
+The daemon also enforces server-side that quantities respect the asset's
+precision (`CheckAmountWithUnits` — see [Quantities and asset units](#quantities-and-asset-units)),
+so e.g. trying to issue `0.1` of a `units=0` asset is rejected with
+`min-qty-not-multiple-of-units` regardless of what the client sent.
+
 ## Network Configuration
 
 ```javascript
@@ -656,6 +693,8 @@ are `xna` and `xna-test`; `xna-pq` and `xna-pq-test` remain available as compati
 
 Asset transactions are usually built with one or two XNA inputs plus, depending on the operation, an owner-token or qualifier UTXO. The library estimates the fee twice per build: a rough pre-estimate to size the initial XNA selection, and a final estimate once the actual UTXOs are known.
 
+Both estimates share a single `estimatesmartfee` lookup. The fee rate is stable for the lifetime of one build, so it is fetched on the first `estimateFee` call and cached on the builder instance for the second — half as many RPC round trips as before `1.3.1`.
+
 Both estimates use the helpers in [`src/utils/feeSizing.js`](src/utils/feeSizing.js) and distinguish PQ AuthScript inputs/outputs from legacy P2PKH ones. PQ inputs spend ~977 vbytes vs ~148 for legacy — without this distinction, transactions built from PQ addresses fall under the node's `min relay fee` and are rejected with `code -26: min relay fee not met`.
 
 You should not need to call these helpers directly; they are wired into every builder. They are documented here so you can audit the fee math or use the same constants if you compose transactions outside the standard builder flow.

package/dist/NeuraiAssets.global.js

@@ -4418,6 +4418,11 @@ var NeuraiAssetsBundle = (function (exports) {
 		    this.ownerTokenManager = new OwnerTokenManager(rpc);
 		    this.utxoSelector = new UTXOSelector(rpc);
 		    this.outputOrderer = new OutputOrderer();
+
+		    // `estimatesmartfee` is called twice per build (pre-selection guess and
+		    // post-selection recompute). The fee rate is stable for the duration of
+		    // a single build, so cache the first lookup and reuse it.
+		    this._feeRatePromise = null;
 		  }
 
 		  /**
@@ -4464,7 +4469,10 @@ var NeuraiAssetsBundle = (function (exports) {
 		   * @returns {Promise<number>} Estimated fee in XNA
 		   */
 		  async estimateFee(inputs, outputs) {
-		    const feeRate = await this.utxoSelector.getFeeRate();
+		    if (!this._feeRatePromise) {
+		      this._feeRatePromise = this.utxoSelector.getFeeRate();
+		    }
+		    const feeRate = await this._feeRatePromise;
 		    return this.utxoSelector.estimateFee(inputs, outputs, feeRate);
 		  }
 
@@ -4598,24 +4606,47 @@ var NeuraiAssetsBundle = (function (exports) {
 		  }
 
 		  /**
-		   * Convert asset amount to protocol raw units.
-		   * Asset raw quantities in transaction payloads are always encoded with
-		   * 8 decimal places, regardless of the asset's displayed `units`.
+		   * Build the JSON `asset_quantity` value for a `createrawtransaction`
+		   * output (issue / reissue / tag change_quantity / etc.).
+		   *
+		   * The chain parses this field with `AmountFromValue()` (Bitcoin-style
+		   * decimal-XNA → 10^8 sats), then validates that the resulting CAmount
+		   * is a multiple of `10^(8 - units)` via `CheckAmountWithUnits`
+		   * (assets.cpp). So:
+		   *
+		   *   - The JSON value MUST be the user-facing display amount
+		   *     (e.g. "1" for one token, "1.5" for one and a half tokens).
+		   *   - The lib must NOT pre-multiply by 10^8 or 10^units; the daemon
+		   *     does the 10^8 scaling itself, and any extra factor here lands
+		   *     duplicated and inflates the minted supply (or trips the
+		   *     ParseFixedPoint `exponent >= 18` cap → "Invalid amount (3)").
+		   *
+		   * History: pre-1.2.2 multiplied by 10^units (correct only for units=0
+		   * assets, inflated everything else by 10^units). v1.2.2 changed to
+		   * always 10^8 (correct only for units=8, inflated everything else by
+		   * 10^8 — e.g. reissuing 1 token of a units=0 asset minted 100,000,000).
+		   * The right answer is to send the value untouched.
+		   *
+		   * The `units` parameter is kept for API compatibility but is unused.
 		   *
 		   * @param {number} amount - User-facing asset amount
-		   * @param {number} units - Asset decimal places (kept for API compatibility)
-		   * @returns {number} Amount in protocol raw units
+		   * @param {number} units - Asset decimal places (unused; kept for API)
+		   * @returns {number} The user-facing amount, ready for the JSON output
 		   */
 		  toSatoshis(amount, units) {
-		    return Math.round(amount * 100000000);
+		    return amount;
 		  }
 
 		  /**
-		   * Convert protocol raw units back to a user-facing asset amount.
+		   * Convert a chain-side asset balance / UTXO satoshis value back to a
+		   * user-facing amount. The chain consistently encodes asset balances
+		   * in 10^8 sats (because everything goes through AmountFromValue on
+		   * the way in), so the divisor is always 10^8 — independent of the
+		   * asset's `units`.
 		   *
-		   * @param {number} satoshis - Amount in protocol raw units
-		   * @param {number} units - Asset decimal places (kept for API compatibility)
-		   * @returns {number} Amount in asset units
+		   * @param {number} satoshis - Chain value in 10^8 sats
+		   * @param {number} units - Asset decimal places (unused; kept for API)
+		   * @returns {number} User-facing asset amount
 		   */
 		  fromSatoshis(satoshis, units) {
 		    return satoshis / 100000000;