Blockchain Context Bundle Laravel Package

Technical Evaluation

Architecture fit. This is a Symfony 7 bundle, not a Laravel package, and that distinction dominates the evaluation. Laravel shares individual Symfony components (HttpFoundation, Console, Routing, Process) but does not ship symfony/framework-bundle or the DI container compiler pass, so BlockchainContextBundle::class => ['all' => true] has no Laravel equivalent, and the tagged-iterator chains (ChainDepositCheckChain, ConfirmationCheckChain, DepositTxBuilderChain) depend on !tagged_iterator semantics that Laravel's container resolves differently. The genuinely reusable asset is the layer below the bundle: the pure-PHP SDKs (amashukov/ton-php, amashukov/eth-php, toncenter-client-php, eth-rpc-client-php) plus framework-agnostic domain services (SignatureVerifier, PrivKeyEncrypter, gas fetchers, tx builders). Treat the bundle as a reference wiring blueprint, not an installable artifact. The architectural shape it implies — ports-and-adapters, host app implements DepositWalletDeriverInterface, chains collected by tag — is sound and maps cleanly onto Laravel service providers and tagged bindings via $this->app->tag().

Integration feasibility. Moderate, and entirely contingent on bypassing the bundle. A Laravel integration means writing a BlockchainContextServiceProvider that reads config/blockchain_context.php, constructs the SDK clients (PSR-18 cURL transport), binds interfaces (JsonRpcProviderInterface, ToncenterClientInterface), and registers chain members with $this->app->tag([...], 'blockchain_context.detection'). Concrete services (Eip1559Signer, ToncenterClient, SignatureVerifier, PrivKeyEncrypter) are plain classes and should instantiate without the Symfony container — this must be verified, not assumed, since many Symfony bundles leak ContainerInterface or ParameterBagInterface into service constructors. Hard requirement on PHP 8.3+ and ext-gmp, ext-sodium, ext-openssl, ext-bcmath — check against the target Laravel runtime image before committing.

Technical risk. High, concentrated in three areas. (1) Supply chain: 0 stars, 0 dependents, single maintainer, "readme"-level maturity, and a crypto-payments workload that handles private keys. Any dependency in the signing/key-storage path is a security-critical dependency regardless of its line count — this one has no third-party review surface. (2) Framework mismatch: the primary documented entry point does not work on the target stack, so the README's "installation" and "usage" sections are largely non-actionable and the real integration work is undocumented. (3) Release hygiene: a release dated 2026-10-13 with v0.7.x semver signals an actively churning API pre-1.0; the presence of a Bitcoin verbosity-2 evidence reader that does not appear in the top-level README features list suggests the surface is expanding faster than the docs. Secondary risk: AES-256-GCM key encryption is provided, but key custody — KMS/HSM, rotation, envelope encryption, audit — remains entirely the host's problem.

Key questions.

• Do the domain services and SDK clients instantiate without the Symfony container? (Spike answer required before any estimate.)
• Who owns the fork if the maintainer goes dark? Is there appetite to vendor and maintain ~5 interdependent packages?
• Does our threat model permit a zero-review third-party library to touch private keys, or must we reimplement Eip1559Signer / PrivKeyEncrypter?
• Which chains are actually in scope — ETH + USDT-ERC20 + TON only, or does the Bitcoin evidence reader imply BTC roadmap? Scope drives effort materially.
• Is there an existing wallet/custody vendor (Fireblocks, Coinbase Prime, BitGo) that already covers this and would make the bundle redundant?

Integration Approach

Stack fit. Poor-to-moderate as shipped, good once decomposed. Do not attempt to install the bundle in Laravel and shim framework-bundle — that path leads to a container-within-a-container and unpredictable behavior. Instead, depend on the leaf SDK packages directly (amashukov/eth-rpc-client-php, amashukov/toncenter-client-php, amashukov/http-client-php) and port only the bundle's Service\* classes we need into app/Blockchain/, adapting constructor signatures to Laravel's container. This gives us the SDK's value without inheriting the framework coupling.

Migration path. Greenfield-friendly; there is no brownfield to migrate from, which is the one structural advantage here. Sequence:

1. Spike (1–2 days, timeboxed): in a scratch Laravel 12 app, composer require the leaf SDKs, confirm the crypto extensions are present in the runtime image, and prove out one read path (ETH getBalance) and one write-adjacent path (Eip1559Signer signing an EIP-1559 tx offline, verified against a known vector).
2. Wrap, don't inherit: define Laravel-native interfaces (EvmRpcClient, TonRpcClient, SignatureVerifier, DepositTxBuilder) in domain code; bind SDK implementations in a single BlockchainServiceProvider. No domain class may type-hint an Amashukov\* class — this is the insurance policy if we fork or swap vendors later.
3. Port the chain pattern: reproduce the tagged-iterator chains as Laravel tagged bindings; keep Detection, Finality, Gas, TxBuilder as separate concerns exactly as the bundle does — the separation is genuinely good and cheap to replicate.
4. Config surface: translate the bundle's env-agnostic %blockchain_context.*% tree into config/blockchain_context.php with per-chain enabled flags preserved (single-chain deployments must be able to disable the other chain cleanly).

Compatibility. Pin exact versions (composer require amashukov/...:0.7.*) and commit composer.lock; treat every minor bump as a breaking change until 1.0. Vendor all amashukov/* packages into the repo (Composer path repository or a private Satis/Packagist mirror) so builds do not depend on a single GitHub account remaining available. PHP 8.3 floor likely forces the Laravel 10+ / 11+ line — confirm against the platform's supported PHP matrix.

Sequencing. Read-only RPC + balance/health checks first (no keys, low blast radius) → signature verification (SignatureVerifier, stateless, high value for deposit validation) → deposit detection + finality polling on a testnet → tx building and signing last, behind a feature flag and a manual-approval gate. Bitcoin evidence reader is explicitly out of scope for v1 — it is a single-release-old feature not reflected in the top-level docs and implies a roadmap we have not validated.

Operational Impact

Maintenance. The real cost is not the code we write; it is the code we now co-own. With one maintainer, zero dependents, and pre-1.0 churn, budget ongoing stewardship: routine upstream diffs, our own fork if the project stalls, and a standing security-review obligation on any package touching key material. Estimate 0.1–0.2 FTE ongoing for a two-chain integration, plus a named owner. PHPStan level 9, @PER-CS, and CI on 8.3/8.4 are genuinely positive signals that lower the review cost of upstream diffs — this is a well-engineered project with no adoption, not a sloppy one, and that distinction matters for the buy-vs-fork call.

Support. Zero community: no Stack Overflow corpus, no dependents to mine for issues, no third-party tutorials. Escalation path is "read the source" — acceptable for a strong PHP team, unacceptable if the payments surface is owned by a small or junior group. No SLA, no security disclosure policy documented. Compensate with an internal runbook and a documented fork procedure before go-live.

Scaling. Depends almost entirely on external RPCs, not on this package. Two hard limits: toncenter rate limits (the bundle ships X-Api-Key plus 429/5xx/542 retry middleware, which tells you the limit is real and frequently hit) and EVM JSON-RPC provider quotas. Deposit detection and finality depth-polling are inherently poll-shaped — put them on Laravel queues with Horizon, enforce per-provider concurrency caps, and add jitter to avoid synchronized polling bursts. DepthPollingFinalityVerifier with finality_polls and RealSleeper is a long-running-process pattern; it must run in queue workers, never in a web request. Plan for a paid RPC tier and a paid toncenter tier as a line item, and design detection to be idempotent and replay-safe so workers can scale horizontally.

Failure modes. Enumerate and instrument each:

• RPC outage / rate limit — retry middleware helps but masks latency; add circuit breakers and surface provider degradation to on-call.
• Reorg / premature finality — the highest-severity failure for a payments system: crediting a deposit that later disappears. Confirmation depth policy needs explicit product sign-off per chain, and ConfirmationCounterRegistry behavior must be tested against real reorg data, not just unit tests.
• Key handling — encryption at rest is provided; key custody, rotation, and access audit are not. A leaked DEPOSIT_WALLET_ENCRYPTION_KEY compromises every derived wallet. This is a design decision, not a library feature.
• Silent detection gaps — a new deposit checker added but not tagged/registered fails open (deposit never detected). Alert on expected-vs-registered chain coverage at boot.
• Derivation drift — DepositWalletDeriverInterface is a port we implement; a derivation bug means funds sent to an address we cannot sweep. Needs a golden-vector test suite against known mnemonics, non-negotiable.
• Upstream abandonment — mitigated by vendoring; unmigrated means a frozen, unpatched crypto library in the payment path within a year.

Ramp-up. Two separate curves. The PHP/Symfony-idiom curve is shallow for a competent Laravel team — the ports-and-adapters structure is legible and the bundle's separation of Detection/Finality/Gas/TxBuilder is a good teaching scaffold. The crypto domain curve is the real cost: EIP-1559 semantics, EIP-191 vs. TON Connect signature schemes, UTXO vs. account models, confirmation-depth policy, and the operational reflexes around reorgs and key custody. Budget 2–3 weeks for an engineer to reach productive independence on the read/detect path, and require a crypto-fluent reviewer (internal or contracted) for anything in the signing path. Do not let the absence of community docs be papered over with "the code is clean" — clean code is not documentation, and the README's install instructions do not apply to our stack.