.coderabbit.yaml

language: "en-US" # USA English
# Set up means coderabbit should review PRs but only provide one high level walkthrough, collapsed
# It should not state preliminary information like: getting ready to review, draw a picture
# It should not state additional information like: related issues, PRs, suggest reviewers
# It should not continue a casual conversation with users that reply to it

knowledge_base: # Enable knowledge base access for up-to-date information
  web_search: # Enable web search for up-to-date information
    enabled: true

# Only documents non-default options:
reviews:
  profile: "assertive" # Assertive profile yields more feedback, that may be considered nitpicky.
  high_level_summary: false # Do not summarise a pull request first as there is a walkthrough
  review_status: false # Do not state what kind of review as performed or why (spammy)
  commit_status: false # Do not state the review is in progress (spammy)
  collapse_walkthrough: false # Provide a walkthrough for reviewers
  related_issues: false # Do not suggest related issues (spammy)
  related_prs: false # Do not suggest related PRs (spammy)
  suggested_labels: false # Do not suggest labels for the PR (spammy)
  suggested_reviewers: false # Do not suggest reviewers for the PR (spammy)
  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
    in the hiero-sdk-python project.

    This includes:
    - Token transaction classes (inherit from Transaction)
    - Token data classes (e.g. TokenInfo)
    - Token enums and status types

    NOTE:
    - Review focus levels indicate areas requiring careful verification.
    - They do NOT imply severity or urgency.
    - Only recommend fixes when behavior, safety, or API stability is impacted.

    Scope is STRICTLY LIMITED to:
    - Changes under src/hiero_sdk_python/tokens/
    - Their interaction with shared SDK base classes

    ----------------------------------------------------------
    REVIEW FOCUS 1 — API STABILITY & BACKWARDS COMPATIBILITY
    (CONTRACTUAL / HIGH SENSITIVITY)
    ----------------------------------------------------------
    Token APIs are public and user-facing.

    The following MUST remain stable:
    - Public class names
    - Method names and signatures
    - Default values and behaviors
    - Fluent setter chaining semantics

    Flag any change that:
    - Alters method signatures or return types
    - Changes default behavior
    - Renames or removes public attributes

    If a breaking change is unavoidable:
    - Require explicit deprecation warnings
    - Require unit + integration tests
    - Require inline comments explaining migration impact

    ----------------------------------------------------------
    REVIEW FOCUS 2 — TRANSACTION BASE CLASS CONTRACT
    ----------------------------------------------------------
    Applies to classes inheriting from Transaction.

    REQUIRED STRUCTURE:
    - Must call super().__init__() correctly
    - Must implement:
      * _build_proto_body()
      * build_transaction_body()
    - build_scheduled_body():
      * may be less strict, but must be intentional and documented
    - _get_method():
      * MUST reference the correct Hedera service stub
      * MUST align with protobuf service definitions

    Subclasses MUST NOT:
    - Override execution, retry, or backoff logic
    - Manage gRPC deadlines manually
    - Bypass Transaction lifecycle hooks

    ----------------------------------------------------------
    REVIEW FOCUS 3 — PROTOBUF ALIGNMENT
    ----------------------------------------------------------
    Token behavior MUST align with official Hedera protobuf definitions:
    https://github.com/hashgraph/hedera-protobufs/tree/8c27786cec93abab974309074feaef9b48a695b7/services

    Verify that:
    - Protobuf field names match exactly
    - Optional vs required fields are respected
    - Defaults match protobuf expectations
    - No silent divergence in semantics

    Flag mismatches explicitly.

    ----------------------------------------------------------
    REVIEW FOCUS 4 — VALIDATION & ERROR BEHAVIOR
    ----------------------------------------------------------
    Validation rules:
    - All required identifiers must be validated before proto construction
    - Errors must be deterministic and user-readable
    - Exceptions should be raised early and consistently

    Avoid:
    - Deferred runtime failures
    - Ambiguous or generic error messages
    - Silent no-op behavior

    ----------------------------------------------------------
    REVIEW FOCUS 5 — IMPORT & HALLUCINATION SAFETY
    ----------------------------------------------------------
    STRICT IMPORT RULES:
    - All imports MUST exist in src/hiero_sdk_python/
    - Validate paths against existing token modules or shared SDK code
    - Do NOT assume helpers, enums, or utilities exist

    Flag immediately:
    - Non-existent modules
    - Inferred helpers not present in the codebase
    - Copy-paste artifacts from examples or other SDKs

    ----------------------------------------------------------
    REVIEW FOCUS 6 — DATA CLASSES & ENUMS
    ----------------------------------------------------------
    Applies to non-transaction token files.

    Verify that:
    - Enums map cleanly to protobuf or documented values
    - No magic numbers or undocumented defaults exist
    - Public classes are extensible and documented
    - Convenience methods (__str__, __repr__) are present where useful

    ----------------------------------------------------------
    REVIEW FOCUS 7 — TEST & EXAMPLE EXPECTATIONS
    ----------------------------------------------------------
    Good to check whether:
    - Unit tests exist for new or modified behavior
    - Integration tests exist for new transactions
    - Examples reference real, existing APIs

    Missing coverage should be flagged clearly.

    ----------------------------------------------------------
    REVIEW FOCUS 8 — EXPLICIT NON-GOALS
    ----------------------------------------------------------
    Do NOT:
    - Propose refactors unless correctness or safety is impacted
    - Review unrelated SDK components
    - Comment on formatting or lint-only issues

    ----------------------------------------------------------
    FINAL OBJECTIVE
    ----------------------------------------------------------
    Ensure token code is:
    - Backward-compatible
    - Transaction-lifecycle correct
    - Protobuf-aligned
    - Deterministic and user-safe

  # QUERY REVIEW INSTRUCTIONS
  query_review_instructions: &query_review_instructions |
    You are acting as a senior maintainer reviewing the Query base class
    and its subclasses for the hiero-sdk-python project.

    NOTE:
    - Review focus levels indicate areas that are important to check carefully.
    - They do NOT imply severity or urgency.
    - Only recommend fixes when there is a clear behavioral regression.

    Scope is STRICTLY LIMITED to:
    - Changes to the base `Query` class
    - Changes to existing `Query` subclasses
    - Newly added `Query` subclasses

    ----------------------------------------------------------
    REVIEW FOCUS 1 — QUERY SEMANTICS & PAYMENT BEHAVIOR
    (CONTRACTUAL / HIGH SENSITIVITY)
    ----------------------------------------------------------
    Queries do not reach consensus and use `QueryHeader` for payment and responseType.

    The following behaviors are contractual and must remain unchanged:
    - `_is_payment_required()` semantics
    - FREE vs PAID query classification
    - COST_ANSWER vs ANSWER_ONLY behavior
    - Whether a payment transaction is attached

    Good to check and verify that changes do NOT:
    - Alter FREE → PAID or PAID → FREE behavior
    - Attach payment to COST_ANSWER queries
    - Bypass `get_cost(client)` for paid queries
    - Hardcode fees or override payment logic

    ----------------------------------------------------------
    REVIEW FOCUS 2 — EXECUTION LIFECYCLE & BASE CLASS INTEGRITY
    ----------------------------------------------------------
    All queries MUST:
    - Use the base `Query` execution flow
    - Delegate retries, backoff, and node selection to `_Executable`
    - Call `_before_execute(client)` before `_execute(client)`

    Subclasses MUST NOT:
    - Override retry logic
    - Implement custom node selection
    - Manage gRPC deadlines manually
    - Bypass `_Executable` state handling

    Flag deviations for review; recommend fixes only if behavior changes.

    ----------------------------------------------------------
    REVIEW FOCUS 3 — REQUEST CONSTRUCTION CONTRACT
    ----------------------------------------------------------
    `_make_request()` MUST:
    - Validate all required identifiers (accountId, tokenId, topicId, etc.)
    - Call `_make_request_header()` exactly once
    - Populate protobuf fields via `_to_proto()` helpers
    - Avoid manual `QueryHeader` mutation
        
    Subclasses MUST NOT:
    - Set `responseType` directly
    - Inject payment logic
    - Rebuild headers manually

    ----------------------------------------------------------
    REVIEW FOCUS 4 — RESPONSE EXTRACTION & DOMAIN MAPPING
    ----------------------------------------------------------
    `_get_query_response()` MUST:
    - Return the exact protobuf response field
    - Perform NO data transformation
    - Match the expected protobuf response type

    `execute()` MUST NOT:
    - Implement retries or error handling
    - Modify payment or execution behavior
    - Catch and suppress execution errors

    ----------------------------------------------------------
    REVIEW FOCUS 5 — NEW SUBCLASS VALIDATION
    ----------------------------------------------------------
    For newly added `Query` subclasses:
    - Ensure they extend `Query` directly
    - Verify required abstract methods are implemented
    - Confirm payment semantics match the Hedera API
    - Validate protobuf service and method correctness
    - Ensure naming matches existing query patterns

    Missing or incorrect semantics should be flagged clearly.

    ----------------------------------------------------------
    REVIEW FOCUS 6 — REGRESSION & BEHAVIOR CHANGE DETECTION
    ----------------------------------------------------------
    Good to check whether any change:
    - Alters base `Query` behavior
    - Changes default responseType handling
    - Modifies `_make_request_header()` usage
    - Alters `_get_method()` behavior
    - Introduces side effects (logging, prints, stack traces)
    - Changes error propagation behavior

    Small changes should be flagged for verification
    if they could affect execution flow or payment safety.

    ----------------------------------------------------------
    REVIEW FOCUS 7 — EXPLICIT NON-GOALS
    ----------------------------------------------------------
    Do NOT:
    - Review query consumers
    - Propose refactors unless correctness is impacted
    - Comment on style, formatting, or naming unless misleading

    ----------------------------------------------------------
    FINAL OBJECTIVE
    ----------------------------------------------------------
    Ensure Query code remains:
    - Backward-compatible
    - Payment-safe
    - Execution-consistent
    - Strictly aligned with Hedera query semantics
  
  # TRANSACTION REVIEW INSTRUCTIONS - CORE FOUNDATION (MOST CRITICAL MODULE)
  transaction_review_instructions: &transaction_review_instructions |
    You are acting as a senior maintainer and security architect reviewing the **core transaction module** in the hiero-sdk-python project.

    Changes to this module affect **all 50+ transaction implementations** across the entire SDK.

    NOTE:
    - Review focus levels indicate areas requiring careful verification.
    - They do NOT imply severity or urgency.
    - Only recommend fixes when behavior, safety, immutability, or network compatibility is impacted.

    Scope is STRICTLY LIMITED to:
    - Changes under src/hiero_sdk_python/transaction/
    - Interaction with _Executable base class and all transaction subclasses

    ----------------------------------------------------------
    REVIEW FOCUS 1 — BASE CLASS CONTRACT INTEGRITY (HIGH SENSITIVITY)
    ----------------------------------------------------------
    The Transaction base class (which inherits from _Executable) defines the contract for the entire SDK.

    Verify:
    - Abstract methods remain unchanged: build_transaction_body(), build_scheduled_body(), _get_method()
    - Inheritance hierarchy (_Executable → Transaction → subclass) is never broken
    - Any change to public methods (freeze, freeze_with, sign, execute, to_bytes, from_bytes, etc.) includes backwards-compatibility analysis

    Flag as high-risk: signature changes or removal of lifecycle guards that would ripple to every transaction subclass.

    ----------------------------------------------------------
    REVIEW FOCUS 2 — TRANSACTION LIFECYCLE SAFETY (CRITICAL)
    ----------------------------------------------------------
    The freeze-sign-execute pattern with immutability guards is non-negotiable.

    MUST verify:
    - Every setter calls self._require_not_frozen()
    - sign(), execute(), to_bytes(), _to_proto(), etc. call self._require_frozen()
    - No code path allows mutation after freeze
    - freeze_with(client) correctly populates _transaction_body_bytes for every node (including batch_key special case node 0.0.0)
    - freeze() vs freeze_with() distinction is preserved

    Any bypass of these guards = critical security issue.

    ----------------------------------------------------------
    REVIEW FOCUS 3 — MULTI-NODE BODY & SIGNATURE MANAGEMENT (HIGH SENSITIVITY)
    ----------------------------------------------------------
    Node failover and multi-signature support depend on these exact patterns.

    Verify:
    - _transaction_body_bytes: dict[AccountId, bytes] maintains one entry per node AccountId
    - _signature_map keys off the exact body bytes (not node), enabling correct signature lookup on failover
    - Both Ed25519 and ECDSA paths in sign() are preserved and consistent
    - Signature accumulation works for multi-sig and batch_key scenarios

    Any change that could break node failover or signature lookup must be flagged.

    ----------------------------------------------------------
    REVIEW FOCUS 4 — PROTOBUF SERIALIZATION INTEGRITY (CRITICAL)
    ----------------------------------------------------------
    Round-trip safety and type mapping are mandatory.

    Verify:
    - to_bytes() + from_bytes() produce identical, executable objects
    - _get_transaction_class() type map remains complete (especially atomic_batch and all 30+ types)
    - Proper handling of SignedTransaction → bodyBytes → TransactionBody
    - Subclass _from_protobuf / _to_proto implementations stay aligned with Hedera protobufs
    - TransactionId, Receipt, Record parsing (defaultdicts, HasField guards, children/duplicates) is untouched unless intentional

    Missing type-map entry or broken round-trip = critical omission.

    ----------------------------------------------------------
    REVIEW FOCUS 5 — VALIDATION & ERROR HANDLING
    ----------------------------------------------------------
    Validation must be early, deterministic, and occur before any network call.

    Verify:
    - TypeError/ValueError raised correctly in all setters and helpers
    - _should_retry() retryable status codes are not altered casually
    - Proper use of PrecheckError, ReceiptStatusError, MaxAttemptsError
    - BatchTransaction._verify_inner_transaction enforces all constraints

    ----------------------------------------------------------
    REVIEW FOCUS 6 — BATCH TRANSACTION CONSTRAINT GUIDELINES (SECURITY CRITICAL)
    ----------------------------------------------------------
    BatchTransaction is the atomic safety boundary.

    Verify:
    - _verify_inner_transaction rejects FreezeTransaction and nested BatchTransaction
    - Inner transactions must be frozen + have batch_key set
    - build_scheduled_body() always raises ValueError
    - Protobuf packing of inner signedTransactionBytes and atomic_batch field is preserved
    - batchify() / set_batch_key() flow does not bypass lifecycle

    ----------------------------------------------------------
    REVIEW FOCUS 7 — TEST EXPECTATIONS FOR TRANSACTION CHANGES
    ----------------------------------------------------------
    Changes require strong coverage:

    - Unit tests for any new/modified validation, lifecycle, or serialization logic
    - Full freeze → sign → execute (and freeze_with) lifecycle tests
    - Serialization round-trip tests (to_bytes ↔ from_bytes)
    - Integration/mock-server tests covering retry, node failover, error states, and BatchTransaction

    ----------------------------------------------------------
    REVIEW FOCUS 8 — EXPLICIT NON-GOALS
    ----------------------------------------------------------
    Do NOT:
    - Propose large refactors unless they directly improve safety or correctness
    - Review transaction usage outside this module
    - Comment on style/linting unless it affects critical logic
    - Suggest changes to token/query/schedule/contract modules (they inherit the base)

    ----------------------------------------------------------
    FINAL OBJECTIVE
    ----------------------------------------------------------
    Ensure the core Transaction system remains:
    - Secure & immutable by design
    - Failover-safe (multi-node bodies + signatures)
    - Serialization-correct with complete type mapping
    - Extremely safe for batching
    - 100% backwards compatible

  # SCHEDULE REVIEW INSTRUCTIONS
  schedule_review_instructions: &schedule_review_instructions |
    You are acting as a senior maintainer reviewing schedule-related code
    in the hiero-sdk-python project.

    This includes:
    - Schedule transaction classes (ScheduleCreateTransaction, ScheduleSignTransaction, ScheduleDeleteTransaction)
    - Schedule query (ScheduleInfoQuery)
    - Schedule data models (ScheduleId, ScheduleInfo)
    - ScheduleCreateParams dataclass

    NOTE:
    - Review focus levels indicate areas requiring careful verification.
    - They do NOT imply severity or urgency.
    - HIGH SENSITIVITY items require elevated scrutiny — even small changes here can break user code or introduce subtle regressions.
    - Only recommend fixes when behavior, safety, API stability, or spec compliance is impacted.

    Scope is STRICTLY LIMITED to:
    - Changes under src/hiero_sdk_python/schedule/
    - Their interaction with shared SDK base classes (Transaction, Query)

    ----------------------------------------------------------
    REVIEW FOCUS 1 — API STABILITY & BACKWARDS COMPATIBILITY
    (HIGH SENSITIVITY)
    ----------------------------------------------------------
    Public API contracts for ScheduleId, ScheduleInfo, and all schedule transaction classes are user-facing and considered stable.

    The following MUST remain unchanged unless explicitly justified with migration path:
    - Setter method signatures (set_*, build_*) and fluent chaining behavior
    - Constructor signatures and defaults
    - Public property/attribute names
    - Exception types and messages for invalid states

    ScheduleCreateParams dataclass field changes (adding/removing/renaming):
    - Require deprecation warnings if removing or changing behavior
    - Must preserve existing initialization patterns

    Flag any change that alters public method signatures, return types, defaults, or exception behavior.

    ----------------------------------------------------------
    REVIEW FOCUS 2 — TRANSACTION BASE CLASS CONTRACT
    ----------------------------------------------------------
    All schedule transaction classes MUST extend Transaction and follow its contract:

    Required implementations:
    - _build_proto_body()
    - build_transaction_body()
    - build_scheduled_body() — MUST raise ValueError for all schedule tx types
    - _get_method(channel) — correct service stub (createSchedule / signSchedule / deleteSchedule)

    All setter methods MUST:
    - Call self._require_not_frozen() before any mutation
    - Return self for fluent method chaining

    Default transaction fee MUST be Hbar(5).to_tinybars()

    Subclasses MUST NOT:
    - Override execution/retry/backoff logic
    - Bypass lifecycle hooks
    - Manage gRPC deadlines manually

    Flag deviations only if they change observable behavior.

    ----------------------------------------------------------
    REVIEW FOCUS 3 — ANTI-NESTING CONSTRAINT (CRITICAL)
    ----------------------------------------------------------
    The anti-nesting rule is a fundamental safety constraint:

    - build_scheduled_body() MUST raise ValueError("Cannot schedule a Schedule...Transaction")
      in ScheduleCreateTransaction, ScheduleDeleteTransaction, and ScheduleSignTransaction
    - This prevents recursive scheduling — schedule transactions cannot themselves be scheduled

    Any change that:
    - Removes or weakens this raise
    - Implements a working build_scheduled_body() for schedule tx types
    is a critical defect — flag immediately and strongly.

    Unit tests MUST verify the anti-nesting constraint raises ValueError for all three schedule transaction types.

    ----------------------------------------------------------
    REVIEW FOCUS 4 — SIGNATURE SEMANTICS (HIGH SENSITIVITY)
    ----------------------------------------------------------
    Signature roles MUST be clearly distinguished and preserved:

    - Payer signature: Only pays schedule creation fees; does NOT count toward execution
      unless the payer key is also required by the inner transaction
    - Admin key signature: Only required for delete/modify operations; NOT required for execution
    - Inner transaction signatures: Collected via ScheduleSignTransaction; trigger execution when threshold met

    ScheduleInfo.signers MUST contain only inner transaction signers (not payer or admin unless they overlap)

    Documentation and comments MUST clearly distinguish these roles — flag any confusion or incorrect statements.

    ----------------------------------------------------------
    REVIEW FOCUS 5 — SCHEDULE EXECUTION SEMANTICS
    ----------------------------------------------------------
    Execution timing rules MUST be preserved:

    - wait_for_expiry=True: Forces execution to wait until expiration_time, even if all signatures collected early
    - wait_for_expiry=False or None: Executes immediately once all required signatures received

    Key points:
    - expiration_time has network-enforced constraints (client should validate future-dated but not rely solely on it)
    - Edge cases to check: expired schedules, signatures added after execution attempt, timing conflicts

    Flag any change that alters wait_for_expiry propagation or execution triggering logic.

    ----------------------------------------------------------
    REVIEW FOCUS 6 — PROTOBUF ALIGNMENT
    ----------------------------------------------------------
    Serialization/deserialization MUST be faithful to Hedera protobuf definitions.

    All relevant classes MUST implement:
    - _to_proto()
    - _from_proto() (or equivalent classmethod)

    Verify:
    - Field mapping exact (wait_for_expiry, adminKey, payerAccountID, scheduledTransactionBody, etc.)
    - Null-safe conversions using _from_proto_field() / _convert_to_proto() helpers
    - Underscore prefix convention for serialization methods preserved
    - Round-trip integrity (create → info query → fields match)

    Flag any field loss, incorrect defaults, or divergence from protobuf spec.

    ----------------------------------------------------------
    REVIEW FOCUS 7 — VALIDATION & ERROR BEHAVIOR
    ----------------------------------------------------------
    Validation MUST be early, deterministic, and user-friendly:

    - Required fields raise descriptive ValueError (e.g. "Missing required ScheduleID")
    - ScheduleId.from_string() validates format shard.realm.schedule (exactly three integers)
    - Checksum validation uses shared entity_id_helper utilities
    - Error messages include context about what was invalid

    Avoid:
    - Deferred failures
    - Generic messages
    - Silent acceptance of invalid state

    ----------------------------------------------------------
    REVIEW FOCUS 8 — TEST & EXAMPLE EXPECTATIONS
    ----------------------------------------------------------
    Expected coverage:
    - Unit tests for all public methods, constructors, protobuf conversions, and edge cases
    - Integration tests for network interactions, execution triggering, and error scenarios
    - Tests MUST verify anti-nesting constraint raises ValueError for all schedule tx types
    - Examples MUST demonstrate proper multi-signature workflows
    - Examples MUST document signature semantics (payer vs admin vs inner txn roles)

    Missing critical coverage (especially anti-nesting, wait_for_expiry paths) should be flagged.

    ----------------------------------------------------------
    EXPLICIT NON-GOALS
    ----------------------------------------------------------
    Do NOT:
    - Flag style, lint, formatting, or cosmetic changes
    - Propose refactors unless correctness/safety/API stability impacted
    - Suggest unrelated features or broad cleanups

    ----------------------------------------------------------
    FINAL OBJECTIVE
    ----------------------------------------------------------
    Ensure schedule code is:
    - Backward-compatible
    - Anti-nesting & execution semantics correct
    - Signature roles clearly separated
    - Protobuf-aligned
    - Validation-safe
    - Deterministic and protective of users

  # CONTRACT REVIEW INSTRUCTIONS
  contract_review_instructions: &contract_review_instructions |
    You are acting as a senior maintainer reviewing smart contract-related code
    in the hiero-sdk-python project.
    This includes:
    - Contract transaction classes (ContractCreateTransaction, ContractExecuteTransaction, EthereumTransaction)
    - ABI handling (ContractFunctionParameters, ContractFunctionResult)
    - ContractId and related utilities
    NOTE:
    - Review focus levels indicate areas requiring careful verification.
    - They do NOT imply severity or urgency.
    - Only recommend fixes when behavior, safety, ABI correctness, or API stability is impacted.
    Scope is STRICTLY LIMITED to:
    - Changes under src/hiero_sdk_python/contract/
    - Their interaction with shared SDK base classes (Transaction, etc.)
    ----------------------------------------------------------
    REVIEW FOCUS 1 — API STABILITY & BACKWARDS COMPATIBILITY
    (CONTRACTUAL / HIGH SENSITIVITY)
    ----------------------------------------------------------
    Contract APIs are public and user-facing.
    The following MUST remain stable:
    - Public class/method names and signatures (set_*, add_*, get_*)
    - Fluent setter chaining
    - eth-abi based encoding/decoding behavior
    - ContractId constructors and string representations
    - Default gas/initial_balance handling (or lack thereof)
    Flag any change that:
    - Alters method signatures, return types, or exceptions
    - Changes encoding/decoding results for same inputs
    - Modifies ContractId EVM alias ↔ numeric mapping
    - Alters payable amount (amount vs initial_balance) semantics
    
    If breaking: require deprecation warnings (e.g. warnings.warn(..., DeprecationWarning)), migration docs, dual-behavior tests.
    ----------------------------------------------------------
    REVIEW FOCUS 2 — ABI ENCODING/DECODING SAFETY (CRITICAL)
    ----------------------------------------------------------
    Relies on eth-abi — verify strict adherence:
    - All add_* / get_* methods match Solidity types exactly (padding, dynamic handling, signed/unsigned)
    - Function selector computation correct (keccak if function_name set)
    - Dynamic types (string, bytes, arrays) use proper offset + length encoding
    - Revert/custom error decoding in ContractFunctionResult (if enhanced)
    - No silent truncation/overflow in int/uint handling
    Flag unsafe conversions, missing validation, or non-standard ABI deviations.
    ----------------------------------------------------------
    REVIEW FOCUS 3 — TRANSACTION LIFECYCLE & PROTOBUF ALIGNMENT
    ----------------------------------------------------------
    Classes inherit from Transaction — must follow contract:
    - super().__init__()
    - Implement _build_proto_body(), build_transaction_body(), _get_method()
    - build_scheduled_body() optional but consistent
    Protobuf fields MUST match Hedera protobufs (ContractCreateTransactionBody, ContractCallTransactionBody, EthereumTransactionBody):
    - gas, initialBalance/amount, constructorParameters/functionParameters
    - Correct handling of optional fields (None → omitted)
    - No manual mutation of protobuf objects
    EthereumTransaction: cannot be scheduled — enforce raise
    Flag lifecycle bypasses or protobuf mismatches.
    ----------------------------------------------------------
    REVIEW FOCUS 4 — GAS, VALUE & PAYABLE SAFETY
    ----------------------------------------------------------
    - Gas required for create/execute — enforce validation
    - Payable amount (initial_balance / amount) in tinybars — verify Hbar conversion
    - No automatic gas estimation — users set explicitly
    - Flag missing checks for payable functions (if SDK adds awareness)
    - Ensure no negative/zero gas without justification
    ----------------------------------------------------------
    REVIEW FOCUS 5 — EVM ADDRESS & CONTRACT ID HANDLING
    ----------------------------------------------------------
    - ContractId supports EVM alias — verify from_evm_address(), to_evm_address()
    - Mirror-node population (populate_contract_num) safe and optional
    - Checksum validation only for numeric form
    - Flag invalid conversions or missing validation
    ----------------------------------------------------------
    REVIEW FOCUS 6 — VALIDATION, ERRORS & SAFETY
    ----------------------------------------------------------
    - Raise early on missing required fields (bytecode/gas/contract_id)
    - Deterministic, clear exceptions (ValueError preferred)
    - No silent failures or deferred errors
    - Avoid unsafe assumptions in eth_abi calls
    ----------------------------------------------------------
    REVIEW FOCUS 7 — TEST & EXAMPLE EXPECTATIONS
    ----------------------------------------------------------
    Good to check:
    - Unit tests for encoding/decoding round-trips, edge types (large arrays, zero values)
    - Failure cases: revert, invalid params, gas exhaustion
    - Integration: deploy → call → query → result parse
    - Examples use safe patterns (explicit gas, receipt checks, try/except)
    ----------------------------------------------------------
    REVIEW FOCUS 8 — EXPLICIT NON-GOALS
    ----------------------------------------------------------
    Do NOT:
    - Propose adding gas estimation unless PR claims it
    - Review unrelated protobuf or transaction base logic
    - Nitpick style/formatting unless misleading
    ----------------------------------------------------------
    FINAL OBJECTIVE
    ----------------------------------------------------------
    Ensure contract code is:
    - Backward-compatible
    - ABI-correct & eth-abi safe
    - Protobuf-aligned with Hedera/Hiero
    - Gas/value safe
    - Deterministic and user-protective
  
  # NODES REVIEW INSTRUCTIONS — PRIVILEGED NODE LIFECYCLE OPERATIONS
  node_review_instructions: &node_review_instructions |
    You are acting as a senior maintainer and security architect reviewing the nodes module
    in the hiero-sdk-python project.

    This module handles privileged administrative operations for network node lifecycle management
    (create, update, delete). These operations are restricted to network operators and require
    special permissions (e.g., account 0.0.2 on solo network).

    The module contains three transaction classes — NodeCreateTransaction, NodeUpdateTransaction,
    NodeDeleteTransaction — that all inherit from the Transaction base class.

    NOTE:
    - Review focus levels indicate areas requiring careful verification.
    - They do NOT imply severity or urgency.
    - Only recommend fixes when they impact security, correctness, reliability, or public API stability.

    Scope is STRICTLY LIMITED to:
    - src/hiero_sdk_python/nodes/**/*.py
    - src/hiero_sdk_python/node.py
    - src/hiero_sdk_python/managed_node_address.py
    - src/hiero_sdk_python/address_book/**/*.py
    - Direct interactions with the Transaction base class and AddressBookService

    ----------------------------------------------------------
    REVIEW FOCUS 1 — PRIVILEGED OPERATIONS (CRITICAL)
    ----------------------------------------------------------
    All node transactions are administrative operations, not available to regular users.

    Verify:
    - Privilege documentation is clear in docstrings and examples
    - Any change that might expose these operations includes appropriate warnings
    - Tests and examples clearly document network/permission requirements

    ----------------------------------------------------------
    REVIEW FOCUS 2 — TRANSACTION LIFECYCLE COMPLIANCE
    ----------------------------------------------------------
    Verify strict adherence to the freeze-sign-execute pattern used across the SDK.

    Verify:
    - All setters call self._require_not_frozen()
    - All setters return self for fluent method chaining
    - freeze_with → sign → execute flow is preserved
    - NodeCreateTransaction and NodeUpdateTransaction require admin key signing
    - NodeDeleteTransaction has different signing semantics

    ----------------------------------------------------------
    REVIEW FOCUS 3 — CERTIFICATE HANDLING (SECURITY CRITICAL)
    ----------------------------------------------------------
    Certificate handling is security critical.

    Verify:
    - gossip_ca_certificate is bytes (DER-encoded x509 certificate)
    - grpc_certificate_hash is the SHA-384 hash of the gRPC TLS certificate
    - No acceptance of arbitrary certificate data without size/format validation
    - Certificate format conversion (hex string → bytes.fromhex()) is correct
    - Examples correctly show hex-to-bytes conversion

    ----------------------------------------------------------
    REVIEW FOCUS 4 — ENDPOINT CONFIGURATION
    ----------------------------------------------------------
    Verify correct handling of endpoint types and validation.

    Verify:
    - Distinction between gossip_endpoints (node-to-node), service_endpoints (client-to-node),
      and grpc_web_proxy_endpoint
    - Endpoint objects have required properties (domain_name or address + port)
    - Port normalization behavior (0 or 50111 → 50211 in protobuf conversion)
    - Empty endpoint lists are handled appropriately
    - Integration with address_book.endpoint.Endpoint class is correct

    ----------------------------------------------------------
    REVIEW FOCUS 5 — ADMIN KEY SEMANTICS (HIGH SENSITIVITY)
    ----------------------------------------------------------
    Admin key handling follows HIP-869 rules.

    Verify:
    - Admin key changes in NodeUpdateTransaction often require dual signatures (old + new key)
    - NodeCreateTransaction and NodeUpdateTransaction must be signed with the admin key
    - NodeDeleteTransaction does not require admin key signature
    - Lost admin key scenario (delete + recreate) is handled correctly
    - Proper PublicKey generation and extraction patterns

    ----------------------------------------------------------
    REVIEW FOCUS 6 — NODE ID & INPUT VALIDATION
    ----------------------------------------------------------
    Verify robust validation and clear error handling.

    Verify:
    - node_id (integer) is required in NodeDeleteTransaction (raises ValueError if missing)
    - node_id is the integer identifier returned from NodeCreate
    - Clear distinction between node_id (int) and account_id (AccountId object)
    - Validation logic uses clear, actionable error messages

    ----------------------------------------------------------
    REVIEW FOCUS 7 — PROTOBUF ALIGNMENT
    ----------------------------------------------------------
    Verify perfect alignment with official Hiero protobufs.

    Verify:
    - Field mapping matches NodeCreateTransactionBody / NodeUpdateTransactionBody / NodeDeleteTransactionBody
    - NodeUpdateTransaction correctly uses protobuf wrapper types (StringValue, BytesValue, BoolValue)
    - _build_proto_body(), build_transaction_body(), build_scheduled_body() maintain consistency
    - Integration with AddressBookService gRPC methods (createNode, updateNode, deleteNode) is correct

    ----------------------------------------------------------
    REVIEW FOCUS 8 — BACKWARDS COMPATIBILITY & CLIENT INTEGRATION
    ----------------------------------------------------------
    These APIs are public-facing.

    Verify:
    - No breaking changes to existing usage patterns
    - Client node configuration and transaction patterns remain unchanged

    ----------------------------------------------------------
    REVIEW FOCUS 9 — TEST & EXAMPLE EXPECTATIONS
    ----------------------------------------------------------
    Good to check whether:
    - Unit tests exist for new or modified node transaction behavior
    - Integration tests cover privileged operations with appropriate network setup
    - Examples clearly document permission requirements (e.g., account 0.0.2)
    - Certificate and endpoint handling edge cases are tested

    Missing coverage should be flagged clearly.
    
    ----------------------------------------------------------
    EXPLICIT NON-GOALS
    ----------------------------------------------------------
    Do NOT:
    - Review style, formatting, or linting issues (handled by other tools)
    - Propose refactors unless they impact correctness, safety, or security
    - Review unrelated SDK components outside the nodes module
    - Suggest generic improvements beyond the PR’s stated objectives
    - Validate network-level privilege enforcement (delegated to Hedera consensus)

    ----------------------------------------------------------
    FINAL OBJECTIVE
    ----------------------------------------------------------
    Ensure the nodes module is:
    - Secure (especially certificates and admin keys)
    - Protocol-correct
    - Backwards-compatible
    - Clearly documented for its privileged nature

  # FILE REVIEW INSTRUCTIONS
  file_review_instructions: &file_review_instructions |
    You are acting as a senior maintainer reviewing file service-related code
    in the hiero-sdk-python project.
    
    This includes:
    - File transactions (FileCreateTransaction, FileUpdateTransaction, FileAppendTransaction, FileDeleteTransaction)
    - File query (FileContentsQuery, FileInfoQuery)
    - File data models (FileId, FileInfo)

    NOTE:
    - Review focus levels (including labels like "HIGH SENSITIVITY") indicate where to apply extra scrutiny.
    - They do NOT map to production incident severity or operational urgency.
    - Only recommend fixes when behavior, safety, backwards compatibility, or chunking semantics are impacted.

    Scope is STRICTLY LIMITED to:
    - Changes under src/hiero_sdk_python/file/
    - Their interaction with shared SDK base classes (Transaction, Query)

    ----------------------------------------------------------
    REVIEW FOCUS 1 — API STABILITY & BACKWARDS COMPATIBILITY
    (HIGH SENSITIVITY)
    ----------------------------------------------------------
    Public API contracts for FileId, FileInfo, and file transactions are user-facing.
    
    Verify that:
    - Setter method signatures (e.g., set_contents, set_file_memo) stay backward compatible.
    - Method chaining (returning self) is preserved.
    - FileId constructors and string representations don't break existing use cases.
    
    If breaking changes are necessary, they must be explicit and deprecation warnings should be added.

    ----------------------------------------------------------
    REVIEW FOCUS 2 — CHUNKING SEMANTICS (HIGH VERIFICATION)
    ----------------------------------------------------------
    Specific to FileAppendTransaction, which natively handles chunking.
    
    Verify that:
    - freeze_with() correctly generates sequential TransactionIds for each chunk.
    - valid_start timestamps for each chunk are spaced out correctly (e.g., incremented by at least 1 nanosecond).
    - execute() handles signing and executing each chunk sequentially.
    - Validation bounds for max_chunks and chunk_size are strictly enforced.

    Flag any change that modifies the multi-chunk loop or skips timestamp incrementation.

    ----------------------------------------------------------
    REVIEW FOCUS 3 — MEMO HANDLING
    ----------------------------------------------------------
    Nuanced memo distinction across the file module:
    
    Verify that:
    - The distinction between file_memo (the metadata attribute of the file) and transaction_memo (the note on the transaction itself) is respected.
    - FileCreateTransaction handles file_memo as a native string.
    - FileUpdateTransaction correctly wraps its memo in Google's StringValue protobuf wrapper to distinguish between an absent unchanged state and an explicit clearing of the memo.

    Flag if file_memo string values are mishandled or swapped with transaction_memo.

    ----------------------------------------------------------
    REVIEW FOCUS 4 — TRANSACTION BASE CLASS CONTRACT
    ----------------------------------------------------------
    All file transaction classes MUST inherit from Transaction.
    
    Required implementations:
    - _build_proto_body()
    - build_transaction_body()
    - build_scheduled_body()
    - _get_method(channel)

    Verify that:
    - All setters call self._require_not_frozen() before mutation.
    - Chunk payload slicing in build_transaction_body() accurately extracts the current chunk before signing and execution.

    ----------------------------------------------------------
    REVIEW FOCUS 5 — PROTOBUF ALIGNMENT
    ----------------------------------------------------------
    Serialization and deserialization MUST map directly to Hedera protobufs.
    
    Verify that:
    - fileCreate, fileUpdate, fileAppend, and fileDelete fields map exactly to their respective protobuf bodies.
    - Null-safe conversions are handling optional properties safely.

    ----------------------------------------------------------
    REVIEW FOCUS 6 — TEST EXPECTATIONS
    ----------------------------------------------------------
    Good to check:
    - Robust unit and integration tests exist for chunking limits and bounds.
    - Examples accurately depict native chunking over manual looping.

    ----------------------------------------------------------
    REVIEW FOCUS 7 — VALIDATION & ERROR BEHAVIOR
    ----------------------------------------------------------
    Required validations must not be deferred to the node.

    Verify that:
    - Null-checking is aggressively performed (e.g., FileId existence before queries or delete operations).
    - Client-side size and bounds validations correctly raise deterministic exceptions prior to network execution.
    - File keys are strictly required for creation and update commands.
    - Silent no-ops or ignored input states are flagged.

    ----------------------------------------------------------
    EXPLICIT NON-GOALS
    ----------------------------------------------------------
    Do NOT:
    - Propose refactors unless they directly improve safety, chunking correctness, or API stability.
    - Suggest sweeping style or naming changes unless they are actively misleading.
    - Flag logic outside of the file module.

    ----------------------------------------------------------
    FINAL OBJECTIVE
    ----------------------------------------------------------
    Ensure the file service code is:
    - Backward-compatible
    - Chunking-safe and deterministically executed
    - Accurately aligned with protobuf definitions
    - Validating inputs consistently

  # CRYPTO REVIEW INSTRUCTIONS
  crypto_review_instructions: &crypto_review_instructions |
    You are acting as a senior maintainer reviewing cryptography-related code
    in the hiero-sdk-python project.

    This includes:
    - PrivateKey (Ed25519 and ECDSA(secp256k1))
    - PublicKey (Ed25519 and ECDSA(secp256k1))
    - EvmAddress
  
    NOTE:
    - Review focus levels indicate areas requiring careful verification.
    - They do NOT imply severity or urgency.
    - Only recommend fixes when correctness, safety, determinism,
      cryptographic soundness, or API stability is impacted.

    Scope is STRICTLY LIMITED to:
    - src/hiero_sdk_python/crypto/*.py
    - Their interaction with shared SDK utilities

    ----------------------------------------------------------
    REVIEW FOCUS 1 — API STABILITY & BACKWARDS COMPATIBILITY
    ----------------------------------------------------------
    Crypto APIs are public and security-sensitive.

    The following MUST remain stable:
    - Public class names
    - Method names and signatures
    - Return types
    - Key serialization formats (raw, DER, hex)
    - Signature formats (raw r||s for ECDSA)

    Flag any change that:
    - Alters method signatures or return types
    - Changes serialization output format
    - Changes signature encoding behavior
    - Modifies equality or hashing semantics

    If a breaking change is unavoidable:
    - Require explicit deprecation warnings
    - Require unit tests covering old vs new behavior
    - Require inline documentation explaining migration impact

    ----------------------------------------------------------
    REVIEW FOCUS 2 — CRYPTOGRAPHIC CORRECTNESS
    ----------------------------------------------------------
    Verify correctness of:
    - Ed25519 key handling
    - ECDSA (secp256k1) key handling
    - Compressed vs uncompressed public keys
    - DER parsing and generation
    - Raw 64-byte (r||s) signature handling
    - keccak256 hashing usage
    - EVM address derivation (rightmost 20 bytes of Keccak-256)

    Confirm that:
    - No incorrect hash function combinations are used
    - Prehashed signing/verification is used correctly
    - Signature malleability risks are addressed or intentional
    - No ambiguous key interpretation occurs silently
    - Invalid key lengths fail deterministically

    Flag:
    - Any incorrect hash algorithm pairing
    - Any improper DER normalization
    - Any silent fallback logic
    - Any potential signature malleability issue
    - Any inconsistent signature verification logic

    ----------------------------------------------------------
    REVIEW FOCUS 3 — KEY AMBIGUITY & TYPE SAFETY
    ----------------------------------------------------------
    32-byte inputs can represent:
    - Ed25519 private keys
    - ECDSA (secp256k1) private scalars

    Verify that:
    - Ambiguity is handled explicitly
    - No silent reinterpretation occurs
    - Explicit algorithm intent is preserved
    - Warnings or safeguards are meaningful and consistent

    PublicKey and PrivateKey MUST:
    - Never silently switch algorithms
    - Never infer algorithm incorrectly from length alone

    ----------------------------------------------------------
    REVIEW FOCUS 4 — SERIALIZATION & DETERMINISM
    ----------------------------------------------------------
    Verify that:
    - Raw bytes serialization is stable
    - DER serialization is canonical
    - Hex encoding is lowercase and deterministic
    - Equality (__eq__) matches cryptographic identity
    - __hash__ is correct and deterministic
    - No runtime errors occur in hashing

    Flag:
    - Incorrect hash implementations
    - NameErrors or undefined variables
    - Non-deterministic serialization behavior

    ----------------------------------------------------------
    REVIEW FOCUS 5 — EVM ADDRESS INTEGRITY
    ----------------------------------------------------------
    EvmAddress MUST:
    - Be exactly 20 bytes
    - Be derived correctly from Keccak-256
    - Reject invalid hex strings
    - Avoid silent truncation or padding

    Verify:
    - from_string validation correctness
    - to_string format consistency
    - Equality and hashing correctness

    Flag:
    - Incorrect length checks
    - Unsafe parsing
    - Broken __hash__ implementations

    ----------------------------------------------------------
    REVIEW FOCUS 6 — VALIDATION & ERROR BEHAVIOR
    ----------------------------------------------------------
    All validation must:
    - Fail early
    - Raise deterministic exceptions
    - Avoid ambiguous error messages
    - Avoid leaking sensitive key material in errors

    Ensure:
    - Private keys are never exposed in __repr__
    - Error messages do not contain raw key material
    - TypeErrors and ValueErrors are consistent

    ----------------------------------------------------------
    REVIEW FOCUS 7 — IMPORT SAFETY
    ----------------------------------------------------------
    STRICT IMPORT RULES:
    - All imports MUST exist in src/hiero_sdk_python/
    - Do NOT assume helpers exist
    - Do NOT infer utilities from other SDKs
    - Validate keccak256 implementation source

    Flag immediately:
    - Undefined names
    - Copy-paste artifacts
    - Incorrect external crypto assumptions

    ----------------------------------------------------------
    REVIEW FOCUS 8 — EXPLICIT NON-GOALS
    ----------------------------------------------------------
    Do NOT:
    - Suggest refactors unless security or correctness is impacted
    - Recommend stylistic or formatting-only changes
    - Propose performance optimizations without correctness impact
    - Review unrelated SDK components

    ----------------------------------------------------------
    FINAL OBJECTIVE
    ----------------------------------------------------------
    Ensure crypto code is:
    - Cryptographically correct
    - Deterministic
    - Non-ambiguous
    - Backward-compatible
    - Safe against misuse
    - Free from silent cryptographic errors

  # ============================================================
  # GLOBAL REVIEW INSTRUCTIONS (APPLY TO ALL FILES)
  # ============================================================
  instructions: |
    You are a code reviewer whose primary responsibility is to verify that the code changes in this pull request fully address the specific requirements outlined in the associated issue description or pull request description.
    **ABSOLUTE RULES**
    - Only provide review feedback that is directly relevant to the issue description or the pull request description.
    - Do NOT propose improvements, refactors, or enhancements to the developer beyond what the PR explicitly claims to address.
    **SCOPE CONTROL**
    - If you identify issues that are real but outside the PR's stated scope:
      - 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.
  path_instructions:
    # --- CODEOWNERS REVIEW INSTRUCTIONS ---
    - path: ".github/CODEOWNERS"
      instructions: |
        You are acting as a senior maintainer reviewing the CODEOWNERS file
        for the hiero-sdk-python repository. This file controls review
        enforcement and repository governance.

        Your role is to verify correctness, coverage, and organizational
        alignment — not formatting preferences.

        ----------------------------------------------------------
        REVIEW FOCUS 1 — TEAM SLUG CORRECTNESS (CRITICAL)
        ----------------------------------------------------------
        All GitHub team references MUST use the exact, valid organization
        team slugs that represent teams with write or higher permissions.

        Flag as critical:
        - Any non-existent team slugs
        - Use of individual usernames
        - Inclusion of teams that do NOT have write permissions
          (eg @hiero-ledger/hiero-sdk-python-triage)

        Expected teams commonly include:
        - @hiero-ledger/hiero-sdk-python-maintainers
        - @hiero-ledger/hiero-sdk-python-committers
        - @hiero-ledger/github-maintainers
        - @hiero-ledger/tsc

        The following team MUST NOT appear because they do not have write access:
        - @hiero-ledger/hiero-sdk-python-triage
        ----------------------------------------------------------
        REVIEW FOCUS 2 — DIRECTORY VS FILE MATCHING (HIGH IMPORTANCE)
        ----------------------------------------------------------
        Directories that are intended to cover their contents MUST use /**
        Flag directory cases like:
        - /.github/workflows incorrect, use /.github/workflows/**

        Specific files MUST remain specific to them and NOT use /**
        - /.github/CODEOWNERS/** incorrect, use /.github/CODEOWNERS

        Ensure rules actually match real repo assets.

        ----------------------------------------------------------
        REVIEW FOCUS 3 — PRECEDENCE & ORDERING (HIGH IMPORTANCE)
        ----------------------------------------------------------
        CODEOWNERS uses last-match-wins precedence.

        Flag if rule ordering breaks CODEOWNERS precedence (last match wins):
        - A broad rule (e.g. *) appears after more specific rules
        - A broader path (e.g. /.github/**) appears after a more specific subpath rule
          (e.g. /.github/workflows/**)        
        - A sensitive path (e.g. /.github/workflows/**) is followed by a broader rule that would override it

        ----------------------------------------------------------
        REVIEW FOCUS 4 — REPOSITORY GOVERNANCE PROTECTION (HIGH IMPORTANCE)
        ----------------------------------------------------------
        These paths must NOT be owned only by committers.

        Ensure these include @hiero-ledger/github-maintainers:
        - /.github/workflows/**
        - /.github/scripts/**
        - /.github/CODEOWNERS
        - /CODEOWNERS (enables root-level protection)

        Ensure packaging governance includes:
        - /pyproject.toml → @hiero-ledger/hiero-sdk-python-maintainers, @hiero-ledger/github-maintainers, @hiero-ledger/tsc


        Flag missing governance coverage.

        ----------------------------------------------------------
        REVIEW FOCUS 5 — SCOPE APPROPRIATENESS (MEDIUM IMPORTANCE)
        ----------------------------------------------------------
        Committers may own source, tests, and documentation, but
        governance and infrastructure files should be maintainer-level
        or higher.

        Flag if:
        - TSC or GitHub maintainers are missing from critical governance files

        ----------------------------------------------------------
        REVIEW FOCUS 6 — REDUNDANCY & DEAD RULES (MEDIUM IMPORTANCE)
        ----------------------------------------------------------
        Identify rules that will never apply because a later rule overrides
        them, or because the path does not exist.

        Examples to flag:
        - Duplicate patterns that are shadowed by broader ones, that do not improve clarity
        - Rules referencing directories or files not present in the repo

        EXCEPTION:
        The following paths are intentional future-protection rules and MUST
        NOT be flagged as dead even if the file does not currently exist:
        - /CODEOWNERS
        ----------------------------------------------------------
        EXPLICIT NON-GOALS (CRITICAL IMPORTANCE)
        ----------------------------------------------------------
        Do NOT:
        - Suggest stylistic formatting changes
        - Suggest reordering rules UNLESS precedence is incorrect
        - Suggest adding reviewers or changing org governance policy

        ----------------------------------------------------------
        FINAL OBJECTIVE
        ----------------------------------------------------------
        Ensure the CODEOWNERS file:
        - Uses valid GitHub team slugs
        - Correctly matches repository paths
        - Enforces intended review governance
        - Has no precedence bugs that weaken protection
    # PROTOBUF INSTRUCTIONS
    - path: "src/hiero_sdk_python/**/*.py"
      instructions: |
        ## Protobuf Schema Alignment Review
    
        ### Step 1 — Detect protobuf imports
    
        Scan the file for all imports matching this pattern:
          `from hiero_sdk_python.hapi.<path> import <module>_pb2`
    
        For each import found, skip `_grpc` stubs (those end in `_pb2_grpc`) — only
        process `_pb2` message modules.
    
        ### Step 2 — Construct the canonical schema URL
    
        For each `_pb2` import:
        1. Extract the path segment after `hapi`
           (e.g. `services` from `hiero_sdk_python.hapi.services`)
        2. Extract the module name before `_pb2`
           (e.g. `transaction_record` from `transaction_record_pb2`)
        3. Build the canonical URL:
           `https://github.com/hashgraph/hedera-protobufs/blob/v0.72.0-rc.2/<path>/<module>.proto`
    
        **Example:**
        ```
        Import:  from hiero_sdk_python.hapi.services import transaction_record_pb2
        Schema:  https://github.com/hashgraph/hedera-protobufs/blob/v0.72.0-rc.2/services/transaction_record.proto
        ```
    
        ### Step 3 — Compare the SDK class against the proto schema
    
        For each SDK class that calls `_from_proto` or `_to_proto` using messages from
        the detected proto module, verify the following:
    
        #### 3a. Field coverage
        - Every non-deprecated proto field SHOULD have a corresponding SDK attribute.
        - Flag any proto field that is present in the schema but missing from the SDK
          class (either as a dataclass field or handled in `_from_proto`).
        - Flag any SDK attribute that references a proto field name that does not exist
          in the schema.
    
        #### 3b. Field name mapping
        - Proto field names use `snake_case` (e.g. `ethereum_hash`) or `camelCase`
          (e.g. `transactionHash`, `consensusTimestamp`). Verify that `_from_proto`
          accesses the correct proto field name, not a renamed/misspelled version.
        - Verify `_to_proto` sets the correct proto field name.
    
        #### 3c. Field type alignment
        Check that each SDK field type correctly represents the proto type:
    
        | Proto type             | Expected SDK type                            |
        |------------------------|----------------------------------------------|
        | `string`               | `str \| None` or `str`                       |
        | `bytes`                | `bytes \| None` or `bytes`                   |
        | `bool`                 | `bool`                                       |
        | `int32`, `uint32`      | `int`                                        |
        | `int64`, `uint64`, `sint64` | `int`                                   |
        | `MessageType`          | corresponding SDK wrapper class or `None`    |
        | `repeated MessageType` | `list[SdkType]`                              |
        | `repeated scalar`      | `list[scalar]`                               |
    
        #### 3d. `oneof` field handling
        - Identify all `oneof` blocks in the proto schema for the message.
        - Verify that `_to_proto` does NOT set more than one field from the same
          `oneof` block simultaneously. If it does, a `ValueError` guard MUST be
          present before setting those fields.
        - Verify that `_from_proto` uses `proto.HasField(...)` (not attribute access)
          to detect which branch of a `oneof` is populated.
        - Common `oneof` groups to watch for in `TransactionRecord`:
          - `oneof body { contractCallResult, contractCreateResult }` (fields 7, 8)
          - `oneof entropy { prng_bytes, prng_number }` (fields 19, 20)
    
        #### 3e. Bytes field normalization
        - Proto `bytes` fields default to `b""` (empty bytes) when unset, not `None`.
        - If the SDK models the field as `bytes | None`, verify that `_from_proto`
          uses `proto.<field> or None` to normalize empty bytes to `None`.
        - Conversely, if `_to_proto` sets a bytes field, verify it guards against
          setting `None` (which would cause a protobuf type error).
    
        #### 3f. `_from_proto` / `_to_proto` symmetry
        - Every field parsed in `_from_proto` SHOULD also be serialized in `_to_proto`,
          and vice versa, unless the field is intentionally read-only (e.g. server-set
          fields that clients never send).
        - Flag any asymmetry that is not accompanied by a code comment explaining why.
    
        #### 3g. Repeated field default values
        - SDK attributes representing proto `repeated` fields MUST default to an empty
          list (`field(default_factory=list)`), never `None`.
        - Flag any `repeated` field that defaults to `None`.
    
        #### 3h. Type annotation consistency
        - The codebase uses `X | None` union syntax (Python 3.10+). Flag any use of
          `Optional[X]` from `typing` in newly added or modified code, as it is
          inconsistent with the established style.
    
        ### Step 4 — Report format
    
        For each issue found, report:
        - **File and line**: where the issue occurs
        - **Proto field**: the canonical proto field name and number from the schema
        - **Issue type**: one of — Missing field | Wrong field name | Wrong type |
          oneof violation | Bytes not normalized | Asymmetric round-trip |
          Wrong default | Style inconsistency
        - **Description**: concise explanation of the discrepancy
        - **Suggested fix**: the corrected code snippet
    
        If no issues are found for a file, state:
          All mapped proto fields align with the schema at `<URL>`.
    - path: "src/hiero_sdk_python/tokens/**/*.py"
      instructions: *token_review_instructions
    - path: "src/hiero_sdk_python/transaction/**/*.py"
      instructions: *transaction_review_instructions
    - path: "src/hiero_sdk_python/schedule/**/*.py"
      instructions: *schedule_review_instructions

    # --- CUSTOM INSTRUCTIONS FOR EXAMPLES DIRECTORY ---
    - path: "examples/**/*"
      instructions: |
        You are acting as a senior maintainer reviewing SDK examples. Your goal is to ensure examples work verbatim for users who copy-paste them.

        **Priority 1 - Correctness**: 
        - Verify transaction lifecycle chain (construction -> freeze_with -> sign -> execute).
        - Ensure `freeze_with(client)` is called BEFORE signing.
        - Validate that methods referenced actually exist in the `hiero_sdk_python` codebase.
        - Ensure response validation checks `receipt.status` against `ResponseCode` enums (e.g., `ResponseCode.SUCCESS`).

        **Priority 2 - Transaction Lifecycle**: 
        - Check method chaining logic.
        - Verify correct signing order (especially for multi-sig).
        - Ensure explicit `.execute(client)` calls.
        - Verify response property extraction (e.g., using `.token_id`, `.account_id`, `.serial_numbers`).
        - Ensure error handling uses `ResponseCode(receipt.status).name` for clarity.

        **Priority 3 - Naming & Clarity**: 
        - Enforce role-based naming: `operator_id`/`_key`, `treasury_account_id`/`_key`, `receiver_id`/`_key`.
        - Use `_id` suffix for AccountId and `_key` suffix for PrivateKey variables.
        - Validate negative examples explicitly check for failure codes (e.g., `TOKEN_HAS_NO_PAUSE_KEY`).
        - Ensure logical top-to-bottom flow without ambiguity.

        **Priority 4 - Consistency**: 
        - Verify standard patterns: `def main()`, `if __name__ == "__main__":`, `load_dotenv()`.
        - **IMPORT RULES**: 
          1. Accept both top-level imports (e.g., `from hiero_sdk_python import PrivateKey`) and fully qualified imports (e.g., `from hiero_sdk_python.crypto.private_key import PrivateKey`).
          2. STRICTLY validate that the import path actually exists in the project structure. Compare against other files in `/examples` or your knowledge of the SDK file tree.
          3. Flag hallucinations immediately (e.g., `hiero_sdk_python.keys` does not exist).
        - Check for `try-except` blocks with `sys.exit(1)` for critical failures.

        **Priority 5 - User Experience**: 
        - Ensure comments explain SDK usage patterns (for users, not contributors).
        - Avoid nitpicking functional code.
        - Suggest type hints or docstrings only if they significantly improve clarity.

        **Philosophy**: 
        - Examples are copied by users - prioritize explicitness over brevity.
        - Avoid suggestions that `ruff` or linters would catch.
        - Be concise, technical, and opinionated.
        - Flag out-of-scope improvements as potential new issues rather than blocking.

    # --- UNIT TESTS REVIEW INSTRUCTIONS ---
    - path: "tests/unit/**/*"
      instructions: |
        You are acting as a senior maintainer reviewing unit tests for the hiero-sdk-python project.  Your goal is to ensure tests are extensive, deterministic, and protect against breaking changes.

        **CRITICAL PRINCIPLES - Tests Must Fail Loudly & Deterministically**:
        - Tests must provide useful error messages when they fail for future debugging.
        - No `print()` statements - use assertions with descriptive messages.
        - No timing-dependent or unseeded random assertions.
        - No network calls or external dependencies (unit tests are isolated).
        - No unjustified TODOs or skipped tests without tracking issues.

        **PRIORITY 1 - Protect Against Breaking Changes**:
        - Assert public attributes exist (e.g., `assert hasattr(obj, 'account_id')`).
        - Assert return types where relevant (e.g., `assert isinstance(result, AccountId)`).
        - Assert fluent setters return `self` (e.g., `assert tx.set_memo("test") is tx`).
        - Assert backward-compatible defaults are maintained. 
        - If a breaking change is introduced, tests must assert deprecation behavior and test old behavior until removal.

        **PRIORITY 2 - Constructor & Setter Behavior**:
        - Test constructor behavior with valid inputs, edge cases, and invalid inputs.
        - Test setter behavior including method chaining (fluent interface).
        - Verify that setters validate input and raise appropriate exceptions.
        - Test that getters return expected values after construction/setting.

        **PRIORITY 3 - Comprehensive Coverage**: 
        - Unit tests should be extensive - test even if we don't expect users to use it currently.
        - Cover happy paths AND unhappy paths/edge cases.
        - Test boundary conditions, null/None values, empty collections, etc.
        - Avoid brittle ordering assertions unless order is part of the contract. 

        **PRIORITY 4 - No Mocks for Non-Existent Modules**:
        - All imports must reference actual SDK modules - no hallucinated paths.
        - Validate import paths against the actual `src/hiero_sdk_python` structure.
        - Mocks should only be used for external dependencies, not SDK internals.

        **PRIORITY 5 - Test Framework Philosophy**:
        - Prefer repetitive but clear tests over abstracted helper functions.
        - Some core functionality may warrant helper files (considered an exception).
        - Discourage custom helper functions; prefer pytest fixtures when shared setup is needed. 
        - Prefer testing real functionality over mocked behavior.

        **AVOID**:
        - Linter or formatting feedback (leave that to ruff/pre-commit).
        - Nitpicking minor stylistic issues unless they impact maintainability.
        - Overly abstracted test helpers that obscure what's being tested. 

        **PHILOSOPHY**:  
        - Unit tests protect our future selves - be defensive and forward-looking.
        - Tests should be readable by SDK developers:  clear names, brief docstrings, key inline comments.
        - When tests fail, we should immediately know what broke and why.

    # --- INTEGRATION TESTS REVIEW INSTRUCTIONS ---
    - path: "tests/integration/**/*"
      instructions: |
        You are acting as a senior maintainer reviewing integration tests for the hiero-sdk-python project. Your goal is to ensure end-to-end tests validate real network behavior safely and deterministically.

        **CRITICAL PRINCIPLES - Safety & Diagnosability**:
        - **Prioritize safety**: No implicit or default mainnet usage.
        - Secrets and credentials must be injected safely (env vars, not hardcoded).
        - Test failures must be diagnosable with clear error messages.
        - Tests must assert observable network behavior, not just `SUCCESS`.
        - Failure-path tests must assert specific `ResponseCode` values (e.g., `TOKEN_HAS_NO_PAUSE_KEY`).

        **PRIORITY 1 - End-to-End Behavior**:
        - Tests should be end-to-end:  construct → freeze → sign → execute → verify.
        - Validate resulting balances, ownership, and state changes (not just transaction success).
        - Assert transaction receipts contain expected data (IDs, serial numbers, etc.).
        - Verify network state after operations (e.g., account balance changed, token transferred).

        **PRIORITY 2 - Test Structure & Maintainability**:
        - One major behavior per test (clear focus).
        - Tests should be readable:  clear names, brief docstrings, key inline comments.
        - Minimal abstraction layers - prefer clarity over DRY.
        - Is the file too monolithic? Flag if tests should be split into smaller modules. 
        - Are helper functions good candidates for pytest fixtures or shared utilities?

        **PRIORITY 3 - Isolation & Cleanup**:
        - Local account creation over operator reuse (avoid state pollution).
        - Are accounts, tokens, and allowances properly cleaned up to avoid state leakage?
        - Recommend teardown strategies or fixture scoping improvements. 
        - Tests should not depend on execution order (avoid brittle assumptions).

        **PRIORITY 4 - Assertions & Coverage**:
        - Do tests validate only success/failure, or also assert resulting state? 
        - Suggest additional assertions that would strengthen correctness (balances, allowances, ownership).
        - Cover happy paths AND unhappy paths (e.g., invalid spender, revoked allowance, insufficient balance).
        - Avoid timing-based or flaky assumptions.

        **PRIORITY 5 - Observability & Debugging**:
        - Could structured logging or transaction metadata improve debugging?
        - Suggest capturing allowance values, transaction IDs, and balances in logs.
        - Ensure error messages provide context for failure diagnosis. 

        **AVOID**:
        - Linter or formatting feedback.
        - Overly abstracted helpers that obscure what's being tested.
        - Timing-dependent assertions (use explicit waits or retries if needed).

        **PHILOSOPHY**: 
        - Integration tests validate real network behavior - they must be reliable and safe.
        - Tests should protect against regressions while being maintainable.
        - When tests fail in CI, developers should immediately understand what broke. 
        - Redundant setup code should be refactored, but clarity trumps abstraction.

    # --- DOCUMENTATION REVIEW INSTRUCTIONS ---
    - path: "docs/**"
      instructions: |
        You are reviewing documentation for the Hiero Python SDK. These pages serve both SDK users and SDK developers.

        Priority 1 - Correctness (code, commands, links)
        1. Verify code snippets conceptually run and match the current SDK API.
        2. Check shell commands and workflow steps against actual project tooling.
        3. Validate URLs and cross-references; flag broken or misleading links.

        Priority 2 - Clarity and completeness
        1. Ensure each page states its purpose and expected outcome early.
        2. Prefer concrete, step-wise explanations over vague descriptions.
        3. Highlight missing prerequisites that would block a reader.
        4. For larger gaps, suggest filing a follow-up issue instead of blocking.

        Priority 3 - Consistency and navigation
        1. Encourage consistent terminology with the SDK and examples.
        2. Check headings form a logical reading path.
        3. Confirm each page makes clear which audience it serves.

        PHILOSOPHY
        - Treat docs as work-in-progress: optimize for correctness and clarity over perfection.
        - Keep feedback concise, action-oriented, and focused on reader success.
        - Do not request large-scale restructures unless current structure blocks understanding.

        AVOID
        - Avoid lint-style feedback on Markdown formatting or minor wording.
        - Avoid proposing new conventions without clear benefit.
        - Avoid turning every high-level gap into a blocker.

    - path: "docs/sdk_users/**"
      instructions: |
        These documents are for SDK users who want to USE the Hiero Python SDK quickly and correctly.

        Priority 1 - High-level guidance
        1. Ensure explanations are conceptual and point to `/examples` for runnable code.
        2. Check that required environment variables and network choices are clearly stated.

        Priority 2 - No hidden assumptions
        1. Assume zero prior knowledge of this SDK and minimal Hedera background.
        2. Avoid requiring knowledge of repository layout or contribution workflow.

        PHILOSOPHY
        - Keep explanations high-level and conceptual; defer runnable examples to `/examples`.
        - Focus on what users need to know before diving into code examples.

    - path: "docs/sdk_developers/**"
      instructions: |
        These documents are for SDK developers and contributors, including `docs/sdk_developers/training/**`.

        Priority 1 - Workflow accuracy
        1. Ensure contribution, branching, rebasing, signing (DCO, GPG), CI, linting, and testing instructions match the repo.
        2. Verify `git` and GitHub flows agree with CONTRIBUTING.md and current practice.
        3. Flag outdated references to scripts, directories, or configuration files.

        Priority 2 - Training flow
        1. For training docs, ensure logical progression and clear prerequisites.
        2. Check that cross-links between training files are coherent.

        PHILOSOPHY
        - Treat these docs as a training ground for future maintainers and regular contributors.
        - Help readers move from "I cloned the repo" to "I can safely extend and debug the SDK".
        - Balance approachability for beginners with enough depth for experts.

    # --- CUSTOM INSTRUCTIONS FOR .GITHUB DIRECTORY ---
    - path: ".github/workflows/**/*"
      instructions: |
        You are reviewing GitHub Actions workflows as a thoughtful senior
        engineer. Your goal is to nudge contributors toward higher-quality,
        maintainable workflows — not to impose a rigid checklist.

        ---------------------------------------------------------
        SECURITY ESSENTIALS
        ---------------------------------------------------------
        These are firm expectations for every workflow:

        - All third-party actions must be pinned to full commit SHAs,
          consistent with other workflows in this repository.
        - `permissions:` must be explicitly declared and scoped to the
          minimum needed. Flag over-permissioned or under-permissioned
          workflows, and any reliance on broad default permissions.
        - Workflows must not request `contents: write` unless strictly
          required.
        - Workflows must behave safely when executed from forks.
        - Treat all GitHub event data as potentially untrusted input:
          issue titles, bodies, comments, labels, usernames, branch
          names. Prefer strict allowlists or exact string matches.
          Free-form user input must not flow directly into shell
          commands, `gh` CLI arguments, or Node.js exec/spawn calls.

        ---------------------------------------------------------
        CLARITY & CODE ORGANIZATION
        ---------------------------------------------------------
        Each workflow should have a single, clearly defined objective.
        YAML should orchestrate execution — not implement business
        logic.

        - Non-trivial logic belongs in dedicated scripts under
          `.github/scripts/`, keeping the workflow YAML focused on
          orchestration.
        - Environment variables should be defined in the YAML and
          passed to scripts, not hardcoded inside scripts.
        - Flag large `run: |` blocks, inline loops or conditionals,
          and API calls embedded directly in YAML steps.

        ---------------------------------------------------------
        DRY-RUN
        ---------------------------------------------------------
        If used, dry-run should be clear, well-logged, and default
        to true on `workflow_dispatch`. It should have a reasonable
        use case and be easy to maintain. Do not flag missing dry-run
        as a blocker.

        ---------------------------------------------------------
        OPERATIONAL QUALITY
        ---------------------------------------------------------
        - Log key decisions and early exits — avoid silent skips.
        - Avoid raw payload dumps and any secret or token leakage.
        - Workflows that mutate state should use concurrency groups
          and duplicate prevention patterns (marker-based comments,
          check-before-create for labels).
        - Assume workflows may run multiple times or be retried.

        ---------------------------------------------------------
        API DISCIPLINE
        ---------------------------------------------------------
        - Prefer reusing data already in the event payload over
          making additional API calls.
        - Prefer aggregated queries and server-side filtering over
          per-entity loops and client-side iteration.
        - Pagination should have reasonable upper bounds.

        ---------------------------------------------------------
        REVIEW SCOPE
        ---------------------------------------------------------
        - Focus feedback on the PR's stated scope.
        - Flag out-of-scope issues as irrelevant and suggest opening
          a separate PR — do not block for them.
        - Do not propose major refactors unless correctness or
          security is affected.

        ---------------------------------------------------------
        BLOCKERS vs SUGGESTIONS
        ---------------------------------------------------------
        - Block only for security, correctness, or firm expectation
          violations.
        - Style and maintainability improvements should be
          non-blocking suggestions.
        - When in doubt, suggest — don't block.

    # ============================================================
    # SHELL SCRIPTS
    # ============================================================
    - path: ".github/scripts/**/*.sh"
      instructions: |
        Review shell scripts as production-grade CI automation.

        Firm expectations:
        - Use `set -euo pipefail` to fail fast on errors.
        - Environment variables should be passed from the YAML,
          validated early, and defensively quoted.
        - No `eval`, `bash -c`, backticks, or `$(...)` with untrusted content.

        Good practices:
        - Log key decisions and early exits.
        - Keep scripts purpose-built — flag overly generic helpers.

    # ============================================================
    # JAVASCRIPT SCRIPTS
    # ============================================================
    - path: ".github/scripts/**/*.js"
      instructions: |
        Review JavaScript scripts as production-grade CI automation.

        Firm expectations:
        - Validate `context.payload` fields before use.
        - Do not trust free-form text from issues, PRs, or comments.
        - No `eval`, `new Function`, or dynamic code execution.
        - Use top-level constants for configuration — avoid
          hardcoded values scattered through the script.
        - Environment variables should be passed from the workflow
          YAML, not hardcoded in the script.

        Good practices:
        - Wrap async operations in try/catch with contextual errors.
        - Reuse event context data instead of making redundant API
          calls.
        - Use marker-based patterns to prevent duplicate actions.
        - Handle permission failures gracefully.

    - path: "src/hiero_sdk_python/query/**/*.py"
      instructions: *query_review_instructions

    - path: "src/hiero_sdk_python/contract/**/*_query.py"
      instructions: *query_review_instructions

    - path: "src/hiero_sdk_python/file/**/*_query.py"
      instructions: *query_review_instructions

    - path: "src/hiero_sdk_python/contract/**"
      instructions: *contract_review_instructions

    # Nodes module — Privileged administrative node lifecycle operations (new anchor)
    - path: "src/hiero_sdk_python/nodes/**/*.py"
      instructions: *node_review_instructions
    - path: "src/hiero_sdk_python/node.py"
      instructions: *node_review_instructions
    - path: "src/hiero_sdk_python/managed_node_address.py"
      instructions: *node_review_instructions
    - path: "src/hiero_sdk_python/address_book/**/*.py"
      instructions: *node_review_instructions
    - path: "src/hiero_sdk_python/file/**/*.py"
      instructions: *file_review_instructions
    - path: "src/hiero_sdk_python/consensus/**/*.py"
      instructions: |
        You are reviewing Python files in the `src/hiero_sdk_python/consensus/` directory.
        These files implement consensus-related transactions and queries for the Hiero SDK.

        > Note: Protobuf schema alignment (field names, types, oneof, bytes normalization,
        > repeated defaults, and canonical `.proto` URL derivation) is already enforced by
        > the global `src/hiero_sdk_python/**/*.py` instruction. Do NOT re-run those checks
        > here — focus exclusively on the consensus-domain concerns below.

        ---

        ## Review priorities (highest → lowest)

        ### 1) Protobuf correctness (must-not-break)
        - Validate field names, field types, and (if visible/known) field numbers +
          repeated/optional semantics.
        - Flag any divergence as **BLOCKER**.

        ### 2) Serialization / wire-format integrity
        - Ensure `to_proto` / `from_proto` (or equivalent) set the correct oneof
          branches and do not drop fields.
        - Confirm byte/string encoding, timestamps/durations, and `TransactionID` /
          `TopicID` mapping are correct.
        - Treat silent coercions, defaulting, or ignored exceptions as **BLOCKER** if
          they could change what is signed or sent.
        - **Memo-overwrite trap**: any field whose Python default is `""` or `0` instead
          of `None` and is later guarded by `if field is not None` will *always* serialize
          — even when the caller never set it — silently overwriting the on-chain value.
          Verify every optional update field defaults to `None`, not a falsy sentinel.
          Flag as **BLOCKER** if the unintended overwrite affects keys, expiry, or memo.

        ### 3) Signing / transaction body construction
        - Verify the class builds the transaction/query body exactly once and uses the
          correct protobuf message type.
        - Ensure required fields are enforced before freezing/signing (if the SDK has a
          freeze step).
        - Missing required fields or signing the wrong body type is **BLOCKER**.

        #### 3a) Multi-chunk TransactionID safety (`TopicMessageSubmitTransaction`)
        When reviewing chunked message submission, verify all of the following:

        **Nanos-overflow guard**
        - In `freeze_with()`, the expression `base_timestamp.nanos + i` MUST be checked
          for overflow. Protobuf `Timestamp.nanos` is bounded to `[0, 999_999_999]`.
          If `nanos + num_chunks > 999_999_999` the value wraps or is rejected by the
          node. An overflow guard MUST carry seconds over:
          ```python
          total_nanos = base_timestamp.nanos + i
          chunk_valid_start = timestamp_pb2.Timestamp(
              seconds=base_timestamp.seconds + total_nanos // 1_000_000_000,
              nanos=total_nanos % 1_000_000_000
          )
          ```
          Flag the absence of this guard as **BLOCKER**.

        **`_initial_transaction_id` null-safety**
        - `_build_proto_body()` calls `self._initial_transaction_id._to_proto()` when
          `_total_chunks > 1`. If `freeze_with()` was never called (e.g. the caller
          invokes `build_transaction_body()` directly on a multi-chunk message),
          `_initial_transaction_id` is `None` and this raises `AttributeError` at
          serialization time. An explicit `if self._initial_transaction_id is None`
          guard with a descriptive `ValueError` MUST be present.
          Flag as **BLOCKER**.

        **Chunk signing consistency**
        - In `execute()`, each chunk clears `_transaction_body_bytes` and
          `_signature_map` then re-signs with every key in `_signing_keys`. Verify
          that the re-sign loop uses the *stored* signing keys and not the operator
          key only, so submit-key-protected topics are signed correctly for every chunk.
          Flag any chunk that may be sent unsigned or with an incomplete signature set
          as **BLOCKER**.

        ### 4) Topic ID handling & validation
        - Validate `TopicId` parsing, checksum/network validation (if applicable), and
          conversion to protobuf.
        - Check `from_string` for the bare `except Exception` catch: it loses the
          original exception type; the re-raised `ValueError` should chain with `from e`
          (already present) — verify the chaining is not accidentally removed.
        - Incorrect network scoping/checksum behavior is **MAJOR** (or **BLOCKER** if
          it can misroute funds/requests).
        - **Frozen-dataclass checksum mutation**: `topic_id.py` uses
          `object.__setattr__(topic_id, "checksum", checksum)` to bypass `frozen=True`.
          Verify this is the only site where the frozen contract is broken, and that no
          other attribute is mutated this way.

        ### 5) Fees, limits, and defaults

        #### 5a) Mutable default arguments in `__init__`
        - Flag any mutable object used directly as a default parameter value in a method
          signature. This is a Python anti-pattern because the object is shared across
          all instances constructed without that argument.
        - **Known instance**: `TopicUpdateTransaction.__init__` declares
          `auto_renew_period: Optional[Duration] = Duration(7890000)`.
          The fix is to default to `None` and assign in the body:
          ```python
          def __init__(self, ..., auto_renew_period: Optional[Duration] = None, ...):
              ...
              self.auto_renew_period = auto_renew_period if auto_renew_period is not None \
                  else Duration(7890000)
          ```
          Flag as **MAJOR** (shared mutable state across instances; mutating one
          instance's default would silently affect others).
        - Apply the same check to any `list` or `dict` default arguments.

        #### 5b) Cross-class `transaction_fee` consistency
        - Verify that the hardcoded `transaction_fee` defaults are intentional and
          consistent across all sibling classes in this directory.
        - Flag the **missing override** in `TopicMessageSubmitTransaction` as **MAJOR**
          if the base-class default is not appropriate for message submission, or add a
          comment confirming the base-class value is intentional.
        - Flag any value that deviates from sibling-class defaults as **MAJOR**.

        #### 5c) General fee/limit logic
        - Confirm any fee/max payment logic is consistent and does not allow unintended
          "free" execution.
        - Suspicious defaults or overflow/underflow issues are **MAJOR**.

        ### 6) Errors & API ergonomics
        - Errors should be actionable and consistent; avoid swallowing RPC/precheck errors.
        - Ambiguous exceptions or inconsistent return types are **MINOR** / **MAJOR**
          depending on impact.
        - **`execute()` return-type consistency**: `TopicMessageSubmitTransaction.execute()`
          returns `responses[0] if responses else None`. The `None` branch is unreachable
          in practice (the loop always runs at least once for `num_chunks >= 2`) but
          it makes the declared return type `TransactionReceipt | None`, which is
          inconsistent with the single-chunk path. Flag as **MINOR**.

        ### 7) Tests / examples (regression protection)
        - Prefer tests that assert on produced protobufs (fields set, oneofs, ids).
        - Cover: valid submit, missing topic id, empty message, large message boundary (if enforced), invalid checksum/network.
        - Missing critical tests is **MAJOR** (or **MINOR** if coverage exists elsewhere).

        ---

        ## Severity labels
        Use exactly these labels in all findings:
        - **BLOCKER** — must be fixed before merge; wire-format, signing, or data-loss risk
        - **MAJOR** — should be fixed; correctness or significant usability issue
        - **MINOR** — should be fixed; low-risk correctness or ergonomics issue
        - **NIT** — optional; style, naming, or documentation only

    - path: "src/hiero_sdk_python/crypto/**/*.py"
      instructions: *crypto_review_instructions

    - path: "src/hiero_sdk_python/account/**/*.py"
      instructions: |
        You are reviewing Python files in the `src/hiero_sdk_python/account/` directory.
        These files implement account-related transactions, queries, and data types for the Hiero SDK.

        > Note: Protobuf schema alignment (field names, types, oneof, bytes normalization,
        > repeated defaults, and canonical `.proto` URL derivation) is already enforced by
        > the global `src/hiero_sdk_python/**/*.py` instruction. Do NOT re-run those checks
        > here — focus exclusively on the account-domain concerns below.

        ---

        ## Review priorities (highest → lowest)

        ### 1) Protobuf correctness (must-not-break)
        - Validate field names, field types, and field numbers +
          repeated/optional semantics against the canonical `.proto` schema.
        - Ensure `_to_proto` / `_from_proto` set the correct oneof branches
          and do not drop fields.
        - Treat silent coercions, defaulting, or ignored exceptions as
          **BLOCKER** if they could change what is signed or sent.

        ### 2) AccountId — alias / EVM address handling
        `AccountId` has three identity modes: numeric `num`, `alias_key`,
        and `evm_address`. Verify `_from_proto`/`_to_proto` symmetry across
        all three. `__hash__` only covers `(shard, realm, num)` — alias-only
        IDs with `num=0` can collide in dicts/sets. **MAJOR** if broken.

        ### 3) Allowance mutation paths
        When modifying existing `TokenNftAllowance` entries, mutation path and
        append path must set `approved_for_all` to the same intended value.
        `None` passed to typed arguments like `amount` must raise, not silently
        produce zero. **MAJOR**.

        ### 4) Errors & API ergonomics
        - Errors should be actionable and consistent; avoid swallowing or
          printing RPC/precheck errors.
        - Ambiguous exceptions or inconsistent return types are **MINOR** /
          **MAJOR** depending on impact.

        ---

        ## ARCHITECTURAL INVARIANTS (stable)
        These describe what must always be true, regardless of code changes.
        They are ordered by severity.

        1. **Falsy-guard trap on optional integers** — Fields like
          `staked_node_id` where `0` is a valid value must never use
          `if field:` guards. Use `if field is not None:`. **BLOCKER**
          if it silently drops valid data.

        2. **Mutable default arguments** — Flag any mutable object
          (`list`, `dict`, `set`, or non-frozen class instance) used as
          a default parameter in `__init__`. Default to `None` and assign
          in the body. **MAJOR**.

          Exception: frozen/immutable types are safe as defaults and must
          NOT be flagged. This includes `@dataclass(frozen=True)` classes
          (e.g., `Duration`), tuples, frozensets, and primitives (int, str,
          bool, None).

        3. **Library-safe error handling** — No bare `except Exception`
          with `print`/`traceback` in library code. Callers cannot
          suppress stdout side effects. **MAJOR**.

        ---

        ## KNOWN INSTANCES (transient — remove when fixed)

        _Check if these still exist before flagging._

        - `AccountRecordsQuery._make_request`: bare except + print
          → violates invariant #3
        - `AccountId.from_string`: verify `from e` chaining not removed
          → exception context silently lost if removed
        - `AccountInfo._to_proto`: falsy guard on `staked_node_id`
          → violates invariant #1

        ---

        ## Test expectations
        PRs modifying account code should have tests covering:
        - AccountId round-trip across all three identity modes
        - `__hash__` behavior for alias-only IDs with `num=0`
        - Invalid/None arguments raising errors, not silently defaulting
        - `_from_proto(_to_proto(x))` field round-trip equality
        
        ---

        ## Severity labels
        Use exactly these labels in all findings:
        - **BLOCKER** — must be fixed before merge; wire-format, signing, or data-loss risk
        - **MAJOR** — should be fixed; correctness or significant usability issue
        - **MINOR** — should be fixed; low-risk correctness or ergonomics issue
        - **NIT** — optional; style, naming, or documentation only

chat:
  art: false # Don't draw ASCII art (false)
  auto_reply: false # Don't allow bot to converse (spammy)