Merge pull request #208 from exploreriii/proto-prompt

feat: proto prompt

Author: exploreriii

.coderabbit.yaml

@@ -18,7 +18,6 @@ reviews:
   in_progress_fortune: false # Do not stall time with a message (spammy)
   poem: false # Do not write a literal poem (spammy)
   enable_prompt_for_ai_agents: false # Disable prompts for AI agents (spammy)
-
   # TOKEN REVIEW INSTRUCTIONS
   token_review_instructions: &token_review_instructions |
     You are acting as a senior maintainer reviewing token-related code
@@ -291,6 +290,34 @@ reviews:
       - Do NOT block the PR on them.
       - Do NOT suggest fixes inline.
       - Instead, aggregate all out-of-scope issues into a single comment with a list of recommendations for one or more follow-up issues that can be created.
+
+    PROTOCOL SOURCE OF TRUTH
+    The protobuf files under `/proto` are the source of truth for
+    what the Hedera network accepts. 
+
+    These definitions should be checked when reviewing any code that constructs or processes network requests or responses, to ensure:
+     - Field names match exactly
+     - Required vs optional fields are respected
+     - Defaults align with protobuf expectations
+     - No silent divergence in semantics exists
+
+    They define wire format, semantic meaning, and contractual
+    requirements — not SDK architecture.
+
+    When reviewing changes, ensure:
+
+    - Values sent to the network map correctly to protobuf definitions.
+    - Required fields are validated before proto construction.
+    - RFC2119 requirements (MUST, SHALL, REQUIRED) are enforced.
+    - Limits such as size bounds, ranges, and uniqueness are implemented where missing.
+    - Enum mappings are correct.
+    - Signing requirements implied by the spec are visible or documented.
+
+    Do NOT require SDK structure, naming, or class design to mirror protobuf.
+
+    If the SDK intentionally diverges from the spec behavior,
+    the pull request MUST clearly explain why the divergence is safe.
+
   path_instructions:
     # --- CODEOWNERS REVIEW INSTRUCTIONS ---
     - path: ".github/CODEOWNERS"

.gitmodules

@@ -153,17 +153,9 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - Replaced the docstring in `entity_id_helper.py` with one that is correct. (#1623)
 
 ### Changed
-- Refactored `setup_client()` in all `examples/query/` files to use `Client.from_env()` for simplified client initialization (#1449)
-- Updated return of to_bytes function in `src/hiero_sdk_python/transaction/transaction.py`. (#1631)
-- Added missing return type `src/hiero_sdk_python/utils/entity_id_helper.py`. (#1622)
-- Update `verify_freeze()` to treat only ACCOUNT_FROZEN_FOR_TOKEN as a successful freeze verification (#1515)
-- Updated team.md with new triage, committers and maintainer (#1692)
-- Removed outdated "Common Issues" section from CONTRIBUTING.md that referenced non-existent docs/common_issues.md (`#1665`)
-- Hide the commit verification bot marker in pull request comments.
-- Added missing type hints to sign method in Transaction class (#1630)
-- Refactored `examples/consensus/topic_create_transaction.py` to use `Client.from_env()` (#1611)
-- Updated GitHub Actions setup-node action to v6.2.0.
+- Refactored AccountInfo class to use the staking_info(#1366)
 - chore: format tests/unit/mock_server.py with black (#1542)
+- Refactored AccountInfo class to use the staking_info
 - Updated actions/checkout to v6.0.1 and actions/github-script v8.0.0 in bot-next-issue-recommendation workflow (#1586)
 - Expanded inactivity bot messages to include `/unassign` command information for contributors (#1555)
 - Update the acceptance criteria wording in the issue templates to improve clarity and consistency for contributors (#1491)

CHANGELOG.md

@@ -0,0 +1,152 @@
+/**
+ * # Address Book Service API
+ * GRPC service definitions for the Hedera Address Book Service (HABS).
+ *
+ * ### 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 proto;
+
+/*
+ * 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.hederahashgraph.service.proto.java";
+// <<<pbj.java_package = "com.hedera.hapi.node.addressbook">>> This comment is special code for setting PBJ Compiler java package
+
+import "transaction_response.proto";
+import "transaction.proto";
+
+/**
+ * The Address Book service provides the ability for Hedera network node
+ * administrators to add, update, and remove consensus nodes. This addition,
+ * update, or removal of a consensus node requires governing council approval,
+ * but each node operator may update their own operational attributes without
+ * additional approval, reducing overhead for routine operations.
+ *
+ * Most operations are `privileged operations` and require governing council
+ * approval.
+ *
+ * ### For a node creation transaction.
+ * - The node operator SHALL create a `createNode` transaction.
+ *    - The node operator MUST sign this transaction with the `Key`
+ *      set as the `admin_key` for the new `Node`.
+ *    - The node operator SHALL deliver the signed transaction to the Hedera
+ *      council representative.
+ *    - The Hedera council representative SHALL arrange for council members to
+ *      review and sign the transaction.
+ *    - Once sufficient council members have signed the transaction, the
+ *      Hedera council representative SHALL submit the transaction to the
+ *      network.
+ * - Upon receipt of a valid and signed node creation transaction the network
+ *   software SHALL
+ *    - Validate the threshold signature for the Hedera governing council
+ *    - Validate the signature of the `Key` provided as the new `admin_key`
+ *      for the `Node`.
+ *    - Create the new node in state, this new node SHALL NOT be active in the
+ *      network at this time.
+ *    - When executing the next `freeze` transaction with `freeze_type` set to
+ *      `PREPARE_UPGRADE`, update network configuration and bring the
+ *      new node to an active status within the network. The node to be added
+ *      SHALL be active in the network following this upgrade.
+ *
+ * ### For a node deletion transaction.
+ * - The node operator or Hedera council representative SHALL create a
+ *   `deleteNode` transaction.
+ *    - If the node operator creates the transaction
+ *       - The node operator MUST sign this transaction with the `Key`
+ *         set as the `admin_key` for the existing `Node`.
+ *       - The node operator SHALL deliver the signed transaction to the Hedera
+ *         council representative.
+ *    - The Hedera council representative SHALL arrange for council members to
+ *      review and sign the transaction.
+ *    - Once sufficient council members have signed the transaction, the
+ *      Hedera council representative SHALL submit the transaction to the
+ *      network.
+ * - Upon receipt of a valid and signed node deletion transaction the network
+ *   software SHALL
+ *    - Validate the signature for the Hedera governing council
+ *    - Remove the existing node from network state. The node SHALL still
+ *      be active in the network at this time.
+ *    - When executing the next `freeze` transaction with `freeze_type` set to
+ *      `PREPARE_UPGRADE`, update network configuration and remove the
+ *      node to be deleted from the network. The node to be deleted SHALL NOT
+ *      be active in the network following this upgrade.
+ *
+ * ### For a node update transaction.
+ * - The node operator SHALL create an `updateNode` transaction.
+ *    - The node operator MUST sign this transaction with the active `key`
+ *      assigned as the `admin_key`.
+ *    - The node operator SHALL submit the transaction to the
+ *      network.  Hedera council approval SHALL NOT be sought for this
+ *      transaction
+ * - Upon receipt of a valid and signed node update transaction the network
+ *   software SHALL
+ *    - If the transaction modifies the value of the "node account",
+ *       - Validate the signature of the active `key` for the account
+ *         assigned as the _current_ "node account".
+ *       - Validate the signature of the active `key` for the account to be
+ *         assigned as the _new_ "node account".
+ *    - Modify the node information held in network state with the changes
+ *      requested in the update transaction. The node changes SHALL NOT be
+ *      applied to network configuration, and SHALL NOT affect network
+ *      operation at this time.
+ *    - When executing the next `freeze` transaction with `freeze_type` set to
+ *      `PREPARE_UPGRADE`, update network configuration according to the
+ *      modified information in network state. The requested changes SHALL
+ *      affect network operation following this upgrade.
+ */
+service AddressBookService {
+    /**
+     * A transaction to create a new consensus node in the network
+     * address book.
+     * <p>
+     * This transaction, once complete, SHALL add a new consensus node to the
+     * network state.<br/>
+     * The new consensus node SHALL remain in state, but SHALL NOT participate
+     * in network consensus until the network updates the network configuration.
+     * <p>
+     * Hedera governing council authorization is REQUIRED for this transaction.
+     */
+    rpc createNode (proto.Transaction) returns (proto.TransactionResponse);
+
+    /**
+     * A transaction to remove a consensus node from the network address
+     * book.
+     * <p>
+     * This transaction, once complete, SHALL remove the identified consensus
+     * node from the network state.
+     * <p>
+     * Hedera governing council authorization is REQUIRED for this transaction.
+     */
+    rpc deleteNode (proto.Transaction) returns (proto.TransactionResponse);
+
+    /**
+     * A transaction to update an existing consensus node from the network
+     * address book.
+     * <p>
+     * This transaction, once complete, SHALL modify the identified consensus
+     * node state as requested.
+     * <p>
+     * This transaction is authorized by the node operator
+     */
+    rpc updateNode (proto.Transaction) returns (proto.TransactionResponse);
+}