@neuraiproject/neurai-assets 1.3.1 → 1.3.3

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
@@ -151,6 +183,28 @@ const result = await assets.createDepinAsset({
 > **Note**: DEPIN assets always use `units = 0`. Recipient and change destinations
 > can be either legacy or AuthScript, as long as they belong to the same chain family.
 
+### Transfer Asset
+
+```javascript
+// Works for any asset type (regular, sub, restricted, DePIN).
+const result = await assets.transferAsset({
+  assetName: 'MYTOKEN',
+  recipients: [
+    { address: 'nM...', amount: 5 },   // amount in display units
+    { address: 'nQ...', amount: 2.5 }
+  ]
+  // changeAddress is optional; defaults to the configured change address.
+  // Asset change and the network fee are handled automatically.
+});
+```
+
+> **DePIN (`&`) note**: DePIN assets are soulbound — the transfer is only valid
+> if it is authorized by the owner. `transferAsset` handles this automatically:
+> it spends the asset's owner token (`&NAME!`) and returns it to the change
+> address, so authority stays with the sender. You must hold the owner token, or
+> the call throws `OwnerTokenNotFoundError`. Transferring ownership itself (handing
+> the owner token to the recipient) is not done here.
+
 ### Create UNIQUE Assets (NFTs)
 
 ```javascript
@@ -465,7 +519,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 +530,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 +539,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

package/dist/NeuraiAssets.global.js

@@ -4606,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;
@@ -5746,6 +5769,274 @@ var NeuraiAssetsBundle = (function (exports) {
 		return ReissueBuilder_1;
 	}
 
+	/**
+	 * Transfer Builder
+	 * Builds transactions that transfer an existing asset to one or more recipients.
+	 *
+	 * Works for any asset type (regular, sub, restricted, DePIN). The only
+	 * type-specific rule lives in Neurai consensus for DePIN (`&`) assets, which are
+	 * soulbound: a DePIN transfer is only valid if the same transaction
+	 *   1. SPENDS the asset's owner token `&NAME!` as an input, and
+	 *   2. re-creates (transfers) that owner token in an output.
+	 * See Neurai-DePIN/src/consensus/tx_verify.cpp (bad-txns-depin-transfer-not-by-owner).
+	 * For non-DePIN assets no owner token is required for a plain transfer.
+	 *
+	 * Owner-token destination: the owner token is returned to the sender's change
+	 * address — the asset moves to the recipient but authority stays with the owner
+	 * (soulbound semantics). Transferring ownership itself is out of scope here.
+	 *
+	 * This builder mirrors ReissueBuilder (which also spends + returns an owner
+	 * token) but, since a transfer has no reissue entry, it adds the owner-token
+	 * return output explicitly via OwnerTokenManager.
+	 */
+
+	var TransferBuilder_1;
+	var hasRequiredTransferBuilder;
+
+	function requireTransferBuilder () {
+		if (hasRequiredTransferBuilder) return TransferBuilder_1;
+		hasRequiredTransferBuilder = 1;
+		const BaseAssetTransactionBuilder = requireBaseAssetTransactionBuilder();
+		const { OutputFormatter, AssetNameParser } = requireUtils();
+		const { OwnerTokenNotFoundError } = requireErrors();
+
+		class TransferBuilder extends BaseAssetTransactionBuilder {
+		  /**
+		   * Validate transfer parameters
+		   * @param {object} params - Transfer parameters
+		   * @throws {Error} If validation fails
+		   */
+		  validateParams(params) {
+		    if (!params.assetName) {
+		      throw new Error('assetName is required');
+		    }
+
+		    if (!Array.isArray(params.recipients) || params.recipients.length === 0) {
+		      throw new Error('recipients is required (non-empty array of { address, amount })');
+		    }
+
+		    params.recipients.forEach((recipient, index) => {
+		      if (!recipient || !recipient.address) {
+		        throw new Error(`recipients[${index}].address is required`);
+		      }
+		      if (recipient.amount === undefined || recipient.amount === null) {
+		        throw new Error(`recipients[${index}].amount is required`);
+		      }
+		      if (recipient.amount <= 0) {
+		        throw new Error(`recipients[${index}].amount must be greater than 0`);
+		      }
+		    });
+
+		    return true;
+		  }
+
+		  /**
+		   * Build transfer transaction
+		   * @returns {Promise<object>} Transaction result
+		   */
+		  async build() {
+		    // 1. Validate parameters
+		    this.validateParams(this.params);
+
+		    const { assetName, recipients } = this.params;
+
+		    // Total amount to send, in user-facing asset units (NOT raw 10^8 sats).
+		    // selectAssetUTXOs / the createrawtransaction transfer output both expect
+		    // display units and scale by 10^8 themselves — pre-multiplying would
+		    // double-scale (see UTXOSelector.selectAssetUTXOs / BaseBuilder.toSatoshis).
+		    const totalAssetUnits = recipients.reduce((sum, r) => sum + r.amount, 0);
+
+		    // 2. Addresses
+		    const addresses = await this._getAddresses();
+		    const changeAddress = await this.getChangeAddress();
+
+		    // 3. DePIN detection + owner token lookup (soulbound rule)
+		    const isDepin = AssetNameParser.isDepin(assetName);
+		    let ownerTokenName = null;
+		    let ownerTokenUTXO = null;
+		    if (isDepin) {
+		      ownerTokenName = AssetNameParser.getOwnerTokenName(assetName); // &NAME -> &NAME!
+		      try {
+		        ownerTokenUTXO = await this.ownerTokenManager.findOwnerTokenUTXO(
+		          ownerTokenName,
+		          addresses
+		        );
+		      } catch (error) {
+		        if (error instanceof OwnerTokenNotFoundError) {
+		          throw new OwnerTokenNotFoundError(
+		            `You must own the asset's owner token (${ownerTokenName}) to transfer ` +
+		            `this DePIN asset. DePIN assets are soulbound: the transfer must be ` +
+		            `authorized by the owner.`,
+		            ownerTokenName
+		          );
+		        }
+		        throw error;
+		      }
+		    }
+
+		    // 4. Output addresses used only for the fee (vsize) estimate. Include every
+		    //    potential output so the fee is never under-estimated.
+		    const outputAddresses = [
+		      changeAddress, // XNA change
+		      ...recipients.map(r => r.address), // one transfer per recipient
+		      changeAddress, // asset change (harmless over-count if absent)
+		      ...(isDepin ? [changeAddress] : []), // owner token return
+		    ];
+
+		    // 5. First (rough) fee estimate, then select asset + XNA UTXOs.
+		    const estimatedFee = await this.estimateFee(isDepin ? 3 : 2, outputAddresses);
+		    const utxoSelection = await this.selectUTXOs(estimatedFee, assetName, totalAssetUnits);
+		    const assetUTXOs = utxoSelection.assetUTXOs;
+		    const baseCurrencyUTXOs = utxoSelection.xnaUTXOs;
+		    let totalXNAInput = utxoSelection.totalXNA;
+
+		    // Asset change computed in raw 10^8-sats to avoid float drift, then back to units.
+		    const assetInputRawSats = assetUTXOs.reduce((sum, u) => sum + u.satoshis, 0);
+		    const totalAssetRawSats = Math.round(totalAssetUnits * 100000000);
+		    const assetChangeRawSats = assetInputRawSats - totalAssetRawSats;
+		    const assetChangeUnits = assetChangeRawSats / 100000000;
+
+		    // 6. Recompute the fee with the real inputs (PQ-aware), including the owner
+		    //    token when DePIN, then top up XNA if the rough estimate fell short.
+		    const actualFeeInputs = [
+		      ...baseCurrencyUTXOs,
+		      ...assetUTXOs,
+		      ...(isDepin ? [ownerTokenUTXO] : []),
+		    ];
+		    const actualFee = await this.estimateFee(actualFeeInputs, outputAddresses);
+
+		    if (totalXNAInput < actualFee) {
+		      const additionalNeeded = actualFee - totalXNAInput + 0.001;
+		      const additionalSelection = await this.selectUTXOs(additionalNeeded, null, 0);
+		      baseCurrencyUTXOs.push(...additionalSelection.xnaUTXOs);
+		      totalXNAInput += additionalSelection.totalXNA;
+		    }
+
+		    // 7. XNA change (no burn for a transfer)
+		    const finalXNAInput = baseCurrencyUTXOs.reduce(
+		      (sum, utxo) => sum + utxo.satoshis / 100000000,
+		      0
+		    );
+		    const xnaChange = finalXNAInput - actualFee;
+
+		    // 8. Build inputs: asset UTXOs + [owner token] + XNA UTXOs
+		    const inputs = [];
+
+		    assetUTXOs.forEach(utxo => {
+		      inputs.push({
+		        txid: utxo.txid,
+		        vout: utxo.outputIndex,
+		        address: utxo.address,
+		        assetName: utxo.assetName,
+		        satoshis: utxo.satoshis,
+		      });
+		    });
+
+		    if (isDepin) {
+		      inputs.push({
+		        txid: ownerTokenUTXO.txid,
+		        vout: ownerTokenUTXO.outputIndex,
+		        address: ownerTokenUTXO.address,
+		        assetName: ownerTokenUTXO.assetName,
+		        satoshis: ownerTokenUTXO.satoshis,
+		      });
+		    }
+
+		    baseCurrencyUTXOs.forEach(utxo => {
+		      inputs.push({
+		        txid: utxo.txid,
+		        vout: utxo.outputIndex,
+		        address: utxo.address,
+		        satoshis: utxo.satoshis,
+		      });
+		    });
+
+		    // 9. Build outputs (unordered — outputOrderer enforces protocol order)
+		    const outputs = [];
+
+		    // XNA change
+		    if (xnaChange > 0.00000001) {
+		      outputs.push({ [changeAddress]: parseFloat(xnaChange.toFixed(8)) });
+		    }
+
+		    // One transfer per recipient (display units; the daemon scales by 10^8)
+		    recipients.forEach(r => {
+		      outputs.push({ [r.address]: OutputFormatter.formatTransferOutput(assetName, r.amount) });
+		    });
+
+		    // Asset change back to the sender
+		    if (assetChangeRawSats > 0) {
+		      outputs.push({
+		        [changeAddress]: OutputFormatter.formatTransferOutput(assetName, assetChangeUnits),
+		      });
+		    }
+
+		    // DePIN: return the owner token (required so the tx contains a transfer of
+		    // &NAME! — satisfies the consensus `transfersOwnerToken` check).
+		    if (isDepin) {
+		      outputs.push(
+		        this.ownerTokenManager.createOwnerTokenReturnOutput(ownerTokenName, changeAddress)
+		      );
+		    }
+
+		    // 10. Order outputs (protocol requirement)
+		    const orderedOutputs = this.outputOrderer.order(outputs);
+
+		    // 11. Create raw transaction
+		    const rawTx = await this.buildRawTransaction(inputs, orderedOutputs);
+
+		    // 12. Format and return result
+		    const allUTXOs = [
+		      ...assetUTXOs,
+		      ...(isDepin ? [ownerTokenUTXO] : []),
+		      ...baseCurrencyUTXOs,
+		    ];
+		    const xnaChangeOut = xnaChange > 0.00000001 ? parseFloat(xnaChange.toFixed(8)) : null;
+
+		    return this.formatResult(
+		      rawTx,
+		      allUTXOs,
+		      inputs,
+		      orderedOutputs,
+		      actualFee,
+		      0, // burnAmount — transfers don't burn
+		      {
+		        assetName,
+		        recipients: recipients.map(r => ({ address: r.address, amount: r.amount })),
+		        assetChange: assetChangeRawSats > 0 ? assetChangeUnits : 0,
+		        isDepin,
+		        ownerTokenUsed: isDepin ? ownerTokenName : null,
+		        operationType: 'TRANSFER',
+		        localRawBuild: this.buildLocalRawBuild(
+		          'TRANSFER',
+		          inputs,
+		          null, // no burn
+		          changeAddress,
+		          xnaChangeOut,
+		          {
+		            assetName,
+		            transfers: recipients.map(r => ({
+		              address: r.address,
+		              assetName,
+		              amount: r.amount,
+		            })),
+		            assetChange: assetChangeRawSats > 0
+		              ? { address: changeAddress, assetName, amount: assetChangeUnits }
+		              : null,
+		            ownerReturn: isDepin
+		              ? { address: changeAddress, assetName: ownerTokenName, amount: 1 }
+		              : null,
+		          }
+		        ),
+		      }
+		    );
+		  }
+		}
+
+		TransferBuilder_1 = TransferBuilder;
+		return TransferBuilder_1;
+	}
+
 	/**
 	 * Issue Unique Builder
 	 * Builds transactions for creating UNIQUE assets (NFTs)
@@ -7382,6 +7673,7 @@ var NeuraiAssetsBundle = (function (exports) {
 		const IssueSubBuilder = requireIssueSubBuilder();
 		const IssueDepinBuilder = requireIssueDepinBuilder();
 		const ReissueBuilder = requireReissueBuilder();
+		const TransferBuilder = requireTransferBuilder();
 
 		// Advanced Builders
 		const IssueUniqueBuilder = requireIssueUniqueBuilder();
@@ -7400,6 +7692,7 @@ var NeuraiAssetsBundle = (function (exports) {
 		  IssueSubBuilder,
 		  IssueDepinBuilder,
 		  ReissueBuilder,
+		  TransferBuilder,
 
 		  // Advanced Builders
 		  IssueUniqueBuilder,
@@ -7452,7 +7745,8 @@ var NeuraiAssetsBundle = (function (exports) {
 		  ReissueBuilder,
 		  ReissueRestrictedBuilder,
 		  TagAddressBuilder,
-		  FreezeAddressBuilder
+		  FreezeAddressBuilder,
+		  TransferBuilder
 		} = requireBuilders();
 
 		class NeuraiAssets {
@@ -7569,6 +7863,32 @@ var NeuraiAssetsBundle = (function (exports) {
 		    return await builder.build();
 		  }
 
+		  // ========================================
+		  // TRANSFER OPERATIONS
+		  // ========================================
+
+		  /**
+		   * Transfer an existing asset to one or more recipients.
+		   *
+		   * Works for any asset type. DePIN (`&`) assets are soulbound: this method
+		   * automatically spends and returns the asset's owner token (`&NAME!`) so the
+		   * transfer satisfies Neurai consensus (bad-txns-depin-transfer-not-by-owner).
+		   * The owner token is returned to the change address (authority stays with the
+		   * sender). For non-DePIN assets no owner token is involved.
+		   *
+		   * @param {object} params - Transfer parameters
+		   * @param {string} params.assetName - Asset to transfer (e.g. 'TOKEN', '$SEC', '&DEVICE')
+		   * @param {Array<object>} params.recipients - Recipients
+		   * @param {string} params.recipients[].address - Destination address
+		   * @param {number} params.recipients[].amount - Amount in asset display units (> 0)
+		   * @param {string} [params.changeAddress] - Override change/owner-return address
+		   * @returns {Promise<object>} Transaction data
+		   */
+		  async transferAsset(params) {
+		    const builder = new TransferBuilder(this.rpc, this._buildParams(params));
+		    return await builder.build();
+		  }
+
 		  // ========================================
 		  // UNIQUE ASSET (NFT) OPERATIONS
 		  // ========================================