Lepton Agent Laravel Package

Product Decisions This Supports

• Build vs. buy on crypto rails. This is the "buy the integration layer, keep your domain logic" option: it absorbs Circle WaaS contract details (REST paths, feeLevel placement, signing payloads, Entity Secret handling, webhook key retrieval) that would otherwise be bespoke code your team owns forever. The decision it informs is whether your roadmap needs a stablecoin payout/treasury capability at all — if it does, the alternative is 4–8 weeks of in-house HTTP/signing/webhook plumbing plus its ongoing maintenance.
• Phased feature delivery via capability interfaces. WalletGateway stays at four methods, with wallet management, transfer observation, estimation, webhook verification, and transport behind optional interfaces. That maps cleanly onto a product phasing decision: ship read balances / observe transfers first, add wallet provisioning and webhooks in a later milestone without a rewrite. It also means a read-only feature doesn't inherit a full custody surface area.
• "Preview payout" and fee-transparency UX. The real estimator (lepton:transfer --estimate now uses it) plus dry-run that blocks REST signing and mutations gives you a legitimate basis for a confirm-before-send screen with disclosed fees — a feature execs and support teams both ask for, and one that is hard to retrofit.
• Retry-safety as a product requirement, not a code detail. Mandatory caller-supplied UUID v4 idempotency keys on mutations convert "never double-pay" from an aspiration into an enforceable contract. This is the decision that lets you promise safe retries in payout flows and in artisan-driven ops (--idempotency-key).
• Honest failure states over plausible-looking ones. UnsupportedOperation instead of a zero balance or placeholder is a UX and incident-response decision: it prevents dashboards, reconcile jobs, and support tooling from displaying a confident wrong number. Worth writing into your acceptance criteria.
• Decimal correctness for ledger/reporting features. Arc native (18 dp) vs. ERC-20 (6 dp) USDC never being summed, plus Amounts rejecting overflow and bad scale, directly de-risks financial reporting, invoice settlement, and reconciliation features where a silent rounding class of bug becomes a customer-facing incident.
• Explicit network and wallet-set per mutation is a product-safety decision: it removes the class of bug where a request silently lands on the wrong environment. Previously "succeeded" invalid requests now fail — this changes your error-handling and onboarding copy, but in the right direction.
• Webhook verification done correctly (ECDSA SHA-256 against raw bytes via the public-key endpoint, never the Entity Secret RSA key) is a compliance-review checkbox you can hand to security rather than defend in design review.

When to Consider This Package

Consider it when:

• You are a Laravel/PHP shop integrating Circle's WaaS for USDC payouts, treasury, or wallet provisioning, and you want the Circle contract encapsulated rather than re-derived.
• You are on PHP 8.5+. This is the gating criterion, not a footnote — the release requires native RSA-OAEP SHA-256 digest support and explicitly drops 8.4. Most production fleets are on 8.2/8.3; adoption is contingent on an upgrade you should scope separately.
• You need idempotent mutations, webhook verification, or decimal-safe amount handling — i.e., the parts of the problem that are expensive to get right and cheap to get wrong.
• You are comfortable treating this as prerelease. The 98 offline tests / 435 assertions are evidence of internal consistency, not of correctness against live Circle. No live wallet creation, transfer, faucet request, or webhook delivery has been exercised.
• Your usage tolerates HTTPS-only Arc RPC via an injectable transport, with no CLI fallback and no mainnet fallback after failure.

Look elsewhere or wait when:

• You cannot move to PHP 8.5 in the near term. Nothing else about the package compensates for this — treat it as a hard no until the upgrade is funded.
• You need a GA, vendor-supported SDK with an SLA and a live-certification record. This is rc.1; the README's production-readiness checklist is the real gate.
• Your requirements are read-only balances and transfer history — a thin HTTP client may be less surface area than an SDK with custody capabilities you'll never enable.
• You depend on the removed operational paths: arc-canteen CLI fallback, mainnet fallback after failure, or the previously permissive request shapes. Those flows need redesign, not a version bump.
• You need provider abstraction across Fireblocks / Coinbase CDP / BitGo, or chains outside Circle + Arc. The interfaces are Circle-shaped by design.
• You are not on Laravel. The gateways themselves are plain PHP and portable, but the Lepton facade, artisan commands, and service-provider wiring are the ergonomic value.

How to Pitch It (Stakeholders)

To executives: This release turns a partially-wired CLI wrapper into a Laravel-native SDK for Circle's USDC infrastructure, which shortens time-to-market for payouts and treasury features by removing integration work we would otherwise own and maintain. It also hard-codes two things we would have had to enforce socially: mandatory idempotency keys on every money-moving call (safe retries, no double-pay) and correct decimal handling across 18-dp and 6-dp USDC (no silent rounding errors in reporting). The caveats are equally clear: it is a release candidate with zero live Circle traffic exercised, and it requires PHP 8.5, which is ahead of our current fleet. Recommendation: fund a timeboxed sandbox integration spike (1–2 sprints, includes the PHP 8.5 upgrade assessment) and treat production dependency as contingent on our own live certification — not on the vendor's offline test suite. Do not commit a customer-facing date to this path yet.

To engineering: The contracts are cleaner than a wrapper: a four-method WalletGateway core you can implement minimally, with wallet management, transfer observation, estimation, webhook verification, and JSON transport as optional interfaces that fail loudly via UnsupportedOperation rather than returning zeros or placeholders. Breaking changes are bounded — existing four-method implementations keep working. Mutations now require an explicit idempotency key, wallet set, and network, so expect previously "successful" invalid calls to start failing; that is intentional. Transport follows no redirects and retries no writes, and dry-run blocks signing entirely. Webhook verification uses GET /v2/notifications/publicKey/{keyId} with ECDSA_SHA_256 over the original raw bytes — never the Entity Secret RSA key, so don't hand-roll that path. CI runs PHP 8.5 with phpunit; add live sandbox coverage before you trust it.

To security and compliance: Two items are worth adopting as internal standards regardless of whether we ship this package: webhook signature verification against the raw request body with the correct key type, and mandatory idempotency on every mutation. Explicit network/wallet-set requirements and HTTPS-only transport with no mainnet fallback reduce the misconfiguration blast radius we usually find in these integrations. Note the honest gap — no live transfer, faucet, or webhook delivery has been validated — so our review should include a live sandbox verification step rather than accepting the offline suite as evidence.