diff --git a/docs/src/developing/clients/jsonrpc-api.md b/docs/src/developing/clients/jsonrpc-api.md index 8c29ec96ae..4ac188980a 100644 --- a/docs/src/developing/clients/jsonrpc-api.md +++ b/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: ` - 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: ` - 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: ` - Defines the content of the transaction. - `accountKeys: ` - 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: ` - 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: - `` - fully-signed Transaction, as encoded string @@ -2813,7 +2832,7 @@ Before submitting, the following preflight checks are performed: #### Results: -- `` - Transaction Signature, as base-58 encoded string +- `` - First Transaction Signature embedded in the transaction, as base-58 encoded string ([transaction id](../../terminology.md#transanction-id)) #### Example: diff --git a/docs/src/terminology.md b/docs/src/terminology.md index 0f712d03c9..77cffd3562 100644 --- a/docs/src/terminology.md +++ b/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