What moves through Keylay
- Descriptors or cosigner data
- PSBTs and related wallet files
- JSON, text, or binary payloads needed for coordination
How it works
Coordination flow, architecture, and project status.
This page covers what participants do, what moves through Keylay, how the system is built, and where development stands. For threat assumptions, cryptographic guarantees, and known gaps, see the Security page.
Flow
A coordination layer, not a custody layer.
Keylay moves setup and signing data across distance while keeping key material and signing operations on the devices that hold them.
Participant A
Wallet / signer device
QR or file exchange
Keylay
Session code
Current: encrypted WebSocket relay
Planned: Nostr primary
No custody of funds
Participant B
Wallet / signer device
QR or file exchange
What does not
- Private keys
- Seed phrases
- Custody of funds
Setup flow
How remote wallet setup works.
1
Create a session
One participant opens Keylay and creates a session. The app produces a short session code for the others.
The code is shared out of band. Keylay does not require accounts or long-term identities for participants to connect.
2
Join the session
Other participants open Keylay, enter the session code, and join the coordination session from their own device.
The current implementation uses an encrypted WebSocket relay. Future versions are intended to use Nostr relays as the primary transport, with WebSocket retained as fallback.
3
Exchange setup data
Participants exchange the information needed to assemble a multisig wallet: cosigner data, descriptors, addresses, or other setup material supported by their wallet tools.
Keylay is the coordination path. The actual wallet assembly still happens in the wallet software each participant uses.
4
Verify locally
Each participant verifies the received information in their own wallet or signer environment before proceeding. Keylay moves data; it does not replace wallet-side verification.
Signing flow
How remote signing works.
1
Prepare a PSBT
One participant creates a transaction in their wallet and exports a PSBT.
2
Send the PSBT through Keylay
The PSBT is shared with the other participant or cosigner through the active session. Depending on the signer workflow, that may be direct file transfer, animated QR, or both.
3
Sign locally
Each signer imports or scans the PSBT into their wallet or hardware signer, reviews the transaction, and signs on the device that holds the key.
Signing happens outside Keylay. That is the point.
4
Return the signed PSBT
The partially signed result is returned through Keylay, again using file or QR workflows as needed, until the transaction can be finalized in the wallet coordinator.
Air-gapped use
QR and file transfer are first-class, not an afterthought.
Keylay is designed to work with offline signers instead of forcing participants to collapse everything onto one online device.
QR workflows
- Animated UR/QR and BBQr sequences can move data between online and offline devices
- Useful when the signer can scan but should not be network-connected
- Well suited for PSBT exchange in air-gapped signing flows
File workflows
- Files can be transferred through the coordination session where wallet tools support import and export
- Useful for descriptors, PSBTs, JSON payloads, and related setup artifacts
- Better fit when signer devices prefer SD card or local file handoff
Architecture
How the current system is structured.
Session bootstrapping
A participant creates a session and shares a short code out of band. That code connects peers without requiring sign-up, address books, or persistent accounts.
Encrypted transport
X25519 key exchange and AES-256-GCM create end-to-end encrypted sessions. Public keys are HMAC-signed using the session code so the relay cannot substitute them mid-handshake.
Air-gapped compatibility
Data can move between offline and online devices using BBQr and UR/QR animated sequences, along with ordinary file transfer. The coordination path changes; key isolation does not.
Self-hostable relay
The relay is a single Node.js file with no database; it keeps session state in memory only. Any server capable of running Node.js works. The frontend is a single HTML file served statically. To use your own relay, edit WS_LOCAL_URL / WS_CLOUD_URL in index.html and add your relay's origin to the page's Content-Security-Policy (CSP — the browser rule list that says which servers the page may connect to) connect-src line. There is no URL-parameter override.
Known issue: currently the page's CSP only allows the hosted relay, so a local relay is blocked and the app falls back to the cloud relay (visible in the status indicator). A fix is planned; until then, the workaround is to add your relay's origin to connect-src as described above.
Security model
Keylay is a coordination layer, not a custody layer.
The tool is designed to narrow the trust placed in remote coordination, not to replace wallet software or signer policy.
What Keylay is designed to do
- Reduce metadata exposure during remote setup and signing
- Preserve compatibility with QR-based and file-based air-gapped workflows
- Allow spontaneous sessions without accounts or long-term identity binding
- Keep coordination usable from ordinary desktop and mobile browsers
What Keylay does not do
- It does not custody funds
- It does not hold or derive signing keys
- It does not replace wallet verification or signer review
- It does not make compromised endpoints safe
Status
Alpha, with a concrete roadmap.
Alpha
The current release is usable for real remote coordination workflows across desktop and mobile browsers. The remaining work is not conceptual; it is engineering and hardening.
Current
- Encrypted sessions — X25519 key exchange with AES-256-GCM; the relay never sees plaintext
- Authenticated handshake — HMAC-signed public keys prevent relay key substitution mid-handshake
- Replay protection — per-message counters that must always increase; a race condition that can let a replayed message through was reported in October 2026 (finding E5 on the security page) and a fix is planned for the next client release
- Supported payloads — PSBTs, BSMS files, JSON, and arbitrary binary or text files
- Air-gapped exchange — BBQr and UR (BC-UR) animated sequences, both encode and decode, so a PSBT or wallet descriptor can be shown to or read from an air-gapped signer in either format; received UR data decodes to real files (PSBT, transaction, or a coordinator-importable descriptor)
- Browser-native use — no install, no accounts, no database or stored server-side state (the relay keeps session state in memory only)
- Mobile support — tested on Android and iOS
- Protocol v2 (since v0.9.0) — both participants must run v0.9 or later; a v0.8 client and a v0.9 client cannot connect to each other. If you self-host the app, update your copy — the current release hash is on the verify page
Planned
- Near-term — client security fixes from the October 2026 external report (findings E5–E9, listed on the security page) and a fix for the self-hosting Content-Security-Policy (CSP — the browser rule list that says which servers the page may connect to) problem; comparison-code pairing (a short code both people compare to confirm they reached each other — challenge/response pairing); more wallet guides (Sparrow + Coldcard Q available)
- Next — Nostr transport, with WebSocket kept as a fallback (removes dependence on a single relay operator; relays still see connection metadata); sessions with more than two participants (a declared signer count with numbered slots for cosigner data, so the descriptor can be assembled in the browser without a separate session per signer)
- Longer-term — resumable/asynchronous sessions (participants online at different times); PWA support (progressive web app — installable mobile use without an app store); a memory-hard KDF (key-derivation function that makes guessing session codes more expensive; blocked on browser support); CSP hash-pinning (the page allows only scripts that match published fingerprints); an independent third-party security audit