[Discussion] Retroactive Big Tipper: xcm-lens v0.0.2 — XCM debugging toolkit (136 tests, MIT)

Governance
,
1

Retroactive Big Tipper: xcm-lens v0.0.2 — XCM debugging toolkit

Hello Polkadot community :waving_hand:

I’d like to discuss a retroactive Big Tipper for xcm-lens v0.0.2 — an XCM debugging toolkit (TypeScript CLI + library) that I shipped over the past 4 days. The artifact is already live and reviewable on GitHub before any funding ask: 136 tests passing, 5/5 build vectors green, MIT licensed, no upstream merge dependencies.

This post opens a 7-day community discussion. If the feedback is constructive, I plan to submit an on-chain referendum next week.

TL;DR

  • What: CLI + library that turns a high-level intent (“teleport DOT from AH to Bridge Hub for Alice”) into the right post-AHM extrinsic, dry-runs it, surfaces real XcmPaymentApi fees, and explains each instruction.
  • Why: XCM is consistently the #1 developer friction point. Existing tools cover chain state OR scaffold projects — none address the construct-simulate-explain loop.
  • Status: v0.0.2 shipped, public, working. Two adversarial code review passes closed (Wednesday: 6 critical + 4 major; Thursday: 5 critical + 7 major findings) before this submission.
  • Ask: 800 DOT (~$5,200 at current DOT price) retroactive Big Tipper. Solo-dev, ~4 days of focused work.
  • Precedent: ref #1340 (PVM Debugger) — 100% Aye, $16K USDT, almost identical profile.

What ships in v0.0.2

Repo · Release notes · STATUS.md

Two TypeScript packages + CLI:

@xcm-lens/core (PAPI-free)

  • IntentSchema v1 — frozen Zod schema with semver-aware versioning, schema-level invariants (Parachain only at interior[0], fee asset must equal action asset, u64 weights).
  • buildFromIntent — post-AHM call selection matrix covering 5 corridors (Relay<->AH teleport DOT, Relay->para reserve DOT, AH->para transfer USDT, AH->BridgeHub teleport DOT).
  • Decoder for XCM v3/v4/v5 covering 22+ instructions per version.
  • Vector resolver with networkProfiles + networkBehavior (live / chopsticks-only / skip).

@xcm-lens/chain

  • dryRun + estimateFees orchestrators (single dry_run_call source of truth; sharable between APIs).
  • ChainAdapter contract + ChainAdapterPool (TOCTOU-safe in-flight dedup).
  • ChainRegistry — 18 chains (Polkadot + Westend + Paseo system parachains) with trusted teleport sources scaffolded for M5 commit pinning (config/teleport-pins.json).
  • LocationResolver, reanchorLocation, assetIdEq (null/undefined normalized), OriginSynthesizer (Alice on testnets; throws on Polkadot mainnet without explicit origin).
  • StubChainAdapter via @xcm-lens/chain/testing subpath (kept out of production bundles).

xcm-lens-cli

  • decode, build, dry-run (stub default), estimate-fees (stub default), corridors (STATUS.md reader).
  • --live flag opts into the live PAPI adapter (lands in v0.0.3, post-grant work — currently throws with a clear error).

Why this matters for Polkadot

XCM is the ecosystem’s #1 developer friction. Reference points:

  • polkadot-sdk#3050 — XCM v3->v4->v5 migration churn.
  • polkadot-sdk#6637 — Asset Hub Migration’s new transfer_assets call shape breaks every existing integration that doesn’t dynamically dispatch.
  • polkadot-sdk#4736 — builders explicitly asking for runtime-API-driven dry-run + fee-estimation tooling.
  • polkadot-sdk#6774 — no end-to-end XCM cookbook for modern typed PAPI.

Existing tooling falls into three buckets, none of which address XCM message construction + execution + fee discovery in one workflow:

Existing tool What it does XCM execution?
shawntabrizi/polkadot-mcp Read-only RPC over MCP No
r0gue-io/pop-mcp Project scaffolding No
docs.polkadot.com MCP Docs RAG No
Polkadot.js Apps UI for already-formed calls Manual, error-prone

xcm-lens is the missing execution-side tool.

What I’m NOT asking funding for

To be explicit about scope of the Big Tipper ask:

  • This Big Tipper covers ONLY v0.0.2 — the M1 cut already shipped. ~4 days of focused work.
  • v0.0.3 (live PAPI adapter, Chopsticks integration, nightly Westend) is future work I’ll do without grant funding to build a longer track record, before any second proposal.
  • M2 (MCP server for AI agents, error knowledge base) and M3 (90-day patch SLA) would be a separate Small Spender proposal in 4-6 weeks, only after v0.0.3 is shipped and the community has had time to evaluate v0.0.2 usage.

This is NOT a salary request. It’s a one-time tip for finished work.

Budget breakdown (800 DOT ≈ $5,200)

Item Hours Notes
Day 1: monorepo + tooling + decoder 8 SCALE codec helpers, v3/v4/v5 decoder (22+ instructions)
Day 2: IntentSchema v1 + buildFromIntent 10 Post-AHM call selection matrix, 5 corridor vectors, Wednesday review fixes
Day 3: @xcm-lens/chain split + dryRun + estimateFees orchestrators 12 ChainRegistry, LocationResolver, reanchor, fee pipeline, Thursday review fixes
Day 4: M5 scaffolding + CLI + STATUS.md + CONTRIBUTING.md + release 6 Two adversarial review passes, polish, v0.0.2 release
Total 36 hours At $145/hr ≈ $5,220

At 800 DOT × $6.50 = $5,200, this is a fair retroactive rate for senior Polkadot infra work delivered as MIT open source.

Track record

  • PR #12 in polkadot-developers/bounties — 3-chapter PAPI XCM Cookbook (12,500 words + 300 lines of runnable TypeScript on Paseo), submitted 2026-05-29, currently up for tip review.
  • Code is vendored under xcm-lens/resources/cookbook/ so the deliverable is independent of upstream merge timing.
  • GitHub: @1DanWave2
  • Polkadot SS58: 15ou8P2L6GkKj8fio4PeNyZUUaeEJfYqtMifsM3MR8pqq8Lv (where the Big Tipper would settle)

Quickstart for reviewers

git clone https://github.com/1DanWave2/xcm-lens
cd xcm-lens
pnpm install
pnpm -r build
pnpm test                 # 136 tests pass
pnpm vectors:check        # 5/5 build vectors green
node packages/xcm-lens-cli/bin/xcm-lens.mjs build \
  docs/examples/01-relay-to-ah-teleport-dot.json

The CLI defaults to stub mode in v0.0.2 (no network calls, no surprise gas costs in CI). See STATUS.md for the corridor matrix and CONTRIBUTING.md for the dev loop.

What I’d like feedback on (before going on-chain)

  1. Amount calibration — is 800 DOT (~$5.2K) appropriate for the scope? Reference #1340 paid $16K for a comparable scope; #1657 paid $7.5K for a smaller retroactive scope. I’m choosing on the low end of the range to respect the 2026 Treasury tightening signal.
  2. Track choice — Big Tipper (≤1K DOT, 7-day vote) vs Small Spender (≤10K DOT, 28-day vote, larger window for community discussion). I’m picking Big Tipper for v0.0.2 specifically because the ceiling fits the M1-cut scope and the faster cycle matches “retroactive for already-shipped work.”
  3. Future M2/M3 scope — is the community OK with a separate Small Spender proposal in 4-6 weeks for the MCP server + error knowledge base + 90-day SLA, or should that be deferred entirely?
  4. Anything missing in the v0.0.2 cut that would unlock more confident funding (e.g. tagged npm release, docs site, more vectors)?

Happy to iterate on the framing here in the forum before going on-chain. Open to feedback and to changing the ask amount based on comments.

Thanks for reading :folded_hands:

-– @1DanWave2

2

I’m curious — why build a separate toolkit instead of extending ParaSpell? What do you see as the key difference between XCM Lens and ParaSpell?

3

Great question @dandan — ParaSpell is the obvious comparison and I want to be honest about where these overlap and where xcm-lens is solving a different problem.

Where ParaSpell is the right tool today: if you’re a DeFi UI integrator who needs to build a typed cross-chain transfer extrinsic — “user has DOT on AH, send to Hydration” — ParaSpell’s Builder() API is exactly that, used in production, with mature chain coverage. I’m not trying to replace it. If a DeFi team came to me asking “should I use xcm-lens or ParaSpell for my swap UI”, I’d point them at ParaSpell.

Where xcm-lens lives is a different layer of the stack — three differences in audience and surface:

  1. CLI + agent-facing, not SDK-facing. ParaSpell’s primary surface is a TypeScript library imported into a dApp. xcm-lens’s primary surface is a CLI you run against an intent file, and (in M2) an MCP server exposing the same toolset to AI agents. Different audience: a dApp developer who already knows what extrinsic they want, vs a person debugging a failed XCM at 3am or an AI agent trying to figure out which extrinsic to construct in the first place.

  2. Decode + explain, not just build. xcm-lens decodes existing XCM blobs (v3/v4/v5, 22 instructions each) into an annotated tree, and the M2 deliverable is an error knowledge base scoring 60% top-1 / 80% top-3 on 50 real failed extrinsics. The build → dry-run → estimate-fees → explain loop is the unit of work, not just “produce a signed extrinsic”. This is the “I have a failed XCM in a block, why did it fail” workflow that today people debug by reading polkadot-sdk source.

  3. Frozen IntentSchema v1 + adversarial-review process as a deliverable. The schema has explicit semver-aware versioning, schema-level invariants (Parachain only at interior[0], fee asset must equal action asset, u64 weights), and the v0.0.2 release came with two public adversarial code review passes that closed 11 critical + 11 major findings. That’s not better engineering — it’s a different commitment shape, suitable for grant-funded retroactive tipping where reviewers want a stable, citable surface to evaluate.

On collaboration: the trusted-teleport pinning work in packages/xcm-lens-chain/src/registry.ts (M5 follow-up) is exactly the kind of thing that would benefit from a shared registry across ParaSpell + xcm-lens + the runtime fellowship — I’d love to chat with the ParaSpell team about whether the citation format I’m using makes sense as a community convention, or whether their existing chain config approach is the better seed.

Bottom line — same lower 30% of the stack (typed cross-chain extrinsic construction), but xcm-lens is targeting a different upper 70% (debugging, decode, agent integration, public adversarial review trail) than ParaSpell’s DeFi-UI focus. Happy to be wrong about any of these dimensions if I’ve misread ParaSpell’s current scope — please correct me.

-– @1DanWave2