feat(sdk): expose transitionHash from state transition broadcast functions

[thepastaclaw]

Summary

State transition functions (in both Rust SDK and WASM SDK) compute transaction hashes internally but never expose them to callers. This makes it impossible to reference or link state transitions to each other — a fundamental composability primitive.

Use Case

In Yappr (decentralized blog on Platform), tipping works by:

1. Broadcasting a credit transfer state transition (the actual tip)
2. Creating a document (tip receipt) that references both the credit transfer transition hash AND the post being replied to

Without the transition hash being returned from step 1, there is no way to create a verifiable link between "this document" and "that payment." Anyone should be able to take the transitionHash from the tip document, fetch the actual state transition, and confirm the credits were sent.

This pattern applies broadly: receipts, escrow references, audit trails, any cross-transition linkage.

Proposed Approach

Per review feedback on platform#2953, this should be implemented in the Rust SDK first, with the WASM SDK inheriting it as a thin wrapper:

1. Rust SDK: Modify broadcast/broadcast_and_wait return types to include the transaction hash (hex-encoded SHA256 transaction ID)
2. WASM SDK: Surface the Rust SDK return values through the JS bindings

Prior Art

• platform#2953 implemented this directly in WASM SDK for all 22 state transition functions
• Reviewer feedback (shumkov): should go through Rust SDK first, WASM SDK should stay thin
• Pushed to 3.1 milestone by QuantumExplorer for further discussion

Scope

All state transition categories need this:

• Identity (5 functions): create, topUp, creditTransfer, creditWithdrawal, update
• Tokens (10 functions): mint, burn, transfer, freeze, unfreeze, destroyFrozen, etc.
• Contracts (2 functions): create, update
• Documents (6 functions): create, replace, delete, transfer, purchase, setPrice

Related: platform#2953 (being closed, concept preserved here)

[shumkov]

You could create a state transition and then use broadcast method. In this case you have transition hash

[thepastaclaw]

Good point — you're right. The two-step approach already works:

// 1. Create + broadcast (returns StateTransition)
let st = document.put_to_platform(sdk, doc_type, entropy, key, payment, signer, settings).await?;

// 2. Get the hash
let tx_hash = st.transaction_id()?;

// 3. Wait for confirmation separately
let result = Document::wait_for_response(sdk, st, settings).await?;

The transaction_id() is available on StateTransition before waiting. The convenience methods (put_to_platform_and_wait_for_response, transfer_credits, etc.) hide it, but splitting into two steps gives you everything you need.

Should we close this, or is there still interest in having the convenience methods return a tuple/struct that includes the hash for DX?

[PastaPastaPasta]

@thephez do you have thoughts on dev-x here?

It seems to me, having to manually build the st is poor dev-x

[thephez]

@thephez do you have thoughts on dev-x here?

It seems to me, having to manually build the st is poor dev-x

I don't understand why we wouldn't return the hash. Someone shouldn't have to jump through hoops just to find out the hash of their state transition imo. Why hide that?

[thephez]

For the benefit of anyone that ends up here, a partial example of a way to get hash:

import { Document, DocumentCreateTransition, BatchTransition, BatchedTransition, PrivateKey } from '@dashevo/evo-sdk';

...

  // Create a new document
  const document = new Document({
    properties: {
      message: `Tutorial Test @ ${new Date().toUTCString()}`,
    },
    documentTypeName: 'note',
    dataContractId: 'FW3DHrQiG24VqzPY4ARenMgjEPpBNuEQTZckV8hbVCG4',
    ownerId: identity.id,
  });

  // --- Low-level flow to get the state transition hash ---

  const w = await sdk.getWasmSdkConnected();

  // 1. Fetch the identity-contract nonce
  const nonce = await w.getIdentityContractNonce(identity.id, DATA_CONTRACT_ID);
  const nextNonce = (nonce ?? 0n) + 1n;

  // 2. Create the document create transition
  const createTransition = new DocumentCreateTransition({
    document,
    identityContractNonce: nextNonce,
  });

  // 3. Convert: DocumentCreateTransition → DocumentTransition → BatchedTransition
  const docTransition = createTransition.toDocumentTransition();
  const batchedTransition = new BatchedTransition(docTransition);

  // 4. Wrap in a BatchTransition
  const batch = BatchTransition.fromBatchedTransitions(
    [batchedTransition],
    identity.id,
    0,  // userFeeIncrease
  );

  // 5. Convert to StateTransition and sign
  const stateTransition = batch.toStateTransition();
  const privateKey = PrivateKey.fromWIF(keyManager.keys.auth.privateKeyWif);
  stateTransition.sign(privateKey, identityKey);

  // 6. Get the hash!
  const transitionHash = stateTransition.hash(false);
  console.log('State Transition Hash:', transitionHash);

  // 7. Broadcast, then wait for the result using the hash
  await sdk.stateTransitions.broadcastStateTransition(stateTransition);
  const result = await sdk.stateTransitions.waitForStateTransitionResult(transitionHash);
  console.log('Result:', result.toJSON());