[abhayrajjais01]

Description

This pull request implements the SATP UI Inspector inside cacti-ledger-browser to enable real-time telemetry, monitoring, and deep forensic inspection of Secure Asset Transfer Protocol (SATP v2 / Hermes) gateways and cross-chain transfers.

fixes #4617

Key Features & Architectural Additions:

1. App Category & Registration:

   • Added AppCategory.CrossChain with CompareArrows icon and category metadata.
   • Registered satpInspector in global GUI application registry (common/config.tsx).

2. Core Queries & REST API Integration:

   • Real-time React Query hooks querying SATP Hermes gateway endpoints:
     • GET /get-sessions-ids: List of active and archived session IDs.
     • GET /status?SessionID=...: Live session stage, substatus, step, and network pair.
     • GET /audit?startTimestamp=...&endTimestamp=...: Verifiable chronological audit trail.
     • GET /healthcheck: Live gateway operational health status.
     • GET /supported-ledgers: List of active blockchain connectors.

3. Forensic Inspection Views & Components:

   • Transfers Dashboard: Searchable and filterable transfer table with KPI summary cards (Total Transfers, Completed, In-Progress, Failed, Rollbacks).
   • Lifecycle Timeline Stepper: Visual multi-step progress bar tracking Stage 0 (Pre-Transfer Handshake) $\rightarrow$ Stage 1 (Transfer Initialization) $\rightarrow$ Stage 2 (Lock-Assertion) $\rightarrow$ Stage 3 (Commit & Complete).
   • Failure Lens Diagnostic Card: Dedicated banner for failed transfers displaying root causes, failing step, and automated rollback/refund status.
   • Gateway & Ledger Topology: Card visualizing the end-to-end route: Origin DLT $\rightarrow$ Source Gateway (TLS/gRPC-Web) $\rightarrow$ Counterparty Gateway $\rightarrow$ Destination DLT.
   • Cryptographic Audit Trail: Ordered table with copyable proof keys and a syntax-highlighted raw JSON payload modal with one-click copy.
   • Gateway & Network Health: Diagnostics view showing connection status, supported ledgers (Ethereum, Fabric), and protocol specifications.

4. Reviewer-Friendly Interactive Demo Mode & Standalone Support:

   • Integrated an interactive Demo Mode exhibiting realistic cross-chain transfer scenarios (Completed Ethereum $\rightarrow$ Fabric, In-Progress Besu $\rightarrow$ Fabric, and Failed Ethereum $\rightarrow$ Polygon with Rollback).
   • Allows maintainers and reviewers to test all UI capabilities immediately without needing to spin up live multi-gateway and multi-ledger clusters.
   • Added one-click "Export JSON" button to download session audit bundles for compliance reporting.

---

Screenshots

Transfers Dashboard -> KPI summary metrics, search bar, status tabs, and transfer table

Failure Lens & Stepper -> Aborted transfer diagnosis, failing step badge, rollback status, and 4-stage stepper

Audit Trail & JSON Modal -> Proof log table with interactive syntax-highlighted JSON viewer

Gateway & Network Health -> Health status banner, supported networks, and protocol specifications

🗺️ SATP UI Inspector — Architecture & User Workflow

The SATP UI Inspector provides an end-to-end telemetry and forensic auditing interface for Secure Asset Transfer Protocol (SATP) gateways within the cacti-ledger-browser.

graph TD
    A["Cacti Ledger Browser (/satp)"] --> B["Navigation Bar"]
    
    B --> C["Sessions Dashboard (/)"]
    B --> D["Gateways Page (/gateways)"]
    B --> E["Messages Page (/messages)"]
    B --> F["Overview Page (/overview)"]
    B --> G["Setup Guide (/guide)"]

    subgraph "1. Sessions Dashboard"
        C --> C1["KPI Filter Cards: Total, Completed, In-Progress, Failed, Rollbacks"]
        C --> C2["Filterable & Sortable Sessions Table"]
        C --> C3["Search & Keyboard Navigation (Tab, Enter)"]
        C2 -->|Click Row / Inspect| H["Session Detail View (/satp/session/:id)"]
    end

    subgraph "2. Forensic Session Detail"
        H --> H1["Transfer Route: Origin DLT -> Channel -> Destination DLT"]
        H --> H2["Audit Timeline: Sequential Proof Numbers (Ascending)"]
        H --> H3["Cryptographic Proofs: Lock & Mint Claims"]
        H --> H4["Failure Lens: Root Cause Diagnostics & Rollback Status"]
        H --> H5["Compliance Export: One-Click JSON Audit Bundle"]
    end

    subgraph "3. Gateway Telemetry & Messages"
        D --> D1["Live Healthcheck Ping (Port 4010 / 3013)"]
        D --> D2["Supported Ledgers (Besu, Fabric, Ethereum, Polygon)"]
        E --> E1["Cross-Gateway Message Sequence Audit Log"]
    end

    subgraph "4. Observability & Deployment"
        F --> F1["Prometheus Metrics (Port 9090): Latency & Throughput"]
        G --> G1["In-App Guide with Copyable Docker & Yarn Commands"]
    end

Loading

UPDATE:

Follow-up: iteration on top of the initial implementation

Inspector

• Default gateway endpoint corrected to the plugin's OAPI port 4010 (was 3000)
• App status is now healthcheck-backed — the home-page card pings the gateway instead of always reporting "connected"
• All views render live gateway data only; the demo data moved to a bundled, clearly-labeled read-only example gateway (tools/docker/ledger-browser-config-postgrest, port 3013) instead of fabricated sessions being mixed into results
• Hand-written typed API client (the 5 admin GET endpoints) — the package keeps zero workspace dependencies, enforced by a CI test, so the browser bundle never pulls in Node-only plugin code
• Hardening against hostile gateway payloads: coercing transform layer + fuzz tests; instance gateway/Prometheus URLs must pass strict isHttpUrl validation (rejects non-http schemes, embedded credentials, homoglyph hosts…)
• Polling uses capped exponential backoff (5 min ceiling) instead of a fixed 5 s hammer; audit queries use a bounded 7-day window
• Pages: Sessions (KPI cards that double as outcome filters, search, sortable columns, keyboard-accessible rows), Session detail (audit timeline, proofs, transfer path, failure lens, JSON audit-bundle export), Gateways, Messages, Overview (Prometheus metrics)

Ledger browser shell

• Crash guards: ErrorBoundary at app-route, app-card and shell levels — one broken app no longer takes the whole browser down
• Setup-guide links on connection errors; the connection-failed dialog is now actionable (shows the resolved store URL and the fix command)
• Runtime configuration tier (/config.js): one build, many environments, strict validation with graceful degradation
• Local-first config defaults + the slim self-hosted backend profile (Postgres + PostgREST + example gateway, one compose command) — full Supabase profiles remain supported
• First frontend test infrastructure (vitest + RTL + fast-check): 135 tests, including URL-boundary and transform fuzzing; jest transform suite unchanged (23 tests)
• Production Docker image (non-root nginx, CSP + security headers), vite preview hardening
• Docs: user guide, demo guide (satp-inspector-demo.md), trust model, and an in-app Guide page (last menu entry) with copyable setup commands

Try it

docker compose -f tools/docker/ledger-browser-config-postgrest/docker-compose.yml up -d
corepack yarn workspace @hyperledger-cacti/cacti-ledger-browser start   # http://localhost:3001

The seeded "SATP Inspector (example data)" instance works immediately. For a real gateway use the plugin's docker-compose-satp.yml (REST on 3012) — or point an instance at port 4010 while test:integration:docker-local runs to watch real transfers live.

yarn tsc, eslint, cspell, prettier (CI scopes) green; no generated/ edits. Happy to walk through any of the decisions — the biggest ones were dropping default-on demo data, the zero-dependency posture, and the local-first defaults.

[github-actions]

⚠️ Triage gate: this PR does not reference a triaged issue.

Every PR must be linked to an issue carrying the Triage_Ready label. See PULL.md §9 — Linked Issue and Traceability.

Please edit the PR description to include a closing keyword and an issue number, for example:

Closes #1234

The referenced issue must already carry Triage_Ready (assigned by a maintainer during triage).

⌛ If this is not resolved within 7 days of the Triage_Warning label being applied, the PR will be closed automatically. You will be able to reopen it once the linkage is in place.

Members of the hyperledger-cacti GitHub organization and Dependabot are exempt from this check.

[RafaelAPB]

@abhayrajjais01 thank you, this is super useful. Could you please give us a deployed link so other maintainers can inspect it without running it locally?

[abhayrajjais01]

@RafaelAPB,
here is the deployed link--

https://cacti-browser-ui-abhayrajjais01s-projects.vercel.app/

take a look and give me feedback on it, more than happy to fix and work on
thank you

[RafaelAPB]

@RafaelAPB, here is the deployed link--

https://cacti-browser-ui-abhayrajjais01s-projects.vercel.app/

take a look and give me feedback on it, more than happy to fix and work on thank you

I am unable to open that link without authentication

[abhayrajjais01]

@RafaelAPB ,
sorry for that you can use this link now--
https://dapper-biscuit-2afa71.netlify.app

[RafaelAPB]

@abhayrajjais01 could you please add me as contributor in your fork so I can push some changes to this PR?

[abhayrajjais01]

@RafaelAPB,
Sent you a invite for that

[RafaelAPB]

@abhayrajjais01 — thank you for the great starting point. I pushed a follow-up commit on top of yours that reworks the inspector for production use and hardens the ledger browser around it. Let's work together, and please do not use push forces (only force-with-lease), so we don't accidentally override each others work.

This PR still needs a lot of work before merging. In particular, 3 big areas for improvement: 1) un-hardcode gateway connections/data, we should be able to provide the URLs for different gateways that are instantiated with each other's address and inspect a real flow; 2) the visual identity is fragmented, follow the design system introduced here #4746; 3) reproducibility: it should be a few clicks to instantiate a CBDC demo and configure the SATP browser based on it

[abhayrajjais01]

Hi @Rafael-Belchior,

I have pushed a new commit (f4e8e86b7) to implement the navigation shell and visual identity alignment for cacti-ledger-browser:

Summary of Changes:

• Persistent Sidebar Navigation (Sidebar.tsx):

  • Added a collapsible sidebar navigation UI layout and styled using the Cacti design tokens (#4e8c5e, #f7f9f6, #dfe5e3).
  • Integrated the official Hyperledger Cacti brand mark illustration in the header alongside "Cacti Ledger Browser".
  • Added a Network Context pill, Overview root link, active application tree with sub-navigation, and a quick + Add Application modal action.
  • Added collapse/expand toggling with state persistence via localStorage.

• Refined Header Bar (HeaderBar.tsx):

  • Converted the top bar into a clean, sticky header with dynamic breadcrumbs and contextual back navigation.
  • Implemented a search bar with / keyboard shortcut support.
  • Added direct triggers for documentation and settings.

• Shell & Layout Integration:

  • Wrapped content in a responsive flex shell in CactiLedgerBrowserApp.tsx and standardized padding in ContentLayout.tsx.
  • Resolved minor React key warnings in SelectAppView.tsx and SelectGroupView.tsx.

here are the screenshot for the same---

Looking forward to your review and feedback!

[abhayrajjais01]

https://cute-quokka-56d44a.netlify.app/

here is the deployed link

[RafaelAPB]

@abhayrajjais01 please check the checks that are failing and solve the conflicts