Boilerplate starter template for a new TON blockchain project - FunC contracts, JS tests, compilation and deployment scripts

Overview

TON Starter Template - Contracts

Starter template for a new TON project - FunC contracts, JS tests, compilation and deployment scripts

Overview

This project is part of a set of 3 typical repositories needed for a blockchain dapp running on TON blockchain:

  • Smart contracts in FunC that are deployed on-chain (this repo)
  • Web frontend for interacting with the dapp from a web browser (coming soon)
  • Telegram bot for interacting with the dapp from inside Telegram messenger (coming soon)

What does this repo contain?

  • contracts/*.fc - Smart contracts for TON blockchain written in FunC language
  • test/*.spec.ts - Test suite for the contracts in TypeScript running on Mocha test runner
  • build/_build.ts - Build script to compile the FunC code to Fift and TVM opcodes
  • build/_deploy.ts - Deploy script to deploy the compiled code to TON mainnet (or testnet)
  • build/_setup.ts - Setup script to install build dependencies (used primarily for Glitch.com support)

There is no one official way to develop smart contracts for TON. Every developer has their own best practices. This setup is definitely opinionated and some developers may not appreciate the choices made. Nevertheless, we stand by every choice made here and believe that this is the optimal setup to develop fully tested contracts in the most seamless way possible.

Some of the opinionated choices made here include:

  • Cross platform support - allow developers to work on Mac M1, Mac Intel, Windows or Linux
  • Strong belief in tests - contracts often manage money - they must be developed under high scrutiny
  • Clear and documented code to help users audit the contracts sources and understand what they do
  • Reliance on modern TypeScript to develop clean and typed scripts and tests in a modern framework
  • Reliance on TypeScript for deployment instead of working with fift CLI tools - it's simply easier
  • Tests are executed in JavaScript with TVM in web-assembly - a great balance of speed and convenience
  • Following of the TON contract best practices appearing in the official docs

Dependencies and requirements

To setup your local machine for development, please make sure you have the following:

  • A modern version of Node.js
    • Installation instructions can be found here
    • Run in terminal node -v to verify your installation, the project was tested on v17.3.0
  • The func CLI tool (FunC compiler)
    • Installation instructions can be found here
    • Run in terminal func -V to verify your installation
  • The fift CLI tool
    • Installation instructions can be found here
    • Don't forget to set the FIFTPATH env variable as part of the installation above
    • Run in terminal fift -V and fift to verify your installation
  • A decent IDE with FunC and TypeScript support

Once your local machine is ready, install the project:

  • Git clone the repo locally and rename the directory to your own project name
  • In the root repo dir, run in terminal npm install

or.. work 100% online instead

Alternatively, you can ignore the above requirements and develop right inside a web browser with an online IDE and zero setup. Simply open this repo inside Glitch without installing anything:

  • Create your new Glitch workspace by opening this link in your browser
  • Wait about 60 seconds until installation completes
    (click the "LOGS" button on the bottom of the IDE to see progress)
  • Edit your contract files and tests in the online IDE
  • To run terminal commands like npm run build click the "TERMINAL" button on the bottom of the online IDE
  • Working online is slow! run on a local machine if you want a much faster experience

Development instructions

  • Write code

    • FunC contracts are located in contracts/*.fc
      • Standalone root contracts are located in contracts/*.fc
      • Shared imports (when breaking code to multiple files) are in contracts/imports/*.fc
      • Contract-specific imports that aren't shared are in contracts/imports/mycontract/*.fc
    • Each contract may have optional but recommended auxiliary files:
      • TL-B file defining the encoding of its data and message ops in contracts/mycontract.tld
      • TypeScript file that implements the encoding of its data and message ops in contracts/mycontract.ts
    • Tests in TypeScript are located in test/*.spec.ts
  • Build

    • In the root repo dir, run in terminal npm run build
    • Compilation errors will appear on screen
    • Resulting build artifacts include:
      • mycontract.merged.fc - merged and flattened FunC source code with all imports
      • mycontract.fif - Fift file result of compilation (not very useful by itself)
      • mycontract.cell - the binary code cell of the compiled contract (for deployment)
  • Test

    • In the root repo dir, run in terminal npm run test
    • Don't forget to build (or rebuild) before running tests
    • Tests are running inside Node.js by running TVM in web-assembly using ton-contract-executor
  • Deploy

    • Make sure all contracts are built and your setup is ready to deploy:
      • Each contract to deploy should have a script build/mycontract.deploy.ts to return its init data cell
      • The deployment wallet is configured in .env (created automatically if not exists), with contents:
        DEPLOYER_MNEMONIC="mad nation chief flavor ..." (24 secret words)
    • To deploy to mainnet (production), run in terminal npm run deploy
      • To deploy to testnet instead (where TON coins are free), run npm run deploy:testnet
      • Follow the on-screen instructions of the deploy script
Comments
  • NodeJS 18 Fix

    NodeJS 18 Fix

    It seems that in node.js 18 ton-contract-exectuaor wasm build doesn't work, This issue has a good explanation

    npm run test now runs with --no-experimental-fetch flag

    opened by doronaviguy 1
  • Create a process the generates deep links for contract interaction

    Create a process the generates deep links for contract interaction

    • expose contracts message generators, (arg1, arg2) => Promise,
    • getters method with parameter signature and result encoding ** balanceOf( address) => Promise**
    opened by doronaviguy 1
  • WalletV4 not supported by ton v9...

    WalletV4 not supported by ton v9...

    Hello.

    I want to ask you to update the version of the ton library to the latest because right now, newcomers are confused that they can't use V4 wallet contracts while it's necessary by TonHub.

    So they lose their time understanding what's wrong.

    opened by SwiftAdviser 0
  • Deploying to testnet doesn't work

    Deploying to testnet doesn't work

    When deploying a contract to testnet the build/_deploy.ts doesn't work correctly if process.env.TESTNET is not set.

    The first time scripts checks for either TESTNET env or npm command match: image

    The following times script only checks for TESTNET env and not npm command match so TonClient will always use mainnet toncenter if process.env.TESTNET is not set: image

    opened by serhiibeznisko 0
  • fixed deploy

    fixed deploy

    Needed to update to use json artifact instead of .cell

    ➜ tonstarter-contracts git:(github_actions) ✗ npm run deploy

    [email protected] deploy ts-node ./build/_deploy.ts

    ================================================================= Deploy script running, let's find some contracts to deploy..

    • We are working with 'testnet' (https://t.me/testgiver_ton_bot will give you test TON)

    • Config file '.env' found and will be used for deployment!

    • Wallet address used to deploy from is: EQD4gS-Nj2Gjr2FYtg-s3fXUvjzKbzHGZ5_1Xe_V0-GCp0p2
    • Wallet balance is 0.4 TON, which will be used for gas
    • Found root contract 'build/main.deploy.ts - let's deploy it':
    • Based on your init code+data, your new contract address is: EQC-QTihJV_B4f8M2nynateMLynaRT_uwNYnnuyy87kam-G7
    • Let's deploy the contract on-chain..
    • Deploy transaction sent successfully
    • Block explorer link: https://test.tonwhales.com/explorer/address/EQC-QTihJV_B4f8M2nynateMLynaRT_uwNYnnuyy87kam-G7
    • Waiting up to 20 seconds to check if the contract was actually deployed..
    • SUCCESS! Contract deployed successfully to address: EQC-QTihJV_B4f8M2nynateMLynaRT_uwNYnnuyy87kam-G7
    • New contract balance is now 0.018096 TON, make sure it has enough to pay rent
    • Running a post deployment test: Getter 'counter' = 11 Sent 'increment' op message Getter 'counter' = 12
    opened by shaharyakir 0
  • fix: update release url for fiftlib.zip

    fix: update release url for fiftlib.zip

    Fixes #14

    Release https://github.com/ton-defi-org/ton-binaries/releases/fiftlib doesn't seem to include fiftlib.zip so I swapped it with https://github.com/ton-defi-org/ton-binaries/releases/ubuntu-18-0.3.0 and it seems to work just fine in Glitch.

    Although, I'm not sure about potential version mismatch.

    opened by noctifer20 0
Owner
TON DeFi Ecosystem
TON DeFi Ecosystem
Solana blockchain candy machine app boilerplate on top of Metaplex Candy Machine. NextJS, Tailwind, Anchor, SolanaLabs.React, dev/mainnet automation scripts.

NFT Candy Factory NOTE: This repo will prob only work on unix-based environments. The NFT Candy Factory project is designed to let users fork, customi

Kevin Faveri 261 Dec 30, 2022
Grupprojekt för kurserna 'Javascript med Ramverk' och 'Agil Utveckling'

JavaScript-med-Ramverk-Laboration-3 Grupprojektet för kurserna Javascript med Ramverk och Agil Utveckling. Utvecklingsguide För information om hur utv

Svante Jonsson IT-Högskolan 3 May 18, 2022
Hemsida för personer i Sverige som kan och vill erbjuda boende till människor på flykt

Getting Started with Create React App This project was bootstrapped with Create React App. Available Scripts In the project directory, you can run: np

null 4 May 3, 2022
Kurs-repo för kursen Webbserver och Databaser

Webbserver och databaser This repository is meant for CME students to access exercises and codealongs that happen throughout the course. I hope you wi

null 14 Jan 3, 2023
🦠🔬 Forta agent that detect deployment of smart contracts containing an exploit function

Attack Simulation Bot Description The agent detects deployment of smart contracts containing an exploit function. Using a simulation-based approach, t

Artem Kovalchuk 29 Dec 26, 2022
Simple NextJS Project Template to write less boilerplate code when starting a new Next JS Project

Simple NextJS Project Template to write less boilerplate code when starting a new Next JS Project

Juan David Ramirez Mendoza 1 Feb 12, 2022
SAP Community Code Challenge: This repository contains an empty OpenUI5 application and end-to-end tests written with wdi5. Take part in the challenge and develop an app that passes the tests.

SAP Community Code Challenge - UI5 The change log describes notable changes in this package. Description This repository is the starting point for the

SAP Samples 8 Oct 24, 2022
The best Discord bot with a shit ton of commands w/ a website.

REAPER An Multi-purpose Discord bot with many features! Getting started Creating a fork: 1). Click here to fork the repository 2). Open your terminal

Ryder 2 Oct 6, 2022
Contracts with missing implementation details and unit tests to help guide junior solidity developers.

template-challenge-staking Contracts with missing implementation details and unit tests to help guide junior solidity developers. Getting started Open

BuiltByFrancis 4 Oct 7, 2022
Minimalistic configuration for TS to only extend JS with types. No TS features, no bundling. Readable maintainable code after compilation.

ts-guideline Minimalistic configuration for TS to only extend JS with types. No TS-scpecific features, no bundling. Readable maintainable code after c

Georg Oldenburger 41 Dec 22, 2022
A compilation of Google Tag Manager (GTM) adapters written for measuring interactions with embedded content.

Google Tag Manager (GTM) Custom HTML Adapters for Measuring Embedded Content Interactions This repository contains adapters for sending interaction da

Derek Cavaliero 7 Oct 3, 2022
🌬 Opiniated Nuxt 3 Starter — visual deployment indicator & more

Nuxt 3 Minimal Starter I recommend to look at the documentation. Key Features ?? State management with Pinia ?? Prettier & ESLint ?? Pre-configured VS

Johann Schopplich 7 Dec 7, 2022
Elrond blockchain CLI helper tools - interaction with APIs, smart contracts and protocol

Buildo Begins ?? Meet Buildo. He is here to help you start creating in the Elrond blockchain ecosystem. Here is where everything begins. I'm going on

Elrond's Dev Guild 22 Dec 30, 2022
JellyChain1 is a blockchain network platform that supports smart contracts and can act as a payment system/cryptocurrency

JellyChain1 is an experimental blockchain network, that will serve as a starter blockchain test network and scale out database software and other applications. JellyChain1 is created to cut energy costs when mining transactions on the blockchain.

JellyChain 10 Dec 1, 2022
Context-aware smart contracts for blockchain IoT systems

Context-aware smart contracts for blockchain IoT systems It contains 2 directories: contracts: contains the ContextAwareSmartContract.sol contract wit

ibelab 6 Jun 17, 2022
Using a Decentralized Application (DApp) to Sell artwork on the Ethereum blockchain with smart contracts written in Solidity.

Decentralized Applications For Selling Limited Time Artwork This repository houses the Solidity, JavaScript, and HTML code for a Decentralized Applica

Keyan Ahmadi 4 Mar 20, 2023
GitHub starter project link: https://github.com/buildspace/waveportal-starter-project

Running React on Repl.it React is a popular JavaScript library for building user interfaces. Vite is a blazing fast frontend build tool that includes

MD Rafi Uddin 0 Jun 5, 2022
HackMIT 2022. 2nd Place in Blockchain for Society sponsored by Jump Crypto. A revolutionary web application that leverages machine learning and blockchain technology to improve the crowdsourcing experience!

?? Wikisafe ?? Wikisafe is a revolutionary new crowdsourcing web application that innovates the process of crowdsourcing information. This application

Benson Liu 5 Dec 8, 2022