CLI Usage
Last updated
Was this helpful?
Last updated
Was this helpful?
Scribble accepts normal Solidity files and has 3 output modes:
In flat
mode, all the dependencies of the target Solidity file(s) are bunched up and emitted as one giant blob of Solidity. This is useful for submitting the instrumented code to services like ` .
In files
mode, for each file foo.sol
containing contracts with scribble annotations, Scribble emits a foo.instrumented.sol
in the same directory and leaves the original unchanged. Note that scribble
may instrument files that are not specified on the command line, but are reachable by a chain of imports.
In json
mode, Scribble behaves similarly to flat
mode, in that it first flattens all the files necessary to compile the target into one flat Solidity blob. Afterwards, it runs solc
on that flat solidity blob and outputs the of the used compiler version.
We provide examples for the most common use cases. For all examples assume we have the following 2 solidity files in the current directory:
Base.sol
Foo.sol
If we want to instrument Foo.sol
(and any required imports) and emit it all into a single Foo.flat.sol
we can run:
Note that both the input and the output can be --
which would make Scribble work with stdin
/stdout
. The below command uses stdin
/stdout
to do the same thing as the previous command:
The files
mode is more involved and is intended for interoperability with various user testing and deployment environments. To instrument Foo.sol
and Base.sol
in-place we run:
After running this we will have 2 new files in the directory - Foo.instrumented.sol
and __scribble_ReentrancyUtils.sol
. Foo.instrumented.sol
is the instrumented version of Foo.sol
, and __scribble_ReentrancyUtils.sol
contains a helper contract.
Emitting an instrumented JSON artifact is almost the same as running in flat-mode:
--output
option doesn't have any effect with --output-mode files
.
--utils-output-path
allows to specify a different directory for the __scribble_ReentrancyUtils.sol
file. It only works with --output-mode files
. It doesn't have any effect with --output-mode flat
.
If --no-assert
is omitted, then there is an assert(false)
emitted in the instrumented code every time an invariant is violated. For longer-running fuzzing campaigns, it may be useful to keep running the code even after a property is violated. In those cases only an AssertionFailed(string)
event is emitted, which can be caught by tools such as Dili-Faas/MythX/Mythril/Harvey.
With the --compiler-kind
option you have the choice between using a binary compiler (native
) or a WASM based compiler (wasm
). If a binary compiler is not available for your environment (e.g. M1 Macs) please use `--compiler-kind wasm`.
When instrumenting in-place (i.e. with the option --output-mode files --arm
) scribble will always emit an instrumentation metadata file. By default this is placed in the root of the current project tree. The root is defined as the closest directory with a node_modules/
folder in it. If a root folder is not detected, scribble will throw an error requiring you to supply a location for the metadata with the `--instrumentation-metadata-file` option.
Note that the instrumented Foo.instrumented.sol
still imports the original Base.sol
. To actually use the instrumented files in this mode, you have to swap them with the originals, before compiling/testing/deploying. You can do so manually, or automatically with the the --arm
and --disarm
options to scribble (more details ).
The generated Foo.flat.json
contains the compiled version of the flattened instrumented solidity, along with some extra info. (For more details see ).
You will get an error if you pass with missing to scribble
. Scribble needs the source code to fill in missing information in the AST in certain compiler versions.