@stellar/typescript-wallet-sdk 1.2.0 → 1.3.0

package/src/walletSdk/Horizon/Transaction/SponsoringBuilder.ts

@@ -1,21 +1,30 @@
-import StellarSdk, {
-  TransactionBuilder as StellarTransactionBuilder,
-  Transaction,
-  xdr,
-} from "stellar-sdk";
-import { IssuedAssetId } from "../../Asset";
+import StellarSdk, { xdr } from "stellar-sdk";
 
 import { CommonTransactionBuilder } from "./CommonTransactionBuilder";
 import { AccountKeypair } from "../Account";
 
+/**
+ * Used for building transactions that will include a sponsor.
+ * Do not create this object directly, use the TransactionBuilder class to create.
+ * @class
+ */
 export class SponsoringBuilder extends CommonTransactionBuilder<SponsoringBuilder> {
   private sponsorAccount: AccountKeypair;
 
+  /**
+   * Creates a new instance of the SponsoringBuilder class.
+   * @constructor
+   * @param {string} sponsoredAddress - The address of the account being sponsored.
+   * @param {AccountKeypair} sponsorAccount - The sponsor account keypair.
+   * @param {xdr.Operation[]} operations - An array of Stellar operations.
+   * @param {(builder: SponsoringBuilder) => SponsoringBuilder} buildingFunction - Function for creating the
+   * operations that will be sponsored.
+   */
   constructor(
     sponsoredAddress: string,
     sponsorAccount: AccountKeypair,
     operations: Array<xdr.Operation>,
-    buildingFunction: (SponsoringBuilder) => SponsoringBuilder,
+    buildingFunction: (builder: SponsoringBuilder) => SponsoringBuilder,
   ) {
     super(sponsoredAddress, operations);
     this.sponsorAccount = sponsorAccount;
@@ -25,6 +34,12 @@ export class SponsoringBuilder extends CommonTransactionBuilder<SponsoringBuilde
     this.stopSponsoring();
   }
 
+  /**
+   * Creates a Stellar account with sponsored reserves.
+   * @param {AccountKeypair} newAccount - The new account's keypair.
+   * @param {number} [startingBalance=0] - The starting balance for the new account (default is 0 XLM).
+   * @returns {SponsoringBuilder} The SponsoringBuilder instance.
+   */
   createAccount(
     newAccount: AccountKeypair,
     startingBalance: number = 0,
@@ -39,6 +54,10 @@ export class SponsoringBuilder extends CommonTransactionBuilder<SponsoringBuilde
     return this;
   }
 
+  /**
+   * Start sponsoring the future reserves of an account.
+   * @returns {void}
+   */
   startSponsoring() {
     this.operations.push(
       StellarSdk.Operation.beginSponsoringFutureReserves({
@@ -48,6 +67,10 @@ export class SponsoringBuilder extends CommonTransactionBuilder<SponsoringBuilde
     );
   }
 
+  /**
+   * Stop sponsoring the future reserves of an account.
+   * @returns {void}
+   */
   stopSponsoring() {
     this.operations.push(
       StellarSdk.Operation.endSponsoringFutureReserves({

package/src/walletSdk/Horizon/Transaction/TransactionBuilder.ts

@@ -2,10 +2,9 @@ import StellarSdk, {
   TransactionBuilder as StellarTransactionBuilder,
   Account as StellarAccount,
   Transaction,
-  Server,
+  Horizon,
   Memo,
   xdr,
-  Networks,
 } from "stellar-sdk";
 
 import { Config } from "walletSdk";
@@ -16,7 +15,7 @@ import {
   WithdrawalTxNotPendingUserTransferStartError,
   WithdrawalTxMemoError,
 } from "../../Exceptions";
-import { IssuedAssetId, StellarAssetId } from "../../Asset";
+import { StellarAssetId } from "../../Asset";
 import {
   WithdrawTransaction,
   TransactionStatus,
@@ -26,16 +25,30 @@ import { PathPayOnlyOneAmountError } from "../../Exceptions";
 import { CommonTransactionBuilder } from "./CommonTransactionBuilder";
 import { SponsoringBuilder } from "./SponsoringBuilder";
 
+/**
+ * Used for building transactions.
+ * Do not create this object directly, use the Stellar class to create a transaction.
+ * @class
+ */
 export class TransactionBuilder extends CommonTransactionBuilder<TransactionBuilder> {
   private cfg: Config;
   private builder: StellarTransactionBuilder;
 
+  /**
+   * Creates a new instance of the TransactionBuilder class for constructing Stellar transactions.
+   * @constructor
+   * @param {Config} cfg - Configuration object for Stellar operations.
+   * @param {StellarAccount} sourceAccount - The source account for the transaction.
+   * @param {number} [baseFee] - The base fee for the transaction. If not given will use the config base fee.
+   * @param {Memo} [memo] - The memo for the transaction.
+   * @param {Horizon.Server.Timebounds} [timebounds] - The timebounds for the transaction. If not given will use the config timebounds.
+   */
   constructor(
     cfg: Config,
     sourceAccount: StellarAccount,
     baseFee?: number,
     memo?: Memo,
-    timebounds?: Server.Timebounds,
+    timebounds?: Horizon.Server.Timebounds,
   ) {
     super(sourceAccount.accountId(), []);
     this.builder = new StellarTransactionBuilder(sourceAccount, {
@@ -49,9 +62,18 @@ export class TransactionBuilder extends CommonTransactionBuilder<TransactionBuil
     }
   }
 
+  /**
+   * Sponsoring a transaction.
+   * @param {AccountKeypair} sponsorAccount - The account doing the sponsoring.
+   * @param {(builder: SponsoringBuilder) => SponsoringBuilder} buildingFunction - Function for creating the
+   * operations that will be sponsored.
+   * @see {@link ./SponsoringBuilder.ts} or {@link ./CommonTransactionBuilder.ts} for operations that can be sponsored.
+   * @param {AccountKeypair} [sponsoredAccount] - The account that will be sponsored.
+   * @returns {TransactionBuilder} The transaction builder to build the transaction before submitting.
+   */
   sponsoring(
     sponsorAccount: AccountKeypair,
-    buildingFunction: (SponsoringBuilder) => SponsoringBuilder,
+    buildingFunction: (builder: SponsoringBuilder) => SponsoringBuilder,
     sponsoredAccount?: AccountKeypair,
   ): TransactionBuilder {
     new SponsoringBuilder(
@@ -63,6 +85,13 @@ export class TransactionBuilder extends CommonTransactionBuilder<TransactionBuil
     return this;
   }
 
+  /**
+   * Creates a Stellar account.
+   * @param {AccountKeypair} newAccount - The new account's keypair.
+   * @param {number} [startingBalance=1] - The starting balance for the new account (default is 1 XLM).
+   * @throws {InsufficientStartingBalanceError} If the starting balance is less than 1.
+   * @returns {TransactionBuilder} The TransactionBuilder instance.
+   */
   createAccount(
     newAccount: AccountKeypair,
     startingBalance: number = 1,
@@ -81,6 +110,13 @@ export class TransactionBuilder extends CommonTransactionBuilder<TransactionBuil
     return this;
   }
 
+  /**
+   * Adds a payment operation to transfer an amount of an asset to a destination address.
+   * @param {string} destinationAddress - The destination account's public key.
+   * @param {StellarAssetId} assetId - The asset to transfer.
+   * @param {string} amount - The amount to transfer.
+   * @returns {TransactionBuilder} The TransactionBuilder instance.
+   */
   transfer(
     destinationAddress: string,
     assetId: StellarAssetId,
@@ -98,19 +134,19 @@ export class TransactionBuilder extends CommonTransactionBuilder<TransactionBuil
 
   /**
    * Creates and adds a path payment operation to the transaction builder.
-   *
-   * @param {string} destinationAddress - The destination Stellar address to which the payment is sent.
-   * @param {StellarAssetId} sendAsset - The asset to be sent.
-   * @param {StellarAssetId} destAsset - The asset the destination will receive.
-   * @param {string} [sendAmount] - The amount to be sent. Must specify either sendAmount or destAmount,
+   * @param {PathPayParams} params - The path payment parameters.
+   * @param {string} params.destinationAddress - The destination Stellar address to which the payment is sent.
+   * @param {StellarAssetId} params.sendAsset - The asset to be sent.
+   * @param {StellarAssetId} params.destAsset - The asset the destination will receive.
+   * @param {string} [params.sendAmount] - The amount to be sent. Must specify either sendAmount or destAmount,
    * but not both.
-   * @param {string} [destAmount] - The amount to be received by the destination. Must specify either sendAmount or destAmount,
+   * @param {string} [params.destAmount] - The amount to be received by the destination. Must specify either sendAmount or destAmount,
    * but not both.
-   * @param {string} [destMin] - The minimum amount of the destination asset to be receive. This is a
+   * @param {string} [params.destMin] - The minimum amount of the destination asset to be receive. This is a
    * protective measure, it allows you to specify a lower bound for an acceptable conversion. Only used
    * if using sendAmount.
    * (optional, default is ".0000001").
-   * @param {string} [sendMax] - The maximum amount of the destination asset to be sent. This is a
+   * @param {string} [params.sendMax] - The maximum amount of the destination asset to be sent. This is a
    * protective measure, it allows you to specify an upper bound for an acceptable conversion. Only used
    * if using destAmount.
    * (optional, default is int64 max).
@@ -157,12 +193,10 @@ export class TransactionBuilder extends CommonTransactionBuilder<TransactionBuil
   /**
    * Swap assets using the Stellar network. This swaps using the
    * pathPaymentStrictReceive operation.
-   *
    * @param {StellarAssetId} fromAsset - The source asset to be sent.
    * @param {StellarAssetId} toAsset - The destination asset to receive.
    * @param {string} amount - The amount of the source asset to be sent.
    * @param {string} [destMin] - (Optional) The minimum amount of the destination asset to be received.
-   *
    * @returns {TransactionBuilder} Returns the current instance of the TransactionBuilder for method chaining.
    */
   swap(
@@ -181,16 +215,35 @@ export class TransactionBuilder extends CommonTransactionBuilder<TransactionBuil
     return this;
   }
 
+  /**
+   * Adds an operation to the transaction.
+   * @param {xdr.Operation} op - The operation to add.
+   * @returns {TransactionBuilder} The TransactionBuilder instance.
+   */
   addOperation(op: xdr.Operation): TransactionBuilder {
     this.builder.addOperation(op);
     return this;
   }
 
+  /**
+   * Add a memo for the transaction.
+   * @param {Memo} memo - The memo to add to the transaction.
+   * @returns {TransactionBuilder} The TransactionBuilder instance.
+   */
   setMemo(memo: Memo): TransactionBuilder {
     this.builder.addMemo(memo);
     return this;
   }
 
+  /**
+   * Add a transfer operation to the builder from a sep-24 withdrawal transaction.
+   * @param {WithdrawTransaction} transaction - The withdrawal transaction.
+   * @param {StellarAssetId} assetId - The asset ID to transfer.
+   * @throws {WithdrawalTxNotPendingUserTransferStartError} If the withdrawal transaction status is not pending_user_transfer_start.
+   * @throws {WithdrawalTxMissingMemoError} If the withdrawal transaction is missing a memo.
+   * @throws {WithdrawalTxMemoError} If there is an issue with the withdrawal transaction memo.
+   * @returns {TransactionBuilder} The TransactionBuilder instance.
+   */
   transferWithdrawalTransaction(
     transaction: WithdrawTransaction,
     assetId: StellarAssetId,
@@ -226,6 +279,26 @@ export class TransactionBuilder extends CommonTransactionBuilder<TransactionBuil
     );
   }
 
+  /**
+   * Merges account into a destination account.
+   * **Warning**: This operation will give full control of the account to the destination account,
+   * effectively removing the merged account from the network.
+   * @param {string} destination - The stellar account merging into.
+   * @param {string} [source] - Account that is being merged. If not given then will default to
+   * the TransactionBuilder source account.
+   * @returns {TransactionBuilder} The TransactionBuilder instance.
+   */
+  accountMerge(destination: string, source?: string): TransactionBuilder {
+    this.operations.push(
+      StellarSdk.Operation.accountMerge({ destination, source }),
+    );
+    return this;
+  }
+
+  /**
+   * Builds the Stellar transaction so can be submitted.
+   * @returns {Transaction} The built Stellar transaction.
+   */
   build(): Transaction {
     this.operations.forEach((op) => {
       this.builder.addOperation(op);

package/src/walletSdk/Horizon/index.ts

@@ -1,5 +1,6 @@
-export { PublicKeypair, SigningKeypair } from "./Account";
+export { AccountKeypair, PublicKeypair, SigningKeypair } from "./Account";
 export { AccountService } from "./AccountService";
 export { Stellar } from "./Stellar";
+export { CommonTransactionBuilder } from "./Transaction/CommonTransactionBuilder";
 export { TransactionBuilder } from "./Transaction/TransactionBuilder";
 export { SponsoringBuilder } from "./Transaction/SponsoringBuilder";

package/src/walletSdk/Recovery/AccountRecover.ts

@@ -0,0 +1,255 @@
+import { AxiosInstance } from "axios";
+import { Horizon, Transaction } from "stellar-sdk";
+
+import {
+  RecoveryServer,
+  RecoveryServerKey,
+  RecoveryServerMap,
+  RecoveryServerSigning,
+  RecoveryServerSigningMap,
+} from "walletSdk/Types";
+import {
+  LostSignerKeyNotFound,
+  NoDeviceKeyForAccountError,
+  NotAllSignaturesFetchedError,
+  RecoveryServerNotFoundError,
+  ServerRequestFailedError,
+  UnableToDeduceKeyError,
+} from "../Exceptions";
+import {
+  AccountKeypair,
+  PublicKeypair,
+  SponsoringBuilder,
+  Stellar,
+} from "../Horizon";
+
+/**
+ * Used for Account Recovery using Sep-30.
+ * @see {@link https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md}
+ * @class
+ */
+export abstract class AccountRecover {
+  protected stellar: Stellar;
+  protected httpClient: AxiosInstance;
+  protected servers: RecoveryServerMap;
+
+  /**
+   * Creates a new instance of the AccountRecover class.
+   * @constructor
+   * @param {Stellar} stellar - The stellar instance used to interact with Horizon server.
+   * @param {AxiosInstance} httpClient - The client used to make http calls.
+   * @param {RecoveryServerMap} servers - The recovery servers to use.
+   */
+  constructor(
+    stellar: Stellar,
+    httpClient: AxiosInstance,
+    servers: RecoveryServerMap,
+  ) {
+    this.stellar = stellar;
+    this.httpClient = httpClient;
+    this.servers = servers;
+  }
+
+  /**
+   * Sign transaction with recovery servers. It is used to recover an account using
+   * [SEP-30](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0030.md).
+   * @param {Transaction} transaction - The transaction with new signer to be signed by recovery servers.
+   * @param {AccountKeypair} account - The keypair of the account that will be recovered.
+   * @param {RecoveryServerSigningMap} serverAuth - The map of recovery servers to use.
+   * @returns {Transaction} - The transaction with recovery server signatures
+   * @throws {NotAllSignaturesFetchedError} when all recovery servers don't return signatures
+   */
+  async signWithRecoveryServers(
+    transaction: Transaction,
+    account: AccountKeypair,
+    serverAuth: RecoveryServerSigningMap,
+  ): Promise<Transaction> {
+    await Promise.all(
+      Object.keys(serverAuth).map((serverKey: RecoveryServerKey) =>
+        this.addRecoveryServerTxnSignature(transaction, account.publicKey, [
+          serverKey,
+          serverAuth[serverKey],
+        ]),
+      ),
+    );
+    return transaction;
+  }
+
+  /**
+   * Replace a lost device key with a new key.
+   * @param {AccountKeypair} account - The target account.
+   * @param {AccountKeypair} newKey - The key to replace the lost key with.
+   * @param {RecoveryServerSigningMap} serverAuth - A map of recovery servers to use.
+   * @param {AccountKeypair} [lostKey] - The lost device key. If not specified, try to deduce the key from the account signers list.
+   * @param {AccountKeypair} [sponsorAddress] - The sponsor address of the transaction. Please note that not all SEP-30 servers support signing sponsored transactions.
+   * @returns {Promise<Transaction>} The transaction with operations for replacing the device key.
+   */
+  async replaceDeviceKey(
+    account: AccountKeypair,
+    newKey: AccountKeypair,
+    serverAuth: RecoveryServerSigningMap,
+    lostKey?: AccountKeypair,
+    sponsorAddress?: AccountKeypair,
+  ): Promise<Transaction> {
+    const stellarAccount = await this.stellar
+      .account()
+      .getInfo({ accountAddress: account.publicKey });
+
+    let lost: AccountKeypair;
+    let weight: number;
+
+    if (lostKey) {
+      lost = lostKey;
+
+      const lostSigner = stellarAccount.signers.find(
+        ({ key }) => key === lost.publicKey,
+      );
+      if (!lostSigner) {
+        throw new LostSignerKeyNotFound();
+      }
+
+      weight = lostSigner.weight;
+    } else {
+      const deduced = this.deduceKey(stellarAccount, serverAuth);
+      lost = PublicKeypair.fromPublicKey(deduced.key);
+      weight = deduced.weight;
+    }
+
+    let transaction: Transaction;
+
+    const txBuilder = await this.stellar.transaction({
+      sourceAddress: account,
+    });
+
+    if (sponsorAddress) {
+      const buildingFunction = (builder: SponsoringBuilder) =>
+        builder.removeAccountSigner(lost).addAccountSigner(newKey, weight);
+
+      transaction = txBuilder
+        .sponsoring(sponsorAddress, buildingFunction)
+        .build();
+    } else {
+      transaction = txBuilder
+        .removeAccountSigner(lost)
+        .addAccountSigner(newKey, weight)
+        .build();
+    }
+
+    return this.signWithRecoveryServers(transaction, account, serverAuth);
+  }
+
+  protected getServer = (serverKey: RecoveryServerKey): RecoveryServer => {
+    const server = this.servers[serverKey];
+
+    if (!server) {
+      throw new RecoveryServerNotFoundError(serverKey);
+    }
+
+    return server;
+  };
+
+  /**
+   * Try to deduce the lost key. If any of these criteria match, one of the signers
+   * from the account will be recognized as the lost device key:
+   * 1. Only signer that's not in [serverAuth]
+   * 2. All signers in [serverAuth] have the same weight, and the potential signer is
+   * the only one with a different weight.
+   * @private
+   * @param {Horizon.ServerApi.AccountRecord} stellarAccount - The Stellar account to lookup existing signers on account.
+   * @param {RecoveryServerSigningMap} serverAuth - A map of recovery servers to use.
+   * @returns {Horizon.ServerApi.AccountRecordSigners} The deduced account signer.
+   * @throws {NoDeviceKeyForAccountError} When no existing ("lost") device key is found.
+   * @throws {UnableToDeduceKeyError} When no criteria match.
+   */
+  private deduceKey(
+    stellarAccount: Horizon.ServerApi.AccountRecord,
+    serverAuth: RecoveryServerSigningMap,
+  ): Horizon.ServerApi.AccountRecordSigners {
+    // Recovery servers addresses
+    const recoveryAddresses = Object.values(serverAuth).map(
+      ({ signerAddress }) => signerAddress,
+    );
+
+    // All signers on stellar account
+    const accountSigners = stellarAccount.signers;
+
+    // All signers on stellar account that are not recovery server
+    const nonRecoverySigners = accountSigners.filter(
+      ({ key, weight }) => !recoveryAddresses.includes(key) && weight > 0,
+    );
+
+    // Throws in case there is no signer other than the recovery signers
+    if (nonRecoverySigners.length === 0) {
+      throw new NoDeviceKeyForAccountError();
+    }
+
+    // If we have only 1 signer that's not a recovery signer deduce it
+    // as the lost key
+    if (nonRecoverySigners.length === 1) {
+      return nonRecoverySigners[0];
+    }
+
+    // If we have multiple signers that are not recovery signers:
+
+    // First get all signers on stellar account that are recovery server
+    const recoverySigners = accountSigners.filter(({ key }) =>
+      recoveryAddresses.includes(key),
+    );
+
+    // Check if all recovery signers have the same weight
+    const recoveryWeight = recoverySigners[0]?.weight || 0;
+    if (recoverySigners.find(({ weight }) => weight !== recoveryWeight)) {
+      throw new UnableToDeduceKeyError();
+    }
+
+    // Then in case we have only one non-recovery signer that has different
+    // weight deduce it as the lost key
+    const filtered = nonRecoverySigners.filter(
+      ({ weight }) => weight !== recoveryWeight,
+    );
+
+    if (filtered.length !== 1) {
+      throw new UnableToDeduceKeyError();
+    }
+
+    return filtered[0];
+  }
+
+  private async addRecoveryServerTxnSignature(
+    transaction: Transaction,
+    accountAddress: string,
+    recoveryAuth: [RecoveryServerKey, RecoveryServerSigning],
+  ): Promise<void> {
+    const [serverKey, auth] = recoveryAuth;
+
+    const server = this.getServer(serverKey);
+
+    const requestUrl = `${server.endpoint}/accounts/${accountAddress}/sign/${auth.signerAddress}`;
+
+    let signature: string;
+    try {
+      const resp = await this.httpClient.post(
+        requestUrl,
+        {
+          transaction: transaction.toXDR(),
+        },
+        {
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${auth.authToken.token}`,
+          },
+        },
+      );
+
+      signature = resp.data.signature;
+
+      if (!signature) {
+        throw new NotAllSignaturesFetchedError();
+      }
+    } catch (e) {
+      throw new ServerRequestFailedError(e);
+    }
+
+    transaction.addSignature(auth.signerAddress, signature);
+  }
+}