diff --git a/.changeset/sixty-rice-read.md b/.changeset/sixty-rice-read.md new file mode 100644 index 0000000..a8f3b94 --- /dev/null +++ b/.changeset/sixty-rice-read.md @@ -0,0 +1,5 @@ +--- +'@solana/kit-plugin-payer': minor +--- + +Deprecate `@solana/kit-plugin-payer` in favor of `@solana/kit-plugin-signer`. All exports are available under the same name in the new package, which also provides `identity` and `signer` variants for each plugin. diff --git a/packages/kit-plugin-payer/README.md b/packages/kit-plugin-payer/README.md index 76e5149..6104db6 100644 --- a/packages/kit-plugin-payer/README.md +++ b/packages/kit-plugin-payer/README.md @@ -1,4 +1,4 @@ -# Kit Plugins ➤ Payer +# Kit Plugins ➤ Payer (deprecated) [![npm][npm-image]][npm-url] [![npm-downloads][npm-downloads-image]][npm-url] @@ -7,125 +7,50 @@ [npm-image]: https://img.shields.io/npm/v/@solana/kit-plugin-payer.svg?style=flat&label=%40solana%2Fkit-plugin-payer [npm-url]: https://www.npmjs.com/package/@solana/kit-plugin-payer -This package offers plugins that set up the main "payer" signer on your Kit clients. It does this by adding a `payer` property to the client, which can then be used to sign transactions, pay for fees, etc. This is a good way to feed signer information to subsequent plugins. +> [!WARNING] +> This package is deprecated. Use [`@solana/kit-plugin-signer`](../kit-plugin-signer) instead, which provides the same payer plugins plus new `identity` and `signer` variants. -## Installation +## Migration -```sh -pnpm install @solana/kit-plugin-payer -``` - -## `payer` plugin - -This plugin simply accepts a `TransactionSigner` and sets it as the `payer` property on the client. - -### Installation - -```ts -import { createClient } from '@solana/kit'; -import { payer } from '@solana/kit-plugin-payer'; - -const client = createClient().use(payer(mySigner)); -``` - -### Features - -- `payer`: The main payer signer for your Kit client. - ```ts - console.log(client.payer.address); - const transactionMessage = pipe( - createTransactionMessage({ version: 0 }), - tx => setTransactionFeePayerSigner(client.payer, tx), - tx => appendTransactionMessageInstruction(getTransferSolInstruction({ source: client.payer, ... }), tx), - ); - ``` - -## `generatedPayer` plugin - -This asynchronous plugin generates a new random `KeyPairSigner` to be used as the `payer` property on the client. - -### Installation - -```ts -import { createClient } from '@solana/kit'; -import { generatedPayer } from '@solana/kit-plugin-payer'; - -const client = await createClient().use(generatedPayer()); -``` - -### Features - -_See the `payer` plugin for available features_. - -## `generatedPayerWithSol` plugin - -This asynchronous plugin generates a new random `KeyPairSigner`, airdrops some SOL to it and sets it as the `payer` property on the client. - -### Installation +All exports are available under the same name in `@solana/kit-plugin-signer`. Simply update your import path: -Note that this plugin requires an airdrop plugin to be installed on the client beforehand (e.g. `rpcAirdrop` or `litesvmAirdrop`) which itself either requires an RPC connection or a LiteSVM instance. +```diff + import { createClient } from '@solana/kit'; +- import { payer } from '@solana/kit-plugin-payer'; ++ import { payer } from '@solana/kit-plugin-signer'; -```ts -import { createClient } from '@solana/kit'; -import { solanaRpcConnection, solanaRpcSubscriptionsConnection, rpcAirdrop } from '@solana/kit-plugin-rpc'; -import { generatedPayerWithSol } from '@solana/kit-plugin-payer'; - -const client = await createClient() - .use(solanaRpcConnection('http://127.0.0.1:8899')) - .use(solanaRpcSubscriptionsConnection('ws://127.0.0.1:8900')) - .use(rpcAirdrop()) - // or .use(litesvmConnection()).use(litesvmAirdrop()) - .use(generatedPayerWithSol(lamports(10_000_000_000n))); // 10 SOL -``` - -### Features - -_See the `payer` plugin for available features_. - -## `payerOrGeneratedPayer` plugin - -This asynchronous plugin uses the provided `TransactionSigner` as the payer if one is given. Otherwise, it generates a new random `KeyPairSigner`, airdrops 100 SOL to it, and sets it as the `payer` property on the client. This is useful when you want to optionally accept a payer from the caller but fall back to a generated and funded payer for convenience (e.g. in testing or local development). - -### Installation - -When no explicit payer is given, this plugin requires an airdrop plugin to be installed on the client beforehand (e.g. `rpcAirdrop` or `litesvmAirdrop`) which itself either requires an RPC connection or a LiteSVM instance. - -```ts -import { createClient } from '@solana/kit'; -import { solanaRpcConnection, solanaRpcSubscriptionsConnection, rpcAirdrop } from '@solana/kit-plugin-rpc'; -import { payerOrGeneratedPayer } from '@solana/kit-plugin-payer'; - -// With an explicit payer — no airdrop needed. -const client = await createClient().use(payerOrGeneratedPayer(mySigner)); - -// Without a payer — generates one and airdrops 100 SOL. -const client = await createClient() - .use(solanaRpcConnection('http://127.0.0.1:8899')) - .use(solanaRpcSubscriptionsConnection('ws://127.0.0.1:8900')) - .use(rpcAirdrop()) - // or .use(litesvmConnection()).use(litesvmAirdrop()) - .use(payerOrGeneratedPayer(undefined)); + const client = createClient().use(payer(mySigner)); ``` -### Features - -_See the `payer` plugin for available features_. - -## `payerFromFile` plugin - -This plugin loads a `KeyPairSigner` from a local file and sets it as the `payer` property on the client. - -### Installation - -Note that this plugin requires access to the local filesystem and therefore can only work in Node.js environments. Other environments (like browsers) will throw an error when trying to use this plugin. - -```ts -import { createClient } from '@solana/kit'; -import { payerFromFile } from '@solana/kit-plugin-payer'; - -const client = createClient().use(payerFromFile('path/to/keypair.json')); +The full mapping is: + +| `@solana/kit-plugin-payer` | `@solana/kit-plugin-signer` | +| -------------------------- | ---------------------------------------------------------------------------------------------------- | +| `payer()` | `payer()` (also available: `identity()`, `signer()`) | +| `generatedPayer()` | `generatedPayer()` (also available: `generatedIdentity()`, `generatedSigner()`) | +| `generatedPayerWithSol()` | `generatedPayerWithSol()` (also available: `generatedIdentityWithSol()`, `generatedSignerWithSol()`) | +| `payerFromFile()` | `payerFromFile()` (also available: `identityFromFile()`, `signerFromFile()`) | +| `payerOrGeneratedPayer()` | Use `payer()` and/or `generatedPayerWithSol()` directly | + +### `payerOrGeneratedPayer` migration + +`payerOrGeneratedPayer` has no direct replacement. Use `payer()` for the explicit case and `generatedPayerWithSol()` for the generated case: + +```diff + import { createClient, lamports } from '@solana/kit'; + import { solanaRpcConnection, solanaRpcSubscriptionsConnection, rpcAirdrop } from '@solana/kit-plugin-rpc'; +- import { payerOrGeneratedPayer } from '@solana/kit-plugin-payer'; ++ import { payer, generatedPayerWithSol } from '@solana/kit-plugin-signer'; + + // With an explicit payer. +- const client = await createClient().use(payerOrGeneratedPayer(mySigner)); ++ const client = createClient().use(payer(mySigner)); + + // With a generated payer funded with SOL. + const client = await createClient() + .use(solanaRpcConnection('http://127.0.0.1:8899')) + .use(solanaRpcSubscriptionsConnection('ws://127.0.0.1:8900')) + .use(rpcAirdrop()) +- .use(payerOrGeneratedPayer(undefined)); ++ .use(generatedPayerWithSol(lamports(100_000_000_000n))); ``` - -### Features - -_See the `payer` plugin for available features_. diff --git a/packages/kit-plugin-payer/package.json b/packages/kit-plugin-payer/package.json index 8199260..0b36365 100644 --- a/packages/kit-plugin-payer/package.json +++ b/packages/kit-plugin-payer/package.json @@ -1,7 +1,7 @@ { "name": "@solana/kit-plugin-payer", "version": "0.9.0", - "description": "Payer helpers for Kit clients", + "description": "[DEPRECATED] Payer helpers for Kit clients", "exports": { "types": "./dist/types/index.d.ts", "react-native": "./dist/index.react-native.mjs", diff --git a/packages/kit-plugin-payer/src/index.ts b/packages/kit-plugin-payer/src/index.ts index 0830f5c..b0cc402 100644 --- a/packages/kit-plugin-payer/src/index.ts +++ b/packages/kit-plugin-payer/src/index.ts @@ -16,17 +16,12 @@ import { * * @param payer - The `TransactionSigner` to set as the payer. * - * @example + * @deprecated Use `payer` from `@solana/kit-plugin-signer` instead. * ```ts * import { createClient } from '@solana/kit'; - * import { payer } from '@solana/kit-plugin-payer'; + * import { payer } from '@solana/kit-plugin-signer'; * - * // Install the payer plugin with your signer. * const client = createClient().use(payer(mySigner)); - * - * // Use the payer in your client. - * console.log(client.payer.address); - * setTransactionFeePayerSigner(client.payer, transactionMessage); * ``` */ export function payer(payer: TransactionSigner) { @@ -36,17 +31,12 @@ export function payer(payer: TransactionSigner) { /** * Generates a new `KeyPairSigner` and sets it as the `payer` property on the client. * - * @example + * @deprecated Use `generatedPayer` from `@solana/kit-plugin-signer` instead. * ```ts * import { createClient } from '@solana/kit'; - * import { generatedPayer } from '@solana/kit-plugin-payer'; + * import { generatedPayer } from '@solana/kit-plugin-signer'; * - * // Install the generatedPayer plugin. * const client = await createClient().use(generatedPayer()); - * - * // Use the payer in your client. - * console.log(client.payer.address); - * setTransactionFeePayerSigner(client.payer, transactionMessage); * ``` */ export function generatedPayer() { @@ -60,18 +50,13 @@ export function generatedPayer() { * * @param amount - The amount of lamports to airdrop to the generated payer. * - * @example + * @deprecated Use `generatedPayerWithSol` from `@solana/kit-plugin-signer` instead. * ```ts - * import { createClient } from '@solana/kit'; - * import { generatedPayerWithSol } from '@solana/kit-plugin-payer'; - * - * // Install the generatedPayerWithSol plugin. - * const amount = lamports(10_000_000_000n); // 10 SOL. - * const client = await createClient().use(generatedPayerWithSol(amount)); + * import { createClient, lamports } from '@solana/kit'; + * import { generatedPayerWithSol } from '@solana/kit-plugin-signer'; * - * // Use the payer in your client. - * console.log(client.payer.address); - * setTransactionFeePayerSigner(client.payer, transactionMessage); + * const client = await createClient() + * .use(generatedPayerWithSol(lamports(10_000_000_000n))); * ``` */ export function generatedPayerWithSol(amount: Lamports) { @@ -93,17 +78,12 @@ export function generatedPayerWithSol(amount: Lamports) { * * @param path - The file path to the JSON file containing the keypair bytes. * - * @example + * @deprecated Use `payerFromFile` from `@solana/kit-plugin-signer` instead. * ```ts * import { createClient } from '@solana/kit'; - * import { payerFromFile } from '@solana/kit-plugin-payer'; - * - * // Install the payerFromFile plugin. - * const client = createClient().use(payerFromFile('path/to/keypair.json')); + * import { payerFromFile } from '@solana/kit-plugin-signer'; * - * // Use the payer in your client. - * console.log(client.payer.address); - * setTransactionFeePayerSigner(client.payer, transactionMessage); + * const client = await createClient().use(payerFromFile('path/to/keypair.json')); * ``` */ export function payerFromFile(path: string) { @@ -130,21 +110,21 @@ export function payerFromFile(path: string) { * @param explicitPayer - An optional `TransactionSigner` to use as the payer. * When `undefined`, a new payer is generated and airdropped 100 SOL. * - * @example + * @deprecated Use `payer` and/or `generatedPayerWithSol` from `@solana/kit-plugin-signer` instead. * ```ts - * import { createClient } from '@solana/kit'; + * import { createClient, lamports } from '@solana/kit'; * import { solanaRpcConnection, solanaRpcSubscriptionsConnection, rpcAirdrop } from '@solana/kit-plugin-rpc'; - * import { payerOrGeneratedPayer } from '@solana/kit-plugin-payer'; + * import { payer, generatedPayerWithSol } from '@solana/kit-plugin-signer'; * * // With an explicit payer. - * const client = await createClient().use(payerOrGeneratedPayer(mySigner)); + * const client = createClient().use(payer(mySigner)); * - * // Without a payer — generates one and airdrops 100 SOL. + * // With a generated payer funded with SOL. * const client = await createClient() * .use(solanaRpcConnection('http://127.0.0.1:8899')) * .use(solanaRpcSubscriptionsConnection('ws://127.0.0.1:8900')) * .use(rpcAirdrop()) - * .use(payerOrGeneratedPayer(undefined)); + * .use(generatedPayerWithSol(lamports(100_000_000_000n))); * ``` */ export function payerOrGeneratedPayer(explicitPayer: TransactionSigner | undefined) {