Add more comments to the Hash type

soroban-sdk/src/crypto.rs

@@ -5,12 +5,18 @@ use crate::{
     TryFromVal, Val,
 };
 
-/// A Bytes generated by a cryptographic hash function.
-///
-/// This struct is designed to be used in contexts where a hash value generated
-/// by a secure cryptographic function is required.  It can only be constructed
-/// via secure manners, i.e. output from a secure hash function, or received
-/// from the Soroban Env (e.g. via [`CustomAccountInterface`][crate::auth::CustomAccountInterface])
+/// A Bytes generated by a cryptographic hash function. This struct is designed
+/// to be used in contexts where a hash value generated by a secure
+/// cryptographic function is required.  
+/// 
+/// **__Note:_** this struct is used as a special annotation of `Bytes` in
+/// certain internally-defined interfaces: output of hash functions, input hash
+/// to ECDSA, `__check_auth`. In these scenarios, it is guaranteed the enclosed
+/// bytes is the output of a secure hash function. It cannot be used as a
+/// contract type (either stored as user data, or as an argument or return type
+/// of a contract function). If your contract interface requires to work with a
+/// hash, you need to use `Bytes`/`BytesN` and make sure it comes from a secure
+/// hash function.
 pub struct Hash<const N: usize>(BytesN<N>);
 
 impl<const N: usize> Hash<N> {