Build guide: DNA properties

src/pages/build/dnas.md

@@ -6,7 +6,7 @@ title: "DNAs"
 A **DNA** is a bundle of one or more [**zomes**](/build/zomes/), along with optional **DNA modifiers**. Together, the zomes and DNA modifiers define the executable code and settings for a single **peer-to-peer network**.
 :::
 
-## DNAs: the 'rules of the game' for a network
+## DNAs: the 'rules of the game' for a network {#dnas-the-rules-of-the-game-for-a-network}
 
 Holochain supports multiple, separate peer-to-peer networks, each with its own membership and shared [graph database](/build/working-with-data/). Each network is backed by its own DNA, whose executable code and settings create the 'rules of the game' for the network.
 
@@ -65,7 +65,7 @@ coordinator:
 * `name`: A string for humans to read. This might get used in the admin panel of Holochain [conductors](/concepts/2_application_architecture/#conductor) like [Holochain Launcher](https://github.com/holochain/launcher).
 * `integrity`: Contains all the integrity modifiers for the DNA, the things that **change the DNA hash**.
     * `network_seed`: A string that serves only to change the DNA hash without affecting behavior. It acts like a network-wide passcode. {#network-seed}
-    * `properties`: Arbitrary, application-specific constants. The zome code can read this at runtime. Think of it as configuration for the DNA.
+    * `properties`: Arbitrary, application-specific constants. The zome code can [read this at runtime](#use-dna-properties). Think of it as configuration for your DNA.
     * `origin_time`: The earliest possible timestamp for any data; serves as a basis for coordinating network communication. Pick a date that's guaranteed to be slightly earlier than you expect that the app will start to get used. The scaffolding tool and `hc dna init` will both pick the date you created the DNA.
     * `zomes`: A list of all the integrity zomes in the DNA.
         * `name`: A unique name for the zome, to be used for dependencies.
@@ -229,6 +229,30 @@ Note that **bridging between different cells only happens within one agent's hAp
 | Alice `main`      | `call`        | `call`         | `call_remote` | ⛔            |
 | Alice `search`    | `call`        | `call`         | ⛔            | `call_remote` |
 
+## Use DNA properties
+
+The `properties` field in your DNA is just arbitrary bytes, but it's meant to be written and deserialized as YAML. Any of your zomes can access it. Because it's a DNA modifier, it [changes the DNA hash](#dnas-the-rules-of-the-game-for-a-network), which results in a new network. The reason for this is that you can use the properties in your validation callbacks<!-- TODO: link when validation PR is merged -->, configuring how they work for different networks. You can only modify DNA properties before an app is installed or when a cell is cloned --- not while the cell is running.
+
+You can deserialize your DNA modifiers automatically by using the [`dna_properties` macro](https://docs.rs/hdk_derive/latest/hdk_derive/attr.dna_properties.html) on a type definition, which will give your type a method called `try_from_dna_properties`.
+
+This example shows a helper function that only permits one agent to write data. This function could be used in a validation callback to enforce this restriction.
+
+```rust
+use hdi::prelude::*;
+
+#[dna_properties]
+struct DnaProperties {
+    // The only agent that's allowed to write data to this DHT.
+    // Configurable per network.
+    writer: AgentPubKey,
+}
+
+fn is_allowed_to_write_data(author: AgentPubKey) -> ExternResult<bool> {
+    let dna_props = DnaProperties::try_from_dna_properties()?;
+    Ok(author == dna_props.writer)
+}
+```
+
 ## Next steps
 
 Now that you've created a bare DNA, it's time to [fill it with zomes](/build/zomes/), [define some data types](/build/working-with-data), and write some [callbacks](/build/callbacks-and-lifecycle-hooks/) and an [API](/build/zome-functions/).