perf(bcs): closure-based encoder/decoder with bulk ops and bounds checks

[hayes-mysten]

Description

Major performance rewrite of @mysten/bcs replacing the DataView-based reader/writer with a closure-based encoder/decoder architecture.

Many performance ideas in this rewrite were inspired by @unconfirmedlabs/bcs by BL. Their work on codegen-based BCS decoding and object factory patterns informed several of the optimizations here.

Benchmarks vs main (Node.js, 100K iterations)

Serialize:

Payload	Main	This PR	Speedup
SimpleStruct (41B)	1,712 ns	83 ns	20.6x
NestedStruct (65B)	1,485 ns	175 ns	8.5x
Enum variant (33B)	762 ns	128 ns	6x
u64 (8B)	937 ns	75 ns	12.5x
u128 (16B)	1,339 ns	81 ns	16.5x
u256 (32B)	2,578 ns	284 ns	9.1x
Option<Struct> (42B)	1,997 ns	99 ns	20.2x
Vec<u32> x1000 (4KB)	28,778 ns	2,356 ns	12.2x
Address [32]u8 (32B)	1,340 ns	84 ns	16x

Deserialize:

Payload	Main	This PR	Speedup
SimpleStruct (41B)	657 ns	127 ns	5.2x
NestedStruct (65B)	639 ns	249 ns	2.6x
Enum variant (33B)	354 ns	43 ns	8.2x
u64 (8B)	1,036 ns	79 ns	13.1x
u128 (16B)	2,332 ns	196 ns	11.9x
u256 (32B)	5,291 ns	498 ns	10.6x
Option<Struct> (42B)	921 ns	93 ns	9.9x
Vec<u32> x1000 (4KB)	13,246 ns	2,511 ns	5.3x
Address [32]u8 (32B)	495 ns	67 ns	7.4x

Real-world TX Effects (1000 transactions, bun):

Phase	Main	This PR	Speedup
Serialize	44K ops/s	354K ops/s	8.1x
Deserialize	93K ops/s	498K ops/s	5.3x
Roundtrip	28K ops/s	197K ops/s	7.0x

Architecture changes

• New bcs-decode.ts / bcs-encode.ts with createDecoder() / createEncoder() factories closing over private offset/buffer state
• Singleton instances for BcsType.parse() / toBytes(); independent instances for standalone BcsReader / BcsWriter
• BcsReader / BcsWriter are now thin wrappers around decoder/encoder instances
• Deleted uleb.ts — ULEB logic inlined into encoder/decoder closures

Performance optimizations

• Manual little-endian byte reads instead of DataView
• Bulk decode/encode for primitive vectors (u8, u16, u32, u64, bool)
• ASCII fast path for string encode/decode
• Unrolled struct/enum/tuple codecs for 1-8 fields
• Object factory pattern for struct/enum decode (stable hidden classes)
• Shared buffer reuse for small serializations
• Pre-computed ULEB bytes for enum variant indices

Safety

• Post-decode bounds check in parse() and read() — throws RangeError on truncated/malformed input
• maxSize enforced in ensure() during buffer growth (fails early)
• Per-field validation preserved through compound builders (_codec.write includes validation)
• Decoded bytes always returned as copies (slice, not subarray)
• Enum property order preserved (variant key before $kind)
• Defense-in-depth throw in enum encoder on no matching variant

Public API

• No exports added or removed from index.ts
• New convenience methods on BcsType: toBytes, toHex, toBase64, toBase58
• BcsType.read() and write() deprecated in favor of parse()/toBytes()/serialize()
• BcsType.toBytes() is the fast path; serialize() wraps it with SerializedBcs

Test plan

• 328 BCS tests (up from 124 on main), +5 new test files
• 339 sui unit tests all passing
• Test coverage for: enum property order, decoded byte independence, per-field validation in structs/enums/tuples, transform validation chain, malformed input, ULEB >2^32

---

AI Assistance Notice

• This PR was primarily written by AI.
• I used AI for docs / tests, but manually wrote the source code.
• I used AI to understand the problem space / repository.
• I did not use AI for this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
sui-typescript-docs	Ignored	Preview	Apr 7, 2026 5:56pm