feat(sdk-coin-tempo): implement tx deserialization, structured outputs, and field accessors

Ticket: CECHO-286

Author: nayandas190

modules/sdk-coin-tempo/src/lib/transaction.ts

@@ -9,6 +9,7 @@ import { BaseTransaction, ParseTransactionError, TransactionType } from '@bitgo/
 import { BaseCoin as CoinConfig } from '@bitgo/statics';
 import { ethers } from 'ethers';
 import { Address, Hex, Tip20Operation } from './types';
+import { amountToTip20Units } from './utils';
 
 /**
  * TIP-20 Transaction Request Structure
@@ -44,6 +45,15 @@ export class Tip20Transaction extends BaseTransaction {
     super(_coinConfig);
     this.txRequest = request;
     this._operations = operations;
+    // One output per operation: value in base units (6 decimals), coin is the token contract address
+    this._outputs = operations.map((op) => ({
+      address: op.to,
+      value: amountToTip20Units(op.amount).toString(),
+      coin: op.token,
+    }));
+    // Single input entry with total in base units; address is empty for unsigned transactions
+    const totalUnits = operations.reduce((sum, op) => sum + amountToTip20Units(op.amount), 0n);
+    this._inputs = [{ address: '', value: totalUnits.toString(), coin: _coinConfig.name }];
   }
 
   get type(): TransactionType {
@@ -117,17 +127,17 @@ export class Tip20Transaction extends BaseTransaction {
   }
 
   /**
-   * Encode secp256k1 signature as 65-byte envelope
+   * Encode secp256k1 signature as 65-byte envelope.
+   * Follows EIP-2718 typed transaction convention: v = yParity (0 or 1).
    * @param signature ECDSA signature components
    * @returns Hex string of concatenated r (32) + s (32) + v (1) bytes
    * @private
    */
   private encodeSignature(signature: { r: Hex; s: Hex; yParity: number }): string {
-    const v = signature.yParity + 27;
     const signatureBytes = ethers.utils.concat([
       ethers.utils.zeroPad(signature.r, 32),
       ethers.utils.zeroPad(signature.s, 32),
-      ethers.utils.hexlify(v),
+      ethers.utils.hexlify(signature.yParity),
     ]);
     return ethers.utils.hexlify(signatureBytes);
   }
@@ -170,6 +180,37 @@ export class Tip20Transaction extends BaseTransaction {
     return [...this._operations];
   }
 
+  /** Transaction nonce */
+  get nonce(): number {
+    return this.txRequest.nonce;
+  }
+
+  /** Chain ID of the Tempo network */
+  get chainId(): number {
+    return this.txRequest.chainId;
+  }
+
+  /** Gas limit as a decimal string */
+  get gasLimit(): string {
+    return this.txRequest.gas.toString();
+  }
+
+  /** Maximum fee per gas as a decimal string (wei) */
+  get maxFeePerGas(): string {
+    return this.txRequest.maxFeePerGas.toString();
+  }
+
+  /** Maximum priority fee per gas as a decimal string (wei) */
+  get maxPriorityFeePerGas(): string {
+    return this.txRequest.maxPriorityFeePerGas.toString();
+  }
+
+  /** TIP-20 fee token contract address, or undefined if the native token is used */
+  get feeToken(): string | undefined {
+    return this.txRequest.feeToken;
+  }
+
+  /** @deprecated Use the `feeToken` getter instead */
   getFeeToken(): Address | undefined {
     return this.txRequest.feeToken;
   }
@@ -209,8 +250,15 @@ export class Tip20Transaction extends BaseTransaction {
     return await this.serialize(this._signature);
   }
 
+  /** @inheritdoc */
   get id(): string {
-    return 'pending';
+    try {
+      // Compute keccak256 of the serialized transaction (signed if available, otherwise unsigned)
+      const serialized = this.serializeTransaction(this._signature);
+      return ethers.utils.keccak256(ethers.utils.arrayify(serialized));
+    } catch {
+      return 'pending';
+    }
   }
 
   toString(): string {

modules/sdk-coin-tempo/src/lib/transactionBuilder.ts

@@ -8,12 +8,29 @@
  * - EIP-7702 Account Abstraction (type 0x76)
  */
 
-import { TransactionBuilder as AbstractTransactionBuilder, TransferBuilder } from '@bitgo/abstract-eth';
-import { BaseTransaction, BuildTransactionError } from '@bitgo/sdk-core';
+import {
+  Transaction as EthTransaction,
+  TransactionBuilder as AbstractTransactionBuilder,
+  TransferBuilder,
+} from '@bitgo/abstract-eth';
+import {
+  BaseTransaction,
+  BuildTransactionError,
+  InvalidTransactionError,
+  ParseTransactionError,
+} from '@bitgo/sdk-core';
 import { BaseCoin as CoinConfig } from '@bitgo/statics';
+import { ethers } from 'ethers';
 import { Address, Hex, Tip20Operation } from './types';
 import { Tip20Transaction, Tip20TransactionRequest } from './transaction';
-import { amountToTip20Units, encodeTip20TransferWithMemo, isValidAddress, isValidTip20Amount } from './utils';
+import {
+  amountToTip20Units,
+  encodeTip20TransferWithMemo,
+  isValidAddress,
+  isValidTip20Amount,
+  tip20UnitsToAmount,
+} from './utils';
+import { TIP20_TRANSFER_WITH_MEMO_ABI } from './tip20Abi';
 import { AA_TRANSACTION_TYPE } from './constants';
 
 /**
@@ -27,6 +44,7 @@ export class Tip20TransactionBuilder extends AbstractTransactionBuilder {
   private _gas?: bigint;
   private _maxFeePerGas?: bigint;
   private _maxPriorityFeePerGas?: bigint;
+  private _restoredSignature?: { r: Hex; s: Hex; yParity: number };
 
   constructor(_coinConfig: Readonly<CoinConfig>) {
     super(_coinConfig);
@@ -74,8 +92,165 @@ export class Tip20TransactionBuilder extends AbstractTransactionBuilder {
     }
   }
 
+  /** @inheritdoc */
+  validateRawTransaction(rawTransaction: any): void {
+    if (!rawTransaction) {
+      throw new InvalidTransactionError('Raw transaction is empty');
+    }
+    if (typeof rawTransaction !== 'string') {
+      throw new InvalidTransactionError('Transaction is not a hex string or stringified json');
+    }
+    // Accept Tempo AA transactions (type 0x76)
+    if (/^0x76[0-9a-f]+$/i.test(rawTransaction)) {
+      try {
+        ethers.utils.RLP.decode('0x' + rawTransaction.slice(4));
+        return;
+      } catch (e) {
+        throw new ParseTransactionError(`Failed to RLP decode TIP-20 transaction: ${e}`);
+      }
+    }
+    // Fall back to parent validation for standard ETH hex or JSON formats
+    super.validateRawTransaction(rawTransaction);
+  }
+
+  /** @inheritdoc */
+  protected fromImplementation(rawTransaction: string, isFirstSigner?: boolean): EthTransaction {
+    if (!rawTransaction) {
+      throw new InvalidTransactionError('Raw transaction is empty');
+    }
+    if (/^0x76[0-9a-f]+$/i.test(rawTransaction)) {
+      // Cast is safe: Tip20Transaction shares the BaseTransaction contract and the builder
+      // only uses the transaction through BaseTransaction's interface after from().
+      return this.fromTip20Transaction(rawTransaction) as unknown as EthTransaction;
+    }
+    return super.fromImplementation(rawTransaction, isFirstSigner);
+  }
+
+  /**
+   * Deserialize a Tempo AA transaction (type 0x76) from its hex-encoded RLP form
+   * and restore builder state so the transaction can be re-built or signed.
+   *
+   * RLP field layout (from buildBaseRlpData in transaction.ts):
+   *   [0]  chainId
+   *   [1]  maxPriorityFeePerGas
+   *   [2]  maxFeePerGas
+   *   [3]  gas
+   *   [4]  calls[ [to, value, data], ... ]
+   *   [5]  accessList
+   *   [6]  nonceKey  (2D-nonce reserved, '0x')
+   *   [7]  nonce
+   *   [8]  validBefore (time-bound reserved, '0x')
+   *   [9]  validAfter  (time-bound reserved, '0x')
+   *   [10] feeToken
+   *   [11] feePayerSignature (sponsorship reserved, '0x')
+   *   [12] authorizationList
+   *   [13] signature (65-byte envelope, if signed)
+   */
+  private fromTip20Transaction(rawTransaction: string): Tip20Transaction {
+    try {
+      const rlpHex = '0x' + rawTransaction.slice(4); // strip '0x76'
+      const decoded = ethers.utils.RLP.decode(rlpHex) as any[];
+
+      if (!Array.isArray(decoded) || decoded.length < 13) {
+        throw new ParseTransactionError('Invalid TIP-20 transaction: unexpected RLP structure');
+      }
+
+      const parseBigInt = (hex: string): bigint => (!hex || hex === '0x' ? 0n : BigInt(hex));
+      const parseHexInt = (hex: string): number => (!hex || hex === '0x' ? 0 : parseInt(hex, 16));
+
+      const chainId = parseHexInt(decoded[0] as string);
+      const maxPriorityFeePerGas = parseBigInt(decoded[1] as string);
+      const maxFeePerGas = parseBigInt(decoded[2] as string);
+      const gas = parseBigInt(decoded[3] as string);
+      const callsTuples = decoded[4] as string[][];
+      const nonce = parseHexInt(decoded[7] as string);
+      const feeTokenRaw = decoded[10] as string;
+
+      const calls: { to: Address; data: Hex; value: bigint }[] = callsTuples.map((tuple) => ({
+        to: tuple[0] as Address,
+        value: parseBigInt(tuple[1] as string),
+        data: tuple[2] as Hex,
+      }));
+
+      const operations: Tip20Operation[] = calls.map((call) => this.decodeCallToOperation(call));
+
+      // Parse optional signature at index [13] (65-byte r+s+v envelope)
+      let signature: { r: Hex; s: Hex; yParity: number } | undefined;
+      if (decoded.length >= 14 && decoded[13] && (decoded[13] as string).length > 2) {
+        const sigBytes = ethers.utils.arrayify(decoded[13] as string);
+        if (sigBytes.length === 65) {
+          const r = ethers.utils.hexlify(sigBytes.slice(0, 32)) as Hex;
+          const s = ethers.utils.hexlify(sigBytes.slice(32, 64)) as Hex;
+          const v = sigBytes[64];
+          // Handle both EIP-2718 convention (v=0/1) and legacy offset (v=27/28)
+          const yParity = v > 1 ? v - 27 : v;
+          signature = { r, s, yParity };
+        }
+      }
+
+      const feeToken = feeTokenRaw && feeTokenRaw !== '0x' ? (feeTokenRaw as Address) : undefined;
+
+      const txRequest: Tip20TransactionRequest = {
+        type: AA_TRANSACTION_TYPE,
+        chainId,
+        nonce,
+        maxFeePerGas,
+        maxPriorityFeePerGas,
+        gas,
+        calls,
+        accessList: [],
+        feeToken,
+      };
+
+      // Restore builder state so validateTransaction() passes after from()
+      this._nonce = nonce;
+      this._gas = gas;
+      this._maxFeePerGas = maxFeePerGas;
+      this._maxPriorityFeePerGas = maxPriorityFeePerGas;
+      this._feeToken = feeToken;
+      this.operations = operations;
+      // Preserve signature so buildImplementation() can re-apply it
+      this._restoredSignature = signature;
+
+      const tx = new Tip20Transaction(this._coinConfig, txRequest, operations);
+      if (signature) {
+        tx.setSignature(signature);
+      }
+      return tx;
+    } catch (e) {
+      if (e instanceof ParseTransactionError) throw e;
+      throw new ParseTransactionError(`Failed to deserialize TIP-20 transaction: ${e}`);
+    }
+  }
+
+  /**
+   * Decode a single AA call's data back into a Tip20Operation.
+   * Expects the call data to encode transferWithMemo(address, uint256, bytes32).
+   */
+  private decodeCallToOperation(call: { to: Address; data: Hex; value: bigint }): Tip20Operation {
+    const iface = new ethers.utils.Interface(TIP20_TRANSFER_WITH_MEMO_ABI);
+    try {
+      const decoded = iface.decodeFunctionData('transferWithMemo', call.data);
+      const toAddress = decoded[0] as string;
+      const amountUnits = BigInt(decoded[1].toString());
+      const memoBytes32 = decoded[2] as string;
+
+      const amount = tip20UnitsToAmount(amountUnits);
+
+      // Decode memo: bytes32 is left-padded with zeros via hexZeroPad, so strip leading zeros
+      const stripped = ethers.utils.stripZeros(memoBytes32);
+      const memo = stripped.length > 0 ? ethers.utils.toUtf8String(stripped) : undefined;
+
+      return { token: call.to, to: toAddress, amount, memo };
+    } catch {
+      // Fallback for unrecognised call data (e.g., native coin value transfers)
+      return { token: call.to, to: call.to, amount: tip20UnitsToAmount(call.value) };
+    }
+  }
+
   /**
    * Build the transaction from configured TIP-20 operations and transaction parameters.
+   * Signs with _sourceKeyPair if it has been set via sign({ key }).
    */
   protected async buildImplementation(): Promise<BaseTransaction> {
     if (
@@ -110,7 +285,28 @@ export class Tip20TransactionBuilder extends AbstractTransactionBuilder {
       feeToken: this._feeToken,
     };
 
-    return new Tip20Transaction(this._coinConfig, txRequest, this.operations);
+    const tx = new Tip20Transaction(this._coinConfig, txRequest, this.operations);
+
+    // Re-apply a signature that was parsed from a serialized transaction
+    if (this._restoredSignature) {
+      tx.setSignature(this._restoredSignature);
+    }
+
+    // Sign if a key pair was provided via sign({ key })
+    if (this._sourceKeyPair && this._sourceKeyPair.getKeys().prv) {
+      const prv = this._sourceKeyPair.getKeys().prv!;
+      const unsignedHex = await tx.serialize();
+      const msgHash = ethers.utils.keccak256(ethers.utils.arrayify(unsignedHex));
+      const signingKey = new ethers.utils.SigningKey('0x' + prv);
+      const sig = signingKey.signDigest(ethers.utils.arrayify(msgHash));
+      tx.setSignature({
+        r: sig.r as Hex,
+        s: sig.s as Hex,
+        yParity: sig.recoveryParam ?? 0,
+      });
+    }
+
+    return tx;
   }
 
   /**