Updates to Entry Definitions, Conductor Network Configuration, and More

Holochain Dev Pulse 37

Summary

Two recent releases have brought with them a variety of updates. We’ve extended the functionality of DNAs and added more sophistication to the configuration files. The HDK now has encryption/decryption, and we made it easier to handle different entry types. Altogether, developers should find that several tasks are easier to understand and that they are less likely to be tripped up in their work due to errors.

Highlights

1. Added Properties to Entry Definitions

2. Added Type Field to Conductor Network Configuration

3. Added Encryption and Decryption Methods in the HDK

4. DNAs Can Be Run in Different Places

5. Added hc hash CLI Subcommand

6. Breaking Change: Conductor Configuration Sanitization

7. Breaking Change: Validation Callback

8. Breaking Change: Reduction in App-Spec’s DNA File and Reformatting .hcbuild Files

Details

Holochain Dev Pulse July 8–July 15, 2019

Release 0.0.22-alpha1 Changes

1. Added Properties to Entry Definitions (#1558)

We want zomes to be more comprehensible at a glance, so we’ve changed how entry definitions are handled. Entry types used to have description fields, but we felt that more information needed to be conveyed than just text. We therefore changed the description field into a properties field, which is a JSON object with arbitrary data, instead of a single string.

This change enables DNA developers to add more metadata to their entry types so that UIs can automatically pass information when rendering entries. These fields can be retrieved using the entry_type_properties HDK function.

This addition is especially important in the context of dealing with different entry types. You either have a UI that is generic for several apps or DNAs and can use these hints for rendering; or you already have different entry types and an app to combine current zomes for which you can use this information. We are still exploring how this addition would be most helpful and in what types of use cases.

UI

Importantly, this field is still called a description in new DNAs; they are outwardly presented as properties, but we treat them as JSON strings internally. In the future, we may need to change the field in the HDK macro.

2. Added Type Field to Conductor Network Configuration (#1540)

This update affects the lib3h repository; you must now add type=”n3h” for current configuration files to work. This change is one step, but a big one, in our transition from n3h, which is based in Node.JS, to lib3h, which is Rust-based, for networking. Our networking team is still laying the groundwork for this transition, but we do expect it to happen once lib3h is ready.

Network

3. Added Encryption and Decryption Methods in the HDK (#1534)

This change gives zome developers the ability to encrypt or decrypt messages with the Holochain HDK using an agent’s private keys. As you may know, public/private key pairs form the basis for establishing one’s identity on a hApp network, as well as for restricting access to, or digitally signing, one’s data.

Encrypting Key Pair

For example, an entry data might contain secret IDs that you would not want to reveal to others. Previously, you could only encrypt and decrypt such IDs with your own key.

The Holochain HDK will now give you the option to encrypt IDs, as well as decrypt them, using another’s keys.

4. DNAs Can Be Run in Different Places (#1561)

This change allows developers to specify where the DNA is located and run it in different places. Specifically, you can now add a — dna flag to hc run so DNAs can run outside the standard ./dist/ directory. This change addresses a need that the community brought to our attention.

We had a few zome developers who did not adhere to the normal naming standards for DNAs, which kept hc run from running. We’d established a specific directory structure with hc package and hc run, and while you could override that structure for hc package, you could not for hc run. With the — dna flag, this is no longer the case. Importantly, you will need to know the hash for the DNA, which will be discussed in the next sections.

5. Added hc hash CLI Subcommand (#1562)

With this new command, you can compute the hash of a DNA in the current ./dist/ directory or pass a path to a DNA with the — path flag. When developing, it’s important to know the hash of your DNA, which up to now has been somewhat difficult. Enter hc hash, which will make getting DNA hashes to match (mentioned below in #1335) much easier.

Release 0.0.23-alpha1 Changes

6. Breaking Change: Conductor Configuration Sanitization (#1335)

We made a significant change to how conductor configuration files are handled. Simply put, configurations have to specify the hash of the DNA that is being installed — this is no longer an optional task. The system will now also check that the hash is “sanitized,” meaning that it will make sure that the hash of the DNA in the configuration file matches the file on your local drive. If you have changed your file, it will sign an error and flag a discrepancy. Though we recognize that this change will break some existing configurations, it will also ensure that when you set up a configuration file, you can’t set it up in a way that is not going to work.

Here’s what we mean — the problem with DNA hashes is that you can easily get it wrong. You can run the DNA and accidentally compile the old to the new. We’ve seen some problems arise after debugging, and subsequently discovered that a few members of the Holo Dev Team already had old DNA in their source chain. If they were developing DNA and recompiling it, the Holochain conductor would load the old version without notifying them of a discrepancy.

Now, when you run a production conductor for the first time, it will create a storage space for your DNA in the source chain. Within the source chain, your entry is the stored DNA. If you need to recompile your file later, it will use the file found in storage and you won’t even notice a difference.

7. Breaking Change: Validation Callback (#1563)

There are two cases when making a validation call. In the first, you are the author and you are committing it. The second is when the network requests that you hold on the DHT to hold an entry. There is a flag in the code, EntryLifeCycle, that tells you which case you are in, and some validation functions rely on entries being at the top of the chain in a hold case. As a result, the differences in how the two cases present data causes you have to write your validation routines separately.

DHT

However, we want to make writing validation functions easier.

Validation callback now shows consistent behavior, regardless the case. You no longer have to distinguish between the two cases, which you shouldn’t have to do in the first place.

This is a breaking change because some devs had already written the code to make sure we were distinguishing between the two cases. If you are one of those devs, you don’t have to do that anymore! The EntryLifeCycle flag itself may be deprecated in the future.

8. Breaking Change: Reduction in App-Spec’s DNA File and Reformatting .hcbuild Files (#1577)

We applied a WASM size optimization to our app-spec test suite, reducing its footprint from 18 MB to 6.8 MB.

In order to do this, we had to change the format of the .hcbuild files, since Steps was a map that resulted in non-deterministic ordering. However, the build steps required extra tools used in the correct order (1. compiling binary, 2. running wasm-gc) to make the size reduction possible.

As a result, Steps is now an array. Build files will no longer be compatible with the new version, meaning app developers will now have to modify them — basically, change them from a JSON hash to a JSON array.

Conductor Configuration and a New Format for .hcbuild Files

Development Status:

Learn more about Holochain and join our community!

Website | Mattermost Chat | Youtube | Reddit | Medium | Twitter