feat: Add for_network() method to configure a custom network

[manishdait]

Description:
This PR remove unintended tls port converstion for the non-tls:port and tls:port for non self-hosted network. Also introduce the for_network() method to create network using Node object

Changes:

• Added Client.for_network to ensure the internal Network instance defaults to a non-hosted label.
• Verified that port conversion logic is now only triggered when the network is explicitly set to mainnet, testnet, or previewnet.

Related issue(s):

Fixes #2181

Notes for reviewer:

Checklist

• Documented (Code comments, README, etc.)
• Tested (unit, integration, etc.)

[codecov]

Codecov Report

❌ Patch coverage is 95.00000% with 3 lines in your changes missing coverage. Please review.

@@            Coverage Diff             @@
##             main    #2182      +/-   ##
==========================================
- Coverage   94.01%   93.99%   -0.02%     
==========================================
  Files         163      163              
  Lines       10403    10442      +39     
==========================================
+ Hits         9780     9815      +35     
- Misses        623      627       +4     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity

Metric	Results
Complexity	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Client no longer stores or initializes mirror gRPC channel/stub; mirror access and lifecycle are delegated to Network. Added Client.for_network(network_map, network_name="localhost") which validates shard/realm and constructs a Network from node map. Network defaults to "localhost", adds mirror lifecycle helpers and conditional TLS/port handling.

Changes

Client/Network mirror & for_network

Layer / File(s)	Summary
Data Shape / Inputs src/hiero_sdk_python/client/client.py, src/hiero_sdk_python/client/network.py	Client.for_network(network_map, network_name) added. Network.__init__ accepts `network: str
Core Implementation src/hiero_sdk_python/client/network.py	Added mirror_address property with validation and change-triggered reset; added get_mirror_stub() that lazily creates/caches a ConsensusServiceStub choosing secure vs insecure gRPC channel based on mirror port; added _close() to safely close/clear mirror channel/stub; node TLS application made conditional on transport-security.
Client Behavior / Wiring src/hiero_sdk_python/client/client.py	Removed client-owned mirror channel/stub and _init_mirror_stub(); added mirror_stub and mirror_channel properties that delegate to Network (get_mirror_stub() / _mirror_channel); Client.for_network() builds _Node instances, validates shard/realm, and returns a Client wired to a constructed Network; Client.close() delegates to self.network._close().
Integration / Usage tck/handlers/sdk.py	Replaced manual Client() + Network/_Node construction with Client.for_network(network_map=...) and then set client.network.mirror_address. Removed direct _Node/Network instantiation in handler.
Tests tests/unit/client_test.py, tests/unit/network_test.py	Added/updated unit tests covering Client.for_network() behavior (map handling, hosted vs non-hosted TLS/port normalization, empty map and shard/realm validation), Network defaults, mirror lifecycle (setter validation, reset/no-op, secure/insecure channel selection), and safety of mirror close.

Sequence Diagram(s)

sequenceDiagram
    participant Caller as Caller
    participant ClientCtor as Client.for_network()
    participant Network as Network
    participant Mirror as Mirror gRPC
    Caller->>ClientCtor: provide network_map, network_name
    ClientCtor->>Network: validate shard/realm, build nodes
    ClientCtor-->>Caller: return Client (holds Network)
    Caller->>Client: access client.mirror_stub
    Client->>Network: network.get_mirror_stub()
    Network->>Mirror: create grpc.secure_channel or grpc.insecure_channel
    Mirror-->>Network: return ConsensusServiceStub
    Network-->>Client: return mirror stub
    Caller->>Client: client.close()
    Client->>Network: _close()
    Network->>Mirror: close channel (if present)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR fully addresses the requirements from issue #2181: network now defaults to localhost, port conversion is prevented for non-hosted networks, and TLS is not applied to custom nodes.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the network initialization and TLS port conversion logic described in #2181; no unrelated modifications were introduced.
Docstring Coverage	✅ Passed	Docstring coverage is 86.49% which is sufficient. The required threshold is 80.00%.
Description check	✅ Passed	The PR description clearly explains the changes: removing unintended TLS port conversion for non-self-hosted networks and introducing the for_network() method. It directly relates to the changeset.
Title check	✅ Passed	The title 'Add for_network() method to configure a custom network' accurately describes the primary change—a new factory method to configure networks. However, the PR also includes significant changes to default network behavior (localhost vs testnet) and TLS port conversion logic, which are equally important objectives per the linked issue #2181. The title captures only one aspect of the change.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: faea089f-bfc4-4d74-8593-eac6020c6132

📥 Commits

Reviewing files that changed from the base of the PR and between 2db1106 and 7df9a17.

📒 Files selected for processing (5)

• src/hiero_sdk_python/client/client.py
• src/hiero_sdk_python/client/network.py
• tck/handlers/sdk.py
• tests/unit/client_test.py
• tests/unit/network_test.py

[coderabbitai]

Actionable comments posted: 7

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 28ae9415-cbc4-4482-99e2-c11e26361eef

📥 Commits

Reviewing files that changed from the base of the PR and between 7df9a17 and f8100c0.

📒 Files selected for processing (3)

• src/hiero_sdk_python/client/client.py
• src/hiero_sdk_python/client/network.py
• tests/unit/network_test.py

[coderabbitai]

Actionable comments posted: 2

♻️ Duplicate comments (1)

src/hiero_sdk_python/client/client.py (1)

160-185: 🧹 Nitpick | 🔵 Trivial

for_network does not expose mirror_address; forces callers to rely on the setter.

Callers like tck/handlers/sdk.py (Line 19–20) now construct with for_network(...) and then assign client.network.mirror_address = ... afterward. That works because Client no longer eagerly initializes the mirror stub, but it leaves for_network without a first-class way to configure the mirror address at construction time, and any caller that inspects client.network.get_mirror_address() before setting it will observe the wrong default (MIRROR_ADDRESS_DEFAULT.get("localhost", "localhost:5600")). Consider exposing it directly:

♻️ Proposed fix

-    def for_network(cls, network_map: dict[str, AccountId], network_name: str | None = "localhost") -> Client:
+    def for_network(
+        cls,
+        network_map: dict[str, AccountId],
+        network_name: str | None = "localhost",
+        mirror_address: str | None = None,
+    ) -> Client:
@@
-        nodes = [_Node(account_id, address, None) for address, account_id in network_map.items()]
-        return cls(Network(network=network_name, nodes=nodes))
+        nodes = [_Node(account_id, address, None) for address, account_id in network_map.items()]
+        return cls(Network(network=network_name, nodes=nodes, mirror_address=mirror_address))

Then in tck/handlers/sdk.py:

-        client = Client.for_network(network_map=nodes)
-        client.network.mirror_address = params.mirrorNetworkIp
+        client = Client.for_network(network_map=nodes, mirror_address=params.mirrorNetworkIp)

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 58bdca43-2abb-4ff4-a2a2-2f8c4a0e5d9f

📥 Commits

Reviewing files that changed from the base of the PR and between f8100c0 and c064829.

📒 Files selected for processing (5)

• src/hiero_sdk_python/client/client.py
• src/hiero_sdk_python/client/network.py
• tck/handlers/sdk.py
• tests/unit/client_test.py
• tests/unit/network_test.py

[MonaaEid]

I think changing the default network from testnet to localhost is a big behavioral shift, is this will affect the user and developers experience? I ask because I use the testnet network

[manishdait]

@MonaaEid, that's a nice question. to clarify, this change will not affect users who initialize via factory methods, the from_env method, or by passing a specific network name to the constructor.

The only scenario where backward compatibility is impacted is when a developer calls Client() with a default Network() object without specifying a name, which defaults to localhost instead of the previous testnet. While the probability of this empty initialization is low, I am happy to keep testnet as the default if needed

[aceppaluni]

Great Work!

[manishdait]

Remove the changes to the default network configuration localhost to preserve backward compatibility, and only keep the fix that prevents unintended port conversion for self-hosted networks such as localhost or solo.

[aceppaluni]

Can you update the branch when you have a moment?

[aceppaluni]

Can you update your branch?

Thank you