.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

# 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)
  knowledge_base: # Enable knowledge base access for up-to-date information
    web_search: # Enable web search for up-to-date information
      enabled: true

  # 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

  # 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

  # GLOBAL REVIEW INSTRUCTIONS
  python_review_instructions: &python_review_instructions |
    **CRITICAL FOCUS - Protobuf Alignment**
    When reviewing Python files, check for imports containing "hapi" in the format:  
    `from hiero_sdk_python.hapi.<path> import <module>_pb2`  
      
    For each such import found:  
    1. Extract the path component after "hapi" (e.g., "services" from "hapi.services")  
    2. Extract the module name before "_pb2" (e.g., "consensus_submit_message" from "consensus_submit_message_pb2")  
    3. Construct the canonical schema URL:   
        https://github.com/hashgraph/hedera-protobufs/blob/main/<path>/<module>.proto  
      
    Example:  
    For import: `from hiero_sdk_python.hapi.services import consensus_submit_message_pb2`
    Generate: https://github.com/hashgraph/hedera-protobufs/blob/main/services/consensus_submit_message.proto
    Ensure all message fields and types align with the latest definitions in the referenced .proto file.
    Flag any discrepancies in field names, types, or required/optional status.
  
  # ============================================================
  # 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
    - path: "src/hiero_sdk_python/tokens/**/*.py"
      instructions: *token_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: |
        Review workflows as security-sensitive infrastructure.

        A good workflow is small, focused, and boring.
        If a workflow is clever, generic, or overly flexible, it is a risk.

        ---------------------------------------------------------
        PRIORITY 0 — ABSOLUTE REQUIREMENTS 
        ---------------------------------------------------------
        - All third-party actions MUST be pinned to full commit SHAs, similar to other workflows.
        - `permissions:` MUST be explicitly declared and minimally scoped.
        - Workflows MUST behave safely when executed from forks.
        - YAML MUST orchestrate steps, not implement business logic.
        - Any workflow that mutates GitHub state MUST support dry-run mode.
        - Dry-run behavior must be explicit and visible in logs.
        - Workflows MUST NOT modify repository source code outside `.github/`.

        ---------------------------------------------------------
        PRIORITY 1 — SCOPE, FOCUS & RESTRAINT
        ---------------------------------------------------------
        - The title of each workflow must be relevant, match similar naming schemes, and match its script filename.
        - Each workflow MUST have a single, clearly defined objective and SHOULD document this in a top-level comment.
        - Flag workflows that:
          - Attempt to be generic “frameworks”
          - Include speculative or future-facing logic
          - Perform actions unrelated to the stated goal
        - Over-abstraction and excess flexibility are maintenance risks.

        ---------------------------------------------------------
        PRIORITY 2 — INPUT HARDENING
        ---------------------------------------------------------
        - Treat ALL GitHub event data as potentially hostile input, including:
          - issue titles, bodies, and comments
          - labels, usernames, branch names
        - Free-form user input MUST NOT be passed directly into:
          - shell commands
          - gh CLI arguments
          - Node.js exec / spawn calls
        - Require strict allowlists or exact string matches.
        - Flag any use of:
          - eval or bash -c
          - backticks or $(...) with user-controlled input

        ---------------------------------------------------------
        PRIORITY 3 — DRY-RUN & SAFE OPERATION
        ---------------------------------------------------------
        - Workflows that mutate state MUST expose:
          workflow_dispatch:
            inputs:
              dry_run:
                default: "true"
        - When dry_run=true, workflows MUST:
          - Log dry mode is active
          - Function on dry run: never post, comment, label, assign or edit
          - Be easy to expand in the future
          - Exit successfully

        ---------------------------------------------------------
        PRIORITY 4 — SCRIPT EXTRACTION & CODE TRIM
        ---------------------------------------------------------
        - YAML should orchestrate execution only.
        - All non-trivial logic MUST live in:
          - `.github/scripts/*.sh`
          - `.github/scripts/*.js`
        - Workflow filenames and their primary scripts SHOULD share a clear, matching name.
        - Scripts MUST remain:
          - Purpose-built
          - Trim and readable
          - Easy to maintain
        - Flag:
          - Large `run: |` blocks
          - Inline loops, conditionals, or API calls in YAML
          - Overly generic helper scripts for narrow tasks

        ---------------------------------------------------------
        PRIORITY 5 — API EFFICIENCY & DISCIPLINE
        ---------------------------------------------------------
        - GitHub API usage must be intentional and minimal.
        - Prefer:
          - Aggregated queries over per-entity loops
          - Server-side filtering over client-side iteration
          - Reusing data already present in the event payload
        - Pagination MUST:
          - Be considered and justified
          - Enforce hard upper bounds
        - Flag:
          - Repeated API calls inside loops
          - Unbounded pagination
          - Fetching data already available in context

        ---------------------------------------------------------
        PRIORITY 6 — CONCURRENCY & IDEMPOTENCY
        ---------------------------------------------------------
        - Workflows that mutate state MUST:
          - Define a deterministic concurrency group
          - Be safe under retries and parallel execution
        - Duplicate prevention is REQUIRED:
          - Marker-based comment detection
          - Check-before-create logic for labels and assignments
        - Assume workflows may:
          - Run multiple times
          - Be retried automatically
          - Execute concurrently with other automations
        - Workflows should avoid logic that duplicates or causes conflicts.

        ---------------------------------------------------------
        PRIORITY 7 — PERMISSION CORRECTNESS
        ---------------------------------------------------------
        - Requested permissions MUST exactly match behavior.
        - Explicitly validate common cases:
          - issues: write → comments, labels, assignments
          - contents: read → repository checkout
          - pull-requests: write → PR mutations
        - Flag:
          - Over-permissioned workflows
          - Under-permissioned workflows that would fail at runtime
          - Reliance on default permissions

        ---------------------------------------------------------
        PRIORITY 8 — LOGGING & OPERABILITY
        ---------------------------------------------------------
        - Logs should include, where applicable:
          - repository
          - workflow name
          - issue or PR number
          - triggering actor
          - dry-run status
          - decisions made (performed vs skipped)
        - Avoid:
          - Silent success or silent skips
          - Raw payload dumps
          - Any secret or token leakage

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

        Scripts should be small, focused, and explicit.
        Avoid “do-everything” or overly generic scripts.

        - MUST use: `set -euo pipefail`
        - MUST validate all required environment variables
        - MUST defensively quote variables
        - MUST validate all untrusted input
        - MUST have bounded loops and pagination
        - MUST support dry-run mode if state is mutated
        - MUST log key decisions and early exits

    # ============================================================
    # JAVASCRIPT SCRIPTS
    # ============================================================
    - path: ".github/scripts/**/*.js"
      instructions: |
        Review JavaScript scripts as long-lived automation code.

        Scripts must remain:
        - Focused
        - Readable
        - Purpose-built

        - All `context.payload` fields MUST be validated
        - Free-form text MUST NOT be trusted
        - Dynamic code execution is prohibited
        - Avoid `child_process.exec`; prefer `execFile` if needed
        - All async operations MUST be wrapped in try/catch
        - Errors MUST include contextual metadata
        - Duplicate API calls MUST be avoided
        - Marker-based deduplication is required
        - Scripts MUST NOT assume write access
        - Permission failures MUST be handled 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/contract/**"
      instructions: *contract_review_instructions

    - path: "src/hiero_sdk_python/consensus/**/*.py"  
      instructions: |
        <<apply: *python_review_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.
        Please apply the global review instructions for Python files, with a critical focus on protobuf alignment. In addition to the global instructions, please pay special attention to the following aspects specific to consensus-related code:
        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_protobuf` / `from_protobuf` (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/sent.

        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**.

        4) **Topic ID handling & validation**
          - Validate `TopicId` parsing, checksum/network validation (if applicable), and conversion to protobuf.
          - Incorrect network scoping/checksum behavior is **MAJOR** (or **BLOCKER** if it can misroute funds/requests).

        5) **Fees, limits, and defaults**
          - 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.

        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).

        When reporting findings:
        - Use severity labels: **BLOCKER**, **MAJOR**, **MINOR**, **NIT**.
        - For protobuf issues, always include the computed hedera-protobufs `.proto` URL(s) you used.


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