rpc: enrich tx/prepare response with MSB preimage + fix mbs field (tests/docs)

Author: jusufsuljic

APP_DEV.md

@@ -181,7 +181,9 @@ curl -s -X POST http://127.0.0.1:5001/v1/contract/tx/prepare \
 
 The response contains:
 - `tx` (hex32): the exact 32-byte tx hash that must be signed
-- `command_hash` (hex32): hash of the prepared command (used by MSB payload)
+- `prepared_command` (object): echo of the typed command `{ type, value }` (what the wallet should display)
+- `command_hash` (hex32): hash of the canonical JSON of `prepared_command`
+- `msb` (object): the MSB tx preimage fields the `tx` commits to (`networkId`, `txv`, `iw`, `ch`, `bs`, `mbs`, `in`, `operationType`)
 
 ### Step D — Sign locally in the wallet
 
@@ -222,11 +224,18 @@ curl -s -X POST http://127.0.0.1:5001/v1/contract/tx \
 
 ### Step G — Read app state
 
-Apps typically write under `app/...`. Read via:
+Apps typically write under `app/...` (app-defined). Read via:
+
+```sh
+curl -s 'http://127.0.0.1:5001/v1/state?key=<urlencoded-hyperbee-key>&confirmed=false' | jq
+```
+
+Example (Tuxemon demo app):
 
 ```sh
 curl -s 'http://127.0.0.1:5001/v1/state?key=app%tuxedex%2F<wallet-pubkey-hex32>&confirmed=false' | jq
 ```
+```
 
 The `confirmed` flag controls whether you read from:
 - the latest local view (`confirmed=false`), or

rpc/services.js

@@ -17,10 +17,10 @@ const requireApi = (peer) => {
 };
 
 export async function getStatus(peer) {
-  const subnetBootstrapHex = b4a.isBuffer(peer.bootstrap)
-    ? b4a.toString(peer.bootstrap, "hex")
-    : peer.bootstrap != null
-      ? String(peer.bootstrap)
+  const subnetBootstrapHex = b4a.isBuffer(peer.config.bootstrap)
+    ? b4a.toString(peer.config.bootstrap, "hex")
+    : peer.config.bootstrap != null
+      ? String(peer.config.bootstrap)
       : null;
 
   const peerMsbAddress = peer.msbClient.pubKeyHexToAddress(peer.wallet.publicKey);
@@ -123,19 +123,67 @@ export async function contractGenerateNonce(peer) {
 export async function contractPrepareTx(peer, { prepared_command, address, nonce } = {}) {
   const api = requireApi(peer);
   if (!isObject(prepared_command)) throw new Error("prepared_command must be an object.");
+  if (typeof prepared_command.type !== "string" || prepared_command.type.length < 1) {
+    throw new Error("prepared_command.type must be a non-empty string.");
+  }
+  if (prepared_command.value === undefined) {
+    throw new Error("prepared_command.value is missing.");
+  }
   const addr = asHex32(address, "address");
   const n = asHex32(nonce, "nonce");
 
   if (peer?.protocol.instance?.safeJsonStringify == null) {
     throw new Error("safeJsonStringify is not available on protocol instance.");
   }
 
-  const json = peer.protocol.instance.safeJsonStringify(prepared_command);
-  if (json == null) throw new Error("Failed to stringify prepared_command.");
+  const prepared_json = peer.protocol.instance.safeJsonStringify(prepared_command);
+  if (prepared_json == null) throw new Error("Failed to stringify prepared_command.");
+
+  const command_hash = await createHash(prepared_json);
+
+  const networkId = peer.msbClient.networkId;
+  const msbBootstrap = peer.msbClient.bootstrapHex;
+  const txv = await peer.msbClient.getTxvHex();
+  const subnetBootstrap =
+    b4a.isBuffer(peer.config.bootstrap)
+      ? b4a.toString(peer.config.bootstrap, "hex")
+      : peer.config.bootstrap != null
+        ? String(peer.config.bootstrap)
+        : null;
+
+  const incomingWritingKey = peer.writerLocalKey ?? api.getPeerWriterKey?.();
+  if (!incomingWritingKey || !/^[0-9a-f]{64}$/i.test(String(incomingWritingKey))) {
+    throw new Error("Peer writer key is not available.");
+  }
+  if (!subnetBootstrap || !/^[0-9a-f]{64}$/i.test(String(subnetBootstrap))) {
+    throw new Error("Peer subnet bootstrap is not available.");
+  }
+
+  const tx = await peer.protocol.instance.generateTx(
+    networkId,
+    txv,
+    String(incomingWritingKey).toLowerCase(),
+    command_hash,
+    String(subnetBootstrap).toLowerCase(),
+    String(msbBootstrap).toLowerCase(),
+    n
+  );
 
-  const command_hash = await createHash(json);
-  const tx = await api.generateTx(addr, command_hash, n);
-  return { tx, command_hash };
+  return {
+    tx,
+    prepared_command,
+    command_hash,
+    msb: {
+      networkId,
+      txv,
+      iw: String(incomingWritingKey).toLowerCase(),
+      ch: command_hash,
+      bs: String(subnetBootstrap).toLowerCase(),
+      mbs: String(msbBootstrap).toLowerCase(),
+      in: n,
+      operationType: 12,
+    },
+  };
 }
 
 export async function contractTx(peer, { tx, prepared_command, address, signature, nonce, sim = false } = {}) {

tests/acceptance/rpc.test.js

@@ -288,6 +288,15 @@ test("rpc: wallet-signed tx simulate via prepare+sign+broadcast", async (t) => {
       });
       t.is(prep.status, 200);
       const tx = prep.json?.tx;
+      t.is(prep.json?.command_hash, prep.json?.msb?.ch);
+      t.is(prep.json?.msb?.in, nonce);
+      t.is(prep.json?.msb?.operationType, 12);
+      t.is(typeof prep.json?.msb?.networkId, "number");
+      t.is(typeof prep.json?.msb?.txv, "string");
+      t.is(typeof prep.json?.msb?.iw, "string");
+      t.is(typeof prep.json?.msb?.bs, "string");
+      t.is(typeof prep.json?.msb?.mbs, "string");
+      t.is(prep.json?.prepared_command?.type, prepared_command.type);
 
       const signature = externalWallet.sign(b4a.from(tx, "hex"));
       const simRes = await httpJson("POST", `${baseUrl}/v1/contract/tx`, {