Holochain Upgrade 0.2 → 0.3

Steps to update from Holochain version 0.2 to 0.3 in Holonix

Update your flake.nix using a command

In the root folder of the hApp to be upgraded, execute the following command in a terminal:

nix run nixpkgs#gnused -- -i 's/dir=versions\/0_2/dir=versions\/0_3/g' flake.nix

Update your flake.nix manually

Alternatively, open flake.nix in an editor. It should look like this:

{
  description = "My hApp";

  inputs = {
    nixpkgs.follows = "holonix/nixpkgs";
    versions.url = "github:holochain/holochain?dir=versions/0_2";
    holonix.url = "github:holochain/holochain";
    holonix.inputs.versions.follows = "versions";
  };

  ...
}

Change this line:

versions.url = "github:holochain/holochain?dir=versions/0_2";

to:

versions.url = "github:holochain/holochain?dir=versions/0_3";

Apply the update

Updating the flake.nix won’t make Nix use the new Holochain version when you next open a dev shell with nix develop. For the changes to take effect you need to run:

nix flake update

Check the update has worked

Open a dev shell like you normally would:

nix develop

Then check that Holochain is on a 0.3.x version:

holochain --version

This should print something like holochain 0.3.1. It is fine for the last number to be higher. It’s the minor version, the 3, that tells you that you’ve successfully updated from Holochain version 0.2 to 0.3 in Holonix.

Update NPM dependencies

Update the @holochain/client

In your project’s ui/package.json and tests/package.json you will find a dependency on @holochain/client. These should be using 0.16.x, which is the version compatible with Holochain 0.2. To work with Holochain 0.3, you need to update to 0.17.x.

You can always check what versions of the Holochain client are available on the NPM registry and you can find out what versions are compatible with a Holochain version by checking the project’s documentation.

To update the Holochain client for the UI, you can run:

npm install --workspace ui @holochain/client@^0.17.0

and for the tests you can run:

npm install --workspace tests @holochain/client@^0.17.0

There have been a few changes to the client. First, the AppAgentWebsocket has been merged with the AppWebsocket, and its connect method has been simplified. You can now connect to a websocket by changing:

const client = await AppAgentWebsocket.connect(new URL('https://UNUSED'), 'hello-world');

To this:

const client = await AppWebsocket.connect();

Then, anywhere that you used to need to pass the installed app ID (e.g., 'hello-world' above), you no longer need to. So for example, you would change this:

await client.appInfo('hello-world');

To this:

await client.appInfo();

This is because app client connections are now bound to the app that they are connected to. So there’s no need to tell the conductor which app you want to operate on — it already knows.

Update @holochain/hc-spin

If you’re using hc-spin then you will need to upgrade it to work with the new Holochain version.

You can do this by running:

npm install --save-dev @holochain/hc-spin@">=0.300.0 <0.400.0"

You can always check what versions of @holochain/hc-spin are available on the NPM registry.

Update @holochain/tryorama

In your project’s tests/package.json you will find a dependency on @holochain/tryorama. This should be using 0.15.x, which is the version compatible with Holochain 0.2. To work with Holochain 0.3, you need to update to 0.16.x.

You can always check what versions of Tryorama are available on the NPM registry and you can find out what versions are compatible with a Holochain version by checking the project’s documentation.

To update Tryorama, you can run:

npm install --workspace tests @holochain/tryorama@^0.16.0

Update Cargo dependencies

This section is harder to write a general guide for, because it’s common for hApps to add dependencies on other Holochain crates. If you have added other dependencies than the hdi and hdk to your project, then you will need to update those too, but figuring out which versions you need is not described here. There is a hint at the end of the section.

Update the HDK and the HDI

Open your project’s Cargo.toml in an editor and look for the [workspace.dependencies] section. Here you should find something like:

[workspace.dependencies]
hdi = "=0.3.8"
hdk = "=0.2.8"

Change these to point to their latest versions. At the time of writing this would be:

[workspace.dependencies]
hdi = "=0.4.1"
hdk = "=0.3.1"

Please check the latest version for these on their respective pages on the crates.io registry, HDK and HDI. You need to use 0.3.x for hdk and 0.4.x for hdi, so you are looking for the latest patch version that is available for each.

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:

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:

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.

Dealing with API changes in the HDK and HDI

You are likely to run into API changes in the HDK and HDI at this point. You can check the Holochain changelog to see what has changed. In some cases there will be guidance for what you need to change.

If you have trouble resolving the build issues or the changelog doesn’t give you enough information about what has changed, then please reach out on Discord or open a Github issue.

Below are some known changes that you might need to address.

HDI: macro rename hdk_entry_defs -> hdk_entry_types

This macro was renamed for consistency with other macros. The changelog entry for this change is here.

You’re looking for code like:

#[derive(Serialize, Deserialize)]
#[serde(tag = "type")]
#[hdk_entry_defs]
#[unit_enum(UnitEntryTypes)]
pub enum EntryTypes {
    Hello(Hello),
}

Which should be updated to:

#[derive(Serialize, Deserialize)]
#[serde(tag = "type")]
#[hdk_entry_types]
#[unit_enum(UnitEntryTypes)]
pub enum EntryTypes {
    Hello(Hello),
}

HDK: get_links function signature change

The get_links function signature has changed. The changelog entry for this change is here.

You’re looking for code like:

let links = get_links(path.path_entry_hash()?, LinkTypes::AllHellos, None)?;

Which should be updated to:

let links = get_links(GetLinksInputBuilder::try_new(path.path_entry_hash()?, LinkTypes::AllHellos)?.build())?;

HDK: remote_signal function renamed

Most HDK functions follow the naming pattern verb[_target]. The remote_signal function was renamed to send_remote_signal to follow this pattern and make it clearer what the function does. The changelog entry for this change is here.

HDK: GetOptions rework

The GetOptions enum used to have Content and Latest variants. The meaning of these weren’t clear and they were not consistently implemented. The Content variant was renamed to Local and using it will request that data lookups are done using local data only. The Latest variant was renamed to Network and allows Holochain to choose to go to the network to fetch data if required. The changelog entry for this change is here.

You’re looking for code like:

get(r.action().entry_hash().unwrap().clone(), GetOptions::content())?;

Which should be updated to:

get(r.action().entry_hash().unwrap().clone(), GetOptions::network())?;

The Local variant is intended to support a local first app which is willing to operate with the currently available data. If you aren’t sure which option to use, then Network is recommended to use as the default. Then you can build in local-first capabilities when you are ready.

Updating other dependencies

If you depend on other Holochain crates, then you will need to find compatible versions to update to. You can check available versions on crates.io by searching for them by name. You can also check the Holochain changelog to see what versions have been released together. Note that we don’t release crates unless they have changes, so if you don’t see the crate you’re looking for in a release, then please check the previous releases for the last time we released it. If you get stuck or have build issues, then please reach out on Discord or open a Github issue.

General advice for upgrading

It’s likely that you will need to make more changes than have been mentioned above, but hopefully this guide has given you a head start! Here are some other things to look out for in this upgrade:

• There have been significant changes to Holochain’s data validation. You may see validation failures that you didn’t see before upgrading. Our experience of helping people upgrade to dev versions of 0.3 is that these are often due to issues in your app’s validation logic, and simply weren’t caught before due to issues in Holochain’s validation workflow. Please check your validation logic and check whether there might be an issue there. If not, then please reach out on Discord or open a Github issue for help.
• There have been changes to the data structures provided for app validation. This means that you will need to update your validation code to remove some fields that are no longer available. You should check the changelog here. If you need to retain the fields that have been removed for your validation logic, then your best option is probably to scaffold an app for 0.3 and take a look at how its validation code retrieves data that’s no longer part of the data structures. You can do this by running nix run --override-input versions "github:holochain/holochain?dir=versions/0_3" github:holochain/holochain#hc-scaffold.
• There have been significant WebSocket app interface changes for Holochain 0.3. There is a changelog entry here. Most problems will be taken care of by picking the right client versions and following any changes that are required to use the new client. However, if you are integrating with Holochain’s app interface directly or maintaining your own client then you should get in touch if you run into any difficulties upgrading.
• Databases prior to 0.3 have been unencrypted by default. From 0.3 onwards, databases are always encrypted by default. You can disable this by building Holochain with different options if you need to, or we can show you how to open the encrypted databases. For now, we are assuming that people don’t often need to do this, so there is no guide. If this assumption turns out to be wrong, we can create one!
• A change was made to help hApp developers spot mistakes in DNA manifests that might catch you out if they contain extra fields or obsolete fields. You can read about this change here.
• Holochain 0.2 and 0.3 are not network-compatible. That means that if you have users of your hApp still running Holochain 0.2, then even with the same DNA hash, they would not be able to connect to users running Holochain 0.3. The changes between 0.2 and 0.3 are not as significant as they were between 0.1 and 0.2, but they still prevent communication between the two versions.

Next steps

You should check that your project builds, tests are passing, and that anything else your CI will check is working. You should also check that your hApp is still working because static checks and tests might not catch changes that are required in your UI.

For general project health, you should check if any other dependencies in your project need an update. Please refer to NPM and Cargo documentation for this.

That should be everything — you can now develop against Holochain 0.3! Good luck, and once again, if you need help then please do get in touch on Discord or open a Github issue.