Ton Wallet Php Laravel Package

Technical Evaluation

Architecture Fit

• Strong alignment with TON ecosystem: The package provides a pure-PHP implementation of TON Wallet v4r2, ensuring compatibility with @ton/ton (JavaScript SDK) for address derivation. This is critical for cross-platform consistency in wallet interactions.
• Modular design: The package decouples address derivation, transfer assembly, and RPC broadcasting, allowing for flexible integration with existing Laravel services (e.g., using Symfony bundles or standalone services).
• Offline-first approach: The ability to sign transactions offline and broadcast later via a pluggable RPC interface reduces latency and improves security by minimizing on-chain exposure during transaction assembly.

Integration Feasibility

• Laravel compatibility: The package is dependency-light (only requires ext-sodium and ext-bcmath), making it easy to integrate into Laravel without heavyweight dependencies.
• Symfony bundle support: The related blockchain-context-bundle suggests seamless integration with Laravel’s service container, enabling dependency injection for WalletV4R2, Address, and WalletRpcInterface.
• TON RPC abstraction: The pluggable RPC interface (getSeqno + sendBoc) allows TPMs to swap between TonCenter, custom nodes, or test doubles without modifying business logic.

Technical Risk

• Low-risk core functionality: Address derivation and transfer assembly are battle-tested against @ton/ton, reducing risk of on-chain mismatches.
• RPC dependency: Since broadcasting is not baked in, the TPM must implement or integrate a compatible RPC client (e.g., toncenter-client-php). This adds minor risk if the chosen RPC provider has downtime or rate limits.
• PHP 8.3+ requirement: If the Laravel app uses an older PHP version, this could block adoption. However, Laravel 10+ supports PHP 8.3+, mitigating this risk.
• Limited adoption: The package has 0 stars/dependents, indicating unproven real-world usage. However, its MIT license, PHPStan L9, and parity with @ton/ton reduce this concern.

Key Questions

1. RPC Strategy:

   • Will the team use TonCenter, a self-hosted node, or a custom RPC provider? If TonCenter, the toncenter-client-php adapter simplifies integration.
   • Are there rate limits or reliability concerns with the chosen RPC provider?

2. Transaction Lifecycle:

   • How will sequence number (seqno) management be handled? Will it be fetched per-transaction or cached?
   • Are there idempotency requirements for retries (e.g., failed broadcasts)?

3. Error Handling:

   • How will failed broadcasts (e.g., insufficient funds, network errors) be retried or logged?
   • Should the package’s offline signing be extended to support multi-signature wallets or custom contract interactions?

4. Scaling:

   • Will the package be used for high-volume transactions (e.g., batch processing)? If so, parallel signing or worker queues may be needed.
   • Are there performance bottlenecks in address derivation or BOC serialization for large-scale use?

5. Testing:

   • How will test doubles (e.g., mock RPC) be integrated into Laravel’s testing suite?
   • Should fuzz testing be added to validate address parsing/serialization edge cases?

Integration Approach

Stack Fit

• Laravel + PHP 8.3+: The package’s minimal dependencies (ext-sodium, ext-bcmath) align perfectly with Laravel’s ecosystem. No additional PHP extensions are required beyond standard Laravel setups.
• Service Container Integration:
  • Bind WalletV4R2, Address, and WalletRpcInterface as Laravel services for dependency injection.
  • Example:

    $this->app->bind(WalletRpcInterface::class, function ($app) {
        return new TonCenterRpcClient(config('ton.rpc_key'));
    });
    

• Symfony Bundle (Optional):
  • Use blockchain-context-bundle to centralize TON-related services (wallets, RPC clients, mnemonic handling) and reduce boilerplate.

Migration Path

1. Phase 1: Core Integration

   • Install the package:

     composer require amashukov/ton-wallet-php amashukov/toncenter-client-php
     

   • Implement a basic RPC adapter (e.g., TonCenterRpc) for WalletRpcInterface.
   • Test address derivation and offline transfer assembly in isolation.

2. Phase 2: Laravel Service Wrapping

   • Create a Laravel service class (e.g., TonWalletService) to encapsulate wallet operations:

     class TonWalletService {
         public function __construct(
             private WalletV4R2 $wallet,
             private WalletRpcInterface $rpc
         ) {}
     
         public function sendTransfer(Address $to, string $amount): string {
             $messages = [new InternalMessage($to, $amount, false)];
             return $this->wallet->sendTransfer($this->rpc, $messages);
         }
     }
     

   • Register the service in AppServiceProvider.

3. Phase 3: RPC and Error Handling

   • Add retry logic for failed broadcasts (e.g., using Laravel’s retry helper).
   • Implement seqno caching (e.g., Redis) to avoid repeated RPC calls.
   • Extend the RPC interface to support custom error handling (e.g., mapping TonCenter errors to Laravel exceptions).

4. Phase 4: Advanced Use Cases

   • Integrate with Laravel Queues for async transaction broadcasting.
   • Add multi-signature support or custom contract interactions if needed.

Compatibility

• TON Wallet v4r2: The package matches @ton/ton byte-for-byte, ensuring compatibility with existing TON wallets and tools.
• Address Formats: Supports user-friendly (UQ..., EQ...) and raw (workchain:hex) formats, reducing friction with frontend integrations.
• BOC Serialization: Uses amashukov/ton-cell-php for Cell/BOC handling, which is a dependency and thus pre-integrated.

Sequencing

1. Prerequisites:
   • Ensure PHP 8.3+ and required extensions (sodium, bcmath) are installed.
   • Set up a TON RPC provider (TonCenter or self-hosted node).
2. Core Setup:
   • Install dependencies and configure the RPC client.
   • Implement a mnemonic-to-keypair flow (e.g., using Amashukov\TonCrypto\Mnemonic).
3. Testing:
   • Validate address derivation against @ton/ton or a TON explorer.
   • Test offline signing and broadcasting in a staging environment.
4. Production Rollout:
   • Gradually replace manual TON interactions (e.g., in payment controllers) with the new service.
   • Monitor seqno management and broadcast success rates.

Operational Impact

Maintenance

• Low Maintenance Overhead:
  • The package is MIT-licensed, actively CI-tested (PHPStan L9), and dependency-light, reducing long-term maintenance risks.
  • Updates can be version-pinned to avoid breaking changes.
• Dependency Management:
  • Monitor amashukov/ton-cell-php and amashukov/ton-crypto-php for updates, as they are core dependencies.
  • If using toncenter-client-php, watch for TonCenter API changes (e.g., rate limits, endpoint updates).

Support

• Debugging:
  • Address derivation issues: Cross-check with @ton/ton or a TON explorer.
  • Broadcast failures: Use the RPC provider’s logs (e.g., TonCenter) or implement detailed error logging in Laravel.
  • Offline signing: Validate BOC serialization with ton-cli or a TON testnet.
• Community Support:
  • Limited by 0 stars/dependents, but the MIT license and GitHub issues provide a fallback.
  • Consider contributing to the repo or forking if critical bugs arise.

Scaling

• Horizontal Scaling:
  • The package is stateless (except for seqno management), making it easy to scale with multiple Laravel instances.
  • Use Redis or database caching for seqno to avoid RPC bottlenecks.
• High-Volume Transactions:
  • For batch processing, implement parallel signing (e.g., using Laravel Jobs + Queues).
  • Consider offloading BOC serialization to a worker process if CPU becomes a bottleneck.
• RPC Load:
  • If using TonCenter, monitor API limits and implement exponential backoff for retries.
  • For self-hosted nodes, ensure the node can handle the transaction throughput.

Failure Modes

| Failure Scenario | Impact