diff options
-rw-r--r-- | packages/dev-tools-pages/ts/pages/coverage.tsx | 2 | ||||
-rw-r--r-- | packages/dev-tools-pages/ts/pages/profiler.tsx | 4 | ||||
-rw-r--r-- | packages/dev-tools-pages/ts/pages/trace.tsx | 10 | ||||
-rw-r--r-- | packages/website/md/docs/sol_coverage/installation.md | 2 | ||||
-rw-r--r-- | packages/website/md/docs/sol_coverage/introduction.md | 2 | ||||
-rw-r--r-- | packages/website/md/docs/sol_coverage/usage.md | 26 | ||||
-rw-r--r-- | packages/website/md/docs/sol_profiler/installation.md | 2 | ||||
-rw-r--r-- | packages/website/md/docs/sol_profiler/usage.md | 30 | ||||
-rw-r--r-- | packages/website/md/docs/sol_trace/installation.md | 6 | ||||
-rw-r--r-- | packages/website/md/docs/sol_trace/introduction.md | 2 | ||||
-rw-r--r-- | packages/website/md/docs/sol_trace/usage.md | 36 |
11 files changed, 67 insertions, 55 deletions
diff --git a/packages/dev-tools-pages/ts/pages/coverage.tsx b/packages/dev-tools-pages/ts/pages/coverage.tsx index de61a4042..dc1f66462 100644 --- a/packages/dev-tools-pages/ts/pages/coverage.tsx +++ b/packages/dev-tools-pages/ts/pages/coverage.tsx @@ -128,7 +128,7 @@ const artifactAdapter = new SolCompilerArtifactAdapter(artifactsDir, contractsDi {`import { TruffleArtifactAdapter } from '@0x/sol-trace'; const projectRoot = '.'; -const solcVersion = '0.4.24'; +const solcVersion = '0.5.0'; const artifactAdapter = new TruffleArtifactAdapter(projectRoot, solcVersion);`} </Code> </TabBlock> diff --git a/packages/dev-tools-pages/ts/pages/profiler.tsx b/packages/dev-tools-pages/ts/pages/profiler.tsx index 4ce69ea7b..4af0dd851 100644 --- a/packages/dev-tools-pages/ts/pages/profiler.tsx +++ b/packages/dev-tools-pages/ts/pages/profiler.tsx @@ -125,7 +125,7 @@ const artifactAdapter = new SolCompilerArtifactAdapter(artifactsDir, contractsDi {`import { TruffleArtifactAdapter } from '@0x/sol-trace'; const projectRoot = '.'; -const solcVersion = '0.4.24'; +const solcVersion = '0.5.0'; const artifactAdapter = new TruffleArtifactAdapter(projectRoot, solcVersion);`} </Code> </TabBlock> @@ -146,7 +146,7 @@ const artifactAdapter = new YourCustomArtifactsAdapter(...);`} <Breakout> <Code language="javascript"> {`import { ProviderEngine, RpcSubprovider } from 'web3-provider-engine'; -import { ProfilerSubprovider } from '@0x/sol-coverage'; +import { ProfilerSubprovider } from '@0x/sol-profiler'; const defaultFromAddress = "..."; // Some ethereum address with test funds const profilerSubprovider = new ProfilerSubprovider(artifactAdapter, defaultFromAddress); diff --git a/packages/dev-tools-pages/ts/pages/trace.tsx b/packages/dev-tools-pages/ts/pages/trace.tsx index 465d995b5..abfac45dd 100644 --- a/packages/dev-tools-pages/ts/pages/trace.tsx +++ b/packages/dev-tools-pages/ts/pages/trace.tsx @@ -95,7 +95,7 @@ const artifactAdapter = new SolCompilerArtifactAdapter(artifactsDir, contractsDi {`import { TruffleArtifactAdapter } from '@0x/sol-trace'; const projectRoot = '.'; -const solcVersion = '0.4.24'; +const solcVersion = '0.5.0'; const artifactAdapter = new TruffleArtifactAdapter(projectRoot, solcVersion);`} </Code> </TabBlock> @@ -110,19 +110,19 @@ const artifactAdapter = new YourCustomArtifactsAdapter(...);`} </Tabs> <p> Now that we have an <InlineCode>artifactAdapter</InlineCode>, we can create a{' '} - <InlineCode>TraceSubprovider</InlineCode> and append it to our provider engine. + <InlineCode>revertTraceSubprovider</InlineCode> and append it to our provider engine. </p> <Breakout> <Code language="javascript"> {`import { ProviderEngine, RpcSubprovider } from 'web3-provider-engine'; -import { TraceSubprovider } from '@0x/sol-coverage'; +import { RevertTraceSubprovider } from '@0x/sol-trace'; const defaultFromAddress = "..."; // Some ethereum address with test funds -const traceSubprovider = new TraceSubprovider(artifactAdapter, defaultFromAddress); +const revertTraceSubprovider = new RevertTraceSubprovider(artifactAdapter, defaultFromAddress); const providerEngine = new ProviderEngine(); -providerEngine.addProvider(traceSubprovider); +providerEngine.addProvider(revertTraceSubprovider); providerEngine.addProvider(new RpcSubprovider({rpcUrl: 'http://localhost:8545'})); providerEngine.start();`} </Code> diff --git a/packages/website/md/docs/sol_coverage/installation.md b/packages/website/md/docs/sol_coverage/installation.md index c7aaf07e9..7c9840ab8 100644 --- a/packages/website/md/docs/sol_coverage/installation.md +++ b/packages/website/md/docs/sol_coverage/installation.md @@ -1,7 +1,7 @@ **Install** ```bash -yarn add @0x/sol-coverage +yarn add -D @0x/sol-coverage ``` **Import** diff --git a/packages/website/md/docs/sol_coverage/introduction.md b/packages/website/md/docs/sol_coverage/introduction.md index 3214e93a9..f21f8ecbe 100644 --- a/packages/website/md/docs/sol_coverage/introduction.md +++ b/packages/website/md/docs/sol_coverage/introduction.md @@ -1 +1 @@ -Welcome to the [sol-coverage](https://github.com/0xProject/0x-monorepo/tree/development/packages/sol-coverage) documentation! Sol-coverage is a Solidity coverage tool for your smart contract tests. +Welcome to the [sol-coverage](https://github.com/0xProject/0x-monorepo/tree/development/packages/sol-coverage) documentation! Sol-coverage is a Solidity coverage tool. diff --git a/packages/website/md/docs/sol_coverage/usage.md b/packages/website/md/docs/sol_coverage/usage.md index dd3cdf597..9f9913d28 100644 --- a/packages/website/md/docs/sol_coverage/usage.md +++ b/packages/website/md/docs/sol_coverage/usage.md @@ -1,4 +1,4 @@ -Sol-coverage uses transaction traces in order to figure out which lines of Solidity source code have been covered by your tests. In order for it to gather these traces, you must add the `CoverageSubprovider` to the [ProviderEngine](https://github.com/MetaMask/provider-engine) instance you use when running your Solidity tests. If you're unfamiliar with ProviderEngine, please read the [Web3 Provider explained](https://0x.org/wiki#Web3-Provider-Explained) wiki article. +Sol-coverage uses transaction traces in order to figure out which lines of Solidity source code have been covered by your tests. In order for it to gather these traces, you must add the `CoverageSubprovider` to the [ProviderEngine](https://github.com/MetaMask/provider-engine) instance you use when running your Solidity tests. If you're unfamiliar with `ProviderEngine`, please read the [Web3 Provider explained](https://0x.org/wiki#Web3-Provider-Explained) wiki article. The CoverageSubprovider eavesdrops on the `eth_sendTransaction` and `eth_call` RPC calls and collects traces after each call using `debug_traceTransaction`. `eth_call`'s' don't generate traces - so we take a snapshot, re-submit it as a transaction, get the trace and then revert the snapshot. @@ -12,9 +12,8 @@ If you are generating your artifacts with [@0x/sol-compiler](https://0x.org/docs ```typescript import { SolCompilerArtifactsAdapter } from '@0x/sol-coverage'; -const artifactsPath = 'src/artifacts'; -const contractsPath = 'src/contracts'; -const artifactsAdapter = new SolCompilerArtifactsAdapter(artifactsPath, contractsPath); +// Both artifactsDir and contractsDir are optional and will be fetched from compiler.json if not passed in +const artifactAdapter = new SolCompilerArtifactAdapter(artifactsDir, contractsDir); ``` ### Truffle @@ -23,8 +22,9 @@ If your project is using [Truffle](https://truffleframework.com/), we've written ```typescript import { TruffleArtifactAdapter } from '@0x/sol-coverage'; -const contractsPath = 'src/contracts'; -const artifactAdapter = new TruffleArtifactAdapter(contractsDir); +const projectRoot = '.'; +const solcVersion = '0.5.0'; +const artifactAdapter = new TruffleArtifactAdapter(projectRoot, solcVersion); ``` Because truffle artifacts don't have all the data we need - we actually will recompile your contracts under the hood. That's why you don't need to pass an `artifactsPath`. @@ -32,7 +32,13 @@ Because truffle artifacts don't have all the data we need - we actually will rec ### Other framework/toolset You'll need to write your own artifacts adapter. It should extend `AbstractArtifactsAdapter`. -Look at the code of the two adapters above for examples. + +```typescript +import { AbstractArtifactAdapter } from '@0x/sol-trace'; + +class YourCustomArtifactsAdapter extends AbstractArtifactAdapter {...}; +const artifactAdapter = new YourCustomArtifactsAdapter(...); +``` ### Usage @@ -41,16 +47,14 @@ import { CoverageSubprovider } from '@0x/sol-coverage'; import ProviderEngine = require('web3-provider-engine'); const provider = new ProviderEngine(); - -const artifactsPath = 'src/artifacts'; -const contractsPath = 'src/contracts'; -const networkId = 50; // Some calls might not have `from` address specified. Nevertheless - transactions need to be submitted from an address with at least some funds. defaultFromAddress is the address that will be used to submit those calls as transactions from. const defaultFromAddress = '0x5409ed021d9299bf6814279a6a1411a7e866a631'; const isVerbose = true; const coverageSubprovider = new CoverageSubprovider(artifactsAdapter, defaultFromAddress, isVerbose); provider.addProvider(coverageSubprovider); +// Add all your other providers +provider.start(); ``` After your test suite is complete (e.g in the Mocha global `after` hook), you'll need to call: diff --git a/packages/website/md/docs/sol_profiler/installation.md b/packages/website/md/docs/sol_profiler/installation.md index be9a365f5..e29ac5ae7 100644 --- a/packages/website/md/docs/sol_profiler/installation.md +++ b/packages/website/md/docs/sol_profiler/installation.md @@ -1,7 +1,7 @@ **Install** ```bash -yarn add @0x/sol-profiler +yarn add -D @0x/sol-profiler ``` **Import** diff --git a/packages/website/md/docs/sol_profiler/usage.md b/packages/website/md/docs/sol_profiler/usage.md index 35ea140da..f9bab7ebf 100644 --- a/packages/website/md/docs/sol_profiler/usage.md +++ b/packages/website/md/docs/sol_profiler/usage.md @@ -1,4 +1,4 @@ -Sol-profiler uses transaction traces in order to figure out which lines of Solidity source code have been covered by your tests. In order for it to gather these traces, you must add the `ProfilerSubprovider` to the [ProviderEngine](https://github.com/MetaMask/provider-engine) instance you use when running your Solidity tests. If you're unfamiliar with ProviderEngine, please read the [Web3 Provider explained](https://0x.org/wiki#Web3-Provider-Explained) wiki article. +Sol-profiler uses transaction traces in order to figure out which lines of Solidity source code have been covered by your tests. In order for it to gather these traces, you must add the `ProfilerSubprovider` to the [ProviderEngine](https://github.com/MetaMask/provider-engine) instance you use when running your Solidity tests. If you're unfamiliar with `ProviderEngine`, please read the [Web3 Provider explained](https://0x.org/wiki#Web3-Provider-Explained) wiki article. The ProfilerSubprovider eavesdrops on the `eth_sendTransaction` and `eth_call` RPC calls and collects traces after each call using `debug_traceTransaction`. `eth_call`'s' don't generate traces - so we take a snapshot, re-submit it as a transaction, get the trace and then revert the snapshot. @@ -12,9 +12,8 @@ If you are generating your artifacts with [@0x/sol-compiler](https://0x.org/docs ```typescript import { SolCompilerArtifactsAdapter } from '@0x/sol-profiler'; -const artifactsPath = 'src/artifacts'; -const contractsPath = 'src/contracts'; -const artifactsAdapter = new SolCompilerArtifactsAdapter(artifactsPath, contractsPath); +// Both artifactsDir and contractsDir are optional and will be fetched from compiler.json if not passed in +const artifactAdapter = new SolCompilerArtifactAdapter(artifactsDir, contractsDir); ``` ### Truffle @@ -23,8 +22,9 @@ If your project is using [Truffle](https://truffleframework.com/), we've written ```typescript import { TruffleArtifactAdapter } from '@0x/sol-profiler'; -const contractsPath = 'src/contracts'; -const artifactAdapter = new TruffleArtifactAdapter(contractsDir); +const projectRoot = '.'; +const solcVersion = '0.5.0'; +const artifactAdapter = new TruffleArtifactAdapter(projectRoot, solcVersion); ``` Because truffle artifacts don't have all the data we need - we actually will recompile your contracts under the hood. That's why you don't need to pass an `artifactsPath`. @@ -32,7 +32,13 @@ Because truffle artifacts don't have all the data we need - we actually will rec ### Other framework/toolset You'll need to write your own artifacts adapter. It should extend `AbstractArtifactsAdapter`. -Look at the code of the two adapters above for examples. + +```typescript +import { AbstractArtifactAdapter } from '@0x/sol-trace'; + +class YourCustomArtifactsAdapter extends AbstractArtifactAdapter {...}; +const artifactAdapter = new YourCustomArtifactsAdapter(...); +``` ### Usage @@ -41,22 +47,20 @@ import { ProfilerSubprovider } from '@0x/sol-profiler'; import ProviderEngine = require('web3-provider-engine'); const provider = new ProviderEngine(); - -const artifactsPath = 'src/artifacts'; -const contractsPath = 'src/contracts'; -const networkId = 50; // Some calls might not have `from` address specified. Nevertheless - transactions need to be submitted from an address with at least some funds. defaultFromAddress is the address that will be used to submit those calls as transactions from. const defaultFromAddress = '0x5409ed021d9299bf6814279a6a1411a7e866a631'; const isVerbose = true; const profilerSubprovider = new ProfilerSubprovider(artifactsAdapter, defaultFromAddress, isVerbose); provider.addProvider(profilerSubprovider); +// Add all your other providers +provider.start(); ``` After your test suite is complete (e.g in the Mocha global `after` hook), you'll need to call: ```typescript -await profilerSubprovider.writeProfilerAsync(); +await profilerSubprovider.writeProfilerOutputAsync(); ``` -This will create a `profiler.json` file in a `profiler` directory. This file has an [Istanbul format](https://github.com/gotwarlost/istanbul/blob/master/profiler.json.md) - so you can use it with any of the existing Istanbul reporters. +This will create a `coverage.json` file in a `coverage` directory. This file has an [Istanbul format](https://github.com/gotwarlost/istanbul/blob/master/profiler.json.md) - so you can use it with any of the existing Istanbul reporters. diff --git a/packages/website/md/docs/sol_trace/installation.md b/packages/website/md/docs/sol_trace/installation.md index 2f794b2f8..eb7bf08b8 100644 --- a/packages/website/md/docs/sol_trace/installation.md +++ b/packages/website/md/docs/sol_trace/installation.md @@ -1,17 +1,17 @@ **Install** ```bash -yarn add @0x/sol-trace +yarn add -D @0x/sol-trace ``` **Import** ```javascript -import { TraceSubprovider } from '@0x/sol-trace'; +import { RevertTraceSubprovider } from '@0x/sol-trace'; ``` or ```javascript -var TraceSubprovider = require('@0x/sol-trace').TraceSubprovider; +var RevertTraceSubprovider = require('@0x/sol-trace').RevertTraceSubprovider; ``` diff --git a/packages/website/md/docs/sol_trace/introduction.md b/packages/website/md/docs/sol_trace/introduction.md index 21fea764e..73f5c2bcd 100644 --- a/packages/website/md/docs/sol_trace/introduction.md +++ b/packages/website/md/docs/sol_trace/introduction.md @@ -1 +1 @@ -Welcome to the [sol-trace](https://github.com/0xProject/0x-monorepo/tree/development/packages/sol-trace) documentation! Sol-trace is a Solidity trace tool for your smart contract tests. +Welcome to the [sol-trace](https://github.com/0xProject/0x-monorepo/tree/development/packages/sol-trace) documentation! Sol-trace gives you a human-readable error stack trace when a revert happens in your Solidity code. diff --git a/packages/website/md/docs/sol_trace/usage.md b/packages/website/md/docs/sol_trace/usage.md index 516585683..e794d0f73 100644 --- a/packages/website/md/docs/sol_trace/usage.md +++ b/packages/website/md/docs/sol_trace/usage.md @@ -1,10 +1,10 @@ -Sol-trace uses transaction traces in order to figure out which lines of Solidity source code have been covered by your tests. In order for it to gather these traces, you must add the `TraceSubprovider` to the [ProviderEngine](https://github.com/MetaMask/provider-engine) instance you use when running your Solidity tests. If you're unfamiliar with ProviderEngine, please read the [Web3 Provider explained](https://0x.org/wiki#Web3-Provider-Explained) wiki article. +Sol-trace uses transaction traces to reconstruct the stack trace when reverts happen in Solidity. In order for it to gather these traces, you must add the `RevertTraceSubprovider` to the [ProviderEngine](https://github.com/MetaMask/provider-engine) instance you use when running your Solidity tests. If you're unfamiliar with `ProviderEngine`, please read the [Web3 Provider explained](https://0x.org/wiki#Web3-Provider-Explained) wiki article. -The TraceSubprovider eavesdrops on the `eth_sendTransaction` and `eth_call` RPC calls and collects traces after each call using `debug_traceTransaction`. `eth_call`'s' don't generate traces - so we take a snapshot, re-submit it as a transaction, get the trace and then revert the snapshot. +The `RevertTraceSubprovider` eavesdrops on the `eth_sendTransaction` and `eth_call` RPC calls and collects traces after each call using `debug_traceTransaction`. `eth_call`'s' don't generate traces - so we take a snapshot, re-submit it as a transaction, get the trace and then revert the snapshot. Trace subprovider needs some info about your contracts (`srcMap`, `bytecode`). It gets that info from your project's artifacts. Some frameworks have their own artifact format. Some artifact formats don't actually contain all the neccessary data. -In order to use `TraceSubprovider` with your favorite framework you need to pass an `artifactsAdapter` to it. +In order to use `RevertTraceSubprovider` with your favorite framework you need to pass an `artifactsAdapter` to it. ### Sol-compiler @@ -12,9 +12,8 @@ If you are generating your artifacts with [@0x/sol-compiler](https://0x.org/docs ```typescript import { SolCompilerArtifactsAdapter } from '@0x/sol-trace'; -const artifactsPath = 'src/artifacts'; -const contractsPath = 'src/contracts'; -const artifactsAdapter = new SolCompilerArtifactsAdapter(artifactsPath, contractsPath); +// Both artifactsDir and contractsDir are optional and will be fetched from compiler.json if not passed in +const artifactAdapter = new SolCompilerArtifactAdapter(artifactsDir, contractsDir); ``` ### Truffle @@ -23,8 +22,9 @@ If your project is using [Truffle](https://truffleframework.com/), we've written ```typescript import { TruffleArtifactAdapter } from '@0x/sol-trace'; -const contractsPath = 'src/contracts'; -const artifactAdapter = new TruffleArtifactAdapter(contractsDir); +const projectRoot = '.'; +const solcVersion = '0.5.0'; +const artifactAdapter = new TruffleArtifactAdapter(projectRoot, solcVersion); ``` Because truffle artifacts don't have all the data we need - we actually will recompile your contracts under the hood. That's why you don't need to pass an `artifactsPath`. @@ -32,25 +32,29 @@ Because truffle artifacts don't have all the data we need - we actually will rec ### Other framework/toolset You'll need to write your own artifacts adapter. It should extend `AbstractArtifactsAdapter`. -Look at the code of the two adapters above for examples. + +```typescript +import { AbstractArtifactAdapter } from '@0x/sol-trace'; + +class YourCustomArtifactsAdapter extends AbstractArtifactAdapter {...}; +const artifactAdapter = new YourCustomArtifactsAdapter(...); +``` ### Usage ```typescript -import { TraceSubprovider } from '@0x/sol-trace'; +import { RevertTraceSubprovider } from '@0x/sol-trace'; import ProviderEngine = require('web3-provider-engine'); const provider = new ProviderEngine(); - -const artifactsPath = 'src/artifacts'; -const contractsPath = 'src/contracts'; -const networkId = 50; // Some calls might not have `from` address specified. Nevertheless - transactions need to be submitted from an address with at least some funds. defaultFromAddress is the address that will be used to submit those calls as transactions from. const defaultFromAddress = '0x5409ed021d9299bf6814279a6a1411a7e866a631'; const isVerbose = true; -const traceSubprovider = new TraceSubprovider(artifactsAdapter, defaultFromAddress, isVerbose); +const revertTraceSubprovider = new RevertTraceSubprovider(artifactsAdapter, defaultFromAddress, isVerbose); -provider.addProvider(traceSubprovider); +provider.addProvider(revertTraceSubprovider); +// Add all your other providers +provider.start(); ``` Now when you run your tests, it should print out stack traces when encountering an error. |