Advance usage features for general MerkleCRDT applications by hsanjuan · Pull Request #337 · ipfs/go-ds-crdt

hsanjuan · 2026-03-03T16:16:09Z

Feat: allow advanced usage for general MerkleCRDT applicaions

This commit enables advanced usecases by opening access to previously internal operations and options. A MerkleCRDT-based Set is still the base but:

We can now use custom Deltas (interface added): this allows storing any custom information in the CRDT tree.
We can now manually create and submit deltas (to complement the above)
We can interact directly with the internal Set.
Heads can be managed manually.
The CRDT now supports DAGNames, which allows to have separate DAGs (namespaces), in the same CRDT, each of them with their own head(s).
- Additionally, some key functions can now return errors.

This is all is possible via a new MerkleCRDT type and custom deltas. The Datastore type and general library usage remains the same as before.

heads.go

merklecrdt.go

crdt.go

hsanjuan

Some smallish things I will be fixing now.

guillaumemichel

A few comments

heads.go

guillaumemichel · 2026-03-04T11:43:02Z

heads.go

+	// sort.Slice(heads, func(i, j int) bool {
+	// 	ci := heads[i].Bytes()
+	// 	cj := heads[j].Bytes()
+	// 	return bytes.Compare(ci, cj) < 0
+	// })


Any reasons to remove the sorting? If yes, remove fully.

crdt.go

heads.go

crdt.go

This commit enables advanced usecases by opening access to previously internal operations and options. A MerkleCRDT-based Set is still the base but: * We can now use custom Deltas (interface added): this allows storing any custom information in the CRDT tree. * We can now manually create and submit deltas (to complement the above) * We can interact directly with the internal Set. This is possible via a new MerkleCRDT type, which wraps the Datastore type. The Datastore type and general library usage remains the same as before.

This introduces support for CRDT-DAG segmentation when using custom deltas. It works as follows: delta.GetDagName() returns a name for a dag segment. Each CRDT-head belongs to the DAG segment specified by its delta and any new head only references previous heads of the same DAG segment. The result is that we have separate dags, one per DagName, with all the nodes in them belonging to the same DagName. Deltas can still reference any keys etc. but this way we can create separate crdt-"histories" that run in parallel. Note that at any time, there will be at least as many heads as different DagNames, so having many DagNames will impact the size of broadcasts as they will include all the heads and new writes will not consolidate them into a single head.

MerkleCRDT.Publish() applies delta to DAG and returns the CID of the resulting root node. Additionally, IsProcessed(ctx, cid) is exported so that it is possible to check from the outside whether a cid has been traversed.

Set height to maxHeight + 1 of heads in that dag only.

This way the user also gets information about the height and DagName.

hsanjuan self-assigned this Mar 3, 2026