Tinkerer Documentation Expansion

polkadot-tinkerers.md

@@ -10,45 +10,81 @@ You can build:
 - 🧪 Proof of Concepts  
 - ✨ Vibe-coded projects  
 
+> For more on the specifics of Polkadot, visit the official [Polkadot Documentation](https://docs.polkadot.com/polkadot-protocol/).
+
 ## 🛠️ Getting Started  
 
-### 🤖 Using AI to Tinker Faster  
+## Quick Primer: What is Polkadot?
 
-You don’t need to know everything — let AI do some heavy lifting:  
+> If you're already famililar with Polkadot, feel free to skip to the [solutions matrix](#polkadot-solutionstooling-matrix) or [APIs and SDKs](#primary-apis--sdks).
 
-- **GitHub Copilot for repos**: Open a repo like [Polkadot SDK](https://github.com/paritytech/polkadot-sdk), and ask Copilot to explain code, functions, or modules. Great for finding answers to “obscure” questions.  
+Polkadot is designed to enable scalable, secure, and interoperable networks to thrive, reflecting the following principles:
 
-- **Query docs with AI**: Use an AI assistant to query [docs.polkadot.com](https://docs.polkadot.com/) directly — it saves time vs. searching manually.  
+1. **Less trust, more truth** — Enable self-verification instead of trusting intermediaries
+2. **Many chains, not one** — Specialized blockchains working together beats a single chain trying to do everything
+3. **Evolution over perfection** — Systems must adapt as technology advances, which Polkadot embraces with its modular forkless upgrades
+
+**The Architecture at a glance:**
+
+- **Relay Chain**: Main hub providing shared security and cross-chain messaging
+- **Parachains**: Specialized blockchains for different use cases (IoT, identity, healthcare etc.)
+- **XCM**: Cross-chain messaging that lets parachains talk to each other
+
+**For Tinkerers:** Build apps that work across multiple blockchains, access rich data from dozens of live chains, and experiment with smart contracts, custom blockchains, or both!
 
-### APIs & SDKs  
+### Primary APIs & SDKs  
 
-- [**Polkadot API (PAPI)**](https://papi.how/) — modern TypeScript API for Polkadot.  
-- [**DeDot**](https://docs.polkadot.com/develop/toolkit/api-libraries/dedot) — lightweight TypeScript library for Polkadot SDK chains, great for quick prototypes.  
-- [**Sidecar**](https://github.com/paritytech/substrate-api-sidecar) — REST service for blockchain data.  
-- [**Subxt**](https://github.com/paritytech/subxt) — Rust library to interact Polkadot SDK–based chains.
-- [**Paraspell**](https://paraspell.github.io/docs/)  - Library which makes working with XCM and interoperability on Polkadot easy.
+- [Polkadot API (PAPI)](https://papi.how/) — modern TypeScript API for Polkadot.  
+- *DeDot](https://docs.polkadot.com/develop/toolkit/api-libraries/dedot) — lightweight, reactive TypeScript library for Polkadot SDK chains.
+- [Sidecar](https://github.com/paritytech/substrate-api-sidecar) — REST service for blockchain data.  
+- [Subxt](https://github.com/paritytech/subxt) — Rust library to interact Polkadot SDK–based chains.
+- [Paraspell](https://paraspell.github.io/docs/)  - Library which makes working with XCM and interoperability on Polkadot easy.
+- [create-dot-app](https://github.com/preschian/create-dot-app) — CLI to scaffold Polkadot dApps with multiple frameworks option and PAPI/DeDot. 
+
+### Polkadot Solutions/Tooling Matrix
+
+Have an idea in mind? Cross-chain tool, a voting system or a verification solution? Check out our [solution matrix](./tinkerer-materials/solution-matrix.md) to find which tools/modules are available for your case!
+
+### Hackathon Quickstarters
+
+Want a quickstart to your project? Look no further than our [hackathon quickstarter guide](./tinkerer-materials/quickstarters.md), where you will find templates, tutorials, and documentation for the above SDKs.
 
 ### Data & Indexing  
 
-- [**SubQuery**](https://subquery.network/) — index and query blockchain data.  
-- [**DotLake**](https://github.com/paritytech/dotlake-community) — a data ingestion pipeline for Substrate-based blockchains (like Polkadot), view it in action [here](https://data.parity.io).
+- [SubQuery](https://subquery.network/) — index and query blockchain data.  
+- [DotLake](https://github.com/paritytech/dotlake-community) — a data ingestion pipeline for Substrate-based blockchains (like Polkadot), view it in action [here](https://data.parity.io).
 
 ### Wallets
 
-- [**Talisman Wallet**](https://www.talisman.xyz/)  
-- [**SubWallet**](https://subwallet.app/)
-- [**Polkadot.js Extension**](https://polkadot.js.org/extension/)
-- [**Nova Wallet**](https://novawallet.io/)
-- [**Polkadot Vault**](https://vault.novasama.io/)  
+- [Talisman Wallet](https://www.talisman.xyz/)  
+- [SubWallet](https://subwallet.app/)
+- [Polkadot.js Extension](https://polkadot.js.org/extension/)
+- [Nova Wallet](https://novawallet.io/)
+- [Polkadot Vault](https://vault.novasama.io/)  
 
 ### Infrastructure  
 
 - [**Pop! CLI**](https://onpop.io/) — is a developer platform for Polkadot that makes it easy to **build, test, and deploy** smart contracts or appchains with a streamlined CLI.
 
+### Interoperability & Bridging
+
+- [**Paraspell**](https://paraspell.github.io/docs/) — SDK for cross-chain transfers and XCM interactions within Polkadot ecosystem
+- [**Snowbridge**](https://docs.snowbridge.network/) — trustless bridge between Ethereum and Polkadot
+- [**Hyperbridge**](https://docs.hyperbridge.network/) — universal interoperability protocol enabling trustless communication between any blockchain networks
+- [**Bridge Hub**](https://wiki.polkadot.network/docs/learn-bridge-hub) — Polkadot's dedicated parachain for bridging operations
+
 ### UI Helpers  
 
 - [**Polkadot Telemetry**](https://telemetry.polkadot.io/) — real-time visualization of multiple networks.
-- [**create-dot-app**](https://github.com/preschian/create-dot-app) — CLI to scaffold Polkadot dApps with multiple frameworks option and PAPI/DeDot. 
+
+### 🤖 Using AI for Efficient Tinkering  
+
+You don’t need to know everything — let AI do some heavy lifting:  
+
+- **GitHub Copilot for repos**: Open a repo like [Polkadot SDK](https://github.com/paritytech/polkadot-sdk), and ask Copilot to explain code, functions, or modules. Great for finding answers to “obscure” questions.  
+
+- **Query docs with AI**: Use an AI assistant to query [docs.polkadot.com](https://docs.polkadot.com/) directly — it saves time vs. searching manually.  
+
 
 ## 🎥 Video Resources
 
@@ -77,31 +113,10 @@ You can use Replit to:
 - **Hack with vibes** — memes, mashups, or unique experiments welcome!  
 - **Spin up an appchain** — use Tanssi to launch a chain tied to your own app.  
 
-## 🌐 Out in the Wild - Deployed Examples
+## 🌐 Deployed Examples
 
 This section highlights **working examples** you can fork, get inspiration from, build on right away. Each entry links to a repo and (where available) a quick summary/tutorial to help you get started fast.  
 
-- **EduChain** → [GitHub Repo](https://github.com/w3f/educhain)  
-  *An example parachain developed by the TechEd team at W3F for education and credentialing, showing how the Polkadot SDK can power real-world solutions.*  
-
-- **create-polkadot-dapp** → [GitHub Repo](https://github.com/paritytech/create-polkadot-dapp)  
-  *A starter template for quickly scaffolding Polkadot dApps with minimal setup.*  
-
-## 🧩 Tinkering Examples  
-
-These show how beginners can **mix and match tools**:  
-
-1. **API + Visualization**  
-   - Fetch balances and transfers via **DeDot** or **PAPI**.  
-   - Pipe the data into a simple **D3.js chart** to show how account balances evolve over time.  
-2. **Explore and use FRAME**
-   - Build a DAO without smart contracts just using the [Proxy pallet](https://www.youtube.com/watch?v=zzcIAjhbAF8).
-   - Use the [Scheduler pallet](https://www.youtube.com/watch?v=olcuZHb4u88) to build a dApp with cyclical actions.
-
-
-
-## 📚 Other Resources  
+- [**EduChain**](https://github.com/w3f/educhain) — An example parachain developed by the TechEd team at W3F for education and credentialing, showing how the Polkadot SDK can power real-world solutions.
 
-- [Polkadot Wiki](https://wiki.polkadot.network/)  
-- [Polkadot Forum](https://forum.polkadot.network/)  
-- [Polkadot SDK Docs](https://docs.polkadot.com/)
+- [**create-polkadot-dapp**](https://github.com/paritytech/create-polkadot-dapp) — A starter template for quickly scaffolding Polkadot dApps with minimal setup.

tinkerer-materials/quickstarters.md

@@ -0,0 +1,66 @@
+## Hackathon Quickstarters
+
+Whether you're creating web applications, CLI tools, analytics dashboards, or entirely new blockchains, this section aims to provide the essential SDKs, templates, and examples to get you started quickly.
+
+- **TypeScript dApps** - Build web applications with libraries like [PAPI](#building-with-typescript-dapps) and [DeDot](#building-with-typescript-dapps).
+- **Rust Applications** - Create high-performance tools and backends with [`subxt`](#building-with-rust)
+- **Create your protocol** - Create quality blockchains (either standlone or parachains) using the [`polkadot-sdk`](#building-with-rust)
+- **Data & Analytics** - Access blockchain data through REST APIs like [Substrate Sidecar](#rest--data--indexing) and build powerful dashboards with tools like [Dotlake](#rest--data--indexing).
+- **Ready-to-use Templates** - [Boilerplates](#boilerplates--examples) and working examples to jumpstart development for the above!
+
+Each section includes documentation links, starter templates, working examples, and notes on when to use each tool. Start with the technology stack that matches your project needs and experience level.
+
+
+### Building with Typescript (dApps)
+
+**Building decentralized applications (dApps) on Polkadot using TypeScript.** dApps on Polkadot are web applications that interact with parachains and/or a relay chain through client libraries. Each chain has a set of custom modules, called **pallets**, each of which has prebuilt functionality you can take advantage of. For more information on what pallets you can use and for what, feel free to [visit the solutions matrix.](./solution-matrix.md)
+
+They typically feature wallet integration, real-time chain data display, and transaction submission.
+
+| SDK | What it's for | When should I use this? | Docs (URL) | Starter / Template (URL) | Working Example(s)  | Tutorial(s)  |
+|---|---|---|---|---|---|---|
+| **Polkadot-API (PAPI)** | TypeScript library for making dApps or CLI tools | Building web apps with wallet integration and need full type safety | https://papi.how/ | `npx create-dot-app` (choose PAPI) or [Polkadot API TS Boilerplate](https://github.com/polkadot-developers/polkadot-api-ts-boilerplate) | [EduNews (Vue + PAPI)](https://github.com/CrackTheCode016/edunews), [Sample CLI ("You Got Mail!")](https://github.com/polkadot-developers/polkadot-api-example-cli) | [PAPI Account Watcher](https://docs.polkadot.com/tutorials/dapps/remark-tutorial/) |
+| **DeDot** | Lightweight TypeScript library for Polkadot chains | Need minimal bundle size and only basic chain interactions | [DeDot Developer Docs](https://docs.dedot.dev/)| `npx create-dot-app` (choose DeDot) | [Working Examples using DeDot](https://docs.dedot.dev/help-and-faq/built-with-dedot) | [Develop ink! dApp using Typink](https://docs.dedot.dev/help-and-faq/tutorials/develop-ink-dapp-using-typink) |
+| **Polkadot UI (beta)** | React component library for Polkadot dApps | Building polished UIs with pre-built wallet integration and chain components | https://polkadot-ui.com/docs | [Polkadot UI Templates](https://polkadot-ui.com/templates) |  | [Getting Started Guide](https://polkadot-ui.com/docs/getting-started) | 
+| **ParaSpell (XCM SDK)** | Cross-chain transfer library | Building cross-chain features without complex XCM setup | https://paraspell.github.io/docs/ | *(use within PAPI app / boilerplate)* |  |  |
+| **create-dot-app** | Project scaffolding tool | Quick project setup with modern frameworks and best practices | https://github.com/preschian/create-dot-app | `npx create-dot-app` (choose PAPI/DeDot) | *(n/a)* | *(n/a)* |
+
+### Building with Rust
+
+**Rust is the native language for Polkadot development.** Use Rust to build high-performance applications, CLI tools, backend services, or entirely new blockchain runtimes. Rust offers compile-time safety, zero-cost abstractions, and direct access to Polkadot's native APIs and primitive types.
+
+| SDK | What it's for | When should I use this? | Docs (URL) | Starter / Template (URL) | Working Example(s)  | Tutorial(s)  |
+|---|---|---|---|---|---|---|
+| **Subxt** | Rust library for Polkadot chains | Building CLI tools, backends, or performance-critical applications | https://docs.rs/subxt/latest/subxt/book | [SubXT Boilerplate](https://github.com/CrackTheCode016/polkadot-subxt-boilerplate) | [EduNews SubXT](https://github.com/CrackTheCode016/edunews-subxt) |  |
+| **Polkadot SDK** | Framework for building blockchains | Creating your own blockchain, custom runtime logic, or parachain | https://docs.polkadot.com/ | [Parachain Template](https://github.com/paritytech/polkadot-sdk/tree/master/templates/parachain) | [EduChain](https://github.com/w3f/educhain) |  |
+
+### REST / Data / Indexing
+
+**Access blockchain data through REST APIs and build analytics dashboards.** These tools provide alternative ways to interact with Polkadot networks without running full nodes, and enable building data-driven applications with historical analysis capabilities.
+
+| SDK | What it's for | When should I use this? | Docs (URL) | Starter / Template (URL) | Working Example(s)  | Tutorial(s)  |
+|---|---|---|---|---|---|---|
+| **Sidecar** | REST API for blockchain data | Need HTTP API access or integrating with non-blockchain systems | https://github.com/paritytech/substrate-api-sidecar | `docker compose` from repo | Use any starter, like Next.js, and make REST calls | [Sidecar Block Explorer Example ](https://github.com/w3f/sidecar-example) |
+| **DotLake (Community)** | Data analytics platform | Building dashboards and need historical data analysis | https://github.com/paritytech/dotlake-community |`docker compose` from repo| https://data.parity.io/home | *(n/a)* |
+| **SubQuery** | Blockchain indexer with GraphQL | Building activity feeds, notifications, or complex data queries | https://academy.subquery.network | use the [SubQuery starter project](https://github.com/polkadot-developers/subquery-starter-example), or use the `npx @subql/cli init test --networkFamily Polkadot` command to bootstrap a project | [Running the Polkadot Multi chain Starter Project using SubQuery](https://www.youtube.com/watch?v=as2aUJLMlos)| [Polkadot SubQuery Quickstart](https://subquery.network/doc/indexer/quickstart/quickstart_chains/polkadot.html) |
+
+### Infrastructure / Local chain deployments
+
+**Tools for local development and testing environments.** Set up local networks for rapid prototyping, testing parachain features, or developing custom blockchain logic before deploying to testnets or mainnet.
+
+| Tool | What it's for | When should I use this? | Docs (URL) | Starter / Template (URL) | Working Example(s)  | Tutorial(s)  |
+|---|---|---|---|---|---|---|
+| **Pop! CLI** | Local blockchain development tool | Developing custom parachains or testing parachain features locally | https://onpop.io/ | [Use the pop! CLI to get started](https://github.com/r0gue-io/pop-cli) | [EduChain](https://github.com/w3f/educhain) | [Create a new parachain - pop! Tutorial](https://learn.onpop.io/chains/guides/create-a-new-parachain) |
+
+### Boilerplates & Examples
+
+**Ready-to-use code templates and working examples to jumpstart your development.** These repositories provide battle-tested starting points for different types of Polkadot applications. Clone, modify, and build upon these foundations rather than starting from scratch.
+
+| Boilerplate | Language | Type | Purpose | Repo URL |
+|---|---|---|---|---|
+| [Polkadot API TS Boilerplate](https://github.com/CrackTheCode016/polkadot-api-ts-boilerplate) | TypeScript | Template | Base PAPI app (balances/tx wiring scaffold) | https://github.com/CrackTheCode016/polkadot-api-ts-boilerplate |
+| [Polkadot API Example CLI](https://github.com/CrackTheCode016/polkadot-api-example-cli) | TypeScript | Example | Sample CLI ("You Got Mail!") using PAPI boilerplate | https://github.com/CrackTheCode016/polkadot-api-example-cli |
+| [EduNews (PAPI + Vue)](https://github.com/CrackTheCode016/edunews) | TypeScript | Example | Working web app using PAPI for chain reads | https://github.com/CrackTheCode016/edunews |
+| [SubXT Template](https://github.com/CrackTheCode016/polkadot-subxt-boilerplate) | Rust | Template | Consolidated Subxt client template with signing examples | https://github.com/CrackTheCode016/polkadot-subxt-boilerplate |
+| [EduNews SubXT](https://github.com/CrackTheCode016/edunews-subxt) | Rust | Example | Working example using Subxt, using the subxt boilerplate. | https://github.com/CrackTheCode016/edunews-subxt |
+| [EduChain (Polkadot SDK)](https://github.com/w3f/educhain) | Rust (SDK) | Example | Example parachain with custom pallets | https://github.com/w3f/educhain |