Portaldot Dev Kit.

The problem

Portaldot is new. Its errors are cruel.

Portaldot is brand-new and Rust-first; in Season 1 you run it from a local node. When a transaction fails, the node hands back a raw, unexplained error code. No hint of what went wrong, no hint of how to fix it.

# a failed transaction on Portaldot, unfiltered
ExtrinsicFailed: DispatchError { Module: { index: 6, error: 2 } }
# ...now what?

FailLens

The same failure, decoded.

FailLens reads the failed transaction's ExtrinsicFailed event, decodes the error against the chain's own metadata, and pairs it with a curated knowledge base of fixes.

$ pdk debug --demo

╭───────────────── FailLens ─────────────────╮
│ ✗ Balances.InsufficientBalance              │
│                                            │
│ What happened                              │
│ You tried to transfer more POT than the    │
│ sending account holds.                     │
│                                            │
│ How to fix                                 │
│   1. Check the sender balance.             │
│   2. Lower the amount, or fund the         │
│      account first with `pdk up`.          │
╰────────────────────────────────────────────╯

The toolkit

Install & use

From zero to a decoded failure.

Requires Python 3.11+. pdk runs natively on Linux, macOS and Windows — only the node binary is Linux/macOS (on Windows, run the node in WSL and connect pdk from PowerShell).

$ pip install portaldot-pdk   # one command, from PyPI

$ pdk up                  # start a local node
$ pdk debug --demo        # submit a failure, then decode it
$ pdk doctor              # inspect the node

$ pdk debug 0x… --json --exit-code   # gate CI on the result

How it works

Metadata-driven, so it never goes stale.

A failed extrinsic emits a System.ExtrinsicFailed event carrying a DispatchError. FailLens resolves that error against the chain's own metadata — no hard-coded tables — so it adapts to any Portaldot runtime version. Every error in the knowledge base is verified against the live runtime.

1. Locate the failed transaction (by hash, or submit one with --demo).
2. Decode the DispatchError into a named error via metadata.
3. Match it to a curated, human-written fix — with a graceful fallback for the long tail.

v0.2 — TypeScript companion (α.1 shipped)

pdk-ts covers what Python can't sign on Portaldot V13 metadata.

The Python substrate-interface library mis-signs custom-pallet calls on Portaldot's V13 metadata (upstream polkascan/py-substrate-interface#9). pdk-ts is a TypeScript companion CLI on @polkadot/api that reaches the parts Python can't — Assets pallet, ink! contract deploy, and any custom-pallet Portaldot ships next.

Alpha.3 covers doctor · accounts · pallets · storage · keys · explain · version — 7 of 14 commands live. The hero explain command (raw-code decoder — the unique feature) works standalone from the shared YAML KB, no node needed. Both CLIs read the same knowledge base so one PR benefits both.

Roadmap

The standard Portaldot dev toolkit.

pdk is built to grow beyond this hackathon: v0.2 TypeScript companion (α.1 shipped), VS Code + Cursor editor extensions, community-owned knowledge base, and public-RPC readiness for Portaldot mainnet.