Giter VIP home page Giter VIP logo

machine-solidity-step's Introduction

Cartesi RISC-V Solidity Emulator

The Cartesi RISC-V Solidity Emulator is the on-chain host implementation of the Cartesi Machine Specification. The libraries and contracts are written in Solidity, and the testing scripts are written in Solidity (with the help of Foundry).

For Cartesi's design to work, this implementation must have the exact transition function as the off-chain Cartesi RISC-V Emulator, meaning that if given the same initial state (s[i]) both implementation's step functions should reach a bit by bit consistent state s[i + 1].

Since the cost of storing a full Cartesi Machine state within the blockchain is prohibitive, all machine states are represented in the blockchain as cryptographic hashes. The contents of those states and memory represented by those hashes are only known off-chain.

Cartesi uses Merkle tree operations and properties to ensure that the blockchain has the ability to correctly verify a state transition without having full state-access. However, the RISC-V Solidity emulator abstracts these operations away and acts as if it knows the full contents of a machine state - it uses the Memory Manager interface to fetch or write any necessary words to memory.

UArch State

The IUArchState.State struct is consumed by the RISC-V Solidity emulator as if the entire state content was available - since the off and on-chain emulators match down to the order in which accesses are logged. When a dispute arises, Alice packs her off-chain state access log referent to the disagreement step in an struct IUArchState.State, which will guide the execution of a step (i.e state transition function).

The UArchState contract implements the RISC-V Solidity emulator all necessary read and write operations.

It also makes sure that all accesses performed by the step function match the ones provided by Alice and are consistent with the Merkle proofs provided by her. If that is not the case, Alice loses the dispute.

Step function

step is the previously mentioned state transition function, it is meant to take the machine from state s[i] to state[i + 1], using the AccessLogs as an assistant. The step function receives IUArchState.State - which should have been populated with the AccessLogs generated by the emulator off-chain and returns an Exit code signaling the result of its execution.

During a step execution, every necessary read or write (be it to memory, registers etc) is processed and verified by the MemoryAccessLog.

Execute Instruction

The UArchExecuteInsn contract consists of the machine instruction logic, such as decoding, executing, opcode matching and etc. The Solidity implementation is converted from the Cpp implementation directly through a translator script. This is to assure that the implementations in two languages are identical. Yet the low level differences in two languages are wrapped in the Compatibility Layer.

Compatibility Layer

The UArchCompat contract is taking care of all the differences in the two implementations. Ranging from programming languages (Cpp versus Solidity) to architectural differences (RISC-V versus EVM).

Getting Started

Run make help for a list of target options. Here are some of them:

Cleaning targets:
  clean                      - clean the cache artifacts
Generic targets:
* all                        - build solidity code. To build from a clean clone, run: make submodules downloads all
  build                      - build solidity code
  dep                        - install npm packages
  depclean                   - remove npm packages
  deploy                     - deploy to local node
  generate                   - generate solidity code from cpp and template
  test                       - test both binary files and log files
  coverage                   - generate coverage report for html view

Obs: Some make targets require the installation of the node.js packages. This can be done with yarn install or make dep.

Requirements

  • Foundry 0.2.0
  • GNU Make >= 3.81
  • Lua 5.3.5
  • Yarn 1.22.19

Different version of tools maybe working but is not guaranteed.

Install

Install dependencies and build:

yarn

Launch a local hardhat node with all contracts deployed:

yarn start

Run tests

There are two types of tests that can be run on the Solidity Emulator.

  1. Load binary rv64i test programs in Solidity and verify the execution result
  2. Collect step logs and proofs of a test program and replay them in Solidity, verify all accesses and proofs.

Run all tests:

forge test

Generate coverage report

To generate a test coverage, run:

forge coverage

To generate a pretty visual report with html, run:

make coverage

And then open report/contracts/index.html with your browser.

Contributing

Thank you for your interest in Cartesi! Head over to our Contributing Guidelines for instructions on how to sign our Contributors Agreement and get started with Cartesi!

Please note we have a Code of Conduct, please follow it in all your interactions with the project.

License

The machine-solidity-step repository and all contributions are licensed under APACHE 2.0. Please review our LICENSE file.

machine-solidity-step's People

Contributors

augustoteixeira avatar colinsteil avatar erickmoura avatar felipeargento avatar gbarros avatar gligneul avatar miltonjonat avatar stephenctw avatar tuler avatar vfusco avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.