Skip to content

Comments

feat: add wasm-dot package for Polkadot transaction building and decoding#145

Open
lcovar wants to merge 1 commit intomasterfrom
BTC-0.dot-wasm
Open

feat: add wasm-dot package for Polkadot transaction building and decoding#145
lcovar wants to merge 1 commit intomasterfrom
BTC-0.dot-wasm

Conversation

@lcovar
Copy link
Contributor

@lcovar lcovar commented Feb 6, 2026

Summary

Add a new WASM package (@bitgo/wasm-dot) for Polkadot/Substrate transaction building and decoding, following the same architecture as wasm-solana.

Architecture

Rust (parser.rs, builder/)    → Byte-level SCALE encoding/decoding
TypeScript (explain.ts, etc.) → Business logic (type derivation, output extraction)

Why this split: Rust handles SCALE binary format (compact integers, MultiAddress, era encoding, recursive batch/proxy calls). TypeScript handles the explain layer — deriving transaction types from pallet+method, extracting outputs/inputs, computing amounts. This means business logic changes don't require WASM rebuilds.

What's included

Builder — build transactions from declarative intents:

  • transfer, transferAll, stake, unstake, withdrawUnbonded, chill
  • addProxy, removeProxy
  • batch / batchAll with nested call encoding
  • Accepts JS BigInt natively for amounts (u64 — matches wasm-solana pattern, no custom deserializers needed)
  • Mortal/immortal eras, tips, nonce

Parser — decode SCALE-encoded extrinsics:

  • Extracts sender, nonce, tip, era, method (pallet + name + decoded args)
  • Hardcoded call resolution for Polkadot, Kusama, Westend
  • Dynamic metadata-based resolution for any Substrate chain
  • Recursive parsing for utility.batch and proxy.proxy with depth limiting (max 10)
  • Arg decoders for all 12+ method types

Explain — structured transaction explanation:

  • Derives TransactionType: Send, StakingActivate, StakingUnlock, StakingWithdraw, StakingUnvote, StakingClaim, AddressInitialization, Batch, Unknown
  • Recursive output/input extraction through batch and proxy wrappers
  • Computes outputAmount (sum of non-ALL outputs)

Key design decisions

Decision Rationale
u64 for amounts (not u128) DOT total supply fits in u64. Matches wasm-solana. serde_wasm_bindgen handles JS BigInt → u64 natively — no custom deserializers, no TS-side .toString() conversion
Rust = bytes, TS = business logic Explain logic is easier to modify/test in TypeScript. No WASM rebuild for business logic changes
Batch returns Batch type Don't unwrap to determine inner type (matches legacy behavior)
proxy.proxy derives from inner call A proxy wrapping a transfer → Send
Depth-limited recursion (max 10) Cheap insurance against malformed nested batch/proxy payloads

Test coverage

  • 28 Rust unit tests — parser, address encoding, call encoding, type serialization
  • 25 TypeScript integration tests — build+explain round-trips for all transaction types, batch output extraction, unsigned transactions, metadata fields

Test plan

  • cargo test — 28 tests passing
  • cargo fmt + cargo clippy — clean
  • npm run build — WASM + TypeScript compilation
  • npm test — 25 tests passing
  • npx prettier --check — clean
  • npm ci — lockfile updated with workspace entry

BTC-0

@lcovar lcovar force-pushed the BTC-0.dot-wasm branch 2 times, most recently from 58a71f1 to 751d3e2 Compare February 19, 2026 22:33
@lcovar lcovar changed the title temp: add wasm-dot package for Polkadot feat: add wasm-dot package for Polkadot transaction building and decoding Feb 19, 2026
@lcovar lcovar force-pushed the BTC-0.dot-wasm branch 11 times, most recently from 3be05b1 to fe73139 Compare February 20, 2026 09:17
…ding

WASM-based Polkadot/Substrate transaction builder, parser, and explainer
for use by sdk-coin-dot (tdot). Supports transfers, staking operations,
proxy management, and batched calls.

Key capabilities:
- Build unsigned extrinsics from high-level intents (transfer, stake, batch, proxy)
- Parse signed/unsigned extrinsics with metadata-aware signed extension decoding
- Explain transactions: derive type, extract outputs/inputs, attach DOT-specific metadata
- Proxy type resolution from chain metadata (works across Polkadot, Kusama, Westend)
- parseTransaction returns DotTransaction with .parse() method (PSBT pattern)

BTC-0
@lcovar lcovar marked this pull request as ready for review February 20, 2026 20:21
@lcovar lcovar requested a review from a team as a code owner February 20, 2026 20:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant