feat(abstract-eth): add ZAMA staking delegate flow (approve + deposit)

Implement SDK builder and ABI encoding utilities for the ZAMA ERC-4626
staking delegate flow:

- zamaStakingUtils.ts: ABI encoding for ERC20 approve(address,uint256)
  and ERC4626 deposit(uint256,address) with correct selectors
  (0x095ea7b3, 0x6e553f65)
- zamaStakingBuilder.ts: ZamaStakingBuilder class with buildApprove()
  and buildDeposit() methods producing {to, data, value} tx requests
- Add CoinFeature.STAKING to ERC7984_TOKEN_FEATURES
- Comprehensive unit tests (38 new tests) with ABI round-trip decoding

TICKET: SI-560

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Vijay-Jagannathan

modules/abstract-eth/src/lib/index.ts

@@ -1,6 +1,8 @@
 export * from './constants';
 export * from './zamaUtils';
+export * from './zamaStakingUtils';
 export * from './decryptionDelegationBuilder';
+export * from './zamaStakingBuilder';
 export * from './contractCall';
 export * from './iface';
 export * from './keyPair';

modules/abstract-eth/src/lib/transactionBuilder.ts

@@ -20,6 +20,7 @@ import {
 } from '@bitgo/sdk-core';
 
 import { KeyPair } from './keyPair';
+import { ZamaStakingBuilder, ZamaStakingOperationType } from './zamaStakingBuilder';
 import { ETHTransactionType, Fee, SignatureParts, TxData } from './iface';
 import {
   calculateForwarderAddress,
@@ -89,6 +90,9 @@ export abstract class TransactionBuilder extends BaseTransactionBuilder {
   // encoded contract call hex
   private _data: string;
 
+  // ZAMA staking builder (approve + deposit flow)
+  private _zamaStakingBuilder?: ZamaStakingBuilder;
+
   // Common parameter for wallet initialization and address initialization transaction
   private _salt: string;
 
@@ -158,6 +162,9 @@ export abstract class TransactionBuilder extends BaseTransactionBuilder {
         return this.buildBase('0x');
       case TransactionType.ContractCall:
       case TransactionType.DecryptionDelegation:
+        if (this._zamaStakingBuilder) {
+          return this.buildZamaStakingTransaction();
+        }
         return this.buildGenericContractCallTransaction();
       default:
         throw new BuildTransactionError('Unsupported transaction type');
@@ -447,6 +454,9 @@ export abstract class TransactionBuilder extends BaseTransactionBuilder {
         break;
       case TransactionType.ContractCall:
       case TransactionType.DecryptionDelegation:
+        if (this._zamaStakingBuilder) {
+          break; // validated by _zamaStakingBuilder.build()
+        }
         this.validateContractAddress();
         this.validateDataField();
         break;
@@ -529,6 +539,7 @@ export abstract class TransactionBuilder extends BaseTransactionBuilder {
    */
   type(type: TransactionType): void {
     this._type = type;
+    this._zamaStakingBuilder = undefined;
   }
 
   /**
@@ -882,6 +893,49 @@ export abstract class TransactionBuilder extends BaseTransactionBuilder {
   }
   // endregion
 
+  // region ZAMA staking (approve + deposit)
+
+  /**
+   * Get the staking approve builder for an ERC20 approve transaction.
+   * Returns the ZamaStakingBuilder for fluent chaining.
+   *
+   * @returns {ZamaStakingBuilder} the staking builder configured for APPROVE
+   */
+  stakingApprove(): ZamaStakingBuilder {
+    if (this._type !== TransactionType.ContractCall) {
+      throw new BuildTransactionError('Staking approve can only be set for ContractCall transactions');
+    }
+    if (!this._zamaStakingBuilder) {
+      this._zamaStakingBuilder = new ZamaStakingBuilder().type(ZamaStakingOperationType.APPROVE);
+    }
+    return this._zamaStakingBuilder;
+  }
+
+  /**
+   * Get the staking deposit builder for an ERC4626 deposit transaction.
+   * Returns the ZamaStakingBuilder for fluent chaining.
+   *
+   * @returns {ZamaStakingBuilder} the staking builder configured for DEPOSIT
+   */
+  stakingDeposit(): ZamaStakingBuilder {
+    if (this._type !== TransactionType.ContractCall) {
+      throw new BuildTransactionError('Staking deposit can only be set for ContractCall transactions');
+    }
+    if (!this._zamaStakingBuilder) {
+      this._zamaStakingBuilder = new ZamaStakingBuilder().type(ZamaStakingOperationType.DEPOSIT);
+    }
+    return this._zamaStakingBuilder;
+  }
+
+  private buildZamaStakingTransaction(): TxData {
+    const stakingResult = this._zamaStakingBuilder!.build();
+    const txData = this.buildBase(stakingResult.data);
+    txData.to = stakingResult.address;
+    return txData;
+  }
+
+  // endregion
+
   /** @inheritdoc */
   protected get transaction(): Transaction {
     return this._transaction;

modules/abstract-eth/src/lib/zamaStakingBuilder.ts

@@ -0,0 +1,206 @@
+import { BuildTransactionError } from '@bitgo/sdk-core';
+import { isValidEthAddress } from './utils';
+import { buildApproveCalldata, buildDepositCalldata, approveMethodId, depositMethodId } from './zamaStakingUtils';
+
+/**
+ * Distinguishes between the two staking operations in the delegate flow.
+ */
+export enum ZamaStakingOperationType {
+  /** ERC20 approve — grant OperatorStaking spending allowance. */
+  APPROVE = 'approve',
+  /** ERC4626 deposit — deposit ZAMA tokens into the OperatorStaking vault. */
+  DEPOSIT = 'deposit',
+}
+
+/**
+ * The output of ZamaStakingBuilder.build().
+ *
+ * Contains everything the TransactionBuilder needs to construct a signed Ethereum
+ * transaction: the target contract address, ABI-encoded calldata, and ETH value.
+ */
+export interface ZamaStakingBuildResult {
+  /** Target contract address (token for approve, operator for deposit). */
+  address: string;
+  /** ABI-encoded calldata (approve or deposit). */
+  data: string;
+  /** Always '0' — staking transactions carry no ETH value. */
+  value: string;
+}
+
+/**
+ * Fluent builder for ZAMA ERC-4626 staking delegate flow transactions.
+ *
+ * Used as a helper owned by the abstract-eth TransactionBuilder. The TransactionBuilder
+ * exposes `stakingApprove()` and `stakingDeposit()` methods that create and return this
+ * builder for fluent configuration.
+ *
+ * The delegate flow consists of two transactions:
+ *
+ * 1. **Approve (TX1):** ERC20 `approve(address,uint256)` on the ZAMA token contract,
+ *    granting the OperatorStaking contract permission to transfer tokens.
+ *
+ * 2. **Deposit (TX2):** ERC4626 `deposit(uint256,address)` on the OperatorStaking
+ *    contract, depositing ZAMA tokens and receiving stZAMA shares.
+ *
+ * Usage via TransactionBuilder:
+ *   txBuilder.type(TransactionType.ContractCall);
+ *   txBuilder.stakingApprove()
+ *     .tokenContractAddress('0xZamaToken...')
+ *     .spenderAddress('0xOperatorStaking...')
+ *     .amount('1000000000000000000');
+ *   const tx = await txBuilder.build();
+ */
+export class ZamaStakingBuilder {
+  private _type?: ZamaStakingOperationType;
+  private _amount?: string;
+  private _tokenContractAddress?: string;
+  private _spenderAddress?: string;
+  private _operatorAddress?: string;
+  private _receiverAddress?: string;
+
+  /**
+   * Set the staking operation type.
+   *
+   * @param type APPROVE or DEPOSIT
+   */
+  type(type: ZamaStakingOperationType): this {
+    this._type = type;
+    return this;
+  }
+
+  /**
+   * Set the amount of ZAMA tokens (18 decimals, as a decimal string).
+   *
+   * @param value Token amount
+   */
+  amount(value: string): this {
+    if (!value || value === '0') {
+      throw new BuildTransactionError('Invalid amount for staking transaction');
+    }
+    this._amount = value;
+    return this;
+  }
+
+  /**
+   * Set the ZAMA ERC-20 token contract address (used for APPROVE).
+   *
+   * @param address Token contract address
+   */
+  tokenContractAddress(address: string): this {
+    if (!isValidEthAddress(address)) {
+      throw new BuildTransactionError('Invalid token contract address: ' + address);
+    }
+    this._tokenContractAddress = address;
+    return this;
+  }
+
+  /**
+   * Set the OperatorStaking contract address — the approved spender (used for APPROVE).
+   *
+   * @param address Spender address
+   */
+  spenderAddress(address: string): this {
+    if (!isValidEthAddress(address)) {
+      throw new BuildTransactionError('Invalid spender address: ' + address);
+    }
+    this._spenderAddress = address;
+    return this;
+  }
+
+  /**
+   * Set the OperatorStaking contract address to deposit into (used for DEPOSIT).
+   *
+   * @param address Operator contract address
+   */
+  operatorAddress(address: string): this {
+    if (!isValidEthAddress(address)) {
+      throw new BuildTransactionError('Invalid operator address: ' + address);
+    }
+    this._operatorAddress = address;
+    return this;
+  }
+
+  /**
+   * Set the address that will receive the minted stZAMA shares (used for DEPOSIT).
+   *
+   * @param address Receiver address
+   */
+  receiverAddress(address: string): this {
+    if (!isValidEthAddress(address)) {
+      throw new BuildTransactionError('Invalid receiver address: ' + address);
+    }
+    this._receiverAddress = address;
+    return this;
+  }
+
+  /**
+   * Build the staking transaction.
+   *
+   * Validates required fields and produces a ZamaStakingBuildResult with the target
+   * contract address and ABI-encoded calldata.
+   *
+   * @returns ZamaStakingBuildResult containing {address, data, value}
+   * @throws BuildTransactionError if required fields are missing
+   */
+  build(): ZamaStakingBuildResult {
+    if (this._type === undefined) {
+      throw new BuildTransactionError('Missing staking operation type');
+    }
+    if (this._amount === undefined) {
+      throw new BuildTransactionError('Missing amount for staking transaction');
+    }
+
+    switch (this._type) {
+      case ZamaStakingOperationType.APPROVE:
+        return this.buildApprove();
+      case ZamaStakingOperationType.DEPOSIT:
+        return this.buildDeposit();
+      default:
+        throw new BuildTransactionError('Invalid staking operation type: ' + this._type);
+    }
+  }
+
+  private buildApprove(): ZamaStakingBuildResult {
+    if (!this._tokenContractAddress) {
+      throw new BuildTransactionError('Missing token contract address for approve');
+    }
+    if (!this._spenderAddress) {
+      throw new BuildTransactionError('Missing spender address for approve');
+    }
+
+    return {
+      address: this._tokenContractAddress,
+      data: buildApproveCalldata(this._spenderAddress, this._amount!),
+      value: '0',
+    };
+  }
+
+  private buildDeposit(): ZamaStakingBuildResult {
+    if (!this._operatorAddress) {
+      throw new BuildTransactionError('Missing operator address for deposit');
+    }
+    if (!this._receiverAddress) {
+      throw new BuildTransactionError('Missing receiver address for deposit');
+    }
+
+    return {
+      address: this._operatorAddress,
+      data: buildDepositCalldata(this._amount!, this._receiverAddress),
+      value: '0',
+    };
+  }
+
+  /**
+   * Classify staking operation type from serialized calldata.
+   *
+   * @param data ABI-encoded calldata hex string
+   * @returns true if the data matches a known staking selector
+   */
+  static isStakingData(data: string): boolean {
+    if (!data || data.length < 10) {
+      return false;
+    }
+    const selector = data.slice(0, 10).toLowerCase();
+    return selector === approveMethodId.toLowerCase() || selector === depositMethodId.toLowerCase();
+  }
+}

modules/abstract-eth/src/lib/zamaStakingUtils.ts

@@ -0,0 +1,62 @@
+import { addHexPrefix } from 'ethereumjs-util';
+import EthereumAbi from 'ethereumjs-abi';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+// ABI parameter type arrays
+export const approveTypes = ['address', 'uint256'] as const;
+export const depositTypes = ['uint256', 'address'] as const;
+
+/**
+ * Function selector for ERC20.approve(address,uint256)
+ * = keccak256('approve(address,uint256)')[0:4] = 0x095ea7b3
+ */
+export const approveMethodId = addHexPrefix(EthereumAbi.methodID('approve', [...approveTypes]).toString('hex'));
+
+/**
+ * Function selector for ERC4626.deposit(uint256,address)
+ * = keccak256('deposit(uint256,address)')[0:4] = 0x6e553f65
+ */
+export const depositMethodId = addHexPrefix(EthereumAbi.methodID('deposit', [...depositTypes]).toString('hex'));
+
+// ---------------------------------------------------------------------------
+// Encoding functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Encodes an ERC20 approve(address,uint256) call.
+ *
+ * Grants `spenderAddress` permission to transfer up to `amount` ZAMA tokens
+ * on behalf of the caller (msg.sender). Used as TX1 of the delegate flow
+ * to authorize the OperatorStaking contract before depositing.
+ *
+ * @param spenderAddress  OperatorStaking contract address (the approved spender)
+ * @param amount          Amount of ZAMA tokens to approve (18 decimals, as a decimal string)
+ * @returns ABI-encoded calldata hex string (0x-prefixed)
+ */
+export function buildApproveCalldata(spenderAddress: string, amount: string): string {
+  const method = EthereumAbi.methodID('approve', [...approveTypes]);
+  const args = EthereumAbi.rawEncode([...approveTypes], [spenderAddress, amount]);
+  return addHexPrefix(Buffer.concat([method, args]).toString('hex'));
+}
+
+/**
+ * Encodes an ERC4626 deposit(uint256,address) call.
+ *
+ * Deposits `amount` ZAMA tokens (18 decimals) into the OperatorStaking vault
+ * and mints stZAMA shares (20 decimals) to `receiverAddress`.
+ *
+ * Requires a prior ERC20 approve() call granting the OperatorStaking contract
+ * at least `amount` allowance.
+ *
+ * @param amount           Amount of ZAMA tokens to deposit (18 decimals, as a decimal string)
+ * @param receiverAddress  Address that will receive the minted stZAMA shares
+ * @returns ABI-encoded calldata hex string (0x-prefixed)
+ */
+export function buildDepositCalldata(amount: string, receiverAddress: string): string {
+  const method = EthereumAbi.methodID('deposit', [...depositTypes]);
+  const args = EthereumAbi.rawEncode([...depositTypes], [amount, receiverAddress]);
+  return addHexPrefix(Buffer.concat([method, args]).toString('hex'));
+}

modules/abstract-eth/test/unit/index.ts

@@ -4,4 +4,6 @@ export * from './transaction';
 export * from './coin';
 export * from './messages';
 export * from './zamaUtils';
+export * from './zamaStakingUtils';
+export * from './zamaStakingBuilder';
 export * from './decryptionDelegationBuilder';

modules/abstract-eth/test/unit/transactionBuilder/index.ts

@@ -3,3 +3,4 @@ export * from './send';
 export * from './walletInitialization';
 export * from './flushNft';
 export * from './decryptionDelegation';
+export * from './zamaStaking';