Skip to content

Commit df62561

Browse files
committed
feat: add comprehensive training documentation for _Executable class
Signed-off-by: MontyPokemon <59332150+MonaaEid@users.noreply.github.com> Signed-off-by: MonaaEid <monaa_eid@hotmail.com>
1 parent e4c0491 commit df62561

File tree

1 file changed

+33
-22
lines changed

1 file changed

+33
-22
lines changed

docs/sdk_developers/training/executable.md

Lines changed: 33 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
- [Logging & Debugging](#logging--debugging)
1111
- [Practical Examples](#practical-examples)
1212

13-
## 📋Introduction to _Executable
13+
## Introduction to _Executable
1414
* The _Executable class is the backbone of the Hedera SDK execution engine. It handles sending transactions and queries, retry logic, error mapping, and logging, allowing child classes (like Transaction and Query) to focus on business logic.
1515

1616
```mermaid
@@ -24,7 +24,7 @@ graph TD;
2424
```
2525

2626

27-
## ▶️⚙️Execution Flow
27+
## Execution Flow
2828

2929
-How _execute(client) works in the Hedera SDK?
3030

@@ -48,7 +48,7 @@ Here’s how child classes hook into the execution pipeline:
4848
| `_map_response(response, node_id, proto_request)` | Convert the raw gRPC/Proto response into the SDK’s response type (e.g., TransactionResponse, Query result) that gets returned to the caller. |
4949

5050

51-
## 🔁Retry Logic
51+
## Retry Logic
5252
- Core Logic:
5353
1. Loop up to max_attempts times — The outer for loop tries the operation multiple times
5454
2. Exponential backoff — Each retry waits longer than the previous one
@@ -61,7 +61,7 @@ Here’s how child classes hook into the execution pipeline:
6161
**_Retry logic = Try the operation, wait progressively longer between attempts, pick a different node if needed, and give up after max attempts. This makes the system resilient to temporary network hiccups._**
6262

6363

64-
## Exponential backoff
64+
## Exponential backoff
6565
Key Steps:
6666

6767
* First retry: wait `_min_backoff` ms
@@ -88,7 +88,7 @@ Key Steps:
8888

8989
_(If the [gRPC](https://en.wikipedia.org/wiki/GRPC) call itself fails, switch to a different network node and retry.)_
9090

91-
## 🚨Error Handling
91+
## Error Handling
9292

9393
* Mapping network errors to Python exceptions
9494
Abstract method that child classes implement:
@@ -125,7 +125,7 @@ Key Steps:
125125

126126

127127

128-
## ⚠️🐞Logging & Debugging
128+
## Logging & Debugging
129129

130130
- Request ID tracking
131131
* Unique request identifier per operation:
@@ -156,11 +156,12 @@ Key Steps:
156156
)
157157
```
158158
* During gRPC call:
159-
```
159+
```python
160160
logger.trace("Executing gRPC call", "requestId", self._get_request_id())
161161
```
162162
* After response received:
163-
```logger.trace(
163+
```python
164+
logger.trace(
164165
f"{self.__class__.__name__} status received",
165166
"nodeAccountID", self.node_account_id,
166167
"network", client.network.network, # Network name (testnet, mainnet)
@@ -170,7 +171,8 @@ Key Steps:
170171
```
171172

172173
* Before backoff/retry:
173-
```logger.trace(
174+
```python
175+
logger.trace(
174176
f"Retrying request attempt",
175177
"requestId", request_id,
176178
"delay", current_backoff, # Milliseconds to wait
@@ -180,15 +182,17 @@ Key Steps:
180182
time.sleep(current_backoff * 0.001) # Convert ms to seconds
181183
```
182184
* Node switch on gRPC error:
183-
```logger.trace(
185+
```python
186+
logger.trace(
184187
"Switched to a different node for the next attempt",
185188
"error", err_persistant,
186189
"from node", self.node_account_id, # Old node
187190
"to node", node._account_id # New node
188191
)
189192
```
190193
* Final failure:
191-
```logger.error(
194+
```python
195+
logger.error(
192196
"Exceeded maximum attempts for request",
193197
"requestId", self._get_request_id(),
194198
"last exception being", err_persistant
@@ -197,7 +201,7 @@ Key Steps:
197201

198202
- Tips for debugging transaction/query failures
199203
1. Enable Trace Logging
200-
Capture detailed execution flow:
204+
* Capture detailed execution flow:
201205
```python
202206
client.logger.set_level("trace") # or DEBUG
203207
```
@@ -231,7 +235,8 @@ Execution State Flow:
231235

232236
3. Track Backoff Progression
233237
Exponential backoff indicates retryable errors:
234-
```Attempt 1: (no backoff, first try)
238+
```text
239+
Attempt 1: (no backoff, first try)
235240
Attempt 2: delay 250ms
236241
Attempt 3: delay 500ms
237242
Attempt 4: delay 1000ms (1s)
@@ -246,7 +251,7 @@ Execution State Flow:
246251
* => Fails immediately (no backoff): Permanent error(precheck/validation)
247252
4. Monitor Node Switches
248253
Watch for node switching patterns in logs:
249-
```
254+
```text
250255
Switched to a different node
251256
from node: 0.0.3
252257
to node: 0.0.4
@@ -263,12 +268,13 @@ Problem patterns:
263268

264269
5. Cross-Reference Transaction ID with Hedera Explorer
265270
For transactions, use the transaction ID to verify on the network:
266-
```# From logs, capture txID
267-
txID: "0.0.123@1702057234.567890123"
271+
```
272+
# From logs, capture txID
273+
txID: "0.0.123@1702057234.567890123"
268274
269-
# Query Hedera mirror node
270-
curl https://testnet.mirrornode.hedera.com/api/v1/transactions/0.0.123-1702057234-567890123
271-
```
275+
# Query Hedera mirror node
276+
curl https://testnet.mirrornode.hedera.com/api/v1/transactions/0.0.123-1702057234-567890123
277+
```
272278
What you'll find:
273279
* => Actual execution result on the network
274280
* => Receipt status
@@ -287,13 +293,18 @@ Problem patterns:
287293

288294
7. Practical Debugging Workflow
289295
* Step 1: Capture the request ID
290-
`From error output: requestId = TransferTransaction:1702057234567890123`
296+
```
297+
From error output: requestId = TransferTransaction:1702057234567890123
298+
```
291299

292300
* Step 2: Search logs for that request ID
293-
```grep "1702057234567890123" application.log```
301+
```text
302+
grep "1702057234567890123" application.log
303+
```
294304

295305
* Step 3: Analyze the sequence
296-
```[TRACE] Executing attempt=1 nodeAccountID=0.0.3 ...
306+
```
307+
[TRACE] Executing attempt=1 nodeAccountID=0.0.3 ...
297308
[TRACE] Executing gRPC call ...
298309
[TRACE] Retrying request delay=250ms ...
299310
[TRACE] Executing attempt=2 nodeAccountID=0.0.4 ...

0 commit comments

Comments
 (0)