41b5b2381b
Also fix some peer dependency related warnings seen during `yarn install`. |
||
---|---|---|
.. | ||
src | ||
.npmrc | ||
CHANGELOG.md | ||
README.md | ||
package.json | ||
tsconfig.json |
README.md
embark-quorum
Quorum blockchain client plugin for Embark
embark-quorum
is an Embark plugin that allows ÐApps to connect to Quorum blockchains. This plugin will not start a Quorum node or nodes automatically as Embark does with other clients.
Using this plugin, you can:
- deploy contracts publically and privately to a Quorum network using the Tessera private transaction manager.
- send public and private transactions on a Quorum network using the Tessera private transaction manager.
Overview
To use the Embark Quorum plugin, you'll need to do the following, which we'll cover in more detail in the sections below:
- Initialise and run a Quorum network, such as the 7nodes example
- Install the
embark-quorum
plugin in your ÐApp - Configure your ÐApp's blockchain config
- Configure your ÐApp's contract config (if necessary)
- Run Embark and deploy a private contract
- Sending a private transaction
1. Initialise and run a Quorum network
In order to get a Quorum network up quickly for development, the easiest path is to download the Quorum/Tessera binaries and use them to run the cloned 7nodes example.
- Download the latest Quorum binary from https://github.com/jpmorganchase/quorum/releases. Let's say it was downloaded to
/repos/jpmorganchase/quorum/build/bin/geth
. - Update your
PATH
environment variable such thatgeth
points to Quorum geth:
export PATH=/repos/jpmorganchase/quorum/build/bin:$PATH
- Download the latest Tessera jar (
tessera-app-{version}-app.jar
, ietessera-app-0.10.3-app.jar
) from https://github.com/jpmorganchase/tessera/releases. - Update your
TESSERA_JAR
environment variable to point to the downloaded Tessera jar:
export TESSERA_JAR=/path/to/tessera-app-0.10.3-app.jar
- Clone the 7nodes example repo:
git clone https://github.com/jpmorganchase/quorum-examples
cd examples/7nodes
- Initialise Quorum using the desired consensus (
istanbul
,raft
,clique
):
# ./{consensus}-init.sh
./istanbul-init.sh
- Start Quorum using the desired consensus from step 6:
# ./{consensus}-start.sh tessera
./istanbul-start.sh
NOTE: the default 7nodes example does not start Quorum geth with WebSockets. We can get around this by updating
./istanbul-start.sh
before executing it, as per https://github.com/jpmorganchase/quorum-examples/pull/221. As an alternative, clone the fork with these changes (on the7nodes-websocket-support
branch) in Step 5 instead.
After a few moments, you should have 7 Quorum nodes up and running.
To stop the network:
./stop.sh
For more information on how to get the 7nodes example up and running, including information on using Vagrant and Docker, see https://github.com/jpmorganchase/quorum-examples.
2. Install the embark-quorum
plugin in your ÐApp
Creating a ÐApp if needed
First, ensure you have a ÐApp set up. We will be using the Embark's demo ÐApp in this README, which can be created using embark demo
:
# /bin/bash
embark demo
cd embark_demo
For more information on how to get started with the Embark Demo, view our Quick Start guide.
Installing embark-quorum
in your ÐApp
To install embark-quorum
in to our ÐApp, we can add embark-quorum
to our packages.json
, then run npm
or yarn
:
# package.json
"dependencies": {
"embark-quorum": "5.3.0"
}
Then install the package with your package manager.
# /bin/bash
npm i
// OR
yarn
Next, update our ÐApp's embark.json
to include the embark-quorum
plugin:
# embark.json
"plugins": {
"embark-quorum": {}
}
3. Configure your ÐApp's blockchain config
We'll need to update our blockchain.js
configuration to instruct Embark on how to connect to the seven Quorum nodes we now have running.
The best option is to create an environment for each node in the network, so that we can connect to each node individually. The rpcPort
and wsPort
are determined by the ./{consensus}-init.sh
script run in step 1.6.
Notice that by setting the tesseraPrivateUrl
in the default
environment, it is shared by all the environments defined.
# config/blockchain.js
module.exports = {
// default applies to all environments
default: {
enabled: true,
client: 'quorum',
clientConfig: {
miningMode: 'dev', // Mode in which the node mines. Options: dev, auto, always, off
tesseraPrivateUrl: 'http://localhost:9081'
}
},
nodeone: {
clientConfig: {
rpcPort: 22000,
wsPort: 23000
}
},
nodetwo: {
clientConfig: {
rpcPort: 22001,
wsPort: 23001
}
},
nodethree: {
clientConfig: {
rpcPort: 22002,
wsPort: 23002
}
},
nodefour: {
clientConfig: {
rpcPort: 22003,
wsPort: 23003
}
},
nodefive: {
clientConfig: {
rpcPort: 22004,
wsPort: 23004
}
},
nodesix: {
clientConfig: {
rpcPort: 22005,
wsPort: 23005
}
},
nodeseven: {
clientConfig: {
rpcPort: 22006,
wsPort: 23006
}
}
};
4. Configure your ÐApp's contract config
We'll need to update our contracts.js
configuration to instruct Embark on how to deploy our contracts.
There are two important things to notice in this configuration. First, notice that nodeone
has the field privateFor
. This is telling Quorum to deploy the contract privately to Node 7, as indicated by Node 7's public key in the privateFor
field. The means Node 1 and Node 7 will be privy to this contract's values once deployed.
Also notice that we include skipBytecodeCheck: true
for all nodes that we assume should have the contract deployed in the network, but not deployed to that node. In our example, Node 1 doesn't need skipBytecodeCheck
because it is deploying the contract and can let Embark handle tracking of the contract deploys. Node 7 also doesn't need this check because Node 1 will have privately deployed the contract to Node 1 and Node 7, so we know the bytecode will exist on Node 7. However, all other Nodes need skipBytecodeCheck: true
, because the bytecode will not exist on those nodes and when Embark connects to any of those environments, we are going to rely on Embark's deployment tracking feature to determine if the contract has been deployed to the network, instead of checking to see if the bytecode for that contract exists on the node Embark is connected to. Please check out the docs for more information on this topic.
# config/contracts.js
module.exports = {
// default applies to all environments
default: {
// order of connections the DApp should connect to
dappConnection: [
"$EMBARK",
"$WEB3", // uses pre existing web3 object if available (e.g in Mist)
"ws://localhost:8546",
"http://localhost:8545"
],
gas: "auto",
},
nodeone: {
deploy: {
SimpleStorage: {
fromIndex: 0,
args: [100],
privateFor: ["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="]
}
}
},
nodetwo: {
deploy: {
SimpleStorage: {
skipBytecodeCheck: true
}
}
},
nodethree: {
deploy: {
SimpleStorage: {
skipBytecodeCheck: true
}
}
},
nodefour: {
deploy: {
SimpleStorage: {
skipBytecodeCheck: true
}
}
},
nodefive: {
deploy: {
SimpleStorage: {
skipBytecodeCheck: true
}
}
},
nodesix: {
deploy: {
SimpleStorage: {
skipBytecodeCheck: true
}
}
},
nodeseven: {}
};
5. Run Embark and deploy a private contract
Now that we have our ÐApp set up, let's run Embark and see the private contract deployment in action. We are going to deploy the SimpleStorage
contract privately between Nodes 1 and 7 (based on the privateFor
parameter specified in the contract configuration for the nodeone
environment), and witness how we can only view the contract's values in Nodes 1 and 7, and not in Nodes 2 - 5.
First, let's run Embark in console mode in our nodeone
environment, ensuring we connect to Node 1 in our 7nodes example:
# /bin/bash
embark console nodeone
You should see all the normal output of embark run
, including information on how the contract SimpleStorage
was deployed:
compiling solidity contracts...
deploying contracts
Deploying SimpleStorage with 151414 gas at the price of 0 Wei. Estimated cost: 0 Wei (txHash: 0xecb96cebf2a4da17206d8b225b77f2a84e3ec2ae1a10cd3f95ddc094381ec5d1)
SimpleStorage deployed at 0x9d13C6D3aFE1721BEef56B55D303B09E021E27ab using 0 gas (txHash: 0xecb96cebf2a4da17206d8b225b77f2a84e3ec2ae1a10cd3f95ddc094381ec5d1)
finished deploying contracts
Once the ÐApp is finished webpacking, you should see the console prompt:
Embark (nodeone) >
In this prompt, enter SimpleStorage.get()
so we can find out what our current value stored in the contract is:
Embark (nodeone) > SimpleStorage.get()
# 100
We can see that the value returned is the value we provided in our SimpleStorage
constructor args
in the contracts configuration. So far, so good.
Now, let's kill our instace of Embark with Ctrl+c
, and then spin up a new instance in the nodeseven
environment.
<ctrl+c>
embark console nodeseven
The output, this time, will be a little bit different. Notice that Embark understands that the contract has been deployed to Node 7 (due to the bytecode check):
deploying contracts
SimpleStorage already deployed at 0x9d13C6D3aFE1721BEef56B55D303B09E021E27ab
finished deploying contracts
Now, do the same thing as before and retrieve the value stored in the contract:
Embark (nodeone) > SimpleStorage.get()
# 100
Again, as expected, we get the value of 100, matching the constructor arguments. This is expected because Node 1 deployed the SimpleStorage
contract privately between nodes 1 and 7.
Let's take this one step further and check the value stored in SimpleStorage
on a node that was not included in the private contract deploy.
Exit the current Embark instance with ctrl+c
, then start up a new instance in the nodetwo
environment:
<ctrl+c>
embark console nodetwo
Notice the warning that the bytecode check is skipped, and also that Embark knows the contract has already been deployed, even though the bytecode doesn't exist on Node 2:
compiling solidity contracts...
deploying contracts
WARNING: Skipping bytecode check for SimpleStorage deployment. Performing an Embark reset may cause the contract to be re-deployed to the current node regardless if it was already deployed on another node in the network.
SimpleStorage already deployed at 0x9d13C6D3aFE1721BEef56B55D303B09E021E27ab
finished deploying contracts
Again, let's see now what Node 2 has stored for the SimpleStorage
contract value:
Embark (nodetwo) > SimpleStorage.get()
# 0
The result is 0
, which is exepcted because Node 2 does not contain the bytecode for SimpleStorage
and does not have its values stored in its Ethereum state.
6. Sending a private transaction
Let's see how the embark-quorum
plugin allows us to send private transactions.
First, run an Embark console in the nodeone
environment to see what the current value of the SimpleStorage
contract is.
# /bin/bash
embark console nodeone
Once started, get our contract value in the console prompt:
Embark (nodeone) > SimpleStorage.get()
# 100
Now, let's update this value only for Node 7. In the console, we're going to send a private transaction between Node 1 and Node 7. This transaction is simply going to set the SimpleStorage
value to 333
by calling the SimpleStorage.set(333)
method in a transaction. Run each of these lines individually in the console:
Embark (nodeone) > from = web3.eth.defaultAccount
Embark (nodeone) > privateFor = ['ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc=']
Embark (nodeone) > await SimpleStorage.methods.set(333).send({ from, privateFor })
We can check that the transaction set our SimpleStorage
value to 333
:
Embark (nodeone) > SimpleStorage.get()
# 333
Now, let's check Node 7:
<ctrl+c>
embark console nodeseven
Then, in the console prompt:
Embark (nodeseven) > SimpleStorage.get()
# 333
Great! We have privately set our SimpleStorage
contract value only in Node 7.
Conclusion
Now you should have a good idea of how to run a Quorum network and use Embark to deploy public and private contracts, and send public and private transactions.
In addition to running on a network of multiple Quorum nodes, embark-quorum
works with any number of Quorum nodes, including one.
Please feel free to explore all the possibilities of Quorum and Embark in your own ÐApp, and report any issues found.
Visit framework.embarklabs.io to get started with Embark.