IPFS Action Types

[baiirun]

Motivation

The Geo knowledge graph stores all offchain information related to the knowledge graph – and any systems built on top of the knowledge graph – on our decentralized storage (IPFS). Each of the data structures for offchain data has some common elements and some unique elements depending on what exactly the offchain data is representing, whether it's something like the knowledge graph data itself, requests to join spaces, or something else.

This document defines the set of IPFS action types and their data structures as part of the initial public version of the Geo knowledge graph.

Action types

For the sake of this document we'll use the term "Action Types" for the different types of data structures that go into IPFS. For v1.0.0 of the knowledge graph, Action Types fall into two primary categories: 1) Changes to the knowledge graph itself 2) Requesting/revoking permissions for a Space.

There are a few fields that are shared across all action types:

• type: This is required for our substream to index the different types as our smart contracts don't disambiguate between the type of content being processed onchain. Read more about our contracts here.
• id: a V4 UUID to uniquely identify the action type data.
• version: a string that uniquely identifies the version of the action type for future backwards compatibility.

Changes to the knowledge graph

Users can publish changes to the knowledge graph either by editing the Triples in the knowledge graph or by adding/removing Subspaces.

Editing triples

The EDIT action type has these fields in addition to the shared ones above:

• ops: Defines a set of Ops that describe the changes being made to individual triples in the knowledge graph. Read about Ops in the offchain data spec here.
• authors: Array of wallet account addresses (or Geo ids?) describing who contributed to these set of Edits. Currently in the data service we derive the author for an Edit from the transaction onchain, but there may be instances in the future where many users collaborate on a set of Edits, so we need a field to describe those.
• name: The name for the set of edits. You can think of these like a "commit message" in git. This name gets used as the name for proposals and for versioning in the data service.

type EditMetadata = {
  type: 'EDIT';
  id: string;
  version: '1.0.0';
  ops: Op[];
  authors: string[];
  name: string;
};

Adding/removing subspaces

The ADD_SUBSPACE and REMOVE_SUBSPACE action types has these fields in addition to the shared ones above:

• subspace: the contract address of the subspace to add or remove

export type SubspaceMetadata = {
  type: 'ADD_SUBSPACE' | 'REMOVE_SUBSPACE';
  id: string;
  version: '1.0.0';
  subspace: `0x${string}`;
};

Requesting/revoking permissions in a space

Users can be added and removed as either Editors or Members in a space. This action type have these action types in addition to the shared ones above:

• user: the address of the account to add or remove as an editor or member

type MembershipMetadata = {
  type: 'ADD_MEMBER' | 'REMOVE_MEMBER' | 'ADD_EDITOR' | 'REMOVE_EDITOR';
  id: string;
  version: '1.0.0';
  user: `0x${string}`;
};

Importing/migrating a space

One special behavior that's not frequently used in the system yet is the concept of "importing" or "migrating" the data from one space to another. This can happen if we decide to migrate to a new IPFS data model (not likely to happen after v1.0.0), if we switch chains, or if someone wants to fork a space.

The IMPORT action type has these fields in addition to the shared ones above:

• edits: array containing a list of ipfs hashes (ipfs://Qm...) each pointing to an EDIT action type

type ImportMetadata = {
  type: "IMPORT",
  previousSpaceContractAddress: string;
  previousSpaceNetwork: string;
  edits: string[] // points to an array of IPFS hashes containing EDIT action types
};

Binary encoding

The Geo knowledge graph expects that these action types are encoded into a binary format using Protocol Buffers before being posted onto IPFS. The data service decodes the Protobuf definition back into the expected data structure at index time. The goal of using Protobufs is to drastically reduce the size of the data posted onto decentralized storage.

The Geo SDKs should APIs for encoding the different IPFS action types before posting on IPFS.

[baiirun]

Are the authors supposed to be account addresses or Geo Person ids? Same question for membership action types.