Operations

🙈Deprecated

This section will soon be replaced with our new namakemono data type which is similar, but cooler.

Operations represent atomic data changes.
Operations are published as the payload of Bamboo entries.
Operations are identified by the hash of their Bamboo entry.
Every operation is associated with a Bamboo author, which is encoded in the operation's entry

🐼Definition: Operation ID

The operation id uniquely identifies an operation. It is equal to the hash of the Bamboo entry that has the operation as its payload.

struct Operation {
  /// Version of this operation.
  version: NonZeroU64,

  /// Describes if this operation creates, updates or deletes data.
  action: OperationAction,

  /// The id of the schema for this operation.
  schema_id: String,

  /// Optional document view id containing the operation ids directly preceding this one in the
  /// document.
  previous_operations?: String{68}[],

  /// Optional fields map holding the operation data.
  fields?: HashMap<String, OperationValue>,
}

Encoding Format

CBOR is a binary encoding that is used to encode the contents of an operation and produce bytes that can be associated with a Bamboo entry, stored, and sent over a network connection.
Operations are encoded as arrays of items, described in more detail below.

🌩️Requirement OP1

An operation MUST be encoded using hexadecimal encoded CBOR with the following format:

[version, action, schema_id, [previous]?, { [field_key]: <field_value> }?]

Operations MUST NOT contain any additional items.

Items

Version

The operation version is the version of the p2panda specification that is followed by that operation.

🌩️Requirement OP2

Every operation MUST have an operation version. An operation version MUST be a positive u64 integer.

Action

The operation action defines the kind of data change that is described by the operation.

enum OperationAction {
  CREATE = 0,
  UPDATE = 1,
  DELETE = 2,
}

🐼Definition: Operation Actions

There are 3 types of operation:

CREATE operations initialise new documents and set all of their field values.
UPDATE operations mutate any number of fields on an existing document.
DELETE operations delete an existing document.

🌩️Requirement OP3

Every operation MUST have an operation action, which MUST be one of

0 - denotes a CREATE action and results in a CREATE operation
1 - denotes an UPDATE action and results in a UPDATE operation
2 - denotes a DELETE action and results in a DELETE operation

Schema Id

The schema of an operation may define additional requirements for the operation's action, previous and fields items.
- See the schema section for more details.

🌩️Requirement OP4

Every operation MUST have a schema id

previous specifies where an operation should be placed when constructing the graph of operations required to materialise a document.
- It contains an array of operation_id's which identify the tip operation of any unmerged branches in this document at the time of publishing this operation.
- In the case where a graph has no unmerged branches, this array will contain only one id (the resolved graph tip).
- Publishing an operation which identifies more than one graph tip effectively merges these branches into one.

🌩️Requirement OP5

DELETE and UPDATE operations MUST have previous with length > 0. CREATE operations MUST NOT have previous.

Fields

Operation fields contain the actual data carried by an operation.
Depending on the operation's action and schema, different requirements exist for which data must be contained in the operation.
Fields map field names to field values
- field names are strings
- field values can be of type: u64, f64, boolean, bytes, string, relation, relation_list, pinned_relation, pinned_relation_list
- see schema for further specification of field names and values
The schema defined by the schema id item of the operation specifies the name and type of each field which can be included in an operation.
In order to deserialise typed field values, a copy of the schema is required.

enum OperationValue {
  Boolean(bool),
  Integer(i64),
  Float(f64),
  String(String),
  Bytes(Vec<u8>),
  Relation(String{68}),
  RelationList(String{68}[]),
  PinnedRelation(String{68}[]),
  PinnedRelationList(String{68}[][]),
}

🌩️Requirement OP6

A CREATE operation MUST contain all fields defined by the operation's operation schema. An UPDATE operation MAY contain any combination of fields from the operation's operation schema. A DELETE operation MUST NOT contain any fields.

🌩️Requirement OP7

The encoding reflects the core data types of CBOR while they MUST be interpreted as p2panda operation values when decoding with the help of a schema:

string can be interpreted as any string or a document id for a relation depending on the schema
string[] can be interpreted as a pinned relation (document view id) or a relation list (list of document ids) depending on the schema
string[][] is a pinned relation list

🌩️Requirement OP8

The type of all operation field values MUST match the corresponding field in the operation's schema.

Usage

Clients can use operations to publish data changes.
Clients must embed operations in Bamboo entries to publish them.
Clients can create a document by publishing a CREATE operation.
Clients can update a document by publishing an UPDATE operation.
- Every UPDATE operation leads to a new document view of the document that is being updated.
Clients can delete a document by publishing a DELETE operation.
Nodes can reduce operations to produce a specific document view of their document.
Clients can delete a document by publishing a DELETE operation.

🌩️Requirement OP9

Nodes MUST delete all operations of a document once it has been deleted.

Encoding Format​

Items​

Version​

Action​

Schema Id​

Previous​

Fields​

Usage​