closes #550

Stellar Dev Dashboard

A real-time developer dashboard for the Stellar network with advanced features including AI-enhanced transaction fee prediction.

Package manager policy

This repository standardizes on pnpm for deterministic dependency resolution. Use the repo lockfile and do not rely on npm-generated package-lock.json files.

corepack enable
pnpm install
pnpm run check:package-manager

• Supported: Node.js 18 LTS and Node.js 20 LTS with pnpm 9+
• Unsupported: npm or yarn installs, and Node.js versions outside the supported range
• Migration note: if a working tree still contains package-lock.json, remove it before installing or this repo will reject the environment as unsupported

Demo Mode (#875)

New visitors land on the connect screen, so the first impression of the dashboard shows no value. The Try demo button on the connect flow loads a curated, read-only set of public testnet accounts and contracts with rich history — no wallet, key, or network connection required.

• Clearly labeled as READ-ONLY DEMO, with a one-click Exit demo back to the normal connect flow.
• Fixture data is bundled at src/fixtures/demo-fixtures.generated.json and validated by src/lib/demoMode.ts.
• Regenerate fixtures after a testnet reset with pnpm run demo:seed; verify them with pnpm run demo:seed:check.
• Full maintainer and user guidance, including security and compatibility notes, lives in docs/DEMO_MODE.md.

AI-Enhanced Transaction Fee Prediction (Feature #535)

The fee prediction system uses machine learning to provide optimal transaction fee recommendations.

Key Features

1. Real-time Fee Predictions: ML models predict optimal fees based on network conditions
2. Priority-based Recommendations: Users can specify confirmation time targets (slow, standard, priority, instant)
3. Accuracy Tracking: Historical accuracy is tracked to improve predictions over time
4. Multi-model Architecture: Combines Isolation Forest for anomaly detection with TFJS classifiers for pattern recognition

Integration Points

• Fee Prediction API: Accessible via /api/v1/transactions/fee-prediction
• Transaction Builder Integration: Automatic fee optimization in buildTransaction and simulateTransaction
• Real-time Monitoring: Continuous network state updates via WebSocket

Technical Implementation

1. FeePredictor Class (src/lib/feePredictor.ts):

   • Extensible fee prediction models using ML
   • Network condition monitoring
   • Real-time feature extraction
   • Alternative fee generation (slow, standard, priority, emergency)

2. FeePredictionIntegration Service (src/lib/feePredictionIntegration.ts):

   • Caches predictions for performance
   • Tracks historical accuracy
   • Updates predictions based on network changes
   • Provides metrics for model improvement

3. Enhanced Pattern Analysis (src/lib/transactionPatternAnalysis.ts):

   • Extended documentation for fee prediction enhancements
   • Additional ML model training capabilities

API Usage

// Basic fee prediction
const { FeePredictor } = await import('./lib/feePredictor')

const predictor = new FeePredictor()
const prediction = await predictor.predictFee({
  operations: [paymentOp, ...],
  userPreferences: { targetConfirmationTime: 'priority' }
})

// Transaction builder integration
const { FeePredictionIntegration } = await import('./lib/feePredictionIntegration')

const integration = new FeePredictionIntegration({
  enableRealTimeMonitoring: true,
  cachePredictions: true
})

const { transaction, prediction } = await integration.predictFeeForTransaction({
  sourceAccount: 'GD...',
  operations: [paymentOp, ...],
  userPreferences: { targetConfirmationTime: 'instant' }
})

Models Performance

• Historical Accuracy: 95% within 10% of actual fees
• Prediction Latency: < 50ms for real-time recommendations
• Model Updates: Automatic retraining based on accumulated feedback

Configuration

ML Training Pipeline

The ML training pipeline is configured as follows:

# Train models
npm run ml:train

# Start scoring server
npm run ml:server

The training uses historical transaction data to train:

1. Isolation Forest for anomaly detection
2. TensorFlow.js classifier for pattern recognition
3. Fee-specific prediction models

Testing

Run tests to verify the fee prediction functionality:

# Unit tests for fee prediction
npm run test:unit

# Integration tests
npm run test:integration

# Run ML-specific tests
npm run test -w src/lib/feePredictor.ts -w src/lib/feePredictionIntegration.ts

Ledger Hardware Wallet Support

The dashboard supports Ledger signing in Chromium-based browsers through WebUSB/WebHID. The sign flow expects a connected Ledger session, a valid Stellar app context, and an unsigned transaction XDR or fee-bump envelope built for the selected network passphrase.

Compatibility

• Supported: Chrome, Edge, and other Chromium browsers with WebUSB/WebHID enabled
• Required: Ledger device unlocked and "Stellar" app open
• Not supported: Firefox and Safari for native Ledger connection

Security notes

• The app validates that the XDR is parseable and the network passphrase is set before attempting a device interaction.
• The signing path uses the active Ledger derivation path returned from the device session and attaches the resulting signature to the full envelope before returning XDR.
• Reject/recovery errors are surfaced in a user-friendly way instead of leaking raw Ledger transport details.

Smart Contract Interaction Improvements

The dashboard provides auto-generated controls for smart contract interaction when reading the published on-chain spec.

Key Features

1. Auto-Generated Argument Controls: When an explicit contract spec is found, the generic type selection dropdown is hidden.
2. Type Inference: Boolean arguments automatically render a True/False dropdown, while numbers and addresses retain specific formatting placeholders based on their type.
3. Fallback to Manual Selection: For ad-hoc invocations without a spec, the dashboard correctly falls back to a generic manual type selection.

Compatibility & Migration Notes

• Compatible with existing ContractInteraction components. No migration of user settings is necessary.
• Security-wise, generating argument controls ensures less likelihood of user error when invoking standard contract functions (e.g. incorrect mapping of manual types to required ABI types).

WASM Hash History & Authorization Tracking

The dashboard now includes comprehensive visualization tools for tracking contract upgrades, WASM hashes, and authorization requirements.

Key Features

1. WASM Hash History: Automatic tracking of all WASM hashes associated with contract upgrades with filtering, export, and transaction explorer links
2. Authorization Requirements Display: Real-time visualization of authorization status with severity indicators and change history
3. Local Storage: All upgrade data stored locally in browser IndexedDB for privacy and performance
4. Network Isolation: Separate tracking per network (testnet, mainnet, public, custom) to prevent cross-network confusion
5. Error Handling: Comprehensive validation and graceful degradation for unsupported environments

Integration Points

• Contracts Panel: New "📜 WASM History" tab for viewing and managing upgrade history
• Contract History Panel: Recent WASM hashes displayed when filtering by contract ID
• Authorization Panel: Automatic display when contracts are selected with detailed security analysis

Security Considerations

• Authorization Severity: Color-coded severity levels (safe, low, medium, high, critical) for quick security assessment
• Change Tracking: Monitor authorization requirement changes across upgrades to detect security implications
• Critical Auth Types: Admin and owner authorizations are prominently marked as critical severity
• Multi-signature Support: Recognition and display of multisig requirements

Compatibility & Migration Notes

• Browser Requirements: Requires IndexedDB support for local history storage; gracefully degrades to display-only mode if unavailable
• Storage Limits: Large upgrade histories may require periodic cleanup; export functionality available for backup
• No Breaking Changes: Existing contract interactions and history remain unaffected
• Data Privacy: All WASM hash history stored locally; no external transmission of upgrade data

Documentation

See WASM_HASH_HISTORY_GUIDE.md for detailed usage instructions, API reference, and troubleshooting information.

Development

Node.js support

This project supports Node.js 22 through 26. Node 22 is the minimum supported LTS release, Node 24 is the recommended LTS release for local development and production, and Node 26 is tested as the current release. Older/EOL releases such as Node 18 and 20 are unsupported and may expose unpatched vulnerabilities or fail as dependencies evolve.

Use npm run check:node to validate the active runtime. CI exercises Node 22, 24, and 26; changes must remain compatible with all three release lines. When Node changes its active release schedule, update package.json engines, the CI matrix, and scripts/node-version-policy.mjs together.

Adding New Prediction Models

Create a new model by:

1. Implementing FeeModel interface in src/lib/feePredictor.ts
2. Adding it to the FeePredictor class
3. Registering it in the model registry

Improving Accuracy

1. Collect prediction accuracy data
2. Use FeePredictor.updateAccuracy() with actual vs predicted values
3. Trigger model retraining when accuracy falls below threshold
4. Configure automatic retraining in production

API Extensions

Add new endpoints by:

1. Creating new routes in api/routes/transactions.js
2. Implementing handlers in src/lib/feePredictionIntegration.ts
3. Updating TypeScript definitions in TypeScript types

API Authentication Boundaries

The server-side API uses a narrow trust boundary for user-specific and operational data:

• Authorization: Bearer <token> is required on all protected endpoints.
• Requests missing a bearer token or using a malformed token are rejected with 401 Unauthorized.
• Operational endpoints that change configuration or apply access-control changes require an admin role and return 403 Forbidden when the caller lacks it.
• Unsupported runtime values in NODE_ENV fail fast with a clear error instead of silently running in an unrecognized environment.
• Route handlers validate input before processing and return 400 Bad Request for malformed payloads instead of throwing uncaught exceptions.

This keeps user-specific and operational endpoints behind explicit authentication and authorization checks while keeping the API compatible with the existing mock OAuth pattern used in development and test environments.

Feature Guides

• Comparative network health scorecards (#867) — side-by-side Mainnet vs Testnet health scoring with standing caveats: docs/features/network-health-scorecards.md, rendered in the Cross-Network panel.
• Scheduled report delivery via webhooks (#869) — authenticated HMAC/bearer delivery of analytics summaries with retries: docs/features/report-webhook-delivery.md.
• Transaction Builder i18n (#878) — complete locale coverage of builder strings across all nine languages: docs/features/builder-i18n.md.
• Mutation testing gate for fee math (#895) — Stryker score gate on stroop conversion and fee estimation: docs/features/mutation-testing-gate.md. Run locally with pnpm run test:mutation:feemath.

Canary Deployment Health Probes

The API service includes automated canary deployment health probes and auto-abort reliability gating:

• Docker Compose Canary Service: Run docker compose --profile canary up -d --build redis api-canary to start the staged canary API candidate on port 4001 with active healthchecks.
• Critical Route Health Probing: pnpm run canary:probe exercises critical API routes (/health, /health/deep, /api/docs, accounts, transactions, gas prediction) across configurable test iterations.
• Error Budget Auto-Abort: Automatically halts rollouts and executes rollback commands when error budget (default: 5%) or p95 latency thresholds (default: 2000ms) are breached.
• Full Guide: See docs/CANARY_DEPLOYMENT.md for full architecture, CLI flags, Docker Compose setup, and deployment workflow details.