Zeus Getting Started¶

Overview¶

Zeus-cmd is an extensible command line tool. SDK extensions come packaged in “boxes” and are served through IPFS. Zeus is currently in alpha. As a note, all Zeus commands must be run within the root directory of the package that was unboxed.

Features:¶

Smart contract templating with a single command
Install nodeos, keosd, cleos, and eosio.cdt with a single command
Simulate a blockchain node with a single command
Test, compile, and deploy smart contracts
Easily migrate a contract to a different EOSIO chain such as the Kylin and Jungle testnets or the mainnet
Design fluid dApp frontends
Cross-platform (Windows, OS X, Linux)
Easily install necessary libraries with a package manager
Truffle-like interface
Manage development lifecycle with version control
Open source (BSD License)
And more…

Hardware Requirements¶

16GB RAM
2 CPU Cores

Prerequisites¶

nodejs == 10.x (nvm recommended, install at bottom of doc)
curl
cmake
make

Recommended eosio.cdt and eosio versions¶

Automatically installed with zeus unbox helloworld

Install Zeus¶

npm install -g @liquidapps/zeus-cmd

Update¶

npm update -g @liquidapps/zeus-cmd

Test¶

zeus unbox helloworld
cd helloworld
zeus test

Try out LiquidApps’s take on Elemental Battles:¶

https://cardgame1112.dnsregistry1.com/ | code

The game incorporates:

vRAM - light-weight caching solution for EOSIO based RAM
LiquidAccounts - EOSIO accounts that live in vRAM instead of RAM
LiquidDNS - DNS service on the blockchain | contract table
Frontend stored on IPFS
user data is stored in the vRAM dapp::multi_index table (vRAM) | code
keys stored in dapp::multi_index table | code
keys created using the account name and password as seed phrases | code
eosjs-ecc’s seedPrivate method is used to create the keypair | code
logic to create LiquidAccount transactions | code

To launch locally:

zeus unbox cardgame
cd cardgame
zeus migrate
zeus run frontend main

Or try out vCPU with our LiquidChess game:¶

https://liquidchess1.dnsregistry1.com/ | code

The game incorporates:

vRAM - light-weight caching solution for EOSIO based RAM
LiquidAccounts - EOSIO accounts that live in vRAM instead of RAM
LiquidDNS - DNS service on the blockchain
vCPU - a solution to scale blockchain processing power horizontally

To launch locally:

zeus unbox chess
cd chess
zeus migrate
zeus run frontend main

Samples Boxes¶

zeus unbox <INSERT_BOX>

vRAM Boxes¶

coldtoken - vRAM based eosio.token
deepfreeze - vRAM based cold storage contract
vgrab - vRAM based airgrab for eosio.token
registry - vRAM based item registration

Zeus Extension Boxes¶

contract-migrations-extensions - contract create/deployment command template, deploy contract and allocate DAPP tokens
test-extensions - provides logic to test smart contract with unit tests
eos-extensions - install eos/eosio.cdt, launch local nodeos, launch system contracts
unbox-extensions - logic to unbox zeus boxes, list all boxes, and deploy a new box
demux - install EOSIO’s demux backend to capture events for contracts using the state-history plugin

DAPP Services Boxes¶

ipfs-dapp-service - utilize the dapp::multi_index table to store data in IPFS (vRAM) instead of RAM
cron-dapp-service - schedule CRON tasks on-chain
oracle-dapp-service - provide oracle services
readfn-dapp-service - read a contract function without the need to submit a trx to the chain
vaccounts-dapp-service - EOSIO accounts that live in vRAM instead of RAM
vcpu-dapp-service - scale blockchain processing power horizontally

Miscellaneous Boxes¶

microauctions - twin reverse dutch auctions used in DAPP’s generation event
eos-detective-reports - EOS Detective Reports - by EOSNation - https://eosdetective.io/
helloworld - Hello World
token - Standard eosio.token
airhodl - First ever Air-HODL

Zeus Options¶

please note: zeus commands are directory sensitive, all commands should be performed in root of box

Zeus compile¶

Compile a smart contract

zeus compile

# optional flags:

--all # compile all contracts
# default: true
--chain # chain to work on
# default: eos

Zeus migrate¶

Compile and migrate a smart contract to another network such as the Kylin Testnet, Jungle Testnet, or Mainnet

zeus key import <CONTRACT_ACCOUNT_NAME> --owner-private-key <KEY> --active-private-key <KEY>
zeus create contract-deployment <CONTRACT_FILE_NAME> <CONTRACT_ACCOUNT_NAME>
zeus migrate --network=kylin --creator=<CONTRACT_ACCOUNT_NAME> --creator-key=<ACTIVE_PRIVATE_KEY>

# optional flags:

--compile-all # compile all contracts
# default: true
--wallet # keosd wallet to use
# default: zeus
--creator-key # contract creator private key
# default: (eosio test key) 5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3
--creator # account to set contract to
# default: eosio
--reset # reset testing environment
# default: true
--chain # chain to work on
# default: eos
--network # network to work on (other options, kylin, jungle, mainnet)
# default: development (local)
--verbose-rpc # verbose logs for blockchain communication
# default: false
--storage-path # path for persistent storage',
# default: path.join(require('os').homedir(), '.zeus')
--stake # account EOSIO staking amount
# default: '30.0000'
--no-compile-all # do not compile contracts
--no-reset # do not reset local testing environment

Zeus test¶

Compile and unit test a smart contract

zeus test

# optional flags:

--compile-all # compile all contracts
# default: true
--wallet # keosd wallet to use
# default: zeus
--creator-key # contract creator key
# default: (eosio test key) 5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3
--creator # account to set contract to
# default: eosio
--reset # reset testing environment
# default: true
--chain # chain to work on
# default: eos
--network # network to work on (other options, kylin, jungle, mainnet)
# default: development (local)
--verbose-rpc # verbose logs for blockchain communication
# default: false
--storage-path # path for persistent storage',
# default: path.join(require('os').homedir(), '.zeus')
--stake # account EOSIO staking amount
# default: '30.0000'
--no-compile-all # do not compile contracts
--no-reset # do not reset local testing environment

Zeus Import/Export Keys¶

Import and export keys to your Zeus wallet. Please note by default keys are imported without encryption.

zeus key import <ACCOUNT_NAME> --owner-private-key <KEY> --active-private-key <KEY>

# optional flags:

--encrypted # encrypt the account keys with a password
# default: false
--storage # path to the wallet which will store the key
# default: ${home}/.zeus/networks
--network # network to work on (other options, kylin, jungle, mainnet)
# development (local)
--password # password to encrypt the keys with

zeus key export <ACCOUNT_NAME>

# optional flags:

--encrypted # exports encrypted key
# default: false
--storage # path to where the key is stored
# default: ${home}/.zeus/networks
--network # network to work on (other options, kylin, jungle, mainnet)
# default: development (local)
--password # password to decrypt the keypair

Zeus Deploy¶

Deploy a custom Zeus box to your local IPFS node. Once deployed, if the --update-mapping flag is used, you may unbox this box like other packages.

zeus deploy box

# optional flags:

--update-mapping # updates local mapping.js file with an IPFS URI where the package may be accessed at
# default: false

Help¶

zeus --help

List Boxes¶

Lists all available zeus boxes that can be unboxed.

zeus list-boxes

Update Boxes¶

Updates zeus boxes for currently unboxed project

zeus update --boxes

Project structure¶

Directory structure¶

    extensions/
    contracts/
    frontends/
    models/
    test/
    migrations/
    utils/
    services/
    zeus-box.json
    zeus-config.js

zeus-box.json¶

Add commands, NPM intalls, ignores, and command hooks

    {
      "ignore": [
        "README.md"
      ],
      "commands": {
        "Compile contracts": "zeus compile",
        "Migrate contracts": "zeus migrate",
        "Test contracts": "zeus test"
      },
      "install":{
          "npm": {
              
          }
      },
      "hooks": {
        "post-unpack": "echo hello",
        "post-install": "git clone ..."
      }
    }

zeus-config.js¶

Configure zeus environments available to interact with

    module.exports = {
        defaultArgs:{
          chain:"eos",
          network:"development"
        },
        chains:{
            eos:{
                networks: {
                    development: {
                        host: "localhost",
                        port: 7545,
                        network_id: "*", // Match any network id
                        secured: false
                    },
                    jungle: {
                        host: "jungle2.cryptolions.io",
                        port: 80,
                        network_id: "*", // Match any network id
                        secured: false
                    },
                    kylin: {
                        host: "api.kylin.eosbeijing.one",
                        port: 80,
                        network_id: "*",
                        secured: false
                    },
                    mainnet:{
                        host: "bp.cryptolions.io",
                        port: 8888,
                        network_id: "*", // Match any network id
                        secured: false
                    }
                }
            }
        }
    };

Notes regarding permissions errors:¶

Recommend using Node Version Manager (nvm)

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash
# use install instructions provided to set PATH
nvm install 10
nvm use 10