@neuraiproject/neurai-sign-esp32 0.6.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -773,3 +773,54 @@ Opera 75+. Firefox and Safari are not supported.
773
773
  For non-browser platforms (React Native / Android USB, Node test doubles, …)
774
774
  inject a custom transport instead — see
775
775
  [React Native / Android USB](#react-native--android-usb).
776
+
777
+
778
+ ## Exact amounts (0.6.1)
779
+
780
+ `IUTXO.satoshis`, `IPQUTXO.satoshis`, output `value`, PQ `amount` and
781
+ `sighashAmount` accept `bigint`, integer strings, or safe integer numbers. These
782
+ are **raw protocol units**, not decimal XNA or asset units. Values must be
783
+ non-negative and no greater than `2100000000000000000n`. Already unsafe numbers
784
+ are rejected; converting a rounded number to bigint cannot restore its digits.
785
+
786
+ ```ts
787
+ const output = { address: destination, value: 10000000000000001n };
788
+ // The same exact amount can be passed as value: '10000000000000001'.
789
+ ```
790
+
791
+ Both high-level builders sum funds, calculate change and subtract fees in bigint.
792
+ `feeRate` accepts a number or decimal string in satoshis per byte. Fractional
793
+ rates are multiplied exactly and rounded upward to a whole satoshi once.
794
+
795
+ Asset transactions prepared externally should use `buildPSBTFromRawTransaction`
796
+ (legacy) or `signPqRawTransaction` (PQ). Their asset payload quantities remain
797
+ encoded in the transaction bytes at scale 10^8, independent of asset divisibility.
798
+ The high-level address/value output builders construct XNA payment outputs;
799
+ they do not create asset transfer payloads. For asset-wrapped PQ inputs, pass
800
+ `amount: 0` to the raw signing API, or `sighashAmount: 0` when using the builder.
801
+ An asset quantity must never count toward XNA funding: an explicit zero prevout
802
+ value contributes zero to fees and payment funding, so separate XNA inputs are
803
+ required.
804
+
805
+ Display metadata uses decimal **strings** for large asset quantities and fees:
806
+
807
+ ```ts
808
+ const display = buildAssetTransferDisplayMetadata({
809
+ assetName: 'LARGE',
810
+ assetAmount: '100000000.00000001',
811
+ destinationAddress: destination,
812
+ feeAmount: '0.00000249',
813
+ });
814
+ ```
815
+
816
+ Plain strings retain their formatting. Invalid amounts, excess decimals and
817
+ unsafe large fractional numbers are rejected instead of silently rounded.
818
+ Direct signing calls validate display amounts too.
819
+
820
+ Before handing `sign_tx` to a transport, the library encodes safe raw amounts as
821
+ JSON numbers and larger ones as integer strings. Custom transports must preserve
822
+ those strings. The reviewed firmware reads `amount` using ArduinoJson
823
+ `as<unsigned long long>()`, which supports exact integer strings. Its local
824
+ ArduinoJson parser was checked on the host up to MAX_MONEY; this does not replace
825
+ an on-device signing and display check of the firmware installed on your ESP32.
826
+ No global bigint JSON serializer is required.