From fb285b898d08618b5e356b2de6410d87cb6fe06b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Quiroz?= Date: Thu, 8 Sep 2022 17:09:53 -0300 Subject: [PATCH] chore: prettier fix .md files --- content/docs/developers/contributing.md | 10 +- .../dapp-developer/built-in-tracers.md | 55 ++-- .../dapp-developer/custom-tracer.md | 254 ++++++++------- .../docs/developers/dapp-developer/mobile.md | 39 ++- .../dapp-developer/native-accounts.md | 36 +-- .../dapp-developer/native-bindings.md | 71 +++-- .../docs/developers/dapp-developer/native.md | 15 +- .../docs/developers/dapp-developer/tracing.md | 65 ++-- .../geth-developer/Private-Network.md | 41 +-- .../geth-developer/code-review-guidelines.md | 20 +- .../developers/geth-developer/dev-mode.md | 36 +-- .../developers/geth-developer/devguide.md | 2 - .../geth-developer/dns-discovery-setup.md | 8 +- .../geth-developer/issue-handling-workflow.md | 54 ++-- .../geth-developer/vulnerabilities.md | 16 +- content/docs/faq.md | 5 +- content/docs/fundamentals/Backup--restore.md | 6 +- .../docs/fundamentals/Command-Line-Options.md | 6 +- .../docs/fundamentals/account-management.md | 30 +- content/docs/fundamentals/les.md | 4 +- content/docs/fundamentals/mining.md | 29 +- .../docs/fundamentals/node-architecture.md | 5 +- content/docs/fundamentals/peer-to-peer.md | 20 +- content/docs/fundamentals/pruning.md | 25 +- content/docs/fundamentals/security.md | 9 +- content/docs/fundamentals/sync-modes.md | 2 +- .../docs/getting_started/Backup--restore.md | 7 +- .../docs/getting_started/Installing-Geth.md | 62 ++-- .../docs/getting_started/consensus-clients.md | 20 +- .../getting-started-with-clef.md | 62 ++-- .../docs/getting_started/getting_started.md | 60 ++-- .../JavaScript-Console.md | 21 +- .../docs/interacting_with_geth/RPC/batch.md | 38 ++- .../docs/interacting_with_geth/RPC/graphql.md | 35 ++- .../interacting_with_geth/RPC/ns-admin.md | 53 ++-- .../interacting_with_geth/RPC/ns-clique.md | 30 +- .../interacting_with_geth/RPC/ns-debug.md | 291 ++++++++---------- .../docs/interacting_with_geth/RPC/ns-eth.md | 45 +-- .../docs/interacting_with_geth/RPC/ns-les.md | 92 +++--- .../interacting_with_geth/RPC/ns-miner.md | 48 +-- .../docs/interacting_with_geth/RPC/ns-net.md | 7 +- .../interacting_with_geth/RPC/ns-personal.md | 146 +++++---- .../interacting_with_geth/RPC/ns-txpool.md | 20 +- .../docs/interacting_with_geth/RPC/objects.md | 40 +-- .../docs/interacting_with_geth/RPC/pubsub.md | 11 +- .../docs/interacting_with_geth/RPC/server.md | 17 +- content/docs/monitoring/dashboards.md | 4 +- content/docs/monitoring/ethstats.md | 36 +-- content/docs/monitoring/metrics.md | 33 +- content/docs/tools/Clef/CliqueSigning.md | 134 ++++---- content/docs/tools/Clef/Introduction.md | 11 +- content/docs/tools/Clef/Rules.md | 204 ++++++------ content/docs/tools/Clef/Setup.md | 50 +-- content/docs/tools/Clef/Tutorial.md | 137 +++++---- content/docs/tools/Clef/apis.md | 243 ++++++++------- content/docs/tools/Clef/datatypes.md | 21 ++ content/docs/tools/abigen/index.md | 30 +- content/docs/tools/devp2p/index.md | 16 +- content/docs/tools/puppeth/index.md | 3 +- content/homepage.md | 10 +- content/resources.md | 5 +- 61 files changed, 1431 insertions(+), 1474 deletions(-) diff --git a/content/docs/developers/contributing.md b/content/docs/developers/contributing.md index 126395d0a5..522ecf8845 100644 --- a/content/docs/developers/contributing.md +++ b/content/docs/developers/contributing.md @@ -11,11 +11,11 @@ If you'd like to contribute to the Geth source code, please fork the [Github rep Please make sure your contributions adhere to our coding guidelines: -* Code must adhere to the official Go formatting guidelines (i.e. uses gofmt). -* Code must be documented adhering to the official Go commentary guidelines. -* Pull requests need to be based on and opened against the master branch. -* Commit messages should be prefixed with the package(s) they modify. - E.g. "eth, rpc: make trace configs optional" +- Code must adhere to the official Go formatting guidelines (i.e. uses gofmt). +- Code must be documented adhering to the official Go commentary guidelines. +- Pull requests need to be based on and opened against the master branch. +- Commit messages should be prefixed with the package(s) they modify. + E.g. "eth, rpc: make trace configs optional" Pull requests generally need to be based on and opened against the `master` branch, unless by explicit agreement because the work is contributing to some more complex feature branch. diff --git a/content/docs/developers/dapp-developer/built-in-tracers.md b/content/docs/developers/dapp-developer/built-in-tracers.md index fc01d24aea..2c93414daf 100644 --- a/content/docs/developers/dapp-developer/built-in-tracers.md +++ b/content/docs/developers/dapp-developer/built-in-tracers.md @@ -5,25 +5,24 @@ description: Explanation of the tracers that come bundled in Geth as part of the Geth comes bundled with a choice of tracers ready for usage through the [tracing API](/docs/rpc/ns-debug). Some of them are implemented natively in Go, and others in JS. In this page a summary of each of these will be outlined. They have to be specified by name when sending a request. The only exception is the opcode logger (otherwise known as struct logger) which is the default tracer for all the methods and cannot be specified by name. - ## Struct logger Struct logger or opcode logger is a native Go tracer which executes a transaction and emits the opcode and execution context at every step. This is the tracer that will be used when no name is passed to the API, e.g. `debug.traceTransaction()`. The following information is emitted at each step: -| field | type | description | -|------------|---------------|-----------------------------------------------------------------------------------------------------------------------------------| -| pc | uint64 | program counter | -| op | byte | opcode to be executed | -| gas | uint64 | remaining gas | -| gasCost | uint64 | cost for executing op | -| memory | []byte | EVM memory. Enabled via `enableMemory` | -| memSize | int | Size of memory | -| stack | []uint256 | EVM stack. Disabled via `disableStack` | -| returnData | []byte | Last call's return data. Enabled via `enableReturnData` | -| storage | map[hash]hash | Storage slots of current contract read from and written to. Only emitted for `SLOAD` and `SSTORE`. Disabled via `disableStorage` | -| depth | int | Current call depth | -| refund | uint64 | Refund counter | -| error | string | Error message if any | +| field | type | description | +| ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| pc | uint64 | program counter | +| op | byte | opcode to be executed | +| gas | uint64 | remaining gas | +| gasCost | uint64 | cost for executing op | +| memory | []byte | EVM memory. Enabled via `enableMemory` | +| memSize | int | Size of memory | +| stack | []uint256 | EVM stack. Disabled via `disableStack` | +| returnData | []byte | Last call's return data. Enabled via `enableReturnData` | +| storage | map[hash]hash | Storage slots of current contract read from and written to. Only emitted for `SLOAD` and `SSTORE`. Disabled via `disableStorage` | +| depth | int | Current call depth | +| refund | uint64 | Refund counter | +| error | string | Error message if any | Note that the fields `memory`, `stack`, `returnData`, and `storage` have dynamic size and depending on the exact transaction they could grow large in size. This is specially true for `memory` which could blow up the trace size. It is recommended to keep them disabled unless they are explicitly required for a given use-case. @@ -52,18 +51,18 @@ The `4byteTracer` collects the function selectors of every function executed in The `callTracer` tracks all the call frames executed during a transaction, including depth 0. The result will be a nested list of call frames, resembling how EVM works. They form a tree with the top-level call at root and sub-calls as children of the higher levels. Each call frame has the following fields: -| field | type | description | -|---------|-------------|-------------------------------------------| -| type | string | CALL or CREATE | -| from | string | address | -| to | string | address | -| value | string | hex-encoded amount of value transfer | -| gas | string | hex-encoded gas provided for call | -| gasUsed | string | hex-encoded gas used during call | -| input | string | call data | -| output | string | return data | -| error | string | error, if any | -| calls | []callframe | list of sub-calls | +| field | type | description | +| ------- | ----------- | ------------------------------------ | +| type | string | CALL or CREATE | +| from | string | address | +| to | string | address | +| value | string | hex-encoded amount of value transfer | +| gas | string | hex-encoded gas provided for call | +| gasUsed | string | hex-encoded gas used during call | +| input | string | call data | +| output | string | return data | +| error | string | error, if any | +| calls | []callframe | list of sub-calls | Things to note about the call tracer: @@ -79,7 +78,7 @@ This tracer is noop. It returns an empty object and is only meant for testing th Executing a transaction requires the prior state, including account of sender and recipient, contracts that are called during execution, etc. The `prestateTracer` replays the tx and tracks every part of state that is touched. This is similar to the concept of a [stateless witness](https://ethresear.ch/t/the-stateless-client-concept/172), the difference being this tracer doesn't return any cryptographic proof, rather only the trie leaves. The result is an object. The keys are addresses of accounts. The value is an object with the following fields: | field | type | description | -|---------|-------------------|-------------------------------| +| ------- | ----------------- | ----------------------------- | | balance | string | balance in Wei | | nonce | uint64 | nonce | | code | string | hex-encoded bytecode | diff --git a/content/docs/developers/dapp-developer/custom-tracer.md b/content/docs/developers/dapp-developer/custom-tracer.md index 231760a4c6..a025c87dcd 100644 --- a/content/docs/developers/dapp-developer/custom-tracer.md +++ b/content/docs/developers/dapp-developer/custom-tracer.md @@ -11,42 +11,41 @@ Transaction traces include the complete status of the EVM at every point during ### A simple filter -Filters are Javascript functions that select information from the trace to persist and discard based on some conditions. The following Javascript function returns only the sequence of opcodes executed by the transaction as a comma-separated list. The function could be written directly in the Javascript console, but it is cleaner to write it in a separate re-usable file and load it into the console. +Filters are Javascript functions that select information from the trace to persist and discard based on some conditions. The following Javascript function returns only the sequence of opcodes executed by the transaction as a comma-separated list. The function could be written directly in the Javascript console, but it is cleaner to write it in a separate re-usable file and load it into the console. 1. Create a file, `filterTrace_1.js`, with this content: ```javascript - - tracer = function(tx) { - return debug.traceTransaction(tx, {tracer: + tracer = function (tx) { + return debug.traceTransaction(tx, { + tracer: '{' + - 'retVal: [],' + - 'step: function(log,db) {this.retVal.push(log.getPC() + ":" + log.op.toString())},' + - 'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' + - 'result: function(ctx,db) {return this.retVal}' + + 'retVal: [],' + + 'step: function(log,db) {this.retVal.push(log.getPC() + ":" + log.op.toString())},' + + 'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' + + 'result: function(ctx,db) {return this.retVal}' + '}' - }) // return debug.traceTransaction ... - } // tracer = function ... - + }); // return debug.traceTransaction ... + }; // tracer = function ... ``` 2. Run the [JavaScript console](https://geth.ethereum.org/docs/interface/javascript-console). - 3. Get the hash of a recent transaction from a node or block explorer. 4. Run this command to run the script: ```javascript - loadScript("filterTrace_1.js") + loadScript('filterTrace_1.js'); ``` 5. Run the tracer from the script. Be patient, it could take a long time. ```javascript - tracer("") + tracer(''); ``` The bottom of the output looks similar to: + ```sh "3366:POP", "3367:JUMP", "1355:JUMPDEST", "1356:PUSH1", "1358:MLOAD", "1359:DUP1", "1360:DUP3", "1361:ISZERO", "1362:ISZERO", "1363:ISZERO", "1364:ISZERO", "1365:DUP2", "1366:MSTORE", "1367:PUSH1", "1369:ADD", "1370:SWAP2", "1371:POP", "1372:POP", "1373:PUSH1", @@ -56,10 +55,10 @@ Filters are Javascript functions that select information from the trace to persi 6. Run this line to get a more readable output with each string in its own line. ```javascript - console.log(JSON.stringify(tracer(""), null, 2)) + console.log(JSON.stringify(tracer(''), null, 2)); ``` -More information about the `JSON.stringify` function is available [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). +More information about the `JSON.stringify` function is available [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). The commands above worked by calling the same `debug.traceTransaction` function that was previously explained in [basic traces](https://geth.ethereum.org/docs/dapp/tracing), but with a new parameter, `tracer`. This parameter takes the JavaScript object formated as a string. In the case of the trace above, it is: @@ -71,6 +70,7 @@ The commands above worked by calling the same `debug.traceTransaction` function result: function(ctx,db) {return this.retVal} } ``` + This object has three member functions: - `step`, called for each opcode. @@ -86,21 +86,22 @@ The `step` function adds to `retVal` the program counter and the name of the opc For actual filtered tracing we need an `if` statement to only log relevant information. For example, to isolate the transaction's interaction with storage, the following tracer could be used: ```javascript -tracer = function(tx) { - return debug.traceTransaction(tx, {tracer: +tracer = function (tx) { + return debug.traceTransaction(tx, { + tracer: '{' + - 'retVal: [],' + - 'step: function(log,db) {' + - ' if(log.op.toNumber() == 0x54) ' + - ' this.retVal.push(log.getPC() + ": SLOAD");' + - ' if(log.op.toNumber() == 0x55) ' + - ' this.retVal.push(log.getPC() + ": SSTORE");' + - '},' + - 'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' + - 'result: function(ctx,db) {return this.retVal}' + + 'retVal: [],' + + 'step: function(log,db) {' + + ' if(log.op.toNumber() == 0x54) ' + + ' this.retVal.push(log.getPC() + ": SLOAD");' + + ' if(log.op.toNumber() == 0x55) ' + + ' this.retVal.push(log.getPC() + ": SSTORE");' + + '},' + + 'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' + + 'result: function(ctx,db) {return this.retVal}' + '}' - }) // return debug.traceTransaction ... -} // tracer = function ... + }); // return debug.traceTransaction ... +}; // tracer = function ... ``` The `step` function here looks at the opcode number of the op, and only pushes an entry if the opcode is `SLOAD` or `SSTORE` ([here is a list of EVM opcodes and their numbers](https://github.com/wolflo/evm-opcodes)). We could have used `log.op.toString()` instead, but it is faster to compare numbers rather than strings. @@ -120,7 +121,6 @@ The output looks similar to this: ] ``` - ### Stack Information The trace above reports the program counter (PC) and whether the program read from storage or wrote to it. That alone isn't particularly useful. To know more, the `log.stack.peek` function can be used to peek into the stack. `log.stack.peek(0)` is the stack top, `log.stack.peek(1)` the entry below it, etc. @@ -129,28 +129,28 @@ The values returned by `log.stack.peek` are Go `big.Int` objects. By default the #### Storage Information -The function below provides a trace of all the storage operations and their parameters. This gives a more complete picture of the program's interaction with storage. +The function below provides a trace of all the storage operations and their parameters. This gives a more complete picture of the program's interaction with storage. ```javascript -tracer = function(tx) { - return debug.traceTransaction(tx, {tracer: +tracer = function (tx) { + return debug.traceTransaction(tx, { + tracer: '{' + - 'retVal: [],' + - 'step: function(log,db) {' + - ' if(log.op.toNumber() == 0x54) ' + - ' this.retVal.push(log.getPC() + ": SLOAD " + ' + - ' log.stack.peek(0).toString(16));' + - ' if(log.op.toNumber() == 0x55) ' + - ' this.retVal.push(log.getPC() + ": SSTORE " +' + - ' log.stack.peek(0).toString(16) + " <- " +' + - ' log.stack.peek(1).toString(16));' + - '},' + - 'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' + - 'result: function(ctx,db) {return this.retVal}' + + 'retVal: [],' + + 'step: function(log,db) {' + + ' if(log.op.toNumber() == 0x54) ' + + ' this.retVal.push(log.getPC() + ": SLOAD " + ' + + ' log.stack.peek(0).toString(16));' + + ' if(log.op.toNumber() == 0x55) ' + + ' this.retVal.push(log.getPC() + ": SSTORE " +' + + ' log.stack.peek(0).toString(16) + " <- " +' + + ' log.stack.peek(1).toString(16));' + + '},' + + 'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' + + 'result: function(ctx,db) {return this.retVal}' + '}' - }) // return debug.traceTransaction ... -} // tracer = function ... - + }); // return debug.traceTransaction ... +}; // tracer = function ... ``` The output is similar to: @@ -176,35 +176,36 @@ storage, so here we can't. The solution is to have a flag, `afterSload`, which is only true in the opcode right after an `SLOAD`, when we can see the result at the top of the stack. ```javascript -tracer = function(tx) { - return debug.traceTransaction(tx, {tracer: +tracer = function (tx) { + return debug.traceTransaction(tx, { + tracer: '{' + - 'retVal: [],' + - 'afterSload: false,' + - 'step: function(log,db) {' + - ' if(this.afterSload) {' + - ' this.retVal.push(" Result: " + ' + - ' log.stack.peek(0).toString(16)); ' + - ' this.afterSload = false; ' + - ' } ' + - ' if(log.op.toNumber() == 0x54) {' + - ' this.retVal.push(log.getPC() + ": SLOAD " + ' + - ' log.stack.peek(0).toString(16));' + - ' this.afterSload = true; ' + - ' } ' + - ' if(log.op.toNumber() == 0x55) ' + - ' this.retVal.push(log.getPC() + ": SSTORE " +' + - ' log.stack.peek(0).toString(16) + " <- " +' + - ' log.stack.peek(1).toString(16));' + - '},' + - 'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' + - 'result: function(ctx,db) {return this.retVal}' + + 'retVal: [],' + + 'afterSload: false,' + + 'step: function(log,db) {' + + ' if(this.afterSload) {' + + ' this.retVal.push(" Result: " + ' + + ' log.stack.peek(0).toString(16)); ' + + ' this.afterSload = false; ' + + ' } ' + + ' if(log.op.toNumber() == 0x54) {' + + ' this.retVal.push(log.getPC() + ": SLOAD " + ' + + ' log.stack.peek(0).toString(16));' + + ' this.afterSload = true; ' + + ' } ' + + ' if(log.op.toNumber() == 0x55) ' + + ' this.retVal.push(log.getPC() + ": SSTORE " +' + + ' log.stack.peek(0).toString(16) + " <- " +' + + ' log.stack.peek(1).toString(16));' + + '},' + + 'fault: function(log,db) {this.retVal.push("FAULT: " + JSON.stringify(log))},' + + 'result: function(ctx,db) {return this.retVal}' + '}' - }) // return debug.traceTransaction ... -} // tracer = function ... + }); // return debug.traceTransaction ... +}; // tracer = function ... ``` -The output now contains the result in the line that follows the `SLOAD`. +The output now contains the result in the line that follows the `SLOAD`. ```javascript [ @@ -229,64 +230,55 @@ So the storage has been treated as if there are only 2256 cells. Howe However, `log.contract.getAddress()` returns an array of bytes. To convert this to the familiar hexadecimal representation of Ethereum addresses, `this.byteHex()` and `array2Hex()` can be used. ```javascript -tracer = function(tx) { - return debug.traceTransaction(tx, {tracer: +tracer = function (tx) { + return debug.traceTransaction(tx, { + tracer: '{' + - 'retVal: [],' + - 'afterSload: false,' + - 'callStack: [],' + - - 'byte2Hex: function(byte) {' + - ' if (byte < 0x10) ' + - ' return "0" + byte.toString(16); ' + - ' return byte.toString(16); ' + - '},' + - - 'array2Hex: function(arr) {' + - ' var retVal = ""; ' + - ' for (var i=0; i