From c67db94c21edd919c7e6909bf5d94d2d83cc8ca0 Mon Sep 17 00:00:00 2001
From: Stephen Robinson <robinsonsc@google.com>
Date: Mon, 24 Jun 2024 17:47:25 +0000
Subject: [PATCH] Create ExchangeCheckpoint protobuf message for Kingdom-less
 panel exchange.

---
 .../panelmatch/client/internal/BUILD.bazel    | 16 ++++
 .../client/internal/exchange_checkpoint.proto | 92 +++++++++++++++++++
 2 files changed, 108 insertions(+)
 create mode 100644 src/main/proto/wfa/panelmatch/client/internal/exchange_checkpoint.proto

diff --git a/src/main/proto/wfa/panelmatch/client/internal/BUILD.bazel b/src/main/proto/wfa/panelmatch/client/internal/BUILD.bazel
index 1d5a00de7b3..638b3b006d8 100644
--- a/src/main/proto/wfa/panelmatch/client/internal/BUILD.bazel
+++ b/src/main/proto/wfa/panelmatch/client/internal/BUILD.bazel
@@ -3,6 +3,22 @@ load("@wfa_rules_kotlin_jvm//kotlin:defs.bzl", "kt_jvm_proto_library")
 
 package(default_visibility = ["//visibility:public"])
 
+proto_library(
+    name = "exchange_checkpoint_proto",
+    srcs = ["exchange_checkpoint.proto"],
+    deps = [
+        ":exchange_step_attempt_proto",
+        ":exchange_workflow_proto",
+        "@com_google_googleapis//google/type:date_proto",
+        "@com_google_protobuf//:timestamp_proto",
+    ],
+)
+
+kt_jvm_proto_library(
+    name = "exchange_checkpoint_kt_jvm_proto",
+    deps = [":exchange_checkpoint_proto"],
+)
+
 proto_library(
     name = "exchange_step_attempt_proto",
     srcs = ["exchange_step_attempt.proto"],
diff --git a/src/main/proto/wfa/panelmatch/client/internal/exchange_checkpoint.proto b/src/main/proto/wfa/panelmatch/client/internal/exchange_checkpoint.proto
new file mode 100644
index 00000000000..2edbdebf02b
--- /dev/null
+++ b/src/main/proto/wfa/panelmatch/client/internal/exchange_checkpoint.proto
@@ -0,0 +1,92 @@
+// Copyright 2024 The Cross-Media Measurement Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package wfa.panelmatch.client.internal;
+
+import "google/protobuf/timestamp.proto";
+import "google/type/date.proto";
+import "wfa/panelmatch/client/internal/exchange_step_attempt.proto";
+import "wfa/panelmatch/client/internal/exchange_workflow.proto";
+
+option java_package = "org.wfanet.panelmatch.client.internal";
+option java_multiple_files = true;
+
+// Tracks the progress of an exchange for a single party. For a Kingdom-less
+// exchange, both parties keep a single checkpoint for each exchange date.
+// Together, the two checkpoints for a given exchange date can be used to
+// determine the current state of the exchange.
+message ExchangeCheckpoint {
+  // The party that owns this checkpoint.
+  ExchangeWorkflow.Party party = 1;
+
+  // ID of the recurring exchange for this checkpoint.
+  string recurring_exchange_id = 2;
+
+  // Date of the exchange.
+  google.type.Date exchange_date = 3;
+
+  // Cryptographically secure fingerprint of the workflow being executed. The
+  // fingerprint is of the pre-shared serialized workflow which both parties
+  // have a copy of. This can be compared against the fingerprint in the other
+  // party's checkpoint to verify that both parties are running the same
+  // workflow.
+  bytes workflow_fingerprint = 4;
+
+  // Progress info about a single exchange step attempt.
+  message ProgressEntry {
+    // Details about an attempt of an exchange step.
+    ExchangeStepAttempt attempt = 1;
+
+    // Time when the attempt began.
+    google.protobuf.Timestamp start_time = 2;
+
+    // Time when the attempt reached a terminal state. Unset if the attempt is
+    // still in progress.
+    google.protobuf.Timestamp end_time = 3;
+  }
+
+  // Progress entries for all exchange step attempts by the party that owns
+  // this checkpoint. When a new attempt is claimed, it as appended to the end
+  // of this list. Entries are modified by the owning party when the attempt
+  // reaches a terminal state.
+  repeated ProgressEntry progress_entries = 5;
+
+  // State of the exchange from the perspective of the party that owns this
+  // checkpoint.
+  enum ExchangeState {
+    EXCHANGE_STATE_UNSPECIFIED = 0;
+
+    // The exchange is still in-progress. Indicates that this party is
+    // currently executing an exchange step, or has further steps remaining to
+    // execute (which may be currently blocked).
+    IN_PROGRESS = 1;
+
+    // All steps belonging to this party have completed successfully. If both
+    // parties reach this state, then the entire exchange is considered to have
+    // completed successfully.
+    //
+    // Terminal state.
+    SUCCEEDED = 2;
+
+    // One or more steps belonging to this party have failed permanently. If
+    // either party reaches this state, then the entire exchange is considered
+    // to have failed.
+    //
+    // Terminal state.
+    FAILED = 3;
+  }
+  ExchangeState exchange_state = 6;
+}