Octraban — Frontend

A human-readable block explorer & developer workspace for Soroban smart contracts on Stellar.

Decode raw contract calls into plain English, visualise contract relationships, replay transactions, and prototype against live contracts — all in the browser.

🟢 Live on Testnet

The Octraban Soroban contracts are deployed and verifiable on the Stellar test network right now:

Contract	Contract ID	Stellar Explorer
Explorer / registry	`CBKPNRQ4D3KTAAE7MMJ4HL6JNF2J2EBG2PSSRW4YHOMHTRHUU734CFWJ`	View on stellar.expert ↗
Ticket	`CDX3V6OE72KUIEEJTBLFCQZFXZCAKOYWYXK2KPRM57M6FLZFAVUSVL42`	View on stellar.expert ↗

Network: Test SDF Network ; September 2015 · RPC: https://soroban-testnet.stellar.org

Point the app at these contracts by keeping the default testnet configuration in your .env (see Configuration).

📋 Overview

Raw Soroban activity is opaque — a swap looks like an unlabelled base64 XDR blob. Octraban turns that noise into signal. It pairs an ABI-aware indexer (in the backend repo) with a rich React UI that renders contract calls, events, and relationships the way a human actually reads them:

"Address GABC… swapped 100 USDC → 98.7 XLM on StellarSwap at ledger 4,521,983."

Beyond read-only exploration, Octraban ships a developer workspace — an in-browser editor and sandbox for prototyping contract interactions against live testnet contracts without leaving the tab.

✨ Features

🔍 Explore

Feature	Description
Contract dashboard	Metadata, ABI, privileged roles, recent transactions and events for any contract (`/contract/:id`)
Human-readable events	XDR decoded into plain-English event rows via the ABI registry
Event & sub-invocation views	Drill into a single event (`/event/:seq`) or the full sub-invocation tree of a call
Wallet history	All transactions and events for an address (`/wallet/:address`)
Universal search	Look up contracts, wallets, transactions, and events from one bar (`/search`)
XDR inspector	Paste any XDR envelope and decode it field-by-field (`/xdr`)

🕸️ Visualise

Feature	Description
Relationship graph	Interactive contract/address relationship graph (`/graph`) built with Cytoscape
3D dependency graph	`3d-force-graph` view of contract dependencies and factory deployment trees
Invocation & batch flow charts	React-Flow diagrams of call flows and batched multi-calls
Address connection graph	Trace value and call flow between accounts

🛠️ Build

Feature	Description
Developer workspace	Monaco-powered editor + file explorer scoped to a contract (`/contract/:id/workspace`)
Sandbox	Run and share snippets against live contracts using a WebContainer runtime (`/sandbox`, `/sandbox/:id`)
Batch multi-call	Compose and preview batched contract invocations (`/batch`)
ABI upload	Drop a local ABI to decode events for unregistered contracts
Guided setup	First-run configuration walkthrough (`/setup`)

📊 Operate

Feature	Description
RPC metrics dashboard	Latency, throughput, and circuit-breaker status for the RPC layer (`/rpc-metrics`)
Rate-limit dashboard	Admin view of rate-limit hits (`/admin/rate-limits`)
Network switcher & comparison	Toggle networks and compare state side-by-side
Wallet integration	Connect with Freighter for signing and account context

🧱 Tech Stack

Layer	Technology
Framework	React 18 + TypeScript, bundled with Vite
Routing	React Router
Data	TanStack Query (server state, caching, retries)
Stellar	`@stellar/stellar-sdk`, `@stellar/freighter-api`
Visualisation	Cytoscape, `3d-force-graph`, React-Flow
In-browser IDE	Monaco Editor + `@webcontainer/api` sandbox
Testing	Vitest + Testing Library (jsdom)
Tooling	ESLint, Prettier, TypeScript strict mode

📁 Project Structure

src/
├── pages/          # Route-level screens (Home, ContractPage, GraphPage, Sandbox, …)
├── components/     # Reusable UI (graphs, tables, editor, dashboards, banners)
├── contexts/       # React context providers (network, wallet, …)
├── hooks/          # Custom hooks (data fetching, wallet, RPC metrics)
├── services/       # API/RPC clients, templates, WebContainer glue
├── types/          # Shared TypeScript types
├── utils/          # Formatting, XDR helpers, snippet generation
└── styles/         # Global styles

🚀 Getting Started

Prerequisites

Node.js ≥ 18
The octraban_backend indexer running locally on :3001 (provides all /api/* data the UI reads from). Clone and start it first — the frontend will show a prominent banner until the backend is reachable.
A Freighter wallet for signing (optional, for write flows)

Installation

git clone https://github.com/octraban/octraban_frontend.git
cd octraban_frontend

npm install
cp .env.example .env      # then edit as needed
npm run dev               # http://localhost:5173

Scripts

Command	Description
`npm run dev`	Start the Vite dev server
`npm run build`	Type-check and build for production
`npm run preview`	Preview the production build locally
`npm test`	Run the Vitest suite
`npm run test:watch`	Run tests in watch mode

🔧 Configuration

Copy .env.example → .env and adjust:

Variable	Default	Description
`VITE_INDEXER_URL`	`http://localhost:3001`	Octraban indexer API the UI reads from
`VITE_SOROBAN_RPC_URL`	`https://soroban-testnet.stellar.org`	Soroban RPC endpoint (used by the Sandbox)
`VITE_NETWORK_PASSPHRASE`	`Test SDF Network ; September 2015`	Stellar network passphrase

The defaults point at Stellar testnet, so a fresh checkout talks to the live testnet deployment out of the box.

🗺️ How it fits together

Octraban is split across three repositories:

octraban_frontend (this repo) — the explorer & developer workspace UI.
octraban_backend — the API + indexer that ingests on-chain data and serves it to the UI (:3001).
octraban_contract — the Soroban smart contracts (explorer registry + ticket), deployed to testnet.

Port topology

Service	Default port	Notes
octraban_frontend (Vite dev)	`:5173`	`npm run dev`; production build served on `:3000` (nginx / Docker)
octraban_backend (indexer)	`:3001`	All `/api/*` traffic is proxied here
Soroban RPC	n/a	`VITE_SOROBAN_RPC_URL` (testnet default)

Browser (user)
     │
     ▼
octraban_frontend  :5173 dev / :3000 prod
     │  all /api/* requests
     ▼
octraban_backend (indexer)  :3001   ◀─── start this first
     │
     ▼
Soroban RPC / Stellar testnet
     ▲
     │
octraban_contract (deployed testnet contracts)

In development, Vite proxies every /api/* request to http://localhost:3001 (configured in vite.config.ts). The production Docker image uses nginx for the same proxy. The frontend will display a banner and all data views will fail if the backend is not running.

🔌 Backend API contract

All endpoints are served by the octraban_backend indexer on port 3001. In development the Vite proxy (server.proxy in vite.config.ts) forwards /api → http://localhost:3001 so the frontend always uses relative /api/* paths.

Health

Method	Path	Description
GET	`/api/health`	Liveness check — 200 OK when the indexer is up. Used by `BackendStatusBanner` on startup.

Explorer — read endpoints

Method	Path	Description
GET	`/api/events`	Paginated event list (`?contract=&fn=&page=&type=`)
GET	`/api/events/:seq`	Single decoded event
GET	`/api/events/:seq/zk-costs`	CAP-0080 ZK host-function telemetry for an event
GET	`/api/search`	Universal search (`?q=&limit=`) — contracts, events, wallets
GET	`/api/contracts/:id`	Contract metadata + ABI
GET	`/api/contracts/:id/abi`	Download ABI as JSON blob
GET	`/api/contracts/:id/spec-full`	Full contract spec (functions + custom types)
GET	`/api/contracts/:id/migration-status`	SEP-49 migration state
GET	`/api/contracts/:id/roles`	Privileged role addresses
GET	`/api/contracts/:id/network-comparison`	State across networks
GET	`/api/contracts/:id/address-graph`	Address relationship graph data
GET	`/api/contracts/:id/circuit-breaker`	Circuit-breaker pause status
GET	`/api/contracts/:id/rwa-metadata`	Real-world asset token metadata
GET	`/api/contracts/:id/source-verifications`	Multi-sig source verifications (`?wasm_hash=`)
GET	`/api/contracts/:id/ttl`	Live TTL for instance + code entries
GET	`/api/contracts/:id/state-diffs`	Storage state-diff timeline (`?key=`)
GET	`/api/contracts/:id/quorum-freeze`	CAP-0077 quorum-freeze status
GET	`/api/burn-alerts`	Burn-rate alerts (`?contract=`)
GET	`/api/wallet/:address`	Events for a wallet address
GET	`/api/contract-graph`	Global contract dependency graph (`?limit=`)
GET	`/api/v1/contracts/:id/events-deep`	Events where contract appears directly or as sub-invocation (`?page=`)

Transactions & sub-invocations

Method	Path	Description
GET	`/api/transactions/:txHash/sub-invocations`	Sub-invocation tree for a transaction
GET	`/api/transactions/:txHash/status`	Transaction status (polling)
GET	`/api/transactions/:txHash/status/stream`	Live status via Server-Sent Events
GET	`/api/transactions/:txHash/call-path-metrics`	Analytical call-path metrics
GET	`/api/transactions/compare`	Cross-transaction tree diff (`?a=&b=`)
GET	`/api/sub-invocations/search`	Filtered sub-invocation search (8+ filter params)
GET	`/api/sub-invocations/analytics`	Aggregate analytics across all sub-invocations
GET	`/api/sub-invocations/stream`	SSE feed of live sub-invocations (`?contract=&function=`)

Write & simulation

Method	Path	Description
POST	`/api/contracts/:id/source-verifications`	Submit a source verification signature
POST	`/api/simulate`	Simulate a single contract invocation
POST	`/api/batch/simulate`	Batch multi-call simulation
POST	`/api/batch/estimate-gas`	Batch gas estimation
POST	`/api/batch/optimize`	Batch call-order optimisation
POST	`/api/batch/validate`	Batch call validation

Sandbox persistence

Method	Path	Description
POST	`/api/sandbox`	Save a sandbox session
GET	`/api/sandbox/:id`	Load a sandbox session
DELETE	`/api/sandbox/:id`	Delete a sandbox session
GET	`/api/sandboxes`	List sandbox sessions (`?limit=&offset=`)

Operations & admin

Method	Path	Description
GET	`/api/rpc-metrics`	RPC layer latency, throughput, and circuit-breaker state
GET	`/api/admin/analytics/rate-limit-hits`	Rate-limit hit counts (`?minutes=60`)
GET	`/api/admin/analytics/top-users`	Top rate-limit offenders (`?window=`)
GET	`/api/admin/analytics/violation-heatmap`	Rate-limit heatmap
GET	`/api/admin/analytics/upgrade-recommendations`	Upgrade advisories
GET	`/api/setup/doctor`	Backend diagnostic / health check
POST	`/api/setup/test-db`	Test database connection
POST	`/api/setup/save-config`	Persist backend configuration
POST	`/api/setup/db-init`	Initialise the database

🤝 Contributing

Issues and pull requests are welcome. Please run npm run build and npm test before opening a PR, and keep changes consistent with the existing ESLint/Prettier configuration.

📄 License

Released under the MIT License.

Navigation Menu

Uh oh!

Octraban — Frontend

🟢 Live on Testnet

📋 Overview

✨ Features

🔍 Explore

🕸️ Visualise

🛠️ Build

📊 Operate

🧱 Tech Stack

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

Scripts

🔧 Configuration

🗺️ How it fits together

Port topology

🔌 Backend API contract

Health

Explorer — read endpoints

Transactions & sub-invocations

Write & simulation

Sandbox persistence

Operations & admin

🤝 Contributing

📄 License

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Octraban — Frontend

🟢 Live on Testnet

📋 Overview

✨ Features

🔍 Explore

🕸️ Visualise

🛠️ Build

📊 Operate

🧱 Tech Stack

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

Scripts

🔧 Configuration

🗺️ How it fits together

Port topology

🔌 Backend API contract

Health

Explorer — read endpoints

Transactions & sub-invocations

Write & simulation

Sandbox persistence

Operations & admin

🤝 Contributing

📄 License