@solana/instructions 6.3.1 → 6.3.2-canary-20260313112147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/instructions",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Helpers for creating transaction instructions",
   "homepage": "https://www.solanakit.com/api#solanainstructions",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,8 +56,8 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/codecs-core": "6.3.1",
-    "@solana/errors": "6.3.1"
+    "@solana/codecs-core": "6.3.2-canary-20260313112147",
+    "@solana/errors": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/accounts.ts

@@ -0,0 +1,92 @@
+import { Address } from '@solana/addresses';
+
+import { AccountRole } from './roles';
+
+/**
+ * Represents an account's address and metadata about its mutability and whether it must be a signer
+ * of the transaction.
+ *
+ * Typically, you will use one of its subtypes.
+ *
+ * |                                   | `role`                        | `isSigner` | `isWritable` |
+ * | --------------------------------- | ----------------------------- | ---------- | ------------ |
+ * | `ReadonlyAccount<TAddress>`       | `AccountRole.READONLY`        |  No        |  No          |
+ * | `WritableAccount<TAddress>`       | `AccountRole.WRITABLE`        |  No        |  Yes         |
+ * | `ReadonlySignerAccount<TAddress>` | `AccountRole.READONLY_SIGNER` |  Yes       |  No          |
+ * | `WritableSignerAccount<TAddress>` | `AccountRole.WRITABLE_SIGNER` |  Yes       |  Yes         |
+ *
+ * @example A type for the Rent sysvar account
+ * ```ts
+ * type RentSysvar = ReadonlyAccount<'SysvarRent111111111111111111111111111111111'>;
+ * ```
+ */
+export interface AccountMeta<TAddress extends string = string> {
+    readonly address: Address<TAddress>;
+    readonly role: AccountRole;
+}
+
+/**
+ * @see {@link AccountMeta}
+ */
+export type ReadonlyAccount<TAddress extends string = string> = AccountMeta<TAddress> & {
+    readonly role: AccountRole.READONLY;
+};
+/**
+ * @see {@link AccountMeta}
+ */
+export type WritableAccount<TAddress extends string = string> = AccountMeta<TAddress> & { role: AccountRole.WRITABLE };
+/**
+ * @see {@link AccountMeta}
+ */
+export type ReadonlySignerAccount<TAddress extends string = string> = AccountMeta<TAddress> & {
+    role: AccountRole.READONLY_SIGNER;
+};
+/**
+ * @see {@link AccountMeta}
+ */
+export type WritableSignerAccount<TAddress extends string = string> = AccountMeta<TAddress> & {
+    role: AccountRole.WRITABLE_SIGNER;
+};
+
+/**
+ * Represents a lookup of the account's address in an address lookup table. It specifies which
+ * lookup table account in which to perform the lookup, the index of the desired account address in
+ * that table, and metadata about its mutability. Notably, account addresses obtained via lookups
+ * may not act as signers.
+ *
+ * Typically, you will use one of its subtypes.
+ *
+ * |                                                        | `role`                 | `isSigner` | `isWritable` |
+ * | ------------------------------------------------------ | ---------------------- | ---------- | ------------ |
+ * | `ReadonlyLookupAccount<TAddress, TLookupTableAddress>` | `AccountRole.READONLY` |  No        |  No          |
+ * | `WritableLookupAccount<TAddress, TLookupTableAddress>` | `AccountRole.WRITABLE` |  No        |  Yes         |
+ *
+ * @example A type for the Rent sysvar account that you looked up in a lookup table
+ * ```ts
+ * type RentSysvar = ReadonlyLookupAccount<
+ *     'SysvarRent111111111111111111111111111111111',
+ *     'MyLookupTable111111111111111111111111111111'
+ * >;
+ * ```
+ */
+export interface AccountLookupMeta<TAddress extends string = string, TLookupTableAddress extends string = string> {
+    readonly address: Address<TAddress>;
+    readonly addressIndex: number;
+    readonly lookupTableAddress: Address<TLookupTableAddress>;
+    readonly role: AccountRole.READONLY | AccountRole.WRITABLE;
+}
+
+/**
+ * @see {@link AccountLookupMeta}
+ */
+export type ReadonlyAccountLookup<
+    TAddress extends string = string,
+    TLookupTableAddress extends string = string,
+> = AccountLookupMeta<TAddress, TLookupTableAddress> & { readonly role: AccountRole.READONLY };
+/**
+ * @see {@link AccountLookupMeta}
+ */
+export type WritableAccountLookup<
+    TAddress extends string = string,
+    TLookupTableAddress extends string = string,
+> = AccountLookupMeta<TAddress, TLookupTableAddress> & { readonly role: AccountRole.WRITABLE };

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * This package contains types for creating transaction instructions. It can be used standalone, but it is also exported as part of Kit [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
+ * @packageDocumentation
+ */
+export * from './accounts';
+export * from './instruction';
+export * from './roles';

package/src/instruction.ts

@@ -0,0 +1,129 @@
+import { Address } from '@solana/addresses';
+import { ReadonlyUint8Array } from '@solana/codecs-core';
+import {
+    SOLANA_ERROR__INSTRUCTION__EXPECTED_TO_HAVE_ACCOUNTS,
+    SOLANA_ERROR__INSTRUCTION__EXPECTED_TO_HAVE_DATA,
+    SOLANA_ERROR__INSTRUCTION__PROGRAM_ID_MISMATCH,
+    SolanaError,
+} from '@solana/errors';
+
+import { AccountLookupMeta, AccountMeta } from './accounts';
+
+/**
+ * An instruction destined for a given program.
+ *
+ * @example
+ * ```ts
+ * type StakeProgramInstruction = Instruction<'StakeConfig11111111111111111111111111111111'>;
+ * ```
+ */
+export interface Instruction<
+    TProgramAddress extends string = string,
+    TAccounts extends readonly (AccountLookupMeta | AccountMeta)[] = readonly (AccountLookupMeta | AccountMeta)[],
+> {
+    readonly accounts?: TAccounts;
+    readonly data?: ReadonlyUint8Array;
+    readonly programAddress: Address<TProgramAddress>;
+}
+
+/**
+ * An instruction that loads certain accounts.
+ *
+ * @example
+ * ```ts
+ * type InstructionWithTwoAccounts = InstructionWithAccounts<
+ *     [
+ *         WritableAccount, // First account
+ *         RentSysvar, // Second account
+ *     ]
+ * >;
+ * ```
+ */
+export interface InstructionWithAccounts<
+    TAccounts extends readonly (AccountLookupMeta | AccountMeta)[],
+> extends Instruction {
+    readonly accounts: TAccounts;
+}
+
+export function isInstructionForProgram<TProgramAddress extends string, TInstruction extends Instruction>(
+    instruction: TInstruction,
+    programAddress: Address<TProgramAddress>,
+): instruction is TInstruction & { programAddress: Address<TProgramAddress> } {
+    return instruction.programAddress === programAddress;
+}
+
+export function assertIsInstructionForProgram<TProgramAddress extends string, TInstruction extends Instruction>(
+    instruction: TInstruction,
+    programAddress: Address<TProgramAddress>,
+): asserts instruction is TInstruction & { programAddress: Address<TProgramAddress> } {
+    if (instruction.programAddress !== programAddress) {
+        throw new SolanaError(SOLANA_ERROR__INSTRUCTION__PROGRAM_ID_MISMATCH, {
+            actualProgramAddress: instruction.programAddress,
+            expectedProgramAddress: programAddress,
+        });
+    }
+}
+
+export function isInstructionWithAccounts<
+    TAccounts extends readonly (AccountLookupMeta | AccountMeta)[] = readonly (AccountLookupMeta | AccountMeta)[],
+    TInstruction extends Instruction = Instruction,
+>(instruction: TInstruction): instruction is InstructionWithAccounts<TAccounts> & TInstruction {
+    return instruction.accounts !== undefined;
+}
+
+export function assertIsInstructionWithAccounts<
+    TAccounts extends readonly (AccountLookupMeta | AccountMeta)[] = readonly (AccountLookupMeta | AccountMeta)[],
+    TInstruction extends Instruction = Instruction,
+>(instruction: TInstruction): asserts instruction is InstructionWithAccounts<TAccounts> & TInstruction {
+    if (instruction.accounts === undefined) {
+        throw new SolanaError(SOLANA_ERROR__INSTRUCTION__EXPECTED_TO_HAVE_ACCOUNTS, {
+            data: instruction.data,
+            programAddress: instruction.programAddress,
+        });
+    }
+}
+
+/**
+ * An instruction whose data conforms to a certain type.
+ *
+ * This is most useful when you have a branded `Uint8Array` that represents a particular
+ * instruction's data.
+ *
+ * @example A type for the \`AdvanceNonce\` instruction of the System program
+ * ```ts
+ * type AdvanceNonceAccountInstruction<
+ *     TNonceAccountAddress extends string = string,
+ *     TNonceAuthorityAddress extends string = string,
+ * > = Instruction<'11111111111111111111111111111111'> &
+ *     InstructionWithAccounts<
+ *         [
+ *             WritableAccount<TNonceAccountAddress>,
+ *             ReadonlyAccount<'SysvarRecentB1ockHashes11111111111111111111'>,
+ *             ReadonlySignerAccount<TNonceAuthorityAddress>,
+ *         ]
+ *     > &
+ *     InstructionWithData<AdvanceNonceAccountInstructionData>;
+ * ```
+ */
+export interface InstructionWithData<TData extends ReadonlyUint8Array> extends Instruction {
+    readonly data: TData;
+}
+
+export function isInstructionWithData<
+    TData extends ReadonlyUint8Array = ReadonlyUint8Array,
+    TInstruction extends Instruction = Instruction,
+>(instruction: TInstruction): instruction is InstructionWithData<TData> & TInstruction {
+    return instruction.data !== undefined;
+}
+
+export function assertIsInstructionWithData<
+    TData extends ReadonlyUint8Array = ReadonlyUint8Array,
+    TInstruction extends Instruction = Instruction,
+>(instruction: TInstruction): asserts instruction is InstructionWithData<TData> & TInstruction {
+    if (instruction.data === undefined) {
+        throw new SolanaError(SOLANA_ERROR__INSTRUCTION__EXPECTED_TO_HAVE_DATA, {
+            accountAddresses: instruction.accounts?.map(a => a.address),
+            programAddress: instruction.programAddress,
+        });
+    }
+}

package/src/roles.ts

@@ -0,0 +1,105 @@
+/**
+ * Describes the purpose for which an account participates in a transaction.
+ *
+ * Every account that participates in a transaction can be read from, but only ones that you mark as
+ * writable may be written to, and only ones that you indicate must sign the transaction will gain
+ * the privileges associated with signers at runtime.
+ *
+ * |                               | `isSigner` | `isWritable` |
+ * | ----------------------------- | ---------- | ------------ |
+ * | `AccountRole.READONLY`        | ❌   | ❌     |
+ * | `AccountRole.WRITABLE`        | ❌   | ✅     |
+ * | `AccountRole.READONLY_SIGNER` | ✅   | ❌     |
+ * | `AccountRole.WRITABLE_SIGNER` | ✅   | ✅     |
+ */
+export enum AccountRole {
+    // Bitflag guide: is signer ⌄⌄ is writable
+    WRITABLE_SIGNER = /* 3 */ 0b11, // prettier-ignore
+    READONLY_SIGNER = /* 2 */ 0b10, // prettier-ignore
+    WRITABLE =        /* 1 */ 0b01, // prettier-ignore
+    READONLY =        /* 0 */ 0b00, // prettier-ignore
+}
+
+// Quick primer on bitwise operations: https://stackoverflow.com/a/1436448/802047
+const IS_SIGNER_BITMASK = 0b10;
+const IS_WRITABLE_BITMASK = 0b01;
+
+/**
+ * @returns An {@link AccountRole} representing the non-signer variant of the supplied role.
+ */
+export function downgradeRoleToNonSigner(role: AccountRole.READONLY_SIGNER): AccountRole.READONLY;
+export function downgradeRoleToNonSigner(role: AccountRole.WRITABLE_SIGNER): AccountRole.WRITABLE;
+export function downgradeRoleToNonSigner(role: AccountRole): AccountRole;
+export function downgradeRoleToNonSigner(role: AccountRole): AccountRole {
+    return role & ~IS_SIGNER_BITMASK;
+}
+
+/**
+ * @returns An {@link AccountRole} representing the read-only variant of the supplied role.
+ */
+export function downgradeRoleToReadonly(role: AccountRole.WRITABLE): AccountRole.READONLY;
+export function downgradeRoleToReadonly(role: AccountRole.WRITABLE_SIGNER): AccountRole.READONLY_SIGNER;
+export function downgradeRoleToReadonly(role: AccountRole): AccountRole;
+export function downgradeRoleToReadonly(role: AccountRole): AccountRole {
+    return role & ~IS_WRITABLE_BITMASK;
+}
+
+/**
+ * Returns `true` if the {@link AccountRole} given represents that of a signer. Also refines the
+ * TypeScript type of the supplied role.
+ */
+export function isSignerRole(role: AccountRole): role is AccountRole.READONLY_SIGNER | AccountRole.WRITABLE_SIGNER {
+    return role >= AccountRole.READONLY_SIGNER;
+}
+
+/**
+ * Returns `true` if the {@link AccountRole} given represents that of a writable account. Also
+ * refines the TypeScript type of the supplied role.
+ */
+export function isWritableRole(role: AccountRole): role is AccountRole.WRITABLE | AccountRole.WRITABLE_SIGNER {
+    return (role & IS_WRITABLE_BITMASK) !== 0;
+}
+
+/**
+ * Given two {@link AccountRole | AccountRoles}, will return the {@link AccountRole} that grants the
+ * highest privileges of both.
+ *
+ * @example
+ * ```ts
+ * // Returns `AccountRole.WRITABLE_SIGNER`
+ * mergeRoles(AccountRole.READONLY_SIGNER, AccountRole.WRITABLE);
+ * ```
+ */
+export function mergeRoles(roleA: AccountRole.WRITABLE, roleB: AccountRole.READONLY_SIGNER): AccountRole.WRITABLE_SIGNER; // prettier-ignore
+export function mergeRoles(roleA: AccountRole.READONLY_SIGNER, roleB: AccountRole.WRITABLE): AccountRole.WRITABLE_SIGNER; // prettier-ignore
+export function mergeRoles(roleA: AccountRole, roleB: AccountRole.WRITABLE_SIGNER): AccountRole.WRITABLE_SIGNER; // prettier-ignore
+export function mergeRoles(roleA: AccountRole.WRITABLE_SIGNER, roleB: AccountRole): AccountRole.WRITABLE_SIGNER; // prettier-ignore
+export function mergeRoles(roleA: AccountRole, roleB: AccountRole.READONLY_SIGNER): AccountRole.READONLY_SIGNER; // prettier-ignore
+export function mergeRoles(roleA: AccountRole.READONLY_SIGNER, roleB: AccountRole): AccountRole.READONLY_SIGNER; // prettier-ignore
+export function mergeRoles(roleA: AccountRole, roleB: AccountRole.WRITABLE): AccountRole.WRITABLE; // prettier-ignore
+export function mergeRoles(roleA: AccountRole.WRITABLE, roleB: AccountRole): AccountRole.WRITABLE; // prettier-ignore
+export function mergeRoles(roleA: AccountRole.READONLY, roleB: AccountRole.READONLY): AccountRole.READONLY; // prettier-ignore
+export function mergeRoles(roleA: AccountRole, roleB: AccountRole): AccountRole; // prettier-ignore
+export function mergeRoles(roleA: AccountRole, roleB: AccountRole): AccountRole {
+    return roleA | roleB;
+}
+
+/**
+ * @returns An {@link AccountRole} representing the signer variant of the supplied role.
+ */
+export function upgradeRoleToSigner(role: AccountRole.READONLY): AccountRole.READONLY_SIGNER;
+export function upgradeRoleToSigner(role: AccountRole.WRITABLE): AccountRole.WRITABLE_SIGNER;
+export function upgradeRoleToSigner(role: AccountRole): AccountRole;
+export function upgradeRoleToSigner(role: AccountRole): AccountRole {
+    return role | IS_SIGNER_BITMASK;
+}
+
+/**
+ * @returns An {@link AccountRole} representing the writable variant of the supplied role.
+ */
+export function upgradeRoleToWritable(role: AccountRole.READONLY): AccountRole.WRITABLE;
+export function upgradeRoleToWritable(role: AccountRole.READONLY_SIGNER): AccountRole.WRITABLE_SIGNER;
+export function upgradeRoleToWritable(role: AccountRole): AccountRole;
+export function upgradeRoleToWritable(role: AccountRole): AccountRole {
+    return role | IS_WRITABLE_BITMASK;
+}