solana_kit_programs 0.10.0

Program utilities for the Solana Kit Dart SDK.

solana_kit_programs

Check whether a transaction error came from a specific Solana program, with optional error code matching.

Installation

Install the package directly:

dependencies:
  "solana_kit_programs": ^0.10.0

If your app uses several Solana Kit packages together, you can also depend on the umbrella package instead:

dart pub add solana_kit

Inside this monorepo, Dart workspace resolution uses the local package automatically.

Documentation

• Package page: https://pub.dev/packages/solana_kit_programs
• API reference: https://pub.dev/documentation/solana_kit_programs/latest/
• Workspace docs: https://openbudgetfun.github.io/solana_kit/
• Package catalog entry: https://openbudgetfun.github.io/solana_kit/reference/package-catalog#solana_kit_programs
• Source code: https://github.com/openbudgetfun/solana_kit/tree/main/packages/solana_kit_programs

For architecture notes, getting-started guides, and cross-package examples, start with the workspace docs site and then drill down into the package README and API reference.

Usage

Identifying program errors

isProgramError determines whether an error is a custom program error from a specific program address. Since the Solana RPC only reports the index of the failed instruction, you must provide the transaction message so the function can look up which program was invoked.

import 'package:solana_kit_addresses/solana_kit_addresses.dart';
import 'package:solana_kit_errors/solana_kit_errors.dart';
import 'package:solana_kit_programs/solana_kit_programs.dart';

void main() {
  const myProgramAddress = Address(
    'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
  );

  // Build a transaction message input with instruction mappings.
  final transactionMessage = TransactionMessageInput(
    instructions: {
      0: InstructionInput(programAddress: myProgramAddress),
      1: InstructionInput(
        programAddress: const Address('11111111111111111111111111111111'),
      ),
    },
  );

  // Simulate an instruction error from the RPC.
  final error = SolanaError(
    SolanaErrorCode.instructionErrorCustom,
    {'index': 0, 'code': 42},
  );

  // Check if this is any custom error from our program.
  print(isProgramError(error, transactionMessage, myProgramAddress));
  // true

  // Check if this is a specific custom error code from our program.
  print(isProgramError(error, transactionMessage, myProgramAddress, 42));
  // true

  // Wrong error code.
  print(isProgramError(error, transactionMessage, myProgramAddress, 99));
  // false

  // Wrong program.
  const otherProgram = Address('11111111111111111111111111111111');
  print(isProgramError(error, transactionMessage, otherProgram));
  // false
}

Catching program errors in transactions

A typical pattern is to catch errors after sending a transaction and determine which program raised the error.

import 'package:solana_kit_addresses/solana_kit_addresses.dart';
import 'package:solana_kit_programs/solana_kit_programs.dart';

void main() async {
  const myProgramAddress = Address(
    'MyProgram11111111111111111111111111111111111',
  );

  final transactionMessage = TransactionMessageInput(
    instructions: {
      0: InstructionInput(programAddress: myProgramAddress),
    },
  );

  try {
    // Send and confirm your transaction...
    // await sendAndConfirmTransaction(signedTransaction);
  } catch (error) {
    if (isProgramError(error, transactionMessage, myProgramAddress, 6000)) {
      print('Insufficient funds error from my program');
    } else if (isProgramError(error, transactionMessage, myProgramAddress)) {
      print('Some other custom error from my program');
    } else {
      rethrow;
    }
  }
}

Non-SolanaError values

The function safely returns false for non-SolanaError values or errors that are not custom program errors.

import 'package:solana_kit_addresses/solana_kit_addresses.dart';
import 'package:solana_kit_errors/solana_kit_errors.dart';
import 'package:solana_kit_programs/solana_kit_programs.dart';

void main() {
  const programAddress = Address('11111111111111111111111111111111');
  final transactionMessage = TransactionMessageInput(
    instructions: {
      0: InstructionInput(programAddress: programAddress),
    },
  );

  // Not a SolanaError at all.
  print(isProgramError('not an error', transactionMessage, programAddress));
  // false

  // A SolanaError but not a custom instruction error.
  final nonInstructionError = SolanaError(SolanaErrorCode.blockHeightExceeded);
  print(isProgramError(
    nonInstructionError,
    transactionMessage,
    programAddress,
  ));
  // false

  // Null values.
  print(isProgramError(null, transactionMessage, programAddress));
  // false
}

Example

Use example/main.dart as a runnable starting point for solana_kit_programs.

• Import path: package:solana_kit_programs/solana_kit_programs.dart
• This section is centrally maintained with mdt to keep package guidance aligned.
• After updating shared docs templates, run docs:update from the repo root.

Maintenance

• Validate docs in CI and locally with docs:check.
• Keep examples focused on one workflow and reference package README sections for deeper API details.