Rlp Laravel Package

Technical Evaluation

Architecture fit

• web3p/rlp is a single-purpose, low-level codec — two public methods (encode, decode) plus a Str helper. It carries no Ethereum domain model, no transaction abstraction, no signing, no RPC. Architecturally it belongs in an infrastructure/adapter layer, never called directly from controllers, jobs, or domain services. The TPM decision is less "should we use this" and more "what do we wrap it in."
• It is the correct primitive for Ethereum transaction envelope serialization (legacy and typed/EIP-2718 payloads), trie key/node encoding, and p2p wire formats. It is not a substitute for ABI encoding: contract calldata and eth_getTransactionByHash.input are ABI-encoded, not RLP. Scope conversations should settle this early — it is the most common misunderstanding in stakeholder requests and it will be mis-sold internally otherwise.
• Because the package is stateless and dependency-free, it is trivially testable and trivially replaceable. That is the strongest architectural argument for adopting it over hand-rolled RLP: the interface you own is small enough that a fork or a swap costs days, not months.

Integration feasibility

• Composer-installable, pure PHP, no extensions, no Laravel coupling. CI covers PHP 7.1 through 8.4. There is no service provider, facade, config, or exception hierarchy — the team writes roughly 30–50 lines of Laravel glue. That is a feature for a TPM: minimal surface area to audit.
• The friction points are at the boundaries, and they are cheap to design away:
  • decode() accepts only 0x-prefixed hex, rejects odd-length hex, and returns an array of hex strings (not binary, not scalars). Every caller must convert. Centralize this once.
  • encode() returns non-zero-prefixed hex. Callers expecting 0x… must add it.
  • Negative, fractional, and out-of-range numbers throw InvalidArgumentException; values above PHP_INT_MAX must be passed as hex strings. This is a runtime-error class the application layer must pre-validate.
• 0.4.0 is a breaking release that fixed genuine protocol bugs (leading-zero stripping, non-canonical lengths, truncated input accepted silently, list payloads ≥56 bytes followed by other items). The feasibility conclusion is blunt: only 0.4.x is safe to ship. Anything pinned earlier produces RLP that other clients will reject or misinterpret.

Technical risk

• Bus factor / adoption: 28 stars, 0 dependents, no corporate backing, no visible maintainer team. Treat this as "we are adopting a stable codec and will own it," not "we are consuming a supported product."
• Packaging hygiene: the README instructs Set minimum stability to dev before requiring. That is inappropriate for a production Laravel app and will destabilize the whole dependency graph. Must be overridden with an explicit stable pin.
• DoS surface: decode() performs recursive parsing of attacker-controllable payloads. 0.4.0 fixed a TypeError crash on declared lengths above PHP_INT_MAX, but large-but-legal declarations still allocate. Without an input-size cap and recursion cap at the adapter, untrusted input is a memory/CPU amplification vector.
• Performance unknown: no benchmarks. PHP string concatenation and recursion mean this is fine for request-path volumes and wrong for bulk pipelines until measured.
• Correctness confidence: Codecov badge and a test suite that specifically regression-tests boundaries (0/1/55/56-byte payloads, nested lists, canonical single bytes) is reassuring for interoperability. Still, our vectors must be validated against an independent implementation.

Key questions for the TPM

1. Where does RLP actually execute — our PHP services, or an already-trusted JS/Go/Rust signer downstream? If nothing in PHP needs to produce canonical RLP, adopting this is premature.
2. Which transaction types must we support (legacy, EIP-155, EIP-1559, EIP-2930)? The package encodes the payload; the surrounding type-byte framing is ours to own.
3. Are decode inputs internal-only or user-supplied? This determines whether we need size/depth caps as a launch blocker.
4. Who owns the fork if a protocol-adjacent bug appears? Name the engineer and the review skill (the repo's own RLP review checklist is a good template).
5. What is the parity requirement — byte-exact against ethereumjs/rlp and one Go/Rust implementation — and in which environment is that verified?
6. Do we accept a dependency with zero production users, or do we vendor/fork it into our monorepo to eliminate the supply-chain question?

Integration Approach

Stack fit

• Composer-only; no Laravel version constraints; works under PHP 7.1–8.4. Bind Web3p\RLP\RLP as a singleton in a Web3ServiceProvider. Do not let new RLP appear outside the adapter.
• Define an owned interface (RlpCodec::encode(mixed): string, ::decode(string): array) and a single implementation delegating to the vendor class. Every future decision — fork, swap, native extension — becomes an implementation change.
• Standardize the boundary contract in that adapter: accept/emit 0x-prefixed hex consistently, convert to binary only at the last mile, and translate vendor InvalidArgumentException/RuntimeException into domain exceptions. Add the size and recursion caps here.
• If signing is in scope, this package is one leg only. Pair with web3p/web3.php / ethereum-tx for the transaction model and signature, and use this strictly for the RLP layer.

Migration path

• Greenfield: adopt directly at 0.4.x with the adapter and a golden-vector suite on day one.
• Replacing hand-rolled or older-version RLP: this is the higher-risk path and needs a real migration, not a swap. Build a golden-file corpus from real payloads (raw transactions pulled via eth_getRawTransactionByHash, plus trie keys) and run old vs. new in shadow mode — encode and decode both ways, assert byte equality, log divergence, fix, then cut over. Expect divergence specifically on leading-zero addresses/hashes and non-canonical inputs, which older code accepted and 0.4.0 rejects.

Compatibility

• Pin ^0.4 in composer.json, commit composer.lock, and explicitly do not adopt the README's minimum-stability: dev guidance — set root stability to stable.
• Add composer audit and a dependency-review step to CI so a future advisory surfaces without relying on the maintainer.
• PHP 8.3/8.4 deprecations are covered by upstream CI, but our own upgrade tests must run the adapter suite against each PHP version we support.

Sequencing

1. Spike (1–2 days): verify known vectors — 'dog' → 83646f67, ['dog'] → c483646f67, empty string → 80, empty list → c0, 55/56-byte boundaries, nested lists, zero/leading-zero hex, over-PHP_INT_MAX values. Confirm 0.4.0 is retrievable at stable stability.
2. Adapter + DI + exception mapping + input caps (~2 days, with tests).
3. Golden-vector suite in CI, cross-checked against ethereumjs/rlp (and a Go/Rust reference) as the authoritative oracle.
4. Shadow validation against real production payloads if migrating.
5. Feature-flagged rollout, then document the fork policy and upgrade runbook.
6. Defer any batch/high-throughput use until benchmarked.

Operational Impact

Maintenance

• Expect very low churn and near-zero upstream responsiveness. That is acceptable for a frozen serialization spec: RLP has not changed since inception, and the 0.4.0 release closed the known correctness gaps. The realistic maintenance load is ~2–3 engineer-days per year: PHP version bumps, occasional dependency review, and one planned fork if a bug is ever found. Budget it explicitly rather than assuming the community covers it.
• Pin the version, watch GitHub releases (there is no security feed for a 28-star repo), and keep composer audit in CI. Vendor or fork pre-emptively if procurement requires a named maintainer; the codebase is small enough that forking is a legitimate, low-cost risk mitigation.

Support

• No vendor, no SLA, no support contract. Support model is internal ownership with public docs. The repo's own RLP review checklist (canonical encoding, prefix boundaries, length-of-length, non-canonical rejection, truncation, trailing bytes) should become our review checklist and our test-plan source.
• Because there are zero dependents, any bug we hit is almost certainly unreported. Write the failure triage into the runbook: reproduce with a minimal hex vector, compare against ethereumjs/rlp, then decide patch-vs-fork.

Scaling

• Pure-PHP string manipulation, CPU-bound, single-threaded. Comfortable for request-path volumes (tens to low hundreds of encodes per request cycle); not suited to bulk backfills or high-rate pipeline work without measurement. Move batch encoding to queued workers, cache any constant encodings, and benchmark before committing to a throughput SLO.
• The real scaling hazard is decode of untrusted data: recursive descent plus length declarations means a small input can trigger large allocation. Cap input size (e.g., reject > 64–128KB) and recursion depth at the adapter before calling the vendor. This is a launch blocker for any public endpoint.

Failure modes

• InvalidArgumentException — bad hex, odd-length hex, 0xhello, negative/fractional/out-of-range numerics. Mostly preventable by validating and normalizing upstream; each occurrence is a 500 until mapped.
• RuntimeException — malformed RLP: truncated payloads, items longer than their list, trailing bytes, non-canonical lengths. For untrusted input, map to a 4xx and log the vector.
• Silent non-interoperability — the worst mode. Pre-0.4.0 encodings of leading-zero addresses or single bytes below 0x10 are wrong but look plausible; downstream nodes reject or misinterpret. The mitigation is the version pin plus the cross-implementation golden suite.
• Precision loss on large integers — values above PHP_INT_MAX passed as ints rather than hex strings. Enforce a "quantities are hex strings" convention at the adapter.
• Conceptual misapplication — someone uses RLP where ABI encoding is required, or expects input from eth_getTransactionByHash to be RLP. Produces garbage that fails silently at the contract layer. Address in onboarding, not in code.
• Memory exhaustion on adversarial decode payloads until caps are in place.

Ramp-up

• Library ramp-up is trivial: under half a day for a mid-level PHP engineer. Two methods, no config, no lifecycle.
• Domain ramp-up is the real cost: 1–3 days to internalize when RLP applies (transaction envelopes, trie keys) versus when it does not (calldata, JSON-RPC params), how canonicality and single-byte encoding rules bite, and how the hex/binary boundary is handled in this codebase.
• Onboarding package: the boundary contract (0x-prefixed hex in/out, no zero-prefixing assumptions, hex-only decode), a 20-vector regression file, the exception-to-HTTP mapping table, and a one-page note that this dependency is intentionally frozen and internally owned.