Download the PHP package amashukov/toncenter-client-php without Composer

amashukov/toncenter-client-php

Typed PHP toncenter v2 client for The Open Network — PSR-18 transport, {ok, result} envelope unwrapping, retry-aware, typed Value Objects.

A typed PHP client for the toncenter v2 HTTP API on The Open Network (TON). It speaks any PSR-18 HTTP client, unwraps the {ok, result} envelope into typed exceptions in one place, and returns Value Objects instead of loose arrays — masterchain info, account state, a run-get-method stack reader, and typed transactions. TON balances exceed PHP_INT_MAX past ~9,223 TON, so every nano-TON value comes back as a decimal string, never a lossy float. Includes ToncenterWalletRpc, a drop-in WalletRpcInterface adapter for ton-wallet-php.

Features

• {ok, result} envelope unwrapping in one place — a non-200 status, ok: false, or a missing result becomes a TonRpcException; business code never touches the envelope. Toncenter sends its errors with a matching HTTP status and a {"ok": false, "error": …, "code": …} body, so a non-200 response is read for that body: the exception carries toncenter's code and error (code 0 when the body is not toncenter JSON, e.g. a proxy error page). That is how tryLocateResultTx turns toncenter's 404 "transaction was not found" into null.
• Typed Value Objects — masterchain info, account state, run-get-method stack reader, and a five-state transaction status (Pending, Success, ComputePhaseFailed, ActionPhaseFailed, Aborted) derived from the TVM compute / action phases.
• Transaction phases from the transaction BOC — toncenter v2 answers getTransactions without a description, so a naive reader sees every transaction as successful. When the row has no description, the client parses the TL-B Transaction in the row's data field: credit, compute and action phases, aborted, whether a bounce message was sent, and destroyed land in TonTransaction::$description (TonTransactionDescription) and drive the status. getTypedTransactions, getTypedTransaction and tryLocateResultTx refuse a row without data with a TonRpcException, so a transaction read through the client never comes back without its phases: a caller that sees $description === null on such a transaction can treat it as a bug, not as "no bounce".
• Decimal-string big numbers — balances and gas values are returned as decimal strings, safe past PHP_INT_MAX.
• Transport-agnostic — bring your own PSR-18 client and PSR-17 factories. The retry policy and the X-Api-Key rate-limit header are middleware concerns, not baked into the client.
• 542 / 429 retry decider — toncenter emits transient 542 ("no workers available") and 429; the recommended retry status set is documented so a retry middleware can target exactly those.
• Wallet RPC adapter — ToncenterWalletRpc implements Amashukov\TonWallet\WalletRpcInterface (getSeqno + sendBoc) so a ton-wallet-php wallet broadcasts through toncenter with no glue code.

Why amashukov/toncenter-client-php

The common alternative is hand-rolled Guzzle calls scattered across a service layer, each re-implementing envelope checks, bigint parsing, and 542/429 retry logic. This package centralizes all of that behind a typed surface with PHPStan level 9, returns Value Objects instead of arrays, and stays transport-agnostic so retry / API-key concerns live in your PSR-18 pipeline.

Installation

Usage

Any PSR-18 client and PSR-17 factory pair works. The example below wires amashukov/http-client-php (cURL transport + retry / header-injection middleware) with nyholm/psr7 for the PSR-7 messages:

Logging

Pass any PSR-3 logger (Psr\Log\LoggerInterface, e.g. Monolog or a framework's logger) as the last constructor argument; without one the client logs nothing.

• debug — every request (method, path) and every response (status).
• warning — a failure of the transport rather than of the request: the PSR-18 client threw (connection refused, timeout, a dropped connection) or toncenter answered with a 5xx status. Such a failure usually passes on the next call, so it is logged as context, not as an incident.
• error — every other failure that reaches the caller as a TonRpcException: a 4xx status, ok: false, invalid JSON, missing result.
• Both carry exception, method, path and toncenter's code in the context; the exception thrown is the same either way.
• An answer the client handles itself is not an error: toncenter's 404 "transaction was not found" from tryLocateResultTx is logged at debug, and the method returns null.

Reading get-method results

The stack reader is a cursor over a TON TupleItem sum-type (TonTupleItemInt / Cell / Slice / Builder / Null / Tuple) and decodes both decimal and 0x-prefixed bigints via GMP.

Following a message to its result

tryLocateResultTx asks toncenter for the transaction in which the destination processed one internal message, so it does not page through the destination's history and answers the same for a quiet wallet and for an exchange address with thousands of transactions a minute. It returns null while the transaction is not known yet.

Broadcasting a wallet transfer

API

Requirements

• PHP 8.3+
• ext-gmp (bigint decoding of get-method stack values)
• A PSR-18 client + PSR-17 request / stream factories
• Optional: a PSR-3 logger

Related packages

Quality

• PHPStan level 9, clean.
• php-cs-fixer @PER-CS ruleset.
• GitHub Actions CI on every push.

License

MIT — see LICENSE.

Strict evidence for undeployed accounts

TonAccountInfo::isProvenUninitialized() is suitable for deciding that a contract has no deployed token state. It requires an explicit uninitialized, uninit or nonexist wire state, an unsigned decimal-string native balance, and absent/empty code and data. Missing, unknown or malformed fields never qualify. Native TON may still be present at an undeployed address; this predicate does not mean its native balance is zero. The legacy state normalization and isUninitialized() remain compatible, including their defaults; use the strict predicate for absence decisions. Direct constructor calls have no strict wire evidence by default.

Estimate message fees

estimateFee calls the v2 /estimateFee endpoint without sending a transaction. Pass the base64 message body, not the complete external-message BOC. Optional initCodeBoc and initDataBoc support undeployed accounts. ignoreSignature defaults to true; pass false to require a valid signature during estimation.

TonFeeEstimate preserves sourceFees and the ordered destinationFees list. Each TonFeeBreakdown exposes inForwardFee, storageFee, gasFee and forwardFee as nonnegative decimal strings in nanotons, including explicit zero. Missing, negative, fractional or malformed components raise TonRpcException; large JSON integers are preserved without floating-point conversion. Existing transport/envelope errors and logging apply to estimation as to other methods.

This is an estimate, not a receipt or a guaranteed final charge. The provider may return no destination fees; that does not establish zero downstream cost or full trace coverage. Applications must establish which message executions are covered before using the estimate to price a multi-contract operation.