feat(sdk)!: state transition broadcast result for Evo SDK

[shumkov]

Issue being fixed or feature implemented

waitForResponse and broadcastAndWait returned untyped unknown in TypeScript. SDK consumers had no way to work with proof results in a type-safe way. Also, waitForStateTransitionResult was misplaced on SystemFacade.

What was done?

Typed WASM proof result wrappers

• Added packages/wasm-sdk/src/state_transitions/proof_result.rs — 21 typed #[wasm_bindgen] structs (one per StateTransitionProofResult variant) with typed getters, toObject/fromObject/toJSON/fromJSON, and __struct discriminator
• TypeScript discriminated union StateTransitionProofResultType for all variants
• waitForResponse and broadcastAndWait now return StateTransitionProofResultTypeJs
• u64 balances exposed as BigInt

JS Evo SDK

• New StateTransitionsFacade (packages/js-evo-sdk/src/state-transitions/facade.ts) with broadcastStateTransition, waitForResponse, broadcastAndWait, waitForStateTransitionResult
• Moved waitForStateTransitionResult from SystemFacade → StateTransitionsFacade

How Has This Been Tested?

• packages/wasm-sdk/tests/unit/proof-result.spec.ts — exports, __struct discriminator, conversion methods, and round-trip serialization for all 21 variant types
• packages/js-evo-sdk/tests/unit/facades/state-transitions.spec.ts — all 4 facade methods correctly delegate to WASM SDK with and without settings
• Updated packages/js-evo-sdk/tests/unit/facades/system.spec.ts — removed moved method

Breaking Changes

• sdk.system.waitForStateTransitionResult() → sdk.stateTransitions.waitForStateTransitionResult()
• waitForResponse() / broadcastAndWait() return typed StateTransitionProofResultType instead of unknown

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 a state transitions surface on the SDK with broadcast, wait-for-response, and broadcast-and-wait operations.
  • Introduced strongly typed proof-result bindings for richer result objects.

• Improvements

  • Enabled JSON/JS (de)serialization for many WASM-exposed types to improve interoperability.
  • Streamlined proof-result conversion to return typed results.

• Breaking Changes

  • Removed the waitForStateTransitionResult method from the system facade.

• Tests

  • Added comprehensive tests covering state transitions and proof-result serialization round-trips.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new StateTransitionsFacade to the JS SDK (moved waitForStateTransitionResult out of SystemFacade), introduces typed WASM bindings for StateTransitionProofResult with conversion helpers, updates impl_wasm_conversions macro to target concrete types, and enables serde (de)serialization on many wasm-dpp2 wrapper types; includes new tests and some test removals.

Changes

Cohort / File(s)	Summary
StateTransitions Facade packages/js-evo-sdk/src/sdk.ts, packages/js-evo-sdk/src/state-transitions/facade.ts, packages/js-evo-sdk/tests/unit/facades/state-transitions.spec.ts	Adds StateTransitionsFacade; integrates it into EvoSDK as stateTransitions; implements four async methods that delegate to the connected WASM SDK; adds unit tests verifying forwarding and settings handling.
SystemFacade Cleanup packages/js-evo-sdk/src/system/facade.ts, packages/js-evo-sdk/tests/unit/facades/system.spec.ts	Removes waitForStateTransitionResult from SystemFacade and deletes its tests/stubs from system facade unit tests.
WASM Proof Result Bindings packages/wasm-dpp2/src/state_transitions/mod.rs, packages/wasm-dpp2/src/state_transitions/proof_result.rs, packages/wasm-dpp2/src/lib.rs	Adds a new proof_result module with many wasm-exported wrapper structs for each StateTransitionProofResult variant, conversion helpers, convert_proof_result, and re-exports the proof-result types.
WASM SDK: broadcast/result changes packages/wasm-sdk/src/state_transitions/broadcast.rs	Replaces loose object return type with strongly-typed StateTransitionProofResultTypeJs; updates wait_for_response and broadcast_and_wait signatures to return the typed result and uses convert_proof_result.
Serialization macro packages/wasm-dpp2/src/serialization/conversions.rs	Changes impl_wasm_conversions macro to operate on concrete types ($ty) instead of wrapper types ($wrapper), updating generated toObject/fromObject/toJSON/fromJSON implementations accordingly.
Serde derives (many files) packages/wasm-dpp2/src/... (identity, data_contract, epoch, group, tokens, voting, asset_lock_proof, block, state_transitions/transitions, etc.)	Adds serde::Serialize, serde::Deserialize and #[serde(transparent)] to ~25+ wasm wrapper structs across the repo to enable transparent (de)serialization without runtime control-flow changes.
Tests: ProofResult suite packages/wasm-dpp2/tests/unit/ProofResult.spec.ts	Adds comprehensive serialization/deserialization round-trip tests for many proof-result wrapper types, Maps, optional fields, and nested structures.
Test removals / docs packages/wasm-sdk/tests/unit/api-availability.spec.ts, .claude/skills/pr-description/SKILL.md	Removes an API-availability unit test file; adds a PR-description skill doc in .claude/skills.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Client
participant EvoSDK
participant WasmSdk
Client->>EvoSDK: call stateTransitions.broadcastAndWait(stateTransition, settings?)
EvoSDK->>EvoSDK: stateTransitions.facade.broadcastAndWait(...)
EvoSDK->>WasmSdk: getWasmSdkConnected()
WasmSdk-->>EvoSDK: connected wasm sdk instance
EvoSDK->>WasmSdk: wasmSdk.broadcast_and_wait(stateTransition, settings)
WasmSdk-->>EvoSDK: StateTransitionProofResult (Rust enum)
EvoSDK->>WasmSdk: convert_proof_result(result)
WasmSdk-->>EvoSDK: StateTransitionProofResultTypeJs
EvoSDK-->>Client: Promise resolves with StateTransitionProofResultTypeJs

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐇 I hopped through facades, proofs, and code,

State hops now travel a clearer road.
Wrappers learn to speak JSON bright,
Proofs converted, typed just right.
The SDK nudges on—what a delightful sight! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding state transition broadcast result support to the Evo SDK, using conventional commit format with breaking change indicator.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/sdk/state-transition-proof-result

---

No actionable comments were generated in the recent review. 🎉

---

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: 1

🤖 Fix all issues with AI agents

In @.claude/skills/pr-description/SKILL.md:
- Line 78: Update the wording in the instruction string that currently says
"```markdown" (the language tag in the triple-backtick example) to use the
proper noun "Markdown" (capitalized) so the output guidance reads "```Markdown";
locate the exact phrase in the SKILL.md text that begins "Output the entire PR
description (title + body) as a single raw markdown code block" and change the
lowercase "markdown" to "Markdown" in that sentence and in the triple-backtick
language tag example to keep both occurrences consistent.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@packages/wasm-dpp2/src/identity/transitions/credit_withdrawal_transition.rs`:
- Around line 99-102: The wrapper struct IdentityCreditWithdrawalTransitionWasm
is missing the Clone derive which other wrappers have and which callers (e.g.,
impl_wasm_conversions!) expect; add Clone to the derive attributes for
IdentityCreditWithdrawalTransitionWasm so it becomes #[derive(Clone,
serde::Serialize, serde::Deserialize)] (keep the existing #[wasm_bindgen(...)]
and #[serde(transparent)] attributes intact).

In `@packages/wasm-dpp2/tests/unit/ProofResult.spec.ts`:
- Around line 1-3: Rename the test file from ProofResult.spec.ts to kebab-case
proof-result.spec.ts and update any references/imports to that filename in the
test suite or build/test configs; locate the file by the imports shown (expect,
initWasm, wasm, identifier) and ensure test runner entries and any relative
import paths are updated so tests continue to import the same symbols from the
new filename.

🧹 Nitpick comments (3)

packages/wasm-dpp2/src/state_transitions/proof_result.rs (2)

690-698: doc_to_wasm uses placeholder metadata — verify consumers handle this.

Identifier::default() (all-zeros) and an empty string for document_type_name means consumers inspecting the contract ID or type name on documents returned by proof results will get meaningless values. The comment explains the trade-off, but if JS consumers use contractId or documentTypeName on these DocumentWasm instances, they'll silently get wrong data instead of an error.

Consider whether the metadata should be made optional or if a sentinel value/warning should be added to the TS type.

---

119-121: Reflect::get error messages are slightly misleading.

js_sys::Reflect::get returns Err when the target itself is null/undefined (not when the property is absent — that returns Ok(undefined)). The error messages like "Missing property: dataContract" suggest a missing property, but this error path only triggers when the input value is not an object at all. The actual missing-property case would surface as a downstream deserialization error.

This is a very minor cosmetic issue and consistent across the file — not blocking.

Also applies to: 134-136, 271-273, 344-346, 531-533, 585-587, 598-600, 654-656, 668-670

packages/wasm-dpp2/tests/unit/ProofResult.spec.ts (1)

7-9: Top-level before hook is outside describe block.

The before hook on line 7 is at the file/module level, not within a describe block. While Mocha allows this (it becomes a root-level hook), placing it inside the describe('StateTransitionProofResult types', ...) block would scope it more clearly and is a more conventional pattern.