Grid Core
What is Grid?
Ethereum Grid started as a desktop application that would allow users to easily download and configure binaries. It has since evolved into two projects: Grid Core (this repository) and Grid.
Grid Core
Grid core is is a secure execution environment that allows scripts to safely interact with binaries and even docker containers. It comes with many tools and helpers to configure binaries, spin up user interfaces and wire everything together into workflows that can be versioned and shared. Gird Core follows the infrastructure as code (IaC) philosophy where we use known software best practices and tools to design, implement, deploy and orchestrate application infrastructure. It comes with a command line interface (CLI) .
Grid
Grid is the desktop application that integrates with the OS and provides a simplified UI to make binaries, apps and workflows accessible to less technical people or just to have a more convenient access to Ethereum tools. Please note that both are still undergoing a refactoring and are under heavy development.
Running the examples
Grid workflows are simple JavaScript files that are executed in a sandboxed runtime environment - without access to NPM modules but with access to Grid and some special API's. Please note that the constrained environment is NOT a Protection Mechanism since workflows can download and execute binaries and have other ways to bypass the sandbox. For security concerns please refer to the section about scoped and signed packages.
To explore Grid workflows please checkout the Grid Workflows repository.
All workflows in this repository can be executed with following schema:
grid-core workflow run 0x39830fed4b4b17fcdfa0830f9ab9ed8a1d0c11d9/<name>@version
<name>
is the name as defined in the individual workflow package.json.
The <version>
tag is optional and can be left out - default will be latest
.
Without installation
I you have NPM installed and just want to try things out:
npx grid-core run 0x39830fed4b4b17fcdfa0830f9ab9ed8a1d0c11d9/hello-grid
is the perfect one-liner to get you started.
With installation
If you want to write your own workflows or run more examples it makes sense to install the CLI tools:
npm install -g grid-core
or
yarn global add grid-core
Run "Hello Grid"
grid-core workflow run 0x39830fed4b4b17fcdfa0830f9ab9ed8a1d0c11d9/hello-grid
_____ _ _ _____ _ _____ / ____| | | / ____| | |_ _|| | __ _ __ _ __| |______| | | | | | | | |_ | '__| |/ _' |______| | | | | | | |__| | | | |
Verify your security model
Now try to run an "unoffical" / untrusted fork of hello grid. Please note that the author has a different address.
grid-core workflow run 0x988194bc7dad7882acb9a3bb5d27c484ad863fb5/hello-grid
_____ _ _ _____ _ _____ / ____| | | / ____| | |_ _|| | __ _ __ _ __| |______| | | | | | | | |_ | '__| |/ _' |______| | | | | | | |__| | | | |
The current security model is to reject execution of hosted packages that are not signed by a Grid author. We will make adjustments to this model and allow more white listing options soon.
Scoped and signed Packages
Grid has a strong concept of authorship and authentication. This is why every project name is scoped to an Ethereum address like:
0x39830fed4b4b17fcdfa0830f9ab9ed8a1d0c11d9/ethers-repl@1.0.0
, usually owned by one individual or organization e.g a team.
This address is also the address that was used to sign the package using ethpkg
.
In order to avoid execution of untrusted code on your machine you should familiarize with the Ethereum address concept. In the future, white-listing of authors will be required before execution is possible. It is also an advantage to have a basic understanding of asymmetric cryptography and public and private keys - though you can absolutely use Grid without knowing these concepts in advance.
To make things easier, ENS support is available so that 0x39830fed4b4b17fcdfa0830f9ab9ed8a1d0c11d9/ethers-repl@1.0.0
becomes a more readable name like grid.philipplgh.eth/ethers-repl
.
Writing your own workflow
Best thing to do is to first create a workspace to host our workflows:
mkdir grid-workflows
cd grid-workflows
Inside the workspace run:
Creating Grid config at: "Projects/grid-workflows/.grid.config.js" ...✔ Path to keystore : · ✔ Path to cache : · ✔ License
Verify that the config file was created and looks good:
cat .grid.config.js
Now, it's time to create a workflow from a template:
$ grid-workflows % grid-core workflow init _____ _ _ _____ _ _____ / ____| | | / ____| | |_ _|| | __ _ __ _ __| |______| | | | | | | | |_ | '__| |/ _' |______| | | | | | | |__| | | | |
You should also see the output "Grid uses configuration: .../grid-workflows/.grid.config.js"
. Use it to verify that your config is active.
Follow on-screen instructions:
cd my-workflowyarn start
You should see an output similar to:
Grid Version 1.0.3 Grid uses configuration: ...grid-workflows/.grid.config.js Starting workflow:===================================================Name: my-workflowVersion: 1.0.0Description: This is the auto-generated test workflow.===================================================Output: INFO : >> hello workflow {}✔ Found release for: geth - darwin/latest✔ Starting client geth with flags: []INFO : >> Received client version via RPC: Geth/v1.9.12-unstable-556888c4-20200302/darwin-amd64/go1.13.8===================================================
Congratulations! You just created and run your first workflow that sets up a local Geth node. Now, is a good time to checkout the code. Open the `index.js' in your favorite IDE:
caode . index.js
const default: Grid FlagBuilder WorkflowUtils = const ethers = const createLogger prompt = WorkflowUtils // create a logger for your workflowconst logger = // and a new Grid instanceconst grid = logger // entry point of your workflowconst run = async { logger // this will download and extract the latest binaries const client = await grid // the FlagBuilder tool is used to generate flags from // multiple sources: e.g. user input, defaults, supported flags, profiles const flags = await FlagBuilder // we pass the default flags to grid and start the binary // the call will return once the ipc connection is established // which is when geth is ready to receive commands const ipc = await grid // we can use the rpc API to send rpc commands const clientVersion = await client logger await grid} // lifecycle method:called before workflow stopsconst onStop = async { // used to clean up // await grid.stopClients()} moduleexports = run onStop
You can make modifications and re-run the code as you like. Give your workflow a nice name and edit the metadata in the package.json. Remove tags that are not fitting and make sure to change the default description.
Once you're done you can publish the workflow:
yarn release
_____ _ _ _____ _ _____ / ____| | | / ____| | |_ _|| | __ _ __ _ __| |______| | | | | | | | |_ | '__| |/ _' |______| | | | | | | |__| | | | |
If you want to be informed about updates and releases please follow https://twitter.com/philipplgh https://twitter.com/ethereumgrid