gill/dist/index.d.mts

a modern javascript/typescript client library for interacting with the Solana blockchain

import { FullySignedTransaction, TransactionWithBlockhashLifetime, CompilableTransactionMessage, Signature, Commitment, Rpc, SendTransactionApi, GetEpochInfoApi, GetSignatureStatusesApi, RpcSubscriptions, SignatureNotificationsApi, SlotNotificationsApi, Transaction, SimulateTransactionApi, MainnetUrl, DevnetUrl, TestnetUrl, createSolanaRpc, createSolanaRpcSubscriptions, RpcFromTransport, SolanaRpcApiFromTransport, RpcTransportFromClusterUrl, SolanaRpcSubscriptionsApi, Address, TransactionSigner, TransactionVersion, ITransactionMessageWithFeePayerSigner, ITransactionMessageWithFeePayer, TransactionMessageWithBlockhashLifetime, GetLatestBlockhashApi, TransactionMessage, KeyPairSigner, Base64EncodedWireTransaction, GetSignaturesForAddressApi, BaseTransactionMessage } from '@solana/kit';
export * from '@solana/kit';
import { S as Simplify, C as CreateTransactionInput, F as FullTransaction } from './index-x1jMRy1Z.mjs';
import { waitForRecentTransactionConfirmation } from '@solana/transaction-confirmation';

interface SendAndConfirmTransactionWithBlockhashLifetimeConfig extends SendTransactionBaseConfig, SendTransactionConfigWithoutEncoding {
    confirmRecentTransaction: (config: Omit<Parameters<typeof waitForRecentTransactionConfirmation>[0], "getBlockHeightExceedencePromise" | "getRecentSignatureConfirmationPromise">) => Promise<void>;
    transaction: FullySignedTransaction & TransactionWithBlockhashLifetime;
}
interface SendTransactionBaseConfig extends SendTransactionConfigWithoutEncoding {
    abortSignal?: AbortSignal;
    commitment: Commitment;
    rpc: Rpc<SendTransactionApi>;
    transaction: FullySignedTransaction;
}
type SendTransactionConfigWithoutEncoding = Omit<NonNullable<Parameters<SendTransactionApi["sendTransaction"]>[1]>, "encoding">;
type SendAndConfirmTransactionWithSignersFunction = (transaction: (FullySignedTransaction & TransactionWithBlockhashLifetime) | CompilableTransactionMessage, config?: Omit<SendAndConfirmTransactionWithBlockhashLifetimeConfig, "confirmRecentTransaction" | "rpc" | "transaction">) => Promise<Signature>;
type SendAndConfirmTransactionWithSignersFactoryConfig<TCluster> = {
    rpc: Rpc<GetEpochInfoApi & GetSignatureStatusesApi & SendTransactionApi> & {
        "~cluster"?: TCluster;
    };
    rpcSubscriptions: RpcSubscriptions<SignatureNotificationsApi & SlotNotificationsApi> & {
        "~cluster"?: TCluster;
    };
};
declare function sendAndConfirmTransactionWithSignersFactory({ rpc, rpcSubscriptions, }: SendAndConfirmTransactionWithSignersFactoryConfig<"devnet">): SendAndConfirmTransactionWithSignersFunction;
declare function sendAndConfirmTransactionWithSignersFactory({ rpc, rpcSubscriptions, }: SendAndConfirmTransactionWithSignersFactoryConfig<"testnet">): SendAndConfirmTransactionWithSignersFunction;
declare function sendAndConfirmTransactionWithSignersFactory({ rpc, rpcSubscriptions, }: SendAndConfirmTransactionWithSignersFactoryConfig<"mainnet">): SendAndConfirmTransactionWithSignersFunction;
declare function sendAndConfirmTransactionWithSignersFactory({ rpc, rpcSubscriptions, }: SendAndConfirmTransactionWithSignersFactoryConfig<"localnet">): SendAndConfirmTransactionWithSignersFunction;

type SimulateTransactionFunction = (transaction: Transaction | CompilableTransactionMessage, config?: Simplify<Omit<Parameters<SimulateTransactionApi["simulateTransaction"]>[1], "encoding" | "sigVerify">>) => Promise<ReturnType<SimulateTransactionApi["simulateTransaction"]>>;
type SimulateTransactionFactoryConfig<TCluster> = {
    rpc: Rpc<SimulateTransactionApi> & {
        "~cluster"?: TCluster;
    };
};
declare function simulateTransactionFactory({ rpc, }: SimulateTransactionFactoryConfig<"devnet">): SimulateTransactionFunction;
declare function simulateTransactionFactory({ rpc, }: SimulateTransactionFactoryConfig<"testnet">): SimulateTransactionFunction;
declare function simulateTransactionFactory({ rpc, }: SimulateTransactionFactoryConfig<"mainnet">): SimulateTransactionFunction;
declare function simulateTransactionFactory({ rpc, }: SimulateTransactionFactoryConfig<"localnet">): SimulateTransactionFunction;

/** Solana cluster moniker */
type SolanaClusterMoniker = "mainnet" | "devnet" | "testnet" | "localnet";
type LocalnetUrl = string & {
    "~cluster": "localnet";
};
type GenericUrl = string & {};
type ModifiedClusterUrl = MainnetUrl | DevnetUrl | TestnetUrl | LocalnetUrl | GenericUrl;
type SolanaClientUrlOrMoniker = SolanaClusterMoniker | URL | ModifiedClusterUrl;
type CreateSolanaClientArgs<TClusterUrl extends SolanaClientUrlOrMoniker = GenericUrl> = {
    /** Full RPC URL (for a private RPC endpoint) or the Solana moniker (for a public RPC endpoint) */
    urlOrMoniker: SolanaClientUrlOrMoniker | TClusterUrl;
    /** Configuration used to create the `rpc` client */
    rpcConfig?: Parameters<typeof createSolanaRpc>[1] & {
        port?: number;
    };
    /** Configuration used to create the `rpcSubscriptions` client */
    rpcSubscriptionsConfig?: Parameters<typeof createSolanaRpcSubscriptions>[1] & {
        port?: number;
    };
};
type SolanaClient<TClusterUrl extends ModifiedClusterUrl | string = string> = {
    /** Used to make RPC calls to your RPC provider */
    rpc: RpcFromTransport<SolanaRpcApiFromTransport<RpcTransportFromClusterUrl<TClusterUrl>>, RpcTransportFromClusterUrl<TClusterUrl>>;
    /** Used to make RPC websocket calls to your RPC provider */
    rpcSubscriptions: RpcSubscriptions<SolanaRpcSubscriptionsApi> & TClusterUrl;
    /**
     * Send and confirm a transaction to the network (including signing with available Signers)
     *
     * Default commitment level: `confirmed`
     */
    sendAndConfirmTransaction: SendAndConfirmTransactionWithSignersFunction;
    /**
     * Simulate a transaction on the network
     */
    simulateTransaction: SimulateTransactionFunction;
};

type ExplorerLinkAccount = {
    address: string;
};
type ExplorerLinkTransaction = {
    transaction: string;
};
type ExplorerLinkBlock = {
    block: string;
};
/**
 * @param cluster - Default: `mainnet`
 */
type GetExplorerLinkArgs = {
    cluster?: SolanaClusterMoniker | "mainnet-beta" | "localhost";
} & (ExplorerLinkAccount | ExplorerLinkTransaction | ExplorerLinkBlock | {});

/**
 *
 */
type LogLevel = "debug" | "info" | "warn" | "error";
declare global {
    /**
     * Whether or not to enable debug mode. When enabled, default log level of `info`
     */
    var __GILL_DEBUG__: boolean | undefined;
    /**
     * Set the a desired level of logs to be output in the application
     *
     * - Default: `info`
     * - Options: `debug` | `info` | `warn` | `error`
     */
    var __GILL_DEBUG_LEVEL__: LogLevel | undefined;
}
/**
 * Check if the `gill` debug logger is enabled or not
 */
declare const isDebugEnabled: () => boolean;
/**
 * Log debug messages based on the desired application's logging level.
 *
 * @param message - the message contents to be logged
 * @param level - default: `info` (see: {@link GILL_LOG_LEVELS})
 * @param prefix - default: `[GILL]`
 *
 * To enable gill's debug logger, set any of the following to `true`:
 * - `process.env.GILL_DEBUG`
 * - `global.__GILL_DEBUG__`
 * - `window.__GILL_DEBUG__`
 *
 * To set a desired level of logs to be output in the application, set the value of one of the following:
 * - `process.env.GILL_DEBUG_LEVEL`
 * - `global.__GILL_DEBUG_LEVEL__`
 * - `window.__GILL_DEBUG_LEVEL__`
 */
declare function debug(message: unknown, level?: LogLevel, prefix?: string): void;

/** 1 billion lamports per SOL */
declare const LAMPORTS_PER_SOL = 1000000000;
/**
 * Genesis hash for Solana network clusters
 */
declare const GENESIS_HASH: {
    mainnet: string;
    devnet: string;
    testnet: string;
};

/**
 * Determine the Solana moniker from its genesis hash
 *
 * If the hash is NOT known, returns `unknown`
 */
declare function getMonikerFromGenesisHash(hash: string): SolanaClusterMoniker | "unknown";
declare function checkedAddress<TAddress extends string = string>(input: Address<TAddress> | TransactionSigner<TAddress>): Address<TAddress>;
declare function checkedTransactionSigner<TAddress extends string = string>(input: Address<TAddress> | TransactionSigner<TAddress>): TransactionSigner<TAddress>;
/**
 * Convert a lamport number to the human readable string of a SOL value
 */
declare function lamportsToSol(lamports: bigint | number): string;

declare function localnet(putativeString: string): LocalnetUrl;
/**
 * Get a public Solana RPC endpoint for a cluster based on its moniker
 *
 * Note: These RPC URLs are rate limited and not suitable for production applications.
 */
declare function getPublicSolanaRpcUrl(cluster: SolanaClusterMoniker | "mainnet-beta" | "localhost"): ModifiedClusterUrl;

/**
 * Craft a Solana Explorer link on any cluster
 */
declare function getExplorerLink(props?: GetExplorerLinkArgs): string;

/**
 * Simple interface for creating a Solana transaction
 */
declare function createTransaction<TVersion extends TransactionVersion, TFeePayer extends TransactionSigner>(props: CreateTransactionInput<TVersion, TFeePayer>): FullTransaction<TVersion, ITransactionMessageWithFeePayerSigner>;
declare function createTransaction<TVersion extends TransactionVersion, TFeePayer extends Address>(props: CreateTransactionInput<TVersion, TFeePayer>): FullTransaction<TVersion, ITransactionMessageWithFeePayer>;
declare function createTransaction<TVersion extends TransactionVersion, TFeePayer extends TransactionSigner, TLifetimeConstraint extends TransactionMessageWithBlockhashLifetime["lifetimeConstraint"]>(props: CreateTransactionInput<TVersion, TFeePayer, TLifetimeConstraint>): Simplify<FullTransaction<TVersion, ITransactionMessageWithFeePayerSigner, TransactionMessageWithBlockhashLifetime>>;
declare function createTransaction<TVersion extends TransactionVersion, TFeePayer extends Address, TLifetimeConstraint extends TransactionMessageWithBlockhashLifetime["lifetimeConstraint"]>(props: CreateTransactionInput<TVersion, TFeePayer, TLifetimeConstraint>): Simplify<FullTransaction<TVersion, ITransactionMessageWithFeePayer, TransactionMessageWithBlockhashLifetime>>;
declare function createTransaction<TVersion extends TransactionVersion, TFeePayer extends Address | TransactionSigner, TLifetimeConstraint extends TransactionMessageWithBlockhashLifetime["lifetimeConstraint"]>(props: CreateTransactionInput<TVersion, TFeePayer, TLifetimeConstraint>): Simplify<FullTransaction<TVersion, ITransactionMessageWithFeePayer, TransactionMessageWithBlockhashLifetime>>;

type PrepareCompilableTransactionMessage = CompilableTransactionMessage | (ITransactionMessageWithFeePayer & TransactionMessage);
type PrepareTransactionConfig<TMessage extends PrepareCompilableTransactionMessage> = {
    /**
     * Transaction to prepare for sending to the blockchain
     */
    transaction: TMessage;
    /**
     * RPC client capable of simulating transactions and getting the latest blockhash
     **/
    rpc: Rpc<GetLatestBlockhashApi & SimulateTransactionApi>;
    /**
     * Multiplier applied to the simulated compute unit value obtained from simulation
     *
     * Default: `1.1`
     **/
    computeUnitLimitMultiplier?: number;
    /**
     * Whether or not you wish to force reset the compute unit limit value (if one is already set)
     * using the simulation response and `computeUnitLimitMultiplier`
     **/
    computeUnitLimitReset?: boolean;
    /**
     * Whether or not you wish to force reset the latest blockhash (if one is already set)
     *
     * Default: `true`
     **/
    blockhashReset?: boolean;
};
/**
 * Prepare a Transaction to be signed and sent to the network. Including:
 * - setting a compute unit limit (if not already set)
 * - fetching the latest blockhash (if not already set)
 * - (optional) simulating and resetting the compute unit limit
 * - (optional) resetting latest blockhash to the most recent
 */
declare function prepareTransaction<TMessage extends PrepareCompilableTransactionMessage>(config: PrepareTransactionConfig<TMessage>): Promise<TMessage & TransactionMessageWithBlockhashLifetime>;

/**
 * Create a Solana `rpc` and `rpcSubscriptions` client
 */
declare function createSolanaClient(props: Omit<CreateSolanaClientArgs<MainnetUrl | "mainnet">, "urlOrMoniker"> & {
    urlOrMoniker: "mainnet";
}): SolanaClient<MainnetUrl>;
declare function createSolanaClient(props: Omit<CreateSolanaClientArgs<DevnetUrl | "devnet">, "urlOrMoniker"> & {
    urlOrMoniker: "devnet";
}): SolanaClient<DevnetUrl>;
declare function createSolanaClient(props: Omit<CreateSolanaClientArgs<TestnetUrl | "testnet">, "urlOrMoniker"> & {
    urlOrMoniker: "testnet";
}): SolanaClient<TestnetUrl>;
declare function createSolanaClient(props: Omit<CreateSolanaClientArgs<LocalnetUrl | "localnet">, "urlOrMoniker"> & {
    urlOrMoniker: "localnet";
}): SolanaClient<LocalnetUrl>;
declare function createSolanaClient<TClusterUrl extends ModifiedClusterUrl>(props: CreateSolanaClientArgs<TClusterUrl>): SolanaClient<TClusterUrl>;

/**
 * Calculate the total rent needed for to create an account, with or without extra data stored in it
 */
declare function getMinimumBalanceForRentExemption(space?: bigint | number): bigint;

declare function assertKeyPairIsExtractable(keyPair: CryptoKeyPair): asserts keyPair is ExtractableCryptoKeyPair;
type Extractable = {
    "~extractable": true;
};
type ExtractableCryptoKeyPair = CryptoKeyPair & Extractable;
type ExtractableKeyPairSigner = KeyPairSigner & Extractable;
/**
 * Generates an extractable Ed25519 `CryptoKeyPair` capable of signing messages and transactions
 * */
declare function generateExtractableKeyPair(): Promise<ExtractableCryptoKeyPair>;
/**
 * Generates an extractable signer capable of signing messages and transactions using a Crypto KeyPair.
 * */
declare function generateExtractableKeyPairSigner(): Promise<ExtractableKeyPairSigner>;
/**
 * Extracts the raw key material from an extractable Ed25519 CryptoKeyPair.
 *
 * @remarks
 * - Requires a keypair generated with extractable=true. See {@link generateExtractableKeyPair}.
 * - The extracted bytes can be used to reconstruct the `CryptoKeyPair` with {@link createKeyPairFromBytes}.
 *
 * @param keypair An extractable Ed25519 `CryptoKeyPair`
 * @returns Raw key bytes as `Uint8Array`
 */
declare function extractBytesFromKeyPair(keypair: ExtractableCryptoKeyPair | CryptoKeyPair): Promise<Uint8Array>;
/**
 * Extracts the raw key material from an extractable Ed25519 KeyPairSigner.
 *
 * @remarks
 * - Requires a keypair generated with extractable=true. See {@link generateExtractableKeyPairSigner}.
 * - The extracted bytes can be used to reconstruct the `CryptoKeyPair` with {@link createKeyPairSignerFromBytes}.
 *
 * @param keypairSigner An extractable Ed25519 `KeyPairSigner`
 * @returns Raw key bytes as `Uint8Array`
 */
declare function extractBytesFromKeyPairSigner(keypairSigner: ExtractableKeyPairSigner | KeyPairSigner): Promise<Uint8Array>;

/**
 * Create a `CryptoKeyPair` from as base58 encoded secret key
 */
declare function createKeypairFromBase58(punitiveSecretKey: string): Promise<CryptoKeyPair>;
/**
 * Create a `KeyPairSigner` from as base58 encoded secret key
 */
declare function createKeypairSignerFromBase58(punitiveSecretKey: string): Promise<KeyPairSigner>;

/**
 * Compile a transaction to a base64 string
 *
 * Note: This will NOT attempt to sign the transaction,
 * so it will be missing `signatures` from any of the attached Signers
 *
 * Use {@link transactionToBase64WithSignatures} sign and base64 encode
 */
declare function transactionToBase64(tx: CompilableTransactionMessage | Transaction): Base64EncodedWireTransaction;
/**
 * Compile a transaction to a base64 string and sign it with all attached Signers
 *
 * See also {@link partiallySignTransactionMessageWithSigners}
 */
declare function transactionToBase64WithSigners(tx: CompilableTransactionMessage | Transaction): Promise<Base64EncodedWireTransaction>;

/**
 * Convert a base64 encoded transaction string into compiled transaction
 *
 * Use {@link transactionToBase64} or {@link transactionToBase64WithSigners} to create the base64 encoded transaction string
 */
declare function transactionFromBase64(base64EncodedTransaction: string): Transaction;

type GetOldestSignatureForAddressRpc<TCluster> = Rpc<GetSignaturesForAddressApi> & {
    "~cluster"?: TCluster;
};
type GetOldestSignatureForAddressConfig = Simplify<Parameters<GetSignaturesForAddressApi["getSignaturesForAddress"]>[1]> & {
    abortSignal?: AbortSignal;
};
/**
 * Get the oldest signature for the provided `address`
 */
declare function getOldestSignatureForAddress<TCluster>(rpc: GetOldestSignatureForAddressRpc<TCluster>, address: Address, config?: GetOldestSignatureForAddressConfig): Promise<ReturnType<GetSignaturesForAddressApi["getSignaturesForAddress"]>[0]>;

/**
 * Insert a single of reference key {@link Address} into a transaction message
 *
 * Use {@link getOldestSignatureForAddress} to locate the oldest signature for a reference key's address
 *
 * Note: The `transaction` must have at least one non-memo instruction.
 */
declare function insertReferenceKeyToTransactionMessage<TTransaction extends BaseTransactionMessage>(reference: Address, transaction: TTransaction): TTransaction;
/**
 * Insert multiple reference key {@link Address | Addresses} into a transaction message
 *
 * Use {@link getOldestSignatureForAddress} to locate the oldest signature for a reference key's address
 *
 * Note: The `transaction` must have at least one non-memo instruction.
 */
declare function insertReferenceKeysToTransactionMessage<TTransaction extends BaseTransactionMessage>(references: Address[], transaction: TTransaction): TTransaction;

/**
 * Codama dependency map to utilize gill imports
 */
declare const GILL_EXTERNAL_MODULE_MAP: Record<string, string>;
/**
 * Create a Codama CLI configuration to generate a program client from an IDL.
 * Normally saved to `codama.js`.
 *
 * @example
 * ```ts
 * import { createCodamaConfig } from "gill";
 *
 * export default createCodamaConfig({
 *  idl: "program/idl.json",
 *  clientJs: "clients/js/src/generated",
 *  // clientRust: "clients/rust/src/generated",
 * });
 * ```
 */
declare function createCodamaConfig({ idl, clientJs, clientRust, dependencyMap, }: {
    idl: string;
    clientJs: string;
    clientRust?: string;
    dependencyMap?: Record<string, string>;
}): {
    idl: string;
    scripts: {
        js: {
            args: (string | {
                dependencyMap: Record<string, string>;
            })[];
            from: string;
        };
        rust: {
            from: string;
            args: (string | {
                crateFolder: string;
                formatCode: boolean;
            })[];
        } | undefined;
    };
};

export { type CreateSolanaClientArgs, CreateTransactionInput, FullTransaction, GENESIS_HASH, GILL_EXTERNAL_MODULE_MAP, type GenericUrl, type GetExplorerLinkArgs, LAMPORTS_PER_SOL, type LocalnetUrl, type ModifiedClusterUrl, type PrepareTransactionConfig, type SendAndConfirmTransactionWithSignersFunction, Simplify, type SimulateTransactionFunction, type SolanaClient, type SolanaClientUrlOrMoniker, type SolanaClusterMoniker, assertKeyPairIsExtractable, checkedAddress, checkedTransactionSigner, createCodamaConfig, createKeypairFromBase58, createKeypairSignerFromBase58, createSolanaClient, createTransaction, debug, extractBytesFromKeyPair, extractBytesFromKeyPairSigner, generateExtractableKeyPair, generateExtractableKeyPairSigner, getExplorerLink, getMinimumBalanceForRentExemption, getMonikerFromGenesisHash, getOldestSignatureForAddress, getPublicSolanaRpcUrl, insertReferenceKeyToTransactionMessage, insertReferenceKeysToTransactionMessage, isDebugEnabled, lamportsToSol, localnet, prepareTransaction, sendAndConfirmTransactionWithSignersFactory, simulateTransactionFactory, transactionFromBase64, transactionToBase64, transactionToBase64WithSigners };