pdk — 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 decoding a Portaldot transaction failure, live

$ 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

pdk up

Start a local Portaldot node and verify it with a real on-chain transaction.

pdk accounts

Show the pre-funded dev accounts and their POT balances — the one-command answer to "how do I get POT?".

pdk debug

FailLens — decode any failed transaction into a plain-language diagnosis and fix. Add --watch for a live monitor, --json for CI.

pdk explain

Look up what any Portaldot error means and how to fix it — a queryable reference, no transaction needed.

pdk doctor

Check the node version, runtime, and ink! / contracts-API compatibility.

pdk simulate

Preview a transfer's POT fee and feasibility — without sending it.

pdk seed

Fund accounts from YAML fixtures so you start from realistic state.

pdk pallets

Browse the runtime's pallets, calls, and errors — straight from metadata.

pdk send

Send POT from a dev account — a real on-chain transfer.

pdk storage

Read any value from the chain's storage, straight from the terminal.

pdk watch

Stream every chain event live — a general monitoring view.

pdk keys

Generate or inspect a keypair — no separate tool needed.

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.

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

Portaldot Dev Kit.