holochain_chc

License: Apache-2.0

lib.rs:

Defines the Chain Head Coordination API and an HTTP client for talking to a remote CHC server.

A Chain Head Coordinator (CHC) is an external service which Holochain can communicate with. A CHC is used in situations where it is desirable to run the same Holochain Cell (source chain) on multiple different conductors. The CHC ensures that these multiple devices don't inadvertently create a fork of the source chain by doing simultaneous uncoordinated writes.

This crate introduces a ChainHeadCoordinator trait which defines the interface that Holochain weaves into its logic to make use of a CHC service. Currently, the only Holochain-supported implementation of this trait is ChcHttp, which makes HTTP requests to a remote server and returns the responses. There is also a ChcLocal reference implementation which is used for testing. Other implementations can be written as needed, including alternate implementations of a HTTP client, or also other kinds of clients using other protocols.

Holochain specifies an optional chc_url field in its configuration which can point to an HTTP server that implements the CHC interface. See the chc_http module docs for specs on how to set up a remote CHC HTTP server that Holochain can talk to using the provided chc_http::ChcHttp implementation.

The CHC trait contains two methods, and Holochain actually only uses one of them: Every time Holochain is about to commit some records to a source chain, it first calls add_records_request to request that the CHC store those new records. The CHC must be written so that it recognizes that the new records being added are a valid extension of the existing chain of stored records, i.e. that the first record being pushed has a Action::prev_action field which matches the hash of the last record already stored, and additionally that the new records also form a valid hash chain (via prev_action). If the new records are valid, they are added to CHC's chain, and an Ok result is returned.

If these criteria for valid new records are not met, the CHC must return ChcError::InvalidChain, which lets the client know that the local chain is out of sync with CHC's version, due to some other conductor having updated its own chain. In this case, the user (the driver of the conductor) should call the other CHC method, get_record_data_request, which will return the diff of records that CHC has that the local conductor does not. Then, the Holochain admin method GraftRecords can be called to "stitch" these records onto the existing chain, removing any fork if necessary.

Note that currently, get_record_data_request is never called directly by Holochain, but it might be in the future.

Note also that when a CHC is used, the CHC is always considered the authoritative source of truth. If a local conductor's state for whatever reason contradicts the CHC in any way, whether the local chain contains different data altogether or is strictly ahead of the CHC, the CHC's version is always considered correct and the local chain should always be modified to match the CHC's state.