Lepton Agent Laravel Package

Technical Evaluation

What this release is. v3.0.0-rc.1 is a repositioning, not an increment. The package moves from "CLI wrapper with gaps" to a Laravel-first SDK with a stable core (WalletGateway, four methods) plus optional capability interfaces. For a TPM, the material fact is that the contract changed even though the headline interface didn't.

Architecture fit. The shape is sound for a Laravel codebase: service provider + Lepton facade, Artisan commands (lepton:transfer, --estimate), injectable JsonTransport, and capability interfaces that let drivers advertise what they actually support. UnsupportedOperation replacing zero-balance/placeholder returns is exactly the right failure semantics for money movement — fail loud, never fabricate. Dry-run blocking signing and mutations, plus a transport that follows no redirects and retries no writes, are the correct defaults for a payments client and tell me the author has been burned before.

Integration feasibility — the blockers are environmental, not architectural.

• PHP 8.5+ is a hard floor. The justification (native RSA-OAEP SHA-256 digest API) is legitimate but the cost is real: this constrains base images, CI runners, static analysis, and every other package in the app. Most organizations will not be on 8.5 for months. This single line determines whether the release is adoptable at all.
• Caller-supplied idempotency keys, explicit wallet set, explicit network push correctness obligations into our application. Previously "succeeding" invalid requests now fail — that is a fix, but it will surface as production breakage for anyone upgrading without auditing call sites.
• The "Fixed" list is an indictment of v2. REST paths, feeLevel placement, and signing payloads previously did not match the Circle OpenAPI contract. Webhook verification previously used the Entity Secret RSA key instead of the ECDSA_SHA_256 public key. Anyone running v2 in anger may have been shipping incorrect signing payloads while believing the integration worked. Assume v2 correctness is unproven everywhere.

Technical risk.

1. No live validation. 98 offline tests / 435 assertions is a good floor and says nothing about whether Circle accepts these bytes. Wallet creation, transfer, faucet, and webhook delivery have never been exercised. Offline green is not certification, and the release notes say so.
2. Pre-release API surface. Capability interfaces and constructor contracts may still move between rc.1 and GA.
3. Webhook raw-bytes verification. The requirement to verify ECDSA_SHA_256 against original raw bytes is correct and is also the most common place Laravel integrations break — body parsers, middleware, and proxies all mutate payloads.
4. Decimal-scale hazard is contained but adjacent logic is not. The package correctly refuses to sum Arc native (18 dp) and ERC-20 (6 dp) USDC views. Any of our own aggregation, reporting, or ledger code must adopt the same rule.
5. No mainnet fallback after failure — deliberate and correct, but it converts a silent degradation into a hard outage path we must have runbooks for.

Key questions for the maintainer.

• Support window for 2.x, and is there a documented upgrade/migration guide for call sites that relied on implicit wallet set and network?
• Is there a sandbox/testnet certification plan with a published pass criteria and date, and will GA be gated on it?
• Is PHP 8.4 support ever coming back (polyfill path for RSA-OAEP), or is 8.5 permanent?
• Laravel version support matrix, and does the package publish config?
• Who is expected to persist idempotency keys across queue retries, and is there guidance?

Integration Approach

Stack fit. Good fit for a Laravel service that holds USDC balances or initiates Circle transfers. Bind JsonTransport to a client with explicit timeouts and no redirects; register WalletManagementGateway / TransferObserver / TransferEstimator / WebhookVerifier behind capability checks rather than assuming a driver implements everything. Treat UnsupportedOperation as a first-class control-flow branch, not an error to swallow.

Migration path from 2.x. Do not do a lift-and-shift. Sequence:

1. Audit v2 call sites. Given the signing-payload and path fixes, inventory every mutation and reconcile against actual Circle activity. Assume some historical requests failed silently or landed incorrectly.
2. Pin wallet set and network explicitly in config, per environment. Remove any code that depended on mainnet fallback.
3. Introduce an idempotency key store before touching mutations — minted at request/job creation, persisted, reused on every retry. A retry with a fresh key is a double-spend.
4. Adopt capability interfaces incrementally. The four-method WalletGateway keeps working; land read paths and estimation first, then webhooks, then mutations.
5. Upgrade the runtime to PHP 8.5 as a prerequisite workstream with its own ticket and blast-radius review — this is not a composer bump.

Compatibility. Requires ext-curl, ext-openssl, PHP 8.5+. Confirm base image, CI, and any sidecar tooling. Verify the webhook route bypasses body-mutating middleware and that any ingress preserves raw bytes and does not buffer-rewrite.

Sequencing. Dev sandbox → dry-run wiring and estimation in CI → read operations against testnet → webhook verification with replayed fixtures → first live testnet mutation (wallet create, faucet, small transfer) → mainnet behind a flag with manual approval. Do not compress the live-testnet phase; it is the only phase this release has not de-risked for us.

Operational Impact

Maintenance. Prerelease churn between rc.1 and GA is likely, so pin exactly and budget for a second upgrade inside the quarter. The package is a thin, well-tested layer; the ongoing maintenance burden is mostly ours — idempotency persistence, retry policy, capability negotiation, and webhook endpoint hygiene.

Support. With zero live exercise, the first real failure will be diagnosed by our team against the Circle OpenAPI spec, not by the maintainer's test suite. Budget for that. Escalation path to the maintainer should be agreed before mainnet.

Scaling. The HTTP transport is injectable, so connection pooling, timeouts, and observability are ours to own. Because writes are not retried at transport level, throughput and durability depend entirely on our queue design — which is correct, but means queue concurrency, tries, and backoff must be tuned with idempotency semantics in mind. Reads scale conventionally.

Failure modes to instrument.

• UnsupportedOperation — alert on unexpected occurrences per driver; they indicate config drift.
• Idempotency key reuse and collision — log key + request, reconcile against Circle before any manual retry.
• Hard failure with no mainnet fallback — needs a runbook and a circuit-breaker policy at the caller.
• Webhook verification failures from byte mutation — alert separately from signature mismatch.
• Decimal-scale confusion in any downstream aggregation — assert on unit before summing.
• Balance/resolve parsing and terminal-state mapping — the code paths that were silently wrong in v2 deserve explicit dashboards.

Ramp-up. Moderate. Engineers need PHP 8.5 tooling familiarity, comfort with the Circle OpenAPI contract, disciplined idempotency-key handling, and enough ECDSA/webhook knowledge to not accidentally verify against the wrong key. The capability-interface pattern is easy to learn and easy to misuse — establish a team convention that UnsupportedOperation is never caught and discarded.

Recommendation. Adopt rc.1 for evaluation and non-production integration now — it is a clear correctness improvement over v2, and the fail-loud semantics are worth the migration pain. Gate production on three things: PHP 8.5 available in the runtime, a completed live testnet certification with wallet creation, faucet, transfer, and webhook delivery all exercised, and an idempotency key store shipped and tested under queue retry. Until the live path is proven, treat this as unvalidated against the system it actually talks to.