Add UnwrapRpcResponse<T> + isSolanaRpcResponse() to @solana/rpc-types

Adds `UnwrapRpcResponse<T>` (a conditional type that unwraps `SolanaRpcResponse<U> → U` and passes non-envelope types through) and `isSolanaRpcResponse()` (a runtime type guard) to `@solana/rpc-types`.

The guard validates the envelope shape by duck-typing `context.slot: bigint` and the presence of `value` — only the load-bearing fields, so adding new envelope fields like `apiVersion` in the future doesn't ripple through the guard's contract. The narrowed type is `SolanaRpcResponse<UnwrapRpcResponse<T>>`, inferring the inner type from `T` directly so callers don't need a second generic parameter.

Callers that previously needed to lift `slot` from `context` can branch on the guard and access whatever fields they need.

Author: mcintyre94

.changeset/true-geese-bow.md

@@ -0,0 +1,24 @@
+---
+'@solana/rpc-types': minor
+---
+
+Add `UnwrapRpcResponse<T>` type and `isSolanaRpcResponse()` runtime helper alongside `SolanaRpcResponse`. Use them to detect and unwrap notifications that may or may not be wrapped in a `SolanaRpcResponse` envelope.
+
+`UnwrapRpcResponse<T>` is a conditional type:
+
+```ts
+type UnwrapRpcResponse<T> = T extends SolanaRpcResponse<infer U> ? U : T;
+```
+
+`isSolanaRpcResponse()` is a type guard that validates the envelope shape by checking `context.slot: bigint` and the presence of `value`, leaving room for additional envelope fields without changing the guard's contract. The narrowed type is `SolanaRpcResponse<UnwrapRpcResponse<T>>`, so callers don't need to spell out the inner type separately.
+
+```ts
+import { isSolanaRpcResponse } from '@solana/rpc-types';
+
+function lift<T>(notification: T) {
+    if (isSolanaRpcResponse(notification)) {
+        return { slot: notification.context.slot, value: notification.value };
+    }
+    return { slot: undefined, value: notification };
+}
+```

CLAUDE.md

@@ -46,7 +46,7 @@ Four private "impl" packages (`@solana/crypto-impl`, `@solana/text-encoding-impl
 - **Framework**: Jest v30 with `@swc/jest` for TypeScript transformation.
 - **Shared config**: `packages/test-config/` (`@solana/test-config`).
 - **File naming**: `*-test.ts` (runs in both environments), `*-test.node.ts` (Node only), `*-test.browser.ts` (browser/jsdom only). Tests live in `src/__tests__/`.
-- **Type tests**: `src/__typetests__/` directories contain compile-time type tests using `satisfies` and `@ts-expect-error`.
+- **Type tests**: `src/__typetests__/` directories contain compile-time type tests using `satisfies` and `@ts-expect-error`. Structure each file as one or more `// [DESCRIBE] <name>` blocks, with each individual test wrapped in its own nested `{ ... }` block (preceded by a one-line `// comment` describing the test) so that variable scopes don't leak between tests.
 - **Lint/prettier**: Also run through Jest runners (`jest-runner-eslint`, `jest-runner-prettier`).
 - **Commands**: `pnpm test` runs all unit tests. `pnpm lint` runs lint checks. `pnpm style:fix` auto-fixes formatting.
 - **`expect.assertions`**: Only use `expect.assertions(n)` in **async** tests (where you need to guarantee the expected number of assertions ran). Synchronous tests do not need it.

packages/rpc-types/README.md

@@ -35,6 +35,22 @@ This type represents a number which has been encoded as a string for transit ove
 
 This type represents a Unix timestamp in _seconds_. It is represented as a `bigint` in client code and an `i64` in server code.
 
+### `UnwrapRpcResponse<T>`
+
+A conditional type that unwraps `SolanaRpcResponse<U>` → `U` at the type level so callers can surface the inner value without losing static type information. Values that are not wrapped in a `SolanaRpcResponse` envelope pass through unchanged.
+
+```ts
+import type { SolanaRpcResponse, UnwrapRpcResponse } from '@solana/rpc-types';
+
+type AccountValue = UnwrapRpcResponse<SolanaRpcResponse<{ lamports: bigint }>>;
+//   ^? { lamports: bigint }
+
+type AccountValue = UnwrapRpcResponse<{ lamports: bigint }>;
+//   ^? { lamports: bigint }
+```
+
+Pairs with [`isSolanaRpcResponse()`](#issolanarpcresponse) for runtime detection.
+
 ## Functions
 
 ### `assertIsLamports()`
@@ -140,6 +156,23 @@ import { lamports } from '@solana/rpc-types';
 await transfer(address(fromAddress), address(toAddress), lamports(100000n));
 ```
 
+### `isSolanaRpcResponse()`
+
+Type-guards a notification as a `SolanaRpcResponse` envelope. Validates `context.slot: bigint` and the presence of `value`, so adding new fields to the envelope in the future doesn't change the guard's contract — only the load-bearing fields are checked. The narrowed type is `SolanaRpcResponse<UnwrapRpcResponse<T>>`, so callers don't need to spell out the inner type separately.
+
+```ts
+import { isSolanaRpcResponse, type SolanaRpcResponse } from '@solana/rpc-types';
+
+function lift<T>(notification: T) {
+    if (isSolanaRpcResponse(notification)) {
+        return { slot: notification.context.slot, value: notification.value };
+    }
+    return { slot: undefined, value: notification };
+}
+```
+
+Pairs with [`UnwrapRpcResponse<T>`](#unwraprpcresponset) for the type-level counterpart.
+
 ### `stringifiedBigInt()`
 
 This helper combines _asserting_ that a string represents a `bigint` with _coercing_ it to the `StringifiedBigInt` type. It's best used with untrusted input.

packages/rpc-types/src/__tests__/rpc-api-test.ts

@@ -0,0 +1,59 @@
+import { isSolanaRpcResponse, type SolanaRpcResponse } from '../rpc-api';
+import type { Slot } from '../typed-numbers';
+
+describe('isSolanaRpcResponse', () => {
+    it('returns true for a well-formed envelope', () => {
+        const envelope: SolanaRpcResponse<{ lamports: bigint }> = {
+            context: { slot: 99n as Slot },
+            value: { lamports: 5n },
+        };
+        expect(isSolanaRpcResponse(envelope)).toBe(true);
+    });
+
+    it('accepts envelopes whose value is `undefined` or `null`', () => {
+        expect(isSolanaRpcResponse({ context: { slot: 7n }, value: undefined })).toBe(true);
+        expect(isSolanaRpcResponse({ context: { slot: 8n }, value: null })).toBe(true);
+    });
+
+    it('ignores extra fields on `context` (future-proof against new envelope fields)', () => {
+        expect(isSolanaRpcResponse({ context: { apiVersion: '2.0', slot: 1n }, value: 42 })).toBe(true);
+    });
+
+    it('returns false for raw notifications without an envelope', () => {
+        expect(isSolanaRpcResponse({ parent: 9n, root: 8n, slot: 10n })).toBe(false);
+    });
+
+    it('returns false for primitives', () => {
+        expect(isSolanaRpcResponse(42)).toBe(false);
+        expect(isSolanaRpcResponse('hello')).toBe(false);
+        expect(isSolanaRpcResponse(true)).toBe(false);
+    });
+
+    it('returns false for nullish input', () => {
+        expect(isSolanaRpcResponse(undefined)).toBe(false);
+        expect(isSolanaRpcResponse(null)).toBe(false);
+    });
+
+    it('returns false when `value` is missing', () => {
+        expect(isSolanaRpcResponse({ context: { slot: 1n } })).toBe(false);
+    });
+
+    it('returns false when `context` is missing', () => {
+        expect(isSolanaRpcResponse({ value: 42 })).toBe(false);
+    });
+
+    it('returns false when `context` is not an object', () => {
+        expect(isSolanaRpcResponse({ context: 'oops', value: 42 })).toBe(false);
+        expect(isSolanaRpcResponse({ context: null, value: 42 })).toBe(false);
+    });
+
+    it('returns false when `context.slot` is missing', () => {
+        expect(isSolanaRpcResponse({ context: { apiVersion: '2.0' }, value: 42 })).toBe(false);
+    });
+
+    it('returns false when `context.slot` is not a bigint', () => {
+        expect(isSolanaRpcResponse({ context: { slot: 1 }, value: 42 })).toBe(false);
+        expect(isSolanaRpcResponse({ context: { slot: '1' }, value: 42 })).toBe(false);
+        expect(isSolanaRpcResponse({ context: { slot: null }, value: 42 })).toBe(false);
+    });
+});

packages/rpc-types/src/__typetests__/rpc-api-typetest.ts

@@ -0,0 +1,79 @@
+import { isSolanaRpcResponse, type SolanaRpcResponse, type UnwrapRpcResponse } from '../rpc-api';
+import type { Slot } from '../typed-numbers';
+
+// [DESCRIBE] UnwrapRpcResponse
+{
+    // Unwraps `SolanaRpcResponse<U>` to `U`
+    {
+        null as unknown as UnwrapRpcResponse<SolanaRpcResponse<{ lamports: bigint }>> satisfies {
+            lamports: bigint;
+        };
+    }
+
+    // Non-envelope types pass through unchanged
+    {
+        null as unknown as UnwrapRpcResponse<{ lamports: bigint }> satisfies { lamports: bigint };
+        null as unknown as UnwrapRpcResponse<number> satisfies number;
+        null as unknown as UnwrapRpcResponse<string> satisfies string;
+    }
+}
+
+// [DESCRIBE] isSolanaRpcResponse
+{
+    // Narrows an envelope-typed value to the same envelope shape.
+    {
+        const envelope = null as unknown as SolanaRpcResponse<{ lamports: bigint }>;
+        if (isSolanaRpcResponse(envelope)) {
+            envelope.context.slot satisfies Slot;
+            envelope.value satisfies { lamports: bigint };
+        }
+    }
+
+    // For a raw notification, the true-branch narrows to `SolanaRpcResponse<RawValue>`.
+    // (Reaching the true branch on a raw value is impossible at runtime — the guard
+    // validates the envelope shape — so the imprecision is benign.)
+    {
+        const raw = null as unknown as { parent: bigint; slot: bigint };
+        if (isSolanaRpcResponse(raw)) {
+            raw.context.slot satisfies Slot;
+            raw.value satisfies { parent: bigint; slot: bigint };
+        }
+    }
+
+    // For a union of envelope and raw, the true branch narrows to an envelope wrapping
+    // either inner type.
+    {
+        const mixed = null as unknown as SolanaRpcResponse<{ lamports: bigint }> | { lamports: bigint };
+        if (isSolanaRpcResponse(mixed)) {
+            mixed.context.slot satisfies Slot;
+            mixed.value satisfies { lamports: bigint };
+        } else {
+            mixed satisfies { lamports: bigint };
+        }
+    }
+
+    // `unknown` input narrows to `SolanaRpcResponse<unknown>` in the true branch.
+    {
+        const u = null as unknown;
+        if (isSolanaRpcResponse(u)) {
+            u.context.slot satisfies Slot;
+            u.value satisfies unknown;
+        }
+    }
+
+    // Generic-T call-site: the narrowing must work when invoked from inside a generic function
+    // with a parameter typed as `T | undefined`. This mirrors how `useSubscription` consumes
+    // the guard against a `ReactiveStreamStore`'s current value.
+    {
+        function generic<T>(value: T | undefined): {
+            slot: Slot | undefined;
+            value: UnwrapRpcResponse<T> | undefined;
+        } {
+            if (isSolanaRpcResponse(value)) {
+                return { slot: value.context.slot, value: value.value };
+            }
+            return { slot: undefined, value: value as UnwrapRpcResponse<T> | undefined };
+        }
+        void generic;
+    }
+}

packages/rpc-types/src/rpc-api.ts

@@ -4,3 +4,56 @@ export type SolanaRpcResponse<TValue> = Readonly<{
     context: Readonly<{ slot: Slot }>;
     value: TValue;
 }>;
+
+/**
+ * Unwraps `SolanaRpcResponse<U>` → `U` at the type level so callers can surface
+ * the inner value without losing static type information. Values that are not
+ * wrapped in a `SolanaRpcResponse` envelope pass through unchanged.
+ *
+ * Pairs with {@link isSolanaRpcResponse} for runtime detection.
+ *
+ * @typeParam T - The raw notification shape.
+ *
+ * @example
+ * ```ts
+ * type AccountValue = UnwrapRpcResponse<SolanaRpcResponse<{ lamports: bigint }>>;
+ * //   ^? { lamports: bigint }
+ *
+ * type AccountValue = UnwrapRpcResponse<{ lamports: bigint }>;
+ * //   ^? { lamports: bigint }
+ * ```
+ */
+export type UnwrapRpcResponse<T> = T extends SolanaRpcResponse<infer U> ? U : T;
+
+/**
+ * Type-guards a notification as a {@link SolanaRpcResponse} envelope. Validates the shape by
+ * duck-typing for `context.slot: bigint` and the presence of `value`.
+ *
+ * The narrowed type is `SolanaRpcResponse<UnwrapRpcResponse<T>>`. In the false branch,
+ * `notification` retains its original type.
+ *
+ * @typeParam T - The notification shape, which may be a raw value, an envelope, or a union of the two.
+ * @param notification - The value to test.
+ * @return `true` when `notification` is a `SolanaRpcResponse` envelope, narrowing accordingly.
+ *
+ * @example
+ * ```ts
+ * if (isSolanaRpcResponse(notification)) {
+ *     return { slot: notification.context.slot, value: notification.value };
+ * }
+ * ```
+ */
+export function isSolanaRpcResponse<T>(
+    notification: SolanaRpcResponse<UnwrapRpcResponse<T>> | T,
+): notification is SolanaRpcResponse<UnwrapRpcResponse<T>> {
+    return (
+        notification != null &&
+        typeof notification === 'object' &&
+        'context' in notification &&
+        notification.context != null &&
+        typeof notification.context === 'object' &&
+        'slot' in notification.context &&
+        typeof notification.context.slot === 'bigint' &&
+        'value' in notification
+    );
+}