Ton Crypto Php Laravel Package

Product Decisions This Supports

• Feature feasibility for TON-based products in a PHP/Laravel stack. This package answers a specific scoping question cheaply: can we derive TON keypairs and sign payloads server-side without a Node/Go/Python sidecar? The answer is yes — pure PHP, ext-sodium only, zero composer dependencies. That single answer determines whether a TON login, custodial wallet, or payment flow is a two-week spike or a multi-quarter platform project.
• Non-custodial vs custodial wallet design. The package gives you KeyPair::generate() and deterministic Mnemonic::toKeyPair(), which is enough to model both onboarding paths: a user-supplied 24-word phrase (import/restore flow) or a server-generated keypair with the seed encrypted at rest. This is the core decision in any wallet product; it is normally made months before engineering starts, and it is normally made wrong because the team assumes BIP-39 works everywhere.
• Build vs buy on the crypto primitive. The realistic alternative is writing ~150 lines of PBKDF2/HMAC/sodium glue in-house, or adopting a generic BIP-39 library and shipping silently broken wallets. This package turns "build" into a weekend, and turns "buy a generic library" into a known failure mode you can cite in a decision doc. That is a legitimate roadmap lever, not just an engineering convenience.
• Interoperability / exit-anywhere guarantees. Because derivation mirrors the TON reference implementation byte-for-byte, funds derived here are recoverable in Tonkeeper, MyTonWallet, and any other TON wallet from the same phrase. That is a product promise ("your keys work anywhere"), not a technical detail, and it constrains which libraries you're allowed to adopt.
• Scope boundary setting for the roadmap. The package produces keys, not addresses. Addresses need amashukov/ton-wallet-php; chain reads/writes need toncenter-client-php. Deciding to adopt this as a trio rather than a single dependency is a resourcing decision — plan three integrations, not one, and budget the wallet contract work separately from day one.
• Risk posture on third-party crypto. 0 stars, 0 dependents, one maintainer, README-level maturity. This is the classic "vendor risk vs. time-to-market" tradeoff: adopting buys weeks of delivery, and commits you to a code-review and wrap-it-in-our-own-interface obligation. That obligation should be an explicit roadmap line item, not a silent assumption.
• Compliance and key-custody scoping. If seeds are ever stored server-side, this package's output becomes a regulated asset. Surfacing "we will hold encrypted seed material; what's our retention, rotation, and incident-response story?" early is exactly the sort of decision a PM should force before the sprint, not after the first pen test.

When to Consider This Package

Adopt it when all of the following hold:

• You are on PHP 8.3+ with ext-sodium (Sail/Herd have it; slim Docker images and many distro packages do not — verify before committing, this is the most common install failure).
• Your product needs TON key derivation or Ed25519 signing from PHP, and you are willing to accept a sibling-dependency trio to reach a usable end-to-end flow (ton-crypto-php + ton-wallet-php + toncenter-client-php).
• The cryptography is TOL/TON-adjacent but not the core product — a login flow, an onboarding flow, a payment signature check. If your business is the wallet, the risk calculus changes.
• You can afford the wrapping discipline: an interface you own (TonKeyService), encrypted seed storage and $hidden model attributes, base64 at API boundaries, seed material excluded from logs, Telescope payloads, and queued job properties.
• You accept reviewing the derivation code yourself — it's small enough (a handful of public surfaces) that a senior engineer can verify it against the TON reference implementation in an afternoon. That review is the price of admission, not an optional extra.
• You have a fixture-based test strategy, ideally asserting a derived address against a wallet created in a real TON app — the only test that catches a wrong derivation.

Look elsewhere (or build) when:

• You need addresses, not keys. This package will not produce them; evaluating it alone will produce a false negative on feasibility.
• You need a maintained, multi-contributor dependency with a security track record. Zero stars, zero dependents, single maintainer, readme-tier maturity. If your threat model or procurement process demands an established vendor, this fails on paper regardless of code quality.
• You're considering a BIP-39 library instead. Don't. TON uses PBKDF2-HMAC-SHA512 with salt "TON default seed" at 100,000 iterations plus an extra HMAC pass — a generic BIP-39 helper will produce a valid-looking keypair and an address no TON wallet recognises. That failure is invisible until a user tries to restore.
• You need mnemonic validation (checksum, wordlist membership) as a first-class feature. Assume toKeyPair() accepts an arbitrary string and returns some 32-byte seed. If you need validation, you build it — exactly 24 words, all in the TON/BIP-39 English wordlist, checksum bit set — before handing anything to the library.
• You're doing bulk or high-volume derivation. PBKDF2-SHA512 at 100k iterations is tens of milliseconds of pure-PHP CPU per phrase. Fine for logins and one-off imports; wrong for bulk CSV imports in a request path and a cheap DoS vector on any user-facing endpoint that accepts a phrase.
• Your stack isn't PHP-and-willing-to-own-it. If the team has no appetite for maintaining a thin wrapper around a low-maturity crypto dependency, a service-level integration in a more mature ecosystem may be the better buy.

How to Pitch It (Stakeholders)

For executives, one paragraph: TON is a growing chain and this package makes it possible for our Laravel product to derive TON keys and sign payloads server-side, with no new infrastructure, no new runtime, and no vendor contract. It is MIT-licensed, has zero composer dependencies, and is deliberately scoped: it produces keys, not addresses, so it is one piece of an integration rather than a complete wallet solution. The commercial case is time-to-market — it converts a genuinely risky build (getting TON cryptography subtly wrong, and shipping wallets that users cannot restore) into a reviewed integration of a few hundred lines we can wrap in our own interface and swap out without touching product code.

For engineering, the honest framing: the code is small, correct where it counts, and well-disciplined — final readonly value objects, strict_types, PHPStan level 9, CI, and derived seeds validated against the TON reference implementation. The risk is not the code, it's the dependency: one maintainer, no dependents, readme-level maturity. So we adopt it behind an interface we own, we pay for the derivation review up front, and we build a test suite pinned to a real TON address so any regression or upstream abandonment is caught loudly. Requirements first: PHP 8.3+ and ext-sodium present in every environment including CI and production images.

For security and compliance: this package holds key material, so it inherits every obligation that implies. Seeds are encrypted at rest (Laravel Crypt), excluded from $hidden-less serialisation, kept out of logs, dumps, Telescope payloads, and queued job constructors, and never passed as raw byte strings across a JSON boundary. The $password argument to mnemonic derivation is a second factor that permanently changes the derived key — a UI "password" field must never be wired to it by accident, or we mint unrecoverable wallets. Mnemonic validation is ours to implement, not theirs. These are sprint-one acceptance criteria, not hardening tickets.