feat: Implement Paginated get_transaction_history Function in Budget Contract #45

[martinvibes]

🚀 Implement Paginated get_transaction_history in Budget Contract

✅ Overview

This PR introduces the get_transaction_history function in the Budget contract to enable paginated retrieval of transactions. The goal is to enhance transparency and ensure scalable access to financial history with optimized gas usage.

closes #45

🛠️ Changes Made

• Added get_transaction_history(page: u64, page_size: u64) to the Budget contract.
• Pagination logic includes:
  • page > 0 → returns ERROR_INVALID_PAGE if invalid.
  • 1 <= page_size <= 100 → returns ERROR_INVALID_PAGE_SIZE otherwise.
  • Throws ERROR_INVALID_PAGE if the page exceeds the transaction count.
• Returns a Result<Array<Transaction>, felt252> with the selected page of transactions.
• Integrated into the IBudget interface with full NatSpec documentation.
• Optimized storage reads and iteration to minimize gas usage.

---

🧪 Unit Tests

• ✅ Retrieval of multiple pages of transactions.
• ✅ Handling of an empty transaction list.
• ✅ Proper error handling for:
  • page == 0 → ERROR_INVALID_PAGE
  • page_size == 0 or > 100 → ERROR_INVALID_PAGE_SIZE
  • Page exceeding available transactions → ERROR_INVALID_PAGE

---

⛽ Gas & Performance

• Benchmarked gas costs for page sizes of 10, 25, 50, and 100.
• Confirmed efficient performance across common usage scenarios.

---

📘 Documentation

• Fully documented the function in IBudget using NatSpec.
• Includes input validation, return values, and potential error conditions.
• Optional debug events considered but not included in this PR.

---

✅ Acceptance Criteria

• Returns paginated Array<Transaction> correctly.
• Validates and handles all edge cases and input errors.
• Unit tests cover various page sizes and invalid scenarios.
• Gas usage remains within acceptable bounds.
• Function is integrated and documented in the interface.

---

This PR enables efficient and scalable access to transaction history while aligning with the Budget contract’s core mission of transparency and financial accountability.

Looking forward to your review! 🙌

[martinvibes]

@anonfedora kindly review sir :)

[martinvibes]

closes #45

[martinvibes]

@anonfedora i have fixed ci issues by runnuing scarb fmt