🏆 1st Place · Portaldot Online Mini Hackathon S1 · Builder Tools v0.2 alpha.7 · signs Assets pallet calls Python can't → pdk-ts

Portaldot Dev Kit.

A command-line toolkit for the Portaldot blockchain. Its hero feature, FailLens, turns cryptic transaction failures into clear, human-readable diagnoses — with fixes.
A starter kit helps you write Portaldot code; pdk is what saves you when it breaks.

▶ Watch live demo Get started View source

90 s · voiced narration · all 16 commands running against a real local Portaldot node · replay the terminal in your browser →

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. --dry-run previews the fee first.

pdk fund

Top up an account with POT from //Alice — the literal answer to "how do I get POT?".

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.

pdk report

Scan recent blocks and summarise every failure by type. --exit-code gates CI on the result.

pdk kb

Knowledge-base introspection — coverage, missing entries, and live verification against a node.

pdk ai-setup

Set up (or verify) the optional AI diagnosis layer — auto-on once PDK_AI_KEY is set.

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 (α.7 · signs what Python can't)

pdk-ts signs Assets pallet calls Python cannot sign on Portaldot at all.

Verified directly against a live node: Assets.create from Python's substrate-interface fails at the RPC layer with "Invalid Transaction: bad signature" before it even reaches a dispatch error (upstream polkascan/py-substrate-interface#9). @polkadot/api signs the identical call successfully — pdk-ts assets create/mint/transfer is the only member of the pair that can do this. ink! contract deploy is next on the same path.

Alpha.7 covers all 17 commands — the full chain / FailLens / signing surface Python has (doctor · accounts · pallets · storage · keys · explain · debug · report · simulate · send · fund · seed · watch · diagnose · examples · kb · version), plus assets — the surface Python can't touch. Importable as a library too (import { resolveByName } from 'portaldot-pdk-ts'). Both CLIs read the same knowledge base so one PR benefits both.

npm install portaldot-pdk-ts@alpha Browse pdk-ts source Roadmap

Roadmap

The standard Portaldot dev toolkit.

pdk is built to grow beyond this hackathon: the v0.2 TypeScript companion has shipped through alpha.7 (Assets pallet signing). Next: ink! contract deploy in pdk-ts, VS Code + Cursor editor extensions, community-owned knowledge base growth, and public-RPC readiness for Portaldot mainnet.