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

[lcovar]

Summary

add wasm-dot package for Polkadot/Substrate transaction building, parsing, and signing. follows wasm-utxo conventions: Uint8Array only, signing separate from parsing, get wasm() for internal access.

API

three entry points:

1. DotTransaction.fromBytes(bytes) — deserialize for signing
2. parseTransaction(bytes, context) — decode into structured data
3. explainTransaction(bytes, options) — high-level explanation with type derivation

// signing
const tx = DotTransaction.fromBytes(txBytes);
tx.addSignature(signature, pubkey);
const signedBytes = tx.toBytes();

// parsing
const parsed = parseTransaction(txBytes, { material });
console.log(parsed.method.pallet); // "balances"
console.log(parsed.method.name);   // "transferKeepAlive"

// explaining
const explained = explainTransaction(txBytes, { context: { material } });
console.log(explained.type); // TransactionType.Send
console.log(explained.outputs); // [{ address, amount }]

architecture

Rust (parser.rs, builder/) → SCALE encoding/decoding
TS (explain.ts)            → business logic (type derivation, output extraction)

rust handles SCALE binary format (compact integers, MultiAddress, era encoding, recursive batch/proxy calls). typescript handles explain layer — deriving transaction types from pallet+method, extracting outputs/inputs. business logic changes don't require WASM rebuilds.

what's included

builder — build from declarative intents:

• transfer, transferAll, stake, unstake, withdrawUnbonded, chill
• addProxy, removeProxy
• batch / batchAll with nested call encoding
• accepts JS BigInt for amounts (u64 — matches wasm-solana)
• mortal/immortal eras, tips, nonce

parser — decode SCALE 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 (depth-limited, max 10)

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)

conventions followed

• Uint8Array everywhere (no hex methods on Transaction)
• parsing separate from Transaction class (standalone parseTransaction function)
• get wasm() accessor (not getInner())
• DotTransaction.fromBytes() for signing (no top-level parseTransaction that returns Transaction)
• callers do their own base conversions

test coverage

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

test plan

• cargo test — 28 passing
• cargo fmt + cargo clippy — clean
• npm run build — WASM + TypeScript compilation
• npm test — 30 passing
• npx prettier --check — clean

Tickets

• BTC-3064 — Transaction deserialization and signing
• BTC-3065 — Transaction parsing and call data decoding
• BTC-3066 — Transaction explanation
• BTC-3067 — Transaction building

[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]

much better

[OttoAllmendinger]

( ͡° ͜ʖ ͡°)

[OttoAllmendinger]

seriously consider Uint8Array

[lcovar]

hesitating a bit since its a string anyway when we fetch from the node so ill just be doing a back and forth conversion but i understand your hate for strings

[lcovar]

https://github.com/BitGo/BitGoWASM/pull/178/changes

[OttoAllmendinger]

well do we end up decoding it anyway or does it stay a string the whole time?

[lcovar]

ah it gets decoded to bytes so might as well start out with bytes.