Learn to build on Tezos with Figment Learn

Tezos 101

In many cases when a blockchain wants to change or upgrade its functionality, there are significant risks. Tezos is unique in that it is a “self-amending” blockchain: upgrades can be made automatically through its on-chain governance and user-submitted proposals. Tezos is also quite popular among artists and creators, for its community and collaborative nature.

Tezos

1 hour

1.5 hours

Beginner

Intermediate

JS/TS

Python

Native stablecoins

React

NodeJS

Smart contracts

IPFS

Next.js

Payment

Time Commitment

Difficulty

Programming Language

Feature

Technology

In this tutorial we will learn how to connect to a Tezos node via DataHub, using functions from the Taquito JavaScript library.

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/tezos/connect.ts`, implement the function and try to establish your first connection to the Tezos network. To verify that the connection has been made, try to return the chainId. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

```typescript
//...
  try {
    const url = getTezosUrl();
    const toolkit = undefined;
    const chainId = undefined;
    if (validateChain(chainId) != 3) {
      throw Error("invalid chain Id");
    }
    res.status(200).json(chainId);
  } 
//...
```

**Need some help?** Check out these links
* [**Class `TezosToolkit`**](https://tezostaquito.io/typedoc/classes/_taquito_taquito.tezostoolkit.html)
* [**Taquito**](https://tezostaquito.io/typedoc/modules.html)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
  try {
    const url = getTezosUrl();
    const toolkit = new TezosToolkit(url);
    const chainId = await toolkit.rpc.getChainId();
    if (validateChain(chainId) != 3) {
      throw Error("invalid chain Id");
    }
    res.status(200).json(chainId);
  } 
```

**What happened in the code above?**

* `getTezosUrl` is a helper function used to generate a valid endpoint URL.
* The `TezosToolkit` instance manages the connection.
* Unlike other blockchains, Tezos does not expose a software version for nodes. We will instead retrieve the Chain ID with `getChainId`.

------------------------

# Make sure it works

Once the code is complete and the file has been saved, refresh the page to see it update & display the Chain ID.

![](../../../.gitbook/assets/pathways/tezos/tezos-connect.gif)

-----------------------------

# Conclusion

Congratulations! You have connected to the Tezos blockchain and queried the chain ID with a few lines of JavaScript code. In the next tutorial, we will create an account for use on Florence, the Tezos testnet.


Learn how to connect to the Tezos network

Connect to Tezos node

# Introduction
Hey Reader! Welcome to this Tutorial on How to write, deploy & interact with a smart contract on Tezos in SmartPy. We will be learing a lot and having fun alongside!
You will be able to understand the industry standards of coding on SmartPy and be able to deploy your own Calculator Smart Contract whilist Understading the code as well.

- Tezos is an open-source blockchain protocol for assets and applications backed by a global community of validators, researchers, and builders. The Tezos protocol is secure, upgradable, and built to last.
- SmartPy is an intuitive and powerful smart contract development platform for Tezos and is available through a Python library for building and analyzing Tezos smart contracts.


# Prerequisites

To complete this tutorial, you will need a basic understanding of the Python programming language. Everything else will be explained, from getting XTZ from the faucet to coding and deployment.


# Requirements

You will need to have Temple Wallet Installed in your browser. Get it from https://templewallet.com/


# SmartPy IDE
SmartPy is a high-level smart contracts library and comes with related tools in the form of [SmartPy.io](https://smartpy.io/) to greatly ease the accessibility, understandability and provability of smart contracts on Tezos.

So head over to [SmartPy.io](https://smartpy.io/) and let us begin writing our first smart contract in Python!


![SmartPy](https://github.com/figment-networks/learn-tutorials/raw/master/assets/smartpy1.png)

For our purposes, the important links on this page are:
- [Online Editor](https://smartpy.io/ide)
- [Documentation](https://smartpy.io/docs/)

The Online Editor will help us write , execute and test our code before it is deployed on the blockchain and Documentation will help us with various DataStructures , Conditions , DataTypes and much more!

Click the Online Editor button to go to the IDE page:

![SmartPy](https://github.com/figment-networks/learn-tutorials/raw/master/assets/smartpy2_1.png)

Here SmartPy has provided us with various templates and sample contracts including games, token contracts and some basic utility contracts.
We will be coding our own version of a Calculator contract that is present as one of the examples.

Go Ahead and click on the **Close** button.

Before we start writing the code of the smart contract itself, we need to cover some of the basics:
We will be importing the SmartPy library and using it throughout the smart contract.

```python
import smartpy as sp
```
The functions of SmartPy can thereafter be called with the prefix `sp.`

Python does not support direct conversion of Python code to Michelson, so we will have to use functions present in SmartPy:
- sp.if
- sp.else
- sp.verify
- sp.for
- sp.while

You can read more about the usage of loops and conditions in SmartPy in the [Documentation](https://smartpy.io/docs/)

In SmartPy, smart contracts are essentially Python classes which have to be inherited from `sp.Contract` .
All the class attributes will be taken as the contract storage, and all the class methods will be considered as entrypoints of the contract which we can call from a front-end (client side) to change the state of the contract.

> **NOTE**: No change will take place in the contract unless called by the user via an entrypoint.

Now on to Coding our Contract:

Create a Python class that inherits the class `sp.Contract` and define its storage:

```python
class Calculator(sp.Contract):
    def __init__(self):
        self.init(value = 0)
```
Here we have defined a variable named *value* and set its initial value as 0.

As mentioned previously, Python does not support direct conversion of Python code to Michelson, so we use different data types as well. For example:
- sp.TInt 
- sp.TBool
- sp.TTimestamp
- TBytes

As well as Tezos specific data types like:
- sp.TAddress
- sp.TMutez
- sp.big_map

You can read more about all the types and why SmartPy uses type inference in the [Documentation](https://smartpy.io/docs/)

Moving on, we will define our first method (entrypoint). We have to write `@sp.entry_point` before we define a method so that the compiler knows that whatever code follows is an entrypoint:

```python
@sp.entry_point
    def add(self, x, y):
        self.data.value = x + y
```
The `add` function takes two parameters x and y and stores their sum in the variable we defined before: value, which is accessed by `self.data.value`.

With these concepts, we can create all the entrypoints needed for a Calculator contract:

- Subtract
```python
@sp.entry_point
    def subtract(self, x, y):
        self.data.value = sp.as_nat(x - y)
```

- Multiply
```python
@sp.entry_point
    def multiply(self, x, y):
        self.data.value = x * y
```

- Divide
```python
@sp.entry_point
    def divide(self, x, y):
        self.data.value = x / y
```

Now it's time to put all the entrypoints together and create our contract:

```python
import smartpy as sp

class Calculator(sp.Contract):
    def __init__(self):
        self.init(value = 0)

    @sp.entry_point
    def multiply(self, x, y):
        self.data.value = x * y

    @sp.entry_point
    def add(self, x, y):
        self.data.value = x + y

    @sp.entry_point
    def subtract(self, x, y):
        self.data.value = sp.as_nat(x - y)

    @sp.entry_point
    def divide(self, x, y):
        self.data.value = x // y

    @sp.entry_point
    def square(self, x):
        self.data.value = x * x

    @sp.entry_point
    def factorial(self, x):
        self.data.value = 1
        sp.for y in sp.range(1, x + 1):
            self.data.value *= y
```

You will notice that I have added two EntryPoints named `square` and `factorial`. These are to demonstrate how we do basic Python operations with SmartPy.

# Test Scenarios
Before we move on to deploying our contract on the Tezos network, we need to first make sure all of the code is working as we expect it to by testing it. Once deployed, smart contracts are immutable (and we do not want to waste our XTZ tokens).

Let's examine the concept of **test scenarios** :

Test scenarios are an important tool to make sure our smart contracts are working correctly.
- A new test is a method marked with `@sp.add_test`
- A new scenario is instantiated by `sp.test_scenario`.
- Scenarios describe a sequence of actions: originating contracts, computing expressions or calling entry points, etc.
- In the online editor of SmartPy.io, the scenario is computed and then displayed as an HTML document on the output panel.

Let's start by defining a method named `test()`:

```python
@sp.add_test(name = "Calculator")
    def test():
        pass
```
Now we need to instantiate (also known as originate) our smart contract and create a test scenario:

```python
@sp.add_test(name = "Calculator")
    def test():
        ob = Calculator()
        scenario = sp.test_scenario()
```

Now we can call all our entrypoints and see in the output panel if the value is being updated correctly:

```python
@sp.add_test(name = "Calculator")
    def test():
        ob = Calculator()
        scenario = sp.test_scenario()
        scenario.h1("Calculator")
        scenario += ob
        ob.multiply(x = 4, y = 2)
        ob.add(x = 4, y = 2)
        ob.subtract(x = 11, y = 5)
        ob.divide(x = 15, y = 3)
        ob.square(x = 3)
```

Now that the code has been tested and works properly, we will need to get some Tezos tokens on the testnet so that we can pay for deployment.

# Faucet and Temple Wallet
Before we can deploy anything, let's first get some Testnet ꜩ from the [Tezos Faucet](https://faucet.tzalpha.net/).

On the Faucet page, complete the CAPTCHA Verification and you will be given a faucet key, which looks like this:
![Faucet](https://github.com/figment-networks/learn-tutorials/raw/master/assets/faucet1.png)

Download and keep this JSON file in a secure location as it contains the secret key and mnemonic which will be used for deployment of the smart contract we have created.

Now Open your Temple Wallet and click **Settings** > **Import account**:

![Temple](https://github.com/figment-networks/learn-tutorials/raw/master/assets/temple1.png)

Now select Faucet File as the source and upload the JSON file you got from the faucet:

![Temple](https://github.com/figment-networks/learn-tutorials/raw/master/assets/temple2.png)

Now that we have a funded wallet on the Tezos testnet, we can move on to deploying the code.

# Deployment

Coming back to SmartPy.io:

```python
import smartpy as sp

class Calculator(sp.Contract):
    def __init__(self):
        self.init(value = 0)

    @sp.entry_point
    def multiply(self, x, y):
        self.data.value = x * y

    @sp.entry_point
    def add(self, x, y):
        self.data.value = x + y

    @sp.entry_point
    def subtract(self, x, y):
        self.data.value = sp.as_nat(x - y)

    @sp.entry_point
    def divide(self, x, y):
        self.data.value = x // y

    @sp.entry_point
    def square(self, x):
        self.data.value = x * x

    @sp.entry_point
    def factorial(self, x):
        self.data.value = 1
        sp.for y in sp.range(1, x + 1):
            self.data.value *= y
            
    @sp.add_test(name = "Calculator")
    def test():
        ob = Calculator()
        scenario = sp.test_scenario()
        scenario.h1("Calculator")
        scenario += ob
        ob.multiply(x = 4, y = 2)
        ob.add(x = 4, y = 2)
        ob.subtract(x = 11, y = 5)
        ob.divide(x = 15, y = 3)
        ob.square(3)
```
Go ahead and run this code in the SmartPy IDE (click on the "Play" button at the top left) and in the Output panel on the right side, you will see the option to **Deploy Michelson Contract**:

![Deploy](https://github.com/figment-networks/learn-tutorials/raw/master/assets/deploy1.png)

You will be be redirected to the Origination page of the contract. On this page we have to select on which Node we wish to deploy our contract. Check your Temple Wallet and the JSON you got from the faucet in the previous section and select the appropriate Node. Then Click on the Temple Wallet option and connect your wallet to SmartPy.io:

![Deploy](https://github.com/figment-networks/learn-tutorials/raw/master/assets/deploy2_1.png)

Scroll Down and click **Estimate Cost From RPC** and then click on **Deploy Contract**:

![Deploy](https://github.com/figment-networks/learn-tutorials/raw/master/assets/deploy3.png)

Then in the pop-up that appears click on **ACCEPT** and then Temple Wallet will open up and you will need to click on the **SIGN** button.

Once the transaction is confirmed, your contract will be deployed on the Granada testnet.

Copy the contract address as seen on the screen and wait for at least 3 block confirmations.

![Deploy](https://github.com/figment-networks/learn-tutorials/raw/master/assets/deploy4.png)

# Interacting with the contract

Now we are at the final step of this tutorial. We are going to learn how to explore our contract on-chain and how to interact with it.

Copy your contract address and head over to [Better Call Dev](https://better-call.dev/). Paste the contract address in the search box and press Enter.

![Interact](https://github.com/figment-networks/learn-tutorials/raw/master/assets/interact1.png)

You will now be able to see your contract details. If they do not appear, wait for a couple of minutes and then refresh the page as it takes some time for the block confirmations to arrive after you have deployed the contract.

![Interact](https://github.com/figment-networks/learn-tutorials/raw/master/assets/interact2.png)


On the **Interact** tab, you will be able to see all your available entrypoints there with the input parameters that we specified.

![Interact](https://github.com/figment-networks/learn-tutorials/raw/master/assets/interact3.png)

Now we will call our `add` EntryPoint!

1. Select **add** from the right-side pane (the list of entrypoints).
2. Put integer values in **x** and **y** fields.
3. Add your wallet address as the **source** and leave the **amount** field blank.

![Interact](https://github.com/figment-networks/learn-tutorials/raw/master/assets/interact4.png)

One of the best features of Better Call Dev is that we can simulate any transaction without having to spend any XTZ. So click on **EXECUTE** and choose **Simulate**. BetterCallDev will simulate the transaction and tell us if it is valid or will it fail and also what changes it will make to the contract's storage.

![Interact](https://github.com/figment-networks/learn-tutorials/raw/master/assets/interact5.png)


Now it is time to complete our first on-chain interaction!

This time, click on **EXECUTE** and Select **Temple - Tezos Wallet** instead of **Simulate**.

It will pop up your Temple Wallet and ask you to sign the transaction. It will also tell you the gas fee you are paying to complete the transaction:

![Interact](https://github.com/figment-networks/learn-tutorials/raw/master/assets/interact6.png)

Finally, go to the **Operations** tab on BetterCallDev and you will be able to see your transaction and all of its details:

![Interact](https://github.com/figment-networks/learn-tutorials/raw/master/assets/interact7.png)

As we can see our transaction changed the **value** in storage to the sum of the parameters we supplied to the `add` entrypoint (i.e. 5 + 11 = 16).


# Conclusion

In this Tutorial we learned about coding in SmartPy, how to get testnet XTZ from the faucet, how to deploy a contract on the blockchain and how to interact with the contract using a block explorer. We also saw how our entrypoints can change a contract's storage.

# Next Steps

I would like for you to try out all the entrypoints that we have created and check what changes they make to the storage! Once you are comfortable with this basic contract you can go about creating more complex contracts, NFT tokens and much more.

# About The Author

This tutorial was written by Udit Kapoor, who is a Tezos India 2.0 Fellow and a blockchain enthusiast. Their signature project is CryptoWill and they like to dabble in Flutter as well! Reach out to Udit on [GitHub](https://github.com/Udit-Kapoor) and you can find them on Discord as user **pichkari#56**.

# References

- Calculator example code from SmartPy.io
- [OpenTezos](https://opentezos.com/)



Learn how to write, deploy & interact with a smart contract on Tezos, using SmartPy.

Using the SmartPy IDE to write and deploy smart contracts on Tezos

Now that we have our account created, wouldn’t it be nice to keep track of our **tez** balance? In this step, we will examine how we can do just that!

{% hint style="info" %}
The native token on the **Tezos Blockchain** is **tez** indicated by the **ꜩ** symbol.
{% endhint %}

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/tezos/balance.ts`, implement the function and try to return the current balance of the account. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const { address } = req.body;
    const url = getTezosUrl();
    const toolkit = new TezosToolkit(url);
    const balance = undefined;
    res.status(200).json(balance.toString());
  }
//...
```

**Need some help?** Check out these links
* [**method `getBalance`**](https://tezostaquito.io/typedoc/interfaces/_taquito_taquito.tzprovider.html#getbalance)
* [**Get the current Tezos balance for an address`**](https://tezostaquito.io/docs/quick_start/#get-the-current-tezos-balance-for-an-address)

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const { address } = req.body;
    const url = getTezosUrl();
    const toolkit = new TezosToolkit(url);
    const balance = await toolkit.tz.getBalance(address);
    res.status(200).json(balance.toString());
  }
//...
```

**What happened in the code above?**

* First, we create a new `TezosToolkit` instance.
* Next, we call the `getBalance` method of the `tz` module, passing the address of the account we want to know the balance of.


{% hint style="tip" %}
The amount returned by `getBalance` is denominated in **μꜩ** (mutez), so to convert it to **ꜩ** you'll need to divide it by 10**6 
{% endhint %}


------------------------

# Make sure it works

Once the code is complete and the file is saved, Next.js will rebuild the API route. Click on **Check Balance** and you should see the balance displayed on the page:

![](../../../.gitbook/assets/pathways/tezos/tezos-balance.gif)

-----------------------------

# Conclusion

Querying the balance information is fun, but being able to submit transactions and change the state of a blockchain is even better! In the next step, we will dive deeper and submit our first transactions on Tezos.


Check the account balance

A faucet is a way for users to acquire some amount of tokens on a blockchain, typically on a test network, such as the Florence testnet for Tezos. The tokens from the faucet we will be using in this step are not equivalent to the tez on mainnet - there is a difference in how the accounts are derived. 

Take all available precautions when dealing with crypto assets. Keeping mnemonic seed phrases and private cryptographic keys safe is an important consideration when dealing with any blockchain, Tezos is no exception. 

{% hint style="info" %}
Visit the [faucet](https://faucet.tzalpha.net/) to generate a mnemonic and get some testnet ꜩ (tez).
{% endhint %} 

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/tezos/account.ts`, implement the function and try to activate your first account on the Tezos network. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const { mnemonic, email, password, secret } = req.body;
    const url = getTezosUrl();
    const tezos = new TezosToolkit(url);

    // call the importKey method
    undefined;

    res.status(200).json('Activation of the account ok');
  }
//...
```

**Need some help?** Check out these links
* [**method `importKey`**](https://tezostaquito.io/typedoc/modules/_taquito_signer.html#importkey)
* [**Importing a Faucet Key**](https://tezostaquito.io/docs/quick_start/#importing-a-faucet-key)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const { mnemonic, email, password, secret } = req.body
    const url = getTezosUrl();
    const tezos = new TezosToolkit(url);

    await importKey(
      tezos,
      email,
      password,
      mnemonic,
      secret
    )

    res.status(200).json('Activation of the account ok');
  }
//...
```

**What happened in the code above?**

* First, we create a new `TezosToolkit` instance.
* Next, we call the `importKey` method in order to activate the account.

------------------------

# Make sure it works

Once the code is complete and the file has been saved:
* Copy/paste the faucet information
* Click on **Feed the storage**
* Click on **Activate account**

![](../../../.gitbook/assets/pathways/tezos/tezos-account.gif)

-----------------------------

# Conclusion

Nice work! You now have a Tezos account on the Florence testnet. In the next tutorial, we will query a Tezos node using DataHub, to determine the current balance of our account.


Create a Tezos account

[**The original tutorial can be found in the Tezos documentation here**](https://assets.tqtezos.com/docs/oracle/). 

# Introduction

Smart contracts that require blockchain-external realtime data or events require a trusted _oracle_, i.e. a trusted smart contract that provides the data on-chain.

What is it useful for?

* An oracle that provides XTZ/USD prices could allow users to deposit funds that are immediately converted to some on-chain asset and represented as fiat.
* An oracle that provides weather data could allow a tsunami insurance contract: users purchase coverage from the contract, which pays out when there's a sufficiently severe tsunami in their area
* A combination of different oracles could be used to provide consensus, for example, where only results published by a majority of the oracles are considered valid.

# Setup

* Follow instructions in [Client Setup](https://assets.tqtezos.com/docs/setup/1-tezos-client) to set up `tezos-client` and create a test network wallet
* Clone [`lorentz-contract-oracle` repo](https://github.com/tqtezos/lorentz-contract-oracle) from GitHub and build from source using `stack`.

# The CLI

```text
❯❯❯ lorentz-contract-oracle Oracle --help
Usage: lorentz-contract-oracle Oracle COMMAND
  Oracle contract CLI interface

Available options:
  -h,--help                Show this help text

Available commands:
  print                    Dump the Oracle contract in form of Michelson code
  print-timestamped        Dump the Timestamped Oracle contract in form of
                           Michelson code
  init                     Initial storage for the Oracle contract
  get-value                get value
  update-value             update value
  update-admin             update admin
```

# Originating the contract

## Printing the contract

The print command takes a single argument: `valueType`, the type of the value provided by the oracle.

Note: Until [Issue \#6](https://github.com/tqtezos/lorentz-contract-oracle/issues/6) in the repo is fixed, the CLI tool will throw an error if `valueType` is _not_ `nat` when printing the contract or the `timestamped` version.

For example, if `nat`'s are provided:

```text
❯❯❯ lorentz-contract-oracle Oracle print --valueType "nat"

parameter (or (pair %getValue unit
                              (contract nat))
              (or (nat %updateValue)
                  (address %updateAdmin)));
storage (pair nat
              address);
code { CAST (pair (or (pair unit (contract nat)) (or nat address)) (pair nat address));
       DUP;
       CAR;
       DIP { CDR };
       IF_LEFT { DUP;
                 CAR;
                 DIP { CDR };
                 DIP { DIP { DUP };
                       SWAP };
                 PAIR;
                 CDR;
                 CAR;
                 DIP { AMOUNT };
                 TRANSFER_TOKENS;
                 NIL operation;
                 SWAP;
                 CONS;
                 PAIR }
               { IF_LEFT { DIP { DUP;
                                 CAR;
                                 DIP { CDR } };
                           DIP { DROP;
                                 DUP;
                                 DIP { SENDER;
                                       COMPARE;
                                       EQ;
                                       IF {  }
                                          { PUSH string "only admin may update";
                                            FAILWITH } } };
                           PAIR;
                           NIL operation;
                           PAIR }
                         { DIP { DUP;
                                 CAR;
                                 DIP { CDR };
                                 DIP { SENDER;
                                       COMPARE;
                                       EQ;
                                       IF {  }
                                          { PUSH string "only admin may update";
                                            FAILWITH } } };
                           SWAP;
                           PAIR;
                           NIL operation;
                           PAIR } } };
```

## Initial storage

```text
❯❯❯ lorentz-contract-oracle Oracle init --help
Usage: lorentz-contract-oracle Oracle init --initialValueType Michelson Type
                                           --initialValue Michelson Value
                                           --admin ADDRESS
  Initial storage for the Oracle contract

Available options:
  -h,--help                Show this help text
  --initialValueType Michelson Type
                           The Michelson Type of initialValue
  --initialValue Michelson Value
                           The Michelson Value: initialValue
  --admin ADDRESS          Address of the admin.
  -h,--help                Show this help text
```

Since we're using `nat`, `initialValueType` is `nat` and `initialValue` can be `0`:

```text
❯❯❯ lorentz-contract-oracle Oracle init \
  --initialValueType "nat" \
  --initialValue 3 \
  --admin $ALICE_ADDRESS
Pair 3 "tz1R3vJ5TV8Y5pVj8dicBR23Zv8JArusDkYr"
```

## Running the origination

> **NOTE:** to use the annotated $timestamped$ version, e.g. for `nat`:

```text
❯❯❯ tezos-client --wait none originate contract NatOracle \
  transferring 0 from $ALICE_ADDRESS running \
  "$(lorentz-contract-oracle Oracle print-timestamped --valueType "nat")" \
  --init "$(lorentz-contract-oracle Oracle init \
  --initialValueType "pair timestamp nat" --initialValue 'Pair "2019-12-10T17:43:53Z" 26871' \
  --admin $ALICE_ADDRESS)" --burn-cap 0.859 --force
```

> **NOTE:** the `nat_oracle.tz` contract may be found [here](https://github.com/tqtezos/lorentz-contract-oracle/blob/master/nat_oracle.tz)

Otherwise:

```text
❯❯❯ tezos-client --wait none originate contract NatOracle \
  transferring 0 from $ALICE_ADDRESS running \
  "$(lorentz-contract-oracle Oracle print --valueType "nat")" \
  --init "$(lorentz-contract-oracle Oracle init \
  --initialValueType "nat" --initialValue 3 \
  --admin $ALICE_ADDRESS)" --burn-cap 0.612

Waiting for the node to be bootstrapped before injection...
Current head: BLE8kx6VhXbk (timestamp: 2020-04-03T15:28:43-00:00, validation: 2020-04-03T15:29:02-00:00)
Node is bootstrapped, ready for injecting operations.
Estimated gas: 20483 units (will add 100 for safety)
Estimated storage: 683 bytes added (will add 20 for safety)
Operation successfully injected in the node.
Operation hash is 'onsEwbbm71wpzgnk6baBGacDzsnKceypEL841STJ6B5V9cA4swr'
NOT waiting for the operation to be included.
Use command
  tezos-client wait for onsEwbbm71wpzgnk6baBGacDzsnKceypEL841STJ6B5V9cA4swr to be included --confirmations 30 --branch BLE8kx6VhXbka6FGjXmKxnH56iypJLYZ9pM5mM3HLKvoVDBiMeS
and/or an external block explorer to make sure that it has been included.
This sequence of operations was run:
  Manager signed operations:
    From: tz1bDCu64RmcpWahdn9bWrDMi6cu7mXZynHm
    Fee to the baker: ꜩ0.002729
    Expected counter: 623928
    Gas limit: 20583
    Storage limit: 703 bytes
    Balance updates:
      tz1bDCu64RmcpWahdn9bWrDMi6cu7mXZynHm ............. -ꜩ0.002729
      fees(tz1Ke2h7sDdakHJQh8WX4Z372du1KChsksyU,154) ... +ꜩ0.002729
    Origination:
      From: tz1bDCu64RmcpWahdn9bWrDMi6cu7mXZynHm
      Credit: ꜩ0
      Script:
        {...}
        Initial storage: (Pair 3 "tz1R3vJ5TV8Y5pVj8dicBR23Zv8JArusDkYr")
        No delegate for this contract
        This origination was successfully applied
        Originated contracts:
          KT1LVLUsC1WCo4yHzeoDEE8FxxoC7EW6bSyp
        Storage size: 426 bytes
        Paid storage size diff: 426 bytes
        Consumed gas: 20483
        Balance updates:
          tz1bDCu64RmcpWahdn9bWrDMi6cu7mXZynHm ... -ꜩ0.426
          tz1bDCu64RmcpWahdn9bWrDMi6cu7mXZynHm ... -ꜩ0.257

New contract KT1LVLUsC1WCo4yHzeoDEE8FxxoC7EW6bSyp originated.
Contract memorized as NatOracle.
```

Make an alias for the resulting address:

```text
❯❯❯ ORACLE_ADDRESS="KT1LVLUsC1WCo4yHzeoDEE8FxxoC7EW6bSyp"
```

# Getting a value

## Preparing a view contract

Originate the contract:

```text
❯❯❯ tezos-client --wait none originate contract nat_storage transferring 0 \
  from $ALICE_ADDRESS running "$(lorentz-contract print --name NatStorageContract)" \
  --init 0 --burn-cap 0.295
```

Make an alias for its address:

```text
❯❯❯ NAT_STORAGE_ADDRESS="KT1ShW17HERZgjUTxSxSc4W3tuWrfLCqBmEi"
```

See the [`FA1.2` Quickstart](https://assets.tqtezos.com/docs/token-contracts/fa12/3-fa12-lorentz) for more info.

## Make the parameter

```text
❯❯❯ lorentz-contract-oracle Oracle get-value --help
Usage: lorentz-contract-oracle Oracle get-value --callbackContract ADDRESS
  get value

Available options:
  -h,--help                Show this help text
  --callbackContract ADDRESS
                           Address of the callbackContract.
  -h,--help                Show this help text
```

```text
❯❯❯ lorentz-contract-oracle Oracle get-value --callbackContract $NAT_STORAGE_ADDRESS
Left (Pair Unit "KT1ShW17HERZgjUTxSxSc4W3tuWrfLCqBmEi")
```

## Get the value

```text
❯❯❯ tezos-client --wait none transfer 0 from $ALICE_ADDRESS to $ORACLE_ADDRESS \
  --arg "$(lorentz-contract-oracle Oracle get-value \
  --callbackContract $NAT_STORAGE_ADDRESS)" --burn-cap 0.000001

Waiting for the node to be bootstrapped before injection...
Current head: BL7fbZE3Gs2V (timestamp: 2020-04-03T15:33:25-00:00, validation: 2020-04-03T15:33:45-00:00)
Node is bootstrapped, ready for injecting operations.
Estimated gas: 31566 units (will add 100 for safety)
Estimated storage: no bytes added
Operation successfully injected in the node.
Operation hash is 'opWqWvkJczWzq5m99svSDzW7HmWY5nCUB1rerDn6utLLH5NJ1dS'
NOT waiting for the operation to be included.
Use command
  tezos-client wait for opWqWvkJczWzq5m99svSDzW7HmWY5nCUB1rerDn6utLLH5NJ1dS to be included --confirmations 30 --branch BL7fbZE3Gs2VkmziY11S4biX9cfuLVnQmLr8r7ALbJukxD4tRSY
and/or an external block explorer to make sure that it has been included.
This sequence of operations was run:
  Manager signed operations:
    From: tz1bDCu64RmcpWahdn9bWrDMi6cu7mXZynHm
    Fee to the baker: ꜩ0.00347
    Expected counter: 623930
    Gas limit: 31666
    Storage limit: 0 bytes
    Balance updates:
      tz1bDCu64RmcpWahdn9bWrDMi6cu7mXZynHm ............. -ꜩ0.00347
      fees(tz1Ke2h7sDdakHJQh8WX4Z372du1KChsksyU,154) ... +ꜩ0.00347
    Transaction:
      Amount: ꜩ0
      From: tz1bDCu64RmcpWahdn9bWrDMi6cu7mXZynHm
      To: KT1LVLUsC1WCo4yHzeoDEE8FxxoC7EW6bSyp
      Parameter: (Left (Pair Unit "KT1ShW17HERZgjUTxSxSc4W3tuWrfLCqBmEi"))
      This transaction was successfully applied
      Updated storage:
        (Pair 3 0x00003b5d4596c032347b72fb51f688c45200d0cb50db)
      Storage size: 426 bytes
      Consumed gas: 20242
    Internal operations:
      Transaction:
        Amount: ꜩ0
        From: KT1LVLUsC1WCo4yHzeoDEE8FxxoC7EW6bSyp
        To: KT1ShW17HERZgjUTxSxSc4W3tuWrfLCqBmEi
        Parameter: 3
        This transaction was successfully applied
        Updated storage: 3
        Storage size: 38 bytes
        Consumed gas: 11324
```

# Update the value

## Make the parameter

```javascript
❯❯❯ lorentz-contract-oracle Oracle update-value --help
Usage: lorentz-contract-oracle Oracle update-value --newValueType Michelson Type
                                                   --newValue Michelson Value
  update value

Available options:
  -h,--help                Show this help text
  --newValueType Michelson Type
                           The Michelson Type of newValue
  --newValue Michelson Value
                           The Michelson Value: newValue
  -h,--help                Show this help text
```

## Update the value

To update the value to `4`:

```text
Waiting for the node to be bootstrapped before injection...
Current head: BMLjQ5pgcmxd (timestamp: 2020-04-03T15:35:39-00:00, validation: 2020-04-03T15:35:44-00:00)
Node is bootstrapped, ready for injecting operations.
Estimated gas: 19463 units (will add 100 for safety)
Estimated storage: no bytes added
Operation successfully injected in the node.
Operation hash is 'ooEf7sgpvhMcUBcn66iMLaWNzs4TEAxb4icjXKF27xM2QPMTGQP'
NOT waiting for the operation to be included.
Use command
  tezos-client wait for ooEf7sgpvhMcUBcn66iMLaWNzs4TEAxb4icjXKF27xM2QPMTGQP to be included --confirmations 30 --branch BMLjQ5pgcmxdN11kfhA2NS4igfSdJeL5HbopDn8LyAckBroWZhi
and/or an external block explorer to make sure that it has been included.
This sequence of operations was run:
  Manager signed operations:
    From: tz1R3vJ5TV8Y5pVj8dicBR23Zv8JArusDkYr
    Fee to the baker: ꜩ0.001259
    Expected counter: 632294
    Gas limit: 10000
    Storage limit: 0 bytes
    Balance updates:
      tz1R3vJ5TV8Y5pVj8dicBR23Zv8JArusDkYr ............. -ꜩ0.001259
      fees(tz1Ke2h7sDdakHJQh8WX4Z372du1KChsksyU,154) ... +ꜩ0.001259
    Revelation of manager public key:
      Contract: tz1R3vJ5TV8Y5pVj8dicBR23Zv8JArusDkYr
      Key: edpkvCHgVArnZo9RTP4P6euLTyhE89u73CYjBgsP4wEJbj4quao9oR
      This revelation was successfully applied
      Consumed gas: 10000
  Manager signed operations:
    From: tz1R3vJ5TV8Y5pVj8dicBR23Zv8JArusDkYr
    Fee to the baker: ꜩ0.002123
    Expected counter: 632295
    Gas limit: 19563
    Storage limit: 0 bytes
    Balance updates:
      tz1R3vJ5TV8Y5pVj8dicBR23Zv8JArusDkYr ............. -ꜩ0.002123
      fees(tz1Ke2h7sDdakHJQh8WX4Z372du1KChsksyU,154) ... +ꜩ0.002123
    Transaction:
      Amount: ꜩ0
      From: tz1R3vJ5TV8Y5pVj8dicBR23Zv8JArusDkYr
      To: KT1LVLUsC1WCo4yHzeoDEE8FxxoC7EW6bSyp
      Parameter: (Right (Left 4))
      This transaction was successfully applied
      Updated storage:
        (Pair 4 0x00003b5d4596c032347b72fb51f688c45200d0cb50db)
      Storage size: 426 bytes
      Consumed gas: 19463
```

# Setting up a server

While we have everything we need to originate and administer an oracle contract, we'd like to automatically push updates to the contract.

Below are two simple examples of how you can periodically fetch some data and automatically push it to the oracle contract.

## Minimal server implementation

A minimal server written in bash shellscript could consist of:

* A Bash script `update_value.sh` that gets the `NEW_VALUE` and then calls the `update-value` entrypoint:

```bash
##!/bin/bash
## update_value.sh

NEW_VALUE="$(my_get_new_value_script)

tezos-client --wait none transfer 0 from $ALICE_ADDRESS to $ORACLE_ADDRESS \
  --arg "$(lorentz-contract-oracle Oracle update-value \
  --newValueType "nat" --newValue $NEW_VALUE)" --burn-cap 0.000001
```

* A `crontab` job to run `update_value.sh` periodically $in the example it's daily at `5:03 pm`$:

```text
03 05 * * * update_value.sh
```

## Docker Flask server

There is an implementation of the above Bash server in Python, packaged as a Docker image, which:

* Fetches the latest stock price from Alpha Vantage
* Runs a "cron job" to push the update to the oracle contract with [`pytezos`](https://github.com/baking-bad/pytezos) every 30 seconds
* Serves a webpage for debugging

It does the same thing as the Bash script where `my_get_new_value_script` fetches the latest ticker price from Alpha Vantage.

You can find the project on Github [here](https://github.com/tqtezos/lorentz-contract-oracle/tree/master/stock_ticker) or view the one-file Python code [here](https://github.com/tqtezos/lorentz-contract-oracle/blob/master/stock_ticker/tq/oracles/ticker.py).

To get the image from [the DockerHub repo](https://hub.docker.com/r/tqtezos/oracle-stock-ticker), run:

```text
❯❯❯ docker pull tqtezos/oracle-stock-ticker:2.1
```

The server is configured using environment variables:

* To generate the `TEZOS_USER_KEY` parameter, run: `echo "$(base64 MY_KEY_FILE.json | tr -d '\n')"`, where `MY_KEY_FILE.json` is your Tezos faucet file $see [here](https://faucet.tzalpha.net/) to get a testnet faucet file$.
* You can get a free `ALPHA_VANTAGE_API_KEY` from [Alpha Vantage](https://www.alphavantage.co/support/#api-key)
* Alpha Vantage's `Search Endpoint` may be used to find `ALPHA_VANTAGE_TICKER_SYMBOL`'s

```
TEZOS_USER_KEY=".."
ORACLE_ADDRESS="KT1CUTjTqf4UMf6c9A8ZA4e1ntWbLVTnvrKG"
ALPHA_VANTAGE_API_KEY=".."
ALPHA_VANTAGE_TICKER_SYMBOL="AAPL"
FLASK_APP="tq/oracles/ticker.py"
```

To run the Docker container:

```javascript
❯❯❯ docker run -d -p 5000:5000 \
  --env TEZOS_USER_KEY=".."
  --env ORACLE_ADDRESS="KT1.." \
  --env ALPHA_VANTAGE_API_KEY=".." \
  --env ALPHA_VANTAGE_TICKER_SYMBOL="AAPL" \
  --env FLASK_APP="tq/oracles/ticker.py" \
  oracle-stock-ticker
```

Once it's up, it will serve the debug page and update the oracle contract roughly every 30 seconds.

You should be able to view the debug screen at `localhost:5000`, fetch the latest values using `get-value`, and use a block explorer to inspect the contract.

You can find a running example of the contract [on Carthage](https://you.better-call.dev/carthage/KT1CUTjTqf4UMf6c9A8ZA4e1ntWbLVTnvrKG/operations).

If you had any difficulties following this tutorial or simply want to discuss Tezos tech with us you can [**join our community today**](https://discord.gg/fszyM7K)!


Learn how to get started with Oracle Contracts on Tezos

Oracle Contracts

[**The original tutorial can be found in the Tezos documentation here**](https://github.com/tqtezos/nft-tutorial). 

# Introduction

This tutorial shows how to originate and interact with the FA2 NFT contract implementation. The tutorial uses a pre-compiled FA2 NFT contract written in [LIGO](https://ligolang.org/) smart contract language and a command line interface $CLI$ to originate and interact with the NFT contracts either on the [Flextesa](https://tezos.gitlab.io/flextesa/) sandbox or Tezos testnet $Carthagenet$.

> **Disclaimer:** We highly recommend users read the additional resources above and take necessary precautions before following this tutorial and interacting with experimental technology. Use this tutorial at your own risk.

## What is FA2 $TZIP-12$?

FA2 refers to a token standard $[TZIP-12](https://gitlab.com/tzip/tzip/-/blob/master/proposals/tzip-12/tzip-12.md)$ on Tezos. FA2 proposes a unified token contract interface, supporting a wide range of token types. The FA2 provides a standard API to transfer tokens, check token balances, manage operators $addresses that are permitted to transfer tokens on behalf of the token owner$ and manage token metadata.

## What is a Non-Fungible Token $NFT$?

An NFT $non-fungible token$ is a special type of cryptographic token which represents something unique; non-fungible tokens are thus not mutually interchangeable. NFTs can represent ownership over digital or physical assets like virtual collectibles or unique artwork.

For each individual non-fungible token, the FA2 assigns a unique token ID and associates it with the token owner address. The FA2 API enables the inspection of token balances for the specific token ID and token owner address. For NFTs the balance can be either 0 $which means that the address does not own this particular token$ or 1 $the address owns the token$.

The FA2 contract also associates some metadata with each token. This tutorial supports token symbol and token name metadata attributes. However, the implementation can be easily extended to support custom metadata attributes such as an associated image or document URL and its crypto-hash.

# Prerequisites

* [Node.js](https://nodejs.org/) must be installed. The Node installation must also include `npm` $Node package manager$.
* [Docker](https://www.docker.com/) must be installed. You need docker to run Flextesa sandbox. You might skip docker installation if you plan to run this tutorial on the testnet $Carthagenet$ only.

# Requirements

You will need to install `tznft` CLI tool. After the installation, you can invoke various commands in the form of `tznft <command> [options]`. `tznft` provides the following commands:

* mint $contract origination$ NFT with metadata command
* token inspection commands
* NFT transfer command
* Configuration commands to bootstrap Tezos network and configure address aliases

The commands will be explained in more detail below. You can always run `tznft --help` to list all available commands.

# Initial Setup

1. Create a new local directory to keep your tutorial configuration:

```javascript
$ mkdir nft-tutorial
$ cd nft-tutorial
```

1. Install `@tqtezos/nft-tutorial` npm package:

```text
npm install -g https://github.com/tqtezos/nft-tutorial.git

/usr/local/bin/tznft -> /usr/local/lib/node_modules/@tqtezos/nft-tutorial/lib/tznft.js

+ @tqtezos/nft-tutorial@1.0.0
added 3 packages from 1 contributor and updated 145 packages in 11.538s
```

The command installs `tznft` CLI tool.

1. Initialize tutorial config:

```text
tznft init-config

tznft.json config file created
```

1. Check that the default active network is `sandbox`:

```text
tznft show-network

active network: sandbox
```

1. Bootstrap Tezos network:

```text
tznft bootstrap

ebb03733415c6a8f6813a7b67905a448556e290335c5824ca567badc32757cf4

starting sandbox...
sandbox started
originating balance inspector contract...
originated balance inspector KT1Pezr7JjgmrPcPhpkbkH1ytG7saMZ34sfd
```

If you are bootstrapping a `sandbox` network for the first time, Docker will download the Flextesa docker-image as well.

The default configuration comes with two account aliases `bob` and `alice` that can be used for token minting and transferring.

# Mint NFT Token$s$

This tutorial uses an NFT collection contract. Each time the user mints a new set $collection$ of tokens, a new NFT contract is created. The user cannot add more tokens or remove $burn$ existing tokens within the contract. However tokens can be transferred to other owners.

`mint` command requires the following parameters:

* alias or address of the new tokens owner
* `--tokens` new tokens metadata. Each token metadata is represented as comma delimited string: `'<token_id>, <token_symbol>, <token_name>'`:

```javascript
tznft mint <owner_alias> --tokens <token_meta_list>`
```

Example:

```text
tznft mint bob --tokens '0, T1, My Token One' '1, T2, My Token Two'

originating new NFT contract...
originated NFT collection KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh
```

# Inspecting The NFT Contract

Using `KT1..` address of the NFT contract created by the `mint` command, we can inspect token metadata and balances $i. e. which addresses own the tokens$.

## Inspect Token Metadata

`show-meta` command requires the following parameters:

* `--nft` address of the FA2 NFT contract to inspect
* `--signer` alias on behalf of which contract is inspected
* `--tokens` a list of token IDs to inspect

```text
tznft show-meta --nft <nft_address> --signer <alias> --tokens <token_id_list>
```

Example:

```text
tznft show-meta --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --signer bob --tokens 0 1

token_id: 0	symbol: T1	name: My Token One	extras: { }
token_id: 1	symbol: T2	name: My Token Two	extras: { }
```

## Inspect Token Balances

`show-balance` command requires the following parameters:

* `--nft` address of the FA2 NFT contract to inspect
* `--signer` alias on behalf of which contract is inspected
* `--owner` alias of the token owner to check balances
* `--tokens` a list of token IDs to inspect

```text
tznft show-balance --nft <nft_address> --signer <alias> --owner <alias> --tokens <token_id_list>
```

Example 1, check `bob`'s balances:

```text
tznft show-balance --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --signer bob --owner bob --tokens 0 1

querying NFT contract KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh using balance inspector KT1Pezr7JjgmrPcPhpkbkH1ytG7saMZ34sfd
requested NFT balances:
owner: tz1YPSCGWXwBdTncK2aCctSZAXWvGsGwVJqU	token: 0	balance: 1
owner: tz1YPSCGWXwBdTncK2aCctSZAXWvGsGwVJqU	token: 1	balance: 1
```

Example 2, check `alice` balances:

```text
tznft show-balance --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --signer bob --owner alice --tokens 0 1

querying NFT contract KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh using balance inspector KT1Pezr7JjgmrPcPhpkbkH1ytG7saMZ34sfd
requested NFT balances:
owner: tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb	token: 0	balance: 0
owner: tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb	token: 1	balance: 0
```

# Tokens With External Metadata

Token metadata can store a reference to some external document and/or image. This tutorial supports storing external data on [IPFS](https://ipfs.io/) and keeping an IPFS hash as a part of the token metadata.

Let's create a single NFT token which references an image on IPFS.

1. Upload your image to IPFS and obtain an image file hash. There are multiple ways to do that. One of the possible solutions is to install the [IPFS Companion](https://github.com/ipfs-shipyard/ipfs-companion) web plugin and upload an image file from there. You can upload multiple images and/or documents if you plan to create a collection of multiple NFTs.
2. Copy the IPFS file hash code $`CID`$. For this example we will use `QmRyTc9KbD7ZSkmEf4e7fk6A44RPciW5pM4iyqRGrhbyvj`
3. Execute `tznft mint` command adding IPFS hash as a fourth parameter in the token description:

```text
tznft mint bob -t '0, TZT, Tezos Token, QmRyTc9KbD7ZSkmEf4e7fk6A44RPciW5pM4iyqRGrhbyvj'

originating new NFT contract...
originated NFT collection KT1SgzbcfTtdHRV8qHNG3hd3w1x23oiC31B8
```

1. Now we can inspect new token metadata and see that the IPFS hash $`ipfs_cid`$ is there.

```text
tznft show-meta -s bob --nft KT1SgzbcfTtdHRV8qHNG3hd3w1x23oiC31B8 --tokens 0

token_id: 0	symbol: TZT	name: Tezos Token	extras: { ipfs_cid=QmRyTc9KbD7ZSkmEf4e7fk6A44RPciW5pM4iyqRGrhbyvj }
```

1. You can inspect the file on the web by opening a URL `https://ipfs.io/ipfs/<ipfs_cid>`. For our example, the URL would be [https://ipfs.io/ipfs/QmRyTc9KbD7ZSkmEf4e7fk6A44RPciW5pM4iyqRGrhbyvj](https://ipfs.io/ipfs/QmRyTc9KbD7ZSkmEf4e7fk6A44RPciW5pM4iyqRGrhbyvj)

# Transferring Tokens

`transfer` command requires the following parameters:

* `--nft` address of the FA2 NFT contract that holds tokens to be transferred
* `--signer` alias or address that initiates the transfer operation
* `--batch` a list of individual transfers. Each individual transfer is represented as a comma delimited string: `<from_address_or_alias>, <to_address_or_alias>, <token_id>`. We do not need to specify amount of the transfer for NFTs since we can only transfer a single token for any NFT type.

```text
tznft transfer --nft <nft_address> --signer <signer> --batch <batch_list>`
```

Example, `bob` transfers his own tokens `0` and `1` to `alice`:

```text
tznft transfer --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --signer bob --batch 'bob, alice, 0' 'bob, alice, 1'

transferring tokens...
tokens transferred
```

Now, we can check token balances after the transfer:

```text
tznft show-balance --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --signer bob --owner bob --tokens 0 1

querying NFT contract KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh using balance inspector KT1Pezr7JjgmrPcPhpkbkH1ytG7saMZ34sfd
requested NFT balances:
owner: tz1YPSCGWXwBdTncK2aCctSZAXWvGsGwVJqU	token: 0	balance: 0
owner: tz1YPSCGWXwBdTncK2aCctSZAXWvGsGwVJqU	token: 1	balance: 0
```

```text
tznft show-balance --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --signer bob --owner alice --tokens 0 1

querying NFT contract KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh using balance inspector KT1Pezr7JjgmrPcPhpkbkH1ytG7saMZ34sfd
requested NFT balances:
owner: tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb	token: 0	balance: 1
owner: tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb	token: 1	balance: 1
```

# Operator Transfer

It is also possible to transfer tokens on behalf of the owner.

`bob` is trying to transfer one of `alice`'s tokens back:

```text
tznft transfer --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --signer bob --batch 'alice, bob, 1'

transferring tokens...
Tezos operation error: FA2_NOT_OPERATOR
```

As we can see, this operation has failed. The default behavior of the FA2 token contract is to allow only token owners to transfer their tokens. In our example, bob $as an operator$ tries to transfer token `1` that belongs to `alice`.

However, `alice` can add `bob` as an operator to allow him transfer any tokens on behalf of `alice`.

`update-ops` command has the following parameters:

* `<owner>` alias or address of the token owner to update operators for
* `--nft` address of the FA2 NFT contract
* `--add` list of pairs aliases or addresses and token id to add to the operator set
* `--remove` list of aliases or addresses and token id to remove from the operator set

```text
tznft update-ops <owner> --nft <nft_address> --add [add_operators_list] --remove [add_operators_list]
```

Example, `alice` adds `bob` as an operator:

```text
tznft update-ops alice --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --add 'bob, 1'

updating operators...
updated operators
```

Now `bob` can transfer a token on behalf of `alice` again:

```text
tznft transfer --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --signer bob --batch 'alice, bob, 1'

transferring tokens...
tokens transferred
```

Inspecting balances after the transfer:

```text
tznft show-balance --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --signer bob --owner bob --tokens 0 1

querying NFT contract KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh using balance inspector KT1Pezr7JjgmrPcPhpkbkH1ytG7saMZ34sfd
requested NFT balances:
owner: tz1YPSCGWXwBdTncK2aCctSZAXWvGsGwVJqU	token: 0	balance: 0
owner: tz1YPSCGWXwBdTncK2aCctSZAXWvGsGwVJqU	token: 1	balance: 1
```

```text
tznft show-balance --nft KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh --signer bob --owner alice --tokens 0 1

querying NFT contract KT1XP3RE6S9t44fKR9Uo5rAfqHvHXu9Cy7fh using balance inspector KT1Pezr7JjgmrPcPhpkbkH1ytG7saMZ34sfd
requested NFT balances:
owner: tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb	token: 0	balance: 1
owner: tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb	token: 1	balance: 0
```

Token `1` now belongs to `bob`.

# Configuration

`tznft` can be configured to interact with different Tezos networks. The user can also configure address aliases to sign Tezos operations and/or use them as command parameters when addresses are required. The default configuration that is created by `tznft init-config` command includes two pre-configured networks: `sandbox` and `testnet` $Carthagenet$. Each pre-configured network has two bootstrap aliases: `bob` and `alice`.

## Network Configuration Commands

* `set-network <network>` select specified pre-configured network as an active one. All subsequent commands will operate on the active network

  Example:

```text
tznft set-network sandbox

network sandbox is selected
```

* `show-network [--all]` show currently selected network. If `--all` flag is specified, show all pre-configured networks

  Example:

```text
tznft show-network --all

* sandbox
  testnet
```

* `bootstrap` bootstrap selected network and deploy helper balance inspector contract. If selected network is `sandbox` this command needs to be run each time sandbox is restarted, for other public networks like `testnet` is it enough to run this command once.

  Example:

```text
tznft bootstrap

366b9f3ead158a086e8c397d542b2a2f81111a119f3bd6ddbf36574b325f1f03

starting sandbox...
sandbox started
originating balance inspector contract...
originated balance inspector KT1WDqPuRFMm2HwDRBotGmnWdkWm1WyG4TYE
```

* `kill-sandbox` stop Flextesa sandbox process if selected network is `sandbox`. This command has no effect on other network types.

  Example:

```text
tznft kill-sandbox

flextesa-sandbox

killed sandbox.
```

The sandbox network $selected by default$ is configured to bake new Tezos blocks every 5 seconds. It makes running the commands that interact with the network faster. However, all originated contracts will be lost after the sandbox is stopped.

If you are using `testnet`, your originated contracts will remain on the blockchain and you can inspect them afterwards using an block explorer like [BCD](https://better-call.dev/).

> **NOTE:** Although `testnet` configuration already has two bootstrap aliases `bob` and `alice`, it is a good practice to create your own alias from the faucet file $see `tznft add-alias-faucet` command described below$ and use it as a signer for the commands like `mint`, `transfer` and `show_balance`. In this way, your Tezos operations will not interfere with the operations initiated by other users._

# Alias Configuration Commands

`tznft` allows user to configure and use short names $aliases$ instead of typing in full Tezos addresses when invoking `tznft` commands. Each network comes with two pre-configured aliases `bob` and `alice`. The user can manage aliases by directly editing `tznft.json` file or using the following commands:

* `show-alias [alias]` show address and private key $if configured$ of the specified `[alias]`. If `[alias]` option is not specified, show all configured aliases.

  Example:

```text
tznft show-alias bob

bob	tz1YPSCGWXwBdTncK2aCctSZAXWvGsGwVJqU	edsk3RFgDiCt7tWB2oe96w1eRw72iYiiqZPLu9nnEY23MYRp2d8Kkx

tznft show-alias

bob	tz1YPSCGWXwBdTncK2aCctSZAXWvGsGwVJqU	edsk3RFgDiCt7tWB2oe96w1eRw72iYiiqZPLu9nnEY23MYRp2d8Kkx
alice	tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb	edsk3QoqBuvdamxouPhin7swCvkQNgq4jP5KZPbwWNnwdZpSpJiEbq
```

* `add-alias <alias> <private_key>` add alias using its private key. Aliases that configured with the private key can be used to sign operations that originate or call smart contracts on chain. `tznft` commands that require Tezos operation signing have `--signer` option.

Example:

```text
tznft add-alias jane edsk3QoqBuvdamxouPhin7swCvkQNgq4jP5KZPbwWNnwdZpSpJiEbq

alias jane has been added

tznft show-alias jane

jane	tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb	edsk3QoqBuvdamxouPhin7swCvkQNgq4jP5KZPbwWNnwdZpSpJiEbq
```

* `add-alias <alias> <address>` add alias using Tezos address $public key hash$. Such aliases do not have associated private key and cannot be used to sign Tezos operations.

  Example:

```text
tznft add-alias michael tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb

alias michael has been added

tznft show-alias michael

michael	tz1VSUr8wwNhLAzempoch5d6hLRiTh8Cjcjb
```

* `add-alias-faucet <alias> <faucet_json_file_path>` add alias with private key from the faucet file $see [Tezos Faucet](https://faucet.tzalpha.net/)$. This command will not work on `sandbox` network. An alias configured from the faucet has the private key and can be used to sign Tezos operations.

  Example:

```text
tznft add-alias-faucet john ~/Downloads/tz1NfTBQM9QpZpEY6GSvdw3XBpyEjLLGhcEU.json

activating faucet account...
faucet account activated
alias john has been added

tznft show-alias john

john	tz1NfTBQM9QpZpEY6GSvdw3XBpyEjLLGhcEU	edskRzaCrGEDr1Ras1U55U73dXoLfQQJyuwE95rSkqbydxUS4oS3fGmWywbaVcYw7DLH34zedoJzwMQxzAXQdixi5QzYC5pGJ6
```

* `remove-alias <alias>` remove alias from the selected network configuration.

  Example:

```javascript
tznft remove-alias john

alias john has been deleted
```


Learn how to create and interact a non-fungible token contract on Tezos

Creating NFTs

In this tutorial we will learn how to transfer an amount of Tezos tokens from our account to another account. Token transfers are the simplest function on most blockchains, and one of the most common.

The role of TezosToolkit here is to provide a simplified way of dealing with the lifecycle of an RPC request. It would be possible to implement the transfer functionality for ourselves, however it is preferable to utilize the toolkit for the flexible functionality and ease of use that it provides.

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/tezos/transfer.ts`, implement the function and try to make your first transfer on the Tezos network. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const { mnemonic, email, password, secret, amount, recipient } = req.body
    const url = getTezosUrl();
    const tezos = new TezosToolkit(url);

    await importKey(undefined);

    // Call the transfer method

    // Await confirmation 
    await operation.confirmation(1) 

    res.status(200).json(operation.hash);
  }
//...
```

**Need some help?** Check out these links
* [**Transfer with Taquito**](https://tezostaquito.io/docs/quick_start/#transfer)
* [**Check out the `transfer` method's interface**](https://tezostaquito.io/typedoc/interfaces/_taquito_taquito.contractprovider.html#transfer)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const { mnemonic, email, password, secret, amount, recipient } = req.body;
    const url = getTezosUrl();
    const tezos = new TezosToolkit(url);

    await importKey(
      tezos,
      email,
      password,
      mnemonic,
      secret
    );

    const operation = await tezos.contract.transfer({ 
      to: recipient, 
      amount: amount 
    });

    await operation.confirmation(1);

    res.status(200).json(operation.hash);
  }
//...
```

**What happened in the code above?**

* First, we create a new `TezosToolkit` instance.
* Next, we import our wallet data using `importKey`.
* Next, we create an transaction using the method `transfer` of the `contract` module, passing:
  * The recipient address.
  * The amount in **μꜩ** (**mutez**).
* Then, we wait for the confirmation of the transaction.
* Finally, we send the `operation.hash` back to the client-side as JSON.

------------------------

# Make sure it works

Once you have the code above saved:
* Fill in the amount of **mutez** you want to send.
* Click on **Submit Transfer**.

![](../../../.gitbook/assets/pathways/tezos/tezos-transfer.gif)

-----------------------------

# Conclusion

Now that we have created our account and made a transfer, let's move on to deploying some code (known as a "smart contract") to the **Tezos** blockchain! Ready to take the plunge? Let's go... 


Learn how to transfer TEZ from one account to another

Transfer TEZ tokens

# 🧩 DataHub API keys

To make use of the Pathway content, you will require a DataHub account and a valid API key to access Tezos via DataHub's infrastructure.
You will need to [sign up for a DataHub account](https://auth.figment.io/sign_up) and verify your email address.

To use your API key you must create a new file named `.env.local` in the project root directory `/learn-web3-dapp/`, copying the contents of the existing `.env.example` file. Your API key needs to be pasted into `.env.local` so that you can authenticate your connections with DataHub.

Your personal API key can be found on the [**DataHub Services Dashboard**](https://datahub.figment.io/). Click on the **Tezos** icon in the list of available protocols and then copy your key as shown below:

![](../../../.gitbook/assets/pathways/tezos/tezos-setup.gif)

You can then paste your personal API key into `.env.local`, as the value for the environment variable `DATAHUB_TEZOS_API_KEY`. This will authenticate you and enable you to make JSON-RPC requests to Tezos via DataHub:

![API keys](https://user-images.githubusercontent.com/2707197/136927423-d4c0074a-ebaf-49b0-a37f-080feb19dea8.png)

{% hint style="info" %}
[**Join us on Discord**](https://figment.io/devchat), if you encounter any issues with the tutorial or have any questions!
{% endhint %}


Let's setup the project to connect & interact with Tezos

Setup the project

# What is Tezos?

Tezos is a secure, smart contract blockchain platform that uses its built-in governance mechanism for protocol upgrades. Tezos is one of the first blockchain platforms to introduce a formal on-chain governance process. The Tezos network is highly decentralized with over 500 nodes distributed globally. Tezos’ smart contract language, Michelson, is designed to facilitate formal verification, a technique used to improve security by mathematically proving properties. This technique, if used properly, can help avoid costly bugs and contentious debates that follow.

# Why build on Tezos?

Tezos is an open-source platform for assets and applications that can evolve by upgrading itself. Stakeholders govern upgrades to the core protocol, including upgrades to the amendment process itself. **It benefits from three main characteristics: self-amendment, on-chain governance, and decentralized innovation.**

Self-amendment allows Tezos to upgrade itself without having to split (“fork”) the network into two different blockchains. This is important as the suggestion or expectation of a fork can divide the community, alter stakeholder incentives, and disrupt the network effects that are formed over time. Because of self-amendment, coordination and execution costs for protocol upgrades are reduced and future innovations can be seamlessly implemented.

In Tezos, all stakeholders can participate in governing the protocol. The election cycle provides a formal and systematic procedure for stakeholders to reach agreement on proposed protocol amendments. By combining this on-chain mechanism with self-amendment, Tezos can change this initial election process to adopt better governance mechanisms when they are discovered.

Proposed amendments that are accepted by stakeholders can include payment to individuals or groups that improve the protocol. This funding mechanism encourages robust participation and decentralizes the maintenance of the network. Fostering an active, open, and diverse developer ecosystem that is incentivized to contribute to the protocol will facilitate Tezos development and adoption.

# What can you build on Tezos?

Turing-complete smart contract platforms like Tezos or Ethereum allow for arbitrary code to be executed in a trust-minimized manner. However, certain applications may be well suited for Tezos based on formal governance and focus on smart contract security. Below are some preliminary examples:

1. Digital Assets

  Assets like digital money, tokenized real estate, stablecoins, digital collectibles, and so on are particularly well-suited for Tezos. Avoiding contentious forks can preserve value and coordination around one network, making Tezos a compelling platform for issuing digital assets.

Although no system can be unconditionally secure, the Tezos smart contract language, Michelson, was designed with security and formal verification in mind. This is especially critical for smart contracts representing high value assets, given the unforgiving nature of smart contracts bugs.

2. Trust-Minimized Financial Contracts

  Financial contracts such as decentralized exchanges, swaps, loans, and so on demand a high-level of correctness. Decentralized blockchain networks derive their value from the absence of a trusted third party, which makes a loss of funds from a bug in the code particularly unforgiving.

# Network Specifications

## Transaction Fees

So far, this system is similar to the way Ethereum handles transaction. However, we differ in the way we handle fees. Ethereum allows arbitrarily long programs to execute by requiring a fee that increases linearly with the program's executing time.

## Transaction Speed & Finality

Currently, Tezos does around 30-40 transactions per second.

In the current Tezos protocol, 30 confirmations (~30 minutes) may be considered a good rule of thumb for transaction to be considered final. Since Tezos uses a chain-based PoS consensus algorithm, the possibility of a chain re-organization remains after a transaction. Users must wait a number of confirmations before they can be overwhelmingly confident that a transaction will not be reversed.

## Languages supported

There are various high-level languages available for programming Smart Contracts for Tezos. The intention of these languages is to ease the development experience, so you can focus on the content of your Smart Contracts, rather than the implementation.

Current options in development include:

* LIGO: A Smart Contract language offering Pascal, Ocaml, and ReasonML syntax flavors
* SmartPy: A Python library with tools to write and test Smart Contracts
* Morley/Lorentz: A Haskell-flavored eDSL for writing Smart Contracts

## EVM compatibility

Tezos does not currently support an EVM implementation.

## Role of the XTZ token

XTZ, tez, or ꜩ is the native currency of Tezos. XTZ is programmable money created by smart contract on the Tezos blockchain. It is used to pay on-chain fees and influence the network's governance.


Learn how Tezos works and what makes it special

Introduction

Learn how to deploy and interact with a digital asset on Tezos

Token Contracts

Our Contract is on-chain, and we're going to learn how to fetch the data stored on the contract. 

{% hint style="info" %}
If you want to learn more about Tezos smart contracts, follow [**The Taco Shop Smart Contract**](https://ligolang.org/docs/tutorials/get-started/tezos-taco-shop-smart-contract) tutorial.
{% endhint %}

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/tezos/getter.ts`, implement the function and try to read the value of the counter stored in the smart contract. You must replace the instances of `undefined` with working code to accomplish this. 
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const { mnemonic, email, password, secret, contract } = req.body;
    const url = getTezosUrl();
    const tezos = new TezosToolkit(url);

    await importKey(
      tezos,
      email,
      password,
      mnemonic,
      secret
    );

    // Use the contract module to get the storage
    const counter = undefined;

    // @ts-ignore
    res.status(200).json(counter.toString());
  } 
//...
```

**Need some help?** Check out these links
* [**Interface ContractProvider method `getStorage`**](https://tezostaquito.io/typedoc/interfaces/_taquito_taquito.contractprovider.html#getstorage)  

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const { mnemonic, email, password, secret, contract } = req.body;
    const url = getTezosUrl();
    const tezos = new TezosToolkit(url);

    await importKey(
      tezos,
      email,
      password,
      mnemonic,
      secret
    );

    const counter = await tezos.contract.getStorage(contract);

    // @ts-ignore
    res.status(200).json(counter.toString());
  } 
//...
```

**What happened in the code above?**

* First, we create a new `TezosToolkit` instance.
* Next, we import our wallet data using `importKey`.
* Then, using the `getStorage` function of the `contract` module, we return the counter stored on the contract.
* Finally, we send the `counter` value converted `toString` back to the client-side as JSON.

------------------------

# Make sure it works

Once you have the code above saved, click the button and watch the magic happen:

![](../../../.gitbook/assets/pathways/tezos/tezos-getter.gif)

-----------------------------

# Conclusion

Nicely done! You learned how to get a value from a smart contract's storage on the Tezos blockchain. Now it is time for the final challenge: Modify the state of the contract and thus the state of the blockchain. Let's go!


Get the storage of a smart contract

Learn how to create your own fungible tokens on Tezos using SmartPy

Mint your own Fungible Token

Our Contract is on-chain, and we're going to learn how to fetch the data stored on the contract. 

{% hint style="info" %}
If you want to learn more about Tezos smart contracts, follow [**The Taco Shop Smart Contract**](https://ligolang.org/docs/tutorials/get-started/tezos-taco-shop-smart-contract) tutorial.
{% endhint %}

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/tezos/setter.ts`, implement the function and try to increment the value stored in the smart contract by one. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const { mnemonic, email, password, secret, contract } = req.body;
    const url = getTezosUrl();
    const tezos = new TezosToolkit(url);
    await importKey(
      tezos,
      email,
      password,
      mnemonic,
      secret
    );
    
    const n = 1;
    // Load the interface of the contract
    const counterContract = undefined;
    // Call the increment function of the contract
    const transaction = await undefined;
    // Await confirmations
    await transaction.confirmation(3);

    res.status(200).json(transaction.hash);
  }
//...
```

**Need some help?** Check out these links
* [**Interact with a smart contract**](https://tezostaquito.io/docs/quick_start/#interact-with-a-smart-contract)  
* [**Interface ContractProvider method `at`**](https://tezostaquito.io/typedoc/interfaces/_taquito_taquito.contractprovider.html#at) 
* [**Class ContractAbstraction `methods`**](https://tezostaquito.io/typedoc/classes/_taquito_taquito.contractabstraction.html#methods) 

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const { mnemonic, email, password, secret, contract } = req.body;
    console.log(CONTRACT_JSON);
    const url = getTezosUrl();
    const tezos = new TezosToolkit(url);

    await importKey(
      tezos,
      email,
      password,
      mnemonic,
      secret
    );
    
    const n = 1;
    // Load the interface of the contract
    const counterContract = await tezos.contract.at(contract);
    // Call the increment function of the contract
    const transaction = await counterContract.methods.increment(n).send();
    // Await confirmations
    await transaction.confirmation(3);

    res.status(200).json(transaction.hash);
  }
//...
```

**What happened in the code above?**

* First, we must supply the address of our newly deployed contract to `tezos.contract.at`.
* Next, using `contract.methods.increment(n).send()` will pass the value of `n` to the `increment` method of the deployed contract. Note: _if the contract functions are not annotated, they are still indexed by number._ 
* Next, using the instruction `transaction.confirmation(3)` we wait for **3** block confirmations before returning.
* Finally, the transaction hash is then available and we can return it to the client-side as JSON via `transaction.hash`.

------------------------

# Make sure it works

Once you have the code above saved, click the button and watch the magic happen:

![](../../../.gitbook/assets/pathways/tezos/tezos-setter.gif)

-----------------------------

# Conclusion

Congratulations! You have completed the Tezos Pathway, all the way from connecting to Tezos to being able to deploy smart contracts! You are now empowered to learn and build on Tezos, using the dedicated infrastructure of DataHub.

Continue to explore the [LIGO API documentation](https://ligolang.org/docs/api/cheat-sheet), learn more about [Michelson](https://tezos.gitlab.io/michelson-reference/) or perhaps dive straight into the [JSON/RPC documentation](https://tezos.gitlab.io/developer/rpc.html). 

If you had any difficulties following this tutorial or simply want to discuss Tezos with other developers you can join [our Discord](https://discord.gg/fszyM7K) or head over to our [community forums](https://community.figment.io).


Set Smart Contract's value

Learn how to mint NFTs on Tezos using SmartPy & BetterCall.dev

Mint NFTs on Tezos 

Although it is beyond the scope of this tutorial to teach the specific syntax of LIGO or Michelson, we will cover the deployment of compiled Michelson code to Tezos. Michelson is a human-readable, stack-based language. It is possible to write smart contracts in Michelson & it can also be compiled directly from LIGO.

{% hint style="info" %}
One of the properties of Michelson is that it has been designed to facilitate formal verification. Further reading on the specifics of formal verification is [available here](https://runtimeverification.com/blog/formal-verification-framework-for-michelson/)
{% endhint %}

We won't go through the process of reviewing the smart contract code base, compiling it or testing it. We will focus instead on how one can deploy a smart contract using the **Taquito** library. To do this, we're going to use a pre-compiled smart contract, you can find the compiled Michelson code under `contracts/tezos/counter.js`.

Our contract will be pretty basic. It stores a counter on the blockchain and implements two functions:
* The `Increment(n)` function which increases by n the counter stored on the contract.
* The `Decrement(n)` function which decreases by n the counter stored on the contract.

{% hint style="info" %}
If you want to learn more about Tezos smart contracts, follow [**The Taco Shop Smart Contract**](https://ligolang.org/docs/tutorials/get-started/tezos-taco-shop-smart-contract) tutorial on the official LIGO site.
{% endhint %}

------------------------

# Challenge

{% hint style="tip" %}
In `pages/api/tezos/deploy.ts`, implement the function and try to deploy the compiled smart contract. You must replace the instances of `undefined` with working code to accomplish this.
{% endhint %}

**Take a few minutes to figure this out**

```typescript
//...
  try {
    const { mnemonic, email, password, secret, amount } = req.body
    const url = getTezosUrl();
    const tezos = new TezosToolkit(url);

    await importKey(
      tezos,
      email,
      password,
      mnemonic,
      secret
    )

    const operation = await undefined;

    const contract = await undefined;
 
    res.status(200).json({
      contractAddress: contract.address,
      hash: operation.hash
    });
  }
//...
```

**Need some help?** Check out these links
* [**Interface ContractProvider method `originate`**](https://tezostaquito.io/typedoc/interfaces/_taquito_taquito.contractprovider.html#originate) 
* [**Class OriginateOperation method `contract`**](https://tezostaquito.io/typedoc/classes/_taquito_taquito.originationoperation.html#contract)

{% hint style="info" %}
You can [**join us on Discord**](https://discord.gg/fszyM7K), if you have questions or want help completing the tutorial.
{% endhint %}

Still not sure how to do this? No problem! The solution is below so you don't get stuck.

------------------------

# Solution

```typescript
// solution
//...
  try {
    const { mnemonic, email, password, secret, amount } = req.body
    const url = getTezosUrl();
    const tezos = new TezosToolkit(url);

    await importKey(
        tezos,
        email,
        password,
        mnemonic,
        secret
      )

    const operation = await tezos.contract.originate({
        code: CONTRACT_JSON,
        storage: 0
      })

    const contract = await operation.contract()
 
    res.status(200).json({
      contractAddress: contract.address,
      hash: operation.hash
    });
  }
//...
```

**What happened in the code above?**

* First, we create a new `TezosToolkit` instance.
* `importKey` has the side effect of setting the TezosToolkit instance to use the `InMemorySigner` provider.
* Next, we execute the `Tezos.contract.originate` function. This deploys the Michelson contract code to the Tezos blockchain, from the `CONTRACT_JSON` in `counter.js`. The storage property is also set to `0`.
* Next, the resulting operation ([`op`](https://opentezos.com/tezos-basics/operations/)) object is used to provide the contract address of the newly originated contract.

------------------------

# Make sure it works

Once you have the code above saved, click on **Deploy Contract**

![](../../../.gitbook/assets/pathways/tezos/tezos-deploy.gif)

-----------------------------

# Conclusion

Now that we have deployed a smart contract on Tezos, let's interact with it! In the following tutorials, we will look at how to use both view and change functions.


Learn how to deploy a Smart Contract on Tezos

Deploy a smart contract

Learn how to create your own NFT marketplace on Tezos

Create an NFT marketplace on Tezos

# Introduction
Hey Reader! Welcome to this Tutorial on Testing a smart contract on Tezos in SmartPy. We will be learning how to run unit tests and make sure our code works before deployment because once deployed, smart contracts are immutable (and we do not want to waste our XTZ tokens).


- Tezos is an open-source blockchain protocol for assets and applications backed by a global community of validators, researchers, and builders. The Tezos protocol is secure, upgradable, and built to last.
- SmartPy is an intuitive and powerful smart contract development platform for Tezos and is available through a Python library for building and analyzing Tezos smart contracts.


# Prerequisites

To complete this tutorial, you will need a basic understanding of the Python programming language and know-how of how to write and deploy Tezos Contracts.
I will suggest you take a look at this [Tutorial](https://learn.figment.io/tutorials/using-the-smartpy-ide-to-deploy-tezos-smart-contracts) first.

# Requirements
Any modern Browser!


# Smart Contract
Before we go to the depths of testing the contract, we need to first have a sample contract that is complex enough so that we can understand its testing.

Below I have taken a simple time-based Escrow Contract : 

```python
import smartpy as sp

class Escrow(sp.Contract):
    def __init__(self, owner, fromOwner, counterparty, fromCounterparty, epoch, hashedSecret):
        self.init(fromOwner           = fromOwner,
                  fromCounterparty    = fromCounterparty,
                  balanceOwner        = sp.tez(0),
                  balanceCounterparty = sp.tez(0),
                  hashedSecret        = hashedSecret,
                  epoch               = epoch,
                  owner               = owner,
                  counterparty        = counterparty)

    @sp.entry_point
    def addBalanceOwner(self):
        sp.verify(self.data.owner == sp.sender , "Wrong Owner")
        sp.verify(self.data.balanceOwner == sp.tez(0) , "There is already some stake")
        sp.verify(sp.amount == self.data.fromOwner , "Only the stake amount is allowed")
        self.data.balanceOwner = self.data.fromOwner

    @sp.entry_point
    def addBalanceCounterparty(self):
        sp.verify(self.data.counterparty == sp.sender , "Wrong CounterParty")
        sp.verify(self.data.balanceCounterparty == sp.tez(0) , "There is already some stake")
        sp.verify(sp.amount == self.data.fromCounterparty , "Only the stake amount is allowed")
        self.data.balanceCounterparty = self.data.fromCounterparty

    def claim(self, identity):
        sp.verify(sp.sender == identity , "Wrong Identity. Internal call only")
        sp.send(identity, self.data.balanceOwner + self.data.balanceCounterparty)
        self.data.balanceOwner = sp.tez(0)
        self.data.balanceCounterparty = sp.tez(0)

    @sp.entry_point
    def claimCounterparty(self, params):
        sp.verify(sp.now < self.data.epoch , "Time limit expired")
        sp.verify(self.data.hashedSecret == sp.blake2b(params.secret) , "Wrong Secret Key")
        self.claim(self.data.counterparty)

    @sp.entry_point
    def claimOwner(self):
        sp.verify(self.data.epoch < sp.now , "Time Limit not yet reached")
        self.claim(self.data.owner)
```

An Escrow contract acts as security between two untrusting parties whenever there is an amount involved.
A task and a deadline are agreed upon and both parties stake some amount **fromOwner** and **fromCounterparty**.
In this case, we have **owner** and **counterParty** as the two parties and the latter can claim the amount till the deadline **time** does not expire.
Once the deadline has expired and if the **counterParty** hasn't claimed the amount yet then **owner** can claim all the amount. 
A secret code is hashed and stored in the contract which acts as the password for the **counterParty** and is revealed to the **counterParty** only after the agreed-upon task is completed making sure that both parties are serious about the task!

Now a contract of such high importance must be iron-clad and no bug should allow either of the parties to claim the amount before the specified task is completed. Hence the need for testing it extensively arises.

# Test Scenarios
In SmartPy we can simulate all kinds of transaction possibilities and test out our contract without having to spend a single XTZ.

To implement testing we must examine the concept of **test scenarios** :

Test scenarios are an important tool to make sure our smart contracts are working correctly.
- A new test is a method marked with `@sp.add_test`
- A new scenario is instantiated by `sp.test_scenario`.
- Scenarios describe a sequence of actions: originating contracts, computing expressions or calling entry points, etc.
- In the online editor of SmartPy.io, the scenario is computed and then displayed as an HTML document on the output panel.

Let's start by defining a method named `test()`:

```python
@sp.add_test(name = "Escrow")
    def test():
        pass
```
Now we need to create a test scenario:

```python
@sp.add_test(name = "Escrow")
def test():
    scenario = sp.test_scenario()
    scenario.h1("Escrow")
```

# Test Accounts

Test Accounts are unique dummy accounts provided to us via the SmartPy library so that we can simulate real-world user accounts which will interact with our contract.
It is instatiated the following way:

```python
bob = sp.test_account("Bob")
udit = sp.test_account("Udit")
```
The string parameter acts like a seed phrase so that no two test accounts are the same.

Test Accounts have the following properties for us to use:
- *admin*.address
- *admin*.public_key_hash
- *admin*.public_key
- *admin*.secret_key

These represent the values that the user will have in their account. For us, the most important is their **Address**.

# Originating a Contract
Now we have the two parties of the Escrow contract namely **bob** and **udit** and we are ready to Originate our contract in our **test scenario**.
According to our contract above we need the following parameters:
- Owner (bob)
- Owner's Stake
- Counter Party (udit)
- Counter Party's Stake
- Time Limit
- Secret

```python
s = sp.pack("SECRETKEY") #String to Bytes
secret = sp.blake2b(s) #Hashing bytes to secret key
ob = Escrow(bob.address, sp.tez(25), udit.address, sp.tez(5), sp.timestamp(1634753427), secret)
scenario += ob
```

Now in our **test scenario** we have added a Smart Contract between two users (bob and udit) with each of them staking 50 XTZ and 5 XTZ respectively with a deadline of 20th October 2021 and a hashed secret key

> You can read up on Human Date to Epoch Timestamp conversion [HERE](https://www.epochconverter.com/).

> I have used blake2b as my cryptographic hash function. Read more about it [HERE](https://www.blake2.net/)

# Run Method
As we know that we can directly call our contract's EntryPoints using the `.` operator like `ob.addBalanceOwner()` but to simulate the intricate parameters of a real-world transaction we user the `.run()` method which has the following parameters :

Parameter | Function
--------- | --------
sender | It simulates the user who is sending the transaction to the contract. Sets the value of `sp.sender`
source | It simulates the source of the transaction. Sets the value of `sp.source`
amount | It simulates the amount sent by the user in the transaction. Sets the value of `sp.amount`
now | It simulates the timestamp of the transaction. Sets the value of `sp.now`
level | It simulates the block level of the transaction. Sets the value of `sp.level`
chain_id | It simulates the chain_id of the transaction. Sets the value of `sp.chain_id`
voting_powers | It simulates the voting power of different users in the contract's implementation. It is a dictionary. Sets the value of `sp.voting_power`
valid | If we expect a transaction to fail i.e. testing out edge cases we put this parameter as **FALSE** so that the compiler won't throw an error
show | If we do not want to show a transaction in the HTML Output we set this parameter as **FALSE** 
exception | If we expect a transaction to fail then we can also specify the expected exception that it will raise. **Valid** must be **False**

For our tutorial, we will be focusing on the `sender` , `amount`, `now`, `valid` , `show` parameters.

# Unit Tests
We write all our verifying conditions in the contract and create transactions that would test all the functionalities of our contract. 
My advice here is to proceed by isolating an EntryPoint and then testing all its variables and then moving on to the next EntryPoint:

## addBalanceOwner()

```python
ob.addBalanceOwner().run(sender=udit , amount = sp.tez(25) , valid = False)
ob.addBalanceOwner().run(sender=bob , amount = sp.tez(1) , valid = False)
ob.addBalanceOwner().run(sender = bob, amount = sp.tez(25))
ob.addBalanceOwner().run(sender = bob , amount = sp.tez(25) , valid = False)
```

- Faults

1. In the first transaction we are sending **udit** as the **sender** who we have set as **CounterParty**. Hence, we expect our transaction to fail and have **valid** set as **False**.
2. In the second transaction we are sending ```sp.tez(1)``` as the owner's stake which we have set as 25 XTZ. Hence, we expect our transaction to fail and have **valid** set as **False**.
3. The third transaction has both the owner and stake amount correct and we expect it to be a valid transaction.
4. In the fourth transaction even though all the parameters are correct, the owner has already staked once in the contract and can not stake again. Hence, we expect our transaction to fail and have **valid** set as **False**.

## addBalanceCounterparty()

```python
ob.addBalanceCounterparty().run(sender=bob , amount = sp.tez(5) , valid = False)
ob.addBalanceCounterparty().run(sender=udit , amount = sp.tez(25) , valid = False)
ob.addBalanceCounterparty().run(sender = udit, amount = sp.tez(5))
ob.addBalanceCounterparty().run(sender = udit, amount = sp.tez(5) , valid = False)
```

- Faults

1. In the first transaction we are sending **bob** as the **sender** who we have set as **Owner**. Hence, we expect our transaction to fail and have **valid** set as **False**.
2. In the second transaction we are sending ```sp.tez(25)``` as the counter party's stake which we have set as 5 XTZ. Hence, we expect our transaction to fail and have **valid** set as **False**.
3. The third transaction has both the counterparty and stake amount correct and we expect it to be a valid transaction.
4. In the fourth transaction even though all the parameters are correct, the counter arty has already staked once in the contract and can not stake again. Hence, we expect our transaction to fail and have **valid** set as **False**.

## claimCounterparty()

```python
ob.claimCounterparty(secret = s).run(sender = bob , valid = False)
ob.claimCounterparty(secret = sp.bytes("0x01223343")).run(sender = udit, valid = False)
ob.claimCounterparty(secret = s).run(sender = udit , now = sp.timestamp(1635192186) , valid=False)
ob.claimCounterparty(secret = s).run(sender = udit)
```

- Faults
1. In the first transaction we are sending bob as the **sender** who is not the counterparty. Hence, we expect our transaction to fail and have **valid** set as **False**.
2. In the second transaction we are sending the wrong secret key. Hence, we expect our transaction to fail and have **valid** set as **False**.
3. The third transaction has both the counterparty and secret key correct but the timestamp is for 25th October 2021 which is past our deadline set during origination.
4. The fourth transaction has everything in order and hence is a valid transaction.

## claimOwner()

```python
ob.claimOwner().run(sender = udit , valid = False)
ob.claimOwner().run(sender = bob, valid=False)
ob.claimOwner().run(sender = bob ,now = sp.timestamp(1635192186) )
```

- Faults
1. In the first transaction we are sending udit as the **sender** who is not the owner. Hence, we expect our transaction to fail and have **valid** set as **False**.
2. The second transaction has the correct **sender** but the time limit has not yet expired. Hence, we expect our transaction to fail and have **valid** set as **False**.
3. The third transaction has everything in order and hence is a valid transaction with the timestamp simulated as of 25th October 2021.

# Accessing Contract Data
We can also access a lot of parameters associated with the contract using the ```.``` operator like ```ob.data```. We have the following options : 
- *ob*.data
- *ob*.balance
- *ob*.baker
- *ob*.address

Parameter | Function
--------- | --------
data | Fetches contract's storage 
balance | Fetches contract's balance amount in XTZ
baker | Fetches contract's optional delegated baker
address | Fetches contract's deployed address within the scenario

# Scenario Methods
The scenario we made in the above tutorial also provides us with various tools to verify, compute and show in HTML Output.

## Verify
We can verify all the parameters of our storage or any condition using **verify** method.

```python
scenario.verify(ob.data.owner == bob.address)
```

## Compute
Using **compute** we perform calculations and store them in local variables inside the scenario.

```python
x = scenario.compute(ob.data.fromOwner + sp.tez(15))
```

## Show
**show** method is used to add expressions that are not transactions into the HTML Output. This will compute the expression and add it to our output panel

```python
scenario.show(ob.data)
scenario.show(ob.data.fromOwner + sp.tez(15))
```

## HTML Tags
We are also provided with 6 levels of headings in our scenario so that we can beautify and segregate our output panel.

```python
scenario.h1("title")
scenario.h2("subtitle")
scenario.h3("<h3> HTML tag.")
scenario.h4("<h4> HTML tag.")
scenario.p("<p> HTML tag.")
```

Now that we have completed the depths of testing our smart contract we are ready to deploy it in the real world and have real users interact with it.

# Final Code

```python
import smartpy as sp

class Escrow(sp.Contract):
    def __init__(self, owner, fromOwner, counterparty, fromCounterparty, epoch, hashedSecret):
        self.init(fromOwner           = fromOwner,
                  fromCounterparty    = fromCounterparty,
                  balanceOwner        = sp.tez(0),
                  balanceCounterparty = sp.tez(0),
                  hashedSecret        = hashedSecret,
                  epoch               = epoch,
                  owner               = owner,
                  counterparty        = counterparty)

    @sp.entry_point
    def addBalanceOwner(self):
        sp.verify(self.data.owner == sp.sender , "Wrong Owner")
        sp.verify(self.data.balanceOwner == sp.tez(0) , "There is already some stake")
        sp.verify(sp.amount == self.data.fromOwner , "Only the stake amount is allowed")
        self.data.balanceOwner = self.data.fromOwner

    @sp.entry_point
    def addBalanceCounterparty(self):
        sp.verify(self.data.counterparty == sp.sender , "Wrong CounterParty")
        sp.verify(self.data.balanceCounterparty == sp.tez(0) , "There is already some stake")
        sp.verify(sp.amount == self.data.fromCounterparty , "Only the stake amount is allowed")
        self.data.balanceCounterparty = self.data.fromCounterparty

    def claim(self, identity):
        sp.verify(sp.sender == identity , "Wrong Identity. Internal call only")
        sp.send(identity, self.data.balanceOwner + self.data.balanceCounterparty)
        self.data.balanceOwner = sp.tez(0)
        self.data.balanceCounterparty = sp.tez(0)

    @sp.entry_point
    def claimCounterparty(self, params):
        sp.verify(sp.now < self.data.epoch , "Time limit expired")
        sp.verify(self.data.hashedSecret == sp.blake2b(params.secret) , "Wrong Secret Key")
        self.claim(self.data.counterparty)

    @sp.entry_point
    def claimOwner(self):
        sp.verify(self.data.epoch < sp.now , "Time Limit not yet reached")
        self.claim(self.data.owner)

@sp.add_test(name = "Escrow")
def test():
    scenario = sp.test_scenario()
    scenario.h1("Escrow")

    bob = sp.test_account("Bob")
    udit = sp.test_account("Udit")

    s = sp.pack("SECRETKEY") #String to Bytes
    secret = sp.blake2b(s) #Hashing bytes to secret key
    ob = Escrow(bob.address, sp.tez(25), udit.address, sp.tez(5), sp.timestamp(1634753427), secret)
    scenario += ob

    scenario.h1("Workflows")
    
    scenario.h2("Add Balance Owner")
    ob.addBalanceOwner().run(sender=udit , amount = sp.tez(25) , valid = False)
    ob.addBalanceOwner().run(sender=bob , amount = sp.tez(1) , valid = False)

    ob.addBalanceOwner().run(sender = bob, amount = sp.tez(25))

    ob.addBalanceOwner().run(sender = bob , amount = sp.tez(25) , valid = False)


    scenario.h2("Add Balance CounterParty")
    ob.addBalanceCounterparty().run(sender=bob , amount = sp.tez(5) , valid = False)
    ob.addBalanceCounterparty().run(sender=udit , amount = sp.tez(25) , valid = False)

    ob.addBalanceCounterparty().run(sender = udit, amount = sp.tez(5))

    ob.addBalanceCounterparty().run(sender = udit, amount = sp.tez(5) , valid = False)

    scenario.h2("Claim CounterParty")
    ob.claimCounterparty(secret = s).run(sender = bob , valid = False)
    ob.claimCounterparty(secret = sp.bytes("0x01223343")).run(sender = udit, valid = False)
    ob.claimCounterparty(secret = s).run(sender = udit , now = sp.timestamp(1635192186) , valid=False)


    scenario.h2("Claim Owner")
    ob.claimOwner().run(sender = udit , valid = False)
    ob.claimOwner().run(sender = bob, valid=False)

 
    ob.claimOwner().run(sender = bob ,now = sp.timestamp(1635192186) )

    scenario.verify(ob.data.owner == bob.address)
    x = scenario.compute(ob.data.fromOwner + sp.tez(15))
    scenario.show(ob.data)
    scenario.show(ob.data.fromOwner + sp.tez(15))
```

# Conclusion

In this tutorial, we learned how to create test scenarios, simulate complex transactions in SmartPy, and how to use the various functionalities provided by SmartPy to test and make our code bug-free. You can create your test scenarios like above and save yourself a lot of time and XTZ by ironing out the bugs before deployment.

# Next Steps

I would like for you to make your contracts and test all their EntryPoints, Storage and make sure they are perfect before deploying them to the chain.

# About The Author

This tutorial was written by Udit Kapoor, who is a Tezos India 2.0 Fellow and a blockchain enthusiast. Their signature project is CryptoWill and they like to dabble in Flutter as well! Reach out to Udit on [GitHub](https://github.com/Udit-Kapoor).

# References

- Escrow example code from SmartPy.io
- [SmartPy Docs](https://smartpy.io/docs/)


Learn how to unit test Python smart contracts for Tezos using the SmartPy suite of tools

Unit testing Python smart contracts for Tezos using SmartPy

Learn how to make your own Decentralized Exchange