Update the getTransaction documentation to mostly match that in the @solana/rpc-types documentation

Author: steveluscher

Diff for: packages/rpc-api/src/getTransaction.ts

@@ -24,25 +24,37 @@ type ReturnData = {
 };
 
 type TransactionMetaBase = Readonly<{
-    /** The number of compute units consumed by the transaction */
+    /** Number of compute units consumed by the transaction */
     computeUnitsConsumed?: bigint;
-    /** If the transaction failed, this property will contain the error */
+    /** Error if transaction failed, `null` if transaction succeeded. */
     err: TransactionError | null;
     /** The fee this transaction was charged, in {@link Lamports} */
     fee: Lamports;
-    /** An array of string log messages or `null` if log message recording was disabled when this transaction was processed */
+    /**
+     * String log messages or `null` if log message recording was not enabled during this
+     * transaction
+     */
     logMessages: readonly string[] | null;
-    /** An array of account balances, in {@link Lamports}, after the transaction was processed */
+    /** Account balances after the transaction was processed */
     postBalances: readonly Lamports[];
-    /** List of token balances from after the transaction was processed or omitted if token balance recording was disabled when this transaction was processed */
+    /**
+     * List of token balances from after the transaction was processed or omitted if token balance
+     * recording was not yet enabled during this transaction
+     */
     postTokenBalances?: readonly TokenBalance[];
-    /** An array of account balances, in {@link Lamports}, before the transaction was processed */
+    /** Account balances from before the transaction was processed */
     preBalances: readonly Lamports[];
-    /** List of token balances from before the transaction was processed or omitted if token balance recording was disabled when this transaction was processed */
+    /**
+     * List of token balances from before the transaction was processed or omitted if token balance
+     * recording was not yet enabled during this transaction
+     */
     preTokenBalances?: readonly TokenBalance[];
     /** The most-recent return data generated by an instruction in the transaction */
     returnData?: ReturnData;
-    /** Transaction-level rewards; currently only `"Rent"`, but other types may be added in the future */
+    /**
+     * Transaction-level rewards; currently only `"Rent"`, but other types may be added in the
+     * future
+     */
     rewards: readonly Reward[] | null;
     /** @deprecated */
     status: TransactionStatus;
@@ -51,65 +63,147 @@ type TransactionMetaBase = Readonly<{
 type AddressTableLookup = Readonly<{
     /** The address of the address lookup table account. */
     accountKey: Address;
-    /** The list of indices used to load addresses of readonly accounts from the lookup table. */
+    /** Indices of accounts in a lookup table to load as read-only. */
     readableIndexes: readonly number[];
-    /** The list of indices used to load addresses of writable accounts from the lookup table. */
+    /** Indices of accounts in a lookup table to load as writable. */
     writableIndexes: readonly number[];
 }>;
 
 type TransactionBase = Readonly<{
     message: {
+        /**
+         * For transactions whose lifetime is specified by a recent blockhash, this is that
+         * blockhash, and for transactions whose lifetime is specified by a durable nonce, this is
+         * the nonce value.
+         */
         recentBlockhash: Blockhash;
     };
+    /**
+     * An ordered list of signatures belonging to the accounts required to sign this transaction.
+     *
+     * Each signature is an Ed25519 signature of the transaction message using the private key
+     * associated with the account required to sign the transaction.
+     */
     signatures: readonly Base58EncodedBytes[];
 }>;
 
-type TransactionInstruction = Readonly<{
-    accounts: readonly number[];
+type InstructionWithStackHeight = Readonly<{
+    /**
+     * A number indicating the height at which this instruction was called with respect to the
+     * bottom of the call stack denoted by `1` or `null`.
+     *
+     * For instance, an instruction explicitly declared in the transaction message will have a `1`
+     * or `null` height, the first instruction that it calls using a cross-program invocation (CPI)
+     * will have a height of 2, an instruction called by that instruction using a CPI will have a
+     * depth of 3, and so on.
+     */
+    stackHeight: number; // FIXME(https://github.com/anza-xyz/agave/issues/5732) Should be `1` instead of `null` at base of stack
+}>;
+
+type InstructionWithData = Readonly<{
+    /** The input to the invoked program */
     data: Base58EncodedBytes;
-    programIdIndex: number;
-    stackHeight?: number;
 }>;
 
+type TransactionInstruction = InstructionWithData &
+    Partial<InstructionWithStackHeight> &
+    Readonly<{
+        /**
+         * An ordered list of indices that indicate which accounts in the transaction message's
+         * accounts list are loaded by this instruction.
+         */
+        accounts: readonly number[];
+        /**
+         * The index of the address in the transaction message's accounts list associated with the
+         * program to invoke.
+         */
+        programIdIndex: number;
+    }>;
+
 type TransactionJson = Readonly<{
     message: {
+        /** An ordered list of addresses belonging to the accounts loaded by this transaction */
         accountKeys: readonly Address[];
         header: {
+            /**
+             * The number of read-only accounts in the static accounts list that must sign this
+             * transaction.
+             *
+             * Subtracting this number from `numRequiredSignatures` yields the index of the first
+             * read-only signer account in the static accounts list.
+             */
             numReadonlySignedAccounts: number;
+            /**
+             * The number of accounts in the static accounts list that are neither writable nor
+             * signers.
+             *
+             * Adding this number to `numRequiredSignatures` yields the index of the first read-only
+             * non-signer account in the static accounts list.
+             */
             numReadonlyUnsignedAccounts: number;
+            /**
+             * The number of accounts in the static accounts list that must sign this transaction.
+             *
+             * Subtracting `numReadonlySignedAccounts` from this number yields the number of
+             * writable signer accounts in the static accounts list. Writable signer accounts always
+             * begin at index zero in the static accounts list.
+             *
+             * This number itself is the index of the first non-signer account in the static
+             * accounts list.
+             */
             numRequiredSignatures: number;
         };
         instructions: readonly TransactionInstruction[];
     };
 }> &
     TransactionBase;
 
-type PartiallyDecodedTransactionInstruction = Readonly<{
-    accounts: readonly Address[];
-    data: Base58EncodedBytes;
-    programId: Address;
-    stackHeight?: number;
-}>;
+type PartiallyDecodedTransactionInstruction = InstructionWithData &
+    Partial<InstructionWithStackHeight> &
+    Readonly<{
+        /** An ordered list of addresses belonging to the accounts loaded by this instruction */
+        accounts: readonly Address[];
+        /** The address of the program to invoke */
+        programId: Address;
+    }>;
 
-type ParsedTransactionInstruction = Readonly<{
-    parsed: {
-        info?: object;
-        type: string;
-    };
-    program: string;
-    programId: Address;
-    stackHeight?: number;
-}>;
+type ParsedTransactionInstruction = Partial<InstructionWithStackHeight> &
+    Readonly<{
+        /** The output of the program's instruction parser */
+        parsed: {
+            /** The instruction, as interpreted the program's instruction parser. */
+            info?: object;
+            /**
+             * A label that indicates the type of the instruction, as determined by the program's
+             * instruction parser.
+             */
+            type: string;
+        };
+        /** The name of the program. */
+        program: string;
+        /** The address of the program */
+        programId: Address;
+    }>;
 
 type ParsedAccount = Readonly<{
+    /** The address of the account */
     pubkey: Address;
+    /** Whether this account is required to sign the transaction that it's a part of */
     signer: boolean;
+    /**
+     * Indicates whether the account was statically declared in the transaction message or loaded
+     * from an address lookup table.
+     */
     source: 'lookupTable' | 'transaction';
+    /** Whether this account must be loaded with a write-lock */
     writable: boolean;
 }>;
 
 type TransactionJsonParsed = Readonly<{
     message: {
+        /**
+         * An ordered list of parsed accounts belonging to the accounts loaded by this transaction
+         */
         accountKeys: readonly ParsedAccount[];
         instructions: readonly (ParsedTransactionInstruction | PartiallyDecodedTransactionInstruction)[];
     };
@@ -166,32 +260,37 @@ type GetTransactionApiResponseBase = Readonly<{
 }>;
 
 type TransactionMetaLoadedAddresses = Readonly<{
-    /** Transaction account addresses loaded from address lookup tables */
+    /** Addresses loaded from lookup tables */
     loadedAddresses: {
-        /** Ordered list of base-58 encoded addresses for writable accounts */
-        readonly: readonly Address[];
         /** Ordered list of base-58 encoded addresses for read-only accounts */
+        readonly: readonly Address[];
+        /** Ordered list of base-58 encoded addresses for writable accounts */
         writable: readonly Address[];
     };
 }>;
 
 type InnerInstructions<TInstructionType> = Readonly<{
+    /** The index of the instruction in the transaction */
     index: number;
+    /** The instructions */
     instructions: readonly TInstructionType[];
 }>;
 
 type TransactionMetaInnerInstructionsNotParsed = Readonly<{
+    /** A list of instructions called by programs via cross-program invocation (CPI) */
     innerInstructions?: readonly InnerInstructions<TransactionInstruction>[] | null;
 }>;
 
 type TransactionMetaInnerInstructionsParsed = Readonly<{
+    /** A list of instructions called by programs via cross-program invocation (CPI) */
     innerInstructions?:
         | readonly InnerInstructions<ParsedTransactionInstruction | PartiallyDecodedTransactionInstruction>[]
         | null;
 }>;
 
 type TransactionAddressTableLookups = Readonly<{
     message: Readonly<{
+        /** A list of address tables and the accounts that this transaction loads from them */
         addressTableLookups: readonly AddressTableLookup[];
     }>;
 }>;