docs(vrf): add SNIP-12 inline comments to outside execution signing

Document the type hashes, struct hash computation steps, and link to
the SNIP-12 specification. Note the account_sdk dependency conflict
that prevents reusing MessageHashRev1 directly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kariy

tests/vrf/src/main.rs

@@ -449,7 +449,18 @@ async fn whitelist_on_forwarder(
     println!("Whitelisted VRF account {address_to_whitelist} on forwarder");
 }
 
-/// Signs an OutsideExecutionV2 using SNIP-12 (same hash computation as the OZ SRC9 contract).
+/// Signs an OutsideExecutionV2 per SNIP-12 rev1 (off-chain typed structured data hashing).
+///
+/// Implements the same message hash as OpenZeppelin's SRC9Component, which the on-chain
+/// account uses to verify the signature. The hash is:
+///
+///   H("StarkNet Message", domain_hash, signer_address, outside_execution_hash)
+///
+/// where each component is a Poseidon hash following the SNIP-12 specification:
+/// <https://github.com/starknet-io/SNIPs/blob/main/SNIPS/snip-12.md>
+///
+/// NOTE: ideally we'd use `account_sdk::hash::MessageHashRev1` from controller-rs, but
+/// it currently pins an incompatible `starknet-types-core` version.
 async fn sign_outside_execution_v2(
     outside_execution: &OutsideExecutionV2,
     chain_id: Felt,
@@ -459,26 +470,34 @@ async fn sign_outside_execution_v2(
     use starknet::signers::Signer;
     use starknet_crypto::{poseidon_hash_many, PoseidonHasher};
 
+    // sn_keccak("\"StarknetDomain\"(\"name\":\"shortstring\",\"version\":\"shortstring\",
+    //            \"chainId\":\"shortstring\",\"revision\":\"shortstring\")")
     const STARKNET_DOMAIN_TYPE_HASH: Felt = Felt::from_hex_unchecked(
         "0x1ff2f602e42168014d405a94f75e8a93d640751d71d16311266e140d8b0a210",
     );
+    // sn_keccak("\"OutsideExecution\"(\"Caller\":\"ContractAddress\",\"Nonce\":\"felt\",
+    //            \"Execute After\":\"u128\",\"Execute Before\":\"u128\",\"Calls\":\"Call*\")
+    //            \"Call\"(\"To\":\"ContractAddress\",\"Selector\":\"selector\",
+    //            \"Calldata\":\"felt*\")")
     const OUTSIDE_EXECUTION_TYPE_HASH: Felt = Felt::from_hex_unchecked(
         "0x312b56c05a7965066ddbda31c016d8d05afc305071c0ca3cdc2192c3c2f1f0f",
     );
+    // sn_keccak("\"Call\"(\"To\":\"ContractAddress\",\"Selector\":\"selector\",
+    //            \"Calldata\":\"felt*\")")
     const CALL_TYPE_HASH: Felt = Felt::from_hex_unchecked(
         "0x3635c7f2a7ba93844c0d064e18e487f35ab90f7c39d00f186a781fc3f0c2ca9",
     );
 
-    // Domain hash
+    // 1. StarknetDomain struct hash: H(type_hash, name, version, chain_id, revision)
     let domain_hash = poseidon_hash_many(&[
         STARKNET_DOMAIN_TYPE_HASH,
         Felt::from_bytes_be_slice(b"Account.execute_from_outside"),
-        Felt::TWO,
+        Felt::TWO,  // version
         chain_id,
-        Felt::ONE,
+        Felt::ONE,  // revision
     ]);
 
-    // Hash each call
+    // 2. Call struct hashes: H(type_hash, to, selector, H(calldata))
     let mut hashed_calls = Vec::new();
     for call in &outside_execution.calls {
         let mut h = PoseidonHasher::new();
@@ -489,7 +508,7 @@ async fn sign_outside_execution_v2(
         hashed_calls.push(h.finalize());
     }
 
-    // Outside execution hash
+    // 3. OutsideExecution struct hash: H(type_hash, caller, nonce, after, before, H(calls))
     let mut h = PoseidonHasher::new();
     h.update(OUTSIDE_EXECUTION_TYPE_HASH);
     h.update(outside_execution.caller.into());
@@ -499,7 +518,7 @@ async fn sign_outside_execution_v2(
     h.update(poseidon_hash_many(&hashed_calls));
     let outside_execution_hash = h.finalize();
 
-    // Final message hash
+    // 4. Final SNIP-12 message hash: H("StarkNet Message", domain, signer, message)
     let mut h = PoseidonHasher::new();
     h.update(Felt::from_bytes_be_slice(b"StarkNet Message"));
     h.update(domain_hash);