feat(jito): implements staking deactivate

[haritkapadia]

Description

This PR adds support for Jito withdrawal. It also includes a refactor from isMarinade and isJito flags to a stakingTypeParams.type enum.

Issue Number

Ticket: SC-2418
Ticket: SC-2620

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Existing calls to txBuilder.isMarinade will have to be replaced with txBuilder.stakingTypeParams(StakingType.MARINADE)

How Has This Been Tested?

Unit tests. See files changed.

[haritkapadia]

I accidentally closed the old PR when I renamed the branch.
#6643

[haritkapadia]

pass decoded data

Done.

this keeps growing and make it harder to read. Either name it like jitoStakingPool or create a sub interface. I prefer later

Created sub interface.

better naming findStakePoolWithdrawAuthoritySync and some JSDoc explaining what it is

Added JSDoc. I kept the name the same because it's a sync version of findStakePoolWithdrawAuthority in @solana/spl-stake-pool. I also explained the naming in the JSDoc.

[haritkapadia]

The transaction needs 3 signatures (see https://github.com/jito-foundation/jito-stake-unstake-reference/blob/master/hooks/useManualUnstake.ts or https://github.com/solana-program/stake-pool/blob/main/clients/js-legacy/src/index.ts).

I'm thinking of generating unstakingAddress and transferAuthorityAddress in wallet-platform.

[haritkapadia]

This information needs to come from on chain. I'm thinking of parsing getAccountInfo RPC call in staking-service.

[haritkapadia]

The validator needs to be selected from data on chain. I'm thinking of parsing getAccountInfo RPC call in staking-service and implementing https://github.com/solana-program/stake-pool/blob/main/clients/js-legacy/src/utils/stake.ts.

[haritkapadia]

This was refactored so that I could add the Approve instruction easily.

[evanzbitgo]

Moving stakingType out as an enum is cleaner, e.g.

  enum StakingType {
    NATIVE = 'NATIVE',
    MARINADE = 'MARINADE',
    JITO = 'JITO'
  }

export interface StakingDeactivate {
  type: InstructionBuilderTypes.StakingDeactivate;
  params: {
    fromAddress: string;
    stakingAddress: string;
    amount?: string;
    stakingType: StakingType;
    extraParams?: JitoStakePoolData | MarinadeParams | NativeParams;

Similarly for Activate

[haritkapadia]

Done

[evanzbitgo]

could we just expand required field here?

poolMint: string
validatorList: string
managerFeeAccount: string

[evanzbitgo]

Also do we need to pass validatorList here? Isn't the caller(staking service) already selecting the validator (validatorAddress below)?

[haritkapadia]

validatorList is the address of the account that stores the validator list data. It's derived from parsing the stake pool account data. We need the public key as part of the withdraw stake instruction.

Edit: and yes, validatorAddress is selected by the caller.

[haritkapadia]

could we just expand required field here?

We could, but I think that would make it less clear that those fields come from parsing the stake pool account data.

With the current setup, you can do something like this:

const account = await connection.getAccountInfo("J1to.....")
const stakePoolData = StakePoolLayout.decode(account.data)
const txBuilder = new StakingDeactivateBulder()
txBuilder.extraParams({
  stakePoolData, // notice we can pass the entire parsed object instead of having to select fields
  validatorAddress: await getValidatorFrom(connection, stakePoolData.validatorList)
})

[evanzbitgo]

could we just expand required field here?

If SOL has schema changes of those unused fields, the fields defined here might not be consistent and others might find it confusing in the future. But I am also okay with keeping them. Your call

[evanzbitgo]

validatorList is the address of the account that stores the validator list data

If validatorList is an account address, the name looks confusing. Could we have a more accurate name?

[haritkapadia]

I can change the validatorList name

[haritkapadia]

If SOL has schema changes of those unused fields, the fields defined here might not be consistent and others might find it confusing in the future. But I am also okay with keeping them. Your call

If this happens then we'll have to update the instruction encoder/decoder in jitoStakePoolOperations.ts, i.e. the file that exports WithdrawStakeStakePoolData. I think it won't be confusing because it's linked together by the compiler, so I will keep it.

[haritkapadia]

Changed validatorList name

[evanzbitgo]

to be cleaner, you can find out the stakingType upfront and use switch later

[haritkapadia]

Done.

[evanzbitgo]

Not your problem, but this file is 1100+ line and is a nightmare to maintain. Create a followup ticket and refactor when you have more bandwidth

 🚨 Critical Problems:

  1. Massive monolithic functions - parseSendInstructions() is 180+ lines
  2. Repeated code patterns - Nonce parsing duplicated 8+ times
  3. Deep nested switches - Multiple levels of switch statements
  4. Mixed responsibilities - Parsing, validation, and construction all mixed
  5. Hard to maintain - Adding new instruction types requires touching multiple places
  6. No abstraction - Each instruction type reimplements similar logic

⏺ 🎯 Specific Refactoring Opportunities:

  1. Extract instruction parsers - Each case in switches should be a separate class
  2. Common nonce handling - Extract to shared utility
  3. Validation separation - Move validation to dedicated validators
  4. Factory pattern - Use registry of instruction parsers
  5. Eliminate duplicated token logic - Extract token name resolution

⏺ 💡 Proposed Refactoring Strategy:

  Step 1: Create Instruction Parser Interface
  interface InstructionParser<T extends InstructionParams> {
    canParse(instruction: TransactionInstruction): boolean;
    parse(instruction: TransactionInstruction, context?: ParsingContext): T;
  }

  Step 2: Extract Individual Parsers
  // instructionParsers/NonceParser.ts
  class NonceParser implements InstructionParser<Nonce> {
    canParse(instruction: TransactionInstruction): boolean {
      return getInstructionType(instruction) === ValidInstructionTypesEnum.AdvanceNonceAccount;
    }

    parse(instruction: TransactionInstruction): Nonce {
      const decoded = SystemInstruction.decodeNonceAdvance(instruction);
      return {
        type: InstructionBuilderTypes.NonceAdvance,
        params: {
          walletNonceAddress: decoded.noncePubkey.toString(),
          authWalletAddress: decoded.authorizedPubkey.toString(),
        },
      };
    }
  }

  Step 3: Registry Pattern
  class InstructionParserRegistry {
    private parsers: InstructionParser<any>[] = [
      new NonceParser(),
      new TransferParser(),
      new TokenTransferParser(),
      // ... etc
    ];

    parse(instruction: TransactionInstruction, context?: ParsingContext): InstructionParams {
      const parser = this.parsers.find(p => p.canParse(instruction));
      if (!parser) throw new NotSupported(`Unsupported instruction: ${getInstructionType(instruction)}`);
      return parser.parse(instruction, context);
    }
  }

  Step 4: Transaction Type Handlers
  // transactionHandlers/SendTransactionHandler.ts  
  class SendTransactionHandler {
    constructor(private registry: InstructionParserRegistry) {}

    handle(instructions: TransactionInstruction[], context: ParsingContext): InstructionParams[] {
      return instructions.map(instruction => this.registry.parse(instruction, context));
    }
  }

  Step 5: Simplified Factory
  export function instructionParamsFactory(
    type: TransactionType,
    instructions: TransactionInstruction[],
    coinName?: string,
    instructionMetadata?: InstructionParams[],
    _useTokenAddressTokenName?: boolean
  ): InstructionParams[] {
    const context = { coinName, instructionMetadata, _useTokenAddressTokenName };
    const handler = TransactionHandlerRegistry.getHandler(type);
    return handler.handle(instructions, context);
  }

  Benefits:
  - Single Responsibility - Each parser handles one instruction type
  - Easy to Test - Small, focused classes
  - Extensible - Add new parsers without touching existing code
  - Maintainable - Clear separation of concerns
  - Reusable - Common parsers shared across transaction types

  This would reduce the file from 1100+ lines to ~50 lines of registry code plus small focused parser classes.

[haritkapadia]

Done: https://bitgoinc.atlassian.net/browse/SC-2686

[evanzbitgo]

Please address the new comments for cleaner code

[evanzbitgo]

These mixes of type infers and validation are fragile and hard to debug. Try to decouple it into a separate function, e.g.

function determineStakingType(instructions: StakingInstructions): StakingType {
    if (instructions.depositSol) return StakingType.JITO;
    if (!instructions.delegate && instructions.create && instructions.initialize) return StakingType.MARINADE;
    if (instructions.delegate && instructions.create) return StakingType.NATIVE;
    throw new Error('Unknown staking type');
  }

  // Then use switch statements instead of complex boolean logic
  const stakingType = determineStakingType(stakingInstructions);
  switch (stakingType) {
    case StakingType.JITO: // handle JITO
    case StakingType.MARINADE: // handle MARINADE  
    case StakingType.NATIVE: // handle NATIVE
  }

[haritkapadia]

Done.

One of the reasons I was using the if statements was to determine which fields were not null. So my new solution uses type guards (e.g. isJitoStakingInstructions) as a replacement.

[haritkapadia]

Also StakingInstructions.authorize?: AuthorizeStakeParams[]; wasn't being used anywhere, so I removed that field.

[evanzbitgo]

throw error. Look at https://softwareengineering.stackexchange.com/questions/15515/when-to-use-assertions-and-when-to-use-exceptions

[haritkapadia]

Looks like I can remove it entirely because stakingType cannot be null.

[haritkapadia]

I removed the check on this line.

I added a compile time check on the default case of the switch statements:

    default: {
      const unreachable: never = stakingType;
      throw new Error(`Unknown staking type ${unreachable}`);
    }