Skip to content

Commit

Permalink
Update docs about Taquito (#469)
Browse files Browse the repository at this point in the history
  • Loading branch information
@timothymcmackin
timothymcmackin authored Nov 15, 2024
1 parent f0b3602 commit 0b2fcf1
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 58 deletions.
120 changes: 63 additions & 57 deletions docs/dApps/taquito.md
View file
Original file line number Diff line number Diff line change
@@ -1,80 +1,85 @@
---
title: Taquito dApp SDK for TypeScript
authors: Claude Barde
authors: Claude Barde, Tim McMackin
last_update:
date: 15 November 2023
date: 14 November 2024
---

## Introduction
[Taquito](https://tezostaquito.io) is a TypeScript library that dApp developers can use to get information about Tezos and submit transactions.
Many wallets in the Tezos ecosystem use the Taquito library.

Interacting with the Tezos blockchain can be done using the Tezos CLI. However, it is not suitable for dapps since it needs to be integrated into web interfaces.

Fortunately, the Tezos ecosystem offers libraries in several languages that enable developers to build efficient Dapps. _Taquito_ is one of these: it is a Typescript library developed and maintained by _ECAD Labs_. This library offers developers all of the everyday interactions with the blockchain: retrieving information about a Tezos network, sending a transaction, contract origination and interactions such as calling an entrypoint and fetching the storage, delegation, fetching metadata, etc.

A lot of wallets in the Tezos ecosystem also use the _Taquito_ library to function.

A full reference is available [here](https://tezostaquito.io/docs/quick_start).
A full reference is available in the [Taquito documentation](https://tezostaquito.io/docs/quick_start).

## Installation

The _Taquito_ library is made of several modules:
The Taquito library is made of several NPM modules:

- [@taquito/taquito](https://www.npmjs.com/package/@taquito/taquito): High-level functionalities that build upon the other packages in the Tezos Typescript Library Suite.
- [@taquito/taquito](https://www.npmjs.com/package/@taquito/taquito): High-level functionality that builds on the other packages in the Tezos Typescript Library Suite.
- [@taquito/ledger-signer](https://www.npmjs.com/package/@taquito/ledger-signer): Provides ledger signing functionality.
- [@taquito/rpc](https://www.npmjs.com/package/@taquito/rpc): Provides low-level methods and types to interact with an RPC node.
- [@taquito/utils](https://www.npmjs.com/package/@taquito/utils): Provides utility methods to verify Tezos-specific data and convert data types.
- [@taquito/michelson-encoder](https://www.npmjs.com/package/@taquito/michelson-encoder): Provides a JavaScript abstraction based on a Tezos smart contracts code, parameters and storage.
- [@taquito/michel-codec](https://www.npmjs.com/package/@taquito/michel-codec): Michelson parser/validator/formatter.
- [@taquito/michel-codec](https://www.npmjs.com/package/@taquito/michel-codec): Provides a Michelson parser/validator/formatter.
- [@taquito/local-forging](https://www.npmjs.com/package/@taquito/local-forging): Provides local forging functionality.
- [@taquito/signer](https://www.npmjs.com/package/@taquito/signer): Provides signing functionality.
- [@taquito/beacon-wallet](https://www.npmjs.com/package/@taquito/beacon-wallet): Provides a wrapper for the Beacon SDK.
- [@taquito/http-utils](https://www.npmjs.com/package/@taquito/http-utils): Provides http functionalities for Taquito.
- [@taquito/tzip12](https://www.npmjs.com/package/@taquito/tzip12): Provide TZIP-12 functionalities for Taquito.
- [@taquito/tzip16](https://www.npmjs.com/package/@taquito/tzip16): Provide TZIP-16 functionalities for Taquito.
- [@taquito/http-utils](https://www.npmjs.com/package/@taquito/http-utils): Provides HTTP functionality for Taquito.
- [@taquito/tzip12](https://www.npmjs.com/package/@taquito/tzip12): Provides TZIP-12 functionality for Taquito.
- [@taquito/tzip16](https://www.npmjs.com/package/@taquito/tzip16): Provides TZIP-16 functionality for Taquito.
- [@taquito/remote-signer](https://www.npmjs.com/package/@taquito/remote-signer): Remote signer provider.
- [@taquito/contracts-library](https://www.npmjs.com/package/@taquito/contracts-library): Allows to specify static data related to contracts (i.e., script and entrypoints) avoiding Taquito to fetch them from the network.
- [@taquito/contracts-library](https://www.npmjs.com/package/@taquito/contracts-library): Allows you to store static data related to contracts (such as scripts and entrypoints) to prevent Taquito from needing to fetch them from the network.

The main module is `@taquito/taquito`, it will be used for most actions. The other modules are used by the `@taquito/taquito` methods as complementary features, but can also be used separately.
The main module is `@taquito/taquito`; it is used for most actions.
The other modules are used by the `@taquito/taquito` methods as complementary features, but they can also be used separately.

You can install Taquito from NPM:

```shell
$ npm install @taquito/taquito
npm install @taquito/taquito
```

## Taquito configuration
## Tutorials

### General setup
For tutorials that include using Taquito, see:

- [Build a simple web application](tutorials/build-your-first-app)
- [Create a contract and web app that mints NFTs](/tutorials/create-an-nft/nft-taquito)
- [Mint NFTs from a web app](/tutorials/create-an-nft/nft-web-app)

We first need to configure _Taquito_ with an RPC URL (to communicate with a Tezos node).
## Taquito configuration

To do that we use the `TezosToolkit`: it is the "facade class that surfaces all of the libraries capability and allows its configuration". When instantiated, it requires an RPC URL.
### General setup

Here, we will use the _Ghostnet_ RPC URL offered for free by ECAD Labs at [https://ghostnet.ecadinfra.com](https://ghostnet.ecadinfra.com).
Like all Tezos clients, Taquito must be connected to an RPC node.
To connect Taquito to a node, create an instance of the `TezosToolkit` class, which is the façade class that surfaces the library's features, and pass the URL of the node.
For example, this code uses the public Ghostnet node at `https://rpc.ghostnet.teztnets.com`:

```typescript
import { TezosToolkit } from '@taquito/taquito'

const Tezos = new TezosToolkit('https://ghostnet.ecadinfra.com')
const Tezos = new TezosToolkit('https://rpc.ghostnet.teztnets.com')
```

### Wallet setup
### Connecting to wallets

First, download the `@taquito/beacon-wallet` and `@airgap/beacon-types` packages from NPM:
Taquito can connect to Tezos wallets through the Beacon protocol.
Follow these steps to connect to wallets in an application:

```
npm install @taquito/beacon-wallet @airgap/beacon-types
```
1. Install Taquito and the `@taquito/beacon-wallet` and `@airgap/beacon-types` packages from NPM:

```
npm install @taquito/taquito @taquito/beacon-wallet @airgap/beacon-types
```

Next, import the `BeaconWallet` class and create a new instance by passing an object with the different options required by the Beacon SDK.
1. Import the `BeaconWallet` class and create a new instance by passing an object with the different options required by the Beacon SDK.
After creating the instance of the wallet, you can request permission from the user to connect their wallet before passing the wallet instance to the wallet provider in the TezosToolkit provided by Taquito:

```typescript
import { BeaconWallet } from "@taquito/beacon-wallet";
import { NetworkType } from "@airgap/beacon-types";
import { TezosToolkit } from "@taquito/taquito";

const Tezos = new TezosToolkit('https://ghostnet.ecadinfra.com')
const Tezos = new TezosToolkit('https://rpc.ghostnet.teztnets.com')
const options = {
name: 'MyAwesomeDapp',
iconUrl: 'https://tezostaquito.io/img/favicon.svg',
Expand All @@ -89,13 +94,13 @@ Tezos.setWalletProvider(wallet)

## Getting data from the Tezos blockchain

Taquito provides methods to get different types of data from the Tezos blockchain, for example, the balance of a user account, the storage of a contract or token metadata.
Taquito provides methods to get different types of data from the Tezos blockchain, for example, the balance of a user account, the storage of a contract, or token metadata.

> Note: querying data from the blockchain doesn't create a new transaction.
### Getting the balance of an account

Taquito allows developers to get the current balance in tez of a user account. The `getBalance` method is available on the instance of the TezosToolkit and requires a parameter of type `string` that represents the address of the account.
Taquito allows developers to get the current balance in mutez of a user account. The `getBalance` method is available on the instance of the TezosToolkit and requires a parameter of type `string` that represents the address of the account.

The returned value is of type `BigNumber`:

Expand All @@ -104,7 +109,7 @@ import { TezosToolkit } from '@taquito/taquito'
import { BeaconWallet } from '@taquito/beacon-wallet'
import type { BigNumber } from 'bignumber.js'

const Tezos = new TezosToolkit('https://ghostnet.ecadinfra.com')
const Tezos = new TezosToolkit('https://rpc.ghostnet.teztnets.com')
const wallet = new BeaconWallet(OPTIONS)
await wallet.requestPermissions()
Tezos.setWalletProvider(wallet)
Expand All @@ -116,13 +121,11 @@ const balance: BigNumber = await Tezos.tz.getBalance(userAddress)

### Getting the storage of a contract

One of the distinctive features of the Tezos blockchain is having the storage of smart contracts publicly available.

Taquito provides an easy way to get the storage of any contract and exposes it as a JavaScript value:
Taquito provides an easy way to get the storage of any contract and exposes it as a JavaScript object:

```typescript
import { TezosToolkit } from '@taquito/taquito'
const Tezos = new TezosToolkit('https://ghostnet.ecadinfra.com')
const Tezos = new TezosToolkit('https://rpc.ghostnet.teztnets.com')
// creates the contract abstraction required to get the storage
const contract = await Tezos.wallet.at(CONTRACT_ADDRESS)
// returns the storage of the contract
Expand All @@ -131,14 +134,14 @@ const storage = await contract.storage()

### Getting token metadata

Taquito also provides a library to get token metadata, which can be very useful when you build a dapp that handles NFTs.
Without Taquito, you would have to fetch the location of the metadata from the contract, understand where the metadata is stored, fetch it and parse it. Taquito does all of that for you:
Taquito also provides a library to get token metadata, which can be very useful when you build a dApp that handles NFTs.
Without Taquito, you would have to fetch the location of the metadata from the contract, understand where the metadata is stored, fetch it, and parse it. Taquito does all of that for you, as in this example:

```typescript
import { TezosToolkit } from '@taquito/taquito'
import { Tzip12Module, tzip12 } from '@taquito/tzip12'

const Tezos = new TezosToolkit('https://ghostnet.ecadinfra.com')
const Tezos = new TezosToolkit('https://rpc.ghostnet.teztnets.com')
Tezos.addExtension(new Tzip12Module())

const contract = await Tezos.contract.at(CONTRACT_ADDRESS, tzip12)
Expand All @@ -147,16 +150,16 @@ const tokenMetadata = await contract.tzip12().getTokenMetadata(TOKEN_ID)

## Interacting with the Tezos blockchain

Taquito lets you interact with the Tezos blockchain in multiple ways, for example, by sending tez, originating new contracts, interacting with existing contracts or reading events emitted by a contract. Most of these interactions start with an instance of the `TezosToolkit`.
Taquito lets you interact with the Tezos blockchain in multiple ways, for example, by sending tez, originating new contracts, interacting with existing contracts or reading events emitted by a contract. Most of these interactions start with an instance of the `TezosToolkit` object.

### Sending tez

After creating an instance of the `TezosToolkit`, you can use the Contract API (for backend apps) or the Wallet API (for frontend apps) to access the `transfer` method and pass an object as a parameter with a `to` property for the recipient of the transfer and an `amount` property for the amount to be sent:
After creating an instance of the `TezosToolkit` object, you can use the Contract API (for backend apps) or the Wallet API (for frontend apps) to access the `transfer` method and pass an object as a parameter with a `to` property for the recipient of the transfer and an `amount` property for the amount to be sent:

```typescript
import { TezosToolkit } from '@taquito/taquito'

const Tezos = new TezosToolkit('https://ghostnet.ecadinfra.com')
const Tezos = new TezosToolkit('https://rpc.ghostnet.teztnets.com')
const op = await Tezos.contract.transfer({ to: ADDRESS, amount: 1 })
await op.confirmation()
```
Expand All @@ -168,7 +171,7 @@ The origination of a new contract is also possible through the Contract API or t
```typescript
import { TezosToolkit } from '@taquito/taquito'

const Tezos = new TezosToolkit('https://ghostnet.ecadinfra.com')
const Tezos = new TezosToolkit('https://rpc.ghostnet.teztnets.com')
const initialStorage = {
counter: 1,
admin: "tz1Me1MGhK7taay748h4gPnX2cXvbgL6xsYL"
Expand All @@ -185,14 +188,14 @@ const { contractAddress } = op

### Sending a contract call

One of the main features of your dapp is probably smart contract interactions.
One of the main features of your dApp is probably smart contract interactions.

After creating the contract abstraction for the contract you want to interact with, you can call one of the entrypoints available as a method on the `methods` property. The entrypoint method takes a parameter of the type expected by the contract and returns a contract call that can be executed by calling the `send` method:

```typescript
import { TezosToolkit } from '@taquito/taquito'

const Tezos = new TezosToolkit('https://ghostnet.ecadinfra.com')
const Tezos = new TezosToolkit('https://rpc.ghostnet.teztnets.com')

const contract = await Tezos.wallet.at(CONTRACT_ADDRESS)
const op = await contract.methods.mint(3).send()
Expand All @@ -201,14 +204,14 @@ await op.confirmation()

### Reading smart contract events

Contract events is a way for contracts to deliver event-like information to third-party (off-chain) applications. It can be emitted by using the `EMIT` instruction in Michelson.
[Events](/smart-contracts/events) are a way for contracts to deliver event-like information to third-party (off-chain) applications.

Taquito provides a simple way for users to subscribe to certain events on the blockchain via the `PollingSubscribeProvider`.
Taquito provides a simple way for users to subscribe to certain events on the blockchain via the `PollingSubscribeProvider` object.

```typescript
import { TezosToolkit, PollingSubscribeProvider } from '@taquito/taquito'

const Tezos = new TezosToolkit('https://ghostnet.ecadinfra.com')
const Tezos = new TezosToolkit('https://rpc.ghostnet.teztnets.com')

Tezos.setStreamProvider(
Tezos.getFactory(PollingSubscribeProvider)({
Expand All @@ -231,15 +234,15 @@ try {

## Best practices

### One single TezosToolkit instance
### One single `TezosToolkit` instance

You should make sure that you only have one instance of the `TezosToolkit` at all times in your app to avoid using the wrong one, which can have negative financial consequences for your users.
Even if your app requires a change in the network or Tezos node, it is better to create a new instance of the `TezosToolkit` and stop using the previous one to prevent unexpected behaviours.
You should make sure that you only have one instance of the `TezosToolkit` object at all times in your app to avoid using the wrong one, which can have negative financial consequences for your users.
Even if your app requires a change in the network or Tezos node, it is better to create a new instance of the `TezosToolkit` and stop using the previous one to prevent unexpected behaviors.

### Contract API vs Wallet API

The Contract API is better suited for backend applications that don't require the manual signing of transactions, while the Wallet API is better suited for frontend applications that will interact with the users' wallets.
The use of one or the other should be consistent within the same app to prevent unexpected behaviours.
The use of one or the other should be consistent within the same app to prevent unexpected behaviors.

### `methods` vs `methodsObject`

Expand All @@ -248,7 +251,10 @@ You can use `methods` to pass single parameters or simple pairs.

### Catching transaction errors

It is important to wrap contract calls and other transactions sent from the app inside a `try... catch` in order to handle transaction failures. Transactions fail more often than you think and you must handle it to provide visual feedback to your users and prevent unwanted behaviours like users clicking a button again even if the transaction already failed before.
It is important to wrap contract calls and other transactions sent from the app inside a `try... catch` block to handle transaction failures. You must handle failures to provide visual feedback to your users and prevent unwanted behaviors like users clicking a button again because the UI did not inform them that the previous attempt failed.

:::note More information
You can find more information about Taquito on the official website: [Taquito](https://tezostaquito.io/docs/quick_start)

For more information, see the [Taquito documentation](https://tezostaquito.io/docs/quick_start).

:::
3 changes: 2 additions & 1 deletion docs/tutorials/build-your-first-app/getting-information.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ Your application can use the Taquito library to access the storage for the contr
```

Like the `deposit` and `withdraw` functions, this function creates an object that represents the contract.
Then it retrieves the contract's storage and uses the `get` method to look up a value from the big-map.
Then it retrieves the contract's storage.,
In this case, the contract's storage is a [big-map](/smart-contracts/data-types/complex-data-types#big-maps), so Taquito represents it as a `BigMapAbstraction` object and the application uses the `get` method to look up a value from it.
If it does not find a value, it sets the user's balance to 0.
If it finds a value, it divides by 1 million because the contract stores values in mutez, which is 1 millionth of a tez.

Expand Down

0 comments on commit 0b2fcf1

Please sign in to comment.