[Good First Issue]: Add top level comment to the src/sdk/examples/AccountAllowanceExample.cpp #1196
Description
🆕🐥 First-Time Friendly
This issue is especially welcoming for people who are new to contributing to the Hiero C++ SDK.
We know that opening your first pull request can feel like a big step.
Issues labeled Good First Issue are designed to make that experience easier, clearer, and more comfortable.
No prior knowledge of Hiero, Hedera, or distributed ledger technology is required.
Just a basic familiarity with C++ and Git is more than enough to get started.
👾 Description of the Issue
We have an example file at src/sdk/examples/AccountAllowanceExample.cpp
We already have some explanation what this example does in backslashes //
e.g.:
// Get a client for the Hiero testnet, and set the operator account ID and key such that all generated transactions
// will be paid for by this account and be signed by this key.But we lack a top level explanation, such as the one in src/sdk/examples/AccountAliasExample.cpp, which is:
/**
* This example demonstrates Hiero's alias-based automatic account creation.
*
* An alias is an AccountId derived from a public key.
* It can be used in transactions before the account exists on-ledger.
*
* Essential steps:
* - Load an operator account to sign and pay for transactions.
* - Generate a key pair locally.
* - Derive an alias AccountId from the public key.
* - Transfer HBAR to the alias, which creates the account on-ledger.
*
* Optional steps (for illustration purposes):
* - Query the account balance.
* - Query account info to obtain the permanent numeric AccountId.
*
* No explicit CreateAccount transaction is used.
* Funding the alias both creates and initializes the account, which can then be referenced by
* either its alias (public key) or numeric AccountId.
*/💡 Proposed Solution
We can create a top level explanation of src/sdk/examples/AccountAllowanceExample.cpp
👩💻 Implementation Steps (End-to-End)
To do this, ensure you follow the exact formatting style which is
/**
* text
* text
*/
Ensure you are exact!
Follow this structure:
- what does the example demonstrate at a high level?
- any key definitions
- outline the key steps taken in the example
- outline any steps additionally taken in the example to provide clarity, but perhaps not essential for the transaction
- any important notes
but don't make it too long.
You should add this above line 2 and change nothing else in the file.
Some information to help you:
This example demonstrates how Hbar allowances function by showing how one account (Alice) can authorize another account (Bob) to spend a limited amount of her Hbar without needing her signature on each transaction. The program creates three accounts (Alice, Bob, and Charlie), funds them, and has Alice grant Bob an allowance of 2 Hbar. Bob successfully transfers 1 Hbar from Alice to Charlie using this allowance, then fails when attempting to exceed the remaining limit, illustrating enforcement. Alice then increases the allowance, enabling Bob to complete another transfer, after which the allowance is revoked by setting it to zero. Throughout, balances are checked and transactions are handled to demonstrate approval, usage, adjustment, and deletion of allowances, followed by cleanup through account deletion.
Please don't copy this comment exactly, but double check the contents of the explanation and improve it:
/**
* This example demonstrates Hiero's Hbar allowance mechanism.
*
* An allowance allows one account (the owner) to approve another account (the spender)
* to transfer a limited amount of Hbar on its behalf without requiring the owner's signature
* for each transaction.
*
* Essential steps:
* - Load an operator account to pay for transactions.
* - Generate accounts for Alice (owner), Bob (spender), and Charlie (receiver).
* - Alice approves Bob to spend a fixed amount of her Hbar.
* - Bob performs an approved transfer using the allowance.
* Optional steps (for illustration or closure purposes):
* - Attempt a transfer that exceeds the allowance to demonstrate enforcement.
* - Update the allowance and perform another transfer.
* - Revoke the allowance by setting it to zero.
* - Delete the created accounts after completion.
*
* No owner signature is required for approved transfers.
* The spender signs and pays for transactions executed using the allowance.
*/✅ Acceptance Criteria
To merge a pull request for this issue:
- Scope: Changes are limited to this issue
- Behavior: No SDK behavior or public API changes
- Tests: Existing CI checks pass
- Review: All code review feedback addressed
📋 Step-by-Step Contribution Guide
To help your first contribution go as smoothly as possible, we recommend following these steps:
- Comment
/assignto request the issue - Wait for assignment
- Fork the repository and create a branch
- Set up the project by following the instructions in
README.md - Make the requested changes
- Sign each commit using
-s -S - Push your branch and open a pull request
Read Workflow Guide for step-by-step workflow guidance.
Read README.md for setup instructions.
❗ Pull requests cannot be merged without S and s signed commits.
See the Signing Guide.
🤔 Additional Information
If you need help, reach out to the @hiero-ledger/hiero-sdk-good-first-issue-support team.
You can also join our community on Discord:
Hiero-SDK-C++
Maintainers are happy to help first-time contributors succeed!