olifanton/ton

PHP library for The Open Network blockchain

1.5.1 2024-08-28 14:33 UTC

Requires

• php: >=8.1
• ext-json: *
• ext-sodium: *
• olifanton/interop: ^1.4
• olifanton/mnemonic: ^1.0.2
• php-http/client-common: ^2.0
• php-http/discovery: ^1.0
• php-http/httplug: ^2.0
• psr/http-client-implementation: ^1.0
• psr/http-factory-implementation: ^1.0
• psr/log: ^1.0|^2.0|^3.0
• psr/simple-cache: ^3.0

Requires (Dev)

• cakephp/cache: ^5.0
• guzzlehttp/guzzle: ^7.5
• http-interop/http-factory-guzzle: ^1.2
• jetbrains/phpstorm-attributes: ^1.0
• mockery/mockery: ^1.5
• overtrue/phplint: 9.3.1
• php-http/guzzle7-adapter: ^1.0
• phpstan/phpstan: ^1.9
• phpunit/phpunit: ^9.5
• vlucas/phpdotenv: ^5.4

MIT

• Roman Zaycev

• blockchain
• ton
• the open network
• olifanton
• toncenter

README

💬 En chat | 💬 Ру чат

Prerequisites

• Minimum PHP 8.1;
• ext-hash;
• ext-sodium required as default cryptographic implementation;
• any httplug-compatible HTTP client (php-http/client-common), see Documentation;
• ext-bcmath not required, but strongly recommended for performance reasons.

Installation

composer require olifanton/ton

Examples

See examples directory.

Running examples

1. Clone repository and install with development dependencies;
2. Get own testnet API key for Toncenter from Telegram bot;
3. Copy .env.dist to .env;
4. Put API key and seed phrase variables to .env file;
5. Run examples in console.

Documentation

Toncenter transport initialization

To use the SDK via Toncenter API, an HTTP client implementation is required. For the example, Guzzle will be used. If you are using another HTTP client supplied by your framework, refer to your framework's documentation and the httplug documentation for additional information.

1. Install http components via Composer:

composer require guzzlehttp/guzzle http-interop/http-factory-guzzle php-http/guzzle7-adapter

1. Setup Toncenter transport:

<?php

use Http\Client\Common\HttpMethodsClient;
use Http\Discovery\Psr18ClientDiscovery;
use Http\Discovery\Psr17FactoryDiscovery;
use Olifanton\Ton\Transports\Toncenter\ToncenterHttpV2Client;
use Olifanton\Ton\Transports\Toncenter\ClientOptions;
use Olifanton\Ton\Transports\Toncenter\ToncenterTransport;

$isMainnet = false;
$toncenterApiKey = "..."; // Request API key from https://t.me/tontestnetapibot or https://t.me/tonapibot

// HTTP client initialization
$httpClient = new HttpMethodsClient(
    Psr18ClientDiscovery::find(),
    Psr17FactoryDiscovery::findRequestFactory(),
    Psr17FactoryDiscovery::findStreamFactory(),
);

// Toncenter API client initialization
$toncenter = new ToncenterHttpV2Client(
    $httpClient,
    new ClientOptions(
        $isMainnet ? "https://toncenter.com/api/v2" : "https://testnet.toncenter.com/api/v2",
        $toncenterApiKey,
    ),
);

// Transport initialization
$toncenterTransport = new ToncenterTransport($toncenter);

// ...

// Now you can use Toncenter transport as access point to blockchain
$toncenterTransport->send($someBoc);

See examples/common.php for complex Toncenter example.

SDK components

Primitives

To read description of primitives (Address, Cell, Slice, Builder, Hashmap), refer to documentation in the olifanton/interop repository.

Performance tips

• First of all, use the latest version of PHP, despite the fact that the minimum version is 8.1
• Install the bcmath extension for PHP. This dramatically speeds up the work with large integers, which is necessary for interacting with TVM
• Disable xdebug (or other debuggers) in your production. BoC serialisation/deserialisation speedup can be up to 5 times with XDEBUG_MODE=off

Contributing

Please make sure to read the Olifanton contribution guide before making a pull request.

Tests

composer run test:unit

License

MIT