@solana/rpc-types 6.3.1 → 6.3.2-canary-20260313112147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/rpc-types",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Type definitions for values used in the Solana RPC, and helper functions for working with them",
   "homepage": "https://www.solanakit.com/api#solanarpc-types",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,12 +56,12 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/codecs-core": "6.3.1",
-    "@solana/addresses": "6.3.1",
-    "@solana/codecs-numbers": "6.3.1",
-    "@solana/codecs-strings": "6.3.1",
-    "@solana/errors": "6.3.1",
-    "@solana/nominal-types": "6.3.1"
+    "@solana/addresses": "6.3.2-canary-20260313112147",
+    "@solana/codecs-core": "6.3.2-canary-20260313112147",
+    "@solana/codecs-numbers": "6.3.2-canary-20260313112147",
+    "@solana/codecs-strings": "6.3.2-canary-20260313112147",
+    "@solana/errors": "6.3.2-canary-20260313112147",
+    "@solana/nominal-types": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/account-filters.ts

@@ -0,0 +1,46 @@
+import { Base58EncodedBytes, Base64EncodedBytes } from './encoded-bytes';
+
+export type DataSlice = Readonly<{
+    /** The number of bytes to return */
+    length: number;
+    /** The byte offset from which to start reading */
+    offset: number;
+}>;
+
+type ProgramNotificationsMemcmpFilterBase58 = Readonly<{
+    /**
+     * The bytes to match, as a base-58 encoded string.
+     *
+     * Data is limited to a maximum of 128 decoded bytes.
+     */
+    bytes: Base58EncodedBytes;
+    /** The encoding to use when decoding the supplied byte string */
+    encoding: 'base58';
+    /** The byte offset into the account data from which to start the comparison */
+    offset: bigint;
+}>;
+
+type ProgramNotificationsMemcmpFilterBase64 = Readonly<{
+    /**
+     * The bytes to match, as a base-64 encoded string.
+     *
+     * Data is limited to a maximum of 128 decoded bytes.
+     */
+    bytes: Base64EncodedBytes;
+    /** The encoding to use when decoding the supplied byte string */
+    encoding: 'base64';
+    /** The byte offset into the account data from which to start the comparison */
+    offset: bigint;
+}>;
+
+export type GetProgramAccountsMemcmpFilter = Readonly<{
+    /**
+     * This filter matches when the bytes supplied are equal to the account data at the given offset
+     */
+    memcmp: ProgramNotificationsMemcmpFilterBase58 | ProgramNotificationsMemcmpFilterBase64;
+}>;
+
+export type GetProgramAccountsDatasizeFilter = Readonly<{
+    /** This filter matches when the account data length is equal to this */
+    dataSize: bigint;
+}>;

package/src/account-info.ts

@@ -0,0 +1,57 @@
+import type { Address } from '@solana/addresses';
+
+import type {
+    Base58EncodedBytes,
+    Base58EncodedDataResponse,
+    Base64EncodedDataResponse,
+    Base64EncodedZStdCompressedDataResponse,
+} from './encoded-bytes';
+import type { Lamports } from './lamports';
+
+export type AccountInfoBase = Readonly<{
+    /** Indicates if the account contains a program (and is strictly read-only) */
+    executable: boolean;
+    /** Number of {@link Lamports} assigned to this account */
+    lamports: Lamports;
+    /** Address of the program this account has been assigned to */
+    owner: Address;
+    /** The size of the account data in bytes (excluding the 128 bytes of header) */
+    space: bigint;
+}>;
+
+/** @deprecated */
+export type AccountInfoWithBase58Bytes = Readonly<{
+    data: Base58EncodedBytes;
+}>;
+
+/** @deprecated */
+export type AccountInfoWithBase58EncodedData = Readonly<{
+    data: Base58EncodedDataResponse;
+}>;
+
+export type AccountInfoWithBase64EncodedData = Readonly<{
+    data: Base64EncodedDataResponse;
+}>;
+
+export type AccountInfoWithBase64EncodedZStdCompressedData = Readonly<{
+    data: Base64EncodedZStdCompressedDataResponse;
+}>;
+
+export type AccountInfoWithJsonData = Readonly<{
+    data:
+        | Base64EncodedDataResponse // If `jsonParsed` encoding is requested but a parser cannot be found for the given account the `data` field falls back to `base64`.
+        | Readonly<{
+              parsed: {
+                  info?: object;
+                  type: string;
+              };
+              // Name of the program that owns this account.
+              program: string;
+              space: bigint;
+          }>;
+}>;
+
+export type AccountInfoWithPubkey<TAccount extends AccountInfoBase> = Readonly<{
+    account: TAccount;
+    pubkey: Address;
+}>;

package/src/blockhash.ts

@@ -0,0 +1,173 @@
+import { Address, assertIsAddress, getAddressDecoder, getAddressEncoder, isAddress } from '@solana/addresses';
+import { combineCodec, createEncoder, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder } from '@solana/codecs-core';
+import {
+    isSolanaError,
+    SOLANA_ERROR__ADDRESSES__INVALID_BYTE_LENGTH,
+    SOLANA_ERROR__ADDRESSES__STRING_LENGTH_OUT_OF_RANGE,
+    SOLANA_ERROR__BLOCKHASH_STRING_LENGTH_OUT_OF_RANGE,
+    SOLANA_ERROR__INVALID_BLOCKHASH_BYTE_LENGTH,
+    SolanaError,
+} from '@solana/errors';
+import { Brand, EncodedString } from '@solana/nominal-types';
+
+export type Blockhash = Brand<EncodedString<string, 'base58'>, 'Blockhash'>;
+
+/**
+ * A type guard that returns `true` if the input string conforms to the {@link Blockhash} type, and
+ * refines its type for use in your program.
+ *
+ * @example
+ * ```ts
+ * import { isBlockhash } from '@solana/rpc-types';
+ *
+ * if (isBlockhash(blockhash)) {
+ *     // At this point, `blockhash` has been refined to a
+ *     // `Blockhash` that can be used with the RPC.
+ *     const { value: isValid } = await rpc.isBlockhashValid(blockhash).send();
+ *     setBlockhashIsFresh(isValid);
+ * } else {
+ *     setError(`${blockhash} is not a blockhash`);
+ * }
+ * ```
+ */
+export function isBlockhash(putativeBlockhash: string): putativeBlockhash is Blockhash {
+    return isAddress(putativeBlockhash);
+}
+
+/**
+ * From time to time you might acquire a string, that you expect to validate as a blockhash, from an
+ * untrusted network API or user input. Use this function to assert that such an arbitrary string is
+ * a base58-encoded blockhash.
+ *
+ * @example
+ * ```ts
+ * import { assertIsBlockhash } from '@solana/rpc-types';
+ *
+ * // Imagine a function that determines whether a blockhash is fresh when a user submits a form.
+ * function handleSubmit() {
+ *     // We know only that what the user typed conforms to the `string` type.
+ *     const blockhash: string = blockhashInput.value;
+ *     try {
+ *         // If this type assertion function doesn't throw, then
+ *         // Typescript will upcast `blockhash` to `Blockhash`.
+ *         assertIsBlockhash(blockhash);
+ *         // At this point, `blockhash` is a `Blockhash` that can be used with the RPC.
+ *         const { value: isValid } = await rpc.isBlockhashValid(blockhash).send();
+ *     } catch (e) {
+ *         // `blockhash` turned out not to be a base58-encoded blockhash
+ *     }
+ * }
+ * ```
+ */
+export function assertIsBlockhash(putativeBlockhash: string): asserts putativeBlockhash is Blockhash {
+    try {
+        assertIsAddress(putativeBlockhash);
+    } catch (error) {
+        if (isSolanaError(error, SOLANA_ERROR__ADDRESSES__STRING_LENGTH_OUT_OF_RANGE)) {
+            throw new SolanaError(SOLANA_ERROR__BLOCKHASH_STRING_LENGTH_OUT_OF_RANGE, error.context);
+        }
+        if (isSolanaError(error, SOLANA_ERROR__ADDRESSES__INVALID_BYTE_LENGTH)) {
+            throw new SolanaError(SOLANA_ERROR__INVALID_BLOCKHASH_BYTE_LENGTH, error.context);
+        }
+        throw error;
+    }
+}
+
+/**
+ * Combines _asserting_ that a string is a blockhash with _coercing_ it to the {@link Blockhash}
+ * type. It's most useful with untrusted input.
+ *
+ * @example
+ * ```ts
+ * import { blockhash } from '@solana/rpc-types';
+ *
+ * const { value: isValid } = await rpc.isBlockhashValid(blockhash(blockhashFromUserInput)).send();
+ * ```
+ *
+ * > [!TIP]
+ * > When starting from a known-good blockhash as a string, it's more efficient to typecast it
+ * rather than to use the {@link blockhash} helper, because the helper unconditionally performs
+ * validation on its input.
+ * >
+ * > ```ts
+ * > import { Blockhash } from '@solana/rpc-types';
+ * >
+ * > const blockhash = 'ABmPH5KDXX99u6woqFS5vfBGSNyKG42SzpvBMWWqAy48' as Blockhash;
+ * > ```
+ */
+export function blockhash(putativeBlockhash: string): Blockhash {
+    assertIsBlockhash(putativeBlockhash);
+    return putativeBlockhash;
+}
+
+/**
+ * Returns an encoder that you can use to encode a base58-encoded blockhash to a byte array.
+ *
+ * @example
+ * ```ts
+ * import { getBlockhashEncoder } from '@solana/rpc-types';
+ *
+ * const blockhash = 'ABmPH5KDXX99u6woqFS5vfBGSNyKG42SzpvBMWWqAy48' as Blockhash;
+ * const blockhashEncoder = getBlockhashEncoder();
+ * const blockhashBytes = blockhashEncoder.encode(blockhash);
+ * // Uint8Array(32) [
+ * //   136, 123,  44, 249,  43,  19,  60,  14,
+ * //   144,  16, 168, 241, 121, 111,  70, 232,
+ * //   186,  26, 140, 202, 213,  64, 231,  82,
+ * //   179,  66, 103, 237,  52, 117, 217,  93
+ * // ]
+ * ```
+ */
+export function getBlockhashEncoder(): FixedSizeEncoder<Blockhash, 32> {
+    const addressEncoder = getAddressEncoder();
+    return createEncoder({
+        fixedSize: 32,
+        write: (value: string, bytes, offset) => {
+            assertIsBlockhash(value);
+            return addressEncoder.write(value as string as Address, bytes, offset);
+        },
+    });
+}
+
+/**
+ * Returns a decoder that you can use to convert an array of 32 bytes representing a blockhash to
+ * the base58-encoded representation of that blockhash.
+ *
+ * @example
+ * ```ts
+ * import { getBlockhashDecoder } from '@solana/rpc-types';
+ *
+ * const blockhashBytes = new Uint8Array([
+ *     136, 123,  44, 249,  43,  19,  60,  14,
+ *     144,  16, 168, 241, 121, 111,  70, 232,
+ *     186,  26, 140, 202, 213,  64, 231,  82,
+ *     179,  66, 103, 237,  52, 117, 217,  93
+ * ]);
+ * const blockhashDecoder = getBlockhashDecoder();
+ * const blockhash = blockhashDecoder.decode(blockhashBytes); // ABmPH5KDXX99u6woqFS5vfBGSNyKG42SzpvBMWWqAy48
+ * ```
+ */
+export function getBlockhashDecoder(): FixedSizeDecoder<Blockhash, 32> {
+    return getAddressDecoder() as FixedSizeDecoder<string, 32> as FixedSizeDecoder<Blockhash, 32>;
+}
+
+/**
+ * Returns a codec that you can use to encode from or decode to a base-58 encoded blockhash.
+ *
+ * @see {@link getBlockhashDecoder}
+ * @see {@link getBlockhashEncoder}
+ */
+export function getBlockhashCodec(): FixedSizeCodec<Blockhash, Blockhash, 32> {
+    return combineCodec(getBlockhashEncoder(), getBlockhashDecoder());
+}
+
+export function getBlockhashComparator(): (x: string, y: string) => number {
+    return new Intl.Collator('en', {
+        caseFirst: 'lower',
+        ignorePunctuation: false,
+        localeMatcher: 'best fit',
+        numeric: false,
+        sensitivity: 'variant',
+        usage: 'sort',
+    }).compare;
+}

package/src/cluster-url.ts

@@ -0,0 +1,17 @@
+export type MainnetUrl = string & { '~cluster': 'mainnet' };
+export type DevnetUrl = string & { '~cluster': 'devnet' };
+export type TestnetUrl = string & { '~cluster': 'testnet' };
+export type ClusterUrl = DevnetUrl | MainnetUrl | TestnetUrl | string;
+
+/** Given a URL casts it to a type that is only accepted where mainnet URLs are expected. */
+export function mainnet(putativeString: string): MainnetUrl {
+    return putativeString as MainnetUrl;
+}
+/** Given a URL casts it to a type that is only accepted where devnet URLs are expected. */
+export function devnet(putativeString: string): DevnetUrl {
+    return putativeString as DevnetUrl;
+}
+/** Given a URL casts it to a type that is only accepted where testnet URLs are expected. */
+export function testnet(putativeString: string): TestnetUrl {
+    return putativeString as TestnetUrl;
+}

package/src/commitment.ts

@@ -0,0 +1,31 @@
+import { SOLANA_ERROR__INVARIANT_VIOLATION__SWITCH_MUST_BE_EXHAUSTIVE, SolanaError } from '@solana/errors';
+
+/**
+ * A union of all possible commitment statuses -- each a measure of the network confirmation and
+ * stake levels on a particular block.
+ *
+ * Read more about the statuses themselves, [here](https://docs.solana.com/cluster/commitments).
+ */
+export type Commitment = 'confirmed' | 'finalized' | 'processed';
+
+function getCommitmentScore(commitment: Commitment): number {
+    switch (commitment) {
+        case 'finalized':
+            return 2;
+        case 'confirmed':
+            return 1;
+        case 'processed':
+            return 0;
+        default:
+            throw new SolanaError(SOLANA_ERROR__INVARIANT_VIOLATION__SWITCH_MUST_BE_EXHAUSTIVE, {
+                unexpectedValue: commitment satisfies never,
+            });
+    }
+}
+
+export function commitmentComparator(a: Commitment, b: Commitment): -1 | 0 | 1 {
+    if (a === b) {
+        return 0;
+    }
+    return getCommitmentScore(a) < getCommitmentScore(b) ? -1 : 1;
+}

package/src/encoded-bytes.ts

@@ -0,0 +1,12 @@
+import { Brand, CompressedData, EncodedString } from '@solana/nominal-types';
+
+export type Base58EncodedBytes = Brand<EncodedString<string, 'base58'>, 'Base58EncodedBytes'>;
+export type Base64EncodedBytes = Brand<EncodedString<string, 'base64'>, 'Base64EncodedBytes'>;
+export type Base64EncodedZStdCompressedBytes = Brand<
+    EncodedString<CompressedData<string, 'zstd'>, 'base64'>,
+    'Base64EncodedZStdCompressedBytes'
+>;
+
+export type Base58EncodedDataResponse = [Base58EncodedBytes, 'base58'];
+export type Base64EncodedDataResponse = [Base64EncodedBytes, 'base64'];
+export type Base64EncodedZStdCompressedDataResponse = [Base64EncodedZStdCompressedBytes, 'base64+zstd'];

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * This package defines types for values used in the
+ * [Solana JSON-RPC](https://docs.solana.com/api/http) and a series of helpers for working with
+ * them. It can be used standalone, but it is also exported as part of Kit
+ * [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
+ *
+ * @packageDocumentation
+ */
+export * from './account-filters';
+export * from './account-info';
+export * from './blockhash';
+export * from './cluster-url';
+export * from './commitment';
+export * from './encoded-bytes';
+export * from './lamports';
+export * from './rpc-api';
+export * from './stringified-bigint';
+export * from './stringified-number';
+export * from './token-amount';
+export * from './token-balance';
+export * from './transaction';
+export * from './transaction-error';
+export * from './typed-numbers';
+export * from './unix-timestamp';

package/src/lamports.ts

@@ -0,0 +1,195 @@
+import {
+    Codec,
+    combineCodec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    transformDecoder,
+} from '@solana/codecs-core';
+import { getU64Decoder, getU64Encoder, NumberCodec, NumberDecoder, NumberEncoder } from '@solana/codecs-numbers';
+import { SOLANA_ERROR__LAMPORTS_OUT_OF_RANGE, SolanaError } from '@solana/errors';
+import { Brand } from '@solana/nominal-types';
+
+/**
+ * Represents an integer value denominated in Lamports (ie. $1 \times 10^{-9}$ ◎).
+ *
+ * It is represented as a `bigint` in client code and an `u64` in server code.
+ */
+export type Lamports = Brand<bigint, 'Lamports'>;
+
+// Largest possible value to be represented by a u64
+const maxU64Value = 18446744073709551615n; // 2n ** 64n - 1n
+
+let memoizedU64Encoder: FixedSizeEncoder<bigint | number, 8> | undefined;
+let memoizedU64Decoder: FixedSizeDecoder<bigint, 8> | undefined;
+
+function getMemoizedU64Encoder(): FixedSizeEncoder<bigint | number, 8> {
+    if (!memoizedU64Encoder) memoizedU64Encoder = getU64Encoder();
+    return memoizedU64Encoder;
+}
+
+function getMemoizedU64Decoder(): FixedSizeDecoder<bigint, 8> {
+    if (!memoizedU64Decoder) memoizedU64Decoder = getU64Decoder();
+    return memoizedU64Decoder;
+}
+
+/**
+ * This is a type guard that accepts a `bigint` as input. It will both return `true` if the integer
+ * conforms to the {@link Lamports} type and will refine the type for use in your program.
+ *
+ * @example
+ * ```ts
+ * import { isLamports } from '@solana/rpc-types';
+ *
+ * if (isLamports(lamports)) {
+ *     // At this point, `lamports` has been refined to a
+ *     // `Lamports` that can be used anywhere Lamports are expected.
+ *     await transfer(fromAddress, toAddress, lamports);
+ * } else {
+ *     setError(`${lamports} is not a quantity of Lamports`);
+ * }
+ * ```
+ */
+export function isLamports(putativeLamports: bigint): putativeLamports is Lamports {
+    return putativeLamports >= 0 && putativeLamports <= maxU64Value;
+}
+
+/**
+ * Lamport values returned from the RPC API conform to the type {@link Lamports}. You can use a
+ * value of that type wherever a quantity of Lamports is expected.
+ *
+ * @example
+ * From time to time you might acquire a number that you expect to be a quantity of Lamports, from
+ * an untrusted network API or user input. To assert that such an arbitrary number is usable as a
+ * quantity of Lamports, use this function.
+ *
+ * ```ts
+ * import { assertIsLamports } from '@solana/rpc-types';
+ *
+ * // Imagine a function that creates a transfer instruction when a user submits a form.
+ * function handleSubmit() {
+ *     // We know only that what the user typed conforms to the `number` type.
+ *     const lamports: number = parseInt(quantityInput.value, 10);
+ *     try {
+ *         // If this type assertion function doesn't throw, then
+ *         // Typescript will upcast `lamports` to `Lamports`.
+ *         assertIsLamports(lamports);
+ *         // At this point, `lamports` is a `Lamports` that can be used anywhere Lamports are expected.
+ *         await transfer(fromAddress, toAddress, lamports);
+ *     } catch (e) {
+ *         // `lamports` turned out not to validate as a quantity of Lamports.
+ *     }
+ * }
+ * ```
+ */
+export function assertIsLamports(putativeLamports: bigint): asserts putativeLamports is Lamports {
+    if (putativeLamports < 0 || putativeLamports > maxU64Value) {
+        throw new SolanaError(SOLANA_ERROR__LAMPORTS_OUT_OF_RANGE);
+    }
+}
+
+/**
+ * This helper combines _asserting_ that a number is a possible number of {@link Lamports} with
+ * _coercing_ it to the {@link Lamports} type. It's best used with untrusted input.
+ *
+ * @example
+ * ```ts
+ * import { lamports } from '@solana/rpc-types';
+ *
+ * await transfer(address(fromAddress), address(toAddress), lamports(100000n));
+ * ```
+ */
+export function lamports(putativeLamports: bigint): Lamports {
+    assertIsLamports(putativeLamports);
+    return putativeLamports;
+}
+
+type ExtractAdditionalProps<T, U> = Omit<T, keyof U>;
+
+/**
+ * Returns an encoder that you can use to encode a 64-bit {@link Lamports} value to 8 bytes in
+ * little endian order.
+ */
+export function getDefaultLamportsEncoder(): FixedSizeEncoder<Lamports, 8> {
+    return getLamportsEncoder(getMemoizedU64Encoder());
+}
+
+/**
+ * Returns an encoder that you can use to encode a {@link Lamports} value to a byte array.
+ *
+ * You must supply a number decoder that will determine how encode the numeric value.
+ *
+ * @example
+ * ```ts
+ * import { getLamportsEncoder } from '@solana/rpc-types';
+ * import { getU16Encoder } from '@solana/codecs-numbers';
+ *
+ * const lamports = lamports(256n);
+ * const lamportsEncoder = getLamportsEncoder(getU16Encoder());
+ * const lamportsBytes = lamportsEncoder.encode(lamports);
+ * // Uint8Array(2) [ 0, 1 ]
+ * ```
+ */
+export function getLamportsEncoder<TEncoder extends NumberEncoder>(
+    innerEncoder: TEncoder,
+): Encoder<Lamports> & ExtractAdditionalProps<TEncoder, NumberEncoder> {
+    return innerEncoder;
+}
+
+/**
+ * Returns a decoder that you can use to decode a byte array representing a 64-bit little endian
+ * number to a {@link Lamports} value.
+ */
+export function getDefaultLamportsDecoder(): FixedSizeDecoder<Lamports, 8> {
+    return getLamportsDecoder(getMemoizedU64Decoder());
+}
+
+/**
+ * Returns a decoder that you can use to convert an array of bytes representing a number to a
+ * {@link Lamports} value.
+ *
+ * You must supply a number decoder that will determine how many bits to use to decode the numeric
+ * value.
+ *
+ * @example
+ * ```ts
+ * import { getLamportsDecoder } from '@solana/rpc-types';
+ * import { getU16Decoder } from '@solana/codecs-numbers';
+ *
+ * const lamportsBytes = new Uint8Array([ 0, 1 ]);
+ * const lamportsDecoder = getLamportsDecoder(getU16Decoder());
+ * const lamports = lamportsDecoder.decode(lamportsBytes); // lamports(256n)
+ * ```
+ */
+export function getLamportsDecoder<TDecoder extends NumberDecoder>(
+    innerDecoder: TDecoder,
+): Decoder<Lamports> & ExtractAdditionalProps<TDecoder, NumberDecoder> {
+    return transformDecoder<bigint | number, Lamports>(innerDecoder, value =>
+        lamports(typeof value === 'bigint' ? value : BigInt(value)),
+    ) as Decoder<Lamports> & ExtractAdditionalProps<TDecoder, NumberDecoder>;
+}
+
+/**
+ * Returns a codec that you can use to encode from or decode to a 64-bit {@link Lamports} value.
+ *
+ * @see {@link getDefaultLamportsDecoder}
+ * @see {@link getDefaultLamportsEncoder}
+ */
+export function getDefaultLamportsCodec(): FixedSizeCodec<Lamports, Lamports, 8> {
+    return combineCodec(getDefaultLamportsEncoder(), getDefaultLamportsDecoder());
+}
+
+/**
+ * Returns a codec that you can use to encode from or decode to {@link Lamports} value.
+ *
+ * @see {@link getLamportsDecoder}
+ * @see {@link getLamportsEncoder}
+ */
+export function getLamportsCodec<TCodec extends NumberCodec>(
+    innerCodec: TCodec,
+): Codec<Lamports, Lamports> & ExtractAdditionalProps<TCodec, NumberCodec> {
+    return combineCodec(getLamportsEncoder(innerCodec), getLamportsDecoder(innerCodec)) as Codec<Lamports, Lamports> &
+        ExtractAdditionalProps<TCodec, NumberCodec>;
+}

package/src/rpc-api.ts

@@ -0,0 +1,6 @@
+import type { Slot } from './typed-numbers';
+
+export type SolanaRpcResponse<TValue> = Readonly<{
+    context: Readonly<{ slot: Slot }>;
+    value: TValue;
+}>;

package/src/stringified-bigint.ts

@@ -0,0 +1,81 @@
+import { SOLANA_ERROR__MALFORMED_BIGINT_STRING, SolanaError } from '@solana/errors';
+import { Brand } from '@solana/nominal-types';
+
+/**
+ * This type represents a `bigint` which has been encoded as a string for transit over a transport
+ * that does not support `bigint` values natively. The JSON-RPC is such a transport.
+ */
+export type StringifiedBigInt = Brand<string, 'StringifiedBigInt'>;
+
+/**
+ * A type guard that returns `true` if the input string parses as a `BigInt`, and refines its type
+ * for use in your program.
+ *
+ * @example
+ * ```ts
+ * import { isStringifiedBigInt } from '@solana/rpc-types';
+ *
+ * if (isStringifiedBigInt(bigintString)) {
+ *     // At this point, `bigintString` has been refined to a `StringifiedBigInt`
+ *     bigintString satisfies StringifiedBigInt; // OK
+ * } else {
+ *     setError(`${bigintString} does not represent a BigInt`);
+ * }
+ * ```
+ */
+export function isStringifiedBigInt(putativeBigInt: string): putativeBigInt is StringifiedBigInt {
+    try {
+        BigInt(putativeBigInt);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * From time to time you might acquire a string, that you expect to parse as a `BigInt`, from an
+ * untrusted network API or user input. Use this function to assert that such an arbitrary string
+ * will in fact parse as a `BigInt`.
+ *
+ * @example
+ * ```ts
+ * import { assertIsStringifiedBigInt } from '@solana/rpc-types';
+ *
+ * // Imagine having received a value that you presume represents the supply of some token.
+ * // At this point we know only that it conforms to the `string` type.
+ * try {
+ *     // If this type assertion function doesn't throw, then
+ *     // Typescript will upcast `supplyString` to `StringifiedBigInt`.
+ *     assertIsStringifiedBigInt(supplyString);
+ *     // At this point, `supplyString` is a `StringifiedBigInt`.
+ *     supplyString satisfies StringifiedBigInt;
+ * } catch (e) {
+ *     // `supplyString` turned out not to parse as a `BigInt`
+ * }
+ * ```
+ */
+export function assertIsStringifiedBigInt(putativeBigInt: string): asserts putativeBigInt is StringifiedBigInt {
+    try {
+        BigInt(putativeBigInt);
+    } catch {
+        throw new SolanaError(SOLANA_ERROR__MALFORMED_BIGINT_STRING, {
+            value: putativeBigInt,
+        });
+    }
+}
+
+/**
+ * This helper combines _asserting_ that a string will parse as a `BigInt` with _coercing_ it to the
+ * {@link StringifiedBigInt} type. It's best used with untrusted input.
+ *
+ * @example
+ * ```ts
+ * import { stringifiedBigInt } from '@solana/rpc-types';
+ *
+ * const supplyString = stringifiedBigInt('1000000000');
+ * ```
+ */
+export function stringifiedBigInt(putativeBigInt: string): StringifiedBigInt {
+    assertIsStringifiedBigInt(putativeBigInt);
+    return putativeBigInt;
+}