doc: update transaction call object (ethereum#25113)

* rpc: add transactionArgs object * rm deprecated note * admin: rename rpc->http * rpc: link to transaction object from methods * rpc/personal: add signTransaction * change link order
Zachinquarantine · Jun 17, 2022 · 3b5a767 · 3b5a767
1 parent 8c0cc91
commit 3b5a767
Show file tree

Hide file tree

Showing 5 changed files with 98 additions and 50 deletions.
diff --git a/docs/_rpc/ns-admin.md b/docs/_rpc/ns-admin.md
@@ -141,10 +141,10 @@ protocols (e.g. `eth`, `les`, `shh`, `bzz`).
 }]
 ```
 
-### admin_startRPC
+### admin_startHTTP
 
-The `startRPC` administrative method starts an HTTP based [JSON RPC](https://www.jsonrpc.org/specification)
-API webserver to handle client requests. All the parameters are optional:
+The `startHTTP` administrative method starts an HTTP based JSON-RPC [API](/docs/rpc/server)
+webserver to handle client requests. All the parameters are optional:
 
 * `host`: network interface to open the listener socket on (defaults to `"localhost"`)
 * `port`: network port to open the listener socket on (defaults to `8545`)
@@ -155,14 +155,14 @@ The method returns a boolean flag specifying whether the HTTP RPC listener was o
 
 | Client  | Method invocation                                                                             |
 |:--------|-----------------------------------------------------------------------------------------------|
-| Go      | `admin.StartRPC(host *string, port *rpc.HexNumber, cors *string, apis *string) (bool, error)` |
-| Console | `admin.startRPC(host, port, cors, apis)`                                                      |
-| RPC     | `{"method": "admin_startRPC", "params": [host, port, cors, apis]}`                            |
+| Go      | `admin.StartHTTP(host *string, port *rpc.HexNumber, cors *string, apis *string) (bool, error)` |
+| Console | `admin.startHTTP(host, port, cors, apis)`                                                      |
+| RPC     | `{"method": "admin_startHTTP", "params": [host, port, cors, apis]}`                            |
 
 #### Example
 
 ```javascript
-> admin.startRPC("127.0.0.1", 8545)
+> admin.startHTTP("127.0.0.1", 8545)
 true
 ```
 
@@ -191,20 +191,20 @@ The method returns a boolean flag specifying whether the WebSocket RPC listener
 true
 ```
 
-### admin_stopRPC
+### admin_stopHTTP
 
-The `stopRPC` administrative method closes the currently open HTTP RPC endpoint. As the node can only have a single HTTP endpoint running, this method takes no parameters, returning a boolean whether the endpoint was closed or not.
+The `stopHTTP` administrative method closes the currently open HTTP RPC endpoint. As the node can only have a single HTTP endpoint running, this method takes no parameters, returning a boolean whether the endpoint was closed or not.
 
 | Client  | Method invocation               |
 |:--------|---------------------------------|
-| Go      | `admin.StopRPC() (bool, error`) |
-| Console | `admin.stopRPC()`               |
-| RPC     | `{"method": "admin_stopRPC"`    |
+| Go      | `admin.StopHTTP() (bool, error`) |
+| Console | `admin.stopHTTP()`               |
+| RPC     | `{"method": "admin_stopHTTP"`    |
 
 #### Example
 
 ```javascript
-> admin.stopRPC()
+> admin.stopHTTP()
 true
 ```
 

diff --git a/docs/_rpc/ns-debug.md b/docs/_rpc/ns-debug.md
@@ -573,16 +573,7 @@ References:
 
 ### debug_traceCall
 
-The `debug_traceCall` method lets you run an `eth_call` within the context of the given block execution using the final state of parent block as the base. The block can be specified either by hash or by number. It takes the same input object as a `eth_call`.
-It returns the same output as `debug_traceTransaction`. A tracer can be specified as a third argument, similar to `debug_traceTransaction`.
-
-`Object` - The transaction call object
-- `from`: `DATA`, 20 Bytes - (optional) The address the transaction is sent from.
-- `to`: `DATA`, 20 Bytes - The address the transaction is directed to.
-- `gas`: `QUANTITY` - (optional) Integer of the gas provided for the transaction execution. eth_call consumes zero gas, but this parameter may be needed by some executions.
-- `gasPrice`: `QUANTITY` - (optional) Integer of the gasPrice used for each paid gas
-- `value`: `QUANTITY` - (optional) Integer of the value sent with this transaction
-- `data`: `DATA` - (optional) Hash of the method signature and encoded parameters. For details see Ethereum Contract ABI in the Solidity documentation
+The `debug_traceCall` method lets you run an `eth_call` within the context of the given block execution using the final state of parent block as the base. The first argument (just as in `eth_call`) is a [transaction object](/docs/rpc/objects#transaction-call-object). The block can be specified either by hash or by number as the second argument. A tracer can be specified as a third argument, similar to `debug_traceTransaction`. It returns the same output as `debug_traceTransaction`.
 
 | Client  | Method invocation                 |
 |:-------:|-----------------------------------|

diff --git a/docs/_rpc/ns-eth.md b/docs/_rpc/ns-eth.md
@@ -28,28 +28,7 @@ allow executing the call against a modified chain state.
 
 ##### 1. `Object` - Transaction call object
 
-The *transaction call object* is mandatory and contains all the necessary parameters to
-execute a read-only EVM contract method.
-
-| Field      | Type       | Bytes | Optional | Description |
-|:-----------|:-----------|:------|:---------|:------------|
-| `from`     | `Address`  | 20    | Yes      | Address the transaction is simulated to have been sent from. Defaults to first account in the local keystore or the `0x00..0` address if no local accounts are available. |
-| `to`       | `Address`  | 20    | No       | Address the transaction is sent to. |
-| `gas`      | `Quantity` | <8    | Yes      | Maximum gas allowance for the code execution to avoid infinite loops. Defaults to `2^63` or whatever value the node operator specified via `--rpc.gascap`. |
-| `gasPrice` | `Quantity` | <32   | Yes      | Number of `wei` to simulate paying for each unit of gas during execution. Defaults to `1 gwei`. |
-| `value`    | `Quantity` | <32   | Yes      | Amount of `wei` to simulate sending along with the transaction. Defaults to `0`. |
-| `data`     | `Binary`   | any   | Yes      | Binary data to send to the target contract. Generally the 4 byte hash of the method signature followed by the ABI encoded parameters. For details please see the [Ethereum Contract ABI](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI). |
-
-Example:
-
-```json
-{
-  "from": "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3",
-  "to":   "0xebe8efa441b9302a0d7eaecc277c09d20d684540",
-  "gas":  "0x1bd7c",
-  "data": "0xd459fc46000000000000000000000000000000000000000000000000000000000046c650dbb5e8cb2bac4d2ed0b1e6475d37361157738801c494ca482f96527eb48f9eec488c2eba92d31baeccfb6968fad5c21a3df93181b43b4cf253b4d572b64172ef000000000000000000000000000000000000000000000000000000000000008c00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000002b85c0c828d7a98633b4e1b65eac0c017502da909420aeade9a280675013df36bdc71cffdf420cef3d24ba4b3f9b980bfbb26bd5e2dcf7795b3519a3fd22ffbb2000000000000000000000000000000000000000000000000000000000000000238fb6606dc2b5e42d00c653372c153da8560de77bd9afaba94b4ab6e4aa11d565d858c761320dbf23a94018d843772349bd9d92301b0ca9ca983a22d86a70628",
-}
-```
+The *transaction call object* is mandatory. Please see [here](/docs/rpc/objects#transaction-call-object) for details.
 
 ##### 2. `Quantity | Tag` - Block number or the string `latest` or `pending`
 
@@ -189,7 +168,7 @@ Just for the sake of completeness, decoded the response is: `2`.
 
 This method creates an [EIP2930](https://eips.ethereum.org/EIPS/eip-2930) type `accessList` based on a given `Transaction`.
 The `accessList` contains all storage slots and addresses read and written by the transaction, except for the sender account and the precompiles.
-This method uses the same `transaction` call object and `blockNumberOrTag` object as `eth_call`.
+This method uses the same `transaction` call [object](/docs/rpc/objects#transaction-call-object) and `blockNumberOrTag` object as `eth_call`.
 An `accessList` can be used to unstuck contracts that became inaccessible due to gas cost increases.
 
 #### Parameters

diff --git a/docs/_rpc/ns-personal.md b/docs/_rpc/ns-personal.md
@@ -126,16 +126,13 @@ true
 
 Validate the given passphrase and submit transaction.
 
-The transaction is the same argument as for `eth_sendTransaction` and contains the `from` address. If the passphrase can be used to decrypt the private key belogging to `tx.from` the transaction is verified, signed and send onto the network. The account is not unlocked globally in the node and cannot be used in other RPC calls.
+The transaction is the same argument as for `eth_sendTransaction` (i.e. [transaction object](/docs/rpc/objects#transaction-call-object)) and contains the `from` address. If the passphrase can be used to decrypt the private key belogging to `tx.from` the transaction is verified, signed and send onto the network. The account is not unlocked globally in the node and cannot be used in other RPC calls.
 
 | Client   | Method invocation                                                |
 | :--------| -----------------------------------------------------------------|
 | Console  | `personal.sendTransaction(tx, passphrase)`                       |
 | RPC      | `{"method": "personal_sendTransaction", "params": [tx, string]}` |
 
-*Note, prior to Geth 1.5, please use `personal_signAndSendTransaction` as that was the
-original introductory name and only later renamed to the current final version.*
-
 #### Examples
 
 ``` javascript
@@ -167,6 +164,15 @@ See ecRecover to verify the signature.
 "0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b"
 ```
 
+### personal_signTransaction
+
+SignTransaction will create a transaction from the given arguments and tries to sign it with the key associated with `tx.from`. If the given passwd isn't able to decrypt the key it fails. The transaction is returned in RLP-form, not broadcast to other nodes. The first argument is a [transaction object](/docs/rpc/objects#transaction-call-object) and the second argument is the password, similar to `personal_sendTransaction`.
+
+| Client   | Method invocation                                                |
+| :--------| -----------------------------------------------------------------|
+| Console  | `personal.signTransaction(tx, passphrase)`                       |
+| RPC      | `{"method": "personal_signTransaction", "params": [tx, string]}` |
+
 ### personal_ecRecover
 
 `ecRecover` returns the address associated with the private key that was used to calculate the signature in `personal_sign`. 

diff --git a/docs/_rpc/objects.md b/docs/_rpc/objects.md
@@ -0,0 +1,72 @@
+---
+title: Objects
+sort_key: D
+---
+
+The following are data structures which are used for various RPC methods.
+
+### Transaction call object
+
+The *transaction call object* contains all the necessary parameters for executing an EVM contract method.
+
+| Field      | Type       | Bytes | Optional | Description |
+|:-----------|:-----------|:------|:---------|:------------|
+| `from`     | `Address`  | 20    | Yes      | Address the transaction is simulated to have been sent from. Defaults to first account in the local keystore or the `0x00..0` address if no local accounts are available. |
+| `to`       | `Address`  | 20    | No       | Address the transaction is sent to. |
+| `gas`      | `Quantity` | <8    | Yes      | Maximum gas allowance for the code execution to avoid infinite loops. Defaults to `2^63` or whatever value the node operator specified via `--rpc.gascap`. |
+| `gasPrice` | `Quantity` | <32   | Yes      | Number of `wei` to simulate paying for each unit of gas during execution. Defaults to `1 gwei`. |
+| `maxFeePerGas` | `Quantity` | <32   | Yes      | Maximum fee per gas the transaction should pay in total. Relevant for type-2 transactions. |
+| `maxPriorityFeePerGas` | `Quantity` | <32   | Yes      | Maximum tip per gas that's given directly to the miner. Relevant for type-2 transactions. |
+| `value`    | `Quantity` | <32   | Yes      | Amount of `wei` to simulate sending along with the transaction. Defaults to `0`. |
+| `nonce`     | `Quantity`   | <8   | Yes      | Nonce of sender account. |
+| `input`     | `Binary`   | any   | Yes      | Binary data to send to the target contract. Generally the 4 byte hash of the method signature followed by the ABI encoded parameters. For details please see the [Ethereum Contract ABI](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI). This field was previously called `data`. |
+| `accessList`     | `AccessList`   | any   | Yes      | A list of addresses and storage keys that the transaction plans to access. Used in non-legacy, i.e. type 1 and 2 transactions. |
+| `chainId`     | `Quantity`   | <32   | Yes      | Transaction only valid on networks with this chain ID. Used in non-legacy, i.e. type 1 and 2 transactions. |
+
+Example for a legacy transaction:
+
+```json
+{
+  "from": "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3",
+  "to":   "0xebe8efa441b9302a0d7eaecc277c09d20d684540",
+  "gas":  "0x1bd7c",
+  "data": "0xd459fc46000000000000000000000000000000000000000000000000000000000046c650dbb5e8cb2bac4d2ed0b1e6475d37361157738801c494ca482f96527eb48f9eec488c2eba92d31baeccfb6968fad5c21a3df93181b43b4cf253b4d572b64172ef000000000000000000000000000000000000000000000000000000000000008c00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000002b85c0c828d7a98633b4e1b65eac0c017502da909420aeade9a280675013df36bdc71cffdf420cef3d24ba4b3f9b980bfbb26bd5e2dcf7795b3519a3fd22ffbb2000000000000000000000000000000000000000000000000000000000000000238fb6606dc2b5e42d00c653372c153da8560de77bd9afaba94b4ab6e4aa11d565d858c761320dbf23a94018d843772349bd9d92301b0ca9ca983a22d86a70628",
+}
+```
+
+Example for a type-1 transaction:
+
+```json
+{
+  "from": "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3",
+  "to":   "0xebe8efa441b9302a0d7eaecc277c09d20d684540",
+  "gas":  "0x1bd7c",
+  "data": "0xd459fc46000000000000000000000000000000000000000000000000000000000046c650dbb5e8cb2bac4d2ed0b1e6475d37361157738801c494ca482f96527eb48f9eec488c2eba92d31baeccfb6968fad5c21a3df93181b43b4cf253b4d572b64172ef000000000000000000000000000000000000000000000000000000000000008c00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000002b85c0c828d7a98633b4e1b65eac0c017502da909420aeade9a280675013df36bdc71cffdf420cef3d24ba4b3f9b980bfbb26bd5e2dcf7795b3519a3fd22ffbb2000000000000000000000000000000000000000000000000000000000000000238fb6606dc2b5e42d00c653372c153da8560de77bd9afaba94b4ab6e4aa11d565d858c761320dbf23a94018d843772349bd9d92301b0ca9ca983a22d86a70628",
+  "chainId": "0x1",
+  "accessList":  [
+    {
+      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+      "storageKeys": ["0xda650992a54ccb05f924b3a73ba785211ba39a8912b6d270312f8e2c223fb9b1", "0x10d6a54a4754c8869d6886b5f5d7fbfa5b4
+                  522237ea5c60d11bc4e7a1ff9390b"]
+    }, {
+      "address": "0xa2327a938febf5fec13bacfb16ae10ecbc4cbdcf",
+      "storageKeys": []
+    },
+  ]
+}
+```
+
+Example for a type-2 transaction:
+
+```json
+{
+  "from": "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3",
+  "to":   "0xebe8efa441b9302a0d7eaecc277c09d20d684540",
+  "gas":  "0x1bd7c",
+  "maxFeePerGas": "0x6b44b0285",
+  "maxPriorityFeePerGas": "0x6b44b0285",
+  "data": "0xd459fc46000000000000000000000000000000000000000000000000000000000046c650dbb5e8cb2bac4d2ed0b1e6475d37361157738801c494ca482f96527eb48f9eec488c2eba92d31baeccfb6968fad5c21a3df93181b43b4cf253b4d572b64172ef000000000000000000000000000000000000000000000000000000000000008c00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000002b85c0c828d7a98633b4e1b65eac0c017502da909420aeade9a280675013df36bdc71cffdf420cef3d24ba4b3f9b980bfbb26bd5e2dcf7795b3519a3fd22ffbb2000000000000000000000000000000000000000000000000000000000000000238fb6606dc2b5e42d00c653372c153da8560de77bd9afaba94b4ab6e4aa11d565d858c761320dbf23a94018d843772349bd9d92301b0ca9ca983a22d86a70628",
+  "chainId": "0x1",
+  "accessList":  []
+}
+```