• This repository has been archived on 02/Dec/2021
  • Stars
    star
    175
  • Rank 218,059 (Top 5 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created almost 7 years ago
  • Updated almost 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Hyperledger Fabric EVM chaincode

This project has been archived for lack of interest within the community.

This is the project for the Hyperledger Fabric chaincode, integrating the Burrow EVM. At its essence, this project enables one to use the Hyperledger Fabric permissioned blockchain platform to interact with Ethereum smart contracts written in an EVM compatible language such as Solidity or Vyper.

The integration is achieved through the EVM chaincode (EVMCC) and Fab3. The EVMCC wraps the Hyperledger Burrow EVM package in a Go chaincode shim and maps the various methods between the peer and the EVM itself. The EVMCC acts as the smart contract runtime and stores the deployed contract code on the ledger under the evmcc namespace.

The second piece is Fab3, a web3 provider, which is a proxy that implements a subset of the Ethereum compliant JSON RPC interfaces, so that users could use tools such as Web3.js to interact with smart contracts running in the Fabric EVM. Using the Fabric GO SDK, Fab3 is able to communicate with the Fabric network to interact with the EVMCC. Without Fab3, users can still interact with the EVMCC using the Fabric APIs.

Used together, the EVMCC and Fab3 recreates the Ethereum smart contract runtime and developer experience. Applications that make use of the Ethereum JSON RPC API and EVM smart contracts should be able to stay unchanged and can be brought to use with Hyperledger Fabric.

EndToEnd

Table of Contents

We hang out in the #fabric-evm channel. We are always interested in feedback and help in development and testing! For more information about contributing look below at the Contributions section.

Deploying the Fabric EVM Chaincode (EVMCC)

This chaincode can be deployed like any other user chaincode to Hyperledger Fabric. The chaincode has no instantiation arguments.

When installing, point to the EVMCC main package. Below is an example of installation and instantiation through the peer cli.

 peer chaincode install -n evmcc -l golang -v 0 -p github.com/hyperledger/fabric-chaincode-evm/evmcc
 peer chaincode instantiate -n evmcc -v 0 -C <channel-name> -c '{"Args":[]}' -o <orderer-address> --tls --cafile <orderer-ca>

The interaction is the same as with any other chaincode, except that the first argument of a chaincode invoke is the address for the contract and the second argument is the input you typically provide for an Ethereum transaction. In general the inputs match the To and Data fields in an ethereum transaction. Typically the To field is the contract address that contains the desired transaction. The Data field is the function to be invoked concatenated with the encoded parameters expected.

peer chaincode invoke -n evmcc -C <channel-name> -c '{"Args":[<to>,<data>]}' -o <orderer-address> --tls --cafile <orderer-ca>

# Contract Invocation
peer chaincode invoke -n evmcc -C <channel-name> -c '{"Args":[<contract-address>,<function-with-encoded-params>]}' -o <orderer-address> --tls --cafile <orderer-ca>

A special case of the ethereum transaction is contract creation. The To field is the zero address and the Data field is the compiled bytecode of the smart contract to be deployed.

# Contract Creation
peer chaincode invoke -n evmcc -C <channel-name> -c '{"Args":["0000000000000000000000000000000000000000",<compiled-bytecode>]}' -o <orderer-address> --tls --cafile <orderer-ca>

The only actions that do not follow the above pattern are to query for contract runtime code and accounts.

# To query for the user account address that is generated from the user public key
peer chaincode query -n evmcc -C <channel-name> -c '{"Args":["account"]}'

# To query for the runtime bytecode for a contract
peer chaincode query -n evmcc -C <channel-name> -c '{"Args":["getCode", "<contract-address>"]}'

NOTE No Ether or token balance is associated with user accounts, so Ethereum smart contracts that require a native token cannot be migrated to Fabric and must be rewritten. Token contracts such as those that follow the ERC 20 standard can still be deployed to the EVMCC. Consequently since no balances exist, user accounts are not stored on the ledger and the addresses are generated on the fly when needed. This should not affect Ethereum smart contract execution. If a contract stores an address, it will be stored under that contract's data.

NOTE In the current implementation of the EVMCC, the opcode BLOCKHASH is not supported. Therefore contracts that use the blockhash(uint blockNumber) function will result in an error.

Running Fab3

Fab3 is a web3 provider that allows the use of ethereum tools such as Web3.js and the Remix IDE to interact with the Ethereum Smart Contracts that have been deployed through the Fabric EVM Chaincode.

For the most up to date instruction set look at the ethservice and netservice implementations. For details about limitations and implementations of the the instructions look at the Fab3 Instructions.

To create the Fab3 binary, this repository must be checked out in the GOPATH

mkdir -p $(go env GOPATH)/src/github.com/hyperledger/
git clone https://github.com/hyperledger/fabric-chaincode-evm.git $(go env GOPATH)/src/github.com/hyperledger/fabric-chaincode-evm
cd $(go env GOPATH)/src/github.com/hyperledger/fabric-chaincode-evm

Fab3 requires golang version 1.11 and up.

Run the following at the root of this repository:

make fab3

A binary named fab3 will be created in the bin directory.

To run Fab3, the user needs to provide a Fabric SDK Config and Fabric user information. To specify the Fabric user, the organization and user id needs to be provided which corresponds to the credentials provided in the SDK config. We provide a sample config that can be used with the first network example from the fabric-samples repository. The credentials specified in the config, are expected to be in the directory format that the cryptogen binary outputs.

The expected inputs can be provided to fab3 as environment variables or flags. Flags will take precedence over the environment variables.

fab3 is a web3 provider used to interact with the EVM chaincode on a Fabric Network.
The flags provided will be honored over the corresponding environment variables.

Usage:
  fab3 [flags]

Flags:
  -i, --ccid string      ID of the EVM Chaincode deployed in your fabric network.
                         The CCID to be used in by fab3 can also be set by the FAB3_CCID environment variable. (default "evmcc")

  -C, --channel string   Channel to be used for the transactions.
                         This flag is required if FAB3_CHANNEL is not set

  -c, --config string    Path to a compatible Fabric SDK Go config file.
                         This flag is required if FAB3_CONFIG is not set

  -h, --help             help for fab3

  -o, --org string       Organization of the specified user.
                         This flag is required if FAB3_ORG is not set

  -p, --port int         Port that Fab3 will be running on.
                         The listening port can also be set by the FAB3_PORT environment variable. (default 5000)

  -u, --user string      User identity being used for the proxy (Matches the users' names in the
                         crypto-config directory specified in the config).
                         This flag is required if FAB3_USER is not set

Tutorial

We have a tutorial that runs through the basic setup of the EVM chaincode as well as setting up fab3. It also covers deploying a Solidity contract and interacting with it using the Web3.js node library.

Testing

You can run the integration tests in which a sample Fabric Network is run and the chaincode is installed with the CCID: evmcc.

make integration-test

The end-2-end test is derivative of the hyperledger/fabric/integration/e2e test. You can compare them to see what is different.

The fab3 test focuses on the JSON RPC API compatibility. The web3 test uses the Web3 node.js library as a client to run tests against fab3 and the EVMCC.

Contributions

Pull requests are now accepted on github. When submitting a pull request, please include the JIRA number associated with your JIRA work item in the commit message title.

To report a new issue, open a ticket in the Hyperledger Fabric JIRA under the Fabric Chaincode EVM (FABCE) project.

Current Dependencies

  • Hyperledger Fabric v1.4. EVMCC can be run on Fabric 1.0 and newer.
  • Hyperledger Fabric Go SDK 1.0.0-alpha5
  • Minimum of Go 1.11 is required to compile Fab3.

Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License

More Repositories

1

composer

⚠️ ⚠️ ⚠️ Hyperledger Composer has been deprecated ⚠️ ⚠️ ⚠️
JavaScript
1,629
star
2

sawtooth-core

Core repository for Sawtooth Distributed Ledger
Python
1,424
star
3

fabric

THIS IS A READ-ONLY historic repository. Current development is at https://gerrit.hyperledger.org/r/#/admin/projects/fabric . pull requests not accepted
Go
1,168
star
4

burrow

https://wiki.hyperledger.org/display/burrow
Go
1,027
star
5

iroha

Iroha - A simple, decentralized ledger
C++
989
star
6

indy-sdk

indy-sdk
Rust
669
star
7

education

Hyperledger training material
JavaScript
372
star
8

ursa

Hyperledger Ursa (a shared cryptographic library) has moved to end-of-life status, with the components of Ursa still in use moved to their relevant Hyperledger projects (AnonCreds, Indy, Aries and Iroha).
Rust
319
star
9

sawtooth-supply-chain

Sawtooth Supply Chain
JavaScript
261
star
10

aries-framework-go

Hyperledger Aries Framework Go provides packages for building Agent / DIDComm services.
Go
240
star
11

composer-sample-networks

⚠️ ⚠️ ⚠️ Hyperledger Composer has been deprecated ⚠️ ⚠️ ⚠️
JavaScript
222
star
12

quilt

Hyperledger Quilt - An implementation of the Interledger Protocol
Java
219
star
13

grid

Grid has moved to end-of-life status.
Rust
208
star
14

avalon

Hyperledger Avalon enables privacy in blockchain transactions, moving intensive processing from a main blockchain to improve scalability and latency, and to support attested Oracles
Python
136
star
15

iroha-android

Android library for Iroha, a Distributed Ledger Technology (blockchain) platform.
Java
107
star
16

composer-sample-applications

⚠️ ⚠️ ⚠️ Hyperledger Composer has been deprecated ⚠️ ⚠️ ⚠️
JavaScript
105
star
17

education-cryptomoji

JavaScript
97
star
18

fabric-chaintool

Clojure
91
star
19

sawtooth-next-directory

HTML
87
star
20

aries-framework-dotnet

Aries Framework .NET for building multiplatform SSI services
C#
84
star
21

sawtooth-marketplace

Python
84
star
22

fabric-sdk-rest

Read-only mirror of https://gerrit.hyperledger.org/r/#/admin/projects/fabric-sdk-rest
JavaScript
79
star
23

sawtooth-pbft

Sawtooth PBFT consensus engine
Rust
76
star
24

composer-tools

⚠️ ⚠️ ⚠️ Hyperledger Composer has been deprecated ⚠️ ⚠️ ⚠️
JavaScript
74
star
25

caliper

A blockchain benchmark framework to measure performance of multiple blockchain solutions
JavaScript
74
star
26

sawtooth-seth

Rust
73
star
27

transact

Transact is a transaction execution platform designed to be used as a library or component when implementing distributed ledgers, including blockchains.
Rust
66
star
28

fabric-baseimage

Deprecated Fabric Base Images
Shell
54
star
29

sawtooth-sabre

Sawtooth Sabre (WASM Smart Contracts)
Rust
52
star
30

education-sawtooth-simple-supply

Python
51
star
31

fabric-api-archive

Read-only mirror of https://gerrit.hyperledger.org/r/#/admin/projects/fabric-api
Java
49
star
32

indy-crypto

Archive of Indy Crypto library. Superseded by the Hyperledger Ursa Project.
Rust
49
star
33

aries-toolbox

Hyperledger Aries
Vue
43
star
34

indy-agent

Archive of Indy Reference Agents and Tools. Superseded by the Hyperledger Aries Project.
Python
43
star
35

composer-knowledge-wiki

⚠️ ⚠️ ⚠️ Hyperledger Composer has been deprecated ⚠️ ⚠️ ⚠️
40
star
36

aries-mobile-agent-xamarin

C#
39
star
37

fabric-chaintool-original

THIS IS A READ-ONLY historic repository. Current development is at https://gerrit.hyperledger.org/r/#/admin/projects/fabric-chaintool . pull requests not accepted
Clojure
38
star
38

sawtooth-explorer

TypeScript
37
star
39

iroha-dotnet

.NET library for Hyperledger Iroha, a simple distributed ledger.
C++
32
star
40

iroha-api

Iroha API
HTML
32
star
41

fabric-api

Read-only historic repo. Current development is at https://gerrit.hyperledger.org/r/#/admin/projects/fabric-api . pull requests not accepted
Java
32
star
42

sawtooth-sdk-javascript

JavaScript
30
star
43

composer-sample-models

⚠️ ⚠️ ⚠️ Hyperledger Composer has been deprecated ⚠️ ⚠️ ⚠️
JavaScript
29
star
44

hyperledgerwp

Hyperledger Whitepaper
TeX
28
star
45

sawtooth-sdk-go

Go
28
star
46

iroha-scala

Scala library for Hyperledger Iroha, a simple distributed ledger. http://iroha.tech
Scala
28
star
47

composer-vscode-plugin

⚠️ ⚠️ ⚠️ Hyperledger Composer has been deprecated ⚠️ ⚠️ ⚠️
TypeScript
27
star
48

sawtooth-sdk-rust

Rust
27
star
49

aries-protocol-test-suite

Test Suite for testing protocol compliance of Aries Agents
Python
26
star
50

sawtooth-raft

Rust
26
star
51

indy-anoncreds

Python
24
star
52

sawtooth-rfcs

22
star
53

indy-sdk-react-native

React Native wrapper around Indy SDK Java and Objective-C wrappers.
Java
22
star
54

ci-management

Read-only mirror of https://gerrit.hyperledger.org/r/#/admin/projects/ci-management
Shell
20
star
55

sawtooth-sdk-java

Java
19
star
56

indy-client

Sovrin client
Python
18
star
57

aries-cloudagent-loadgenerator

aries-cloudagent-loadgenerator
Kotlin
17
star
58

grid-contrib

Grid has moved to end-of-life status.
JavaScript
17
star
59

sawtooth-sdk-python

Python
17
star
60

iroha-ametsuchi

Flatbuffer database for the Hyperledger Iroha project.
C++
15
star
61

aries-framework-go-ext

Go
14
star
62

ursa-rfcs

Hyperledger Ursa has moved to end-of-life status.
TeX
13
star
63

composer-atom-plugin

⚠️ ⚠️ ⚠️ Hyperledger Composer has been deprecated ⚠️ ⚠️ ⚠️
CoffeeScript
12
star
64

fabric-cop

This is a read-only mirror of https://gerrit.hyperledger.org/r/#/admin/projects/fabric-cop no pull requests accepted
Go
12
star
65

aries-sdk-javascript

C++
12
star
66

sawtooth-private-utxo

11
star
67

sawtooth-sdk-dotnet

C#
11
star
68

ursa-wrapper-go

Hyperledger Ursa has moved to end-of-life status.
Go
11
star
69

indy-common

Common utility functions for other sovrin repos (like sovrin-client, sovrin-node etc)
Python
10
star
70

sawtooth-docs

Documentation source for Sawtooth Lake. Published docs at the link.
Python
10
star
71

iroha-docker

Dockerfiles for Iroha
Shell
10
star
72

sawtooth-poet

Python
9
star
73

grid-rfcs

Grid has moved to end-of-life status.
8
star
74

cello-analytics

Shell
8
star
75

sawtooth-mktplace

Example trading system for Sawtooth Lake distributed ledger.
Python
8
star
76

sawtooth-sdk-swift

Sawtooth SDK Swift
Swift
8
star
77

indy-ledger

Python
8
star
78

iroha-network-tools

Network tools for Hyperledger Iroha
7
star
79

sawtooth-validator

This repo builds a validator (miner) for the Sawtooth Lake ledger. Docs at the link:
Python
7
star
80

smart-contracts-wg

Repository for HL Smart Contracts Working Group working products
7
star
81

aries-sdk-java

Java
7
star
82

learning-materials-dev

https://wiki.hyperledger.org/display/LMDWG
Shell
7
star
83

sawtooth-arcade

Example transaction families for Sawtooth Lake distributed ledger.
Python
7
star
84

sawtooth-lib

Rust
6
star
85

sawtooth-dev-tools

Development environment and tools for Sawtooth Lake distributed ledger.
Shell
6
star
86

fabric-test-resources-gerrit

READ ONLY MIRROR of https://gerrit.hyperledger.org/r/#/admin/projects/fabric-test-resources NO PULL REQUESTS
Java
6
star
87

transact-contrib

5
star
88

homebrew-fabric

Ruby
5
star
89

sawtooth-devmode

Simple consensus engine for Hyperledger Sawtooth for developers
Python
5
star
90

sawtooth-ansible

5
star
91

aries-sdk-ruby

Rust
5
star
92

composer-sample-applications-hlfv1

Sample applications for Composer (with Fabric v1.0 support)
JavaScript
5
star
93

sawtooth-sdk-cxx

C++
4
star
94

sawtooth-docs-archive

Source files for the Hyperledger Sawtooth website
HTML
4
star
95

IDWG

All resources related to the Identity Working Group in Hyperledger
4
star
96

fabric-docs

Read-only mirror of https://gerrit.hyperledger.org/r/#/admin/projects/fabric-docs
4
star
97

transact-rfcs

3
star
98

fabric-gerrit

JavaScript
3
star
99

tf-security

Documentation and other things for the security task force.
TeX
3
star
100

aries-sdk-android

3
star