Skip to content

Commit

Permalink
adds the forestrie confirm message
Browse files Browse the repository at this point in the history 
* Adds MerkleLogConfirm &Adds MerkleLogConfirmMessage
* Adds MerkleLogUnequivocal & MerkleLogUnequivocalMessage (currently
  empty, just claims the pb ordinals we know we will need)
* Removes MerkleLogCommitMongoDB
* Removes log version, log epoch and massif index. All of which
  are harmful to our strategy for managing the backing storage.
  See [changing the massifheight](https://github.com/datatrails/epic-8120-scalable-proof-mechanisms/blob/e38ca5e050356a47028b1d2b47bb6f02ff6c5c3c/mmr/forestrie-mmrblobs.md#changing-the-massifheight-for-a-log)
  for important context
* Adds EventResponseJSONAPI, which largely duplicates EventResponse but
  importantly, supports decoding the format the *customer* will see from
  our apis. The duplication is unfortunate, but it means we can stop
  having ad-hoc soultions to this problem in all our go-lang based demo
  code. It also means the data can be reliably decoded with protojson.
  the generic json unmarshal fails to deal with 64 bit unsigned integers
  (and other numbers) correctly for example.
  • Loading branch information
Robin Bryce committed Feb 27, 2024
1 parent 73f875c commit d93b8f8
Show file tree
Hide file tree
Showing 2 changed files with 220 additions and 50 deletions.
191 changes: 182 additions & 9 deletions datatrails-common-api/assets/v2/assets/eventresponse.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -168,19 +168,192 @@ message EventResponse {
max_length: 1024
}];

// An event has exactly one proof mechanism. This field caputures the proof
// mechanism specific details supporting the trustworthyness of the event
// record. We anticipate at least two proof mechs: merkle_log and
// verkle_log. We use oneof to avoid repeating the scattering of randomly
// re-purposed fields we currently have for simple hash vs khipu.

// An event has exactly one proof mechanism. On any event only the entry
// corresponding to the chosen proof mechanism will be present. (Note that
// onfof exposes us to to many tooling compatibility issues)

// proof details for proof_mechanism MERKLE_LOG
MerkleLogEntry merklelog_entry = 19 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description:
"verifiable merkle mmr log entry details",
oneof proof_details {
MerkleLogEntry merklelog_entry = 19 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description:
"verifiable merkle mmr log entry details",
// see https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-openapiv2/options/openapiv2.proto
// for specific types.
type: OBJECT
}];
}
}

// EventResponseJSONAPI represents how the consumer of the events api sees the event data.
message EventResponseJSONAPI {
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
json_schema: {
description: "This describes an Event."
}
example:"{ "
"\"identity\": \"assets/add30235-1424-4fda-840a-d5ef82c4c96f/events/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000\", "
"\"asset_identity\": \"assets/add30235-1424-4fda-840a-d5ef82c4c96f\", "
"\"operation\": \"Record\", "
"\"behaviour\": \"RecordEvidence\", "
"\"event_attributes\": { "
" \"arc_attachments\": ["
" {"
" \"arc_attachment_identity\": \"blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d\","
" \"arc_hash_value\": \"01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b\","
" \"arc_display_name\": \"Picture from yesterday\","
" \"arc_hash_alg\": \"sha256\""
" }"
" ]"
"}, "
"\"asset_attributes\": { "
" \"arc_firmware_version\": \"3.2.1\", "
" \"arc_home_location_identity\": \"locations/42054f10-9952-4c10-a082-9fd0d10295ae\""
"}, "
"\"timestamp_accepted\": \"2019-11-27T14:44:19Z\", "
"\"timestamp_declared\": \"2019-11-27T14:44:19Z\", "
"\"timestamp_committed\": \"2019-11-27T14:44:19Z\", "
"\"principal_declared\": { "
" \"issuer\": \"job.idp.server/1234\", \"subject\":\"bob@job\" "
" }, "
" \"principal_accepted\": { "
" \"issuer\": \"job.idp.server/1234\", \"subject\":\"bob@job\" "
"}, "
"\"confirmation_status\": \"CONFIRMED\", "
"\"block_number\": 12, "
"\"transaction_index\": 5, "
"\"transaction_id\": \"0x07569\", "
"\"tenant_identity\": \"tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9\" "
"}"
};

// Relative Resource Name for the operation event
string identity = 1 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "identity of a event resource"
read_only: true
}];

// relative resource name for associated asset ( asset the operation is performed on - has to have specific behaviour enabled)
string asset_identity = 2 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "identity of a related asset resource `assets/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000`"
read_only: true
}];

// map of event attributes. Specific behaviours define required and optional event attributes for each supported operation.
map<string, string> event_attributes = 16 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "key value mapping of event attributes"
}
];

// map of asset attributes. Specific behaviours define required and optional asset attributes. These attributes cause the corresponding attributes on the asset to be updated.
map<string, string> asset_attributes = 17 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "key value mapping of asset attributes"
}
];

// name of operation on this behviour
string operation = 4 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "The operation represented by the event. `Record`"
read_only: true
max_length: 4096
}];

// name of this behaviour
string behaviour = 14 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "The behaviour used to create event. `RecordEvidence`"
read_only: true
max_length: 4096
}];

// timestamp when operation was actually performed - if not provided will be set to timestamp_accepted
string timestamp_declared = 5 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "RFC 3339 time of event as declared by the user"
read_only: true
}];

// timestamp when system received operation request
string timestamp_accepted = 6 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "RFC 3339 time of event as recorded by the server"
read_only: true
}];

// timestamp for when the event was committed to a verifiable log
string timestamp_committed = 7 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "RFC 3339 time of event as recorded in verifiable storage"
read_only: true
}];

// principal information associated with event - if not provided will be set to principal_accepted
Principal principal_declared = 8 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "principal provided by the user"
read_only: true
// see https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-openapiv2/options/openapiv2.proto
// for specific types.
type: OBJECT
}];

// principal logged into the system that performed the operation
Principal principal_accepted = 9 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "principal recorded by the server"
read_only: true
// see https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-openapiv2/options/openapiv2.proto
// for specific types.
type: OBJECT
}];

// indicated if operation has been committed to the blockchain
string confirmation_status = 10 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "indicates if the event has been succesfully committed to the blockchain"
read_only: true
// see https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-openapiv2/options/openapiv2.proto
// for specific types.
type: STRING
}];

// NOTICE: We expect to retire simple hash and then remove all the top level dlt fields.

// hash of transaction committing this operation on blockchain
string transaction_id = 11 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "hash of the transaction as a hex string `0x11bf5b37e0b842e08dcfdc8c4aefc000`"
max_length: 4096
}];

// block number of committing transaction
uint64 block_number = 12 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "number of block event was commited on"
read_only: true
}];

// transaction index of committing transaction
uint64 transaction_index = 13 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "index of event within commited block"
read_only: true
}];

// wallet address for the creator of this event
string from = 15 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description: "wallet address for the creator of this event"
read_only: true
}];

string tenant_identity = 18 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description:
"Identity of the tenant the that created this event"
max_length: 1024
}];

// An event has exactly one proof mechanism. This field caputures the proof
// mechanism specific details supporting the trustworthyness of the event
// record. We anticipate at least two proof mechs: merkle_log and
// verkle_log. We use oneof to avoid repeating the scattering of randomly
// re-purposed fields we currently have for simple hash vs khipu.
oneof proof_details {
// proof details for proof_mechanism MERKLE_LOG
MerkleLogEntry merklelog_entry = 19 [ (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
description:
"verifiable merkle mmr log entry details"
max_length: 1024
}];
};
}
79 changes: 38 additions & 41 deletions datatrails-common-api/assets/v2/assets/merklelogentry.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,69 +7,66 @@ import "google/protobuf/timestamp.proto";

// MerkeLogCommit provides the log entry details for a single mmr leaf.
message MerkleLogCommit {

/* The mmr index */
uint64 index = 1;
/* The mmr *leaf* index */
uint64 leaf_index = 2; // TBD: this may be redundant.
/* time ordered and strictly unique per tenant. system wide
* unique with very reasonable operational assumptions. */
fixed64 idtimestamp = 3;

/* time ordered and strictly unique per tenant. system wide unique with very
* reasonable operational assumptions. prefixed with time epoch if len > 8
* bytes (after conversion back from hex). */
string idtimestamp = 2;
}

message MerkleLogCommitMongoDB {
message MerkleLogConfirm {

// Note that should we ever have more than 2^63 events in a tenant log, the
// index and leaf_index fields will not persist to mongo.
// The following correspond to mmrblobs.MMRState
uint64 mmr_size = 1;

/* The mmr index */
uint64 index = 1;
/* The mmr *leaf* index */
uint64 leaf_index = 2; // TBD: this may be redundant.

/* time ordered and strictly unique per tenant. system wide
* unique with very reasonable operational assumptions.
*
* EXPRESSED AS A 16 character padded hex string because mongo db does not
* support unsigned integers and we need all 64 bits to get a sensible epoch
* duration.
*/
string idtimestamp = 3;
bytes root = 2;
// The regular unix time the root was signed
int64 timestamp = 3;
// The idtimestamp of the last leaf under mmr_size. prefixed with time epoch if len > 8 bytes (after conversion back from hex)
string idtimestamp = 4;
// The signed state at mmr_size
bytes signed = 5;
}

message MerkleLogUnequivocal { }

// The message sent from forestrie to avid notifying that the corresponding
// event is commited to the tenants log.
message MerkleLogCommitMessage {

// The tenant identity and the event identity for the committed event.
string tenant_identity = 1;
string event_identity = 2;
/* The time portion of idtimestamp that contributed to the hash of the event
* (the idtimestamp is _also_ included.
* This must be copied into event.timestamp_committed when the saas db is updated */
google.protobuf.Timestamp timestamp = 6;

uint32 log_version = 3;
uint32 log_epoch = 4;
MerkleLogCommit commit = 5;
// The time portion of idtimestamp that contributed to the hash of the event
google.protobuf.Timestamp timestamp = 3;

MerkleLogCommit commit = 4;
}

message MerkleLogConfirmMessage {

string tenant_identity = 1;

MerkleLogConfirm confirm = 2;
}

message MerkleLogUnequivocalMessage {
string tenant_identity = 1;
MerkleLogUnequivocal unequivocal = 2;
}

// The details stored in the SaaS db for a proof mech MERKLE_LOG commitment
message MerkleLogEntry {

// The tenant log version and epoch when the log entry was created.
uint32 log_version = 1;
uint32 log_epoch = 2;

// Event trust level commited fields. Note that we have to use a special
// message because mongo db does not support unsigned integers. If/when we
// move away from that, we can move this ordinal safely into a oneof
MerkleLogCommitMongoDB commit = 3;

// TODO: Event trust level confirmed fields
// Event trust level COMMITTED details
MerkleLogCommit commit = 1;

// signature over tenant mmr root
// Event trust level CONFIRMED details
MerkleLogConfirm confirm = 2;

// TODO: Event trust level uniquivocal fields
// Event trust level UNEQUIVOCAL details
MerkleLogUnequivocal unequivocal = 3;
}

0 comments on commit d93b8f8

Please sign in to comment.