@buildonspark/issuer-sdk 0.0.78 → 0.0.80

package/src/tests/integration/spark.test.ts

@@ -139,9 +139,14 @@ describe.each(TEST_CONFIGS)(
       const tokenAmount: bigint = 1000n;
 
       await sharedIssuerWallet.mintTokens(tokenAmount);
+
+      const sharedIssuerBalance =
+        await sharedIssuerWallet.getIssuerTokenBalance();
+      expect(sharedIssuerBalance).toBeDefined();
+      expect(sharedIssuerBalance.tokenIdentifier).toBeDefined();
       await sharedIssuerWallet.transferTokens({
         tokenAmount,
-        tokenPublicKey: sharedTokenPublicKey,
+        tokenIdentifier: sharedIssuerBalance.tokenIdentifier!,
         receiverSparkAddress: await sharedUserWallet.getSparkAddress(),
       });
 
@@ -308,24 +313,28 @@ describe.each(TEST_CONFIGS)(
         });
 
       await sharedIssuerWallet.mintTokens(tokenAmount);
-      const sourceBalanceBefore = (
-        await sharedIssuerWallet.getIssuerTokenBalance()
-      ).balance;
+      const sharedIssuerBalance =
+        await sharedIssuerWallet.getIssuerTokenBalance();
+      expect(sharedIssuerBalance).toBeDefined();
+      expect(sharedIssuerBalance.tokenIdentifier).toBeDefined();
+
+      const tokenIdentifier = sharedIssuerBalance.tokenIdentifier!;
+      const sourceBalanceBefore = sharedIssuerBalance.balance;
 
       await sharedIssuerWallet.batchTransferTokens([
         {
           tokenAmount: tokenAmount / 3n,
-          tokenPublicKey: sharedTokenPublicKey,
+          tokenIdentifier,
           receiverSparkAddress: await destinationWallet.getSparkAddress(),
         },
         {
           tokenAmount: tokenAmount / 3n,
-          tokenPublicKey: sharedTokenPublicKey,
+          tokenIdentifier,
           receiverSparkAddress: await destinationWallet2.getSparkAddress(),
         },
         {
           tokenAmount: tokenAmount / 3n,
-          tokenPublicKey: sharedTokenPublicKey,
+          tokenIdentifier,
           receiverSparkAddress: await destinationWallet3.getSparkAddress(),
         },
       ]);
@@ -461,9 +470,14 @@ describe.each(TEST_CONFIGS)(
         await issuerWallet.mintTokens(tokenAmount);
 
         // Check issuer balance after minting
-        const issuerBalanceAfterMint = (
-          await issuerWallet.getIssuerTokenBalance()
-        ).balance;
+        const issuerBalanceObjAfterMint =
+          await issuerWallet.getIssuerTokenBalance();
+        expect(issuerBalanceObjAfterMint).toBeDefined();
+        expect(issuerBalanceObjAfterMint.tokenIdentifier).toBeDefined();
+
+        const issuerBalanceAfterMint = issuerBalanceObjAfterMint.balance;
+        const tokenIdentifier = issuerBalanceObjAfterMint.tokenIdentifier!;
+
         expect(issuerBalanceAfterMint).toEqual(tokenAmount);
 
         const { wallet: userWallet } = await SparkWalletTesting.initialize({
@@ -473,7 +487,7 @@ describe.each(TEST_CONFIGS)(
 
         await issuerWallet.transferTokens({
           tokenAmount,
-          tokenPublicKey: await issuerWallet.getIdentityPublicKey(),
+          tokenIdentifier,
           receiverSparkAddress: userWalletPublicKey,
         });
         const issuerBalanceAfterTransfer = (
@@ -533,17 +547,18 @@ describe.each(TEST_CONFIGS)(
         .balance;
 
       await sharedIssuerWallet.mintTokens(tokenAmount);
-
-      const issuerBalanceAfterMint = (
-        await sharedIssuerWallet.getIssuerTokenBalance()
-      ).balance;
+      const issuerBalanceObjAfterMint =
+        await sharedIssuerWallet.getIssuerTokenBalance();
+      expect(issuerBalanceObjAfterMint).toBeDefined();
+      const issuerBalanceAfterMint = issuerBalanceObjAfterMint.balance;
       expect(issuerBalanceAfterMint).toEqual(initialBalance + tokenAmount);
-
+      expect(issuerBalanceObjAfterMint.tokenIdentifier).toBeDefined();
+      const tokenIdentifier = issuerBalanceObjAfterMint.tokenIdentifier!;
       const userWalletPublicKey = await userWallet.getSparkAddress();
 
       await sharedIssuerWallet.transferTokens({
         tokenAmount,
-        tokenPublicKey: sharedTokenPublicKey,
+        tokenIdentifier,
         receiverSparkAddress: userWalletPublicKey,
       });
 
@@ -560,7 +575,7 @@ describe.each(TEST_CONFIGS)(
       expect(userBalanceAfterTransfer.balance).toEqual(tokenAmount);
 
       await userWallet.transferTokens({
-        tokenPublicKey: sharedTokenPublicKey,
+        tokenIdentifier,
         tokenAmount,
         receiverSparkAddress: await sharedIssuerWallet.getSparkAddress(),
       });
@@ -660,6 +675,37 @@ describe.each(TEST_CONFIGS)(
     //   expect(transferBackTransaction).toBeDefined();
     //   expect(userBurnTransaction).toBeDefined();
     // });
+
+    (config.tokenTransactionVersion === "V0" ? it.skip : it)(
+      "should create a token using createToken API",
+      async () => {
+        const { wallet: issuerWallet } =
+          await IssuerSparkWalletTesting.initialize({
+            options: config,
+          });
+
+        const tokenName = `${name}Creatable`;
+        const tokenTicker = "CRT";
+        const maxSupply = 5000n;
+        const decimals = 0;
+        const txId = await issuerWallet.createToken({
+          tokenName,
+          tokenTicker,
+          decimals,
+          isFreezable: false,
+          maxSupply,
+        });
+
+        expect(typeof txId).toBe("string");
+        expect(txId.length).toBeGreaterThan(0);
+
+        const metadata = await issuerWallet.getIssuerTokenMetadata();
+        expect(metadata.tokenName).toEqual(tokenName);
+        expect(metadata.tokenTicker).toEqual(tokenTicker);
+        expect(metadata.maxSupply).toEqual(maxSupply);
+        expect(metadata.decimals).toEqual(decimals);
+      },
+    );
   },
 );
 

package/src/tests/stress/transfers.test.ts

@@ -45,6 +45,10 @@ describe("Stress test for token transfers", () => {
     const tokenPublicKey = await issuerWallet.getIdentityPublicKey();
     const userWalletSparkAddress = await userWallet.getSparkAddress();
     const issuerWalletSparkAddress = await issuerWallet.getSparkAddress();
+    const issuerBalanceObj = await issuerWallet.getIssuerTokenBalance();
+    expect(issuerBalanceObj).toBeDefined();
+    expect(issuerBalanceObj.tokenIdentifier).toBeDefined();
+    const tokenIdentifier = issuerBalanceObj.tokenIdentifier!;
 
     for (let i = 0; i < maxTransactionCycles; i++) {
       if (timeoutReached) {
@@ -59,7 +63,7 @@ describe("Stress test for token transfers", () => {
       try {
         // Transfer tokens from issuer to user
         await issuerWallet.transferTokens({
-          tokenPublicKey,
+          tokenIdentifier,
           tokenAmount: TOKEN_AMOUNT,
           receiverSparkAddress: userWalletSparkAddress,
         });
@@ -75,7 +79,7 @@ describe("Stress test for token transfers", () => {
 
         // Transfer tokens from user to issuer
         await userWallet.transferTokens({
-          tokenPublicKey: tokenPublicKey,
+          tokenIdentifier,
           tokenAmount: TOKEN_AMOUNT,
           receiverSparkAddress: issuerWalletSparkAddress,
         });
@@ -126,20 +130,23 @@ describe("Stress test for token transfers", () => {
           });
 
           await issuer.wallet.mintTokens(TOKEN_AMOUNT);
-          const tokenPublicKey = await issuer.wallet.getIdentityPublicKey();
           const userAddress = await user.wallet.getSparkAddress();
+          const issuerBalanceObj = await issuer.wallet.getIssuerTokenBalance();
+          expect(issuerBalanceObj).toBeDefined();
+          expect(issuerBalanceObj.tokenIdentifier).toBeDefined();
+          const tokenIdentifier = issuerBalanceObj.tokenIdentifier!;
 
-          return { issuer, tokenPublicKey, userAddress };
+          return { issuer, tokenIdentifier, userAddress };
         }),
     );
 
     const transactions = walletPairs.map(
-      ({ issuer, tokenPublicKey, userAddress }) =>
+      ({ issuer, tokenIdentifier, userAddress }) =>
         async () => {
           const start_time = Date.now();
           try {
             await issuer.wallet.transferTokens({
-              tokenPublicKey,
+              tokenIdentifier,
               tokenAmount: TOKEN_AMOUNT,
               receiverSparkAddress: userAddress,
             });

package/src/tests/token-create.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "@jest/globals";
+import { validateTokenParameters } from "../utils/create-validation.js";
+
+const MAX_SUPPLY_128 = (1n << 128n) - 1n;
+
+describe("validateTokenParameters (V1)", () => {
+  describe("valid inputs", () => {
+    it("accepts minimum & maximum byte length for name", () => {
+      expect(() => validateTokenParameters("abc", "AAA", 0, 1n)).not.toThrow();
+      expect(() =>
+        validateTokenParameters("12345678901234567890", "AAA", 0, 1n),
+      ).not.toThrow();
+    });
+
+    it("accepts minimum & maximum byte length for symbol", () => {
+      expect(() =>
+        validateTokenParameters("Token", "ABC", 0, 1n),
+      ).not.toThrow();
+      expect(() =>
+        validateTokenParameters("Token", "ABCDEF", 0, 1n),
+      ).not.toThrow();
+    });
+
+    it("accepts combined length exactly at upper bound", () => {
+      // name 17 bytes + symbol 3 bytes = 20 bytes
+      expect(() =>
+        validateTokenParameters("ABCDEFGHIJKLMNOPQ", "AAA", 0, 1n),
+      ).not.toThrow();
+    });
+
+    it("accepts decimals within 0-255 and maxSupply within u128", () => {
+      expect(() =>
+        validateTokenParameters("Token", "TOK", 255, MAX_SUPPLY_128),
+      ).not.toThrow();
+    });
+
+    it("handles multi-byte UTF-8 characters correctly", () => {
+      // "🚀" is 4 bytes in UTF-8
+      expect(() =>
+        validateTokenParameters("Tok🚀n", "TOK", 8, 1000n),
+      ).not.toThrow();
+    });
+  });
+
+  describe("invalid inputs", () => {
+    it("rejects name too short or too long", () => {
+      expect(() => validateTokenParameters("ab", "AAA", 0, 1n)).toThrow();
+      expect(() =>
+        validateTokenParameters("123456789012345678901", "AAA", 0, 1n),
+      ).toThrow();
+    });
+
+    it("rejects symbol too short or too long", () => {
+      expect(() => validateTokenParameters("Token", "AB", 0, 1n)).toThrow();
+      expect(() =>
+        validateTokenParameters("Token", "ABCDEFG", 0, 1n),
+      ).toThrow();
+    });
+
+    it("rejects decimals outside 0-255 or non-integer", () => {
+      // >255
+      expect(() => validateTokenParameters("Token", "TOK", 256, 1n)).toThrow();
+      // negative
+      expect(() => validateTokenParameters("Token", "TOK", -1, 1n)).toThrow();
+      // non-integer (should be rejected by safe-integer check)
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore intentional wrong type for test
+      expect(() => validateTokenParameters("Token", "TOK", 1.5, 1n)).toThrow();
+    });
+
+    it("rejects decimals >= 2^53", () => {
+      const hugeDecimal = 2 ** 53;
+      expect(() =>
+        validateTokenParameters("Token", "TOK", hugeDecimal, 1n),
+      ).toThrow();
+    });
+
+    it("rejects maxSupply outside u128 range", () => {
+      expect(() => validateTokenParameters("Token", "TOK", 0, -1n)).toThrow();
+      expect(() =>
+        validateTokenParameters("Token", "TOK", 0, MAX_SUPPLY_128 + 1n),
+      ).toThrow();
+    });
+  });
+});

package/src/utils/create-validation.ts

@@ -0,0 +1,92 @@
+import { ValidationError } from "@buildonspark/spark-sdk";
+
+/**
+ * Returns true when the input is already in NFC normalisation form.
+ * JavaScript strings are UTF-16 encoded, so any JavaScript string is
+ * already valid Unicode.  However, we still need to ensure canonical
+ * equivalence so that, for example, \u00E9 (é) and \u0065\u0301 (é)
+ * are treated identically.  We do this by comparing the original
+ * string to its NFC-normalised representation.
+ */
+function isNfcNormalized(value: string): boolean {
+  return value.normalize("NFC") === value;
+}
+
+const MIN_NAME_SIZE = 3; // bytes
+const MAX_NAME_SIZE = 20; // bytes
+const MIN_SYMBOL_SIZE = 3; // bytes
+const MAX_SYMBOL_SIZE = 6; // bytes
+const MAX_DECIMALS = 255; // fits into single byte
+const MAXIMUM_MAX_SUPPLY = (1n << 128n) - 1n; // fits into 16 bytes (u128)
+
+export function validateTokenParameters(
+  tokenName: string,
+  tokenTicker: string,
+  decimals: number,
+  maxSupply: bigint,
+) {
+  if (!isNfcNormalized(tokenName)) {
+    throw new ValidationError("Token name must be NFC-normalised UTF-8", {
+      field: "tokenName",
+      value: tokenName,
+      expected: "NFC normalised string",
+    });
+  }
+
+  if (!isNfcNormalized(tokenTicker)) {
+    throw new ValidationError("Token ticker must be NFC-normalised UTF-8", {
+      field: "tokenTicker",
+      value: tokenTicker,
+      expected: "NFC normalised string",
+    });
+  }
+
+  const nameBytes = Buffer.from(tokenName, "utf-8").length;
+  if (nameBytes < MIN_NAME_SIZE || nameBytes > MAX_NAME_SIZE) {
+    throw new ValidationError(
+      `Token name must be between ${MIN_NAME_SIZE} and ${MAX_NAME_SIZE} bytes`,
+      {
+        field: "tokenName",
+        value: tokenName,
+        actualLength: nameBytes,
+        expected: `>=${MIN_NAME_SIZE} and <=${MAX_NAME_SIZE}`,
+      },
+    );
+  }
+
+  const tickerBytes = Buffer.from(tokenTicker, "utf-8").length;
+  if (tickerBytes < MIN_SYMBOL_SIZE || tickerBytes > MAX_SYMBOL_SIZE) {
+    throw new ValidationError(
+      `Token ticker must be between ${MIN_SYMBOL_SIZE} and ${MAX_SYMBOL_SIZE} bytes`,
+      {
+        field: "tokenTicker",
+        value: tokenTicker,
+        actualLength: tickerBytes,
+        expected: `>=${MIN_SYMBOL_SIZE} and <=${MAX_SYMBOL_SIZE}`,
+      },
+    );
+  }
+
+  if (
+    !Number.isSafeInteger(decimals) ||
+    decimals < 0 ||
+    decimals > MAX_DECIMALS
+  ) {
+    throw new ValidationError(
+      `Decimals must be an integer between 0 and ${MAX_DECIMALS}`,
+      {
+        field: "decimals",
+        value: decimals,
+        expected: `>=0 and <=${MAX_DECIMALS}`,
+      },
+    );
+  }
+
+  if (maxSupply < 0n || maxSupply > MAXIMUM_MAX_SUPPLY) {
+    throw new ValidationError(`maxSupply must be between 0 and 2^128-1`, {
+      field: "maxSupply",
+      value: maxSupply.toString(),
+      expected: `>=0 and <=${MAXIMUM_MAX_SUPPLY.toString()}`,
+    });
+  }
+}