Skip to content

Commit eddd9db

Browse files
mattdean-digicatapultmattdean-digicatapult
committed
StateManager documentation
Initial `StateManager` documentation. In the process of writing this a couple of inconsistencies in the code were found. Firstly several methods, which should only be called when there are no outstanding checkpoints, were found and updated to error when this is not the case. Secondly the `checkpoint` function was made asynchronous to match other methods.
1 parent db3db1c commit eddd9db

File tree

8 files changed

+854
-126
lines changed

8 files changed

+854
-126
lines changed

‎docs/index.md

Lines changed: 90 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@
1414
- [Parameters][10]
1515
- [vm.runTx][11]
1616
- [Parameters][12]
17-
- [vm.runCode][13]
17+
- [runCode~callback][13]
1818
- [Parameters][14]
19-
- [runCode~callback][15]
19+
- [vm.runCode][15]
2020
- [Parameters][16]
2121
- [Event: beforeBlock][17]
2222
- [Properties][18]
@@ -26,35 +26,33 @@
2626
- [Properties][22]
2727
- [Event: afterTx][23]
2828
- [Properties][24]
29-
- [Event: newContract][25]
29+
- [Event: step][25]
3030
- [Properties][26]
31-
- [Event: step][27]
32-
- [Properties][28]
3331

3432
## vm.runBlockchain
3533

3634
Processes blocks and adds them to the blockchain
3735

3836
### Parameters
3937

40-
- `blockchain` **Blockchain** A [blockchain][29] that to process
41-
- `cb` **[Function][30]** the callback function
38+
- `blockchain` **Blockchain** A [blockchain][27] that to process
39+
- `cb` **[Function][28]** the callback function
4240

4341
## VM
4442

4543
VM Class, `new VM(opts)` creates a new VM object
4644

4745
### Parameters
4846

49-
- `opts` **[Object][31]**
50-
- `opts.stateManager` **StateManager** a state manager instance (EXPERIMENTAL - unstable API)
47+
- `opts` **[Object][29]**
48+
- `opts.stateManager` **StateManager** a [`StateManager`][30] instance to use as the state store (Beta API)
5149
- `opts.state` **Trie** a merkle-patricia-tree instance for the state tree (ignored if stateManager is passed)
5250
- `opts.blockchain` **Blockchain** a blockchain object for storing/retrieving blocks (ignored if stateManager is passed)
53-
- `opts.chain` **([String][32] \| [Number][33])** the chain the VM operates on [default: 'mainnet']
54-
- `opts.hardfork` **[String][32]** hardfork rules to be used [default: 'byzantium', supported: 'byzantium' (will throw on unsupported)]
55-
- `opts.activatePrecompiles` **[Boolean][34]** create entries in the state tree for the precompiled contracts
56-
- `opts.allowUnlimitedContractSize` **[Boolean][34]** allows unlimited contract sizes while debugging. By setting this to `true`, the check for contract size limit of 24KB (see [EIP-170][35]) is bypassed. (default: `false`; ONLY set to `true` during debugging)
57-
- `opts.emitFreeLogs` **[Boolean][34]** Changes the behavior of the LOG opcode, the gas cost of the opcode becomes zero and calling it using STATICCALL won't throw. (default: `false`; ONLY set to `true` during debugging)
51+
- `opts.chain` **([String][31] \| [Number][32])** the chain the VM operates on [default: 'mainnet']
52+
- `opts.hardfork` **[String][31]** hardfork rules to be used [default: 'byzantium', supported: 'byzantium' (will throw on unsupported)]
53+
- `opts.activatePrecompiles` **[Boolean][33]** create entries in the state tree for the precompiled contracts
54+
- `opts.allowUnlimitedContractSize` **[Boolean][33]** allows unlimited contract sizes while debugging. By setting this to `true`, the check for contract size limit of 24KB (see [EIP-170][34]) is bypassed. (default: `false`; ONLY set to `true` during debugging)
55+
- `opts.emitFreeLogs` **[Boolean][33]** Changes the behavior of the LOG opcode, the gas cost of the opcode becomes zero and calling it using STATICCALL won't throw. (default: `false`; ONLY set to `true` during debugging)
5856

5957
## vm.runBlock
6058

@@ -63,37 +61,37 @@ Processes the `block` running all of the transactions it contains and updating t
6361
### Parameters
6462

6563
- `opts`
66-
- `opts.block` **Block** the [`Block`][36] to process
67-
- `opts.generate` **[Boolean][34]** [gen=false] whether to generate the stateRoot, if false `runBlock` will check the stateRoot of the block against the Trie
68-
- `cb` **[runBlock~callback][37]** callback
64+
- `opts.block` **Block** the [`Block`][35] to process
65+
- `opts.generate` **[Boolean][33]** [gen=false] whether to generate the stateRoot, if false `runBlock` will check the stateRoot of the block against the Trie
66+
- `cb` **[runBlock~callback][36]** callback
6967

7068
## runBlock~callback
7169

7270
Callback for `runBlock` method
7371

74-
Type: [Function][30]
72+
Type: [Function][28]
7573

7674
### Parameters
7775

78-
- `error` **[Error][38]** an error that may have happened or `null`
79-
- `results` **[Object][31]**
80-
- `results.receipts` **[Array][39]** the receipts from the transactions in the block
81-
- `results.results` **[Array][39]**
76+
- `error` **[Error][37]** an error that may have happened or `null`
77+
- `results` **[Object][29]**
78+
- `results.receipts` **[Array][38]** the receipts from the transactions in the block
79+
- `results.results` **[Array][38]**
8280

8381
## runTx~callback
8482

8583
Callback for `runTx` method
8684

87-
Type: [Function][30]
85+
Type: [Function][28]
8886

8987
### Parameters
9088

91-
- `error` **[Error][38]** an error that may have happened or `null`
92-
- `results` **[Object][31]**
89+
- `error` **[Error][37]** an error that may have happened or `null`
90+
- `results` **[Object][29]**
9391
- `results.amountSpent` **BN** the amount of ether used by this transaction as a `bignum`
9492
- `results.gasUsed` **BN** the amount of gas as a `bignum` used by the transaction
9593
- `results.gasRefund` **BN** the amount of gas as a `bignum` that was refunded during the transaction (i.e. `gasUsed = totalGasConsumed - gasRefund`)
96-
- `vm` **[VM][40]** contains the results from running the code, if any, as described in `vm.runCode(params, cb)`
94+
- `vm` **[VM][39]** contains the results from running the code, if any, as described in `vm.runCode(params, cb)`
9795

9896
## vm.runTx
9997

@@ -102,54 +100,54 @@ Process a transaction. Run the vm. Transfers eth. Checks balances.
102100
### Parameters
103101

104102
- `opts`
105-
- `opts.tx` **Transaction** a [`Transaction`][41] to run
106-
- `opts.skipNonce` **[Boolean][34]** skips the nonce check
107-
- `opts.skipBalance` **[Boolean][34]** skips the balance check
103+
- `opts.tx` **Transaction** a [`Transaction`][40] to run
104+
- `opts.skipNonce` **[Boolean][33]** skips the nonce check
105+
- `opts.skipBalance` **[Boolean][33]** skips the balance check
108106
- `opts.block` **Block** the block to which the `tx` belongs, if no block is given a default one is created
109-
- `cb` **[runTx~callback][42]** the callback
110-
111-
## vm.runCode
112-
113-
Runs EVM code
114-
115-
### Parameters
116-
117-
- `opts` **[Object][31]**
118-
- `opts.account` **Account** the [`Account`][43] that the executing code belongs to. If omitted an empty account will be used
119-
- `opts.address` **[Buffer][44]** the address of the account that is executing this code. The address should be a `Buffer` of bytes. Defaults to `0`
120-
- `opts.block` **Block** the [`Block`][36] the `tx` belongs to. If omitted a blank block will be used
121-
- `opts.caller` **[Buffer][44]** the address that ran this code. The address should be a `Buffer` of 20bits. Defaults to `0`
122-
- `opts.code` **[Buffer][44]** the EVM code to run given as a `Buffer`
123-
- `opts.data` **[Buffer][44]** the input data
124-
- `opts.gasLimit` **[Buffer][44]** the gas limit for the code
125-
- `opts.origin` **[Buffer][44]** the address where the call originated from. The address should be a `Buffer` of 20bits. Defaults to `0`
126-
- `opts.value` **[Buffer][44]** the value in ether that is being sent to `opt.address`. Defaults to `0`
127-
- `cb` **[runCode~callback][45]** callback
107+
- `cb` **[runTx~callback][41]** the callback
128108

129109
## runCode~callback
130110

131111
Callback for `runCode` method
132112

133-
Type: [Function][30]
113+
Type: [Function][28]
134114

135115
### Parameters
136116

137-
- `error` **[Error][38]** an error that may have happened or `null`
138-
- `results` **[Object][31]**
117+
- `error` **[Error][37]** an error that may have happened or `null`
118+
- `results` **[Object][29]**
139119
- `results.gas` **BN** the amount of gas left
140120
- `results.gasUsed` **BN** the amount of gas as a `bignum` the code used to run
141121
- `results.gasRefund` **BN** a `bignum` containing the amount of gas to refund from deleting storage values
142-
- `results.selfdestruct` **[Object][31]** an `Object` with keys for accounts that have selfdestructed and values for balance transfer recipient accounts
143-
- `results.logs` **[Array][39]** an `Array` of logs that the contract emitted
144-
- `results.exception` **[Number][33]** `0` if the contract encountered an exception, `1` otherwise
145-
- `results.exceptionError` **[String][32]** a `String` describing the exception if there was one
146-
- `results.return` **[Buffer][44]** a `Buffer` containing the value that was returned by the contract
122+
- `results.selfdestruct` **[Object][29]** an `Object` with keys for accounts that have selfdestructed and values for balance transfer recipient accounts
123+
- `results.logs` **[Array][38]** an `Array` of logs that the contract emitted
124+
- `results.exception` **[Number][32]** `0` if the contract encountered an exception, `1` otherwise
125+
- `results.exceptionError` **[String][31]** a `String` describing the exception if there was one
126+
- `results.return` **[Buffer][42]** a `Buffer` containing the value that was returned by the contract
127+
128+
## vm.runCode
129+
130+
Runs EVM code
131+
132+
### Parameters
133+
134+
- `opts` **[Object][29]**
135+
- `opts.account` **Account** the [`Account`][43] that the executing code belongs to. If omitted an empty account will be used
136+
- `opts.address` **[Buffer][42]** the address of the account that is executing this code. The address should be a `Buffer` of bytes. Defaults to `0`
137+
- `opts.block` **Block** the [`Block`][35] the `tx` belongs to. If omitted a blank block will be used
138+
- `opts.caller` **[Buffer][42]** the address that ran this code. The address should be a `Buffer` of 20bits. Defaults to `0`
139+
- `opts.code` **[Buffer][42]** the EVM code to run given as a `Buffer`
140+
- `opts.data` **[Buffer][42]** the input data
141+
- `opts.gasLimit` **[Buffer][42]** the gas limit for the code
142+
- `opts.origin` **[Buffer][42]** the address where the call originated from. The address should be a `Buffer` of 20bits. Defaults to `0`
143+
- `opts.value` **[Buffer][42]** the value in ether that is being sent to `opt.address`. Defaults to `0`
144+
- `cb` **[runCode~callback][44]** callback
147145

148146
## Event: beforeBlock
149147

150148
The `beforeBlock` event
151149

152-
Type: [Object][31]
150+
Type: [Object][29]
153151

154152
### Properties
155153

@@ -159,17 +157,17 @@ Type: [Object][31]
159157

160158
The `afterBlock` event
161159

162-
Type: [Object][31]
160+
Type: [Object][29]
163161

164162
### Properties
165163

166-
- `result` **[Object][31]** emits the results of processing a block
164+
- `result` **[Object][29]** emits the results of processing a block
167165

168166
## Event: beforeTx
169167

170168
The `beforeTx` event
171169

172-
Type: [Object][31]
170+
Type: [Object][29]
173171

174172
### Properties
175173

@@ -179,40 +177,29 @@ Type: [Object][31]
179177

180178
The `afterTx` event
181179

182-
Type: [Object][31]
180+
Type: [Object][29]
183181

184182
### Properties
185183

186-
- `result` **[Object][31]** result of the transaction
187-
188-
## Event: newContract
189-
190-
The `newContract` event when a contract is created
191-
192-
Type: [Object][31]
193-
194-
### Properties
195-
196-
- `address` **[Buffer][44]** the created address for the new contract (type `Buffer | Uint8Array`)
197-
- `code` **[Buffer][44]** the deployment bytecode for reference (type `Buffer | Uint8Array`)
184+
- `result` **[Object][29]** result of the transaction
198185

199186
## Event: step
200187

201188
The `step` event for trace output
202189

203-
Type: [Object][31]
190+
Type: [Object][29]
204191

205192
### Properties
206193

207-
- `pc` **[Number][33]** representing the program counter
208-
- `opcode` **[String][32]** the next opcode to be ran
194+
- `pc` **[Number][32]** representing the program counter
195+
- `opcode` **[String][31]** the next opcode to be ran
209196
- `gasLeft` **BN** amount of gasLeft
210-
- `stack` **[Array][39]** an `Array` of `Buffers` containing the stack
211-
- `account` **Account** the [`Account`][46] which owns the code running
212-
- `address` **[Buffer][44]** the address of the `account`
213-
- `depth` **[Number][33]** the current number of calls deep the contract is
214-
- `memory` **[Buffer][44]** the memory of the VM as a `buffer`
215-
- `storageManager` **StateManager** a state manager instance (EXPERIMENTAL - unstable API)
197+
- `stack` **[Array][38]** an `Array` of `Buffers` containing the stack
198+
- `account` **Account** the [`Account`][45] which owns the code running
199+
- `address` **[Buffer][42]** the address of the `account`
200+
- `depth` **[Number][32]** the current number of calls deep the contract is
201+
- `memory` **[Buffer][42]** the memory of the VM as a `buffer`
202+
- `stateManager` **StateManager** a [`StateManager`][30] instance (Beta API)
216203

217204
[1]: #vmrunblockchain
218205

@@ -238,11 +225,11 @@ Type: [Object][31]
238225

239226
[12]: #parameters-5
240227

241-
[13]: #vmruncode
228+
[13]: #runcodecallback
242229

243230
[14]: #parameters-6
244231

245-
[15]: #runcodecallback
232+
[15]: #vmruncode
246233

247234
[16]: #parameters-7
248235

@@ -262,46 +249,44 @@ Type: [Object][31]
262249

263250
[24]: #properties-3
264251

265-
[25]: #event-newcontract
252+
[25]: #event-step
266253

267254
[26]: #properties-4
268255

269-
[27]: #event-step
256+
[27]: https://github.com/ethereum/ethereumjs-blockchain
270257

271-
[28]: #properties-5
258+
[28]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
272259

273-
[29]: https://github.com/ethereum/ethereumjs-blockchain
260+
[29]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
274261

275-
[30]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
262+
[30]: stateManager.md
276263

277-
[31]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
264+
[31]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
278265

279-
[32]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
266+
[32]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
280267

281-
[33]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
268+
[33]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
282269

283-
[34]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
270+
[34]: https://git.io/vxZkK
284271

285-
[35]: https://git.io/vxZkK
272+
[35]: https://github.com/ethereumjs/ethereumjs-block
286273

287-
[36]: https://github.com/ethereumjs/ethereumjs-block
274+
[36]: #runblockcallback
288275

289-
[37]: #runblockcallback
276+
[37]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
290277

291-
[38]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
278+
[38]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
292279

293-
[39]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
280+
[39]: #vm
294281

295-
[40]: #vm
282+
[40]: https://github.com/ethereum/ethereumjs-tx
296283

297-
[41]: https://github.com/ethereum/ethereumjs-tx
284+
[41]: #runtxcallback
298285

299-
[42]: #runtxcallback
286+
[42]: https://nodejs.org/api/buffer.html
300287

301288
[43]: https://github.com/ethereumjs/ethereumjs-account
302289

303-
[44]: https://nodejs.org/api/buffer.html
304-
305-
[45]: #runcodecallback
290+
[44]: #runcodecallback
306291

307-
[46]: https://github.com/ethereum/ethereumjs-account
292+
[45]: https://github.com/ethereum/ethereumjs-account

0 commit comments

Comments
 (0)