Holochain Upgrade 0.1 → 0.2

Steps to update from Holochain version 0.1 to 0.2 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_1/dir=versions\/0_2/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_1";
    holonix.url = "github:holochain/holochain";
    holonix.inputs.versions.follows = "versions";
  };
  ...
}

Change this line:

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

to:

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

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

Optional: Update your Node.js version

Check if your flake.nix still contains the Node.js package that was included by the scaffolding. It will look something like:

packages = [
  pkgs.nodejs-18_x
];

Change this to the latest long-term support (LTS) release of Node.js. You can find all releases here and check which version is currently the LTS version. At the time of writing this is Node.js 20 so you would update your packages to look something like

packages = [
  pkgs.nodejs_20
];

To find the package name for a given Node.js release, you can search on the Nix package listing.

Holochain’s TypeScript/JavaScript code is tested on the LTS version of Node.js, which is the recommended version for building hApps. You can choose to use a different version but you may run into bugs we aren’t aware of yet, so please let us know if you do!

Check the update has worked

Open a dev shell like you normally would:

nix develop

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

holochain --version

This should print something like holochain 0.2.6. It is fine for the last number to be higher. It’s the minor version, the 2, that tells you that you’ve successfully updated from Holochain version 0.1 to 0.2 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.12.x, which is the version compatible with Holochain 0.1. To work with Holochain 0.2, you need to update to 0.16.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.16.9

and for the tests you can run:

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

One notable change in the client is that it now requires a URL rather than a string when connecting to Holochain. You should change:

this.client = await AppAgentWebsocket.connect('', 'myHapp');

To this:

this.client = await AppAgentWebsocket.connect(new URL('http://UNUSED'), 'myHapp');

Update @holochain/tryorama

In your project’s tests/package.json you will find a dependency on @holochain/tryorama. This should be using 0.11.x, which is the version compatible with Holochain 0.1. To work with Holochain 0.2, you need to update to 0.15.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.15.2

Recommended: Switch from sleep to dhtSync in Tryorama tests

In the version of Tryorama that was compatible with 0.1, you had to use the sleep function when creating data with one player and waiting for it to be visible to other players. With the version of Tryorama you have just upgraded to, there is a new way to do this using the dhtSync function instead.

For example, if you are writing a test with two players, you can replace:

await sleep(3000);

with a call that will actually wait for data to be synced between the two players.

await dhtSync([alice, bob], alice.cells[0].cell_id[0]);

This makes tests much more reliable. It is faster too, because you don’t have to wait for a long time to be safe; you can proceed as soon as the two players have synced their DHTs.

Recommended: Switch from hc-launch to hc-spin for running hApps

The hc-launch tool that came with hApps scaffolded for Holochain 0.1 is still available, but we are now recommending a new tool which does the same job but with a better developer experience. To switch to hc-spin, you will need to add it as an NPM dependency by running:

npm install --save-dev @holochain/hc-spin@^0.200.10

Then you will need to update the scripts section of your project’s root package.json. These are often customized, so we can’t give you a simple command to make this change. If you scaffolded a new project, you would get a scripts section that looks like this (at the time of writing):

{
  ...,
  "scripts": {
    "start": "AGENTS=2 BOOTSTRAP_PORT=$(port) SIGNAL_PORT=$(port) npm run network",
    "network": "hc s clean && npm run build:happ && UI_PORT=8888 concurrently \"npm start -w ui\" \"npm run launch:happ\" \"holochain-playground\"",
    "test": "npm run build:zomes && hc app pack workdir --recursive && npm t -w tests",
    "launch:happ": "hc-spin -n $AGENTS --ui-port $UI_PORT workdir/check_scripts.happ",
    "start:tauri": "AGENTS=2 BOOTSTRAP_PORT=$(port) SIGNAL_PORT=$(port) npm run network:tauri",
    "network:tauri": "hc s clean && npm run build:happ && UI_PORT=8888 concurrently \"npm start -w ui\" \"npm run launch:tauri\" \"holochain-playground\"",
    "launch:tauri": "concurrently \"hc run-local-services --bootstrap-port $BOOTSTRAP_PORT --signal-port $SIGNAL_PORT\" \"echo pass | RUST_LOG=warn hc launch --piped -n $AGENTS workdir/check_scripts.happ --ui-port $UI_PORT network --bootstrap http://127.0.0.1:\"$BOOTSTRAP_PORT\" webrtc ws://127.0.0.1:\"$SIGNAL_PORT\"\"",
    "package": "npm run build:happ && npm run package -w ui && hc web-app pack workdir --recursive",
    "build:happ": "npm run build:zomes && hc app pack workdir --recursive",
    "build:zomes": "RUSTFLAGS='' CARGO_TARGET_DIR=target cargo build --release --target wasm32-unknown-unknown"
  },
  ...
}

You can get the latest version of these scripts yourself by running the following commands:

nix run --override-input versions "github:holochain/holochain?dir=versions/0_2" github:/holochain/holochain#hc-scaffold -- web-app --template svelte --setup-nix true check_scripts
cd check_scripts
cat package.json

The scripts which have a postfix of :tauri are similar to the scripts you will already have. The new scripts for start, network and launch are now set up around hc-spin. It’s up to you how you want to merge these scripts with your project. If you haven’t made any customizations, then feel free to copy the sample scripts above. Please take care to update the hApp name to match yours. I have called my hApp check_scripts, so you would replace that string with your happ name.

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.2.6"
hdk = "=0.1.6"

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

[workspace.dependencies]
hdi = "=0.3.6"
hdk = "=0.2.6"

Please check the latest version for these on their respective pages on the crates.io registry, HDK and HDI. You need to use 0.2.x for the hdk and 0.3.x for the 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 is building. 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.

As an example, you can no longer convert an AnyLinkableHash directly to an ActionHash using From. That is because an AnyLinkableHash may not be an ActionHash, so we now provide a TryFrom instead to make this clear.

You might get an error that looks something like:

error[E0277]: the trait bound `HoloHash<hdi::prelude::holo_hash::hash_type::Action>: From<HoloHash<AnyLinkable>>` is not satisfied
  --> dnas/test/zomes/integrity/tinker/src/test.rs:34:23
   |
34 |     let action_hash = ActionHash::from(base_address);
   |                       ^^^^^^^^^^ the trait `From<HoloHash<AnyLinkable>>` is not implemented for `HoloHash<hdi::prelude::holo_hash::hash_type::Action>`

You would need to change your code from:

let action_hash = ActionHash::from(base_address);

to something like:

let action_hash = ActionHash::try_from(base_address).map_err(|_| {
    wasm_error!(
        WasmErrorInner::Guest(String::from("Failed to convert base_address to ActionHash"))
    )
})?;

The specific changelog entry for this change can be found here.

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.

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.

Recommended: use resolver = "2" in your Cargo workspace

Projects scaffolded for Holochain 0.1 didn’t include this, but new projects scaffolded for Holochain 0.2 and onwards do. You can read about this configuration option here. The quick summary is that it changes the algorithm that Cargo uses for resolving crate features. We use this on the Holochain project and recommend it for hApp projects because it results in less surprising behavior when adding dependencies on Holochain crates.

In your project’s Cargo.toml, look for the [workspace] section. Add the resolver = "2" option here.

You should check that your project still builds correctly with cargo build and probably run your tests too! If everything is still working then you’re done; you can just leave this option set and it should help you avoid some future build problems.

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.2! Good luck, and if you need help then please do get in touch on Discord or open a Github issue.