Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Beacon events in docs #2725

Merged
merged 4 commits into from
Nov 14, 2023
Merged

Beacon events in docs #2725

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6dbebb0
docs: small refactor, add section about events
ac10n Nov 9, 2023
9dc5099
docs: apply suggestions from PR reviews
ac10n Nov 10, 2023
70a8d60
make changes in response to PR comments
ac10n Nov 14, 2023
c20a4bf
docs: added a previously removed paragraph
ac10n Nov 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/quick_start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
66 changes: 46 additions & 20 deletions docs/wallet_API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,27 +6,32 @@ 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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. 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. From a user's perspective, the workflow is as follows:

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.
3. The user takes action to interact with the dApp.
4. The dApp asks the user to connect their wallet.
5. The user selects their wallet.
6. The wallet asks the user to confirm the connection.
7. When the dApp wants to send an operation, it asks the wallet to sign it. This might need additional confirmation from the user.
8. 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.
9. The dApp can now wait for the operation to be confirmed.

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

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

```

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:

```
npm install @taquito/beacon-wallet

npm install @temple-wallet/dapp

npm install @taquito/taquito @taquito/beacon-wallet @temple-wallet/dapp
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's your suggestion?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i misread, this looks good

```

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 set up the wallet as the user. This step is different for each wallet (e.g., Temple needs the user to install a browser extension). 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

Expand Down Expand Up @@ -77,10 +82,15 @@ The necessary bare minimum to instantiate the wallet is an object with a `name`
The Beacon wallet requires an extra step to set up the network to connect to and the permissions:

```js
// TODO: subscribe to events, more information below
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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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();

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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:

Expand Down Expand Up @@ -117,6 +127,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).
Expand Down Expand Up @@ -187,12 +213,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}`);
Expand Down Expand Up @@ -247,7 +273,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:

Expand Down Expand Up @@ -711,7 +737,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
Expand Down
Loading