Elrond Sdk Laravel Laravel Package

Getting Started

• Install: composer require peermehq/mx-sdk-laravel (verify the exact Packagist name against the repo's composer.json — the GitHub repo is PeerMeHQ/mx-sdk-laravel). Laravel package auto-discovery registers the service provider and facade, so no manual config/app.php edits are needed on Laravel 10+.
• Where to look first: after install, publish the config with php artisan vendor:publish --provider="PeerMe\\MxSdk\\MxSdkServiceProvider" (check the actual provider/tag in the README — tags vary between releases) and read config/mx-sdk.php before touching code. That file is the map: network selection, API/gateway endpoints, and default timeout/retry behaviour all live there.
• Configure per environment: set the network (mainnet / devnet / testnet) via env rather than hardcoding, and always start on devnet. Keep the network in .env alongside the other MX settings so config:cache and per-environment deploys behave predictably.
• First use case: read something before you write something. Fetch an account's balance or a token's properties through the configured network provider and dump the result in php artisan tinker. This validates credentials, endpoint, and network in under a minute without risking funds or burning gas on a malformed transaction.

Implementation Patterns

• Inject, don't app(): resolve the SDK's network provider / account service through the container (constructor injection or a facade alias) so tests can swap it. Avoid static calls sprinkled through controllers — the package is a thin wrapper over the underlying PHP SDK, and the container is your only clean seam.
• Separate read and write paths. Read operations (balances, token metadata, VM query results, transaction status) are cheap and cacheable; write operations (build → sign → send) are stateful and must be serialized. Keep them in different service classes so a cached read never accidentally triggers a signed transaction.
• Treat signing as a pipeline: build the transaction → set nonce → estimate/assign gas → sign with the configured signer → broadcast → poll for status. Wrap the last three steps in a single method returning a result object, so callers never broadcast a half-built transaction.
• Wallet material belongs in secrets, not the repo. Load PEM/keyfile paths from env or a secrets manager and resolve them at boot via a dedicated WalletService. Never let the path default to something inside the project tree; a stray *.pem in a repo is the most common real-world incident with SDKs like this.
• Serialize per-address writes. If two jobs sign for the same address concurrently they will fetch the same nonce and one transaction will be rejected. Route all outbound transactions for an address through a single queued job (or a lock keyed by address) and fetch the nonce inside the lock.
• Push broadcasting into the queue. Network latency and gateway 5xxs will dominate request time. Dispatch a job, return the transaction hash immediately, and let the job retry with backoff. Store the hash, the intended payload, and the final status in your own table — the SDK won't remember it for you.
• Wrap external reads in a cache with a short TTL. Token metadata and network config are near-static (minutes-to-hours TTL); balances are not (seconds at most, or skip caching entirely). A stale balance in a checkout flow is worse than a slow one.
• Fake the HTTP layer in tests. Most of the SDK's surface ultimately hits the API/gateway, so Http::fake() with recorded responses is far more reliable than trying to mock the SDK's internal objects. Keep a small fixture set per network.
• Pin the version explicitly in composer.json and read the changelog on every bump. This package wraps an upstream PHP SDK, so a wrapper patch release can still pull transitive breaking changes.

Gotchas and Tips

• v3.0.0 is a compatibility release, not a feature release. The only change is Laravel 12 support, yet it shipped as a major bump — that almost always means the illuminate/* constraint was raised or narrowed, not that the API changed. Before upgrading, diff the composer.json constraints in the v2.3.0 and v3.0.0 tags. If you're on Laravel 10 or 11 and the new constraint drops your version, you cannot upgrade and should stay pinned to ^2.3. If you're already on 11/12, expect a near-zero-risk upgrade.
• Run the full suite after upgrading anyway. A major bump signals the author reserves the right to break things; even a constraint-only release can change which transitive SDK version Composer resolves for you. composer why mx-sdk and composer outdated --direct are your friends here.
• Floats will silently corrupt amounts. EGLD has 18 decimals and ESDT tokens vary. Any use of PHP floats or (float) casts on amounts is a bug waiting to lose funds — keep amounts as strings/integers in the smallest denomination and convert only at the display boundary.
• A "failed" transaction still costs gas. Underestimated gas limits produce on-chain failures after broadcast, not before. Log the gas used vs. the gas limit on every transaction; a consistent gap is your signal to raise the default in config.
• Network mismatch is the classic misconfiguration. The network setting, the API endpoint, and the token identifiers you're passing must all agree. A devnet token queried against a mainnet endpoint returns a confusing "not found" rather than a clear error. Assert the network in a boot-time check on non-production environments.
• Polling for finality needs a deadline. Transactions move through pending → success/failure, and the pending window can be long. Always bound the poll loop with a timeout and a terminal "unknown, check manually" state; infinite while loops against the gateway are a common production hang.
• Gateway rate limits are real. Batch reads, add jittered retry with exponential backoff, and avoid per-item calls inside a foreach over a user list. If you need N balances, look for a bulk endpoint before writing the loop.
• Debug with Http::fake failing loudly. If a request 404s in tests, log the actual URL — it's nearly always a trailing-slash or /v1 prefix difference between the configured endpoint and the SDK default. Dumping the resolved config in tinker settles it faster than reading the SDK source.
• Extension point: the config file is the intended override surface. Resist patching vendor code for endpoint tweaks; anything you can't express in config is worth an issue upstream, because the next minor release will overwrite your patch.