Context
The project's secure, pure-TypeScript XDR parser (lib/translator/secure-xdr-parser.ts) already exists and is well-tested — this issue is not about security hardening, that's done. This is about the previously-documented (but never-built) performance path: a native Rust decoder for high-throughput scenarios, with the existing TypeScript parser kept as the automatic fallback.
native/soroban-xdr-decode doesn't exist. There is currently no native module, no build tooling for one, and no benchmark demonstrating it's actually worth the complexity before you build it.
Scope of work
Benchmark first. Before writing Rust, write a benchmark harness that exercises secure-xdr-parser.ts against realistic event payload sizes and volumes, and establish the actual throughput baseline. This becomes your comparison point — a native module that isn't demonstrably faster under realistic load isn't worth merging.
native/soroban-xdr-decode — a Rust crate exposing a decode function via N-API (napi-rs is the natural choice given this is a Node.js project), matching the exact input/output contract of secureParseScVal in secure-xdr-parser.ts — same success/error shape, same security limits enforced (recursion depth, memory allocation, timeout, collection size — port the same guards, don't relax them for speed).
Automatic fallback: the code path that currently calls secureParseScVal should attempt the native module first (if built and available for the current platform) and transparently fall back to the TS implementation if the native addon isn't present or fails to load — this must not be a manual toggle a deployer has to configure correctly, it should just work either way.
Build tooling: npm run build:native, build:native:debug, build:native:docker (for cross-compilation in a container, since contributors and CI won't all be on the same OS/arch), wired to actually build the crate this time.
Parity test suite: the single most important deliverable here — a test suite that runs the same fuzz/security test cases already in lib/translator/tests/fuzz-xdr-parser.test.ts and parser-security.test.ts against both the native and TS implementations and asserts identical results. A native decoder that's fast but handles a malicious payload differently than the TS parser is a security regression, not a performance win.
Document real numbers in the README section for this feature — actual before/after throughput from your benchmark, not a marketing claim.
Out of scope
Native modules for anything other than XDR decoding.
Supporting platforms beyond what a standard napi-rs prebuild matrix covers (Linux x64/arm64, macOS x64/arm64, Windows x64) — document unsupported platforms clearly rather than trying to cover everything.
Acceptance criteria
Benchmark harness exists and shows a clear, documented throughput comparison
npm run build:native produces a working addon
Fallback to the TS parser is automatic and covered by a test that simulates the native addon being unavailable
Parity test suite passes identically on both implementations for every existing fuzz/security test case
No security guard is weaker in the native implementation than in secure-xdr-parser.ts
npm run build:native:docker succeeds in a clean container (proves it's not just working on your machine)
Context
The project's secure, pure-TypeScript XDR parser (lib/translator/secure-xdr-parser.ts) already exists and is well-tested — this issue is not about security hardening, that's done. This is about the previously-documented (but never-built) performance path: a native Rust decoder for high-throughput scenarios, with the existing TypeScript parser kept as the automatic fallback.
native/soroban-xdr-decode doesn't exist. There is currently no native module, no build tooling for one, and no benchmark demonstrating it's actually worth the complexity before you build it.
Scope of work
Benchmark first. Before writing Rust, write a benchmark harness that exercises secure-xdr-parser.ts against realistic event payload sizes and volumes, and establish the actual throughput baseline. This becomes your comparison point — a native module that isn't demonstrably faster under realistic load isn't worth merging.
native/soroban-xdr-decode — a Rust crate exposing a decode function via N-API (napi-rs is the natural choice given this is a Node.js project), matching the exact input/output contract of secureParseScVal in secure-xdr-parser.ts — same success/error shape, same security limits enforced (recursion depth, memory allocation, timeout, collection size — port the same guards, don't relax them for speed).
Automatic fallback: the code path that currently calls secureParseScVal should attempt the native module first (if built and available for the current platform) and transparently fall back to the TS implementation if the native addon isn't present or fails to load — this must not be a manual toggle a deployer has to configure correctly, it should just work either way.
Build tooling: npm run build:native, build:native:debug, build:native:docker (for cross-compilation in a container, since contributors and CI won't all be on the same OS/arch), wired to actually build the crate this time.
Parity test suite: the single most important deliverable here — a test suite that runs the same fuzz/security test cases already in lib/translator/tests/fuzz-xdr-parser.test.ts and parser-security.test.ts against both the native and TS implementations and asserts identical results. A native decoder that's fast but handles a malicious payload differently than the TS parser is a security regression, not a performance win.
Document real numbers in the README section for this feature — actual before/after throughput from your benchmark, not a marketing claim.
Out of scope
Native modules for anything other than XDR decoding.
Supporting platforms beyond what a standard napi-rs prebuild matrix covers (Linux x64/arm64, macOS x64/arm64, Windows x64) — document unsupported platforms clearly rather than trying to cover everything.
Acceptance criteria
Benchmark harness exists and shows a clear, documented throughput comparison
npm run build:native produces a working addon
Fallback to the TS parser is automatic and covered by a test that simulates the native addon being unavailable
Parity test suite passes identically on both implementations for every existing fuzz/security test case
No security guard is weaker in the native implementation than in secure-xdr-parser.ts
npm run build:native:docker succeeds in a clean container (proves it's not just working on your machine)