Skip to content

Commit a37bfae

Browse files
karalabekaralabe
authored
Merge pull request ethereum#19947 from karalabe/gh-pages
Add RPC API docs section, write eth_call reference
2 parents ea00558 + 30f1466 commit a37bfae

File tree

5 files changed

+163
-8
lines changed

5 files changed

+163
-8
lines changed

‎_config.yml

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ collections:
3131
sidebar_index: 1
3232
frontpage: _install-and-build/Installing-Geth.md
3333
interface:
34-
output: true
34+
output: true
3535
caption: Interacting with Geth
3636
sidebar_index: 2
3737
support:
@@ -52,14 +52,15 @@ collections:
5252
caption: Whisper
5353
sidebar_index: 6
5454
frontpage: _whisper/Whisper-Overview.md
55+
rpc:
56+
output: true
57+
caption: JSON RPC APIs
58+
sidebar_index: 7
5559
doc:
5660
output: true
5761
caption: Other
58-
sidebar_index: 7
62+
sidebar_index: 8
5963
legacy:
6064
output: true
6165
caption: Legacy content
62-
sidebar_index: 8
63-
64-
65-
66+
sidebar_index: 9

‎doc.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ permalink: /doc/
55
---
66
{% for p in site.doc %}
77
* [{{ p.title }}]({% include link.html url=p.url %})
8-
{% endfor %}
8+
{% endfor %}

‎docs/_rpc/eth_call.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: eth_call
3+
---
4+
5+
Executes a new message call immediately, without creating a transaction on the block chain. The `eth_call` method can be used to query internal contract state, to execute validations coded into a contract or even to test what the effect of a transaction would be without running it live.
6+
7+
## Parameters
8+
9+
The method takes 3 parameters: an unsigned transaction object to execute in read-only mode; the block number to execute the call against; and an optional state override-set to allow executing the call against a modified chain state.
10+
11+
##### 1. `Object` - Transaction call object
12+
13+
The *transaction call object* is mandatory and contains all the necessary parameters to execute a read-only EVM contract method.
14+
15+
| Field | Type | Bytes | Optional | Description |
16+
|:---:|:---:|:---:|:---:|:---|
17+
| `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. |
18+
| `to` | `Address` | 20 | No | Address the transaction is sent to. |
19+
| `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`. |
20+
| `gasPrice` | `Quantity` | <32 | Yes | Number of `wei` to simulate paying for each unit of gas during execution. Defaults to `1 gwei`. |
21+
| `value` | `Quantity` | <32 | Yes | Amount of `wei` to simulate sending along with the transaction. Defaults to `0`. |
22+
| `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). |
23+
24+
Example:
25+
26+
```json
27+
{
28+
"from": "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3",
29+
"to": "0xebe8efa441b9302a0d7eaecc277c09d20d684540",
30+
"gas": "0x1bd7c",
31+
"data": "0xd459fc46000000000000000000000000000000000000000000000000000000000046c650dbb5e8cb2bac4d2ed0b1e6475d37361157738801c494ca482f96527eb48f9eec488c2eba92d31baeccfb6968fad5c21a3df93181b43b4cf253b4d572b64172ef000000000000000000000000000000000000000000000000000000000000008c00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000000000000000000000000000000000000000002b85c0c828d7a98633b4e1b65eac0c017502da909420aeade9a280675013df36bdc71cffdf420cef3d24ba4b3f9b980bfbb26bd5e2dcf7795b3519a3fd22ffbb2000000000000000000000000000000000000000000000000000000000000000238fb6606dc2b5e42d00c653372c153da8560de77bd9afaba94b4ab6e4aa11d565d858c761320dbf23a94018d843772349bd9d92301b0ca9ca983a22d86a70628",
32+
}
33+
```
34+
35+
##### 2. `Quantity | Tag` - Block number or the string `latest` or `pending`
36+
37+
The *block number* is mandatory and defines the context (state) against which the specified transaction should be executed. It is not possible to execute calls against reorged blocks; or blocks older than 128 (unless the node is an archive node).
38+
39+
##### 3. `Object` - Optional - State override set
40+
41+
The *state override set* is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call. Each address maps to an object containing:
42+
43+
| Field | Type | Bytes | Optional | Description |
44+
|:---:|:---:|:---:|:---:|:---|
45+
| `balance` | `Quantity` | <32 | Yes | Fake balance to set for the account before executing the call. |
46+
| `nonce` | `Quantity` | <8 | Yes | Fake nonce to set for the account before executing the call. |
47+
| `code` | `Binary` | any | Yes | Fake EVM bytecode to inject into the account before executing the call. |
48+
| `state` | `Object` | any | Yes | Fake key-value mapping to override **all** slots in the account storage before executing the call. |
49+
| `stateDiff` | `Object` | any | Yes | Fake key-value mapping to override **individual** slots in the account storage before executing the call. |
50+
51+
The goal of the *state override set* is manyfold:
52+
53+
* It can be used by DApps to reduce the amount of contract code needed to be deployed on chain. Code that simply returns internal state or does pre-defined validations can be kept off chain and fed to the node on-demand.
54+
* It can be used for smart contract analysis by extending the code deployed on chain with custom methods and invoking them. This avoids having to download and reconstruct the entire state in a sandbox to run custom code against.
55+
* It can be used to debug smart contracts in an already deployed large suite of contracts by selectively overriding some code or state and seeing how execution changes. Specialized tooling will probably be necessary.
56+
57+
Example:
58+
59+
```json
60+
{
61+
"0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3": {
62+
"balance": "0xde0b6b3a7640000"
63+
},
64+
"0xebe8efa441b9302a0d7eaecc277c09d20d684540": {
65+
"code": "0x...",
66+
"state": {
67+
""
68+
}
69+
}
70+
}
71+
```
72+
73+
## Returns
74+
75+
The method returns a single `Binary` consisting the return value of the executed contract call.
76+
77+
## Simple example
78+
79+
With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --rpc`) we can make a call against the [Checkpoint Oracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540) to retrieve the list of administrators:
80+
81+
```
82+
$ curl --data '{"method":"eth_call","params":[{"to":"0xebe8efa441b9302a0d7eaecc277c09d20d684540","data":"0x45848dfc"},"latest"],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
83+
```
84+
85+
And the result is an Ethereum ABI encoded list of accounts:
86+
87+
```json
88+
{
89+
"id": 1,
90+
"jsonrpc": "2.0",
91+
"result": "0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000004000000000000000000000000d9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f300000000000000000000000078d1ad571a1a09d60d9bbf25894b44e4c8859595000000000000000000000000286834935f4a8cfb4ff4c77d5770c2775ae2b0e7000000000000000000000000b86e2b0ab5a4b1373e40c51a7c712c70ba2f9f8e"
92+
}
93+
```
94+
95+
Just for the sake of completeness, decoded the response is:
96+
97+
```
98+
0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3,
99+
0x78d1ad571a1a09d60d9bbf25894b44e4c8859595,
100+
0x286834935f4a8cfb4ff4c77d5770c2775ae2b0e7,
101+
0xb86e2b0ab5a4b1373e40c51a7c712c70ba2f9f8e
102+
```
103+
104+
## Override example
105+
106+
The above *simple example* showed how to call a method already exposed by an on-chain smart contract. What if we want to access some data not exposed by it?
107+
108+
We can gut out the [original](https://github.com/ethereum/go-ethereum/blob/master/contracts/checkpointoracle/contract/oracle.sol) checkpoint oracle contract with one that retains the same fields (to retain the same storage layout), but one that includes a different method set:
109+
110+
```
111+
pragma solidity ^0.5.10;
112+
113+
contract CheckpointOracle {
114+
mapping(address => bool) admins;
115+
address[] adminList;
116+
uint64 sectionIndex;
117+
uint height;
118+
bytes32 hash;
119+
uint sectionSize;
120+
uint processConfirms;
121+
uint threshold;
122+
123+
function VotingThreshold() public view returns (uint) {
124+
return threshold;
125+
}
126+
}
127+
```
128+
129+
With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --rpc`) we can make a call against the live [Checkpoint Oracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540), but override its byte code with our own version that has an accessor for the voting theshold field:
130+
131+
```
132+
$ curl --data '{"method":"eth_call","params":[{"to":"0xebe8efa441b9302a0d7eaecc277c09d20d684540","data":"0x0be5b6ba"}, "latest", {"0xebe8efa441b9302a0d7eaecc277c09d20d684540": {"code":"0x6080604052348015600f57600080fd5b506004361060285760003560e01c80630be5b6ba14602d575b600080fd5b60336045565b60408051918252519081900360200190f35b6007549056fea265627a7a723058206f26bd0433456354d8d1228d8fe524678a8aeeb0594851395bdbd35efc2a65f164736f6c634300050a0032"}}],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
133+
```
134+
135+
And the result is the Ethereum ABI encoded threshold number:
136+
137+
```json
138+
{
139+
"id": 1,
140+
"jsonrpc": "2.0",
141+
"result": "0x0000000000000000000000000000000000000000000000000000000000000002"
142+
}
143+
```
144+
145+
Just for the sake of completeness, decoded the response is: `2`.

‎docs/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ root: ..
55
* User documentation can be found at our [Ethereum User Guide and reference manual](http://ethereum.gitbooks.io/frontier-guide/content/).
66
* For the API reference and developer documentation head over to the auto generated [GoDoc](https://godoc.org/github.com/ethereum/go-ethereum) documentation.
77

8-
This is the documentation for the official Ethereum golang implementation. For generic Ethereum-related information (whitepaper, yellow paper, protocol and interface specs, APIs, DAPP development guides, etc) see the [Ethereum main wiki](https://github.com/ethereum/wiki/wiki).
8+
This is the documentation for the official Ethereum golang implementation. For generic Ethereum-related information (whitepaper, yellow paper, protocol and interface specs, APIs, DAPP development guides, etc) see the [Ethereum main wiki](https://github.com/ethereum/wiki/wiki).
99

1010
Main entry points:
1111

‎static/styles/custom/common.css

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,12 @@ a code {
3535
display: inline-block;
3636
margin-bottom: -0.25em;
3737
}
38+
39+
table {
40+
margin-top: 16px;
41+
margin-bottom: 16px;
42+
}
43+
table thead tr th, table tbody tr td {
44+
border-bottom: 1px solid #ddd;
45+
padding: 4px;
46+
}

0 commit comments

Comments
 (0)