Two weeks ago I promised an update on the status of all the moving pieces of the Holochain development experience. I wanted to do it once it was ready for hApp devs to port their existing codebases over to the new beta release candidate, and while it took longer than we expected, it’s finally here. And not only that, but the new scaffolding tool is ready for new devs ready to build their first hApp!

Here’s a full list of things that are ready for existing and new devs:

  • Holochain 0.1.0-beta-rc.2
  • HDI 0.2.0-beta-rc.1 and HDK 0.1.0-beta-rc.1
  • The hc command-line tool, including hc launch and hc scaffold
  • Tryorama, the hApp testing framework
  • The JavaScript client
  • Integration of all the above into Holonix, the Holochain development environment

Here are the things that are still being updated:

  • Holochain Launcher for end-users
  • The DevHub hApp for distributing hApps
  • The Rust client

Holochain release notes

Holochain 0.1.0-beta-rc.0: Signed zome calls, API and gossip changes

Release date: 15 December 2022
HDI compatibility: 0.2.0-beta-rc.0
HDK compatibility: 0.1.0-beta-rc.0
Breaking changes: admin API, app API, network protocol

The developers have packed a fair number of changes into this release in order to present a first release candidate that resembles our vision for the beta release as closely as possible. Read on to learn what you need for refactoring your hApp and tests.

Breaking (app API): The change with the biggest impact is that all zome calls must have a valid capability and be signed. The end-user Launcher hosts UIs in a WebView and signs calls with the author key using the built-in Lair keystore, which lets it use the author capability for all calls. That means you don’t need to worry about hApps deployed for use in this context. The Holo-hosted context has also had support for built-in signing and now applies it to zome calls. Finally, the web browser context lets you authorise a browser-generated public key for signing calls. There are some other changes to the RPC message envelope format, but the JS client lib already supports those. (#1510)

Breaking (admin API, app API): The two conductor APIs have had name changes and removals of some deprecated endpoints. (#1662, #1704, #1707, #1719) In the admin API:

  • The deprecated InstallApp has been deleted, and InstallAppBundle has been renamed to InstallApp. (Note: this endpoint can receive app bundle manifest blobs or filesystem paths.)
  • The deprecated ActivateApp, DeactivateApp, ListActiveApps, and ListEnabledApps have been removed.
  • RestoreArchivedCloneCell has been renamed to EnableCloneCell and moved to the app API.
  • DeleteArchivedCloneCells has been replaced with DeleteCloneCell, which only allows the deletion of one cell at a time.

In the app API:

  • ZomeCall has been renamed to CallZome.
  • ArchiveCloneCell has been renamed to DisableCloneCell.
  • EnableCloneCell (formerly RestoreArchivedCloneCell) has been moved here from the admin API.
  • GossipInfo has been replaced with NetworkInfo, which now returns only the number of ops a node expects to receive and their combined size. (#1662)

Breaking (admin API, app API): All data structure names (struct names and fields, enum names and variants) are serialised to snake case over the WebSocket ports. (#1694)

Breaking (network protocol): Gossip rounds no longer transfer ops; they only share information on what ops should be transferred, for later transfer via a processing queue. This is intended to break up network bottlenecks as part of our ongoing real-world performance improvement work for beta. (#1662)

We’ll keep testing the impact of this change in the coming weeks, but preliminary automated and human testing with simulated and real networks is looking very good. The DHT feels more ‘live’, which is exactly what we want to see as we get Holochain ready for production-ready hApps serving real users.

New: The hc command has gotten the ability to run subcommands — any commands in your system’s PATH that start with hc-. This includes the new hc launch and hc scaffold commands: hc launch uses the Launcher in CLI mode to start a hApp and open up a WebView window, and hc scaffold is a powerful new tool that lets you build out boilerplate code really quickly. (#1680)

Holochain 0.1.0-beta-rc.1: Bug fix in app installation

Release date: 16 December 2022
HDI compatibility: 0.2.0-beta-rc.0
HDK compatibility: 0.1.0-beta-rc.0
Breaking changes: none

Bugfix (admin and app APIs): This is exactly why we have release candidates, folks — to find and fix bugs. As part of the work getting the Launcher updated to 0.1.0-beta-rc.0, we discovered some bugs in a couple API functions. (#1725)

  • The admin API’s InstallApp was returning an empty set of cells; now it returns the cells that were installed.
  • The app API’s CallZome would let you call functions in disabled clone cells; now it returns an error.

Holochain 0.1.0-beta-rc.2: Wildcard cap grants

Release date: 23 December 2022
HDI compatibility: 0.2.0-beta-rc.1
HDK compatibility: 0.1.0-beta-rc.1
Breaking changes: HDI, HDK, admin API

Breaking (HDI, HDK, admin API): The GrantedFunctions type in a capability grant has changed to an enum, with which you can specify either a list of functions (as before) or a wildcard. This was prompted by the need to make Tryorama tests easier to write after signed zome calls became mandatory, but it can also be useful for UIs. (#1732)

Read the full release notes for the last three releases.

Known issues

  • The ‘latest’ version of the documentation for the release candidates, including hdi, hdk, and holochain_conductor_api, are pointing to the pre-beta-RC version; use the version selector at the top of the page to choose the latest version.
  • The standalone holochain binary sometimes crashes on macOS after startup.
  • Holochain occasionally errors out on startup when there’s no network connection — if you can reproduce this, please let us know. (#1580)
  • If a countersigning session fails, the results returned by must_get_* in the middle of the session (either in the zome call or during validation) are inconsistent with the actual DHT state.
  • macOS builds of the Lair keystore are currently having troubles. We intend to officially support macOS (and Windows via WSL2) for developers by the beta in January.
  • Passing InstallApp a large hApp bundle as a blob over Websocket can fail; we believe this is because of a WebSocket transfer limit.

Client release notes

JavaScript client 0.10.0 to 0.10.4: Holochain/Holo API unification

I’m going to collapse the 0.10.x release series into one changelog, because (a) none of these releases support Holochain 0.1.x (the only supported version is 0.0.175), and (b) the work all pertains to the unification of the Holochain JavaScript client with the Holo Web SDK. Once this work is done, you’ll be able to code to one API and swap out the connection backend based on the environment the app is running.

  • 0.10.0, released 7 December 2022, updates the client to work with Holochain 0.0.175, which included some changes in the HDK and conductor APIs that ripple out to the client. It also introduces AppAgentClient, a common interface for accessing hApps via a local connection or the Holo hosting network. (Currently the only implementation is AppAgentWebsocket, which uses a local connection.) As the changelog says, “hApp devs will now be able to write the majority of their client code using the AppAgentClient interface, completely agnostic as to whether they're in a pure holochain or holo context.” Support has also been added for the admin API’s GossipInfo endpoint, which lets a UI display DHT health info. (Note: this endpoint will change in Holochain 0.1.0-beta.rc0, which means it’s incompatible with this client release.)
  • 0.10.1, released 8 December 2022, changes the event emitter library from events to emittery, to make bundling easier.
  • 0.10.2, released on 12 December 2022, makes the AppAgentWebsocket object available to consumers (note that this is hidden again in 0.11.7).
  • 0.10.3, released on 12 December 2022 as well, replace a dependency on lodash with lodash-es to give better compatibility with modern ECMAScript implementations.
  • 0.10.4, released on 14 December, changes the getLauncherEnvironment function to synchronous. This function is exposed by the backend object representing the Launcher environment with its embedded WebViews in place of spawned browser windows.

JavaScript client 0.11.0: Holochain Beta-RC support, signed zome calls

Release date: 18 December 2022
Holochain compatibility: 0.1.0-beta-rc.0 and 0.1.0-beta-rc.1

In addition to the breaking conductor API changes that came with Holochain 0.1.0-beta-rc.0 (see above), this client also supports the new requirement that every zome call have a valid capability. In general, this is handled automatically or nearly automatically for all three client contexts that this library supports:

  • In the Launcher and Holo-hosted contexts, the environment will handle signing using the author capability (that is, all calls are signed using the private key of the source chain owner).
  • In the web browser context, there’s a new async function authorizeNewSigningKeyPair() that generates a key in-browser and asks the conductor to authorise it using the admin API. This is not secured right now; the conductor will always approve the request. In the future, conductor managers (such as the Launcher) will likely show some sort of popup asking for authorisation, and the in-browser keypair will be secured with a password on page close. Note that this function has a name change in 0.11.4.

JavaScript client 0.11.1 to 0.11.9: Maintenance, bugfixes, and breaking changes

Once we released the updated JavaScript client we discovered some issues that necessitated a series of bugfixes. There are also some refactors of previously introduced functionality. Versions 0.11.1 to 0.11.8 all support Holochain 0.1.0-beta-rc.0 and 0.1.0-beta-rc.0, while 0.11.9 supports 0.1.0-beta-rc.2.

  • 0.11.1, released on 18 December 2022, introduces a breaking change: the provenance field has been removed from AppAgentCallZomeRequest, because the provenance is provided by the backend in all three contexts (Launcher, web browser, and Holo-hosted).
  • 0.11.2, released on 20 December 2022, fixes a bug in bundling the client module, where the WebSocket serialisation module (written in WASM) wasn’t getting bundled. It also introduces a breaking change, in which all deprecated conductor API functions (see release notes for Holochain 0.1.0-beta-rc.0 above) have been removed. Finally, it adds a TypeScript type definition for the new authorizeNewSigningKeyPair function.
  • 0.11.3, released on 21 December 2022, fixes a bug in serialisation.
  • 0.11.4, released on the same day, refactors the in-browser signing key machinery and introduces one breaking change, renaming authorizeNewSigningKeyPair to authorizeSigningCredentials.
  • 0.11.5, released on the same day, fixes a bug in the Launcher context implementation.
  • 0.11.6, released on the same day, reverts some of the changes introduced in 0.11.3 that caused a regression in compatibility with the Launcher.
  • 0.11.7, released on the same day, introduces a breaking change, re-hiding the AppAgentWebsocket implementation introduced in 0.10.2.
  • 0.11.8, released on 21 December 2022, reorganises some code involved in the new signing code and introduces breaking changes as a consequence.
  • 0.11.9, released on 23 December 2022, introduces a breaking change in the introduction of the new wildcard option for capability grants, bringing it up to date with Holochain 0.1.0-beta-rc.2’s admin API.

Read the full changelogs.

Test framework release notes

Note: if you’re writing Rust-based tests with Sweettest, the version included in the holochain crate is always up to date.

Tryorama 0.9.1 and 0.9.2: TryCP additions and Holochain 0.0.175

Again, I’m collapsing the 0.9.x series of Tryorama because they target older Holochain versions.

  • 0.9.1, released 26 October 2022 and compatible with Holochain 0.0.165 to 0.0.171, features two additions to TryCP, the distributed test orchestrator. ClientsPlayersOptions can take a partial config parameter, allowing you to specify defaults for all players and fill in specific missing config for each player later. And the shortcut function stopAllTryCpServers lets you shut down multiple servers at once.
  • 0.9.2, released 12 December 2022 and compatible with Holochain 0.0.175, bumps the JavaScript client to 0.10.3 and breaks compatibility with previous Holochain releases. The TryCP orchestrator also now exposes the conductor admin API endpoints get_dna_definition and grant_zome_call_capability.

Tryorama 0.10.0: Holochain Beta-RC support

Release date: 21 December 2022
Holochain compatibility: 0.1.0-beta-rc.0 and 0.1.0-beta-rc.1

This is the release needed to test your hApp against the updated Holochain — and test Holochain 0.1.0-beta-rc.* and report any bugs you find! Building on the newest JavaScript client, it reflects all the changes to the conductor APIs that I described above.

Tryorama 0.10.1: Wildcard cap grants

Release date: 21 December 2022
Holochain compatibility: 0.1.0-beta-rc.2

Breaking: After updating Tryorama to the new beta release candidate of Holochain, tests became much more challenging to write because of the requirement to sign all zome calls. Holochain 0.1.0-beta-rc.2 introduced wildcard function matches for cap grants for this very reason. This version adds support for wildcards, allowing you to generate a single wildcard grant at the beginning of your test script.

To update your tests for the Tryorama 0.10 series, check the diffs to see all the name changes, removals, and additions, and read the excellent documentation.

The new scaffolding tool: like Rails, but for dApps!

Guillem Cordoba, creator of the previous scaffolding GUI tool, has applied his skill once again to this tool after receiving feedback from other devs in the community.

Now it’s a lot  like Ruby on Rails’ celebrated scaffolder, which empowered a generation of developers to create basic, working web apps in just a few minutes. This brings that same power to distributed web apps!

It’s all driven by the command line, and it lets you create and edit project folders, DNAs, zomes, UIs, entry and link types, and collections. It’ll even update existing code as you add new features to your hApp.

We think this scaffolding tool will be a game-changer for hApp development. Now, newcomers to Holochain who are comfortable with the command line can create and run a demo forum hApp in less than a minute, and create the basic code for their own hApp in less than an hour. Because the design decisions involved in building a hApp are slightly different from what devs are used to, it guides you through sensible default choices. It’ll also likely have contextual help in the future.

What it makes accessible for new hApp devs, it also makes quick and easy for experienced ones. A lot of boilerplate code can be generated in moments with the various scaffolding commands available.

I’ll feature the scaffolding tool in the next Dev Pulse, but until then, try generating a sample hApp learn more about its project structure in the Holochain developer website, and check out the full documentation. I think you’ll like what you see, no matter your level of experience.

Go forth and code!

If you’re a hApp developer with existing code, now is the time to update your zome, UI, and test code and look for bugs and rough edges in Holochain. Your feedback will help us get Holochain ready for its beta release.

If you’re a newcomer with some Rust and JavaScript experience who wants to start building hApps, I invite you to install Holochain, read the Core Concepts, and try creating something this weekend!

If you’re an end-user who’s eager to start using a real hApp, we have a working-but-unreleased version of the Launcher with greatly improved network performance. We're testing it internally and fix any bugs before we release it. Once that happens, you’ll find a sample sticky notes / kanban app in the hApp store, and you can expect to see more apps as devs update them.

Happy new year to everyone who follows the Gregorian calendar. I wish you great success whatever you’re up to, and I’m excited about all the ways that a rapidly maturing Holochain might be able to support your endeavours.

And by the way — I love talking with people about this stuff. If you’ve got a plan for a way to use Holochain to support new ways of creating, sharing, connecting and doing business, come to the Holochain developers’ Discord and share your ideas. I’ll be there to help you figure out how Holochain can fit into your plan.

Cover photo by Parker Hilton on Unsplash

Install Holochain Learn about Holochain Join the Discussion