entrycredit-block and admin-block API parameter incorrectly named? about factomd HOT 6 CLOSED

The naming problem actually also spread to the result of directory-block API where the Admin Block hash and Entry Credit Block header hash are presented in a field named keymr. Now the problem is you made the decision to include special blocks Admin, Entry Credit and Factoid with regular blocks which pushed you to have a uniform keymr even though it doesn't sound semantically correct... So maybe those special blocks should not be flatten with other regular Entry Blocks (especially as the processing of those special blocks is fairly different from Entry blocks)

from factomd.

Hi Paul:

Indeed this a quirk of how the system is designed.

The 3 special chains (admin, EC, FCT) are granted their own unique ChainIDs. These chainds are almost all zeros, so there won't be a collision with a real hash. These fake (non-hash derived) ChainIDs are basically are handles to those blocks inside the directory block. The fake ChainID is paired with the handle to the specific block for that DB height.

https://github.com/FactomProject/FactomDocs/blob/master/factomDataStructureDetails.md#directory-block

Since the handles for those special blocks are treated similarly to the handles to the regular entry blocks, they fall into the same control flow for the directory blocks as the regular entry blocks.

The keyMR style is great for proving existence a specific element in any of the lower blocks. It allows a clean merkle proof all the way from the anchored hash to the entry hash or factoid tx. It bypasses the headers, while also leaving the header hash in the merkle tree. If we had gone with your suggestion of putting all these special blocks into the header, then we wouldn't be able to have the clean merkle proofs all the way to the factoid transactions. As for the other 2 types, it made sense to keep them as separate blocks, and have the same control flows as the separate blocks, hence being grouped with the other separate blocks.

The EC blocks were going to be the largest in the system. Making a merkle tree of those would have caused a lot of overhead, and there wasn't a clear reason why someone would want to efficiently prove
that a specific entry was paid for. Therefore, we just took the serial hash of that block to be handle, instead of a merkle root.

As far as the API went, having different field names in the same array seemed kind of messy. Normal people won't be accessing these blocks anyways, so adding complications with edge cases where people needed to deal with things that they shouldn't have to even look at seemed like a bad choice.

With that design decision, the calls to get those blocks should match the thing that was returned in the DBlock, even though it isn't actually a keymr, as you observed.

Does that make sense?

from factomd.

Here is a diagram of how the Merkle proof can be followed all the way down from the DB KeyMR to the entry hash.
https://imgur.com/y5e3WMu

from factomd.

Hi Brian, thanks for taking the time for a thorough answer.

I understand the block structures and you design decision for it, I was just thinking that maybe the API layer could have abstracted those quirks to make it a bit more "user-friendly" (because in practice I'd not process an AdminBlock the same way I'd process an EntryBlock). So it seems you envisioned the API rather "low level" (i.e. very close to the protocol structures). I was asking that because I'm actually developing a JS library on top of the API and I was planning to hide those quirks. I think I'll go ahead and thanks to your answer I have a better understanding of the reasoning behind the API choices.

from factomd.

@PaulBernier do you still have feedback for this going forward ? (since re-write is on the horizion)

from factomd.

That probably fits in a API v3 that would clean up all the quirks of the V2. I am not sure it is worth keeping this issue open any longer tbh.

from factomd.