Function hdk::entry::must_get_valid_element

source · [−]
pub fn must_get_valid_element(
    header_hash: HoloHash<Header>
) -> Result<Element, WasmError>
Expand description

MUST get a VALID Element at a given HeaderHash.

The Element is guaranteed to be valid. More accurately the Element is guarantee to be consistently reported as valid by the visible network.

The validity requirement makes this more complex but notably enables inductive validation of arbitrary graph structures. For example “If this Element is valid, and its parent is valid, up to the root, then the whole tree of Elements is valid”.

If at least one authority (1 of N trust) claims the Element is invalid then a conflict resolution/warranting round will be triggered.

In the case of a total eclipse (every visible authority is lying) then we cannot immediately detect an invalid Element. Unlike must_get_entry and must_get_header we cannot simply inspect the cryptographic integrity to know this.

In theory we can run validation of the returned Element ourselves, which itself may be based on must_get_X calls. If there is a large nested graph of must_get_valid_element calls this could be extremely heavy. Note though that each “hop” in recursive validation is routed to a completely different set of authorities. It does not take many hops to reach the point where an attacker needs to eclipse the entire network to lie about Element validity.

@TODO We keep signed receipts from authorities serving up “valid elements”.

  • If we ever discover an element we were told is valid is invalid we can retroactively look to warrant authorities
  • We can async (e.g. in a background task) be recursively validating Element dependencies ourselves, following hops until there is no room for lies
  • We can with small probability recursively validate to several hops inline to discourage potential eclipse attacks with a credible immediate threat

If you do not care about validity and simply want a pair of Header+Entry data, then use both must_get_header and must_get_entry together.

must_get_valid_element is available in contexts such as validation where both determinism and network access is desirable.

An Element will not be returned if:

  • @TODO It is WITHDRAWN by the author
  • @TODO The Entry is PURGED by the community
  • It is ABANDONED by ALL authorities due to failed validation
  • If ANY authority (1 of N trust) OR ourselves (0 of N trust) believes it INVALID
  • Nobody knows about it on the visible network

If an Element fails to be returned:

  • Callbacks will return early with UnresolvedDependencies
  • Zome calls will receive a WasmError from the host