Merge pull request #8216 from BitGo/SC-5947

feat(irys): implement transaction builder factory for stake and pledge

Author: abhijit0943

modules/sdk-coin-irys/src/lib/commitmentTransactionBuilder.ts

@@ -11,24 +11,24 @@ import {
   AnchorInfo,
   COMMITMENT_TX_VERSION,
 } from './iface';
-import { encodeBase58, decodeBase58ToFixed } from './utils';
+import { encodeBase58, decodeBase58ToFixed, hexAddressToBytes } from './utils';
+
+/** String commitment type for the standard coin API (e.g. wallet-platform) */
+export type CommitmentTypeString = 'STAKE' | 'PLEDGE';
 
 /**
  * Builder for Irys commitment transactions (STAKE, PLEDGE).
  *
  * Commitment transactions are NOT standard EVM transactions. They use a custom
  * 7-field RLP encoding with keccak256 prehash and raw ECDSA signing.
  *
- * Usage (STAKE):
- *   const builder = new IrysCommitmentTransactionBuilder(apiUrl, chainId);
- *   builder.setCommitmentType({ type: CommitmentTypeId.STAKE });
- *   builder.setFee(fee);
- *   builder.setValue(value);
- *   builder.setSigner(signerAddress);
- *   const result = await builder.build(); // fetches anchor, RLP encodes, returns prehash
+ * Usage (standard coin pattern, e.g. from TransactionBuilderFactory):
+ *   const builder = factory.getCommitmentTransactionBuilder();
+ *   builder.setCommitmentType('STAKE').setSigner(hexAddress).setFee('1000').setValue('5000');
+ *   const result = await builder.build(); // { serializedTxHex, signableHex, fields, coinSpecific }
  *
- * Usage (PLEDGE):
- *   builder.setCommitmentType({ type: CommitmentTypeId.PLEDGE, pledgeCount: 0n });
+ * Usage (low-level, for tests or advanced use):
+ *   builder.setCommitmentType({ type: CommitmentTypeId.STAKE }).setSigner(bytes).setFee(1000n)...
  */
 export class IrysCommitmentTransactionBuilder {
   private _irysApiUrl: string;
@@ -38,40 +38,62 @@ export class IrysCommitmentTransactionBuilder {
   private _value?: bigint;
   private _signer?: Uint8Array; // 20 bytes
   private _anchor?: Uint8Array; // 32 bytes (set during build, or manually for testing)
+  private _pledgeCount = 0;
 
   constructor(irysApiUrl: string, chainId: bigint) {
     this._irysApiUrl = irysApiUrl;
     this._chainId = chainId;
   }
 
   /**
-   * Set the commitment type for this transaction.
-   * STAKE is a single-operation type.
-   * PLEDGE requires pledgeCount.
+   * Set the commitment type. Accepts string ('STAKE' | 'PLEDGE') for the standard API
+   * or CommitmentType for low-level use. For PLEDGE string form, use setPledgeCount() before or after.
    */
-  setCommitmentType(type: CommitmentType): this {
-    this._commitmentType = type;
+  setCommitmentType(type: CommitmentType | CommitmentTypeString): this {
+    if (type === 'STAKE') {
+      this._commitmentType = { type: CommitmentTypeId.STAKE };
+    } else if (type === 'PLEDGE') {
+      this._commitmentType = { type: CommitmentTypeId.PLEDGE, pledgeCount: BigInt(this._pledgeCount) };
+    } else {
+      this._commitmentType = type;
+    }
+    return this;
+  }
+
+  /** Set the transaction fee (bigint or string from Irys price API) */
+  setFee(fee: bigint | string): this {
+    this._fee = typeof fee === 'string' ? BigInt(fee) : fee;
+    return this;
+  }
+
+  /** Set the transaction value (bigint or string from Irys price API) */
+  setValue(value: bigint | string): this {
+    this._value = typeof value === 'string' ? BigInt(value) : value;
     return this;
   }
 
-  /** Set the transaction fee (from Irys price API) */
-  setFee(fee: bigint): this {
-    this._fee = fee;
+  /** Set the signer address (hex string with or without 0x, or 20-byte Uint8Array) */
+  setSigner(signer: Uint8Array | string): this {
+    const bytes = typeof signer === 'string' ? hexAddressToBytes(signer) : signer;
+    if (bytes.length !== 20) {
+      throw new Error(`Signer must be 20 bytes, got ${bytes.length}`);
+    }
+    this._signer = bytes;
     return this;
   }
 
-  /** Set the transaction value (from Irys price API) */
-  setValue(value: bigint): this {
-    this._value = value;
+  /** Set the chain ID (number or bigint, e.g. 3282 mainnet, 1270 testnet) */
+  setChainId(chainId: bigint | number): this {
+    this._chainId = typeof chainId === 'number' ? BigInt(chainId) : chainId;
     return this;
   }
 
-  /** Set the signer address (20-byte Ethereum address as Uint8Array) */
-  setSigner(signer: Uint8Array): this {
-    if (signer.length !== 20) {
-      throw new Error(`Signer must be 20 bytes, got ${signer.length}`);
+  /** Set the pledge count for PLEDGE. Call before or after setCommitmentType('PLEDGE'). */
+  setPledgeCount(n: number): this {
+    this._pledgeCount = n;
+    if (this._commitmentType?.type === CommitmentTypeId.PLEDGE) {
+      this._commitmentType = { type: CommitmentTypeId.PLEDGE, pledgeCount: BigInt(n) };
     }
-    this._signer = signer;
     return this;
   }
 
@@ -150,17 +172,11 @@ export class IrysCommitmentTransactionBuilder {
 
   /**
    * Build the unsigned commitment transaction.
-   *
-   * 1. Validates all fields are set
-   * 2. Fetches anchor from Irys API (if not manually set) -- done LAST to minimize expiration
-   * 3. RLP encodes the 7 fields in exact order
-   * 4. Computes keccak256 prehash
-   * 5. Returns prehash (for HSM) and rlpEncoded (for HSM validation)
+   * Returns the standard build result with serializedTxHex, signableHex, fields, and coinSpecific.
    */
   async build(): Promise<CommitmentTransactionBuildResult> {
     this.validateFields();
 
-    // Fetch anchor LAST -- it expires in ~45 blocks (~9 min)
     if (!this._anchor) {
       this._anchor = await this.fetchAnchor();
     }
@@ -178,7 +194,12 @@ export class IrysCommitmentTransactionBuilder {
     const rlpEncoded = this.rlpEncode(fields);
     const prehash = this.computePrehash(rlpEncoded);
 
-    return { prehash, rlpEncoded, fields };
+    return {
+      serializedTxHex: Buffer.from(rlpEncoded).toString('hex'),
+      signableHex: Buffer.from(prehash).toString('hex'),
+      fields,
+      coinSpecific: { keyServerPathPrefix: 'irys' },
+    };
   }
 
   /**

modules/sdk-coin-irys/src/lib/iface.ts

@@ -60,16 +60,20 @@ export interface AnchorInfo {
 }
 
 /**
- * Result of building an unsigned commitment transaction.
- * Contains the prehash (for HSM signing) and the RLP-encoded bytes (for HSM validation).
+ * Build result from the commitment transaction builder (wallet-platform / standard coin pattern).
+ * Exposes serializedTxHex and signableHex for the signing pipeline and coinSpecific for HSM routing.
  */
 export interface CommitmentTransactionBuildResult {
-  /** keccak256(rlpEncoded) - 32 bytes, used as prehash for signing */
-  prehash: Uint8Array;
-  /** Full RLP-encoded transaction bytes - sent to HSM for validation before signing */
-  rlpEncoded: Uint8Array;
-  /** The transaction fields used to build this result */
+  /** Hex string of the RLP-encoded commitment transaction */
+  serializedTxHex: string;
+  /** Hex string of the prehash (keccak256 of RLP-encoded tx) for signing */
+  signableHex: string;
+  /** The transaction fields (for broadcast payload creation if needed) */
   fields: CommitmentTransactionFields;
+  /** Coin-specific data for signing pipeline (e.g. keyServerPathPrefix for HSM routing) */
+  coinSpecific: {
+    keyServerPathPrefix: 'irys';
+  };
 }
 
 /**

modules/sdk-coin-irys/src/lib/index.ts

@@ -1,3 +1,4 @@
 export * from './iface';
 export * from './commitmentTransactionBuilder';
+export * from './transactionBuilderFactory';
 export * from './utils';

modules/sdk-coin-irys/src/lib/transactionBuilderFactory.ts

@@ -0,0 +1,69 @@
+import { BaseCoin as CoinConfig } from '@bitgo/statics';
+import { IrysCommitmentTransactionBuilder } from './commitmentTransactionBuilder';
+import { IRYS_MAINNET_CHAIN_ID, IRYS_TESTNET_CHAIN_ID } from './iface';
+
+/** Irys API base URLs for anchor fetch (mainnet and testnet) */
+const IRYS_MAINNET_API_URL = 'https://mainnet.irys.xyz/v1';
+const IRYS_TESTNET_API_URL = 'https://testnet.irys.xyz/v1';
+
+/** Coin names for mainnet vs testnet */
+const IRYS_MAINNET_NAME = 'irys';
+const IRYS_TESTNET_NAME = 'tirys';
+
+/**
+ * Minimal coin config shape used by the factory to derive API URL and chain ID.
+ * Compatible with coins.get(coinName) from @bitgo/statics.
+ */
+export interface IrysCoinConfigLike {
+  name: string;
+  network: { chainId: number };
+}
+
+function getIrysApiUrlAndChainId(coinConfig: IrysCoinConfigLike): { irysApiUrl: string; chainId: bigint } {
+  const name = coinConfig.name;
+  const chainIdFromNetwork = coinConfig.network?.chainId;
+  if (name === IRYS_MAINNET_NAME) {
+    return {
+      irysApiUrl: IRYS_MAINNET_API_URL,
+      chainId: chainIdFromNetwork !== undefined ? BigInt(chainIdFromNetwork) : IRYS_MAINNET_CHAIN_ID,
+    };
+  }
+  if (name === IRYS_TESTNET_NAME) {
+    return {
+      irysApiUrl: IRYS_TESTNET_API_URL,
+      chainId: chainIdFromNetwork !== undefined ? BigInt(chainIdFromNetwork) : IRYS_TESTNET_CHAIN_ID,
+    };
+  }
+  // Fallback: use chainId from network if present, otherwise default to testnet
+  const chainId = chainIdFromNetwork !== undefined ? BigInt(chainIdFromNetwork) : IRYS_TESTNET_CHAIN_ID;
+  const irysApiUrl = chainId === IRYS_MAINNET_CHAIN_ID ? IRYS_MAINNET_API_URL : IRYS_TESTNET_API_URL;
+  return { irysApiUrl, chainId };
+}
+
+/**
+ * Factory for Irys commitment transaction builders.
+ * Accepts coin config (e.g. from coins.get('irys') or coins.get('tirys')) and provides
+ * getCommitmentTransactionBuilder() for building STAKE/PLEDGE transactions with the
+ * wallet-platform–friendly API (serializedTxHex, signableHex).
+ */
+export class TransactionBuilderFactory {
+  private readonly _coinConfig: Readonly<CoinConfig>;
+  private readonly _irysApiUrl: string;
+  private readonly _chainId: bigint;
+
+  constructor(coinConfig: Readonly<CoinConfig>) {
+    this._coinConfig = coinConfig;
+    const configLike = coinConfig as unknown as IrysCoinConfigLike;
+    const { irysApiUrl, chainId } = getIrysApiUrlAndChainId(configLike);
+    this._irysApiUrl = irysApiUrl;
+    this._chainId = chainId;
+  }
+
+  /**
+   * Returns a commitment transaction builder configured with the factory's
+   * Irys API URL and chain ID. Same pattern as other coins (e.g. getTransferBuilder()).
+   */
+  getCommitmentTransactionBuilder(): IrysCommitmentTransactionBuilder {
+    return new IrysCommitmentTransactionBuilder(this._irysApiUrl, this._chainId);
+  }
+}

modules/sdk-coin-irys/test/unit/commitmentTransactionBuilder.ts

@@ -166,12 +166,14 @@ describe('IrysCommitmentTransactionBuilder', function () {
         .setAnchor(testAnchor);
 
       const result = await builder.build();
-      result.prehash.should.be.instanceOf(Uint8Array);
-      result.prehash.length.should.equal(32);
-      result.rlpEncoded.should.be.instanceOf(Uint8Array);
-      result.rlpEncoded.length.should.be.greaterThan(0);
+      result.signableHex.should.be.a.String();
+      result.signableHex.should.have.length(64);
+      Buffer.from(result.signableHex, 'hex').length.should.equal(32);
+      result.serializedTxHex.should.be.a.String();
+      result.serializedTxHex.length.should.be.greaterThan(0);
       result.fields.version.should.equal(COMMITMENT_TX_VERSION);
       result.fields.chainId.should.equal(testChainId);
+      result.coinSpecific.should.deepEqual({ keyServerPathPrefix: 'irys' });
     });
 
     it('should build a PLEDGE transaction with manually set anchor', async function () {
@@ -183,7 +185,7 @@ describe('IrysCommitmentTransactionBuilder', function () {
         .setAnchor(testAnchor);
 
       const result = await builder.build();
-      result.prehash.length.should.equal(32);
+      result.signableHex.should.have.length(64);
       result.fields.commitmentType.should.deepEqual({ type: CommitmentTypeId.PLEDGE, pledgeCount: 5n });
     });
 
@@ -200,7 +202,7 @@ describe('IrysCommitmentTransactionBuilder', function () {
         .setSigner(testSigner);
 
       const result = await builder.build();
-      result.prehash.length.should.equal(32);
+      result.signableHex.should.have.length(64);
       Buffer.from(result.fields.anchor).equals(Buffer.from(testAnchor)).should.be.true();
       scope.done();
     });
@@ -357,11 +359,11 @@ describe('IrysCommitmentTransactionBuilder', function () {
       const expectedRlp =
         '0xf84702a06c77daebc2db4e572e4f296983d1413fc10d4852e0fabfdb8323c9c69a2b85' +
         '9e9422f9c9f1845d9b6c22b96ef35e46e265ac4af30c018204f6648a043c33c1937564800000';
-      const actualRlp = '0x' + Buffer.from(result.rlpEncoded).toString('hex');
+      const actualRlp = '0x' + result.serializedTxHex;
       actualRlp.should.equal(expectedRlp);
 
       const expectedPrehash = '0xe6fe57810c12785e3ce5fa64e2eb4da120b89ec0e469213715916abf36358d01';
-      const actualPrehash = '0x' + Buffer.from(result.prehash).toString('hex');
+      const actualPrehash = '0x' + result.signableHex;
       actualPrehash.should.equal(expectedPrehash);
     });
 
@@ -385,11 +387,11 @@ describe('IrysCommitmentTransactionBuilder', function () {
       const expectedRlp =
         '0xf84802a00ae16c8476bbde2f28b2e4629d393dfe6fa7affcf0a0c4654f8246a9ba78970594' +
         '22f9c9f1845d9b6c22b96ef35e46e265ac4af30cc202808204f66489337fe5feaf2d180000';
-      const actualRlp = '0x' + Buffer.from(result.rlpEncoded).toString('hex');
+      const actualRlp = '0x' + result.serializedTxHex;
       actualRlp.should.equal(expectedRlp);
 
       const expectedPrehash = '0xfe07c2f3c6e50d9c9e2cff57f6d7015b4528f425b6132f567e26bba745228102';
-      const actualPrehash = '0x' + Buffer.from(result.prehash).toString('hex');
+      const actualPrehash = '0x' + result.signableHex;
       actualPrehash.should.equal(expectedPrehash);
     });
   });
@@ -406,7 +408,7 @@ describe('IrysCommitmentTransactionBuilder', function () {
         .setAnchor(testAnchor);
 
       const result = await builder.build();
-      result.prehash.length.should.equal(32);
+      result.signableHex.should.have.length(64);
     });
   });