Adityarya11 · Adityarya11 · Apr 15, 2026 · Apr 16, 2026
diff --git a/.ci/examples-manifest.txt b/.ci/examples-manifest.txt
@@ -0,0 +1,15 @@
+# Example execution manifest for CI.
+# Format:
+# <binary-name>|<mode>|<timeout-seconds>|<args>|<note>
+# mode: run or skip
+
+hiero-sdk-cpp-consensus-pub-sub-chunked-example|skip|180||Infinite receive loop by design.
+hiero-sdk-cpp-validate-checksum-example|skip|180||Interactive std::cin loop is not CI-safe.
+hiero-sdk-cpp-schedule-network-update-example|skip|180||Sleeps for one hour by design.
+hiero-sdk-cpp-solidity-precompile-example|skip|180||Path assumptions differ between source and CI runtime.
+hiero-sdk-cpp-zero-token-operations-example|skip|180||Path assumptions differ between source and CI runtime.
+
+hiero-sdk-cpp-token-metadata-example|run|240|-ft|Requires either -ft or -nft argument.
+hiero-sdk-cpp-consensus-pub-sub-example|run|240||Longer timeout for network propagation.
+hiero-sdk-cpp-consensus-pub-sub-with-submit-key-example|run|240||Longer timeout for network propagation.
+hiero-sdk-cpp-long-term-scheduled-transaction-example|run|240||Longer timeout due scheduled execution flow.
diff --git a/.github/workflows/flow-run-examples.yaml b/.github/workflows/flow-run-examples.yaml
@@ -0,0 +1,139 @@
+name: Run Examples
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, reopened, synchronize]
+  push:
+    branches: ["**"]
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash
+
+permissions:
+  contents: read
+
+concurrency:
+  group: run-examples-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  run-examples:
+    name: Build and run SDK examples (Linux + Solo)
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Harden runner (audit outbound calls)
+        if: github.repository_owner == 'hiero-ledger'
+        uses: step-security/harden-runner@f808768d1510423e83855289c910610ca9b43176
+        with:
+          egress-policy: audit
+
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          submodules: true
+
+      - name: Use Node.js 22
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 22
+
+      - name: Install build dependencies (including CMake + Ninja)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            pkg-config \
+            libc6-dbg \
+            libgtest-dev \
+            build-essential \
+            cmake \
+            ninja-build
+
+      - name: Ensure binary cache path exists
+        run: mkdir -p "${{ github.workspace }}/b/vcpkg_cache"
+
+      - name: Setup VCPkg
+        run: |
+          rm -rf vcpkg
+          git clone https://github.com/microsoft/vcpkg.git
+          ./vcpkg/bootstrap-vcpkg.sh -disableMetrics
+
+      - name: Convert VCPkg to full clone
+        working-directory: vcpkg
+        run: |
+          if [[ "$(git rev-parse --is-shallow-repository)" == "true" ]]; then
+            git fetch --unshallow --prune
+          else
+            git fetch --prune
+          fi
+
+      - name: Prepare Hiero Solo
+        id: solo
+        uses: hiero-ledger/hiero-solo-action@692b186bd2e4c8d46b9deb1c067dc6ddcf0abcd7 # v0.18.0
+        with:
+          soloVersion: v0.68.0
+          installMirrorNode: true
+          mirrorNodeVersion: v0.151.0
+          hieroVersion: v0.72.0
+          dualMode: true
+
+      - name: Configure CMake
+        run: |
+          cmake --preset linux-x64-release \
+            -DBUILD_EXAMPLES=ON \
+            -DBUILD_TESTS=OFF \
+            -DBUILD_TCK=OFF \
+            -DBUILD_TCK_TESTS=OFF
+
+      - name: Build examples
+        run: |
+          cmake --build build/linux-x64-release --config Release -j 6
+
+      - name: Run examples
+        env:
+          OPERATOR_ID: ${{ steps.solo.outputs.accountId }}
+          OPERATOR_KEY: ${{ steps.solo.outputs.privateKey }}
+          HIERO_TESTNET_CONFIG_PATH: config/local_node.json
+          HIERO_NETWORK: testnet
+          NETWORK_NAME: testnet
+          PASSPHRASE: passphrase
+          DEFAULT_TIMEOUT_SECONDS: "180"
+          EXECUTABLES_DIRECTORY: build/linux-x64-release/src/sdk/examples/Release
+          EXAMPLE_MANIFEST_PATH: .ci/examples-manifest.txt
+        run: |
+          chmod +x ./run_examples.sh
+          ./run_examples.sh
+
+      - name: Publish example summary
+        if: always()
+        run: |
+          if [[ -f .ci/example-results.txt ]]; then
+            cat .ci/example-results.txt >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "No example results were generated." >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+          if [[ -f .ci/example-failures.txt ]] && [[ -s .ci/example-failures.txt ]]; then
+            {
+              echo
+              echo "Failure excerpts"
+              echo '```text'
+              cat .ci/example-failures.txt
+              echo '```'
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Upload example run logs (always)
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: run-examples-logs
+          path: |
+            .ci/example-results.txt
+            .ci/example-failures.txt
+            .ci/example-logs/
+          if-no-files-found: ignore
diff --git a/README.md b/README.md
@@ -43,6 +43,7 @@ The C++ SDK for interacting with a [Hiero](https://hiero.org) network.
 - [NASM](https://www.nasm.us) (`nasm.exe` must be added to `%PATH%`)
 
 #### Run
+
 ```powershell
 New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
 ```
@@ -93,12 +94,12 @@ cmake --build --preset macos-arm64-release
 
 The following optional flags can be added during configuration:
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `BUILD_TESTS` | `OFF` | Include the test suite in the build |
-| `BUILD_TCK` | `OFF` | Include TCK tests in the build |
-| `BUILD_EXAMPLES` | `OFF` | Include example programs in the build |
-| `BUILD_TCK_TESTS`| `OFF` | Include TCK Server unit tests in the build |
+| Flag              | Default | Description                                |
+| ----------------- | ------- | ------------------------------------------ |
+| `BUILD_TESTS`     | `OFF`   | Include the test suite in the build        |
+| `BUILD_TCK`       | `OFF`   | Include TCK tests in the build             |
+| `BUILD_EXAMPLES`  | `OFF`   | Include example programs in the build      |
+| `BUILD_TCK_TESTS` | `OFF`   | Include TCK Server unit tests in the build |
 
 Example with all options enabled:
 
@@ -148,9 +149,7 @@ Once your local network is running, verify the configuration in `config/local_no
   "network": {
     "0.0.3": "127.0.0.1:50211"
   },
-  "mirrorNetwork": [
-    "127.0.0.1:5600"
-  ],
+  "mirrorNetwork": ["127.0.0.1:5600"],
   "operator": {
     "accountId": "0.0.2",
     "privateKey": "302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137"
@@ -172,21 +171,23 @@ Examples demonstrate various SDK features and must be run from the project root
 
 Create a `.env` file in the project root with the following variables:
 
-| Variable | Description |
-|----------|-------------|
-| `OPERATOR_ID` | The ID of the operator account (e.g., `0.0.1234`) |
-| `OPERATOR_KEY` | The DER-encoded hex private key of the operator account |
-| `HIERO_NETWORK` | Network name: `mainnet`, `testnet`, or `previewnet` |
-| `PASSPHRASE` | (Optional) Passphrase for mnemonic-based key generation |
+| Variable        | Description                                             |
+| --------------- | ------------------------------------------------------- |
+| `OPERATOR_ID`   | The ID of the operator account (e.g., `0.0.1234`)       |
+| `OPERATOR_KEY`  | The DER-encoded hex private key of the operator account |
+| `HIERO_NETWORK` | Network name: `mainnet`, `testnet`, or `previewnet`     |
+| `PASSPHRASE`    | (Optional) Passphrase for mnemonic-based key generation |
 
 ### Running Examples
 
 #### Mac
+
 ```C++
 package/Release/Darwin/arm64/examples/Release/<EXAMPLE-NAME>
 ```
 
 #### Windows
+
 ```C++
 package\Release\Windows\AMD64\examples\Release\<EXAMPLE-NAME>
 ```
@@ -212,7 +213,30 @@ You can run all examples using the provided scripts:
 - macOS/Linux: `run_examples.sh`
 - Windows: `run_examples.bat`
 
-Before running, update the `EXECUTABLES_DIRECTORY` variable in the script to point to your build output folder.
+By default, `run_examples.sh` auto-detects common build output folders. You can override with:
+
+```sh
+EXECUTABLES_DIRECTORY=build/linux-x64-release/src/sdk/examples/Release ./run_examples.sh
+```
+
+The script also supports manifest-driven behavior for CI:
+
+- `EXAMPLE_MANIFEST_PATH`: Override the manifest path (defaults to `.ci/examples-manifest.txt`)
+- `DEFAULT_TIMEOUT_SECONDS`: Per-example timeout default (defaults to `180`)
+
+### CI Example Validation
+
+Examples are automatically validated in CI by the `Run Examples` workflow:
+
+- Workflow: `.github/workflows/flow-run-examples.yaml`
+- Manifest: `.ci/examples-manifest.txt`
+- Results: `.ci/example-results.txt`
+- Failure excerpts: `.ci/example-failures.txt`
+
+The CI workflow sets `HIERO_TESTNET_CONFIG_PATH=config/local_node.json` so examples that call `Client::forTestnet()`
+execute against a Solo local network instead of public testnet.
+
+The workflow fails when any non-skipped example fails.
 
 ## Contributing