diff options
Diffstat (limited to 'packages/website/md/docs/sol_trace/usage.md')
-rw-r--r-- | packages/website/md/docs/sol_trace/usage.md | 62 |
1 files changed, 0 insertions, 62 deletions
diff --git a/packages/website/md/docs/sol_trace/usage.md b/packages/website/md/docs/sol_trace/usage.md deleted file mode 100644 index d117a0faf..000000000 --- a/packages/website/md/docs/sol_trace/usage.md +++ /dev/null @@ -1,62 +0,0 @@ -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 `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 `RevertTraceSubprovider` with your favorite framework you need to pass an `artifactsAdapter` to it. - -### Sol-compiler - -If you are generating your artifacts with [@0x/sol-compiler](https://0x.org/docs/sol-compiler) you can use the `SolCompilerArtifactsAdapter` we've implemented for you. - -```typescript -import { SolCompilerArtifactsAdapter } from '@0x/sol-trace'; -// Both artifactsDir and contractsDir are optional and will be fetched from compiler.json if not passed in -const artifactAdapter = new SolCompilerArtifactAdapter(artifactsDir, contractsDir); -``` - -### Truffle - -If your project is using [Truffle](https://truffleframework.com/), we've written a `TruffleArtifactsAdapter`for you. - -```typescript -import { TruffleArtifactAdapter } from '@0x/sol-trace'; -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`. - -### Other framework/toolset - -You'll need to write your own artifacts adapter. It should extend `AbstractArtifactsAdapter`. - -```typescript -import { AbstractArtifactAdapter } from '@0x/sol-trace'; - -class YourCustomArtifactsAdapter extends AbstractArtifactAdapter {...}; -const artifactAdapter = new YourCustomArtifactsAdapter(...); -``` - -### Usage - -```typescript -import { RevertTraceSubprovider } from '@0x/sol-trace'; -import ProviderEngine = require('web3-provider-engine'); - -const provider = new ProviderEngine(); -// 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 revertTraceSubprovider = new RevertTraceSubprovider(artifactsAdapter, defaultFromAddress, isVerbose); - -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. - -Use [Geth](https://github.com/ethereum/go-ethereum) as a backing node. We recommend using our [Devnet Docker container](https://hub.docker.com/r/0xorg/devnet) which sets up a Geth node for testing purposes. Ganache support is a [work in progress](https://github.com/0xProject/0x-monorepo/issues/1520). |