ecadlabs/taquito

Welcome, Web3 developer!

What is Taquito?

Taquito is a fast and lightweight TypeScript library to accelerate DApp development on the Tezos blockchain. With it, you can easily interact with Smart Contracts deployed to Tezos. It is distributed as a suite of individual npm packages, to reduce bloat and improve application startup times.

What about Smart Contract Development?

If you are a current or aspiring "full-stack" blockchain developer, be sure to check out Taquito's sister project Taqueria. Taqueria is a Developer Tool Suite with rich support for Smart Contract development and orchestration on Tezos, and fully compliments Taquito.

What is Included in Taquito?

Taquito is primarily targeted at Front-End Web3 developers, so it comes with batteries included, such as a React Template Project, an extensible framework, and many helpful utilities. It can be used in many execution contexts, including Serverless, Node.js, Deno, and Electron (to name a few) and has minimal dependencies.

Who uses Taquito?

Taquito is used by over 80% of DApps in the Tezos ecosystem. It is easy to use, proven secure and tested continuously against current versions of Tezos (both Mainnet and Testnets).

Why should I use Taquito?

Taquito provides convenient abstractions for a multitude of common operations, including wallet interactions (with WalletConnect2 in the works), batching operations, calling into contracts, querying the blockchain, and more. Taquito will isolate your code from subtle - and some not-so-subtle - changes made to the underlying Tezos protocol.

...Not to mention our thriving, helpful, and welcoming community!

Ok, I'm Ready!

To get started with Taquito quickly, visit the Taquito QuickStart.

If you prefer to start with a skeleton project, check out our Taquito React Template.

Do you wish to make a contribution to Taquito? See below, Contributing to Taquito.

Supported versions of Node

Taquito currently supports the following versions of Node.js®:

While other versions often work, the above are what we officially support. YMMV!

Community support channels

We are active and enthusiastic participants of the following community support channels:

• ECAD Labs Discord Channel
• Tezos StackExchange

Project Organization

Taquito is organized as a monorepo, and is composed of several npm packages that are published to npmjs.org under the @taquito handle. Each package has its own README which can be found in the corresponding directory within packages/.

API Documentation

TypeDoc API documentation for Taquito is available here.

Versioning Strategy

Supported versions of Taquito packages are maintained for the current and next (beta) protocol versions.

Taquito uses Semantic Versioning, (or, "SemVer") but with a small twist: the Major version number that we use tracks the latest version of Tezos (the Minor and Patch numbers do however follow SemVer norms).

For example, in a past release the protocol was at 004-..., and 005-... was being promoted through the on-chain amendment process (a feature unique to Tezos). So at that time, the current version for Taquito was v4.0.0, and work commenced on version v5.0.0-beta.1.

Release Timing

When it becomes clear that the next protocol proposal will be promoted, AND we have implemented and tested interoperability with the new protocol, we release the next version (v5.0.0-beta.1 in this example) BEFORE the chain transitions to the new protocol.

It is essential for updated packages to be released before the protocol changes, so that Taquito developers have time to update and test their projects.

During "Major" version updates, the Taquito public APIs MAY include breaking changes; we endeavor to make this clear, and document it in our release notes.

Note that all previous releases are backwards compatible with chain data, all the way back to the genesis protocol. Support for older Tezos node RPCs is maintained where feasible, but are eventually dropped.

We encourage you to update older versions of Taquito, and you are encouraged to contact us with any technical issues that preclude doing so.

Releases

Releases are pushed to npmjs.org and the Github releases page. The maintainers sign all official releases.

Releases (git tags and npm packages) are signed either by keybase/jevonearth or keybase/simrob. Releases that are not signed, or signed by other keys, should be brought to our attention immediately please.

Contributors Getting Started

You would like to make a contribution to Taquito? Wonderful! Please read on.

Setup and build the Taquito project

It is important to perform the following in the stated order

• Install libudev-dev, if developing on GNU/Linux:
  • For Ubuntu and other Debian-based distros: sudo apt-get install libudev-dev
  • For Fedora and other Redhat-based distros: sudo dnf install libudev-devel

This package contains low-level files required to compile against libudev-*.

• Install/use a suitable version of Node.js (as listed above), for example:

  nvm use lts/gallium

• Install lerna globally (used by our blazingly-fast nx-based build system):

  npm install --global lerna

Setup and build Taquito

Now that your prerequisites have been installed, run the following commands:

npm clean-install
...
npm run build
...

If all goes well, the last step is to run the unit tests, which should all pass:

npm run test

Build GOTCHAS!

• Do not delete node_modules/ manually, as this will confuse the build system

The taquito build system is based on nx, which uses caching extensively; please use npm run clean instead.

• Do not use npm install, as it will unnecessarily update package.json

The npm clean-install command (or just npm ci) produces a stable installation of all dependencies and respects package-lock.json. This will ensure a deterministic and repeatable build. It is also some 2x to 10x faster than npm install: hooray!

Useful npm command targets/scripts

See the top-level package.json "scripts" section. Common targets include:

• npm run clean: Recursively delete all build artifacts
• npm run test: Run the unit tests
• npm run build: Generate bundles, typings, and create TypeDocs for all packages
• npm run lint: Run the code linter (eslint)
• npm run example: Run an example Node.js app that demonstrates all functionality

Running Integration Tests

The Taquito integration tests are located in the integration-tests/ directory. Please see the README.md in that directory for further information.

Modifying Taquito source

After making your changes to Taquito, lint and run the unit test suite; this will let you know if your changes are working well with the rest of the project:

npm run lint
npm run test
npm run commit

Please use npm run commit for your last commit before you push, as this will automagically formulate the correct commit format. A final lint and test cycle will take place before the commit is performed.

Running the website locally

You may wish to contribute to the live code examples, this explains how to do that. Note that the Tezos Taquito website is built using Docusaurus.

To run the Taquito website in development mode locally, run the following commands from top-level:

• Run npm clean-install
• Run npm -w @taquito/website start

Contributions / Reporting Issues

Security Issues

To report a security issue, please contact [email protected] or via keybase/jevonearth on keybase.io. You can also encrypt your bug report using the keybase/jevonearth key.

Bug or Feature Requests

Please use our GitHub Issue Tracker to report bugs or request new features.

To contribute, please check the issue tracker to see if an existing issue exists for your planned contribution. If there's no issue, please create one first and then submit a pull request with your contribution.

For a contribution to be merged, it is required to have complete documentation, unit tests, and integration tests as appropriate. Submitting a "work in progress" pull request for review/feedback is always welcome!

Disclaimer

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE ARE ENTIRELY DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS OR ANY AFFILIATED PARTIES OR ENTITIES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. PERSONS USING THIS SOFTWARE DO SO ENTIRELY AT THEIR OWN RISK.

Credits

Special thanks to these libraries, which have been excellent references for developing Taquito

• https://github.com/AndrewKishino/sotez
• https://github.com/TezTech/eztz