Skip to content

Commit c0066ee

Browse files
ccamelccamel
committed
docs(gov): document RecordDecision execution and decision queries
1 parent b3e900b commit c0066ee

File tree

1 file changed

+104
-13
lines changed

1 file changed

+104
-13
lines changed

‎docs/axone-gov.md‎

Lines changed: 104 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -102,15 +102,35 @@ Where:
102102

103103
Execute messages.
104104

105+
### ExecuteMsg::record_decision
106+
107+
Record a decision on-chain by deciding a case using the stored constitution.
108+
109+
The `case` parameter is a Prolog dict term string (typically `ctx{...}`) representing the decision context provided by the caller.
110+
111+
Before evaluation, the contract enriches the case with contract-derived facts:
112+
113+
`prolog ctx{ 'gov:module': module{ id: <atom>, version: <atom> }, 'gov:cosmwasm': cosmwasm{ message: message{ sender: <atom>, % Bech32 address of message sender funds: [coin(Amount, Denom), ...] % List of coins sent with message }, block: block{ height: <integer>, % Block height time: <integer>, % Block timestamp (seconds since epoch) tx_index: <integer> % Transaction index (optional) } }, <caller_provided_keys>: <caller_provided_values> } `
114+
115+
Injected keys are authoritative and overwrite any caller-provided value under the same keys.
116+
117+
The contract evaluates `governance:decide/2` or `governance:decide/3` depending on `motivated`, and records the resulting verdict (and optional motivation) as a durable decision record.
118+
119+
| parameter | description |
120+
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
121+
| `record_decision` | _(Required.) _ **object**. |
122+
| `record_decision.case` | _(Required.) _ **string**. The decision context. |
123+
| `record_decision.motivated` | **boolean\|null**. Whether to request a motivated decision (defaults to `false`).<br /><br />- If `false`, the contract calls `governance:decide/2` and records only the verdict. - If `true`, the contract calls `governance:decide/3` and records both verdict and motivation. |
124+
105125
### ExecuteMsg::revise_constitution
106126

107127
Propose a constitutional revision (constitutional amendment).
108128

109129
The contract asks the **current** constitution to decide whether the revision is allowed by evaluating a case that includes the intent `gov:revise_constitution`.
110130

111-
The contract builds the decision case by merging the caller-provided `case` (if any) with contract-enriched context. The complete case structure is:
131+
The complete case structure is (keys containing `:` are quoted atoms):
112132

113-
`prolog ctx{ intent: 'gov:revise_constitution', 'gov:proposed_constitution_hash': &lt;hex_string&gt;, % SHA256 of constitution bytes (authoritative) 'gov:module': module{ id: &lt;atom&gt;, % Contract module ID (e.g., 'axone:axone-gov') version: &lt;atom&gt; % Contract version (e.g., '1.2.3') }, 'gov:cosmwasm': cosmwasm{ message: message{ sender: &lt;atom&gt;, % Bech32 address of message sender funds: [coin(Amount, Denom), ...] % List of coins sent with message }, block: block{ height: &lt;integer&gt;, % Block height time: &lt;integer&gt;, % Block timestamp (seconds since epoch) tx_index: &lt;integer&gt; % Transaction index } }, &lt;caller_provided_keys&gt;: &lt;caller_provided_values&gt; % Any additional keys from caller's case } `
133+
`prolog ctx{ intent: 'gov:revise_constitution', 'gov:proposed_constitution_hash': &lt;atom&gt;, % Hex string atom (authoritative SHA256 of payload) 'gov:module': module{ id: &lt;atom&gt;, % Contract module ID (e.g., 'axone:axone-gov') version: &lt;atom&gt; % Contract version (e.g., '1.2.3') }, 'gov:cosmwasm': cosmwasm{ message: message{ sender: &lt;atom&gt;, % Bech32 address of message sender funds: [coin(Amount, Denom), ...] % List of coins sent with message }, block: block{ height: &lt;integer&gt;, % Block height time: &lt;integer&gt;, % Block timestamp (seconds since epoch) tx_index: &lt;integer&gt; % Transaction index } }, &lt;caller_provided_keys&gt;: &lt;caller_provided_values&gt; % Any additional keys from caller's case } `
114134

115135
The revision is applied only if the decision verdict is exactly the atom `gov:permitted`. Any other verdict (atom or compound term) refuses the revision.
116136

@@ -150,19 +170,44 @@ Example:
150170

151171
`ctx{intent:read, user:"did:example:123", object:"obj:42"}`
152172

153-
- If `motivated` is `false`, the contract calls `decide/2` and returns only the verdict. - If `motivated` is `true`, the contract calls `decide/3` and returns both verdict and motivation.
154-
155173
The returned `verdict` is an arbitrary Prolog term (atom or compound), for example:
156174

157175
- `gov:permitted` - `gov:forbidden` - `pay("did:...", 1000)`
158176

159177
The optional `motivation` is an arbitrary Prolog term returned by the constitution and intended to justify the verdict (e.g. grounds/articles, findings, interpretation rules).
160178

161-
| parameter | description |
162-
| ------------------ | --------------------------- |
163-
| `decide` | _(Required.) _ **object**. |
164-
| `decide.case` | _(Required.) _ **string**. |
165-
| `decide.motivated` | _(Required.) _ **boolean**. |
179+
Before evaluation, the contract enriches the case with module metadata (`'gov:module'`).
180+
181+
Injected keys are authoritative and overwrite any caller-provided value under the same keys.
182+
183+
| parameter | description |
184+
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
185+
| `decide` | _(Required.) _ **object**. |
186+
| `decide.case` | _(Required.) _ **string**. The decision context. |
187+
| `decide.motivated` | **boolean\|null**. Whether to request a motivated decision (defaults to `false`).<br /><br />- If `false`, the contract calls `governance:decide/2` and returns only the verdict. - If `true`, the contract calls `governance:decide/3` and returns both verdict and motivation. |
188+
189+
### QueryMsg::decision
190+
191+
Return a recorded decision by its unique identifier.
192+
193+
The returned record is created by `ExecuteMsg::RecordDecision` and includes the decision payload (case/verdict, optional motivation) along with constitution metadata (revision/hash) and block metadata.
194+
195+
| parameter | description |
196+
| ---------------------- | ----------------------------------------------------------- |
197+
| `decision` | _(Required.) _ **object**. |
198+
| `decision.decision_id` | _(Required.) _ **integer**. The unique decision identifier. |
199+
200+
### QueryMsg::decisions
201+
202+
Return a paginated list of recorded decisions.
203+
204+
Decisions are ordered by their unique identifier in ascending order.
205+
206+
| parameter | description |
207+
| ----------------------- | -------------------------------------------------------------------------------- |
208+
| `decisions` | _(Required.) _ **object**. |
209+
| `decisions.limit` | **integer\|null**. Optional maximum number of decisions to return (default: 10). |
210+
| `decisions.start_after` | **integer\|null**. Optional decision ID to start after (exclusive). |
166211

167212
## MigrateMsg
168213

@@ -185,9 +230,9 @@ Reserved for future migrations.
185230

186231
Response returned by `QueryMsg::Constitution`.
187232

188-
| property | description |
189-
| ------------ | ----------------------------------------------------------------------------------------- |
190-
| `governance` | _(Required.) _ **[Binary](#binary)**. The stored constitution (raw Prolog program bytes). |
233+
| property | description |
234+
| -------------- | ----------------------------------------------------------------------------------------- |
235+
| `constitution` | _(Required.) _ **[Binary](#binary)**. The stored constitution (raw Prolog program bytes). |
191236

192237
### constitution_status
193238

@@ -207,6 +252,33 @@ Response returned by `QueryMsg::Decide`.
207252
| `motivation` | **string\|null**. Optional motivation term returned as the third argument of `decide/3`. |
208253
| `verdict` | _(Required.) _ **string**. The verdict returned by the constitution as a Prolog term string. |
209254

255+
### decision
256+
257+
Response returned by `QueryMsg::Decision`.
258+
259+
| property | description |
260+
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
261+
| `author` | _(Required.) _ **string**. The author Bech32 address. |
262+
| `block_height` | _(Required.) _ **integer**. The block height at which the decision was recorded. |
263+
| `block_time_seconds` | _(Required.) _ **integer**. The block time (seconds since epoch) at which the decision was recorded. |
264+
| `case` | _(Required.) _ **string**. The case term as a Prolog term string. |
265+
| `case_hash` | _(Required.) _ **[Binary](#binary)**. The case hash (32 bytes, sha256). |
266+
| `constitution_hash` | _(Required.) _ **[Binary](#binary)**. The constitution hash at the time of decision (32 bytes, sha256). |
267+
| `constitution_revision` | _(Required.) _ **integer**. The constitution revision number at the time of decision. |
268+
| `decision_id` | _(Required.) _ **integer**. The unique decision identifier. |
269+
| `motivation` | **string\|null**. Optional motivation term as a Prolog term string. |
270+
| `motivation_hash` | **[Binary](#binary)\|null**. The motivation hash (32 bytes, sha256). |
271+
| `verdict` | _(Required.) _ **string**. The verdict term as a Prolog term string. |
272+
| `verdict_hash` | _(Required.) _ **[Binary](#binary)**. The verdict hash (32 bytes, sha256). |
273+
274+
### decisions
275+
276+
Response returned by `QueryMsg::Decisions`.
277+
278+
| property | description |
279+
| ----------- | ---------------------------------------------------------------------- |
280+
| `decisions` | _(Required.) _ **Array&lt;[DecisionResponse](#decisionresponse)&gt;**. |
281+
210282
## Definitions
211283

212284
### Binary
@@ -217,6 +289,25 @@ A string containing Base64-encoded data.
217289
| ----------- |
218290
| **string**. |
219291

292+
### DecisionResponse
293+
294+
Response returned by `QueryMsg::Decision`.
295+
296+
| property | description |
297+
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
298+
| `author` | _(Required.) _ **string**. The author Bech32 address. |
299+
| `block_height` | _(Required.) _ **integer**. The block height at which the decision was recorded. |
300+
| `block_time_seconds` | _(Required.) _ **integer**. The block time (seconds since epoch) at which the decision was recorded. |
301+
| `case` | _(Required.) _ **string**. The case term as a Prolog term string. |
302+
| `case_hash` | _(Required.) _ **[Binary](#binary)**. The case hash (32 bytes, sha256). |
303+
| `constitution_hash` | _(Required.) _ **[Binary](#binary)**. The constitution hash at the time of decision (32 bytes, sha256). |
304+
| `constitution_revision` | _(Required.) _ **integer**. The constitution revision number at the time of decision. |
305+
| `decision_id` | _(Required.) _ **integer**. The unique decision identifier. |
306+
| `motivation` | **string\|null**. Optional motivation term as a Prolog term string. |
307+
| `motivation_hash` | **[Binary](#binary)\|null**. The motivation hash (32 bytes, sha256). |
308+
| `verdict` | _(Required.) _ **string**. The verdict term as a Prolog term string. |
309+
| `verdict_hash` | _(Required.) _ **[Binary](#binary)**. The verdict hash (32 bytes, sha256). |
310+
220311
---
221312

222-
_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-gov.json` (`9c380ee3f4499a8b`)_
313+
_Rendered by [Fadroma](https://fadroma.tech) ([@fadroma/schema 1.1.0](https://www.npmjs.com/package/@fadroma/schema)) from `axone-gov.json` (`5f5c92435d2b7af4`)_

0 commit comments

Comments
 (0)