@streamflow/common 7.5.3 → 8.0.0-alpha.p287.25d0c28

package/dist/esm/solana/index.d.ts

@@ -1,5 +1,297 @@
-export * from "./account-filters.js";
-export * from "./instructions.js";
-export * from "./public-key.js";
-export * from "./types.js";
-export * from "./utils.js";
+import * as _solana_web3_js from '@solana/web3.js';
+import { PublicKey, MemcmpFilter, Connection, TransactionInstruction, VersionedTransaction, AccountInfo, BlockhashWithExpiryBlockHeight, Context, Commitment, Keypair, Transaction, RpcResponseAndContext, SimulatedTransactionResponse, SignatureStatus } from '@solana/web3.js';
+import BN from 'bn.js';
+import PQueue from 'p-queue';
+import { Mint } from '@solana/spl-token';
+import { SignerWalletAdapter } from '@solana/wallet-adapter-base';
+
+declare const getFilters: <T extends Record<string, number | PublicKey>>(criteria: T, byteOffsets: Record<keyof T, number>) => MemcmpFilter[];
+
+declare const prepareWrappedAccount: (connection: Connection, senderAddress: PublicKey, amount: BN) => Promise<TransactionInstruction[]>;
+
+type ComputePriceEstimate = (tx: string | (string | PublicKey)[]) => Promise<number>;
+type ComputeLimitEstimate = (tx: VersionedTransaction) => Promise<number>;
+interface ITransactionSolanaExt {
+    computePrice?: number | ComputePriceEstimate;
+    computeLimit?: number | ComputeLimitEstimate | "autoSimulate";
+}
+/**
+ * Acceptable type with resolved values.
+ * Function types may be omitted if passed to destinations that do not support them.
+ */
+type ITransactionSolanaExtResolvedValues = {
+    computePrice?: number | ComputePriceEstimate;
+    computeLimit?: number | ComputeLimitEstimate;
+};
+type KeysNotOfA<T, ToExclude> = Pick<T, Exclude<keyof T, keyof ToExclude>>;
+type ITransactionSolanaExtResolved<T extends ITransactionSolanaExt = ITransactionSolanaExt> = {
+    [AK in keyof KeysNotOfA<T, ITransactionSolanaExt>]: T[AK];
+} & ITransactionSolanaExtResolvedValues;
+interface IInteractSolanaExt extends ITransactionSolanaExt {
+    invoker: {
+        publicKey: string | PublicKey | null;
+    };
+}
+interface Account {
+    pubkey: PublicKey;
+    account: AccountInfo<Buffer>;
+}
+interface CheckAssociatedTokenAccountsData {
+    sender: PublicKey;
+    recipient: PublicKey;
+    partner: PublicKey;
+    streamflowTreasury: PublicKey;
+    mint: PublicKey;
+}
+interface AtaParams {
+    mint: PublicKey;
+    owner: PublicKey;
+    programId?: PublicKey;
+}
+interface ConfirmationParams {
+    hash: BlockhashWithExpiryBlockHeight;
+    context: Context;
+    commitment?: Commitment;
+}
+interface ThrottleParams {
+    sendRate?: number;
+    sendThrottler?: PQueue;
+    waitBeforeConfirming?: number | undefined;
+}
+interface TransactionExecutionParams extends ThrottleParams {
+    skipSimulation?: boolean;
+}
+interface IProgramAccount<T> {
+    publicKey: PublicKey;
+    account: T;
+}
+declare class TransactionFailedError extends Error {
+    constructor(m: string);
+}
+
+declare const buildSendThrottler: (sendRate: number, sendInterval?: number) => PQueue;
+/**
+ * Wrapper function for Solana web3 getProgramAccounts with slightly better call interface
+ * @param {Connection} connection - Solana web3 connection object.
+ * @param {PublicKey} wallet - PublicKey to compare against.
+ * @param {number} offset - Offset of bits of the PublicKey in the account binary.
+ * @param {PublicKey} programId - Solana program ID.
+ * @return {Promise<Account[]>} - Array of resulting accounts.
+ */
+declare function getProgramAccounts(connection: Connection, wallet: PublicKey, offset: number, programId: PublicKey): Promise<Account[]>;
+/**
+ * Utility function to check if the transaction initiator is a Wallet object
+ * @param {Keypair | SignerWalletAdapter} walletOrKeypair - Wallet or Keypair in question
+ * @return {boolean} - Returns true if parameter is a Wallet.
+ */
+declare function isSignerWallet(walletOrKeypair: Keypair | SignerWalletAdapter): walletOrKeypair is SignerWalletAdapter;
+/**
+ * Utility function to check if the transaction initiator a Keypair object, tries to mitigate version mismatch issues
+ * @param walletOrKeypair {Keypair | SignerWalletAdapter} walletOrKeypair - Wallet or Keypair in question
+ * @returns {boolean} - Returns true if parameter is a Keypair.
+ */
+declare function isSignerKeypair(walletOrKeypair: Keypair | SignerWalletAdapter): walletOrKeypair is Keypair;
+/**
+ * Utility function to check whether given transaction is Versioned
+ * @param tx {Transaction | VersionedTransaction} - Transaction to check
+ * @returns {boolean} - Returns true if transaction is Versioned.
+ */
+declare function isTransactionVersioned(tx: Transaction | VersionedTransaction): tx is VersionedTransaction;
+/**
+ * Creates a Transaction with given instructions and optionally signs it.
+ * @param connection - Solana client connection
+ * @param ixs - Instructions to add to the Transaction
+ * @param payer - PublicKey of payer
+ * @param commitment - optional Commitment that will be used to fetch latest blockhash
+ * @param partialSigners - optional signers that will be used to partially sign a Transaction
+ * @returns Transaction and Blockhash
+ */
+declare function prepareTransaction(connection: Connection, ixs: TransactionInstruction[], payer: PublicKey | undefined | null, commitment?: Commitment, partialSigners?: (Keypair | undefined)[]): Promise<{
+    tx: VersionedTransaction;
+    hash: BlockhashWithExpiryBlockHeight;
+    context: Context;
+}>;
+declare function createVersionedTransaction(ixs: TransactionInstruction[], payer: PublicKey | undefined | null, recentBlockhash: BlockhashWithExpiryBlockHeight["blockhash"], partialSigners?: (Keypair | undefined)[]): VersionedTransaction;
+declare function signTransaction<T extends Transaction | VersionedTransaction>(invoker: Keypair | SignerWalletAdapter, tx: T): Promise<T>;
+/**
+ * Signs, sends and confirms Transaction
+ * @param connection - Solana client connection
+ * @param invoker - Keypair used as signer
+ * @param tx - Transaction instance
+ * @param confirmationParams - Confirmation Params that will be used for execution
+ * @param transactionExecutionParams - rate or throttler instance to throttle TX sending - to not spam the blockchain too much and solana execution params (eg. skipSimulation)
+ * @returns Transaction signature
+ */
+declare function signAndExecuteTransaction(connection: Connection, invoker: Keypair | SignerWalletAdapter, tx: Transaction | VersionedTransaction, confirmationParams: ConfirmationParams, transactionExecutionParams: TransactionExecutionParams): Promise<string>;
+/**
+ * Sends and confirms Transaction
+ * Uses custom confirmation logic that:
+ * - simulates tx before sending separately
+ * - sends transaction without preFlight checks but with some valuable flags https://twitter.com/jordaaash/status/1774892862049800524?s=46&t=bhZ10V0r7IX5Lk5kKzxfGw
+ * - rebroadcasts a tx every 500 ms
+ * - after broadcasting check whether tx has executed once
+ * - catch errors for every actionable item, throw only the ones that signal that tx has failed
+ * - otherwise there is a chance of marking a landed tx as failed if it was broadcasted at least once
+ * @param connection - Solana client connection
+ * @param tx - Transaction instance
+ * @param confirmationParams - Confirmation Params that will be used for execution
+ * @param transactionExecutionParams - rate or throttler instance to throttle TX sending - to not spam the blockchain too much and solana execution params (eg. skipSimulation)
+ * @returns Transaction signature
+ */
+declare function executeTransaction(connection: Connection, tx: Transaction | VersionedTransaction, confirmationParams: ConfirmationParams, transactionExecutionParams: TransactionExecutionParams): Promise<string>;
+/**
+ * Launches a PromisePool with all transaction being executed at the same time, allows to throttle all TXs through one Queue
+ * @param connection - Solana client connection
+ * @param txs - Transactions
+ * @param confirmationParams - Confirmation Params that will be used for execution
+ * @param throttleParams - rate or throttler instance to throttle TX sending - to not spam the blockchain too much
+ * @param throttleParams.sendRate - rate
+ * @param throttleParams.sendThrottler -  throttler instance
+ * @returns Raw Promise Results - should be handled by the consumer and unwrapped accordingly
+ */
+declare function executeMultipleTransactions(connection: Connection, txs: (Transaction | VersionedTransaction)[], confirmationParams: ConfirmationParams, { sendRate, sendThrottler, ...throttlingParams }: ThrottleParams): Promise<PromiseSettledResult<string>[]>;
+/**
+ * Sends and confirm transaction in a loop, constantly re-broadcsting the tx until Blockheight expires.
+ * - we add additional 30 bocks to account for validators in an PRC pool divergence
+ * @param connection - Solana client connection
+ * @param tx - Transaction instance
+ * @param confirmationParams - Confirmation Params that will be used for execution
+ * @param confirmationParams.hash - blockhash information, the same hash should be used in the Transaction
+ * @param confirmationParams.context - context at which blockhash has been retrieve
+ * @param confirmationParams.commitment - optional commitment that will be used for simulation and confirmation
+ * @param throttleParams - rate or throttler instance to throttle TX sending - to not spam the blockchain too much
+ * @param throttleParams.sendRate - rate
+ * @param throttleParams.sendThrottler -  throttler instance
+ */
+declare function sendAndConfirmTransaction(connection: Connection, tx: Transaction | VersionedTransaction, { hash, context, commitment }: ConfirmationParams, { sendRate, sendThrottler, waitBeforeConfirming }: ThrottleParams): Promise<string>;
+declare function simulateTransaction(connection: Connection, tx: Transaction | VersionedTransaction): Promise<RpcResponseAndContext<SimulatedTransactionResponse>>;
+/**
+ * Confirms and validates transaction success once
+ * @param connection - Solana client connection
+ * @param signature - Transaction signature
+ * @param ignoreError - return status even if tx failed
+ * @returns Transaction Status
+ */
+declare function confirmAndEnsureTransaction(connection: Connection, signature: string, ignoreError?: boolean): Promise<SignatureStatus | null>;
+/**
+ * Shorthand call signature for getAssociatedTokenAddress, with allowance for address to be offCurve
+ * @param {PublicKey} mint - SPL token Mint address.
+ * @param {PublicKey} owner - Owner of the Associated Token Address
+ * @param {PublicKey} programId - Program ID of the mint
+ * @return {Promise<PublicKey>} - Associated Token Address
+ */
+declare function ata(mint: PublicKey, owner: PublicKey, programId?: PublicKey): Promise<PublicKey>;
+/**
+ * Function that checks whether ATA exists for each provided owner
+ * @param connection - Solana client connection
+ * @param paramsBatch - Array of Params for each ATA account: {mint, owner}
+ * @returns Array of boolean where each member corresponds to an owner
+ */
+declare function ataBatchExist(connection: Connection, paramsBatch: AtaParams[]): Promise<boolean[]>;
+declare function enrichAtaParams(connection: Connection, paramsBatch: AtaParams[]): Promise<AtaParams[]>;
+/**
+ * Generates a Transaction to create ATA for an array of owners
+ * @param connection - Solana client connection
+ * @param payer - Transaction invoker, should be a signer
+ * @param paramsBatch - Array of Params for an each ATA account: {mint, owner}
+ * @param commitment - optional commitment that will be used to fetch Blockhash
+ * @returns Unsigned Transaction with create ATA instructions
+ */
+declare function generateCreateAtaBatchTx(connection: Connection, payer: PublicKey, paramsBatch: AtaParams[], commitment?: Commitment): Promise<{
+    tx: VersionedTransaction;
+    hash: BlockhashWithExpiryBlockHeight;
+    context: Context;
+}>;
+/**
+ * Creates ATA for an array of owners
+ * @param connection - Solana client connection
+ * @param invoker - Transaction invoker and payer
+ * @param paramsBatch - Array of Params for an each ATA account: {mint, owner}
+ * @param commitment - optional commitment that will be used to fetch Blockhash
+ * @param rate - throttle rate for tx sending
+ * @returns Transaction signature
+ */
+declare function createAtaBatch(connection: Connection, invoker: Keypair | SignerWalletAdapter, paramsBatch: AtaParams[], commitment?: Commitment, rate?: number): Promise<string>;
+/**
+ * Utility function that checks whether associated token accounts exist and return instructions to populate them if not
+ * @param connection - Solana client connection
+ * @param owners - Array of ATA owners
+ * @param mint - Mint for which ATA will be checked
+ * @param invoker - Transaction invoker and payer
+ * @param programId - Program ID of the Mint
+ * @returns Array of Transaction Instructions that should be added to a transaction
+ */
+declare function checkOrCreateAtaBatch(connection: Connection, owners: PublicKey[], mint: PublicKey, invoker: SignerWalletAdapter | Keypair, programId?: PublicKey): Promise<TransactionInstruction[]>;
+/**
+ * Create Base instructions for Solana
+ * - sets compute price if `computePrice` is provided. If `computePrice` is a function, it will be ignored (the value must be resolved before calling this function).
+ * - sets compute limit if `computeLimit` is provided. If `computeLimit` is a function, it will be ignored (the value must be resolved before calling this function).
+ */
+declare function prepareBaseInstructions(connection: Connection, { computePrice, computeLimit }: ITransactionSolanaExt): TransactionInstruction[];
+/**
+ * Retrieve information about a mint and its program ID, support all Token Programs.
+ *
+ * @param connection Connection to use
+ * @param address    Mint account
+ * @param commitment Desired level of commitment for querying the state
+ *
+ * @return Mint information
+ */
+declare function getMintAndProgram(connection: Connection, address: PublicKey, commitment?: Commitment): Promise<{
+    mint: Mint;
+    tokenProgramId: PublicKey;
+}>;
+/**
+ * Split fetching of Multiple Accounts Info into batches of 100
+ * as the maximum number of accounts that can be fetched in a single call is 100
+ *
+ * @param connection Connection to use
+ * @param pubKeys Array of public keys to fetch account info for
+ * @param commitment Desired level of commitment for querying the state
+ *
+ * @return Array of AccountInfo objects
+ */
+declare function getMultipleAccountsInfoBatched(connection: Connection, pubKeys: PublicKey[], commitment?: Commitment): Promise<(AccountInfo<Buffer> | null)[]>;
+
+declare function deserializeRawTransaction(serializedTx: string): {
+    type: string;
+    transaction: Transaction;
+    accounts: PublicKey[];
+    writableAccounts: PublicKey[];
+} | {
+    type: string;
+    transaction: VersionedTransaction;
+    accounts: PublicKey[];
+    writableAccounts: PublicKey[];
+};
+declare const resolveTransactionAccounts: (tx: VersionedTransaction | Transaction) => {
+    type: string;
+    transaction: Transaction;
+    accounts: PublicKey[];
+    writableAccounts: PublicKey[];
+} | {
+    type: string;
+    transaction: VersionedTransaction;
+    accounts: PublicKey[];
+    writableAccounts: PublicKey[];
+};
+
+declare const createTestTransaction: (ixs: Parameters<typeof createVersionedTransaction>[0], payer: Parameters<typeof createVersionedTransaction>[1], recentBlockhash?: Parameters<typeof createVersionedTransaction>[2], partialSigners?: Parameters<typeof createVersionedTransaction>[3]) => _solana_web3_js.VersionedTransaction;
+declare function estimateComputeUnitPrice(estimate: ComputePriceEstimate, testTx: ReturnType<typeof createTestTransaction>): Promise<number>;
+declare function createAndEstimateTransaction<ParamsT extends ITransactionSolanaExtResolved<IInteractSolanaExt>, CreateFn extends (extParams: ParamsT) => Promise<TransactionInstruction[]>>(createFn: CreateFn, extParams: ParamsT): Promise<Awaited<ReturnType<CreateFn>>>;
+declare function createAndEstimateTransaction<ParamsT extends ITransactionSolanaExtResolved<IInteractSolanaExt>, CreateFn extends (extParams: ParamsT) => Promise<any>>(createFn: CreateFn, extParams: ParamsT, select: (result: Awaited<ReturnType<CreateFn>>) => TransactionInstruction[]): Promise<Awaited<ReturnType<CreateFn>>>;
+
+/**
+ * Converts a string or PublicKey to a PublicKey object.
+ * @param address - The input address as a string or PublicKey.
+ * @returns The PublicKey object.
+ */
+declare const pk: (address: string | PublicKey) => PublicKey;
+
+type UnwrapAutoSimulate<T extends IInteractSolanaExt = IInteractSolanaExt> = Omit<T, "computeLimit"> & {
+    skipSimulation: boolean;
+    computeLimit?: ITransactionSolanaExtResolved["computeLimit"];
+};
+declare const unwrapExecutionParams: <T extends IInteractSolanaExt>({ computeLimit, ...rest }: T, connection: Connection) => UnwrapAutoSimulate<T>;
+
+export { type Account, type AtaParams, type CheckAssociatedTokenAccountsData, type ComputeLimitEstimate, type ComputePriceEstimate, type ConfirmationParams, type IInteractSolanaExt, type IProgramAccount, type ITransactionSolanaExt, type ITransactionSolanaExtResolved, type ThrottleParams, type TransactionExecutionParams, TransactionFailedError, ata, ataBatchExist, buildSendThrottler, checkOrCreateAtaBatch, confirmAndEnsureTransaction, createAndEstimateTransaction, createAtaBatch, createVersionedTransaction, deserializeRawTransaction, enrichAtaParams, estimateComputeUnitPrice, executeMultipleTransactions, executeTransaction, generateCreateAtaBatchTx, getFilters, getMintAndProgram, getMultipleAccountsInfoBatched, getProgramAccounts, isSignerKeypair, isSignerWallet, isTransactionVersioned, pk, prepareBaseInstructions, prepareTransaction, prepareWrappedAccount, resolveTransactionAccounts, sendAndConfirmTransaction, signAndExecuteTransaction, signTransaction, simulateTransaction, unwrapExecutionParams };