Hashgraph Laravel Package

Getting Started

• Install with composer require trustenterprises/hashgraph:3.0.1-alpha and pin the exact version — no caret, no tilde. This is a major-version, alpha-tagged release (2.3.0 → 3.0.1) with a new inscription subsystem; treat it as a breaking change until the changelog proves otherwise.
• If you need stability, pin to 2.3.0 and skip this release. The 3.x line is explicitly "alpha, use at your own risk" per the release notes. Make that decision consciously per environment — it's fine to run 3.0.1-alpha in staging and 2.3.0 in production, but never the reverse.
• Publish the config with php artisan vendor:publish --provider="TrustEnterprises\\Hashgraph\\HashgraphServiceProvider" (verify the provider namespace in composer.json/README first; it may differ). Open config/hashgraph.php and read every key before writing code — that file is the real API surface. Diff it against any previously published config after upgrading, as 3.x likely adds keys.
• Populate the expected env vars: Hedera operator account ID (0.0.xxxxx), operator private key, network selection (mainnet vs testnet), and the Trust Enterprises REST API base URL. Most "it doesn't work" reports on wrappers like this come from network/key mismatch, not code.
• Read the PHP tests before the README. The release notes explicitly point to tests/ for inscription examples, which strongly implies the README has not caught up with 3.x. The tests are the de facto API reference for this release.
• First use case: a read-only or cheap call. Submit a message to a consensus topic (or fetch account info) to prove credentials, base URL, and network all line up before attempting inscriptions, HBAR transfers, or token creation — all of which cost real money on mainnet.
• Where to look first: the facade's docblock and the underlying service class, then the inscription service/classes introduced in 3.x. The REST API documentation from Trust Enterprises/Hedera is your secondary. Because the wrapper is thin, the upstream API docs describe behavior the README may omit.

Implementation Patterns

• Inject the service class via the container rather than resolving the facade statically. This is the single most important pattern here: it keeps the package mockable and makes it trivial to swap out if the package is abandoned — and if you're on the alpha, that risk is higher than usual.
• Put a thin domain gateway in front of it (e.g. HederaGateway) that exposes only the 5–10 operations your app actually needs, including any inscription operations. Never let package method signatures leak into controllers or models — inscription APIs in an alpha are exactly the kind of surface that will move between patch releases.
• Isolate the 2.x vs 3.x decision behind your gateway. If you adopt inscriptions, keep the inscription code path in its own adapter class so that reverting to 2.3.0, or moving to 3.1 stable, touches one file. Do not scatter inscription calls through application code.
• Run all writes (transfers, token creation/minting, topic creation, inscriptions) inside queued jobs. These are network-bound HTTP calls with non-trivial failure rates; synchronous calls in a request cycle will hurt. Inscription payloads can be large and expensive, so this matters more than for simple transfers.
• Normalize responses immediately. Expect arrays or loosely typed objects, and map them into your own DTOs so a future package upgrade or replacement only touches the gateway. An alpha release is where this discipline pays off most.
• Test with Http::fake() if the package uses Laravel's HTTP client; if it ships its own Guzzle client, bind a fake implementation of the service class in the container instead. Add fixtures for the REST API's error bodies, not just happy paths. Port the package's own inscription tests into your integration suite as smoke coverage — they encode the expected request shape.
• Keep per-environment operator accounts. A testnet operator key must never be present in a mainnet-connected environment, and vice versa. With inscriptions, a misconfigured mainnet operator is a direct HBAR bill.
• Treat writes as idempotent-by-transaction-ID: persist request IDs / transaction IDs, and reconcile with mirror-node lookups rather than retrying blindly. Inscriptions are no exception — an inscription is a transaction and should be tracked the same way.
• If the package emits events, hook listeners for audit logging; otherwise dispatch your own domain events after successful calls so the rest of the app isn't coupled to the wrapper.

Gotchas and Tips

• This is alpha, and it's a major version bump. 2.3.0 → 3.0.1 means the API may have changed in ways the release notes don't enumerate. Read the diff on GitHub (compare/2.3.0...3.0.1-alpha), skim README, and check config/hashgraph.php for new keys. Pin 3.0.1-alpha exactly; ^3.0 is dangerous when 3.0.2 could ship anything.
• Maintenance risk remains the headline gotcha. Four stars, zero dependents, long gaps between releases, and now an alpha major. Pin the version, read the source (it's small), and assume you may need to fork or replace it. Budget for that in your design (see the gateway pattern above).
• Inscriptions cost HBAR per write and are not cheap. Treat an inscription as a paid transaction: cap it, rate-limit it, and never let it run in a loop or a seeder. Verify current inscription fees against Hedera's docs before you wire it to an end-user action.
• Private key formats. Hedera keys are typically DER-encoded; the REST API may expect hex, DER, or a specific string format. Check the config comments and README, and test key parsing in isolation before debugging a "signature invalid" error inside a larger flow. Inscription endpoints likely sign payloads too, so a key-format bug will surface there first.
• Network mismatch (testnet credentials against a mainnet base URL, or vice versa) produces confusing "account not found" and "invalid payer" errors. Log the resolved network and base URL at boot in non-production. Also log the resolved package version — debugging an alpha with an unknown version in the logs is miserable.
• Latency and rate limits. Set explicit HTTP timeouts and wrap calls in retry-with-backoff for transient 5xx/429s. Inscriptions involve larger payloads, so raise the timeout for those calls specifically if the package reads one from config.
• Error handling is usually inconsistent. Don't rely on exceptions alone — inspect 4xx response bodies for the actual reason (insufficient balance, invalid account ID, throttled, malformed inscription). Surface the raw body in logs, but see the next point.
• Don't log secrets. Operator private keys and signed payloads must be excluded from logs, exception handlers, and queue failure output. Inscription payloads may embed sensitive content — whitelist what you log rather than dumping the request body.
• Never call write endpoints in tests or loops against mainnet. Every transaction costs HBAR; a runaway seeder or retry loop is a real bill, and an inscription loop is a bigger one.
• Validate Hedera IDs (0.0.\d+) and formats before sending. The API's validation errors are less clear than a local regex.
• Extension points are limited but real: the published config (base URL, timeout, network), the container binding (replace or decorate the service class), and the facade accessor. For inscriptions specifically, check whether the package exposes the inscription model/class for decoration — if not, keep your adapter thin so you can still own the boundary.
• If the alpha bites, calling the REST API directly with Http::withToken(...) is a legitimate alternative, and it removes a dependency you'd otherwise have to maintain. Now that the wrapper carries a major-version alpha, this option deserves more weight than it did on 2.x.