Erd Laravel Laravel Package

Getting Started

• Install via Composer: composer require peerme/mx-sdk-laravel. v3.0.0 adds Laravel 12 support; if you're still on Laravel 10/11, check the constraint resolved by Composer before upgrading a major version.
• Publish the package config (php artisan vendor:publish --tag=...) and set the network + provider in .env (typically mainnet / devnet / testnet, and a Gateway vs API endpoint choice).
• First place to look: the package's config/ file and the service provider bindings — these tell you which classes are swappable (HTTP client, signing provider, network config) and are where 90% of "why is it calling that URL" questions get answered.
• First use case to validate your wiring: read an account's EGLD balance for a known address, then build → sign → broadcast a small self-transfer on devnet. If the balance call works but the broadcast fails, the problem is almost always signing config, not networking.

Implementation Patterns

• Resolve from the container, don't new. Inject the SDK/facade into services, jobs, and artisan commands. This keeps you compatible with the package's config-driven network switching and makes it fakeable in tests.
• Treat transactions as a pipeline, not a method call. The reliable shape is: build unsigned tx → assign nonce → sign with your provider → broadcast → poll for status → dispatch domain events. Wrap steps 4–5 in a queued job with backoff rather than blocking a request.
• Keep signing isolated. Put key material behind a dedicated service or a custom signing provider binding, and inject that interface. This lets you use a local PEM in dev, a KMS/HSM or external wallet in production, and a stub in tests.
• Network-parameterise everything. Any address, token identifier, or contract address in your code should come from config, not be hardcoded — you will want to replay the same flow on devnet.
• Model ESDT/NFT operations as their own services. Issuing a token, minting an NFT, and transferring an ESDT are multi-step and have different gas profiles; putting them behind narrow service methods keeps controllers thin and makes them individually testable.
• Cache read-heavy calls. Balance, token metadata, and network config lookups are cheap per call but add up fast in dashboards. A short-TTL cache (Cache::remember, 5–30s) in front of reads is usually the single biggest latency win.
• Idempotency for outgoing transfers. Store a local transaction record keyed by your own request ID before broadcasting, so a retry after a timeout doesn't double-send.

Gotchas and Tips

• Major version bump for a Laravel compatibility change. v3.0.0 is nominally just "Laravel 12 support," but a major bump means the constraint moved — assume Laravel 10 (or whichever floor existed in 2.x) may be dropped. Pin and test on a branch; don't assume it's a drop-in.
• Values are big-number strings, not ints. Amounts are denominated in the smallest unit and will overflow PHP integers on 32-bit and exceed float precision everywhere. Handle them as strings, use the SDK's formatter/denomination helpers, and never do arithmetic with + on raw amounts.
• Nonce collisions. If you fire two transactions from the same wallet concurrently (parallel jobs, two requests), the second will fail nonce validation. Serialise signing per address with a lock, or fetch-and-increment nonce deliberately.
• Gas is not optional to get right. Leaving defaults works on simple transfers but fails on contract calls that need more. Keep gas limit/price in config per operation type, and check the "insufficient gas" error path exists in your UI rather than surfacing a raw exception.
• Finality ≠ broadcast success. A 200 from the broadcast endpoint means "accepted," not "executed." Poll status with a bounded timeout and a terminal-failure branch; otherwise you'll ship transactions that silently never confirm.
• Config caching bites silently. With php artisan config:cache in production, changes to .env don't apply until you re-cache. If "it works locally but not on the server," check this before anything else.
• Address format mismatches. Bech32 (erd1...) vs hex is a recurring source of "invalid address" errors. Normalise at your application boundary (form requests / DTOs) and convert once, rather than sprinkling conversions through the codebase.
• Gateway vs API endpoint differences. They don't expose identical capabilities or rate limits. Pick deliberately per feature, and put retry-with-backoff behind the HTTP client binding rather than in every caller.
• Extension points worth knowing: the HTTP client binding (for logging/tracing/retries), the signing provider (for external key management), and the network config object (for private/custom chains). These three cover most real-world customisation without forking the package.