I want to introduce you to a new developer tool called Kangaroo. You can use it to bundle up a hApp into an installable binary, ready for use on macOS, Windows, and Linux. It makes it easy for people to start using a hApp, because the installation experience feels like any other app install rather than having to learn about the Holochain Launcher (which is honestly fairly easy but still a bit of a shift from what people are used to).

After I introduce Kangaroo, I’ve got some upcoming events to help you in your development journey and some notes on the newest unstable release in the Holochain 0.2.x branch and its supporting tools and libraries. (Yes, you read that correctly — this is an unstable release. There are known issues with performance and possibly DHT resilience, but there have been a lot of bugfixes in that area and we wanted to get those into people’s hands.)

Kangaroo: Bundle up your hApp and Holochain together

Kangaroo is a tool that makes it easy for you, dear dev, to make installation easy for the people using your hApp. It scaffolds a project structure that contains just enough Holochain and webview to generate a self-contained binary with your hApp in it. The included GitHub actions will then generate installers for all three major desktop OSes, with code signing on the OSes that need it.

As mentioned above, this means that the installation experience feels familiar and easy — there’s no need to install ‘some other thing’ (the Launcher) in order to install and start using a hApp. All they have to do is go to your website or GitHub repo, or their OS’ app store if that’s how you choose to distribute your hApp, download the thing, and install it.

Kangaroo is a bit like Lightningrod Labs’ electron-holochain-template, but builds your hApp on a fully Rusty stack using a webview container called Tauri. That makes binaries smaller, faster, and less resource-consuming than Electron binaries, although you do have to deal with compatibility issues for webview libraries on older OSes. (You can read more about the differences and similarities between Electron and Tauri here.)

Tauri also supports auto-updating; the compiled binary will automatically check for and download new hApp binaries. Keep note that, if your version bump signals a breaking change per SemVer rules (that is, the leftmost non-zero number increases), user data will not be ported to the new version.

Bundling your hApp with Kangaroo is pretty straightforward:

  • Install the dev dependencies (Rust and Go).
  • Clone, snapshot, or fork the repo.
  • Run npm install in the repo’s working folder.
  • Add your hApp and its UI to the ./pouch folder.
  • Do a project-wide search/replace to change replace-me to your hApp’s name.
  • Add an icon.
  • Add a version number for your hApp.
  • Build the hApp using npm run tauri build.

After that, you can push the repo to GitHub and configure GitHub actions to build the installers for you.

The readme for the repo is well-written and friendly, so you should have an easy time getting started. This tool is new, so please try it out and give the developers your feedback!

Holochain development environment setup support

This upcoming series of calls is an ‘open office hours’ sort of thing where you can come and get guided through the process of setting up all the dev tools you need to create hApps. We do ask that you try the quick start guide first, but if you hit a roadblock, come to one of these calls with your needs, questions, and frustrations to get unstuck!

The first session is on Thursday, 3rd August at 13:00 UTC. Here’s the event page, which has a registration link. See you there!

Developer-focused AMA in August

This will be the first in a new quarterly series of Holochain AMAs just for developers. Rather than a livestream, it’ll be an intimate Zoom call where developers and other dev-related folks can ask focused questions about the things that matter to them. (We will publish the recording afterwards though!)

We’ve had one or two Holo/Holochain AMAs targeted at developers in the past, but this will be a dedicated AMA just for you, with a regular rhythm that you can put on your calendar. This event joins the fabulous community-led Holochain In Action calls in fostering a community you can journey with as you develop your skills (and your applications).

The first AMA will be on Tuesday, 15th August at 17:00 UTC. Submit your questions here and register for the Zoom call here.

Even if you can’t make the call, please register anyway. This will ensure that you will get notified right away when a link to the recording becomes available.

Online developer training in October

Along with Marcus and Guillem from our education partner Mythosthesia, we’re co-hosting another online hApp developer training course this October. Just like the first one, it’ll be four days of instruction followed by a weekend hackathon. And just like the first one, the curriculum will be fantastic and you and your fellow students will learn a lot together. Read the landing page to learn more and register. Make sure you get your application in by 18th September!

Holochain 0.2.1 (unstable): Bug fixes, small improvements, and big changes

As mentioned in previous Dev Pulses, we discovered some performance issues and other bugs in Holochain 0.2.0. We promised a quick turnaround to fix these issues, but some of them have been challenging to diagnose.

We’ve recently released Holochain 0.2.1, which tackles quite a few of these issues. We’re still aware of some outstanding issues, so we’re pronouncing this release unstable. But if you’ve been itching to update your hApp to the 0.2.x series, this release is ready for development with new features and improved performance over the 0.1.x series, but do expect to run into issues. If you need stability, stick with 0.1.5 or wait for a later release in the 0.2.x series. We intend for this release to be API-stable with future 0.2.x releases, but we may need to make unanticipated breaking changes in the service of fixing bugs.

Here’s a list of changes since 0.1.5, including those that landed in 0.2.0:

General

  • Breaking/new (network protocol): This is one of the two big news items with this release — a new WebRTC-based networking protocol, which lets us rely more on off-the-shelf libraries and tools than our QUIC-based protocol did. It means we can use standard WebRTC ICE (interactive connectivity establishment) strategies for making peer-to-peer connections over the public internet, and reduces our burden of security compliance due to the fact that WebRTC tools and libs are more mature and better maintained.
  • New (conductor): The conductor now supports ‘blocking’, in which a peer adds other peers to their block list. Blocking is the foundation of everything we’ll be doing to create the validation-based network immune system in future releases, and can also be used for things that don’t involve validation, such as community moderation or removing an employee from workspaces when they leave the company.
  • Breaking (conductor config): Networking types proxy and quic have been removed; please transition to webrtc if you have any conductor config files lying around (this is likely if you’ve generated test configs with hc sandbox generate). (#2208)
  • Breaking (holochain Rust crate): The feature test_utils, which builds Sweettest into the resulting binary, is no longer default. If you’re relying on the holochain crate to use Sweettest, use default-features = false and the feature sweetest (note only one t). (#2281)
  • New (networking, conductor config): There’s a new network tuning param called gossip_arc_clamping that lets you optionally override automatic arc size tuning to be either full or empty, allowing a node to claim responsibility for all or none of the DHT. This lets resource-constrained nodes (like cell phones) offload their work to willing ‘full nodes’, and is also accompanied by a new ability of standard nodes to tune their DHT coverage to compensate for freeloading (legitimate or otherwise). (#2352, #2380)
  • New/experimental: A chain head coordinator feature allows multiple machines to share the same source chain. This will be used mainly for redundancy in the Holo hosting network. (#2502)
  • Bugfix: A bootstrap server must be reachable when a conductor with installed hApps is launched. This fixes an issue where hApps would get paused if the conductor was launched without access to a bootstrap. (#2419)
  • Bugfix: Attempts to duplicate a clone cell (that is, a cell with the same DNA and agent hashes as a cell that already exists) now fail. (#1997)
  • Bugfix (networking): A lockup on certain network layer error types has been fixed. (#2315, tx5 #31)
  • Bugfix (networking): Mismatched gossip rounds, caused by rounding errors in storage arc boundaries on multi-agent conductors, has been fixed. (#2332)
  • Bugfix (networking): A bug in which self-authored data couldn’t be retrieved if the author wasn’t also responsible for that region of the DHT has been fixed. (#2425)
  • Bugfix (networking): A race condition that caused network instability (temporary blocking of newly joined nodes) has been fixed. (#2534)
  • Optimisation: When uninstalling an app, any DNAs that are no longer used by any other app will have their DHT data removed. (#1805)
  • Optimisation: Capability grant verification during a zome function call is faster, which speeds up calls (especially remote calls) considerably. (#2097)

Bundle manifests

  • Breaking/bugfix (DNA manifest, conductor APIs): name in a DNA definition no longer affects/forks the DNA hash. (#2099)
  • Breaking (app manifest): version is renamed to installed_hash, and now only accepts a single optional DNA hash value, where previously it could accept a list of values. (#2157)
  • New (app manifest): A new cell provisioning strategy clone_only has been implemented, designed for situations where a cell shouldn’t be instantiated for a DNA immediately upon app installation. This is useful for when you want to create clones of a DNA but don’t want to have a ‘default’ cell. (#2243)
  • New (zome manifest): The zome manifest can now take a dylib argument which points to a WebAssembly module compiled specifically to work on iOS. It’s used with artifacts produced by hc dna pack --dylib-ios option. (#2218)

HDI and HDK

  • Breaking/new (HDI/HDK): HoloHash::retype() is removed from the public API, along with From<AnyDhtHash> and From<AnyLinkableHash> impls. (#2191) Casting can now be done via the remaining impls, new TryFrom impls, or a new .into_agent_pub_key() conversion function (#2283).
  • Breaking/new (HDI/HDK): ChainQueryFilter now lets you filter on multiple entry and action types in one query. The query builder API hasn’t changed, but the underlying data structures have, so you’ll still need to recompile your code. (#2302)
  • Breaking (HDI): The `DhtOp``validation rules have been significantly expanded on and changed. While the data structures and API haven’t changed, stricter rules may cause some previously accepted ops to be rejected. Run those automated tests! (#2215)
  • New (host API): block_agent and unblock_agent have been added to allow for app-level, agent-driven blocking of peers. This means that a hApp can allow an agent to add other peers to their blocklist, rejecting any signals, remote calls, or gossip attempts from them. (Their DHT neighbours may still ask them to validate and store DHT data for the blocked peers though.) This is useful for moderation of things that can’t or shouldn’t be covered by validation, especially of the subjective kind. (Note: as far as I can tell, these functions haven’t yet been wired up to the network plumbing, nor do they yet have convenience functions in the HDK. But the functionality that makes it possible is all there.) (#1828)
  • New (HDK): OpType is now FlatOp, and Op::to_type() is now Op::flattened(). The old names still exist as aliases, though, so this isn’t (yet) a breaking change. (#1909)
  • New (HDK): Path has a String<TryInto> conversion for easy string representation. (#2306)
  • New (HDK): There’s a new count_links function that works like get_links but only returns a number. (#2430)
  • Bugfix (HDI): Fixed a problem with validation of private entry data, where Op::to_type() would fail for StoreEntry ops. (#1910)

Conductor APIs

  • New (admin API): DnaStorageInfo gives information about the data that is being stored for a DNA across all apps/cells that use it. (#2147)
  • New (admin API): DumpNetworkStats is an endpoint that lets you do diagnostics on the conductor. (#2182)
  • Bugfix (admin API): Supplying a network seed during InstallApp now properly updates the network seed for roles whose provisioning strategy is set to None. (#2102)

hc CLI

  • There have been a lot of small documentation updates and bugfixes; you should find the dev experience slightly smoother now. (#2125)
  • Breaking: hc sandbox run now outputs a new string when an app port is successfully provisioned. If you’ve written tools to help you manage conductors via this command and are watching for this string, you may to update your code. See this diff for details.
  • Bugfix: A comma-separated argument passed to hc sandbox generate --directories is now parsed properly as multiple directories. (#2080)
  • New: hc dna schema, hc app schema, and hc web-app schema output JSON schemas for integration into your favourite IDE. (#2138)
  • New: hc sandbox generate has a new in-process-lair option, which comes with an associated changes to make hc sandbox run respect the config and only launch an out-of-process lair instance when required.
  • New: hc dna pack now takes a --dylib-ios option, which produces iOS-optimised WASM files. This is paired with a new dylib property in the zome manifest. (#2218)
  • New: The new hc run-local-services command runs a local WebRTC signal server whose URL can be passed to hc sandbox generate network webrtc, as well as a local bootstrap server. These aren’t appropriate for use as production servers; rather, they’re meant to be used during testing. (#2265, #2353)

For more information, read the full changelog for 0.2.1 all the way back to 0.2.0-beta-rc.0.

JavaScript client 0.15.0: Holochain 0.2 support

If you’re planning to update to the unstable Holochain 0.2.1, you’ll also want to update the JavaScript client in your hApp’s UI to 0.15.0. Here’s a list of changes:

  • Breaking: The input params for the networkInfo API endpoint have been changed to match changes in the conductor API.
  • Breaking: The client and websocket classes have been refactored to accept URL objects rather than strings.
  • Breaking: Error responses from the conductor are thrown as new instances of HolochainError, which extends Error.
  • New/breaking: The dependency on the encryption package tweetnacl has been replaced with @noble/ed25519, because tweetnacl is getting old — so old that it didn’t support modern ES modules. This may break your build pipeline because your bundler will need to target ES2020 in order to support BigInt. The crypto module is imported conditionally — it’s only needed in Node.js, as browsers use the Web Crypto API instead.
  • New: When making a WsClient request, the client will try to reconnect automatically if the socket is closed.
  • New: admin API endpoints for storageInfo, dumpNetworkStats, and updateCoordinators.
  • Changed: The default timeout for API calls has been bumped from 15 seconds to 60 seconds.

Read all the changelogs from v0.15.0 back to v0.13.0 to see everything that’s changed.

Tryorama 0.15.0-rc.1: Holochain 0.2 support

And of course, with an update to the JS client, Tryorama needs to change too. It inherits all the changes in the client, along with:

  • Breaking: A local signal server (provided conveniently by hc run-local-services) is required for Tryorama tests, but optional for tests orchestrated by TryCP.
  • Breaking: With the update to Holochain 0.2.1, there’s a change in Tryorama that depends on a changed output from hc sandbox run on conductor startup.
  • Breaking: runScenario re-throws errors that it catches rather than consuming them.
  • Breaking: App websockets are decoupled from conductors, to better imitate real-life scenarios, in which different agents would not be using the same websocket to connect to their own conductor.
  • New: dhtSync is a new utility function that waits until two players’ views of the DHT are identical.
  • Changed: runScenario catches and outputs errors.
  • Optimisation (TryCP): App installations for a conductor, and conductor installations for a client, are done in parallel.

Read all the changelogs from v0.15.0-rc.1 back to v0.13.0.

Cover photo by Suzuha Kozuki on Unsplash

Install Holochain Learn about Holochain Join the Discussion