Feat: Getting an agent's status

.markdownlint.json

@@ -0,0 +1,5 @@
+{
+  "MD007": {
+    "indent": 4
+  }
+}

src/pages/_data/navigation/mainNav.json5

@@ -58,6 +58,7 @@
           { title: "Validate Callback", url: "/build/validate-callback/" },
           { title: "must_get_* Host Functions", url: "/build/must-get-host-functions/" },
           { title: "DHT Operations", url: "/build/dht-operations/" },
+          { title: "Getting an Agent's Status", url: "/build/getting-an-agents-status/" },
         ]},
         { title: "Testing", url: "/build/testing-with-tryorama/", children: []},
         { title: "Operating a hApp", url: "/build/operating-a-happ/", children: []},

src/pages/build/dht-operations.md

@@ -2,6 +2,17 @@
 title: "DHT operations"
 ---
 
+::: topic-list
+### In this section {data-no-toc}
+
+* [Validation](/build/validation/)
+    * [`genesis_self_check` Callback](/build/genesis-self-check-callback/) --- writing a function to control access to a network
+    * [`validate` Callback](/build/validate-callback/) --- basic callback, examples using stub functions
+    * [`must_get_*` Host Functions](/build/must-get-host-functions/) --- Deterministically retrieving DHT data for use in validation
+    * DHT operations (this page) --- advanced details on the underlying data structure used in DHT replication and validation
+    * [Getting an Agent's Status](/build/getting-an-agents-status/) --- checking for invalid actions committed by another agent
+:::
+
 ::: intro
 An agent receives **DHT operations**, which are requests for them to transform [their slice of the DHT](/concepts/4_dht/#finding-peers-and-data-in-a-distributed-database) in some way. A DHT operation must be validated before it's applied. For this reason it's the input parameter to the [`validate` callback](/build/validate-callback/).
 :::
@@ -45,17 +56,17 @@ While the following info describes the way Holochain should work [as formally sp
         * Contents: action (and optionally entry, if applicable) <!--TODO: system validation? -->
         * Effect: Store the action, along with any entry data.
 * [`Create`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/action/enum.Action.html#variant.Create)
-    * [`StoreEntry`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.StoreEntry)
+    * [`StoreEntry`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.StoreEntry){#store-entry}
         * Basis address: entry hash
         * Contents: entry, and the action that wrote it
         * System validation: Check that the action's entry hash matches the entry hash.
-        * Effect: Store the entry, if an identical entry hasn't been created yet, and add the action to the the list of actions associated with its creation. An entry can be created by multiple authors, and each creation action paired with its entry [can be treated as an independent piece of data](/build/entries/#entries-and-actions). **This operation isn't produced for private entries.**
-* [`Update`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/action/enum.Action.html#variant.Update)
+        * Effect: Store the entry, if an identical entry hasn't been created yet, and add the action to the list of actions associated with its creation. An entry can be created by multiple authors, and each creation action paired with its entry [can be treated as an independent piece of data](/build/entries/#entries-and-actions). **This operation isn't produced for private entries.**
+* [`Update`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/action/enum.Action.html#variant.Update){#update}
     * `StoreEntry` (see above)
-    * [`RegisterUpdate`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.RegisterUpdate)
+    * [`RegisterUpdate`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.RegisterUpdate){#register-update}
         * Basis addresses: entry and action hashes of the _old_ entry being updated
         * Contents: action and entry <!--TODO: system validation? -->
-        * Effect: Mark an entry creation action as being replaced by a new one, pointing the the entry and action that replace it. **An entry and its creation action can have multiple actions updating them.**
+        * Effect: Mark an entry creation action as being replaced by a new one, pointing to the entry and action that replace it. **An entry and its creation action can have multiple actions updating them.**
 * [`Delete`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/action/enum.Action.html#variant.Delete)
     * [`RegisterDelete`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.RegisterDelete)
         * Basis addresses: entry and action hashes of the entry being deleted
@@ -67,7 +78,14 @@ While the following info describes the way Holochain should work [as formally sp
         * Contents: action <!--TODO: system validation? -->
         * Effect: Add a link to the list of links pointing from the base to other locations
 * [`DeleteLink`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/action/enum.Action.html#variant.DeleteLink)
-    * [`RegisterDeleteLink`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.RegisterCreateLink)
+    * [`RegisterDeleteLink`](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/op/enum.Op.html#variant.RegisterDeleteLink)
         * Basis addresses: old link's [base address](/build/links-paths-and-anchors/#define-a-link-type) and action hash
         * Contents: action <!--TODO: system validation? -->
-        * Effect: Mark a link as deleted, without removing the actual data.
+        * Effect: Mark a link as deleted, without removing the actual data.
+
+## Warrant operations
+
+There's one final DHT operation type, a [`WarrantOp`](https://docs.rs/holochain_types/latest/holochain_types/warrant/struct.WarrantOp.html). Rather than being produced from an action, it gets produced by a validator when they discover an invalid operation. Its basis address is the public key of the author of the operation, which means warrants get collected on the agent ID address. Warrants can be [retrieved with `get_agent_activity`](/build/getting-an-agents-status/).
+
+You don't need to write validation code for warrant operations; they're system-only operations.
+

src/pages/build/entries.md

@@ -339,7 +339,7 @@ You can use any of these identifiers as a field in your entry types to model a m
 
 ### As a single record
 
-Get a record by calling [`hdk::entry::get`](https://docs.rs/hdk/latest/hdk/entry/fn.get.html) with the hash of either its entry creation action. The return value is an <code>Option&lt;[holochain_integrity_types::record::Record](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/record/struct.Record.html)&gt;</code> wrapped in an `ExternResult`.
+Get a record by calling [`hdk::entry::get`](https://docs.rs/hdk/latest/hdk/entry/fn.get.html) with the hash of its entry creation action. The return value is an <code>Option&lt;[holochain_integrity_types::record::Record](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/record/struct.Record.html)&gt;</code> wrapped in an `ExternResult`.
 
 You can also pass an _entry hash_ to `get`, and the record returned will contain the _oldest live_ entry creation action that wrote it.
 
@@ -383,6 +383,10 @@ match maybe_record {
 };
 ```
 
+!!! info `get` only returns valid data
+This function will only return entry and action data that's valid from the perspective of the agent delivering it; if it's not valid, they'll return `None` instead. Note also that, even if a record is returned, other validators may consider it to be invalid. Read [Getting an Agent's Status](/build/getting-an-agents-status/) for more info.
+!!!
+
 ### All data, actions, and links at an address
 
 #### Records

src/pages/build/genesis-self-check-callback.md

@@ -2,6 +2,17 @@
 title: "Genesis Self-Check Callback"
 ---
 
+::: topic-list
+### In this section {data-no-toc}
+
+* [Validation](/build/validation/)
+    * `genesis_self_check` Callback (this page) --- writing a function to control access to a network
+    * [`validate` Callback](/build/validate-callback/) --- basic callback, examples using stub functions
+    * [`must_get_*` Host Functions](/build/must-get-host-functions/) --- Deterministically retrieving DHT data for use in validation
+    * [DHT operations](/build/dht-operations/) --- advanced details on the underlying data structure used in DHT replication and validation
+    * [Getting an Agent's Status](/build/getting-an-agents-status/) --- checking for invalid actions committed by another agent
+:::
+
 ::: intro
 To enforce access control for a network, a DNA can require a [**membrane proof**](/concepts/3_source_chain/#membrane-proof), which is a piece of data that gets entered by the user and written to their [**source chain**](/concepts/3_source_chain/). The `genesis_self_check` function can guard against user entry error and help prevent them from being accidentally marked as a bad actor.
 :::