@stellar/typescript-wallet-sdk-soroban 1.5.0

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./Helpers";
+export * from "./Types";

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@stellar/typescript-wallet-sdk-soroban",
+  "version": "1.5.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "browser": "./lib/bundle_browser.js",
+  "main": "./lib/bundle.js",
+  "types": "./lib/index.d.ts",
+  "license": "Apache-2.0",
+  "private": false,
+  "devDependencies": {
+    "@babel/preset-env": "^7.24.0",
+    "@babel/preset-typescript": "^7.23.3",
+    "@stellar/prettier-config": "^1.0.1",
+    "@stellar/tsconfig": "^1.0.2",
+    "@types/jest": "^29.5.12",
+    "@typescript-eslint/parser": "^7.1.1",
+    "babel-jest": "^29.7.0",
+    "husky": "^9.0.11",
+    "jest": "^29.7.0",
+    "npm-run-all": "^4.1.5",
+    "ts-jest": "^29.1.2",
+    "ts-loader": "^9.5.1",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3",
+    "webpack": "^5.90.3",
+    "webpack-cli": "^5.1.4"
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "^11.1.0"
+  },
+  "scripts": {
+    "prepare": "husky install",
+    "test": "jest --watchAll",
+    "test:ci": "jest --ci",
+    "build:web": "webpack --config webpack.config.js",
+    "build:node": "webpack --env NODE=true --config webpack.config.js",
+    "build": "run-p build:web build:node"
+  }
+}

package/src/Helpers/formatTokenAmount.ts

@@ -0,0 +1,23 @@
+import { Soroban } from "@stellar/stellar-sdk";
+
+/**
+ * https://github.com/stellar/js-stellar-base/blob/4b510113738aefb5decb31e2ae72c27da5dd7f5c/src/soroban.js
+ *
+ * Given a whole number smart contract amount of a token and an amount of
+ * decimal places (if the token has any), it returns a "display" value.
+ *
+ * All arithmetic inside the contract is performed on integers to avoid
+ * potential precision and consistency issues of floating-point.
+ *
+ * @param {string | bigint} amount  the token amount you want to display
+ * @param {number} decimals  specify how many decimal places a token has
+ *
+ * @returns {string}  the display value
+ * @throws {TypeError}  if the given amount has a decimal point already
+ * @example
+ * formatTokenAmount("123000", 4) === "12.3";
+ */
+export const formatTokenAmount = (
+  amount: string | bigint,
+  decimals: number,
+): string => Soroban.formatTokenAmount(amount.toString(), decimals);

package/src/Helpers/getInvocationDetails.ts

@@ -0,0 +1,81 @@
+import { Address, Asset, StrKey, xdr } from "@stellar/stellar-sdk";
+
+import { InvocationArgs } from "Types";
+
+/**
+ * Extract invocation args and params from a Soroban authorized invocation
+ * tree up to its immediate sub invocations.
+ *
+ * @param {xdr.SorobanAuthorizedInvocation} invocationTree - The invocation tree.
+ *
+ * @returns {InvocationArgs[]} A list of user friendly invocation args and params.
+ */
+export const getInvocationDetails = (
+  invocationTree: xdr.SorobanAuthorizedInvocation,
+): InvocationArgs[] => {
+  const invocations = [
+    getInvocationArgs(invocationTree),
+    ...invocationTree.subInvocations().map(getInvocationArgs),
+  ];
+  return invocations.filter(isInvocationArg);
+};
+
+const isInvocationArg = (
+  invocation: InvocationArgs | undefined,
+): invocation is InvocationArgs => !!invocation;
+
+export const getInvocationArgs = (
+  invocation: xdr.SorobanAuthorizedInvocation,
+): InvocationArgs | undefined => {
+  const fn = invocation.function();
+
+  switch (fn.switch().value) {
+    // sorobanAuthorizedFunctionTypeContractFn
+    case 0: {
+      const _invocation = fn.contractFn();
+      const contractId = StrKey.encodeContract(
+        _invocation.contractAddress().contractId(),
+      );
+      const fnName = _invocation.functionName().toString();
+      const args = _invocation.args();
+      return { fnName, contractId, args, type: "invoke" };
+    }
+
+    // sorobanAuthorizedFunctionTypeCreateContractHostFn
+    case 1: {
+      const _invocation = fn.createContractHostFn();
+      const [exec, preimage] = [
+        _invocation.executable(),
+        _invocation.contractIdPreimage(),
+      ];
+
+      switch (exec.switch().value) {
+        // contractExecutableWasm
+        case 0: {
+          const details = preimage.fromAddress();
+
+          return {
+            type: "wasm",
+            salt: details.salt().toString("hex"),
+            hash: exec.wasmHash().toString("hex"),
+            address: Address.fromScAddress(details.address()).toString(),
+          };
+        }
+
+        // contractExecutableStellarAsset
+        case 1:
+          return {
+            type: "sac",
+            asset: Asset.fromOperation(preimage.fromAsset()).toString(),
+          };
+
+        default:
+          throw new Error(`unknown creation type: ${JSON.stringify(exec)}`);
+      }
+    }
+
+    default: {
+      return undefined;
+    }
+  }
+};

package/src/Helpers/getTokenInvocationArgs.ts

@@ -0,0 +1,94 @@
+import { Operation, StrKey, scValToNative, xdr } from "@stellar/stellar-sdk";
+
+import {
+  ArgsForTokenInvocation,
+  SorobanTokenInterface,
+  TokenInvocationArgs,
+} from "../Types";
+
+export const getArgsForTokenInvocation = (
+  fnName: string,
+  args: xdr.ScVal[],
+): ArgsForTokenInvocation => {
+  let amount: bigint | number;
+  let from = "";
+  let to = "";
+
+  switch (fnName) {
+    case SorobanTokenInterface.transfer:
+      from = StrKey.encodeEd25519PublicKey(
+        args[0].address().accountId().ed25519(),
+      );
+      to = StrKey.encodeEd25519PublicKey(
+        args[1].address().accountId().ed25519(),
+      );
+      amount = scValToNative(args[2]);
+      break;
+    case SorobanTokenInterface.mint:
+      to = StrKey.encodeEd25519PublicKey(
+        args[0].address().accountId().ed25519(),
+      );
+      amount = scValToNative(args[1]);
+      break;
+    default:
+      amount = BigInt(0);
+  }
+
+  return { from, to, amount };
+};
+
+/**
+ * Get params and args related to the invoked contract. It must use a valid
+ * "transfer" or "mint" invocation otherwise it will return 'null'.
+ *
+ * @param {Operation.InvokeHostFunction} hostFn - The invoke host function.
+ *
+ * @returns {TokenInvocationArgs | null} Params and args related to the
+ * "transfer" or "mint" invocation like function name, contract id, from/to
+ * addresses and amount.
+ */
+export const getTokenInvocationArgs = (
+  hostFn: Operation.InvokeHostFunction,
+): TokenInvocationArgs | null => {
+  if (!hostFn?.func?.invokeContract) {
+    return null;
+  }
+
+  let invokedContract: xdr.InvokeContractArgs;
+
+  try {
+    invokedContract = hostFn.func.invokeContract();
+  } catch (e) {
+    return null;
+  }
+
+  const contractId = StrKey.encodeContract(
+    invokedContract.contractAddress().contractId(),
+  );
+  const fnName = invokedContract
+    .functionName()
+    .toString() as SorobanTokenInterface;
+  const args = invokedContract.args();
+
+  if (
+    ![SorobanTokenInterface.transfer, SorobanTokenInterface.mint].includes(
+      fnName,
+    )
+  ) {
+    return null;
+  }
+
+  let opArgs: ArgsForTokenInvocation;
+
+  try {
+    opArgs = getArgsForTokenInvocation(fnName, args);
+  } catch (e) {
+    return null;
+  }
+
+  return {
+    fnName,
+    contractId,
+    ...opArgs,
+  };
+};

package/src/Helpers/index.ts

@@ -0,0 +1,5 @@
+export * from "./formatTokenAmount";
+export * from "./getInvocationDetails";
+export * from "./getTokenInvocationArgs";
+export * from "./parseTokenAmount";
+export * from "./scValByType";

package/src/Helpers/parseTokenAmount.ts

@@ -0,0 +1,33 @@
+import { Soroban } from "@stellar/stellar-sdk";
+import BigNumber from "bignumber.js";
+
+/**
+ * https://github.com/stellar/js-stellar-base/blob/4b510113738aefb5decb31e2ae72c27da5dd7f5c/src/soroban.js
+ *
+ * Parse a token amount to use it on smart contract
+ *
+ * This function takes the display value and its decimals (if the token has
+ * any) and returns a string that'll be used within the smart contract.
+ *
+ * @param {string | number | BigNumber} amount  the token amount you want to
+ *    use in a smart contract which you've been displaying in a UI
+ * @param {number} decimals  the number of decimal places expected in the
+ *    display value (different than the "actual" number, because suffix zeroes
+ *    might not be present)
+ *
+ * @returns {bigint}  the whole number token amount represented by the display
+ *    value with the decimal places shifted over
+ *
+ * @example
+ * const displayValueAmount = "123.4560"
+ * const parsedAmtForSmartContract = parseTokenAmount(displayValueAmount, 5);
+ * parsedAmtForSmartContract === "12345600"
+ */
+export const parseTokenAmount = (
+  amount: string | number | BigNumber,
+  decimals: number,
+): bigint => {
+  const parsedAmount = Soroban.parseTokenAmount(amount.toString(), decimals);
+
+  return BigInt(parsedAmount.toString());
+};

package/src/Helpers/scValByType.ts

@@ -0,0 +1,97 @@
+import { StrKey, scValToNative, xdr } from "@stellar/stellar-sdk";
+
+/* eslint-disable jsdoc/require-returns-type */
+/**
+ * This function attempts to convert smart contract (complex) value types
+ * to common/simpler types like string, array, buffer, JSON string, etc.
+ *
+ * @param {xdr.ScVal} scVal  the smart contract (complex) value
+ *
+ *
+ * @returns the smart contract value converted to a common/simpler
+ *     value like string, array, buffer, JSON string, etc.
+ *
+ * @example
+ *   const accountAddress = xdr.ScVal.scvAddress(
+ *     xdr.ScAddress.scAddressTypeAccount(
+ *       xdr.PublicKey.publicKeyTypeEd25519(
+ *         StrKey.decodeEd25519PublicKey("GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB"),
+ *       ),
+ *     )
+ *   ); ===> complex object
+ *
+ *   scValByType(accountAddress) returns "GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB"
+ */
+export const scValByType = (scVal: xdr.ScVal) => {
+  switch (scVal.switch()) {
+    case xdr.ScValType.scvAddress(): {
+      const address = scVal.address();
+      const addressType = address.switch();
+      if (addressType.name === "scAddressTypeAccount") {
+        return StrKey.encodeEd25519PublicKey(address.accountId().ed25519());
+      }
+      return StrKey.encodeContract(address.contractId());
+    }
+
+    case xdr.ScValType.scvBool(): {
+      return scVal.b();
+    }
+
+    case xdr.ScValType.scvBytes(): {
+      return JSON.stringify(scVal.bytes().toJSON().data);
+    }
+
+    case xdr.ScValType.scvContractInstance(): {
+      const instance = scVal.instance();
+      return instance.executable().wasmHash()?.toString();
+    }
+
+    case xdr.ScValType.scvError(): {
+      const error = scVal.error();
+      return error.value();
+    }
+
+    case xdr.ScValType.scvTimepoint():
+    case xdr.ScValType.scvDuration():
+    case xdr.ScValType.scvI128():
+    case xdr.ScValType.scvI256():
+    case xdr.ScValType.scvI32():
+    case xdr.ScValType.scvI64():
+    case xdr.ScValType.scvU128():
+    case xdr.ScValType.scvU256():
+    case xdr.ScValType.scvU32():
+    case xdr.ScValType.scvU64(): {
+      return scValToNative(scVal).toString();
+    }
+
+    case xdr.ScValType.scvLedgerKeyNonce():
+    case xdr.ScValType.scvLedgerKeyContractInstance(): {
+      if (scVal.switch().name === "scvLedgerKeyNonce") {
+        const val = scVal.nonceKey().nonce();
+        return val.toString();
+      }
+      return scVal.value();
+    }
+
+    case xdr.ScValType.scvVec():
+    case xdr.ScValType.scvMap(): {
+      return JSON.stringify(
+        scValToNative(scVal),
+        (_, val) => (typeof val === "bigint" ? val.toString() : val),
+        2,
+      );
+    }
+
+    case xdr.ScValType.scvString():
+    case xdr.ScValType.scvSymbol(): {
+      const native = scValToNative(scVal);
+      if (native.constructor === "Uint8Array") {
+        return native.toString();
+      }
+      return native;
+    }
+
+    default:
+      return null;
+  }
+};

package/src/Types/index.ts

@@ -0,0 +1,39 @@
+import { xdr } from "@stellar/stellar-sdk";
+
+// https://github.com/stellar/soroban-examples/blob/main/token/src/contract.rs
+export enum SorobanTokenInterface {
+  transfer = "transfer",
+  mint = "mint",
+}
+
+export type ArgsForTokenInvocation = {
+  from: string;
+  to: string;
+  amount: bigint | number;
+};
+
+export type TokenInvocationArgs = ArgsForTokenInvocation & {
+  fnName: SorobanTokenInterface;
+  contractId: string;
+};
+
+export interface FnArgsInvoke {
+  type: "invoke";
+  fnName: string;
+  contractId: string;
+  args: xdr.ScVal[];
+}
+
+export interface FnArgsCreateWasm {
+  type: "wasm";
+  salt: string;
+  hash: string;
+  address: string;
+}
+
+export interface FnArgsCreateSac {
+  type: "sac";
+  asset: string;
+}
+
+export type InvocationArgs = FnArgsInvoke | FnArgsCreateWasm | FnArgsCreateSac;

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./Helpers";
+export * from "./Types";