Dear Polkadot Community,

We are pleased to present our proposal for retroactive funding for the Polkadot Virtual Machine (PVM) Debugger, a tool designed to streamline the development and validation of PVM implementations. This open-source debugger offers key functionalities such as breakpoints, memory inspection, and parallel execution across multiple PVM clients, enabling developers to identify discrepancies and ensure alignment with formal specifications.

The PVM Debugger was created to address the lack of specialized tools for debugging and validating PVM programs. By providing detailed insights into program execution and memory states, it aims to enhance development efficiency and improve the robustness of PVM implementations across the Polkadot ecosystem.

Full proposal text: https://docs.google.com/document/d/1plq5C0kdMMuHscGNqnhvw0TebqXLZXQsIfqcbVLf-6M

General Project Information

Project Category / Type: Software development
Proponent: FluffyLabs.dev
USDT address: 15fGrDWmFoaApnZXEw1Zg45zuCqpkbMS9YPzczeU9dHseUUu
Requested allocation: 16.000 USD
Income taxable: 19% tax on “virtual currencies” tax in Poland: https://www.podatki.gov.pl/en/your-e-pit/pit-38-for-2022/
Discussion date: 24th November 2024
Onchain publish date: scheduled for 5th December 2024
Previous treasury proposals: none

Context

The JAM (Join-Accumulate Machine) prize is a Polkadot initiative that encourages teams to develop diverse implementations of the new iteration of Polkadot network proposed by Gavin Wood. As part of the implementation of the JAM protocol, teams need to implement the Polkadot Virtual Machine (PVM) which is responsible for execution of the state transition of underlying services. This implementation diversity is essential for ensuring the Polkadot network remains flexible, secure, and resilient. However, building these various PVM implementations introduces significant technical challenges, particularly around debugging and analyzing the behavior of PVM programs across different client implementations.

Our team is one of the participants in the JAM prize, focusing on creating a robust PVM interpreter. During our work, we realized the need for a specialized tool to streamline debugging and validation processes. Standard debugging tools did not provide the level of insight required to efficiently inspect program execution, memory usage, and register interactions within the PVM.

To address this, we developed the PVM Disassembler & Debugger (https://pvm.fluffylabs.dev) specifically tailored for the JAM ecosystem. The tool includes a machine code and assembly view, allowing developers to inspect the PVM programs at a low level. After plugging in one of many possible PVM interpreter implementations, it also offers key debugging features such as step-over functionality, breakpoints, and memory inspection, giving developers a detailed view of program behavior during execution.A significant potential benefit of the debugger is its ability to validate programs simultaneously across multiple PVM implementations, helping teams participating in the JAM prize identify discrepancies and improve client interoperability.

While the tool was initially created for our own development purposes, we recognized its value for the broader Polkadot community and have decided to open-source it. This will allow other teams to use the debugger for cross-client validation and debugging, accelerating their development process and ensuring the robustness of their PVM implementations.

Problem

The development of diverse Polkadot Virtual Machine (PVM) implementations, as encouraged by the JAM prize, introduces significant technical challenges. Developers might struggle with debugging and validating PVM programs across different implementations, lacking tools to gain deep insights into program execution, memory states, and discrepancies between clients. This slows down development and increases the risk of bugs going undetected.

Additionally, we believe the PVM Disassembler & Debugger will serve a greater educational purpose of introducing a new wave of developers that are going to build Services on top of JAM. With references to Gray Paper definitions of instructions we strive to make it easier to understand in depth the complexity of PVM’s formal specification.

While our current main focus is creating a tool that would serve JAM implementers, with a proposal Solidity smart contracts running on top of PolkaVM on Asset Hub: https://forum.polkadot.network/t/contracts-update-solidity-on-polkavm/6949, the PVM Disassembler & Debugger might prove itself useful much wider.

Proposal

We propose retroactive funding of the PVM Disassembler & Debugger aimed at supporting the implementers of Polkadot Virtual Machine (PVM) interpreters as part of the JAM prize. The tool addresses the complexities and technical challenges developers face when debugging and validating PVM programs. Our goal is to provide a robust solution that helps developers better understand program execution, identify discrepancies between multiple PVM implementations, and align with the formal specifications in the Gray Paper.

By creating this open-source debugger, we aimed to not only solve immediate development issues but also contribute to the long-term robustness of the Polkadot/JAM ecosystem by promoting client diversity, enhancing the overall quality of PVM implementations and helping the builders of programs running on top of the PVM.

Please note that the JAM prize or other funding mechanisms do not cover tooling for JAM. The JAM prize focuses on client implementations but does not cover the development of ecosystem tools such as debuggers, which benefit all participants. This is why we are submitting this proposal directly to the treasury and the Polkadot ecosystem.

Available solutions

While RISC-V debuggers exist, there is no dedicated debugger for PVM currently available. Even if one existed, it would probably not support running a program in parallel across multiple PVM implementations, which is crucial for identifying discrepancies in client behavior—something that traditional debugging tools cannot achieve in a standard debugging setup. This project aims to fill that gap with a PVM-specific debugger tailored to the unique requirements of the JAM ecosystem.

Scope of work

The PVM Debugger (https://pvm.fluffylabs.dev) initial version 1.0 has been completed, providing a basic range of functionalities to support PVM client implementations in the Polkadot ecosystem. Below is an outline of the key deliverables and functionalities. The deliverable is under Mozilla Public License (MPL-2.0) license.

Deliverables

1. TypeScript and React.js-based UI and Debugger Logic: A responsive and intuitive user interface built with TypeScript and React.js, facilitating easy interaction with debugging features.
2. Example Integration with Dummy Rust PVM: A demonstration of how the debugger integrates with a Rust-based PVM implementation using WebAssembly (Wasm) - https://github.com/FluffyLabs/pvm-shell
3. Integration with typeberry’s PVM implementation (TypeScript) - https://www.npmjs.com/package/@typeberry/pvm
4. Integration with PolkaVM reference implementation (Rust) - https://github.com/tomusdrw/polkavm/tree/master/pvm-shell
5. Integration with Gosamer’s team PVM implementation (Go)
6. Open Source Code: The full codebase is publicly available on GitHub (https://github.com/FluffyLabs/pvm-debugger), allowing other developers to use and extend the tool.

Key Functionalities

1. Step-Over & Breakpoints: Developers can control program flow, setting breakpoints and stepping over instructions.
2. Memory & Register Inspector: View memory and register states in real-time during program execution.
3. Machine Code / Assembly View: Offers a side-by-side display of machine code and assembly to help trace execution flow.
4. Parallel Execution of Multiple PVM Clients: Run PVM programs across various implementations to detect discrepancies.
5. Integrated Assembler: A built-in assembler that allows for easy assembly-level debugging and execution.
6. Hex/Dec Mode: Switch between hexadecimal and decimal representations of data for easier inspection and analysis.
7. Import JAM Test Vectors: Support for importing JAM test vectors to test and validate PVM implementations.
8. Pre-Built Examples: Includes sample programs like the Fibonacci sequence, add instruction, and branch instruction to help developers understand core functionality.
9. Glossary of PVM Operations: Integrated glossary referencing PVM specifications from the Gray Paper, helping developers quickly understand PVM operations and their implementations.
10. This set of functionalities makes the PVM Debugger a comprehensive and essential tool for anyone developing or validating Polkadot Virtual Machine implementations. The project is now publicly available for the community on GitHub (https://github.com/FluffyLabs/pvm-debugger).

Ensuring Adoption and Onboarding Support for the PVM Debugger

For information on Adoption and Onboarding, please refer to “Detailed proposal: Scope of work > Ensuring Adoption and Onboarding Support for the PVM Debugger”

Timeline

For timeline details, please refer to “Detailed proposal: Timeline”

Budget

**Total Budget
**Developer Hours: 140 hours × $100/hour = $14,000
Product Management Hours: 20 hours × $100/hour = $2,000
Total: $16,000 (16,000 USDT)

This budget represents the full scope of work required to develop and deliver the open-source PVM Debugger, which is now available for the Polkadot and JAM communities.

For full budget breakdown, please refer to “Detailed proposal: Budget”

Payment condition

For payment conditions details, please refer to “Detailed proposal: Payment Conditions”

Key deliverables

1. Software

• Open-source PVM Debugger: Fully functional debugging tool with core features such as step-over, breakpoints, memory and register inspection, machine code/assembly view, integrated assembler, and support for parallel execution across multiple PVM implementations.
• TypeScript and React.js UI: User interface allowing easy interaction with PVM programs.
• Wasm Integration: Example integration with a dummy Rust PVM via WebAssembly.
• Glossary of PVM Operations: A built-in reference guide aligned with the PVM specifications in the JAM Gray Paper.
• Integration of three PVM implementations

typeberry’s PVM implementation (TypeScript)
PolkaVM reference implementation (Rust)
Gosamer’s team PVM implementation (Go)

2. Code Repository

GitHub Repository: The complete source code for the debugger has been made available in a public repository (https://github.com/FluffyLabs/pvm-debugger), providing full transparency and allowing further community development.

Objectives / Success criteria

The success of the PVM Debugger project will be measured based on several key criteria focused on its adoption and utility within the Polkadot and JAM communities. These criteria will help determine if the project has met its objectives and if the final deliverable is satisfactory:

1. Adoption by Other JAM Teams

• Objective: The debugger will be used by other JAM prize participants to debug and validate their PVM implementations.
• Success Criteria: At least three different PVM implementations are integrated into the PVM Debugger

2. Community Feedback

• Objective: Gain positive feedback from the Polkadot and JAM communities regarding the debugger’s utility and ease of use.
• Success Criteria: Positive feedback from at least two JAM prize teams, with discussions in Polkadot forums or developer channels highlighting the debugger's value.

These success criteria will confirm that the PVM Debugger is an effective tool that serves its intended purpose of improving PVM implementation and debugging within the Polkadot ecosystem.

Known constraints

As we continue to expand the PVM Debugger by integrating additional PVM implementations, there are some known constraints that may affect future efforts:

1. Integration Complexity: Further integration of PVMs, may require additional development time and resources. Managing the technical complexity of supporting new implementations could influence the timeline for integrating new PVMs.
2. Coordination with Other JAM Teams: Future integrations may depend on testing and feedback from other JAM prize teams. Delays in receiving feedback or coordinating external testing could affect the speed of further integrations.
3. No Prior Funding: The project has not been previously funded, ensuring no conflict of interest with other proposals or ongoing projects.

These constraints will be considered when expanding the debugger to support additional PVM implementations.

Reporting

Since the PVM Debugger project is already completed and this proposal seeks retroactive funding, there is no need for ongoing reporting related to the development process. However, the history of commits and progress can be fully tracked and reviewed on GitHub, providing full transparency on the project's timeline and milestones.

Should any future updates or enhancements be made, relevant information will be shared through appropriate channels, such as GitHub or Polkadot community forums.

Communication strategy

1. For the PVM Debugger, ongoing communication with the community will primarily be managed through GitHub and other Polkadot-related channels. The following outlines how the team will present information, engage with the community, and handle feedback.
2. Channels for Communication:

• GitHub Issues: For bug reports, feature requests, and general issues, community members can create and track issues via GitHub Issues. This will be the primary channel for technical discussions and development tracking.
• Polkassembly: Updates, feedback, and larger announcements will be shared with the Polkadot community via Polkassembly posts.
• Element: For real-time communication, the project team will participate in relevant JAM-related Element channels to engage with users, answer questions, and provide updates.

Contact Information:
Team Member: Piotr Zwolinski
Email: piotr@fluffylabs.dev
Element: @tomusdrw:matrix.org

Team

The PVM Debugger was built by the FluffyLabs team, a group involved in the development of decentralized tools for the Polkadot ecosystem:

1. Tomasz Drwięga
2. Piotr Zwolinski
3. Wojciech Kwiatek
4. Krystian Fras
5. Mateusz Sikora

For full team members details, please refer to “Detailed proposal: Team”

Why Polkadot

The Polkadot ecosystem is a cutting-edge of blockchain innovation that builds trustless, privacy-preserving solutions, which are the foundations of Web3.0. JAM, as an important next step for Polkadot development, stands as a crucial initiative to make that vision happen. Our values are fully aligned and we are seeing an opportunity to build the development tooling for JAM as early as possible to make sure we are ready to get wider developer adoption of the protocol.

Comments, Qs&As

How does the PVM Debugger benefit teams beyond the JAM prize? Since the PVM is going to be an execution bedrock of future JAM services, we hope that the PVM Debugger (and its future iterations) will help not only the JAM implementers, but also the developers building services on top of JAM. Moreover, given the proposal to have Solidity Smart Contracts on PVM running on Asset Hub (https://forum.polkadot.network/t/contracts-update-solidity-on-polkavm/6949) we are considering to support more specialized debugging primitives for such contracts (like supporting debug symbols or the required host calls - cross contract calls, storage, etc).

Why are you requesting retroactive funding instead of building this under the JAM prize? The JAM prize focuses on client implementations but does not cover the development of ecosystem tools like e.g. debuggers, which benefit all participants. We developed the PVM Debugger to solve problems that arose during our own implementation and are now making it available to the entire community. Retroactive funding allows us to recover the costs of building this tool and ensures that it remains freely available and open-source.

Will there be further development of the PVM Debugger? While this proposal is specifically for retroactive funding, we are going to continue developing the PVM Debugger to add more features and integrations in the future. However, these future developments are independent from the current funding request.

How will you ensure that the debugger remains relevant as Polkadot evolves? The PVM Debugger is built to be flexible, allowing integration with new PVM implementations as they emerge. By keeping the tool open-source, we also invite contributions from the wider developer community to help ensure it remains relevant and aligned with Polkadot’s ongoing development.

Your feedback

We welcome feedback and suggestions from the Polkadot community to ensure the PVM Debugger meets the needs of developers and contributes effectively to the ecosystem. Your insights will help us refine the tool, prioritize future features, and maximize its impact. Please share your thoughts on Polkassembly or reach out to us directly through the provided channels. We look forward to collaborating with you to strengthen the Polkadot ecosystem together!