bitshares-ui: a reference wallet that signs in the browser and never sends the keys

A wallet that keeps the keys in the browser, and says so

BitShares-UI is the reference wallet of the BitShares blockchain, and it connects to BitShares blockchain nodes, which the readme calls bitshares-core. The project description calls it a fully featured graphical user interface and reference wallet.

The security model is the first thing the readme explains, and it is the reason the project is a browser application rather than a native one. It is a browser based wallet, which means your keys are stored locally in your browser and never leave it while using the wallet. Transactions are signed locally before being transmitted to a node, and the readme says plainly that you should never expose your keys to anyone.

That distinction between signing and transmitting is the whole design. The node never sees a private key, it only sees a signed transaction, so the trust assumption is about the browser rather than about a server operator. It is also why the warning is emphatic rather than a footnote.

There is a Chinese version of the readme linked at the top, and the wallet site is at wallet.bitshares.org.

The primary language is JavaScript, the licence is MIT, and the default branch is develop. The last push was on 2026-10-20, so the working tree is active even though the newest tagged release in the listing is 5.0.230907 from September 2023.

The package manifest gives the internal name as BitShares2-light and the version as 5.0.250727-rc1, which is a release candidate string rather than a plain release number, and that matches the branching scheme described further down.

The engines field asks for node 16.x or newer and yarn 1.0 or newer, so the build tooling is pinned to the version the readme tells you to install.

Building it, and the node version the wallet expects

Building the browser based reference wallet depends on node version 16 using a non-root user, and that last condition is repeated later when the packages are installed.

The readme recommends Node Version Manager on Ubuntu or macOS as the easiest way to install node, and the version is set with two commands:

nvm install v16
nvm use v16

Then the repository is cloned:

git clone https://github.com/bitshares/bitshares-ui.git
cd bitshares-ui

And the packages are installed with yarn, again as a non-root user:

yarn install

The development server is started with a single script:

yarn start

Once the compilation is done the interface is served at localhost:8080 or 127.0.0.1:8080, and hot reloading is enabled so the browser updates as you edit the source files.

Two details in that sequence are worth noticing. The non-root user requirement is stated twice, which usually means it caused trouble for someone, and running the build as root is a common way to end up with packages you cannot update later. And the webpack dev server on port 8080 is the same port the production bundle is served on, which is why the Docker setup maps the host port to the container's nginx rather than to the dev server.

The manifest confirms the toolchain. The start script runs webpack in serve mode with the development environment set through cross-env, and the main field points at build/electron/index.js, which tells you the Electron build and the browser build share a source tree and differ in their entry point.

There is also a postinstall step that installs the charting library and then compiles its stylesheets with sass, and a separate script for compiling the charting CSS on its own. So the charting library is a vendored dependency that is built from source during install rather than pulled from a registry.

Three branches, three deployment sites, one release train

The release branch section is the most precise part of the readme, and it explains why the repository has a develop branch as its default.

There are three branches that form the current release process. The develop branch is where all pull requests should be pushed, and new commits are automatically deployed to that branch and published for review, browsable at develop.bitshares.org.

Staging is the current release candidate. At the end of each milestone the develop branch is pushed to staging and forms the release candidate, and the date of the release candidate forms the name, with the example given being 5.0.220214-rc1. Application breaking issues and bugs should go to the issue tracker and the pull requests should be pushed to staging, and it is browsable at staging.bitshares.org.

Master is the stable branch. When all the major issues for the current release candidate are fixed, staging is released to the stable master branch, and that is the one behind wallet.bitshares.org, the official reference wallet for BitShares.

So every change to the wallet passes through a publicly browsable deployment before it reaches users, and the naming convention for release candidates encodes the date, which makes it possible to tell which build is live from the version string alone. The manifest version 5.0.250727-rc1 follows that convention.

The consequence for a contributor is that the branch you target depends on the kind of change. A new feature goes to develop, and a fix for something that breaks goes to staging, because the release candidate is what the team is fixing against.

The same pattern explains the tagged releases in the listing. There is 5.0.230113 from March 2023, then 5.0.230907-rc1, tagged on 8 September 2023, and 5.0.230907, released on 22 September 2023, so the release candidate is tagged first and the final release follows.

Testnet, Electron and Docker, three ways to run the same wallet

The readme covers three deployment shapes, and each answers a different question about who runs the wallet.

By default bitshares-ui connects to the BitShares mainnet, and switching to the testnet is a setting rather than a build flag. You open the interface in a browser, go to Settings, then under Nodes, and select the Testnet in the dropdown. The interface reloads and connects to the testnet. There is also a ready-made deployment directly connected to testnet, including account creation, at test.xbts.io.

That the testnet choice is a dropdown in settings rather than an environment variable is worth noticing, because it means the same built artefact serves both networks. For a wallet, where the network decides what the keys are for, that is a meaningful design decision rather than a convenience.

The installable local wallet uses Electron, and the readme says the Electron build is available for Windows, macOS and Linux Debian platforms such as Ubuntu. A GitHub Action is linked that shows all the steps necessary for the build. The action compiles the interface with some special modifications for use with Electron, generates the installable binaries and copies the result to the build/binaries folder.

The Docker route is the shortest to describe. Clone the repository, run docker-compose up and visit localhost:8080.

Clone this repository, run `docker-compose up` and visit localhost:8080

The compose file shows what the container does. It builds from the repository root, publishes host port 8080 to container port 80, and mounts two volumes, one for the wallet build output and one for the source itself.

version: "2"
volumes:
 wallet_build: {}
services:
 web-wallet:
  build: .
  ports:
   - "8080:80"
  volumes:
   - wallet_build:/bitshares-ui/build/dist
   - .:/bitshares-ui

So the container runs nginx in front of a build, and the source is mounted so the image can be rebuilt without re-copying the tree. The Dockerfile installs nginx on top of a node base image, installs cross-env globally, copies in the package.json, runs the production install and exposes port 80.

For a reference wallet, the Docker route is the one most interesting for a self-hoster, because the whole point of the local-key design is that the operator of the node never holds the user's funds. The compose file's source mount makes it easy to run a modified build, and the port mapping keeps the wallet on the same address a developer would use.

The scam parser, the localisation pipeline, and the tooling around the app

The repository layout has a few entries that reveal what the project has had to deal with beyond the wallet itself.

There is a scamParser.js at the top level, and there is a bloom_filter/ directory. Both point at the same problem, which is that a wallet connects to a chain where anyone can publish a transaction, and a user interface has to warn about the ones that are trying to steal. A parser and a filter for that are production concerns rather than demo code, and their presence in the top level rather than inside the app directory suggests they are shared between the interface and something else.

The localisation side is set up with crowdin.yml and a translate-howto.md file, so translations are managed on the Crowdin platform rather than as pull requests, and there is a resources/ directory for the translated strings.

There is also a write_digest.js and a release-notes.txt, which together suggest the release notes are generated from something rather than written by hand for each build, and a CHANGELOG.md at the root. The news.json file is the kind of artefact a wallet uses for the announcements shown to users.

The build and linting stack is the conventional modern JavaScript one. There is a .babelrc for transpilation, a webpack.config.js, a .eslintrc with an .eslintignore, a .prettierrc with a .prettierignore, a postcss.config.js, and a bower.json alongside a yarn.lock.

The bower.json is the interesting leftover. Bower was the package manager for front end libraries before npm took over, and its presence next to a yarn.lock and a webpack build is what a project of this age looks like when it grew up through both eras.

Testing is partial and honest about it. The manifest has a test script for the market code run through mocha with babel register in watch mode, and a benchmark script that compiles the market classes and runs a market benchmark. BrowserStack is integrated for manual compatibility testing across devices and browser versions, and the readme says that in the future they will switch to an automated Selenium testing framework.

That sentence is a good marker of where the project was when the readme was written. Manual cross-browser testing on a service, with automation named as the intended future.

Editorial conclusion

bitshares-ui suits a BitShares user who wants to hold their own keys rather than hand them to a server operator, since the wallet signs locally and the node only ever sees a signed transaction, and it suits a self-hoster who wants to run their own interface over their own node. It does not suit you if you want a mobile wallet, because the design starts in a browser, and it does not suit you if you need automated browser testing, since the readme says cross-browser coverage is manual through BrowserStack with automation named as future work. Before you run it against real funds, use the testnet first, since the network switch is a dropdown in Settings and the testnet deployment already includes account creation.

Frequently asked questions

Official sources

1. bitshares/bitshares-ui on GitHub
2. License: MIT
3. Project website
4. README
5. Releases