Merge pull request #298 from okp4/docs/predicate

Docs/predicate

x/logic/predicate/block.go

@@ -13,6 +13,11 @@ import (
 //	block_height(?Height)
 //
 // where Height represents the current chain height at the time of the query.
+//
+// Example:
+//
+//	# Query the current block height.
+//	- block_height(Height).
 func BlockHeight(vm *engine.VM, height engine.Term, cont engine.Cont, env *engine.Env) *engine.Promise {
 	return engine.Delay(func(ctx context.Context) *engine.Promise {
 		sdkContext, err := util.UnwrapSDKContext(ctx)
@@ -29,6 +34,11 @@ func BlockHeight(vm *engine.VM, height engine.Term, cont engine.Cont, env *engin
 //	block_time(?Time)
 //
 // where Time represents the current chain time at the time of the query.
+//
+// Example:
+//
+//	# Query the current block time.
+//	- block_time(Time).
 func BlockTime(vm *engine.VM, time engine.Term, cont engine.Cont, env *engine.Env) *engine.Promise {
 	return engine.Delay(func(ctx context.Context) *engine.Promise {
 		sdkContext, err := util.UnwrapSDKContext(ctx)

x/logic/predicate/chain.go

@@ -13,6 +13,11 @@ import (
 //	chain_id(?ChainID)
 //
 // where ChainID represents the current chain ID at the time of the query.
+//
+// Example:
+//
+//	# Query the current chain ID.
+//	- chain_id(ChainID).
 func ChainID(vm *engine.VM, chainID engine.Term, cont engine.Cont, env *engine.Env) *engine.Promise {
 	return engine.Delay(func(ctx context.Context) *engine.Promise {
 		sdkContext, err := util.UnwrapSDKContext(ctx)

x/logic/predicate/crypto.go

@@ -10,6 +10,22 @@ import (
 	"github.com/tendermint/tendermint/crypto"
 )
 
+// SHAHash is a predicate that computes the Hash of the given Data. The signature is as follow:
+//
+//	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.
+//
+// Example:
+//
+//	# Compute the hash of the given data and unify it with the given Hash.
+//	- sha_hash("Hello OKP4", Hash).
 func SHAHash(vm *engine.VM, data, hash engine.Term, cont engine.Cont, env *engine.Env) *engine.Promise {
 	return engine.Delay(func(ctx context.Context) *engine.Promise {
 		var result []byte
@@ -23,6 +39,18 @@ func SHAHash(vm *engine.VM, data, hash engine.Term, cont engine.Cont, env *engin
 	})
 }
 
+// HexBytes is a predicate that unifies hexadecimal encoded bytes to a list of bytes. The signature is as follow:
+//
+// hex_bytes(?Hex, ?Bytes) is det
+//
+// Where:
+// - Hex is an Atom, string or list of characters in hexadecimal encoding.
+// - Bytes is the list of numbers between 0 and 255 that represent the sequence of bytes.
+//
+// Example:
+//
+// # Convert hexadecimal atom to list of bytes.
+// - hex_bytes('2c26b46b68ffc68ff99b453c1d3041341342d706483bfa0f98a5e886266e7ae', Bytes).
 func HexBytes(vm *engine.VM, hexa, bts engine.Term, cont engine.Cont, env *engine.Env) *engine.Promise {
 	return engine.Delay(func(ctx context.Context) *engine.Promise {
 		var result []byte