- How do I install this package in a Laravel project?
- Run `composer require amashukov/ton-wallet-php` and ensure your PHP version is 8.3+. The package requires only `ext-sodium` and `ext-bcmath`, which are commonly enabled in Laravel environments. For RPC functionality, pair it with `amashukov/toncenter-client-php` or implement a custom `WalletRpcInterface`.
- Does this package support Laravel’s service container for dependency injection?
- Yes. Bind the `WalletV4R2`, `Address`, and `WalletRpcInterface` classes as Laravel services in your `AppServiceProvider`. For example, inject a `TonCenterRpcClient` via the container for RPC operations. The modular design ensures easy integration with Laravel’s DI system.
- Can I use this package with older Laravel versions (e.g., Laravel 9) or PHP 8.1?
- No, this package requires PHP 8.3+. Laravel 10+ supports PHP 8.3+, so ensure your project meets this requirement. If you’re on an older Laravel version, consider upgrading or evaluating alternatives like `tonconnect/sdk` for broader compatibility.
- How does sequence number (seqno) management work? Should I fetch it per transaction?
- The package decouples seqno fetching via the `WalletRpcInterface`. You can fetch it per transaction or cache it locally, depending on your use case. For high-frequency transactions, consider caching with a TTL to avoid rate limits on your RPC provider.
- What RPC providers are supported, and how do I switch between them?
- The package uses a pluggable `WalletRpcInterface` for RPC operations (e.g., `getSeqno`, `sendBoc`). You can integrate providers like `TonCenter`, self-hosted nodes, or test doubles. For TonCenter, use `amashukov/toncenter-client-php` as an adapter. Switching providers only requires binding a new implementation to the interface.
- How do I handle failed broadcasts or retries in production?
- Failed broadcasts should be retried with exponential backoff. Implement a retry mechanism in your Laravel service layer, logging errors for debugging. The package’s offline signing ensures you can retry without re-signing, but validate seqno consistency before rebroadcasting.
- Can this package handle multi-signature wallets or custom contract interactions?
- Currently, the package focuses on TON Wallet v4r2 (single-signature). For multi-signature wallets, you’d need to extend the `WalletV4R2` class or use a different contract wrapper. Custom contract interactions require building `InternalMessage` manually, which the package supports via its low-level API.
- Are there performance concerns for high-volume transactions (e.g., batch processing)?
- The package is optimized for offline signing, but high-volume use may require parallel processing. Offload signing to queues (e.g., Laravel Queues) or workers to avoid blocking requests. Address derivation and BOC serialization are lightweight, but batch RPC calls should be rate-limited.
- How do I mock the RPC layer for testing in Laravel?
- Create a test double implementing `WalletRpcInterface` and bind it to the container during tests. For example, mock `getSeqno` to return fixed values and verify `sendBoc` calls. Use Laravel’s `Mockery` or PHPUnit’s mocking tools to simulate RPC responses.
- What alternatives exist for TON wallet integration in Laravel?
- Alternatives include the official `@ton/ton` JavaScript SDK (via Laravel Mix or Inertia.js), `tonconnect/sdk` for wallet connectivity, or `toncenter-client-php` for RPC-only needs. This package stands out for its pure-PHP implementation and offline signing capabilities, ideal for backend-heavy Laravel apps.