Improve documentation of sendTransaction (#14770)

* Improve documentation of sendTransaction

* Apply suggestions from code review

Co-authored-by: Tyera Eulberg <teulberg@gmail.com>

* Word wrap and improve terminology

* Tweak

* Oops

* Apply suggestions from code review

Co-authored-by: Tyera Eulberg <teulberg@gmail.com>

Co-authored-by: Tyera Eulberg <teulberg@gmail.com>

docs/src/developing/clients/jsonrpc-api.md

@@ -120,8 +120,8 @@ Requests can be sent in batches by sending an array of JSON-RPC request objects
 
 - Hash: A SHA-256 hash of a chunk of data.
 - Pubkey: The public key of a Ed25519 key-pair.
-- Signature: An Ed25519 signature of a chunk of data.
-- Transaction: A Solana instruction signed by a client key-pair.
+- Transaction: A list of Solana instructions signed by a client keypair to authorize those actions.
+- Signature: An Ed25519 signature of transaction's payload data including instructions. This can be used to identify transactions.
 
 ## Configuring State Commitment
 
@@ -642,7 +642,7 @@ Transactions are quite different from those on other blockchains. Be sure to rev
 
 The JSON structure of a transaction is defined as follows:
 
-- `signatures: <array[string]>` - A list of base-58 encoded signatures applied to the transaction. The list is always of length `message.header.numRequiredSignatures`, and the signature at index `i` corresponds to the public key at index `i` in `message.account_keys`.
+- `signatures: <array[string]>` - A list of base-58 encoded signatures applied to the transaction. The list is always of length `message.header.numRequiredSignatures` and not empty. The signature at index `i` corresponds to the public key at index `i` in `message.account_keys`. The first one is used as the [transaction id](../../terminology.md#transaction-id).
 - `message: <object>` - Defines the content of the transaction.
   - `accountKeys: <array[string]>` - List of base-58 encoded public keys used by the transaction, including by the instructions and for signatures. The first `message.header.numRequiredSignatures` public keys must sign the transaction.
   - `header: <object>` - Details the account types and signatures required by the transaction.
@@ -2795,6 +2795,20 @@ Result:
 
 Submits a signed transaction to the cluster for processing.
 
+This method does not alter the transaction in any way; it relays the
+transaction created by clients to the node as-is.
+
+If the node's rpc service receives the transaction, this method immediately
+succeeds, without waiting for any confirmations. A successful response from
+this method does not guarantee the transaction is processed or confirmed by the
+cluster.
+
+While the rpc service will reasonably retry to submit it, the transaction
+could be rejected if transaction's `recent_blockhash` expires before it lands.
+
+Use [`getSignatureStatuses`](jsonrpc-api.md#getsignaturestatuses) to ensure
+a transaction is processed and confirmed.
+
 Before submitting, the following preflight checks are performed:
 
 1. The transaction signatures are verified
@@ -2803,6 +2817,11 @@ Before submitting, the following preflight checks are performed:
    disabled if desired. It is recommended to specify the same commitment and
    preflight commitment to avoid confusing behavior.
 
+The returned signature is the first signature in the transaction, which
+is used to identify the transaction ([transaction id](../../terminology.md#transanction-id)).
+This identifier can be easily extracted from the transaction data before
+submission.
+
 #### Parameters:
 
 - `<string>` - fully-signed Transaction, as encoded string
@@ -2813,7 +2832,7 @@ Before submitting, the following preflight checks are performed:
 
 #### Results:
 
-- `<string>` - Transaction Signature, as base-58 encoded string
+- `<string>` - First Transaction Signature embedded in the transaction, as base-58 encoded string ([transaction id](../../terminology.md#transanction-id))
 
 #### Example:
 

docs/src/terminology.md

@@ -141,6 +141,7 @@ A sequence of [validator](terminology.md#validator) [public keys](terminology.md
 ## ledger
 
 A list of [entries](terminology.md#entry) containing [transactions](terminology.md#transaction) signed by [clients](terminology.md#client).
+Conceptually, this can be traced back to the [genesis block](terminology.md#genesis-block), but actual [validators](terminology.md#validator)'s ledger may have only newer [blocks](terminology.md#block) to save storage usage as older ones not needed for validation of future blocks by design.
 
 ## ledger vote
 
@@ -213,6 +214,8 @@ A fraction of a [block](terminology.md#block); the smallest unit sent between [v
 ## signature
 
 A 64-byte ed25519 signature of R (32-bytes) and S (32-bytes). With the requirement that R is a packed Edwards point not of small order and S is a scalar in the range of 0 <= S < L.
+This requirement ensures no signature malleability. Each transaction must have at least one signature for [fee account](terminology#fee-account).
+Thus, the first signature in transaction can be treated as [transacton id](terminology.md#transaction-id)
 
 ## slot
 
@@ -260,7 +263,11 @@ A scarce, fungible member of a set of tokens.
 
 ## transaction
 
-One or more [instructions](terminology.md#instruction) signed by the [client](terminology.md#client) and executed atomically.
+One or more [instructions](terminology.md#instruction) signed by the [client](terminology.md#client) using one or more [keypairs](terminology.md#keypair) and executed atomically with only two possible outcomes: success or failure.
+
+## transaction id
+
+The first [signature](terminology.md#signature) in a [transaction](terminology.md#transaction), which can be used to uniquely identify the transaction across the complete [ledger](terminology.md#ledger).
 
 ## transaction confirmations