rewrite docs with hallucinations

Author: mise42

poc/runtime/README.md

@@ -1,252 +1,20 @@
 # PVQ PoC Runtime
 
-<!-- generated by polka.codes -->
+FRAME runtime demonstrating PVQ integration used in this repository.
 
-A proof-of-concept Substrate runtime demonstrating PVQ (PolkaVM Query) system integration. This runtime serves as a testing environment and reference implementation for integrating PVQ capabilities into Substrate-based blockchains.
+### What it exposes
 
-## Overview
+- Runtime API `PvqApi` with two methods:
+  - `execute_query(...)`: runs a PVQ program with input bytes and an optional gas limit; if not provided, a default ~2s limit is applied.
+  - `metadata()`: returns serialized extension metadata bytes (portable type registry + extension functions).
 
-This PoC runtime showcases how to:
-- Integrate the `PvqApi` runtime API into a Substrate runtime
-- Configure PVQ extensions for runtime interaction
-- Provide a development environment for testing PVQ queries
-- Demonstrate best practices for PVQ integration
+### How it’s wired
 
-## Features
+- Uses the generated `extensions` module to connect extension traits to runtime pallets.
+- Executes programs via `ExtensionsExecutor` with invocation source set to runtime API.
 
-- 🏗️ **Complete Runtime**: Full Substrate runtime with PVQ integration
-- 🔌 **Extension Support**: Pre-configured with core PVQ extensions
-- 🧪 **Testing Ready**: Optimized for development and testing workflows
-- 📡 **Chopsticks Compatible**: Works with Chopsticks for local development
-- ⚙️ **Configurable**: Easy to modify and extend for custom use cases
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────┐
-│                PoC Runtime                      │
-├─────────────────────────────────────────────────┤
-│  Standard Pallets          │  PVQ Integration   │
-│  ├─ Balances              │  ├─ PvqApi         │
-│  ├─ Assets                │  ├─ Extensions     │
-│  ├─ Timestamp             │  └─ Executor       │
-│  ├─ Transaction Payment   │                    │
-│  └─ Sudo                  │                    │
-└─────────────────────────────────────────────────┘
-```
-
-## Runtime Components
-
-### Standard Pallets
-
-| Pallet | Purpose |
-|--------|---------|
-| **Balances** | Native token balance management |
-| **Assets** | Multi-asset support for fungible tokens |
-| **Timestamp** | Block timestamp functionality |
-| **Transaction Payment** | Fee calculation and payment |
-| **Sudo** | Privileged operations for testing |
-
-### PVQ Integration
-
-| Component | Purpose |
-|-----------|---------|
-| **PvqApi** | Runtime API for executing PVQ queries |
-| **Extensions** | Configured extensions (core, fungibles, swap) |
-| **Executor** | PVQ program execution environment |
-
-## Getting Started
-
-### Prerequisites
-
-- Rust toolchain (stable)
-- PVQ project dependencies
-- Chopsticks (for local development)
-
-### Building the Runtime
-
-```bash
-# Build the runtime
-cargo build -p poc-runtime --release
-
-# The compiled WASM runtime will be available in target/release/wbuild/
-```
-
-### Running with Chopsticks
-
-1. **Start the local development chain:**
-   ```bash
-   make run
-   ```
-
-2. **The runtime will be available at:**
-   - HTTP RPC: `http://localhost:8000`
-   - WebSocket: `ws://localhost:8000`
-
-### Testing PVQ Integration
-
-1. **Build guest programs:**
-   ```bash
-   make guests
-   ```
-
-2. **Test with PVQ runner:**
-   ```bash
-   cargo run -p pvq-test-runner -- --program output/guest-total-supply
-   ```
-
-3. **Use with Polkadot JS UI:**
-   - Connect to `ws://localhost:8000`
-   - Navigate to Developer → Extrinsics → pvq → executeQuery
-   - Upload program blob and arguments
-
-## Configuration
-
-### Chopsticks Configuration
-
-The runtime includes a `chopsticks.yml` configuration file:
-
-```yaml
-endpoint: wss://acala-rpc-0.aca-api.network
-block: latest
-runtime-log-level: 5
-```
-
-### Runtime Parameters
-
-Key runtime configurations:
-
-```rust
-// Maximum execution time for PVQ queries
-pub const MAX_EXECUTION_TIME: u64 = 10_000; // 10 seconds
-
-// Maximum memory allocation for guest programs
-pub const MAX_MEMORY: u32 = 16 * 1024 * 1024; // 16MB
-
-// Supported extensions
-pub const EXTENSIONS: &[&str] = &["core", "fungibles", "swap"];
-```
-
-## Development Workflow
-
-### Adding New Pallets
-
-1. **Add dependency to `Cargo.toml`:**
-   ```toml
-   my-custom-pallet = { version = "1.0.0", default-features = false }
-   ```
-
-2. **Configure in `lib.rs`:**
-   ```rust
-   impl my_custom_pallet::Config for Runtime {
-       // Configuration here
-   }
-   ```
-
-3. **Add to runtime construction:**
-   ```rust
-   construct_runtime!(
-       pub struct Runtime {
-           // ... existing pallets
-           MyCustomPallet: my_custom_pallet,
-       }
-   );
-   ```
-
-### Adding PVQ Extensions
-
-1. **Add extension dependency:**
-   ```toml
-   my-pvq-extension = { path = "../my-pvq-extension" }
-   ```
-
-2. **Configure in PVQ setup:**
-   ```rust
-   use my_pvq_extension::ExtensionMyCustom;
-
-   // Add to extensions list
-   ```
-
-### Testing Changes
+### Build
 
 ```bash
-# Build and test
-cargo build -p poc-runtime
-make run
-
-# Test with guest programs
-cargo run -p pvq-test-runner -- --program output/guest-example
-```
-
-## API Reference
-
-### PVQ Runtime API
-
-The runtime exposes the following PVQ API methods:
-
-#### `execute_query(program: Vec<u8>, args: Vec<u8>) -> Vec<u8>`
-
-Executes a PVQ program with the provided arguments.
-
-**Parameters:**
-- `program`: Compiled PVQ program blob
-- `args`: Serialized input arguments
-
-**Returns:** Serialized query results
-
-#### `metadata() -> Vec<u8>`
-
-Returns metadata about available PVQ extensions and capabilities.
-
-**Returns:** Serialized metadata information
-
-### Extension APIs
-
-All standard PVQ extensions are available:
-
-- **Core Extension**: Basic functionality and extension discovery
-- **Fungibles Extension**: Asset queries and balance information
-- **Swap Extension**: DEX interactions and liquidity data
-
-## Troubleshooting
-
-### Common Issues
-
-**Runtime doesn't build:**
-```bash
-# Clean and rebuild
-cargo clean
 cargo build -p poc-runtime --release
 ```
-
-**Chopsticks connection fails:**
-```bash
-# Check if the endpoint is accessible
-curl -X POST -H "Content-Type: application/json" \
-  --data '{"jsonrpc":"2.0","method":"system_name","id":1}' \
-  http://localhost:8000
-```
-
-**PVQ queries fail:**
-- Ensure guest programs are compiled correctly
-- Check that required extensions are configured
-- Verify argument serialization format
-
-### Debug Mode
-
-Enable debug logging:
-
-```bash
-RUST_LOG=debug cargo run -p pvq-test-runner -- --program output/guest-example
-```
-
-## Related Components
-
-- [PVQ Executor](../pvq-executor/) - Core execution engine
-- [PVQ Runtime API](../pvq-runtime-api/) - API definitions
-- [PVQ Extensions](../pvq-extension/) - Extension system
-- [Guest Examples](../guest-examples/) - Example programs
-
----
-
-*This PoC runtime demonstrates PVQ integration patterns and serves as a foundation for production implementations.*