diff --git a/CONVENTIONS.md b/CONVENTIONS.md index c4bc12748fd..5996096cc58 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -199,18 +199,18 @@ const tx = Transaction.fromBytes(bytes); // Unnecessary round-trip ### Context/material must be passed at deserialization time -For chains where the byte layout depends on runtime configuration (e.g. Substrate signed extensions), the deserializer needs chain material/metadata to correctly identify field boundaries in the extrinsic bytes. This context must be passed to `fromHex()`/`fromBytes()`, not to `parseTransaction()`. +For chains where the byte layout depends on runtime configuration (e.g. Substrate signed extensions), the deserializer needs chain material/metadata to correctly identify field boundaries in the extrinsic bytes. This context must be passed to `fromHex()`/`fromBytes()`. `parseTransaction(tx)` derives material from the transaction and does not accept a separate parsing context. -If you deserialize without material and the chain has non-standard extensions (e.g. Westend's `AuthorizeCall`, `StorageWeightReclaim`), the call_data boundary lands in the wrong place. At that point the damage is done — `tx.callData` returns wrong bytes. `parseTransaction()` only uses context for name resolution (pallet index → name) and address formatting, not for re-parsing the byte layout. +If you deserialize without material and the chain has non-standard extensions (e.g. Westend's `AuthorizeCall`, `StorageWeightReclaim`), the call_data boundary lands in the wrong place. At that point the damage is done — `tx.callData` returns wrong bytes. `parseTransaction()` uses the transaction's stored material for name resolution (pallet index → name) and address formatting, not for re-parsing the byte layout. ```typescript -// ✅ Material passed at deserialization time +// ✅ Material passed at deserialization time and reused for parsing const tx = DotTransaction.fromHex(hex, material); -const parsed = parseTransaction(tx, { material }); +const parsed = parseTransaction(tx); // ❌ Material passed only at parse time — call_data boundaries are already wrong const tx = DotTransaction.fromHex(hex); // Wrong boundaries baked in -const parsed = parseTransaction(tx, { material }); // Can't fix it +const parsed = parseTransaction(tx); // Cannot recover the correct boundaries ``` **Good:** @@ -344,14 +344,14 @@ The wasm package exports `parseTransaction(tx) → ParsedTransaction`. BitGoJS i ```typescript // In @bitgo/wasm-dot (wasm package) -export function parseTransaction(tx: DotTransaction, context?: ParseContext): ParsedTransaction; +export function parseTransaction(tx: DotTransaction): ParsedTransaction; // In sdk-coin-dot (BitGoJS) — wasmParser.ts import { DotTransaction, parseTransaction } from "@bitgo/wasm-dot"; function buildExplanation(params) { const tx = DotTransaction.fromHex(params.txHex, params.material); - const parsed = parseTransaction(tx, { material: params.material }); + const parsed = parseTransaction(tx); // derive transaction type, extract outputs, map to TransactionExplanation... } ``` diff --git a/packages/wasm-dot/js/index.ts b/packages/wasm-dot/js/index.ts index 8569f2546ae..eac35e65d3b 100644 --- a/packages/wasm-dot/js/index.ts +++ b/packages/wasm-dot/js/index.ts @@ -2,7 +2,7 @@ * wasm-dot: WASM bindings for Polkadot/DOT transaction operations * * This module provides: - * - Transaction parsing: parseTransaction(tx, context) → ParsedTransaction + * - Transaction parsing: parseTransaction(tx) → ParsedTransaction * - Transaction building: buildTransaction(intent, context) → DotTransaction * - Transaction signing: DotTransaction.fromBytes(bytes) → inspect + sign */ diff --git a/packages/wasm-dot/js/parser.ts b/packages/wasm-dot/js/parser.ts index 07c5966a450..c43c56869bb 100644 --- a/packages/wasm-dot/js/parser.ts +++ b/packages/wasm-dot/js/parser.ts @@ -7,9 +7,9 @@ * Use parseTransaction() when you need decoded data. */ -import { ParserNamespace, MaterialJs, ParseContextJs } from "./wasm/wasm_dot.js"; +import { ParserNamespace } from "./wasm/wasm_dot.js"; import type { DotTransaction } from "./transaction.js"; -import type { ParseContext, ParsedTransaction } from "./types.js"; +import type { ParsedTransaction } from "./types.js"; /** * Parse a DOT transaction into structured data. @@ -20,23 +20,21 @@ import type { ParseContext, ParsedTransaction } from "./types.js"; * Returns a plain `ParsedTransaction` object with decoded pallet, method, * args, nonce, tip, era, etc. * - * @param tx - A DotTransaction instance (from DotTransaction.fromBytes()) - * @param context - Parsing context with chain material (required for decoding) + * @param tx - A DotTransaction instance with stored runtime material * @returns Parsed transaction data * * @example * ```typescript * import { DotTransaction, parseTransaction } from '@bitgo/wasm-dot'; * - * const tx = DotTransaction.fromBytes(txBytes, context); - * const parsed = parseTransaction(tx, { material }); + * const tx = DotTransaction.fromBytes(txBytes, material); + * const parsed = parseTransaction(tx); * console.log(parsed.method.pallet); // "balances" * console.log(parsed.method.name); // "transferKeepAlive" * ``` */ -export function parseTransaction(tx: DotTransaction, context?: ParseContext): ParsedTransaction { - const ctx = context ? createParseContext(context) : undefined; - return ParserNamespace.parseFromTransaction(tx.wasm, ctx) as ParsedTransaction; +export function parseTransaction(tx: DotTransaction): ParsedTransaction { + return ParserNamespace.parseFromTransaction(tx.wasm) as ParsedTransaction; } /** @@ -54,18 +52,3 @@ export function parseTransaction(tx: DotTransaction, context?: ParseContext): Pa export function getProxyDepositCost(metadataHex: string): bigint { return BigInt(ParserNamespace.getProxyDepositCost(metadataHex)); } - -/** - * 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); -} diff --git a/packages/wasm-dot/js/transaction.ts b/packages/wasm-dot/js/transaction.ts index db6dfdb15f1..8d6073ee9be 100644 --- a/packages/wasm-dot/js/transaction.ts +++ b/packages/wasm-dot/js/transaction.ts @@ -11,7 +11,7 @@ import { AddressFormat } from "./types.js"; * * Provides a high-level interface for working with DOT transactions. * Handles signing context and serialization — parsing is separate - * (use `parseTransactionData()` from parser.ts). + * (use `parseTransaction()` from parser.ts). */ export class DotTransaction { private _wasm: WasmTransaction; @@ -59,13 +59,12 @@ export class DotTransaction { * * If you deserialize without material and the chain has non-standard * extensions, the call_data boundary lands in the wrong place. At that - * point the damage is done — `tx.callData` returns wrong bytes, and no - * amount of context passed later to `parseTransaction()` can fix it. - * That function only uses context for name resolution (pallet index → - * name) and address formatting, not for re-parsing the byte layout. + * point the damage is done — `tx.callData` returns wrong bytes, and + * parsing cannot repair the byte boundary. `parseTransaction()` uses + * the same stored material for name resolution and address formatting. * - * TL;DR: material must be available at deserialization time, which is - * here in `fromHex`/`fromBytes`, not later in `parseTransaction`. + * TL;DR: material must be available at deserialization time, where it + * remains bound to parsing and signing. * * @param hex - Hex-encoded extrinsic bytes (with or without 0x prefix) * @param material - Chain material from the fullnode (genesisHash, @@ -125,16 +124,15 @@ export class DotTransaction { * Get the signable payload * * Returns the bytes that should be signed with Ed25519. - * Requires context to be set via `setContext()`. + * Requires runtime material and signing context to be set. */ signablePayload(): Uint8Array { return this._wasm.signablePayload(); } /** - * Set the signing context (material, validity, reference block) - * - * Required before calling signablePayload if transaction was created without context + * Update signing validity and reference block while preserving the + * material already bound to this transaction. Different material is rejected. */ setContext(material: Material, validity: Validity, referenceBlock: string): void { const materialJs = new MaterialJs( diff --git a/packages/wasm-dot/js/types.ts b/packages/wasm-dot/js/types.ts index 149b093413a..4a7649f93cb 100644 --- a/packages/wasm-dot/js/types.ts +++ b/packages/wasm-dot/js/types.ts @@ -49,20 +49,6 @@ export interface Validity { maxDuration: number; } -/** - * Context for parsing transactions - */ -export interface ParseContext { - /** Chain material metadata */ - material: Material; - /** Sender address (optional, helps with decoding) */ - sender?: string; - /** Reference block hash (not in extrinsic bytes, pass-through for consumers) */ - referenceBlock?: string; - /** Block number when transaction becomes valid (not in extrinsic bytes, pass-through for consumers) */ - blockNumber?: number; -} - // ============================================================================= // Build Context (how to build the transaction) // ============================================================================= diff --git a/packages/wasm-dot/src/builder/mod.rs b/packages/wasm-dot/src/builder/mod.rs index 0d92300030a..3d51f794063 100644 --- a/packages/wasm-dot/src/builder/mod.rs +++ b/packages/wasm-dot/src/builder/mod.rs @@ -31,13 +31,19 @@ pub fn build_transaction( // Calculate era from validity let era = compute_era(&context.validity); - // Create transaction directly from components (no extrinsic encoding needed). + // Create the transaction with its material attached to this call data. // to_bytes() on unsigned transactions returns signable_payload(), which is the // signing payload format: call_data | era | nonce | tip | extensions | additional_signed. - let mut tx = Transaction::new(call_data, era, context.nonce, context.tip as u128); - tx.set_context(context.material, context.validity, &context.reference_block)?; - - Ok(tx) + Transaction::new_with_context( + call_data, + era, + context.nonce, + context.tip as u128, + context.material, + metadata, + context.validity, + &context.reference_block, + ) } // Re-use the central decode_metadata from transaction.rs diff --git a/packages/wasm-dot/src/parser.rs b/packages/wasm-dot/src/parser.rs index 802ce8645de..d1dd25e1d3f 100644 --- a/packages/wasm-dot/src/parser.rs +++ b/packages/wasm-dot/src/parser.rs @@ -65,37 +65,31 @@ pub fn parse_transaction( bytes: &[u8], context: Option, ) -> Result { - // Extract prefix and decode metadata BEFORE moving context into from_bytes. - // This avoids cloning the entire context (which contains megabytes of metadata hex). + // Extract the address prefix before moving context into the transaction. let prefix = context .as_ref() .map(|ctx| AddressFormat::from_chain_name(&ctx.material.chain_name).prefix()) .unwrap_or(42); // Default to Substrate generic - let metadata = context - .as_ref() - .and_then(|ctx| decode_metadata(&ctx.material.metadata).ok()); - - let tx = Transaction::from_bytes(bytes, context, metadata.as_ref())?; + let tx = Transaction::from_bytes(bytes, context)?; - build_parsed_transaction(&tx, prefix, metadata.as_ref()) + build_parsed_transaction(&tx, prefix, tx.metadata()) } /// Parse a pre-deserialized Transaction into structured data. /// -/// Same logic as `parse_transaction(bytes, context)` but skips deserialization. +/// Parses using the runtime material stored on `tx`. /// Used when the caller already has a `Transaction` from `fromBytes()`. -pub fn parse_from_transaction( - tx: &Transaction, - context: Option<&ParseContext>, -) -> Result { - let prefix = context - .map(|ctx| AddressFormat::from_chain_name(&ctx.material.chain_name).prefix()) - .unwrap_or(42); - - let metadata = context.and_then(|ctx| decode_metadata(&ctx.material.metadata).ok()); +pub fn parse_from_transaction(tx: &Transaction) -> Result { + let material = tx.material().ok_or_else(|| { + WasmDotError::MissingContext("No runtime material stored for transaction".to_string()) + })?; + let metadata = tx.metadata().ok_or_else(|| { + WasmDotError::MissingContext("No runtime metadata stored for transaction".to_string()) + })?; + let prefix = AddressFormat::from_chain_name(&material.chain_name).prefix(); - build_parsed_transaction(tx, prefix, metadata.as_ref()) + build_parsed_transaction(tx, prefix, Some(metadata)) } /// Shared logic for building ParsedTransaction from an already-deserialized Transaction. @@ -121,9 +115,6 @@ fn build_parsed_transaction( }) } -// Re-use the central decode_metadata from transaction.rs -use crate::transaction::decode_metadata; - /// Resolve pallet and call names from metadata using indices. /// /// Returns `(pallet_name, call_name)` in JS-friendly format: diff --git a/packages/wasm-dot/src/transaction.rs b/packages/wasm-dot/src/transaction.rs index ee215373039..767becb5a14 100644 --- a/packages/wasm-dot/src/transaction.rs +++ b/packages/wasm-dot/src/transaction.rs @@ -148,31 +148,55 @@ impl Transaction { } } + /// Create a new transaction already bound to its runtime material. + pub(crate) fn new_with_context( + call_data: Vec, + era: Era, + nonce: u32, + tip: u128, + material: Material, + metadata: Metadata, + validity: Validity, + reference_block: &str, + ) -> Result { + let reference_block = parse_hex_hash(reference_block)?; + let mut tx = Self::new(call_data, era, nonce, tip); + tx.context = Some(TransactionContext { + material, + validity, + reference_block, + metadata: Some(metadata), + }); + Ok(tx) + } + /// Create a transaction from raw bytes /// /// # Arguments /// * `bytes` - Raw extrinsic bytes /// * `context` - Optional parsing context with chain material - pub fn from_bytes( - bytes: &[u8], - context: Option, - metadata: Option<&Metadata>, - ) -> Result { + pub fn from_bytes(bytes: &[u8], context: Option) -> Result { if bytes.is_empty() { return Err(WasmDotError::InvalidTransaction( "Empty transaction".to_string(), )); } + // Decode the same metadata that is retained for parsing and signing. + let metadata = context + .as_ref() + .map(|ctx| decode_metadata(&ctx.material.metadata)) + .transpose()?; + // Parse the extrinsic (metadata-aware for signed extension handling) let (is_signed, signer, signature, era, nonce, tip, call_data) = - parse_extrinsic(bytes, metadata)?; + parse_extrinsic(bytes, metadata.as_ref())?; let tx_context = context.map(|ctx| TransactionContext { material: ctx.material, validity: Validity::default(), reference_block: [0u8; 32], // Unknown from bytes alone - metadata: None, + metadata, }); Ok(Transaction { @@ -400,7 +424,22 @@ impl Transaction { &self.call_data } - /// Set context for the transaction + /// Get the runtime material associated with this transaction. + pub(crate) fn material(&self) -> Option<&Material> { + self.context.as_ref().map(|context| &context.material) + } + + /// Get the decoded runtime metadata associated with this transaction. + pub(crate) fn metadata(&self) -> Option<&Metadata> { + self.context + .as_ref() + .and_then(|context| context.metadata.as_ref()) + } + + /// Update signing context without rebinding established runtime material. + /// + /// Material must already be attached and must match exactly. Only validity + /// and reference block can change. pub fn set_context( &mut self, material: Material, @@ -408,12 +447,18 @@ impl Transaction { reference_block: &str, ) -> Result<(), WasmDotError> { let block_hash = parse_hex_hash(reference_block)?; - self.context = Some(TransactionContext { - material, - validity, - reference_block: block_hash, - metadata: None, - }); + let context = self.context.as_mut().ok_or_else(|| { + WasmDotError::MissingContext( + "Runtime material must be attached when call data is created".to_string(), + ) + })?; + if context.material != material { + return Err(WasmDotError::InvalidTransaction( + "Runtime material cannot be changed after call data is established".to_string(), + )); + } + context.validity = validity; + context.reference_block = block_hash; Ok(()) } @@ -849,4 +894,50 @@ mod tests { let (decoded, _) = decode_era_bytes(&mortal_bytes).unwrap(); assert!(!decoded.is_immortal()); } + + #[test] + fn test_from_bytes_decodes_metadata_from_stored_material() { + let context = ParseContext { + material: Material { + genesis_hash: "0x00".to_string(), + chain_name: "Westend".to_string(), + spec_name: "westend".to_string(), + spec_version: 1, + tx_version: 1, + metadata: "0x00".to_string(), + }, + sender: None, + }; + + let error = Transaction::from_bytes(&[0x00], Some(context)).unwrap_err(); + + assert!( + matches!(error, WasmDotError::InvalidInput(message) if message.contains("Failed to decode metadata")) + ); + } + + #[test] + fn test_set_context_cannot_attach_material_after_call_data_creation() { + let material = Material { + genesis_hash: "0x00".to_string(), + chain_name: "Westend".to_string(), + spec_name: "westend".to_string(), + spec_version: 1, + tx_version: 1, + metadata: "0x00".to_string(), + }; + let nonce = std::process::id(); + let mut tx = Transaction::new(vec![1, 2], Era::Immortal, nonce, 0); + + let error = tx + .set_context( + material, + Validity::default(), + &format!("0x{}", "00".repeat(32)), + ) + .unwrap_err(); + + assert!(matches!(error, WasmDotError::MissingContext(_))); + assert!(tx.material().is_none()); + } } diff --git a/packages/wasm-dot/src/types.rs b/packages/wasm-dot/src/types.rs index caac6bfaf53..57cf7fe9deb 100644 --- a/packages/wasm-dot/src/types.rs +++ b/packages/wasm-dot/src/types.rs @@ -3,7 +3,7 @@ use serde::{Deserialize, Serialize}; /// Chain material metadata required for transaction encoding/decoding -#[derive(Debug, Clone, Serialize, Deserialize)] +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Material { /// Chain genesis hash (e.g., "0x91b171bb158e2d...") diff --git a/packages/wasm-dot/src/wasm/parser.rs b/packages/wasm-dot/src/wasm/parser.rs index 7ebbfc1410a..174a299802c 100644 --- a/packages/wasm-dot/src/wasm/parser.rs +++ b/packages/wasm-dot/src/wasm/parser.rs @@ -52,20 +52,13 @@ impl ParserNamespace { /// Parse a pre-deserialized Transaction into structured data. /// - /// Same as `parseTransaction(bytes)` but accepts an already-deserialized - /// WasmTransaction, avoiding double deserialization when the caller already - /// has a DotTransaction from `fromBytes()`. + /// Parse a pre-deserialized transaction using its stored runtime material. /// - /// @param tx - A WasmTransaction instance - /// @param context - Optional parsing context with chain material + /// @param tx - A WasmTransaction instance with material from deserialization /// @returns Parsed transaction as JSON-compatible JS object #[wasm_bindgen(js_name = parseFromTransaction)] - pub fn parse_from_transaction_wasm( - tx: &WasmTransaction, - context: Option, - ) -> Result { - let ctx = context.map(|c| c.into_inner()); - let parsed = parse_from_transaction(tx.inner(), ctx.as_ref())?; + pub fn parse_from_transaction_wasm(tx: &WasmTransaction) -> Result { + let parsed = parse_from_transaction(tx.inner())?; to_js_value(&parsed) } diff --git a/packages/wasm-dot/src/wasm/transaction.rs b/packages/wasm-dot/src/wasm/transaction.rs index 6290ae7b8cf..a71ae43915b 100644 --- a/packages/wasm-dot/src/wasm/transaction.rs +++ b/packages/wasm-dot/src/wasm/transaction.rs @@ -2,7 +2,7 @@ //! //! Thin wrapper around core Transaction with #[wasm_bindgen] -use crate::transaction::{decode_metadata, Transaction}; +use crate::transaction::Transaction; use crate::types::{Material, ParseContext, Validity}; use crate::WasmDotError; use wasm_bindgen::prelude::*; @@ -23,10 +23,7 @@ impl WasmTransaction { #[wasm_bindgen(constructor)] pub fn new(bytes: &[u8], context: Option) -> Result { let ctx = context.map(|c| c.into_inner()); - let metadata = ctx - .as_ref() - .and_then(|c| decode_metadata(&c.material.metadata).ok()); - let inner = Transaction::from_bytes(bytes, ctx, metadata.as_ref())?; + let inner = Transaction::from_bytes(bytes, ctx)?; Ok(WasmTransaction { inner }) } @@ -46,10 +43,7 @@ impl WasmTransaction { let bytes = hex::decode(hex) .map_err(|e| WasmDotError::InvalidInput(format!("Invalid hex: {}", e)))?; let ctx = context.map(|c| c.into_inner()); - let metadata = ctx - .as_ref() - .and_then(|c| decode_metadata(&c.material.metadata).ok()); - let inner = Transaction::from_bytes(&bytes, ctx, metadata.as_ref())?; + let inner = Transaction::from_bytes(&bytes, ctx)?; Ok(WasmTransaction { inner }) } diff --git a/packages/wasm-dot/test/builder.ts b/packages/wasm-dot/test/builder.ts index 34aa1ad2b93..9f3c571ef8d 100644 --- a/packages/wasm-dot/test/builder.ts +++ b/packages/wasm-dot/test/builder.ts @@ -1,5 +1,11 @@ import * as assert from "assert"; -import { buildTransaction, type TransactionIntent, type BuildContext } from "../js/index.js"; +import { + buildTransaction, + DotTransaction, + parseTransaction, + type TransactionIntent, + type BuildContext, +} from "../js/index.js"; import { getWestendMetadata } from "./resources/westend.js"; /** Convert Uint8Array to hex string (no 0x prefix) */ @@ -36,6 +42,59 @@ describe("buildTransaction", () => { referenceBlock: REFERENCE_BLOCK, }); + describe("transaction metadata binding", () => { + it("parses with stored material and rejects runtime material replacement", () => { + const tx = buildTransaction( + { + type: "payment", + to: RECIPIENT, + amount: 1000000000000n, + }, + testContext(), + ); + const signablePayload = tx.signablePayload(); + + assert.throws(() => + tx.setContext( + { ...WESTEND_MATERIAL, metadata: "0x00" }, + { firstValid: 1000, maxDuration: 2400 }, + REFERENCE_BLOCK, + ), + ); + assert.deepStrictEqual(tx.signablePayload(), signablePayload); + + const parsed = parseTransaction(tx); + assert.strictEqual(parsed.method.pallet, "balances"); + assert.strictEqual(parsed.method.name, "transferKeepAlive"); + assert.strictEqual(parsed.method.args.dest, RECIPIENT); + assert.strictEqual(parsed.method.args.value, "1000000000000"); + }); + + it("derives deserialization metadata from the stored material", () => { + const tx = buildTransaction( + { + type: "payment", + to: RECIPIENT, + amount: 1000000000000n, + }, + testContext(), + ); + const bytes = tx.toBytes(); + + assert.throws( + () => DotTransaction.fromBytes(bytes, { ...WESTEND_MATERIAL, metadata: "0x00" }), + /Failed to decode metadata/, + ); + + const deserialized = DotTransaction.fromBytes(bytes, WESTEND_MATERIAL); + const parsed = parseTransaction(deserialized); + assert.strictEqual(parsed.method.pallet, "balances"); + assert.strictEqual(parsed.method.name, "transferKeepAlive"); + assert.strictEqual(parsed.method.args.dest, RECIPIENT); + assert.strictEqual(parsed.method.args.value, "1000000000000"); + }); + }); + describe("payment", () => { it("should build a payment transaction (transferKeepAlive)", () => { const intent: TransactionIntent = {