refactor(sdk)!: fix type inconsistencies across wasm-sdk and js-evo-sdk

[shumkov]

Issue being fixed or feature implemented

Type inconsistencies between the wasm-sdk Rust layer and the js-evo-sdk TypeScript facades resulted in incorrect nullability annotations, unknown return types, and inconsistent parameter types that hurt developer experience and could mask runtime errors.

What was done?

• Unified optional return types: Changed | null to | undefined in unchecked_return_type macro to match JavaScript/TypeScript conventions where WASM returns undefined (not null) for absent values
• Replaced unknown return types with actual wasm types in all js-evo-sdk facade methods (e.g., Promise<unknown> → Promise<wasm.TokenMintResult>)
• Introduced named array type aliases: IdentifierLikeArray, PlatformAddressLikeArray, ProTxHashLikeArray for cleaner function signatures instead of raw IdentifierLike[]
• Fixed TokenLastClaim → RewardDistributionMoment mapping in unchecked_return_type to match the actual Rust type export
• Corrected ProTxHashLike nullability: Use ProTxHashLike | undefined instead of string | Uint8Array | null
• Removed unnecessary ?? null coercions in facade methods where the wasm layer already handles optional parameters
• Fixed missing | undefined in proof return types that incorrectly declared non-optional results
• Removed unused once_cell dependency from rs-platform-version
• Fixed eslint max-len warnings in facade files by reformatting long type signatures

How Has This Been Tested?

• Existing unit tests in js-evo-sdk updated and passing (e.g., identities.spec.ts mock adjustments)
• Type-checked with TypeScript compiler — no type errors in facade files
• Wasm-sdk unit tests remain green

Breaking Changes

No breaking changes at runtime. TypeScript return types are now more precise (e.g., unknown → specific type, | null → | undefined), which may surface compile-time errors in downstream code that was relying on the looser types.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

Summary by CodeRabbit

• New Features

  • Added document management actions: create, replace, delete, transfer, purchase, and set price.
  • Expanded proof-enabled queries and batch lookups across the SDK.

• Refactor

  • Standardized optional results to use undefined (replacing null) for more consistent responses.
  • Unified batch input parameters to typed array aliases across addresses, contracts, identities, tokens, groups, and epoch queries.
  • Some values are now guaranteed (e.g., total platform credits, prefunded balances).
  • Certain proof responses now return maps for clearer keyed results.

• Tests

  • Updated test configuration to use a different network preset.

• Chores

  • Lint cleanup and minor dependency removal.

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

📝 Walkthrough

Walkthrough

Type/interface updates across JS SDK facades and WASM bindings unify array aliases and shift optional results from null to undefined. DocumentsFacade adds six mutation methods delegating to the WASM SDK. Some return types are narrowed to non-optional. Tests switch to testnet SDK. Minor Rust/Cargo and lint changes included.

Changes

Cohort / File(s)	Summary
DocumentsFacade additions packages/js-evo-sdk/src/documents/facade.ts	Added create/replace/delete/transfer/purchase/setPrice delegations; reformatted existing signatures.
Identities & System: null→undefined and typing packages/js-evo-sdk/src/identities/facade.ts, packages/js-evo-sdk/src/system/facade.ts	Shifted many returns from null to undefined; adopted IdentifierLikeArray; narrowed some returns to non-optional (e.g., totalCreditsInPlatform, prefundedSpecializedBalance).
Batch array alias updates packages/js-evo-sdk/src/addresses/facade.ts, .../contracts/facade.ts, .../group/facade.ts, .../epoch/facade.ts, .../tokens/facade.ts, .../protocol/facade.ts	Replaced raw arrays with typed aliases (IdentifierLikeArray, PlatformAddressLikeArray, ProTxHashLikeArray); adjusted some proof return generic shapes; minor reformatting.
DPNS null→undefined packages/js-evo-sdk/src/dpns/facade.ts	Changed proof-returned optionals from null to undefined; minor formatting.
Voting formatting only packages/js-evo-sdk/src/voting/facade.ts	Signature reflow; no semantic changes.
Wallet optional param forwarding packages/js-evo-sdk/src/wallet/functions.ts	Stopped coalescing optionals to null; pass through undefined; multiline formatting.
WASM TS type alias normalization packages/wasm-dpp2/src/core/pro_tx_hash.rs, .../identifier.rs, .../platform_address/address.rs	Array aliases now use unified XLike element types; nullable bindings switched from null to undefined.
WASM SDK bindings: proof return types packages/wasm-sdk/src/dpns.rs, .../queries/identity.rs, .../queries/token.rs	Unchecked return types updated: null→undefined for optionals; token last-claim proof type adjusted; maps updated to use undefined values.
Tests and config packages/js-evo-sdk/tests/karma/options.cjs, .../tests/unit/facades/identities.spec.ts, packages/rs-platform-version/Cargo.toml	Removed ESLint disable; tests use testnet() instead of testnetTrusted(); removed once_cell dependency.

Sequence Diagram(s)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• fix(sdk): non proved JS SDK methods #2871 — Mirrors proof-enabled facade changes (epoch/protocol/tokens) and corresponding wasm_bindgen return-type updates.
• refactor(sdk)!: user-friendly evo sdk params #2856 — Coordinates JS SDK facade signature shifts to typed array aliases and null→undefined semantics across modules.

Suggested reviewers

• QuantumExplorer
• lklimek

Poem

I twitch my whiskers at types refined,
Arrays now march in aliases aligned.
Null hops out, undefined hops in—
Proofs return with cleaner grin.
I stamp a paw: “Docs can write!”
Then bound through tests by moonlit night.
— A happy rabbit 🐇✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 52.17% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change of refactoring the SDK to fix type inconsistencies across wasm-sdk and js-evo-sdk.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refactor/sdk-type-fixes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (10)

packages/wasm-sdk/src/dpns.rs (1)

458-507: ⚠️ Potential issue | 🟠 Major

Use undefined instead of null for proof optional data.

Both proof helper methods declare | undefined in their return type annotation but return JsValue::NULL on missing data. This violates the type contract—when data is absent, line 506 and line 577 should use JsValue::UNDEFINED.

Suggested fix

        } else {
-           JsValue::NULL
+           JsValue::UNDEFINED
        };

Apply to both locations (lines 506 and 577).

packages/wasm-sdk/src/queries/token.rs (1)

610-638: ⚠️ Potential issue | 🟠 Major

Fix NULL vs UNDEFINED mismatch in proof response type.

get_token_total_supply_with_proof_info declares unchecked_return_type = "ProofMetadataResponseTyped<TokenTotalSupply | undefined>" but returns JsValue::NULL instead of JsValue::UNDEFINED. This breaks the contract with TypeScript consumers, where null and undefined are semantically distinct types. Other similar functions in this file (get_token_contract_info_with_proof_info, get_token_perpetual_distribution_last_claim_with_proof_info) correctly use JsValue::UNDEFINED.

Suggested fix

-        let data = supply_result
-            .map(|supply| JsValue::from(TokenTotalSupplyWasm::new(supply.token_supply as u64)))
-            .unwrap_or(JsValue::NULL);
+        let data = supply_result
+            .map(|supply| JsValue::from(TokenTotalSupplyWasm::new(supply.token_supply as u64)))
+            .unwrap_or(JsValue::UNDEFINED);

packages/wasm-sdk/src/queries/identity.rs (8)

553-579: ⚠️ Potential issue | 🟠 Major

Same null vs undefined inconsistency.

Line 555 declares bigint | undefined but line 573 returns JsValue::NULL.

---

603-638: ⚠️ Potential issue | 🟠 Major

Same null vs undefined inconsistency.

Line 605 declares bigint | undefined but line 631 returns JsValue::NULL.

---

657-687: ⚠️ Potential issue | 🟠 Major

Same null vs undefined inconsistency.

Line 659 declares Map<Identifier, bigint | undefined> but line 681 returns JsValue::NULL for missing balances.

---

911-938: ⚠️ Potential issue | 🟠 Major

Same null vs undefined inconsistency.

Line 913 declares bigint | undefined but line 932 returns JsValue::NULL.

---

940-981: ⚠️ Potential issue | 🟠 Major

Same null vs undefined inconsistency.

Line 942 declares Map<Identifier, bigint | undefined> but line 971 returns JsValue::NULL.

---

983-1012: ⚠️ Potential issue | 🟠 Major

Same null vs undefined inconsistency.

Line 985 declares IdentityBalanceAndRevision | undefined but line 1006 returns JsValue::NULL.

---

1014-1045: ⚠️ Potential issue | 🟠 Major

Same null vs undefined inconsistency.

Line 1016 declares Identity | undefined but line 1039 returns JsValue::NULL.

---

325-348: ⚠️ Potential issue | 🟠 Major

Type mismatch: TypeScript declares undefined but Rust returns null.

The unchecked_return_type on line 327 declares Identity | undefined, but line 342 returns JsValue::NULL when the identity is None. In JavaScript, JsValue::NULL is the literal null value, not undefined. This creates a type-safety issue for TypeScript consumers checking result === undefined, which will be false when the value is null.

Change JsValue::NULL to JsValue::UNDEFINED to match the declared type:

Diff

         let data: JsValue = match identity {
             Some(identity) => IdentityWasm::from(identity).into(),
-            None => JsValue::NULL,
+            None => JsValue::UNDEFINED,
         };

This same pattern applies to other methods in this file where JsValue::NULL is used but the type declares | undefined.

🧹 Nitpick comments (3)

packages/js-evo-sdk/tests/unit/facades/identities.spec.ts (3)

35-36: Consider adding test coverage for getIdentitiesContractKeysWithProofInfoStub.

The ESLint suppression indicates this stub is declared but unused. There's a contractKeys() test but no corresponding contractKeysWithProof() test to exercise this stub.

Would you like me to generate a test case for contractKeysWithProof() to match the pattern of other *WithProof methods?

---

79-84: Inconsistent indentation in multi-line stub chain.

The object properties on lines 81-83 are indented at 6 spaces, but similar patterns elsewhere (e.g., lines 103-105) use 8 spaces for proper alignment under the .resolves({ call.

🔧 Suggested fix

     getIdentityContractNonceWithProofInfoStub = this.sinon
       .stub(wasmSdk, 'getIdentityContractNonceWithProofInfo').resolves({
-      data: BigInt(0),
-      proof: {},
-      metadata: {},
-    });
+        data: BigInt(0),
+        proof: {},
+        metadata: {},
+      });

---

130-135: Same indentation inconsistency as noted above.

Apply the same fix pattern here for consistency.

🔧 Suggested fix

     getIdentityTokenBalancesWithProofInfoStub = this.sinon
       .stub(wasmSdk, 'getIdentityTokenBalancesWithProofInfo').resolves({
-      data: new Map(),
-      proof: {},
-      metadata: {},
-    });
+        data: new Map(),
+        proof: {},
+        metadata: {},
+      });