This documentation is for the prototype version of Holochain, written in Go.
There is a new version under development, for which there is new documentation and a Developer Preview pre-release.
View the future of Holochain here.
The documentation for the holochain-proto version will remain available online.

Why use anchors?

Let's say you're working on a P2P Twitter clone (aka Clutter). People type their meows and send them out into a massive unsearchable DHT. If you're browsing the site, you won't be able to find their posts unless you know the hash of each one. Considering that there are trillions of potential hashes, you wouldn't have much luck actually searching for them.That is unless you use an anchor.

An anchor provides an easy to find, fixed hash, from which you can link to things that are not so easy to find. For example, you can make an anchor for someone's Clutter handle, and then from there you can link to things associated with them (meows, followers, following, favorites, lists, their current public key, etc.). To find the anchor, all you need to know is their handle, then because all content of the DHT is content addressable by hash, you can generate the hash for that anchor to find all the links. See examples below...

With an anchor, you can find all of the meows that are connected to a particular hash tag. For example, you could look for everything tagged with #catridingrobotvacuumcleaner and the anchor would allow you to dig up all meows connected to that.

Note: Passing empty string ('') to anchor finds the root anchor for that type which all sub-anchors should also be linked from. Also passing empty string into getLinks as the tag to retrieve, should get back all the links with any tags.

The mixin makes it super easy. You just need to include the anchor files in your app and add the zome definition to your DNA file.

Including the anchor files

Copy the files from the anchors mixin into your app's DNA folder. The path to the anchors directory should be: yourapp/dna/anchors. Check out the folder structure of clutter.

Adding the anchors zome to your DNA file

You'll already have a zome for your app. You just need to add the anchors zome next to it. Copy and paste it in to your dna.json. Have a look at how it's done in clutter.

Testing the results

You can test to see if anchors is working in your new app, by copying over the anchors.json in the anchors test folder into the test folder of your application. Then run hcdev test .

How it all works under the hood

If you want to understand how the mixin works under the hood - keep reading.

What is an anchor?

Remember that Holochain is essentially a key value store. The only difference from something like Cassandra/Dynamo DB is that all of the keys are cryptographically hashed. The structure of a DHT might look something like this (warning: this is a vast oversimplification and is not really how it is stored):

In this case the entry with hash QmZWKNcabXJQCb9Nh8acxHbB1oo3BXedKF6pZK28rnoP8Q is an anchor and QmTVEBMWRZyWoQtJSvkuEB9okjP9JXJf1bkXrxXU8rVdXp and QmNPoiEp7WQ761mkxNe6xqvATGm6og72Noyk5enUM6YwDq are linked to that anchor.

If we can locate the anchor, we can retrieve all the messages connected to it.

How do anchors work?

The hash for the anchor QmZWKNcabXJQCb9Nh8acxHbB1oo3BXedKF6pZK28rnoP8Q looks a bit impeneterable. How could you ever locate that?

All you need to do is use makeHash. The makeHash function returns the same hash for a DHT entry, that the DHT uses to store the entry, if you give it the same input that is held in the entry.