[Retroactive Funding] JAM GrayPaper Reader

Dear Polkadot Community,

we are excited to share our proposal for retroactive funding of the Gray Paper Reader, a tool that makes it easier to work with the Gray Paper for JAM. The Reader helps with sharing, annotating, and tracking changes in the document, solving challenges many teams face. It’s open-source, already in use by the community, and hosted at graypaper.fluffylabs.dev. We hope for your support to continue improving this tool for everyone in the Polkadot ecosystem.

Full proposal text: https://docs.google.com/document/d/1i_tg_scBP5GrY_IM7eH4lpPZDrGbk5rGAi-Lf1s28cU

 

General project information

Project Category / Type: Software development
Proponent: FluffyLabs.dev
USDC address: 15fGrDWmFoaApnZXEw1Zg45zuCqpkbMS9YPzczeU9dHseUUu
Requested allocation: 21.000 USDC
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: Jan 19th 2025
Onchain publish date: planned for Feb 1st 2025
Previous treasury proposals: none for the GrayPaper (The team received retroactive funding for the PVM Debugger)

 

Context

The Gray Paper is the formal specification of JAM, the next generation of Polkadot Cloud. It’s detailed but not easy to read, understand, and keep up with it, as it changes over time.

There are over 20 teams that publicly stated (including us), they are participating in the JAM Prize Contest and all their members surely do read the Gray Paper. Discussions in Element channels highlight the need to clarify some parts or fix errors, so the document changes over time. There are also at least 4 major revisions planned adding extra features.

We built the Gray Paper Reader to alleviate major pain points we identified.

 

Problem

While working with the Gray Paper PDF versions internally, we identified the following issues and addressed them in the Gray Paper Reader. It’s difficult to quickly share a fragment or formula from the PDF.

Screenshots are somewhat of an option, but they lack the bigger context and require indication from which version of the GP they are taken. Referencing GP from the code comments may quickly get outdated.

Both quoting a fragment or referencing a formula id may not be valid in the newer revision of GP.

Notes on both printed or digital versions are hard to transfer to a newer revision.

 

Proposal

We propose retroactive funding for the development of the Gray Paper Reader hosted at https://graypaper.fluffylabs.dev with open source code using permissive license available on github (https://github.com/fluffylabs/graypaper-reader). Unlike the JAM prize, which focuses on client implementations, no existing funding covers the creation of ecosystem tools like the Gray Paper Reader.

 

Available solutions

There are tools like Adobe Acrobat, Mendeley, and Notion for working with PDFs. These tools include features like annotations, version history, and sharing, but they don’t fully alleviate identified problems:

• Adobe Acrobat: Great for comments and highlights, but doesn’t help with tracking notes across versions or supporting Gray Paper discussions by sharing short links.
• Mendeley: Good for research papers but not built for changing, evolving documents like the Gray Paper.
• Notion: Useful for shared notes and organization but doesn’t directly support detailed version tracking or work well with PDFs.

 

Features

The Gray Paper Reader features:

• Archive of published Gray Paper versions
• Easily switching between multiple revisions of the Gray Paper.
• Quickly switching the color scheme of the Gray Paper (Light, Dark and Gray modes).
• Short Links to specific fragments of a specific revision for easy sharing on open discussion channels
• Attaching notes with rich formatting to specific fragments and automatically migrating them between revisions.
• A command line tool to scan codebase for links to the reader and automatically migrating them to newer revisions.
• Backlinks to all messages sent on JAM Element Chat that included the link to the reader.
• Automatic upgrade of the tool in case a new version of Gray Paper is released. Below is an outline of the deliverables and key functionalities.

The deliverable is open-source under the MIT license.

 

Deliverables

• Web application: https://graypaper.fluffylabs.dev
• Open Source Code: https://github.com/FluffyLabs/graypaper-reader (MPL-2.0)
• Links check tool: https://www.npmjs.com/package/@fluffylabs/links-check
• Matrix Bot: https://github.com/FluffyLabs/graypaper-reader/tree/main/tools/matrix-bot

 

Adoption

Links to Gray Paper Reader are already used extensively in the official Element Gray Paper room (https://app.element.io/#/room/#graypaper:polkadot.io) as a common way to reference sections of the document. Over the period of 2.5 months (Mid-Oct to End-Dec) 21 unique users sent 136 messages that included a link to Gray Paper Reader. These conversations can be viewed as in-document annotations in the beta version of the tool available here (link).

 

Timeline

This proposal seeks retroactive funding for the development of the Graypaper Reader, which began in early August 2024 and finished End of December with Release 1.0.

For detailed information and the features planned in the futures, please refer to the Full Proposal Text

 

Budget

The Graypaper Reader development is complete, and we are seeking retroactive funding

Total budget: $21,000 (Detailed breakdown of the budget in the Full Proposal Text)

 

Proponent

USDC Address:15fGrDWmFoaApnZXEw1Zg45zuCqpkbMS9YPzczeU9dHseUUu
Requested Allocation: 21.000 USDC
Governance Referenda Origin Call: Small spender

 

Contact Information

Team Member: Piotr Zwolinski
Email: [email protected]
Element: @piotrzwolinski:matrix.org

 

Team

FluffyLabs develops JAM and supporting tools, including the PVM Debugger (with successful retroactive funding from the Treasury) and the GrayPaper reader.

For details on the development team, please refer to the Full Proposal Text