feat: add AccountRecordsQuery (#407)

Signed-off-by: nadineloe <[email protected]>
Co-authored-by: nadineloe <[email protected]>

Author: Dosik13

CHANGELOG.md

@@ -10,17 +10,19 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 ### Added
 - Add Google-style docstrings to `AccountInfo` class and its methods in `account_info.py`.
 
+- add AccountRecordsQuery class
+
 ### Changed
 
 ### Fixed
+
 - Added explicit read permissions to examples.yml (#623)
 
 ### Breaking Changes
 
 
 ## [0.1.7] - 2025-10-28
 
-
 ### Added
 - Expanded `README.md` with a new "Follow Us" section detailing how to watch, star, and fork the repository (#472).
 - Refactored `examples/topic_create.py` into modular functions for better readability and reuse.
@@ -129,7 +131,6 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 ## [0.1.5] - 2025-09-25
 
 ### Added
-
 - ScheduleSignTransaction class
 - NodeUpdateTransaction class
 - NodeDeleteTransaction class

docs/sdk_users/running_examples.md

@@ -18,6 +18,7 @@ You can choose either syntax or even mix both styles in your projects.
   - [Updating an Account](#updating-an-account)
   - [Allowance Approve Transaction](#allowance-approve-transaction)
   - [Allowance Delete Transaction](#allowance-delete-transaction)
+  - [Querying Account Records](#querying-account-records)
 - [Token Transactions](#token-transactions)
   - [Creating a Token](#creating-a-token)
   - [Minting a Fungible Token](#minting-a-fungible-token)
@@ -345,6 +346,28 @@ transaction.sign(owner_private_key)
 transaction.execute(client)
 ```
 
+### Querying Account Records
+
+#### Pythonic Syntax:
+```python
+records = AccountRecordsQuery(account_id=account_id).execute(client)
+
+for record in records:
+    print(record)
+```
+
+#### Method Chaining:
+```python
+records = (
+    AccountRecordsQuery()
+    .set_account_id(account_id)
+    .execute(client)
+)
+
+for record in records:
+    print(record)
+```
+
 ## Token Transactions
 
 ### Creating a Token

examples/query_account_records.py

@@ -0,0 +1,159 @@
+"""
+Example demonstrating account records query on the network.
+"""
+
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from hiero_sdk_python import (
+    AccountCreateTransaction,
+    AccountId,
+    Client,
+    Hbar,
+    Network,
+    PrivateKey,
+    ResponseCode,
+)
+from hiero_sdk_python.account.account_records_query import AccountRecordsQuery
+from hiero_sdk_python.transaction.transfer_transaction import TransferTransaction
+
+load_dotenv()
+
+
+def setup_client():
+    """Initialize and set up the client with operator account"""
+    network = Network(os.getenv('NETWORK'))
+    client = Client(network)
+
+    operator_id = AccountId.from_string(os.getenv("OPERATOR_ID"))
+    operator_key = PrivateKey.from_string(os.getenv("OPERATOR_KEY"))
+    client.set_operator(operator_id, operator_key)
+
+    return client
+
+
+def create_account(client):
+    """Create a test account"""
+    account_private_key = PrivateKey.generate_ed25519()
+    account_public_key = account_private_key.public_key()
+
+    receipt = (
+        AccountCreateTransaction()
+        .set_key(account_public_key)
+        .set_initial_balance(Hbar(2))
+        .set_account_memo("Test account for records query")
+        .freeze_with(client)
+        .execute(client)
+    )
+
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"Account creation failed with status: {ResponseCode(receipt.status).name}")
+        sys.exit(1)
+
+    account_id = receipt.account_id
+    print(f"\nAccount created with ID: {account_id}")
+
+    return account_id, account_private_key
+
+
+def format_single_record(record, idx):
+    """Format a single account record"""
+    lines = []
+    lines.append(f"\nRecord #{idx}")
+    lines.append("-" * 80)
+
+    transaction_id = getattr(record, 'transaction_id', None)
+    if transaction_id:
+        lines.append(f"  Transaction ID: {transaction_id}")
+
+    consensus_timestamp = getattr(record, 'consensus_timestamp', None)
+    if consensus_timestamp:
+        lines.append(f"  Consensus Timestamp: {consensus_timestamp}")
+
+    transaction_fee = getattr(record, 'transaction_fee', None)
+    if transaction_fee:
+        lines.append(f"  Transaction Fee: {transaction_fee} tinybar")
+
+    transaction_hash = getattr(record, 'transaction_hash', None)
+    if transaction_hash:
+        lines.append(f"  Transaction Hash: {transaction_hash.hex()}")
+
+    receipt = getattr(record, 'receipt', None)
+    if receipt:
+        lines.append(f"  Receipt Status: {ResponseCode(receipt.status).name}")
+
+    transfers = getattr(record, 'transfers', None)
+    if transfers:
+        lines.append(f"  Transfers:")
+        for account_id, amount_in_tinybar in transfers.items():
+            amount_hbar = amount_in_tinybar / 100_000_000  # Convert tinybar to hbar
+            lines.append(f"    {account_id}: {amount_hbar:+.8f} ℏ")
+
+    lines.append("-" * 80)
+    return "\n".join(lines)
+
+
+def format_account_records(records):
+    """Format account records for readable display"""
+    if not records:
+        return "No records found"
+
+    output = ["=" * 80]
+
+    for idx, record in enumerate(records, 1):
+        output.append(format_single_record(record, idx))
+
+    output.append("=" * 80)
+    return "\n".join(output)
+
+
+def query_account_records():
+    """
+    Demonstrates the account record query functionality by:
+    1. Setting up client with operator account
+    2. Creating a new account and setting it as the operator
+    3. Querying account records and displaying basic information
+    4. Performing a transfer transaction
+    5. Querying account records again to see updated transaction history
+    """
+    client = setup_client()
+
+    # Store the original operator account ID before creating new account
+    original_operator_id = client.operator_account_id
+
+    # Create a new account
+    account_id, account_private_key = create_account(client)
+
+    records_before = AccountRecordsQuery().set_account_id(account_id).execute(client)
+
+    print(f"\nAccount {account_id} has {len(records_before)} transaction records")
+    print("\nTransaction records (before transfer):")
+    print(format_account_records(records_before))
+
+    # Set the newly created account as the operator for executing the transfer
+    client.set_operator(account_id, account_private_key)
+
+    # Perform a transfer transaction from the newly created account to the original operator
+    print(f"\nTransferring 1 ℏ from {account_id} to {original_operator_id}...")
+    receipt = (
+        TransferTransaction()
+        .add_hbar_transfer(account_id, -Hbar(1).to_tinybars())
+        .add_hbar_transfer(original_operator_id, Hbar(1).to_tinybars())
+        .execute(client)
+    )
+
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"Transfer failed with status: {ResponseCode(receipt.status).name}")
+        sys.exit(1)
+
+    records_after = AccountRecordsQuery().set_account_id(account_id).execute(client)
+
+    print(f"\nAccount {account_id} has {len(records_after)} transaction record(s)")
+    print("\nTransaction records (after transfer):")
+    print(format_account_records(records_after))
+
+
+if __name__ == "__main__":
+    query_account_records()

src/hiero_sdk_python/__init__.py

@@ -10,6 +10,7 @@
 from .account.account_delete_transaction import AccountDeleteTransaction
 from .account.account_allowance_approve_transaction import AccountAllowanceApproveTransaction
 from .account.account_allowance_delete_transaction import AccountAllowanceDeleteTransaction
+from .account.account_records_query import AccountRecordsQuery
 
 # Crypto
 from .crypto.private_key import PrivateKey
@@ -149,6 +150,7 @@
     "AccountDeleteTransaction",
     "AccountAllowanceApproveTransaction",
     "AccountAllowanceDeleteTransaction",
+    "AccountRecordsQuery",
 
     # Crypto
     "PrivateKey",

src/hiero_sdk_python/account/account_records_query.py

@@ -0,0 +1,144 @@
+"""
+Query to get records about a specific account on the network.
+"""
+
+import traceback
+from typing import List, Optional
+
+from hiero_sdk_python.account.account_id import AccountId
+from hiero_sdk_python.channels import _Channel
+from hiero_sdk_python.client.client import Client
+from hiero_sdk_python.executable import _Method
+from hiero_sdk_python.hapi.services import crypto_get_account_records_pb2, query_pb2, response_pb2
+from hiero_sdk_python.hapi.services.crypto_get_account_records_pb2 import (
+    CryptoGetAccountRecordsResponse,
+)
+from hiero_sdk_python.query.query import Query
+from hiero_sdk_python.transaction.transaction_record import TransactionRecord
+
+
+class AccountRecordsQuery(Query):
+    """
+    A query to retrieve records about a specific Account.
+
+    This class constructs and executes a query to retrieve records of all transactions
+    against the specified account within the last 25 hours.
+    """
+
+    def __init__(self, account_id: Optional[AccountId] = None):
+        """
+        Initializes a new AccountRecordsQuery instance with an optional account_id.
+
+        Args:
+            account_id (Optional[AccountId]): The ID of the account to query.
+        """
+        super().__init__()
+        self.account_id: Optional[AccountId] = account_id
+
+    def set_account_id(self, account_id: Optional[AccountId]) -> "AccountRecordsQuery":
+        """
+        Sets the ID of the account to query.
+
+        Args:
+            account_id (Optional[AccountId]): The ID of the account.
+
+        Returns:
+            AccountRecordsQuery: Returns self for method chaining.
+        """
+        self.account_id = account_id
+        return self
+
+    def _make_request(self) -> query_pb2.Query:
+        """
+        Constructs the protobuf request for the query.
+
+        Builds a CryptoGetAccountRecordsQuery protobuf message with the
+        appropriate header and account ID.
+
+        Returns:
+            Query: The protobuf query message.
+
+        Raises:
+            ValueError: If the account ID is not set.
+            Exception: If any other error occurs during request construction.
+        """
+        try:
+            if not self.account_id:
+                raise ValueError("Account ID must be set before making the request.")
+
+            query_header = self._make_request_header()
+
+            crypto_records_query = crypto_get_account_records_pb2.CryptoGetAccountRecordsQuery()
+            crypto_records_query.header.CopyFrom(query_header)
+            crypto_records_query.accountID.CopyFrom(self.account_id._to_proto())
+
+            query = query_pb2.Query()
+            query.cryptoGetAccountRecords.CopyFrom(crypto_records_query)
+
+            return query
+        except Exception as e:
+            print(f"Exception in _make_request: {e}")
+            traceback.print_exc()
+            raise
+
+    def _get_method(self, channel: _Channel) -> _Method:
+        """
+        Returns the appropriate gRPC method for the account records query.
+
+        Implements the abstract method from Query to provide the specific
+        gRPC method for getting account records.
+
+        Args:
+            channel (_Channel): The channel containing service stubs
+
+        Returns:
+            _Method: The method wrapper containing the query function
+        """
+        return _Method(transaction_func=None, query_func=channel.crypto.getAccountRecords)
+
+    def execute(self, client: Client) -> List[TransactionRecord]:
+        """
+        Executes the account records query.
+
+        Sends the query to the Hedera network and processes the response
+        to return a list of TransactionRecord objects.
+
+        This function delegates the core logic to `_execute()`, and may propagate
+        exceptions raised by it.
+
+        Args:
+            client (Client): The client instance to use for execution
+
+        Returns:
+            List[TransactionRecord]: The account records from the network
+
+        Raises:
+            PrecheckError: If the query fails with a non-retryable error
+            MaxAttemptsError: If the query fails after the maximum number of attempts
+            ReceiptStatusError: If the query fails with a receipt status error
+        """
+        self._before_execute(client)
+        response = self._execute(client)
+
+        records = []
+        for record in response.cryptoGetAccountRecords.records:
+            records.append(TransactionRecord._from_proto(record))
+
+        return records
+
+    def _get_query_response(
+        self, response: response_pb2.Response
+    ) -> CryptoGetAccountRecordsResponse:
+        """
+        Extracts the account records response from the full response.
+
+        Implements the abstract method from Query to extract the
+        specific account records response object.
+
+        Args:
+            response: The full response from the network
+
+        Returns:
+            The crypto get account records response object
+        """
+        return response.cryptoGetAccountRecords