Speed up PlutusData/CBORSerializable decode ~5.4x and encode ~4.3x (no behavior change)

[theeldermillenial]

Summary

A set of backend-independent optimizations to pycardano's (de)serialization hot paths, primarily benefiting PlutusData- and set-heavy workloads such as on-chain data indexing and transaction building. No new dependencies and no change to the CBOR library. Output is byte-for-byte identical (one documented exception noted below). All tests pass on Python 3.9–3.13.

Motivation

Profiling showed the cost of typed PlutusData decode and real-transaction (de)serialization is dominated by repeated, data-independent work in pycardano itself — not the CBOR backend: per-node get_type_hints() / signature introspection, per-value type dispatch, redundant typeguard return-checks, re-encoding set elements for de-duplication, and defensive deepcopys on every multi-asset encode.

Changes

Decode

• Memoize get_type_hints(cls) and from_primitive type_args introspection per class.
• Cache PlutusData.__post_init__ field-type validation per class (per-instance byte-length check preserved).
• Resolve each field's decode dispatch once into a memoized decode plan, plus per-class array/map field plans, instead of re-running the issubclass/__origin__/isinstance chain on every value.
• OrderedSet keys de-duplication by the element's native hash (CBOR-bytes fallback for unhashable elements), avoiding a dumps() per element — previously ~78% of real-transaction decode time.
• Guard the speculative Byron-address cbor2.loads probe behind a byte-prefix check.

Encode

• Route the recursive to_primitive descent through an un-annotated worker, and drop the redundant typeguard return-check on to_validated_primitive, so the large Primitive Union isn't re-validated at every node.
• _dfs: scalar-leaf fast path and direct IndefiniteList.data iteration (avoids the slow Sequence.__iter__).
• Cache dataclasses.fields() per class in to_shallow_primitive.
• Skip deepcopy().normalize() in Asset/MultiAsset.to_shallow_primitive when there are no zero/empty entries.

All caches are keyed by class, not data (so the wins hold across millions of unique objects) and use WeakKeyDictionary so dynamically-created classes are still garbage-collected.

Benchmarks

Pure-Python CBOR backend, best-of-5 (reproduce with the included benchmarks/plutus_bench.py):

Operation	Before	After	Speedup
Typed PlutusData decode (200 fields)	4942 µs	~900 µs	~5.4×
Typed PlutusData encode (200 fields)	13531 µs	~2285 µs	~5.9×
Set-heavy transaction decode	886 µs	224 µs	~4×
MultiAsset.to_shallow_primitive	130 µs	33 µs	~3.9×

Correctness

• Decode: identical behavior — same DeserializeException cases, Union fallback order, list/dict/Optional handling, IndefiniteList preservation, object_hook metadata, and one-time f.type resolution.
• Encode: byte-for-byte identical output (verified on transaction / plutus / metadata round-trips).
• One documented behavior nuance: for hashable OrderedSet elements, de-duplication is now by Python __eq__/__hash__ rather than CBOR-byte equality. These coincide for pycardano's set element types (transaction inputs, key hashes, witnesses); unhashable elements retain the original CBOR-byte semantics. Covered by new tests.
• Full suite (unit + doctests) passes; flake8, mypy, black, isort clean. New code paths are covered by added tests; genuinely-unreachable defensive branches are marked # pragma: no cover.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 97.73756% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.83%. Comparing base (46382fd) to head (4bcaa5e).

Files with missing lines	Patch %	Lines
pycardano/address.py	80.00%	0 Missing and 2 partials ⚠️
pycardano/transaction.py	75.00%	0 Missing and 2 partials ⚠️
pycardano/serialization.py	99.47%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #492      +/-   ##
==========================================
+ Coverage   90.62%   90.83%   +0.20%     
==========================================
  Files          34       34              
  Lines        5154     5289     +135     
  Branches      781      802      +21     
==========================================
+ Hits         4671     4804     +133     
  Misses        304      304              
- Partials      179      181       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.