- How do I install and configure amashukov/blockchain-context-bundle in a Symfony 7 app?
- Install it with Composer using composer require amashukov/blockchain-context-bundle, then register the bundle in config/bundles.php. It requires PHP 8.3 or newer and Symfony 7, and it pulls in the pure-PHP SDKs amashukov/ton-php and amashukov/eth-php. All chain endpoints, API keys, and encryption settings are configured in one place under config/packages, ideally fed from environment variables. Because every client and domain service is autowired, you just type-hint the class or interface in your constructor and the bundle injects the configured instance.
- Does this bundle work with Laravel or plain PHP projects?
- No, not as a drop-in package: it is a Symfony 7 bundle, and its dependency injection autowiring, service configuration, and tagged per-chain services are Symfony-specific. The underlying SDKs (amashukov/ton-php and amashukov/eth-php) are pure PHP and framework-agnostic, so a Laravel app can use them directly with a PSR-18 HTTP client and register its own container bindings. You would, however, have to rebuild the wiring, retry middleware, and domain services yourself. If you need a ready-made Laravel service provider, this package is not it.
- Which blockchains and assets does the bundle support today?
- It covers TON through a typed toncenter v2 client and EVM chains such as ETH and USDT through an ethers-style JSON-RPC client with an EIP-1559 signer. As of v0.7.2 it also reads Bitcoin Core data for deposit analytics, including typed verbosity-2 transaction evidence and fee extraction. Bitcoin support at this stage is read-only and analytics oriented, so signing and broadcast parity exists for TON and EVM but not yet for BTC. Deposit detection, finality, gas, and transaction-builder services are exposed per chain, so support can be extended.
- How does deposit detection and finality verification work in this bundle?
- Each chain gets its own deposit-detection service, finality verifier, gas fetcher, and deposit transaction builder, registered as tagged services behind a chain-agnostic domain pattern. Detection services query the chain RPC for activity on monitored addresses, and finality verifiers apply per-chain confirmation rules before a deposit is treated as settled. You inject the service for the chain you care about and run it from a worker or cron job, then persist state in your own database. Keeping parsing and analytics out of the chain adapter means adding a new chain does not change existing consumers.
- How do I verify wallet signatures, such as EIP-191 and TON Connect, server-side?
- The bundle includes EIP-191 personal-sign verification for EVM wallets and Ed25519 / TON Connect verification for TON wallets, exposed as autowired services. The typical flow is: the client signs a server-issued nonce, you pass the signature, message, and expected address to the verifier, and only then link the wallet or credit the account. Always bind the signed message to a single-use nonce with an expiry so signatures cannot be replayed. Verification should happen before any balance or deposit logic runs.
- How are private keys encrypted, and where should I store the encryption key?
- Private keys are protected with AES-256-GCM, and TON wallets are built from a mnemonic through the bundle factory rather than being stored raw. In practice you keep only the ciphertext in your database or a vault, and the master encryption key lives in an environment variable or a secrets manager, never in code or the repository. Because GCM is authenticated encryption, tampered ciphertext fails to decrypt instead of silently yielding a wrong key. Plan for rotation and for restricting decrypt access to the payment worker only.
- How do I configure RPC endpoints and API keys for each chain?
- Configuration is centralized in the bundle config, where you set the EVM JSON-RPC URL and the toncenter endpoint plus its X-Api-Key. The toncenter client comes with a middleware pipeline that adds the API key and retries on 429, 5xx, and 542 responses, and all transports run over a PSR-18 client from amashukov/http-client-php. Bitcoin features need a Bitcoin Core JSON-RPC endpoint, which may be self-hosted or managed, adding node operations as a dependency. Multi-provider fallback and RPC batching are not documented as built-in, so add a wrapper or decorator if you need redundancy.
- Is this package production ready, and how is it tested?
- The project ships 245 tests with 462 assertions and runs PHPStan at level 9, PHP-CS-Fixer, and Rector dry runs in CI on PHP 8.3 and 8.4. That combination of static analysis and a test suite materially reduces the risk of a README-only integration, which was an earlier concern. The test count is still modest relative to the growing chain surface area, so treat the suite as a floor rather than a guarantee. Add your own integration tests against the exact RPC providers and node versions you deploy.
- Can I use it for Bitcoin signing and broadcasting like I do with TON and EVM?
- Not yet. The v0.7.2 Bitcoin support is observability and analytics focused: it reads verbosity-2 transactions and blocks to produce typed fee evidence for deposit reconciliation. If your node runs at verbosity 1 or is pruned, full fee derivation may be impossible, and the reader deliberately reports the fee as unavailable instead of guessing. Contradictory fee data reported by the node is rejected rather than averaged, so downstream analytics must handle the unavailable state explicitly. Wallet, signer, and transaction-builder parity for BTC would require additional integration work or a future release.
- How does this compare to using web3.php or raw JSON-RPC calls, and who maintains the underlying SDKs?
- Rolling your own JSON-RPC plus signing is possible, but you would reimplement EIP-1559 offline signing, TON wallet v4r2 from a mnemonic, finality rules, deposit detection, and fee derivation. web3.php covers EVM JSON-RPC but not TON, Bitcoin evidence, or the bundle-level domain services. The trade-off is dependency maturity: amashukov/ton-php and amashukov/eth-php are relatively young and largely single-maintainer, while the Bitcoin side depends on the mature but operationally heavy Bitcoin Core RPC. Pin versions, review release cadence before upgrading, and keep a fallback plan for critical payment paths.