Toncenter Client Php Laravel Package

Technical Evaluation

Architecture Fit

• Strong alignment with Laravel’s HTTP stack: The package leverages PSR-18 (HTTP client) and PSR-17 (factories), which Laravel’s built-in HttpClient (Guzzle-based) and Symfony HttpClient already support. No architectural friction exists for integration.
• Decoupled design: The client is transport-agnostic, allowing Laravel’s native HttpClient or third-party PSR-18 clients (e.g., GuzzleHttp\Client) to be used without modification.
• Value Object pattern: Typed responses (e.g., TonMasterchainInfo, TonTransaction) align well with Laravel’s DTO/Collection patterns, reducing manual parsing and validation overhead.
• TON-specific abstractions: The package encapsulates TON’s unique data structures (e.g., run-get-method stack decoding, bigint handling) behind a clean API, abstracting blockchain complexity from business logic.

Integration Feasibility

• Minimal boilerplate: Laravel’s HttpClient can replace the example’s CurlClient + middleware pipeline with built-in retry and header injection (via withOptions() or middleware).
• Symfony compatibility: Laravel’s dependency injection and service container can directly instantiate the client, with PSR-17 factories resolved via Laravel’s Psr17Factory or Symfony\Component\HttpFoundation.
• Wallet RPC integration: The ToncenterWalletRpc adapter bridges seamlessly with Laravel services needing WalletRpcInterface (e.g., wallet management modules).

Technical Risk

• Dependency on ext-gmp: PHP’s GMP extension is required for bigint decoding. Laravel deployments must ensure this extension is enabled (common in most PHP stacks but may need explicit configuration in Docker/Cloud environments).
• TON-specific edge cases: Handling 542/429 retries and {ok, result} envelopes is abstracted, but custom error handling (e.g., rate-limiting logic) may require middleware tweaks.
• Laravel’s HTTP client quirks: While PSR-18 compliant, Laravel’s HttpClient may have subtle differences in middleware handling (e.g., retry logic). Testing with the package’s retry middleware is recommended.
• Bigint precision: Decimal-string returns for balances/gas avoid float loss, but Laravel’s Eloquent or query builder may need adjustments for numeric comparisons (e.g., where('balance', '>', '1000000000')).

Key Questions

1. Retry Strategy:
   • Should Laravel’s built-in retry middleware (e.g., retry() helper) replace the package’s RetryMiddleware, or keep the package’s retry logic for consistency?
2. Authentication:
   • How will the X-Api-Key be managed? Laravel’s config + environment variables or a dedicated service provider?
3. Error Handling:
   • Should TonRpcException map to Laravel’s HttpException or a custom exception class for consistency with existing error handling?
4. Performance:
   • Will the package’s retry logic (3 attempts by default) suffice for production, or should Laravel’s queue-based retries (e.g., retryAfter()) be layered in?
5. Testing:
   • How will mocking the PSR-18 client be handled in Laravel’s testing stack (e.g., Mockery or Laravel’s HttpClient mocks)?

Integration Approach

Stack Fit

• Laravel’s HTTP Client: Replace the example’s CurlClient + middleware with Laravel’s HttpClient (Guzzle-based) and its middleware stack:

  use Illuminate\Support\Facades\Http;
  use Amashukov\Toncenter\ToncenterClient;
  
  $http = Http::withOptions([
      'headers' => ['X-Api-Key' => config('toncenter.api_key')],
  ])->retry(3, 100, function ($retries, $response) {
      return $response->status() === 429 || $response->status() === 542;
  });
  
  $client = new ToncenterClient($http, new \Nyholm\Psr7\Factory\Psr17Factory(), new \Nyholm\Psr7\Factory\Psr17Factory());
  

• Symfony HTTP Client: If using Laravel’s Symfony components, Symfony\Contracts\HttpClient\HttpClient can be injected directly.
• Wallet RPC: The ToncenterWalletRpc adapter can be registered as a Laravel service binding:

  $this->app->bind(\Amashukov\TonWallet\WalletRpcInterface::class, function ($app) {
      return new \Amashukov\Toncenter\ToncenterWalletRpc($app->make(ToncenterClient::class));
  });
  

Migration Path

1. Phase 1: Proof of Concept
   • Replace a single Guzzle call (e.g., getBalance) with the package’s client in a feature branch.
   • Verify typed responses (e.g., TonAccountInfo) integrate with Laravel’s DTO/Collection patterns.
2. Phase 2: Full Integration
   • Replace all TON API calls with the package’s client.
   • Migrate wallet RPC logic to use ToncenterWalletRpc.
   • Add middleware for retries/headers (if not using Laravel’s built-in solutions).
3. Phase 3: Optimization
   • Benchmark performance (e.g., retry logic, bigint parsing).
   • Adjust Laravel’s caching (e.g., Cache::remember) for frequent calls like getMasterchainInfo.

Compatibility

• Laravel 10+: Full compatibility due to PHP 8.3+ requirement and PSR-18/PSR-17 support.
• Guzzle vs. Symfony HTTP Client: Both work; prefer Laravel’s HttpClient for consistency.
• Existing TON Logic: Minimal changes needed if current code uses raw Guzzle calls (replace with package methods).
• Third-Party Packages: No conflicts expected; the package is self-contained.

Sequencing

1. Infrastructure Setup:
   • Enable ext-gmp in PHP configuration.
   • Configure X-Api-Key in Laravel’s .env.
2. Client Initialization:
   • Register ToncenterClient as a Laravel service provider or use the container directly.
3. Feature Integration:
   • Start with read-only operations (e.g., getBalance, getMasterchainInfo).
   • Gradually add write operations (e.g., sendBoc).
4. Testing:
   • Mock PSR-18 client in unit tests (e.g., using Mockery or Laravel’s HttpClient mocks).
   • Test retry logic with simulated 542/429 responses.

Operational Impact

Maintenance

• Low Ongoing Effort:
  • Typed Value Objects reduce runtime errors from malformed responses.
  • Centralized {ok, result} unwrapping minimizes future envelope-handling bugs.
• Dependency Updates:
  • Monitor amashukov/toncenter-client-php for breaking changes (low risk due to MIT license and active CI).
  • Laravel’s built-in HTTP client or Symfony HTTP Client will handle most PSR-18 updates transparently.
• Logging:
  • Leverage Laravel’s logging (e.g., Log::debug) to track retries, failed requests, or unexpected {ok, false} responses.

Support

• Debugging:
  • TonRpcException provides clear error context (e.g., TonRpcException::INVALID_ENVELOPE).
  • Laravel’s exception handler can format these for user-facing errors or monitoring.
• Monitoring:
  • Track metrics for:
    • Retry rates (e.g., 542/429 occurrences).
    • Response times for critical endpoints (e.g., getMasterchainInfo).
  • Use Laravel’s events or a queue worker to log slow transactions.
• Documentation:
  • Add package-specific docs to Laravel’s internal wiki (e.g., retry policies, bigint handling).

Scaling

• Horizontal Scaling:
  • Stateless PSR-18 client design ensures no issues in multi-server Laravel deployments.
  • Rate-limiting (X-Api-Key) can be managed via Laravel’s ThrottleRequests middleware.
• Performance Bottlenecks:
  • Bigint Parsing: GMP extension is the only dependency; ensure it’s optimized in PHP runtime.
  • Retry Logic: Laravel’s queue-based retries can replace the package’s middleware if needed for async workloads.
  • Concurrency: Toncenter’s API limits (e.g., 10 RPS with X-Api-Key) may require Laravel’s queue workers for high-throughput operations.
• Caching:
  • Cache getMasterchainInfo and getBalance results in Laravel’s cache (e.g., Redis) with short TTLs (e.g., 5 minutes).

Failure Modes