stellar-shade 0.0.1 → 0.0.2

package/dist/index.d.cts

@@ -45,17 +45,48 @@ interface WithdrawReceipt {
     /** Amount withdrawn in whole units */
     amount: number;
 }
+/**
+ * External transaction signer.
+ *
+ * Given the base64 XDR of a prepared transaction, return the base64 XDR of the
+ * signed transaction. This is exactly the shape of a browser wallet's signing
+ * call (e.g. Freighter's `signTransaction`), allowing the client to sign
+ * without ever handling a raw secret key.
+ */
+type TransactionSigner = (xdr: string, context: {
+    /** Network passphrase the transaction must be signed against. */
+    networkPassphrase: string;
+    /** The account expected to sign (public key, G...). */
+    address: string;
+}) => Promise<string>;
 /** Options for sending to a stealth address. */
 interface SendOpts {
     /** Asset to send. Default: native XLM. Format: "CODE:ISSUER" */
     asset?: string;
+    /**
+     * Sign with an external wallet instead of a raw secret key. When provided,
+     * the `senderSecret` argument of `send()` is treated as the sender's public
+     * key (G...) and is never used to sign.
+     */
+    signTransaction?: TransactionSigner;
 }
 /** Options for withdrawing from a stealth address. */
 interface WithdrawOpts {
     /** Stealth keys (need view + spend private keys) */
     keys: StealthKeys;
-    /** Secret key of account paying the Soroban invocation fee */
-    feePayer: string;
+    /**
+     * Secret key of the account paying the Soroban invocation fee.
+     * Optional when `signTransaction` + `feePayerAddress` are supplied instead.
+     */
+    feePayer?: string;
+    /**
+     * Sign the fee-payer side with an external wallet instead of `feePayer`.
+     * The stealth withdraw authorization is still produced internally from
+     * `keys`; only the transaction envelope signature is delegated.
+     */
+    signTransaction?: TransactionSigner;
+    /** Fee payer's public key (G...). Required when using `signTransaction`. */
+    feePayerAddress?: string;
     /** Relay URL for fee-bumped submission (privacy-preserving) */
     relay?: string;
     /** Asset to withdraw. Default: native XLM. Format: "CODE:ISSUER" */
@@ -121,12 +152,27 @@ declare class StealthClient {
      * Derives a one-time stealth address from the recipient's meta-address,
      * deposits tokens into the pool contract, and records the announcement.
      *
+     * Signing: by default the transaction is signed with `senderSecret` (a
+     * Stellar secret key). If `opts.signTransaction` is provided, signing is
+     * delegated to that external signer (e.g. a browser wallet) and the
+     * `senderSecret` argument is treated as the sender's public key instead.
+     *
      * @param metaAddress - Recipient's meta-address (st:stellar:... format)
      * @param amount - Amount in whole units (e.g. 100 = 100 XLM)
-     * @param senderSecret - Sender's Stellar secret key
-     * @param opts - Optional: asset to send
+     * @param senderSecret - Sender's secret key, or public key when using `opts.signTransaction`
+     * @param opts - Optional: asset to send, external signer
      */
     send(metaAddress: string, amount: number, senderSecret: string, opts?: SendOpts): Promise<SendReceipt>;
+    /**
+     * Sign a prepared transaction either with a local secret key (legacy path)
+     * or by delegating to an external signer that returns signed XDR.
+     *
+     * @param prepared - The prepared transaction to sign
+     * @param secretOrPublic - Secret key (local signing) or public key (external)
+     * @param publicKey - Signer's public key (G...)
+     * @param signer - Optional external signer; when present, no secret is used
+     */
+    private signTx;
     /**
      * Scan for stealth payments you received.
      *
@@ -156,4 +202,4 @@ declare class StealthClient {
     withdraw(stealthAddress: string, destination: string, opts: WithdrawOpts): Promise<WithdrawReceipt>;
 }
 
-export { type Balance, type ClientConfig, type Payment, type SendOpts, type SendReceipt, StealthClient, type StealthKeys, type WithdrawOpts, type WithdrawReceipt };
+export { type Balance, type ClientConfig, type Payment, type SendOpts, type SendReceipt, StealthClient, type StealthKeys, type TransactionSigner, type WithdrawOpts, type WithdrawReceipt };

package/dist/index.d.ts

@@ -45,17 +45,48 @@ interface WithdrawReceipt {
     /** Amount withdrawn in whole units */
     amount: number;
 }
+/**
+ * External transaction signer.
+ *
+ * Given the base64 XDR of a prepared transaction, return the base64 XDR of the
+ * signed transaction. This is exactly the shape of a browser wallet's signing
+ * call (e.g. Freighter's `signTransaction`), allowing the client to sign
+ * without ever handling a raw secret key.
+ */
+type TransactionSigner = (xdr: string, context: {
+    /** Network passphrase the transaction must be signed against. */
+    networkPassphrase: string;
+    /** The account expected to sign (public key, G...). */
+    address: string;
+}) => Promise<string>;
 /** Options for sending to a stealth address. */
 interface SendOpts {
     /** Asset to send. Default: native XLM. Format: "CODE:ISSUER" */
     asset?: string;
+    /**
+     * Sign with an external wallet instead of a raw secret key. When provided,
+     * the `senderSecret` argument of `send()` is treated as the sender's public
+     * key (G...) and is never used to sign.
+     */
+    signTransaction?: TransactionSigner;
 }
 /** Options for withdrawing from a stealth address. */
 interface WithdrawOpts {
     /** Stealth keys (need view + spend private keys) */
     keys: StealthKeys;
-    /** Secret key of account paying the Soroban invocation fee */
-    feePayer: string;
+    /**
+     * Secret key of the account paying the Soroban invocation fee.
+     * Optional when `signTransaction` + `feePayerAddress` are supplied instead.
+     */
+    feePayer?: string;
+    /**
+     * Sign the fee-payer side with an external wallet instead of `feePayer`.
+     * The stealth withdraw authorization is still produced internally from
+     * `keys`; only the transaction envelope signature is delegated.
+     */
+    signTransaction?: TransactionSigner;
+    /** Fee payer's public key (G...). Required when using `signTransaction`. */
+    feePayerAddress?: string;
     /** Relay URL for fee-bumped submission (privacy-preserving) */
     relay?: string;
     /** Asset to withdraw. Default: native XLM. Format: "CODE:ISSUER" */
@@ -121,12 +152,27 @@ declare class StealthClient {
      * Derives a one-time stealth address from the recipient's meta-address,
      * deposits tokens into the pool contract, and records the announcement.
      *
+     * Signing: by default the transaction is signed with `senderSecret` (a
+     * Stellar secret key). If `opts.signTransaction` is provided, signing is
+     * delegated to that external signer (e.g. a browser wallet) and the
+     * `senderSecret` argument is treated as the sender's public key instead.
+     *
      * @param metaAddress - Recipient's meta-address (st:stellar:... format)
      * @param amount - Amount in whole units (e.g. 100 = 100 XLM)
-     * @param senderSecret - Sender's Stellar secret key
-     * @param opts - Optional: asset to send
+     * @param senderSecret - Sender's secret key, or public key when using `opts.signTransaction`
+     * @param opts - Optional: asset to send, external signer
      */
     send(metaAddress: string, amount: number, senderSecret: string, opts?: SendOpts): Promise<SendReceipt>;
+    /**
+     * Sign a prepared transaction either with a local secret key (legacy path)
+     * or by delegating to an external signer that returns signed XDR.
+     *
+     * @param prepared - The prepared transaction to sign
+     * @param secretOrPublic - Secret key (local signing) or public key (external)
+     * @param publicKey - Signer's public key (G...)
+     * @param signer - Optional external signer; when present, no secret is used
+     */
+    private signTx;
     /**
      * Scan for stealth payments you received.
      *
@@ -156,4 +202,4 @@ declare class StealthClient {
     withdraw(stealthAddress: string, destination: string, opts: WithdrawOpts): Promise<WithdrawReceipt>;
 }
 
-export { type Balance, type ClientConfig, type Payment, type SendOpts, type SendReceipt, StealthClient, type StealthKeys, type WithdrawOpts, type WithdrawReceipt };
+export { type Balance, type ClientConfig, type Payment, type SendOpts, type SendReceipt, StealthClient, type StealthKeys, type TransactionSigner, type WithdrawOpts, type WithdrawReceipt };

package/dist/index.js

@@ -576,15 +576,20 @@ var StealthClient = class {
    * Derives a one-time stealth address from the recipient's meta-address,
    * deposits tokens into the pool contract, and records the announcement.
    *
+   * Signing: by default the transaction is signed with `senderSecret` (a
+   * Stellar secret key). If `opts.signTransaction` is provided, signing is
+   * delegated to that external signer (e.g. a browser wallet) and the
+   * `senderSecret` argument is treated as the sender's public key instead.
+   *
    * @param metaAddress - Recipient's meta-address (st:stellar:... format)
    * @param amount - Amount in whole units (e.g. 100 = 100 XLM)
-   * @param senderSecret - Sender's Stellar secret key
-   * @param opts - Optional: asset to send
+   * @param senderSecret - Sender's secret key, or public key when using `opts.signTransaction`
+   * @param opts - Optional: asset to send, external signer
    */
   async send(metaAddress, amount, senderSecret, opts) {
     if (amount <= 0) throw new Error("Amount must be positive");
     const { spendPubKey, viewPubKey } = decodeMetaAddress(metaAddress);
-    const senderKeypair = Keypair.fromSecret(senderSecret);
+    const senderPublicKey = opts?.signTransaction ? senderSecret : Keypair.fromSecret(senderSecret).publicKey();
     const tokenAddress = resolveTokenAddress(opts?.asset, this.networkPassphrase);
     const stroops = BigInt(Math.round(amount * 1e7));
     const ephemeralPrivKey = new Uint8Array(randomBytes(32));
@@ -594,14 +599,14 @@ var StealthClient = class {
       ephemeralPrivKey
     );
     const contract = new Contract(this.contractId);
-    const account = await this.server.getAccount(senderKeypair.publicKey());
+    const account = await this.server.getAccount(senderPublicKey);
     const depositTx = new TransactionBuilder(account, {
       fee: "100",
       networkPassphrase: this.networkPassphrase
     }).addOperation(
       contract.call(
         "deposit",
-        new StellarSdk.Address(senderKeypair.publicKey()).toScVal(),
+        new StellarSdk.Address(senderPublicKey).toScVal(),
         new StellarSdk.Address(tokenAddress).toScVal(),
         nativeToScVal(stroops, { type: "i128" }),
         nativeToScVal(Buffer.from(stealth.stealthPubKey)),
@@ -610,8 +615,13 @@ var StealthClient = class {
       )
     ).setTimeout(30).build();
     const prepared = await this.server.prepareTransaction(depositTx);
-    prepared.sign(senderKeypair);
-    const result = await this.server.sendTransaction(prepared);
+    const signed = await this.signTx(
+      prepared,
+      senderSecret,
+      senderPublicKey,
+      opts?.signTransaction
+    );
+    const result = await this.server.sendTransaction(signed);
     if (result.status === "ERROR") {
       throw new Error("Transaction submission failed");
     }
@@ -623,6 +633,27 @@ var StealthClient = class {
       txHash: result.hash
     };
   }
+  /**
+   * Sign a prepared transaction either with a local secret key (legacy path)
+   * or by delegating to an external signer that returns signed XDR.
+   *
+   * @param prepared - The prepared transaction to sign
+   * @param secretOrPublic - Secret key (local signing) or public key (external)
+   * @param publicKey - Signer's public key (G...)
+   * @param signer - Optional external signer; when present, no secret is used
+   */
+  async signTx(prepared, secretOrPublic, publicKey, signer) {
+    if (signer) {
+      const signedXdr = await signer(prepared.toXDR(), {
+        networkPassphrase: this.networkPassphrase,
+        address: publicKey
+      });
+      const tx = TransactionBuilder.fromXDR(signedXdr, this.networkPassphrase);
+      return tx;
+    }
+    prepared.sign(Keypair.fromSecret(secretOrPublic));
+    return prepared;
+  }
   /**
    * Scan for stealth payments you received.
    *
@@ -764,9 +795,15 @@ var StealthClient = class {
       nonce
     );
     const signature = signWithStealthKey(messageHash, stealthPrivKey);
-    const feePayerKeypair = Keypair.fromSecret(opts.feePayer);
+    if (!opts.signTransaction && !opts.feePayer) {
+      throw new Error("Provide either opts.feePayer or opts.signTransaction + opts.feePayerAddress");
+    }
+    if (opts.signTransaction && !opts.feePayerAddress) {
+      throw new Error("opts.feePayerAddress is required when using opts.signTransaction");
+    }
+    const feePayerPublicKey = opts.signTransaction ? opts.feePayerAddress : Keypair.fromSecret(opts.feePayer).publicKey();
     const contract = new Contract(this.contractId);
-    const feePayerAccount = await this.server.getAccount(feePayerKeypair.publicKey());
+    const feePayerAccount = await this.server.getAccount(feePayerPublicKey);
     const withdrawTx = new TransactionBuilder(feePayerAccount, {
       fee: "100",
       networkPassphrase: this.networkPassphrase
@@ -782,14 +819,19 @@ var StealthClient = class {
       )
     ).setTimeout(30).build();
     const prepared = await this.server.prepareTransaction(withdrawTx);
-    prepared.sign(feePayerKeypair);
+    const signedTx = await this.signTx(
+      prepared,
+      opts.feePayer ?? "",
+      feePayerPublicKey,
+      opts.signTransaction
+    );
     let txHash;
     if (opts.relay) {
       const url = opts.relay.endsWith("/relay") ? opts.relay : `${opts.relay}/relay`;
       const res = await fetch(url, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ xdr: prepared.toEnvelope().toXDR("base64") })
+        body: JSON.stringify({ xdr: signedTx.toEnvelope().toXDR("base64") })
       });
       if (!res.ok) {
         const err = await res.json();
@@ -798,7 +840,7 @@ var StealthClient = class {
       const data = await res.json();
       txHash = data.txHash;
     } else {
-      const result = await this.server.sendTransaction(prepared);
+      const result = await this.server.sendTransaction(signedTx);
       if (result.status === "ERROR") throw new Error("Transaction submission failed");
       if (result.status === "PENDING") {
         await waitForTransaction(this.server, result.hash);