diff --git a/predicates/predicates.md b/predicates/predicates.md index 01c88a4c74f..7226db725cb 100644 --- a/predicates/predicates.md +++ b/predicates/predicates.md @@ -163,18 +163,62 @@ chain_id/1 is a predicate which unifies the given term with the current chain ID The signature is as follows: ```text -chain_id(?chain_id/1) +chain_id(?ID) ``` where: -- chain_id/1 represents the current chain ID at the time of the query. +- ID represents the current chain ID at the time of the query. Examples: ```text # Query the current chain ID. -- chain_id(chain_id/1). +- chain_id(ID). +``` + +## crypto_data_hash/3 + +crypto_data_hash/3 is a predicate that computes the Hash of the given Data using different algorithms. + +The signature is as follows: + +```text +crypto_data_hash(+Data, -Hash, +Options) is det +crypto_data_hash(+Data, +Hash, +Options) is det +``` + +Where: + +- Data represents the data to be hashed, given as an atom, or code\-list. +- Hash represents the Hashed value of Data, which can be given as an atom or a variable. +- Options are additional configurations for the hashing process. Supported options include: encoding\(\+Format\) which specifies the encoding used for the Data, and algorithm\(\+Alg\) which chooses the hashing algorithm among the supported ones \(see below for details\). + +For Format, the supported encodings are: + +- utf8 \(default\), the UTF\-8 encoding represented as an atom. +- hex, the hexadecimal encoding represented as an atom. +- octet, the raw byte encoding depicted as a list of integers ranging from 0 to 255. + +For Alg, the supported algorithms are: + +- sha256 \(default\): The SHA\-256 algorithm. +- sha512: The SHA\-512 algorithm. +- md5: \(insecure\) The MD5 algorithm. + +Note: Due to the principles of the hash algorithm \(pre\-image resistance\), this predicate can only compute the hash value from input data, and cannot compute the original input data from the hash value. + +Examples: + +```text +# Compute the SHA-256 hash of the given data and unify it with the given Hash. +- crypto_data_hash('Hello OKP4', Hash). + +# Compute the SHA-256 hash of the given hexadecimal data and unify it with the given Hash. +- crypto_data_hash('9b038f8ef6918cbb56040dfda401b56b...', Hash, encoding(hex)). + +# Compute the SHA-256 hash of the given hexadecimal data and unify it with the given Hash. +- crypto_data_hash([127, ...], Hash, encoding(octet)). ``` ## did_components/2 @@ -384,31 +428,6 @@ String = 'Hello World' Length = 11 ``` -## sha_hash/2 - -sha_hash/2 is a predicate that computes the Hash of the given Data. - -The signature is as follows: - -```text -sha_hash(+Data, -Hash) is det -sha_hash(+Data, +Hash) is det -``` - -Where: - -- Data represents the data to be hashed with the SHA\-256 algorithm. -- Hash is the variable that will contain Hashed value of Data. - -Note: Due to the principles of the hash algorithm \(pre\-image resistance\), this predicate can only compute the hash value from input data, and cannot compute the original input data from the hash value. - -Examples: - -```text -# Compute the hash of the given data and unify it with the given Hash. -- sha_hash("Hello OKP4", Hash). -``` - ## source_file/1 source_file/1 is a predicate that unify the given term with the currently loaded source file.