toncenter · slavafomin · Apr 23, 2022 · Apr 23, 2022 · Apr 23, 2022 · Apr 23, 2022
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,27 @@
+
+# Contribution guide
+
+All contributions are quite welcome!
+
+Please use the following procedure to contribute:
+
+1. [Create an issue][issues] with description of the
+   proposed changes.
+
+2. Discuss the issue with the project maintainers and other
+   contributors to determine the best course of actions.
+
+3. Write the good quality code, cover it with tests,
+   write the documentation, create a PR.
+
+
+## Building the project
+
+```bash
+npm install 
+
+npm run build
+```
+
+
+  [issues]: https://github.com/toncenter/tonweb/issues
diff --git a/README.md b/README.md
@@ -1,40 +1,73 @@
+
 ![splash_js_sdk](https://user-images.githubusercontent.com/1449561/154848382-e89fef68-3aee-4ca6-8d52-1466bfdf2c89.png)
 
-# TonWeb - JavaScript SDK for [The Open Network](https://ton.org)
+# TonWeb — JavaScript SDK for [The Open Network](https://ton.org)
 
 [![NPM](https://img.shields.io/npm/v/tonweb.svg)](https://www.npmjs.org/package/tonweb)
 
-## Install Web
 
-`npm install tonweb` or `yarn add tonweb`
+## Install for Web or Node.js
 
-```js
-import TonWeb from "tonweb";
+```shell
+npm install tonweb
+```
+
+
+## Install to page directly
+
+```html
+<body>
+    <!-- Page's content -->
+
+    <!-- Specify a path to tonweb.js -->
+    <script type="application/javascript" src="tonweb.js"></script>
+
+    <script type="application/javascript">
+        const tonWeb = new self.TonWeb();
+    </script>
 
-const tonweb = new TonWeb();
+</body>
+
 ```
 
-or
 
-`<script src="tonweb.js"></script>`
+## TonCenter API
 
-`const tonweb = new window.TonWeb();`
+Due to the current technology limitations, TonWeb must
+communicate with the TON nodes using a special proxy-server
+called [TonCenter HTTP API][toncenter], which must be 
+[hosted by you][toncenter-own] separately.
 
-## Install NodeJS
+You can also use our [publicly hosted](#public-toncenter-api)
+TonCenter API if you are learning or just getting started,
+but it enforces strict request limits, so it's not recommended
+to be used in production.
 
-`npm install tonweb` or `yarn add tonweb`
 
-```js
-const TonWeb = require('tonweb');
+## Usage
+
+1. Instantiate `HttpProvider` and the `TonWeb`.
 
-const tonweb = new TonWeb();
+```js
+import TonWeb from 'tonweb';
+
+// Create an instance of HttpProvider that is used to
+// communicate with the TonCenter
+const httpProvider = new TonWeb.HttpProvider(
+    // Use the URL of your hosted TonCenter API
+    'https://toncetner.example.com/api/v2/jsonRPC', {
+        // You can configure TonCenter to require the API key
+        apiKey: 'OPTIONAL_API_KEY'
+    }
+);
+
+// Create an instance of TonWeb
+const tonWeb = new TonWeb(httpProvider);
 ```
 
-## Overview example
+2. Use various provided APIs and utilities:
 
 ```js
-const tonweb = new TonWeb();
-
 const wallet = tonweb.wallet.create({publicKey});
 
 const address = await wallet.getAddress();
@@ -67,79 +100,148 @@ const history = await tonweb.getTransactions(address);
 const balance = await tonweb.getBalance(address);
 
 tonweb.sendBoc(bocBytes);
-
 ```
 
-## API
 
-By default, mainnet [toncenter.com](https://toncenter.com) API is used. Please note that without the API key there will be a request rate limit.
+## Type safety
 
-You can start your own TON HTTP API instance as it is [open source](https://github.com/toncenter/ton-http-api).
+The library is covered with TypeScript types. Declaration
+files are provided with the package. We are strongly recommend
+to use TypeScript for your projects due to the great type safety
+benefits that it provides.
 
-Use mainnet TonCenter API with high ratelimit API key:
 
-```js
-const tonweb = new TonWeb(new TonWeb.HttpProvider('https://toncenter.com/api/v2/jsonRPC', {apiKey: 'YOUR_MAINNET_TONCENTER_API_KEY'}));
-```
+## Documentation
 
-Use testnet TonCenter API with high ratelimit API key:
+Each part is documented separately:
 
-```js
-const tonweb = new TonWeb(new TonWeb.HttpProvider('https://testnet.toncenter.com/api/v2/jsonRPC', {apiKey: 'YOUR_TESTNET_TONCENTER_API_KEY'}));
-```
+| Module                                                    | Description                                                  |
+| --------------------------------------------------------- | ------------------------------------------------------------ |
+| [tonweb](./src/README.md)                                 | Root class and methods.                                      |
+| [tonweb-contract-wallet](./src/contract/wallet/README.md) | Interaction with wallet's smart contracts.                   |
+| [tonweb-contract](./src/contract/README.md)               | Abstract interface to interact with TON smart contracts.     |
+| [tonweb-boc](./src/boc/README.md)                         | Serializations of Cell and BitString.                        |
+| [tonweb-utils](./src/utils/README.md)                     | Work with TON Addresses, coin values, byte arrays, hex, hash functions. |
+| [tonweb-nft](./src/contract/token/nft/README.md)          | work with **TON NFT** (non-fungible tokens).                 |
+| [tonweb-jettons](./src/contract/token/ft/README.md)       | work with **TON Jettons** (fungible tokens).                 |
 
-## Documentation
 
-Each part is documented separately:
+## Support
 
-[tonweb](https://github.com/toncenter/tonweb/blob/master/src/README.md) - root class and methods
+We have Telegram chats for developers with a lively community, don't hesitate to ask any questions there:
 
-[tonweb-contract-wallet](https://github.com/toncenter/tonweb/blob/master/src/contract/wallet/README.md) - interaction with wallet's smart contracts.
+| Link                                   | Title        | Description                                     |
+| -------------------------------------- | ------------ |-------------------------------------------------|
+| [@tondev_eng](https://t.me/tondev_eng) | TON Dev Chat | 🇬🇧 English-speaking TON developers community. |
+| [@tondev](https://t.me/tondev)         | TON Дев Чат  | 🇷🇺 Russian-speaking TON developers community. |
 
-[tonweb-contract](https://github.com/toncenter/tonweb/blob/master/src/contract/README.md) - abstract interface to interact with TON smart contracts.
 
-[tonweb-boc](https://github.com/toncenter/tonweb/blob/master/src/boc/README.md) - serializations of Cell and BitString
+## Self-executing Node.js script
 
-[tonweb-utils](https://github.com/toncenter/tonweb/blob/master/src/utils/README.md) - work with TON Addresses, coin values, byte arrays, hex, hash functions.
+You can use TonWeb as an alternative to Fift, e.g.
+to build binary messages for smart-contracts.
 
+1. Install the TonWeb globally:
+```shell
+npm install -g tonweb
+```
 
-**Also we use JSDoc in code**
+2. Create a text file with the following content:
 
-## Roadmap
+```shell
+#!/usr/bin/env bash
 
-1. Unit-tests
+NODE_PATH="$(npm root -g):$NODE_PATH" node <<EOF
 
-2. Typescript
+  const TonWeb = require('tonweb');
+
+  console.log('TonWeb v' + TonWeb.version);
+
+  const tonWeb = new TonWeb();
+
+  // Work with tonWeb…
 
-## Build
+EOF
+```
 
-```bash
-npm install 
+3. Make it executable:
+```shell
+chmod +x ./script-file
+```
 
-npm run build
+4. Run the script:
+```shell
+./script-file
 ```
 
-## Use as alternative to Fift for building binary messages to smart-contracts
 
-```bash
-npm install -g tonweb
+## Public TonCenter API
 
-export NODE_PATH=$(npm root --quiet -g)
-```
+Though, [hosting your own][toncenter-own] TonCenter API
+server is highly recommended, TON FOUNDATION provides a
+[public TonCenter API server][toncenter],
+that could be used for testing/development purposes or
+for projects with low throughput requirements.
+Both `testnet` and `mainnet` are supported.
 
-Then create your_script.js
+The public server enforces a very strict request limits:
 
-```js
-const TonWeb = require('tonweb');
+| Mode                | Limit  |
+| ------------------- | ------ |
+| Without the API key | 1 RPS  |
+| With the API key    | 10 RPS |
+
+You can obtain an API key by [registering][toncenter-bot]
+for free using a special Telegram bot.
 
-const tonweb = new TonWeb();
 
-. . .
+### Use `mainnet` public TonCenter API with the API key:
 
+```js
+const tonWeb = new TonWeb(
+    new TonWeb.HttpProvider(
+        'https://toncenter.com/api/v2/jsonRPC', {
+            apiKey: 'YOUR_MAINNET_TONCENTER_API_KEY'
+        }
+    )
+);
 ```
 
-run script
 
-```bash
-node your_script.js
+### Use `testnet` public TonCenter API with the API key:
+
+```js
+const tonWeb = new TonWeb(
+    new TonWeb.HttpProvider(
+        'https://testnet.toncenter.com/api/v2/jsonRPC', {
+            apiKey: 'YOUR_TESTNET_TONCENTER_API_KEY'
+        }
+    )
+);
 ```
+
+
+## Roadmap
+
+1. TypeScript support `(present, 90% done)`
+2. Unit-tests `(in progress)`
+3. Better documentation `(TBD)`
+
+
+## Contributing
+
+Please see the [contribution guide](./CONTRIBUTING.md).
+
+
+## License
+
+© TON FOUNDATION
+
+GNU GENERAL PUBLIC LICENSE  Version 3, 29 June 2007
+
+[» Read full license text](./LICENSE)
+
+
+[toncenter]: https://toncenter.com/
+[toncenter-own]: https://github.com/toncenter/ton-http-api#building-and-running
+[toncenter-bot]: https://t.me/tonapibot
diff --git a/src/contract/token/ft/README.md b/src/contract/token/ft/README.md
@@ -0,0 +1,10 @@
+
+# TON Jettons (fungible tokens)
+
+This directory contains implementation of
+[TON Jettons standard][TIP-74] (TIP-74).
+
+Please, see the [code examples](../../../test-jetton.js).
+
+
+  [TIP-74]: https://github.com/ton-blockchain/TIPs/issues/74
diff --git a/src/contract/token/nft/README.md b/src/contract/token/nft/README.md
@@ -0,0 +1,10 @@
+
+# TON NFT (non-fungible tokens)
+
+This directory contains implementation of
+[TON NFT standard][TIP-62] (TIP-62).
+
+Please, see the [code examples](../../../test-nft.js).
+
+
+[TIP-62]: https://github.com/ton-blockchain/TIPs/issues/62