Zooming In on the Install Process and Developer Resources

Holochain Dev Pulse 27

Summary

We’re doubling down on developer experience — particularly the installation process and our beginner learning resources. This release brings a new feature or two and a couple of small breaking changes. Some groundwork for privilege management has been laid out and there’s a very exciting development in our DHT networking layer!

Highlights

Developer Experience: Testing and Refining First Encounters Developer Experience: New Default Install Process for Linux and macOs Security: `hdk::grant_capability`, Groundwork for In-App Privilege Management API/Breaking Changes: `remove_entry` and `link_entries` Now Return Hash Networking: Local Peer Discovery with mDNS! Networking: Persistent Transport IDs for Happier Restarts API/Security: Commit Multiple Authors to Entry for Countersigning Documentation: Fixes to JSON-RPC Doc, Reading/Writing Entries, and the Cleanup Of Apps List

Details

Holochain Dev Pulse April 29–May 6, 2019

1. Developer Experience: Testing and Refining First Encounters

This week we took at hard look at the roadblocks that developers hit when they are introduced to Holochain for the first time. First impressions matter — they can draw people into a rewarding experience or they can cause them to get frustrated and quietly leave.

We appreciate everyone’s feedback on the Quick Start Guide. We also conducted some one-on-one user testing and found that both beginner and experienced developers were having quite a few issues with the installation process and/or quick start installation instructions. We’re so glad we took the time to gather some empirical data. It gave us good insight into what developers struggle with, and just as importantly, how it impacts their impression of Holochain. (We’re revamping our install process — read the next section!)

We’re also working on a revamp of the Holochain website complete with an Introductory Guide that presents the concepts you need to know when building an app.

Each concept will come with a tutorial or two that will bring it to life in a simple app! Keep watching this space for more details.

2. Developer Experience: New Default Install Process for Linux and macOs

Feedback from user testing, as well as our own awareness of installation difficulties, has resulted in a new install process for both app devs and Holochain-Core contributors. It now only takes two terminal commands! This goodness is brought to you by NixOS, the same toolkit we’re using to build the HoloPortOS.

We invite you to try out the Quick Start Guide and let us know how it went. Be generous with your critique — feedback will help us improve the process even more.

Quick Start Installation

3. Security: `hdk::grant_capability`, Groundwork for In-App Privilege Management

The Rust HDK now has a new API function: `hdk::grant_capability()`. This lets agents create new capability grants and commit them to their source chains. It brings our capability-based security model into the realm of app development.

You may ask, “What is a capability grant?” It’s a general-purpose way for an agent to authorize others to call their zome functions. These agents could be the user’s GUI, a bridged DNA, or an entirely different agent on the DHT.

These are early days for this feature, so there’s not much to play with right now. We’ll talk more about it when the rest of the necessary functionality lands!

4. API/Breaking Changes: `remove_entry` and `link_entries` Now Return Hash

In the Rust HDK, `hdk::remove_entry()` and `hdk::link_entries()` now return the hash of the newly created entry rather than a unit/nil type `()`. If you have any zome functions that end with either of these functions, you will either need to change the return type of the function’s signature or explicitly return `()`.

If this function returns a hash, what’s actually happening when you remove an existing entry? You may be aware that all data is immutable once it’s committed to the source chain or DHT. When you remove an entry, it doesn’t actually get deleted — it just gets retired. A deletion action has its own special `Deletion` entry type on your source chain; when you commit it, it adds a piece of metadata to the original entry marking it as `Deleted`. This happens on your source chain and the DHT.

Links work the same way — you commit a special `LinkAdd` entry to your source chain, which also adds a piece of metadata to the linked entry that points to the link’s target.

Because each of these actions happens by committing a special type of entry to your source chain, they have hashes just like any other entry.

5. Networking: Local Peer Discovery with mDNS!

Network Discovery

This is an exciting development — the n3h networking library that powers Holochain’s DHT now looks for peers on your local LAN. This is turned on by default if you’re using n3h’s default ‘real mode,’ which maintains separate DHTs per DNA.

The goal is to revolutionize local testing and events such as hackathons by removing the need top copy/paste a bootstrap node’s URI into other nodes’ configs!

When we achieve full function, it will be possible to just clone your DNA onto each participant’s machine, start it up in the Conductor, and watch all the nodes find each other automagically.

If you want to turn this behavior off, you can pass this config to n3h via stdin or a config file:

{“mdns”: {“enabled”: false}}

Addendum: In Dev Pulse 25 we didn’t mention that you no longer need to download n3h separately; the dev and production conductors now download the correct version for you.

6. Networking: Persistent Transport IDs for Happier Restarts

N3h will now retain the same ‘transport IDs’ as the previous session when it is stopped and started. This is not specific to real mode, it is also used in hack mode. In the code it was renamed ‘machine ID’ since the idea is to uniquely identify a device, despite a change of IP address or agent. However, you can have many machine IDs for one device if you run multiple conductors with different persistence folders.

N3hHackMode Code

Previously, n3h would generate new transport IDs for each DNA on each run. This caused troubles when a node set up as a ‘bootstrap node’ was restarted because other peers would no longer be able to find it. It also created more ‘churn’ of nodes’ peer routing tables as nodes changed and rebroadcast their transport IDs.

Together, this change and the introduction of mDNS discovery mean that networking is a lot easier to set up and keep running.

7. API/Security: Commit Multiple Authors to Entry for Countersigning

We’ve added a function called `hdk::commit_entry_result()` that allows you to attach additional ‘provenances’ or pubkey/signature pairs to entries. This is helpful for things like countersigned transactions, collecting votes, and other things that require the approval of multiple agents. Note that you’ll still have to find some way to collect signatures from those parties — by asking them to sign the entry via `send()`/`receive()` for example. It’s also a good idea to check the signatures you receive via `verify_signature()` before committing them to your own source chain!

8. Documentation: Fixes to JSON-RPC Doc, Reading/Writing Entries, and the Cleanup Of Apps List

A few updates from documentation land:

We updated the JSON-RPC article to reflect the recent change to the inner args format. If you visited that article in the past week, you may have noticed that it was still using the newly deprecated format. Sorry we missed that detail!

We’ve been cleaning up our official list of apps built with Holochain. We’ve removed all the apps built on Holochain-Proto, and archived their GitHub repos if they belonged to us. This reflects the fact that the Rust refactor is coming to maturity as a usable and useful app development framework!

We’ve added a new article to the Guidebook, Read & Write Data Operations, which is all about committing, deleting, updating, and retrieving entries from the source chain and DHT. This is key to being able to do things in a Holochain app, so it’s wonderful to have a good overview in addition to the API documentation. This new article is 70% complete.

Development Status:

Building an App/Platform on Holochain? We want to hear from you!

Are you building on Holochain? We would love to connect and hear more about your app/platform. Please, take a few moments to fill out this survey! Our goal is to list all the projects building on Holochain on our website.

Stack Overflow: Expand the Holochain Knowledge Base

Help us grow the Holochain knowledge base on Stack Overflow!

Submit your Holochain question.

Submit your Holochain Rust question.

Contribute to Documentation

Lastly, to all of our readers — we’d like to encourage you to submit an issue or a pull request if you are interested in contributing to code. If you have a passion for, or would like to see, improvements made to the documentation, submit a new issue or add a suggestion to the Holochain Guidebook.

Connect with the developer community: