From 6c11738ce2ec4d6d08fa3a10972df210e9df4a75 Mon Sep 17 00:00:00 2001 From: Jay Geng Date: Mon, 22 Apr 2024 14:32:04 -0400 Subject: [PATCH] Add more comments to the `Hash` type --- soroban-sdk/src/crypto.rs | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/soroban-sdk/src/crypto.rs b/soroban-sdk/src/crypto.rs index fe5b2f0e..5b1b7d3f 100644 --- a/soroban-sdk/src/crypto.rs +++ b/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(BytesN); impl Hash {