@hashgraph/hedera-wallet-connect 1.0.6 → 1.2.0

package/README.md

@@ -65,6 +65,65 @@ reference the [WalletConnect documentation](https://docs.walletconnect.com/2.0/)
 Upon successfully configuring your dApp and/or wallet to manage WalletConnect sessions, you can
 use this library’s functions to easily create and handle requests for the Hedera network.
 
+### DApps
+
+#### Signer
+
+This library provides a `DAppSigner` class that implements the `@hashgraph/sdk`'s `Signer`
+interface. You may use the `DAppSigner` class to sign and execute transactions on the Hedera
+network.
+
+##### Get Signer
+
+After you have paired your wallet with your dApp, you can get the signer from the
+`DAppConnector` instance:
+
+```javascript
+const signer = dAppConnector.signers[0] // DAppSigner
+```
+
+Or, if multiple signers are available, you can find the signer by account ID:
+
+```javascript
+const signer = dAppConnector.signers.find(
+  (signer_) => signer_.getAccountId().toString() === '0.0.100',
+) // DAppSigner
+```
+
+##### Sign Transactions
+
+```javascript
+const transaction = new TransferTransaction()
+  .addHbarTransfer('0.0.100', new Hbar(-1))
+  .addHbarTransfer('0.0.101', new Hbar(1))
+
+await transaction.freezeWithSigner(signer)
+const signedTransaction = await signer.signTransaction(transaction)
+```
+
+##### Sign and Execute Transactions
+
+```javascript
+const transaction = new TransferTransaction()
+  .addHbarTransfer('0.0.100', new Hbar(-1))
+  .addHbarTransfer('0.0.101', new Hbar(1))
+
+await transaction.freezeWithSigner(signer)
+const transactionResponse = await transaction.executeWithSigner(signer)
+```
+
+##### Sign and verify messages
+
+```javascript
+const text = 'Example message to sign'
+const base64String = btoa(text)
+
+const sigMaps = await signer.sign([base64StringToUint8Array(base64String)]) // import { base64StringToUint8Array } from '@hashgraph/hedera-wallet-connect'
+
+// sigMaps[0].publicKey also contains the public key of the signer, but you should obtain a PublicKey you can trust from a mirror node.
+const verifiedResult = verifySignerSignature(base64String, sigMaps[0], publicKey) // import { verifySignerSignature } from '@hashgraph/hedera-wallet-connect'
+```
+
 ### Wallet
 
 This library provides a Wallet class that extends the
@@ -128,6 +187,67 @@ to approve or reject the session:
 Upon receiving a `session_request` event, process the request. For instance, if the dApp
 requests a transaction to be signed:
 
+#### Extension popup
+
+By default, it is not possible to directly pop up an extension with Wallet Connect. However, to
+allow this possibility, the dAppConnector look for extensions. If you create the AppConnector,
+it will automatically send a message to the extension to detect if it is installed. In case the
+extension is installed, it will be added to the available extensions and its data can be found
+at the extensions property of dAppConnector.
+
+To connect an available extension, use the method `connectExtension(<extensionId>)`. This will
+link the extension to the signer and session. Whenever you use the signer created for this
+session, the extension will automatically open. You can find out if the extension is available
+by checking the `extensions` property.
+
+```javascript
+const dAppConnector = new DAppConnector(
+  dAppMetadata,
+  LedgerId.TESTNET,
+  projectId,
+  Object.values(HederaJsonRpcMethod),
+  [HederaSessionEvent.ChainChanged, HederaSessionEvent.AccountsChanged],
+  [HederaChainId.Testnet]
+)
+
+[...]
+
+dAppConnector?.extensions?.forEach((extension) => {
+  console.log(extension)
+})
+
+const extension = dAppConnector?.extensions?.find((extension) => extension.name === '<Extension name>')
+if (extension.available) {
+  await dAppConnector!.connectExtension(extension.id);
+  const signer = dAppConnector.getSigner(AccountId.fromString('0.0.12345'))
+
+  // This request will open the extension
+  const response = await signer.signAndExecuteTransaction(transaction)
+}
+```
+
+Wallets that are compatible should be able to receive and respond to the following messages:
+
+- `"hedera-extension-query"`: The extension is required to respond with
+  `"hedera-extension-response"` and provide the next set of data in the metadata property.
+  ```javascript
+  let metadata = {
+    id: '<extesnionId>',
+    name: '<Wallet name>',
+    url: '<Wallet url>',
+    icon: '<Wallet con>',
+    description: '<Wallet url>',
+  }
+  ```
+- `"hedera-extension-open-<extensionId>"`: The extension needs to listen to this message and
+  automatically open.
+- `"hedera-extension-connect-<extensionId>"`: The extension must listen to this message and
+  utilize the `pairingString` property in order to establish a connection.
+
+This communication protocol between the wallet and web dApps requires an intermediate script to
+use the Chrome API. Refer to the
+[Chrome Extensions documentation](https://developer.chrome.com/docs/extensions/develop/concepts/messaging)
+
 ## Demo & docs
 
 This repository includes a vanilla html/css/javascript implementation with a dApp and wallet