Lepton Agent Laravel Package

Getting Started

This is a new assessment — no prior baseline — so treat v3.0.0-rc.1 as the first look at a package that just changed shape substantially.

Before you composer require, verify the floor. The package requires PHP 8.5+ (it uses the native RSA-OAEP SHA-256 digest API) plus ext-curl and ext-openssl. PHP 8.4 is explicitly out.

php -v
php -m | grep -E '^(curl|openssl)$'

If your app or CI image is on 8.4, stop here — there is no compatibility shim. Options are: upgrade the runtime, or run this package in a dedicated service/queue worker rather than in the main Laravel app.

First three steps once installed:

1. Publish and populate config. You need Circle API credentials, the entity secret (RSA, used for request signing), a wallet set ID, and a network. The wallet set and network are no longer defaulted — mutations require them to be explicit, so decide them at config time.
2. Start with a read. Wallet resolution and balance lookups are the lowest-risk entry point, and they exercise transport + auth without needing an idempotency key. They hit the /v1/w3s/... read paths.
3. Then a dry run. Use the artisan tooling (lepton:transfer --estimate) to hit the real estimator and check feeLevel handling and amount formatting without signing anything.

First real use case: a sandbox transfer with all three new required inputs — --idempotency-key (a UUID v4), --wallet-set, and --account-type. That single command is the fastest way to confirm your entity secret, signing payload, and REST path are all correct, because every one of those is a place the old version was silently wrong.

Implementation Patterns

Type-hint capability interfaces, not the concrete driver. WalletGateway keeps its original four methods, and that is your stable seam. For anything else — wallet management, transfer observation, estimation, webhook verification, custom transport — depend on the optional interface (WalletManagementGateway, TransferObserver, TransferEstimator, WebhookVerifier, JsonTransport) and be prepared for a driver not to implement it:

try {
    $estimate = $this->estimator->estimate($intent);
} catch (UnsupportedOperation $e) {
    // degrade explicitly — hide the fee preview, don't show zero
}

Generate idempotency keys at the edge, not in the retry loop. A UUID v4 must be created when the intent is created (HTTP request, queued job dispatch), persisted alongside the intent row, and reused on every retry. Generating inside a try/catch retry defeats the entire mechanism and, since the key is now mandatory, will just throw on a malformed value.

Keep two money pipelines. Arc native USDC is 18 dp; ERC-20 USDC is 6 dp. The package refuses to sum them, and Amounts rejects overflow and bad scale. In your schema, don't have one amount column that receives both — keep them separate and convert only at presentation. In tests, use the package's own Amounts when building fixtures so you inherit the validation.

Verify webhooks on the raw body, before middleware touches it. The fix here is important: verification uses GET /v2/notifications/publicKey/{keyId} and ECDSA_SHA_256 over the original raw bytes — never the Entity Secret RSA key. That means verification must run ahead of anything that re-encodes the request (TrimStrings, ConvertEmptyStringsToNull, or a $request->all()-based re-serialise). Cache the public key by keyId; it's a network call on the hot path otherwise.

Bind JsonTransport in tests. It's injectable specifically so you can swap in a fake for offline unit tests and add logging/tracing in production. Prefer that over mocking the gateway — the gateway has capability-conditional behaviour and mocks get brittle fast.

Use the facade for artisan-style code, DI everywhere else. Lepton::transfer() existed in intent but was missing from the facade; it's there now. In application code, inject WalletGateway — the facade is a service locator and makes feature-detection awkward.

Treat terminal states as driver-specific. Transfer-state mapping was fixed in CircleCliGateway, which tells you mapping is not universal. If you branch on status, keep the mapping behind a small adapter in your own code rather than checking enum cases from the gateway.

Gotchas and Tips

• PHP 8.5 is the real gate, not the API. This is the item most likely to block adoption in a normal Laravel app. Check your Laravel version, your CI image, and your hosting provider before committing to an upgrade path — 8.5 runtime availability is likely thinner than the package's CI suggests.
• This is a prerelease, and the notes say so directly. 98 offline tests and 435 assertions are green, but no live wallet creation, transfer, faucet request, or webhook delivery has been exercised. Offline green is not production certification. Budget a sandbox smoke-test pass — one wallet create, one transfer, one faucet request, one webhook delivery — before trusting this with real funds, and read the production-readiness checklist in the README.
• Silent successes are now failures. Requests that previously "succeeded" without a wallet set, network, or idempotency key will throw. If you have any code (or stored artisan invocations) relying on defaults, audit it before upgrading — this is the most likely source of post-deploy breakage.
• The key must be UUID v4. Not a ULID, not Str::random(), not a hash. Validate at the boundary so you get a clean domain error instead of an SDK exception mid-flight.
• A green dry run proves less than you think. Dry-run blocks REST signing and mutations, which is exactly what makes it safe — but it also means it never exercises your entity secret or signer. Dry run validates shape and estimation; only a sandbox mutation validates signing.
• No redirects, no write retries — by design. If you sit behind a proxy or load balancer that 301/302s your API calls, mutations will fail and that's intentional (it prevents replaying signed bodies to an unexpected host). Same for retries: the SDK won't retry writes, so implement retry yourself with the same idempotency key.
• Don't map UnsupportedOperation to a zero balance. The notes are explicit that this replaces the old placeholder behaviour. Surface it as a capability flag or domain error; a zero balance is a wrong answer that looks like a right one.
• feeLevel placement changed. If you build request payloads by hand anywhere, compare them against the SDK's output — the old placement against the Circle OpenAPI contract was incorrect, and the old behaviour may have been silently defaulting rather than failing.
• Debugging tip: with docs lagging the OpenAPI contract, the 98-test suite is the most reliable description of payload shape. When correlating with Circle's API logs, remember reads are /v1/w3s/... and mutations are /developer/... — mixing those up is the easiest way to misread a 404.
• Extension point worth knowing: if a driver lacks something you need, implement the capability interface yourself and bind it — the interfaces exist precisely so third-party drivers and decorators don't have to fork the concrete gateway.