In this post, we will cover setting up a complete environment for developing on the TON Ecosystem. These tools will be
discussed:

- TON binaries (`lite-client`, `tonlib`, `func`, `fift`, `...`)
- toncli
- ton-contract-executor
- tonstarter-contracts
- MyLocalTON

## TON Binaries

> **NOTE**: Completing this step is essential for developing on TON blockchain.

For developing on and interacting with TON Blockchain, you'll need to have the needed binaries for compilers, clients,
nodes, ... .
There are two options to get them:

- Compiling from the source code
- Getting binaries from Auto Builds

We'll need to proceed with the former option because Auto Builds aren't available for our target branch. Also, the
official TON Binaries can be downloaded from ton
repositories [Auto Builds](https://github.com/ton-blockchain/ton/actions). But we will use a fork of TON which provides
testing capabilities that are later needed.
To build follow these steps:

1. Install the latest versions of:
- `make`
- `cmake >= 3.0.2`
- `g++` or `clang` (or another C++ 14 compatible compiler)
- OpenSSL (with C Headers) >= 1.1.1
2. Clone [SpyChesses's TON](https://github.com/SpyCheese/ton/actions) and switch to `toncli-local` branch:
```bash
git clone https://github.com/SpyCheese/ton
git checkout toncli-local
```
3. Create a build directory in an arbitrary place, we will refer to it as `<ton-build>`. Also let's assume you
   have `ton` cloned in `<ton-rep>`, in a terminal:
```bash
cd <ton-build>
cmake <ton-rep>
```
4. Build each target:
```bash
cmake --build . --target lite-client
cmake --build . --target func
cmake --build . --target fift
```
5. Those steps will take some time, wait until they're finished. Binaries will be available in:
```
fift: <ton-build>/crypto/fift
func: <ton-build>/crypto/func
lite-client: <ton-build>/lite-client/lite-client
```
You can copy them to a special directory and add them to your `PATH`.
6. TON Binaries are built and ready!

## toncli

[`toncli`](https://github.com/disintar/toncli) is a cross-platform cli for TON, that makes smart contracts manipulation
and interaction with blockchain much easier.

We will use a fork of `toncli` which comes with a new testing framework and thus needs forked TON binaries.
To install you must follow these steps:

1. Make sure to complete `TON Binaries` Section.
2. Install python(`>=3.9`) from the [official website](https://www.python.org/downloads/) on your system.
> Note 1: Don't use the Microsoft store version if you're on windows.

> Note 2: Make sure you add python to the `PATH` (On windows simply tick the `Add Python 3.xx to PATH` option)
3. Install `toncli` using this command:
```bash
git clone https://github.com/AminRezaei0x443/toncli
cd toncli
git checkout dev
python setup.py develop
```
> Note: If you see `WARNING: The script toncli is installed in '.../Python/3.X/bin' which is not on PATH.` add the
mentioned address to your `PATH` environment variable.
4. Go to the folder of TON binaries, and open a terminal in that folder. Then, run `toncli` command in the terminal. You
   should see that it automatically detects the binaries and sets them up. If for any reason it can't find the binaries,
   just provide the abstract path of binaries as it asks. Upon a successful detection you'll see an output like:

 ![](https://storage.googleapis.com/ton-strapi/env1_9973a0f5e1/env1_9973a0f5e1.png) 

As you see, toncli comes with several commands that help the development and interaction of smart contracts. The
commands are well documented but we'll go through their usage here.

### Setting up a project

To set up a project we can use `start` command to create a new project from an example project. Currently it has 4
options: `wallet`, `external_data`, `external_code`, and `simple_storage`. We will proceed with the `simple_storage`
option:

```bash
toncli start simple_storage
```

You can see how the contract is implemented in `simple_storage/func/` and how the tests are implemented
in `simple_storage/tests/`.

### Project yaml file

The `project.yaml` file contains the project's structure and metadata. You can specify the contract with its data
cell/fift files, func contracts, and tests there so toncli detects and uses them.

### Testing contracts

Testing is essential during contract development to be sure about the contract's safety and to prevent unexpected
behaviors. To run the tests:

```bash
toncli run_tests
```

This runs all the tests for the contracts specified in the `project.yaml` file.

 ![](https://storage.googleapis.com/ton-strapi/env2_6946901457/env2_6946901457.png) 

You can test one special contract by passing `-c` parameter.

```bash
toncli run_tests -c contract
```

### Deploying contracts

You can deploy contracts to mainnet or testnet easily by using the command:

```bash
toncli deploy -n testnet -wc 0
```

It will create a wallet for you if not present and will request you to send some TONs to it, so the contract deployment
fee is covered.

For a more detailed description, you can check [toncli's docs](https://github.com/disintar/toncli/blob/master/docs/).

## ton-contract-executor

> **Note: This library depends on `ton-compiler` which supports only `macOS`, at the time this article was written. So
if you're not a macOS user you won't be able to use this library until the support is added.**

`ton-contract-executor` allows you to run TVM locally and execute contracts, which eases writing, debugging, and fully
testing your contracts before launching them to the network.

To set up, you'll need to:

1. Install [`Node.js`](https://nodejs.org/en/download/)
2. Install `yarn` package manager:
```bash
npm install --global yarn
```
3. Create a directory representing your project's root, and initialize it:
```bash
yarn init
```
4. Install `ton-contract-executor` and `ton`:
```bash
yarn add ton-contract-executor
yarn add ton
```
5. Create file `contract.js` with content:
```javascript
   let {SmartContract} = require("ton-contract-executor");
   let { Cell } = require("ton");

   async function main() {
      const source = `
      () main() {
         ;; noop
      }

      int sum(int a, int b) method_id {
         return a + b;
      }
   `

      let contract = await SmartContract.fromFuncSource(source, new Cell())
      
      let res = await contract.invokeGetMethod('sum', [
         // argument a
         { type: 'int', value: '1' },
         // argument b
         { type: 'int', value: '2' },
      ])
      
      console.log('1 + 2 = ', res.result[0])
   };

   main().then(()=>{});
```
6. After successful execution, you'll see the console log with the correct result.

This was just a basic example, you can develop scripts to read the code from contract files, and execute and test their
methods. More examples are available at the [main repository](https://github.com/Naltox/ton-contract-executor).

## tonstarter-contracts

This project is a starter template for developing decentralized applications (dApps) on TON. It currently contains the
codes for contract development but it will contain frontend and telegram bot templates for interaction with contracts in
the future.

To get started:

1. Install a modern version of [`Node.js`](https://nodejs.org/en/download/).
2. Make sure you complete `TON Binaries` step and add the binaries to your `PATH` environment variable. (`fift`
   and `func` must be detectable)
3. Clone the repository:
```bash
git clone https://github.com/ton-defi-org/tonstarter-contracts
```
4. Install the dependencies:
```bash
npm install
```
5. You're all set up!

### Writing code

Contracts are present in `contracts/`, and the behavior of each subfolder and extension in the folder structure is as
follows:

- `contracts/*.fc`: standalone root contracts
- `contracts/imports/*.fc`: shared import between contracts
- `contracts/imports/<contract>/*.fc`: contract-specific imports - not shared
- `contracts/<contract>.tld`: optional [TL-B](https://ton.org/docs/learn/overviews/TL-B) Schema for data and message ops
- `contracts/<contract>.ts`: optional typescript file that encodes data and message ops

### Building Code

In the repository root, run `npm run build` to build the contracts. If any errors occur they will be displayed,
otherwise the resulting files are:

- `<contract>.merged.fc` - merged and flattened FunC source code with all imports
- `<contract>.fif` - compiled contract as Fift assembly file
- `<contract>.cell` - the binary code cell of the compiled contract (for deployment)

### Testing

You must build the code before proceeding to test. Run the tests using `npm run test`. The tests are run by TVM
using `ton-contract-executor`.

> **Note: As mentioned before, at the time this article was written, `ton-contract-executor` runs only on macOS because
of its dependency. So, you won't be able to run tests if you're not on macOS**

### Deploying

First of all, build your contracts. Each contract to deploy should have a script `build/<contract>.deploy.ts` to return
its init data cell.

The deployment wallet can be configured by the `DEPLOYER_MNEMONIC` variable in the `.env` file. You should provide the
24 secret words in the `.env` like:

```bash
DEPLOYER_MNEMONIC="tumble degree cousin sand ..."
```

Run `npm run deploy` for deploying on mainnet and `npm run deploy:testnet` for testnet, then follow the on-screen
instructions.

More details are available at the [main repository](https://github.com/ton-defi-org/tonstarter-contracts).

## MyLocalTON

`MyLocalTON` is a cross-platform local TON Blockchain. It comes as a standalone application in form of a `.jar` file.

It can be used to ease testing and inspecting the state of the blockchain, without the need to use and deploy on
the `testnet`.

To setup `MyLocalTON`:

1. Make sure of OpenJDK17 Installation, If you already have it, skip this step.
> In case of need, these are some guides on installing OpenJDK:
> - [Ubuntu](https://techviewleo.com/install-java-openjdk-on-ubuntu-linux/)
> - [Windows](https://java.tutorials24x7.com/blog/how-to-install-openjdk-17-on-windows)
> - [MacOS](https://knasmueller.net/how-to-install-java-openjdk-17-on-macos-big-sur)
2. Proceed to [Auto Builds](https://github.com/neodiX42/MyLocalTon/actions) of `MyLocalTON`, Open the latest successful
   build and download `MyLocalTon` from the generated artifacts.

 ![](https://storage.googleapis.com/ton-strapi/env3_9ce9eb9895/env3_9ce9eb9895.png) 

 ![](https://storage.googleapis.com/ton-strapi/env4_244d7ed68d/env4_244d7ed68d.png) 

3. Extract the downloaded file and execute it with java:
```bash
java -jar MyLocalTon.jar
```
4. You'll see the following screen,It will take some time to initialize TON Blockchain:

 ![](https://storage.googleapis.com/ton-strapi/env5_fe2ec778d0/env5_fe2ec778d0.png) 

5. After successful initialization, the blockchain will be ready:

 ![](https://storage.googleapis.com/ton-strapi/env6_aef02e4c20/env6_aef02e4c20.png) 


Setting up a Development Environment

In this tutorial, we will develop a simple storage contract that can be updated by an admin and can be used to retrieve information. This is the first tutorial in the ***Step-by-Step with Rift*** series, where we will discuss the basic primitives in Rift.

## Getting Started
### Install Rift
Before we begin, make sure you have a `Python 3.10+` environment installed. You can then install Rift using the following command:
```bash
pip install rift-framework
```
### Initialize Project
Next, open up a terminal and run the following command to generate a bare project:
```bash
rift init simple-storage --base=bare
```
The `--base` option specifies the project template used to initialize with. You should see a message similar to the following:
```bash
➜  Skyring rift init simple-storage --base=bare
Initializing new rift project ...
Getting template bare from https://github.com/sky-ring/rift-bare-template
Successfully created project!
```

## Project structure
After initializing the project, you can open the folder with your favorite editor or IDE. If you don't have one, we recommend using VSCode. You can see the directory structure of the project as follows:

```bash
simple-storage
├── README.md # General Readme
├── contracts
│   └── bare_template.py
├── deployers
│   ├── __init__.py
│   └── deploy_base.py
├── project.toml # Project Configuration
├── pyproject.toml # Python Project Configuration - No Edits Necessary
├── tests
│   ├── __init__.py
│   └── test_example.py
└── tox.ini # Python Code Formatter Configuration
```
### Project Configuration
The project configuration is present in the `project.toml` file. You will need to make changes to this file to define new targets, add test and deploy scripts, or configure `rift`'s settings. The contents of this file are as follows:

```toml
# rift project configuration file

name = "bare-template"

[contracts.bare_template]
    name = "bare-template" # This is the generated target name -> [name].fc
    contract = "BaseContract" # This is the contract class you have in the file
    deploy = "deploy_base" # This is name of the deploy script
    # All test scripts should be mentioned here
    tests = [
        "test_example"
    ]
```

### Contracts
All your contracts will reside in the `contracts/` directory. They are defined as classes that inherit the base `Contract` class. Contract codes are executed, and the execution graph is traced and gets translated to `FunC` (and `TVM` in the future). So if you use untraceable operations, the result will be recorded. For more specific details, visit [here](https://docs.skyring.io/rift/).


### Tests
You can define test scripts in the `tests/` directory. Don't forget to mention the test script in your target configuration. Test scripts are simple Python scripts; you can import contracts from the contracts package and use arbitrary Python code.

### Deployers
You can define deploy scripts under the `deployers` directory. This script will be mentioned in target configuration and will run whenever `rift deploy [TARGET]` is executed.

## Storage Contract

### 0. Specifications
In this section, we will develop a storage contract that stores an unsigned 64-bit integer `value` in its storage. The contract will have the following features:

- The contract's `admin` can change this value by sending an internal message.
- The data should be available with a get-method.


### 1. Configure the project
Let's start by refactoring the existing files. We will rename `contracts/bare_template.py` to `contracts/storage.py` and update its content to the following:


```python
from rift import *


class Storage(Contract):
    def internal_receive(self) -> None:
        pass
```

We will also update the project configuration in `project.toml` to the following:

```toml
# rift project configuration file

name = "storage"

[contracts.storage]
    contract = "Storage"
    deploy = "deploy_storage" # Will create later
    tests = [
        "test_storage" # Will create later
    ]

```
### 2. Define the Contract Data
Next, we will define the contract data scheme by adding the `Data` class under our `Storage` class, which will extend `Model`:

```python
# ...
class Storage(Contract):
    class Data(Model):
        admin: MsgAddress
        value: uint64
    # ...
```

### 3. Define contract message structure
We will also specify the contract message body structure as a `Payload` class:

```python
class ChangeBody(Payload):
    new_value: uint64
```

### 4. Implement the `change` Function
The contract's `internal_receive` function will check whether the sender is `admin` and replace the data with the new value. We can access the full message via `self.message` and the message body with `self.body`:

```python
    # ...
    def internal_receive(self) -> None:
        assert self.message.info.src.is_equal(self.data.admin), 1001
        body = (
            self.body % self.ChangeBody
        )  # This parses body as ChangeBody class
        self.data.value = body.new_value
        self.data.save()
```

### 5. Specify the get-method
We need to define a get-method so that the value will be exposed. To do this, we have two options:

1. Add a config docstring to the class so that it's automatically handled during compile time:
```python
    class Storage(Contract):
        """
        Simple Storage Contract.
    ​
        # config
        get-methods:
            - value
        """
        # ...
```
This approach is best when we want to expose a field in our data and don't need any processing. For other use cases, we should define a get-method using the second approach.

2. Define a new method in the contract with `@method_id()` annotation:
```python
        # ...
        @method_id()
        @method()
        def get_value(self) -> uint64:
            return self.data.value
```

### 6. Compiling
Our contract is complete! You can see the full implementation in this file. Let's compile it using the following command:

```bash
rift build all
```
The built files will be available in the `build/` directory.

 ![](https://storage.googleapis.com/ton-strapi/storage_1_3ecd14d2f9/storage_1_3ecd14d2f9.png) 

## Testing
One of the most critical aspects of contract development is ensuring correctness and security. Even minor bugs can result in significant financial losses for contract parties. Properly testing contracts with appropriate test cases is, therefore, an essential step in the development process. Fortunately, Rift includes a built-in testing framework that minimizes the hassle of testing.

To begin, let's rename the `tests/test_example.py` file to `tests/test_storage.py` and use the initial code provided:

```python
from rift import *
from contracts.bare_template import BaseContract


def test_example():
    data = Cell()
    wallet = BaseContract.instantiate(data)
    res = wallet.recv_internal(0, 0, Cell(), Cell().parse())
    res.expect_ok()
```
In the test environment, we can easily import the target contract and instantiate it with an arbitrary cell as its data. We can then call its methods and analyze the results.

First, we'll proceed with testing our `get_value` method to ensure it can properly read from our data cell:

```python
def test_get_method():
    data = Storage.Data(admin=MsgAddress.std(0, 1), value=1).as_cell()
    storage = Storage.instantiate(data)
    res = storage.get_value()
    res.expect_ok()
    (value,) = res.result.stack
    assert value == 1
```
Then, we'll test the `internal_receive` method with a `change_value` call:

```python
def test_change_value():
    data = Storage.Data(admin=MsgAddress.std(0, 1), value=1).as_cell()
    storage = Storage.instantiate(data)
    body = Storage.ChangeBody(new_value=2)
    msg = InternalMessage[Storage.ChangeBody].build(
        src=MsgAddress.std(0, 1),
        dest=MsgAddress.std(0, 0),
        body=body,
    )
    res = storage.recv_internal(0, 0, msg.as_cell(), body.as_cell().parse())
    res = storage.get_value()
    res.expect_ok()
    (value,) = res.result.stack
    assert value == 2
```

We can also test that the contract disallows unauthorized changes by testing with another admin:

```python
def test_change_value_wrong_admin():
    data = Storage.Data(admin=MsgAddress.std(0, 1), value=1).as_cell()
    storage = Storage.instantiate(data)
    body = Storage.ChangeBody(new_value=2)
    msg = InternalMessage[Storage.ChangeBody].build(
        src=MsgAddress.std(0, 2),
        dest=MsgAddress.std(0, 0),
        body=body,
    )
    res = storage.recv_internal(0, 0, msg.as_cell(), body.as_cell().parse())
    res.expect_exit(1001)
```

To run the test command, enter the following in the command line:

```bash
rift test all
```

The expected output is:
! ![](https://storage.googleapis.com/ton-strapi/storage_2_aa08eeaf50/storage_2_aa08eeaf50.png) 

## Deploying
The first step is to define the `deploy` function in `deployers/deploy_storage.py`. The `deploy` function deploys the contract to the blockchain and returns a message and a boolean flag. The message carries the contract deploy code and initial data, and the boolean flag indicates whether this message will be sent independently or through your wallet as an internal message. In our case, the flag is set to `False` because we are sending the message through our wallet as an internal message. Here is the initial template code:

```python
from rift import *

# You can import from contracts here
from contracts.bare_template import BaseContract


def deploy(network: Network):
    init_data = Cell()
    msg, addr = BaseContract.deploy(init_data, amount=2 * 10 ** 8)
    return msg, False
```

When you execute `rift deploy TARGET`, Rift executes the deploy function and sends the given message to the blockchain.


Now we need to construct the initial data for our contract and deploy it. We'll modify the `deploy` function as follows:

```python
def deploy(network: Network):
    # Get our wallet and it's address
    wallet = WalletManager.acquire_wallet(network)
    my_addr = wallet.calculate_address()
    # Create initial data for contract
    init_data = Storage.Data(admin=my_addr, value=0).as_cell()
    # Create a change body as the first message to the contract
    body = Storage.ChangeBody(new_value=1)
    # Send the deploy request bearing 0.1 TON for fees
    msg, addr = Storage.deploy(init_data, amount=10**8, body=body.as_cell())
    print("Contract getting deployed to:", MsgAddress.human_readable(addr))
    return msg, False
```
In this modified `deploy` function, we first get our wallet and its address. Then, we create the initial data for the contract, which includes the admin address and an initial value of 0. Next, we create a change body as the first message to the contract, setting the new value to 1. Finally, we send the deploy request bearing 0.1 TON for fees.

To deploy the contract on testnet, run the following command:
```bash
rift deploy storage --network=test-net
```
On the first try, you will need to configure/create a wallet with Rift and fund it. After executing the command, you should see a message indicating that the contract is getting deployed to a specific address.

 ![](https://storage.googleapis.com/ton-strapi/storage_3_7959face1b/storage_3_7959face1b.png) 
## The End
This tutorial has demonstrated the step-by-step process of developing and deploying a simple storage contract on testnet using Rift. This will serve as a basis for further development guides with Rift. You can find the full project implementation [*here*](https://github.com/sky-ring/simple-storage). If you want to stay updated, join our [***community channel***](https://t.me/skyring_org). We prioritize simple step-by-step guides and are continuously updating our documentation. Stay tuned!
This tutorial has demonstrated the step-by-step process of developing and deploying a simple storage contract on testnet using Rift. This will serve as a basis for further development guides with Rift. If you want to stay updated, join our community channel. We prioritize simple step-by-step guides and are continuously updating our documentation. Stay tuned!


Step-by-Step with Rift: Simple Storage Contract Tutorial

# Unlocking the Power of TON with Rift Framework
Decentralized technology is the future. With its ability to bring about true democratization and fairness, the world is gravitating towards blockchain and its many applications. One such blockchain is The Open Network (TON), an ultra-fast, low-fee, and environmentally friendly layer-1 blockchain designed to onboard billions of users.

## The Power of Python and TON ⚡️
TON is a decentralized layer-1 blockchain designed for fast and efficient transactions. But despite its many benefits, TON's ***FunC*** and ***Fift*** programming languages can be complex for developers to learn. That's where Rift comes in.

With Rift, developers can leverage the simplicity and versatility of Python to build and interact with TON. Python's syntax and object-oriented programming (OOP) features make it easy for developers to write and test smart contracts, without having to learn a new programming language.

Rift is the magical portal that links **Python** to **TON** world.

 ![](https://storage.googleapis.com/ton-strapi/rift1_466d25b161/rift1_466d25b161.png) 
## Simplifying the Development Process 💻
Rift offers a full suite of tools for TON development. From writing smart contracts in Python to testing and deploying them on the TON network, Rift streamlines every step of the development process. And with its standalone framework, developers only need to know ***Python 3.10*** to start building on TON.

Here are just a few of the many features that make Rift an indispensable tool for TON development:

### Power up your Smart Contract Development with Rift 🔥
With Rift, developers can take full advantage of Python’s syntax and capabilities to develop TON smart contracts with ease. No need to learn a new programming language or worry about compatibility issues, Rift brings the best of both worlds and makes TON development accessible to all.

```python
class SimpleWallet(Contract):
    """
    Simple Wallet Contract.

    # config
    get-methods:
        - seq_no
        - public_key
    """

    class Data(Model):
        seq_no: uint32
        public_key: uint256

    class ExternalBody(SignedPayload):
        seq_no: uint32
        valid_until: uint32

    data: Data

    def external_receive(self) -> None:
        msg = self.body % self.ExternalBody
        assert msg.valid_until > std.now(), 35
        assert msg.seq_no == self.data.seq_no, 33
        assert msg.verify_signature(self.data.public_key), 34
        std.accept_message()
        while msg.refs():
            mode = msg >> uint8
            std.send_raw_message(msg >> Ref[Cell], mode)
        self.data.seq_no += 1
        self.data.save()
```

### Interact with TON like a Pro 💫
Rift provides an all-in-one wrapper around TON development tools, making it easier than ever to interact with the TON network. With Rift, developers can build messages, sign them using the Fift backend, run contract codes, deploy contracts, and interact with the network using the Tonlibjson backend.

```python
from contracts.jetton_minter import JettonMinter
from contracts.jetton_wallet import JettonWallet


def deploy():
    init_data = JettonMinter.Data()
    init_data.admin = "EQCDRmpCsiy5fA0E1voWMpP-L4SQ2lX0liTk3zgFXcyLSYS3"
    init_data.total_supply = 10**11  # 100
    init_data.content = Cell()
    init_data.wallet_code = JettonWallet.code()
    msg, addr = JettonMinter.deploy(init_data, amount=2 * 10 ** 8)
    return msg, False
```

### Test Your Contracts Thoroughly 🧪

Rift also provides a TVM testing framework that makes it easy to test contracts before deploying them to the production network. The framework provides a simple interface for creating message bodies and inspecting the contract's state to ensure correct behavior.

```python
from contracts.jetton_wallet import JettonWallet
from contracts.types import TransferBody


def test_transfer():
    data = create_data().as_cell()
    wallet = JettonWallet.instantiate(data)
    body = create_transfer_body(dest=3)
    res = wallet.send_tokens(
        body.as_cell().parse(), MsgAddress.std(0, 2), int(10e9), 0,
    )
    res.expect_ok()


def test_transfer_no_value():
    data = create_data().as_cell()
    wallet = JettonWallet.instantiate(data)
    body = create_transfer_body(dest=3)
    res = wallet.send_tokens(
        body.as_cell().parse(), MsgAddress.std(0, 2), 0, 0,
    )
    res.expect_error()
```

## Join the TON Revolution 💎
TON has the potential to revolutionize the blockchain world, and Rift is the perfect tool to help developers take advantage of its many benefits. Whether you're just starting out or already have experience with TON, Rift is the perfect way to streamline your development process and bring your ideas to life on TON. So why wait? Start building with Rift today and join the TON revolution! 🚀

Get started now by exploring [Rift's repository](https://github.com/sky-ring/rift) and joining the [Skyring Channel](https://t.me/skyring_org) for the latest updates. We're excited to announce that step-by-step guides will be available soon. Stay tuned! ⏳


Amin Rezaei