Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yungwine/TonTools
High-level OOP Python library to interact with TON Blockchain
https://github.com/yungwine/TonTools
hack-ton-berfest hacktoberfest
Last synced: 11 days ago
JSON representation
High-level OOP Python library to interact with TON Blockchain
- Host: GitHub
- URL: https://github.com/yungwine/TonTools
- Owner: yungwine
- License: mit
- Created: 2022-11-23T13:11:50.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2024-07-24T12:28:18.000Z (3 months ago)
- Last Synced: 2024-07-31T20:39:57.472Z (3 months ago)
- Topics: hack-ton-berfest, hacktoberfest
- Language: Python
- Homepage:
- Size: 75.2 KB
- Stars: 97
- Watchers: 2
- Forks: 21
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ton - yungwine/TonTools - High-level library with HTTP/ADNL interaction with liteservers. (🧑💻 Get Coding / Libraries)
README
# TonTools
__TonTools__ is a _high-level_ OOP library for Python, which can be used to interact with [TON Blockchain](https://ton.org).
If you have any questions join Python - TON [developers chat](https://t.me/pythonnton).
[comment]: <> ([![PyPI version](https://badge.fury.io/py/tontools.svg)](https://badge.fury.io/py/tontools))
[![PyPI version](https://badge.fury.io/py/tontools.svg)](https://badge.fury.io/py/tontools) ![](https://pepy.tech/badge/tontools) [![Downloads](https://static.pepy.tech/badge/tontools/month)](https://pepy.tech/project/tontools) [![](https://img.shields.io/badge/%F0%9F%92%8E-TON-grey)](https://ton.org)
## How to install:```bash
pip install tontools
```
## Possibilities
With __TonTools__ you can:
* Scan custom Contracts and run get methods
* Create, deploy and scan wallets
* Scan NFT Collections, Items, Sale contracts
* Scan Jettons, Jetton Wallets
* Transfer Tons, Jettons, NFTs
* Scan Transactions in raw or User-Friendly forms
* And so much more...
## Examples
You can find them in `examples/` directory.## Donations
__TON__ - EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG## Providers
__TonTools__ gets data from blockchain using Providers: [TonCenterClient](https://toncenter.com/api/v2/), [LsClient](https://ton.org/docs/participate/nodes/node-types),
[DtonClient](https://docs.dton.io/dton/) and [TonApiClient](https://tonapi.io/swagger-ui)Most provider methods are the same, but there are some differences.
### TonCenterClient
[TonCenter](https://toncenter.com/api/v2/) is an Api which uses [lite servers](https://ton.org/docs/participate/nodes/node-types)
To initialize TonCenterClient:
```python
client = TonCenterClient(base_url='http://127.0.0.1:80/')
or
client = TonCenterClient(api_key)
```
Notice that TonCenter has Limit 10 RPS with Api Key, so It's highly recommend to use [Local TonCenter](https://github.com/toncenter/ton-http-api)
and specify your host in `base_url` parameter or use the [Orbs Ton Access](https://www.orbs.com/ton-access/):```python
client = TonCenterClient(orbs_access=True,
testnet=True)contract = Contract('EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG', client)
print((await contract.get_transactions(limit=10))[-1].out_msgs[0].destination) # kQCdaMggjCXoW867yRXilPw2bu8Av9dSBlGGCdDPIGNLKM8N
```### LsClient
**LsClient** gets data from blockhain using [lite servers](https://ton.org/docs/participate/nodes/node-types) (based on [pytonlib](https://github.com/psylopunk/pytonlib))
To initialize LsClient:
```python
client = LsClient(ls_index=2, default_timeout=30, addresses_form='user_friendly')
await client.init_tonlib()
```
*LsClient* is some more advanced, for e.g. you may need to compile binaries to use it.### DtonClient
[Dton](https://docs.dton.io/dton) is a high level indexing GraphQL Api.To initialize DtonClient:
```python
client = DtonClient(
key: str = None, # dton api key
addresses_form='user_friendly', # addresses_form could be 'raw' or 'user_friendly'
testnet=False, # if testnet, all addresses will be in testnet form and base url will start with https://testnet.dton.io/
private_graphql=False # you can use private_graphql if you have an api key
)
```
**_Note:_** Dton currently doesn't support sending messages to blockchain, so you can't, for example, transfer toncoins using this provider### TonApiClient - currently v1
**_Note:_** in future TonApiClient will be overwritten to use v2 methods
and current TonApiClient will be renamed into TonApiClientV1, because tonapi v1 endpoints
soon will become unsupported[TonApi](https://tonapi.io/swagger-ui) is a high level indexing Api.
To initialize TonApiClient:
```python
client = TonApiClient(api_key, addresses_form)
```
`TonApiClient` hasn't `run_get_method` method, but it fast (cause of indexator), so
you should use it if you want to scan a lot of _transactions_ and _contracts_## Contracts
All _Contracts_ are inherited from the base class **Contract**, which has
`.get_transactions(), .run_get_method(), .get_balance(), .get_state()` methods.
So you can use them with any type of **Contract**:
```python
client = TonCenterClient(base_url='http://127.0.0.1:80/')item = NftItem('EQDzyRLwjasHwP-y5c9rtoVi2iqriu-sbL3080FlCc-XyUG4', provider=client)
await item.update()owner = Wallet(provider=client, address=item.sale.owner)
transactions = await owner.get_transactions(limit=2)print(transactions[0], transactions[1])
# Transaction({"type": "out", "utime": 1677531709, "hash": "h+lVX0qK4T76QtRqC0FWWGhLptgPLM4MjSEbgKODcFc=", "value": 2500.0, "from": "EQBZVBXBpirFPOQ5Wmgi5Es2hDCRAfiT3i5JRy_gVsJOlpZv", "to": "EQBfAN7LfaUYgXZNw5Wc7GBgkEX2yhuJ5ka95J1JJwXXf4a8", "comment": "6017835"}) Transaction({"type": "in", "utime": 1677413260, "hash": "erk0nLWW9W3m9boFM+/9v0YSeRz1jJvpyiRQYEgN5AE=", "value": 1e-09, "from": "EQCPGzW1dJURRybL41Q3KYfzX4fZdQUeY8-7-TKyeR7f-7cU", "to": "EQBZVBXBpirFPOQ5Wmgi5Es2hDCRAfiT3i5JRy_gVsJOlpZv", "comment": ""})print(await item.sale.get_balance()) # 75730000
```
You can init object of some Contract just specifying `address` and `provider`,
but to get full data of this object you should call `await object.update()`### NFT Contracts
There are `NftItem, NftCollection and NftItemSale` classes.
```python
item = NftItem('EQDzyRLwjasHwP-y5c9rtoVi2iqriu-sbL3080FlCc-XyUG4', provider=client)
await item.update()collection = item.collection
await collection.update()print(collection.metadata) # {"name": "Whales Club", "description": "Collection limited to 10000 utility-enabled NFTs, where the token is your membership to the Whales Club. Join the club and participate in weekly Ambra token giveaways, have access to the most profitable Ton Whales decentralized staking pools and many other useful club privileges.", "external_link": "https://tonwhales.com/club", "external_url": "https://tonwhales.com/club", "image": "ipfs://QmZc5PwuyVKSV4urDTArqfDbkGVjkKs6q4dBk8kpPt1bqD/logo.gif", "social_links": ["https://t.me/tonwhalesnft", "https://t.me/tonwhalesnften", "https://twitter.com/whalescorp"], "cover_image": "ipfs://QmZc5PwuyVKSV4urDTArqfDbkGVjkKs6q4dBk8kpPt1bqD/cover.gif"}
items = await collection.get_collection_items()
print(len(items), items[0]) # 1621 NftItem({"address": "EQD6ufFjSIUJSkbVuV7w00ORT8UvoMLQ9RDZ1lJ8sYh3cOIx"})sale = item.sale
print(sale.price_value, sale.owner) # 200000000000 EQBZVBXBpirFPOQ5Wmgi5Es2hDCRAfiT3i5JRy_gVsJOlpZv
```### Jetton Contracts
There are `Jetton and JettonWallet` classes.
```python
client = LsClient(ls_index=2, default_timeout=30)
await client.init_tonlib()jetton = Jetton('EQBl3gg6AAdjgjO2ZoNU5Q5EzUIl8XMNZrix8Z5dJmkHUfxI', provider=client)
print(jetton) # Jetton({"address": "EQBl3gg6AAdjgjO2ZoNU5Q5EzUIl8XMNZrix8Z5dJmkHUfxI"})await jetton.update()
print(jetton) # Jetton({"supply": 4600000000000000000, "address": "EQBl3gg6AAdjgjO2ZoNU5Q5EzUIl8XMNZrix8Z5dJmkHUfxI", "decimals": 9, "symbol": "LAVE", "name": "Lavandos", "description": "This is a universal token for use in all areas of the decentralized Internet in the TON blockchain, web3, Telegram bots, TON sites. Issue of 4.6 billion coins. Telegram channels: Englishversion: @lave_eng \u0420\u0443\u0441\u0441\u043a\u043e\u044f\u0437\u044b\u0447\u043d\u0430\u044f \u0432\u0435\u0440\u0441\u0438\u044f: @lavet", "image": "https://i.ibb.co/Bj5KqK4/IMG-20221213-115545-207.png", "token_supply": 4600000000.0})jetton_wallet = await jetton.get_jetton_wallet('EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG') # for TonCenterClient and LsClient
print(jetton_wallet) # JettonWallet({"address": "EQDgCBnCncRp4jOi3CMeLn-b71gymAX3W28YZT3Dn0a2dKj-"})await jetton_wallet.update()
print(jetton_wallet) # JettonWallet({"address": "EQDgCBnCncRp4jOi3CMeLn-b71gymAX3W28YZT3Dn0a2dKj-", "balance": 10000000000000, "owner": "EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG", "jetton_master_address": "EQBl3gg6AAdjgjO2ZoNU5Q5EzUIl8XMNZrix8Z5dJmkHUfxI"})my_wallet_mnemonics = []
my_wallet = Wallet(provider=client, mnemonics=my_wallet_mnemonics, version='v4r2')
await my_wallet.transfer_jetton(destination_address='address', jetton_master_address=jetton.address, jettons_amount=1000, fee=0.15) # for TonCenterClient and LsClient
await my_wallet.transfer_jetton_by_jetton_wallet(destination_address='address', jetton_wallet='your jetton wallet address', jettons_amount=1000, fee=0.1) # for all clients
```### Wallet contracts
Currently there is only `Wallet` class (will add HighLoadWallet and MultiSigWallet in future versions).You can create new wallet just calling `Wallet(provider, wallet_version)`, check existing wallet `Wallet(provider, address)` or enter wallet `Wallet(provider, mnemonics, wallet_version)`
```python
client = LsClient(ls_index=2, default_timeout=20)
await client.init_tonlib()my_wallet_mnemonics = []
my_wallet = Wallet(provider=client, mnemonics=my_wallet_mnemonics, version='v4r2')
my_wallet_nano_balance = await my_wallet.get_balance()new_wallet = Wallet(provider=client)
print(new_wallet.address, new_wallet.mnemonics, my_wallet_nano_balance) # EQBcMK8CBrZKfSYdvT8FDVo1TxZV_d3Lz-xPyGp8c7mUacko ['federal', 'memory', 'scare', 'exact', 'extend', 'rain', 'private', 'ribbon', 'inspire', 'capital', 'arrow', 'glimpse', 'toy', 'double', 'man', 'speak', 'imitate', 'hint', 'dinner', 'oblige', 'rather', 'answer', 'unfold', 'small'] 496348289non_bounceable_new_wallet_address = Address(new_wallet.address).to_string(True, True, False)
await my_wallet.transfer_ton(destination_address=non_bounceable_new_wallet_address, amount=0.02, message='just random comment')
await new_wallet.deploy()print(await new_wallet.get_state()) # active
```### Transactions
Class `Transaction` has `.to_dict()` and `.to_dict_user_friendly()` methods.
The first one returns full data of transaction, and the second one only user-friendly data of transaction*status* - True if computation and action phases have returned zero code.
```python
client = TonApiClient()
wallet = Wallet(provider=client, address='EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG')
trs = await wallet.get_transactions(limit=1)
print(trs[0].to_dict()) # {'utime': 1677658702, 'fee': 7384081, 'data': 'a lot of bytes :)', 'hash': 'skqFysIHksJDkH8Sy4UAKmQSuW95WGS6V/XD/QaJCdE=', 'in_msg': {'created_lt': 35690250000001, 'source': '', 'destination': 'EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG', 'value': 0, 'msg_data': 'a lot of bytes :'}, 'out_msgs': [{'created_lt': 35690250000002, 'source': 'EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG', 'destination': 'EQDgCBnCncRp4jOi3CMeLn-b71gymAX3W28YZT3Dn0a2dKj-', 'value': 100000000, 'msg_data': 'te6ccgEBAQEAVwAAqg+KfqUAAAAAAAAAAF6NSlEACADvv6jNfMa6nPxbbgyeiO7riR4Cq0JAynas1pLFqNpq9wAd9/UZr5jXU5+LbcGT0R3dcSPAVWhIGU7VmtJYtRtNXsA='}]}
print(trs[0].to_dict_user_friendly()) # {'type': 'out', 'utime': 1677658702, 'status': True, 'hash': 'skqFysIHksJDkH8Sy4UAKmQSuW95WGS6V/XD/QaJCdE=', 'value': 0.1, 'from': 'EQBvW8Z5huBkMJYdnfAEM5JqTNkuWX3diqYENkWsIL0XggGG', 'to': 'EQDgCBnCncRp4jOi3CMeLn-b71gymAX3W28YZT3Dn0a2dKj-', 'comment': ''}
```
_Note:_ `.to_dict_user_friendly()` works good with many recipients in one transaction
#### Messages
You can check the type of message using `.try_detect_type()` method.
```python
client = TonCenterClient()contract = Contract('EQB5DER03H1uhKGX6BJh_IWa_zV9MzvH2lcy6t30tZ9k4RSL', client)
print((await contract.get_transactions())[-1].in_msg.try_detect_type()) # JettonTransferNotificationMessagecontract = Contract('EQB5QP6tAVlWBXKhMN9TynyusIR8_oTuN10NozaOfpFzAXDj', client)
print((await contract.get_transactions())[-1].in_msg.try_detect_type()) # JettonInternalTransferMessage
```