From fef1ab1541ff3651a5b6cc10afe6353aad596773 Mon Sep 17 00:00:00 2001 From: Bot Anik <98603954+bot-anik@users.noreply.github.com> Date: Sat, 23 Nov 2024 18:24:06 +0000 Subject: [PATCH] feat(predicates): update axone-protocol/axoned predicates documentation --- predicates/asserta_1.md | 10 +- predicates/assertz_1.md | 10 +- predicates/block_header_1.md | 189 +++++++++++++++++++++++++++++++ predicates/block_height_1.md | 72 +----------- predicates/block_time_1.md | 73 +----------- predicates/chain_id_1.md | 9 +- predicates/consult_1.md | 2 +- predicates/crypto_data_hash_3.md | 2 +- predicates/current_output_1.md | 2 +- predicates/did_components_2.md | 2 +- predicates/ecdsa_verify_4.md | 2 +- predicates/eddsa_verify_4.md | 2 +- predicates/hex_bytes_2.md | 2 +- predicates/json_prolog_2.md | 2 +- predicates/json_read_2.md | 2 +- predicates/json_write_2.md | 2 +- predicates/open_3.md | 2 +- predicates/open_4.md | 2 +- predicates/read_string_3.md | 2 +- predicates/read_term_3.md | 2 +- predicates/retract_1.md | 2 +- predicates/source_file_1.md | 2 +- predicates/string_bytes_3.md | 2 +- predicates/term_to_atom_2.md | 2 +- predicates/uri_encoded_3.md | 2 +- predicates/write_term_3.md | 2 +- 26 files changed, 225 insertions(+), 178 deletions(-) create mode 100644 predicates/block_header_1.md diff --git a/predicates/asserta_1.md b/predicates/asserta_1.md index 5e171cf537..659faddc1a 100644 --- a/predicates/asserta_1.md +++ b/predicates/asserta_1.md @@ -54,9 +54,9 @@ answer: results: - substitutions: - variable: X - expression: "john" - - variable: Y - expression: "pete" + expression: john + - variable: 'Y' + expression: pete ``` ### Only dynamic predicates can be asserted @@ -127,10 +127,10 @@ answer: results: - substitutions: - variable: X - expression: "john" + expression: john - substitutions: - variable: X - expression: "jane" + expression: jane ``` ### Shows a simple counter example diff --git a/predicates/assertz_1.md b/predicates/assertz_1.md index 805f3b6121..a0e721bbc2 100644 --- a/predicates/assertz_1.md +++ b/predicates/assertz_1.md @@ -54,9 +54,9 @@ answer: results: - substitutions: - variable: X - expression: "john" - - variable: Y - expression: "pete" + expression: john + - variable: 'Y' + expression: pete ``` ### Only dynamic predicates can be asserted @@ -127,10 +127,10 @@ answer: results: - substitutions: - variable: X - expression: "jane" + expression: jane - substitutions: - variable: X - expression: "john" + expression: john ``` ### Add and remove items in an inventory diff --git a/predicates/block_header_1.md b/predicates/block_header_1.md new file mode 100644 index 0000000000..d2a32b92e1 --- /dev/null +++ b/predicates/block_header_1.md @@ -0,0 +1,189 @@ +--- +sidebar_position: 10 +--- +[//]: # (This file is auto-generated. Please do not modify it yourself.) + +# block_header/1 + +## Description + +`block_header/1` is a predicate which unifies the given term with the current block header. + +## Signature + +```text +block_header(?Header) is det +``` + +where: + +- Header is a Dict representing the current chain header at the time of the query. + +## Examples + +### Retrieve the header of the current block + +This scenario demonstrates how to retrieve the header of the current block and obtain some of its properties. + +The header of a block carries important information about the state of the blockchain, such as basic information (chain id, the height, +time, and height), the information about the last block, hashes, and the consensus info. + +The header is represented as a Prolog Dict, which is a collection of key-value pairs. + +Here are the steps of the scenario: + +- **Given** a block with the following header: + +``` yaml +app_hash: Q0P6b2hoSUbmpCE6o6Dme4H4FBWqdcpqo89DrpBYSHQ= +chain_id: axone-localnet +height: 33 +next_validators_hash: EIQFMnCDepfXD2e3OeL1QoEfmu6BZQbKR500Wkl4gK0= +proposer_address: yz7PSKMWniQlQWMd7LskBABgDKQ= +time: "2024-11-22T21:22:04.676789Z" +``` + +- **Given** the query: + +``` prolog +block_header(Header). +``` + +- **When** the query is run +- **Then** the answer we get is: + +``` yaml +height: 33 +gas_used: 3975 +answer: + has_more: false + variables: ["Header"] + results: + - substitutions: + - variable: Header + expression: >- + header{app_hash:[67,67,250,111,104,104,73,70,230,164,33,58,163,160,230,123,129,248,20,21,170,117,202,106,163,207,67,174,144,88,72,116],chain_id:'axone-localnet',consensus_hash:[],data_hash:[],evidence_hash:[],height:33,last_block_id:block_id{hash:[],part_set_header:part_set_header{hash:[],total:0}},last_commit_hash:[],last_results_hash:[],next_validators_hash:[16,132,5,50,112,131,122,151,215,15,103,183,57,226,245,66,129,31,154,238,129,101,6,202,71,157,52,90,73,120,128,173],proposer_address:[203,62,207,72,163,22,158,36,37,65,99,29,236,187,36,4,0,96,12,164],time:1732310524,validators_hash:[],version:consensus{app:0,block:0}} +``` + +### Retrieve the block height of the current block + +This scenario demonstrates how to retrieve the block height of the current block. + +Here are the steps of the scenario: + +- **Given** a block with the following header: + +``` yaml +height: 100 +``` + +- **Given** the program: + +``` prolog +height(Height) :- + block_header(Header), + Height = Header.height. +``` + +- **Given** the query: + +``` prolog +height(Height). +``` + +- **When** the query is run +- **Then** the answer we get is: + +``` yaml +height: 100 +gas_used: 3978 +answer: + has_more: false + variables: ["Height"] + results: + - substitutions: + - variable: Height + expression: "100" +``` + +### Retrieve the block time of the current block + +This scenario demonstrates how to retrieve the block time of the current block. + +Here are the steps of the scenario: + +- **Given** a block with the following header: + +``` yaml +time: 2024-03-04T11:03:36.000Z +``` + +- **Given** the program: + +``` prolog +time(Time) :- + block_header(Header), + Time = Header.time. +``` + +- **Given** the query: + +``` prolog +time(Time). +``` + +- **When** the query is run +- **Then** the answer we get is: + +``` yaml +height: 42 +gas_used: 3978 +answer: + has_more: false + variables: ["Time"] + results: + - substitutions: + - variable: Time + expression: "1709550216" +``` + +### Evaluate a condition based on block time and height + +This scenario demonstrates how to evaluate a condition that depends on both the block time and block height. +Specifically, it checks whether the block time is greater than 1709550216 seconds (Monday 4 March 2024 11:03:36 GMT) +or the block height is greater than 42. + +Here are the steps of the scenario: + +- **Given** a block with the following header: + +``` yaml +time: 2024-03-04T11:03:37.000Z +``` + +- **Given** the program: + +``` prolog +evaluate :- + block_header(Header), + (Header.time > 1709550216; Header.height > 42), + !. +``` + +- **Given** the query: + +``` prolog +evaluate. +``` + +- **When** the query is run +- **Then** the answer we get is: + +``` yaml +height: 42 +gas_used: 3981 +answer: + has_more: false + results: + - substitutions: +``` diff --git a/predicates/block_height_1.md b/predicates/block_height_1.md index 5b52afc1f8..7a48003492 100644 --- a/predicates/block_height_1.md +++ b/predicates/block_height_1.md @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 11 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) @@ -19,72 +19,4 @@ where: - Height represents the current chain height at the time of the query. -## Examples - -### Retrieve the block height of the current block - -This scenario demonstrates how to retrieve the block height of the current block. - -Here are the steps of the scenario: - -- **Given** a block with the following header: - -| key | value | -| --- | ----- | -| Height | 100 | - -- **Given** the query: - -``` prolog -block_height(Height). -``` - -- **When** the query is run -- **Then** the answer we get is: - -``` yaml -height: 100 -gas_used: 3975 -answer: - has_more: false - variables: ["Height"] - results: - - substitutions: - - variable: Height - expression: "100" -``` - -### Check that the block height is greater than a certain value - -This scenario demonstrates how to check that the block height is greater than 100. This predicate is useful for -governance which requires a certain block height to be reached before a certain action is taken. - -Here are the steps of the scenario: - -- **Given** a block with the following header: - -| key | value | -| --- | ----- | -| Height | 101 | - -- **Given** the query: - -``` prolog -block_height(Height), -Height > 100. -``` - -- **When** the query is run -- **Then** the answer we get is: - -``` yaml -height: 101 -gas_used: 3976 -answer: - has_more: false - variables: ["Height"] - results: - - substitutions: - - variable: Height - expression: "101" -``` +Deprecated: Use the \`block\_header/1\` predicate instead. diff --git a/predicates/block_time_1.md b/predicates/block_time_1.md index 2e17539af5..8b81831cb8 100644 --- a/predicates/block_time_1.md +++ b/predicates/block_time_1.md @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 12 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) @@ -19,73 +19,4 @@ where: - Time represents the current chain time at the time of the query. -## Examples - -### Retrieve the block time of the current block - -This scenario demonstrates how to retrieve the block time of the current block. - -Here are the steps of the scenario: - -- **Given** a block with the following header: - -| key | value | -| --- | ----- | -| Time | 1709550216 | - -- **Given** the query: - -``` prolog -block_time(Time). -``` - -- **When** the query is run -- **Then** the answer we get is: - -``` yaml -height: 42 -gas_used: 3975 -answer: - has_more: false - variables: ["Time"] - results: - - substitutions: - - variable: Time - expression: "1709550216" -``` - -### Check that the block time is greater than a certain time - -This scenario demonstrates how to check that the block time is greater than 1709550216 seconds (Monday 4 March 2024 11:03:36 GMT) -using the `block_time/1` predicate. This predicate is useful for governance which requires a certain block time to be -reached before a certain action is taken. - -Here are the steps of the scenario: - -- **Given** a block with the following header: - -| key | value | -| --- | ----- | -| Time | 1709550217 | - -- **Given** the query: - -``` prolog -block_time(Time), -Time > 1709550216. -``` - -- **When** the query is run -- **Then** the answer we get is: - -``` yaml -height: 42 -gas_used: 3976 -answer: - has_more: false - variables: ["Time"] - results: - - substitutions: - - variable: Time - expression: "1709550217" -``` +Deprecated: Use the \`block\_header/1\` predicate instead. diff --git a/predicates/chain_id_1.md b/predicates/chain_id_1.md index 9830755f87..46b66a056f 100644 --- a/predicates/chain_id_1.md +++ b/predicates/chain_id_1.md @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 13 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) @@ -19,9 +19,4 @@ where: - ID represents the current chain ID at the time of the query. -## Examples - -```text -# Query the current chain ID. -- chain_id(ID). -``` +Deprecated: Use the \`block\_header/1\` predicate instead. diff --git a/predicates/consult_1.md b/predicates/consult_1.md index 724734ad38..14f342c662 100644 --- a/predicates/consult_1.md +++ b/predicates/consult_1.md @@ -1,5 +1,5 @@ --- -sidebar_position: 13 +sidebar_position: 14 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/crypto_data_hash_3.md b/predicates/crypto_data_hash_3.md index d39bbfd4f1..645a3b814f 100644 --- a/predicates/crypto_data_hash_3.md +++ b/predicates/crypto_data_hash_3.md @@ -1,5 +1,5 @@ --- -sidebar_position: 14 +sidebar_position: 15 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/current_output_1.md b/predicates/current_output_1.md index c375ed7a37..b9d3a38c3c 100644 --- a/predicates/current_output_1.md +++ b/predicates/current_output_1.md @@ -1,5 +1,5 @@ --- -sidebar_position: 15 +sidebar_position: 16 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/did_components_2.md b/predicates/did_components_2.md index 6c8f26c694..8a572afa49 100644 --- a/predicates/did_components_2.md +++ b/predicates/did_components_2.md @@ -1,5 +1,5 @@ --- -sidebar_position: 16 +sidebar_position: 17 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/ecdsa_verify_4.md b/predicates/ecdsa_verify_4.md index b3317cd779..39bd627012 100644 --- a/predicates/ecdsa_verify_4.md +++ b/predicates/ecdsa_verify_4.md @@ -1,5 +1,5 @@ --- -sidebar_position: 17 +sidebar_position: 18 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/eddsa_verify_4.md b/predicates/eddsa_verify_4.md index 09b053f803..6c668201ef 100644 --- a/predicates/eddsa_verify_4.md +++ b/predicates/eddsa_verify_4.md @@ -1,5 +1,5 @@ --- -sidebar_position: 18 +sidebar_position: 19 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/hex_bytes_2.md b/predicates/hex_bytes_2.md index 56423e82dd..7762bf5a02 100644 --- a/predicates/hex_bytes_2.md +++ b/predicates/hex_bytes_2.md @@ -1,5 +1,5 @@ --- -sidebar_position: 19 +sidebar_position: 20 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/json_prolog_2.md b/predicates/json_prolog_2.md index edc3a7d79a..27b5d5f425 100644 --- a/predicates/json_prolog_2.md +++ b/predicates/json_prolog_2.md @@ -1,5 +1,5 @@ --- -sidebar_position: 20 +sidebar_position: 21 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/json_read_2.md b/predicates/json_read_2.md index 8041acf11e..3fdf10ee6e 100644 --- a/predicates/json_read_2.md +++ b/predicates/json_read_2.md @@ -1,5 +1,5 @@ --- -sidebar_position: 21 +sidebar_position: 22 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/json_write_2.md b/predicates/json_write_2.md index 5598e590b1..b893e0fca7 100644 --- a/predicates/json_write_2.md +++ b/predicates/json_write_2.md @@ -1,5 +1,5 @@ --- -sidebar_position: 22 +sidebar_position: 23 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/open_3.md b/predicates/open_3.md index f6676600a5..778a39b317 100644 --- a/predicates/open_3.md +++ b/predicates/open_3.md @@ -1,5 +1,5 @@ --- -sidebar_position: 24 +sidebar_position: 25 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/open_4.md b/predicates/open_4.md index c351b2eb3d..dbefa51a2b 100644 --- a/predicates/open_4.md +++ b/predicates/open_4.md @@ -1,5 +1,5 @@ --- -sidebar_position: 23 +sidebar_position: 24 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/read_string_3.md b/predicates/read_string_3.md index a0db183677..4499960fa5 100644 --- a/predicates/read_string_3.md +++ b/predicates/read_string_3.md @@ -1,5 +1,5 @@ --- -sidebar_position: 25 +sidebar_position: 26 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/read_term_3.md b/predicates/read_term_3.md index 43f969b2eb..ca53a8be91 100644 --- a/predicates/read_term_3.md +++ b/predicates/read_term_3.md @@ -1,5 +1,5 @@ --- -sidebar_position: 26 +sidebar_position: 27 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/retract_1.md b/predicates/retract_1.md index 1d776cc146..e78cf6b8a1 100644 --- a/predicates/retract_1.md +++ b/predicates/retract_1.md @@ -1,5 +1,5 @@ --- -sidebar_position: 27 +sidebar_position: 28 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/source_file_1.md b/predicates/source_file_1.md index 32e6cf8890..49460027fd 100644 --- a/predicates/source_file_1.md +++ b/predicates/source_file_1.md @@ -1,5 +1,5 @@ --- -sidebar_position: 28 +sidebar_position: 29 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/string_bytes_3.md b/predicates/string_bytes_3.md index cee492a19a..3370c60015 100644 --- a/predicates/string_bytes_3.md +++ b/predicates/string_bytes_3.md @@ -1,5 +1,5 @@ --- -sidebar_position: 29 +sidebar_position: 30 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/term_to_atom_2.md b/predicates/term_to_atom_2.md index a83a037f36..ca76db69ef 100644 --- a/predicates/term_to_atom_2.md +++ b/predicates/term_to_atom_2.md @@ -1,5 +1,5 @@ --- -sidebar_position: 30 +sidebar_position: 31 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/uri_encoded_3.md b/predicates/uri_encoded_3.md index 2d2798f103..4f82d9d6b8 100644 --- a/predicates/uri_encoded_3.md +++ b/predicates/uri_encoded_3.md @@ -1,5 +1,5 @@ --- -sidebar_position: 31 +sidebar_position: 32 --- [//]: # (This file is auto-generated. Please do not modify it yourself.) diff --git a/predicates/write_term_3.md b/predicates/write_term_3.md index 721cbb2505..dbfcc3a93a 100644 --- a/predicates/write_term_3.md +++ b/predicates/write_term_3.md @@ -1,5 +1,5 @@ --- -sidebar_position: 32 +sidebar_position: 33 --- [//]: # (This file is auto-generated. Please do not modify it yourself.)