ZNN TS SDK Audit Findings

[0x3639]

Summary

A protocol-first audit of digitalSloth/znn-typescript-sdk v1.0.5 (f56d62e9942821a7d5685ba832fa121af3784f0f) found several node-facing incompatibilities, one unusable builder signature, precision and serialization risks, and five ABI boolean-validation failures.

This report is based on the stabilized Zenon SDK specification, which does not treat the TypeScript SDK, Dart SDK, or Go SDK as a universal gold standard. Node-facing decisions use pinned go-zenon execution/source; published standards govern cryptography; independent SDK agreement is used for ecosystem conventions; node-silent behavior is labeled as SDK policy. See the authority policy and stabilization report.

Confirmed protocol/wire gaps

• Accelerator createProject amount: send 100000000 base units (1 ZNN). v1.0.5 sends PROPOSAL_CREATION_COST_IN_ZNN, currently valued at 10 base units.
• Liquidity setTokenTuple signature: accept and ABI-encode string[], uint32[], uint32[], and uint256[]. The current scalar parameters and minAmounts.toString() cannot encode a valid call.
• Momentum JSON: decode data, publicKey, and signature from standard base64; parse content as an array of AccountHeader objects rather than JSON strings.
• AccountBlock JSON: decode publicKey and signature from standard base64, matching Go []byte JSON encoding, rather than treating them as UTF-8 bytes.
• StakeList precision: keep totalAmount and totalWeightedAmount as arbitrary-precision integers/base-10 strings, not JavaScript number.
• AccountInfo wire key: serialize the canonical RPC key accountHeight; the SDK currently reads accountHeight but writes blockCount.
• Pillar/Sentinel DepositQsr: send QSR, not ZNN. The node rejects a non-QSR token standard for these calls.
• FusionEntry response: do not require isRevocable; the node response contains qsrAmount, beneficiary, expirationHeight, and id.
• TimeChallengeInfo key casing: read the exact node-emitted keys MethodName, ParamsHash, and ChallengeStartHeight.
• Dead stats API: remove or explicitly deprecate stats.extraData and its ExtraData response model; the pinned node exposes only stats.osInfo, stats.processInfo, stats.networkInfo, and stats.syncInfo.

The complete pinned divergence record is spec/reference-divergences.json. Each item records the observed TypeScript behavior, normative behavior, severity, and affected API.

ABI hardening

The checked-in TypeScript ABI witness passes 486 of 491 cases. The five failures are:

• Reject non-boolean encode inputs: numeric 0, numeric 1, and string "true".
• Reject non-canonical decoded boolean words: value 2 and a word with a non-zero high byte.

Evidence: conformance/typescript/abi-results.json. The canonical ABI profile requires booleans to be exactly 0 or 1.

Ecosystem convention and documentation

• Use ZNN for the zero-amount Plasma CancelFuse call to match the official Dart and Go SDKs. This is a cross-SDK convention, not a node rejection: the node validates only that the amount is zero.
• Clarify or rename the keccak256 helper: its required output is FIPS SHA3-256, not Ethereum legacy Keccak-256. Preserve compatibility if renaming would be breaking.

Suggested acceptance criteria

1. Add regression tests for every checklist item above.
2. Run the existing SDK test suite with no regressions.
3. Run all 491 portable ABI cases and record 491/491 matches.
4. Add fixture tests for the corrected RPC JSON shapes and exact embedded-contract block fields.
5. Keep protocol requirements separate from SDK-policy choices; do not change behavior merely because another SDK does it differently.
6. Document any intentionally retained compatibility aliases or deprecated APIs.

Normative artifacts:

• Stable SDK spec
• Portable conformance vectors
• Reference divergences
• Accuracy and stable-gate findings

Proposed Codex implementation prompt

Audit and bring digitalSloth/znn-typescript-sdk into conformance with the stable Zenon SDK specification at:
https://github.com/0x3639/zenon-sdk-spec

Start from the SDK revision under review and record its exact commit. Read these files before changing code:
- docs/authority.md
- docs/stabilization-report.md
- spec/znn-sdk.json
- spec/reference-divergences.json
- conformance/typescript/abi-results.json
- conformance/vectors/

Authority rules:
1. For node-facing behavior, pinned go-zenon execution/source wins.
2. Use published standards for cryptography and derivation.
3. Use independent SDK agreement only for ecosystem conventions.
4. Label node-silent validation and API ergonomics as SDK policy.
Do not assume the TypeScript, Dart, or Go SDK is universally correct.

Implement every TypeScript item in spec/reference-divergences.json that applies to this repository. In particular, fix Accelerator createProject amount, Liquidity setTokenTuple array encoding, Momentum and AccountBlock base64 JSON handling, StakeList precision, AccountInfo accountHeight serialization, Pillar/Sentinel DepositQsr token standard, FusionEntry response parsing, TimeChallengeInfo key casing, and the dead stats.extraData API. Treat Plasma CancelFuse's ZNN token as an ecosystem convention and clarify that the keccak256-named helper computes FIPS SHA3-256.

Harden ABI booleans so encoding accepts only actual booleans and decoding accepts only canonical 0 or 1 words. Preserve all currently passing ABI behavior.

For each change:
- cite the relevant spec claim or divergence ID in the regression test;
- test exact bytes/JSON, not just object construction;
- preserve backward compatibility where it does not preserve incorrect wire behavior;
- deprecate compatibility aliases before removal when practical.

Run the native test suite and the portable conformance adapter. The definition of done is: native tests pass, all 491 ABI cases match, every corrected builder has an exact block/ABI regression test, every corrected model has a canonical wire fixture, and the final report separates protocol fixes from SDK-policy/convention changes. Work in reviewable commits and report any spec ambiguity instead of guessing.

This can remain an umbrella issue and be split into focused PRs by category: embedded-contract builders, wire models, ABI validation, and API cleanup/documentation.