About Acki Nacki SDK
Overview of SDK components
Acki Nacki SDK is a customised for Acki Nacki TVM SDK that consists of
Client Libraries
CLI
Local Blockchain
Core TVM-SDK client library is written in Rust, with bindings for other programming languages.
JS/TS guides are present here as reference guides meaning bindings in other languages have the same api calls.
Get quick help in our telegram channel:
Supported languages
Rust (core library)
Repository: https://github.com/tvmlabs/tvm-sdk
What is Core Client Library?
Core Client Library is written in Rust that can be dynamically linked. It provides all heavy-computation components and functions, such as TVM Virtual Machine, Transaction Executor, ABI-related functions, BOC manipulation functions, crypto functions.
The decision to create the Rust library was made after a period of time using pure JavaScript to implement these use cases.
We ended up with very slow work of pure JavaScript and decided to move all this to Rust library and link it to Javascript as a compiled binary including a wasm module for browser applications.
Also this approach provided an opportunity to easily create bindings for any programming language and platform, thus, to make it possible to develop distributed applications (DApps) for any possible use-cases, such as: mobile DApps, web DApps, server-side DApps, enterprise DApp, desktop Dapps etc.
Client Library exposes all the functionality through a few of exported functions. All interaction with library is performed using JSON-RPC like protocol via C .h file.
Official Javascript(Typescript) binding
Repository: JavaScript SDK
You need to install core package and the package with binary for your platform. See the documentation.
Community bindings
If you did not find the language you need
use library module
json_interface
which provides access to library functions through JSON-RPC interface. This interface exports several extern "C" functions. So you can build a dynamic or static link library and link it to your application as any other external libraries. The JSON Interface is fully "C" compliant. You can find description in section JSON Interface.write your own binding to chosen language and share it with community.
If you choose using JSON Interface please read this document JSON Interface.
Here you can find directions how to use json_interface
and write your own binding.
Use-cases
With TVM SDK you can implement logic of any complexity on TVM compatible blockchains (Everscale, Gosh, TON, Venom, etc).
Create and send messages to blockchain
Process messages reliably (supports retries and message expiration mechanics)
Supports TVM Solidity and ABI compatible contracts
Emulate transactions locally
Run get methods
Get account state
Query blockchain data (blocks, transactions, messages)
Sign data/check signature, calculate hashes (sha256, sha512), encrypt/decrypt data
Validate addresses
Work with blockchain native types (bag of cells or BOCs): encode, decode, calculate hash, etc
Works on top of GraphQL API and compatible with Evernode-SE/DS, Evercloud.
Quick Start
Quick Start (Javascript binding)
JavaScript SDK Types and Methods (API Reference)
Core Types and Methods (API Reference)
Versioning
We aim to follow semver practises, although before the mainnet launch we may introduce breaking changes in any release: patch and minor. Check the CHANGELOG.md file for breaking changes.
How to avoid Soft Breaking Problems
Soft Breaking is API changes that include only new optional fields in the existing structures. This changes are fully backward compatible for JSON Interface.
But in Rust such changes can produce some problems with an old client code.
Look at the example below:
There is an API v1.0 function
foo
and the corresponding params structure:
Application uses this function in this way:
API v.1.1 introduces new field in
ParamsOfFoo
:
From the perspective of JSON-interface it isn't breaking change because the new parameter is optional. But code snippet (2) will produce Rust compilation error.
To avoid such problems we recommend to use default implementation inside structure initialisation:
For all Ton Client API structures Default
trait is implemented.
Build client library
The best way to build client libraries is to use build scripts from this repo.
Note: The scripts are written in JavaScript so you have to install Node.js (v.10 or newer) to run them. Also make sure you have the latest version of Rust installed.
To build a binary for a specific target (or binding), navigate to the relevant folder and run node build.js
.
The resulting binaries are placed to bin
folder in the gz-compressed format.
Note that the build script generates binaries compatible with the platform used to run the script. For example, if you run it on Mac OS, you get binaries targeted at Darwin (macOS) platform.
Note: You need latest version of rust. Upgrade it with rustup update
command. Check version with rustc --version
, it should be above or equal to 1.47.0
.
Build artifacts
Rebuild api.json
:
Rebuild docs
:
Rebuild modules.ts
:
Run tests
To run test suite use standard Rust test command
SDK tests need GraphQL endpoint to run on. Such an API is exposed by a Block Keeper which runs in real networks, Local Network or public testnets..
Local Network is used by default with address http://localhost
and port 80. If you launch it on another port you need to specify it explicitly like this: http://localhost:port
. If you need to run tests on a real network use the following environment variables to override the default parameters
Download precompiled binaries (temporarily not maintained)
Instead of building library yourself, you can download the latest precompiled binaries from TVM SDK Binaries Store.
If you want an older version of library (e.g. 0.25.0
for macOS), you need to choose a link to your platform from the list above and replace 0
with a version: https://binaries.tonlabs.io/tonclient_0_25_0_darwin.gz
Downloaded archive is gzipped file
Last updated