SDK shippability audit 2026-05-22

[linear]

SDK shippability audit 2026-05-22

Parallel to DEM-716 (Identity app), DEM-717 (SuperColony). Source: KYN-221. Auditor: Nesy-Claude.

Repo identification (HIGH)

• @kynesyslabs/demosdk npm package is backed by kynesyslabs/sdks, not kynesyslabs/demos-sdk (which 404s). Confirmed via package.json#name = "@kynesyslabs/demosdk". (HIGH)
• npm latest = 4.0.0 (published 2026-05-12T11:33:25Z). 280 total versions. Active publishing cadence. (HIGH)
• The umbrella's kynesyslabs/demosdk-api-ref is a separate API-reference repo, not the SDK source. (HIGH)

Summary table

Dimension	Finding	Confidence
Latest release	v4.0.0 shipped 2026-05-12. v3.1.0 on 2026-05-07. v3.0.0-rc.1 on 2026-05-07 (P4 osDenomination migration).	HIGH
Last 20 commits on main	All by tcsenpai. Spike 2026-05-07 (release v3.0.0-rc.1 → v3.1.0: 14 commits landing the bigint OS denomination work + fork-detection cache + IPFS / d402 / amounts normalisation). 2026-05-11 single commit added rpc_address to TxFee + extended NetworkParameters for DEM-665. 2026-05-12 → release v4.0.0.	HIGH
Open PRs	7 open, all authored by SergeyG-Solicy (external contractor). Age range 43–132 days. None merged into the v3/v4 release train. One (#70 ERC-8004) is labelled Failed compliance check.	HIGH
CI on HEAD (v4.0.0)	GitHub Actions ✅ Build, ✅ TypeDoc, ✅ CodeQL (TS / Python / Actions), ✅ SonarCloud — all green. claude / greptile / mintlify / railway / graphite apps queued (informational).	HIGH
Test coverage — critical paths	37+ spec files under src/tests/. Denomination module has 4 dedicated specs (conversion, networkInfo, roundTripHash, serializerGate). PQC covered by pqc.spec.ts, ucrypto.spec.ts. Multichain: 14 chain-specific specs (aptos, btc, evm, ibc, multiversx, near, solana, ten, ton, xrpl + finders + fulltx). D402, IPFS cost normalization, fork detection + cache keying, wire format, native tx, storage programs all have dedicated specs. Workflow test.multichain.yml exists.	HIGH
v3.0.0 release state	Shipped. The P4 osDenomination migration: bigint OS internal, OS-string on the wire, dual-format serializerGate matching node's wire format, SubDemPrecisionError guard for pre-fork nodes, denomination module with demToOs / osToDem / parseOsString / toOsString / formatDem + OS_DECIMALS / OS_PER_DEM / MIN_AMOUNT_OS / ZERO_OS. Wire-type widening across TransactionContent, TxFee, RawTransaction, StatusNative, GCREditBalance, GCREditEscrow. Migration guide MIGRATION_v2_to_v3.md is present and complete.	HIGH
v3.1 / v3.2 roadmap	v3.1.0 already shipped (decimals P4 polish — see decimals-p4 PR #86 merged 2026-05-07). No separate v3.2 cut — the next bump went straight to v4.0.0 for a TxFee/NetworkParameters wire widening. No public roadmap document; CHANGELOG only covers 3.0.0-rc.1 with a 2.x stub.	MEDIUM
v4.0.0 contents	Diff v3.1.0 → v4.0.0 = 2 commits, 10 files. The substantive commit (858e205) adds rpc_address: string to TxFee and extends NetworkParameters types for DEM-665 (Gas Fee Separation Plan, now Done). Major bump justified by wire-type widening; runtime impact small.	HIGH
Mainnet-critical surface — bigint denomination APIs	Production-ready. Full module at src/denomination/ (constants + conversion + networkInfo + serializerGate, each with paired tests). Public-API entry points throw SubDemPrecisionError before signing if a pre-fork node would lose sub-DEM precision. Fork detection cached per-Demos-instance lifetime, first failure → single console.warn.	HIGH
Mainnet-critical surface — post-quantum signing	Falcon: implemented under src/encryption/PQC/falconts/ (full module + mnemonic + wordlist). ML-DSA: implemented via @noble/post-quantum and surfaced through unifiedCrypto.ts (SerializedSignedObject.algorithm: "ml-dsa" | "falcon" | "ed25519", PqcSignedObject). ML-KEM also wired for encryption ("ml-kem-aes"). No "dilithium"/"ml-dsa" literal hits in code search beyond unifiedCrypto.ts — algorithm selection is type-routed, not file-per-algorithm. Test coverage: src/tests/encryption/pqc.spec.ts, ucrypto.spec.ts, newdemos.spec.ts.	HIGH
Mainnet-critical surface — Liquid Tanks SDK helpers	GAP: there are no Liquid Tanks SDK helpers. src/bridge/nativeBridge.ts is the only bridge surface and it does not reference liquidityTank, solana_tank, or tank inventory. Liquid Tanks is a node-side concern (DEM-704, bridge contracts + Solidity + Anchor) — not in the SDK. If the v2 mainnet rollout needs client-side tank quote / withdrawal helpers, that is net-new SDK work not present in v4.0.0. (HIGH on the gap; MEDIUM on whether SDK helpers are even the intended carrier — node-only is also viable.)	HIGH (gap) / MEDIUM (need)
L2PS (related but distinct)	src/l2ps/l2ps.ts (12.9 KB, exports L2PSConfig + L2PSEncryptedPayload) is shipped. AES-GCM transaction encryption + Ed25519 outer signing. Docs page /sdk/websdk/l2ps/overview.md exists.	HIGH
Documentation health (docs.kynesys.xyz/sdk)	Index at /llms.txt enumerates ~85 pages: Core, Cross-Chain (15 chains), Storage Programs, WebSDK, Web2 identities, TLSNotary, Cookbook, Bridges, L2PS, PQC. Only Storage Programs carries an explicit v3.1.0 marker. All other pages are unversioned, which is a freshness risk now that v4.0.0 has shipped. Denominations page exists (/sdk/websdk/transactions/denominations.md). PQC page exists. No /sdk/api-reference (404). No visible "last updated" timestamps.	HIGH (structure) / MEDIUM (freshness)
Repo hygiene	0 open issues. 7 open PRs from a single external author, none recent. CI all green. CHANGELOG.md exists but only covers 3.0.0-rc.1 + a 2.x stub — drift behind reality (v3.1.0, v4.0.0 not in CHANGELOG). MIGRATION_v2_to_v3.md is complete.	HIGH

3 most ready-to-ship items

Ranked by "minimum work to declare mainnet-ready". Each item is already in v4.0.0 on npm; the listed action is what would still need to happen before a mainnet ship-out announcement.

1. denomination module + bigint OS public-API surface — READY (confidence: HIGH)

• Ships in v3.0.0-rc.1 / v3.1.0 / v4.0.0. Public APIs accept bigint (preferred) or number (deprecated DEM legacy, auto-converted).
• Tests: 4 dedicated specs in src/denomination/ + 2 cross-cutting specs (amountValidation.spec.ts, d402AmountValidation.spec.ts, wireFormat.spec.ts).
• Fork detection guard (SubDemPrecisionError) protects pre-fork nodes from silent precision loss.
• Migration guide MIGRATION_v2_to_v3.md is in-tree and complete.
• Pre-announce action: none code-side. Add a "v3 → v4 wire-type widening" appendix to the migration doc (10-line note about TxFee.rpc_address + NetworkParameters for DEM-665). Effort: S.

2. Post-quantum signing (Falcon + ML-DSA) via unifiedCrypto — READY (confidence: HIGH)

• unifiedCrypto.ts (18.8 KB) routes signing through typed SerializedSignedObject / PqcSignedObject for ml-dsa | falcon | ed25519, encryption via ml-kem-aes.
• Falcon impl: src/encryption/PQC/falconts/ (own module + mnemonic + wordlist).
• ML-DSA + ML-KEM impl: @noble/post-quantum@^0.4.1 (NIST FIPS-203/204).
• Tests: pqc.spec.ts, ucrypto.spec.ts, newdemos.spec.ts, plus IM (im.spec.ts) and identities (abstraction/identities.spec.ts).
• Pre-announce action: the docs page /sdk/post-quantum-cryptography.md should be sanity-checked against the v4.0.0 types (names: "ml-dsa", "falcon", "ml-kem-aes"). Effort: S.

3. L2PS (Layer 2 Private Subnets) client surface — READY for v4 (confidence: HIGH)

• src/l2ps/l2ps.ts ships L2PSConfig + L2PSEncryptedPayload, AES-GCM tx encryption, encrypted-tx flow documented in l2ps_flow.md (in-tree).
• Public docs at /sdk/websdk/l2ps/overview.md.
• Pre-announce action: confirm the "L2PS" docs page matches v4.0.0 imports (UnifiedCrypto, Hashing, L2PSTransaction types). Effort: S.

Known gaps / non-ready items (parked, not blocking the audit ticket)

• Liquid Tanks SDK helpers — not present. Tied to DEM-704 (Native Bridges v2 / Liquid Tanks ship plan, EVM-only v2, 6–8 week window). DEM-704 plans the node + contracts work; whether the SDK needs to grow LiquidityTank quote / withdrawal helpers is a downstream decision once the node-side multisig (P0-1) lands. Flag: scope DEM-704 follow-up to decide if SDK helpers are in v2 or v2.1. (HIGH gap, MEDIUM whether SDK is the carrier)
• External-contractor PR backlog — 7 PRs from SergeyG-Solicy, oldest 132 days. Nothing in the v3/v4 train picked these up. Worth a separate triage pass to either land, close, or rebase. (HIGH on the staleness, LOW on mainnet criticality)
• CHANGELOG drift — CHANGELOG.md only covers 3.0.0-rc.1. v3.1.0 and v4.0.0 are absent. Low-effort cleanup before public-facing v4 announcement. (HIGH gap, LOW effort)
• Docs version markers — only Storage Programs is tagged v3.1.0. The rest of the docs are unversioned and the v4.0.0 wire-type widening is not reflected anywhere user-visible. (MEDIUM)

SDK ↔ DEM-704 dependency line

• Today (v4.0.0): SDK ships the denomination + PQC + L2PS surface DEM-704 will need. No additional SDK changes are listed as v2 blockers in DEM-704's P0-1 / P0-2 / P0-3.
• If v2 grows client-side tank helpers (e.g. demos.bridge.quoteWithdrawal(tankUid, amount) style), that becomes a v4.x SDK feature ticket — currently unspecced.
• No blocking SDK dependency for DEM-704's W1–W8 schedule based on the ship plan as written.

Provenance

• npm registry: @kynesyslabs/demosdk, dist-tag latest=4.0.0, published 2026-05-12T11:33:25Z.
• GitHub: kynesyslabs/sdks, HEAD 0e09bb2 ("release v4.0.0"), default branch main.
• CI: GitHub Actions + SonarCloud + CodeQL — all green on HEAD.
• Source readings: package.json, CHANGELOG.md, MIGRATION_v2_to_v3.md, src/denomination/*, src/encryption/PQC/, src/encryption/unifiedCrypto.ts, src/l2ps/l2ps.ts, src/l2ps/l2ps_flow.md, src/tests/*, .github/workflows/.
• Docs: docs.kynesys.xyz/llms.txt (full index), docs.kynesys.xyz/sdk (Getting Started landed).
• Related: DEM-704, DEM-665 (Done), DEM-716, DEM-717, KYN-221.

— Nesy-Claude (read-only synthesis; no branch or code state was changed).