Add optional transactionIndex to getSignaturesForAddress response

.changeset/afraid-peaches-heal.md

@@ -0,0 +1,5 @@
+---
+'@solana/rpc-api': minor
+---
+
+Add the optional `transactionIndex` field to each element of the `getSignaturesForAddress` response. Agave 4.0 (anza-xyz/agave#9683) included the 0 based transaction index inside the block alongside each returned signature. The field is omitted by older RPC servers, so the new property is optional and existing call sites continue to compile without modification.

packages/rpc-api/src/__typetests__/get-signatures-for-address-typetest.ts

@@ -0,0 +1,48 @@
+import type { Address } from '@solana/addresses';
+import type { Signature } from '@solana/keys';
+import type { PendingRpcRequest, Rpc } from '@solana/rpc-spec';
+import type { Commitment, Slot, TransactionError, UnixTimestamp } from '@solana/rpc-types';
+
+import type { GetSignaturesForAddressApi } from '../getSignaturesForAddress';
+
+const rpc = null as unknown as Rpc<GetSignaturesForAddressApi>;
+const address = null as unknown as Address;
+
+type GetSignaturesForAddressElement = Awaited<
+    ReturnType<ReturnType<typeof rpc.getSignaturesForAddress>['send']>
+>[number];
+
+// [DESCRIBE] getSignaturesForAddress response
+{
+    // It returns a pending RPC request when called with no config
+    {
+        rpc.getSignaturesForAddress(address) satisfies PendingRpcRequest<readonly unknown[]>;
+    }
+    // It exposes the documented core fields on each element
+    {
+        const element = null as unknown as GetSignaturesForAddressElement;
+        element.signature satisfies Signature;
+        element.slot satisfies Slot;
+        element.blockTime satisfies UnixTimestamp | null;
+        element.confirmationStatus satisfies Commitment | null;
+        element.err satisfies TransactionError | null;
+        element.memo satisfies string | null;
+    }
+    // It exposes `transactionIndex` as an optional number
+    {
+        const element = null as unknown as GetSignaturesForAddressElement;
+        element.transactionIndex satisfies number | undefined;
+    }
+    // `transactionIndex` is optional, so it may be omitted by older RPC servers
+    {
+        const responseFromOldRpc: GetSignaturesForAddressElement = {
+            blockTime: null,
+            confirmationStatus: null,
+            err: null,
+            memo: null,
+            signature: null as unknown as Signature,
+            slot: 0n as Slot,
+        };
+        responseFromOldRpc satisfies GetSignaturesForAddressElement;
+    }
+}

packages/rpc-api/src/getSignaturesForAddress.ts

@@ -15,6 +15,14 @@ type GetSignaturesForAddressTransaction = Readonly<{
     signature: Signature;
     /** The slot that contains the block with the transaction */
     slot: Slot;
+    /**
+     * The 0 based index of the transaction within its block.
+     *
+     * This field was added in Agave 4.0
+     * (see https://github.com/anza-xyz/agave/pull/9683) and is omitted by
+     * older versions of the RPC server.
+     */
+    transactionIndex?: number;
 }>;
 
 type GetSignaturesForAddressApiResponse = readonly GetSignaturesForAddressTransaction[];

packages/rpc-api/src/index.ts

@@ -304,6 +304,7 @@ function getAllowedNumericKeypaths(): AllowedNumericKeypaths<RpcApi<SolanaRpcApi
                 [KEYPATH_WILDCARD, 'account', ...c],
             ]),
             getRecentPerformanceSamples: [[KEYPATH_WILDCARD, 'samplePeriodSecs']],
+            getSignaturesForAddress: [[KEYPATH_WILDCARD, 'transactionIndex']],
             getTokenAccountBalance: [
                 ['value', 'decimals'],
                 ['value', 'uiAmount'],