pdk v0.2.0 — assets + call, parity with pdk-ts

pip install --upgrade portaldot-pdk

Closes the command-surface gap with pdk-ts, and with it the claim that Python "cannot sign Assets calls on Portaldot" — which this release makes false, deliberately. 16 → 18 commands.

Added

pdk assets — create · mint · transfer, mirroring pdk-ts assets argument-for-argument. The hard part was already solved and unreachable: the signing fix had sat in pdk/core since July with no command able to call it.

pdk call <pallet> <call> [args...] — generic extrinsic composer over any pallet/call in live metadata, with discovery built in and a --dry-run fee preview:

pdk call Balances                    # list the pallet's calls + arg types
pdk call Balances transfer           # show one call's signature
pdk call Balances transfer //Bob 100000000000000 --dry-run

Argument types are classified by asking the chain's own type registry what each name resolves to, rather than matching a hand-kept list of aliases. This runtime declares call arguments as BalanceOf, BlockNumber, EraIndex, Perbill, Weight, AccountIndex — all plain unsigned integers underneath, none recognisable as numbers by name. Composites (Call, Vec<T>, Option<T>, structs) are refused with a named error; a signing path never guesses an encoding.

Fixed

Blocks containing Assets amount events could not be decoded at all. V13 metadata declares the Assets pallet's amount fields as the bare name Balance, which resolves globally to u128 while pallet-assets uses u64. A block's events are one SCALE-encoded Vec<EventRecord> read front to back, so the over-wide read desynchronised everything after it and the decoder ran off the end of the buffer.

The blast radius went well past the Assets commands: report and debug --watch read events for the whole block, so they crashed on every failure in a block where any extrinsic happened to move an asset. Fixed once at the shared read path.

A global type override was never possible — one Assets.mint block carries both an Assets.Issued (u64) and a Treasury.Deposit (u128), both declared Balance. Correcting one by name corrupts the other.

Recipient resolution is now one shared helper. Git Bash rewrites //Bob to /Bob, which derives a different valid keypair. The repair existed only in send, and both new commands take recipients.

Packaging. The source distribution was 72 MB of node_modules and demo video. It is 111 KB.

Verification

Verified live against a portaldot-1002 node: assets create/mint/transfer, a genuine Assets.BalanceLow dispatch failure reporting as a failure (exit 1) rather than a crash or a false success, call on Balances.transfer / Assets.mint / System.remark, discovery at both levels, and Sudo.sudo correctly refused as unsupported.

Test suite 126 → 184 cases. pdk-ts unchanged at 141, lint and typecheck clean.

Note on pdk-ts

Assets signing is no longer pdk-ts's reason to exist, and its README, CLI help, examples and tests no longer say it is. Its standing reason is a Node-native CLI and importable library for projects that would rather not add a Python runtime.

One known asymmetry, now the weaker side: pdk-ts call classifies argument types against a hand-kept alias list, so it silently refuses valid arguments on types like BalanceOf and BlockNumber. Adopting the registry approach is queued for beta.1.

Full changelog: CHANGELOG.md

pdk v0.1.8 — fund + send --dry-run

New commands: pdk fund <account> [--amount] (top up from //Alice, default 100 POT — answers 'how do I get POT?') and pdk send --dry-run (preview fee + feasibility for the exact transfer before submitting, reusing simulate's predictor). 16th command overall. Full changelog: CHANGELOG.md.

pdk-ts v0.2.0-alpha.7 — Assets pallet signing

pdk-ts v0.2.0-alpha.7

Release notes body for gh release create pdk-ts-v0.2.0-alpha.7.

What's new

assets — the signing tier's actual reason to exist, shipped and
proven, not just claimed. pdk-ts's README always said it existed to
sign what Python substrate-interface can't. Until this release,
send/seed only signed balances.transferKeepAlive — the same call
Python already signs fine. This release verifies the real claim
directly against a live node and ships the fix:

$ pdk debug --demo ...     # Python: Assets.create → 1010 Invalid Transaction:
                            # "Transaction has a bad signature" — fails at the
                            # RPC layer, before it even reaches a dispatch error.

$ pdk-ts assets create 9001 --node ws://127.0.0.1:9944
✓ created asset #9001      # @polkadot/api signs the identical call successfully.

pdk-ts assets create|mint|transfer is the only member of the pair
that can do this. Verified live end-to-end with balances confirmed via
storage Assets Account (ground truth, not the CLI's own claim): create
→ mint 5000 to Bob → transfer 1500 Bob→Charlie, exact.

Highlights

• assets create <id> [--admin] [--min-balance],
  assets mint <id> <to> --amount N,
  assets transfer <id> <to> --amount N — all three submit through
  a generalised submitExtrinsic engine (extracted from send's
  submitTransfer), so they inherit the false-success guard and the
  submission-timeout hang guard for free.
• send --dry-run — preview the fee + feasibility for the exact
  sender/recipient/amount before submitting, reusing simulate's
  predictor. simulate only ever previewed Alice → Bob; this previews
  the real call.
• fund <account> [--amount] — thin wrapper over send with sender
  forced to //Alice, default 100 POT. Answers the #1 hackathon Q&A
  question ("how do I get POT?") with a command instead of prose.
• report --exit-code — exit 2 when any failure is found in range,
  mirroring debug --exit-code, for CI gating on report.
• Shared knowledge base grew 29 → 38 curated entries (sudo/staking/
  assets/balances dev-loop errors) — bundled into this release.
• A nonce-clash (RPC 1014, "Priority is too low") now gets a plain-
  English hint in every signing command, instead of a raw RPC string.

Fixes (found by a post-ship QA pass)

• assets create --min-balance "" / "0x10" silently resolved to 0
  / 16 instead of erroring — BigInt() alone accepts empty strings
  and hex. Now validated the same way every other numeric input is.
• The "unconfirmed" message pointed at pdk debug <empty-hash> — a
  dead end — when the timeout path (no txHash yet) fired. Now
  distinguishes a real decode-wall case from a genuine timeout.

Install

npm install portaldot-pdk-ts@alpha
npx portaldot-pdk-ts assets create 9001 --node ws://127.0.0.1:9944

Roadmap

• alpha.8 — PAPI migration spike + benchmark vs @polkadot/api;
  bundle-size pass
• beta.1 — hardening + docs pass on the full surface
• 0.2.0 — flip dist-tag from alpha to latest as a stable release

Community

• Bug reports & KB entries: Issues
• good first issue shortlist: pdk-ts kb --missing
• Full changelog: pdk-ts/CHANGELOG.md

pdk-ts v0.2.0-alpha.6 — critical KB-packaging fix + QA pass

pdk-ts v0.2.0-alpha.6

Release notes body for gh release create pdk-ts-v0.2.0-alpha.6.

What's new

Post-publish QA pass. alpha.5 was pdk-ts's first-ever npm publish.
Installing it surfaced a critical packaging bug — and a wider sweep
found several correctness/parity issues alongside it. alpha.5 is
deprecated on npm; this release is what @alpha and latest should
point to.

The critical fix

The shared knowledge base never shipped in the npm tarball. files in
package.json allowed only dist/**/*.js + *.d.ts — no .yaml,
no .json — and nothing copied pdk/data/* into dist/. Every
npm install portaldot-pdk-ts got loadKb() → empty Map, so
explain/debug/kb/diagnose all returned "KB size: 0". The hero
feature was dead for every real installer, working only from a repo
clone. Fixed with a build-time copy step (scripts/copy-data.mjs) that
bundles the KB + error index into dist/pdk-data/, verified by
installing the packed tarball end-to-end.

Fixes

• send/seed/debug --demo could hang forever if a tx never
  reached a block (dropped/invalid/usurped extrinsic, or a
  non-authoring node) — submitTransfer only resolved on isInBlock.
  Now resolves on every terminal status and caps the wait at 60s,
  reporting unconfirmed instead of hanging.
• send --amount 1e3 crashed with a raw BigInt conversion error —
  scientific notation passed Number.isFinite but broke BigInt().
  Added strict plain-decimal validation.
• seed reported failure on a fully-successful run whenever the
  fixtures file mixed in a non-fund/malformed entry — the denominator
  counted all fixtures, not fundable ones. Now applied/attempted.
• watch's Ctrl+C exit code was nondeterministic (0 or 130) from a
  second SIGINT handler racing the one getApi() installs. Now owns
  the signal, exits 0 deterministically.
• debug --json diverged from Python's shape (error was the full
  Pallet.Error label, no pallet field). Now byte-identical keys.
• accounts/doctor/explain --json were pretty-printed while
  Python's is compact, breaking the "byte-identical --json" contract.
• A money-command footgun: send NOTANADDRESS derived a junk
  //NOTANADDRESS account and sent real POT to it. Recipient resolution
  is now strict — an explicit //URI derives, anything else must decode
  as a valid SS58 address.

Install

npm install portaldot-pdk-ts@alpha   # or just portaldot-pdk-ts — latest points here too

Community

• Bug reports & KB entries: Issues
• Full changelog: pdk-ts/CHANGELOG.md

pdk-ts v0.2.0-alpha.5 — signing tier + FailLens

pdk-ts v0.2.0-alpha.5

Release notes body for gh release create pdk-ts-v0.2.0-alpha.5.

What's new

The signing tier lands, and the hero debug (FailLens) ships. This
is the alpha that turns pdk-ts from a read-only companion into a full
member of the pair: send, seed, simulate sign and submit real POT
transfers, and debug diagnoses a failed transaction the same way
Python's does.

The money-path invariant, found and fixed before shipping: the first
cut of send trusted "no dispatchError means success" — reasonable on
most Substrate chains, but @polkadot/api cannot decode Portaldot's
events in a FAILED block, so a genuinely failed transfer (drain-below-ED,
249 POT account sent 999999) reported success: true while the balance
was provably untouched. Fixed: success is confirmed ONLY by a positive
system.ExtrinsicSuccess event. Anything else is status: unconfirmed,
pointing at Python pdk debug <hash> — never a false success.

Highlights

• send <to> --amount N [--from //Alice] — submit a real
  transferKeepAlive, exact 14-decimal BigInt math, false-success guard
  above.
• seed [--file f] — fund accounts from a YAML fixtures file,
  reusing send's submit engine so it inherits the same guard for free.
• simulate --amount N — preview a transfer's fee + feasibility
  (ED-aware: transferKeepAlive refuses to drop the sender below the
  existential deposit) without submitting anything.
• debug [txhash] [--demo] [--exit-code] — FailLens ported. Decodes
  a failed extrinsic to a Pallet.Error + curated fix. Honest about the
  known @polkadot/api decode-wall: a real failed tx that can't be decoded
  resolves to undecodable and points at Python, rather than guessing.
  --demo still shows a diagnosis on the wall because it knows exactly
  which failure it triggered (Balances.InsufficientBalance).
• report — scan recent blocks, group failures by error type,
  degrading gracefully (skips + counts blocks_undecodable) on blocks
  @polkadot/api can't decode.
• watch [--pallet N] — live-stream chain events, same graceful
  per-block degradation as report.

Full command surface reached: 16 commands, matching Python's surface.

Install

npm install portaldot-pdk-ts@alpha
npx portaldot-pdk-ts debug --demo --node ws://127.0.0.1:9944

Community

• Bug reports & KB entries: Issues
• Full changelog: pdk-ts/CHANGELOG.md

pdk v0.1.7 — troubleshooting docs + release pipeline hardening

See CHANGELOG.md#017--2026-07-09 for the full entry. Highlights: README Troubleshooting section covering every real-world install/build hurdle seen this hackathon, PyPI publish pipeline switched from OIDC to API-token auth to survive repo renames, Vercel auto-deploy relinked.

pdk-ts v0.2.0-alpha.4 — library entry + hardening

pdk-ts v0.2.0-alpha.4

Release notes body for gh release create pdk-ts-v0.2.0-alpha.4.

What's new

pdk-ts is now a library, not a bin-only package. import { resolve, resolveByName, collectReport, diagnose, loadKb } from 'portaldot-pdk-ts'
works, and cold import is under half a second — because @polkadot/api
loads lazily on first getApi() call, offline consumers of the FailLens
KB never pay the 4 MB dependency cost.

import { resolveByName } from 'portaldot-pdk-ts';

const fix = resolveByName('balances.InsufficientBalance');
console.log(fix.summary);      // human-friendly explanation
for (const step of fix.steps)  // 3-line remediation
  console.log(`→ ${step}`);

Cold-import cost (measured)

path	before	after
import('portaldot-pdk-ts')	2792 ms	428 ms
offline resolveByName()	2866 ms	42 ms

Published to the alpha dist-tag

npm install portaldot-pdk-ts@alpha — a bare npm install portaldot-pdk-ts
will not pick up a prerelease as latest. Correct semver hygiene.

Highlights

• Library entry (dist/lib.js) — 20 named exports covering FailLens
  (resolve, resolveByName), doctor (collectReport), diagnose,
  the shared KB (loadKb, lookup, indexLookup, indexSize,
  kbSize, indexMatchesChain), chain (getApi, closeApi), and
  config utilities. Deep imports into dist/commands/* are blocked by
  the exports map on purpose.
• accounts --all — extend Alice/Bob/Charlie to include //Dave,
  //Eve, //Ferdie (the full canonical dev-account set).
• error_index.meta.json sidecar — fingerprints the shipped index
  by (specName, specVersion). Both are regenerated together by
  extract_index.py; runtime warns on drift.
• Docker image runs as non-root (USER pdk) + .dockerignore
  trims the build context to what the runtime actually needs.
• Git-bash /Alice path mangling auto-hint — keys command
  detects the C:/Program Files/Git/Alice pattern and suggests
  //Alice, bare Alice, or MSYS_NO_PATHCONV=1.
• KB YAML validation at load — malformed entries (missing summary
  or empty steps) are rejected. Empty diagnoses were worse than none.
• unhandledRejection / uncaughtException handlers — async
  errors past command handlers print a readable message instead of
  a raw Node stack trace.
• .gitattributes — silences the CRLF warnings Windows
  contributors got on every commit.

CI additions

• .github/workflows/docker.yml — build + smoke test (version,
  kb, explain, non-root check) + push to GHCR on pdk-ts-v* tags.
• .github/workflows/security.yml — Gitleaks + CycloneDX SBOM
  (weekly + on-push).
• .github/workflows/pdk-ts.yml extensions:
  • explain --live metadata walk smoke (metadata-driven decode)
  • kb --json offline surface smoke
  • diagnose --skip-connect tool-health smoke
  • Separate job typechecking docs/examples/basic-consumer against
    the freshly built pdk-ts (catches library-surface regressions).

Install

# once published
npm install portaldot-pdk-ts@alpha
npx portaldot-pdk-ts doctor --node wss://rpc.portaldot.io

# from source today
git clone https://github.com/PugarHuda/portaldot-hackathon-2026-pdk-AmpunBang.git
cd portaldot-hackathon-2026-pdk-AmpunBang/pdk-ts
npm install && npm run build
node dist/index.js --help

# Docker (post-tag push to GHCR)
docker run --rm ghcr.io/pugarhuda/portaldot-pdk-ts:0.2.0-alpha.4 \
  explain --module 6 --error 2

Roadmap

• alpha.5 — signing tier: simulate, send, seed
• alpha.6 — debug, report, watch, ai-setup
• alpha.7 — PAPI migration benchmark
• beta.1 — full parity with the Python pdk command surface
• 0.2.0 — flip dist-tag from alpha to latest

Community

• Bug reports & KB entries: Issues
• good first issue shortlist: pdk-ts kb --missing
• Full changelog: pdk-ts/CHANGELOG.md

pdk-ts v0.2.0-alpha.3 — explain (raw-code decoder)

pdk-ts v0.2.0-alpha.3

Release notes body for gh release create pdk-ts-v0.2.0-alpha.3.

What's new

Shipped the hero feature. pdk-ts explain walks live runtime metadata
to decode a raw Module { index, error } code into a named pallet error,
then attaches the shared knowledge base's summary + fix steps. Also runs
fully offline against the packaged error index for the 202 known
Portaldot-1002 errors.

Coverage today: 29 curated fixes / 202 indexed errors (14.4%). Run
pdk-ts kb --missing to see the community-contribution shortlist. Each
missing entry is a ~5-line YAML PR.

Read-only surface (safe against any public RPC)

• pdk-ts explain --module N --error M — walk metadata → named error + fix
• pdk-ts explain --name balances.InsufficientBalance — offline KB lookup
• pdk-ts pallets [name] — list all pallets or detail one
• pdk-ts storage <pallet> <item> [keys...] — read any storage value
• pdk-ts keys [source] — inspect or generate an SS58-42 keypair
• pdk-ts accounts — enumerate //Alice, //Bob, //Charlie + POT balances
• pdk-ts doctor — endpoint health probe
• pdk-ts diagnose — tool + KB + index + connectivity in one report
• pdk-ts kb — KB coverage / missing / list
• pdk-ts examples — curated ready-to-copy invocations

Reliability additions in this alpha

• URL scheme validation rejects http:// / https:// before opening a socket
• Concurrent getApi() calls share one connection promise
• SIGINT / SIGTERM cleanly close the WebSocket before exit
• Verbose @polkadot/api logs no longer corrupt --json stdout
• Consistency test guards the KB ⊆ index invariant

Install

# once published to npm
npx portaldot-pdk-ts@0.2.0-alpha.3 doctor --node wss://rpc.portaldot.io

# from source today
git clone https://github.com/pugarhuda/portaldot-pdk.git
cd portaldot-pdk/pdk-ts && npm install && npm run build
node dist/index.js --help

# Docker (post-tag push to GHCR)
docker run --rm ghcr.io/pugarhuda/portaldot-pdk-ts:0.2.0-alpha.3 explain --module 6 --error 2

Roadmap

• alpha.4 — signing tier: simulate, send, seed
• alpha.5 — debug, report, watch, ai-setup
• alpha.6 — PAPI migration benchmark
• beta.1 — full parity with the Python pdk command surface
• 0.2.0 — npm publish

Community

• Bug reports & KB entries — github.com/pugarhuda/portaldot-pdk/issues
• good first issues are 5-line YAML fixes in pdk/data/error_fixes.yaml. Start with pdk-ts kb --missing.

pdk v0.1.0

First release of the Portaldot Dev Kit. FailLens transaction debugger (--demo, --watch, --json), pdk up, pdk accounts, pdk explain, pdk doctor. Verified end-to-end on a live Portaldot node; 17 tests.