@solana/program-client-core 8.3.0-canary-20260909094827 → 8.3.0

package/dist/types/instruction-input-resolution.d.ts

@@ -1,6 +1,36 @@
-import { type Address, type ProgramDerivedAddress } from '@solana/addresses';
-import { type AccountMeta } from '@solana/instructions';
+import { type Address, type HasAddress, type ProgramDerivedAddress } from '@solana/addresses';
+import { type AccountMeta, type AccountNonSignerMeta, AccountRole } from '@solana/instructions';
 import { type AccountSignerMeta, type TransactionSigner } from '@solana/signers';
+/**
+ * Represents the accepted input values for a non-signer instruction account.
+ *
+ * Namely, one of the following:
+ * - An {@link Address} — the most common case.
+ * - Any object exposing an `address` property (see {@link HasAddress}) — e.g. a framework's
+ *   address wrapper class. Note that {@link TransactionSigner | TransactionSigners} satisfy this
+ *   shape too, in which case they act as plain address carriers for non-signer accounts.
+ * - A {@link ProgramDerivedAddress} — i.e. an `[address, bump]` tuple.
+ * - An {@link AccountNonSignerMeta} — i.e. `{ address, role }` — to explicitly override the
+ *   role derived from the program's IDL, e.g. to mark an account as writable or readonly.
+ *
+ * @typeParam TAddress - Supply a string literal to define an account having a particular address.
+ *
+ * @see {@link InstructionSignerInput}
+ */
+export type InstructionAccountInput<TAddress extends string = string> = AccountNonSignerMeta<TAddress> | Address<TAddress> | HasAddress<TAddress> | ProgramDerivedAddress<TAddress>;
+/**
+ * Represents the accepted input values for a signer instruction account.
+ *
+ * Namely, one of the following:
+ * - A {@link TransactionSigner} — the most common case.
+ * - An {@link AccountSignerMeta} — i.e. `{ address, role, signer }` — to explicitly override the
+ *   role derived from the program's IDL, e.g. to mark a signer account as writable or readonly.
+ *
+ * @typeParam TAddress - Supply a string literal to define an account having a particular address.
+ *
+ * @see {@link InstructionAccountInput}
+ */
+export type InstructionSignerInput<TAddress extends string = string> = AccountSignerMeta<TAddress> | TransactionSigner<TAddress>;
 /**
  * Ensures a resolved instruction input is not null or undefined.
  *
@@ -29,8 +59,9 @@ export declare function getNonNullResolvedInstructionInput<T>(inputName: string,
  * Extracts the address from a resolved instruction account.
  *
  * A resolved instruction account can be an {@link Address}, a {@link ProgramDerivedAddress},
- * or a {@link TransactionSigner}. This function extracts the underlying address from
- * any of these types.
+ * or any object exposing an `address` property — such as a {@link TransactionSigner}, an
+ * account meta, or a framework's address wrapper class (see {@link HasAddress}). This
+ * function extracts the underlying address from any of these types.
  *
  * @typeParam T - The address type, defaults to `string`.
  *
@@ -70,7 +101,8 @@ export declare function getResolvedInstructionAccountAsProgramDerivedAddress<T e
 /**
  * Extracts a {@link TransactionSigner} from a resolved instruction account.
  *
- * This function validates that the resolved account is a transaction signer and returns it.
+ * This function validates that the resolved account is a transaction signer — or an
+ * {@link AccountSignerMeta} carrying one — and returns the signer.
  * Use this when you need the resolved account to be a signer.
  *
  * @typeParam T - The address type, defaults to `string`.
@@ -90,10 +122,16 @@ export declare function getResolvedInstructionAccountAsTransactionSigner<T exten
 /**
  * Represents a resolved account input for an instruction.
  *
- * During instruction building, account inputs are resolved to this type which
- * captures both the account value and whether it should be marked as writable.
- * The value can be an {@link Address}, a {@link ProgramDerivedAddress}, a
- * {@link TransactionSigner}, or `null` for optional accounts.
+ * During instruction building, account inputs are resolved to this type which captures
+ * the account value alongside the signer and writable flags declared by the program's IDL.
+ * The value can be any {@link InstructionAccountInput}, any {@link InstructionSignerInput},
+ * or `null` for optional accounts.
+ *
+ * The optional `isSigner` flag describes whether the IDL requires the account to sign the
+ * transaction — with `'either'` meaning the account may or may not be a signer, in which
+ * case providing a {@link TransactionSigner} value is what marks it as one. Omitting the
+ * flag — e.g. in program clients generated before its introduction — is equivalent to
+ * setting it to `'either'`.
  *
  * @typeParam TAddress - The address type, defaults to `string`.
  * @typeParam TValue - The type of the resolved value.
@@ -102,14 +140,123 @@ export declare function getResolvedInstructionAccountAsTransactionSigner<T exten
  * ```ts
  * const mintAccount: ResolvedInstructionAccount = {
  *   value: mintAddress,
+ *   isSigner: false,
  *   isWritable: true,
  * };
  * ```
  */
-export type ResolvedInstructionAccount<TAddress extends string = string, TValue extends Address<TAddress> | ProgramDerivedAddress<TAddress> | TransactionSigner<TAddress> | null = Address<TAddress> | ProgramDerivedAddress<TAddress> | TransactionSigner<TAddress> | null> = {
+export type ResolvedInstructionAccount<TAddress extends string = string, TValue extends InstructionAccountInput<TAddress> | InstructionSignerInput<TAddress> | null = InstructionAccountInput<TAddress> | InstructionSignerInput<TAddress> | null> = {
+    isSigner?: boolean | 'either';
     isWritable: boolean;
     value: TValue;
 };
+/**
+ * Extracts the address type parameter from an instruction account input.
+ *
+ * Given any {@link InstructionAccountInput} or {@link InstructionSignerInput} — e.g. an
+ * {@link Address}, an address-bearing object (see {@link HasAddress}), a
+ * {@link ProgramDerivedAddress} or an account meta — this type helper resolves to the
+ * branded address string it carries. This allows generated program clients to recover the
+ * address type parameter of an account from the caller's input type alone — e.g. via
+ * `InstructionAccountInputAddress<TInput['authority']>` — instead of declaring a dedicated
+ * address type parameter on the instruction builder.
+ *
+ * When given a union of inputs, the helper distributes over it, so a union whose members
+ * all share the same address brand resolves to that brand. Inputs carrying no brand
+ * resolve to `string`.
+ *
+ * @typeParam TInput - The type of the input provided by the caller for this account.
+ *
+ * @example
+ * ```ts
+ * type A = InstructionAccountInputAddress<Address<'1234'>>; // '1234'
+ * type B = InstructionAccountInputAddress<TransactionSigner<'1234'>>; // '1234'
+ * type C = InstructionAccountInputAddress<ProgramDerivedAddress<'1234'>>; // '1234'
+ * type D = InstructionAccountInputAddress<Address>; // string
+ * ```
+ *
+ * @see {@link ResolvedInstructionAccountMeta}
+ */
+export type InstructionAccountInputAddress<TInput> = TInput extends HasAddress<infer TAddress> ? TAddress : TInput extends ProgramDerivedAddress<infer TAddress> ? TAddress : TInput extends Address<infer TAddress> ? TAddress : string;
+/**
+ * Computes the account meta type produced by an instruction account, based on the input
+ * provided by the caller.
+ *
+ * This type helper mirrors the runtime logic of {@link getAccountMetaFactory} so that
+ * generated program clients can accurately type the accounts of the instructions they
+ * return. Namely:
+ * - When the input carries an explicit `role` — i.e. it is an {@link AccountNonSignerMeta} or an
+ *   {@link AccountSignerMeta} — the meta type preserves the input's role type: an inline
+ *   `role: AccountRole.READONLY` override resolves to `ReadonlyAccount`, while a role only
+ *   known at runtime widens to {@link AccountMeta}. If the input also carries a `signer`,
+ *   {@link AccountSignerMeta} is used so the attached signer is reflected in the type.
+ * - When the input is a {@link TransactionSigner}, the meta type is `TSignerMeta` — e.g.
+ *   `ReadonlySignerAccount<TAddress> & AccountSignerMeta<TAddress>` for accounts the IDL
+ *   declares as signers. For non-signer accounts, `TSignerMeta` should be left to its
+ *   default of `TAddress` so that signers merely act as address carriers.
+ * - Otherwise, the helper resolves to `TAddress` — the branded address string that generated
+ *   instruction types map to the account meta declared by the program's IDL.
+ *
+ * Note that the checks are wrapped in tuples (`[TInput] extends [...]`) to prevent unions
+ * from distributing. If `TInput` is not narrowed to the caller's specific input type — e.g.
+ * when a declared input union is provided instead — the helper deterministically falls back
+ * to `TAddress`, matching the account meta declared by the program's IDL.
+ *
+ * @typeParam TInput - The type of the input provided by the caller for this account.
+ * @typeParam TAddress - The address type parameter of the account.
+ * @typeParam TSignerMeta - The meta type produced when a {@link TransactionSigner} is
+ * provided. Defaults to `TAddress`, which treats signers as plain address carriers.
+ *
+ * @example
+ * The instruction builder below captures the caller's input in a single `TInput` type
+ * parameter and recovers each account's address type parameter from it using
+ * {@link InstructionAccountInputAddress}.
+ * ```ts
+ * declare function getTransferInstruction<TInput extends TransferInput>(
+ *     input: TInput,
+ * ): TransferInstruction<
+ *     ResolvedInstructionAccountMeta<
+ *         TInput['authority'],
+ *         InstructionAccountInputAddress<TInput['authority']>,
+ *         ReadonlySignerAccount<InstructionAccountInputAddress<TInput['authority']>> &
+ *             AccountSignerMeta<InstructionAccountInputAddress<TInput['authority']>>
+ *     >
+ * >;
+ * ```
+ *
+ * Alternatively, instruction builders may keep a dedicated address type parameter per
+ * account. In that case, the parameter below must intersect the concrete input type with
+ * the inferred `TInput` type parameter (`TransferInput<TAccountAuthority> & TInput`) —
+ * referencing the address type parameters only in `TInput`'s constraint makes their
+ * inference fall back to `string`. Defaulting `TInput` to the concrete input type keeps
+ * call sites with explicit type arguments working.
+ * ```ts
+ * declare function getTransferInstruction<
+ *     TAccountAuthority extends string,
+ *     TInput extends TransferInput<TAccountAuthority> = TransferInput<TAccountAuthority>,
+ * >(
+ *     input: TransferInput<TAccountAuthority> & TInput,
+ * ): TransferInstruction<
+ *     ResolvedInstructionAccountMeta<
+ *         TInput['authority'],
+ *         TAccountAuthority,
+ *         ReadonlySignerAccount<TAccountAuthority> & AccountSignerMeta<TAccountAuthority>
+ *     >
+ * >;
+ * ```
+ *
+ * @see {@link getAccountMetaFactory}
+ * @see {@link InstructionAccountInputAddress}
+ */
+export type ResolvedInstructionAccountMeta<TInput, TAddress extends string, TSignerMeta = TAddress> = [TInput] extends [
+    {
+        role: infer TRole extends AccountRole;
+    }
+] ? ([TInput] extends [{
+    signer: TransactionSigner<TAddress>;
+}] ? AccountSignerMeta<TAddress> : AccountMeta<TAddress>) & {
+    readonly role: TRole;
+} : [TInput] extends [TransactionSigner<TAddress>] ? TSignerMeta : TAddress;
 /**
  * Creates a factory function that converts resolved instruction accounts to account metas.
  *
@@ -117,12 +264,26 @@ export type ResolvedInstructionAccount<TAddress extends string = string, TValue
  * {@link AccountMeta} or {@link AccountSignerMeta} objects suitable for building instructions.
  * It also determines how to handle optional accounts based on the provided strategy.
  *
+ * The role of the resulting account meta is determined as follows, in order of precedence:
+ * 1. If the value carries an explicit `role` — i.e. it is an {@link AccountNonSignerMeta} or
+ *    an {@link AccountSignerMeta} — that role is used as-is, regardless of the flags declared
+ *    by the program's IDL.
+ * 2. Otherwise, if the value is a {@link TransactionSigner} and the account's `isSigner` flag
+ *    is not `false`, the IDL's writable flag is upgraded to the corresponding signer role and
+ *    the signer is attached to the meta. When `isSigner` is `false`, the signer merely acts
+ *    as an address carrier and no upgrade occurs. Omitting the flag is equivalent to `'either'`.
+ * 3. Otherwise, the IDL's writable flag decides between the readonly and writable roles.
+ *
  * @param programAddress - The program address, used when optional accounts use the `programId` strategy.
  * @param optionalAccountStrategy - How to handle null account values:
  *   - `'omitted'`: Optional accounts are excluded from the instruction entirely.
  *   - `'programId'`: Optional accounts are replaced with the program address as a read-only account.
  * @returns A factory function that converts a resolved account to an account meta.
  *
+ * @throws Throws a {@link SolanaError} when the account's `isSigner` flag is `true` but the
+ * provided value is neither a {@link TransactionSigner} nor carries an explicit `role`. Use
+ * `createNoopSigner()` from `@solana/signers` if the account's signature is provided by other means.
+ *
  * @example
  * ```ts
  * const toAccountMeta = getAccountMetaFactory(programAddress, 'programId');

package/dist/types/instruction-input-resolution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instruction-input-resolution.d.ts","sourceRoot":"","sources":["../../src/instruction-input-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAA2B,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAMtG,OAAO,EAAE,KAAK,WAAW,EAAoC,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EAAE,KAAK,iBAAiB,EAAuB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtG;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kCAAkC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,CAOvG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wCAAwC,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAC9E,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,SAAS,GAC1D,OAAO,CAAC,CAAC,CAAC,CASZ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oDAAoD,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAC1F,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,SAAS,GAC1D,qBAAqB,CAAC,CAAC,CAAC,CAQ1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gDAAgD,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EACtF,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,SAAS,GAC1D,iBAAiB,CAAC,CAAC,CAAC,CAQtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,0BAA0B,CAClC,QAAQ,SAAS,MAAM,GAAG,MAAM,EAChC,MAAM,SAAS,OAAO,CAAC,QAAQ,CAAC,GAAG,qBAAqB,CAAC,QAAQ,CAAC,GAAG,iBAAiB,CAAC,QAAQ,CAAC,GAAG,IAAI,GACjG,OAAO,CAAC,QAAQ,CAAC,GACjB,qBAAqB,CAAC,QAAQ,CAAC,GAC/B,iBAAiB,CAAC,QAAQ,CAAC,GAC3B,IAAI,IACV;IACA,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,cAAc,EAAE,OAAO,EAAE,uBAAuB,EAAE,SAAS,GAAG,WAAW,IACnG,WAAW,MAAM,EAAE,SAAS,0BAA0B,KAAG,WAAW,GAAG,iBAAiB,GAAG,SAAS,CAc/G"}
+{"version":3,"file":"instruction-input-resolution.d.ts","sourceRoot":"","sources":["../../src/instruction-input-resolution.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/program-client-core",
-  "version": "8.3.0-canary-20260909094827",
+  "version": "8.3.0",
   "description": "Core utilities for building Solana program clients",
   "homepage": "https://www.solanakit.com/api#solanaprogram-client-core",
   "exports": {
@@ -56,15 +56,15 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/accounts": "8.3.0-canary-20260909094827",
-    "@solana/addresses": "8.3.0-canary-20260909094827",
-    "@solana/codecs-core": "8.3.0-canary-20260909094827",
-    "@solana/errors": "8.3.0-canary-20260909094827",
-    "@solana/instruction-plans": "8.3.0-canary-20260909094827",
-    "@solana/instructions": "8.3.0-canary-20260909094827",
-    "@solana/plugin-interfaces": "8.3.0-canary-20260909094827",
-    "@solana/rpc-api": "8.3.0-canary-20260909094827",
-    "@solana/signers": "8.3.0-canary-20260909094827"
+    "@solana/addresses": "8.3.0",
+    "@solana/accounts": "8.3.0",
+    "@solana/codecs-core": "8.3.0",
+    "@solana/instruction-plans": "8.3.0",
+    "@solana/errors": "8.3.0",
+    "@solana/instructions": "8.3.0",
+    "@solana/plugin-interfaces": "8.3.0",
+    "@solana/rpc-api": "8.3.0",
+    "@solana/signers": "8.3.0"
   },
   "peerDependencies": {
     "typescript": ">=5.4.0"

package/src/instruction-input-resolution.ts

@@ -1,12 +1,51 @@
-import { type Address, isProgramDerivedAddress, type ProgramDerivedAddress } from '@solana/addresses';
+import { type Address, type HasAddress, isProgramDerivedAddress, type ProgramDerivedAddress } from '@solana/addresses';
 import {
     SOLANA_ERROR__PROGRAM_CLIENTS__RESOLVED_INSTRUCTION_INPUT_MUST_BE_NON_NULL,
+    SOLANA_ERROR__PROGRAM_CLIENTS__RESOLVED_INSTRUCTION_INPUT_MUST_BE_SIGNER,
     SOLANA_ERROR__PROGRAM_CLIENTS__UNEXPECTED_RESOLVED_INSTRUCTION_INPUT_TYPE,
     SolanaError,
 } from '@solana/errors';
-import { type AccountMeta, AccountRole, upgradeRoleToSigner } from '@solana/instructions';
+import { type AccountMeta, type AccountNonSignerMeta, AccountRole, upgradeRoleToSigner } from '@solana/instructions';
 import { type AccountSignerMeta, isTransactionSigner, type TransactionSigner } from '@solana/signers';
 
+/**
+ * Represents the accepted input values for a non-signer instruction account.
+ *
+ * Namely, one of the following:
+ * - An {@link Address} — the most common case.
+ * - Any object exposing an `address` property (see {@link HasAddress}) — e.g. a framework's
+ *   address wrapper class. Note that {@link TransactionSigner | TransactionSigners} satisfy this
+ *   shape too, in which case they act as plain address carriers for non-signer accounts.
+ * - A {@link ProgramDerivedAddress} — i.e. an `[address, bump]` tuple.
+ * - An {@link AccountNonSignerMeta} — i.e. `{ address, role }` — to explicitly override the
+ *   role derived from the program's IDL, e.g. to mark an account as writable or readonly.
+ *
+ * @typeParam TAddress - Supply a string literal to define an account having a particular address.
+ *
+ * @see {@link InstructionSignerInput}
+ */
+export type InstructionAccountInput<TAddress extends string = string> =
+    | AccountNonSignerMeta<TAddress>
+    | Address<TAddress>
+    | HasAddress<TAddress>
+    | ProgramDerivedAddress<TAddress>;
+
+/**
+ * Represents the accepted input values for a signer instruction account.
+ *
+ * Namely, one of the following:
+ * - A {@link TransactionSigner} — the most common case.
+ * - An {@link AccountSignerMeta} — i.e. `{ address, role, signer }` — to explicitly override the
+ *   role derived from the program's IDL, e.g. to mark a signer account as writable or readonly.
+ *
+ * @typeParam TAddress - Supply a string literal to define an account having a particular address.
+ *
+ * @see {@link InstructionAccountInput}
+ */
+export type InstructionSignerInput<TAddress extends string = string> =
+    | AccountSignerMeta<TAddress>
+    | TransactionSigner<TAddress>;
+
 /**
  * Ensures a resolved instruction input is not null or undefined.
  *
@@ -43,8 +82,9 @@ export function getNonNullResolvedInstructionInput<T>(inputName: string, value:
  * Extracts the address from a resolved instruction account.
  *
  * A resolved instruction account can be an {@link Address}, a {@link ProgramDerivedAddress},
- * or a {@link TransactionSigner}. This function extracts the underlying address from
- * any of these types.
+ * or any object exposing an `address` property — such as a {@link TransactionSigner}, an
+ * account meta, or a framework's address wrapper class (see {@link HasAddress}). This
+ * function extracts the underlying address from any of these types.
  *
  * @typeParam T - The address type, defaults to `string`.
  *
@@ -109,7 +149,8 @@ export function getResolvedInstructionAccountAsProgramDerivedAddress<T extends s
 /**
  * Extracts a {@link TransactionSigner} from a resolved instruction account.
  *
- * This function validates that the resolved account is a transaction signer and returns it.
+ * This function validates that the resolved account is a transaction signer — or an
+ * {@link AccountSignerMeta} carrying one — and returns the signer.
  * Use this when you need the resolved account to be a signer.
  *
  * @typeParam T - The address type, defaults to `string`.
@@ -129,22 +170,29 @@ export function getResolvedInstructionAccountAsTransactionSigner<T extends strin
     inputName: string,
     value: ResolvedInstructionAccount<T>['value'] | undefined,
 ): TransactionSigner<T> {
-    if (!isResolvedInstructionAccountSigner(value)) {
+    const signer = value && hasExplicitRole(value) && 'signer' in value ? value.signer : value;
+    if (!isResolvedInstructionAccountSigner<T>(signer)) {
         throw new SolanaError(SOLANA_ERROR__PROGRAM_CLIENTS__UNEXPECTED_RESOLVED_INSTRUCTION_INPUT_TYPE, {
             expectedType: 'TransactionSigner',
             inputName,
         });
     }
-    return value;
+    return signer;
 }
 
 /**
  * Represents a resolved account input for an instruction.
  *
- * During instruction building, account inputs are resolved to this type which
- * captures both the account value and whether it should be marked as writable.
- * The value can be an {@link Address}, a {@link ProgramDerivedAddress}, a
- * {@link TransactionSigner}, or `null` for optional accounts.
+ * During instruction building, account inputs are resolved to this type which captures
+ * the account value alongside the signer and writable flags declared by the program's IDL.
+ * The value can be any {@link InstructionAccountInput}, any {@link InstructionSignerInput},
+ * or `null` for optional accounts.
+ *
+ * The optional `isSigner` flag describes whether the IDL requires the account to sign the
+ * transaction — with `'either'` meaning the account may or may not be a signer, in which
+ * case providing a {@link TransactionSigner} value is what marks it as one. Omitting the
+ * flag — e.g. in program clients generated before its introduction — is equivalent to
+ * setting it to `'either'`.
  *
  * @typeParam TAddress - The address type, defaults to `string`.
  * @typeParam TValue - The type of the resolved value.
@@ -153,22 +201,139 @@ export function getResolvedInstructionAccountAsTransactionSigner<T extends strin
  * ```ts
  * const mintAccount: ResolvedInstructionAccount = {
  *   value: mintAddress,
+ *   isSigner: false,
  *   isWritable: true,
  * };
  * ```
  */
 export type ResolvedInstructionAccount<
     TAddress extends string = string,
-    TValue extends Address<TAddress> | ProgramDerivedAddress<TAddress> | TransactionSigner<TAddress> | null =
-        | Address<TAddress>
-        | ProgramDerivedAddress<TAddress>
-        | TransactionSigner<TAddress>
+    TValue extends InstructionAccountInput<TAddress> | InstructionSignerInput<TAddress> | null =
+        | InstructionAccountInput<TAddress>
+        | InstructionSignerInput<TAddress>
         | null,
 > = {
+    isSigner?: boolean | 'either';
     isWritable: boolean;
     value: TValue;
 };
 
+/**
+ * Extracts the address type parameter from an instruction account input.
+ *
+ * Given any {@link InstructionAccountInput} or {@link InstructionSignerInput} — e.g. an
+ * {@link Address}, an address-bearing object (see {@link HasAddress}), a
+ * {@link ProgramDerivedAddress} or an account meta — this type helper resolves to the
+ * branded address string it carries. This allows generated program clients to recover the
+ * address type parameter of an account from the caller's input type alone — e.g. via
+ * `InstructionAccountInputAddress<TInput['authority']>` — instead of declaring a dedicated
+ * address type parameter on the instruction builder.
+ *
+ * When given a union of inputs, the helper distributes over it, so a union whose members
+ * all share the same address brand resolves to that brand. Inputs carrying no brand
+ * resolve to `string`.
+ *
+ * @typeParam TInput - The type of the input provided by the caller for this account.
+ *
+ * @example
+ * ```ts
+ * type A = InstructionAccountInputAddress<Address<'1234'>>; // '1234'
+ * type B = InstructionAccountInputAddress<TransactionSigner<'1234'>>; // '1234'
+ * type C = InstructionAccountInputAddress<ProgramDerivedAddress<'1234'>>; // '1234'
+ * type D = InstructionAccountInputAddress<Address>; // string
+ * ```
+ *
+ * @see {@link ResolvedInstructionAccountMeta}
+ */
+export type InstructionAccountInputAddress<TInput> =
+    TInput extends HasAddress<infer TAddress>
+        ? TAddress
+        : TInput extends ProgramDerivedAddress<infer TAddress>
+          ? TAddress
+          : TInput extends Address<infer TAddress>
+            ? TAddress
+            : string;
+
+/**
+ * Computes the account meta type produced by an instruction account, based on the input
+ * provided by the caller.
+ *
+ * This type helper mirrors the runtime logic of {@link getAccountMetaFactory} so that
+ * generated program clients can accurately type the accounts of the instructions they
+ * return. Namely:
+ * - When the input carries an explicit `role` — i.e. it is an {@link AccountNonSignerMeta} or an
+ *   {@link AccountSignerMeta} — the meta type preserves the input's role type: an inline
+ *   `role: AccountRole.READONLY` override resolves to `ReadonlyAccount`, while a role only
+ *   known at runtime widens to {@link AccountMeta}. If the input also carries a `signer`,
+ *   {@link AccountSignerMeta} is used so the attached signer is reflected in the type.
+ * - When the input is a {@link TransactionSigner}, the meta type is `TSignerMeta` — e.g.
+ *   `ReadonlySignerAccount<TAddress> & AccountSignerMeta<TAddress>` for accounts the IDL
+ *   declares as signers. For non-signer accounts, `TSignerMeta` should be left to its
+ *   default of `TAddress` so that signers merely act as address carriers.
+ * - Otherwise, the helper resolves to `TAddress` — the branded address string that generated
+ *   instruction types map to the account meta declared by the program's IDL.
+ *
+ * Note that the checks are wrapped in tuples (`[TInput] extends [...]`) to prevent unions
+ * from distributing. If `TInput` is not narrowed to the caller's specific input type — e.g.
+ * when a declared input union is provided instead — the helper deterministically falls back
+ * to `TAddress`, matching the account meta declared by the program's IDL.
+ *
+ * @typeParam TInput - The type of the input provided by the caller for this account.
+ * @typeParam TAddress - The address type parameter of the account.
+ * @typeParam TSignerMeta - The meta type produced when a {@link TransactionSigner} is
+ * provided. Defaults to `TAddress`, which treats signers as plain address carriers.
+ *
+ * @example
+ * The instruction builder below captures the caller's input in a single `TInput` type
+ * parameter and recovers each account's address type parameter from it using
+ * {@link InstructionAccountInputAddress}.
+ * ```ts
+ * declare function getTransferInstruction<TInput extends TransferInput>(
+ *     input: TInput,
+ * ): TransferInstruction<
+ *     ResolvedInstructionAccountMeta<
+ *         TInput['authority'],
+ *         InstructionAccountInputAddress<TInput['authority']>,
+ *         ReadonlySignerAccount<InstructionAccountInputAddress<TInput['authority']>> &
+ *             AccountSignerMeta<InstructionAccountInputAddress<TInput['authority']>>
+ *     >
+ * >;
+ * ```
+ *
+ * Alternatively, instruction builders may keep a dedicated address type parameter per
+ * account. In that case, the parameter below must intersect the concrete input type with
+ * the inferred `TInput` type parameter (`TransferInput<TAccountAuthority> & TInput`) —
+ * referencing the address type parameters only in `TInput`'s constraint makes their
+ * inference fall back to `string`. Defaulting `TInput` to the concrete input type keeps
+ * call sites with explicit type arguments working.
+ * ```ts
+ * declare function getTransferInstruction<
+ *     TAccountAuthority extends string,
+ *     TInput extends TransferInput<TAccountAuthority> = TransferInput<TAccountAuthority>,
+ * >(
+ *     input: TransferInput<TAccountAuthority> & TInput,
+ * ): TransferInstruction<
+ *     ResolvedInstructionAccountMeta<
+ *         TInput['authority'],
+ *         TAccountAuthority,
+ *         ReadonlySignerAccount<TAccountAuthority> & AccountSignerMeta<TAccountAuthority>
+ *     >
+ * >;
+ * ```
+ *
+ * @see {@link getAccountMetaFactory}
+ * @see {@link InstructionAccountInputAddress}
+ */
+export type ResolvedInstructionAccountMeta<TInput, TAddress extends string, TSignerMeta = TAddress> = [TInput] extends [
+    { role: infer TRole extends AccountRole },
+]
+    ? ([TInput] extends [{ signer: TransactionSigner<TAddress> }]
+          ? AccountSignerMeta<TAddress>
+          : AccountMeta<TAddress>) & { readonly role: TRole }
+    : [TInput] extends [TransactionSigner<TAddress>]
+      ? TSignerMeta
+      : TAddress;
+
 /**
  * Creates a factory function that converts resolved instruction accounts to account metas.
  *
@@ -176,12 +341,26 @@ export type ResolvedInstructionAccount<
  * {@link AccountMeta} or {@link AccountSignerMeta} objects suitable for building instructions.
  * It also determines how to handle optional accounts based on the provided strategy.
  *
+ * The role of the resulting account meta is determined as follows, in order of precedence:
+ * 1. If the value carries an explicit `role` — i.e. it is an {@link AccountNonSignerMeta} or
+ *    an {@link AccountSignerMeta} — that role is used as-is, regardless of the flags declared
+ *    by the program's IDL.
+ * 2. Otherwise, if the value is a {@link TransactionSigner} and the account's `isSigner` flag
+ *    is not `false`, the IDL's writable flag is upgraded to the corresponding signer role and
+ *    the signer is attached to the meta. When `isSigner` is `false`, the signer merely acts
+ *    as an address carrier and no upgrade occurs. Omitting the flag is equivalent to `'either'`.
+ * 3. Otherwise, the IDL's writable flag decides between the readonly and writable roles.
+ *
  * @param programAddress - The program address, used when optional accounts use the `programId` strategy.
  * @param optionalAccountStrategy - How to handle null account values:
  *   - `'omitted'`: Optional accounts are excluded from the instruction entirely.
  *   - `'programId'`: Optional accounts are replaced with the program address as a read-only account.
  * @returns A factory function that converts a resolved account to an account meta.
  *
+ * @throws Throws a {@link SolanaError} when the account's `isSigner` flag is `true` but the
+ * provided value is neither a {@link TransactionSigner} nor carries an explicit `role`. Use
+ * `createNoopSigner()` from `@solana/signers` if the account's signature is provided by other means.
+ *
  * @example
  * ```ts
  * const toAccountMeta = getAccountMetaFactory(programAddress, 'programId');
@@ -195,8 +374,26 @@ export function getAccountMetaFactory(programAddress: Address, optionalAccountSt
             return Object.freeze({ address: programAddress, role: AccountRole.READONLY });
         }
 
+        // Explicit roles always take precedence over the flags declared by the program's IDL.
+        if (hasExplicitRole(account.value)) {
+            return Object.freeze({
+                address: account.value.address,
+                role: account.value.role,
+                ...('signer' in account.value && account.value.signer ? { signer: account.value.signer } : {}),
+            });
+        }
+
+        // Only mark implicit values as signers when the IDL declares
+        // the account as a signer or lets the input decide (`'either'`).
+        const idlIsSigner = account.isSigner ?? 'either';
+        const isSigner = idlIsSigner !== false && isResolvedInstructionAccountSigner(account.value);
+        if (!isSigner && idlIsSigner === true) {
+            throw new SolanaError(SOLANA_ERROR__PROGRAM_CLIENTS__RESOLVED_INSTRUCTION_INPUT_MUST_BE_SIGNER, {
+                inputName,
+            });
+        }
+
         const writableRole = account.isWritable ? AccountRole.WRITABLE : AccountRole.READONLY;
-        const isSigner = isResolvedInstructionAccountSigner(account.value);
         return Object.freeze({
             address: getAddressFromResolvedInstructionAccount(inputName, account.value),
             role: isSigner ? upgradeRoleToSigner(writableRole) : writableRole,
@@ -205,7 +402,23 @@ export function getAccountMetaFactory(programAddress: Address, optionalAccountSt
     };
 }
 
-function isResolvedInstructionAccountSigner(value: unknown): value is TransactionSigner {
+/**
+ * Checks whether a resolved instruction account value carries an explicit account role,
+ * i.e. whether it is an {@link AccountNonSignerMeta} or an {@link AccountSignerMeta}.
+ *
+ * Since {@link AccountRole} is a numeric enum, requiring `role` to be a number prevents
+ * unrelated `role` properties on address-bearing objects from being mistaken for a role
+ * override.
+ */
+function hasExplicitRole(
+    value: NonNullable<ResolvedInstructionAccount['value']>,
+): value is AccountNonSignerMeta | AccountSignerMeta {
+    return typeof value === 'object' && 'role' in value && typeof value.role === 'number';
+}
+
+function isResolvedInstructionAccountSigner<TAddress extends string = string>(
+    value: unknown,
+): value is TransactionSigner<TAddress> {
     return (
         !!value &&
         typeof value === 'object' &&