Beacon events in docs

docs/quick_start.md

@@ -49,6 +49,8 @@ Tezos.setProvider({
 });
 ```
 
+Alternatively, you can use a `WalletProvider` to interact with a wallet. Please refer to the [Wallet API](wallet_API.md) documentation for more information.
+
 ## Examples
 
 ### Get the current Tezos balance for an address

docs/wallet_API.md

@@ -6,27 +6,31 @@ author: Claude Barde
 
 ## What is the Wallet API?
 
-The Tezos blockchain is a fantastic tool, but it is self-contained. Except for the transactions you send to it, it has no interaction with the outside world. However, it would be amazing to interact with it, such as making payments, reading the balance of an account, or recording data in a smart contract. This interaction is what the Wallet API (and Taquito in general) achieves. The Wallet API provides a new yet familiar way to interact with the blockchain and smart contracts by delegating several actions that Taquito previously handled to the wallets. This delegation offers more flexibility for both developers and users and gives the ecosystem more space to evolve.
+You have learned how to use Taquito to interact with the Tezos blockchain. Up to this document, we used a signer to sign operations. Interactive dApps (short for "decentralized Apps") commonly use a wallet to sign operations. From a user's perspective, the workflow is as follows:
 
-## Installing the Wallet API
-
-The first thing to do is to use the wallet API is to install it. You just need to install the Taquito package to use the wallet API:
+1. The user has a wallet installed and configured on their device. (Or they might be using a web-based wallet)
+2. The user visits a dApp and wants to interact with it.
+3. The dApp asks the user to connect their wallet.
+4. The user selects their wallet.
+5. The wallet asks the user to confirm the connection.
+6. When the dApp wants to send an operation, it asks the wallet to sign it. This might need additional confirmation from the user, or they might have set up their wallet to sign operations automatically (for instance, automatically sign transactions below a certain amount in a certain time frame).
+7. There are two possibilities here:
+    1. The wallet signs the operation and sends (injects) it to the blockchain.
+    2. The wallet sends the signed operation to the dApp, and the dApp sends it to the network.
+8. The dApp can now wait for the operation to be confirmed.
 
-```
-npm install @taquito/taquito
+The main benefit of this workflow is that the user does not have to trust a dApp with their private key. The private key never leaves the wallet.
 
-```
+## Installing the Wallet API
 
-Once the package is downloaded, you can install the wallet of your choice. The wallet API supports different kinds of wallets. The _Beacon_ and _Temple_ wallets are available to use at the moment. You can install one or both wallets, depending on your requirements:
+The first thing to do is to use the wallet API is to install it. You just need to install the Taquito package to use the wallet API:
 
 ```
-npm install @taquito/beacon-wallet
-
-npm install @temple-wallet/dapp
-
+npm install @taquito/taquito @taquito/beacon-wallet @temple-wallet/dapp
 ```
 
-Remember that some wallets may require an extra step in addition to the package installation. For example, Temple must be used with an extension installed in the browser. We will explain the requirements for the different wallets in detail in the sections below.
+A separate step from setting up the wallet in the dApp code as a developer is to setup the wallet as the user. This step is different for each wallet. Some wallets are browser extensions, while others are mobile apps or web wallets.
+We will explain the requirements for the different wallets in detail in the sections below.
 
 ## Connecting the wallet
 
@@ -80,7 +84,11 @@ The Beacon wallet requires an extra step to set up the network to connect to and
 await wallet.requestPermissions();
 ```
 
-In previous versions of Beacon, you were able to set the `network` property when doing `requestPermissions()`. This behaviour was removed from Beacon, and you must now set the network when instantiating the wallet.
+:::note Subscribe to Events to be notified of changes in the wallet
+Please check out the section [Subscribing to events](#subscribing-to-events) to learn how to subscribe to events and be notified of changes in the wallet.
+:::
+
+In previous versions of Beacon, you were able to set the `network` property when doing `requestPermissions()`. This behavior was removed from Beacon, and you must now set the network when instantiating the wallet.
 
 You can choose among `mainnet`, `jakartanet` `ghostnet` and `custom` to set up the network. Once the permissions have been configured, you can get the user's address by calling the `getPKH` method on the wallet:
 
@@ -117,6 +125,22 @@ wallet
 Tezos.setWalletProvider(wallet);
 ```
 
+### Subscribing to events
+
+While your dApp is connected to the wallet, different events can happen on the wallet side. A reactive dApp can subscribe to these events and update the UI to create a good user experience.
+The different types of events are defined in the type `BeaconEvent` that can be imported from `"@airgap/beacon-sdk"`. Some of the events are: `ACTIVE_ACCOUNT_SET`, `PAIR_SUCCESS`, `SIGN_REQUEST_SUCCESS`.
+To see all possible events, please check out the [BeaconEvent in Beacon SDK documentation](https://typedocs.walletbeacon.io/enums/beaconevent.html).
+
+You can subscribe to any of these events as follows:
+
+```ts
+await wallet.client.subscribeToEvent(BeaconEvent.ACTIVE_ACCOUNT_SET, (data) => {
+  // logic to update the active account in your dApp's UI
+  console.log(data.address);
+});
+await wallet.requestPermissions();
+```
+
 ### - Development wallets
 
 During the development of your dapp, you may prefer a less "user-friendly" option that gives you more information and details than a more user-friendly wallet. You may also want to install and set up a wallet quickly that requires less boilerplate than the Beacon SDK. In these cases, use the Temple Wallet (for a quick setup using the Temple wallet extension).
@@ -187,12 +211,12 @@ Tezos.setProvider({ wallet });
 //import { TempleWallet } from '@temple-wallet/dapp';
 TempleWallet.isAvailable()
   .then(() => {
-    const mywallet = new TempleWallet('MyAwesomeDapp');
-    mywallet
+    const myWallet = new TempleWallet('MyAwesomeDapp');
+    myWallet
       .connect('ghostnet')
       .then(() => {
-        Tezos.setWalletProvider(mywallet);
-        return mywallet.getPKH();
+        Tezos.setWalletProvider(myWallet);
+        return myWallet.getPKH();
       })
       .then((pkh) => {
         println(`Your address: ${pkh}`);
@@ -247,7 +271,7 @@ Transactions to smart contracts operate in the same fashion as transactions to a
 
 ## Calling a smart contract
 
-Sending a transaction to a smart contract to update its storage will be a different type of action as it implies targetting a specific entrypoint and formatting correctly the data to be sent.
+Sending a transaction to a smart contract to update its storage will be a different type of action as it implies targeting a specific entrypoint and formatting correctly the data to be sent.
 
 Fortunately, Taquito will make this operation go like a breeze! First, you need the contract abstraction created with the address of the smart contract you are targeting:
 
@@ -711,7 +735,7 @@ const op = await Tezos.wallet.transfer({ to: 'tz1...', amount: 2 }).send();
 await op.confirmation();
 ```
 
-If you want to send a transaction to a contract, the process is very similar with the addition of the `parameter` property that must point to the entrypoint you are targetting and the value you want to pass:
+If you want to send a transaction to a contract, the process is very similar with the addition of the `parameter` property that must point to the entrypoint you are targeting and the value you want to pass:
 
 ```js
 const op = await Tezos.wallet