test: update docs and few nits

Signed-off-by: dosi <dosi.kolev@limechain.tech>

Author: Dosik13

sdk/account_id.go

@@ -340,17 +340,9 @@ const (
 	EvmAddress
 )
 
-// _MirrorNodePathID renders the AccountID in a form /accounts/{idOrAliasOrEvmAddress} accepts: an
-// EVM-address alias as bare hex, a public-key alias as base32 (RFC 4648, no padding) of the
-// serialized key -- what the mirror node itself reports -- and anything else as shard.realm.num.
-//
-// The numeric form wins whenever it is available, because it is canonical and because an alias ID
-// keeps its alias field after PopulateAccount fills in the account number. 0.0.0 is not a real
-// account, so a zero Account means only the alias can identify this ID.
-//
-// Note that the alias forms carry no shard.realm prefix; the mirror node resolves an alias without
-// one. A contract is addressed through the same numeric form, so no separate contract variant is
-// needed.
+// _MirrorNodePathID renders the AccountID as the mirror node accepts it: shard.realm.num when a
+// number is set, otherwise an EVM-address alias as bare hex or a public key alias as unpadded
+// base32. Alias forms carry no shard.realm prefix.
 func (id AccountID) _MirrorNodePathID() string {
 	if id.Account != 0 {
 		return fmt.Sprintf("%d.%d.%d", id.Shard, id.Realm, id.Account)

sdk/mirror_node_account_balance_query.go

@@ -84,8 +84,8 @@ func (q *MirrorNodeAccountBalanceQuery) resolveEndpoint(client *Client) (string,
 	return q.buildURL(mirrorUrl), nil
 }
 
-// resolveAttempts picks the retry budget: query, then client, then the SDK default. Not a single
-// attempt: Client.GetMaxAttempts reports -1 when unset and 5xx responses must still be retried.
+// resolveAttempts picks the retry budget: query setting first,
+// client default second, the SDK default as the final fallback.
 func (q *MirrorNodeAccountBalanceQuery) resolveAttempts(client *Client) uint64 {
 	if q.maxAttempts > 0 {
 		return q.maxAttempts
@@ -118,8 +118,7 @@ func (q *MirrorNodeAccountBalanceQuery) validateNetworkOnIDs(client *Client) err
 	return nil
 }
 
-// fetchAccountBalances GETs the balances endpoint; the shared core retries 5xx/429 and transport
-// failures, and returns a 4xx as-is.
+// fetchAccountBalances GETs the balances endpoint through the shared retry core.
 func fetchAccountBalances(client *Client, endpoint string, attempts uint64) ([]byte, error) {
 	resp, err := mirrorNodeGetWithRetry(client, endpoint, attempts, mirrorNodeDefaultTimeout)
 	if err != nil {
@@ -151,6 +150,5 @@ type accountBalancesResponseJSON struct {
 
 type accountBalanceJSON struct {
 	Account string `json:"account"`
-	// Tinybars; int64 holds the whole hbar supply exactly.
-	Balance int64 `json:"balance"`
+	Balance int64  `json:"balance"`
 }

sdk/mirror_node_account_balance_query_unit_test.go

@@ -48,7 +48,6 @@ func TestUnitMirrorNodeAccountBalanceQueryDefaults(t *testing.T) {
 	assert.Zero(t, query.GetMaxAttempts())
 }
 
-// AC 1: a valid account ID returns the hbar balance the mirror node reports.
 func TestUnitMirrorNodeAccountBalanceQueryReturnsHbarBalance(t *testing.T) {
 	var gotAccountID string
 	client := newMockMirrorClient(t, "balance.example.com:443", balancesHandler(t, &gotAccountID,
@@ -79,7 +78,6 @@ func TestUnitMirrorNodeAccountBalanceQueryLargeBalanceIsLossless(t *testing.T) {
 	assert.Equal(t, tinybars, balance.Hbars.AsTinybar())
 }
 
-// AC 2: an EVM address is sent as bare hex, which is what the mirror node resolves.
 func TestUnitMirrorNodeAccountBalanceQueryResolvesEvmAddress(t *testing.T) {
 	var gotAccountID string
 	client := newMockMirrorClient(t, "evm.example.com:443", balancesHandler(t, &gotAccountID,
@@ -97,7 +95,6 @@ func TestUnitMirrorNodeAccountBalanceQueryResolvesEvmAddress(t *testing.T) {
 	assert.Equal(t, "742d35cc6634c0532925a3b844bc454e4438f44e", gotAccountID)
 }
 
-// AC 3: a public key alias is sent base32-encoded, the form the mirror node reports and accepts.
 func TestUnitMirrorNodeAccountBalanceQueryResolvesPublicKeyAlias(t *testing.T) {
 	var gotAccountID string
 	client := newMockMirrorClient(t, "alias.example.com:443", balancesHandler(t, &gotAccountID,
@@ -119,7 +116,6 @@ func TestUnitMirrorNodeAccountBalanceQueryResolvesPublicKeyAlias(t *testing.T) {
 	assert.Equal(t, gotAccountID, url.QueryEscape(gotAccountID), "alias must need no escaping")
 }
 
-// AC 4: a contract is addressed through the same account.id parameter.
 func TestUnitMirrorNodeAccountBalanceQueryResolvesContractID(t *testing.T) {
 	var gotAccountID string
 	client := newMockMirrorClient(t, "contract.example.com:443", balancesHandler(t, &gotAccountID,
@@ -135,7 +131,6 @@ func TestUnitMirrorNodeAccountBalanceQueryResolvesContractID(t *testing.T) {
 	assert.Equal(t, "0.0.98765", gotAccountID)
 }
 
-// AC 5: an unknown account yields an empty list, which is a zero balance and not an error.
 func TestUnitMirrorNodeAccountBalanceQueryNonExistentAccountIsZero(t *testing.T) {
 	var gotAccountID string
 	client := newMockMirrorClient(t, "missing.example.com:443", balancesHandler(t, &gotAccountID,
@@ -149,7 +144,6 @@ func TestUnitMirrorNodeAccountBalanceQueryNonExistentAccountIsZero(t *testing.T)
 	assert.Equal(t, HbarFromTinybar(0), balance.Hbars)
 }
 
-// AC 6: an unset account ID fails before any network call.
 func TestUnitMirrorNodeAccountBalanceQueryNoAccountIDErrorsBeforeRequest(t *testing.T) {
 	var called atomic.Bool
 	client := newMockMirrorClient(t, "unused.example.com:443", func(w http.ResponseWriter, r *http.Request) {
@@ -173,7 +167,6 @@ func TestUnitMirrorNodeAccountBalanceQueryNilClientErrors(t *testing.T) {
 	require.ErrorIs(t, err, errNoClientProvided)
 }
 
-// AC 7: a transient 503 is retried and the following success is returned.
 func TestUnitMirrorNodeAccountBalanceQueryRetriesTransientError(t *testing.T) {
 	var attempts atomic.Int32
 	client := newMockMirrorClient(t, "retry.example.com:443", func(w http.ResponseWriter, r *http.Request) {
@@ -289,8 +282,7 @@ func TestUnitMirrorNodeAccountBalanceQueryBadChecksumErrorsBeforeRequest(t *test
 	assert.False(t, called.Load(), "a checksum mismatch must not reach the network")
 }
 
-// resolveAttempts: query setting, then client, then SDK default. The default must not be a single
-// attempt -- this query has to retry 5xx, and Client.GetMaxAttempts reports -1 when unset.
+// The fallback must not be a single attempt; 5xx responses still have to be retried.
 func TestUnitMirrorNodeAccountBalanceQueryResolveAttempts(t *testing.T) {
 	t.Parallel()
 

sdk/mirror_node_rest_helpers.go

@@ -25,12 +25,8 @@ const (
 )
 
 // mirrorNodeRestBaseURL returns the client's mirror node REST API base URL, erroring when no
-// mirror network is configured.
-//
-// The canonical value comes from _MirrorNode.getBaseRestUrl, which maps a localhost mirror network
-// to port 38081. Endpoints that a local node serves elsewhere override it afterwards: the fee
-// estimate and registered-node endpoints on 8084, the contract-call endpoint on 8545 (the JSON-RPC
-// relay). Callers that need no override use the returned URL as-is.
+// mirror network is configured. A caller whose endpoint is served on a different port against a
+// local node overrides it afterwards.
 func mirrorNodeRestBaseURL(client *Client) (string, error) {
 	if client == nil {
 		return "", errNoClientProvided
@@ -43,8 +39,8 @@ func mirrorNodeRestBaseURL(client *Client) (string, error) {
 	return client.GetMirrorRestApiBaseUrl()
 }
 
-// mirrorNodeValidateURL rejects a URL no HTTP request could ever satisfy, so the retry loop does
-// not spend its whole budget and backoff on a permanent failure.
+// mirrorNodeValidateURL rejects a URL no HTTP request could satisfy, so the retry loop does not
+// spend its budget on a permanent failure.
 func mirrorNodeValidateURL(rawURL string) error {
 	parsed, err := url.Parse(rawURL)
 	if err != nil {
@@ -61,12 +57,9 @@ func mirrorNodeValidateURL(rawURL string) error {
 }
 
 // mirrorNodeRequestWithRetry runs send with exponential backoff, retrying transport failures and
-// 5xx/429; a 4xx is the intended result of the call and is not retried. send runs once per attempt
-// so it can rebuild the request body.
-//
-// The final attempt is returned raw so callers can format their own error: a 200 response, a
-// non-200 response with a nil error, or a nil response and the transport error. The caller must
-// close a non-nil Body (mirrorNodeReadBody does). A timeout of 0 disables the per-request timeout.
+// 5xx/429; a 4xx is the intended result and is not retried. The final attempt is returned raw so
+// callers can format their own error, and the caller must close a non-nil Body. A timeout of 0
+// disables the per-request timeout.
 func mirrorNodeRequestWithRetry(client *Client, maxAttempts uint64, timeout time.Duration, send func(*http.Client) (*http.Response, error)) (*http.Response, error) {
 	if maxAttempts == 0 {
 		return nil, errors.New("maxAttempts must be at least 1")
@@ -180,9 +173,6 @@ func mirrorNodeReadBody(resp *http.Response) ([]byte, error) {
 // mirrorNodeWalkPages walks a paginated endpoint from pageURL, passing each fetched body to
 // handlePage, which returns the raw links.next. Stops when next is absent, or at maxPages so a
 // misbehaving mirror node cannot loop forever.
-//
-// A links.next is a root-relative path, so it is resolved against pageURL itself rather than
-// against a separately supplied base -- one argument cannot then disagree with the other.
 func mirrorNodeWalkPages(
 	pageURL string,
 	maxPages int,