DNA

Skip to section

Version Zome.Name ZomeFunction.Name
UUID Zome.Description ZomeFunction.CallingType
Name Zome.RibosomeType ZomeFunction.Exposure
RequiresVersion Zome.Config  
Properties Zome.Config.ErrorHandling     ZomeEntryType.Name
DHTConfig Zome.CodeFile ZomeEntryType.DataFormat
DHTConfig.HashType     Zome.BridgeFuncs ZomeEntryType.SchemaFile
Zomes Zome.BridgeTo ZomeEntryType.Sharing
  Zome.Functions  
  Zome.Entries  

 

Introduction

With familiarity with the command line tools already, we can cover how a Holochain application is structured, configured, and built. Most fundamental to this is what we call the application "DNA". It's how you configure a Holochain application, and it's covered in detail here.

Every Holochain application is simply a folder with files, and which contains at least a folder called "dna" with a single DNA file in it, called dna.(json, yml, toml). It can be written in JSON, YAML, or TOML. The DNA file acts as an entry point to run your application, and every functional aspect of your app will have to be referenced in it. Like DNA itself, it is a set of instructions.

The DNA file specifies many things, such as application name, which version it needs, and configuration of the "DHT", but most importantly it defines the relevant schemas for data, and functions which perform operations in an app. Furthermore, Holochain defines a way to break down your app functionality into modules, which are called "Zomes", and this is fundamental to your DNA. To make this more clear, here is an example folder structure showing only the DNA parts of a Holochain application:

  • FolderWithAppName
    • dna
      • dna.json
      • FolderWithZomeName
        • ZomeName.js
        • DataSchemaDefinition.json
      • FolderWithOtherZomeName
        • OtherZomeName.zy
        • OtherDataSchemaDefinition.json

As this folder demonstrates, a Holochain app can have multiple Zomes. Each Zome can be written in any of the Holochain supported languages (JavaScript and Zygomys/Lisp currently). A Zome will be ignored unless it is entered into the dna.* file. 

When developing an application, we will have to interact with the dna.* file regularly, and forgetting about it will be a source of grief, so watch out! Below is the complete documentation reference for properties you can specify in the DNA file.

Depending on which language you choose, JSON, YAML, or TOML, your syntax will look a bit different, but the properties are the same. 

JSON Example | TOML Example

HoloWorld Tutorial: Writing the application DNA

Now that configuring the DNA is familiar, you can jump into the details of how to write the application logic in code

 

Properties

 

Version: Integer

An integer value describing the version of this DNA file.

 

 UUID: String

A UUID will make sure your new Holochain is unique and doesn't accidentally collide with the Holochain whose code you have cloned. For example, if you want to create a new and different instance of a chat application, you can clone the DNA of a chat, and the fact that we generate a new UUID for you, will keep you from accidentally creating a new chat team in the same data-space/DHT as your old one. Thus, when creating a new app, you should use the hcdev init --clone <source-app> rather than simply copying the files manually.

 

 Name: String

The name of the application. It is best to edit this if you are cloning an existing chain to serve a new purpose. For example, if you want to create a new slack team, what is the new team called?

 

 RequiresVersion: Integer

Specifies the minimum usable version of the Holochain library for the app for app code compatibility as well as data structure compatibility.

 

Properties: Object

An object of app defined strings that are available to the app via the propertyfunction. This is especially useful for applications that will be cloned and customized.

 

DHTConfig: Object

Settings for DHT behaviors and requirements specific to your application. In the future, there will be many more DHTConfig settings.

 

DHTConfig.HashType: String

Valid Options: sha-1, sha2-256, sha2-512, blake2b-512, blake2b-256, blake2s-256, blake2s-128

Identifies hash type to be used for this application. Should be from the list of hash types from the multihash library

 

Zomes: Array-of-Zome

 

Zome.Name: String

Name of the Zome. What functionality is this part of your application managing? No spaces.

 

Zome.Description: String

Description of the functionality/features being managed within this Zome.

 

Zome.RibosomeType: String

Valid Options: js, zygo

Which virtual machine should be used to process the code in this Zome? js is for JavaScript, zygo is for Lisp, (and as we build them, there will be: Ruby, Lua, etc.)

 

Zome.Config: Object

An object with zome specific configurations. 

 

Zome.Config.ErrorHandling: String

Valid Options: returnErrorValue, throwErrors

Use returnErrorValue to check the result of function calls for errors yourself. Use throwErrors to have the application throw an error when it hits one.

 

Zome.CodeFile: String

File name to find the code for this Zome. By convention, please use <ZomeName>.<LanguageExtension>, like chat.jssort.zy (for zygomys Lisp). The file specified must be located within the Zome folder.

 

Zome.BridgeFuncs: Array-of-String

 A list of function names that are available for bridging apps to call. Note: means this zome must define a bridgeGenesis() function.

 

Zome.BridgeTo: String

The hash of an app that this zome expects to bridge to. Note: means this zome must define a bridgeGenesis() function.

 

Zome.Functions: Array-of-ZomeFunction

The functions that are used inside this Zome that you want to expose to be callable by some other part of the holochain system (such as a web UI, or accessible to another Zome)

 

ZomeFunction.Name: String

Name of the function as it appears in its definition in the code file for the Zome.

 

ZomeFunction.CallingType: String

Valid Options: string, json

How are parameters structured when passed to this function, as well as how the results are returned.

 

ZomeFunction.Exposure: String

Valid Options: public, zome (default: zome)

Defines which sources are authorized to call this function. If you do not want a function in your file to be callable by any zomes, or anywhere externally, simply do not list it in the Zomes. Functions section of the DNA. Options: if Exposure is left off entirely as a property, the function defaults to being usable only by other zomes in the app. If set to public, the function is callable over the webserver.

 

Zome.Entries: Array-of-ZomeEntryType

 

ZomeEntryType.Name: String

Name of this Entry Type (or Data Structure)

 

ZomeEntryType.DataFormat: String

Valid Options: string, json, links

What format is this data structure? A simple string, a more complex json object or links, which are a predefined data structure used for creating semantic links between entries in the DHT.

 

ZomeEntryType.SchemaFile: String

The file name of schema or language schema directive (e.g. "blogpost.json"). You can leave this out of the DNA if there is no schema file (for cases where ZomeEntryType.DataFormat is type string or links). The file specified must be located within the Zome folder.

 

ZomeEntryType.Sharing: String

Valid Options: public, private

With a value of public entries are automatically shared to the DHT after being committed to your chain. With a value of private entries are NOT shared to the DHT, and remain only on your source chain.