[guardian] Add wallet behaviour draft BIP

bitcoinguardian commented at 7:26 am on September 19, 2025: none

Implements wallet behaviour for the Guardian Address proposal.

The source code for the wallet implementation is available at https://github.com/bitcoinguardian/electrum. This serves as a model for self-custodial wallets, while custodial services may adapt the protocol to their infrastructure.

Guardian Signal tooling is available at https://github.com/bitcoinguardian/GASPv1-draft

A demo with testnet transactions and Guardian integration is available at https://github.com/bitcoinguardian/electrum/tree/master/demo

[guardian] Add wallet behaviour draft bip fa9ce59174

jonatack added the label New BIP on Sep 19, 2025

[guardian] Add ack 8df3a3fa70

in bip-guardian-wallet.mediawiki:28 in 8df3a3fa70 outdated

23+
24+### 1. Wallet Behavior
25+
26+The wallet Guardian lifecycle has four distinct states as visualized in this finite state machine:
27+
28+![Guardian FSM](bip-XXXX/guardian-fsm.png)

murchandamus commented at 5:48 pm on October 6, 2025:

This appears to be Markdown syntax, but you are using a MediaWiki file. This is how your document renders:

in bip-guardian-wallet.mediawiki:20 in 8df3a3fa70

15+
16+This BIP defines the wallet implementation of Guardian Addresses, an application layer signaling mechanism that allows users to remotely lock or unlock their Bitcoin wallets via on-chain OP_RETURN signals. The specification standardizes how wallets configure, monitor, and enforce Guardian signals, ensuring consistent behavior across implementations while remaining backwards compatible with existing wallets and bitcoin nodes.
17+
18+==Motivation==
19+
20+Physical coercion and theft remain persistent risks for bitcoin users. Existing protections such as multisig or vault constructions are effective against key compromise but are limited in scenarios where attackers gain direct access to unlocked devices or custodial accounts. The Guardian Address standard provides a uniform, lightweight signalling channel that wallets can use to respond in real time to distress signals. By enabling rapid wallet lock and coordinated monitoring across both self-hosted and custodial environments, Guardian Addresses add an operational security layer that complements consensus layer protections and enhances user resilience under coercion or theft.

murchandamus commented at 5:54 pm on October 6, 2025:

The Motivation section is too generic and fails to motivate why this design should be adopted specifically.

in bip-guardian-wallet.mediawiki:97 in 8df3a3fa70 outdated

92+* Nonces are 32 bit unsigned integers (0 ≤ nonce ≤ 2^32-1). Values outside this range MUST be rejected and MUST warn the user.
93+* Wallets SHOULD alert the user if the nonce exceeds a high value (e.g., 65,535) to indicate possible nonce exhaustion or misconfiguration.
94+
95+**Mempool Conditions**
96+
97+* Wallets MUST treat a signal as effective once it is visible in the mempool, without waiting for block inclusion.

murchandamus commented at 5:57 pm on October 6, 2025:

Propagation of unconfirmed transactions is best effort. There is no guarantee that transactions will be seen by all nodes before they are confirmed.

in bip-guardian-wallet.mediawiki:130 in 8df3a3fa70 outdated

125+
126+#### Device Theft
127+
128+Alice the attacker. Bob the Bitcoin user. Alice coerces Bob under duress to login to his device and applications. Bob's device contains a self-hosted wallet, a Bitcoin exchange application, access to Bob's e-mails, and a two-factor authentication application. After forcing Bob to unlock the device and provide access, Alice takes the device and begins to attempt the Bitcoin theft.
129+
130+Prior to the attack, Bob configured a Guardian Address across all of his Bitcoin wallets. Though he no longer has his device as it has been stolen by Alice, Bob broadcasts a Guardian Lock message to the Bitcoin blockchain using a pre-signed transaction that he has available outside of the stolen device. Centralized services Bob uses have recognized the distress signal and accounts have been frozen. The self-hosted wallet is Guardian Locked and does not allow UTXOs to be spent. Despite having all the information to gain access to Bob's collective Bitcoin holdings, Alice's attack has not resulted in the loss of any Bitcoin.

murchandamus commented at 5:59 pm on October 6, 2025:

This scenario is unconvincing. Why would Alice release Bob from the duress before sending the transaction if the signer is already unlocked?

bitcoinguardian commented at 1:37 pm on October 8, 2025:

I acknowledge that the scenario in the BIP may seem contrived, as it simplifies a complex threat model for illustrative purposes. The example was inspired by Satoshi Nakamoto’s philosophical question from August 2010: “Imagine if gold turned to lead when stolen. If the thief gives it back, it turns to gold again.” (https://satoshi.nakamotoinstitute.org/posts/bitcointalk/340/). While the Guardian Address protocol operates at the wallet/application layer rather than consensus, it aims to echo this concept by enabling a self-sovereign kill switch & emergency signal to protect assets across diverse custody environments.

To address your specific concern about the scenario’s plausibility (Alice releasing Bob before sending the transaction), the intent was to model a situation where temporary access to an unlocked device occurs, such as a stolen phone or brief duress, followed by the victim’s ability to act quickly. I’ve elaborated on this in my detailed response (https://github.com/bitcoin/bips/pull/1972#issuecomment-3375484894), but I’m happy to revise the scenario to better reflect realistic threat models, such as pickpocketing or remote session compromise, if that would clarify the BIP’s motivation.

in bip-guardian-wallet.mediawiki:155 in 8df3a3fa70 outdated

150+This mechanism provides resilience if Guardian keys or pre-signed transactions are not accessible under coercion. It does not protect if attackers demand Guardian material directly or prevent the broadcast of a lock signal.
151+
152+Guardian provides signaling and coordination, not enforceable spending constraints. It is therefore effective in some coercion or theft scenarios, but not all. The following table summarizes the expected impact of the Guardian Address mechanism under various threat scenarios, with and without external monitoring (e.g., security teams, automated alerts, or third-party services actively watching the Guardian Address for signals). External monitoring enhances deterrence by acting as a distress beacon, potentially triggering physical or operational responses that disrupt an attacker's plans.
153+
154+| Threat | Guardian Impact (No External Monitoring) | Guardian Impact (With External Monitoring) |
155+|----------------------------------------|------------------------------------------|------------------------------------------|

murchandamus commented at 6:01 pm on October 6, 2025:

in bip-guardian-wallet.mediawiki:193 in 8df3a3fa70 outdated

188+
189+This design intentionally avoids requiring secure enclaves or hardware protected state. Instead, the device that triggers the lock stores only a pre-signed transaction and not signing material, reducing the risk of key material compromise while still enabling `Lock` activation.
190+
191+Users MAY use hardware for managing Guardian key signing with secure storage.
192+
193+A forced signalling attack occurs when an attacker coerces the victim to send an undesired signal. The key material for the Guardian Address must be physically unavailable to the user in a secure location to prevent this scenario.

murchandamus commented at 6:03 pm on October 6, 2025:

How would you compare your proposal to a multisig setup with signing devices in multiple locations?

murchandamus commented at 6:32 pm on October 6, 2025: contributor

The described signaling mechanism is expensive and unreliable, and adds overhead to the setup. It is likely incompatible with basic security practices like airgap setups as it relies on the wallet to be synchronized with the mempool and blockchain. The motivating scenarios sound implausible. The proposal comes across as fairly convoluted, a simple 2FA co-signer or a multisig setup with distributed signers both seem superior.

I’m not convinced it works at all, as per the described scenario, the attacker gains physical access to the unlocked wallet and therefore could tweak the firmware to make it ignore the Guardian signal, or extract the key material and create the transaction with different software. Relying on the software of a compromised device to enforce security is not reasonable.

I’m not convinced this proposal is a net improvement, nor that it is technically sound.

bitcoinguardian commented at 7:04 am on October 7, 2025: none

@murchandamus

Thank you for the detailed technical review. You’ve identified legitimate limitations that I should address more explicitly in the BIP and refine. Let me respond to your specific concerns:

On Compromised Device Security

You’re correct that Guardian Address cannot protect against sophisticated attackers who can extract keys from memory or modify wallet software. However, this criticism applies equally to any software based security mechanism including password managers, hardware wallet interfaces, and even multisig coordinators running on compromised devices.

Guardian Address doesn’t claim to be a cryptographic guarantee. It’s a coordination protocol that provides defence in depth for realistic threat scenarios:

User’s phone is stolen while unlocked, but the user escapes and can signal from elsewhere using a pre-signed transaction

Even if an attacker compromises a self-custody wallet, the same Guardian signal simultaneously freezes exchange accounts, triggers security team alerts, and locks other services

Many services have withdrawal delays, 2FA verification, or identity checks that create windows where Guardian signalling is effective

The threat model is not “attacker has root access to device and unlimited time” - it’s “attacker has temporary access and must navigate multiple services with their own security layers.”

Guardians are another layer of defence.

On Scenario Plausibility

The example scenario describes device theft, not sustained physical coercion. Realistic cases include:

Phone pickpocketed while unlocked at a cafe
Mugging where victim unlocks device under duress, then escapes
Border seizure of devices with active sessions
Remote compromise where “unlocked” means authenticated web sessions, not physical device control

Additionally, bitcoin services often have anti-theft delays: exchanges require email 2FA, impose withdrawal windows, or require video verification for large amounts. These create realistic timeframes where Guardian signalling provides protection even when the attacker has initial access.

On Cost

You characterise the mechanism as “expensive.” A Guardian lock signal transaction costs under $1 at current fee rates (2.31 sat/vB as of today) or approximately $5 at the BIP recommended 20 sat/vB for reliable confirmation during higher network activity. For an emergency security mechanism that can coordinate lockdown across multiple services and protect potentially significant holdings, this is not expensive.

To put this in perspective, a typical bitcoin transaction costs the same or more as a Guardian signal. Users routinely pay higher fees for routine transactions and the cost is less than a cup of coffee for a mechanism that could protect thousands or millions of dollars in fiat terms.

The cost is actually a feature, not a bug. It prevents spam while remaining accessible for legitimate emergency use. Characterising sub $5 on-chain signalling as “expensive” would similarly apply to any bitcoin transaction based protocol.

On Mempool Propagation

You’re right that mempool propagation is best effort.

However wallets already monitor mempools for incoming payments, RBF detection, and fee estimation. This isn’t introducing new requirements.

Finality provides signal confirmation, while mempool visibility enables rapid response (often critical in emergency scenarios), the protocol requires honouring confirmed signals, making the security guarantee time bounded rather than absent.

Multiple broadcast paths mitigate propagation issues. Users can broadcast through multiple RPC nodes or services simultaneously. If you check out the PoC signal tooling this is the example behaviour. Requiring confirmation means 10+ minute delays that may reduce the emergency response effectiveness.

The question isn’t “is this perfect?” but “is this better than having no emergency signalling mechanism?” I believe imperfect propagation with 30 second to 10 minute response time is substantially better than the status quo of no signals. Guardian signals were detected and applied within seconds in my Electrum fork and testnet3 implementation.

On Airgap Compatibility

You note that the proposal is “likely incompatible with basic security practices like airgap setups.” This limitation is already documented in the BIP section “Threat Model and Limitations”:

“Guardian Addresses will not protect wallets that are airgapped or otherwise unable to query address state from the latest block height.”

This is an acknowledged tradeoff. The protocol serves the majority of Bitcoin users who operate hot wallets, mobile wallets, or desktop wallets with Internet connectivity. For users who prioritise airgap security above emergency coordination capabilities, Guardian Address is not the appropriate tool and the BIP states this explicitly.

On Comparison with Multisig

Multisig and Guardian Address solve orthogonal problems:

Multisig provides: Distributed authorisation for spending (requires multiple parties to approve)
Guardian Address provides: Emergency lockdown coordination (one party can freeze across services)

Key differences:

Capability	Multisig	Guardian Address
Retrofit existing wallets	No	Yes
Emergency lockdown without all signers	No	Yes
Coordinate across custodial services	No	Yes
Prevent spending when attacker has M-of-N devices	No	Yes (if signal sent first)
Cryptographic spending constraints	Yes	No

A sophisticated user should use both; multisig for spending authorisation, Guardian Address for emergency coordination. They’re complementary, not competing.

The value proposition that no other BIP addresses is cross-service emergency coordination via a single on-chain signal that can simultaneously:

Lock self-custody wallets
Freeze exchange/custodial accounts
Alert security monitoring services
Trigger incident response procedures
Notify emergency contacts or insurance providers

On Physical Security Response Coordination

Beyond digital wallet locks Guardian Address enables a broader security response dimension that no other bitcoin protocol provides:

Deterrence through uncertainty: An attacker who gains device access faces fundamental uncertainty - they don’t know if a Guardian lock has already been broadcast, how many services monitor it, what physical security response may be underway, or whether law enforcement has been alerted. This uncertainty itself has protective value, potentially causing attackers to abandon attempts rather than risk detection and apprehension. This significantly changes game theory outcomes by adjusting the risk/reward balance to favour the defender.

Immediate stakeholder notification: Security monitoring services, family members, business partners, or legal counsel can monitor the Guardian Address and receive instant alerts when a lock signal appears on-chain, enabling coordinated response before an attacker can complete theft.

Law enforcement coordination: Guardian signals provide timestamped, cryptographically verifiable evidence of theft attempts. A broadcast lock signal creates an immutable blockchain record that the wallet owner has declared their holdings under threat, which can be critical for investigations and prosecutions.

Insurance claim substantiation: For users with custody insurance or institutional policies, Guardian signals provide irrefutable proof of when control of assets was lost, simplifying claims and establishing clear timelines that satisfy insurers’ evidentiary requirements.

Time buying for physical intervention: Even a 10 minute delay from digital Guardian locks allows critical time for contacting authorities, alerting building security, reaching physical safety, or coordinating with security teams. The Guardian signal serves as a self-sovereign “panic button” that buys time when every second matters.

This physical-digital coordination capability is unique to Guardian Addresses. Multisig requires coordinating multiple parties to act (slow and requires consensus), while timelocks operate on fixed schedules (inflexible and can’t respond to emergencies). Guardian provides near instant, unilateral emergency coordination across both digital services and physical security response, which is a capability gap that no existing bitcoin protocol addresses.

On “Not Technically Sound”

I respectfully disagree with this characterisation. The technical criticisms you’ve raised are:

Expensive - At under $1 (current rates) to $5 (recommended rate), this is trivial for an emergency mechanism protecting significant holdings.

Best effort mempool propagation - Acknowledged. This is a tradeoff for rapid response. Imperfect ≠ unsound.

Airgap incompatibility - Already documented in the Threat Model section. The protocol serves connected wallets (the majority use case).

Attacker can modify software - This applies to any software security and doesn’t make the protocol unsound.

The protocol is technically sound in that:

The ABNF grammar is formally specified
The state machine is defined with clear semantics
The blockchain interaction is straightforward. Working implementation exists (Electrum fork with testnet demo)
The signalling mechanism is cryptographically verifiable

Whether the security benefit justifies adoption is debatable, but the technical specification itself is sound.

Proposed Revisions

Based on your feedback, I’ll revise the BIP to:

Lead with threat model clarity. Explicitly state upfront what attacks this does and doesn’t protect against

Emphasise cross-service coordination rather than device compromise protection as the primary benefit.

Strengthen abstract/motivation: I submitted this proposal to the bitcoin-dev mailing list with a comprehensive abstract/motivation with more detail, but made more generic in the BIP.

Add comparison table to show how Guardian Address complements (not replaces) multisig, timelocks, and vaults.

While airgap incompatibility is documented, I’ll make this more prominent by improving limitations visibility.

Request for Specific Guidance

To move this forward:

If the concern is primarily about overstated claims, would you find the proposal acceptable with more conservative framing and explicit threat model boundaries?
Are there specific technical changes to the protocol itself that would address your concerns, or is this primarily about positioning/motivation?

I believe there’s genuine value in standardising an emergency coordination mechanism that works across both self-custody and custodial environments. I’m committed to revising the BIP to address legitimate concerns while preserving that core utility.

Apologies for the formatting issues, this is my first BIP and I’ll get this resolved!

bitcoinguardian commented at 7:07 am on October 7, 2025: none

Since these two BIPs build heavily on the work by Jameson Lopp, I’m interested in his thoughts too @jlopp

bitcoinguardian requested review from murchandamus on Oct 7, 2025

[guardian] Update Abstract & Motivation 08c7d568e3

[guardian] Update reference 49be1fce86

[guardian] Update threat model to render better on Mediawiki 2dfb4f92ba

[guardian] Update formatting e69c81fc5e

[guardian] More format fixes c61073c80a

[guardian] Mediawiki fixes b2e7b66633

[guardian] Fix indentation c22f3d8176

[guardian] Remove line 4ce0258973

[guardian] Add wallet behaviour draft BIP #1972