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.
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
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
.
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.
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).
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
.
- 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 dependencies and build:
yarn
Launch a local hardhat node with all contracts deployed:
yarn start
There are two types of tests that can be run on the Solidity Emulator.
- Load binary rv64i test programs in Solidity and verify the execution result
- Collect step logs and proofs of a test program and replay them in Solidity, verify all accesses and proofs.
Run all tests:
forge test
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.
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.
The machine-solidity-step repository and all contributions are licensed under APACHE 2.0. Please review our LICENSE file.