feat: add solana-localnet program

web3.js/.travis.yml

@@ -1,8 +1,12 @@
+sudo: required
 language: node_js
 node_js:
   - "lts/*"
   - "node"
 
+services:
+  - docker
+
 cache:
   directories:
     - ~/.npm
@@ -14,8 +18,12 @@ script:
   - npm run doc
   - npm run flow
   - npm run lint
-  - npm run examples
   - npm run codecov
+  - npm run localnet:update
+  - npm run localnet:up
+  - npm run examples
+  - npm run test:live
+  - npm run localnet:down
 
 before_deploy:
   - rm -rf deploy

web3.js/README.md

@@ -68,6 +68,31 @@ console.log(solanaWeb3);
 console.log(solanaWeb3);
 ```
 
+## Local Network
+The `solana-localnet` program is provide to easily start a test Solana network
+locally on your machine.  Docker must be installed.  The JSON RPC endpoint of
+the local network is `http://localhost:8899`.
+
+To start, first fetch the latest Docker image by running:
+```bash
+$ npx solana-localnet update
+```
+
+Then run the following command to start the network
+```bash
+$ npx solana-localnet up
+```
+
+While the network is running logs are available with:
+```bash
+$ npx solana-localnet logs -f
+```
+
+Stop the network with:
+```bash
+$ npx solana-localnet up
+```
+
 ## Flow
 
 A [Flow library definition](https://flow.org/en/docs/libdefs/) is provided at
@@ -79,7 +104,6 @@ activate it:
 node_modules/@solana/web3.js/module.flow.js
 ```
 
-
 ## Examples
 See the [examples/](https://github.com/solana-labs/solana-web3.js/tree/master/examples) directory for small snippets.
 

web3.js/bin/localnet.sh

@@ -0,0 +1,88 @@
+#!/bin/bash -e
+
+usage() {
+  exitcode=0
+  if [[ -n "$1" ]]; then
+    exitcode=1
+    echo "Error: $*"
+  fi
+  cat <<EOF
+usage: $0 [update|up|down|logs] [command-specific options]
+
+Operate a local testnet
+
+ update   - Update the network image from dockerhub.com
+ up       - Start the network
+ down     - Stop the network
+ logs     - Display network logging
+
+
+ logs-specific options:
+   -f     - Follow log output
+
+ update/up-specific options:
+   edge   - Update/start the "edge" channel network
+   beta   - Update/start the "beta" channel network (default)
+
+ down-specific options:
+   none
+
+
+Assumes that docker is installed
+EOF
+  exit $exitcode
+}
+
+[[ -n $1 ]] || usage
+cmd="$1"
+
+channel=beta
+
+docker --version || usage "It appears that docker is not installed"
+case $cmd in
+update)
+  if [[ -n $2 ]]; then
+    channel="$2"
+  fi
+  [[ $channel = edge || $channel = beta ]] || usage "Invalid channel: $channel"
+
+  (
+    set -x
+    docker pull solanalabs/solana:"$channel"
+  )
+  ;;
+up)
+  if [[ -n $2 ]]; then
+    channel="$2"
+  fi
+  [[ $channel = edge || $channel = beta ]] || usage "Invalid channel: $channel"
+
+  (
+    set -x
+    docker run \
+      --detach \
+      --name solana-localnet \
+      --rm \
+      --publish 8899:8899 \
+      --tty \
+      solanalabs/solana:"$channel"
+
+  )
+  ;;
+down)
+  (
+    set -x
+    docker stop --time 0 solana-localnet
+  )
+  ;;
+logs)
+  (
+    set -x
+    docker logs solana-localnet "$@"
+  )
+  ;;
+*)
+  usage "Unknown command: $cmd"
+esac
+
+exit 0

web3.js/examples/README.md

@@ -1,3 +1,10 @@
 ## Examples
 Before trying any of the examples in this directory please populate the `lib/`
-directory by running `npm install`
+directory by running `npm install`.
+
+Additionally most of the examples attempt to connect to a local network.  Start
+your local network first by running:
+```bash
+$ npx solana-localnet update
+$ npx solana-localnet up
+```

web3.js/package.json

@@ -21,6 +21,9 @@
   },
   "main": "lib/index.cjs.js",
   "module": "lib/index.esm.js",
+  "bin": {
+    "solana-localnet": "bin/localnet.sh"
+  },
   "scripts": {
     "clean": "rimraf ./coverage ./lib",
     "dev": "cross-env NODE_ENV=development rollup -c",
@@ -37,6 +40,10 @@
     "lint": "eslint .",
     "lint:fix": "npm run lint -- --fix",
     "lint:watch": "watch 'npm run lint:fix' . --wait=1 --ignoreDirectoryPattern=/doc/",
+    "localnet:up": "bin/localnet.sh up",
+    "localnet:down": "bin/localnet.sh down",
+    "localnet:update": "bin/localnet.sh update",
+    "localnet:logs": "bin/localnet.sh logs",
     "ok": "npm run lint && npm run flow && npm run test && npm run doc",
     "prepare": "npm run clean && npm run ok && npm run build",
     "examples": "set -ex; for example in examples/*.js; do node $example; done",