@stellar/typescript-wallet-sdk-soroban 1.5.0

package/CHANGELOG.MD

@@ -0,0 +1,8 @@
+# Release notes - Typescript Wallet SDK Key Soroban - 1.5.0
+
+### Added
+* Init to the project, added soroban functionality
+* getTokenInvocationArgs function
+* Token parsing/formatting functions
+* scValyByType function 
+* generic getInvocationDetails helper

package/README.md

@@ -0,0 +1,80 @@
+# Stellar Typescript Wallet Soroban SDK [![npm version](https://badge.fury.io/js/@stellar%2Ftypescript-wallet-sdk-soroban.svg)](https://badge.fury.io/js/@stellar%2Ftypescript-wallet-sdk-soroban)
+
+The Typescript Wallet Soroban SDK is a work-in-progress library that (currently)
+allows developers to use soroban helpers in their wallet applications. It works
+in conjuction with the main
+[Typescript Wallet SDK](https://github.com/stellar/typescript-wallet-sdk) to
+hold all the functionality a developer would need to create a wallet for the
+stellar network.
+
+## Dependency
+
+The library is available via npm. To import `typescript-wallet-sdk-soroban` you
+need to add it as a dependency to your code:
+
+yarn:
+
+```shell
+yarn add @stellar/typescript-wallet-sdk-soroban
+```
+
+npm:
+
+```shell
+npm install @stellar/typescript-wallet-sdk-soroban
+```
+
+## Introduction
+
+Here's some examples on how to use the Soroban helpers:
+
+```typescript
+import {
+  getTokenInvocationArgs,
+  formatTokenAmount,
+  parseTokenAmount,
+  scValByType,
+} from "@stellar/typescript-wallet-sdk-soroban";
+
+const transaction = TransactionBuilder.fromXDR(
+  "AAAAAgAAAACM6IR9GHiRoVVAO78JJNksy2fKDQNs2jBn8bacsRLcrDucaFsAAAWIAAAAMQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAGAAAAAAAAAABHkEVdJ+UfDnWpBr/qF582IEoDQ0iW0WPzO9CEUdvvh8AAAAIdHJhbnNmZXIAAAADAAAAEgAAAAAAAAAAjOiEfRh4kaFVQDu/CSTZLMtnyg0DbNowZ/G2nLES3KwAAAASAAAAAAAAAADoFl2ACT9HZkbCeuaT9MAIdStpdf58wM3P24nl738AnQAAAAoAAAAAAAAAAAAAAAAAAAAFAAAAAQAAAAAAAAAAAAAAAR5BFXSflHw51qQa/6hefNiBKA0NIltFj8zvQhFHb74fAAAACHRyYW5zZmVyAAAAAwAAABIAAAAAAAAAAIzohH0YeJGhVUA7vwkk2SzLZ8oNA2zaMGfxtpyxEtysAAAAEgAAAAAAAAAA6BZdgAk/R2ZGwnrmk/TACHUraXX+fMDNz9uJ5e9/AJ0AAAAKAAAAAAAAAAAAAAAAAAAABQAAAAAAAAABAAAAAAAAAAIAAAAGAAAAAR5BFXSflHw51qQa/6hefNiBKA0NIltFj8zvQhFHb74fAAAAFAAAAAEAAAAHa35L+/RxV6EuJOVk78H5rCN+eubXBWtsKrRxeLnnpRAAAAACAAAABgAAAAEeQRV0n5R8OdakGv+oXnzYgSgNDSJbRY/M70IRR2++HwAAABAAAAABAAAAAgAAAA8AAAAHQmFsYW5jZQAAAAASAAAAAAAAAACM6IR9GHiRoVVAO78JJNksy2fKDQNs2jBn8bacsRLcrAAAAAEAAAAGAAAAAR5BFXSflHw51qQa/6hefNiBKA0NIltFj8zvQhFHb74fAAAAEAAAAAEAAAACAAAADwAAAAdCYWxhbmNlAAAAABIAAAAAAAAAAOgWXYAJP0dmRsJ65pP0wAh1K2l1/nzAzc/bieXvfwCdAAAAAQBkcwsAACBwAAABKAAAAAAAAB1kAAAAAA==",
+  Networks.FUTURENET,
+) as Transaction<Memo<MemoType>, Operation.InvokeHostFunction[]>;
+const op = transaction.operations[0];
+
+const args = getTokenInvocationArgs(op);
+/*
+  extracts args from the invoke host function operation:
+  args = {
+    fnName: "transfer,
+    contractId: "CAPECFLUT6KHYOOWUQNP7KC6PTMICKANBURFWRMPZTXUEEKHN67B7UI2",
+    from: "GCGORBD5DB4JDIKVIA536CJE3EWMWZ6KBUBWZWRQM7Y3NHFRCLOKYVAL",
+    to: "GDUBMXMABE7UOZSGYJ5ONE7UYAEHKK3JOX7HZQGNZ7NYTZPPP4AJ2GQJ",
+    amount: 5
+  }
+*/
+
+const formattedAmount = formatTokenAmount("10000123", 3);
+// converts smart contract token amount into a displayable amount that can be
+// used on client UI
+// formattedAmount = "10000.123"
+
+const parsedAmount = parseTokenAmount("10000.123", 3);
+// converts an amount to a whole (bigint) number that can be used on
+// smart contracts operations
+// parsedAmount = 10000123
+
+const accountAddress = xdr.ScVal.scvAddress(
+  xdr.ScAddress.scAddressTypeAccount(
+    xdr.PublicKey.publicKeyTypeEd25519(
+      StrKey.decodeEd25519PublicKey(
+        "GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB",
+      ),
+    ),
+  ),
+);
+
+const addressString = scValByType(accountAddress);
+// converts smart contract complex value into a simple string
+// addressString = "GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB"
+```

package/babel.config.js

@@ -0,0 +1,5 @@
+const parentConfig = require("../../babel.config");
+
+module.exports = {
+  ...parentConfig,
+};

package/lib/Helpers/formatTokenAmount.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare const formatTokenAmount: (amount: string | bigint, decimals: number) => string;

package/lib/Helpers/getInvocationDetails.d.ts

@@ -0,0 +1,12 @@
+import { 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 declare const getInvocationDetails: (invocationTree: xdr.SorobanAuthorizedInvocation) => InvocationArgs[];
+export declare const getInvocationArgs: (invocation: xdr.SorobanAuthorizedInvocation) => InvocationArgs | undefined;

package/lib/Helpers/getTokenInvocationArgs.d.ts

@@ -0,0 +1,14 @@
+import { Operation, xdr } from "@stellar/stellar-sdk";
+import { ArgsForTokenInvocation, TokenInvocationArgs } from "../Types";
+export declare const getArgsForTokenInvocation: (fnName: string, args: xdr.ScVal[]) => ArgsForTokenInvocation;
+/**
+ * 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 declare const getTokenInvocationArgs: (hostFn: Operation.InvokeHostFunction) => TokenInvocationArgs | null;

package/lib/Helpers/index.d.ts

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

package/lib/Helpers/parseTokenAmount.d.ts

@@ -0,0 +1,24 @@
+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 declare const parseTokenAmount: (amount: string | number | BigNumber, decimals: number) => bigint;

package/lib/Helpers/scValByType.d.ts

@@ -0,0 +1,23 @@
+import { xdr } from "@stellar/stellar-sdk";
+/**
+ * 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 declare const scValByType: (scVal: xdr.ScVal) => any;

package/lib/Types/index.d.ts

@@ -0,0 +1,31 @@
+import { xdr } from "@stellar/stellar-sdk";
+export declare 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;