feat: add wasm-dot package for Polkadot transaction building and decoding by lcovar · Pull Request #145 · BitGo/BitGoWASM

lcovar · 2026-02-06T04:02:40Z

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

…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

OttoAllmendinger

let's try this: I will write a high level CONVENTIONS.md file that contains these re-occurring patterns an we'll see if the agents pick it up

OttoAllmendinger · 2026-02-23T09:51:11Z

packages/wasm-dot/js/transaction.ts

+  /**
+   * Get call data as hex string
+   */
+  get callDataHex(): string {


the callers can do the base conversions

OttoAllmendinger · 2026-02-23T09:51:24Z

packages/wasm-dot/js/transaction.ts

+ */
+export class DotTransaction {
+  private inner: WasmTransaction;
+  private _context?: ParseContext;


can we do without this?

OttoAllmendinger · 2026-02-23T09:51:59Z

packages/wasm-dot/js/transaction.ts

+   * ```
+   */
+  parse(context?: ParseContext): ParsedTransaction {
+    return parseTransactionData(this.toHex(), context ?? this._context);


needless base conversion

I think we can do without the context. Maybe have parse as a separate func instead of amethod

OttoAllmendinger · 2026-02-23T09:52:32Z

packages/wasm-dot/js/transaction.ts

+  /**
+   * Get the underlying WASM transaction (for advanced use)
+   */
+  getInner(): WasmTransaction {


we use a different convention in wasm-utxo, I would prefer we stick to one. Maybe we should write it down as a toplevel repo document.

OttoAllmendinger · 2026-02-23T09:52:53Z

packages/wasm-dot/js/transaction.ts

+/**
+ * Create a ParseContextJs from ParseContext
+ */
+function createParseContext(ctx: ParseContext): ParseContextJs {
+  const material = new MaterialJs(
+    ctx.material.genesisHash,
+    ctx.material.chainName,
+    ctx.material.specName,
+    ctx.material.specVersion,
+    ctx.material.txVersion,
+    ctx.material.metadata,
+  );
+  return new ParseContextJs(material, ctx.sender ?? null);
+}


can we move all this to parser.ts and have it distinct from Transaction?

OttoAllmendinger · 2026-02-23T09:53:43Z

packages/wasm-dot/js/parser.ts

+  const ctx = context ? createParseContext(context) : undefined;
+
+  if (typeof input === "string") {
+    return ParserNamespace.parseTransactionHex(input, ctx) as ParsedTransaction;


we can do the hex parsing here and have a parseTransaction that works on Uint8Array

OttoAllmendinger · 2026-02-23T09:53:55Z

packages/wasm-dot/js/parser.ts

+  }
+
+  if (input instanceof DotTransaction) {
+    const hex = input.toHex();


needless base conversion, going through bytes is cleaner

OttoAllmendinger · 2026-02-23T09:54:22Z

packages/wasm-dot/js/transaction.ts

+  /**
+   * Get signable payload as hex
+   */
+  signablePayloadHex(): string {


OttoAllmendinger · 2026-02-23T09:54:33Z

packages/wasm-dot/js/transaction.ts

+   * @param signature - 64-byte Ed25519 signature
+   * @param pubkey - 32-byte public key
+   */
+  addSignature(signature: Uint8Array, pubkey: Uint8Array): void {


OttoAllmendinger · 2026-02-23T09:54:41Z

packages/wasm-dot/js/transaction.ts

+  /**
+   * Serialize to hex string
+   */
+  toHex(): string {


lcovar force-pushed the BTC-0.dot-wasm branch from 481b7ac to ede6160 Compare February 6, 2026 06:39

lcovar force-pushed the BTC-0.dot-wasm branch 2 times, most recently from 58a71f1 to 751d3e2 Compare February 19, 2026 22:33

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 force-pushed the BTC-0.dot-wasm branch 11 times, most recently from 3be05b1 to fe73139 Compare February 20, 2026 09:17

lcovar force-pushed the BTC-0.dot-wasm branch from fe73139 to 19a7ab6 Compare February 20, 2026 19:55

lcovar marked this pull request as ready for review February 20, 2026 20:21

lcovar requested a review from a team as a code owner February 20, 2026 20:21

OttoAllmendinger requested changes Feb 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

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

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

lcovar commented Feb 6, 2026 •

edited

Loading

Uh oh!

OttoAllmendinger left a comment

Uh oh!

OttoAllmendinger Feb 23, 2026

Uh oh!

OttoAllmendinger Feb 23, 2026

Uh oh!

OttoAllmendinger Feb 23, 2026

Uh oh!

OttoAllmendinger Feb 23, 2026

Uh oh!

OttoAllmendinger Feb 23, 2026

Uh oh!

OttoAllmendinger Feb 23, 2026

Uh oh!

OttoAllmendinger Feb 23, 2026

Uh oh!

OttoAllmendinger Feb 23, 2026

Uh oh!

OttoAllmendinger Feb 23, 2026

Uh oh!

OttoAllmendinger Feb 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

lcovar commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Architecture

What's included

Key design decisions

Test coverage

Test plan

Uh oh!

OttoAllmendinger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lcovar commented Feb 6, 2026 •

edited

Loading