aergo-protobuf

This respository stores the AERGO Protocol Buffer definitions that are used by different server and client implementations.

Change rule

Protobuffer recognizes messages as ordered key-value pairs. You must not remove or reuse already occupied field numbers. For example, you must not change protobuf in a following way:

// from
message sometype {
  bytes hash = 1;
  string name = 2;
}

// to
message sometype {
  string hash = 1; // please DO NOT reuse it
  string name = 2;
}

Rather change like this:

message sometype {
  reserved 1;
  string name = 2;
  string hash = 3; // redefine field with a new field number
}

Follow these rules for backwards compatibility.

Add

Just add a new field (or message). Assing additional fields does not break backwards compatability, as protobuffer parser automatically ignores unknown fields. A client can check if unknown fields exists or not.

Example: somefile.proto

// from
message sometype {
  bytes hash = 1;
  string name = 2;
}

// to
message sometype {
  bytes hash = 1;
  string name = 2;
  bytes payload = 3; // just add it
}

Remove

Please do not just remove a field, as this breaks backwards compatability. You can keep removed fields as "reserved". Remember that you should not reorder the field numbers.

Example: somefile.proto

// from
message sometype {
  bytes hash = 1;
  string name = 2;
  bytes payload = 3;
}

// to
message sometype {
  reserved 1;  // left already occupied field number
  string name = 2;
  bytes payload = 3;
}

Update (Remove + Add)

Just a combination of remove and add.

Example: somefile.proto

// from
message sometype {
  bytes hash = 1;
  string name = 2;
}

// to
message sometype {
  reserved 1;  // left already occupied field number
  string name = 2;
  string hash = 3; // add a field with an new number
}

Dump Diff

> ./make_diff.sh v1.x.x. v1.x.x

See also

• Reserved fields in proto3
• Updating message type in proto3
• Protobuf message structure