solana_kit_instructions

Types and helpers for creating Solana transaction instructions: Instruction, AccountMeta, AccountLookupMeta, and AccountRole.

Installation

Install the package directly:

dependencies:
  "solana_kit_instructions": ^0.9.3

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_instructions
• API reference: https://pub.dev/documentation/solana_kit_instructions/latest/
• Workspace docs: https://openbudgetfun.github.io/solana_kit/
• Package catalog entry: https://openbudgetfun.github.io/solana_kit/reference/package-catalog#solana_kit_instructions
• Source code: https://github.com/openbudgetfun/solana_kit/tree/main/packages/solana_kit_instructions

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.

Model an instruction

Use Instruction plus AccountMeta when you need to describe a program call before building a full transaction message around it.

import 'dart:typed_data';

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

void main() {
  const programAddress = Address('11111111111111111111111111111111');
  const signerAddress = Address('11111111111111111111111111111111');

  final instruction = Instruction(
    programAddress: programAddress,
    accounts: const [
      AccountMeta(
        address: signerAddress,
        role: AccountRole.writableSigner,
      ),
    ],
    data: Uint8List(0),
  );

  print(isInstructionForProgram(instruction, programAddress));
}

Keeping instruction construction explicit makes it easier to reason about required signer privileges, writable accounts, and serialized program data.

Usage

Account roles

AccountRole is a bitflag enum. Each role encodes whether the account signs the transaction and whether it is writable:

Role	isSigner	isWritable	Value
readonly	No	No	0b00
writable	No	Yes	0b01
readonlySigner	Yes	No	0b10
writableSigner	Yes	Yes	0b11

Helper functions modify roles without touching bitflags directly:

import 'package:solana_kit_instructions/solana_kit_instructions.dart';

void main() {
  // Upgrade a readonly account to a signer.
  final signer = upgradeRoleToSigner(AccountRole.readonly);
  print(signer); // AccountRole.readonlySigner

  // Downgrade a writable signer to readonly.
  final downgraded = downgradeRoleToReadonly(AccountRole.writableSigner);
  print(downgraded); // AccountRole.readonlySigner

  // Merge two roles (takes the higher privilege of each).
  final merged = mergeRoles(AccountRole.readonlySigner, AccountRole.writable);
  print(merged); // AccountRole.writableSigner
}

Guard and assertion functions

Several top-level functions test instruction properties. The assertIs* variants throw SolanaError on mismatch instead of returning bool.

import 'dart:typed_data';

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

void main() {
  final ix = Instruction(
    programAddress: const Address('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'),
    accounts: const [
      AccountMeta(address: Address('...'), role: AccountRole.writableSigner),
    ],
    data: Uint8List(0),
  );

  isInstructionForProgram(ix, const Address('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA')); // true
  isInstructionWithAccounts(ix); // true
  isInstructionWithData(ix); // true (empty data counts)
}

Account lookup metadata

AccountLookupMeta extends AccountMeta with addressIndex and lookupTableAddress for v0 transactions that use address lookup tables. It can appear anywhere an AccountMeta is expected.

Example

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

• Import path: package:solana_kit_instructions/solana_kit_instructions.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.