On the way to trying to answer this question of EntryHash vs HeaderHash I took some notes. Looking at the source code definitions for Element, Entry, Header and their helpers and cross referencing with the docs was more helpful than either alone. I was hoping to be able to get to the bottom of this in a way that would he helpful for others in the future but it is starting to feel like you have to “understand everything” as a prerequisite to understanding everything. Still, I’ll share my notes in case they are useful.
For each type below, “Definition” is copy/pasted from the Glossary. “Code” is copy/pasted from the hdk doc’s links to the source code, then trimmed according to my whims.
If I hadn’t read https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html the struct definitions would not have been helpful to me.
Types Relevant to EntryHash/HeaderHash
Element
Definition
The data structure that holds an action in an agent’s source chain. Some elements are a combination of header and entry, such as new-entry actions while others contain all their data inside the header.
Sources
pub struct Element {
signed_header: SignedHeaderHashed,
entry: ElementEntry,
}
pub struct SignedHeaderHashed {
header: HeaderHashed,
signature: Signature,
}
pub struct SignedHeader(pub Header, pub Signature);
pub enum ElementEntry {
Present(Entry),
/// The Header has an entry_address reference, but we are in a public
/// context and the entry is private.
Hidden,
/// The Header does not contain an entry_address reference.
NotApplicable,
/// The Header has an entry but was stored without it.
/// This can happen when you receive gossip of just a header
/// when the header type is a [NewEntryHeader]
NotStored,
}
Header
Definition
A piece of data that represents an element on an agent‘s source chain. Headers link to the hash of their previous header, which creates a tamper-evident journal or ledger of all their actions in an application.
Code
pub enum Header {
Dna(Dna),
AgentValidationPkg(AgentValidationPkg),
InitZomesComplete(InitZomesComplete),
CreateLink(CreateLink),
DeleteLink(DeleteLink),
OpenChain(OpenChain),
CloseChain(CloseChain),
Create(Create),
Update(Update),
Delete(Delete),
}
Relevant Header Types
Create or “Create-entry action”
Definition
A new-entry action that, when published to the DHT, causes an entry to be available to other DHT members (unless the entry is private), in which case only a record of its creation is published).
Code
pub struct Create {
pub author: AgentPubKey,
pub timestamp: Timestamp,
pub header_seq: u32,
pub prev_header: HeaderHash,
pub entry_type: EntryType,
pub entry_hash: EntryHash,
}
pub enum EntryType {
AgentPubKey,
App(AppEntryType),
CapClaim,
CapGrant,
}
pub type EntryHash = HoloHash<hash_type::Entry>;
Entry
Definition
A basic unit of user data in a Holochain app. Each entry has its own defined entry type. When an agent commits an entry, it is combined with a header into an element that expresses a new-entry action. Then it is written to their source chain as a record of the action having taken place. An entry can be public or private; if it’s public, it’s also published to the DHT. There are app entries whose purpose and structure are defined by the DNA developer, and there are special system entries such as an agent ID entry.
Code
pub enum Entry {
Agent(AgentPubKey),
App(AppEntryBytes),
CapClaim(CapClaimEntry),
CapGrant(CapGrantEntry),
}
Functions Relevant to HeaderHash/EntryHash
hdk::entry::create_entry
create_entry takes your application defined data, inserts it into the log, then returns a HeaderHash. The HeaderHash points to your specific Create Element, whose EntryHash points to the hash of your application data.
hdk::entry::get
entry::get takes a HeaderHash or EntryHash and returns an Element.
entry::get<HeaderHash>() returns the Element for the Header.
entry::get<EntryHash>() returns the oldest live Header+Entry
Oldest live
I’m still working to understand this part.
“oldest live” only relates to disambiguating many creates and updates
from many authors pointing to a single entry, it is not the “current value”
of an entry in a CRUD sense.
If “foo” is created then updated to “bar”, a get on the Entry hash of
“foo” will return “foo” as part of an element with the “oldest live” header.
To discover “bar” the agent needs to call get_details and decide how
it wants to collapse many potential creates, updates and deletes
down into a single or filtered set of updates, to “walk the tree”.
hdk::entry::get_details
I have a notion based on other technologies that somewhere in your app there is going to be a state machine processing a series of elements to produce the current state of your application data, and that this call is related. I could also imagine that some applications would not have not need to do this. Is this notion accurate, should I keep digging for this answer or just move through the exercises until it becomes clear? Maybe it should be clear from “walking the tree”.
Update to my previous answer
An EntryHash is the hash of an Entry. A HeaderHash is the hash of Header. An Entry, among other things, is the actual serialized application data. Metadata in Holochain lingo has a definition that is different from what I meant, but I think I see why The-A-Man added the documentation for create_link.
Summary
“It’s down there somewhere, let me take another look.” - The Dude
