Instructions and Programs

/**
 * Basic instruction interface for program execution
 */
interface IInstruction<TProgramAddress = Address> {
  /** Program that will process this instruction */
  programId: TProgramAddress;
  /** Account metadata for accounts this instruction will access */
  accounts?: IAccountMeta[];
  /** Instruction data as raw bytes */
  data?: Uint8Array;
}

/**
 * Instruction with required accounts
 */
interface IInstructionWithAccounts<TAccounts> extends IInstruction {
  /** Typed account metadata */
  accounts: TAccounts;
}

/**
 * Instruction with required data
 */
interface IInstructionWithData<TData> extends IInstruction {
  /** Typed instruction data */
  data: TData;
}

/**
 * Account metadata for instruction execution
 */
interface IAccountMeta<TAddress = Address> {
  /** Account address */
  address: TAddress;
  /** Account role and permissions */
  role: AccountRole;
}

/**
 * Account metadata for address lookup tables
 */
interface IAccountLookupMeta<TAddress = Address> {
  /** Lookup table address */
  lookupTableAddress: TAddress;
  /** Index within the lookup table */
  addressIndex: number;
  /** Account role and permissions */
  role: AccountRole;
}

/**
 * Account role defining permissions and signing requirements
 */
type AccountRole = 
  | { readonly __kind: "readonly" }
  | { readonly __kind: "writable" }
  | { readonly __kind: "readonlySigner" }
  | { readonly __kind: "writableSigner" };

import { address, IInstruction, IAccountMeta } from "@solana/web3.js";

// Create basic instruction
const instruction: IInstruction = {
  programId: address("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"),
  accounts: [
    {
      address: address("source-token-account"),
      role: { __kind: "writable" }
    },
    {
      address: address("destination-token-account"), 
      role: { __kind: "writable" }
    },
    {
      address: address("owner-address"),
      role: { __kind: "readonlySigner" }
    }
  ],
  data: new Uint8Array([3, 0, 0, 0, 100, 0, 0, 0]) // Transfer 100 tokens
};

/**
 * Check if instruction is for a specific program
 * @param instruction - Instruction to check
 * @param programId - Expected program ID
 * @returns True if instruction targets the program
 */
function isInstructionForProgram<TProgramAddress extends Address>(
  instruction: IInstruction,
  programId: TProgramAddress
): instruction is IInstruction<TProgramAddress>;

/**
 * Assert instruction is for specific program
 * @param instruction - Instruction to check
 * @param programId - Expected program ID
 * @throws SolanaError if instruction is not for the program
 */
function assertIsInstructionForProgram<TProgramAddress extends Address>(
  instruction: IInstruction,
  programId: TProgramAddress
): asserts instruction is IInstruction<TProgramAddress>;

/**
 * Check if instruction has accounts
 * @param instruction - Instruction to check
 * @returns True if instruction has accounts
 */
function isInstructionWithAccounts<TAccounts>(
  instruction: IInstruction
): instruction is IInstructionWithAccounts<TAccounts>;

/**
 * Assert instruction has accounts
 * @param instruction - Instruction to check
 * @throws SolanaError if instruction lacks accounts
 */
function assertIsInstructionWithAccounts<TAccounts>(
  instruction: IInstruction
): asserts instruction is IInstructionWithAccounts<TAccounts>;

/**
 * Check if instruction has data
 * @param instruction - Instruction to check
 * @returns True if instruction has data
 */
function isInstructionWithData<TData>(
  instruction: IInstruction
): instruction is IInstructionWithData<TData>;

/**
 * Assert instruction has data
 * @param instruction - Instruction to check
 * @throws SolanaError if instruction lacks data
 */
function assertIsInstructionWithData<TData>(
  instruction: IInstruction
): asserts instruction is IInstructionWithData<TData>;

/**
 * Create readonly account role
 * @returns Readonly account role
 */
function createReadonlyRole(): AccountRole;

/**
 * Create writable account role
 * @returns Writable account role
 */
function createWritableRole(): AccountRole;

/**
 * Create readonly signer account role
 * @returns Readonly signer account role
 */
function createReadonlySignerRole(): AccountRole;

/**
 * Create writable signer account role
 * @returns Writable signer account role
 */
function createWritableSignerRole(): AccountRole;

/**
 * Check if account role requires signing
 * @param role - Account role to check
 * @returns True if role requires signing
 */
function isSignerRole(role: AccountRole): boolean;

/**
 * Check if account role allows writing
 * @param role - Account role to check
 * @returns True if role allows writing
 */
function isWritableRole(role: AccountRole): boolean;

import {
  createWritableSignerRole,
  createReadonlyRole,
  isSignerRole,
  isWritableRole
} from "@solana/web3.js";

// Create account metadata with specific roles
const signerAccount = {
  address: myAddress,
  role: createWritableSignerRole()
};

const dataAccount = {
  address: dataAddress, 
  role: createReadonlyRole()
};

// Check role properties
console.log("Requires signing:", isSignerRole(signerAccount.role)); // true
console.log("Allows writing:", isWritableRole(dataAccount.role)); // false

/**
 * Create account metadata for program invocation
 * @param config - Account configuration
 * @returns Account metadata array
 */
function createAccountMetas(config: {
  accounts: Array<{
    address: Address;
    writable?: boolean;
    signer?: boolean;
  }>;
}): IAccountMeta[];

/**
 * Get required signers from instruction accounts
 * @param instruction - Instruction to analyze
 * @returns Array of addresses that must sign
 */
function getRequiredSigners(instruction: IInstruction): Address[];

/**
 * Get writable accounts from instruction
 * @param instruction - Instruction to analyze
 * @returns Array of addresses that will be modified
 */
function getWritableAccounts(instruction: IInstruction): Address[];

/**
 * Merge multiple instructions for the same program
 * @param instructions - Instructions to merge
 * @returns Single merged instruction
 */
function mergeInstructions(instructions: IInstruction[]): IInstruction;

/**
 * Program execution error
 */
interface ProgramError {
  /** Program that generated the error */
  programId: Address;
  /** Instruction index that failed */
  instructionIndex: number;
  /** Custom error code from program */
  customErrorCode?: number;
  /** Error message */
  message: string;
}

/**
 * Parse program error from transaction error
 * @param transactionError - Raw transaction error
 * @returns Parsed program error or null
 */
function parseProgramError(transactionError: TransactionError): ProgramError | null;

/**
 * Check if error is from specific program
 * @param error - Error to check
 * @param programId - Program ID to match
 * @returns True if error is from the program
 */
function isProgramError(error: unknown, programId: Address): error is ProgramError;

/**
 * Cross-program invocation instruction
 */
interface CPIInstruction extends IInstruction {
  /** Invoking program ID */
  invokingProgramId: Address;
  /** Target program ID */
  targetProgramId: Address;
  /** Seeds for program-derived address signing */
  seeds?: Uint8Array[][];
}

/**
 * Create cross-program invocation
 * @param config - CPI configuration
 * @returns CPI instruction
 */
function createCPIInstruction(config: {
  invokingProgramId: Address;
  targetProgramId: Address;
  accounts: IAccountMeta[];
  data?: Uint8Array;
  seeds?: Uint8Array[][];
}): CPIInstruction;

/**
 * System program ID constant
 */
const SYSTEM_PROGRAM_ID: Address;

/**
 * Create account instruction
 */
function createCreateAccountInstruction(config: {
  fromPubkey: Address;
  newAccountPubkey: Address;
  lamports: Lamports;
  space: number;
  programId: Address;
}): IInstruction;

/**
 * Transfer lamports instruction
 */
function createTransferInstruction(config: {
  fromPubkey: Address;
  toPubkey: Address;
  lamports: Lamports;
}): IInstruction;

/**
 * Token program ID constant
 */
const TOKEN_PROGRAM_ID: Address;

/**
 * Token transfer instruction
 */
function createTokenTransferInstruction(config: {
  source: Address;
  destination: Address;
  owner: Address;
  amount: bigint;
}): IInstruction;

/**
 * Token mint instruction
 */
function createMintToInstruction(config: {
  mint: Address;
  destination: Address;
  authority: Address;
  amount: bigint;
}): IInstruction;

import {
  createTransferInstruction,
  createTokenTransferInstruction,
  SYSTEM_PROGRAM_ID,
  TOKEN_PROGRAM_ID,
  lamports
} from "@solana/web3.js";

// Create SOL transfer
const solTransfer = createTransferInstruction({
  fromPubkey: myAddress,
  toPubkey: recipientAddress,
  lamports: lamports(1_000_000_000n) // 1 SOL
});

// Create token transfer
const tokenTransfer = createTokenTransferInstruction({
  source: myTokenAccount,
  destination: recipientTokenAccount,
  owner: myAddress,
  amount: 1000000n // 1 token with 6 decimals
});

// Combine in transaction
const transactionMessage = createTransactionMessage({
  version: 0,
  feePayer: myAddress,
  blockhash,
  instructions: [solTransfer, tokenTransfer]
});