-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
ab39286
commit dea04a0
Showing
1 changed file
with
243 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,243 @@ | ||
| # polka.run - PolkaVM Disassembler | ||
|
|
||
| * **Proposers:** [Rotko Networks](https://rotko.net) | ||
| * **Payment Address:** 1Qrotkokp6taAeLThuwgzR7Mu3YQonZohwrzixwGnrD1QDT | ||
|
|
||
| ## Project Overview | ||
|
|
||
| ### Overview | ||
|
|
||
| polka.run aims to be a premier website offering web tools designed to demystify PolkaVM bytecode. | ||
| The cornerstone of this suite is a disassembler GUI, enabling users to convert .polkavm binary | ||
| files into human-readable formats. | ||
|
|
||
| ### Key Features | ||
|
|
||
| - Ability to read binary data in both HEX and ASCII formats. | ||
| - A robust disassembler that translates binary data into RISC-V assembly instructions. | ||
| - A user-friendly GUI, ensuring easy interaction and navigation for various skill levels. | ||
| - Do processing as much as possible in the client-side. | ||
|
|
||
| ### Benefits | ||
|
|
||
| - Facilitates a deeper understanding of PolkaVM bytecode, making it accessible to a broader audience. | ||
| - Enhances the debugging and development process for PolkaVM-based smart contracts. | ||
| - Encourages innovation and experimentation within the PolkaVM ecosystem by lowering the barrier to entry. | ||
| - Supports the growth of the PolkaVM community by providing essential development tools. | ||
|
|
||
| ### Challenges | ||
| - Keep it performant and responsive to be able to handle large files like doom.polkavm(1.1Mb), | ||
| while code is running in the client-side browser. | ||
| - Loading a lot of html elements gets the browser, so we need to find a way to load only the visible | ||
| elements and load more dynamicly as the user interacts with the interface. | ||
| - Make it easy to use even for new developers to learn riscv32e instructions | ||
| without forking repositories and running code locally. | ||
| - Frontend development with Rust is still extremely cutting edge and leptos as a framework is still | ||
| in its infancy. This will cause development be done in a slower pace than we are used to due | ||
| to the [tooling not being as mature](https://youtrack.jetbrains.com/issue/RUST-11857/RustRover-Failing-to-Find-Methods-Autocompletions-in-Leptos-RSX-fileRust-with-HTML-inside-macros) as we would like it to be. | ||
| - Working with alpha level upstream as dependency, means that we will have to be prepared to be alert | ||
| for breaking changes and be ready to adapt to them. Also building too fancy features on top of | ||
| upstream might be risky, as they might change in the future. | ||
| - PolkaVM does not have any documentation yet, so we will have to rely on the source code. | ||
|
|
||
| ### Tech stack | ||
|
|
||
| #### frontend: | ||
| - [leptos](https://leptos.dev) - Rust frontend framework | ||
| - [UnoCSS](https://unocss.dev) - CSS engine | ||
| - [leptos-use](https://leptos-use.rs/) - Rust frontend state management | ||
|
|
||
| #### client-side backend: | ||
| - [rustlang](https://www.rust-lang.org/) | ||
| - [polkavm](https://github.com/koute/polkavm) - bytecode parser | ||
| - [gloo-worker](https://github.com/rustwasm/gloo/tree/master/gloo-worker) - WebWorkers | ||
| - [web_sys](https://rustwasm.github.io/wasm-bindgen/api/web_sys/) - wasm bindings for browser API's | ||
| - [rexie](https://) - IndexedDB wrapper | ||
|
|
||
| ### Development Plan | ||
|
|
||
| #### [x] Phase 1: Research and Design | ||
|
|
||
| - **Research on PolkaVM Bytecode:** Conduct an in-depth study of PolkaVM bytecode specifications to understand the technical requirements. | ||
| - **Tech Stack Selection:** Choose the appropriate technology stack based on research findings and project needs. | ||
| - **GUI Design:** Design a user-friendly and functional Graphical User Interface (GUI), drawing inspiration from PE-bear’s structure to enhance usability. | ||
|
|
||
| #### [x] Phase 2: Development of prototype | ||
|
|
||
| - **Prototype Development:** Build a prototype to test the core functionalities including: | ||
| - Integration of the upstream PolkaVM to parse for assembly instructions. | ||
| - Incorporation of client-side file upload and processing mechanisms. | ||
| - Implementation of UI to show memorydump in offset, HEX and ASCII. | ||
| - Development of a graphical representation of disassembled instructions with offset and HEX. | ||
|
|
||
| #### Phase 3: Backend Development (Client-Side Data Management and Processing) | ||
|
|
||
| 1. **Setup and Dependencies:** | ||
| - Integrate Rexie for efficient IndexedDB interactions, setting up a robust | ||
| client-side database environment. | ||
| - Define a detailed IndexedDB schema for storing `.polkavm` files. | ||
|
|
||
| 2. **IndexedDB Data Management:** | ||
| - Develop efficient read/write functions using `web_sys::FileReader` for IndexedDB. | ||
| - Implement pagination within IndexedDB to manage large data sets effectively. | ||
|
|
||
| 3. **Chunk-based Processing:** | ||
| - Utilize gloo worker for creating web workers to handle data processing without | ||
| occupying main thread for UI. | ||
| - Use Web Workers for the disassembly of file segments. | ||
| - Dynamically determine segment sizes for optimized processing and store processed data | ||
| in IndexedDB for quick retrieval. | ||
|
|
||
| #### Phase 4: Frontend Development (User Interface and Interaction) | ||
|
|
||
| In Phase 4, we're focusing on advancing the user interface and interaction, | ||
| utilizing Rust and Leptos framework, and leveraging leptos-use utilities for | ||
| efficient data handling: | ||
|
|
||
| 1. **Interactive Master Scroll UI**: | ||
| - Develop a scroll bar for the entire data set, allowing swift navigation. | ||
| - Auto-update the `OffsetScrollState` upon user selection on the scroll bar | ||
| to fetch and load the relevant data section, optimizing HTML element loading. | ||
| - Dynamically calculate and adjust offsets based on user interactions for | ||
| precise data representation. | ||
|
|
||
| 2. **Enhanced Data Loading**: | ||
| - Revise data fetching to pull from IndexedDB, triggered by `OffsetScrollState` changes. | ||
| - Synchronize `MemoryDumpView` and `DisassemblyView` to accurately display data | ||
| relevant to the current offset. | ||
|
|
||
| 3. **Optimized Scrolling**: | ||
| - Guarantee smooth, independent scrolling in both `MemoryDumpView` and `DisassemblyView`. | ||
| - Each view independently manages scroll events for a fluid user experience. | ||
|
|
||
| 4. **Performance and Usability Optimization**: | ||
| - Prioritize swift data retrieval and rendering, focusing on smooth transitions | ||
| and navigation within the application. | ||
|
|
||
| 5. **Comprehensive Testing for Jump-to-Data**: | ||
| - Conduct extensive testing on the jump-to-data functionality to ensure precision | ||
| in offset calculations and data loading responsiveness. | ||
| - Test across various scenarios and data volumes for maximum reliability and accuracy. | ||
|
|
||
| ### Ecosystem Fit | ||
|
|
||
| PolkaVM, with its deterministic execution, stellar performance, and robust security, has emerged | ||
| as a strong contender to WASM in the virtual machine space, particularly for smart contracts and | ||
| extending to broader applications such as parachain verified functions. | ||
|
|
||
| Our focus is on developing tools that not only enhance the learning experience but also lower the | ||
| entry barrier for new developers, enabling them to efficiently create both host and guest functions | ||
| within the PolkaVM ecosystem. | ||
|
|
||
| ## Team | ||
|
|
||
| ### Team Members | ||
|
|
||
| - [Tommi](https://github.com/hitchhooker): UI Developer | ||
| - [Dan](https://github.com/d-r): Backend Developer | ||
|
|
||
|
|
||
| ### Contact | ||
|
|
||
| - **Contact Name:** Tommi Niemi | ||
| - **Contact Email:** [email protected] | ||
| - **Website:** https://rotko.net | ||
|
|
||
| ### Legal Structure | ||
|
|
||
| - **Registered Address:** Akadeemia tee 21-4, Tallinn, 12618 Estonia | ||
| - **Registered Legal Entity:** Rotko Networks OÜ (16740319) | ||
|
|
||
| ### Team's Experience | ||
|
|
||
| Team is spearheaded by seasoned professionals, each bringing a wealth of knowledge and experience to the table. | ||
|
|
||
| Tommi, ecosystem validator for around 3 years and IBP infrabuilder for South East Asia at [Rotko Networks](https://rotko.net/docs/introduction.html), is a full-stack developer. Maintains open Proxmox Ansible rolebooks for running blockchains([Unlabored](https://github.com/rotkonetworks/unlabored)). | ||
|
|
||
| Dan is a seasoned veteran in the field of programming, boasting over 20 years of experience. | ||
| He began his journey in the 90s programming with C, drawing inspiration from the music demoscene. | ||
| His expertise in Rust and functional programming, combined with a passion for writing clear and efficient code. | ||
|
|
||
| ### Team Code Repos | ||
|
|
||
| - [polka.run master](https://github.com/rotkonetworks/polka.run) | ||
| - [polka.run dev(Milestone II worked here)](https://github.com/rotkonetworks/polka.run/compare/master...dev) | ||
| - [Unlabored - Proxmox Ansible infrastructure for blockchains](https://github.com/rotkonetworks/unlabored) | ||
|
|
||
| ## Development Roadmap | ||
|
|
||
| ### Overview | ||
|
|
||
| - **Duration:** 24 weeks | ||
| - **FTE:** 0.458 | ||
| - **Total Costs:** 26400 USD | ||
|
|
||
| ### Milestones | ||
|
|
||
| #### Milestone 1 — Research, Design and MVP | ||
| - Retroactive Milestone | ||
| - Duration: 16 weeks | ||
| - FTE: 0.1875 | ||
| - Total Costs: 7200 USD | ||
|
|
||
| | Number | Deliverable | Specification | | ||
| |--------:|------------------------|---------------------------------------------------------------------------------------------------------------| | ||
| | **0a.** | License | The project will be dual-licensed under both Apache 2.0 and MIT to ensure broad compatibility with the open-source community. | | ||
| | 0b. | Research | Conduct research on the koute/polkavm library to determine its applicability in developing the graphical interface for our disassembler. Select technology stack accordingly. | | ||
| | 0c. | Write a Blog Post | Compose [a blog post](https://kusamaxi.com/post/polkavm-runs-doom) that provides an overview of PolkaVM, its objectives, and benchmarks. | | ||
| | 0d. | Design UI structure | Research and design the UI structure for the disassembler. | | ||
| | 0e. | Design Backend structure | Research and design the backend structure for the disassembler run on browser utilizing client-side API's like File API, IndexedDB and Web Workers. | | ||
| | 0f. | Build a MVP | Construct a Minimum Viable Product (MVP) for the disassembler GUI, featuring file upload capabilities, memory dump (offset, hex, ascii), and a graphical representation of disassembled instructions. [@polka.run](https://polka.run/disassembler) | | ||
|
|
||
| #### Milestone 2 — Disassembler GUI Core Development | ||
|
|
||
| - **Estimated Duration:** 8 weeks | ||
| - **FTE:** 1 | ||
| - **Costs:** $19,200 USD | ||
|
|
||
| | Number | Deliverable | Specification | | ||
| |--------:|-------------|---------------| | ||
| | **0a.** | License | Dual-licensed under Apache 2.0 and MIT for maximum compatibility with the open-source ecosystem. | | ||
| | **0b.** | Documentation | Comprehensive documentation including development setup, architecture overview, and user guide. Hosted on GitHub and project website. | | ||
| | **0c.** | Testing Framework | Implementation of a robust testing framework covering unit tests for all major components and end-to-end integration tests. | | ||
| | **0d.** | Automated Deployment | Setup of automated deployment for seamless updates and releases, including CI/CD pipelines. | | ||
| | **0e.** | Core Disassembler Engine | Development of a core disassembler engine for .polkavm files, with capabilities to handle files up to 4MB. Integration of web storage for session persistence and efficient data paging for optimized performance. | | ||
| | **0f.** | User Interface Implementation | Creation of a user-friendly GUI with a functioning menu, lazy-loaded scrolling for memory and disassembly data, and interactive data linkage. Emphasis on responsive design for desktop users. | | ||
| | **0g.** | Client-Side Processing | Implementation of client-side processing with WebAssembly and HTML5's File API for secure file handling. Use of IndexedDB for local storage and data retrieval, enhancing privacy and security. | | ||
| | **0h.** | Interactive Master Scroll UI | Development of an interactive master scroll UI to enable users to navigate and jump to specific data points within a 1MB blob. Implementation of `OffsetScrollState` for synchronized data loading across multiple views. | | ||
| | **0i.** | Data Management and Optimization | Setup of efficient IndexedDB data management strategies. Implementation of chunk-based processing with Web Workers and optimization for smooth, responsive data loading and rendering. | | ||
| | **0j.** | Maintenance Plan | Development of a maintenance plan detailing regular updates, security patches, and support strategies. Includes workflows for building and releasing code. | | ||
|
|
||
| ## Future Plans | ||
|
|
||
| - **Enhanced Disassembler Features:** Adding hint fields to each instruction for better understanding(LSP?). | ||
| - **RISC-V Assembly LSP Development:** Crafting a Language Server Protocol to provide interactive | ||
| features like hover/click details for disassembled RISC-V code. | ||
| - **Interactive Binary Editor:** Introducing a tool for editing and reassembling binary data, | ||
| enhancing user interaction and control. | ||
| - **Binary Execution on Custom Host Functions:** Implementing functionality to run binaries | ||
| with bespoke host functions for advanced testing and experimentation. | ||
| - **Color coded disassembly output:** Color code the disassembly output to make it easier to read. | ||
| Add color coding to offset navigation bar to make it easier to navigate. | ||
| - **Code Reconstruction and Reassembly:** Long-term goal to enable editing and reconstruction | ||
| of disassembled code for complete cycle management. | ||
|
|
||
| ## Additional Information | ||
|
|
||
| ### Inspirational projectts | ||
|
|
||
| - [PE-bear](https://github.com/hasherezade/pe-bear) - A comprehensive, user-friendly tool for analyzing | ||
| and editing PE (Portable Executable) files. It's a great example of combining functionality with ease | ||
| of use, something we strive to achieve in our own tools. | ||
| - [blinkenlights](https://justine.lol/blinkenlights/) - An innovative project that creatively | ||
| demonstrates system internals and operations. Its unique approach to visualizing and interacting with | ||
| system processes is both educational and engaging. | ||
| - [binaryninja](https://binary.ninja/) - Binary Ninja is an interactive decompiler, disassembler, debugger, | ||
| and binary analysis platform built by reverse engineers, for reverse engineers. | ||
|
|
||
| ### MVP | ||
|
|
||
| MVP GUI is already done and available for use at [polka.run](https://polka.run/disassembler) | ||
| Can be tested with the [hello_world.polkavm](https://github.com/koute/polkavm/blob/master/guest-programs/output/example-hello-world.polkavm) and [doom.polkavm](https://github.com/koute/polkavm/blob/master/examples/doom/roms/doom.polkavm) binaries. | ||
|
|
||
| [](http://www.youtube.com/watch?v=LkAKGYxx9Ec "Video Application") |