chore: Correct locations of various TSS protos (#15780)

Signed-off-by: Matt Hess <[email protected]> Signed-off-by: Thomas Moran <[email protected]> Co-authored-by: Thomas Moran <[email protected]> Co-authored-by: Joseph S. <[email protected]>
hashgraph · Oct 9, 2024 · e31afe7 · e31afe7
1 parent 872ca1a
commit e31afe7
Show file tree

Hide file tree

Showing 9 changed files with 169 additions and 137 deletions.
diff --git a/...dera-protobufs/services/tss_message.proto → .../services/auxiliary/tss/tss_message.proto b/...dera-protobufs/services/tss_message.proto → .../services/auxiliary/tss/tss_message.proto
@@ -10,7 +10,7 @@
  */
 syntax = "proto3";
 
-package proto;
+package com.hedera.hapi.services.auxiliary.tss;
 
 /*
  * Copyright (C) 2024 Hedera Hashgraph, LLC
@@ -28,23 +28,29 @@ package proto;
  * limitations under the License.
  */
 
-option java_package = "com.hederahashgraph.api.proto.java";
-// <<<pbj.java_package = "com.hedera.hapi.node.tss">>> This comment is special code for setting PBJ Compiler java package
+option java_package = "com.hedera.hapi.services.auxiliary.tss.legacy";
+// <<<pbj.java_package = "com.hedera.hapi.services.auxiliary.tss">>> This comment is special code for setting PBJ Compiler java package
 
 option java_multiple_files = true;
 
-/** The TssMessageTransaction is used to send a TssMessage to the network for a
-  * candidate roster.
-  * <br/>
-  * This transaction contains the information to identify the source and target
-  * rosters, as well as the specific TssMessage being sent.
-  */
+/** A transaction body to to send a Threshold Signature Scheme (TSS)
+ * Message.<br/>
+ * This is a wrapper around several different TSS message types that a node
+ * might communicate with other nodes in the network.
+ *
+ * - A `TssMessageTransactionBody` MUST identify the hash of the roster
+ *   containing the node generating this TssMessage
+ * - A `TssMessageTransactionBody` MUST identify the hash of the roster that
+ *   the TSS messages is for
+ * - A `TssMessageTransactionBody` SHALL contain the specificc TssMessage data
+ *   that has been generated by the node for the share_index.
+ */
 message TssMessageTransactionBody {
 
   /**
-   * A hash of the roster containing the node generating the TssMessage.
-   * <br/>
-   * This hash uniquely identifies the source roster.
+   * A hash of the roster containing the node generating the TssMessage.</br>
+   * This hash uniquely identifies the source roster, which will include
+   * an entry for the node generating this TssMessage.
    * <p>
    * This value MUST be set.<br/>
    * This value MUST NOT be empty.<br/>
@@ -62,17 +68,21 @@ message TssMessageTransactionBody {
   bytes target_roster_hash = 2;
 
   /**
-   * An index to order shares.<br/>
-   * This establishes a global ordering of shares across all shares in
-   * the network.<br/>
-   * It corresponds to the index of the public share in the list returned from
-   * the TSS library when the share was created for the source roster.
+   * An index to order shares.
+   * <p>
+   * A share index SHALL establish a global ordering of shares across all
+   * shares in the network.<br/>
+   * A share index MUST correspond to the index of the public share in the list
+   * returned from the TSS library when the share was created for the source
+   * roster.
    */
   uint64 share_index = 3;
 
   /**
-   * A byte array containing the TssMessage data generated by the node for the
-   * share_index.
+   * A byte array.
+   * <p>
+   * This field SHALL contain the TssMessage data generated by the node
+   * for the specified `share_index`.
    */
   bytes tss_message = 4;
 }
diff --git a/hapi/hedera-protobufs/services/auxiliary/tss/tss_vote.proto b/hapi/hedera-protobufs/services/auxiliary/tss/tss_vote.proto
@@ -0,0 +1,98 @@
+/**
+ * # Tss Vote Transaction
+ *
+ * ### Keywords
+ * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ * "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ * document are to be interpreted as described in
+ * [RFC2119](https://www.ietf.org/rfc/rfc2119) and clarified in
+ * [RFC8174](https://www.ietf.org/rfc/rfc8174).
+ */
+syntax = "proto3";
+
+package com.hedera.hapi.services.auxiliary.tss;
+
+/*
+ * Copyright (C) 2024 Hedera Hashgraph, LLC
+ *
+ * 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.
+ */
+
+option java_package = "com.hedera.hapi.services.auxiliary.tss.legacy";
+// <<<pbj.java_package = "com.hedera.hapi.services.auxiliary.tss">>> This comment is special code for setting PBJ Compiler java package
+option java_multiple_files = true;
+
+/**
+ * A transaction body to vote on the validity of Threshold Signature Scheme
+ * (TSS) Messages for a candidate roster.
+ *
+ * - A `TssVoteTransactionBody` MUST identify the hash of the roster containing
+ *   the node generating this TssVote
+ * - A `TssVoteTransactionBody` MUST identify the hash of the roster that the
+ *   TSS messages is for
+ *  - If the candidate roster has received enough yes votes, the candidate
+ *    roster SHALL be adopted.
+ *  - Switching to the candidate roster MUST not happen until enough nodes have
+ *    voted that they have verified a threshold number of TSS messages from the
+ *    active roster.
+ *  - A vote consists of a bit vector of message statuses where each bit
+ *    corresponds to the order of TssMessages as they have come through
+ *    consensus.
+ *  - The threshold for votes to adopt a candidate roster SHALL be at least 1/3
+ *    of the consensus weight of the active roster to ensure that at least 1
+ *    honest node has validated the TSS key material.
+ */
+message TssVoteTransactionBody {
+
+  /**
+   * A hash of the roster containing the node generating this TssVote.
+   */
+  bytes source_roster_hash = 1;
+
+  /**
+   * A hash of the roster that this TssVote is for.
+   */
+  bytes target_roster_hash = 2;
+
+  /**
+   * An identifier (and public key) computed from the TssMessages for the target
+   * roster.
+   */
+  bytes ledger_id = 3;
+
+  /**
+   * A signature produced by the node.
+   * <p>
+   * This signature SHALL be produced using the node RSA signing key to sign
+   * the ledger_id.<br/>
+   * This signature SHALL be used to establish a chain of trust in the ledger id.
+   */
+  bytes node_signature = 4;
+
+  /**
+   * A bit vector of message statuses.
+   * <p>
+   * #### Example
+   * <ul><li>The least significant bit of byte[0] SHALL be the 0th item in the sequence.</li>
+   *     <li>The most significant bit of byte[0] SHALL be the 7th item in the sequence.</li>
+   *     <li>The least significant bit of byte[1] SHALL be the 8th item in the sequence.</li>
+   *     <li>The most significant bit of byte[1] SHALL be the 15th item in the sequence.</li>
+   * </ul>
+   * A bit SHALL be set if the `TssMessage` for the `TssMessageTransaction`
+   * with a sequence number matching that bit index has been
+   * received, and is valid.<br/>
+   * A bit SHALL NOT be set if the `TssMessage` has not been received or was
+   * received but not valid.
+   */
+  bytes tss_vote = 5;
+}
diff --git a/hapi/hedera-protobufs/services/state/roster/ledger_id.proto b/hapi/hedera-protobufs/services/state/roster/ledger_id.proto
@@ -39,19 +39,21 @@ option java_multiple_files = true;
 
 /**
  * A ledger identifier.<br/>
- * This message identifies a ledger and can be used to verify ledger signatures.
- * A LedgerId may change, but does so only in rare circumstances.
+ * This message identifies a ledger and is used to verify ledger
+ * signatures in a Threshold Signature Scheme (TSS).
  *
  * A ledger identifier SHALL be a public key defined according to the TSS
  * process.<br/>
- * A ledger identifier SHOULD NOT change, but MAY do so in rare circumstances.
- * Clients SHOULD always check for the correct ledger identifier, according to the
- * network roster, before attempting to verify any state proof or other ledger
- * signature.
+ * A ledger identifier SHOULD NOT change, but MAY do so in rare
+ * circumstances.<br/>
+ * Clients SHOULD always check for the correct ledger identifier, according to
+ * the network roster, before attempting to verify any state proof or other
+ * ledger signature.
  *
  * ### Block Stream Effects
- * Every Block Stream `BlockProof` item SHALL be signed via TSS and MUST be
- * verified with the ledger identifier current at the _start_ of that block.
+ * Every block in the Block Stream `BlockProof` SHALL be signed via TSS and
+ * MUST be verified with the ledger identifier current at the _start_ of that
+ * block.
  * If the ledger identifier changes, the new value MUST be used to validate
  * Block Proof items after the change.
  * A change to the ledger identifier SHALL be reported in a State Change for
@@ -62,7 +64,8 @@ message LedgerId {
 
   /**
    * A public key.<br/>
-   * This key both identifies the ledger and can be used to verify ledger signatures.
+   * This key both identifies the ledger and can be used to verify ledger
+   * signatures.
    * <p>
    * This value MUST be set.<br/>
    * This value MUST NOT be empty.<br/>
@@ -72,25 +75,25 @@ message LedgerId {
 
   /**
    * A round number.<br/>
-   * This identifies when this ledger id becomes active.
-   * <p>
+   * This identifies when this ledger id becomes active.<br/>
    * This value is REQUIRED.
    */
   uint64 round = 2;
 
   /**
    * A signature from the prior ledger key.<br/>
-   * This signature is the _previous_ ledger ID signing _this_ ledger ID.
-   * <p>
-   * This value MAY be unset, if there is no prior ledger ID. </br>
+   * This signature is the _previous_ ledger ID signing _this_ ledger ID.<br/>
+   * This value MAY be unset, if there is no prior ledger ID.</br>
    * This value SHOULD be set if a prior ledger ID exists
    * to generate the signature.
    */
   bytes ledger_signature = 3;
 
   /**
-   * The signatures from nodes in the active roster signing the new ledger id.<br/>
-   * These signatures establish a chain of trust from the network to the new ledger id.
+   * The signatures from nodes in the active roster signing the new
+   * ledger id.<br/>
+   * These signatures establish a chain of trust from the network to the new
+   * ledger id.
    * <p>
    * This value MUST be present when the ledger signature of a previous ledger
    * id is absent.
@@ -121,11 +124,17 @@ message RosterSignatures {
 message NodeSignature {
   /**
    * The node id of the node that created the _RSA_ signature.
+   * This value MUST be set.<br/>
+   * This value MUST NOT be empty.<br/>
+   * This value is REQUIRED.
    */
   uint64 node_id = 1;
 
   /**
    * The bytes of an _RSA_ signature.
+   * This value MUST be set.<br/>
+   * This value MUST NOT be empty.<br/>
+   * This value MUST contain a valid signature.
    */
   bytes node_signature = 2;
 }
diff --git a/hapi/hedera-protobufs/services/state/tss/tss_message_map_key.proto b/hapi/hedera-protobufs/services/state/tss/tss_message_map_key.proto
@@ -13,8 +13,6 @@ syntax = "proto3";
 package com.hedera.hapi.node.state.tss;
 
 /*
- * Hedera Network Services Protobuf
- *
  * Copyright (C) 2024 Hedera Hashgraph, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -30,14 +28,15 @@ package com.hedera.hapi.node.state.tss;
  * limitations under the License.
  */
 
-option java_package = "com.hederahashgraph.api.proto.java";
+option java_package = "com.hedera.hapi.node.state.tss.legacy";
 // <<<pbj.java_package = "com.hedera.hapi.node.state.tss">>> This comment is special code for setting PBJ Compiler java package
 option java_multiple_files = true;
 
 /**
-  * A key for use in the TssMessageMaps.<br/>
-  * This key is used to uniquely identify entries in the TssMessageMaps.
-  */
+ * A key for use in the Threshold Signature Scheme (TSS) TssMessageMaps.
+ *
+ * This key SHALL be used to uniquely identify entries in the Message Maps.
+ */
 message TssMessageMapKey {
 
   /**

diff --git a/hapi/hedera-protobufs/services/state/tss/tss_vote_map_key.proto b/hapi/hedera-protobufs/services/state/tss/tss_vote_map_key.proto
@@ -13,8 +13,6 @@ syntax = "proto3";
 package com.hedera.hapi.node.state.tss;
 
 /*
- * Hedera Network Services Protobuf
- *
  * Copyright (C) 2024 Hedera Hashgraph, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -30,13 +28,14 @@ package com.hedera.hapi.node.state.tss;
  * limitations under the License.
  */
 
-option java_package = "com.hederahashgraph.api.proto.java";
+option java_package = "com.hedera.hapi.node.state.tss.legacy";
 // <<<pbj.java_package = "com.hedera.hapi.node.state.tss">>> This comment is special code for setting PBJ Compiler java package
 option java_multiple_files = true;
 
  /**
-  * A key for use in the TssVoteMaps.<br/>
-  * This key is used to uniquely identify entries in the TssVoteMaps.
+  * A key for use in the Threshold Signature Scheme (TSS) TssVoteMaps.
+  *
+  * This key SHALL be used to uniquely identify entries in the Vote Maps.
   */
 message TssVoteMapKey {
 
@@ -49,8 +48,7 @@ message TssVoteMapKey {
    */
   bytes roster_hash = 1;
 
-  /* The node id of the node that created the TssVote.
-  * <br/>
+  /** The node id of the node that created the TssVote.</br>
   * This id uniquely identifies the node.
   * <p>
   * This value MUST be set.<br/>

diff --git a/hapi/hedera-protobufs/services/transaction_body.proto b/hapi/hedera-protobufs/services/transaction_body.proto
@@ -89,8 +89,8 @@ import "node_create.proto";
 import "node_update.proto";
 import "node_delete.proto";
 
-import "tss_message.proto";
-import "tss_vote.proto";
+import "auxiliary/tss/tss_message.proto";
+import "auxiliary/tss/tss_vote.proto";
 
 /**
  * A single transaction. All transaction types are possible here.
@@ -425,11 +425,11 @@ message TransactionBody {
         /**
          * A transaction body for a `tssMessage` request.
          */
-        TssMessageTransactionBody tssMessage = 61;
+        com.hedera.hapi.services.auxiliary.tss.TssMessageTransactionBody tssMessage = 61;
 
         /**
          * A transaction body for a `tssVote` request.
          */
-        TssVoteTransactionBody tssVote = 62;
+        com.hedera.hapi.services.auxiliary.tss.TssVoteTransactionBody tssVote = 62;
     }
 }