@stellar/typescript-wallet-sdk 1.5.0 → 1.6.0-beta.1719867067726

package/src/walletSdk/Uri/Sep7Tx.ts

@@ -0,0 +1,193 @@
+import { Networks, Transaction } from "@stellar/stellar-sdk";
+import {
+  Sep7Base,
+  sep7ReplacementsFromString,
+  sep7ReplacementsToString,
+} from "../Uri";
+import {
+  Sep7OperationType,
+  Sep7Replacement,
+  WEB_STELLAR_SCHEME,
+} from "../Types";
+
+/**
+ * The Sep-7 'tx' operation represents a request to sign
+ * a specific XDR TransactionEnvelope.
+ *
+ * @see https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0007.md#operation-tx
+ */
+export class Sep7Tx extends Sep7Base {
+  /**
+   * Creates a Sep7Tx instance with given transaction.
+   *
+   * Sets the 'xdr' param as a Stellar TransactionEnvelope in XDR format that
+   * is base64 encoded and then URL-encoded.
+   *
+   * @param {Transaction} transaction a transaction which will be used to set the
+   * URI 'xdr' and 'network_passphrase' query params.
+   *
+   * @returns {Sep7Tx} the Sep7Tx instance.
+   */
+  static forTransaction(transaction: Transaction): Sep7Tx {
+    const uri = new Sep7Tx();
+    uri.xdr = transaction.toEnvelope().toXDR().toString("base64");
+    uri.networkPassphrase = transaction.networkPassphrase as Networks;
+    return uri;
+  }
+
+  /**
+   * Creates a new instance of the Sep7Tx class.
+   *
+   * @constructor
+   * @param {URL | string} [uri] - uri to initialize the Sep7 instance.
+   */
+  constructor(uri?: URL | string) {
+    super(uri ?? new URL(`${WEB_STELLAR_SCHEME}${Sep7OperationType.tx}`));
+  }
+
+  /**
+   * Returns a deep clone of this instance.
+   *
+   * @returns {Sep7Tx} a deep clone of this Sep7Tx instance.
+   */
+  clone(): Sep7Tx {
+    return new Sep7Tx(this.uri);
+  }
+
+  /**
+   * Returns a URL-decoded version of the uri 'xdr' param.
+   *
+   * @returns {string | undefined} URL-decoded 'xdr' param if present.
+   */
+  get xdr(): string | undefined {
+    return this.getParam("xdr");
+  }
+
+  /**
+   * Sets and URL-encodes the uri 'xdr' param.
+   *
+   * Deletes the uri 'xdr' param if set as 'undefined'.
+   *
+   * @param {string | undefined} xdr the uri 'xdr' param to be set.
+   */
+  set xdr(xdr: string | undefined) {
+    this.setParam("xdr", xdr);
+  }
+
+  /**
+   * Returns the uri 'pubkey' param.
+   *
+   * This param specifies which public key the URI handler should sign for.
+   *
+   * @returns {string | undefined} URL-decoded 'pubkey' param if present.
+   */
+  get pubkey(): string | undefined {
+    return this.getParam("pubkey");
+  }
+
+  /**
+   * Sets the uri 'pubkey' param.
+   *
+   * Deletes the uri 'pubkey' param if set as 'undefined'.
+   *
+   * This param should specify which public key you want the URI handler
+   * to sign for.
+   *
+   * @param {string | undefined} pubkey the uri 'pubkey' param to be set.
+   */
+  set pubkey(pubkey: string | undefined) {
+    this.setParam("pubkey", pubkey);
+  }
+
+  /**
+   * Returns a URL-decoded version of the uri 'chain' param.
+   *
+   * There can be an optional chain query param to include a single SEP-0007
+   * request that spawned or triggered the creation of this SEP-0007 request.
+   * This will be a URL-encoded value. The goal of this field is to be
+   * informational only and can be used to forward SEP-0007 requests.
+   *
+   * @returns {string | undefined} URL-decoded 'chain' param if present.
+   */
+  get chain(): string | undefined {
+    return this.getParam("chain");
+  }
+
+  /**
+   * Sets and URL-encodes the uri 'chain' param.
+   *
+   * Deletes the uri 'chain' param if set as 'undefined'.
+   *
+   * There can be an optional chain query param to include a single SEP-0007
+   * request that spawned or triggered the creation of this SEP-0007 request.
+   * This will be a URL-encoded value. The goal of this field is to be
+   * informational only and can be used to forward SEP-0007 requests.
+   *
+   * @param {string | undefined} chain the 'chain' param to be set.
+   */
+  set chain(chain: string | undefined) {
+    this.setParam("chain", chain);
+  }
+
+  /**
+   * Gets a list of fields in the transaction that need to be replaced.
+   *
+   * @returns {Sep7Replacement[]} list of fields that need to be replaced.
+   */
+  getReplacements(): Sep7Replacement[] {
+    return sep7ReplacementsFromString(this.getParam("replace"));
+  }
+
+  /**
+   * Sets and URL-encodes the uri 'replace' param, which is a list of fields in
+   * the transaction that needs to be replaced.
+   *
+   * Deletes the uri 'replace' param if set as empty array '[]' or 'undefined'.
+   *
+   * This 'replace' param should be a URL-encoded value that identifies the
+   * fields to be replaced in the XDR using the 'Txrep (SEP-0011)' representation.
+   * This will be specified in the format of:
+   * txrep_tx_field_name_1:reference_identifier_1,txrep_tx_field_name_2:reference_identifier_2;reference_identifier_1:hint_1,reference_identifier_2:hint_2
+   *
+   * @see https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0011.md
+   *
+   * @param {Sep7Replacement[]} replacements a list of replacements to set.
+   */
+  setReplacements(replacements: Sep7Replacement[] | undefined) {
+    if (!replacements || replacements.length === 0) {
+      this.setParam("replace", undefined);
+      return;
+    }
+    this.setParam("replace", sep7ReplacementsToString(replacements));
+  }
+
+  /**
+   * Adds an additional replacement.
+   *
+   * @param {Sep7Replacement} replacement the replacement to add.
+   */
+  addReplacement(replacement: Sep7Replacement) {
+    const replacements = this.getReplacements();
+    replacements.push(replacement);
+    this.setReplacements(replacements);
+  }
+
+  /**
+   * Removes all replacements with the given identifier.
+   *
+   * @param {string} id the identifier to remove.
+   */
+  removeReplacement(id: string) {
+    const replacements = this.getReplacements().filter((r) => r.id !== id);
+    this.setReplacements(replacements);
+  }
+
+  /**
+   * Creates a Stellar Transaction from the URI's XDR and networkPassphrase.
+   *
+   * @returns {Transaction} the Stellar Transaction.
+   */
+  getTransaction(): Transaction {
+    return new Transaction(this.xdr, this.networkPassphrase || Networks.PUBLIC);
+  }
+}

package/src/walletSdk/Uri/index.ts

@@ -0,0 +1,9 @@
+export { Sep7Base } from "./Sep7Base";
+export { Sep7Pay } from "./Sep7Pay";
+export { Sep7Tx } from "./Sep7Tx";
+export {
+  isValidSep7Uri,
+  parseSep7Uri,
+  sep7ReplacementsFromString,
+  sep7ReplacementsToString,
+} from "./sep7Parser";

package/src/walletSdk/Uri/sep7Parser.ts

@@ -0,0 +1,220 @@
+import { Networks, StrKey, Transaction } from "@stellar/stellar-sdk";
+
+import { Sep7Pay, Sep7Tx } from "../Uri";
+import {
+  Sep7Replacement,
+  Sep7OperationType,
+  IsValidSep7UriResult,
+  WEB_STELLAR_SCHEME,
+  URI_MSG_MAX_LENGTH,
+} from "../Types";
+import {
+  Sep7InvalidUriError,
+  Sep7UriTypeNotSupportedError,
+} from "../Exceptions";
+
+/**
+ * Returns true if the given URI is a SEP-7 compliant URI, false otherwise.
+ *
+ * Currently this checks whether it starts with 'web+stellar:tx' or 'web+stellar:pay'
+ * and has its required parameters: 'xdr=' and 'destination=' respectively.
+ *
+ * @param {string} uri The URI string to check.
+ *
+ * @returns {IsValidSep7UriResult} returns '{ result: true }' if it's a valid Sep-7
+ * uri, returns '{ result: false, reason: "<reason>" }' containing a 'reason' message
+ * in case the verification fails.
+ */
+export const isValidSep7Uri = (uri: string): IsValidSep7UriResult => {
+  if (!uri.startsWith(WEB_STELLAR_SCHEME)) {
+    return {
+      result: false,
+      reason: `it must start with '${WEB_STELLAR_SCHEME}'`,
+    };
+  }
+
+  const url = new URL(uri);
+
+  const type = url.pathname as Sep7OperationType;
+  const xdr = url.searchParams.get("xdr");
+  const networkPassphrase =
+    url.searchParams.get("network_passphrase") || Networks.PUBLIC;
+  const destination = url.searchParams.get("destination");
+  const msg = url.searchParams.get("msg");
+
+  if (![Sep7OperationType.tx, Sep7OperationType.pay].includes(type)) {
+    return {
+      result: false,
+      reason: `operation type '${type}' is not currently supported`,
+    };
+  }
+
+  if (type === Sep7OperationType.tx && !xdr) {
+    return {
+      result: false,
+      reason: `operation type '${type}' must have a 'xdr' parameter`,
+    };
+  }
+
+  if (type === Sep7OperationType.tx && xdr) {
+    try {
+      new Transaction(xdr, networkPassphrase);
+    } catch {
+      return {
+        result: false,
+        reason: `the provided 'xdr' parameter is not a valid transaction envelope on the '${networkPassphrase}' network`,
+      };
+    }
+  }
+
+  if (type === Sep7OperationType.pay && !destination) {
+    return {
+      result: false,
+      reason: `operation type '${type}' must have a 'destination' parameter`,
+    };
+  }
+
+  if (type === Sep7OperationType.pay && destination) {
+    // Checks if it's a valid "G", "M" or "C" Stellar address
+    const isValidStellarAddress =
+      StrKey.isValidEd25519PublicKey(destination) ||
+      StrKey.isValidMed25519PublicKey(destination) ||
+      StrKey.isValidContract(destination);
+
+    if (!isValidStellarAddress) {
+      return {
+        result: false,
+        reason:
+          "the provided 'destination' parameter is not a valid Stellar address",
+      };
+    }
+  }
+
+  if (msg?.length > URI_MSG_MAX_LENGTH) {
+    return {
+      result: false,
+      reason: `the 'msg' parameter should be no longer than ${URI_MSG_MAX_LENGTH} characters`,
+    };
+  }
+
+  return {
+    result: true,
+  };
+};
+
+/**
+ * Try parsing a SEP-7 URI string and returns a Sep7Tx or Sep7Pay instance,
+ * depending on the type.
+ *
+ * @param {string} uri The URI string to parse.
+ *
+ * @returns {Sep7Tx | Sep7Pay} a uri parsed Sep7Tx or Sep7Pay instance.
+ *
+ * @throws {Sep7InvalidUriError} if the inputted uri is not a valid SEP-7 URI.
+ * @throws {Sep7UriTypeNotSupportedError} if the inputted uri does not have a
+ * supported SEP-7 type.
+ */
+export const parseSep7Uri = (uri: string): Sep7Tx | Sep7Pay => {
+  const isValid = isValidSep7Uri(uri);
+  if (!isValid.result) {
+    throw new Sep7InvalidUriError(isValid.reason);
+  }
+
+  const url = new URL(uri);
+
+  const type = url.pathname;
+  switch (type) {
+    case Sep7OperationType.tx:
+      return new Sep7Tx(url);
+    case Sep7OperationType.pay:
+      return new Sep7Pay(url);
+    default:
+      throw new Sep7UriTypeNotSupportedError(type);
+  }
+};
+
+/**
+ * String delimiters shared by the parsing functions below.
+ */
+const HINT_DELIMITER = ";";
+const ID_DELIMITER = ":";
+const LIST_DELIMITER = ",";
+
+/**
+ * Takes a Sep-7 URL-decoded 'replace' string param and parses it to a list of
+ * Sep7Replacement objects for easy of use.
+ *
+ * This string identifies the fields to be replaced in the XDR using
+ * the 'Txrep (SEP-0011)' representation, which should be specified in the format of:
+ * txrep_tx_field_name_1:reference_identifier_1,txrep_tx_field_name_2:reference_identifier_2;reference_identifier_1:hint_1,reference_identifier_2:hint_2
+ *
+ * @see https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0011.md
+ *
+ * @param {string} [replacements] a replacements string in the
+ * 'Txrep (SEP-0011)' representation.
+ *
+ * @returns {Sep7Replacement[]} a list of parsed Sep7Replacement objects.
+ */
+export const sep7ReplacementsFromString = (
+  replacements?: string,
+): Sep7Replacement[] => {
+  if (!replacements) {
+    return [];
+  }
+
+  const [txrepString, hintsString] = replacements.split(HINT_DELIMITER);
+  const hintsList = hintsString.split(LIST_DELIMITER);
+
+  const hintsMap: { [id: string]: string } = {};
+
+  hintsList
+    .map((item) => item.split(ID_DELIMITER))
+    .forEach(([id, hint]) => (hintsMap[id] = hint));
+
+  const txrepList = txrepString.split(LIST_DELIMITER);
+
+  const replacementsList = txrepList
+    .map((item) => item.split(ID_DELIMITER))
+    .map(([path, id]) => ({ id, path, hint: hintsMap[id] }));
+
+  return replacementsList;
+};
+
+/**
+ * Takes a list of Sep7Replacement objects and parses it to a string that
+ * could be URL-encoded and used as a Sep-7 URI 'replace' param.
+ *
+ * This string identifies the fields to be replaced in the XDR using
+ * the 'Txrep (SEP-0011)' representation, which should be specified in the format of:
+ * txrep_tx_field_name_1:reference_identifier_1,txrep_tx_field_name_2:reference_identifier_2;reference_identifier_1:hint_1,reference_identifier_2:hint_2
+ *
+ * @see https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0011.md
+ *
+ * @param {Sep7Replacement[]} [replacements] a list of Sep7Replacement objects.
+ *
+ * @returns {string} a string that identifies the fields to be replaced in the
+ * XDR using the 'Txrep (SEP-0011)' representation.
+ */
+export const sep7ReplacementsToString = (
+  replacements?: Sep7Replacement[],
+): string => {
+  if (!replacements || replacements.length === 0) {
+    return "";
+  }
+
+  const hintsMap: { [id: string]: string } = {};
+
+  const txrepString = replacements
+    .map(({ id, hint, path }) => {
+      hintsMap[id] = hint;
+
+      return `${path}${ID_DELIMITER}${id}`;
+    })
+    .join(LIST_DELIMITER);
+
+  const hintsString = Object.entries(hintsMap)
+    .map(([id, hint]) => `${id}${ID_DELIMITER}${hint}`)
+    .join(LIST_DELIMITER);
+
+  return `${txrepString}${HINT_DELIMITER}${hintsString}`;
+};

package/src/walletSdk/Utils/index.ts

@@ -1,4 +1,5 @@
 export * from "./camelToSnakeCase";
+export * from "./extractAxiosErrorData";
+export * from "./getResultCode";
 export * from "./toml";
 export * from "./url";
-export * from "./extractAxiosErrorData";

package/src/walletSdk/Watcher/index.ts

@@ -1,4 +1,6 @@
 import { Anchor } from "../Anchor";
+import { Sep6 } from "../Anchor/Sep6";
+import { Sep24 } from "../Anchor/Sep24";
 import {
   AnchorTransaction,
   TransactionStatus,
@@ -329,7 +331,7 @@ export class Watcher {
       };
     }
 
-    let sepObj;
+    let sepObj: Sep6 | Sep24;
     switch (this.sepType) {
       case WatcherSepType.SEP6:
         sepObj = this.anchor.sep6();

package/test/customer.test.ts

@@ -35,18 +35,18 @@ describe("Customer", () => {
         type: customerType,
       },
     });
-    expect(resp.data.id).toBeTruthy();
-    const { id } = resp.data;
+    expect(resp.id).toBeTruthy();
+    const { id } = resp;
 
     // Get
     resp = await sep12.getCustomer({ id, type: customerType });
-    expect(Object.keys(resp.data).sort()).toEqual(
+    expect(Object.keys(resp).sort()).toEqual(
       ["id", "provided_fields", "fields", "status"].sort(),
     );
-    expect(Object.keys(resp.data?.provided_fields).sort()).toEqual(
+    expect(Object.keys(resp?.provided_fields).sort()).toEqual(
       ["first_name", "last_name", "email_address"].sort(),
     );
-    expect(Object.keys(resp.data?.fields).sort()).toEqual(
+    expect(Object.keys(resp?.fields).sort()).toEqual(
       [
         "bank_account_number",
         "bank_number",
@@ -70,11 +70,11 @@ describe("Customer", () => {
       },
       id,
     });
-    expect(resp.data.id).toBeTruthy();
+    expect(resp.id).toBeTruthy();
 
     // Get again, check that the provided fields updated
     resp = await sep12.getCustomer({ id, type: customerType });
-    expect(Object.keys(resp.data.fields).length).toBe(0);
+    expect(Object.keys(resp.fields).length).toBe(0);
 
     // Delete
     await sep12.delete();

package/test/integration/anchorplatform.test.ts

@@ -60,7 +60,7 @@ describe("Anchor Platform Integration Tests", () => {
         bank_account_number: "12345",
       },
     });
-    expect(sep12Resp.data.id).toBeTruthy();
+    expect(sep12Resp.id).toBeTruthy();
 
     // SEP-6 deposit
     const sep6 = anchor.sep6();
@@ -85,7 +85,7 @@ describe("Anchor Platform Integration Tests", () => {
       },
     });
     expect(wResp.id).toBeTruthy();
-  }, 30000);
+  }, 120000);
 
   it("SEP-24 should work", async () => {
     const assetCode = "USDC";