@polymeshassociation/polymesh-local

polymesh-local

Polymesh local environment for development and e2e testing

Tool for managing a Polymesh development or CI environment. This environment includes:

• 3 Polymesh nodes (ws on :9944)
• A Polymesh SubQuery instance
• A PostgreSQL instance (Served on :5432)
• Rest API for interacting with the chain (Served on :3004)
• Polymesh UIs (Dashboard on :3000, Bridge on :3001, Token Studio on :3002, Governance on :3003)
• Tooling-gql, a GraphQL interface to query historic chain data. (Served on :3007)

Individual pieces can be brought up by using the --only flag on start

NOTE: This package requires docker and docker-compose to run. They must be installed on the user's system beforehand. The docker daemon must be running for this tool to work

NOTE: For Mac and Windows users, docker should be allocated at least 4GB of memory. This can be done through the docker UI

Getting Started

The easiest way to run polymesh-local is to grab the latest release from npm.

npm i -g @polymeshassociation/polymesh-local
polymesh-local start

The first time can take a while as the various docker images are pulled in. After the initial start it should be much quicker. The full set of commands can be seen with help command.

Creating a CDD + uID

In order to interact with the UIs you will need the Polymesh wallet browser extension installed, as well as a CDD + uID claim for your account.

To create a CDD claim you can use https://app.polymesh.live/, add in your wallet address in Addresses > Address Book. Then navigate to Developer > Extrinsics. There select testUtils > mockCddRegisterDid and select your account. After a CDD has been generated you can use the mock uID provider to add a uID claim to your wallet.

After creating the CDD claim you will likely want to transfer POLYX from Alice to your account as well. This can be done in app.polymesh.live under Accounts > Transfer.

Building From Source

When developing polymesh-local, commands can be executed with ./bin/run COMMAND, which will execute the repo's code. It can be packaged and installed locally with:

yarn build:ts
yarn pack # produces a .tgz file that can be installed
npm i -g polymesh-local-v3.0.0.tgz # specify the file created from previous step

Updating the UIs

To update the UIs for new chain versions, there is a script build-uis, which will produce a set of UIs and place them in the ui directory. Note the dashboard is private, so you will need an SSH key that has access to that repository for it to work.

Once the UIs are confirmed to have been built successfully zip them with: tar -czvf v?.?.x.tgz -C ./src/local/uis . and upload the resulting file to the asset Github release

License

This project uses Oclif, which is MIT licensed.

The project itself is Apache 2.0 licensed.

• polymesh-local
• Usage
• Commands

Usage

$ npm install -g @polymeshassociation/polymesh-local
$ polymesh-local COMMAND
running command...
$ polymesh-local (-v|--version|version)
@polymeshassociation/polymesh-local/5.12.2 linux-x64 node-v18.20.1
$ polymesh-local --help [COMMAND]
USAGE
  $ polymesh-local COMMAND
...

Commands

• polymesh-local clean
• polymesh-local configure
• polymesh-local help [COMMAND]
• polymesh-local info
• polymesh-local load FILE
• polymesh-local ls
• polymesh-local rm FILE
• polymesh-local save [name]
• polymesh-local start [OPTIONS]
• polymesh-local stop [OPTIONS]

polymesh-local clean

Clean removes the chain data so the next start is starts at a genesis block. Services must be stopped for this command to work

USAGE
  $ polymesh-local clean

OPTIONS
  -h, --help  show CLI help
  --verbose   enables verbose logging

See code: src/commands/clean.ts

polymesh-local configure

Manages the configuration file for polymesh-local

USAGE
  $ polymesh-local configure

OPTIONS
  -h, --help  show CLI help

See code: src/commands/configure.ts

polymesh-local help [COMMAND]

display help for polymesh-local

USAGE
  $ polymesh-local help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

polymesh-local info

Prints service connection information

USAGE
  $ polymesh-local info

OPTIONS
  -h, --help  show CLI help

See code: src/commands/info.ts

polymesh-local load FILE

Loads a snapshot into the data directory. Services must be stopped for this command to work

USAGE
  $ polymesh-local load FILE

OPTIONS
  -h, --help  show CLI help
  --verbose   enables verbose logging

See code: src/commands/load.ts

polymesh-local ls

Lists current snapshots

USAGE
  $ polymesh-local ls

OPTIONS
  -h, --help  show CLI help

See code: src/commands/ls.ts

polymesh-local rm FILE

Removes a snapshot

USAGE
  $ polymesh-local rm FILE

OPTIONS
  -h, --help  show CLI help

See code: src/commands/rm.ts

polymesh-local save [name]

Saves current chain state into an archive file

USAGE
  $ polymesh-local save [name]

ARGUMENTS
  NAME  A name or path for the snapshot

OPTIONS
  -h, --help  show CLI help
  --verbose   enables verbose logging

See code: src/commands/save.ts

polymesh-local start [OPTIONS]

Start all the services

USAGE
  $ polymesh-local start [OPTIONS]

OPTIONS
  -C, 
  --chain=dev|local|testnet-dev|testnet-local|testnet-bootstrap|mainnet-dev|mainnet-local|mainnet-bootstrap|mainnet|test
  net
      (Advanced) Specify a Polymesh runtime.

  -c, --clean
      Cleans state before starting

  -h, --help
      show CLI help

  -i, --image=image
      (Advanced) Specify a local docker image to use for Polymesh containers. Such an image should be debian based and 
      have the polymesh node binary set as its entrypoint

  -o, --only=chain|subquery|gql|rest|uis
      [default: chain,subquery,gql,rest,uis] Run only some services

  -s, --snapshot=snapshot
      Loads snapshot before starting. Current state used if not passed. Can be a "name", path to local file or remote URL

  -u, --uiLatest
      Clears saved UIs so the latest can be fetched

  -v, --version=5.4.0|5.3.0|5.2.0|5.1.3|5.1.0|5.0.3|latest
      [default: 5.4.0] version of the containers to run. `latest` may cause changes between starts

  --restMnemonics=restMnemonics
      [default: //Alice] Comma separated list of signer mnemonics. Defaults to `//Alice`

  --restSigners=restSigners
      [default: alice] Comma separated list of signers available in the rest api. Defaults to `alice`

  --vaultToken=vaultToken
      The Vault API key to use with the REST API

  --vaultUrl=vaultUrl
      The URL the Vault transit engine to use with the REST API

  --verbose
      enables verbose logging

See code: src/commands/start.ts

polymesh-local stop [OPTIONS]

Stops all services started with the "start" command

USAGE
  $ polymesh-local stop [OPTIONS]

OPTIONS
  -c, --clean  Cleans state after stopping
  -h, --help   show CLI help
  --verbose    enables verbose logging

See code: src/commands/stop.ts