@hashgraph/hedera-wallet-connect 2.0.4-canary.e767129.0 → 2.0.5-canary.7b24ac9.0

package/README.md

@@ -64,7 +64,7 @@ reviewing the [Reown docs](https://docs.reown.com/overview).
 1. Add Hedera dependencies to your project:
 
 ```sh
-npm install @hashgraph/hedera-wallet-connect@2.0.4-canary.3ca04e9.0 @hashgraph/sdk @walletconnect/modal
+npm install @hashgraph/hedera-wallet-connect @hashgraph/sdk @walletconnect/modal
 ```
 
 2. Initialize dApp Connector
@@ -211,6 +211,141 @@ createAppKit({
 - [Hedera Wallet Example by Hgraph](https://github.com/hgraph-io/hedera-wallet)
 - <em>[Add an example, demo, or tool here](https://github.com/hashgraph/hedera-wallet-connect/pulls)</em>
 
+# Multi-Signature Transactions
+
+Multi-signature (multi-sig) workflows allow multiple parties to sign a single transaction before it's executed on the Hedera network. This is commonly used for:
+
+- Treasury operations requiring approval from multiple parties
+- Escrow services
+- Joint accounts
+- Backend co-signing for additional security
+
+## Using `hedera_signTransaction` for Multi-Sig Workflows
+
+The `hedera_signTransaction` method allows you to collect a signature from a wallet without immediately executing the transaction. This signature can then be combined with additional signatures (such as from a backend service) before final execution.
+
+### Example: Frontend Wallet Signature + Backend Co-Signature
+
+This example demonstrates a common pattern where a user signs a transaction in their wallet, and then a backend service adds its signature before executing the transaction.
+
+#### Step 1: Create and Sign Transaction on Frontend
+
+```typescript
+import { DAppConnector, HederaJsonRpcMethod } from '@hashgraph/hedera-wallet-connect'
+import { TransferTransaction, Hbar, AccountId } from '@hashgraph/sdk'
+
+// Initialize your DAppConnector (see Getting Started section)
+const dAppConnector = new DAppConnector(/* ... */)
+
+// Create a transaction
+const transaction = new TransferTransaction()
+  .addHbarTransfer(userAccountId, new Hbar(-10))
+  .addHbarTransfer(recipientAccountId, new Hbar(10))
+  .setTransactionMemo('Multi-sig transfer')
+
+// Request signature from wallet (does NOT execute)
+const signer = dAppConnector.getSigner(userAccountId)
+const signedTransaction = await signer.signTransaction(transaction)
+
+// Convert signed transaction to bytes for transmission to backend
+const signedTransactionBytes = signedTransaction.toBytes()
+
+// Send to backend
+const response = await fetch('/api/execute-transaction', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    signedTransaction: Buffer.from(signedTransactionBytes).toString('base64'),
+  }),
+})
+
+const result = await response.json()
+console.log('Transaction executed:', result.transactionId)
+```
+
+#### Step 2: Add Backend Signature and Execute
+
+On your backend, use the `addSignatureToTransaction` utility to add your server's signature:
+
+```typescript
+import { Transaction, PrivateKey, Client } from '@hashgraph/sdk'
+import { addSignatureToTransaction } from '@hashgraph/hedera-wallet-connect'
+
+// Backend API endpoint
+app.post('/api/execute-transaction', async (req, res) => {
+  try {
+    // Reconstruct transaction from bytes
+    const signedTransactionBytes = Buffer.from(req.body.signedTransaction, 'base64')
+    const signedTransaction = Transaction.fromBytes(signedTransactionBytes)
+
+    // Load your backend private key (store securely!)
+    const backendPrivateKey = PrivateKey.fromStringED25519(process.env.BACKEND_PRIVATE_KEY)
+
+    // Add backend signature to the transaction
+    const fullySignedTransaction = await addSignatureToTransaction(
+      signedTransaction,
+      backendPrivateKey,
+    )
+
+    // Execute the fully signed transaction
+    const client = Client.forTestnet() // or Client.forMainnet()
+    client.setOperator(backendAccountId, backendPrivateKey)
+
+    const txResponse = await fullySignedTransaction.execute(client)
+    const receipt = await txResponse.getReceipt(client)
+
+    res.json({
+      success: true,
+      transactionId: txResponse.transactionId.toString(),
+      status: receipt.status.toString(),
+    })
+  } catch (error) {
+    console.error('Error executing transaction:', error)
+    res.status(500).json({ error: error.message })
+  }
+})
+```
+
+### Important Notes
+
+1. **Transaction Must Be Frozen**: Before signing, ensure your transaction is frozen.
+
+2. **Signature Order**: Signatures can be added in any order. Hedera validates that all required signatures are present when the transaction is executed.
+
+3. **Security Considerations**:
+   - Never expose backend private keys to the frontend
+   - Validate transaction contents on the backend before adding your signature
+   - Implement proper authentication and authorization
+   - Consider implementing transaction limits and approval workflows
+
+4. **Multiple Signatures**: You can add more than two signatures using the same pattern:
+
+```typescript
+// Add multiple signatures sequentially
+let signedTx = await addSignatureToTransaction(transaction, privateKey1)
+signedTx = await addSignatureToTransaction(signedTx, privateKey2)
+signedTx = await addSignatureToTransaction(signedTx, privateKey3)
+
+// Execute with all signatures
+await signedTx.execute(client)
+```
+
+5. **Threshold Keys**: For accounts with threshold key structures, ensure you collect enough signatures to meet the threshold requirement before execution.
+
+### Alternative: Using `hedera_signAndExecuteTransaction`
+
+If you don't need backend co-signing and want the wallet to execute the transaction immediately:
+
+```typescript
+// This signs AND executes in one call
+const result = await dAppConnector.signAndExecuteTransaction({
+  signerAccountId: `hedera:testnet:${userAccountId}`,
+  transactionList: transactionToBase64String(transaction),
+})
+```
+
+Use `hedera_signTransaction` when you need to collect multiple signatures. Use `hedera_signAndExecuteTransaction` when the wallet's signature alone is sufficient to execute the transaction.
+
 # Hedera Wallets
 
 - [Hashpack](https://hashpack.app/)
@@ -226,12 +361,10 @@ refer to how to send transactions to wallets using the `hedera:(mainnet|testnet)
 While minimal, the main breaking changes are:
 
 - remove WalletConnect v1 modals
-
   - these are very old, though in the spirit of semver, we kept the dependency until this
     library's v2 release
 
 - remove setting node id's within this library for transactions
-
   - initially, a transaction created by the Hedera Javascript SDK needed to have one or more
     consensus node ids set to be able to serialize into bytes, sent over a network, and
     deserialized by the SDK

package/dist/lib/dapp/DAppSigner.js

@@ -146,7 +146,15 @@ export class DAppSigner {
      * @returns transaction - `Transaction` object with signature
      */
     async signTransaction(transaction) {
-        const transactionBody = transactionToTransactionBody(transaction);
+        var _a, _b;
+        // Ensure transaction is frozen with node account IDs before signing
+        // This is required so the transaction can be executed later by any client
+        if (!transaction.isFrozen()) {
+            transaction.freezeWith(this._getHederaClient());
+        }
+        // Extract the first node account ID from the frozen transaction to preserve it in the transaction body
+        const nodeAccountId = (_b = (_a = transaction.nodeAccountIds) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : null;
+        const transactionBody = transactionToTransactionBody(transaction, nodeAccountId);
         if (!transactionBody)
             throw new Error('Failed to serialize transaction body');
         const transactionBodyBase64 = transactionBodyToBase64String(transactionBody);
@@ -158,9 +166,44 @@ export class DAppSigner {
             },
         });
         const sigMap = base64StringToSignatureMap(signatureMap);
-        const bodyBytes = base64StringToUint8Array(transactionBodyBase64);
-        const bytes = proto.Transaction.encode({ bodyBytes, sigMap }).finish();
-        return Transaction.fromBytes(bytes);
+        // Get the original transaction bytes to preserve the full transaction structure
+        // including all node account IDs
+        const originalTransactionBytes = transaction.toBytes();
+        const originalTransactionList = proto.TransactionList.decode(originalTransactionBytes);
+        // Add the signature to all transactions in the list
+        // Each transaction in the list corresponds to a different node
+        const signedTransactionList = originalTransactionList.transactionList.map((tx) => {
+            // Check if the transaction has signedTransactionBytes (frozen transactions)
+            if (tx.signedTransactionBytes) {
+                // Decode the SignedTransaction to access the bodyBytes and existing sigMap
+                const signedTx = proto.SignedTransaction.decode(tx.signedTransactionBytes);
+                const existingSigMap = signedTx.sigMap || proto.SignatureMap.create({});
+                // Merge the new signatures with existing signatures
+                const mergedSigPairs = [...(existingSigMap.sigPair || []), ...(sigMap.sigPair || [])];
+                // Create updated SignedTransaction with merged signatures
+                const updatedSignedTx = proto.SignedTransaction.encode({
+                    bodyBytes: signedTx.bodyBytes,
+                    sigMap: proto.SignatureMap.create({
+                        sigPair: mergedSigPairs,
+                    }),
+                }).finish();
+                return {
+                    signedTransactionBytes: updatedSignedTx,
+                };
+            }
+            else {
+                // Transaction has bodyBytes and sigMap at the top level (not frozen)
+                const existingSigMap = tx.sigMap || proto.SignatureMap.create({});
+                // Merge the new signatures with existing signatures
+                const mergedSigPairs = [...(existingSigMap.sigPair || []), ...(sigMap.sigPair || [])];
+                return Object.assign(Object.assign({}, tx), { sigMap: Object.assign(Object.assign({}, existingSigMap), { sigPair: mergedSigPairs }) });
+            }
+        });
+        // Encode the signed transaction list back to bytes
+        const signedBytes = proto.TransactionList.encode({
+            transactionList: signedTransactionList,
+        }).finish();
+        return Transaction.fromBytes(signedBytes);
     }
     async _tryExecuteTransactionRequest(request) {
         try {

package/dist/lib/shared/utils.d.ts

@@ -1,4 +1,4 @@
-import { AccountId, PublicKey, Transaction, LedgerId, Query, SignerSignature } from '@hashgraph/sdk';
+import { AccountId, PublicKey, PrivateKey, Transaction, LedgerId, Query, SignerSignature } from '@hashgraph/sdk';
 import { ProposalTypes, SessionTypes } from '@walletconnect/types';
 import { proto } from '@hashgraph/proto';
 /**
@@ -273,3 +273,8 @@ export declare const accountAndLedgerFromSession: (session: SessionTypes.Struct)
     network: LedgerId;
     account: AccountId;
 }[];
+/**
+ * Adds an additional signature to an already-signed transaction.
+ * Uses proto-level manipulation to preserve existing signatures.
+ */
+export declare function addSignatureToTransaction<T extends Transaction>(transaction: T, privateKey: PrivateKey): Promise<T>;

package/dist/lib/shared/utils.js

@@ -418,3 +418,44 @@ export const accountAndLedgerFromSession = (session) => {
         };
     });
 };
+/**
+ * Adds an additional signature to an already-signed transaction.
+ * Uses proto-level manipulation to preserve existing signatures.
+ */
+export async function addSignatureToTransaction(transaction, privateKey) {
+    const originalBytes = transaction.toBytes();
+    const originalList = proto.TransactionList.decode(originalBytes);
+    const firstTransaction = originalList.transactionList[0];
+    let bodyBytes;
+    if (firstTransaction.signedTransactionBytes) {
+        const signedTx = proto.SignedTransaction.decode(firstTransaction.signedTransactionBytes);
+        bodyBytes = signedTx.bodyBytes;
+    }
+    else {
+        bodyBytes = firstTransaction.bodyBytes;
+    }
+    const signature = await privateKey.sign(bodyBytes);
+    const publicKey = privateKey.publicKey;
+    const signedTransactionList = originalList.transactionList.map((tx) => {
+        const newSigPair = publicKey._toProtobufSignature(signature);
+        if (tx.signedTransactionBytes) {
+            const signedTx = proto.SignedTransaction.decode(tx.signedTransactionBytes);
+            const existingSigMap = signedTx.sigMap || proto.SignatureMap.create({});
+            const mergedSigPairs = [...(existingSigMap.sigPair || []), newSigPair];
+            const updatedSignedTx = proto.SignedTransaction.encode({
+                bodyBytes: signedTx.bodyBytes,
+                sigMap: proto.SignatureMap.create({ sigPair: mergedSigPairs }),
+            }).finish();
+            return { signedTransactionBytes: updatedSignedTx };
+        }
+        else {
+            const existingSigMap = tx.sigMap || proto.SignatureMap.create({});
+            const mergedSigPairs = [...(existingSigMap.sigPair || []), newSigPair];
+            return Object.assign(Object.assign({}, tx), { sigMap: Object.assign(Object.assign({}, existingSigMap), { sigPair: mergedSigPairs }) });
+        }
+    });
+    const signedBytes = proto.TransactionList.encode({
+        transactionList: signedTransactionList,
+    }).finish();
+    return Transaction.fromBytes(signedBytes);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashgraph/hedera-wallet-connect",
-  "version": "2.0.4-canary.e767129.0",
+  "version": "2.0.5-canary.7b24ac9.0",
   "description": "A library to facilitate integrating Hedera with WalletConnect",
   "repository": {
     "type": "git",