Add ClientWithIdentity plugin interface (#1530)

This PR adds a new `ClientWithIdentity` interface to `@solana/plugin-interfaces` alongside the existing `ClientWithPayer`, exposing `client.identity` as a `TransactionSigner` representing the wallet that owns things in the application — such as the authority over accounts, tokens, or other on-chain assets owned by the current user. Whereas `ClientWithPayer` describes the signer responsible for paying transaction fees and storage costs, `ClientWithIdentity` describes the signer whose assets the app is acting upon. In many apps these refer to the same wallet, but they can differ — for instance, when a service funds transactions on behalf of a user.

Author: lorisleiva

.changeset/tidy-wasps-mix.md

@@ -0,0 +1,5 @@
+---
+'@solana/plugin-interfaces': minor
+---
+
+Add `ClientWithIdentity` interface for clients that provide a default identity signer. Whereas `ClientWithPayer` describes the signer responsible for paying transaction fees and storage costs, `ClientWithIdentity` describes the signer whose assets the application is acting upon — such as the authority over accounts, tokens, or other on-chain assets owned by the current user. In many apps the payer and identity refer to the same signer, but they can differ when a service pays fees on behalf of a user.

packages/plugin-interfaces/README.md

@@ -52,6 +52,26 @@ function memoPlugin() {
 }
 ```
 
+### `ClientWithIdentity`
+
+Represents a client that provides a default identity signer — the wallet that owns things in the application, such as the authority over accounts, tokens, or other on-chain assets owned by the current user. Unlike `ClientWithPayer`, which describes the signer responsible for paying transaction fees and storage costs, the identity describes the signer whose assets the application is acting upon. In many apps, the payer and identity refer to the same signer, but they can differ — for example, when a service pays fees on behalf of a user.
+
+```ts
+import { extendClient } from '@solana/plugin-core';
+import { ClientWithIdentity } from '@solana/plugin-interfaces';
+
+function nftPlugin() {
+    return <T extends ClientWithIdentity>(client: T) =>
+        extendClient(client, {
+            transferNft: (mint: Address, recipient: Address) => {
+                // Use client.identity as the current owner of the NFT
+                const owner = client.identity;
+                // ...
+            },
+        });
+}
+```
+
 ### `ClientWithAirdrop`
 
 Represents a client that can request SOL airdrops (typically on devnet/testnet). The airdrop succeeds when the promise resolves. Some implementations (e.g., LiteSVM) update balances directly without a transaction, so no signature is returned in those cases.

packages/plugin-interfaces/src/__typetests__/identity-typetest.ts

@@ -0,0 +1,20 @@
+import type { TransactionSigner } from '@solana/signers';
+
+import type { ClientWithIdentity } from '../identity';
+
+// [DESCRIBE] ClientWithIdentity.
+{
+    // It provides an identity property that is a TransactionSigner.
+    {
+        const client = null as unknown as ClientWithIdentity;
+        client.identity satisfies TransactionSigner;
+    }
+
+    // It can be combined with other interfaces via intersection.
+    {
+        type CustomClient = ClientWithIdentity & { customMethod(): void };
+        const client = null as unknown as CustomClient;
+        client.identity satisfies TransactionSigner;
+        client.customMethod satisfies () => void;
+    }
+}

packages/plugin-interfaces/src/identity.ts

@@ -0,0 +1,23 @@
+import { TransactionSigner } from '@solana/signers';
+
+/**
+ * Represents a client that provides a default identity signer.
+ *
+ * The identity is a {@link TransactionSigner} representing the wallet that owns
+ * things in the application — for instance, the authority over accounts, tokens,
+ * or other on-chain assets owned by the current user. Unlike {@link ClientWithPayer},
+ * which describes the signer responsible for paying transaction fees and storage
+ * costs, the identity describes the signer whose assets the application is acting
+ * upon. In many apps, the payer and identity refer to the same signer, but they
+ * can differ — for example, when a service pays fees on behalf of a user.
+ *
+ * @example
+ * ```ts
+ * function getOwnerAddress(client: ClientWithIdentity): Address {
+ *     return client.identity.address;
+ * }
+ * ```
+ *
+ * @see {@link ClientWithPayer}
+ */
+export type ClientWithIdentity = { identity: TransactionSigner };

packages/plugin-interfaces/src/index.ts

@@ -8,5 +8,6 @@
 export * from './airdrop';
 export * from './instruction-plans';
 export * from './get-minimum-balance';
+export * from './identity';
 export * from './payer';
 export * from './rpc';

packages/plugin-interfaces/src/payer.ts

@@ -5,7 +5,13 @@ import { TransactionSigner } from '@solana/signers';
  *
  * The payer is a {@link TransactionSigner} used to sign and pay for transactions.
  * Clients implementing this interface can automatically fund transactions
- * without requiring callers to specify a fee payer explicitly.
+ * without requiring callers to specify a fee payer explicitly. Unlike
+ * {@link ClientWithIdentity}, which describes the signer whose assets the
+ * application is acting upon, the payer describes the signer responsible for
+ * paying transaction fees as well as storage costs — i.e. the minimum balance
+ * required to keep newly created accounts alive based on their size.
+ * In many apps the payer and identity refer to the same signer, but they can
+ * differ — for example, when a service pays fees on behalf of a user.
  *
  * @example
  * ```ts
@@ -14,5 +20,7 @@ import { TransactionSigner } from '@solana/signers';
  *     // Use feePayer.address as the transaction fee payer
  * }
  * ```
+ *
+ * @see {@link ClientWithIdentity}
  */
 export type ClientWithPayer = { payer: TransactionSigner };