remix-project/README.md

REMIX

Ethereum IDE and tools for the web

REMIX MODULES:

This repository contains 4 different modules:

remix-core

Provides:

code: {
    CodeManager: CodeManager,
    BreakpointManager: BreakpointManager
  },
  storage: {
    StorageViewer: StorageViewer,
    StorageResolver: StorageResolver
  },
  trace: {
    TraceManager: TraceManager
  }

TraceManager is a convenient way to access a VM Trace and resolve some value from it.

TraceManager() :

function resolveTrace(stepIndex, tx)

function init(stepIndex, tx)

function inRange(stepIndex, tx)

function isLoaded(stepIndex, tx)

function getLength(stepIndex, tx)

function accumulateStorageChanges(stepIndex, tx)

function getAddresses(stepIndex, tx)

function getCallDataAt(stepIndex, tx)

function getCallStackAt(stepIndex, tx)

function getStackAt(stepIndex, tx)

function getLastCallChangeSince(stepIndex, tx)

function getCurrentCalledAddressAt(stepIndex, tx)

function getContractCreationCode(stepIndex, tx)

function getMemoryAt(stepIndex, tx)

function getCurrentPC(stepIndex, tx)

function getReturnValue(stepIndex, tx)

function getCurrentStep(stepIndex, tx)

function getMemExpand(stepIndex, tx)

function getStepCost(stepIndex, tx)

function getRemainingGas(stepIndex, tx)

function getStepCost(stepIndex, tx)

function isCreationStep(stepIndex, tx)

function findStepOverBack(stepIndex, tx)

function findStepOverForward(stepIndex, tx)

function findStepOverBack(stepIndex, tx)

function findNextCall(stepIndex, tx)

function findStepOut(stepIndex, tx)

function checkRequestedStep(stepIndex, tx)

function waterfall(stepIndex, tx)

---

CodeManager(_traceManager) :

function getCode(stepIndex, tx) : Resolve the code of the given @arg stepIndex and trigger appropriate event

function resolveStep(address, cb) : Retrieve the code located at the given @arg address

function getFunctionFromStep(stepIndex, sourceMap, ast) : Retrieve the called function for the current vm step

function getInstructionIndex(address, step, callback) : Retrieve the instruction index of the given @arg step

function getFunctionFromPC(address, pc, sourceMap, ast) : Retrieve the called function for the given @arg pc and @arg address

---

BreakpointManager(_ethdebugger, _locationToRowConverter) :

function jumpNextBreakpoint(defaultToLimit) : start looking for the next breakpoint

function jumpPreviousBreakpoint(defaultToLimit) : start looking for the previous breakpoint

function jump(direction, defaultToLimit) : start looking for the previous or next breakpoint

function hasBreakpointAtLine((fileIndex, line) : check the given pair fileIndex/line against registered breakpoints

function hasBreakpoint() : return true if current manager has breakpoint

function add(sourceLocation) : add a new breakpoint to the manager

function remove(sourceLocation) : remove a breakpoint from the manager

---

StorageViewer(_context, _storageResolver, _traceManager) :

function storageRange(defaultToLimit) : return the storage for the current context (address and vm trace index)

function storageSlot(defaultToLimit) : return a slot value for the current context (address and vm trace index)

function isComplete(direction, defaultToLimit) : return True if the storage at @arg address is complete

function initialMappingsLocation((fileIndex, line) : return all the possible mappings locations for the current context (cached) do not return state changes during the current transaction

function mappingsLocation() : return all the possible mappings locations for the current context (cached) and current mapping slot. returns state changes during the current transaction

function extractMappingsLocationChanges(sourceLocation) : retrieve mapping location changes from the storage changes.

---

StorageResolver() :

function storageRange(tx, stepIndex, address, callback) : return the storage for the current context (address and vm trace index)

function initialPreimagesMappings(tx, stepIndex, address, callback) : return a slot value for the current context (address and vm trace index)

function storageSlot(slot, tx, stepIndex, address, callback) : return True if the storage at @arg address is complete

function isComplete(address) : return all the possible mappings locations for the current context (cached) do not return state changes during the current transaction

remix-lib

Provides:

{
    EventManager: EventManager,
    helpers: {
        trace: traceHelper,
        ui: uiHelper
    },
    vm: {
        Web3Providers: Web3Providers,
        DummyProvider: DummyProvider,
        Web3VMProvider: Web3VMProvider
    },
    SourceMappingDecoder: SourceMappingDecoder,
    SourceLocationTracker: SourceLocationTracker,
    init: init,
    util: util,
    AstWalker: AstWalker,
    global: global,
    ui: {
        styleGuide: styleGuide
    }
    }
}

remix-solidity

Provides:

{
    InternalCallTree: InternalCallTree,
    SolidityProxy: SolidityProxy,
    localDecoder: localDecoder,
    stateDecoder: stateDecoder,
    CodeAnalysis: CodeAnalysis
}

remix-debugger

Provides:

{
    ui: {
      Debugger: Debugger,
      VMdebugger: VMDebugger,
      BasicPanel: BasicPanel,
      TreeView: TreeView
    }
  }
}

REMIX WEBSITE:

Remix is avalaible at http://ethereum.github.io/remix.

Note that this repository hosts a debugger module. The Remix IDE repository is at https://github.com/ethereum/browser-solidity and an online version is at http://remix.ethereum.org.

You can use it either inside Mist or by connecting to geth or eth. Note that connecting to Geth does not work through https.

You'll have to run your own node using the following parameters:

DO NOT DO THIS IF geth/eth STORES PRIVATE KEYS External system might be able to access your node through the RPC server.

Using Geth:

geth --rpc --rpcapi 'web3,eth,debug' --rpcport 8545 --rpccorsdomain '*'

Using Eth:

eth -j --rpccorsdomain '*'

geth will run the rpc server on http://localhost:8545, remix uses by default this url.

Remix will use this instance of Geth to retrieve the transaction and the associated trace. This instance should only be used for debugging purposes. Never use features that could have an impact on your keys (do not unlock any keys, do not use this instance together with the wallet, do not activate the admin web3 API).

INSTALLATION:

Brief instructions to build for linux(Todo add other platforms) we will add detailed instructions later

Install eth or geth, npm and node.js (see https://docs.npmjs.com/getting-started/installing-node), then do:

• git clone https://github.com/ethereum/remix
• cd remix/remix-debugger
• npm install
• npm start

open remix/index.html in your browser.

TEST:

• For unit tests run npm test

• For local headless browser tests

  • run once to install selenium: npm run selenium-install
  • every time you want to run local browser tests, run: npm run test-browser

DEVELOPING:

Run npm run start_dev and open http://127.0.0.1:8080 in your browser.

Start developing and see your browser live reload when you save files

REMIX First Step:

Once remix is connected to a node, you will be able to debug transactions. There's two way of doing that:

• using a block number and a transaction index.
• using a transaction hash.

When loading the transaction succeed, the hash, from and to field will show up. Then the vm trace is loaded.

The debugger itself contains several controls that allow stepping over the trace and seing the current state of a selected step.

Slider and Stepping action:

The slider allows to move quickly from a state to another. Stepping actions are:

• Step Into Back
• Step Over Back
• Step Over Forward
• Step Into Forward
• Jump Next Call (this will select the next state that refers to a context changes - CALL, CALLCODE, DELEGATECALL, CREATE)

State Viewer:

The upper right panel contains basic informations about the current step:

• VMTraceStep: the index in the trace of the current step.
• Step
• Add memory
• Gas: gas used by this step
• Remaining gas: gas left
• Loaded address: the current code loaded, refers to the executing code.

The other 6 panels describe the current selected state:

• Instructions list: list of all the instruction that defines the current executing code.
• Stack
• Storage Changes
• Memory
• Call Data$
• Call Stack

CODING STYLE:

Remix uses npm coding style: https://docs.npmjs.com/misc/coding-style Please be sure your code is compliant with this coding standard before sending PR. There's on the above page a bunch of links that propose integration with developer tools (Emacs, Atom, ...). You can also run 'npm run test' to check your local repository against the coding style.

CONTRIBUTING

Everyone is very welcome to contribute on the codebase of Remix. Please reach us in gitter: https://gitter.im/ethereum/remix The easiest way to work on remix-debugger or remix-solidity is to pull the browser-solidity (Remix IDE) repository ( https://github.com/ethereum/browser-solidity ) which has a strong Remix integration. then in browser-solidity, execute npm install, npm pull remix, npm link remix. then npm run build && npm run serve to start a new Remix IDE instance (you can browse 127.0.0.1:8080)

To interact with the Remix code:

1. For static analysis: compile a new contact, click on the Analysis, the content of this tab is provided by the remix-solidity/analysis library

2. For Debugging: compile a new contact, deploy it (Create button in the run tab), in the remix IDE terminal a transaction should appear, click on Debug. The Debugger tab get the focus, the content if this tab is provided by the remix-debugger library.

3. For Decoding local and state variable: follow 2), then expand (is not already) the Solidity State and Solidity Locals panels, the content of thoses panel are provided by the remix-solidity/decoder library.

Remainder: the Remix repository contains a bunch of tool used to debug transaction, one of this tool is a debugger. The Browser-solidity repository contains the Remix IDE (online version remix.ethereum.org), which make use of the Remix repository for the debugging features.