feat: 1291 Clause class in action

apps/sdk-nextjs-integration/src/app/transfer-logs/page.tsx

@@ -4,7 +4,7 @@ import { Header } from '@/components';
 import { explorerUrl, thorClient } from '@/const';
 import { type Transfer } from '@/types';
 import { reduceHexStringSize } from '@/utils';
-import { addressUtils, FPN, Units } from '@vechain/sdk-core';
+import { addressUtils, FixedPointNumber, Units } from '@vechain/sdk-core';
 import {
     type CompressedBlockDetail,
     type FilterTransferLogsOptions
@@ -145,7 +145,7 @@ export default function TransferLogs(): JSX.Element {
                                         data-testid={`transfer-amount-${transfer.amount}`}
                                     >
                                         {Units.formatEther(
-                                            FPN.of(transfer.amount)
+                                            FixedPointNumber.of(transfer.amount)
                                         )}
                                     </p>
                                 </td>

docs/diagrams/architecture/core-package.md

@@ -36,7 +36,7 @@ C4Context
                     System(VET, "VET class", "Represent VET monetary amounts.")
                     System(VTHO, "VTHO class", "Represent VTHO monetary amounts.")
                 }
-                System(FPN, "FPN class", "Handle all Fixed Point Number math.")
+                System(FixedPointNumber, "FixedPointNumber class", "Handle all Fixed Point Number math.")
                 Boundary(hash, "Hash module") {
                     System(Blake2b256, "Blake2b256 class")
                     System(Keccak, "Blake2b256 class")

docs/diagrams/architecture/transaction.md

@@ -1,7 +1,7 @@
 ```mermaid
 classDiagram
     class Clause {
-        +FPN amount()
+        +FixedPointNumber amount()
         +Clause callFunction(Address contractAddress, ABIFunction, functionABI, unknown[] args, VET amount, ClauseOptions: clauseOptions)
         +Clause deployContract(HexUInt contractBytecode, DeployParams deployParams?, ClauseOptions clauseOptions?)
         +Clause transferNFT(Address contractAddress, Address senderAddress, Address recipientAddress, HexUInt tokenId, ClauseOptions clauseOptions?)

docs/diagrams/architecture/vcdm.md

@@ -63,22 +63,22 @@ classDiagram
     class Contract
     class Currency {
         +Txt code
-        +FPN value
+        +FixedPointNumber value
     }
-    class FPN {
+    class FixedPointNumber {
         +bigint sv
-        +FPN NaN$
-        +FPN NEGATIVE_INFINITY$
-        +FPN POSITIVE_INFINITY$
-        +FPN ZERO$
-        +FPN abs()
-        +null|number comparedTo(FPN that)
-        +FPN div(FPN that)
-        +FPN dp(bigint|number decimalPlaces)
-        +boolean eq(FPN that)
-        +boolean gt(FPN that)
-        +boolean gte(FPN that)
-        +FPN idiv(FPN that)
+        +FixedPointNumber NaN$
+        +FixedPointNumber NEGATIVE_INFINITY$
+        +FixedPointNumber POSITIVE_INFINITY$
+        +FixedPointNumber ZERO$
+        +FixedPointNumber abs()
+        +null|number comparedTo(FixedPointNumber that)
+        +FixedPointNumber div(FixedPointNumber that)
+        +FixedPointNumber dp(bigint|number decimalPlaces)
+        +boolean eq(FixedPointNumber that)
+        +boolean gt(FixedPointNumber that)
+        +boolean gte(FixedPointNumber that)
+        +FixedPointNumber idiv(FixedPointNumber that)
         +boolean isFinite()
         +boolean isInfinite()
         +boolean isInteger()
@@ -91,16 +91,16 @@ classDiagram
         +boolean isPositive()
         +boolean isPositiveInfinite()
         +boolean isZero()
-        +boolean lt(FPN that)
-        +boolean lte(FPN that)
-        +FPN minus(FPN that)
-        +FPN modulo(FPN that)
-        +FPN negated()
-        +FPN of(bigint|number|string exp)$
-        +FPN plus(FPN that)
-        +FPN pow(FPN that)
-        +FPN sqrt()
-        +FPN times(FPN that)
+        +boolean lt(FixedPointNumber that)
+        +boolean lte(FixedPointNumber that)
+        +FixedPointNumber minus(FixedPointNumber that)
+        +FixedPointNumber modulo(FixedPointNumber that)
+        +FixedPointNumber negated()
+        +FixedPointNumber of(bigint|number|string exp)$
+        +FixedPointNumber plus(FixedPointNumber that)
+        +FixedPointNumber pow(FixedPointNumber that)
+        +FixedPointNumber sqrt()
+        +FixedPointNumber times(FixedPointNumber that)
     }
     class Hex {
         +Hex abs
@@ -151,10 +151,10 @@ classDiagram
         +12 szabo$
         +15 finney$
         +18 ether$
-        +string formatEther(FPN wei)$
-        +string formatUnit(FPN wei, Units unit)$
-        +FPN parseEther(string: ether)$
-        +FPN parseUnit(string exp, Unit unit)$
+        +string formatEther(FixedPointNumber wei)$
+        +string formatUnit(FixedPointNumber wei, Units unit)$
+        +FixedPointNumber parseEther(string: ether)$
+        +FixedPointNumber parseUnit(string exp, Unit unit)$
     }
     class VeChainDataModel {
         <<interface>>
@@ -168,13 +168,13 @@ classDiagram
     class VET {
         +Txt CODE$
         +bigint wei
-        +VET of(bigint|number|string|FPN value)$
+        +VET of(bigint|number|string|FixedPointNumber value)$
         +Clause transferTo(Address: address, ClauseOptions?: clauseOptionsre)
     }
     class VTHO {
         +Txt CODE$
         +bigint wei
-        +VTHO of(bigint|number|string|FPN value)$
+        +VTHO of(bigint|number|string|FixedPointNumber value)$
         +Clause transferTokenTo(Address address, Address to, ClauseOptions? clauseOptions)
     }
     ABI <|-- ABIContract
@@ -187,8 +187,8 @@ classDiagram
     Coin <|-- VET
     Coin <|-- VTHO
     Currency <|.. Coin
-    FPN <|-- VET
-    FPN <|-- VTHO
+    FixedPointNumber <|-- VET
+    FixedPointNumber <|-- VTHO
     Hex <|-- HexInt
     HexInt <|-- HexUInt
     HexUInt <|-- Address
@@ -203,7 +203,7 @@ classDiagram
     VeChainDataModel <|.. ABI
     VeChainDataModel <|.. BloomFilter
     VeChainDataModel <|.. Currency
-    VeChainDataModel <|.. FPN
+    VeChainDataModel <|.. FixedPointNumber
     VeChainDataModel <|.. Hex
     VeChainDataModel <|.. Txt
 ```

packages/core/src/encoding/rlp/helpers/numerickind.ts

@@ -1,5 +1,5 @@
 import { InvalidRLP } from '@vechain/sdk-errors';
-import { FPN, Hex, HexUInt } from '../../../vcdm';
+import { FixedPointNumber, Hex, HexUInt } from '../../../vcdm';
 import { type RLPInput } from '../types';
 
 /**
@@ -76,7 +76,7 @@ const _validateNumericKindNumber = (num: number, context: string): void => {
  */
 const _validateNumericKindString = (str: string, context: string): void => {
     const isHexUInt = HexUInt.isValid0x(str);
-    const isDecimal = FPN.isNaturalExpression(str);
+    const isDecimal = FixedPointNumber.isNaturalExpression(str);
     // Ensure the string is either a hex or decimal number.
     if (!isHexUInt && !isDecimal) {
         throw new InvalidRLP(

packages/core/src/hdkey/HDKey.ts

@@ -2,7 +2,7 @@ import * as s_bip32 from '@scure/bip32';
 import * as s_bip39 from '@scure/bip39';
 import * as nc_utils from '@noble/curves/abstract/utils';
 import { base58 } from '@scure/base';
-import { FPN, Sha256 } from '../vcdm';
+import { FixedPointNumber, Sha256 } from '../vcdm';
 import { HexUInt } from '../vcdm/HexUInt';
 import { Secp256k1 } from '../secp256k1';
 import {
@@ -226,9 +226,9 @@ class HDKey extends s_bip32.HDKey {
             // m
             (index === 0 ? component === 'm' : false) ||
             // "number"
-            FPN.isNaturalExpression(component) ||
+            FixedPointNumber.isNaturalExpression(component) ||
             // "number'"
-            (FPN.isNaturalExpression(component.slice(0, -1)) &&
+            (FixedPointNumber.isNaturalExpression(component.slice(0, -1)) &&
                 component.endsWith("'"))
         );
     }

packages/core/src/transaction/Clause.ts

@@ -2,7 +2,7 @@ import { InvalidDataType } from '@vechain/sdk-errors';
 import {
     abi,
     ABIContract,
-    FPN,
+    FixedPointNumber,
     VET,
     type ABIFunction,
     type Address,
@@ -110,10 +110,10 @@ class Clause implements TransactionClause {
      * Return the amount of {@link VET} or {@link VTHO} token
      * in {@link Units.wei} to transfer to the destination.
      *
-     * @return {FPN} The amount as a fixed-point number.
+     * @return {FixedPointNumber} The amount as a fixed-point number.
      */
-    public amount(): FPN {
-        return FPN.of(HexInt.of(this.value).bi);
+    public amount(): FixedPointNumber {
+        return FixedPointNumber.of(HexInt.of(this.value).bi);
     }
 
     /**
@@ -122,7 +122,7 @@ class Clause implements TransactionClause {
      * @param {Address} contractAddress - The address of the smart contract.
      * @param {ABIFunction} functionAbi - The ABI definition of the function to be called.
      * @param {unknown[]} args - The arguments for the function.
-     * @param {VET} [amount=VET.of(FPN.ZERO)] - The amount of VET to be sent with the transaction calling the function.
+     * @param {VET} [amount=VET.of(FixedPointNumber.ZERO)] - The amount of VET to be sent with the transaction calling the function.
      * @param {ClauseOptions} [clauseOptions] - Optional clause settings.
      * @return {Clause} A clause object to call the function in a transaction.
      * @throws {InvalidDataType} Throws an error if the amount is not a finite positive value.
@@ -131,7 +131,7 @@ class Clause implements TransactionClause {
         contractAddress: Address,
         functionAbi: ABIFunction,
         args: unknown[],
-        amount: VET = VET.of(FPN.ZERO),
+        amount: VET = VET.of(FixedPointNumber.ZERO),
         clauseOptions?: ClauseOptions
     ): Clause {
         if (amount.value.isFinite() && amount.value.isPositive()) {
@@ -223,6 +223,8 @@ class Clause implements TransactionClause {
      * @param {ClauseOptions} [clauseOptions] - Optional clause settings.
      * @return {Clause} The clause to transfer VIP180 tokens as part of a transaction.
      * @throws {InvalidDataType} Throws an error if the amount is not a positive integer.
+     *
+     * @see VTHO.transferTokenTo
      */
     public static transferToken(
         tokenAddress: Address,
@@ -256,6 +258,8 @@ class Clause implements TransactionClause {
      * @param {ClauseOptions} [clauseOptions] - Optional clause settings.
      * @return {Clause} - The clause object to transfer VET as part of a transaction.
      * @throws {InvalidDataType} - If the amount is not a finite positive value.
+     *
+     * @see VET.transferTo
      */
     public static transferVET(
         recipientAddress: Address,