Document @solana/rpc-types with TypeDoc

Author: steveluscher

packages/rpc-graphql/src/resolvers/block.ts

@@ -83,10 +83,15 @@ export const resolveBlock = (fieldName?: string) => {
                                     })
                                 ] = data[0];
                             } else if (typeof data === 'object') {
-                                const jsonParsedData = data;
-                                jsonParsedData.message.instructions = mapJsonParsedInstructions(
-                                    jsonParsedData.message.instructions,
-                                ) as unknown as (typeof jsonParsedData)['message']['instructions'];
+                                const jsonParsedData: typeof data = {
+                                    ...data,
+                                    message: {
+                                        ...data.message,
+                                        instructions: mapJsonParsedInstructions(
+                                            data.message.instructions,
+                                        ) as unknown as (typeof jsonParsedData)['message']['instructions'],
+                                    },
+                                };
 
                                 const loadedInnerInstructions = loadedTransaction.meta?.innerInstructions;
                                 if (loadedInnerInstructions) {

packages/rpc-types/src/account-info.ts

@@ -9,15 +9,15 @@ import type {
 import type { Lamports } from './lamports';
 
 export type AccountInfoBase = Readonly<{
-    /** indicates if the account contains a program (and is strictly read-only) */
+    /** Indicates if the account contains a program (and is strictly read-only) */
     executable: boolean;
-    /** number of lamports assigned to this account */
+    /** Number of {@link Lamports} assigned to this account */
     lamports: Lamports;
-    /** pubkey of the program this account has been assigned to */
+    /** Address of the program this account has been assigned to */
     owner: Address;
-    /** the epoch at which this account will next owe rent */
+    /** The epoch at which this account will next owe rent */
     rentEpoch: bigint;
-    /** the size of the account data in bytes (excluding the 128 bytes of header) */
+    /** The size of the account data in bytes (excluding the 128 bytes of header) */
     space: bigint;
 }>;
 

packages/rpc-types/src/blockhash.ts

@@ -31,6 +31,24 @@ function getMemoizedBase58Decoder(): Decoder<string> {
     return memoizedBase58Decoder;
 }
 
+/**
+ * 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 {
     // Fast-path; see if the input string is of an acceptable length.
     if (
@@ -51,6 +69,31 @@ export function isBlockhash(putativeBlockhash: string): putativeBlockhash is Blo
     return true;
 }
 
+/**
+ * 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 {
     // Fast-path; see if the input string is of an acceptable length.
     if (
@@ -74,21 +117,85 @@ export function assertIsBlockhash(putativeBlockhash: string): asserts putativeBl
     }
 }
 
+/**
+ * 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> {
     return transformEncoder(fixEncoderSize(getMemoizedBase58Encoder(), 32), putativeBlockhash =>
         blockhash(putativeBlockhash),
     );
 }
 
+/**
+ * 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 fixDecoderSize(getMemoizedBase58Decoder(), 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());
 }

packages/rpc-types/src/cluster-url.ts

@@ -3,12 +3,15 @@ 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;
 }

packages/rpc-types/src/commitment.ts

@@ -1,5 +1,11 @@
 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 {

packages/rpc-types/src/index.ts

@@ -1,3 +1,11 @@
+/**
+ * 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';

packages/rpc-types/src/lamports.ts

@@ -11,6 +11,11 @@ import {
 import { getU64Decoder, getU64Encoder, NumberCodec, NumberDecoder, NumberEncoder } from '@solana/codecs-numbers';
 import { SOLANA_ERROR__LAMPORTS_OUT_OF_RANGE, SolanaError } from '@solana/errors';
 
+/**
+ * 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 = bigint & { readonly __brand: unique symbol };
 
 // Largest possible value to be represented by a u64
@@ -29,37 +34,134 @@ function getMemoizedU64Decoder(): FixedSizeDecoder<bigint, 8> {
     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> {
@@ -68,10 +170,22 @@ export function getLamportsDecoder<TDecoder extends NumberDecoder>(
     ) 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> {