update readme

Author: xlc

README.md

@@ -1,30 +1,245 @@
-# PVQ
+# PVQ: PolkaVM Query System for Polkadot
 
-PolkaVM Query for Polkadot
+<!-- generated by polka.codes -->
 
-## Getting Started
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Rust](https://github.com/open-web3-stack/PVQ/workflows/Rust/badge.svg)](https://github.com/open-web3-stack/PVQ/actions)
+
+A powerful and secure query system for Polkadot parachains that enables developers to write expressive, sandboxed guest programs using PolkaVM. PVQ provides a safe and efficient alternative to custom RPC endpoints for runtime data queries.
+
+## ✨ Features
+
+- **🔒 Secure Execution**: Sandboxed PolkaVM environment for safe query execution
+- **🧩 Modular Extensions**: Extensible system for exposing runtime functionalities
+- **⚡ High Performance**: Efficient RISC-V execution with minimal overhead
+- **🛠️ Developer Friendly**: Rust-first development experience with procedural macros
+- **🌐 Runtime Integration**: Seamless integration with Substrate runtimes
+- **🔍 Rich Querying**: Support for complex queries involving multiple runtime components
+
+## 🏗️ Architecture
+
+The PVQ system consists of several interconnected components:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   PVQ Program   │───▶│  PVQ Executor   │───▶│ Substrate       │
+│  (Guest Code)   │    │   (Host Side)   │    │ Runtime         │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                       │                       │
+         │              ┌─────────────────┐              │
+         └─────────────▶│ PVQ Extensions  │◀─────────────┘
+                        │   (Modules)     │
+                        └─────────────────┘
+```
+
+### Core Components
+
+| Component | Description |
+|-----------|-------------|
+| **[PVQ Program](pvq-program/)** | Guest programs written in Rust that compile to RISC-V |
+| **[PVQ Executor](pvq-executor/)** | Host-side component managing PolkaVM instances and runtime interaction |
+| **[PVQ Extensions](pvq-extension/)** | Modular system exposing runtime functionalities to guest programs |
+| **[PVQ Runtime API](pvq-runtime-api/)** | Substrate runtime API for external query submission |
+| **[PVQ Primitives](pvq-primitives/)** | Common types and utilities shared across components |
+
+### Available Extensions
+
+- **[Core Extension](pvq-extension-core/)**: Fundamental functionalities and extension discovery
+- **[Fungibles Extension](pvq-extension-fungibles/)**: Asset querying, balances, and metadata
+- **[Swap Extension](pvq-extension-swap/)**: DEX interactions, liquidity pools, and price quotes
+
+## 🚀 Getting Started
 
 ### Prerequisites
 
-- Pull vendored `polkavm`: `git submodule update --init --recursive`.
-- Install `polkatool` (for relinking the standard RV32E ELF to a PolkaVM blob) and `chain-spec-builder` (for building chainspec from a wasm): `make tools`
+Ensure you have the following installed:
+
+- **Rust** (latest stable version)
+- **Git** with submodule support
+
+### Installation
+
+1. **Clone the repository with submodules:**
+   ```bash
+   git clone --recursive https://github.com/open-web3-stack/PVQ.git
+   cd PVQ
+   ```
+
+2. **Install required tools:**
+   ```bash
+   make tools
+   ```
+   This installs `polkatool` for ELF to PolkaVM blob conversion and `chain-spec-builder`.
+
+3. **Build the project:**
+   ```bash
+   cargo build --release
+   ```
+
+### Quick Start
+
+#### Running Example Programs
+
+1. **Build guest programs:**
+   ```bash
+   make guests
+   ```
+
+2. **Run a test program:**
+   ```bash
+   cargo run -p pvq-test-runner -- --program output/guest-sum-balance
+   ```
+
+#### Available Example Programs
+
+| Program | Description |
+|---------|-------------|
+| `guest-sum-balance` | Sum balances of multiple accounts |
+| `guest-total-supply` | Get total supply of an asset |
+| `guest-sum-balance-percent` | Calculate percentage of total supply for account balances |
+| `guest-swap-info` | Query DEX/swap information |
+
+### Runtime Integration
+
+#### Testing with PoC Runtime
+
+1. **Start local test chain:**
+   ```bash
+   make run
+   ```
+
+2. **Build and test programs:**
+   ```bash
+   make guests
+   cargo run -p pvq-test-runner -- --program output/guest-total-supply
+   ```
+
+3. **Use with Polkadot JS UI:**
+   - Copy the hex-encoded `args` from test runner logs
+   - Upload program and arguments through the PJS UI
+
+## 📖 Documentation
+
+### Writing Your First PVQ Program
+
+```rust
+use pvq_program::program;
+use pvq_extension_fungibles::ExtensionFungibles;
+
+#[program]
+fn query_balance(account: [u8; 32], asset_id: u32) -> u128 {
+    ExtensionFungibles::balance(asset_id, &account)
+}
+```
+
+### Creating Custom Extensions
+
+```rust
+use pvq_extension::extension_decl;
+
+#[extension_decl]
+pub trait MyCustomExtension {
+    fn my_query() -> String;
+}
+```
+
+### Component Documentation
+
+- 📚 **[Development Guide](docs/development.md)** - Comprehensive development setup
+- 🔧 **[Extension Development](docs/extensions.md)** - Creating custom extensions  
+- 🏗️ **[Architecture Deep Dive](docs/architecture.md)** - System design and internals
+- 📋 **[API Reference](docs/api.md)** - Complete API documentation
+
+## 🛠️ Development
+
+### Project Structure
+
+```
+PVQ/
+├── poc/runtime/              # PoC Substrate runtime
+├── pvq-program/              # Program macro and utilities
+├── pvq-executor/             # Core execution engine
+├── pvq-extension*/           # Extension system and implementations
+├── pvq-runtime-api/          # Runtime API definition
+├── pvq-test-runner/          # Testing utilities
+├── guest-examples/           # Example programs
+└── vendor/polkavm/           # Vendored PolkaVM dependency
+```
+
+### Building from Source
+
+```bash
+# Development build
+cargo build
+
+# Release build with optimizations
+cargo build --release
+
+# Build guest examples
+make guests
+
+# Run all tests
+cargo test --all
+
+# Run clippy lints
+cargo clippy --all --all-targets
+```
+
+### Testing
+
+```bash
+# Run unit tests
+cargo test
+
+# Run integration tests
+cargo test --test integration
+
+# Test specific component
+cargo test -p pvq-executor
+
+# Run example programs
+make test-guests
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes and add tests
+4. Ensure all tests pass (`cargo test --all`)
+5. Run formatting (`cargo fmt`) and linting (`cargo clippy`)
+6. Commit your changes (`git commit -am 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+### Code Style
+
+- Follow Rust standard formatting (`cargo fmt`)
+- Ensure clippy passes (`cargo clippy`)
+- Add comprehensive tests for new features
+- Document public APIs with rustdoc comments
+
+## 📄 License
 
-### Run Examples
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
 
-`guest-examples` contains several guest programs to test the PVQ.
+## 🙏 Acknowledgments
 
-1. Build guest program: `make guests`
-2. Run test runner: `cargo run -p pvq-test-runner -- --program output/<guest-program>`
+- [PolkaVM](https://github.com/koute/polkavm) - The underlying virtual machine
+- [Substrate](https://substrate.io/) - The blockchain development framework
+- [Polkadot](https://polkadot.network/) - The multi-chain protocol
 
-Available PoC guest programs:
+## 🔗 Links
 
-- `guest-sum-balance`: sum the balances of multiple accounts
-- `guest-total-supply`: get the total supply of an asset
-- `guest-sum-balance-percent`: sum the balances of multiple accounts and calculate the percentage of the total supply
+- 🌐 **Homepage**: [https://acala.network](https://acala.network)
+- 📖 **Documentation**: [https://docs.pvq.dev](https://docs.pvq.dev)
+- 💬 **Discord**: [Join our community](https://discord.gg/acala)
+- 🐦 **Twitter**: [@AcalaNetwork](https://twitter.com/AcalaNetwork)
 
-### RuntimeAPI PoC
+---
 
-1. Use chopsticks to start a local chain with the RuntimeAPI enabled: `make run`
-2. Build guest programs: `make guests`
-3. Run test runner to display hex-encoded `args` in tracing logs: `cargo run -p pvq-test-runner -- --program output/<guest-program>`
-4. Upload `program` and `args` in PJS UI.
+**Built with ❤️ by the Acala team**