The Obscuro Wallet Extension

The wallet extension is the Obscuro component that ensures that sensitive information in RPC requests between client applications and the Obscuro enclave, such as balances or transactions, cannot be seen by third parties. It achieves this goal without requiring any custom wallet software or application code changes. Private keys for Obscuro addresses may be stored in MetaMask, for example, and the Wallet Extension will act as a bridge between MetaMask and an Obscuro host without ever knowing your wallet’s private keys itself.

The wallet extension performs two functions:

  • Encrypting outgoing RPC requests using the public key of the Obscuro enclave.
  • Decrypting incoming RPC responses for privacy-sensitive requests (e.g. eth_getBalance, eth_call and eth_getTransactionReceipt) using an address-specific viewing key.

Viewing keys are ephemeral public keys generated by the wallet extension. They are sent to the enclave, accompanied by a signature proving the viewing key was generated by a specific address, and are used to securely encrypt messages from the enclave back to the wallet extension. The corresponding private key is stored locally by the wallet extension to securely decrypt the incoming messages.

The wallet extension should be run locally by the user, such that no sensitive data leaves the client’s machine unencrypted. If the data is not particularly sensitive, it can also be run in another trusted location.

This diagram shows how Wallet Extension fits into the Obscuro workflow as a bridge between standard ethereum ecosystem tools. Diagram showing wallet extension as an RPC bridge for common Ethereum tooling


  • MetaMask
    • MetaMask is required to create a signature over each new viewing key. Other signers are not currently supported.
  • Go
    • Required if building the binary locally.


  1. The wallet extension can be downloaded from the Obscuro release page where the binary is built for the Linux, MacOS and Windows platforms. Download the binary for the latest release and rename to wallet_extension. Note that on MacOS the binary has not been signed and notarised yet - see apple support for steps to over-write this. The binary can be compiled by cloning the Obscuro repository and running the following command from the root of the repository:

    cd tools/walletextension/main && go build -o wallet_extension .

    This will build the wallet extension binary under tools/walletextension/main/wallet_extension. Note that the recommended approach is to download from the release page when running against Testnet.

  2. Open a command prompt and start the wallet extension by running the wallet_extension binary. The wallet extension supports the following flags:

    • port (default: 3000): The local port on which to serve the wallet extension.
    • portWS (default: 3001): The local port on which to handle websocket requests.
    • nodeHost (default: The Obscuro node for the RPC connection.
    • nodePortHTTP (default: 13000): The Obscuro node’s HTTP RPC port.
    • nodePortWS (default: 13001): The Obscuro node’s websockets RPC port.
    • logPath (default: wallet_extension_logs.txt): The path for the wallet extension’s logs.
    • persistencePath (default: ~/.obscuro/wallet_extension_persistence): The path to use for the wallet extension’s persistence file.

    The wallet extension is now listening on the specified host and port. For the remainder of this document, we’ll assume that the default ports of 3000 and 3001 were selected.

  3. Sign in to MetaMask and add the Obscuro Testnet network following the instructions here.

  4. At this stage, no viewing key has been set up. The enclave will refuse to respond to sensitive RPC requests such as eth_getBalance, eth_call and eth_getTransactionReceipt. As a result, your balance in MetaMask will not be accurately updated until you have a viewing key.

  5. Visit http://localhost:3000/viewingkeys/ to generate a new viewing key, and sign the viewing key when prompted by MetaMask. Responses to sensitive RPC requests will now be encrypted with the viewing key and decrypted automatically by the wallet extension. Your balance in MetaMask will now display a testnet balance of 1000000 (you may need to switch to another network and back again to force MetaMask to refresh the balance). Once a viewing key is generated it will be persisted across restarts of the wallet extension, saved in the user home space under ~/.obscuro/wallet_extension_persistence.

Auditing the source

The source code for the wallet extension can be found here.