From e397672b443890da5e862c70e58d297bf9528845 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 5 Feb 2025 11:56:14 -0800 Subject: [PATCH 1/4] embellish on meaning of DNA properties --- src/pages/build/dnas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/build/dnas.md b/src/pages/build/dnas.md index 065acc4a4..3dfba5e98 100644 --- a/src/pages/build/dnas.md +++ b/src/pages/build/dnas.md @@ -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 or environment variables](https://12factor.net/config) for your zomes. * `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. From e82bec30d46554f2b5a05f3b9d664cf7ad54ec02 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 5 Feb 2025 11:56:25 -0800 Subject: [PATCH 2/4] add section on using DNA properties --- src/pages/build/dnas.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/src/pages/build/dnas.md b/src/pages/build/dnas.md index 3dfba5e98..b13127482 100644 --- a/src/pages/build/dnas.md +++ b/src/pages/build/dnas.md @@ -229,6 +229,27 @@ 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, which is why it's considered modifier --- it can change the way validation functions operate. + +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. (We call the pattern of giving one agent special privileges via DNA properties the 'progenitor' pattern.) This function could be used in a validation callback to enforce this restriction. + +```rust +use hdi::prelude::*; + +#[dna_properties] +struct DnaProperties { + progenitor: AgentPubKeyB64, +} + +fn is_allowed_to_write_data(author: AgentPubKey) -> ExternResult { + Ok(author == DnaProperties::try_from_dna_properties()?.progenitor.try_into()?) +} +``` + ## 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/). From a6a9e0f2b053ed2d5ee90e8324c7ea38b03c26b9 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 5 Feb 2025 12:48:54 -0800 Subject: [PATCH 3/4] better prose and simpler example for DNA properties; thanks @mattyg --- src/pages/build/dnas.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/pages/build/dnas.md b/src/pages/build/dnas.md index b13127482..c60f19946 100644 --- a/src/pages/build/dnas.md +++ b/src/pages/build/dnas.md @@ -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](#use-dna-properties). Think of it as [configuration or environment variables](https://12factor.net/config) for your zomes. + * `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. @@ -231,22 +231,25 @@ Note that **bridging between different cells only happens within one agent's hAp ## 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, which is why it's considered modifier --- it can change the way validation functions operate. +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, 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. (We call the pattern of giving one agent special privileges via DNA properties the 'progenitor' pattern.) This function could be used in a validation callback to enforce this restriction. +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 { - progenitor: AgentPubKeyB64, + // 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 { - Ok(author == DnaProperties::try_from_dna_properties()?.progenitor.try_into()?) + let dna_props = DnaProperties::try_from_dna_properties()?; + Ok(author == dna_props.writer) } ``` From 7ea374b58a44de171a785e687b7e9fffe154025a Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 5 Feb 2025 12:54:33 -0800 Subject: [PATCH 4/4] fixed CI failure due to slugification discrepancy --- src/pages/build/dnas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/build/dnas.md b/src/pages/build/dnas.md index c60f19946..ce1e234fa 100644 --- a/src/pages/build/dnas.md +++ b/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.