feat(sdk-coin-polyx): add NominateBuilder for standalone nominate transactions (SI-686)

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

@@ -18,6 +18,7 @@ export { RejectInstructionBuilder } from './rejectInstructionBuilder';
 export { Transaction as PolyxTransaction } from './transaction';
 export { BondExtraBuilder } from './bondExtraBuilder';
 export { BatchStakingBuilder as BatchBuilder } from './batchStakingBuilder';
+export { NominateBuilder } from './nominateBuilder';
 export { BatchUnstakingBuilder } from './batchUnstakingBuilder';
 export { UnbondBuilder } from './unbondBuilder';
 export { WithdrawUnbondedBuilder } from './withdrawUnbondedBuilder';

modules/sdk-coin-polyx/src/lib/nominateBuilder.ts

@@ -0,0 +1,111 @@
+import { Transaction } from './transaction';
+import { PolyxBaseBuilder } from './baseBuilder';
+import { DecodedSignedTx, DecodedSigningPayload, UnsignedTransaction } from '@substrate/txwrapper-core';
+import { methods } from '@substrate/txwrapper-polkadot';
+import { BaseCoin as CoinConfig } from '@bitgo/statics';
+import { InvalidTransactionError, TransactionType } from '@bitgo/sdk-core';
+import { NominateTransactionSchema } from './txnSchema';
+import utils from './utils';
+import { NominateArgs } from './iface';
+
+export class NominateBuilder extends PolyxBaseBuilder {
+  protected _validators: string[] = [];
+
+  constructor(_coinConfig: Readonly<CoinConfig>) {
+    super(_coinConfig);
+    this.material(utils.getMaterial(_coinConfig.network.type));
+  }
+
+  protected get transactionType(): TransactionType {
+    return TransactionType.StakingVote;
+  }
+
+  validators(validators: string[]): this {
+    if (validators.length === 0) {
+      throw new InvalidTransactionError('validators must have at least 1 entry');
+    }
+    if (validators.length > 16) {
+      throw new InvalidTransactionError('validators must have at most 16 entries');
+    }
+    for (const address of validators) {
+      this.validateAddress({ address });
+    }
+    this._validators = validators;
+    return this;
+  }
+
+  getValidators(): string[] {
+    return this._validators;
+  }
+
+  protected buildTransaction(): UnsignedTransaction {
+    if (this._validators.length === 0) {
+      throw new InvalidTransactionError('validators must have at least 1 entry');
+    }
+
+    const baseTxInfo = this.createBaseTxInfo();
+
+    return methods.staking.nominate({ targets: this._validators }, baseTxInfo.baseTxInfo, baseTxInfo.options);
+  }
+
+  validateDecodedTransaction(decodedTxn: DecodedSigningPayload | DecodedSignedTx): void {
+    const methodName = decodedTxn.method?.name as string;
+    if (methodName !== 'nominate') {
+      throw new InvalidTransactionError(`Invalid transaction type: ${methodName}`);
+    }
+
+    const args = decodedTxn.method.args as unknown as NominateArgs;
+    const targetAddresses = args.targets.map((target) => {
+      if (typeof target === 'string') {
+        return target;
+      } else if (target && typeof target === 'object' && 'id' in target) {
+        return (target as { id: string }).id;
+      }
+      throw new InvalidTransactionError(`Invalid target format: ${JSON.stringify(target)}`);
+    });
+
+    const validationResult = NominateTransactionSchema.validate({ validators: targetAddresses });
+    if (validationResult.error) {
+      throw new InvalidTransactionError(`Invalid nominate args: ${validationResult.error.message}`);
+    }
+  }
+
+  protected fromImplementation(rawTransaction: string): Transaction {
+    const tx = super.fromImplementation(rawTransaction);
+
+    if ((this._method?.name as string) !== 'nominate') {
+      throw new InvalidTransactionError(`Invalid Transaction Type: ${this._method?.name}. Expected nominate`);
+    }
+
+    if (this._method) {
+      const args = this._method.args as unknown as NominateArgs;
+      const targetAddresses = args.targets.map((target) => {
+        if (typeof target === 'string') {
+          return target;
+        } else if (target && typeof target === 'object' && 'id' in target) {
+          return (target as { id: string }).id;
+        }
+        throw new InvalidTransactionError(`Invalid target format: ${JSON.stringify(target)}`);
+      });
+      this._validators = targetAddresses;
+    }
+
+    return tx;
+  }
+
+  validateTransaction(tx: Transaction): void {
+    super.validateTransaction(tx);
+    this.validateFields();
+  }
+
+  private validateFields(): void {
+    if (this._validators.length === 0) {
+      throw new InvalidTransactionError('validators must have at least 1 entry');
+    }
+
+    const validationResult = NominateTransactionSchema.validate({ validators: this._validators });
+    if (validationResult.error) {
+      throw new InvalidTransactionError(`Invalid transaction: ${validationResult.error.message}`);
+    }
+  }
+}

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

@@ -16,6 +16,7 @@ import { Transaction as PolyxTransaction } from './transaction';
 import { PreApproveAssetBuilder } from './preApproveAssetBuilder';
 import { TokenTransferBuilder } from './tokenTransferBuilder';
 import { RejectInstructionBuilder } from './rejectInstructionBuilder';
+import { NominateBuilder } from './nominateBuilder';
 
 export type SupportedTransaction = BaseTransaction | PolyxTransaction;
 
@@ -67,6 +68,10 @@ export class TransactionBuilderFactory extends BaseTransactionBuilderFactory {
     return new WithdrawUnbondedBuilder(this._coinConfig).material(this._material);
   }
 
+  getNominateBuilder(): NominateBuilder {
+    return new NominateBuilder(this._coinConfig).material(this._material);
+  }
+
   getWalletInitializationBuilder(): void {
     throw new NotImplementedError(`walletInitialization for ${this._coinConfig.name} not implemented`);
   }
@@ -126,7 +131,7 @@ export class TransactionBuilderFactory extends BaseTransactionBuilderFactory {
     } else if (methodName === 'bond') {
       return this.getBatchBuilder();
     } else if (methodName === 'nominate') {
-      return this.getBatchBuilder();
+      return this.getNominateBuilder();
     } else if (methodName === 'unbond') {
       return this.getUnbondBuilder();
     } else if (methodName === 'withdrawUnbonded') {

modules/sdk-coin-polyx/src/lib/txnSchema.ts

@@ -119,9 +119,9 @@ export const BondExtraTransactionSchema = joi.object({
   value: joi.string().required(),
 });
 
-// For nominate transactions in batch
+// For nominate transactions (standalone or in batch)
 export const NominateTransactionSchema = joi.object({
-  validators: joi.array().items(addressSchema).min(1).required(),
+  validators: joi.array().items(addressSchema).min(1).max(16).required(),
 });
 
 // For batch validation
@@ -141,7 +141,7 @@ export const BatchTransactionSchema = {
             })
           )
           .required(),
-        validators: joi.array().items(addressSchema).min(1).required(),
+        validators: joi.array().items(addressSchema).min(1).max(16).required(),
       })
       .validate(value),
 
@@ -165,7 +165,7 @@ export const BatchTransactionSchema = {
   validateNominate: (value: NominateValidationObject): joi.ValidationResult =>
     joi
       .object({
-        validators: joi.array().items(addressSchema).min(1).required(),
+        validators: joi.array().items(addressSchema).min(1).max(16).required(),
       })
       .validate(value),
 };

modules/sdk-coin-polyx/test/resources/index.ts

@@ -136,6 +136,20 @@ export const stakingTx = {
   },
 };
 
+export const nominateTx = {
+  unsigned:
+    '0x11050800025237fdbea82f075296416fa096d3b9807c4f8763d7c3474fdd7470073798110060c819a103b56679947c39924a7cc616cb78e84da6c5303ebe1521b3feb62813',
+  signed:
+    '0xb10284001ed73dfc30f7b1359d92004d6954ea47a1e447f813f637ec44302a9f6d773d4a01822b6f38948c972764afe53df261221dfd65f79bd51517f4384d5669a36aad6a78290cc4c6a678c3ebe698799232a08792cd063e051a642d355bdaa166225d8ec5033c0011050800025237fdbea82f075296416fa096d3b9807c4f8763d7c3474fdd7470073798110060c819a103b56679947c39924a7cc616cb78e84da6c5303ebe1521b3feb62813',
+};
+
+export const nominateSender = '5Cm9EXKwcDDNVNDFSUnsp46YCA7QmMVAaRKSFeeCUed1Jbix';
+
+export const nominateValidators = [
+  '5C7kNpSvVr22Z1X6gVAUjfahSJfSpvw4DHNoY7uUHpLfEJZR',
+  '5EFbtwDBQu64WjUGqAgC3kuaiH86E34CHtqxbN7zAgwwT2cg',
+];
+
 export const { txVersion, specVersion, genesisHash, chainName, specName } = Networks.test.polyx;
 export const {
   txVersion: mainTxVersion,

modules/sdk-coin-polyx/test/unit/transactionBuilder/nominateBuilder.ts

@@ -0,0 +1,193 @@
+import { decode } from '@substrate/txwrapper-polkadot';
+import { coins } from '@bitgo/statics';
+import should from 'should';
+import { TransactionBuilderFactory, NominateBuilder, BatchBuilder } from '../../../src/lib';
+import { TransactionType } from '@bitgo/sdk-core';
+import utils from '../../../src/lib/utils';
+import { accounts, nominateTx, nominateValidators, stakingTx } from '../../resources';
+
+describe('Polyx Nominate Builder', function () {
+  let builder: NominateBuilder;
+  const factory = new TransactionBuilderFactory(coins.get('tpolyx'));
+
+  const senderAddress = accounts.account1.address;
+  const validatorAddress = nominateValidators[0];
+  const validatorAddress2 = nominateValidators[1];
+
+  beforeEach(() => {
+    builder = factory.getNominateBuilder();
+  });
+
+  describe('transaction type', () => {
+    it('should return StakingVote transaction type', () => {
+      should.equal(builder['transactionType'], TransactionType.StakingVote);
+    });
+  });
+
+  describe('validators setter validation', () => {
+    it('should reject empty validators array', () => {
+      should.throws(() => builder.validators([]), /at least 1/);
+    });
+
+    it('should reject more than 16 validators', () => {
+      const tooMany = Array(17).fill(validatorAddress);
+      should.throws(() => builder.validators(tooMany), /at most 16/);
+    });
+
+    it('should reject malformed validator addresses', () => {
+      should.throws(() => builder.validators(['not-a-valid-address']), /is not a well-formed/);
+    });
+
+    it('should accept valid single validator', () => {
+      should.doesNotThrow(() => builder.validators([validatorAddress]));
+      should.deepEqual(builder.getValidators(), [validatorAddress]);
+    });
+
+    it('should accept multiple valid validators', () => {
+      should.doesNotThrow(() => builder.validators([validatorAddress, validatorAddress2]));
+      should.deepEqual(builder.getValidators(), [validatorAddress, validatorAddress2]);
+    });
+
+    it('should accept exactly 16 validators', () => {
+      const exactly16 = Array(16).fill(validatorAddress);
+      should.doesNotThrow(() => builder.validators(exactly16));
+    });
+  });
+
+  describe('build unsigned nominate transaction', () => {
+    it('should build an unsigned nominate transaction', async () => {
+      const material = utils.getMaterial(coins.get('tpolyx').network.type);
+      builder
+        .validators([validatorAddress, validatorAddress2])
+        .sender({ address: senderAddress })
+        .validity({ firstValid: 3933, maxDuration: 64 })
+        .referenceBlock('0x149799bc9602cb5cf201f3425fb8d253b2d4e61fc119dcab3249f307f594754d')
+        .sequenceId({ name: 'Nonce', keyword: 'nonce', value: 15 })
+        .fee({ amount: 0, type: 'tip' })
+        .material(material);
+
+      const tx = await builder.build();
+      should.exist(tx);
+      should.equal(tx.type, TransactionType.StakingVote);
+    });
+  });
+
+  describe('build signed nominate transaction', () => {
+    it('should parse a signed nominate transaction from hex', () => {
+      const material = utils.getMaterial(coins.get('tpolyx').network.type);
+      const signedBuilder = factory.getNominateBuilder();
+      signedBuilder.material(material);
+      signedBuilder.from(nominateTx.signed);
+
+      const validators = signedBuilder.getValidators();
+      should.exist(validators);
+      validators.length.should.be.greaterThan(0);
+    });
+  });
+
+  describe('validateDecodedTransaction', () => {
+    it('should reject non-nominate method name', () => {
+      const mockDecoded = {
+        method: { name: 'bond', pallet: 'staking', args: {} },
+      };
+      should.throws(() => builder.validateDecodedTransaction(mockDecoded as never), /Invalid transaction type/);
+    });
+
+    it('should validate a real built nominate transaction', () => {
+      const material = utils.getMaterial(coins.get('tpolyx').network.type);
+      builder
+        .validators([validatorAddress, validatorAddress2])
+        .sender({ address: senderAddress })
+        .validity({ firstValid: 3933, maxDuration: 64 })
+        .referenceBlock('0x149799bc9602cb5cf201f3425fb8d253b2d4e61fc119dcab3249f307f594754d')
+        .sequenceId({ name: 'Nonce', keyword: 'nonce', value: 15 })
+        .fee({ amount: 0, type: 'tip' })
+        .material(material);
+
+      const unsignedTx = builder['buildTransaction']();
+      const decodedTx = decode(unsignedTx, {
+        metadataRpc: material.metadata,
+        registry: builder['_registry'],
+      });
+
+      should.equal(decodedTx.method.name, 'nominate');
+      should.doesNotThrow(() => builder.validateDecodedTransaction(decodedTx));
+    });
+  });
+
+  describe('parse from raw signed transaction', () => {
+    it('should parse signed nominate tx and recover validators', () => {
+      const material = utils.getMaterial(coins.get('tpolyx').network.type);
+      const newBuilder = factory.getNominateBuilder();
+      newBuilder.material(material);
+      newBuilder.from(nominateTx.signed);
+
+      const validators = newBuilder.getValidators();
+      should.exist(validators);
+      validators.length.should.be.greaterThan(0);
+    });
+  });
+
+  describe('parse from raw unsigned transaction', () => {
+    it('should parse unsigned nominate tx and recover validators', async () => {
+      const material = utils.getMaterial(coins.get('tpolyx').network.type);
+      // Build a real unsigned tx first, then parse it back
+      const originalBuilder = factory.getNominateBuilder();
+      originalBuilder
+        .validators([validatorAddress, validatorAddress2])
+        .sender({ address: senderAddress })
+        .validity({ firstValid: 3933, maxDuration: 64 })
+        .referenceBlock('0x149799bc9602cb5cf201f3425fb8d253b2d4e61fc119dcab3249f307f594754d')
+        .sequenceId({ name: 'Nonce', keyword: 'nonce', value: 15 })
+        .fee({ amount: 0, type: 'tip' })
+        .material(material);
+
+      const tx = await originalBuilder.build();
+      const rawHex = tx.toBroadcastFormat();
+
+      const newBuilder = factory.getNominateBuilder();
+      newBuilder.material(material);
+      newBuilder.from(rawHex);
+
+      const validators = newBuilder.getValidators();
+      should.exist(validators);
+      should.deepEqual(validators, [validatorAddress, validatorAddress2]);
+    });
+  });
+
+  describe('round-trip', () => {
+    it('should rebuild from serialized unsigned transaction and preserve validators', async () => {
+      const material = utils.getMaterial(coins.get('tpolyx').network.type);
+      const originalBuilder = factory.getNominateBuilder();
+      originalBuilder
+        .validators([validatorAddress, validatorAddress2])
+        .sender({ address: senderAddress })
+        .validity({ firstValid: 3933, maxDuration: 64 })
+        .referenceBlock('0x149799bc9602cb5cf201f3425fb8d253b2d4e61fc119dcab3249f307f594754d')
+        .sequenceId({ name: 'Nonce', keyword: 'nonce', value: 15 })
+        .fee({ amount: 0, type: 'tip' })
+        .material(material);
+
+      const tx = await originalBuilder.build();
+      const rawHex = tx.toBroadcastFormat();
+
+      const rebuiltBuilder = factory.getNominateBuilder();
+      rebuiltBuilder.material(material);
+      rebuiltBuilder.from(rawHex);
+
+      should.deepEqual(rebuiltBuilder.getValidators(), [validatorAddress, validatorAddress2]);
+    });
+  });
+
+  describe('factory routing', () => {
+    it('should route raw nominate extrinsic to NominateBuilder', () => {
+      const resolvedBuilder = factory.from(nominateTx.signed);
+      should.ok(resolvedBuilder instanceof NominateBuilder, 'expected NominateBuilder');
+    });
+
+    it('should route batchAll bond+nominate to BatchBuilder', () => {
+      const resolvedBuilder = factory.from(stakingTx.batch.bondAndNominate.signed);
+      should.ok(resolvedBuilder instanceof BatchBuilder, 'expected BatchBuilder');
+    });
+  });
+});