Skip to section
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:
FolderWithAppNamednadna.jsonFolderWithZomeNameZomeName.jsDataSchemaDefinition.json
FolderWithOtherZomeNameOtherZomeName.zyOtherDataSchemaDefinition.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.
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
An integer value describing the version of this DNA file.
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.
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?
Specifies the minimum usable version of the Holochain library for the app for app code compatibility as well as data structure compatibility.
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.
Settings for DHT behaviors and requirements specific to your application. In the future, there will be many more DHTConfig settings.
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
Name of the Zome. What functionality is this part of your application managing? No spaces.
Description of the functionality/features being managed within this Zome.
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.)
An object with zome specific configurations.
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.
File name to find the code for this Zome. By convention, please use <ZomeName>.<LanguageExtension>, like chat.js, sort.zy (for zygomys Lisp). The file specified must be located within the Zome folder.
A list of function names that are available for bridging apps to call. Note: means this zome must define a bridgeGenesis() function.
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)
Name of the function as it appears in its definition in the code file for the Zome.
Valid Options: string, json
How are parameters structured when passed to this function, as well as how the results are returned.
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.
Name of this Entry Type (or Data Structure)
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.
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.
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.