action.yml

# ============================================================
# ZecKit – GitHub Composite Action
# ============================================================
# Published to GitHub Marketplace as "ZecKit E2E"
# https://github.com/marketplace/actions/zeckit-e2e
#
# Usage (from any repo):
#   - uses: zecdev/ZecKit@v1
#     with:
#       backend: zaino
#       ghcr_token: ${{ secrets.GITHUB_TOKEN }}
# ============================================================

name: ZecKit E2E
description: >
  Spin up a ZecKit Zcash devnet with pre-built images, run the complete golden
  E2E shielded-transaction flow (generate UA → fund → autoshield →
  shielded send → rescan/sync → verify), and upload logs/artifacts.
author: zecdev

branding:
  icon: shield
  color: blue

# ============================================================
# INPUTS
# ============================================================
inputs:
  # --- Backend ---
  backend:
    description: >
      Light-client backend: 'zaino' (Zcash Indexer, Rust, faster) or
      'lwd' (Lightwalletd, Go). Defaults to zaino.
    required: false
    default: 'zaino'

  # --- Timeouts ---
  startup_timeout_minutes:
    description: >
      Maximum minutes to wait for all services to become healthy after
      docker compose up. Zaino typically takes 2-3 min; lwd takes 3-4 min.
      Default: 10 min.
    required: false
    default: '10'

  block_wait_seconds:
    description: >
      Seconds to wait for a block to be mined after broadcasting a
      transaction (shield or send). Zebra regtest mines every 30-60 s.
      Default: 75 s.
    required: false
    default: '75'

  # --- Chain / wallet params ---
  send_amount:
    description: >
      Amount in ZEC to send in the shielded-send step of the golden flow.
    required: false
    default: '0.05'

  send_address:
    description: >
      Destination Unified Address for the shielded send. Leave empty to
      perform a self-send to the faucet's own UA (safe default for testing).
    required: false
    default: ''

  send_memo:
    description: Memo text attached to the shielded send transaction.
    required: false
    default: 'ZecKit E2E golden flow'

  # --- Image params ---
  image_prefix:
    description: >
      Docker image prefix used to pull pre-built images.
      Example: ghcr.io/zecdev/zeckit  (results in …-zebra:TAG etc.)
    required: false
    default: 'ghcr.io/zecdev/zeckit'

  image_tag:
    description: >
      Docker image tag to pull. Leave empty (default) for auto-detection:
      the action tries sha-<short>, branch-name, main, latest in order.
    required: false
    default: ''

  # --- Service URLs ---
  faucet_url:
    description: Base URL of the ZecKit faucet service.
    required: false
    default: 'http://localhost:8080'

  zebra_rpc_url:
    description: Zebra JSON-RPC endpoint.
    required: false
    default: 'http://localhost:8232'

  # --- Artifact behaviour ---
  upload_artifacts:
    description: >
      Controls when logs are uploaded as a workflow artifact:
        always     – upload unconditionally
        on-failure – upload only when a step fails (default)
        never      – never upload
    required: false
    default: 'on-failure'

  # --- Auth ---
  ghcr_token:
    description: >
      Token used to pull pre-built images from GHCR.
      Pass secrets.GITHUB_TOKEN from the calling workflow.
    required: true

# ============================================================
# OUTPUTS
# ============================================================
outputs:
  unified_address:
    description: Unified Address (UA) generated by the faucet wallet.
    value: ${{ steps.generate-ua.outputs.unified_address }}

  transparent_address:
    description: Transparent address of the faucet wallet.
    value: ${{ steps.generate-ua.outputs.transparent_address }}

  shield_txid:
    description: >
      Transaction ID of the autoshield operation (transparent → Orchard).
      Empty if transparent balance was below fee threshold.
    value: ${{ steps.autoshield.outputs.shield_txid }}

  send_txid:
    description: Transaction ID of the shielded send (Orchard → Orchard).
    value: ${{ steps.shielded-send.outputs.send_txid }}

  final_orchard_balance:
    description: Orchard (shielded) ZEC balance after the complete E2E flow.
    value: ${{ steps.verify.outputs.final_orchard_balance }}

  block_height:
    description: Zcash regtest blockchain height at end of the test.
    value: ${{ steps.verify.outputs.block_height }}

  test_result:
    description: Overall result of the golden E2E flow – 'pass' or 'fail'.
    value: ${{ steps.verify.outputs.test_result }}

# ============================================================
# COMPOSITE ACTION STEPS
# ============================================================
runs:
  using: composite

  steps:
    # ----------------------------------------------------------
    # 0. Validate inputs & install light dependencies
    # ----------------------------------------------------------
    - name: Validate inputs
      shell: bash
      run: |
        backend="${{ inputs.backend }}"
        if [[ "$backend" != "zaino" && "$backend" != "lwd" ]]; then
          echo "::error::Invalid backend '$backend'. Must be 'zaino' or 'lwd'."
          exit 1
        fi
        echo "backend            : $backend"
        echo "startup_timeout    : ${{ inputs.startup_timeout_minutes }} min"
        echo "block_wait_seconds : ${{ inputs.block_wait_seconds }} s"
        echo "send_amount        : ${{ inputs.send_amount }} ZEC"
        echo "image_prefix       : ${{ inputs.image_prefix }}"
        echo "faucet_url         : ${{ inputs.faucet_url }}"

    - name: Install runtime dependencies (jq, bc)
      shell: bash
      run: |
        missing=()
        command -v jq &>/dev/null || missing+=(jq)
        command -v bc &>/dev/null || missing+=(bc)
        if [[ ${#missing[@]} -gt 0 ]]; then
          sudo apt-get update -qq
          sudo apt-get install -y -qq "${missing[@]}"
        fi
        echo "jq $(jq --version)  bc $(bc --version | head -1)"

    # ----------------------------------------------------------
    # 1. Authenticate & select image tag
    # ----------------------------------------------------------
    - name: Log in to GHCR
      shell: bash
      run: |
        echo "${{ inputs.ghcr_token }}" \
          | docker login ghcr.io -u "${{ github.actor }}" --password-stdin

    - name: Select image tag
      id: select-tag
      shell: bash
      run: |
        image_prefix="$(echo "${{ inputs.image_prefix }}" | tr '[:upper:]' '[:lower:]')"
        echo "ZECKIT_IMAGE_PREFIX=${image_prefix}" >> "$GITHUB_ENV"

        override="${{ inputs.image_tag }}"
        if [[ -n "$override" ]]; then
          echo "Using caller-specified tag: $override"
          echo "ZECKIT_IMAGE_TAG=${override}" >> "$GITHUB_ENV"
          exit 0
        fi

        short_sha="${GITHUB_SHA::7}"
        branch_tag="$(echo "${GITHUB_REF_NAME}" | tr '/' '-')"
        candidates=("sha-${short_sha}" "${branch_tag}" "main" "latest")

        for tag in "${candidates[@]}"; do
          if docker manifest inspect "${image_prefix}-zaino:${tag}" >/dev/null 2>&1; then
            echo "Auto-selected tag: ${tag}"
            echo "ZECKIT_IMAGE_TAG=${tag}" >> "$GITHUB_ENV"
            exit 0
          fi
        done

        echo "::warning::No pre-built image found; docker compose will build locally (slow)."
        echo "ZECKIT_IMAGE_TAG=sha-${short_sha}" >> "$GITHUB_ENV"

    # ----------------------------------------------------------
    # 2. Configure Zebra & pull images
    # ----------------------------------------------------------
    - name: Configure zebra.toml (miner address)
      shell: bash
      run: |
        config="${{ github.action_path }}/docker/configs/zebra.toml"
        if [[ -f "$config" ]]; then
          # Default deterministic seed → transparent address
          miner_addr="tmBsTi2xWTjUdEXnuTceL7fecEQKeWaPDJd"
          sed -i "s|miner_address = \".*\"|miner_address = \"${miner_addr}\"|g" "$config"
          echo "Zebra miner address: ${miner_addr}"
        else
          echo "::warning::zebra.toml not found at $config; using existing image config."
        fi

    - name: Pull pre-built Docker images
      shell: bash
      run: |
        backend="${{ inputs.backend }}"
        cd "${{ github.action_path }}"
        docker compose --profile "$backend" pull \
          || echo "::warning::Pull failed or partial; compose will build missing images locally."

    # ----------------------------------------------------------
    # 3. Start devnet & wait for health
    # ----------------------------------------------------------
    - name: Start devnet
      id: start-devnet
      shell: bash
      run: |
        backend="${{ inputs.backend }}"
        timeout_min="${{ inputs.startup_timeout_minutes }}"
        timeout_sec=$(( timeout_min * 60 ))
        faucet_url="${{ inputs.faucet_url }}"
        zebra_rpc="${{ inputs.zebra_rpc_url }}"

        cd "${{ github.action_path }}"
        docker compose --profile "$backend" up -d
        echo "Docker services started with profile: $backend"

        echo "Waiting up to ${timeout_min}m for services to become healthy..."
        deadline=$(( SECONDS + timeout_sec ))

        # Wait for Zebra RPC
        echo "[1/2] Waiting for Zebra RPC at $zebra_rpc ..."
        zebra_ready=0
        while [[ $SECONDS -lt $deadline ]]; do
          if curl -sf --max-time 5 \
               -H "Content-Type: application/json" \
               -d '{"jsonrpc":"2.0","id":"1","method":"getblockcount","params":[]}' \
               "$zebra_rpc" >/dev/null 2>&1; then
            echo "  ✓ Zebra RPC is ready."
            zebra_ready=1
            break
          fi
          elapsed_min=$(( SECONDS / 60 ))
          echo "  ... still waiting (${elapsed_min}m elapsed)"
          sleep 10
        done
        if [[ "$zebra_ready" != "1" ]]; then
          echo "::error::Zebra did not become available within ${timeout_min} minutes."
          docker compose logs
          exit 1
        fi

        # Wait for Faucet
        echo "[2/2] Waiting for Faucet at $faucet_url ..."
        faucet_ready=0
        while [[ $SECONDS -lt $deadline ]]; do
          http_status=$(curl -sf --max-time 5 -o /dev/null -w "%{http_code}" \
            "$faucet_url/health" 2>/dev/null || true)
          if [[ "$http_status" == "200" ]]; then
            wallet_status=$(curl -sf --max-time 5 "$faucet_url/health" \
              | jq -r '.status // empty' 2>/dev/null)
            if [[ "$wallet_status" == "healthy" ]]; then
              echo "  ✓ Faucet is healthy."
              faucet_ready=1
              break
            fi
          fi
          elapsed_min=$(( SECONDS / 60 ))
          echo "  ... still waiting (${elapsed_min}m elapsed, faucet HTTP=$http_status)"
          sleep 10
        done
        if [[ "$faucet_ready" != "1" ]]; then
          echo "::error::Faucet did not become healthy within ${timeout_min} minutes."
          docker compose logs
          exit 1
        fi

        echo ""
        echo "All services healthy – beginning E2E golden flow."

    # ============================================================
    # GOLDEN E2E FLOW
    # ============================================================

    # ----------------------------------------------------------
    # Step 1 – Generate Unified Address
    # ----------------------------------------------------------
    - name: "E2E 1/6 – Generate Unified Address"
      id: generate-ua
      shell: bash
      run: |
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        echo "  E2E 1/6: Generate Unified Address"
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        faucet_url="${{ inputs.faucet_url }}"

        addr_json=""
        for attempt in 1 2 3; do
          addr_json=$(curl -sf --max-time 15 "$faucet_url/address" 2>/dev/null) && break
          echo "  Attempt $attempt failed, retrying in 5 s..."
          sleep 5
        done

        if [[ -z "$addr_json" ]]; then
          echo "::error::Could not retrieve address from faucet after 3 attempts."
          exit 1
        fi

        ua=$(echo "$addr_json" | jq -r '.unified_address // empty')
        ta=$(echo "$addr_json" | jq -r '.transparent_address // empty')

        if [[ -z "$ua" ]]; then
          echo "::error::Faucet returned no unified_address. Response: $addr_json"
          exit 1
        fi

        echo "  Unified Address : $ua"
        echo "  Transparent     : $ta"
        echo "unified_address=$ua"     >> "$GITHUB_OUTPUT"
        echo "transparent_address=$ta" >> "$GITHUB_OUTPUT"
        echo "::notice::UA generated: $ua"

    # ----------------------------------------------------------
    # Step 2 – Fund (wait for transparent mining rewards)
    # ----------------------------------------------------------
    - name: "E2E 2/6 – Wait for Mining Rewards (Fund)"
      id: fund
      shell: bash
      run: |
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        echo "  E2E 2/6: Wait for Mining Rewards"
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        faucet_url="${{ inputs.faucet_url }}"
        timeout_min="${{ inputs.startup_timeout_minutes }}"
        deadline=$(( SECONDS + timeout_min * 60 ))

        while [[ $SECONDS -lt $deadline ]]; do
          stats=$(curl -sf --max-time 10 "$faucet_url/stats" 2>/dev/null || true)
          transparent=$(echo "$stats" | jq '.transparent_balance // 0' 2>/dev/null || echo 0)
          orchard=$(echo "$stats"      | jq '.orchard_balance // 0' 2>/dev/null || echo 0)

          echo "  transparent=${transparent} ZEC   orchard=${orchard} ZEC"

          has_funds=$(echo "$transparent > 0 || $orchard > 0" | bc -l 2>/dev/null || echo 0)
          if [[ "$has_funds" == "1" ]]; then
            echo "  ✓ Wallet funded."
            break
          fi
          sleep 15
        done

        if [[ $SECONDS -ge $deadline ]]; then
          echo "::error::Wallet had no balance after waiting ${timeout_min} minutes. Is mining running?"
          exit 1
        fi

    # ----------------------------------------------------------
    # Step 3 – Autoshield (transparent → Orchard)
    # ----------------------------------------------------------
    - name: "E2E 3/6 – Autoshield (transparent → Orchard)"
      id: autoshield
      shell: bash
      run: |
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        echo "  E2E 3/6: Autoshield"
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        faucet_url="${{ inputs.faucet_url }}"

        stats=$(curl -sf --max-time 10 "$faucet_url/stats" 2>/dev/null || true)
        transparent=$(echo "$stats" | jq '.transparent_balance // 0' 2>/dev/null || echo 0)
        echo "  Transparent balance: ${transparent} ZEC"

        # Need at least 2× fee (0.0002 ZEC) to be worth shielding
        has_transparent=$(echo "$transparent >= 0.0002" | bc -l 2>/dev/null || echo 0)
        if [[ "$has_transparent" != "1" ]]; then
          echo "  Transparent balance below fee threshold – skipping shield step."
          echo "shield_txid=" >> "$GITHUB_OUTPUT"
          exit 0
        fi

        shield_json=$(curl -sf --max-time 90 -X POST "$faucet_url/shield" 2>/dev/null)
        status=$(echo "$shield_json" | jq -r '.status // "error"')
        txid=$(echo "$shield_json"   | jq -r '.txid // ""')

        echo "  Shield status : $status"
        echo "  Shield txid   : ${txid:-n/a}"
        echo "shield_txid=$txid" >> "$GITHUB_OUTPUT"

        if [[ "$status" != "shielded" && "$status" != "no_funds" ]]; then
          echo "::error::Shield failed with status '$status'. Response: $shield_json"
          exit 1
        fi
        if [[ "$status" == "shielded" ]]; then
          echo "::notice::Autoshield txid: $txid"
        fi

    - name: "E2E 3b/6 – Wait for shield block confirmation"
      shell: bash
      run: |
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        echo "  E2E 3b/6: Block confirmation window"
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        block_wait="${{ inputs.block_wait_seconds }}"
        echo "  Sleeping ${block_wait}s for Zebra to mine a confirming block..."
        sleep "$block_wait"

        faucet_url="${{ inputs.faucet_url }}"
        echo "  Syncing wallet..."
        curl -sf --max-time 120 -X POST "$faucet_url/sync" >/dev/null || true
        sleep 10
        echo "  Sync done."

    # ----------------------------------------------------------
    # Step 4 – Shielded Send (Orchard → Orchard)
    # ----------------------------------------------------------
    - name: "E2E 4/6 – Shielded Send (Orchard → Orchard)"
      id: shielded-send
      shell: bash
      run: |
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        echo "  E2E 4/6: Shielded Send"
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        faucet_url="${{ inputs.faucet_url }}"
        send_amount="${{ inputs.send_amount }}"
        send_memo="${{ inputs.send_memo }}"

        # Resolve destination address
        send_address="${{ inputs.send_address }}"
        if [[ -z "$send_address" ]]; then
          send_address="${{ steps.generate-ua.outputs.unified_address }}"
          echo "  Destination: self (faucet UA)"
        else
          echo "  Destination: $send_address"
        fi
        echo "  Amount     : $send_amount ZEC"
        echo "  Memo       : $send_memo"

        # Verify Orchard balance is sufficient
        stats=$(curl -sf --max-time 10 "$faucet_url/stats" 2>/dev/null || true)
        orchard=$(echo "$stats" | jq '.orchard_balance // 0' 2>/dev/null || echo 0)
        echo "  Orchard balance: $orchard ZEC"

        has_orchard=$(echo "$orchard >= $send_amount" | bc -l 2>/dev/null || echo 0)
        if [[ "$has_orchard" != "1" ]]; then
          echo "::error::Insufficient Orchard balance ($orchard ZEC) to send $send_amount ZEC."
          echo "  Make sure the autoshield step completed and a confirming block was mined."
          exit 1
        fi

        # Build JSON payload safely
        payload=$(jq -nc \
          --arg  addr "$send_address" \
          --argjson amt  "$send_amount" \
          --arg  memo "$send_memo" \
          '{"address":$addr,"amount":$amt,"memo":$memo}')

        send_json=$(curl -sf --max-time 90 -X POST "$faucet_url/send" \
          -H "Content-Type: application/json" \
          -d "$payload" 2>/dev/null)

        status=$(echo "$send_json" | jq -r '.status // "error"')
        txid=$(echo "$send_json"   | jq -r '.txid // ""')

        echo "  Send status : $status"
        echo "  Send txid   : ${txid:-n/a}"
        echo "send_txid=$txid" >> "$GITHUB_OUTPUT"

        if [[ "$status" != "sent" ]]; then
          echo "::error::Shielded send failed with status '$status'. Response: $send_json"
          exit 1
        fi
        echo "::notice::Shielded send txid: $txid"

    # ----------------------------------------------------------
    # Step 5 – Rescan / Sync post-send
    # ----------------------------------------------------------
    - name: "E2E 5/6 – Rescan / Sync"
      shell: bash
      run: |
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        echo "  E2E 5/6: Rescan / Sync"
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        faucet_url="${{ inputs.faucet_url }}"
        block_wait="${{ inputs.block_wait_seconds }}"

        echo "  Waiting ${block_wait}s for send to be mined..."
        sleep "$block_wait"

        echo "  Triggering wallet sync..."
        sync_json=$(curl -sf --max-time 120 -X POST "$faucet_url/sync" 2>/dev/null || true)
        sync_status=$(echo "$sync_json" | jq -r '.status // "unknown"' 2>/dev/null || echo unknown)
        echo "  Sync status: $sync_status"
        sleep 5

    # ----------------------------------------------------------
    # Step 6 – Verify final state
    # ----------------------------------------------------------
    - name: "E2E 6/6 – Verify Final State"
      id: verify
      shell: bash
      run: |
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        echo "  E2E 6/6: Verify"
        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
        faucet_url="${{ inputs.faucet_url }}"
        zebra_rpc="${{ inputs.zebra_rpc_url }}"

        # Faucet final stats
        stats=$(curl -sf --max-time 15 "$faucet_url/stats" 2>/dev/null || true)
        if [[ -z "$stats" ]]; then
          echo "::error::Could not retrieve final stats from faucet."
          echo "test_result=fail" >> "$GITHUB_OUTPUT"
          exit 1
        fi

        final_orchard=$(echo "$stats"      | jq '.orchard_balance // 0')
        final_transparent=$(echo "$stats"  | jq '.transparent_balance // 0')
        echo "  Final Orchard     : $final_orchard ZEC"
        echo "  Final Transparent : $final_transparent ZEC"
        echo "final_orchard_balance=$final_orchard" >> "$GITHUB_OUTPUT"

        # Block height
        height_json=$(curl -sf --max-time 5 \
          -H "Content-Type: application/json" \
          -d '{"jsonrpc":"2.0","id":"1","method":"getblockcount","params":[]}' \
          "$zebra_rpc" 2>/dev/null || true)
        height=$(echo "$height_json" | jq '.result // 0' 2>/dev/null || echo 0)
        echo "  Block height      : $height"
        echo "block_height=$height" >> "$GITHUB_OUTPUT"

        # Sanity: we must have some ZEC and a non-zero chain
        total=$(echo "$final_orchard + $final_transparent" | bc -l 2>/dev/null || echo 0)
        has_balance=$(echo "$total > 0"  | bc -l 2>/dev/null || echo 0)
        blk_ok=$(echo      "$height > 0" | bc -l 2>/dev/null || echo 0)

        if [[ "$has_balance" == "1" && "$blk_ok" == "1" ]]; then
          echo ""
          echo "  ✓ E2E GOLDEN FLOW PASSED"
          echo "  ┌──────────────────────────────────────┐"
          echo "  │  1. UA generated         ✓           │"
          echo "  │  2. Wallet funded        ✓           │"
          echo "  │  3. Autoshield           ✓           │"
          echo "  │  4. Shielded send        ✓           │"
          echo "  │  5. Rescan / sync        ✓           │"
          echo "  │  6. Balance verified     ✓           │"
          echo "  └──────────────────────────────────────┘"
          echo "test_result=pass" >> "$GITHUB_OUTPUT"
        else
          echo "::error::Verification failed: total=${total} ZEC, block_height=${height}."
          echo "  Expected non-zero balance and chain height."
          echo "test_result=fail" >> "$GITHUB_OUTPUT"
          exit 1
        fi

    # ============================================================
    # ARTIFACTS & CLEANUP
    # ============================================================

    - name: Collect logs
      if: always()
      shell: bash
      run: |
        log_dir="/tmp/zeckit-logs"
        mkdir -p "$log_dir"
        cd "${{ github.action_path }}"

        docker compose logs zebra        > "$log_dir/zebra.log"        2>&1 || true
        docker compose logs zaino        > "$log_dir/zaino.log"        2>&1 || true
        docker compose logs lightwalletd > "$log_dir/lightwalletd.log" 2>&1 || true
        docker compose logs faucet-zaino > "$log_dir/faucet.log"       2>&1 || true
        docker compose logs faucet-lwd   >> "$log_dir/faucet.log"      2>&1 || true
        docker ps -a                     > "$log_dir/containers.log"   2>&1 || true
        docker network ls                > "$log_dir/networks.log"     2>&1 || true

        # Final wallet stats
        curl -sf "${{ inputs.faucet_url }}/stats" 2>/dev/null \
          | jq . > "$log_dir/faucet-stats.json" 2>/dev/null || true

        # Machine-readable run summary
        jq -n \
          --arg  backend   "${{ inputs.backend }}" \
          --arg  ua        "${{ steps.generate-ua.outputs.unified_address }}" \
          --arg  shield_tx "${{ steps.autoshield.outputs.shield_txid }}" \
          --arg  send_tx   "${{ steps.shielded-send.outputs.send_txid }}" \
          --arg  orchard   "${{ steps.verify.outputs.final_orchard_balance }}" \
          --arg  height    "${{ steps.verify.outputs.block_height }}" \
          --arg  result    "${{ steps.verify.outputs.test_result }}" \
          '{
            backend:               $backend,
            unified_address:       $ua,
            shield_txid:           $shield_tx,
            send_txid:             $send_tx,
            final_orchard_balance: $orchard,
            block_height:          $height,
            test_result:           $result
          }' > "$log_dir/run-summary.json" 2>/dev/null || true

        echo "Artifact contents:"
        ls -lh "$log_dir/"

    - name: Upload artifacts – always
      if: ${{ inputs.upload_artifacts == 'always' }}
      uses: actions/upload-artifact@v4
      with:
        name: zeckit-e2e-logs-${{ github.run_number }}
        path: /tmp/zeckit-logs/
        retention-days: 14

    - name: Upload artifacts – on failure
      if: >
        inputs.upload_artifacts == 'on-failure' &&
        (failure() || steps.verify.outputs.test_result == 'fail')
      uses: actions/upload-artifact@v4
      with:
        name: zeckit-e2e-logs-${{ github.run_number }}
        path: /tmp/zeckit-logs/
        retention-days: 14

    - name: Stop devnet
      if: always()
      shell: bash
      run: |
        cd "${{ github.action_path }}"
        docker compose down --remove-orphans 2>/dev/null || true
        echo "Devnet stopped."

    - name: Job summary
      if: always()
      shell: bash
      run: |
        result="${{ steps.verify.outputs.test_result }}"
        ua="${{ steps.generate-ua.outputs.unified_address }}"
        shield_tx="${{ steps.autoshield.outputs.shield_txid }}"
        send_tx="${{ steps.shielded-send.outputs.send_txid }}"
        orchard="${{ steps.verify.outputs.final_orchard_balance }}"
        height="${{ steps.verify.outputs.block_height }}"

        {
          echo "## ZecKit E2E – Golden Flow Summary"
          echo ""
          if [[ "$result" == "pass" ]]; then
            echo "**Status: ✅ PASSED**"
          else
            echo "**Status: ❌ FAILED**"
          fi
          echo ""
          echo "| Field | Value |"
          echo "|---|---|"
          echo "| Backend | ${{ inputs.backend }} |"
          echo "| Unified Address | \`${ua}\` |"
          echo "| Shield txid | \`${shield_tx:-n/a}\` |"
          echo "| Send txid | \`${send_tx:-n/a}\` |"
          echo "| Final Orchard balance | ${orchard} ZEC |"
          echo "| Block height | ${height} |"
        } >> "$GITHUB_STEP_SUMMARY"