@buildonspark/issuer-sdk 0.0.84 → 0.0.86

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @buildonspark/issuer-sdk
 
+## 0.0.86
+
+### Patch Changes
+
+- Updated dependencies
+  - @buildonspark/spark-sdk@0.2.7
+
+## 0.0.85
+
+### Patch Changes
+
+- -- Opentelemetry improvements
+  -- Utility function to decode bech32mtokenidentifiers to raw token identifiers
+  -- Add userRequest to transfer in getTransfer() if it exists
+  -- Fixes to getIssuerTokenIdentifier() types
+  -- Migrates some internal filtering logic to key on token identifiers
+  -- Testing improvements
+- Updated dependencies
+  - @buildonspark/lrc20-sdk@0.0.61
+  - @buildonspark/spark-sdk@0.2.6
+
 ## 0.0.84
 
 ### Patch Changes

package/dist/chunk-NRKE2XKD.js

@@ -0,0 +1,610 @@
+import {
+  Buffer
+} from "./chunk-7B4B24XF.js";
+
+// src/issuer-wallet/issuer-spark-wallet.ts
+import {
+  NetworkError as NetworkError2,
+  SparkWallet,
+  ValidationError as ValidationError3
+} from "@buildonspark/spark-sdk";
+import {
+  decodeSparkAddress,
+  encodeSparkAddress
+} from "@buildonspark/spark-sdk";
+import {
+  bytesToHex,
+  bytesToNumberBE,
+  hexToBytes as hexToBytes2
+} from "@noble/curves/abstract/utils";
+import { decodeBech32mTokenIdentifier } from "@buildonspark/spark-sdk";
+
+// src/services/freeze.ts
+import {
+  NetworkError,
+  collectResponses
+} from "@buildonspark/spark-sdk";
+
+// src/utils/token-hashing.ts
+import { sha256 } from "@scure/btc-signer/utils";
+import { ValidationError } from "@buildonspark/spark-sdk";
+function hashFreezeTokensPayload(payload) {
+  if (!payload) {
+    throw new ValidationError("Freeze tokens payload cannot be nil", {
+      field: "payload",
+      value: payload,
+      expected: "valid freeze tokens payload"
+    });
+  }
+  let allHashes = [];
+  const versionHashObj = sha256.create();
+  const versionBytes = new Uint8Array(4);
+  new DataView(versionBytes.buffer).setUint32(
+    0,
+    payload.version,
+    false
+    // false for big-endian
+  );
+  versionHashObj.update(versionBytes);
+  allHashes.push(versionHashObj.digest());
+  const ownerPubKeyHash = sha256.create();
+  if (payload.ownerPublicKey) {
+    ownerPubKeyHash.update(payload.ownerPublicKey);
+  }
+  allHashes.push(ownerPubKeyHash.digest());
+  const tokenIdentifierHash = sha256.create();
+  if (payload.tokenIdentifier) {
+    tokenIdentifierHash.update(payload.tokenIdentifier);
+  }
+  allHashes.push(tokenIdentifierHash.digest());
+  const shouldUnfreezeHash = sha256.create();
+  shouldUnfreezeHash.update(new Uint8Array([payload.shouldUnfreeze ? 1 : 0]));
+  allHashes.push(shouldUnfreezeHash.digest());
+  const timestampHash = sha256.create();
+  if (payload.issuerProvidedTimestamp) {
+    const timestampBytes = new Uint8Array(8);
+    new DataView(timestampBytes.buffer).setBigUint64(
+      0,
+      BigInt(payload.issuerProvidedTimestamp),
+      true
+      // true for little-endian
+    );
+    timestampHash.update(timestampBytes);
+  }
+  allHashes.push(timestampHash.digest());
+  const operatorPubKeyHash = sha256.create();
+  if (payload.operatorIdentityPublicKey) {
+    operatorPubKeyHash.update(payload.operatorIdentityPublicKey);
+  }
+  allHashes.push(operatorPubKeyHash.digest());
+  const finalHash = sha256.create();
+  for (const hash of allHashes) {
+    finalHash.update(hash);
+  }
+  return finalHash.digest();
+}
+
+// src/services/freeze.ts
+import { hexToBytes } from "@noble/curves/abstract/utils";
+var TokenFreezeService = class {
+  config;
+  connectionManager;
+  constructor(config, connectionManager) {
+    this.config = config;
+    this.connectionManager = connectionManager;
+  }
+  async freezeTokens({
+    ownerPublicKey,
+    tokenIdentifier
+  }) {
+    return this.freezeOperation(ownerPublicKey, false, tokenIdentifier);
+  }
+  async unfreezeTokens({
+    ownerPublicKey,
+    tokenIdentifier
+  }) {
+    return this.freezeOperation(ownerPublicKey, true, tokenIdentifier);
+  }
+  async freezeOperation(ownerPublicKey, shouldUnfreeze, tokenIdentifier) {
+    const signingOperators = this.config.getSigningOperators();
+    const issuerProvidedTimestamp = Date.now();
+    const freezeResponses = await Promise.allSettled(
+      Object.entries(signingOperators).map(async ([identifier, operator]) => {
+        const sparkTokenClient = await this.connectionManager.createSparkTokenClient(operator.address);
+        const freezeTokensPayload = {
+          version: 1,
+          ownerPublicKey,
+          tokenIdentifier,
+          shouldUnfreeze,
+          issuerProvidedTimestamp,
+          operatorIdentityPublicKey: hexToBytes(operator.identityPublicKey)
+        };
+        const hashedPayload = hashFreezeTokensPayload(freezeTokensPayload);
+        const issuerSignature = await this.config.signer.signMessageWithIdentityKey(hashedPayload);
+        try {
+          const response = await sparkTokenClient.freeze_tokens({
+            freezeTokensPayload,
+            issuerSignature
+          });
+          return {
+            identifier,
+            response
+          };
+        } catch (error) {
+          throw new NetworkError(
+            `Failed to send a freeze/unfreeze operation to operator: ${operator.address}`,
+            {
+              operation: "freeze_tokens",
+              errorCount: 1,
+              errors: error instanceof Error ? error.message : String(error)
+            },
+            error instanceof Error ? error : void 0
+          );
+        }
+      })
+    );
+    const successfulResponses = collectResponses(freezeResponses);
+    return successfulResponses[0].response;
+  }
+};
+
+// src/services/token-transactions.ts
+import { TokenTransactionService } from "@buildonspark/spark-sdk";
+import { numberToBytesBE } from "@noble/curves/abstract/utils";
+var IssuerTokenTransactionService = class extends TokenTransactionService {
+  constructor(config, connectionManager) {
+    super(config, connectionManager);
+  }
+  async constructMintTokenTransactionV0(tokenPublicKey, tokenAmount) {
+    return {
+      network: this.config.getNetworkProto(),
+      tokenInputs: {
+        $case: "mintInput",
+        mintInput: {
+          issuerPublicKey: tokenPublicKey,
+          issuerProvidedTimestamp: Date.now()
+        }
+      },
+      tokenOutputs: [
+        {
+          ownerPublicKey: tokenPublicKey,
+          tokenPublicKey,
+          tokenAmount: numberToBytesBE(tokenAmount, 16)
+        }
+      ],
+      sparkOperatorIdentityPublicKeys: super.collectOperatorIdentityPublicKeys()
+    };
+  }
+  async constructMintTokenTransaction(rawTokenIdentifierBytes, issuerTokenPublicKey, tokenAmount) {
+    return {
+      version: 1,
+      network: this.config.getNetworkProto(),
+      tokenInputs: {
+        $case: "mintInput",
+        mintInput: {
+          issuerPublicKey: issuerTokenPublicKey,
+          tokenIdentifier: rawTokenIdentifierBytes
+        }
+      },
+      tokenOutputs: [
+        {
+          ownerPublicKey: issuerTokenPublicKey,
+          tokenIdentifier: rawTokenIdentifierBytes,
+          tokenAmount: numberToBytesBE(tokenAmount, 16)
+        }
+      ],
+      clientCreatedTimestamp: /* @__PURE__ */ new Date(),
+      sparkOperatorIdentityPublicKeys: super.collectOperatorIdentityPublicKeys(),
+      expiryTime: void 0
+    };
+  }
+  async constructCreateTokenTransaction(tokenPublicKey, tokenName, tokenTicker, decimals, maxSupply, isFreezable) {
+    return {
+      version: 1,
+      network: this.config.getNetworkProto(),
+      tokenInputs: {
+        $case: "createInput",
+        createInput: {
+          issuerPublicKey: tokenPublicKey,
+          tokenName,
+          tokenTicker,
+          decimals,
+          maxSupply: numberToBytesBE(maxSupply, 16),
+          isFreezable
+        }
+      },
+      tokenOutputs: [],
+      clientCreatedTimestamp: /* @__PURE__ */ new Date(),
+      sparkOperatorIdentityPublicKeys: super.collectOperatorIdentityPublicKeys(),
+      expiryTime: void 0
+    };
+  }
+};
+
+// src/issuer-wallet/issuer-spark-wallet.ts
+import { NotImplementedError } from "@buildonspark/spark-sdk";
+
+// src/utils/create-validation.ts
+import { ValidationError as ValidationError2 } from "@buildonspark/spark-sdk";
+function isNfcNormalized(value) {
+  return value.normalize("NFC") === value;
+}
+var MIN_NAME_SIZE = 3;
+var MAX_NAME_SIZE = 20;
+var MIN_SYMBOL_SIZE = 3;
+var MAX_SYMBOL_SIZE = 6;
+var MAX_DECIMALS = 255;
+var MAXIMUM_MAX_SUPPLY = (1n << 128n) - 1n;
+function validateTokenParameters(tokenName, tokenTicker, decimals, maxSupply) {
+  if (!isNfcNormalized(tokenName)) {
+    throw new ValidationError2("Token name must be NFC-normalised UTF-8", {
+      field: "tokenName",
+      value: tokenName,
+      expected: "NFC normalised string"
+    });
+  }
+  if (!isNfcNormalized(tokenTicker)) {
+    throw new ValidationError2("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 ValidationError2(
+      `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 ValidationError2(
+      `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 ValidationError2(
+      `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 ValidationError2(`maxSupply must be between 0 and 2^128-1`, {
+      field: "maxSupply",
+      value: maxSupply.toString(),
+      expected: `>=0 and <=${MAXIMUM_MAX_SUPPLY.toString()}`
+    });
+  }
+}
+
+// src/issuer-wallet/issuer-spark-wallet.ts
+import {
+  encodeBech32mTokenIdentifier
+} from "@buildonspark/spark-sdk";
+var BURN_ADDRESS = "02".repeat(33);
+var IssuerSparkWallet = class _IssuerSparkWallet extends SparkWallet {
+  issuerTokenTransactionService;
+  tokenFreezeService;
+  tracerId = "issuer-sdk";
+  /**
+   * Initializes a new IssuerSparkWallet instance.
+   * @param options - Configuration options for the wallet
+   * @returns An object containing the initialized wallet and initialization response
+   */
+  static async initialize({
+    mnemonicOrSeed,
+    accountNumber,
+    signer,
+    options
+  }) {
+    const wallet = new _IssuerSparkWallet(options, signer);
+    wallet.initializeTracer(wallet);
+    const initResponse = await wallet.initWallet(mnemonicOrSeed, accountNumber);
+    return {
+      wallet,
+      ...initResponse
+    };
+  }
+  constructor(configOptions, signer) {
+    super(configOptions, signer);
+    this.issuerTokenTransactionService = new IssuerTokenTransactionService(
+      this.config,
+      this.connectionManager
+    );
+    this.tokenFreezeService = new TokenFreezeService(
+      this.config,
+      this.connectionManager
+    );
+    this.wrapIssuerSparkWalletMethodsWithTracing();
+  }
+  /**
+   * Gets the token balance for the issuer's token.
+   * @returns An object containing the token balance as a bigint
+   */
+  async getIssuerTokenBalance() {
+    const publicKey = await super.getIdentityPublicKey();
+    const balanceObj = await this.getBalance();
+    const issuerBalance = [...balanceObj.tokenBalances.entries()].find(
+      ([, info]) => info.tokenMetadata.tokenPublicKey === publicKey
+    );
+    if (!balanceObj.tokenBalances || issuerBalance === void 0) {
+      return {
+        tokenIdentifier: void 0,
+        balance: 0n
+      };
+    }
+    return {
+      tokenIdentifier: issuerBalance[0] ?? void 0,
+      balance: issuerBalance[1].balance
+    };
+  }
+  /**
+   * Retrieves information about the issuer's token.
+   * @returns An object containing token information including public key, name, symbol, decimals, max supply, and freeze status
+   * @throws {NetworkError} If the token metadata cannot be retrieved
+   */
+  async getIssuerTokenMetadata() {
+    const issuerPublicKey = await super.getIdentityPublicKey();
+    const tokenMetadata = this.tokenMetadata;
+    const cachedIssuerTokenMetadata = [...tokenMetadata.entries()].find(
+      ([, metadata]) => bytesToHex(metadata.issuerPublicKey) === issuerPublicKey
+    );
+    if (cachedIssuerTokenMetadata !== void 0) {
+      const metadata = cachedIssuerTokenMetadata[1];
+      return {
+        tokenPublicKey: bytesToHex(metadata.issuerPublicKey),
+        rawTokenIdentifier: metadata.tokenIdentifier,
+        tokenName: metadata.tokenName,
+        tokenTicker: metadata.tokenTicker,
+        decimals: metadata.decimals,
+        maxSupply: bytesToNumberBE(metadata.maxSupply),
+        isFreezable: metadata.isFreezable
+      };
+    }
+    const sparkTokenClient = await this.connectionManager.createSparkTokenClient(
+      this.config.getCoordinatorAddress()
+    );
+    try {
+      const response = await sparkTokenClient.query_token_metadata({
+        issuerPublicKeys: Array.of(hexToBytes2(issuerPublicKey))
+      });
+      if (response.tokenMetadata.length === 0) {
+        throw new ValidationError3(
+          "Token metadata not found - If a token has not yet been created, please create it first. Try again in a few seconds.",
+          {
+            field: "tokenMetadata",
+            value: response.tokenMetadata,
+            expected: "non-empty array",
+            actualLength: response.tokenMetadata.length,
+            expectedLength: 1
+          }
+        );
+      }
+      const metadata = response.tokenMetadata[0];
+      const tokenIdentifier = encodeBech32mTokenIdentifier({
+        tokenIdentifier: metadata.tokenIdentifier,
+        network: this.config.getNetworkType()
+      });
+      this.tokenMetadata.set(tokenIdentifier, metadata);
+      return {
+        tokenPublicKey: bytesToHex(metadata.issuerPublicKey),
+        rawTokenIdentifier: metadata.tokenIdentifier,
+        tokenName: metadata.tokenName,
+        tokenTicker: metadata.tokenTicker,
+        decimals: metadata.decimals,
+        maxSupply: bytesToNumberBE(metadata.maxSupply),
+        isFreezable: metadata.isFreezable
+      };
+    } catch (error) {
+      throw new NetworkError2("Failed to fetch token metadata", {
+        errorCount: 1,
+        errors: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  /**
+   * Retrieves the bech32m encoded token identifier for the issuer's token.
+   * @returns The bech32m encoded token identifier for the issuer's token
+   * @throws {NetworkError} If the token identifier cannot be retrieved
+   */
+  async getIssuerTokenIdentifier() {
+    const tokenMetadata = await this.getIssuerTokenMetadata();
+    return encodeBech32mTokenIdentifier({
+      tokenIdentifier: tokenMetadata.rawTokenIdentifier,
+      network: this.config.getNetworkType()
+    });
+  }
+  /**
+   * Create a new token on Spark.
+   *
+   * @param params - Object containing token creation parameters.
+   * @param params.tokenName - The name of the token.
+   * @param params.tokenTicker - The ticker symbol for the token.
+   * @param params.decimals - The number of decimal places for the token.
+   * @param params.isFreezable - Whether the token can be frozen.
+   * @param [params.maxSupply=0n] - (Optional) The maximum supply of the token. Defaults to <code>0n</code>.
+   *
+   * @returns The transaction ID of the announcement.
+   *
+   * @throws {ValidationError} If `decimals` is not a safe integer or other validation fails.
+   * @throws {NetworkError} If the announcement transaction cannot be broadcast.
+   */
+  async createToken({
+    tokenName,
+    tokenTicker,
+    decimals,
+    isFreezable,
+    maxSupply = 0n
+  }) {
+    validateTokenParameters(tokenName, tokenTicker, decimals, maxSupply);
+    const issuerPublicKey = await super.getIdentityPublicKey();
+    const tokenTransaction = await this.issuerTokenTransactionService.constructCreateTokenTransaction(
+      hexToBytes2(issuerPublicKey),
+      tokenName,
+      tokenTicker,
+      decimals,
+      maxSupply,
+      isFreezable
+    );
+    return await this.issuerTokenTransactionService.broadcastTokenTransaction(
+      tokenTransaction
+    );
+  }
+  /**
+   * Mints new tokens
+   * @param tokenAmount - The amount of tokens to mint
+   * @returns The transaction ID of the mint operation
+   */
+  async mintTokens(tokenAmount) {
+    let tokenTransaction;
+    const issuerTokenPublicKey = await super.getIdentityPublicKey();
+    const issuerTokenPublicKeyBytes = hexToBytes2(issuerTokenPublicKey);
+    const tokenMetadata = await this.getIssuerTokenMetadata();
+    const rawTokenIdentifier = tokenMetadata.rawTokenIdentifier;
+    if (this.config.getTokenTransactionVersion() === "V0") {
+      tokenTransaction = await this.issuerTokenTransactionService.constructMintTokenTransactionV0(
+        issuerTokenPublicKeyBytes,
+        tokenAmount
+      );
+    } else {
+      tokenTransaction = await this.issuerTokenTransactionService.constructMintTokenTransaction(
+        rawTokenIdentifier,
+        issuerTokenPublicKeyBytes,
+        tokenAmount
+      );
+    }
+    return await this.issuerTokenTransactionService.broadcastTokenTransaction(
+      tokenTransaction
+    );
+  }
+  /**
+   * Burns issuer's tokens
+   * @param tokenAmount - The amount of tokens to burn
+   * @param selectedOutputs - Optional array of outputs to use for the burn operation
+   * @returns The transaction ID of the burn operation
+   */
+  async burnTokens(tokenAmount, selectedOutputs) {
+    const burnAddress = encodeSparkAddress({
+      identityPublicKey: BURN_ADDRESS,
+      network: this.config.getNetworkType()
+    });
+    const issuerTokenIdentifier = await this.getIssuerTokenIdentifier();
+    return await this.transferTokens({
+      tokenIdentifier: issuerTokenIdentifier,
+      tokenAmount,
+      receiverSparkAddress: burnAddress,
+      selectedOutputs
+    });
+  }
+  /**
+   * Freezes tokens associated with a specific Spark address.
+   * @param sparkAddress - The Spark address whose tokens should be frozen
+   * @returns An object containing the IDs of impacted outputs and the total amount of frozen tokens
+   */
+  async freezeTokens(sparkAddress) {
+    await this.syncTokenOutputs();
+    const decodedOwnerPubkey = decodeSparkAddress(
+      sparkAddress,
+      this.config.getNetworkType()
+    );
+    const issuerTokenIdentifier = await this.getIssuerTokenIdentifier();
+    const rawTokenIdentifier = decodeBech32mTokenIdentifier(
+      issuerTokenIdentifier,
+      this.config.getNetworkType()
+    ).tokenIdentifier;
+    const response = await this.tokenFreezeService.freezeTokens({
+      ownerPublicKey: hexToBytes2(decodedOwnerPubkey.identityPublicKey),
+      tokenIdentifier: rawTokenIdentifier
+    });
+    const tokenAmount = bytesToNumberBE(response.impactedTokenAmount);
+    return {
+      impactedOutputIds: response.impactedOutputIds,
+      impactedTokenAmount: tokenAmount
+    };
+  }
+  /**
+   * Unfreezes previously frozen tokens associated with a specific Spark address.
+   * @param sparkAddress - The Spark address whose tokens should be unfrozen
+   * @returns An object containing the IDs of impacted outputs and the total amount of unfrozen tokens
+   */
+  async unfreezeTokens(sparkAddress) {
+    await this.syncTokenOutputs();
+    const decodedOwnerPubkey = decodeSparkAddress(
+      sparkAddress,
+      this.config.getNetworkType()
+    );
+    const issuerTokenIdentifier = await this.getIssuerTokenIdentifier();
+    const rawTokenIdentifier = decodeBech32mTokenIdentifier(
+      issuerTokenIdentifier,
+      this.config.getNetworkType()
+    ).tokenIdentifier;
+    const response = await this.tokenFreezeService.unfreezeTokens({
+      ownerPublicKey: hexToBytes2(decodedOwnerPubkey.identityPublicKey),
+      tokenIdentifier: rawTokenIdentifier
+    });
+    const tokenAmount = bytesToNumberBE(response.impactedTokenAmount);
+    return {
+      impactedOutputIds: response.impactedOutputIds,
+      impactedTokenAmount: tokenAmount
+    };
+  }
+  /**
+   * Retrieves the distribution information for the issuer's token.
+   * @throws {NotImplementedError} This feature is not yet supported
+   */
+  async getIssuerTokenDistribution() {
+    throw new NotImplementedError("Token distribution is not yet supported");
+  }
+  getTraceName(methodName) {
+    return `IssuerSparkWallet.${methodName}`;
+  }
+  wrapPublicIssuerSparkWalletMethodWithOtelSpan(methodName) {
+    const original = this[methodName];
+    if (typeof original !== "function") {
+      throw new Error(
+        `Method ${methodName} is not a function on IssuerSparkWallet.`
+      );
+    }
+    const wrapped = this.wrapWithOtelSpan(
+      this.getTraceName(methodName),
+      original.bind(this)
+    );
+    this[methodName] = wrapped;
+  }
+  wrapIssuerSparkWalletMethodsWithTracing() {
+    const methods = [
+      "getIssuerTokenBalance",
+      "getIssuerTokenMetadata",
+      "getIssuerTokenIdentifier",
+      "createToken",
+      "mintTokens",
+      "burnTokens",
+      "freezeTokens",
+      "unfreezeTokens",
+      "getIssuerTokenDistribution"
+    ];
+    methods.forEach(
+      (m) => this.wrapPublicIssuerSparkWalletMethodWithOtelSpan(m)
+    );
+  }
+};
+
+export {
+  IssuerSparkWallet
+};