Merge branch 'hiero-ledger:main' into main

Author: MonaaEid

.github/dependabot.yml

@@ -0,0 +1,27 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 10
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 10
+  - package-ecosystem: "pip-compile"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 10
+  - package-ecosystem: "pipenv"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 10

.github/workflows/test.yml

@@ -7,9 +7,19 @@ on:
   workflow_dispatch:
   pull_request:
 
+permissions:
+  contents: read
+  actions: write
+
 jobs:
   build-and-test:
     runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
     steps:
       - name: Harden the runner (Audit all outbound calls)
         uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
@@ -19,15 +29,18 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
       - name: Install uv
         uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4.2.0
 
       - name: Install setuptools wheel
         run: pip install --upgrade pip setuptools wheel
 
-      - name: Setup Python
-        run: uv python install
-
       - name: Install dependencies
         run: uv sync --all-extras --dev
 
@@ -36,7 +49,7 @@ jobs:
 
       - name: Prepare Hiero Solo
         id: solo
-        uses: hiero-ledger/hiero-solo-action@97b1a5dfff3a18ae92ffb4c27f5ada95906f66bb # v0.12
+        uses: hiero-ledger/hiero-solo-action@b76850c1ac44466900f8e7412b309c3aa0f539c1 # v0.14
         with:
           installMirrorNode: true
 

CHANGELOG.md

@@ -19,7 +19,7 @@ Maintainers are assigned the following scopes in this repository:
 | Name           | GitHub ID     | Scope | LFID | Discord ID     | Email | Company Affiliation |
 | -------------- | ------------- | ----- | ---- | -------------- | ----- | ------------------- |
 | Nadine Loepfe  | nadineloepfe  |       |      | nadine_90669   |       | Hashgraph           |
-| Hendrik Ebbers | hendrikebbers |       |      | hendrik.ebbers |       | Hashgraph           |
+| Sophie Bulloch | exploreriii   |       |      | explorer3      |       |                     |
 | Richard Bair   | rbair23       |       |      | rbair          |       | Hashgraph           |
 
 

CONTRIBUTING.md

@@ -154,7 +154,26 @@ Topic deletion successful.
 
 ## Contributing
 
-We appreciate your interest in improving the Hiero Python SDK! Please see CONTRIBUTING.md for details about our contribution process, including bug reports, feature requests, and code contributions.
+We appreciate your interest in improving the Hiero Python SDK!
+Interested in helping out? We'd love for you to contribute!
+
+Before you start, it's **essential** that you carefully read our main contribution guide: **[CONTRIBUTING.md](./CONTRIBUTING.md)**. This document is your roadmap to making a successful contribution.
+
+Following the steps in this guide is the best way to ensure your pull request (PR) can be merged smoothly. It covers crucial requirements, including:
+
+* How to get your commits **verified** (which is mandatory for merging).
+* The correct way to update the **changelog** with your changes.
+* The full step-by-step workflow for submitting code.
+
+Our guide also explains how you can contribute in other ways, like submitting **bug reports** and proposing new **feature requests**.
+
+### Links
+- [Hiero Python SDK Discord](https://discord.com/channels/905194001349627914/1336494517544681563)
+- [Hedera Developer Support Discord](https://discord.com/channels/373889138199494658/1106578684573388900).
+- [Hiero Blog](https://hiero.org/blog/)
+- [LFDT Youtube Channel](https://www.youtube.com/@lfdecentralizedtrust/videos)
+- [Hiero LFTD Calendar](https://zoom-lfx.platform.linuxfoundation.org/meetings/hiero?view=week)
+
 
 ## License
 

MAINTAINERS.md

@@ -0,0 +1,91 @@
+## Resolving Changelog Conflicts
+
+A common issue you may face when submitting a pull request (PR) is a "changelog conflict." This happens when your PR modifies the `CHANGELOG.md` file, but another PR that also modified it was merged before yours.
+
+### Common Causes
+
+There are two main reasons this happens:
+
+1.  **SDK Version Bump (Scenario A):** The SDK launched a new version (e.g., `0.1.5` became `0.1.6`) while your PR was open. Your changelog entry was under the `[Unreleased]` section, but that section is now part of the `[0.1.6]` release. Your entry needs to be moved to the *new* `[Unreleased]` section.
+2.  **Same Section Conflict (Scenario B):** Another PR was merged that added its own changelog entry to the *exact same* `[Unreleased]` section as yours (e.g., you both added a line under `Changed`). The file now has a conflict because Git doesn't know which line should come first.
+
+### How to Resolve the Conflict
+
+To fix this, you need to sync your branch with the main project (known as `upstream`) and then fix the conflict. This is done using a `rebase`.
+
+**1. Sync Your Local `main` Branch**
+
+First, ensure your local `main` branch has the latest changes from the `hiero-ledger` project.
+
+```bash
+# Switch to your main branch
+git checkout main
+
+# Fetch all the latest changes from the upstream (original) repository
+git fetch upstream
+
+# Pull those changes into your local main branch
+git pull upstream main
+```
+
+## 2. Changelog Conflict Examples
+### Example 1: The SDK Version has upgraded
+If the SDK version has upgraded, you'll need to move your changelog entry to the new unreleased section.
+
+For example:
+before
+
+`UNRELEASED (version 0.1.6)`
+` Changed`
+
+- TransferTransaction refactored to use TokenTransfer and HbarTransfer classes instead of dictionaries
+- Added checksum validation for TokenId
+- Refactor examples/token_cancel_airdrop <-- your entry
+
+Version 0.1.6 is now released but your PR is not yet merged so we need to move your changelog entry to the new UNRELEASED SECTION.
+
+after:
+
+`[Unreleased]`
+
+`Changed`
+- Refactor examples/token_cancel_airdrop <-- CORRECT
+
+ `[0.1.6] - 2025-10-21`
+` Changed`
+
+- TransferTransaction refactored to use TokenTransfer and HbarTransfer classes instead of dictionaries
+- Added checksum validation for TokenId
+
+### Example 2: The SDK has had a minor update
+In this case, a new PR is merged in the same release that has a changelog entry written in the same section as you.
+
+For example:
+
+Alice's Pull Request:
+` UNRELEASED`
+` Changed`
+
+- TransferTransaction refactored to use TokenTransfer and HbarTransfer classes instead of dictionaries
+- Added checksum validation for TokenId <-- ALICE'S Change
+
+Bob's Pull Request:
+` UNRELEASED`
+` Changed`
+
+- TransferTransaction refactored to use TokenTransfer and HbarTransfer classes instead of dictionaries
+- Refactor examples/token_cancel_airdrop <-- BOB's change
+
+They are in conflict.
+
+Alice's change was merged before Bob, so Bob needs update his changelog to be:
+Bob's Pull Request:
+` UNRELEASED`
+` Changed`
+
+- TransferTransaction refactored to use TokenTransfer and HbarTransfer classes instead of dictionaries
+- Added checksum validation for TokenId <-- ALICE'S Change
+- Refactor examples/token_cancel_airdrop <-- BOB's change
+Which has no conflict as they are no longer clashing.
+
+Congratulations!

README.md

@@ -0,0 +1,182 @@
+# Changelog Entry Guide
+
+This document explains how to create proper changelog entries for the Hiero Python SDK.
+
+## Table of Contents
+
+- [Why Changelog Entries Matter](#why-changelog-entries-matter)
+- [Required Format](#required-format)
+- [Changelog Sections](#changelog-sections)
+- [Step-by-Step Guide](#step-by-step-guide)
+- [Examples](#examples)
+
+## Why Changelog Entries Matter
+
+**Every pull request MUST include a changelog entry.**
+
+The changelog is the first place users look to understand what's new, what's fixed, and what's changed in each release. A well-written changelog entry helps users quickly understand the impact of your contribution.
+
+## Required Format
+
+Your changelog entry must:
+
+1. **Link to the issue** - Include a reference to the issue your PR solves
+2. **Use clear, descriptive language** - Be concise but informative
+3. **Be 1-2 sentences** - Keep it brief and focused
+4. **Go under [Unreleased]** - Add your entry at the top of the file, in the appropriate section under `[Unreleased]`
+5. **Use proper markdown** - Follow the bullet point format
+
+## Changelog Sections
+
+The `[Unreleased]` section is divided into three categories. Choose the one that best fits your change:
+
+### Added
+For new features, functionality, or capabilities added to the SDK.
+
+**Examples:**
+- New API methods
+- New query types
+- New transaction types
+- New utility functions
+
+### Changed
+For modifications to existing functionality that change behavior but aren't bug fixes.
+
+**Examples:**
+- Refactored code structure
+- Updated dependencies
+- Modified function signatures
+- Performance improvements
+- Updated documentation
+
+### Fixed
+For bug fixes that resolve incorrect behavior.
+
+**Examples:**
+- Resolved errors or exceptions
+- Corrected incorrect return values
+- Fixed edge cases
+- Patched security vulnerabilities
+
+## Step-by-Step Guide
+
+1. **Open `CHANGELOG.md`** in the repository root
+
+2. **Find the `[Unreleased]` section** at the top of the file
+
+3. **Choose the appropriate subsection** (Added, Changed, or Fixed)
+
+4. **Add your entry as a new bullet point** at the top of that subsection
+
+5. **Format your entry** as:
+   ```markdown
+   - Brief description of your change (#IssueNumber)
+   ```
+
+6. **Ensure it's descriptive** - Readers should understand what changed and why it matters
+
+## Examples
+
+### ✅ Good Examples
+
+#### Good: Clear and Descriptive
+```markdown
+## [Unreleased]
+
+### Changed
+- Refactor `query_balance.py` into modular, reusable functions with `setup_client()`, `create_account()`, `get_balance()`, `transfer_hbars()`, and `main()` for improved readability, maintainability, and error handling (#123)
+```
+
+**Why this is good:**
+- Links to the issue (#123)
+- Describes what was refactored
+- Lists the specific functions created
+- Explains the benefits (readability, maintainability, error handling)
+- Placed correctly under [Unreleased] → Changed
+
+#### Good: Bug Fix
+```markdown
+## [Unreleased]
+
+### Fixed
+- Resolve `TypeError` in `transfer_transaction.py` when passing `None` as memo parameter (#456)
+```
+
+**Why this is good:**
+- Links to the issue
+- Specifies the error type
+- Identifies the affected file
+- Describes the problematic scenario
+
+#### Good: New Feature
+```markdown
+## [Unreleased]
+
+### Added
+- Add support for HIP-### token association transactions with automatic fee calculation (#789)
+```
+
+**Why this is good:**
+- Links to the issue
+- Clearly states what was added
+- Mentions a key feature (automatic fee calculation)
+
+### ❌ Bad Examples
+
+#### Bad: Not Informative
+```markdown
+## [Unreleased]
+
+### Changed
+- Refactor `query_balance.py`
+```
+
+**Why this is bad:**
+- No issue link
+- Doesn't explain what was refactored or why
+- Too vague - users can't understand the impact
+
+#### Bad: Wrong Placement (Version Number Instead of Unreleased)
+```markdown
+## [0.1.6] - 2025-10-21
+
+### Changed
+- Refactor `query_balance.py` into modular, reusable functions (#123)
+```
+
+**Why this is bad:**
+- Added under a released version instead of [Unreleased]
+- Version numbers and dates are added by maintainers during release
+- Your entry should always go under [Unreleased]
+
+#### Bad: No Issue Reference
+```markdown
+## [Unreleased]
+
+### Fixed
+- Fix bug in transaction signing
+```
+
+**Why this is bad:**
+- No issue link
+- Too vague about what bug was fixed
+- Doesn't help users understand if it affects them
+
+## Common Mistakes to Avoid
+
+1. **Don't add entries to released versions** - Always use `[Unreleased]`
+2. **Don't forget the issue number** - Every entry needs a link like `(#123)`
+3. **Don't write paragraphs** - Keep it to 1-2 sentences
+4. **Don't be too technical** - Write for SDK users, not just developers
+5. **Don't skip the changelog** - It's required for all PRs
+
+## Need Help?
+
+If you're unsure about your changelog entry:
+
+1. Look at recent entries in `CHANGELOG.md` for inspiration
+2. Ask in your pull request for feedback
+3. Review this guide again
+4. Check other documentation files in `docs/sdk_developers/`
+
+Remember: A good changelog entry helps thousands of developers understand your contribution!