From c9776516e20e5253038e8acebaae1ae09e33d0dd Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Tue, 19 Nov 2024 14:09:11 -0800 Subject: [PATCH 01/44] better headers in advanced setup guide --- src/pages/get-started/install-advanced.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/pages/get-started/install-advanced.md b/src/pages/get-started/install-advanced.md index 5740e799d..24d858169 100644 --- a/src/pages/get-started/install-advanced.md +++ b/src/pages/get-started/install-advanced.md @@ -19,12 +19,16 @@ If you want to learn more about how this setup works and how to create it manual [Flakes](https://wiki.nixos.org/wiki/Flakes) is an experimental but well-supported feature of the Nix package manager that makes it easier to manage dependencies consistently. [Enable flakes on your system.](https://wiki.nixos.org/wiki/Flakes#Enable_flakes_temporarily) -The flake-based one-liner to get you an ad-hoc Holonix shell looks like this: +### Entering an ad-hoc shell + +The flake-based one-liner to get you an ad-hoc Holonix shell (that is, not using a local flake file) looks like this: ```shell nix develop github:holochain/holonix ``` +#### Specifying a certain release + The above one-liner will give you the latest version of Holochain from branch `main`. To get an ad-hoc shell with a specific version of Holochain, use the flag `--override-input versions `. ```shell From b230aac67e43f173dfee9e3c5640bca50198d76a Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Tue, 19 Nov 2024 14:09:28 -0800 Subject: [PATCH 02/44] customised HC binary --- src/pages/get-started/install-advanced.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/pages/get-started/install-advanced.md b/src/pages/get-started/install-advanced.md index 24d858169..30f89c04a 100644 --- a/src/pages/get-started/install-advanced.md +++ b/src/pages/get-started/install-advanced.md @@ -35,6 +35,10 @@ The above one-liner will give you the latest version of Holochain from branch `m nix develop --override-input holochain "github:holochain/holochain?ref=main-0.4" github:holochain/holonix ``` +### Customizing the Holochain binary + +If you want to enable or disable certain Holochain features, such as unstable features, it's best to do this in a local flake file. [Read the 'Customized Holochain build'](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) on the Holonix readme to find out how. Keep in mind that, because you'll be creating a custom Holochain binary, you won't be able to take advantage of the package cache, so it'll take a while to compile Holochain on your machine. + ### A gotcha with Flakes and Git The behavior of `nix` commands that rely on a `flake.nix` as its input such as `nix develop` can be counterintuitive in a git repository. From a026a0837351105dba9c825ce3d5aa7b83e67121 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 22 Nov 2024 09:59:34 -0800 Subject: [PATCH 03/44] add auto-generated TOC into 0.3 upgrade guide --- src/pages/resources/upgrade/upgrade-holochain-0.3.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.3.md b/src/pages/resources/upgrade/upgrade-holochain-0.3.md index 158f9ab7b..2accb6443 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.3.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.3.md @@ -1,7 +1,5 @@ --- title: Holochain Upgrade 0.2 → 0.3 -hide: - - toc --- ::: intro From 3d8246528bb1dc464c0dea69a405cd0d12729f34 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 22 Nov 2024 09:59:48 -0800 Subject: [PATCH 04/44] 0.4 upgrade guide --- .../upgrade/upgrade-holochain-0.4.md | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 src/pages/resources/upgrade/upgrade-holochain-0.4.md diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md new file mode 100644 index 000000000..a1411e0f3 --- /dev/null +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -0,0 +1,126 @@ +--- +title: Holochain Upgrade 0.3 → 0.4 +--- + +::: intro +For existing hApps that were written for Holochain 0.3, here's the guide to get you upgraded to 0.4. +::: + +## Summary + +Here are all the breaking changes you need to know about in order to update your app for Holochain 0.4: + +* Some unstable features are now behind feature flags. +* Zome calls are signed differently. +* The `OpenChain` and `CloseChain` actions have been modified. +* The database encryption scheme has been change, and the directory structure has moved around. +* The `InstallApp` admin API endpoint has had its request payload changed slightly. +* `CloneCellId`, used as an input argument to clone manipulation functions, has changed. +* The `CountersigningSuccess` signal supplies the action hash, not the entry hash. +* The `AppInfo` admin endpoint's response contains new statuses related to deferred memproofs. +* The WebRTC signalling server architecture has changed, along with new server addresses and self-hosted server binaries. +* Deprecated `OpType` and `op::to_type` have been removed from the HDI. +* Enums are serialized differently. + +## Unstable features removed by default + +The biggest change for 0.4 is that some unstable features aren't compiled into official Holochain releases by default. We're doing this to focus on a stable core Holochain with the minimal feature set that most projects need. The removed features are still available as Rust feature flags, so you can compile a custom Holochain binary if you need them. Here's the full list, along with their feature flags: + +* countersigning `unstable-countersigning` TODO +* DPKI / DeepKey `unstable-dpki` +* DHT sharding `unstable-sharding` +* warrants `unstable-warrants` +* chain head coordination `chc` (this pre-existing feature flag is no longer enabled by default) +* HDI/HDK functions `unstable-functions` + * related to countersigning (enable `unstable-countersigning` if you want to use these): + * `accept_countersigning_preflight_request` + * related to DPKI (enable `unstable-dpki` if you want to use these): + * `get_agent_key_lineage` + * `is_same_agent` + * related to block lists: + * `block_agent` + * `unblock_agent` + * other: + * `schedule` + * an unimplemented `sleep` function has been removed completely +* TODO any more? + +Read the [Holonix readme](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) to find out how to compile a custom Holochain build with these flags enabled. + +`unstable-functions` is a flag used by both the Holochain conductor _and_ the `hdi` and `hdk` crates. If you want to use them, you'll need to edit your zome crates' `Cargo.toml`. If you compile your zomes without `unstable-functions` enabled, users with the flag enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki`). + +## Zome call signing + +Signing a zome call was previously hard to get right, because the conductor would deserialize and reserialize the signed payload before checking the signature. Sometimes the client would order the payload's fields differently from the conductor, which would cause the signature to look invalid. + +Now the payload must be serialized, signed in the client, and sent to the conductor along with the signature. The conductor will now check the signature against the _serialized_ payload before deserializing. + +This is a BREAKING change for the `CallZome` app API endpoint. If you're using the JavaScript or Rust client lib, you don't need to make any code changes; just update the client lib to v?? (JavaScript) TODO or v?? (Rust) TODO. + +If you're a client library author, take a look at the new app API endpoint documentation TODO. + +## DHT sharding is disabled by default + +This feature needs more performance and correctness testing before it's production-ready. With the `unstable-sharding` feature flag disabled by default, your conductor config's `gossip_arc_clamping` must now be set to either `"full"` or `"empty"`, and the previous default `"none"` will cause a conductor startup error. `"gossip_dynamic_arcs"` is also ignored. + +It's unknown exactly what might happen if nodes with DHT sharding disabled try to gossip in the same network as nodes without DHT sharding. Presumably this is still possible, but it might cause unexpected emergent behaviors! + +## Raw hash constructor function rename + +`holo_hash::HoloHash::from_raw_39_panicky` has been renamed to `from_raw_39`. Its behavior is otherwise the same. There are two new functions in the same impl; `try_from_raw_39` and `try_from_raw_36_and_type`, which return errors instead of panicking. + +## `OpenChain` and `CloseChain` actions changed + +If you're one of the rare folks who have been using these two actions, the structs have changed. `CloseChain::new_dna_hash` has been replaced with [`new_target`](TODO), which has a type of `Option`. This new type TODO is an enum of `Dna(DnaHash)` or `Agent(AgentHash)`. + +`OpenChain::prev_dna_hash` has been changed to match; its type is a non-optional `MigrationTarget`. It also gets a new field, `close_hash`, which is the `ActionHash` of the corresponding `CloseChain` action. + +## Dynamic database encryption, folder structure changes + +Previous conductor and keystore SQLite databases used a hardcoded encryption key; v0.4 now uses a dynamic key. This means you won't be able to import data from v0.3. + +The database names have also changed; any file prefix that matches the folder it's in (e.g., `/authorized/authorized--.sqlite`) is dropped, along with the `.sqlite` file extension. + +## `InstallApp` agent key is optional + +The `agent_key` field in the `InstallApp` payload is now optional, and a key will be generated if you don't supply one. If your app is used to generating agent keys and supplying them on install, you shouldn't need to change your code; just update the client library and it'll work. + +## `CloneCellId` changes + +[TODO link] The `CloneCellId::CellId` enum variant has become `DnaHash` and contains, naturally, a `DnaHash` value. This type is used when enabling, disabling, or deleting clones from the app API or a coordinator zome. + +## `CountersigningSuccess` information changed + +The `CountersigningSuccess` signal sent to the client now gives the action hash of the successful countersigned commit rather than its entry hash. + +## New data in `AppInfo` response + +Holochain 0.4 introduces a new flow for app installation that lets an agent supply a membrane proof later with a new `ProvideMemProof` endpoint (TODO link). This allows them to get their freshly generated agent key, submit it to some sort of membrane proof service, and get a membrane proof. + +Because of this, the [`DisabledReason` enum](TODO), after the membrane proof has been provided, will be a new `NotStartedAfterProvidingMemproofs` variant until the app is started. + +## WebRTC signalling server change + +The old signalling server has been replaced with a new one called [`sbd`](https://github.com/holochain/sbd/). If you're hosting your own server, switch to a [new `sbd` server binary](https://github.com/holochain/sbd/tags). If you're using Holo's public infrastructure, switch from `wss://signal.holo.host` to `wss://sbd-0.main.infra.holo.host` in your conductor config file. + +## Deprecated validation op functionality removed + +In your integrity zome's validation functions, you deal with DHT operations, or ops. They are somewhat convoluted, so `FlatOp` was introduced. It was originally called `OpType`, and until now that old name aliased `FlatOp`. The old type has finally been removed, along with the `Op::to_type` method (use `Op::flattened` instead). + +## Change in enum serialization + +The default serialization for bare enum variants has changed. Previously, they would look like this (JSON representation): + +```json +{ + "variant1": null +} +``` + +Now they look like this: + +```json +"variant1" +``` + +(Enum variants with data still follow the `{ "variant": }` pattern.) TODO check if this is true \ No newline at end of file From ab702121d5d4ba981971dd9a00f6ededc94cc55f Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 22 Nov 2024 10:00:30 -0800 Subject: [PATCH 05/44] add 0.4 upgrade guide to TOC; rearrange --- src/pages/resources/upgrade/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/pages/resources/upgrade/index.md b/src/pages/resources/upgrade/index.md index 3b7457bdc..f096561cf 100644 --- a/src/pages/resources/upgrade/index.md +++ b/src/pages/resources/upgrade/index.md @@ -8,6 +8,7 @@ hide: Upgrading between versions of Holochain can be a bit tricky! While Holochain is in beta, you can expect breaking changes between minor versions. To make upgrading your hApp easier, we create guides to help you move from one Holochain version to the next. -* [Holochain Upgrade 0.1 → 0.2](/resources/upgrade/upgrade-holochain-0.2/) -* [Holochain Upgrade 0.2 → 0.3](/resources/upgrade/upgrade-holochain-0.3/) * [Upgrading to the new Holonix](/resources/upgrade/upgrade-new-holonix/) (all Holochain versions) +* [Holochain Upgrade 0.3 → 0.4](/resources/upgrade/upgrade-holochain-0.4/) +* [Holochain Upgrade 0.2 → 0.3](/resources/upgrade/upgrade-holochain-0.3/) +* [Holochain Upgrade 0.1 → 0.2](/resources/upgrade/upgrade-holochain-0.2/) From 8c71c432e5e886c0f332fb668c3dd48776c9c948 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 22 Nov 2024 10:01:46 -0800 Subject: [PATCH 06/44] update redirects for upgrade guide --- netlify.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/netlify.toml b/netlify.toml index 27bf42a9f..b355dbd87 100644 --- a/netlify.toml +++ b/netlify.toml @@ -133,7 +133,7 @@ # The first upgrade guide lived under getting started. It has been moved to its own area. [[redirects]] from = "/get-started/upgrade-holochain/" - to = "/resources/upgrade/upgrade-holochain-0.2/" + to = "/resources/upgrade/" status = 301 # Every time there's a new breaking release that achieves 'recommended' status, @@ -141,5 +141,5 @@ # but it is a handy URL we can hand out without needing to look up what the proper URL is. [[redirects]] from = "/resources/upgrade/latest/" - to = "resources/upgrade/upgrade-holochain-0.2/" + to = "/resources/upgrade/upgrade-holochain-0.4/" status = 302 \ No newline at end of file From f4f61a18bd7c284af3e1dfa9f867c5c5d4d6d18a Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 22 Nov 2024 10:03:41 -0800 Subject: [PATCH 07/44] add mention of new Holonix to 0.4 migration guide --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index a1411e0f3..c333526db 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -4,6 +4,8 @@ title: Holochain Upgrade 0.3 → 0.4 ::: intro For existing hApps that were written for Holochain 0.3, here's the guide to get you upgraded to 0.4. + +NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment, has also been updated. We recommend you [upgrade to the new Holonix](/resources/upgrade-new-holonix/) at the same time! ::: ## Summary From b3521b749f0f8d8b815f7ddc36ec7d38f5b8f6ff Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 28 Nov 2024 12:02:18 -0800 Subject: [PATCH 08/44] language shaping --- .../upgrade/upgrade-holochain-0.4.md | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index c333526db..f89090d43 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -13,7 +13,7 @@ NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment Here are all the breaking changes you need to know about in order to update your app for Holochain 0.4: * Some unstable features are now behind feature flags. -* Zome calls are signed differently. +* Zome call payloads are built and signed differently. * The `OpenChain` and `CloseChain` actions have been modified. * The database encryption scheme has been change, and the directory structure has moved around. * The `InstallApp` admin API endpoint has had its request payload changed slightly. @@ -28,36 +28,36 @@ Here are all the breaking changes you need to know about in order to update your The biggest change for 0.4 is that some unstable features aren't compiled into official Holochain releases by default. We're doing this to focus on a stable core Holochain with the minimal feature set that most projects need. The removed features are still available as Rust feature flags, so you can compile a custom Holochain binary if you need them. Here's the full list, along with their feature flags: -* countersigning `unstable-countersigning` TODO -* DPKI / DeepKey `unstable-dpki` -* DHT sharding `unstable-sharding` -* warrants `unstable-warrants` -* chain head coordination `chc` (this pre-existing feature flag is no longer enabled by default) -* HDI/HDK functions `unstable-functions` - * related to countersigning (enable `unstable-countersigning` if you want to use these): +* **Countersigning `unstable-countersigning`**: Allows agents to temporarily lock their chains in order to agree to write the same entry to their respective chains. +* **DPKI / DeepKey `unstable-dpki`**: Implements a distributed public key infrastructure, allowing agents to manage their keys and confirm continuity of their identity across devices and source chains. +* **DHT sharding `unstable-sharding`**: Lessens the load of each peer in large network, allowing them to take responsibility for validating and storing only a subset of a DHT's entire data set. +* **Warrants `unstable-warrants`**: Spreads news of validation failure around the network, allowing peers to recognize bad actors and take action against them, even if they haven't directly interacted with them. +* **Chain head coordination `chc`**: Developed for Holo, allows source chain changes to be copied from one device to another without causing chain forks. (This pre-existing feature flag is no longer enabled by default.) +* **HDI/HDK functions `unstable-functions`**: + * Related to countersigning (enable `unstable-countersigning` if you want to use these): * `accept_countersigning_preflight_request` - * related to DPKI (enable `unstable-dpki` if you want to use these): + * Related to DPKI (enable `unstable-dpki` if you want to use these): * `get_agent_key_lineage` * `is_same_agent` - * related to block lists: + * Related to block lists (allowing peers in a hApp to selectively block others who haven't necessarily produced invalid data or forked their source chain): * `block_agent` * `unblock_agent` - * other: + * Other: * `schedule` - * an unimplemented `sleep` function has been removed completely + * An unimplemented `sleep` function has been removed completely * TODO any more? Read the [Holonix readme](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) to find out how to compile a custom Holochain build with these flags enabled. -`unstable-functions` is a flag used by both the Holochain conductor _and_ the `hdi` and `hdk` crates. If you want to use them, you'll need to edit your zome crates' `Cargo.toml`. If you compile your zomes without `unstable-functions` enabled, users with the flag enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki`). +`unstable-functions` is a flag used by both the Holochain conductor _and_ the `hdi` and `hdk` crates, and some of the functions also need other Holochain features enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki` enabled; see the list above). If you want to use them, you'll need to edit your zome crates' `Cargo.toml` files and make sure that users are running your custom conductor binary with the right features enabled. If you compile your zomes without `unstable-functions` enabled, users with the flag(s) enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag(s) disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled . ## Zome call signing -Signing a zome call was previously hard to get right, because the conductor would deserialize and reserialize the signed payload before checking the signature. Sometimes the client would order the payload's fields differently from the conductor, which would cause the signature to look invalid. +Signing a zome call payload was previously hard to get right, because the conductor would deserialize and reserialize the signed payload before checking the signature. Sometimes the client would order the payload's fields differently from the conductor, which would cause the signature to look invalid. -Now the payload must be serialized, signed in the client, and sent to the conductor along with the signature. The conductor will now check the signature against the _serialized_ payload before deserializing. +Now the payload must be serialized and signed in the client, then sent to the conductor along with the signature. The conductor will now check the signature against the _serialized_ payload before deserializing. -This is a BREAKING change for the `CallZome` app API endpoint. If you're using the JavaScript or Rust client lib, you don't need to make any code changes; just update the client lib to v?? (JavaScript) TODO or v?? (Rust) TODO. +This is a BREAKING change for the `CallZome` app API endpoint. If you're using the JavaScript or Rust client lib, you don't need to make any code changes [TODO is this right?]; just update the client lib to v?? (JavaScript) TODO or v?? (Rust) TODO. If you're a client library author, take a look at the new app API endpoint documentation TODO. @@ -65,11 +65,11 @@ If you're a client library author, take a look at the new app API endpoint docum This feature needs more performance and correctness testing before it's production-ready. With the `unstable-sharding` feature flag disabled by default, your conductor config's `gossip_arc_clamping` must now be set to either `"full"` or `"empty"`, and the previous default `"none"` will cause a conductor startup error. `"gossip_dynamic_arcs"` is also ignored. -It's unknown exactly what might happen if nodes with DHT sharding disabled try to gossip in the same network as nodes without DHT sharding. Presumably this is still possible, but it might cause unexpected emergent behaviors! +It's unknown exactly what might happen if nodes with DHT sharding disabled try to gossip in the same network as nodes without DHT sharding. Presumably this is still possible, but it might cause unexpected behaviors! ## Raw hash constructor function rename -`holo_hash::HoloHash::from_raw_39_panicky` has been renamed to `from_raw_39`. Its behavior is otherwise the same. There are two new functions in the same impl; `try_from_raw_39` and `try_from_raw_36_and_type`, which return errors instead of panicking. +`holo_hash::HoloHash::from_raw_39_panicky` has been renamed to `from_raw_39`. Its behavior is otherwise the same. There are two new functions in the same impl, `try_from_raw_39` and `try_from_raw_36_and_type`, which return errors instead of panicking. ## `OpenChain` and `CloseChain` actions changed @@ -103,11 +103,11 @@ Because of this, the [`DisabledReason` enum](TODO), after the membrane proof has ## WebRTC signalling server change -The old signalling server has been replaced with a new one called [`sbd`](https://github.com/holochain/sbd/). If you're hosting your own server, switch to a [new `sbd` server binary](https://github.com/holochain/sbd/tags). If you're using Holo's public infrastructure, switch from `wss://signal.holo.host` to `wss://sbd-0.main.infra.holo.host` in your conductor config file. +The old signalling server has been replaced with a new one called [`sbd`](https://github.com/holochain/sbd/). If you're hosting your own server, switch to a [new `sbd` server binary](https://github.com/holochain/sbd/tags). If you're using Holo's public infrastructure, switch from `wss://signal.holo.host` to `wss://sbd-0.main.infra.holo.host` in your conductor config file. (The new URL will automatically be in any conductor config generated by the dev tools for 0.4.) ## Deprecated validation op functionality removed -In your integrity zome's validation functions, you deal with DHT operations, or ops. They are somewhat convoluted, so `FlatOp` was introduced. It was originally called `OpType`, and until now that old name aliased `FlatOp`. The old type has finally been removed, along with the `Op::to_type` method (use `Op::flattened` instead). +In your integrity zome's validation functions, you deal with DHT operations, or ops. They are somewhat convoluted, so `FlatOp` was introduced to make things simpler. It was originally called `OpType`, and until now that old name was an alias of `FlatOp`. The old type has finally been removed, along with the `Op::to_type` method (use `Op::flattened` instead). ## Change in enum serialization @@ -125,4 +125,4 @@ Now they look like this: "variant1" ``` -(Enum variants with data still follow the `{ "variant": }` pattern.) TODO check if this is true \ No newline at end of file +(Enum variants with data still follow the `{ "variant": }` pattern.) \ No newline at end of file From 1ffdc7fa0d06e01a3bed43dbb2feb7baef58bcfe Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 6 Dec 2024 14:28:27 -0800 Subject: [PATCH 09/44] small typos --- .cspell/custom-words.txt | 2 ++ .cspell/holochain-words.txt | 2 ++ .cspell/words-that-should-exist.txt | 1 + src/pages/resources/upgrade/upgrade-holochain-0.4.md | 10 +++++----- 4 files changed, 10 insertions(+), 5 deletions(-) diff --git a/.cspell/custom-words.txt b/.cspell/custom-words.txt index c74c3fee3..9d498288c 100644 --- a/.cspell/custom-words.txt +++ b/.cspell/custom-words.txt @@ -36,6 +36,8 @@ rustflags rustup setgid setuid +struct +structs subl Tauri Ulhaq diff --git a/.cspell/holochain-words.txt b/.cspell/holochain-words.txt index 4b8d11fa6..627323251 100644 --- a/.cspell/holochain-words.txt +++ b/.cspell/holochain-words.txt @@ -11,6 +11,8 @@ Holochain Holochain's Holonix Lightningrod +memproof +memproofs Mythosthesia sharded Snapmail diff --git a/.cspell/words-that-should-exist.txt b/.cspell/words-that-should-exist.txt index 97c97ed7f..0a7ba715c 100644 --- a/.cspell/words-that-should-exist.txt +++ b/.cspell/words-that-should-exist.txt @@ -16,6 +16,7 @@ interoperating permissioned permissivity redistributable +reserialize runtimes sandboxed sandboxing diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index f89090d43..8cf22678f 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -15,8 +15,8 @@ Here are all the breaking changes you need to know about in order to update your * Some unstable features are now behind feature flags. * Zome call payloads are built and signed differently. * The `OpenChain` and `CloseChain` actions have been modified. -* The database encryption scheme has been change, and the directory structure has moved around. -* The `InstallApp` admin API endpoint has had its request payload changed slightly. +* The database encryption scheme has changed, and the directory structure has moved around. +* The `InstallApp` admin API endpoint has had its request payload changed. * `CloneCellId`, used as an input argument to clone manipulation functions, has changed. * The `CountersigningSuccess` signal supplies the action hash, not the entry hash. * The `AppInfo` admin endpoint's response contains new statuses related to deferred memproofs. @@ -49,7 +49,7 @@ The biggest change for 0.4 is that some unstable features aren't compiled into o Read the [Holonix readme](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) to find out how to compile a custom Holochain build with these flags enabled. -`unstable-functions` is a flag used by both the Holochain conductor _and_ the `hdi` and `hdk` crates, and some of the functions also need other Holochain features enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki` enabled; see the list above). If you want to use them, you'll need to edit your zome crates' `Cargo.toml` files and make sure that users are running your custom conductor binary with the right features enabled. If you compile your zomes without `unstable-functions` enabled, users with the flag(s) enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag(s) disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled . +`unstable-functions` is a flag used by both the Holochain conductor _and_ the `hdi` and `hdk` crates, and some of the functions also need other Holochain features enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki` enabled; see the list above). If you want to use them, you'll need to edit your zome crates' `Cargo.toml` files and make sure that users are running your custom conductor binary with the right features enabled. If you compile your zomes without `unstable-functions` enabled, users with the flag(s) enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag(s) disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled. ## Zome call signing @@ -81,7 +81,7 @@ If you're one of the rare folks who have been using these two actions, the struc Previous conductor and keystore SQLite databases used a hardcoded encryption key; v0.4 now uses a dynamic key. This means you won't be able to import data from v0.3. -The database names have also changed; any file prefix that matches the folder it's in (e.g., `/authorized/authorized--.sqlite`) is dropped, along with the `.sqlite` file extension. +The database names have also changed; any file prefix that matches the folder it's in (e.g., `/authorized/authorized--.sqlite`) is dropped, along with the `.sqlite` file extension. ## `InstallApp` agent key is optional @@ -107,7 +107,7 @@ The old signalling server has been replaced with a new one called [`sbd`](https: ## Deprecated validation op functionality removed -In your integrity zome's validation functions, you deal with DHT operations, or ops. They are somewhat convoluted, so `FlatOp` was introduced to make things simpler. It was originally called `OpType`, and until now that old name was an alias of `FlatOp`. The old type has finally been removed, along with the `Op::to_type` method (use `Op::flattened` instead). +In your integrity zome's validation functions, you deal with DHT operations, or ops. They are somewhat complex, so `FlatOp` was introduced to make things simpler. It was originally called `OpType`, and until now that old name was a deprecated alias of `FlatOp`. The old type has finally been removed, along with the `Op::to_type` method (use `Op::flattened` instead). ## Change in enum serialization From 4f3cb3a3c885bfe8d16e408fd0147bdfa927b340 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 9 Dec 2024 15:35:52 -0800 Subject: [PATCH 10/44] add links, get 0.4 upgrade guide ready --- .../upgrade/upgrade-holochain-0.4.md | 44 +++++++++---------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 8cf22678f..1e872fb8c 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -28,28 +28,26 @@ Here are all the breaking changes you need to know about in order to update your The biggest change for 0.4 is that some unstable features aren't compiled into official Holochain releases by default. We're doing this to focus on a stable core Holochain with the minimal feature set that most projects need. The removed features are still available as Rust feature flags, so you can compile a custom Holochain binary if you need them. Here's the full list, along with their feature flags: -* **Countersigning `unstable-countersigning`**: Allows agents to temporarily lock their chains in order to agree to write the same entry to their respective chains. -* **DPKI / DeepKey `unstable-dpki`**: Implements a distributed public key infrastructure, allowing agents to manage their keys and confirm continuity of their identity across devices and source chains. -* **DHT sharding `unstable-sharding`**: Lessens the load of each peer in large network, allowing them to take responsibility for validating and storing only a subset of a DHT's entire data set. -* **Warrants `unstable-warrants`**: Spreads news of validation failure around the network, allowing peers to recognize bad actors and take action against them, even if they haven't directly interacted with them. +* **[Countersigning](/concepts/10_countersigning/) `unstable-countersigning`**: Allows agents to temporarily lock their chains in order to agree to write the same entry to their respective chains. +* **DPKI / DeepKey `unstable-dpki`**: Implements a distributed public key infrastructure, allowing agents to manage their keys and confirm continuity of their identity across devices and source chains. Read the [DeepKey readme](https://github.com/holochain/deepkey) for more info. +* **[DHT sharding](/concepts/4_dht/) `unstable-sharding`**: Lessens the load of each peer in large network, allowing them to take responsibility for validating and storing only a subset of a DHT's entire data set. +* **[Warrants](/concepts/7_validation#remembering-validation-results) `unstable-warrants`**: Spreads news of validation failure around the network, allowing peers to recognize bad actors and take action against them, even if they haven't directly interacted with them. * **Chain head coordination `chc`**: Developed for Holo, allows source chain changes to be copied from one device to another without causing chain forks. (This pre-existing feature flag is no longer enabled by default.) * **HDI/HDK functions `unstable-functions`**: * Related to countersigning (enable `unstable-countersigning` if you want to use these): - * `accept_countersigning_preflight_request` - * Related to DPKI (enable `unstable-dpki` if you want to use these): - * `get_agent_key_lineage` - * `is_same_agent` + * [`accept_countersigning_preflight_request`](https://github.com/holochain/holochain/blob/holochain-0.4.0-rc.2/crates/hdk/src/countersigning.rs#L3-L22) + * Related to DPKI (enable `unstable-dpki` if you want to use these, which are both new to 0.4): + * [`get_agent_key_lineage`](https://github.com/holochain/holochain/blob/holochain-0.4.0-rc.2/crates/hdk/src/agent.rs#L10-L20) * Related to block lists (allowing peers in a hApp to selectively block others who haven't necessarily produced invalid data or forked their source chain): * `block_agent` * `unblock_agent` * Other: - * `schedule` + * [`schedule`](https://github.com/holochain/holochain/blob/holochain-0.4.0-rc.2/crates/hdk/src/time.rs#L67-L137) * An unimplemented `sleep` function has been removed completely -* TODO any more? Read the [Holonix readme](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) to find out how to compile a custom Holochain build with these flags enabled. -`unstable-functions` is a flag used by both the Holochain conductor _and_ the `hdi` and `hdk` crates, and some of the functions also need other Holochain features enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki` enabled; see the list above). If you want to use them, you'll need to edit your zome crates' `Cargo.toml` files and make sure that users are running your custom conductor binary with the right features enabled. If you compile your zomes without `unstable-functions` enabled, users with the flag(s) enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag(s) disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled. +`unstable-functions` is a flag used by both the Holochain conductor _and_ the [`hdi`](https://docs.rs/hdi/latest/hdi) and [`hdk`](https://docs.rs/hdk/latest/hdk) crates, and some of the functions also need other Holochain features enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki` enabled; see the list above). If you want to use them, you'll need to edit your zome crates' `Cargo.toml` files and make sure that users are running your custom conductor binary with the right features enabled. If you compile your zomes without `unstable-functions` enabled, users with the flag(s) enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag(s) disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled. ## Zome call signing @@ -57,11 +55,11 @@ Signing a zome call payload was previously hard to get right, because the conduc Now the payload must be serialized and signed in the client, then sent to the conductor along with the signature. The conductor will now check the signature against the _serialized_ payload before deserializing. -This is a BREAKING change for the `CallZome` app API endpoint. If you're using the JavaScript or Rust client lib, you don't need to make any code changes [TODO is this right?]; just update the client lib to v?? (JavaScript) TODO or v?? (Rust) TODO. +This is a BREAKING change for the [`CallZome`](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/enum.AppRequest.html#variant.CallZome) app API endpoint. If you're using the JavaScript or Rust client lib, you don't need to make any code changes; just update the client lib to [v0.18.0 (JavaScript)](https://github.com/holochain/holochain-client-js/releases/tag/v0.18.0-rc.0) or [v0.6.0 (Rust)](https://github.com/holochain/holochain-client-rust/releases/tag/v0.6.0-dev.9). -If you're a client library author, take a look at the new app API endpoint documentation TODO. +If you're a client library author, take a look at the [documentation for the new input data structure]() for the `CallZome` app API endpoint. -## DHT sharding is disabled by default +## [DHT sharding](/concepts/4_dht/) is disabled by default This feature needs more performance and correctness testing before it's production-ready. With the `unstable-sharding` feature flag disabled by default, your conductor config's `gossip_arc_clamping` must now be set to either `"full"` or `"empty"`, and the previous default `"none"` will cause a conductor startup error. `"gossip_dynamic_arcs"` is also ignored. @@ -69,13 +67,13 @@ It's unknown exactly what might happen if nodes with DHT sharding disabled try t ## Raw hash constructor function rename -`holo_hash::HoloHash::from_raw_39_panicky` has been renamed to `from_raw_39`. Its behavior is otherwise the same. There are two new functions in the same impl, `try_from_raw_39` and `try_from_raw_36_and_type`, which return errors instead of panicking. +`holo_hash::HoloHash::from_raw_39_panicky` has been renamed to [`from_raw_39`](). Its behavior is otherwise the same. There are two new functions in the same impl, `try_from_raw_39` and `try_from_raw_36_and_type`, which return errors instead of panicking. ## `OpenChain` and `CloseChain` actions changed -If you're one of the rare folks who have been using these two actions, the structs have changed. `CloseChain::new_dna_hash` has been replaced with [`new_target`](TODO), which has a type of `Option`. This new type TODO is an enum of `Dna(DnaHash)` or `Agent(AgentHash)`. +If you're one of the rare folks who have been using these two actions, the structs have changed. `CloseChain::new_dna_hash` has been replaced with [`new_target`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.CloseChain.html), which has a type of `Option`. [This new type](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/prelude/enum.MigrationTarget.html) is an enum of `Dna(DnaHash)` or `Agent(AgentHash)`. -`OpenChain::prev_dna_hash` has been changed to match; its type is a non-optional `MigrationTarget`. It also gets a new field, `close_hash`, which is the `ActionHash` of the corresponding `CloseChain` action. +[`OpenChain::prev_dna_hash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.OpenChain.html) has been changed to match; its type is a non-optional `MigrationTarget`. It also gets a new field, `close_hash`, which is the `ActionHash` of the corresponding `CloseChain` action. ## Dynamic database encryption, folder structure changes @@ -85,21 +83,21 @@ The database names have also changed; any file prefix that matches the folder it ## `InstallApp` agent key is optional -The `agent_key` field in the `InstallApp` payload is now optional, and a key will be generated if you don't supply one. If your app is used to generating agent keys and supplying them on install, you shouldn't need to change your code; just update the client library and it'll work. +The `agent_key` field in the [`InstallApp` payload](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/struct.InstallAppPayload.html) is now optional, and a key will be generated if you don't supply one. If your app is used to generating agent keys and supplying them on install, you shouldn't need to change your code; just update the client library and it'll work. ## `CloneCellId` changes -[TODO link] The `CloneCellId::CellId` enum variant has become `DnaHash` and contains, naturally, a `DnaHash` value. This type is used when enabling, disabling, or deleting clones from the app API or a coordinator zome. +The `CloneCellId::CellId` enum variant has become [`DnaHash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/clone/enum.CloneCellId.html) and contains, naturally, a `DnaHash` value. This type is used when enabling, disabling, or deleting clones from the app API or a coordinator zome. ## `CountersigningSuccess` information changed The `CountersigningSuccess` signal sent to the client now gives the action hash of the successful countersigned commit rather than its entry hash. -## New data in `AppInfo` response +## New data in [`AppInfo` response](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/struct.AppInfo.html) -Holochain 0.4 introduces a new flow for app installation that lets an agent supply a membrane proof later with a new `ProvideMemProof` endpoint (TODO link). This allows them to get their freshly generated agent key, submit it to some sort of membrane proof service, and get a membrane proof. +Holochain 0.4 introduces a new flow for app installation that lets an agent supply a membrane proof later with a new [`ProvideMemproofs` endpoint](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/enum.AppRequest.html#variant.ProvideMemproofs). This allows them to get their freshly generated agent key, submit it to some sort of membrane proof service, and get a membrane proof. -Because of this, the [`DisabledReason` enum](TODO), after the membrane proof has been provided, will be a new `NotStartedAfterProvidingMemproofs` variant until the app is started. +Because of this, after the membrane proof has been provided, the [`DisabledAppReason`](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/enum.DisabledAppReason.html) enum, used in the [`AppInfo`](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/struct.AppInfo.html) response, will be a new `NotStartedAfterProvidingMemproofs` variant until the app is started. ## WebRTC signalling server change @@ -107,7 +105,7 @@ The old signalling server has been replaced with a new one called [`sbd`](https: ## Deprecated validation op functionality removed -In your integrity zome's validation functions, you deal with DHT operations, or ops. They are somewhat complex, so `FlatOp` was introduced to make things simpler. It was originally called `OpType`, and until now that old name was a deprecated alias of `FlatOp`. The old type has finally been removed, along with the `Op::to_type` method (use `Op::flattened` instead). +In your integrity zome's validation functions, you deal with DHT operations, or ops. They are somewhat complex, so [`FlatOp`](https://docs.rs/hdi/latest/hdi/flat_op/enum.FlatOp.html) was introduced to make things simpler. It was originally called `OpType`, and until now that old name was a deprecated alias of `FlatOp`. The old type has finally been removed, along with the `Op::to_type` method (use [`OpHelper::flattened`](https://docs.rs/hdi/latest/hdi/op/trait.OpHelper.html#tymethod.flattened) instead). ## Change in enum serialization From 466caff32cad61f8f3559b347d5db8c983bf7757 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 9 Dec 2024 15:38:23 -0800 Subject: [PATCH 11/44] remove holo_hash change from 0.4 upgrade guide --- .../resources/upgrade/upgrade-holochain-0.4.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 1e872fb8c..ea3206a7d 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -13,7 +13,6 @@ NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment Here are all the breaking changes you need to know about in order to update your app for Holochain 0.4: * Some unstable features are now behind feature flags. -* Zome call payloads are built and signed differently. * The `OpenChain` and `CloseChain` actions have been modified. * The database encryption scheme has changed, and the directory structure has moved around. * The `InstallApp` admin API endpoint has had its request payload changed. @@ -49,26 +48,12 @@ Read the [Holonix readme](https://github.com/holochain/holonix?tab=readme-ov-fil `unstable-functions` is a flag used by both the Holochain conductor _and_ the [`hdi`](https://docs.rs/hdi/latest/hdi) and [`hdk`](https://docs.rs/hdk/latest/hdk) crates, and some of the functions also need other Holochain features enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki` enabled; see the list above). If you want to use them, you'll need to edit your zome crates' `Cargo.toml` files and make sure that users are running your custom conductor binary with the right features enabled. If you compile your zomes without `unstable-functions` enabled, users with the flag(s) enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag(s) disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled. -## Zome call signing - -Signing a zome call payload was previously hard to get right, because the conductor would deserialize and reserialize the signed payload before checking the signature. Sometimes the client would order the payload's fields differently from the conductor, which would cause the signature to look invalid. - -Now the payload must be serialized and signed in the client, then sent to the conductor along with the signature. The conductor will now check the signature against the _serialized_ payload before deserializing. - -This is a BREAKING change for the [`CallZome`](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/enum.AppRequest.html#variant.CallZome) app API endpoint. If you're using the JavaScript or Rust client lib, you don't need to make any code changes; just update the client lib to [v0.18.0 (JavaScript)](https://github.com/holochain/holochain-client-js/releases/tag/v0.18.0-rc.0) or [v0.6.0 (Rust)](https://github.com/holochain/holochain-client-rust/releases/tag/v0.6.0-dev.9). - -If you're a client library author, take a look at the [documentation for the new input data structure]() for the `CallZome` app API endpoint. - ## [DHT sharding](/concepts/4_dht/) is disabled by default This feature needs more performance and correctness testing before it's production-ready. With the `unstable-sharding` feature flag disabled by default, your conductor config's `gossip_arc_clamping` must now be set to either `"full"` or `"empty"`, and the previous default `"none"` will cause a conductor startup error. `"gossip_dynamic_arcs"` is also ignored. It's unknown exactly what might happen if nodes with DHT sharding disabled try to gossip in the same network as nodes without DHT sharding. Presumably this is still possible, but it might cause unexpected behaviors! -## Raw hash constructor function rename - -`holo_hash::HoloHash::from_raw_39_panicky` has been renamed to [`from_raw_39`](). Its behavior is otherwise the same. There are two new functions in the same impl, `try_from_raw_39` and `try_from_raw_36_and_type`, which return errors instead of panicking. - ## `OpenChain` and `CloseChain` actions changed If you're one of the rare folks who have been using these two actions, the structs have changed. `CloseChain::new_dna_hash` has been replaced with [`new_target`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.CloseChain.html), which has a type of `Option`. [This new type](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/prelude/enum.MigrationTarget.html) is an enum of `Dna(DnaHash)` or `Agent(AgentHash)`. From 2e1df563f3863c7eb90e2c9cd3b855bf2c59039f Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Tue, 10 Dec 2024 10:29:51 -0800 Subject: [PATCH 12/44] fix broken link --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index ea3206a7d..5cd3451f3 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -5,7 +5,7 @@ title: Holochain Upgrade 0.3 → 0.4 ::: intro For existing hApps that were written for Holochain 0.3, here's the guide to get you upgraded to 0.4. -NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment, has also been updated. We recommend you [upgrade to the new Holonix](/resources/upgrade-new-holonix/) at the same time! +NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment, has also been updated. We recommend you [upgrade to the new Holonix](/resources/upgrade/upgrade-new-holonix/) at the same time! ::: ## Summary From 12ab014ce0f15a44ead2352230929e18ed77eedc Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 12 Dec 2024 13:14:53 -0800 Subject: [PATCH 13/44] rewrite 0.4 upgrade guide to focus on howto --- .../upgrade/upgrade-holochain-0.4.md | 401 ++++++++++++++++-- 1 file changed, 362 insertions(+), 39 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 5cd3451f3..411c6ae43 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -8,22 +8,132 @@ For existing hApps that were written for Holochain 0.3, here's the guide to get NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment, has also been updated. We recommend you [upgrade to the new Holonix](/resources/upgrade/upgrade-new-holonix/) at the same time! ::: -## Summary +## Quick instructions -Here are all the breaking changes you need to know about in order to update your app for Holochain 0.4: +To upgrade your hApp written for Holochain 0.3, follow these steps: -* Some unstable features are now behind feature flags. -* The `OpenChain` and `CloseChain` actions have been modified. -* The database encryption scheme has changed, and the directory structure has moved around. -* The `InstallApp` admin API endpoint has had its request payload changed. -* `CloneCellId`, used as an input argument to clone manipulation functions, has changed. -* The `CountersigningSuccess` signal supplies the action hash, not the entry hash. -* The `AppInfo` admin endpoint's response contains new statuses related to deferred memproofs. -* The WebRTC signalling server architecture has changed, along with new server addresses and self-hosted server binaries. -* Deprecated `OpType` and `op::to_type` have been removed from the HDI. -* Enums are serialized differently. +1. Follow the [Holonix upgrade guide](/resources/upgrade/upgrade-new-holonix/) to update to the newest Holonix command-line developer environment (we're dropping support for the old Holonix in the 0.4 series). +2. Update your project's package dependencies ([see below](#update-your-package-depencencies)). +3. Enter the project's Holonix shell by navigating to the project's root folder and entering: + + ```shell + nix develop + ``` + +3. Try running your tests: + + ```shell + npm test + ``` + + and starting the application: + + ```shell + npm start + ``` + +4. You'll likely see error messages due to breaking changes, either at compile time or test/run time. Follow the [breaking change update instructions](#update-your-application-code) below to get your code working again. +5. Be aware of some changes that won't break your app but may affect its runtime behavior. Read the [guide at the bottom](#subtle-changes). + +## Update your package dependencies + +### Rust + +Update the `hdk` and `hdi` version strings in the project's root `Cargo.toml` file: + +```diff:toml + [workspace.dependencies] +-hdi = "=0.4.6" +-hdk = "=0.3.6" ++hdi = "=0.5.0-rc.1" ++hdk = "=0.4.0-rc.1" + serde = "1.0" +``` + +Once you've updated your `Cargo.toml` you need to update your `Cargo.lock` and check whether your project can still build. To do this in one step you can run: + +```shell +cargo build +``` + +### (Optional) Update other Rust dependencies + +Running a Cargo build, like suggested above, will update as few dependencies as it can. This is good for stability because it's just making the changes you asked for. However, sometimes you do need to update other dependencies to resolve build issues. + +This section is marked as optional because it's possible that new dependencies could introduce new issues as well as fixing existing conflicts or problems. To make it possible to roll back this change, it might be a good idea to commit the changes you've made so far to source control. Then you can run: + +```shell +cargo update +``` + +This will update your `Cargo.lock` with the latest versions of all libraries that the constraints in your `Cargo.toml` files will allow. Now you should try building your project again to see if that has resolved your issue. + +### JavaScript tooling + +If you've created your hApp using our scaffolding tool, you should be able to follow these instructions. If you've created your own project folder layout, adapt these instructions to fit. + +Edit your project's root `package.json` file to update the developer tools: + +```diff:json + "devDependencies": { + "@holochain-playground/cli": "^0.300.1", +- "@holochain/hc-spin": "0.300.3", ++ "@holochain/hc-spin": "^0.400.0-dev.3", + // more dependencies + }, +``` + +Then run your package manager's update command to update the lockfile and install new package versions. Use the command that matches your chosen package manager: + +```shell +bun update +``` +```shell +npm update +``` +```shell +pnpm update +``` +```shell +yarn upgrade +``` + +### Tryorama tests + +Edit your project's `tests/package.json` file: + +```diff:json + "dependencies": { + // some dependencies +- "@holochain/client": "^0.17.1", +- "@holochain/tryorama": "^0.16.0", ++ "@holochain/client": "^0.18.0-rc.1", ++ "@holochain/tryorama": "^0.17.0-rc.0", + // more dependencies + }, +``` + +Then navigate to the `tests/` folder and run your package manager's update command like you did at the project's top level in the last step. + +### UI + +You'll update the UI package dependencies similarly to the test package. Edit `ui/package.json`: + +```diff:json + "dependencies": { +- "@holochain/client": "^0.17.1", ++ "@holochain/client": "^0.18.0-rc.1", + // more dependencies + }, +``` + +Then run navigate to the `ui/` folder and run your package manager's update command. + +## Update your application code -## Unstable features removed by default +Here are all the breaking changes you need to know about in order to update your app for Holochain 0.4. + +### Unstable features removed by default The biggest change for 0.4 is that some unstable features aren't compiled into official Holochain releases by default. We're doing this to focus on a stable core Holochain with the minimal feature set that most projects need. The removed features are still available as Rust feature flags, so you can compile a custom Holochain binary if you need them. Here's the full list, along with their feature flags: @@ -44,57 +154,245 @@ The biggest change for 0.4 is that some unstable features aren't compiled into o * [`schedule`](https://github.com/holochain/holochain/blob/holochain-0.4.0-rc.2/crates/hdk/src/time.rs#L67-L137) * An unimplemented `sleep` function has been removed completely -Read the [Holonix readme](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) to find out how to compile a custom Holochain build with these flags enabled. +`unstable-functions` is a flag used by both the Holochain conductor _and_ the [`hdi`](https://docs.rs/hdi/latest/hdi) and [`hdk`](https://docs.rs/hdk/latest/hdk) crates, and some of the functions also need other Holochain features enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki` enabled; see the list above). -`unstable-functions` is a flag used by both the Holochain conductor _and_ the [`hdi`](https://docs.rs/hdi/latest/hdi) and [`hdk`](https://docs.rs/hdk/latest/hdk) crates, and some of the functions also need other Holochain features enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki` enabled; see the list above). If you want to use them, you'll need to edit your zome crates' `Cargo.toml` files and make sure that users are running your custom conductor binary with the right features enabled. If you compile your zomes without `unstable-functions` enabled, users with the flag(s) enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag(s) disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled. +#### Enabling in Holochain runtime -## [DHT sharding](/concepts/4_dht/) is disabled by default +Read the [Holonix readme](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) to find out how to enter a development shell with a custom-compiled Holochain build with these flags enabled. -This feature needs more performance and correctness testing before it's production-ready. With the `unstable-sharding` feature flag disabled by default, your conductor config's `gossip_arc_clamping` must now be set to either `"full"` or `"empty"`, and the previous default `"none"` will cause a conductor startup error. `"gossip_dynamic_arcs"` is also ignored. +If you're using Holochain as a library in your project, edit your `Cargo.toml` file's `holochain` dependency to enable the flags. Here's an example that enables countersigning: -It's unknown exactly what might happen if nodes with DHT sharding disabled try to gossip in the same network as nodes without DHT sharding. Presumably this is still possible, but it might cause unexpected behaviors! +```diff:toml + [dependencies] +-holochain = { version = "0.3.6" } + # "unstable-functions" is needed in order for coordinator zomes to call the + # host functions related to countersigning. ++holochain = { version = "0.4.0-rc.2", features = ["unstable-countersigning", "unstable-functions"] } +``` -## `OpenChain` and `CloseChain` actions changed +#### Enabling in your zomes -If you're one of the rare folks who have been using these two actions, the structs have changed. `CloseChain::new_dna_hash` has been replaced with [`new_target`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.CloseChain.html), which has a type of `Option`. [This new type](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/prelude/enum.MigrationTarget.html) is an enum of `Dna(DnaHash)` or `Agent(AgentHash)`. +If you want to use unstable features in your zomes, you'll need to edit your zome crates' `Cargo.toml` files. For coordinator zomes: -[`OpenChain::prev_dna_hash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.OpenChain.html) has been changed to match; its type is a non-optional `MigrationTarget`. It also gets a new field, `close_hash`, which is the `ActionHash` of the corresponding `CloseChain` action. +```diff:toml + [dependencies] +-hdk = { workspace = true } ++hdk = { workspace = true, features = ["unstable-functions"] } +``` -## Dynamic database encryption, folder structure changes +And for integrity zomes: -Previous conductor and keystore SQLite databases used a hardcoded encryption key; v0.4 now uses a dynamic key. This means you won't be able to import data from v0.3. +```diff:toml + [dependencies] +-hdk = { workspace = true } ++hdk = { workspace = true, features = ["unstable-functions"] } +``` -The database names have also changed; any file prefix that matches the folder it's in (e.g., `/authorized/authorized--.sqlite`) is dropped, along with the `.sqlite` file extension. +and make sure that users are running your custom conductor binary with the right features enabled ([see above](#enabling-in-holochain-runtime)). If you compile your zomes without `unstable-functions` enabled, users with the flag enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag(s) disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled (e.g., to use countersigning, the conductor must have `unstable-countersigning` enabled, along with `unstable-functions`). -## `InstallApp` agent key is optional +### `OpenChain` and `CloseChain` actions changed -The `agent_key` field in the [`InstallApp` payload](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/struct.InstallAppPayload.html) is now optional, and a key will be generated if you don't supply one. If your app is used to generating agent keys and supplying them on install, you shouldn't need to change your code; just update the client library and it'll work. +If you're one of the rare folks who have been using these two actions, the structs have changed. Take a look at the Rustdoc and update your code accordingly: -## `CloneCellId` changes +* `CloseChain::new_dna_hash` has been replaced with [`new_target`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.CloseChain.html), which has a type of `Option`. [This new type](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/prelude/enum.MigrationTarget.html) is an enum of `Dna(DnaHash)` or `Agent(AgentHash)`. -The `CloneCellId::CellId` enum variant has become [`DnaHash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/clone/enum.CloneCellId.html) and contains, naturally, a `DnaHash` value. This type is used when enabling, disabling, or deleting clones from the app API or a coordinator zome. +* [`OpenChain::prev_dna_hash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.OpenChain.html) has been changed to match; its type is a non-optional `MigrationTarget`. It also gets a new field, `close_hash`, which is the `ActionHash` of the corresponding `CloseChain` action. -## `CountersigningSuccess` information changed +### `InstallApp` agent key is optional -The `CountersigningSuccess` signal sent to the client now gives the action hash of the successful countersigned commit rather than its entry hash. +!!! info +This change is only relevant if you're building a runtime that can install hApp bundles. +!!! -## New data in [`AppInfo` response](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/struct.AppInfo.html) +The `agent_key` field in the [`InstallApp` payload](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/struct.InstallAppPayload.html) is now optional, and a key will be generated if you don't supply one. -Holochain 0.4 introduces a new flow for app installation that lets an agent supply a membrane proof later with a new [`ProvideMemproofs` endpoint](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/enum.AppRequest.html#variant.ProvideMemproofs). This allows them to get their freshly generated agent key, submit it to some sort of membrane proof service, and get a membrane proof. +If you're using the JavaScript client to interact with the conductor, [update the JS client lib](#ui) and test it --- you shouldn't need to change any code. -Because of this, after the membrane proof has been provided, the [`DisabledAppReason`](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/enum.DisabledAppReason.html) enum, used in the [`AppInfo`](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/struct.AppInfo.html) response, will be a new `NotStartedAfterProvidingMemproofs` variant until the app is started. +If you're using the Rust client, first update the Rust client lib, then update your code. Edit your UI project's `Cargo.toml` file: -## WebRTC signalling server change +```diff:toml + [dependencies] +-holochain_client = "0.5.3" ++holochain_client = "0.6.0-rc.0" +``` -The old signalling server has been replaced with a new one called [`sbd`](https://github.com/holochain/sbd/). If you're hosting your own server, switch to a [new `sbd` server binary](https://github.com/holochain/sbd/tags). If you're using Holo's public infrastructure, switch from `wss://signal.holo.host` to `wss://sbd-0.main.infra.holo.host` in your conductor config file. (The new URL will automatically be in any conductor config generated by the dev tools for 0.4.) +Then edit anywhere in your Rust code that uses the `install_app` function: + +```diff:rust + use holochain_client::*; + + fn install_app() -> Result<()> { + let admin_ws = AdminWebsocket::connect((Ipv4Addr::LOCALHOST, 30_000)).await? + // ... set up arguments + let input_payload = InstallAppPayload { + app_bundle_source, +- agent_key, ++ Some(agent_key), + Some(installed_app_id), + membrane_proofs, + Some(network_seed), + }; + let response = admin_ws.install_app(input_payload).await?; + // ... do things + Ok() + } +``` -## Deprecated validation op functionality removed +### `CloneCellId` changes + +The `CloneCellId::CellId` enum variant has become [`DnaHash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/clone/enum.CloneCellId.html) and contains, naturally, a `DnaHash` value. This type is used when enabling, disabling, or deleting clones from the app API or a coordinator zome. + +#### In coordinator zomes + +Edit any coordinator zome code that uses functions from `hdk::clone`: + +```diff:rust + use hdk::prelude::*; + + fn create_chat_room(name: string) -> ExternResult { + // ... set up cell_id + let create_input = CreateCloneCellInput { + cell_id, + None, + name, + }; + let cloned_cell = create_clone_cell(create_input).await?; + let enable_input = EnableCloneCellInput { +- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), ++ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), + }; + enable_clone_cell(enable_input).await?; + cloned_cell.cell_id + } + + fn remove_chat_room(cell_id: CellId) -> ExternResult<()> { + let disable_input = DisableCloneCellInput { +- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), ++ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), + }; + disable_clone_cell(disable_input).await?; + let delete_input = DeleteCloneCellInput { +- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), ++ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), + }; + delete_clone_cell(delete_input).await? + } +``` + +#### In JavaScript front-end + +Edit any client code that manipulates cloned cells: + +```diff:typescript + import { AppWebsocket, CellId } from "@holochain/client"; + + let client: AppClient = await AppWebsocket.connect(); + let role_name = "chat"; + + function createChatRoom(name: String) { + const clonedCell = await client.createCloneCell({ + modifiers: {}, + role_name + }); + await client.enableCloneCell({ +- clone_cell_id: cloned_cell.cell_id, ++ clone_cell_id: cloned_cell.cell_id[0], + }); + return clonedCell.cell_id; + } + + function removeChatRoom(cell_id: CellId) { + await client.disableCloneCell({ +- clone_cell_id: cell_id, ++ clone_cell_id: cell_id[0], + }); + await client.deleteCloneCell({ +- clone_cell_id: cell_id, ++ clone_cell_id: cell_id[0], + }); + } +``` + +#### In Rust front-end + +Edit any client code that manipulates cloned cells: + +```diff:rust + use holochain_client::*; + + async fn connect_to_client() -> Result { + AppWebsocket::connect((Ipv4Addr::LOCALHOST, 30_000)).await? + } + + async fn create_chat_room(name: String) -> Result { + let app = connect_to_client().await?; + // ... set up arguments + let create_payload = CreateCloneCellPayload { + role_name, + modifiers, + none, + Some(name), + }; + let cloned_cell = app.create_clone_cell(input_payload).await?; + let enable_payload = EnableCloneCellPayload { +- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), ++ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), + }; + app.enable_clone_cell(enable_payload).await? + Ok(cloned_cell.cell_id) + } + + fn remove_chat_room(cell_id: CellId) -> Result<()> { + let app = connect_to_client().await?; + let disable_payload = DisableCloneCellPayload { +- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), ++ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), + }; + app.disable_clone_cell(disable_payload).await?; + let delete_payload = DeleteCloneCellPayload { +- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), ++ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), + }; + app.delete_clone_cell(delete_payload).await? + } +``` + +### Deprecated validation op functionality removed In your integrity zome's validation functions, you deal with DHT operations, or ops. They are somewhat complex, so [`FlatOp`](https://docs.rs/hdi/latest/hdi/flat_op/enum.FlatOp.html) was introduced to make things simpler. It was originally called `OpType`, and until now that old name was a deprecated alias of `FlatOp`. The old type has finally been removed, along with the `Op::to_type` method (use [`OpHelper::flattened`](https://docs.rs/hdi/latest/hdi/op/trait.OpHelper.html#tymethod.flattened) instead). -## Change in enum serialization +In your integrity zome, any time you use `Op::to_type`, change it like this: + +```diff:rust + #[hdk_extern] + pub fn validate(op: Op) -> ExternResult { +- match op.to_type::<(), ()>()? { ++ match op.flattened::<(), ()>()? { +- OpType::StoreEntry(store_entry) => { ++ FlatOp::StoreEntry(store_entry) => { + // do things + } +- OpType::RegisterUpdate(update_entry) => { ++ FlatOp::RegisterUpdate(update_entry) => { + // do things + } + // etc + _ => Ok(ValidateCallbackResult::Valid), + } + } +``` + +### New data in [`AppInfo` response](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/struct.AppInfo.html) -The default serialization for bare enum variants has changed. Previously, they would look like this (JSON representation): +Holochain 0.4 introduces a new flow for app installation that lets an agent supply a membrane proof later with a new [`ProvideMemproofs` endpoint](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/enum.AppRequest.html#variant.ProvideMemproofs). This allows them to get their freshly generated agent key, submit it to some sort of membrane proof service, and get a membrane proof. + +Because of this, after the membrane proof has been provided, the [`DisabledAppReason`](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/enum.DisabledAppReason.html) enum, used in the [`AppInfo`](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/struct.AppInfo.html) response, will be a new `NotStartedAfterProvidingMemproofs` variant until the app is started. + +The only change you should need to make to existing code is to make sure you're handling this new variant in your `match` blocks (Rust) or `switch` blocks (JavaScript). + +### Change in enum serialization + +The default serialization for bare (no-data) enum variants has changed. Previously, they would look like this (JSON representation): ```json { @@ -108,4 +406,29 @@ Now they look like this: "variant1" ``` -(Enum variants with data still follow the `{ "variant": }` pattern.) \ No newline at end of file +(Enum variants with data still follow the `{ "variant": }` pattern.) + +This will affect any entries or entry fields that start as instances of a Rust enum and are sent to the front end. If your front end is written in JavaScript, you'll need to be aware of this and update your front-end models to match. If your front end is written in Rust, you're likely defining your entry types in a separate module that you're importing directly into the client, which will handle proper deserialization for you. + +### `CountersigningSuccess` information changed + +The `CountersigningSuccess` signal sent to the client now gives the action hash of the successful countersigned commit rather than its entry hash. In your client code, whether JavaScript or Rust, update your signal handler to deal with a `HoloHash` rather than a `HoloHash` when it receives this kind of signal. + +* The database encryption scheme has changed, and the directory structure has moved around. +* The WebRTC signalling server architecture has changed, along with new server addresses and self-hosted server binaries. + +### WebRTC signalling server change + +The old signalling server has been replaced with a new one called [`sbd`](https://github.com/holochain/sbd/). If you're hosting your own server, switch to a [new `sbd` server binary](https://github.com/holochain/sbd/tags). If you're using Holo's public infrastructure, switch from `wss://signal.holo.host` to `wss://sbd-0.main.infra.holo.host` in your conductor config file. (The new URL will automatically be in any conductor config generated by the dev tools for 0.4.) + +## Subtle changes + +### [DHT sharding](/concepts/4_dht/) is disabled by default + +This feature needs more performance and correctness testing before it's production-ready, but it can be turned on by [compiling Holochain with the `unstable-sharding` flag enabled](#enabling-in-holochain-runtime). + +It's unknown exactly what might happen if nodes with DHT sharding disabled try to gossip in the same network as nodes without DHT sharding. Presumably this is still possible, but it might cause unexpected behaviors! + +### Dynamic database encryption, folder structure changes + +Previous conductor and keystore SQLite databases used a hardcoded encryption key; v0.4 now uses a dynamic key. Additionally, the database paths have changed. These two things mean you won't be able to import data from v0.3. \ No newline at end of file From b4abd043654d83541ae9e6b6482e2bd2a8b6287b Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 12 Dec 2024 13:22:40 -0800 Subject: [PATCH 14/44] fix broken fragment identifier --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 411c6ae43..fa0572420 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -13,7 +13,7 @@ NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment To upgrade your hApp written for Holochain 0.3, follow these steps: 1. Follow the [Holonix upgrade guide](/resources/upgrade/upgrade-new-holonix/) to update to the newest Holonix command-line developer environment (we're dropping support for the old Holonix in the 0.4 series). -2. Update your project's package dependencies ([see below](#update-your-package-depencencies)). +2. Update your project's package dependencies ([see below](#update-your-package-dependencies)). 3. Enter the project's Holonix shell by navigating to the project's root folder and entering: ```shell From 771ea2ced5aa0b53ba5f7c423148e5921a6f0c93 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 12 Dec 2024 13:37:34 -0800 Subject: [PATCH 15/44] change Holonix upgrade recommendation to insistence --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index fa0572420..686f48427 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -5,7 +5,7 @@ title: Holochain Upgrade 0.3 → 0.4 ::: intro For existing hApps that were written for Holochain 0.3, here's the guide to get you upgraded to 0.4. -NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment, has also been updated. We recommend you [upgrade to the new Holonix](/resources/upgrade/upgrade-new-holonix/) at the same time! +NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment, has also been updated. We're no longer supporting the old Holonix for Holochain 0.4 and beyond, so you'll need to [upgrade to the new Holonix](/resources/upgrade/upgrade-new-holonix/) at the same time! ::: ## Quick instructions From c698552370267ec2b9cd7fd0c9551696b2c4beea Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 12 Dec 2024 13:40:17 -0800 Subject: [PATCH 16/44] clean up stuff that shouldn't have been there --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 686f48427..e4629ab45 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -414,9 +414,6 @@ This will affect any entries or entry fields that start as instances of a Rust e The `CountersigningSuccess` signal sent to the client now gives the action hash of the successful countersigned commit rather than its entry hash. In your client code, whether JavaScript or Rust, update your signal handler to deal with a `HoloHash` rather than a `HoloHash` when it receives this kind of signal. -* The database encryption scheme has changed, and the directory structure has moved around. -* The WebRTC signalling server architecture has changed, along with new server addresses and self-hosted server binaries. - ### WebRTC signalling server change The old signalling server has been replaced with a new one called [`sbd`](https://github.com/holochain/sbd/). If you're hosting your own server, switch to a [new `sbd` server binary](https://github.com/holochain/sbd/tags). If you're using Holo's public infrastructure, switch from `wss://signal.holo.host` to `wss://sbd-0.main.infra.holo.host` in your conductor config file. (The new URL will automatically be in any conductor config generated by the dev tools for 0.4.) From f89af9d927410de27aecddf53f76c6cf99e31df4 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 12 Dec 2024 13:42:20 -0800 Subject: [PATCH 17/44] move things around --- .../resources/upgrade/upgrade-holochain-0.4.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index e4629ab45..79ee29515 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -414,10 +414,6 @@ This will affect any entries or entry fields that start as instances of a Rust e The `CountersigningSuccess` signal sent to the client now gives the action hash of the successful countersigned commit rather than its entry hash. In your client code, whether JavaScript or Rust, update your signal handler to deal with a `HoloHash` rather than a `HoloHash` when it receives this kind of signal. -### WebRTC signalling server change - -The old signalling server has been replaced with a new one called [`sbd`](https://github.com/holochain/sbd/). If you're hosting your own server, switch to a [new `sbd` server binary](https://github.com/holochain/sbd/tags). If you're using Holo's public infrastructure, switch from `wss://signal.holo.host` to `wss://sbd-0.main.infra.holo.host` in your conductor config file. (The new URL will automatically be in any conductor config generated by the dev tools for 0.4.) - ## Subtle changes ### [DHT sharding](/concepts/4_dht/) is disabled by default @@ -428,4 +424,12 @@ It's unknown exactly what might happen if nodes with DHT sharding disabled try t ### Dynamic database encryption, folder structure changes -Previous conductor and keystore SQLite databases used a hardcoded encryption key; v0.4 now uses a dynamic key. Additionally, the database paths have changed. These two things mean you won't be able to import data from v0.3. \ No newline at end of file +Previous conductor and keystore SQLite databases used a hardcoded encryption key; v0.4 now uses a dynamic key. Additionally, the database paths have changed. These two things mean you won't be able to import data from v0.3. + +### WebRTC signalling server change + +!!! info +This is only relevant if you're maintaining your own infrastructure or building your own runtime. +!!! + +The old signalling server has been replaced with a new one called [`sbd`](https://github.com/holochain/sbd/). If you're hosting your own server, switch to a [new `sbd` server binary](https://github.com/holochain/sbd/tags). If you're using Holo's public infrastructure, switch from `wss://signal.holo.host` to `wss://sbd-0.main.infra.holo.host` in your conductor config file. (The new URL will automatically be in any conductor config generated by the dev tools for 0.4.) From e86b98f76bd0558d878fb37f6fc65cd7be58f186 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 12 Dec 2024 13:44:40 -0800 Subject: [PATCH 18/44] remove thing about updating UI and test folder packages --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 79ee29515..d217a5c36 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -113,8 +113,6 @@ Edit your project's `tests/package.json` file: }, ``` -Then navigate to the `tests/` folder and run your package manager's update command like you did at the project's top level in the last step. - ### UI You'll update the UI package dependencies similarly to the test package. Edit `ui/package.json`: @@ -127,8 +125,6 @@ You'll update the UI package dependencies similarly to the test package. Edit `u }, ``` -Then run navigate to the `ui/` folder and run your package manager's update command. - ## Update your application code Here are all the breaking changes you need to know about in order to update your app for Holochain 0.4. From 2fc913323199329bf0c169dc7a3c2f57a7838183 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 12 Dec 2024 13:46:08 -0800 Subject: [PATCH 19/44] Add Jost's suggestions Co-authored-by: jost-s <28270981+jost-s@users.noreply.github.com> --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index d217a5c36..a0cb7d8e9 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -180,8 +180,8 @@ And for integrity zomes: ```diff:toml [dependencies] --hdk = { workspace = true } -+hdk = { workspace = true, features = ["unstable-functions"] } +-hdi = { workspace = true } ++hdi = { workspace = true, features = ["unstable-functions"] } ``` and make sure that users are running your custom conductor binary with the right features enabled ([see above](#enabling-in-holochain-runtime)). If you compile your zomes without `unstable-functions` enabled, users with the flag enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag(s) disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled (e.g., to use countersigning, the conductor must have `unstable-countersigning` enabled, along with `unstable-functions`). @@ -388,7 +388,7 @@ The only change you should need to make to existing code is to make sure you're ### Change in enum serialization -The default serialization for bare (no-data) enum variants has changed. Previously, they would look like this (JSON representation): +The default serialization for unit-like enum variants has changed. Previously, they would look like this (JSON representation): ```json { From f0b96d4df1a03e31e8b71a0d0b685cacd6854e9e Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 12 Dec 2024 14:11:30 -0800 Subject: [PATCH 20/44] simplify language per Jost's suggestion Co-authored-by: jost-s <28270981+jost-s@users.noreply.github.com> --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index a0cb7d8e9..609c24f9b 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -131,7 +131,7 @@ Here are all the breaking changes you need to know about in order to update your ### Unstable features removed by default -The biggest change for 0.4 is that some unstable features aren't compiled into official Holochain releases by default. We're doing this to focus on a stable core Holochain with the minimal feature set that most projects need. The removed features are still available as Rust feature flags, so you can compile a custom Holochain binary if you need them. Here's the full list, along with their feature flags: +The biggest change for 0.4 is that some features are marked `unstable` and aren't compiled into Holochain by default. We're doing this to focus on a stable core Holochain with the minimal feature set that most projects need. The removed features are still available as Rust feature flags, so you can compile a custom Holochain binary if you need them. Here's the full list, along with their feature flags: * **[Countersigning](/concepts/10_countersigning/) `unstable-countersigning`**: Allows agents to temporarily lock their chains in order to agree to write the same entry to their respective chains. * **DPKI / DeepKey `unstable-dpki`**: Implements a distributed public key infrastructure, allowing agents to manage their keys and confirm continuity of their identity across devices and source chains. Read the [DeepKey readme](https://github.com/holochain/deepkey) for more info. From 935d00960da9413159e5198b38176332513cf782 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 12 Dec 2024 14:37:17 -0800 Subject: [PATCH 21/44] clarify language about unstable functions --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 609c24f9b..4e12374a6 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -150,7 +150,12 @@ The biggest change for 0.4 is that some features are marked `unstable` and aren' * [`schedule`](https://github.com/holochain/holochain/blob/holochain-0.4.0-rc.2/crates/hdk/src/time.rs#L67-L137) * An unimplemented `sleep` function has been removed completely -`unstable-functions` is a flag used by both the Holochain conductor _and_ the [`hdi`](https://docs.rs/hdi/latest/hdi) and [`hdk`](https://docs.rs/hdk/latest/hdk) crates, and some of the functions also need other Holochain features enabled (e.g., `is_same_agent` requires a conductor with `unstable-dpki` enabled; see the list above). +**If your DNA needs to call a host function that depends on an unstable feature**, you'll need to do two things: + +1. Build a custom Holochain binary with both the specific feature you need (see the list above) and `unstable-functions` enabled (see the next section). +2. Enable the `unstable-functions` flag for either the `hdi` or `hdk` dependency in your zome's `Cargo.toml` (see the section after the next). + +Note that you'll need to make sure your users are running your custom conductor binary. If you compile your zomes without `unstable-functions` enabled for `hdi` or `hdk`, users with the flag enabled in Holochain will still be able to use your hApp, but if you compile your zomes _with_ `unstable-functions`, users with the flag(s) disabled won't be able to use your hApp. #### Enabling in Holochain runtime @@ -184,8 +189,6 @@ And for integrity zomes: +hdi = { workspace = true, features = ["unstable-functions"] } ``` -and make sure that users are running your custom conductor binary with the right features enabled ([see above](#enabling-in-holochain-runtime)). If you compile your zomes without `unstable-functions` enabled, users with the flag enabled in Holochain will still be able to use your hApp, but if you enable it, users with the flag(s) disabled won't be able to use your hApp. If you use any of the unstable functions, note that the conductor will also need to have the corresponding feature enabled (e.g., to use countersigning, the conductor must have `unstable-countersigning` enabled, along with `unstable-functions`). - ### `OpenChain` and `CloseChain` actions changed If you're one of the rare folks who have been using these two actions, the structs have changed. Take a look at the Rustdoc and update your code accordingly: From 756dbe17d995739b06a8d588607a8783a2b101c2 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Thu, 12 Dec 2024 14:53:48 -0800 Subject: [PATCH 22/44] tiny language clarification --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 4e12374a6..b151a348e 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -153,7 +153,7 @@ The biggest change for 0.4 is that some features are marked `unstable` and aren' **If your DNA needs to call a host function that depends on an unstable feature**, you'll need to do two things: 1. Build a custom Holochain binary with both the specific feature you need (see the list above) and `unstable-functions` enabled (see the next section). -2. Enable the `unstable-functions` flag for either the `hdi` or `hdk` dependency in your zome's `Cargo.toml` (see the section after the next). +2. Enable the `unstable-functions` flag for the `hdi` and `hdk` dependencies in your zomes' `Cargo.toml` (see the section after the next). Note that you'll need to make sure your users are running your custom conductor binary. If you compile your zomes without `unstable-functions` enabled for `hdi` or `hdk`, users with the flag enabled in Holochain will still be able to use your hApp, but if you compile your zomes _with_ `unstable-functions`, users with the flag(s) disabled won't be able to use your hApp. From 360f69e7129e695bd9302c3fa155e89d1e224f10 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 13 Dec 2024 09:25:57 -0800 Subject: [PATCH 23/44] apply ThetaSinner's suggestions --- .../upgrade/upgrade-holochain-0.4.md | 74 +++++-------------- 1 file changed, 17 insertions(+), 57 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index b151a348e..77fb3af06 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -3,18 +3,17 @@ title: Holochain Upgrade 0.3 → 0.4 --- ::: intro -For existing hApps that were written for Holochain 0.3, here's the guide to get you upgraded to 0.4. +For existing hApps that are currently using Holochain 0.3, here's the guide to get you upgraded to 0.4. -NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment, has also been updated. We're no longer supporting the old Holonix for Holochain 0.4 and beyond, so you'll need to [upgrade to the new Holonix](/resources/upgrade/upgrade-new-holonix/) at the same time! +NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment, has also been updated. We're not supporting the old Holonix for Holochain 0.4 and beyond, so you'll need to [upgrade to the new Holonix](/resources/upgrade/upgrade-new-holonix/) at the same time if you haven't already! ::: ## Quick instructions To upgrade your hApp written for Holochain 0.3, follow these steps: -1. Follow the [Holonix upgrade guide](/resources/upgrade/upgrade-new-holonix/) to update to the newest Holonix command-line developer environment (we're dropping support for the old Holonix in the 0.4 series). -2. Update your project's package dependencies ([see below](#update-your-package-dependencies)). -3. Enter the project's Holonix shell by navigating to the project's root folder and entering: +1. Check whether your `flake.nix` contains `github:holochain/holonix`. If it does, then you can continue to the next step. Otherwise it will contain `github:holochain/holochain`. If so, then follow the [Holonix upgrade guide](/resources/upgrade/upgrade-new-holonix/) to update to the newest Holonix command-line developer environment (we're not providing a 0.4 version of Holochain through the old Holonix). +2. Update your `flake.nix` to use the 0.4 version of Holochain by changing the version number in the line `holonix.url = "github:holochain/holonix?ref=main-0.3"` from 0.3 to 0.4. This will take effect later when you enter a new Nix shell. It's important to update your Nix flake lock at this point, to ensure you benefit from the cache we provide: ```shell nix develop @@ -68,7 +67,9 @@ cargo update This will update your `Cargo.lock` with the latest versions of all libraries that the constraints in your `Cargo.toml` files will allow. Now you should try building your project again to see if that has resolved your issue. -### JavaScript tooling +### JavaScript + +#### Command-line tools If you've created your hApp using our scaffolding tool, you should be able to follow these instructions. If you've created your own project folder layout, adapt these instructions to fit. @@ -78,27 +79,12 @@ Edit your project's root `package.json` file to update the developer tools: "devDependencies": { "@holochain-playground/cli": "^0.300.1", - "@holochain/hc-spin": "0.300.3", -+ "@holochain/hc-spin": "^0.400.0-dev.3", ++ "@holochain/hc-spin": "^0.400.0-rc.0", // more dependencies }, ``` -Then run your package manager's update command to update the lockfile and install new package versions. Use the command that matches your chosen package manager: - -```shell -bun update -``` -```shell -npm update -``` -```shell -pnpm update -``` -```shell -yarn upgrade -``` - -### Tryorama tests +#### Tryorama tests Edit your project's `tests/package.json` file: @@ -113,7 +99,7 @@ Edit your project's `tests/package.json` file: }, ``` -### UI +#### UI You'll update the UI package dependencies similarly to the test package. Edit `ui/package.json`: @@ -125,6 +111,12 @@ You'll update the UI package dependencies similarly to the test package. Edit `u }, ``` +Then in your project's root folder, run your package manager's update command to update the lockfile and install new package versions for your command-line tools, tests, and UI. Use the command that matches your chosen package manager. For example, if you're using `npm`: + +```shell +npm update +``` + ## Update your application code Here are all the breaking changes you need to know about in order to update your app for Holochain 0.4. @@ -152,43 +144,11 @@ The biggest change for 0.4 is that some features are marked `unstable` and aren' **If your DNA needs to call a host function that depends on an unstable feature**, you'll need to do two things: -1. Build a custom Holochain binary with both the specific feature you need (see the list above) and `unstable-functions` enabled (see the next section). +1. Build a custom Holochain binary with both the specific feature you need (see the list above) and `unstable-functions` enabled. 2. Enable the `unstable-functions` flag for the `hdi` and `hdk` dependencies in your zomes' `Cargo.toml` (see the section after the next). Note that you'll need to make sure your users are running your custom conductor binary. If you compile your zomes without `unstable-functions` enabled for `hdi` or `hdk`, users with the flag enabled in Holochain will still be able to use your hApp, but if you compile your zomes _with_ `unstable-functions`, users with the flag(s) disabled won't be able to use your hApp. -#### Enabling in Holochain runtime - -Read the [Holonix readme](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) to find out how to enter a development shell with a custom-compiled Holochain build with these flags enabled. - -If you're using Holochain as a library in your project, edit your `Cargo.toml` file's `holochain` dependency to enable the flags. Here's an example that enables countersigning: - -```diff:toml - [dependencies] --holochain = { version = "0.3.6" } - # "unstable-functions" is needed in order for coordinator zomes to call the - # host functions related to countersigning. -+holochain = { version = "0.4.0-rc.2", features = ["unstable-countersigning", "unstable-functions"] } -``` - -#### Enabling in your zomes - -If you want to use unstable features in your zomes, you'll need to edit your zome crates' `Cargo.toml` files. For coordinator zomes: - -```diff:toml - [dependencies] --hdk = { workspace = true } -+hdk = { workspace = true, features = ["unstable-functions"] } -``` - -And for integrity zomes: - -```diff:toml - [dependencies] --hdi = { workspace = true } -+hdi = { workspace = true, features = ["unstable-functions"] } -``` - ### `OpenChain` and `CloseChain` actions changed If you're one of the rare folks who have been using these two actions, the structs have changed. Take a look at the Rustdoc and update your code accordingly: From 0b253271b3e616d04db8cf766646e4f2ecc20945 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 13 Dec 2024 09:26:10 -0800 Subject: [PATCH 24/44] address breaking change in JS client 0.18 --- .../upgrade/upgrade-holochain-0.4.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 77fb3af06..000c96ce3 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -316,6 +316,29 @@ Edit any client code that manipulates cloned cells: } ``` +### JavaScript client now receives system signals + +For JavaScript front ends and Tryorama tests, the signal handler callback for `AppWebsocket.prototype.on("signal", cb)` should now take a [`Signal`](https://github.com/holochain/holochain-client-js/blob/main-0.4/docs/client.signal.md). Update your code to look like this: + +```diff:typescript + import { AppWebsocket, Signal, SignalType } from "@holochain/client"; + + let client: AppClient = AppWebsocket.connect(); +-client.on("signal", (signal: AppSignal) => { ++client.on("signal", (signal: Signal) => { ++ switch (Object.keys(signal)[0]) { ++ case SignalType.AppSignal: ++ signal = signal[SignalType.AppSignal]; + console.log(`Received app signal from cell (${signal.cell_id[0]}, ${signal.cell_id[1]}) and zome ${signal.zome_name} with payload ${signal.payload}`); ++ break; ++ case SignalType.SystemSignal: ++ signal = signal[SignalType.SystemSignal]; ++ console.log(`Received system signal of type ${Object.keys(signal)[0]}`); ++ break; ++ } + }); +``` + ### Deprecated validation op functionality removed In your integrity zome's validation functions, you deal with DHT operations, or ops. They are somewhat complex, so [`FlatOp`](https://docs.rs/hdi/latest/hdi/flat_op/enum.FlatOp.html) was introduced to make things simpler. It was originally called `OpType`, and until now that old name was a deprecated alias of `FlatOp`. The old type has finally been removed, along with the `Op::to_type` method (use [`OpHelper::flattened`](https://docs.rs/hdi/latest/hdi/op/trait.OpHelper.html#tymethod.flattened) instead). From dcd577a10370e5669d98ab1cd574796b00e2cb96 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 13 Dec 2024 09:52:52 -0800 Subject: [PATCH 25/44] fix broken fragment id --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 000c96ce3..b14828923 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -400,7 +400,7 @@ The `CountersigningSuccess` signal sent to the client now gives the action hash ### [DHT sharding](/concepts/4_dht/) is disabled by default -This feature needs more performance and correctness testing before it's production-ready, but it can be turned on by [compiling Holochain with the `unstable-sharding` flag enabled](#enabling-in-holochain-runtime). +This feature needs more performance and correctness testing before it's production-ready, but it can be turned on by [compiling Holochain with the `unstable-sharding` flag enabled](#unstable-features-removed-by-default). It's unknown exactly what might happen if nodes with DHT sharding disabled try to gossip in the same network as nodes without DHT sharding. Presumably this is still possible, but it might cause unexpected behaviors! From ec5de94861b3396e25cee9713bc761bf99874c74 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 13 Dec 2024 09:58:40 -0800 Subject: [PATCH 26/44] add import, fix bug --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index b14828923..687cdbd43 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -321,7 +321,7 @@ Edit any client code that manipulates cloned cells: For JavaScript front ends and Tryorama tests, the signal handler callback for `AppWebsocket.prototype.on("signal", cb)` should now take a [`Signal`](https://github.com/holochain/holochain-client-js/blob/main-0.4/docs/client.signal.md). Update your code to look like this: ```diff:typescript - import { AppWebsocket, Signal, SignalType } from "@holochain/client"; + import { AppClient, AppWebsocket, Signal, SignalType } from "@holochain/client"; let client: AppClient = AppWebsocket.connect(); -client.on("signal", (signal: AppSignal) => { From f106698163e60a4dffd4af755a547b27e44709be Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 13 Dec 2024 11:14:06 -0800 Subject: [PATCH 27/44] improve wording re: long CI build times --- src/pages/get-started/install-advanced.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/get-started/install-advanced.md b/src/pages/get-started/install-advanced.md index 30f89c04a..c56e1990a 100644 --- a/src/pages/get-started/install-advanced.md +++ b/src/pages/get-started/install-advanced.md @@ -37,7 +37,7 @@ nix develop --override-input holochain "github:holochain/holochain?ref=main-0.4" ### Customizing the Holochain binary -If you want to enable or disable certain Holochain features, such as unstable features, it's best to do this in a local flake file. [Read the 'Customized Holochain build'](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) on the Holonix readme to find out how. Keep in mind that, because you'll be creating a custom Holochain binary, you won't be able to take advantage of the package cache, so it'll take a while to compile Holochain on your machine. +If you want to enable or disable certain Holochain features, such as unstable features, it's best to do this in a local flake file. [Read the 'Customized Holochain build'](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) on the Holonix readme to find out how. Keep in mind that, because you'll be creating a custom Holochain binary, you won't be able to take advantage of the package cache, so it'll take a while to compile Holochain on your machine. The same will be true on CI, where you should consider setting up your own caching. ### A gotcha with Flakes and Git From e8c689f9286ca0b35845c3af3c1e8cda91c43b12 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 13 Dec 2024 11:44:38 -0800 Subject: [PATCH 28/44] fix basic migration steps --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 687cdbd43..bf3851c0a 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -16,10 +16,12 @@ To upgrade your hApp written for Holochain 0.3, follow these steps: 2. Update your `flake.nix` to use the 0.4 version of Holochain by changing the version number in the line `holonix.url = "github:holochain/holonix?ref=main-0.3"` from 0.3 to 0.4. This will take effect later when you enter a new Nix shell. It's important to update your Nix flake lock at this point, to ensure you benefit from the cache we provide: ```shell + nix flake update nix develop ``` - -3. Try running your tests: +3. Update your project's package dependencies ([see below](#update-your-package-dependencies)). +4. Follow the [breaking change update instructions](#update-your-application-code) below to get your code working again. +5. Try running your tests: ```shell npm test @@ -30,9 +32,7 @@ To upgrade your hApp written for Holochain 0.3, follow these steps: ```shell npm start ``` - -4. You'll likely see error messages due to breaking changes, either at compile time or test/run time. Follow the [breaking change update instructions](#update-your-application-code) below to get your code working again. -5. Be aware of some changes that won't break your app but may affect its runtime behavior. Read the [guide at the bottom](#subtle-changes). +6. Be aware of some changes that won't break your app but may affect its runtime behavior. Read the [guide at the bottom](#subtle-changes). ## Update your package dependencies @@ -114,7 +114,7 @@ You'll update the UI package dependencies similarly to the test package. Edit `u Then in your project's root folder, run your package manager's update command to update the lockfile and install new package versions for your command-line tools, tests, and UI. Use the command that matches your chosen package manager. For example, if you're using `npm`: ```shell -npm update +npm install ``` ## Update your application code From e54d4eb1e0590d1ec6b5d7d70cb9a58773222e15 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 13 Dec 2024 11:44:48 -0800 Subject: [PATCH 29/44] move less important migration steps down --- .../upgrade/upgrade-holochain-0.4.md | 136 +++++++++--------- 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index bf3851c0a..5899dfcf0 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -149,54 +149,6 @@ The biggest change for 0.4 is that some features are marked `unstable` and aren' Note that you'll need to make sure your users are running your custom conductor binary. If you compile your zomes without `unstable-functions` enabled for `hdi` or `hdk`, users with the flag enabled in Holochain will still be able to use your hApp, but if you compile your zomes _with_ `unstable-functions`, users with the flag(s) disabled won't be able to use your hApp. -### `OpenChain` and `CloseChain` actions changed - -If you're one of the rare folks who have been using these two actions, the structs have changed. Take a look at the Rustdoc and update your code accordingly: - -* `CloseChain::new_dna_hash` has been replaced with [`new_target`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.CloseChain.html), which has a type of `Option`. [This new type](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/prelude/enum.MigrationTarget.html) is an enum of `Dna(DnaHash)` or `Agent(AgentHash)`. - -* [`OpenChain::prev_dna_hash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.OpenChain.html) has been changed to match; its type is a non-optional `MigrationTarget`. It also gets a new field, `close_hash`, which is the `ActionHash` of the corresponding `CloseChain` action. - -### `InstallApp` agent key is optional - -!!! info -This change is only relevant if you're building a runtime that can install hApp bundles. -!!! - -The `agent_key` field in the [`InstallApp` payload](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/struct.InstallAppPayload.html) is now optional, and a key will be generated if you don't supply one. - -If you're using the JavaScript client to interact with the conductor, [update the JS client lib](#ui) and test it --- you shouldn't need to change any code. - -If you're using the Rust client, first update the Rust client lib, then update your code. Edit your UI project's `Cargo.toml` file: - -```diff:toml - [dependencies] --holochain_client = "0.5.3" -+holochain_client = "0.6.0-rc.0" -``` - -Then edit anywhere in your Rust code that uses the `install_app` function: - -```diff:rust - use holochain_client::*; - - fn install_app() -> Result<()> { - let admin_ws = AdminWebsocket::connect((Ipv4Addr::LOCALHOST, 30_000)).await? - // ... set up arguments - let input_payload = InstallAppPayload { - app_bundle_source, -- agent_key, -+ Some(agent_key), - Some(installed_app_id), - membrane_proofs, - Some(network_seed), - }; - let response = admin_ws.install_app(input_payload).await?; - // ... do things - Ok() - } -``` - ### `CloneCellId` changes The `CloneCellId::CellId` enum variant has become [`DnaHash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/clone/enum.CloneCellId.html) and contains, naturally, a `DnaHash` value. This type is used when enabling, disabling, or deleting clones from the app API or a coordinator zome. @@ -339,6 +291,74 @@ For JavaScript front ends and Tryorama tests, the signal handler callback for `A }); ``` +### Change in enum serialization + +The default serialization for unit-like enum variants has changed. Previously, they would look like this (JSON representation): + +```json +{ + "variant1": null +} +``` + +Now they look like this: + +```json +"variant1" +``` + +(Enum variants with data still follow the `{ "variant": }` pattern.) + +This will affect any entries or entry fields that start as instances of a Rust enum and are sent to the front end. If your front end is written in JavaScript, you'll need to be aware of this and update your front-end models to match. If your front end is written in Rust, you're likely defining your entry types in a separate module that you're importing directly into the client, which will handle proper deserialization for you. + +### `OpenChain` and `CloseChain` actions changed + +If you're one of the rare folks who have been using these two actions, the structs have changed. Take a look at the Rustdoc and update your code accordingly: + +* `CloseChain::new_dna_hash` has been replaced with [`new_target`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.CloseChain.html), which has a type of `Option`. [This new type](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/prelude/enum.MigrationTarget.html) is an enum of `Dna(DnaHash)` or `Agent(AgentHash)`. + +* [`OpenChain::prev_dna_hash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.OpenChain.html) has been changed to match; its type is a non-optional `MigrationTarget`. It also gets a new field, `close_hash`, which is the `ActionHash` of the corresponding `CloseChain` action. + +### `InstallApp` agent key is optional + +!!! info +This change is only relevant if you're building a runtime that can install hApp bundles. +!!! + +The `agent_key` field in the [`InstallApp` payload](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/struct.InstallAppPayload.html) is now optional, and a key will be generated if you don't supply one. + +If you're using the JavaScript client to interact with the conductor, [update the JS client lib](#ui) and test it --- you shouldn't need to change any code. + +If you're using the Rust client, first update the Rust client lib, then update your code. Edit your UI project's `Cargo.toml` file: + +```diff:toml + [dependencies] +-holochain_client = "0.5.3" ++holochain_client = "0.6.0-rc.0" +``` + +Then edit anywhere in your Rust code that uses the `install_app` function: + +```diff:rust + use holochain_client::*; + + fn install_app() -> Result<()> { + let admin_ws = AdminWebsocket::connect((Ipv4Addr::LOCALHOST, 30_000)).await? + // ... set up arguments + let input_payload = InstallAppPayload { + app_bundle_source, +- agent_key, ++ Some(agent_key), + Some(installed_app_id), + membrane_proofs, + Some(network_seed), + }; + let response = admin_ws.install_app(input_payload).await?; + // ... do things + Ok() + } +``` + ### Deprecated validation op functionality removed In your integrity zome's validation functions, you deal with DHT operations, or ops. They are somewhat complex, so [`FlatOp`](https://docs.rs/hdi/latest/hdi/flat_op/enum.FlatOp.html) was introduced to make things simpler. It was originally called `OpType`, and until now that old name was a deprecated alias of `FlatOp`. The old type has finally been removed, along with the `Op::to_type` method (use [`OpHelper::flattened`](https://docs.rs/hdi/latest/hdi/op/trait.OpHelper.html#tymethod.flattened) instead). @@ -372,26 +392,6 @@ Because of this, after the membrane proof has been provided, the [`DisabledAppRe The only change you should need to make to existing code is to make sure you're handling this new variant in your `match` blocks (Rust) or `switch` blocks (JavaScript). -### Change in enum serialization - -The default serialization for unit-like enum variants has changed. Previously, they would look like this (JSON representation): - -```json -{ - "variant1": null -} -``` - -Now they look like this: - -```json -"variant1" -``` - -(Enum variants with data still follow the `{ "variant": }` pattern.) - -This will affect any entries or entry fields that start as instances of a Rust enum and are sent to the front end. If your front end is written in JavaScript, you'll need to be aware of this and update your front-end models to match. If your front end is written in Rust, you're likely defining your entry types in a separate module that you're importing directly into the client, which will handle proper deserialization for you. - ### `CountersigningSuccess` information changed The `CountersigningSuccess` signal sent to the client now gives the action hash of the successful countersigned commit rather than its entry hash. In your client code, whether JavaScript or Rust, update your signal handler to deal with a `HoloHash` rather than a `HoloHash` when it receives this kind of signal. From c2822d66b211d8c64a0495274afb20fe5d555da1 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 13 Dec 2024 13:23:56 -0800 Subject: [PATCH 30/44] better version-specific ad-hoc shell --- src/pages/get-started/install-advanced.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/get-started/install-advanced.md b/src/pages/get-started/install-advanced.md index c56e1990a..97a1dc4ba 100644 --- a/src/pages/get-started/install-advanced.md +++ b/src/pages/get-started/install-advanced.md @@ -29,10 +29,10 @@ nix develop github:holochain/holonix #### Specifying a certain release -The above one-liner will give you the latest version of Holochain from branch `main`. To get an ad-hoc shell with a specific version of Holochain, use the flag `--override-input versions `. +The above one-liner will give you the latest version of Holochain from branch `main`, which is the weekly development version. To get an ad-hoc shell with a specific version of Holochain, use the `ref=` query string parameter. For example, if you want to enter a Holochain 0.4 development shell, run: ```shell -nix develop --override-input holochain "github:holochain/holochain?ref=main-0.4" github:holochain/holonix +nix develop github:/holochain/holonix?ref=main-0.4 ``` ### Customizing the Holochain binary From b9aadabc38216040beee33469f7d993fd00e2779 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 13 Dec 2024 14:01:29 -0800 Subject: [PATCH 31/44] bump recommended release info in advanced install --- src/pages/get-started/install-advanced.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pages/get-started/install-advanced.md b/src/pages/get-started/install-advanced.md index b3b2a97b8..bb58a037a 100644 --- a/src/pages/get-started/install-advanced.md +++ b/src/pages/get-started/install-advanced.md @@ -24,22 +24,22 @@ If you want to learn more about how this setup works and how to create it manual The flake-based one-liner to get you an ad-hoc Holonix shell (that is, not using a local flake file) looks like this: ```shell -nix develop github:holochain/holonix?ref=main-0.3 +nix develop github:holochain/holonix?ref=main-0.4 ``` #### Specifying a certain release -The above one-liner will give you the latest **recommended** version of Holochain from the 0.3 release branch. To get an ad-hoc shell with a specific version of Holochain, change the `ref` parameter. For example, if you want to enter a Holochain 0.4 development shell, run: +The above one-liner will give you the latest **recommended** version of Holochain from the 0.4 release branch. To get an ad-hoc shell with a different version of Holochain, change the `ref` parameter. For example, if you want to enter a Holochain 0.3 development shell, run: ```shell -nix develop github:holochain/holonix?ref=main-0.4 +nix develop github:holochain/holonix?ref=main-0.3 ``` The options you should know about are: * `main` or no `ref` parameter: The development version of Holochain, released weekly with no guarantee of stability (currently 0.5) -* `main-0.4`: RC of Holochain 0.4 (be aware that many breaking changes are coming in the next RC) -* `main-0.3`: The current recommended version of Holochain for everyday development +* `main-0.4`: The current recommended version of Holochain for everyday development +* `main-0.3`: The previous version of Holochain, which still receives maintenance releases ### Customizing the Holochain binary From 93bc57670446599e064a76de327ec0df7f556032 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 16 Dec 2024 11:34:27 -0800 Subject: [PATCH 32/44] fix signal refactoring so it compiles --- .../resources/upgrade/upgrade-holochain-0.4.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 5899dfcf0..3e9660ffa 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -273,21 +273,15 @@ Edit any client code that manipulates cloned cells: For JavaScript front ends and Tryorama tests, the signal handler callback for `AppWebsocket.prototype.on("signal", cb)` should now take a [`Signal`](https://github.com/holochain/holochain-client-js/blob/main-0.4/docs/client.signal.md). Update your code to look like this: ```diff:typescript - import { AppClient, AppWebsocket, Signal, SignalType } from "@holochain/client"; +-import { AppClient, AppSignal, AppWebsocket } from "@holochain/client"; ++import { AppClient, AppWebsocket, Signal, SignalType } from "@holochain/client"; let client: AppClient = AppWebsocket.connect(); --client.on("signal", (signal: AppSignal) => { +-client.on("signal", (appSignal: AppSignal) => { +client.on("signal", (signal: Signal) => { -+ switch (Object.keys(signal)[0]) { -+ case SignalType.AppSignal: -+ signal = signal[SignalType.AppSignal]; - console.log(`Received app signal from cell (${signal.cell_id[0]}, ${signal.cell_id[1]}) and zome ${signal.zome_name} with payload ${signal.payload}`); -+ break; -+ case SignalType.SystemSignal: -+ signal = signal[SignalType.SystemSignal]; -+ console.log(`Received system signal of type ${Object.keys(signal)[0]}`); -+ break; -+ } ++ if (!(SignalType.App in signal)) return; ++ const appSignal = signal[SignalType.App]; + console.log(`Received app signal from cell (${signal.cell_id[0]}, ${signal.cell_id[1]}) and zome ${signal.zome_name} with payload ${signal.payload}`); }); ``` From b14c432de7dcfe37b9e211101b928d0c1f3f77bf Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 16 Dec 2024 13:44:33 -0800 Subject: [PATCH 33/44] fix bug in sample JS code --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 3e9660ffa..434e5cd92 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -281,7 +281,7 @@ For JavaScript front ends and Tryorama tests, the signal handler callback for `A +client.on("signal", (signal: Signal) => { + if (!(SignalType.App in signal)) return; + const appSignal = signal[SignalType.App]; - console.log(`Received app signal from cell (${signal.cell_id[0]}, ${signal.cell_id[1]}) and zome ${signal.zome_name} with payload ${signal.payload}`); + console.log(`Received app signal from cell (${appSignal.cell_id[0]}, ${appSignal.cell_id[1]}) and zome ${appSignal.zome_name} with payload ${appSgnal.payload}`); }); ``` From ab4ee94720cea36e6a1e38e5ce7d8124bd1a658d Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 16 Dec 2024 13:45:52 -0800 Subject: [PATCH 34/44] simplify/fix sample JS --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 434e5cd92..c4a3dd40b 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -281,7 +281,7 @@ For JavaScript front ends and Tryorama tests, the signal handler callback for `A +client.on("signal", (signal: Signal) => { + if (!(SignalType.App in signal)) return; + const appSignal = signal[SignalType.App]; - console.log(`Received app signal from cell (${appSignal.cell_id[0]}, ${appSignal.cell_id[1]}) and zome ${appSignal.zome_name} with payload ${appSgnal.payload}`); + console.log(`Received app signal from cell [${appSignal.cell_id}] and zome ${appSignal.zome_name} with payload ${appSgnal.payload}`); }); ``` From cfa29404290884ed0a0a9734daf10a42643b5cab Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 16 Dec 2024 13:52:17 -0800 Subject: [PATCH 35/44] fix bug in js --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index c4a3dd40b..f248d54e1 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -281,7 +281,7 @@ For JavaScript front ends and Tryorama tests, the signal handler callback for `A +client.on("signal", (signal: Signal) => { + if (!(SignalType.App in signal)) return; + const appSignal = signal[SignalType.App]; - console.log(`Received app signal from cell [${appSignal.cell_id}] and zome ${appSignal.zome_name} with payload ${appSgnal.payload}`); + console.log(`Received app signal from cell [${appSignal.cell_id}] and zome ${appSignal.zome_name} with payload ${appSignal.payload}`); }); ``` From 236d7067bccd8f2edd8483366e54a9feffa3a42b Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 16 Dec 2024 13:52:40 -0800 Subject: [PATCH 36/44] better copyability for command --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index f248d54e1..dae31ccd8 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -16,8 +16,7 @@ To upgrade your hApp written for Holochain 0.3, follow these steps: 2. Update your `flake.nix` to use the 0.4 version of Holochain by changing the version number in the line `holonix.url = "github:holochain/holonix?ref=main-0.3"` from 0.3 to 0.4. This will take effect later when you enter a new Nix shell. It's important to update your Nix flake lock at this point, to ensure you benefit from the cache we provide: ```shell - nix flake update - nix develop + nix flake update && nix develop ``` 3. Update your project's package dependencies ([see below](#update-your-package-dependencies)). 4. Follow the [breaking change update instructions](#update-your-application-code) below to get your code working again. From 0d1628b5488b7822c07553b89dea386994ff4b47 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 16 Dec 2024 13:52:55 -0800 Subject: [PATCH 37/44] note about optionally using latest versions of hdi/k --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index dae31ccd8..773951eef 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -43,11 +43,13 @@ Update the `hdk` and `hdi` version strings in the project's root `Cargo.toml` fi [workspace.dependencies] -hdi = "=0.4.6" -hdk = "=0.3.6" -+hdi = "=0.5.0-rc.1" ++hdi = "=0.5.0-rc.1" # Pick the latest versions of these libraries if you prefer. +hdk = "=0.4.0-rc.1" serde = "1.0" ``` +The latest versions of these libraries can be found on crates.io: [`hdi`](https://crates.io/crates/hdi), [`hdk`](https://crates.io/crates/hdk). + Once you've updated your `Cargo.toml` you need to update your `Cargo.lock` and check whether your project can still build. To do this in one step you can run: ```shell From 9d08edd0e0ccf8f2c15455882e62b74d825c29ed Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 16 Dec 2024 14:46:15 -0800 Subject: [PATCH 38/44] fix sample code --- .../upgrade/upgrade-holochain-0.4.md | 45 ++++++++++--------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 773951eef..02f914c70 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -161,33 +161,33 @@ Edit any coordinator zome code that uses functions from `hdk::clone`: ```diff:rust use hdk::prelude::*; - fn create_chat_room(name: string) -> ExternResult { - // ... set up cell_id + fn create_chat_room(name: String) -> ExternResult { + // ... instantiate cell_id let create_input = CreateCloneCellInput { - cell_id, - None, - name, + cell_id: cell_id, + membrane_proof: None, + name: Some(name), }; - let cloned_cell = create_clone_cell(create_input).await?; + let cloned_cell = create_clone_cell(create_input)?; let enable_input = EnableCloneCellInput { -- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), -+ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), +- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id.clone()), ++ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash().clone()), }; - enable_clone_cell(enable_input).await?; - cloned_cell.cell_id + enable_clone_cell(enable_input)?; + Ok(cloned_cell.cell_id) } fn remove_chat_room(cell_id: CellId) -> ExternResult<()> { let disable_input = DisableCloneCellInput { -- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), -+ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), +- clone_cell_id: CloneCellId::CellId(cell_id.clone()), ++ clone_cell_id: CloneCellId::DnaHash(cell_id.dna_hash().clone()), }; - disable_clone_cell(disable_input).await?; + disable_clone_cell(disable_input)?; let delete_input = DeleteCloneCellInput { -- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), -+ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), +- clone_cell_id: CloneCellId::CellId(cell_id.clone()), ++ clone_cell_id: CloneCellId::DnaHash(cell_id.dna_hash().clone()), }; - delete_clone_cell(delete_input).await? + delete_clone_cell(delete_input) } ``` @@ -201,9 +201,10 @@ Edit any client code that manipulates cloned cells: let client: AppClient = await AppWebsocket.connect(); let role_name = "chat"; - function createChatRoom(name: String) { + async function createChatRoom(name: string) { const clonedCell = await client.createCloneCell({ modifiers: {}, + name, role_name }); await client.enableCloneCell({ @@ -247,8 +248,8 @@ Edit any client code that manipulates cloned cells: }; let cloned_cell = app.create_clone_cell(input_payload).await?; let enable_payload = EnableCloneCellPayload { -- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), -+ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), +- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id.clone()), ++ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash().clone()), }; app.enable_clone_cell(enable_payload).await? Ok(cloned_cell.cell_id) @@ -257,13 +258,13 @@ Edit any client code that manipulates cloned cells: fn remove_chat_room(cell_id: CellId) -> Result<()> { let app = connect_to_client().await?; let disable_payload = DisableCloneCellPayload { -- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), -+ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), +- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id.clone()), ++ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash().clone()), }; app.disable_clone_cell(disable_payload).await?; let delete_payload = DeleteCloneCellPayload { - clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), -+ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash()), ++ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash().clone()), }; app.delete_clone_cell(delete_payload).await? } From f93bfdf76d2161b1216b8c3dd58b375277dcc64d Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Mon, 16 Dec 2024 14:57:00 -0800 Subject: [PATCH 39/44] remove rust client example from clone cell diffs --- .../upgrade/upgrade-holochain-0.4.md | 44 ------------------- 1 file changed, 44 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 02f914c70..501cafb8a 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -226,50 +226,6 @@ Edit any client code that manipulates cloned cells: } ``` -#### In Rust front-end - -Edit any client code that manipulates cloned cells: - -```diff:rust - use holochain_client::*; - - async fn connect_to_client() -> Result { - AppWebsocket::connect((Ipv4Addr::LOCALHOST, 30_000)).await? - } - - async fn create_chat_room(name: String) -> Result { - let app = connect_to_client().await?; - // ... set up arguments - let create_payload = CreateCloneCellPayload { - role_name, - modifiers, - none, - Some(name), - }; - let cloned_cell = app.create_clone_cell(input_payload).await?; - let enable_payload = EnableCloneCellPayload { -- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id.clone()), -+ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash().clone()), - }; - app.enable_clone_cell(enable_payload).await? - Ok(cloned_cell.cell_id) - } - - fn remove_chat_room(cell_id: CellId) -> Result<()> { - let app = connect_to_client().await?; - let disable_payload = DisableCloneCellPayload { -- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id.clone()), -+ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash().clone()), - }; - app.disable_clone_cell(disable_payload).await?; - let delete_payload = DeleteCloneCellPayload { -- clone_cell_id: CloneCellId::CellId(cloned_cell.cell_id), -+ clone_cell_id: CloneCellId::DnaHash(cloned_cell.cell_id.dna_hash().clone()), - }; - app.delete_clone_cell(delete_payload).await? - } -``` - ### JavaScript client now receives system signals For JavaScript front ends and Tryorama tests, the signal handler callback for `AppWebsocket.prototype.on("signal", cb)` should now take a [`Signal`](https://github.com/holochain/holochain-client-js/blob/main-0.4/docs/client.signal.md). Update your code to look like this: From f7d868bcb2555544a67e410776d620d119fe99a0 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 18 Dec 2024 14:33:15 -0800 Subject: [PATCH 40/44] fix yet another clearly wrong bit of code --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 501cafb8a..6f396c049 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -202,16 +202,16 @@ Edit any client code that manipulates cloned cells: let role_name = "chat"; async function createChatRoom(name: string) { - const clonedCell = await client.createCloneCell({ + const { cell_id } = await client.createCloneCell({ modifiers: {}, name, role_name }); await client.enableCloneCell({ -- clone_cell_id: cloned_cell.cell_id, -+ clone_cell_id: cloned_cell.cell_id[0], +- clone_cell_id: cell_id, ++ clone_cell_id: cell_id[0], }); - return clonedCell.cell_id; + return cell_id; } function removeChatRoom(cell_id: CellId) { From 4458a61228b39e3793b6a8bddf17d23d985ef61f Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 18 Dec 2024 16:39:31 -0800 Subject: [PATCH 41/44] improve language / fix more bugs --- src/pages/resources/upgrade/upgrade-holochain-0.4.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 6f396c049..60314c8d0 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -193,7 +193,7 @@ Edit any coordinator zome code that uses functions from `hdk::clone`: #### In JavaScript front-end -Edit any client code that manipulates cloned cells: +Edit any client code that manipulates cloned cells by cell ID to use DNA hash instead: ```diff:typescript import { AppWebsocket, CellId } from "@holochain/client"; @@ -203,7 +203,7 @@ Edit any client code that manipulates cloned cells: async function createChatRoom(name: string) { const { cell_id } = await client.createCloneCell({ - modifiers: {}, + modifiers: { network_seed: name }, name, role_name }); @@ -214,18 +214,16 @@ Edit any client code that manipulates cloned cells: return cell_id; } - function removeChatRoom(cell_id: CellId) { + async function removeChatRoom(cell_id: CellId) { await client.disableCloneCell({ - clone_cell_id: cell_id, -+ clone_cell_id: cell_id[0], - }); - await client.deleteCloneCell({ -- clone_cell_id: cell_id, + clone_cell_id: cell_id[0], }); } ``` +If you're writing an application that uses the admin API, `AdminClient#deleteCloneCell` changes in the same way as `enableCloneCell` and `disableCloneCell`. + ### JavaScript client now receives system signals For JavaScript front ends and Tryorama tests, the signal handler callback for `AppWebsocket.prototype.on("signal", cb)` should now take a [`Signal`](https://github.com/holochain/holochain-client-js/blob/main-0.4/docs/client.signal.md). Update your code to look like this: From 99a00ac075c75034a9ddd63ac38d7c9b35cab8e7 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Wed, 18 Dec 2024 17:11:58 -0800 Subject: [PATCH 42/44] update clone cell sample code to reflect the fact that clones are enabled at birth --- .../resources/upgrade/upgrade-holochain-0.4.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 60314c8d0..7f9aac574 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -199,23 +199,16 @@ Edit any client code that manipulates cloned cells by cell ID to use DNA hash in import { AppWebsocket, CellId } from "@holochain/client"; let client: AppClient = await AppWebsocket.connect(); - let role_name = "chat"; - async function createChatRoom(name: string) { - const { cell_id } = await client.createCloneCell({ - modifiers: { network_seed: name }, - name, - role_name - }); - await client.enableCloneCell({ + async function archiveChatRoom(cell_id: CellId) { + await client.disableCloneCell({ - clone_cell_id: cell_id, + clone_cell_id: cell_id[0], }); - return cell_id; } - async function removeChatRoom(cell_id: CellId) { - await client.disableCloneCell({ + async function reopenChatRoom(cell_id: CellId) { + await client.enableCloneCell({ - clone_cell_id: cell_id, + clone_cell_id: cell_id[0], }); From 59add029e356a2679aff8579cf8670c800b6c360 Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 20 Dec 2024 08:25:17 -0800 Subject: [PATCH 43/44] feedback from ThetaSinner --- .cspell/holochain-words.txt | 1 + .../upgrade/upgrade-holochain-0.4.md | 20 +++++++++++-------- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/.cspell/holochain-words.txt b/.cspell/holochain-words.txt index 627323251..af34e2afd 100644 --- a/.cspell/holochain-words.txt +++ b/.cspell/holochain-words.txt @@ -17,6 +17,7 @@ Mythosthesia sharded Snapmail Tryorama +unsharded webhapp zome zome's diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 7f9aac574..56659c1a7 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -13,7 +13,7 @@ NOTE: [Holonix](/get-started/install-advanced/), our developer shell environment To upgrade your hApp written for Holochain 0.3, follow these steps: 1. Check whether your `flake.nix` contains `github:holochain/holonix`. If it does, then you can continue to the next step. Otherwise it will contain `github:holochain/holochain`. If so, then follow the [Holonix upgrade guide](/resources/upgrade/upgrade-new-holonix/) to update to the newest Holonix command-line developer environment (we're not providing a 0.4 version of Holochain through the old Holonix). -2. Update your `flake.nix` to use the 0.4 version of Holochain by changing the version number in the line `holonix.url = "github:holochain/holonix?ref=main-0.3"` from 0.3 to 0.4. This will take effect later when you enter a new Nix shell. It's important to update your Nix flake lock at this point, to ensure you benefit from the cache we provide: +2. Update your `flake.nix` to use the 0.4 version of Holochain by changing the version number in the line `holonix.url = "github:holochain/holonix?ref=main-0.3"` from 0.3 to 0.4. This will take effect later when you enter a new Nix shell. It's important to update your Nix flake lockfile at this point, to ensure you benefit from the cache we provide: ```shell nix flake update && nix develop @@ -48,7 +48,7 @@ Update the `hdk` and `hdi` version strings in the project's root `Cargo.toml` fi serde = "1.0" ``` -The latest versions of these libraries can be found on crates.io: [`hdi`](https://crates.io/crates/hdi), [`hdk`](https://crates.io/crates/hdk). +The latest version numbers of these libraries can be found on crates.io: [`hdi`](https://crates.io/crates/hdi), [`hdk`](https://crates.io/crates/hdk). Once you've updated your `Cargo.toml` you need to update your `Cargo.lock` and check whether your project can still build. To do this in one step you can run: @@ -128,13 +128,13 @@ The biggest change for 0.4 is that some features are marked `unstable` and aren' * **[Countersigning](/concepts/10_countersigning/) `unstable-countersigning`**: Allows agents to temporarily lock their chains in order to agree to write the same entry to their respective chains. * **DPKI / DeepKey `unstable-dpki`**: Implements a distributed public key infrastructure, allowing agents to manage their keys and confirm continuity of their identity across devices and source chains. Read the [DeepKey readme](https://github.com/holochain/deepkey) for more info. -* **[DHT sharding](/concepts/4_dht/) `unstable-sharding`**: Lessens the load of each peer in large network, allowing them to take responsibility for validating and storing only a subset of a DHT's entire data set. +* **[DHT sharding](/concepts/4_dht/) `unstable-sharding`**: Lessens the load of each peer in large network, allowing them to take responsibility for validating and storing only a subset of a DHT's entire data set. Omitting this flag doesn't disable code, but it does force you to choose either `"empty"` or `"full"` for DHT arc size clamping. * **[Warrants](/concepts/7_validation#remembering-validation-results) `unstable-warrants`**: Spreads news of validation failure around the network, allowing peers to recognize bad actors and take action against them, even if they haven't directly interacted with them. -* **Chain head coordination `chc`**: Developed for Holo, allows source chain changes to be copied from one device to another without causing chain forks. (This pre-existing feature flag is no longer enabled by default.) +* **Chain head coordination `chc`**: Developed for Holo, allows source chain changes to be copied to a remote server for restoring onto the same device or syncing across devices. (This pre-existing feature flag is no longer enabled by default.) * **HDI/HDK functions `unstable-functions`**: * Related to countersigning (enable `unstable-countersigning` if you want to use these): * [`accept_countersigning_preflight_request`](https://github.com/holochain/holochain/blob/holochain-0.4.0-rc.2/crates/hdk/src/countersigning.rs#L3-L22) - * Related to DPKI (enable `unstable-dpki` if you want to use these, which are both new to 0.4): + * Related to DPKI (enable `unstable-dpki` if you want to use this, which is new to 0.4): * [`get_agent_key_lineage`](https://github.com/holochain/holochain/blob/holochain-0.4.0-rc.2/crates/hdk/src/agent.rs#L10-L20) * Related to block lists (allowing peers in a hApp to selectively block others who haven't necessarily produced invalid data or forked their source chain): * `block_agent` @@ -234,6 +234,8 @@ For JavaScript front ends and Tryorama tests, the signal handler callback for `A }); ``` +(Note that currently you'll only ever see a system signal if you're using countersigning, which is [disabled by default](#unstable-features-removed-by-default).) + ### Change in enum serialization The default serialization for unit-like enum variants has changed. Previously, they would look like this (JSON representation): @@ -265,7 +267,7 @@ If you're one of the rare folks who have been using these two actions, the struc ### `InstallApp` agent key is optional !!! info -This change is only relevant if you're building a runtime that can install hApp bundles. +This change is only relevant if you're using the Rust client to access the admin API, for instance if you're building a custom runtime. !!! The `agent_key` field in the [`InstallApp` payload](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/struct.InstallAppPayload.html) is now optional, and a key will be generated if you don't supply one. @@ -345,11 +347,13 @@ The `CountersigningSuccess` signal sent to the client now gives the action hash This feature needs more performance and correctness testing before it's production-ready, but it can be turned on by [compiling Holochain with the `unstable-sharding` flag enabled](#unstable-features-removed-by-default). -It's unknown exactly what might happen if nodes with DHT sharding disabled try to gossip in the same network as nodes without DHT sharding. Presumably this is still possible, but it might cause unexpected behaviors! +If you leave this feature disabled, you'll need to set gossip arc clamping to either `"empty"` or `"full"`, and we recommend doing this for _all_ participants in a network. We've observed bugs in networks that have a mixture of unsharded (arc-clamped) and sharded peers. ### Dynamic database encryption, folder structure changes -Previous conductor and keystore SQLite databases used a hardcoded encryption key; v0.4 now uses a dynamic key. Additionally, the database paths have changed. These two things mean you won't be able to import data from v0.3. +Previous conductor and keystore SQLite databases used a hardcoded encryption key; 0.4 now uses a dynamic key. This means you won't be able to import data from 0.3, so we recommend providing a data import/export feature in your hApp with instructions to help people move their data over on upgrade to 0.4. + +The locations of the database folders and files have also changed (although if 0.4 finds an unencrypted database in the old locations, it'll move and encrypt the data). ### WebRTC signalling server change From 0628d0bd6634cec3fee2d027f1615c14b5e5434e Mon Sep 17 00:00:00 2001 From: Paul d'Aoust Date: Fri, 20 Dec 2024 08:33:17 -0800 Subject: [PATCH 44/44] remove rc from version numbers --- .../upgrade/upgrade-holochain-0.4.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.4.md b/src/pages/resources/upgrade/upgrade-holochain-0.4.md index 56659c1a7..bde1840c2 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.4.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.4.md @@ -43,8 +43,8 @@ Update the `hdk` and `hdi` version strings in the project's root `Cargo.toml` fi [workspace.dependencies] -hdi = "=0.4.6" -hdk = "=0.3.6" -+hdi = "=0.5.0-rc.1" # Pick the latest versions of these libraries if you prefer. -+hdk = "=0.4.0-rc.1" ++hdi = "=0.5.0" # Pick a later version of these libraries if you prefer. ++hdk = "=0.4.0" serde = "1.0" ``` @@ -94,8 +94,8 @@ Edit your project's `tests/package.json` file: // some dependencies - "@holochain/client": "^0.17.1", - "@holochain/tryorama": "^0.16.0", -+ "@holochain/client": "^0.18.0-rc.1", -+ "@holochain/tryorama": "^0.17.0-rc.0", ++ "@holochain/client": "^0.18.0", ++ "@holochain/tryorama": "^0.17.0", // more dependencies }, ``` @@ -107,7 +107,7 @@ You'll update the UI package dependencies similarly to the test package. Edit `u ```diff:json "dependencies": { - "@holochain/client": "^0.17.1", -+ "@holochain/client": "^0.18.0-rc.1", ++ "@holochain/client": "^0.18.0", // more dependencies }, ``` @@ -133,14 +133,14 @@ The biggest change for 0.4 is that some features are marked `unstable` and aren' * **Chain head coordination `chc`**: Developed for Holo, allows source chain changes to be copied to a remote server for restoring onto the same device or syncing across devices. (This pre-existing feature flag is no longer enabled by default.) * **HDI/HDK functions `unstable-functions`**: * Related to countersigning (enable `unstable-countersigning` if you want to use these): - * [`accept_countersigning_preflight_request`](https://github.com/holochain/holochain/blob/holochain-0.4.0-rc.2/crates/hdk/src/countersigning.rs#L3-L22) + * [`accept_countersigning_preflight_request`](https://github.com/holochain/holochain/blob/holochain-0.4.0/crates/hdk/src/countersigning.rs#L3-L22) * Related to DPKI (enable `unstable-dpki` if you want to use this, which is new to 0.4): - * [`get_agent_key_lineage`](https://github.com/holochain/holochain/blob/holochain-0.4.0-rc.2/crates/hdk/src/agent.rs#L10-L20) + * [`get_agent_key_lineage`](https://github.com/holochain/holochain/blob/holochain-0.4.0/crates/hdk/src/agent.rs#L10-L20) * Related to block lists (allowing peers in a hApp to selectively block others who haven't necessarily produced invalid data or forked their source chain): * `block_agent` * `unblock_agent` * Other: - * [`schedule`](https://github.com/holochain/holochain/blob/holochain-0.4.0-rc.2/crates/hdk/src/time.rs#L67-L137) + * [`schedule`](https://github.com/holochain/holochain/blob/holochain-0.4.0/crates/hdk/src/time.rs#L67-L137) * An unimplemented `sleep` function has been removed completely **If your DNA needs to call a host function that depends on an unstable feature**, you'll need to do two things: @@ -152,7 +152,7 @@ Note that you'll need to make sure your users are running your custom conductor ### `CloneCellId` changes -The `CloneCellId::CellId` enum variant has become [`DnaHash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/clone/enum.CloneCellId.html) and contains, naturally, a `DnaHash` value. This type is used when enabling, disabling, or deleting clones from the app API or a coordinator zome. +The `CloneCellId::CellId` enum variant has become [`DnaHash`](https://docs.rs/holochain_zome_types/0.4.0/holochain_zome_types/clone/enum.CloneCellId.html) and contains, naturally, a `DnaHash` value. This type is used when enabling, disabling, or deleting clones from the app API or a coordinator zome. #### In coordinator zomes @@ -260,9 +260,9 @@ This will affect any entries or entry fields that start as instances of a Rust e If you're one of the rare folks who have been using these two actions, the structs have changed. Take a look at the Rustdoc and update your code accordingly: -* `CloseChain::new_dna_hash` has been replaced with [`new_target`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.CloseChain.html), which has a type of `Option`. [This new type](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/prelude/enum.MigrationTarget.html) is an enum of `Dna(DnaHash)` or `Agent(AgentHash)`. +* `CloseChain::new_dna_hash` has been replaced with [`new_target`](https://docs.rs/holochain_zome_types/0.4.0/holochain_zome_types/action/struct.CloseChain.html), which has a type of `Option`. [This new type](https://docs.rs/holochain_zome_types/0.4.0/holochain_zome_types/prelude/enum.MigrationTarget.html) is an enum of `Dna(DnaHash)` or `Agent(AgentHash)`. -* [`OpenChain::prev_dna_hash`](https://docs.rs/holochain_zome_types/0.4.0-rc.1/holochain_zome_types/action/struct.OpenChain.html) has been changed to match; its type is a non-optional `MigrationTarget`. It also gets a new field, `close_hash`, which is the `ActionHash` of the corresponding `CloseChain` action. +* [`OpenChain::prev_dna_hash`](https://docs.rs/holochain_zome_types/0.4.0/holochain_zome_types/action/struct.OpenChain.html) has been changed to match; its type is a non-optional `MigrationTarget`. It also gets a new field, `close_hash`, which is the `ActionHash` of the corresponding `CloseChain` action. ### `InstallApp` agent key is optional @@ -270,7 +270,7 @@ If you're one of the rare folks who have been using these two actions, the struc This change is only relevant if you're using the Rust client to access the admin API, for instance if you're building a custom runtime. !!! -The `agent_key` field in the [`InstallApp` payload](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/struct.InstallAppPayload.html) is now optional, and a key will be generated if you don't supply one. +The `agent_key` field in the [`InstallApp` payload](https://docs.rs/holochain_types/0.4.0/holochain_types/app/struct.InstallAppPayload.html) is now optional, and a key will be generated if you don't supply one. If you're using the JavaScript client to interact with the conductor, [update the JS client lib](#ui) and test it --- you shouldn't need to change any code. @@ -279,7 +279,7 @@ If you're using the Rust client, first update the Rust client lib, then update y ```diff:toml [dependencies] -holochain_client = "0.5.3" -+holochain_client = "0.6.0-rc.0" ++holochain_client = "0.6.0" ``` Then edit anywhere in your Rust code that uses the `install_app` function: @@ -329,11 +329,11 @@ In your integrity zome, any time you use `Op::to_type`, change it like this: } ``` -### New data in [`AppInfo` response](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/struct.AppInfo.html) +### New data in [`AppInfo` response](https://docs.rs/holochain_conductor_api/0.4.0/holochain_conductor_api/struct.AppInfo.html) -Holochain 0.4 introduces a new flow for app installation that lets an agent supply a membrane proof later with a new [`ProvideMemproofs` endpoint](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/enum.AppRequest.html#variant.ProvideMemproofs). This allows them to get their freshly generated agent key, submit it to some sort of membrane proof service, and get a membrane proof. +Holochain 0.4 introduces a new flow for app installation that lets an agent supply a membrane proof later with a new [`ProvideMemproofs` endpoint](https://docs.rs/holochain_conductor_api/0.4.0/holochain_conductor_api/enum.AppRequest.html#variant.ProvideMemproofs). This allows them to get their freshly generated agent key, submit it to some sort of membrane proof service, and get a membrane proof. -Because of this, after the membrane proof has been provided, the [`DisabledAppReason`](https://docs.rs/holochain_types/0.4.0-rc.2/holochain_types/app/enum.DisabledAppReason.html) enum, used in the [`AppInfo`](https://docs.rs/holochain_conductor_api/0.4.0-rc.2/holochain_conductor_api/struct.AppInfo.html) response, will be a new `NotStartedAfterProvidingMemproofs` variant until the app is started. +Because of this, after the membrane proof has been provided, the [`DisabledAppReason`](https://docs.rs/holochain_types/0.4.0/holochain_types/app/enum.DisabledAppReason.html) enum, used in the [`AppInfo`](https://docs.rs/holochain_conductor_api/0.4.0/holochain_conductor_api/struct.AppInfo.html) response, will be a new `NotStartedAfterProvidingMemproofs` variant until the app is started. The only change you should need to make to existing code is to make sure you're handling this new variant in your `match` blocks (Rust) or `switch` blocks (JavaScript).