demo-wallet

An Aztec wallet application that allows dApps to interact with user accounts through a secure interface.

Architecture

The wallet uses Native Messaging for secure communication between the browser extension and the Electron app:

┌─────────────────┐      stdio            ┌──────────────────┐     Unix socket      ┌──────────────────┐
│ Browser         │ ←──(length-prefix)──→ │ Native Host      │ ←──(newline JSON)──→ │ Electron App     │
│ Extension       │      JSON             │ (compiled binary)│                      │ (wallet-worker)  │
└─────────────────┘                       └──────────────────┘                      └──────────────────┘

Browser Extension: Communicates with dApps via secure encrypted channels (ECDH + AES-GCM)
Native Host: A small binary (native-host) that bridges extension ↔ Electron via stdio/socket
Electron App: Runs the wallet-worker process that handles account management and signing

Development Setup

Prerequisites

Node.js v22
yarn
A running Aztec local node (or access to a remote node)

Running in Development Mode

Follow these steps to run the wallet in development mode:

Install dependencies
```
cd app
yarn install
```
Build the native host

The native host must be compiled before running the app:
```
yarn build:native-host
```
Start the wallet application
```
yarn start
```
Note: In dev mode, the app checks if the system-wide native messaging manifest is installed for Chrome. See WXT dev mode can't connect (Chrome) for setup instructions.
Install and run the browser extension

The browser extension must be running for the app to work properly.

The extension is located at extension. To set it up:
```
cd extension
yarn install
yarn dev
```
This will launch a browser with the extension preloaded.

Loading the Extension Manually (not required if running wxt on the terminal)

For Chromium-based browsers (Chrome, Brave, Edge):

Open your browser and navigate to the extensions page:
- Chrome: chrome://extensions
- Brave: brave://extensions
- Edge: edge://extensions
Enable "Developer mode" (toggle in the top-right corner)
Click "Load unpacked"
Select the extension/.output/chrome-mv3-* directory

For Firefox:

yarn zip:firefox

Navigate to about:debugging#/runtime/this-firefox
Click "Load Temporary Add-on"
Select the created .zip file under extension/.output/*

Native Messaging Reference

The native messaging system requires three components:

Native Host Binary - The executable that bridges extension ↔ Electron
Native Messaging Manifest - JSON file that tells the browser where to find the native host
IPC Socket - Communication channel between native host and Electron app

How Manifest Installation Works

In Production: The Electron app automatically installs manifests to user-level locations on startup via installNativeMessagingManifests() in native-messaging.ts.

In Development (WXT): Chrome runs with a custom --user-data-dir and only checks system-wide locations. You must manually install the manifest to the system-wide path (requires sudo).

macOS

Native Host Binary

Environment	Path
Development	`app/dist/native-host/darwin-arm64/native-host` (arm64) or `darwin-x64` (Intel)
Production	Inside app bundle: `AztecKeychain.app/Contents/Resources/native-host`

IPC Socket

Environment	Path
All	`~/keychain/wallet.sock`

Chrome / Chromium Manifest

Environment	Path	Installed By
Development (WXT)	`/Library/Google/Chrome/NativeMessagingHosts/com.aztec.keychain.json`	Manual (`sudo`)
Production	`~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.aztec.keychain.json`	App (auto)
Production (Chromium)	`~/Library/Application Support/Chromium/NativeMessagingHosts/com.aztec.keychain.json`	App (auto)

Firefox Manifest

Environment	Path	Installed By
All	`~/Library/Application Support/Mozilla/NativeMessagingHosts/com.aztec.keychain.json`	App (auto)

Debug Logs

Component	Path
Electron App	`~/keychain/aztec-keychain-debug.log`
Native Host	`~/keychain/native-host.log`

Dev Mode Setup (macOS + Chrome)

Since WXT uses a custom Chrome profile, you must install the manifest system-wide:

sudo mkdir -p /Library/Google/Chrome/NativeMessagingHosts
sudo tee /Library/Google/Chrome/NativeMessagingHosts/com.aztec.keychain.json << 'EOF'
{
  "name": "com.aztec.keychain",
  "description": "Aztec Keychain Native Messaging Host",
  "path": "/absolute/path/to/demo-wallet/app/dist/native-host/darwin-arm64/native-host",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://<EXTENSION_ID>/"]
}
EOF

Replace:

/absolute/path/to/demo-wallet with your actual repo path
<EXTENSION_ID> with your extension's ID (shown in chrome://extensions)

Linux

Native Host Binary

Environment	Path
Development	`app/dist/native-host/linux-x64/native-host`
Production	Packaged location (e.g., `/opt/AztecKeychain/resources/native-host`)

IPC Socket

Environment	Path
All	`~/keychain/wallet.sock`

Chrome / Chromium Manifest

Environment	Path	Installed By
Development (WXT)	`/etc/opt/chrome/native-messaging-hosts/com.aztec.keychain.json`	Manual (`sudo`)
Production (Chrome)	`~/.config/google-chrome/NativeMessagingHosts/com.aztec.keychain.json`	App (auto)
Production (Chromium)	`~/.config/chromium/NativeMessagingHosts/com.aztec.keychain.json`	App (auto)

Firefox Manifest

Environment	Path	Installed By
All	`~/.mozilla/native-messaging-hosts/com.aztec.keychain.json`	App (auto)

Debug Logs

Component	Path
Electron App	`~/keychain/aztec-keychain-debug.log`
Native Host	`~/keychain/native-host.log`

Dev Mode Setup (Linux + Chrome)

sudo mkdir -p /etc/opt/chrome/native-messaging-hosts
sudo tee /etc/opt/chrome/native-messaging-hosts/com.aztec.keychain.json << 'EOF'
{
  "name": "com.aztec.keychain",
  "description": "Aztec Keychain Native Messaging Host",
  "path": "/absolute/path/to/demo-wallet/app/dist/native-host/linux-x64/native-host",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://<EXTENSION_ID>/"]
}
EOF

Windows

Native Host Binary

Environment	Path
Development	`app\dist\native-host\win32-x64\native-host.exe`
Production	Inside app installation directory

IPC Socket (Named Pipe)

Environment	Path
All	`\\.\pipe\aztec-keychain-wallet`

Chrome Manifest

Environment	Path	Installed By
All	`%LOCALAPPDATA%\AztecKeychain\com.aztec.keychain.json`	App (auto)

Firefox Manifest

Environment	Path	Installed By
All	`%LOCALAPPDATA%\AztecKeychain\com.aztec.keychain.json`	App (auto)

Registry Keys

The app automatically creates these registry keys pointing to the manifest file:

Browser	Registry Key
Chrome	`HKCU\Software\Google\Chrome\NativeMessagingHosts\com.aztec.keychain`
Firefox	`HKCU\Software\Mozilla\NativeMessagingHosts\com.aztec.keychain`

Debug Logs

Component	Path
Electron App	`%USERPROFILE%\keychain\aztec-keychain-debug.log`
Native Host	`%USERPROFILE%\keychain\native-host.log`

Manifest Format Reference

Chrome Manifest (uses `allowed_origins`)

{
  "name": "com.aztec.keychain",
  "description": "Aztec Keychain Native Messaging Host",
  "path": "/absolute/path/to/native-host",
  "type": "stdio",
  "allowed_origins": ["chrome-extension://EXTENSION_ID/"]
}

Firefox Manifest (uses `allowed_extensions`)

{
  "name": "com.aztec.keychain",
  "description": "Aztec Keychain Native Messaging Host",
  "path": "/absolute/path/to/native-host",
  "type": "stdio",
  "allowed_extensions": ["[email protected]"]
}

Production Usage

Note for Mac users

After downloading a release, run:

xattr -d com.apple.quarantine ./AztecKeychain.app

To avoid the "this app is damaged" message.

Troubleshooting

Extension shows "Wallet backend not connected"

Ensure the Electron app is running
Check ~/keychain/native-host.log for connection errors
Verify the manifest is installed correctly for your browser
Confirm the extension ID in the manifest matches your installed extension

Native host fails to start

Ensure the native host binary exists and is executable (chmod +x native-host)
Check that the manifest path points to the correct binary location
On macOS, you may need to allow the binary in System Preferences > Security & Privacy

WXT dev mode can't connect (Chrome)

In dev mode, Chrome uses a custom --user-data-dir and only checks system-wide manifest locations:

macOS: /Library/Google/Chrome/NativeMessagingHosts/
Linux: /etc/opt/chrome/native-messaging-hosts/

You must manually install the manifest there with sudo.

Manifest not being found

Verify the manifest file exists at the expected path
Check that the JSON is valid (no syntax errors)
Ensure the path in the manifest is an absolute path to the native host binary
On Windows, verify the registry key exists and points to the manifest file

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.githooks		.githooks
.github/workflows		.github/workflows
app		app
extension		extension
scripts		scripts
.gitignore		.gitignore
CLAUDE.MD		CLAUDE.MD
README.md		README.md
package.json		package.json

AztecProtocol/demo-wallet

Folders and files

Latest commit

History

Repository files navigation

demo-wallet

Architecture

Development Setup

Prerequisites

Running in Development Mode

Loading the Extension Manually (not required if running wxt on the terminal)

Native Messaging Reference

How Manifest Installation Works

Native Host Binary

IPC Socket

Chrome / Chromium Manifest

Firefox Manifest

Debug Logs

Dev Mode Setup (macOS + Chrome)

Native Host Binary

IPC Socket

Chrome / Chromium Manifest

Firefox Manifest

Debug Logs

Dev Mode Setup (Linux + Chrome)

Native Host Binary

IPC Socket (Named Pipe)

Chrome Manifest

Firefox Manifest

Registry Keys

Debug Logs

Manifest Format Reference

Chrome Manifest (uses allowed_origins)

Firefox Manifest (uses allowed_extensions)

Production Usage

Note for Mac users

Troubleshooting

Extension shows "Wallet backend not connected"

Native host fails to start

WXT dev mode can't connect (Chrome)

Manifest not being found

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Languages

Chrome Manifest (uses `allowed_origins`)

Firefox Manifest (uses `allowed_extensions`)

Packages