Beacon events in docs #2725

ac10n · 2023-11-09T16:05:26Z

Thank you for your contribution to Taquito.

Before submitting this PR, please make sure:

Your code builds cleanly without any errors or warnings
You have run the linter against the changes
You have added unit tests (if relevant/appropriate)
You have added integration tests (if relevant/appropriate)
All public methods or types have TypeDoc coverage with a complete description, and ideally an @example
You have added or updated corresponding documentation
If relevant, you have written a first draft summary describing the change for inclusion in Release Notes.

In this PR, please also make sure:

You have linked this PR to the issue by putting closes #TICKETNUMBER in the description box (when applicable)
You have added a concise description on your changes

Release Note Draft Snippet

If relevant, please write a summary of your change that will be suitable for
inclusion in the Release Notes for the next Taquito release.

netlify · 2023-11-09T16:05:31Z

✅ Deploy Preview for taquito-test-dapp ready!

Name	Link
🔨 Latest commit	`c20a4bf`
🔍 Latest deploy log	https://app.netlify.com/sites/taquito-test-dapp/deploys/6553cf7356b7d400083d01d7
😎 Deploy Preview	https://deploy-preview-2725--taquito-test-dapp.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

github-actions · 2023-11-09T16:08:21Z

New packages have been deployed to the preview repository at https://npm.preview.tezostaquito.io/.

Published packages:

npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/
npm i @taquito/[email protected] --registry https://npm.preview.tezostaquito.io/

github-actions · 2023-11-09T16:12:26Z

A new deploy preview is available on Netlify at https://c03714b--tezostaquito.netlify.app

dsawali · 2023-11-09T20:49:27Z

docs/wallet_API.md

+5. The wallet asks the user to confirm the connection.
+6. Now when the dApp wants to send an operation, it asks the wallet to sign it. This might need additional confirmation from the user, or the user might have setup their wallet to sign operations automatically (for instance, automatically sign transactions below a certain amount in a certain time frame).
+
+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 


this sentence seems incomplete(?)

hui-an-yang · 2023-11-09T22:35:54Z

docs/wallet_API.md

@@ -6,27 +6,27 @@ 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.


[preference] I find these sentences still valuable

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.

Agree. My problem with them is that they are things that make a lot of sense to someone who knows how blockchain ecosystem works, but does not create a clear picture for someone who's just learning. I like to avoid confusing the newcomers.

hui-an-yang · 2023-11-09T22:36:05Z

docs/wallet_API.md

@@ -6,27 +6,27 @@ 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, you have been using a signer to sign operations. For interactive dApps, it is common to use a wallet to sign operations. From a user's perspective, the workflow is as follows:


This seems an assumptions, fe dapp dev can skip entire contractAPI and directly pick up walletAPI

You have learned how to use Taquito to interact with the Tezos blockchain. Up to this document, you have been using a signer to sign operations.

👏 Love the addition of workflow explanation!

I kind-of had the assumption that anyone who reads this code, has at least read the quickstart (or knows most of it).

hui-an-yang · 2023-11-09T22:36:22Z

docs/wallet_API.md

-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, you have been using a signer to sign operations. For interactive dApps, it is common to use a wallet to sign operations. From a user's perspective, the workflow is as follows:
+
+1. The user has a wallet installed and configured on their device.


Unsure if this is necessary, beacon-kukai is an exception in this context it's web based with social log-in

Added additional info about that

hui-an-yang · 2023-11-09T22:36:24Z

docs/wallet_API.md

+
+1. The user has a wallet installed and configured on their device.
+2. The user visits a dApp and wants to interact with it.
+3. The dApp asks the user to connect their wallet.


I see more user actively click connect wallet from dApps

The dApp can technically ask the user to connect to wallet without any interaction from the user.
Even when we click "connect wallet" what happens is:

User is doing some interaction with the dApp

dApp asking the user to connect their wallet.

i think this makes more sense
2. The user visits a dApp
3. User takes action to interact with the dApp
4. dApp asking the user to connect their wallet.

yeah the dApp (through the wallet sdk) will more often than not, ask the user to connect their wallet. And on top of that, ask the user permission to connect to said wallet. Probably good to mention that in detail

hui-an-yang · 2023-11-09T22:36:31Z

docs/wallet_API.md

+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. Now when the dApp wants to send an operation, it asks the wallet to sign it. This might need additional confirmation from the user, or the user might have setup their wallet to sign operations automatically (for instance, automatically sign transactions below a certain amount in a certain time frame).


[preference] think this line is beyond the current scope of wallet api introduction

or the user might have setup their wallet to sign operations automatically (for instance, automatically sign transactions below a certain amount in a certain time frame).

Agree. Still think here is a good chance to let the reader know about this possibility.

If we don't have documentation on how to do that, I think we shouldn't mention it in the docs. Which I think is part of why An thinks it is out of scope

We don't have documentation for that, because it is in the responsibility of the wallet. I included it here, because I believe it adds value to the big picture.
But I will remove it because you both prefer it to be removed.

hui-an-yang · 2023-11-09T22:36:37Z

docs/wallet_API.md

+5. The wallet asks the user to confirm the connection.
+6. Now when the dApp wants to send an operation, it asks the wallet to sign it. This might need additional confirmation from the user, or the user might have setup their wallet to sign operations automatically (for instance, automatically sign transactions below a certain amount in a certain time frame).
+
+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 


This sentence seems unfinished

The private key never ...?

hui-an-yang · 2023-11-09T22:36:39Z

docs/wallet_API.md


 ## 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:

 ```
-npm install @taquito/taquito
-
+npm install @taquito/taquito @taquito/beacon-wallet @temple-wallet/dapp


I can see @taquito/beacon-wallet and @temple-wallet/dapp are installed separately in their own section

What's your suggestion?

i misread, this looks good

hui-an-yang · 2023-11-09T22:36:42Z

docs/wallet_API.md

-```
-
-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.


Think this paragraph is trying to explain different wallet packages (beacon/temple) dev can use to setup their walletProvider, found below sentence not relevant with beacon includes access to all extension, mobile and web wallets

Some wallets are browser extensions, while others are mobile apps or web wallets.

Let's say someone who has never tried web3 development is reading the docs. This step suggests that they need to setup a wallet, like what a user of their future dApp needs to do.

this context is that this step(setup wallet) is different for each wallet with the next sentence saying Some wallets are browser extensions, while others are mobile apps or web wallets. will mislead people that for browser, mobile, or web wallets you all need different set up

I think Ali's sentence here is fine. Maybe keep the example that Temple needs a browser extension to use properly.

(e.g. Temple needs the user to install a browser extension)

I understand and will respect if the team think it's fine to keep.
Just want to be clear I think this paragraph is about to initiate temple instance from temple library (development wallet) is different from initiating beacon instance from beacon library. I find mixing the scope of wallet libraries (temple/beacon) and wallet itself (temple/kukai/plenty/umami) is misleading all diff wallets needs a different set up.

@hui-an-yang I see your point. Yeah that is fair.

hui-an-yang · 2023-11-09T22:36:46Z

docs/wallet_API.md

@@ -80,7 +80,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


From beacon doc I found them dAppClient.subscribeToEvent() then requestPermission(). Might be helpful for user to see this paragraph about subscribe before line 80 of await wallet.requestPermissions();

I think allowing the user to incrementally build a mental model is useful: First let them know how we connect, then let them know they should subscribe to events.

the goal of subscribe to event change is to transition all users to start using them, if we don't give them the right order will defeat the purpose

I don't see any problems with including them in this part, it probably is better for consistency. Having one part mention the events, and the other not will send mixed messages to readers

but I also understand the separation since there's a section specifically for events

Added a comment that reminds the user that they should subscribe to events.

hui-an-yang · 2023-11-09T22:36:49Z

docs/wallet_API.md

@@ -728,3 +732,43 @@ In most cases, you want to use the Wallet API when you give the users of your da
 The Wallet API introduces a new method to process operation confirmations. Observables. When the dApp sends the operation to the wallet, the dApp will "listen" when the operation appears in a block. The Wallet API observable will "emit" a stream of events as they occur. Orphan/Uncle block detection is also surfaced when observing confirmations for an operation.

 The duties of a Wallet are much broader than the very narrow duty of signing operation byte sequences. That's one reason why we built the Wallet API. It offers a better user experience by doing less. It allows Wallets to carry out all the duties expected of a Wallet.
+
+## Subscribing to events


subscribing to events is a beacon client only thing, we might want to move this paragraph to above line 80 to give user correct workflow and not mistaken that it might also work for development wallet (temple package)

Moved it to a location that is beacon only

hui-an-yang · 2023-11-09T22:36:52Z

docs/wallet_API.md

+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"`. Currently the following events are supported:
+
+```


i think providing a link to beaconevent typedoc can save as the cost of maintaining when events grows and shrinks
https://typedocs.walletbeacon.io/enums/beaconevent.html

Good suggestion. Thanks

dsawali · 2023-11-14T18:19:17Z

docs/wallet_API.md

@@ -6,27 +6,27 @@ 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, you have been using a signer to sign operations. For interactive dApps, it is common to use a wallet to sign operations. From a user's perspective, the workflow is as follows:


While correct, this sentence kind of skips the context of what a wallet is. The previous explanation was a bit verbose, but I think it still gives an idea of what the wallets' roles are.

While we don't have a very clear definition of what a wallet's role is and should be, this sentence makes it sound like it's only distinction is to sign your operations. Which kind of discounts what a wallet can be.

I suggest keeping some of the info from the previous paragraph, but condensed into shorter form.

From my understanding, the fundamental reason we have wallets is that we want to avoid sharing our secrets with the dApps. Wallets provide additional functionality, like showing your balance, or history of transactions, but this is mostly convenience, rather than fundamental.

To create a simple mental model for the user, I would like to have this separation of responsibilities:

The blockchain decides what operations are valid, and keeps the data reliably

The dApp implements logic for the users to interact with

The wallet keeps the user's secrets (so that the user does not have to trust other tools like dApps).

Taquito simplifies the communication between the three above components

ac10n requested a review from dsawali November 9, 2023 16:05

ac10n requested a review from hui-an-yang November 9, 2023 16:05

ac10n force-pushed the beacon-events-in-docs branch 2 times, most recently from a918fcd to b39cef8 Compare November 9, 2023 17:23

dsawali reviewed Nov 9, 2023

View reviewed changes

hui-an-yang reviewed Nov 9, 2023

View reviewed changes

dsawali reviewed Nov 14, 2023

View reviewed changes

ac10n added 2 commits November 14, 2023 10:31

docs: small refactor, add section about events

6dbebb0

docs: apply suggestions from PR reviews

9dc5099

ac10n force-pushed the beacon-events-in-docs branch from 61c8d3e to 9dc5099 Compare November 14, 2023 18:31

ac10n added 2 commits November 14, 2023 11:43

make changes in response to PR comments

70a8d60

docs: added a previously removed paragraph

c20a4bf

dsawali approved these changes Nov 14, 2023

View reviewed changes

ac10n merged commit 082cfe0 into master Nov 14, 2023
11 of 12 checks passed

ac10n deleted the beacon-events-in-docs branch November 14, 2023 22:30

		@@ -6,27 +6,27 @@ 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.

Beacon events in docs #2725

Beacon events in docs #2725

Conversation

ac10n commented Nov 9, 2023

Release Note Draft Snippet

netlify bot commented Nov 9, 2023 • edited Loading

✅ Deploy Preview for taquito-test-dapp ready!

github-actions bot commented Nov 9, 2023 • edited Loading

Published packages:

github-actions bot commented Nov 9, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hui-an-yang Nov 9, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dsawali Nov 14, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

netlify bot commented Nov 9, 2023 •

edited

Loading

github-actions bot commented Nov 9, 2023 •

edited

Loading

github-actions bot commented Nov 9, 2023 •

edited

Loading

hui-an-yang Nov 9, 2023 •

edited

Loading

dsawali Nov 14, 2023 •

edited

Loading