A flexible dapp browser for many different use cases.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
none 7f52034bee initial commit 9 months ago
platforms initial commit 9 months ago
src initial commit 9 months ago
.gitignore initial commit 9 months ago
package.json initial commit 9 months ago
readme.md initial commit 9 months ago



A very flexible DApp browser for loading HTML/Javascript based UI's from various sources. Also features the ability to inject a web3 object similar to how MetaMask works. This means you can use many popular MetaMask only Dapps with this browser.

You can think of it sort of like Mist without the launching UI.

This latest version of Ensquare no longer uses the Electron webview for embedding websites or UIs. As a result the address bar feature has been removed. This was done as some websites were no longer compatible with the webview method.

UI Sources

  • Regular HTTP/HTTPS hosted web apps
  • IPFS
  • Swarm
  • Zeronet

Other features

  • Inject web3 for Ethereum based DApps
  • ENS name resolution
  • Configurable proxy support to use with I2P/TOR and CJDNS etc
  • Hide the Zeronet icon/button for hosted sites
  • Configurable Ethereum & IPFS RPC endpoints
  • App-to-app wallet IPC
  • Redirect web3 wallet requests to private node
  • Sandboxed localStorage based on configurable options like domain/appkey
  • Various shims available to be compatible with more DApps
  • Plugin support


Installation is pretty straightforward. We assume you already have a recent version of electron installed and available in your PATH. If not, you will need to download and install separately (npm i electron perhaps)

git clone https://github.com/andrewheadricke/ensquare.git
cd ensquare
npm i

You can run a simple example:

electron src --https wallet.ethereum.org --injectweb3

Create an alias to make life a little easier

alias ensquare='electron '`pwd`'/src $@'
ensquare --https wallet.ethereum.org --injectweb3

Why you might want to use ensquare?

  • If you want to run popular dapps without needing to install browser extensions into your regular browser
  • If you want to support a more diversified way to run dapps
  • You'd like to load decentralized apps by name without relying on centralized DNS
  • To access Dapps hosted on a variety of decentralized hosting platforms like IPFS, Zeronet, localhost apps etc
  • To use a variety of different wallets with your favorite dapps
  • If you want more flexibilty over dapp options like where to redirect ETH and IPFS RPC requests, i.e. redirect IPFS requests to a separate IPFS host on the LAN.
  • You want to use public ETH nodes to use your favorite dapp rather than run your own node
  • You want to use specific proxy settings for a dapp without changing your system or regular browser proxy settings.

Wallet IPC

The wallet IPC functionality allows you to run any html/js based wallet that supports the ensquare JS API to provide wallet services. So for example you might load the fully decentralized badger wallet via IPFS

ensquare --ipfs badger.merklework.eth --walletipchost

to load up a wallet like badger for example. It should load and show a wallet icon indicating that the wallet IPC host is enabled.

Then you can load something like

ensquare --https opensea.io --injectweb3 --interceptweb3wallet


ensquare --https idex.market --injectweb3 --interceptweb3wallet --mimicmetamask

And those dapps wallet requests will be intercepted by ensquare and redirected to the walletipchost, which in this case is the badger wallet. Badger wallet will present the user with an approval request which the user can assign an account to the dapp or reject the request.

All transactions will require approval by the user in badger, however the assigned account will be saved and always provided unless revoked.

It is fairly trivial to implement the ensquare API in a wallet dapp, therefore we should see many different wallet dapps be created to provide different features, and it is simple for users to interchange their favorites.

Wallet IPC API

Wallet host

Your wallet dapp can check if its a host using:

window._ensquare.walletipchost [boolean];

And your wallet dapp can receive wallet requests by setting the following function:

window.onEnsquareWalletIpc = function(args, callback) {
    args.method [string] 'eth_accounts' or 'eth_sendTransaction' or 'personal_sign'
    args.params [object] contains the call parameters

    callback [object] the response to send back to the dapp

Wallet IPC client

You can register your dapp name using:

window.ensquareUIRegisterName('My Dapp')

Using public ETH nodes

Don't wont to run a local Eth node, happy to trust others to do it for you?

Start your wallet:

ensquare --ipfs badger.merklework.eth --walletipchost --injectweb3 --ethrpc https://kovan.infura.io

Load your favorite dapp:

ensquare --https winsome.io --interceptweb3 --injectweb3 --ethrpc https://kovan.infura.io


ensquare --https cryptage.co --interceptweb3 --injectweb3 --ethrpc https://kovan.infura.io


Ensquare comes with an example plugin at ./js/plugin.js, but the best way to implement your own plugin is to create a new project in a sibling directory to ensquare and run ensquare --plugin ../../myplugin.

The plugin system allows developers to add additional functionality like opening up a custom window with configuration or operational options, and can pass commands into the mainWindow webpage. One use case is to parse the DOM in realtime for dynamic SPA websites.