GitHub - open-web3-stack/PVQ: Cross-Consensus Query Language for Polkadot

PVQ: PolkaVM Query

PVQ is a unified query interface that bridges different chain runtime implementations and client tools/UIs. PVQ provides an extension-based system where runtime developers can expose chain-specific functionality through standardized interfaces, while allowing client-side developers to perform custom computations on the data through PolkaVM programs. By abstracting away concrete implementations across chains and supporting both off-chain and cross-chain scenarios, PVQ aims to reduce code duplication and development complexity while maintaining flexibility for custom use cases.

✨ 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 functions from multiple pallets

🏗️ 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	Guest programs written in Rust that compile to RISC-V
PVQ Executor	Host-side component managing PolkaVM instances and runtime interaction
PVQ Extensions	Modular system exposing runtime functionalities to guest programs
PVQ Runtime API	Substrate runtime API for external query submission
PVQ Primitives	Common types and utilities shared across components

Available Example Extensions

Core Extension: Fundamental functionalities and extension discovery
Fungibles Extension: Asset querying, balances, and metadata
Swap Extension: DEX interactions, liquidity pools, and price quotes

🚀 Getting Started

Prerequisites

Ensure you have the following installed:

Rust (latest stable version)
Git with submodule support

Installation

Clone the repository with submodules:

git clone --recursive https://github.com/open-web3-stack/PVQ.git
cd PVQ

Install required tools:

This installs polkatool for ELF to PolkaVM blob conversion and chain-spec-builder.
Build the project:

Quick Start

Running Example Programs

Build guest programs:

Run a test program:

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

Start local test chain:

Build and test programs:

make guests
cargo run -p pvq-test-runner -- --program output/guest-total-supply

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

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

use pvq_extension::extension_decl;

#[extension_decl]
pub trait MyCustomExtension {
    fn my_query() -> String;
}