feat(rs-sdk): expose transition hash from state transition methods#3092
feat(rs-sdk): expose transition hash from state transition methods#3092thepastaclaw wants to merge 4 commits intodashpay:v3.1-devfrom
Conversation
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughA new Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
packages/rs-sdk/src/platform/transition/state_transition_result.rs (1)
11-15: Consider derivingPartialEqandEqfor testability.Adding
PartialEqandEq(bounded onT: PartialEq/T: Eq) would make it straightforward to assert equality in tests without having to decompose into parts.Suggested change
-#[derive(Debug, Clone)] +#[derive(Debug, Clone, PartialEq, Eq)]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/rs-sdk/src/platform/transition/state_transition_result.rs` around lines 11 - 15, The StateTransitionResult struct should derive PartialEq and Eq for easier testing: add PartialEq and Eq to the derive list on StateTransitionResult and constrain implementations so these derives require T: PartialEq (and T: Eq for Eq). Update the derive macro on the struct (StateTransitionResult) to include PartialEq and Eq so tests can directly compare instances without manual decomposition.packages/rs-sdk/src/platform/documents/transitions/create.rs (1)
174-179: Consider propagating the transition hash through the result enums.All document transition methods (create, delete, replace, purchase, set_price) currently discard the transition hash via
into_inner(). To fully surface the hash to SDK consumers — which is the goal of this PR — these per-operation result enums (e.g.,DocumentCreateResult) could carry the[u8; 32]alongside the payload, or the methods could returnStateTransitionResult<DocumentCreateResult>directly. This can be a follow-up.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/rs-sdk/src/platform/documents/transitions/create.rs` around lines 174 - 179, The DocumentCreateResult enum currently drops the transition hash (via into_inner()), so update the API to propagate the transition hash: either add a hash field to the enum (e.g., change DocumentCreateResult::Document(Document) to carry (Document, [u8; 32]) or similar) and adjust all callers that construct/consume DocumentCreateResult, or instead change the create method(s) to return StateTransitionResult<DocumentCreateResult> directly so the hash is preserved; apply the same pattern for the other per-operation enums/methods (delete, replace, purchase, set_price) and ensure functions that call into_inner() are updated to handle the preserved hash accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/rs-sdk/src/platform/tokens/transitions/unfreeze.rs`:
- Around line 69-70: The broadcast call hardcodes None for settings causing
caller-provided settings to be ignored; change the unfreeze transition to
extract settings from the builder (use
unfreeze_tokens_transition_builder.settings or the builder’s with_settings()
value) and pass that into
state_transition.broadcast_and_wait::<StateTransitionProofResult>(self,
put_settings) instead of None; apply the same fix pattern used in
destroy_frozen_funds (and replicate for mint.rs, freeze.rs,
set_price_for_direct_purchase.rs) so user_fee_increase and retry configuration
are honored.
---
Nitpick comments:
In `@packages/rs-sdk/src/platform/documents/transitions/create.rs`:
- Around line 174-179: The DocumentCreateResult enum currently drops the
transition hash (via into_inner()), so update the API to propagate the
transition hash: either add a hash field to the enum (e.g., change
DocumentCreateResult::Document(Document) to carry (Document, [u8; 32]) or
similar) and adjust all callers that construct/consume DocumentCreateResult, or
instead change the create method(s) to return
StateTransitionResult<DocumentCreateResult> directly so the hash is preserved;
apply the same pattern for the other per-operation enums/methods (delete,
replace, purchase, set_price) and ensure functions that call into_inner() are
updated to handle the preserved hash accordingly.
In `@packages/rs-sdk/src/platform/transition/state_transition_result.rs`:
- Around line 11-15: The StateTransitionResult struct should derive PartialEq
and Eq for easier testing: add PartialEq and Eq to the derive list on
StateTransitionResult and constrain implementations so these derives require T:
PartialEq (and T: Eq for Eq). Update the derive macro on the struct
(StateTransitionResult) to include PartialEq and Eq so tests can directly
compare instances without manual decomposition.
|
Addressed the CodeRabbit review in 22fc89c: Fixed:
Deferred:
|
There was a problem hiding this comment.
🧹 Nitpick comments (1)
packages/rs-sdk/src/platform/transition/state_transition_result.rs (1)
27-29: Nit: consider returning&[u8; 32]fromtransition_hash().Currently returns by value (copy). Since
[u8; 32]isCopythis is fine and arguably simpler, but returning a reference would be more conventional for accessor methods on fixed-size data and avoids a 32-byte copy on non-optimized builds. Totally optional.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/rs-sdk/src/platform/transition/state_transition_result.rs` around lines 27 - 29, The accessor transition_hash() currently returns [u8; 32] by value which copies the array; change its signature to return a reference -> &[u8; 32] and return &self.transition_hash to avoid the copy (update the method in the impl for the relevant struct). After changing the signature, update any call sites that rely on ownership (e.g., places that expect a copied array should explicitly clone/copy if needed) and run tests to ensure no API breakages.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@packages/rs-sdk/src/platform/transition/state_transition_result.rs`:
- Around line 27-29: The accessor transition_hash() currently returns [u8; 32]
by value which copies the array; change its signature to return a reference ->
&[u8; 32] and return &self.transition_hash to avoid the copy (update the method
in the impl for the relevant struct). After changing the signature, update any
call sites that rely on ownership (e.g., places that expect a copied array
should explicitly clone/copy if needed) and run tests to ensure no API
breakages.
shumkov
left a comment
shumkov
left a comment
There was a problem hiding this comment.
It doesn't make sense to me. You have already state transition around so you can store hash into varibable and reuse it. @PastaPastaPasta please review your friend's PRs first.
|
Thanks for the review @shumkov. You make a fair point — if the caller already has the state transition, they can compute the hash themselves via The motivation was convenience for the WASM SDK layer (where thephez reported needing the txid from Happy to close this if the consensus is that it's unnecessary overhead. @PastaPastaPasta thoughts? |
|
Shumkov and claw most times you use the SDK you don't actually have the transition? It gets built internally I think. I see no reason to not return txid. |
|
@shumkov — I want to respectfully push back on this. You're right that inside the SDK, the state transition exists as a local variable. But that's exactly the point — it's local to the SDK internals. The caller never sees it. Look at pub async fn document_create(...) -> Result<DocumentCreateResult, Error> {
let state_transition = builder.sign(...).await?; // built internally
let proof_result = state_transition.broadcast_and_wait(self, settings).await?;
match proof_result { ... } // consumed internally — only proof result returned
}The So "you already have the state transition around" is true for someone modifying the SDK, but false for SDK consumers (WASM SDK, js-evo-sdk, application code). Without this PR (or similar), there's no way for WASM SDK callers to get the transaction ID after a The As Pasta noted: "most times you use the SDK you don't actually have the transition. It gets built internally." This PR fixes that gap. |
|
Good catch — the Re: T including transition hash: That's a good idea. The challenge is that |
|
Re: @PastaPastaPasta's inline comments: On On including transition hash in |
thepastaclaw
force-pushed
the
feat/sdk-transition-hash
branch
from
22fc89c to
3b57def
Compare
|
Done — split into its own PR: #3132 Removed the put_settings changes from this PR. Re: T including transition hash: Looked into this. |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/rs-sdk/src/platform/transition/transfer_to_addresses.rs (1)
23-27:⚠️ Potential issue | 🟡 MinorStale duplicate bullet in the
Returnsdoc-comment.The return type is a 2-tuple
(AddressInfos, Credits)but the doc lists three bullets, repeating "Proof-backed address infos for provided recipients" as both the first and third items.📝 Proposed fix
- /// Returns tuple of: - /// * Proof-backed address infos for provided recipients - /// * Updated identity balance - /// * Proof-backed address infos for provided recipients + /// Returns tuple of: + /// * Proof-backed address infos for provided recipients + /// * Updated identity balance after the transfer🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/rs-sdk/src/platform/transition/transfer_to_addresses.rs` around lines 23 - 27, The Returns doc-comment in transfer_to_addresses.rs currently lists three bullets and repeats "Proof-backed address infos for provided recipients" although the function returns a 2-tuple (AddressInfos, Credits); update the doc-comment for the function (e.g., the transfer_to_addresses function) to list exactly two return bullets matching the actual return types: 1) Proof-backed address infos for provided recipients (AddressInfos) and 2) Updated identity balance (Credits), removing the duplicated third bullet and keeping wording consistent with the return type names.
🧹 Nitpick comments (1)
packages/rs-sdk/src/platform/transition/top_up_identity_from_addresses.rs (1)
84-116: Transition hash is silently discarded — high-level helpers won't propagate it to WASM/JS callers.All five high-level SDK methods updated in this PR (
top_up_from_addresses_with_nonce,token_freeze,document_transfer,transfer_credits_to_addresses,put_with_address_funding) call.into_inner()immediately and throw away the 32-byte transition hash. The hash is only observable from callers who invokebroadcast_and_waitdirectly — but the PR's stated motivation is specifically that "WASM SDK, js-evo-sdk, application code do not have access to the internal StateTransition". Callers using these high-level SDK methods, including the WASM SDK thin layer built on top of them, will still receive no hash.Consider either:
- Returning
(ReturnType, [u8; 32])from each high-level method, or- Defining a higher-level counterpart of
StateTransitionResult<T>that wraps the domain-specific result types (FreezeResult,DocumentTransferResult, etc.)If propagation is intentionally deferred, tracking the gap in a follow-up issue would help ensure it's not forgotten.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/rs-sdk/src/platform/transition/top_up_identity_from_addresses.rs` around lines 84 - 116, The code discards the 32-byte transition hash by calling .into_inner() on broadcast_and_wait results; update top_up_from_addresses_with_nonce (and the other high-level methods) to capture the transition hash before into_inner() and propagate it to callers—either by returning a tuple like (address_infos, balance, transition_hash) from the handler that matches StateTransitionProofResult::VerifiedIdentityWithAddressInfos (use the existing collect_address_infos_from_proof and identity.balance logic) or by introducing a small wrapper type (e.g., StateTransitionResult<T> containing result and [u8;32]) and returning that instead so the transition hash from broadcast_and_wait is not lost.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@packages/rs-sdk/src/platform/transition/transfer_to_addresses.rs`:
- Around line 23-27: The Returns doc-comment in transfer_to_addresses.rs
currently lists three bullets and repeats "Proof-backed address infos for
provided recipients" although the function returns a 2-tuple (AddressInfos,
Credits); update the doc-comment for the function (e.g., the
transfer_to_addresses function) to list exactly two return bullets matching the
actual return types: 1) Proof-backed address infos for provided recipients
(AddressInfos) and 2) Updated identity balance (Credits), removing the
duplicated third bullet and keeping wording consistent with the return type
names.
---
Nitpick comments:
In `@packages/rs-sdk/src/platform/transition/top_up_identity_from_addresses.rs`:
- Around line 84-116: The code discards the 32-byte transition hash by calling
.into_inner() on broadcast_and_wait results; update
top_up_from_addresses_with_nonce (and the other high-level methods) to capture
the transition hash before into_inner() and propagate it to callers—either by
returning a tuple like (address_infos, balance, transition_hash) from the
handler that matches
StateTransitionProofResult::VerifiedIdentityWithAddressInfos (use the existing
collect_address_infos_from_proof and identity.balance logic) or by introducing a
small wrapper type (e.g., StateTransitionResult<T> containing result and
[u8;32]) and returning that instead so the transition hash from
broadcast_and_wait is not lost.
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/wasm-sdk/src/state_transitions/broadcast.rs (1)
94-100:⚠️ Potential issue | 🟠 Major
transition_hashis silently discarded — consider surfacing it to JS callers.
.into_inner()correctly satisfies theconvert_proof_resulttype, but it throws away thetransition_hashthatStateTransitionResult<T>carries. The PR discussion explicitly identifies WASM SDK consumers (js-evo-sdk, browser apps) as the primary beneficiaries of having the transaction hash, yet those callers receive no way to observe it frombroadcastAndWait.A minimal approach would be to return a small two-field JS object that contains both the proof result and the hex-encoded hash, e.g.:
💡 Sketch of a hash-exposing return value
+use wasm_bindgen::JsValue; +use js_sys::Object; pub async fn broadcast_and_wait( &self, #[wasm_bindgen(js_name = "stateTransition")] state_transition: &StateTransitionWasm, settings: Option<PutSettingsJs>, -) -> Result<StateTransitionProofResultTypeJs, WasmSdkError> { +) -> Result<JsValue, WasmSdkError> { let st: StateTransition = state_transition.into(); let put_settings = parse_put_settings(settings)?; let result = st .broadcast_and_wait::<StateTransitionProofResult>(self.as_ref(), put_settings) .await .map_err(|e| WasmSdkError::generic(format!("Failed to broadcast: {}", e)))?; + let (inner, hash) = result.into_parts(); + let proof = convert_proof_result(inner).map_err(WasmSdkError::from)?; + let hash_hex = hex::encode(hash); + let obj = Object::new(); + js_sys::Reflect::set(&obj, &"result".into(), &proof.into())?; + js_sys::Reflect::set(&obj, &"transitionHash".into(), &hash_hex.into())?; + Ok(obj.into()) - convert_proof_result(result.into_inner()).map_err(WasmSdkError::from) }Alternatively, exposing a
broadcastAndWaitWithHashsibling method would avoid a breaking change tobroadcastAndWait's return type for existing callers.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/wasm-sdk/src/state_transitions/broadcast.rs` around lines 94 - 100, The code currently discards the transition_hash by calling result.into_inner() before convert_proof_result; update the broadcast path (the method invoking st.broadcast_and_wait::<StateTransitionProofResult> — the wasm-facing broadcastAndWait wrapper) to extract both the inner proof result and the transition_hash from the returned StateTransitionResult<T> (do not call into_inner() alone), then return both to JS either by changing the return to a small two-field object { proofResult, transitionHashHex } or by adding a sibling method broadcastAndWaitWithHash that returns that object; ensure you hex-encode the transition_hash, keep existing error handling (WasmSdkError) and still call convert_proof_result on the proof payload before packaging the result.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@packages/wasm-sdk/src/state_transitions/broadcast.rs`:
- Around line 94-100: The code currently discards the transition_hash by calling
result.into_inner() before convert_proof_result; update the broadcast path (the
method invoking st.broadcast_and_wait::<StateTransitionProofResult> — the
wasm-facing broadcastAndWait wrapper) to extract both the inner proof result and
the transition_hash from the returned StateTransitionResult<T> (do not call
into_inner() alone), then return both to JS either by changing the return to a
small two-field object { proofResult, transitionHashHex } or by adding a sibling
method broadcastAndWaitWithHash that returns that object; ensure you hex-encode
the transition_hash, keep existing error handling (WasmSdkError) and still call
convert_proof_result on the proof payload before packaging the result.
9aba70e to
07b2e5c
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
packages/rs-sdk/src/platform/transition.rs (1)
19-19: Optional:state_transition_resultmodule declaration is out of alphabetical order.It is placed after
transfer_to_addresses(line 18) rather than betweenput_settingsandtop_up_address, breaking the existing alphabetical grouping. Consider moving it to maintain consistency.♻️ Suggested placement
pub mod put_settings; +pub mod state_transition_result; pub mod top_up_address; ... -pub mod state_transition_result; // remove from line 19🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/rs-sdk/src/platform/transition.rs` at line 19, The module declaration for state_transition_result is out of alphabetical order relative to the other pub mod lines; move the pub mod state_transition_result; declaration so it appears between pub mod put_settings; and pub mod top_up_address; (i.e., place state_transition_result between those two) to restore the alphabetical grouping and consistent ordering with transfer_to_addresses, put_settings, and top_up_address.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/rs-sdk/src/platform/transition/state_transition_result.rs`:
- Line 11: Add PartialEq and Eq to the derive list for the StateTransitionResult
struct so tests can use assert_eq!; update the existing #[derive(Debug, Clone)]
line to #[derive(Debug, Clone, PartialEq, Eq)] (i.e., extend the derive on the
struct defined in state_transition_result.rs) and run cargo test to verify
equality-based assertions now work.
---
Nitpick comments:
In `@packages/rs-sdk/src/platform/transition.rs`:
- Line 19: The module declaration for state_transition_result is out of
alphabetical order relative to the other pub mod lines; move the pub mod
state_transition_result; declaration so it appears between pub mod put_settings;
and pub mod top_up_address; (i.e., place state_transition_result between those
two) to restore the alphabetical grouping and consistent ordering with
transfer_to_addresses, put_settings, and top_up_address.
4e49bd2 to
b2f3b42
Compare
…3092) The into_inner() calls on broadcast results require the StateTransitionResult type from PR dashpay#3092. Since this PR targets v3.1-dev which doesn't have dashpay#3092 merged yet, these calls break compilation. Reverting until dashpay#3092 lands.
|
Addressing the review comments:
|
thepastaclaw
force-pushed
the
feat/sdk-transition-hash
branch
from
8d45834 to
261c79f
Compare
thepastaclaw
force-pushed
the
feat/sdk-transition-hash
branch
from
261c79f to
28721d3
Compare
Add StateTransitionResult<T> wrapper type that bundles the proof result with the transition hash (transaction ID). The hash is computed deterministically from the serialized StateTransition BEFORE broadcast, avoiding any race condition with blockchain state. broadcast_and_wait now returns StateTransitionResult<T> instead of T. The wrapper implements Deref<Target=T> for ergonomic access and provides into_inner() for callers that only need the result. All existing callers updated to use .into_inner() to maintain current behavior. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…esult - Move state_transition_result module to alphabetical position in transition.rs - Update wasm-sdk broadcast.rs to unwrap StateTransitionResult with into_inner()
wait_for_response returns T directly, not StateTransitionResult<T>, so into_inner() is not needed there.
thepastaclaw
force-pushed
the
feat/sdk-transition-hash
branch
from
28721d3 to
cb08e5e
Compare
thepastaclaw
left a comment
thepastaclaw
left a comment
There was a problem hiding this comment.
Code Review
Well-structured PR that cleanly introduces StateTransitionResult to bundle the transition hash with broadcast results. The core implementation is correct — the hash is computed deterministically before broadcast, the wrapper is simple, and all 28 RS-SDK callers are properly updated. The WASM SDK intentionally unwraps the hash for now (acknowledged in the PR as follow-up work). Two design-level suggestions around type safety and test coverage are worth addressing.
Reviewed commit: cb08e5e
🟡 3 suggestion(s) | 💬 2 nitpick(s)
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.
In `packages/wasm-sdk/src/state_transitions/broadcast.rs`:
- [SUGGESTION] line 99: WASM broadcastAndWait discards the transition hash before crossing the FFI boundary
The WASM SDK's public `broadcastAndWait` calls `result.into_inner()` at line 99, permanently discarding the transition hash before converting to `StateTransitionProofResultTypeJs`. JavaScript consumers have no way to access the transition hash through this path. The same pattern exists in `contract.rs:228-230` and `identity.rs:691-694`, where `broadcast_and_wait` is called and the entire `StateTransitionResult` is dropped.
If this is intentionally deferred to the #2953 follow-up, consider adding a brief `// TODO(#2953): propagate transition_hash to JS` comment so the gap is tracked alongside the code.
In `packages/rs-sdk/src/platform/transition/state_transition_result.rs`:
- [SUGGESTION] lines 1-56: No unit tests for StateTransitionResult<T>
The new type has 6 public methods (`new`, `transition_hash`, `into_parts`, `into_inner`, `map`) plus a `Deref` impl, but no `#[cfg(test)]` module. While the type is simple, unit tests would lock the contract — especially that `into_parts()` returns both components, that `map` preserves the hash, and that `Deref` provides transparent access to the inner value. This also guards against future refactors silently breaking the hash-carrying invariant.
- [SUGGESTION] line 14: Use the existing TxId newtype instead of raw [u8; 32] for transition_hash
The `transition_hash` field uses `[u8; 32]`, but a `TxId` newtype wrapping `[u8; 32]` already exists in `transition/txid.rs` and is re-exported from the same module (`pub use txid::TxId`). Using `TxId` would provide domain-level type safety, preventing accidental use of an arbitrary 32-byte array as a transition hash, and would give callers access to future `TxId` methods (like `is_confirmed`) without a conversion step.
|
Re-checked this draft on current head A couple of stale review threads are now cleaned up:
The remaining open items on this draft look like suggestions/nits rather than blockers (tests for @shumkov — your old changes-request still seems to be the only thing keeping |
|
Pushed
I left the |
|
✅ Review complete (commit ffa5609) |
thepastaclaw
force-pushed
the
feat/sdk-transition-hash
branch
from
7088dae to
ffa5609
Compare
thepastaclaw
left a comment
thepastaclaw
left a comment
There was a problem hiding this comment.
Code Review
PR adds a StateTransitionResult<T> wrapper to BroadcastStateTransition::broadcast_and_wait so callers can recover the transition hash. Implementation at HEAD ffa5609 is sound and contained — no consensus-critical or security concerns. Validated findings are scope/quality nits: stale book signature, missing wiring test, Deref anti-pattern, and gaps where the new type isn't yet threaded through higher-level helpers (with TODO(#2953) tracking the WASM follow-up).
Reviewed commit: ffa5609
Fresh rerun of the review pipeline for this dispatcher item. An earlier same-SHA automated review already exists, so I am posting this current run as a top-level review to avoid duplicating inline threads while still recording the fresh verification.
🟡 5 suggestion(s) | 💬 2 nitpick(s)
🟡 suggestion: Book documents stale `broadcast_and_wait` signature
book/src/sdk/put-operations.md:186-190
Verified at lines 186-190: the trait excerpt still shows Result<T, Error>, but broadcast.rs:268 now returns Result<StateTransitionResult<T>, Error>. Since the book is the canonical reference for BroadcastStateTransition, leaving the old signature will mislead consumers who upgrade and try to match on T directly. Update the snippet and add a short note pointing readers at into_inner() / transition_hash() so the breaking change called out in the PR description is reflected in the docs.
💡 Suggested change
async fn broadcast_and_wait<T: TryFrom<StateTransitionProofResult> + Send>(
&self,
sdk: &Sdk,
settings: Option<PutSettings>,
) -> Result<StateTransitionResult<T>, Error>;
🟡 suggestion: No test verifies `broadcast_and_wait` returns the correct transition hash
packages/rs-sdk/src/platform/transition/broadcast.rs:264-285
Verified at state_transition_result.rs:58-103: the unit tests only cover the inert wrapper (new, into_parts, into_inner, map, Deref). The actual contract this PR introduces — that broadcast_and_wait returns transition_hash() == StateTransition::transaction_id() of the broadcast transition — is not exercised. Downstream consumers (WASM SDK, evo-sdk) will key on this hash to reconcile against wait_for_state_transition_result_request (broadcast_request.rs:81 uses the same transaction_id()), so a regression here would be silent. Add a mock-mode integration test asserting result.transition_hash() == state_transition.transaction_id()? so future refactors of transaction_id() cannot diverge unnoticed. The PR checklist also leaves the unit/integration tests box unchecked.
🟡 suggestion: `Deref` on a non-smart-pointer wrapper is a Rust API anti-pattern
packages/rs-sdk/src/platform/transition/state_transition_result.rs:50-56
Rust API Guidelines (C-DEREF) recommend Deref only for smart pointers. StateTransitionResult<T> is a value bundle, not a pointer-like wrapper. Two practical hazards: (1) any future method on T that collides with transition_hash, into_inner, into_parts, or map will silently shadow without a compiler error; (2) callers can keep using the inner result transparently and never get nudged toward the hash, partially defeating the point of the wrapper. An explicit .result() / .inner() accessor or AsRef<T> impl would surface the same ergonomics without the foot-guns.
🟡 suggestion: Higher-level `put_*_and_wait_for_response` helpers still discard the transition hash
packages/rs-sdk/src/platform/transition/put_identity.rs:88-107
Verified across put_identity.rs:88-107, put_contract.rs:81-93, put_document.rs, top_up_identity.rs, transfer.rs: these helpers do not call broadcast_and_wait — they call put_to_platform followed by Waitable::wait_for_response, returning bare domain values (Identity, DataContract, etc.). So the new StateTransitionResult<T> is stranded at the lowest layer and Rust callers of the ergonomic API still cannot retrieve the transaction ID without manually serializing the transition again. This is the natural follow-up to thread the hash through; doing it now would close the loop on the rs-sdk side rather than leaving a partial migration. Codex's two reports labelled this blocking; downgraded here because the PR scope is clearly the BroadcastStateTransition trait and the wrapper is non-breaking via into_inner()/Deref.
🟡 suggestion: WASM `broadcastAndWait` still drops the transition hash before crossing into JS
packages/wasm-sdk/src/state_transitions/broadcast.rs:94-102
Verified: the WASM binding immediately calls result.into_inner() and only converts the inner StateTransitionProofResult, so JavaScript callers cannot read the txid the new wrapper just plumbed through. There is, however, an explicit // TODO(#2953) on line 99 acknowledging this is deferred to a follow-up. Codex flagged this as blocking in two reports; downgraded to suggestion because the deferral is intentional and tracked. Worth confirming that #2953 is filed and linked in the PR description before merge so the follow-up is not lost.
💬 nitpick: `broadcast_and_wait` now serializes the transition an extra time to compute the hash
packages/rs-sdk/src/platform/transition/broadcast.rs:264-285
StateTransition::transaction_id() (rs-dpp state_transition/mod.rs:749) calls PlatformSerializable::serialize_to_bytes(self) and SHA-256s the result. With the new line 274, the same serialization runs in addition to the one inside broadcast_request_for_state_transition() and the trace/timeout paths in wait_for_response (line 250) and wait_for_state_transition_result_request (broadcast_request.rs:81). For BatchTransitions with many document operations the body is non-trivial and ends up being serialized 3-4 times per submission. Caching the hash once in broadcast_and_wait and threading it (or the bytes) into the inner calls would amortize the cost. Not blocking — the SDK is not a hot path — but the new wrapper makes the redundancy more visible.
💬 nitpick: Eager `transaction_id()?` changes failure ordering of `broadcast_and_wait`
packages/rs-sdk/src/platform/transition/broadcast.rs:274
Placing let transition_hash = self.transaction_id()?; before self.broadcast(...) means a serialization error now preempts broadcast and surfaces a ProtocolError-shaped error before any nonce/retry path runs. In practice transaction_id() cannot fail for a transition the caller could have broadcast anyway (broadcast itself serializes), so this is mostly observable in error message ordering and timing. If the eager check is intentional (so a broken transition fails fast without occupying the broadcast pipeline), a one-line comment would prevent future refactors from quietly moving it.
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review. Verify each finding against the current code and only fix it if needed.
In `book/src/sdk/put-operations.md`:
- [SUGGESTION] lines 186-190: Book documents stale `broadcast_and_wait` signature
Verified at lines 186-190: the trait excerpt still shows `Result<T, Error>`, but `broadcast.rs:268` now returns `Result<StateTransitionResult<T>, Error>`. Since the book is the canonical reference for `BroadcastStateTransition`, leaving the old signature will mislead consumers who upgrade and try to match on `T` directly. Update the snippet and add a short note pointing readers at `into_inner()` / `transition_hash()` so the breaking change called out in the PR description is reflected in the docs.
In `packages/rs-sdk/src/platform/transition/broadcast.rs`:
- [SUGGESTION] lines 264-285: No test verifies `broadcast_and_wait` returns the correct transition hash
Verified at `state_transition_result.rs:58-103`: the unit tests only cover the inert wrapper (`new`, `into_parts`, `into_inner`, `map`, `Deref`). The actual contract this PR introduces — that `broadcast_and_wait` returns `transition_hash() == StateTransition::transaction_id()` of the broadcast transition — is not exercised. Downstream consumers (WASM SDK, evo-sdk) will key on this hash to reconcile against `wait_for_state_transition_result_request` (`broadcast_request.rs:81` uses the same `transaction_id()`), so a regression here would be silent. Add a mock-mode integration test asserting `result.transition_hash() == state_transition.transaction_id()?` so future refactors of `transaction_id()` cannot diverge unnoticed. The PR checklist also leaves the unit/integration tests box unchecked.
In `packages/rs-sdk/src/platform/transition/state_transition_result.rs`:
- [SUGGESTION] lines 50-56: `Deref<Target = T>` on a non-smart-pointer wrapper is a Rust API anti-pattern
Rust API Guidelines (C-DEREF) recommend `Deref` only for smart pointers. `StateTransitionResult<T>` is a value bundle, not a pointer-like wrapper. Two practical hazards: (1) any future method on `T` that collides with `transition_hash`, `into_inner`, `into_parts`, or `map` will silently shadow without a compiler error; (2) callers can keep using the inner result transparently and never get nudged toward the hash, partially defeating the point of the wrapper. An explicit `.result()` / `.inner()` accessor or `AsRef<T>` impl would surface the same ergonomics without the foot-guns.
In `packages/rs-sdk/src/platform/transition/put_identity.rs`:
- [SUGGESTION] lines 88-107: Higher-level `put_*_and_wait_for_response` helpers still discard the transition hash
Verified across `put_identity.rs:88-107`, `put_contract.rs:81-93`, `put_document.rs`, `top_up_identity.rs`, `transfer.rs`: these helpers do not call `broadcast_and_wait` — they call `put_to_platform` followed by `Waitable::wait_for_response`, returning bare domain values (`Identity`, `DataContract`, etc.). So the new `StateTransitionResult<T>` is stranded at the lowest layer and Rust callers of the ergonomic API still cannot retrieve the transaction ID without manually serializing the transition again. This is the natural follow-up to thread the hash through; doing it now would close the loop on the rs-sdk side rather than leaving a partial migration. Codex's two reports labelled this `blocking`; downgraded here because the PR scope is clearly the `BroadcastStateTransition` trait and the wrapper is non-breaking via `into_inner()`/`Deref`.
In `packages/wasm-sdk/src/state_transitions/broadcast.rs`:
- [SUGGESTION] lines 94-102: WASM `broadcastAndWait` still drops the transition hash before crossing into JS
Verified: the WASM binding immediately calls `result.into_inner()` and only converts the inner `StateTransitionProofResult`, so JavaScript callers cannot read the txid the new wrapper just plumbed through. There is, however, an explicit `// TODO(#2953)` on line 99 acknowledging this is deferred to a follow-up. Codex flagged this as `blocking` in two reports; downgraded to suggestion because the deferral is intentional and tracked. Worth confirming that #2953 is filed and linked in the PR description before merge so the follow-up is not lost.
3 participants
Issue being fixed or feature implemented
State transition methods in the Rust SDK (
broadcast_and_wait,put_to_platform_and_wait_for_response, etc.) discard the transition hash (transaction ID) after broadcast. Downstream consumers (WASM SDK, evo-sdk) cannot access it without re-computing or restructuring their calls.This is the Rust SDK foundation for the work started in #2953, restructured per review feedback to implement the logic in the Rust SDK first (rather than only in the WASM SDK).
What was done?
Added
StateTransitionResult<T>— a thin wrapper that bundles a proof resultTwith the 32-byte transition hash (transaction ID).Core changes:
StateTransitionResult<T>inpackages/rs-sdk/src/platform/transition/state_transition_result.rstransition_hash() -> [u8; 32]— get the hashinto_parts() -> (T, [u8; 32])— destructureinto_inner() -> T— unwrap (backward compat)Deref<Target=T>— transparent access to inner resultBroadcastStateTransition::broadcast_and_waitreturnsStateTransitionResult<T>instead ofTRace condition avoidance
The transition hash is computed deterministically from the
StateTransitionstruct before broadcast viaStateTransition::transaction_id()(SHA-256 of serialized transition). It does not depend on blockchain state — no race condition possible. This addresses the concern raised in #2953.Files modified (30 files)
broadcast.rs— core trait changestate_transition_result.rs— new wrapper typeHow Has This Been Tested?
cargo check -p dash-sdkpassesinto_inner()orDerefworks unchangedValidation
Build verification
cargo check -p dash-sdk— confirms the newStateTransitionResult<T>type and all 28 updated method signatures compile correctlycargo check -p wasm-sdk— confirms the WASM SDK consumer compiles against the updatedbroadcast_and_waitreturn type (usesinto_inner()to unwrap)Type-level correctness
broadcast_and_waitreturnsStateTransitionResult<T>instead ofT, and the wrapper implementsDeref<Target=T>, so all existing call sites that accessTmethods continue to work without modificationStateTransitionResult<T>throughput_to_platform_and_wait_for_response→ callers that need onlyTuse.into_inner()wasm-sdkbroadcast layer correctly unwraps via.into_inner()forbroadcast_and_waitwhile leavingwait_for_response(which already returnsTdirectly) unchangedBackward compatibility
into_inner()provides a zero-cost migration path for callers that don't need the transition hashDerefimpl means existing code that calls methods on the result works transparently without changesManual review
StateTransitionResultand surfaces it through the return typetransaction_id()is called before broadcast (no race condition with blockchain state)Breaking Changes
broadcast_and_waitnow returnsStateTransitionResult<T>instead ofT. Callers that need justTcan use.into_inner()or rely onDeref.Checklist: