diff --git a/.github/workflows/test-docs-scripts-frontend.yaml b/.github/workflows/test-docs-scripts-frontend.yaml new file mode 100644 index 000000000..a49c0e56e --- /dev/null +++ b/.github/workflows/test-docs-scripts-frontend.yaml @@ -0,0 +1,106 @@ +name: Test Documentation Scripts - Frontend + +# Test locally with: +# ```bash +# # Ubuntu 22.04 (recommended) +# gh extension exec act \ +# --workflows .github/workflows/test-docs-scripts-frontend.yaml \ +# --matrix os:ubuntu-22.04 +# +# # Ubuntu 24.04 (requires platform mapping) +# gh extension exec act \ +# --workflows .github/workflows/test-docs-scripts-frontend.yaml \ +# --matrix os:ubuntu-24.04 \ +# -P ubuntu-24.04=catthehacker/ubuntu:act-24.04 +# ``` + +on: + push: + +jobs: + test-frontend-scripts: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-22.04, ubuntu-24.04, macos-latest] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Make scripts executable + run: | + chmod +x website/docs/developers/scripts/frontend/*.sh + + - name: Install Node.js on Linux + if: runner.os == 'Linux' + run: | + bash website/docs/developers/scripts/frontend/install-nodejs-linux.sh + # Set up nvm environment for future steps + echo "NVM_DIR=$HOME/.nvm" >> $GITHUB_ENV + + - name: Install Node.js on macOS + if: runner.os == 'macOS' + run: | + bash website/docs/developers/scripts/frontend/install-nodejs-macos.sh + + - name: Install Angular CLI using documentation script + run: | + # Source nvm if available (Linux) + if [ -n "$NVM_DIR" ] && [ -s "$NVM_DIR/nvm.sh" ]; then + \. "$NVM_DIR/nvm.sh" + fi + bash website/docs/developers/scripts/frontend/install-angular-cli.sh + + - name: Install gtimeout on macOS + if: runner.os == 'macOS' + run: | + brew install coreutils + # Create symlink for timeout command + sudo ln -sf /usr/local/bin/gtimeout /usr/local/bin/timeout + + - name: Test install dependencies script + run: | + # Source nvm if available (Linux) + if [ -n "$NVM_DIR" ] && [ -s "$NVM_DIR/nvm.sh" ]; then + \. "$NVM_DIR/nvm.sh" + fi + bash website/docs/developers/scripts/frontend/install-dependencies.sh + + - name: Test build development script + run: | + # Source nvm if available (Linux) + if [ -n "$NVM_DIR" ] && [ -s "$NVM_DIR/nvm.sh" ]; then + \. "$NVM_DIR/nvm.sh" + fi + bash website/docs/developers/scripts/frontend/build-development.sh + + - name: Test build production script + run: | + # Source nvm if available (Linux) + if [ -n "$NVM_DIR" ] && [ -s "$NVM_DIR/nvm.sh" ]; then + \. "$NVM_DIR/nvm.sh" + fi + bash website/docs/developers/scripts/frontend/build-production.sh + + - name: Test format code script + run: | + # Source nvm if available (Linux) + if [ -n "$NVM_DIR" ] && [ -s "$NVM_DIR/nvm.sh" ]; then + \. "$NVM_DIR/nvm.sh" + fi + bash website/docs/developers/scripts/frontend/format-code.sh + + - name: Prepare for Cypress tests (Ubuntu 22.04) + if: matrix.os == 'ubuntu-22.04' + run: | + sudo apt-get update + sudo apt-get install -y libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev \ + libnss3 libxss1 libasound2 libxtst6 xauth xvfb + + - name: Prepare for Cypress tests (Ubuntu 24.04) + if: matrix.os == 'ubuntu-24.04' + run: | + sudo apt-get update + sudo apt-get install -y libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev \ + libnss3 libxss1 libasound2t64 libxtst6 xauth xvfb diff --git a/Makefile b/Makefile index 7dfd19e16..ee32daf1b 100644 --- a/Makefile +++ b/Makefile @@ -224,6 +224,7 @@ lint-bash: ## Check all shell scripts using shellcheck -not -path "*/target/*" \ -not -path "*/node_modules/*" \ -not -path "*/website/docs/developers/scripts/setup/*" \ + -not -path "*/website/docs/developers/scripts/frontend/*" \ -print0 | xargs -0 shellcheck @echo "Shellcheck completed successfully!" diff --git a/frontend/Makefile b/frontend/Makefile index 7fbd2e7e9..b79e66c1d 100644 --- a/frontend/Makefile +++ b/frontend/Makefile @@ -66,6 +66,14 @@ deploy: ## Deploy the application .PHONY: deploy-leaderboard deploy-leaderboard: ## Deploy the leaderboard application + $(MAKE) prebuild + $(MAKE) build-prod + cp dist/frontend/browser/assets/environments/leaderboard.js \ + dist/frontend/browser/assets/environments/env.js + firebase deploy + +.PHONY: deploy-leaderboard-sentry +deploy-leaderboard-sentry: ## Deploy the leaderboard application with Sentry sourcemaps $(MAKE) prebuild $(MAKE) build-prod-sentry cp dist/frontend/browser/assets/environments/leaderboard.js \ diff --git a/frontend/README.md b/frontend/README.md index fa9a956d4..96e1b3745 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,79 +1,14 @@ # Openmina Frontend -This is a simple Angular application that will help you to see the behaviour of -your local rust based mina node. +The frontend documentation has been moved to the main project website. -## Prerequisites +Please see: [Frontend Documentation](../website/docs/developers/frontend.mdx) -### 1. Node.js v23.1.0 - -#### MacOS - -```bash -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -brew install node@23.1.0 -``` - -#### Linux - -```bash -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash -source ~/.bashrc -nvm install 23.1.0 -``` - -#### Windows - -Download [Node.js v23.1.0](https://nodejs.org/) from the official website, open -the installer and follow the prompts to complete the installation. - -### 2. Angular CLI v19.2.14 - -```bash -npm install -g @angular/cli@19.2.14 -``` - -### 3. Installation - -Open a terminal and navigate to this project's root directory - -```bash -cd PROJECT_LOCATION/openmina/frontend -``` - -Install the dependencies - -```bash -npm install -``` - -## Run the application - -```bash -npm start -``` - -# Using O1JS wrapper - -as of now, o1js is not prepared to work with Angular, therefore we need to use -the wrapper that is provided in the `src/assets/o1js` folder. This wrapper is a -simple javascript webpack based application that will allow us to use the o1js -library in our Angular application. - -How to use it: - -1. Open a terminal and navigate to the `src/assets/o1js` folder -2. Install the dependencies - -```bash -npm install -``` - -3. Build the wrapper +To view the documentation locally: ```bash -npm run build-o1jswrapper +cd ../website +make docs-serve ``` -4. That's it. Now you can use your code from o1js-wrapper inside the Angular - application by using `BenchmarksWalletsZkService => o1jsInterface` +Then navigate to http://localhost:3000/docs/developers/frontend diff --git a/website/docs/developers/frontend/index.mdx b/website/docs/developers/frontend/index.mdx new file mode 100644 index 000000000..36f72ffff --- /dev/null +++ b/website/docs/developers/frontend/index.mdx @@ -0,0 +1,86 @@ +--- +title: Frontend Applications +description: Web-based interfaces for the Mina Rust node ecosystem +sidebar_position: 1 +--- + +import CodeBlock from "@theme/CodeBlock"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import InstallNodejsLinux from "!!raw-loader!../scripts/frontend/install-nodejs-linux.sh"; +import InstallNodejsMacos from "!!raw-loader!../scripts/frontend/install-nodejs-macos.sh"; +import InstallAngularCli from "!!raw-loader!../scripts/frontend/install-angular-cli.sh"; + +# Frontend Applications + +The Mina Rust node ecosystem includes several web-based frontend applications, +each serving a specific purpose in the network. + +## Components + +### [Node Dashboard](./node-dashboard) + +A comprehensive web interface for monitoring and interacting with your Mina Rust +node. View real-time blockchain state, network activity, and node metrics +through an intuitive dashboard. + +### [Leaderboard](./leaderboard) + +Track community participation in testnets with a competitive leaderboard system. +Previously used to monitor and rank testnet participants based on their +contributions to network stability and block production. + +### [WebNode](./webnode) + +Run a Mina node directly in your web browser using WebAssembly. This +experimental feature enables block production without installing native +software, pushing the boundaries of decentralized infrastructure. + +## Prerequisites + +All frontend applications are built with Angular and require Node.js to be +installed. + + + +:::info Platform Compatibility + +These instructions are tested and compatible with: + +- **Ubuntu**: 22.04, 24.04 +- **macOS**: macOS-13, macOS-14, macOS-latest + +::: + + + +### Install Node.js + + + + + + {InstallNodejsLinux} + + + + + + + {InstallNodejsMacos} + + + + + +### Install Angular CLI + + + {InstallAngularCli} + + +## Next Steps + +With Node.js and Angular CLI installed, you're ready to build and run any of the +frontend applications. Select a component above to learn about its specific +features and configuration. diff --git a/website/docs/developers/frontend/leaderboard.mdx b/website/docs/developers/frontend/leaderboard.mdx new file mode 100644 index 000000000..1ab46f4d4 --- /dev/null +++ b/website/docs/developers/frontend/leaderboard.mdx @@ -0,0 +1,84 @@ +--- +title: Leaderboard +description: Community participation tracking for Mina Rust node testnets +sidebar_position: 3 +--- + +import CodeBlock from "@theme/CodeBlock"; + +# Leaderboard + +The Leaderboard is a specialized frontend application designed to track and rank +community participation in Mina Rust node testnets. It provides real-time +visibility into testnet contributions, encouraging healthy competition among +participants. + +## Overview + +The Leaderboard system was developed to monitor testnet participation metrics +and provide transparent rankings of community members based on their +contributions to network stability, block production, and overall testnet +health. + +## Configuration + +### Building for Leaderboard + +Build the Leaderboard-specific version: + +```bash +cd frontend + +# Build with leaderboard configuration +make build-prod + +# Copy leaderboard environment +cp dist/frontend/browser/assets/environments/leaderboard.js \ + dist/frontend/browser/assets/environments/env.js +``` + +## Deployment + +### Firebase Deployment + + + +:::caution Outdated Configuration + +The Firebase deployment configuration may be outdated. Please verify the current +deployment targets and update the configuration as needed before deploying to +production. + +::: + + + +Deploy the Leaderboard to Firebase hosting: + +```bash +# Deploy leaderboard variant +make deploy-leaderboard +``` + +This command will: + +1. Run prebuild to update version +2. Build production assets with Sentry integration +3. Configure leaderboard-specific environment +4. Deploy to Firebase hosting + +### Standalone Deployment + +For custom hosting solutions: + +```bash +# Build the application +make build-prod + +# Configure for leaderboard +cp dist/frontend/browser/assets/environments/leaderboard.js \ + dist/frontend/browser/assets/environments/env.js + +# Serve the static files +npx http-server dist/frontend/browser -p 8080 +``` diff --git a/website/docs/developers/frontend/node-dashboard.mdx b/website/docs/developers/frontend/node-dashboard.mdx new file mode 100644 index 000000000..07cc71766 --- /dev/null +++ b/website/docs/developers/frontend/node-dashboard.mdx @@ -0,0 +1,212 @@ +--- +title: Node Dashboard +description: + Web interface for monitoring and interacting with the Mina Rust node +sidebar_position: 2 +--- + +import CodeBlock from "@theme/CodeBlock"; +import InstallDependencies from "!!raw-loader!../scripts/frontend/install-dependencies.sh"; +import StartDevelopment from "!!raw-loader!../scripts/frontend/start-development.sh"; +import BuildDevelopment from "!!raw-loader!../scripts/frontend/build-development.sh"; +import BuildProduction from "!!raw-loader!../scripts/frontend/build-production.sh"; +import FormatCode from "!!raw-loader!../scripts/frontend/format-code.sh"; +import RunTests from "!!raw-loader!../scripts/frontend/run-tests.sh"; + +# Node Dashboard + +The Node Dashboard is a comprehensive web interface for monitoring and +interacting with your Mina Rust node. Built with Angular, it provides real-time +insights into your node's operation and the broader network state. + +## Features + +- **Real-time node monitoring** - View node status, blockchain state, and + network activity +- **Block explorer** - Browse blocks, transactions, and accounts +- **Network visualization** - See peer connections and network topology +- **SNARK worker monitoring** - Track SNARK work production and verification +- **Transaction pool viewer** - Monitor pending transactions +- **Performance metrics** - Resource usage and performance dashboards + +## Prerequisites + +Ensure you have Node.js and Angular CLI installed by following the +[Frontend Prerequisites](./#prerequisites) guide. + +## Quick start + +### Installation + +Navigate to the frontend directory and install dependencies: + + + {InstallDependencies} + + +### Development server + +Start the development server with hot-reload: + + + {StartDevelopment} + + +This will: + +1. Install any missing dependencies +2. Start the Angular development server +3. Open the application in your browser at `http://localhost:4200` + +## Build configurations + +The frontend supports multiple build configurations for different environments: + +### Development builds + +For local development with debugging features: + + + {BuildDevelopment} + + +Other development configurations: + +```bash +# Local configuration (connects to local node) +make build-local + +# Mobile-accessible development server +make start-dev-mobile +``` + +### Production builds + +For optimized production deployments: + + + {BuildProduction} + + +Production build with Sentry error tracking: + +```bash +make build-prod-sentry +``` + +### Specialized configurations + +```bash +# Block producer dashboard +make build-producer + +# Fuzzing test interface +make build-fuzzing + +# WebNode integration +make build-webnodelocal +``` + +## Configuration + +### Environment files + +The frontend uses environment-specific configuration files located in +`src/assets/environments/`: + +- [`development.js`](https://github.com/o1-labs/mina-rust-2/blob/develop/frontend/src/assets/environments/development.js) - + Development servers +- [`fuzzing.js`](https://github.com/o1-labs/mina-rust-2/blob/develop/frontend/src/assets/environments/fuzzing.js) - + Fuzzing tests +- [`local.js`](https://github.com/o1-labs/mina-rust-2/blob/develop/frontend/src/assets/environments/local.js) - + Local development +- [`producer.js`](https://github.com/o1-labs/mina-rust-2/blob/develop/frontend/src/assets/environments/producer.js) - + Block producer interface +- [`production.js`](https://github.com/o1-labs/mina-rust-2/blob/develop/frontend/src/assets/environments/production.js) - + Production deployment +- [`webnode.js`](https://github.com/o1-labs/mina-rust-2/blob/develop/frontend/src/assets/environments/webnode.js) - + WebNode integration + +For the most current environment configuration files, see the +[frontend/src/assets/environments](https://github.com/o1-labs/mina-rust-2/tree/develop/frontend/src/assets/environments) +directory in the develop branch. + +## Development workflow + +### Code formatting + +The project uses Prettier for consistent code formatting: + + + {FormatCode} + + +### Testing + +Run the Cypress test suite: + + + {RunTests} + + +For interactive testing: + +```bash +# Interactive test runner +make test +``` + +### Building for production + +Create an optimized production build: + +```bash +# Build with version update +make prebuild +make build-prod + +# Build with Sentry sourcemaps +make build-prod-sentry +``` + +### Serving production builds + +Test production builds locally: + +```bash +make build-prod +make start-bundle +``` + +## Project structure + +``` +frontend/ +├── src/ +│ ├── app/ # Angular application code +│ │ ├── core/ # Core services and utilities +│ │ ├── shared/ # Shared components and modules +│ │ ├── features/ # Feature modules +│ │ └── layout/ # Layout components +│ ├── assets/ # Static assets +│ │ └── environments/ # Environment configurations +│ ├── styles/ # Global styles +│ └── index.html # Main HTML template +├── cypress/ # E2E test specifications +├── scripts/ # Build and deployment scripts +├── Makefile # Build automation +├── angular.json # Angular CLI configuration +├── package.json # Node.js dependencies +└── tsconfig.json # TypeScript configuration +``` + +## Features + +### Real-time updates + +The frontend maintains WebSocket connections for real-time updates: + +- Block production events +- Network peer changes +- Transaction pool updates +- SNARK work completion diff --git a/website/docs/developers/frontend/webnode.mdx b/website/docs/developers/frontend/webnode.mdx new file mode 100644 index 000000000..b061035e1 --- /dev/null +++ b/website/docs/developers/frontend/webnode.mdx @@ -0,0 +1,82 @@ +--- +title: WebNode +description: Run a Mina node in your web browser using WebAssembly +sidebar_position: 4 +--- + +import CodeBlock from "@theme/CodeBlock"; + +# WebNode + +The WebNode is an experimental implementation of the Mina Rust node compiled to +WebAssembly, enabling users to run a fully functional Mina node directly in +their web browser. This groundbreaking approach eliminates the need for native +software installation and pushes the boundaries of decentralized infrastructure. + +## Overview + +WebNode leverages WebAssembly (WASM) technology to bring the full power of the +Mina Rust node to web browsers. This enables block production, transaction +validation, and network participation without traditional infrastructure +requirements. + +## Features + +- **Browser-based node** - Run a complete Mina node in Chrome, Firefox, or Edge +- **Block production** - Participate in consensus directly from your browser +- **P2P networking** - Connect to other nodes using WebRTC +- **State management** - Maintain blockchain state in browser storage +- **Zero installation** - No software installation or system configuration + required + +## Building WebNode + +Build the WebNode version of the frontend: + +```bash +cd frontend + +# Build with WebNode configuration +make build-webnodelocal +``` + + + +:::info Frontend Build Only + +These Makefile commands only build the frontend portion of the WebNode. The +WebAssembly module build is not included in these commands. + +::: + + + +## Running WebNode + +### Development Mode + +Start the WebNode development server: + +```bash +# Start WebNode locally +make start-webnodelocal +``` + +Access the WebNode at `http://localhost:4200` + +### Production Deployment + +Deploy WebNode to a web server: + +```bash +# Build for production +make build-webnodelocal + +# Deploy to static hosting +cp -r dist/frontend/browser/* /var/www/webnode/ +``` + +## Resources + +- [WebAssembly Documentation](https://webassembly.org/) +- [WebRTC Specification](https://www.w3.org/TR/webrtc/) diff --git a/website/docs/developers/scripts/frontend/build-development.sh b/website/docs/developers/scripts/frontend/build-development.sh new file mode 100755 index 000000000..397359517 --- /dev/null +++ b/website/docs/developers/scripts/frontend/build-development.sh @@ -0,0 +1,2 @@ +cd frontend +make build-development diff --git a/website/docs/developers/scripts/frontend/build-o1js-wrapper.sh b/website/docs/developers/scripts/frontend/build-o1js-wrapper.sh new file mode 100755 index 000000000..2d70231dc --- /dev/null +++ b/website/docs/developers/scripts/frontend/build-o1js-wrapper.sh @@ -0,0 +1,3 @@ +cd frontend/src/assets/o1js +npm install +npm run build-o1jswrapper diff --git a/website/docs/developers/scripts/frontend/build-production.sh b/website/docs/developers/scripts/frontend/build-production.sh new file mode 100755 index 000000000..95d2ebc41 --- /dev/null +++ b/website/docs/developers/scripts/frontend/build-production.sh @@ -0,0 +1,3 @@ +cd frontend +make prebuild +make build-prod diff --git a/website/docs/developers/scripts/frontend/format-code.sh b/website/docs/developers/scripts/frontend/format-code.sh new file mode 100755 index 000000000..4aa788357 --- /dev/null +++ b/website/docs/developers/scripts/frontend/format-code.sh @@ -0,0 +1,2 @@ +cd frontend +make prettify diff --git a/website/docs/developers/scripts/frontend/install-angular-cli.sh b/website/docs/developers/scripts/frontend/install-angular-cli.sh new file mode 100755 index 000000000..c52f50c90 --- /dev/null +++ b/website/docs/developers/scripts/frontend/install-angular-cli.sh @@ -0,0 +1,7 @@ +# Install Angular CLI globally +npm install -g @angular/cli@19.2.14 + +# Verify installation +npx ng version + +echo "Angular CLI installation complete!" diff --git a/website/docs/developers/scripts/frontend/install-dependencies.sh b/website/docs/developers/scripts/frontend/install-dependencies.sh new file mode 100755 index 000000000..5f8082a91 --- /dev/null +++ b/website/docs/developers/scripts/frontend/install-dependencies.sh @@ -0,0 +1,2 @@ +cd frontend +make install diff --git a/website/docs/developers/scripts/frontend/install-nodejs-linux.sh b/website/docs/developers/scripts/frontend/install-nodejs-linux.sh new file mode 100755 index 000000000..e422fcbbf --- /dev/null +++ b/website/docs/developers/scripts/frontend/install-nodejs-linux.sh @@ -0,0 +1,17 @@ +# Install nvm (if not already installed) +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash + +# Source nvm +export NVM_DIR="$HOME/.nvm" +[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" + +# Install Node.js +nvm install 23.1.0 +nvm use 23.1.0 +nvm alias default 23.1.0 + +# Verify installation +echo "Node.js version: $(node --version)" +echo "npm version: $(npm --version)" + +echo "Node.js installation complete!" diff --git a/website/docs/developers/scripts/frontend/install-nodejs-macos.sh b/website/docs/developers/scripts/frontend/install-nodejs-macos.sh new file mode 100755 index 000000000..bc146ef0e --- /dev/null +++ b/website/docs/developers/scripts/frontend/install-nodejs-macos.sh @@ -0,0 +1,11 @@ +# Install Node.js +brew install node@23 + +# Link the installed version +brew link --overwrite node@23 + +# Verify installation +echo "Node.js version: $(node --version)" +echo "npm version: $(npm --version)" + +echo "Node.js installation complete!" diff --git a/website/docs/developers/scripts/frontend/run-tests.sh b/website/docs/developers/scripts/frontend/run-tests.sh new file mode 100755 index 000000000..c9fe4749c --- /dev/null +++ b/website/docs/developers/scripts/frontend/run-tests.sh @@ -0,0 +1,2 @@ +cd frontend +make test-headless diff --git a/website/docs/developers/scripts/frontend/start-development.sh b/website/docs/developers/scripts/frontend/start-development.sh new file mode 100755 index 000000000..3b98742e4 --- /dev/null +++ b/website/docs/developers/scripts/frontend/start-development.sh @@ -0,0 +1,2 @@ +cd frontend +make start diff --git a/website/sidebars.ts b/website/sidebars.ts index dcd3d33e8..9b577948c 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -90,6 +90,16 @@ const sidebars: SidebarsConfig = { 'developers/archive-database-queries', ], }, + { + type: 'category', + label: 'Frontend', + items: [ + 'developers/frontend/index', + 'developers/frontend/node-dashboard', + 'developers/frontend/leaderboard', + 'developers/frontend/webnode', + ], + }, { type: 'category', label: 'Docker',