From fa9ce5917479cc9ffc35d00c7b6d90e9be178ae2 Mon Sep 17 00:00:00 2001 From: Bitcoin Guardian Date: Fri, 19 Sep 2025 14:17:27 +0700 Subject: [PATCH 01/10] [guardian] Add wallet behaviour draft bip --- bip-XXXX/guardian-fsm.png | Bin 0 -> 38032 bytes bip-XXXX/guardian-monitoring.png | Bin 0 -> 57018 bytes bip-guardian-wallet.mediawiki | 275 +++++++++++++++++++++++++++++++ 3 files changed, 275 insertions(+) create mode 100644 bip-XXXX/guardian-fsm.png create mode 100644 bip-XXXX/guardian-monitoring.png create mode 100644 bip-guardian-wallet.mediawiki diff --git a/bip-XXXX/guardian-fsm.png b/bip-XXXX/guardian-fsm.png new file mode 100644 index 0000000000000000000000000000000000000000..bfb2ac5a3c28822033f1d040b6c8a5e03277e4a4 GIT binary patch literal 38032 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 B9)AD; literal 0 HcmV?d00001 diff --git a/bip-guardian-wallet.mediawiki b/bip-guardian-wallet.mediawiki new file mode 100644 index 0000000000..99490b93b2 --- /dev/null +++ b/bip-guardian-wallet.mediawiki @@ -0,0 +1,275 @@ +
+  BIP: TBD
+  Layer: Applications
+  Title: Guardian Address Wallet Implementation
+  Author: Bitcoin Guardian 
+  Comments-Summary: No comments yet.
+  Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-?
+  Status: Draft
+  Type: Standards Track
+  Created: 2025-09-19
+  License: BSD-3-Clause
+
+ +==Abstract== + +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. + +==Motivation== + +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. + +==Specification== + +### 1. Wallet Behavior + +The wallet Guardian lifecycle has four distinct states as visualized in this finite state machine: + +![Guardian FSM](bip-XXXX/guardian-fsm.png) + +For each state, the order of operations MUST be adhered to as defined in this BIP. + +### No Guardian Configuration + +This is the state of an unconfigured Guardian Address in a wallet. No Guardian Addresses are monitored for protocol signals. No action will be taken in the wallet if any Guardian Address signals a state change. This is also the behavior of non-cooperating BIP wallets that do not implement the standard, ensuring this specification is kept optional and will not affect the operation of existing wallets or nodes. + +### Guardian Addition + +* Wallets MUST allow only one Guardian Address at a time. If one is already configured, wallets MUST require the user to remove it first (see Guardian Removal). +* Wallets MUST reject any address that matches a spending address managed by the wallet, to enforce key separation and accidental spending of the Guardian signal UTXO. +* Wallets MUST ensure that a Guardian Address maintains at least one reserved UTXO for signalling purposes. +* Wallets MUST validate the address by querying the blockchain and mempool for signals: + - MUST Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII raw ≤40 bytes. Signals MUST match the grammar defined in BIP-A (note: placeholder until BIP assignment). + - MUST Sort them by nonce in ascending order. + - MUST Reject if no signals exist (address not instantiated) or if the highest nonce signal sets `Lock=true`. This prevents accidental locking of the wallet with a Guardian Address outside of the user's control. + - MUST Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate a potential nonce exhaustion issue). +* If valid, store the address state and its current highest nonce locally. +* Wallets MUST transition to Guardian Monitoring if these operations complete. + +### Guardian Monitoring + +![Guardian Monitoring Substate](bip-XXXX/guardian-monitoring.png) + +**Guardian Address Polling** + +* If the previously checked block is not set (the wallet is polling the Guardian Address for the first time) wallets MUST poll the Guardian Address from activation block height 914021 onwards (note: placeholder block height will be updated if the BIP progresses to a future BIP assigned height). This is to prevent wallets from polling the entire chain history for the Guardian Address signals. +* The configured Guardian Address MUST be sourced from the same storage as used in the Guardian Addition. +* Addresses other than the configured Guardian Address MUST NOT be polled for Guardian Monitoring. +* The configured Guardian Address SHOULD be polled every 30 seconds. The lower the polling interval, the faster the wallet can respond to the user triggering the lock of the wallet. +* The configured Guardian Address MUST be checked every time a new block is created, even if the block is produced before the polling interval. +* The Guardian Address MUST be polled for transactions that are pending in the mempool. +* Signal transactions MUST be treated equally whether they are included in a block or still in the mempool. +* Wallets MUST warn users if the Guardian balance drops to zero or UTXOs are moved without a valid signal `OP_RETURN`. +* Wallets MUST validate the address by querying the blockchain and mempool for signals: + - Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-A[^1] (note: placeholder until BIP assignment). + - Sort them by nonce in ascending order. + - Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate potential nonce exhaustion issues). +* Wallets MUST store the current block as the previously checked block. This optimizes for speed at wallet startup. +* Wallets MUST transition to Guardian State Evaluation if signals present. +* Wallets MUST wait for the polling interval before checking for new signals. + +### Guardian State Evaluation + +**Nonce Conflict Resolution** + +Guardian signals use a monotonic nonce to prevent replay attacks and ensure deterministic evaluation of the Guardian state. Wallets MUST resolve conflicts between signals using the following rules: + +**Monotonicity** + +* Nonces MUST be strictly greater than the last observed valid nonce. +* Wallets MUST ignore any signal with a nonce less than or equal to the locally stored nonce of the configured Guardian Address. +* Wallets MUST warn the user if a stale nonce is observed. + +**Duplicate Nonces** + +* If two signals share the same nonce and are both confirmed on-chain, the transaction included at the earliest block height MUST take precedence. +* If two signals share the same nonce and are both unconfirmed in the mempool, wallets MUST treat the first seen transaction (by mempool arrival time) as canonical until confirmation. +* Once one of the duplicates is confirmed, the confirmed transaction MUST override any unconfirmed duplicate. Local storage MUST be updated accordingly. +* Wallets MUST warn the user if duplicate nonce usage is detected with different payloads. + +**Invalid Nonces** + +* Nonces are 32 bit unsigned integers (0 ≤ nonce ≤ 2^32-1). Values outside this range MUST be rejected and MUST warn the user. +* Wallets SHOULD alert the user if the nonce exceeds a high value (e.g., 65,535) to indicate possible nonce exhaustion or misconfiguration. + +**Mempool Conditions** + +* Wallets MUST treat a signal as effective once it is visible in the mempool, without waiting for block inclusion. +* If such a signal later disappears (due to eviction, replacement, or block reorg), wallets MUST retain the resulting state until a higher nonce signal is observed. This ensures wallets are locked in adversarial mempool conditions. Store a local `signal_observed` record that includes `txid`, `nonce`, `observed_time`, and `state` (`Lock`/`Unlock`) so users can audit why the wallet Guardian state has changed. +* Wallets MUST NOT revert to an earlier state purely because the mempool transaction disappeared. +* To mitigate censorship, users SHOULD broadcast signals to multiple mining pools. + +**Latest State Selection** + +* At any given evaluation, the signal with the highest valid nonce MUST be interpreted as the latest Guardian state, regardless of confirmation status. +* Signals MUST be processed in ascending nonce order to ensure sequential evaluation. +* If there is a state delta between the received signal and local storage, wallets MUST transition with the highest nonce signal to the Guardian Lock Change substate. +* If there are no state changes, wallets MUST transition to Guardian Address Polling substate. + +### Guardian Lock Change + +* Wallets MUST update the Guardian lock state in local storage with the signal presented. +* Wallets MUST update the latest used Guardian nonce in local storage with the signal presented. +* Wallets MUST update the global Guardian lock state user interface and allow UTXOs in the wallet to be spent according to lock state. If the lock state is true, wallets MUST NOT allow UTXOs in the wallet to be spent. +* Wallets MUST NOT automatically unlock after any time period or modify state in local storage from sources other than signals from the configured Guardian Address. +* Wallets MAY provide the user a pathway to view funds and history, but MUST NOT broadcast new transactions if Guardian Locked. +* Wallets MUST transition into the Guardian Address Polling substate after the state change. + +### Guardian Removal + +* The Guardian Monitoring substate MUST currently be Guardian Address Polling. +* Wallets MUST validate the existing configured Guardian Address in local storage is unlocked. +* If the Guardian Address state is locked, wallets MUST NOT allow the removal of the Guardian configuration. + +### 2. Attack Scenarios + +#### Device Theft + +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. + +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. + +After the attack is over and the threat has been mitigated, Bob is able to recover access to his wallets by broadcasting a Guardian Unlock transaction with the private key of the Guardian Address. + +If Bob regains the device, he is able to recover access to his wallet(s) by broadcasting a Guardian Unlock transaction with the private key of the Guardian Address. No UTXOs could be spent while the device was stolen since Bob locked the wallet(s). Now Bob has unlocked the wallet(s) he has the ability to spend UTXOs that were previously locked. + +#### Public Figure + +Alice the attacker. Bob the Bitcoin public figure. Bob's public status makes him a target for threat actors. Bob wants a balance between his own personal freedom and security from physical attacks. He keeps a private security team on response near his residence, but lives in his family house with privacy. + +Alice is an intruder that is attempting to break into the house to demand bitcoin be transferred. A security automation system recognises threat and locks wallets via broadcasting a pre-signed Guardian Lock transaction. This locks Bob's wallets and prevents spending of UTXOs through theft. + +The security team has also been alerted since they monitor the Guardian Address. They do not know which wallets belong to Bob, maintaining his privacy while keeping his bitcoin safe. His physical security has been protected with the response ensuring his family's safety. + +### 3. 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. + +If a Guardian Address key is lost or compromised, the user MUST rotate to a new Guardian Address. Wallet funds are unaffected since the Guardian cannot spend UTXOs, but monitoring and `Lock/Unlock` state depends on a secure Guardian. + +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. + +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. + +| Threat | Guardian Impact (No External Monitoring) | Guardian Impact (With External Monitoring) | +|----------------------------------------|------------------------------------------|------------------------------------------| +| **Device Theft** (phone/laptop stolen) | ✅ Lock can be broadcast remotely, rendering the attacker’s copy of the wallet unusable. Funds remain safe until the user broadcasts an Unlock signal. | ✅ Same as without monitoring, plus external responders (e.g., security team) are alerted to the theft via the Lock signal, potentially enabling recovery efforts or tracking. | +| **Custodian Account Compromise** | ✅ Custodian may freeze withdrawals or require manual review upon Lock, limiting exposure for centralized accounts. | ✅ Enhanced by external monitoring, as custodians or third parties can act faster (e.g., freezing accounts or notifying authorities) upon seeing the Lock signal in the mempool. | +| **Travel in Unsafe Jurisdictions** | ✅ User may proactively Lock funds before exposure, reducing risk of forced spending. Pre-signed transactions enable rapid response without carrying keys. | ✅ Lock signal can alert local or remote responders (e.g., private security), increasing deterrence as attackers may fear intervention, especially in high-risk areas. | +| **Opportunistic Mugging** (“hand over your wallet now”) | ⚠️ A Lock may be triggered via voice/automation or pre-signed transaction if the user can safely broadcast it, but success is not guaranteed under immediate threat. Signal Boxes improve chances with diverse activation methods. | ⚠️/✅ External monitoring improves outcomes: the Lock signal could alert nearby responders (e.g., police or security), deterring the attacker if they suspect intervention. Success depends on response speed and attacker awareness. | +| **Sustained Coercion** (attacker controls victim) | ❌ Guardian cannot guarantee safety; an attacker may escalate threats to force disclosure of keys or prevent lock broadcast. Physical separation of pre-signed transactions mitigates but doesn’t eliminate risk. | ⚠️ Limited protection, but external monitoring may deter escalation if the attacker knows the Lock signal could trigger a physical response (e.g., police or security team arrival). Effectiveness depends on response speed and attacker’s knowledge of the Guardian. | +| **Loss or Theft of Guardian Key** | ⚠️ Wallet remains spendable; signaling is disabled until rotated to a new Guardian Address. A leaked pre-signed Lock transaction may cause a one-time griefing Lock, but is recoverable with an Unlock signal. | ⚠️ Same as without monitoring. External responders may still act on a griefing Lock, causing temporary inconvenience but not affecting fund security. Users must rotate the Guardian Address promptly. | + +Guardian Addresses should be considered an additional layer of defense against common theft and coercion scenarios. It MUST NOT be relied upon as complete protection against determined physical attacks. Users leveraging external monitoring (e.g., via APIs, watchtowers, or private security integrations) can enhance deterrence, as the Lock signal serves as a distress beacon, but success depends on the speed and reliability of the response mechanism. + +==Compatibility== + +The proposal is backwards compatible with existing wallets and Bitcoin nodes as it uses standard address formats and `OP_RETURN`. Non-cooperative wallets will ignore the signalling mechanism. This BIP does not attempt to cryptographically restrict spending conditions at the consensus layer. + +Vault and covenant constructions (e.g., pre-signed vaults, deleted key covenants, or future consensus changes such as `OP_VAULT` or `OP_CHECKTEMPLATEVERIFY`) provide enforceable spending constraints that protect coins even if signing keys are compromised. These tools are powerful for self custody, but they apply only to UTXOs that have been intentionally placed under covenant rules, and they cannot directly influence how centralized custodians manage user balances. + +The Guardian Address standard is intended to be complementary to spending rule mechanisms. It can operate across both self-hosted and custodial wallets, providing a uniform way to trigger emergency responses. This BIP requires no changes to Bitcoin consensus and can be deployed immediately by cooperating wallet software and service providers. It can be combined with vault implementations. For example, a Guardian Lock signal could trigger a watchtower or co-signer to broadcast a pre-signed re-vault transaction, or could instruct a custodian to freeze withdrawals pending further verification. + +In this layered model, spending rules provide strong technical enforcement, while the Guardian Address provides operational coordination and rapid signalling across diverse custody wallets. Spending rules and Guardian Addresses are synergistic in this respect. + +The minimum protocol signalling payload in an `OP_RETURN` output is 19 vBytes for a `Lock` and 20 vBytes for an `Unlock` in version 1 of the protocol. The transaction is built with 20 vBytes for the canonical identifier and operation, and 20 vBytes for the monotonic nonce. The protocol is lightweight enough to ensure Guardian signalling transactions will be relayed by nodes with a default maximum `OP_RETURN` transaction limit of 40 vBytes, such as some Bitcoin Knots deployments. + +==Security Considerations== + +This signalling mechanism is an application layer security feature and does not change consensus rules or script enforcement. + +A griefing vector exists where an unauthorized third party broadcasts a `Lock` signal from the Guardian Address. This could happen if the griefing attacker gains access to the pre-signed `Lock` signal transaction and broadcasts it to the mempool. However, this lockout is temporary, recoverable, and fully under the user’s control. A monotonic nonce is included in each protocol signal so that even if a pre-signed transaction is obtained and used by an attacker, it may only be used once, limiting the impact of this to a single occurrence. This griefing vector is further mitigated by user education of secure pre-signed transaction storage. The trade off favors wide usability and deployment over strict tamper resistance hardware requirments, since key material is not required to be carried by the user. + +Wallets will always retain the ability to reset their Guardian state by creating a new transaction with `Lock=false` signed by the same Guardian private key and the incrementing monotonic nonce. + +Users MUST ensure their pre-signed Lock transactions reference a stable UTXO. Wallets SHOULD warn users if the UTXO required for a pre-signed `Lock` transaction is no longer available. + +Non-RBF eliminates the ability to replace pre-signed `Lock` transactions with a tampered `OP_RETURN`, which is crucial for the signal integrity and nonce based replay protection. + +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. + +Users MAY use hardware for managing Guardian key signing with secure storage. + +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. + +To reduce forced Unlock risks, wallets MAY implement a configurable delay (e.g., 24 hours) before processing Unlock signals, allowing time for external responders to act. + +The choice of mining pool by the user can affect the response time of the wallets implementing the standard. Private mining pools are sometimes used for transaction privacy so that transactions are only visible on-chain once they are included in a block. If a user broadcasts the pre-signed signal transaction to a such a pool, the wallet lock time could be 10 minutes, or even longer depending on the transaction inclusion interval. For this reason users SHOULD broadcast signals to public mining pools so that wallets are able to view and act on the unconfirmed signal before block inclusion. + +State changes of the Guardian Address are limited to `10^21 − 1` transitions, making nonce exhaustion an unlikely event given the infrequent nature of signalling transactions. + +==Privacy Considerations== + +This BIP avoids any on-chain link between a user's spending wallet and their Guardian Address. Because the Guardian Address appears as an independent address posting infrequent signalling transactions with `OP_RETURN`, it is indistinguishable from any other transaction format. + +No PII or linking information is included on-chain. Furthermore, wallets that monitor a Guardian Address do so locally. No external observer can deduce which wallets are watching a given Guardian status. + +Users MAY also periodically rotate their Guardian Address if additional unlinkability is desired. + +Guardian Address transactions are infrequent and non-financial in nature. The presence of a Guardian signal in `OP_RETURN` does not expose anything about balances, identity, IP addresses, physical location or wallet associations. + +No on-chain link between the Guardian and the spending wallets exists. However, wallets implementing the BIP will periodically poll nodes for the latest Guardian state, which could expose a link between the wallet and the Guardian Address. Wallet users on untrusted networks may elect to use a local or private node in environments where the interception of network traffic is a concern. + +Polling follows a similar IP exposure model to transaction broadcast but risks address interest leaks in naive implementations. Use Neutrino (BIP-158) or delegated private nodes to avoid direct queries. + +Users SHOULD NOT make transactions on-chain between their Guardian Address and their spending wallet to prevent an association that connects the two entities. + +==Rationale== + +**UTXO Fragility vs. Key Fragility** + +Users face a trade off between carrying Guardian key material and relying on pre-signed transactions. Carrying the key increases coercion risk, since an attacker could force the user to sign a transaction under duress. Pre-signed transactions avoid this risk but introduce UTXO fragility: if the referenced UTXO is spent or becomes invalid, the pre-signed transaction cannot be used. + +This proposal favors pre-signed transactions as the safer approach under coercion scenarios. They minimize the risk of key compromise, enable rapid signalling, and allow users to keep Guardian keys physically separate from everyday devices. + +**Single vs. Multiple Guardians** + +Managing multiple Guardians introduces significant complexity. Each Guardian requires its own key, increasing operational overhead. Because this is a signalling protocol, conflicting messages are possible. For example, one Guardian may broadcast a Lock while another broadcasts an Unlock. Resolving such conflicts would require an arbitration mechanism, adding ambiguity and complexity to wallet behavior. + +To avoid these issues, this proposal specifies support for a single Guardian Address. This ensures deterministic state evaluation, simplifies implementation, and reduces the risk of misconfiguration. + +**Nonce Encoding** + +The nonce is encoded as a decimal ASCII integer for human readability and ease of debugging. While binary encodings were considered, they provide minimal space savings (10 bytes vs. 4) at the cost of greater implementation complexity. + +**Justification of OP_RETURN Usage** + +Guardian signals must be effective as soon as they are broadcast to the mempool, not after block inclusion. Taproot leaf commitments or covenants are invisible until mined, which makes them unsuitable for realtime coercion response. + +`OP_RETURN` of ≤83 bytes is standard and supported in Bitcoin Core. The protocol payload is ≤40 bytes, well under relay limits. This ensures protocol transactions will be relayed irrespective of node configuration for this opcode. + +Using `OP_RETURN` does not consume a spendable UTXO and does not pollute the UTXO set. Alternatives like “dust” marker outputs would bloat UTXO sets. + +Parsing `OP_RETURN` is trivial for wallets. Using Taproot annexes or witness data would complicate light client parsing and prevent efficient use of BIP-158 filters. + +Alternatives considered and rejected: + +* Taproot commitments: invisible until mined. +* PSBT/gossip extensions: off-chain, non-universal, not enforceable. +* Dedicated covenant: requires consensus change. + +Therefore, `OP_RETURN` is the minimal, mempool visible, backwards compatible choice. + +==Reference Implementation== + +An implementation in Electrum demonstrates the Guardian Address signal protocol, including: +- Configuration of a Guardian Address in wallet settings. +- Mempool and blockchain polling for OP_RETURN signals. +- State machine handling for Lock/Unlock transitions, preventing UTXO spends when locked. +- Signal generation via a standalone Python tool for creating pre-signed Lock/Unlock transactions. + +The source code 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 integration and Guardian integration is available at https://github.com/bitcoinguardian/electrum/tree/master/demo + +==Acknowledgements== + +With thanks to @thec00n for feedback and comments of this BIP. + +This BIP has been possible due to diligent prior and ongoing work by Jameson Lopp into physical attacks in the Bitcoin ecosystem. + +==References== + +[^1]: BIP-A https://github.com/bitcoin/bips/ \ No newline at end of file From 8df3a3fa704a3520c252cf9c88e479c5af89a1c4 Mon Sep 17 00:00:00 2001 From: Bitcoin Guardian Date: Fri, 19 Sep 2025 22:51:01 +0700 Subject: [PATCH 02/10] [guardian] Add ack --- bip-guardian-wallet.mediawiki | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bip-guardian-wallet.mediawiki b/bip-guardian-wallet.mediawiki index 99490b93b2..1b5c1a9338 100644 --- a/bip-guardian-wallet.mediawiki +++ b/bip-guardian-wallet.mediawiki @@ -266,10 +266,10 @@ A demo with testnet integration and Guardian integration is available at https:/ ==Acknowledgements== -With thanks to @thec00n for feedback and comments of this BIP. +With thanks to @thec00n @OzMozis for feedback and comments of this BIP. This BIP has been possible due to diligent prior and ongoing work by Jameson Lopp into physical attacks in the Bitcoin ecosystem. ==References== -[^1]: BIP-A https://github.com/bitcoin/bips/ \ No newline at end of file +[^1]: BIP-A https://github.com/bitcoin/bips/ From 08c7d568e344eed55f72735d8b10ea0f53748ab4 Mon Sep 17 00:00:00 2001 From: Bitcoin Guardian Date: Tue, 7 Oct 2025 16:49:07 +0700 Subject: [PATCH 03/10] [guardian] Update Abstract & Motivation --- bip-guardian-wallet.mediawiki | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/bip-guardian-wallet.mediawiki b/bip-guardian-wallet.mediawiki index 1b5c1a9338..1c016621ee 100644 --- a/bip-guardian-wallet.mediawiki +++ b/bip-guardian-wallet.mediawiki @@ -13,11 +13,30 @@ ==Abstract== -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. +This proposal introduces the concept of a Guardian Address and defines a standard signalling mechanism that allows bitcoin wallets to become locked in response to an activation event. A single external control address triggers a security lockdown across one or more unrelated wallets without requiring any on-chain linkage between them. The goal is to prevent theft of bitcoin by enabling users to broadcast a standardized on-chain lock that causes cooperating wallets to enter a restricted mode, disabling the ability to spend UTXOs under duress. + +The design allows a separation of key material between the user's spending wallet and a Guardian Address; a discrete identity that signals lock state changes via a transaction embedding data in an `OP_RETURN` (~$1 at 2.31 sat/vB, ~1BTC=124K USD). This enables emergency responders, user level software, and wallet applications to recognize a distress signal without exposing user spending address(es) or balances. Rapid wallet responses with fast wallet locks (95% signal detection in <10s on testnet3) enable coordination with a physical response. + +Adoption requires minimal overhead for wallet developers. This approach does not alter spending rules. It is a voluntary signalling protocol that requires adoption by wallet and custodial software to be effective. BIP compliant wallets will be able to offer this security mechanism without compromising privacy or usability. This standard is intended to be optional and without breaking compatibility for existing wallets or nodes. ==Motivation== -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. +Bitcoin users are increasingly the targets of physical threats including robbery and coercion[^1]. A non-exhaustive list is maintained with details of physical attacks on bitcoin users[^2], which provides some insight into the prevalence and severity of attacks. Notably the incidence of attacks is also increasing. Security controls have been implemented in some self-hosted wallets as a means to prevent theft of bitcoin. One such is a decoy wallet, which presents a wallet with a smaller balance of bitcoin when a duress PIN is entered. However, this comes with two significant downsides: + +- An assumption is made that the attacker does not know about or understand the purpose of a decoy wallet. If a sophisticated attacker is able to link an address to the real world identity of the user, they may already know the true balance of the bitcoin holder. If the attacker does not know the balance of the user they are attacking, they may still suspect the user has unlocked a decoy wallet given the lower than anticipated balance. +- In the case that the attacker does not know the wallet opened is a decoy wallet, the attack still results in the loss of bitcoin for the user. + +Current self-custody solutions do not provide a safe way to respond under physical duress without risking loss of funds. In addition, participants in the Bitcoin ecosystem commonly use both self-hosted and centralized services[^3]. There's no mechanism that currently exists that can act as a self-sovereign "kill switch" for both user scenarios of a self-hosted wallet or a user with a self-hosted and centralized wallet. + +In addition, existing self-custody solutions do not support integration with a privacy perserving response to physically protect users. + +This proposal introduces an interoperable mechanism to: + +- Allow users to trigger a wallet lockdown using a separate device or operation. +- Preserve privacy by decoupling the Guardian Address from wallet addresses. +- Enable wallet software to observe chain state and mempool to react defensively, signalling an active attack. +- Protect a multiple wallet user (e.g., self-custodial wallet, exchange account, institutional wallet, custodian) with a single on-chain emergency trigger. +- Allow businesses or multi-user custodial setups designating a Guardian Address to coordinate responses and align with risk management frameworks. ==Specification== @@ -272,4 +291,7 @@ This BIP has been possible due to diligent prior and ongoing work by Jameson Lop ==References== -[^1]: BIP-A https://github.com/bitcoin/bips/ +[^1]: Investigating Wrench Attacks, DOI: 10.4230/LIPIcs.AFT.2024.24 +[^2]: https://github.com/jlopp/physical-bitcoin-attacks +[^3]: https://river.com/learn/how-many-people-use-bitcoin/ +[^4]: BIP-A https://github.com/bitcoin/bips/ From 49be1fce86055e87db5eda66b804ad1606f4e540 Mon Sep 17 00:00:00 2001 From: Bitcoin Guardian Date: Tue, 7 Oct 2025 16:52:06 +0700 Subject: [PATCH 04/10] [guardian] Update reference --- bip-guardian-wallet.mediawiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bip-guardian-wallet.mediawiki b/bip-guardian-wallet.mediawiki index 1c016621ee..c753266d3d 100644 --- a/bip-guardian-wallet.mediawiki +++ b/bip-guardian-wallet.mediawiki @@ -80,7 +80,7 @@ This is the state of an unconfigured Guardian Address in a wallet. No Guardian A * Signal transactions MUST be treated equally whether they are included in a block or still in the mempool. * Wallets MUST warn users if the Guardian balance drops to zero or UTXOs are moved without a valid signal `OP_RETURN`. * Wallets MUST validate the address by querying the blockchain and mempool for signals: - - Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-A[^1] (note: placeholder until BIP assignment). + - Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-A[^4] (note: placeholder until BIP assignment). - Sort them by nonce in ascending order. - Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate potential nonce exhaustion issues). * Wallets MUST store the current block as the previously checked block. This optimizes for speed at wallet startup. From 2dfb4f92bab26c850fa964d6444c711231d37154 Mon Sep 17 00:00:00 2001 From: Bitcoin Guardian Date: Tue, 7 Oct 2025 17:03:38 +0700 Subject: [PATCH 05/10] [guardian] Update threat model to render better on Mediawiki --- bip-guardian-wallet.mediawiki | 37 +++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/bip-guardian-wallet.mediawiki b/bip-guardian-wallet.mediawiki index c753266d3d..79c721cf54 100644 --- a/bip-guardian-wallet.mediawiki +++ b/bip-guardian-wallet.mediawiki @@ -170,14 +170,35 @@ This mechanism provides resilience if Guardian keys or pre-signed transactions a 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. -| Threat | Guardian Impact (No External Monitoring) | Guardian Impact (With External Monitoring) | -|----------------------------------------|------------------------------------------|------------------------------------------| -| **Device Theft** (phone/laptop stolen) | ✅ Lock can be broadcast remotely, rendering the attacker’s copy of the wallet unusable. Funds remain safe until the user broadcasts an Unlock signal. | ✅ Same as without monitoring, plus external responders (e.g., security team) are alerted to the theft via the Lock signal, potentially enabling recovery efforts or tracking. | -| **Custodian Account Compromise** | ✅ Custodian may freeze withdrawals or require manual review upon Lock, limiting exposure for centralized accounts. | ✅ Enhanced by external monitoring, as custodians or third parties can act faster (e.g., freezing accounts or notifying authorities) upon seeing the Lock signal in the mempool. | -| **Travel in Unsafe Jurisdictions** | ✅ User may proactively Lock funds before exposure, reducing risk of forced spending. Pre-signed transactions enable rapid response without carrying keys. | ✅ Lock signal can alert local or remote responders (e.g., private security), increasing deterrence as attackers may fear intervention, especially in high-risk areas. | -| **Opportunistic Mugging** (“hand over your wallet now”) | ⚠️ A Lock may be triggered via voice/automation or pre-signed transaction if the user can safely broadcast it, but success is not guaranteed under immediate threat. Signal Boxes improve chances with diverse activation methods. | ⚠️/✅ External monitoring improves outcomes: the Lock signal could alert nearby responders (e.g., police or security), deterring the attacker if they suspect intervention. Success depends on response speed and attacker awareness. | -| **Sustained Coercion** (attacker controls victim) | ❌ Guardian cannot guarantee safety; an attacker may escalate threats to force disclosure of keys or prevent lock broadcast. Physical separation of pre-signed transactions mitigates but doesn’t eliminate risk. | ⚠️ Limited protection, but external monitoring may deter escalation if the attacker knows the Lock signal could trigger a physical response (e.g., police or security team arrival). Effectiveness depends on response speed and attacker’s knowledge of the Guardian. | -| **Loss or Theft of Guardian Key** | ⚠️ Wallet remains spendable; signaling is disabled until rotated to a new Guardian Address. A leaked pre-signed Lock transaction may cause a one-time griefing Lock, but is recoverable with an Unlock signal. | ⚠️ Same as without monitoring. External responders may still act on a griefing Lock, causing temporary inconvenience but not affecting fund security. Users must rotate the Guardian Address promptly. | +{| class="wikitable" +! Threat +! Guardian Impact (No External Monitoring) +! Guardian Impact (With External Monitoring) +|- +| '''Device Theft''' (phone/laptop stolen) +| ✅ Lock can be broadcast remotely, rendering the attacker's copy of the wallet unusable. Funds remain safe until the user broadcasts an Unlock signal. +| ✅ Same as without monitoring, plus external responders (e.g., security team) are alerted to the theft via the Lock signal, potentially enabling recovery efforts or tracking. +|- +| '''Custodian Account Compromise''' +| ✅ Custodian may freeze withdrawals or require manual review upon Lock, limiting exposure for centralized accounts. +| ✅ Enhanced by external monitoring, as custodians or third parties can act faster (e.g., freezing accounts or notifying authorities) upon seeing the Lock signal in the mempool. +|- +| '''Travel in Unsafe Jurisdictions''' +| ✅ User may proactively Lock funds before exposure, reducing risk of forced spending. Pre-signed transactions enable rapid response without carrying keys. +| ✅ Lock signal can alert local or remote responders (e.g., private security), increasing deterrence as attackers may fear intervention, especially in high-risk areas. +|- +| '''Opportunistic Mugging''' ("hand over your wallet now") +| ⚠️ A Lock may be triggered via voice/automation or pre-signed transaction if the user can safely broadcast it, but success is not guaranteed under immediate threat. Signal Boxes improve chances with diverse activation methods. +| ⚠️/✅ External monitoring improves outcomes: the Lock signal could alert nearby responders (e.g., police or security), deterring the attacker if they suspect intervention. Success depends on response speed and attacker awareness. +|- +| '''Sustained Coercion''' (attacker controls victim) +| ❌ Guardian cannot guarantee safety; an attacker may escalate threats to force disclosure of keys or prevent lock broadcast. Physical separation of pre-signed transactions mitigates but doesn't eliminate risk. +| ⚠️ Limited protection, but external monitoring may deter escalation if the attacker knows the Lock signal could trigger a physical response (e.g., police or security team arrival). Effectiveness depends on response speed and attacker's knowledge of the Guardian. +|- +| '''Loss or Theft of Guardian Key''' +| ⚠️ Wallet remains spendable; signaling is disabled until rotated to a new Guardian Address. A leaked pre-signed Lock transaction may cause a one-time griefing Lock, but is recoverable with an Unlock signal. +| ⚠️ Same as without monitoring. External responders may still act on a griefing Lock, causing temporary inconvenience but not affecting fund security. Users must rotate the Guardian Address promptly. +|} Guardian Addresses should be considered an additional layer of defense against common theft and coercion scenarios. It MUST NOT be relied upon as complete protection against determined physical attacks. Users leveraging external monitoring (e.g., via APIs, watchtowers, or private security integrations) can enhance deterrence, as the Lock signal serves as a distress beacon, but success depends on the speed and reliability of the response mechanism. From e69c81fc5e57487a3b53dd032fd278317bc6d547 Mon Sep 17 00:00:00 2001 From: Bitcoin Guardian Date: Tue, 7 Oct 2025 19:05:03 +0700 Subject: [PATCH 06/10] [guardian] Update formatting --- bip-guardian-wallet.mediawiki | 42 +++++++++++++++++------------------ 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/bip-guardian-wallet.mediawiki b/bip-guardian-wallet.mediawiki index 79c721cf54..c2bb89e116 100644 --- a/bip-guardian-wallet.mediawiki +++ b/bip-guardian-wallet.mediawiki @@ -21,12 +21,13 @@ Adoption requires minimal overhead for wallet developers. This approach does not ==Motivation== -Bitcoin users are increasingly the targets of physical threats including robbery and coercion[^1]. A non-exhaustive list is maintained with details of physical attacks on bitcoin users[^2], which provides some insight into the prevalence and severity of attacks. Notably the incidence of attacks is also increasing. Security controls have been implemented in some self-hosted wallets as a means to prevent theft of bitcoin. One such is a decoy wallet, which presents a wallet with a smaller balance of bitcoin when a duress PIN is entered. However, this comes with two significant downsides: +Bitcoin users are increasingly the targets of physical threats including robbery and coercion.Investigating Wrench Attacks, DOI: 10.4230/LIPIcs.AFT.2024.24 +A non-exhaustive list is maintained with details of physical attacks on bitcoin usershttps://github.com/jlopp/physical-bitcoin-attacks, which provides some insight into the prevalence and severity of attacks. Notably the incidence of attacks is also increasing. Security controls have been implemented in some self-hosted wallets as a means to prevent theft of bitcoin. One such is a decoy wallet, which presents a wallet with a smaller balance of bitcoin when a duress PIN is entered. However, this comes with two significant downsides: - An assumption is made that the attacker does not know about or understand the purpose of a decoy wallet. If a sophisticated attacker is able to link an address to the real world identity of the user, they may already know the true balance of the bitcoin holder. If the attacker does not know the balance of the user they are attacking, they may still suspect the user has unlocked a decoy wallet given the lower than anticipated balance. - In the case that the attacker does not know the wallet opened is a decoy wallet, the attack still results in the loss of bitcoin for the user. -Current self-custody solutions do not provide a safe way to respond under physical duress without risking loss of funds. In addition, participants in the Bitcoin ecosystem commonly use both self-hosted and centralized services[^3]. There's no mechanism that currently exists that can act as a self-sovereign "kill switch" for both user scenarios of a self-hosted wallet or a user with a self-hosted and centralized wallet. +Current self-custody solutions do not provide a safe way to respond under physical duress without risking loss of funds. In addition, participants in the Bitcoin ecosystem commonly use both self-hosted and centralized serviceshttps://river.com/learn/how-many-people-use-bitcoin/. There's no mechanism that currently exists that can act as a self-sovereign "kill switch" for both user scenarios of a self-hosted wallet or a user with a self-hosted and centralized wallet. In addition, existing self-custody solutions do not support integration with a privacy perserving response to physically protect users. @@ -40,19 +41,19 @@ This proposal introduces an interoperable mechanism to: ==Specification== -### 1. Wallet Behavior +===Wallet Behavior=== The wallet Guardian lifecycle has four distinct states as visualized in this finite state machine: -![Guardian FSM](bip-XXXX/guardian-fsm.png) +[[File:bip-XXXX/guardian-fsm.png|thumb|Guardian FSM]] For each state, the order of operations MUST be adhered to as defined in this BIP. -### No Guardian Configuration +====No Guardian Configuration==== This is the state of an unconfigured Guardian Address in a wallet. No Guardian Addresses are monitored for protocol signals. No action will be taken in the wallet if any Guardian Address signals a state change. This is also the behavior of non-cooperating BIP wallets that do not implement the standard, ensuring this specification is kept optional and will not affect the operation of existing wallets or nodes. -### Guardian Addition +====Guardian Addition==== * Wallets MUST allow only one Guardian Address at a time. If one is already configured, wallets MUST require the user to remove it first (see Guardian Removal). * Wallets MUST reject any address that matches a spending address managed by the wallet, to enforce key separation and accidental spending of the Guardian signal UTXO. @@ -65,11 +66,11 @@ This is the state of an unconfigured Guardian Address in a wallet. No Guardian A * If valid, store the address state and its current highest nonce locally. * Wallets MUST transition to Guardian Monitoring if these operations complete. -### Guardian Monitoring +====Guardian Monitoring==== -![Guardian Monitoring Substate](bip-XXXX/guardian-monitoring.png) +[[File:bip-XXXX/guardian-monitoring.png|thumb|Guardian Monitoring Substate]] -**Guardian Address Polling** +====Guardian Address Polling==== * If the previously checked block is not set (the wallet is polling the Guardian Address for the first time) wallets MUST poll the Guardian Address from activation block height 914021 onwards (note: placeholder block height will be updated if the BIP progresses to a future BIP assigned height). This is to prevent wallets from polling the entire chain history for the Guardian Address signals. * The configured Guardian Address MUST be sourced from the same storage as used in the Guardian Addition. @@ -80,14 +81,15 @@ This is the state of an unconfigured Guardian Address in a wallet. No Guardian A * Signal transactions MUST be treated equally whether they are included in a block or still in the mempool. * Wallets MUST warn users if the Guardian balance drops to zero or UTXOs are moved without a valid signal `OP_RETURN`. * Wallets MUST validate the address by querying the blockchain and mempool for signals: - - Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-A[^4] (note: placeholder until BIP assignment). + - Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-ABIP-A https://github.com/bitcoin/bips/ + (note: placeholder until BIP assignment). - Sort them by nonce in ascending order. - Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate potential nonce exhaustion issues). * Wallets MUST store the current block as the previously checked block. This optimizes for speed at wallet startup. * Wallets MUST transition to Guardian State Evaluation if signals present. * Wallets MUST wait for the polling interval before checking for new signals. -### Guardian State Evaluation +====Guardian State Evaluation==== **Nonce Conflict Resolution** @@ -125,7 +127,7 @@ Guardian signals use a monotonic nonce to prevent replay attacks and ensure dete * If there is a state delta between the received signal and local storage, wallets MUST transition with the highest nonce signal to the Guardian Lock Change substate. * If there are no state changes, wallets MUST transition to Guardian Address Polling substate. -### Guardian Lock Change +====Guardian Lock Change==== * Wallets MUST update the Guardian lock state in local storage with the signal presented. * Wallets MUST update the latest used Guardian nonce in local storage with the signal presented. @@ -134,15 +136,15 @@ Guardian signals use a monotonic nonce to prevent replay attacks and ensure dete * Wallets MAY provide the user a pathway to view funds and history, but MUST NOT broadcast new transactions if Guardian Locked. * Wallets MUST transition into the Guardian Address Polling substate after the state change. -### Guardian Removal +====Guardian Removal==== * The Guardian Monitoring substate MUST currently be Guardian Address Polling. * Wallets MUST validate the existing configured Guardian Address in local storage is unlocked. * If the Guardian Address state is locked, wallets MUST NOT allow the removal of the Guardian configuration. -### 2. Attack Scenarios +===Attack Scenarios=== -#### Device Theft +====Device Theft==== 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. @@ -152,7 +154,7 @@ After the attack is over and the threat has been mitigated, Bob is able to recov If Bob regains the device, he is able to recover access to his wallet(s) by broadcasting a Guardian Unlock transaction with the private key of the Guardian Address. No UTXOs could be spent while the device was stolen since Bob locked the wallet(s). Now Bob has unlocked the wallet(s) he has the ability to spend UTXOs that were previously locked. -#### Public Figure +====Public Figure==== Alice the attacker. Bob the Bitcoin public figure. Bob's public status makes him a target for threat actors. Bob wants a balance between his own personal freedom and security from physical attacks. He keeps a private security team on response near his residence, but lives in his family house with privacy. @@ -160,7 +162,7 @@ Alice is an intruder that is attempting to break into the house to demand bitcoi The security team has also been alerted since they monitor the Guardian Address. They do not know which wallets belong to Bob, maintaining his privacy while keeping his bitcoin safe. His physical security has been protected with the response ensuring his family's safety. -### 3. Threat Model and Limitations +===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. @@ -311,8 +313,4 @@ With thanks to @thec00n @OzMozis for feedback and comments of this BIP. This BIP has been possible due to diligent prior and ongoing work by Jameson Lopp into physical attacks in the Bitcoin ecosystem. ==References== - -[^1]: Investigating Wrench Attacks, DOI: 10.4230/LIPIcs.AFT.2024.24 -[^2]: https://github.com/jlopp/physical-bitcoin-attacks -[^3]: https://river.com/learn/how-many-people-use-bitcoin/ -[^4]: BIP-A https://github.com/bitcoin/bips/ + \ No newline at end of file From c61073c80a5054691ba6d9ae8c382c1750ff465c Mon Sep 17 00:00:00 2001 From: Bitcoin Guardian Date: Tue, 7 Oct 2025 19:16:20 +0700 Subject: [PATCH 07/10] [guardian] More format fixes --- bip-guardian-wallet.mediawiki | 47 ++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/bip-guardian-wallet.mediawiki b/bip-guardian-wallet.mediawiki index c2bb89e116..affe523133 100644 --- a/bip-guardian-wallet.mediawiki +++ b/bip-guardian-wallet.mediawiki @@ -59,10 +59,10 @@ This is the state of an unconfigured Guardian Address in a wallet. No Guardian A * Wallets MUST reject any address that matches a spending address managed by the wallet, to enforce key separation and accidental spending of the Guardian signal UTXO. * Wallets MUST ensure that a Guardian Address maintains at least one reserved UTXO for signalling purposes. * Wallets MUST validate the address by querying the blockchain and mempool for signals: - - MUST Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII raw ≤40 bytes. Signals MUST match the grammar defined in BIP-A (note: placeholder until BIP assignment). - - MUST Sort them by nonce in ascending order. - - MUST Reject if no signals exist (address not instantiated) or if the highest nonce signal sets `Lock=true`. This prevents accidental locking of the wallet with a Guardian Address outside of the user's control. - - MUST Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate a potential nonce exhaustion issue). + * MUST Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII raw ≤40 bytes. Signals MUST match the grammar defined in BIP-A (note: placeholder until BIP assignment). + * MUST Sort them by nonce in ascending order. + * MUST Reject if no signals exist (address not instantiated) or if the highest nonce signal sets `Lock=true`. This prevents accidental locking of the wallet with a Guardian Address outside of the user's control. + * MUST Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate a potential nonce exhaustion issue). * If valid, store the address state and its current highest nonce locally. * Wallets MUST transition to Guardian Monitoring if these operations complete. @@ -81,46 +81,46 @@ This is the state of an unconfigured Guardian Address in a wallet. No Guardian A * Signal transactions MUST be treated equally whether they are included in a block or still in the mempool. * Wallets MUST warn users if the Guardian balance drops to zero or UTXOs are moved without a valid signal `OP_RETURN`. * Wallets MUST validate the address by querying the blockchain and mempool for signals: - - Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-ABIP-A https://github.com/bitcoin/bips/ + * Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-ABIP-A https://github.com/bitcoin/bips/ (note: placeholder until BIP assignment). - - Sort them by nonce in ascending order. - - Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate potential nonce exhaustion issues). + * Sort them by nonce in ascending order. + * Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate potential nonce exhaustion issues). * Wallets MUST store the current block as the previously checked block. This optimizes for speed at wallet startup. * Wallets MUST transition to Guardian State Evaluation if signals present. * Wallets MUST wait for the polling interval before checking for new signals. ====Guardian State Evaluation==== -**Nonce Conflict Resolution** +=====Nonce Conflict Resolution===== Guardian signals use a monotonic nonce to prevent replay attacks and ensure deterministic evaluation of the Guardian state. Wallets MUST resolve conflicts between signals using the following rules: -**Monotonicity** +=====Monotonicity===== * Nonces MUST be strictly greater than the last observed valid nonce. * Wallets MUST ignore any signal with a nonce less than or equal to the locally stored nonce of the configured Guardian Address. * Wallets MUST warn the user if a stale nonce is observed. -**Duplicate Nonces** +=====Duplicate Nonces===== * If two signals share the same nonce and are both confirmed on-chain, the transaction included at the earliest block height MUST take precedence. * If two signals share the same nonce and are both unconfirmed in the mempool, wallets MUST treat the first seen transaction (by mempool arrival time) as canonical until confirmation. * Once one of the duplicates is confirmed, the confirmed transaction MUST override any unconfirmed duplicate. Local storage MUST be updated accordingly. * Wallets MUST warn the user if duplicate nonce usage is detected with different payloads. -**Invalid Nonces** +=====Invalid Nonces===== * Nonces are 32 bit unsigned integers (0 ≤ nonce ≤ 2^32-1). Values outside this range MUST be rejected and MUST warn the user. * Wallets SHOULD alert the user if the nonce exceeds a high value (e.g., 65,535) to indicate possible nonce exhaustion or misconfiguration. -**Mempool Conditions** +=====Mempool Conditions===== * Wallets MUST treat a signal as effective once it is visible in the mempool, without waiting for block inclusion. * If such a signal later disappears (due to eviction, replacement, or block reorg), wallets MUST retain the resulting state until a higher nonce signal is observed. This ensures wallets are locked in adversarial mempool conditions. Store a local `signal_observed` record that includes `txid`, `nonce`, `observed_time`, and `state` (`Lock`/`Unlock`) so users can audit why the wallet Guardian state has changed. * Wallets MUST NOT revert to an earlier state purely because the mempool transaction disappeared. * To mitigate censorship, users SHOULD broadcast signals to multiple mining pools. -**Latest State Selection** +=====Latest State Selection===== * At any given evaluation, the signal with the highest valid nonce MUST be interpreted as the latest Guardian state, regardless of confirmation status. * Signals MUST be processed in ascending nonce order to ensure sequential evaluation. @@ -142,7 +142,7 @@ Guardian signals use a monotonic nonce to prevent replay attacks and ensure dete * Wallets MUST validate the existing configured Guardian Address in local storage is unlocked. * If the Guardian Address state is locked, wallets MUST NOT allow the removal of the Guardian configuration. -===Attack Scenarios=== +==Attack Scenarios== ====Device Theft==== @@ -162,7 +162,7 @@ Alice is an intruder that is attempting to break into the house to demand bitcoi The security team has also been alerted since they monitor the Guardian Address. They do not know which wallets belong to Bob, maintaining his privacy while keeping his bitcoin safe. His physical security has been protected with the response ensuring his family's safety. -===Threat Model and Limitations=== +==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. @@ -258,23 +258,23 @@ Users SHOULD NOT make transactions on-chain between their Guardian Address and t ==Rationale== -**UTXO Fragility vs. Key Fragility** +===UTXO Fragility vs. Key Fragility=== Users face a trade off between carrying Guardian key material and relying on pre-signed transactions. Carrying the key increases coercion risk, since an attacker could force the user to sign a transaction under duress. Pre-signed transactions avoid this risk but introduce UTXO fragility: if the referenced UTXO is spent or becomes invalid, the pre-signed transaction cannot be used. This proposal favors pre-signed transactions as the safer approach under coercion scenarios. They minimize the risk of key compromise, enable rapid signalling, and allow users to keep Guardian keys physically separate from everyday devices. -**Single vs. Multiple Guardians** +===Single vs. Multiple Guardians=== Managing multiple Guardians introduces significant complexity. Each Guardian requires its own key, increasing operational overhead. Because this is a signalling protocol, conflicting messages are possible. For example, one Guardian may broadcast a Lock while another broadcasts an Unlock. Resolving such conflicts would require an arbitration mechanism, adding ambiguity and complexity to wallet behavior. To avoid these issues, this proposal specifies support for a single Guardian Address. This ensures deterministic state evaluation, simplifies implementation, and reduces the risk of misconfiguration. -**Nonce Encoding** +===Nonce Encoding=== The nonce is encoded as a decimal ASCII integer for human readability and ease of debugging. While binary encodings were considered, they provide minimal space savings (10 bytes vs. 4) at the cost of greater implementation complexity. -**Justification of OP_RETURN Usage** +===Justification of OP_RETURN Usage=== Guardian signals must be effective as soon as they are broadcast to the mempool, not after block inclusion. Taproot leaf commitments or covenants are invisible until mined, which makes them unsuitable for realtime coercion response. @@ -295,10 +295,11 @@ Therefore, `OP_RETURN` is the minimal, mempool visible, backwards compatible cho ==Reference Implementation== An implementation in Electrum demonstrates the Guardian Address signal protocol, including: -- Configuration of a Guardian Address in wallet settings. -- Mempool and blockchain polling for OP_RETURN signals. -- State machine handling for Lock/Unlock transitions, preventing UTXO spends when locked. -- Signal generation via a standalone Python tool for creating pre-signed Lock/Unlock transactions. + +* Configuration of a Guardian Address in wallet settings. +* Mempool and blockchain polling for OP_RETURN signals. +* State machine handling for Lock/Unlock transitions, preventing UTXO spends when locked. +* Signal generation via a standalone Python tool for creating pre-signed Lock/Unlock transactions. The source code 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. From b2e7b666336897c0a4abe5068000204b91eec03e Mon Sep 17 00:00:00 2001 From: Bitcoin Guardian Date: Tue, 7 Oct 2025 19:30:31 +0700 Subject: [PATCH 08/10] [guardian] Mediawiki fixes --- bip-guardian-wallet.mediawiki | 66 +++++++++++++++++------------------ 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/bip-guardian-wallet.mediawiki b/bip-guardian-wallet.mediawiki index affe523133..2d3d04aa58 100644 --- a/bip-guardian-wallet.mediawiki +++ b/bip-guardian-wallet.mediawiki @@ -15,7 +15,7 @@ This proposal introduces the concept of a Guardian Address and defines a standard signalling mechanism that allows bitcoin wallets to become locked in response to an activation event. A single external control address triggers a security lockdown across one or more unrelated wallets without requiring any on-chain linkage between them. The goal is to prevent theft of bitcoin by enabling users to broadcast a standardized on-chain lock that causes cooperating wallets to enter a restricted mode, disabling the ability to spend UTXOs under duress. -The design allows a separation of key material between the user's spending wallet and a Guardian Address; a discrete identity that signals lock state changes via a transaction embedding data in an `OP_RETURN` (~$1 at 2.31 sat/vB, ~1BTC=124K USD). This enables emergency responders, user level software, and wallet applications to recognize a distress signal without exposing user spending address(es) or balances. Rapid wallet responses with fast wallet locks (95% signal detection in <10s on testnet3) enable coordination with a physical response. +The design allows a separation of key material between the user's spending wallet and a Guardian Address; a discrete identity that signals lock state changes via a transaction embedding data in an OP_RETURN (~$1 at 2.31 sat/vB, ~1BTC=124K USD). This enables emergency responders, user level software, and wallet applications to recognize a distress signal without exposing user spending address(es) or balances. Rapid wallet responses with fast wallet locks (95% signal detection in <10s on testnet3) enable coordination with a physical response. Adoption requires minimal overhead for wallet developers. This approach does not alter spending rules. It is a voluntary signalling protocol that requires adoption by wallet and custodial software to be effective. BIP compliant wallets will be able to offer this security mechanism without compromising privacy or usability. This standard is intended to be optional and without breaking compatibility for existing wallets or nodes. @@ -24,8 +24,8 @@ Adoption requires minimal overhead for wallet developers. This approach does not Bitcoin users are increasingly the targets of physical threats including robbery and coercion.Investigating Wrench Attacks, DOI: 10.4230/LIPIcs.AFT.2024.24 A non-exhaustive list is maintained with details of physical attacks on bitcoin usershttps://github.com/jlopp/physical-bitcoin-attacks, which provides some insight into the prevalence and severity of attacks. Notably the incidence of attacks is also increasing. Security controls have been implemented in some self-hosted wallets as a means to prevent theft of bitcoin. One such is a decoy wallet, which presents a wallet with a smaller balance of bitcoin when a duress PIN is entered. However, this comes with two significant downsides: -- An assumption is made that the attacker does not know about or understand the purpose of a decoy wallet. If a sophisticated attacker is able to link an address to the real world identity of the user, they may already know the true balance of the bitcoin holder. If the attacker does not know the balance of the user they are attacking, they may still suspect the user has unlocked a decoy wallet given the lower than anticipated balance. -- In the case that the attacker does not know the wallet opened is a decoy wallet, the attack still results in the loss of bitcoin for the user. +* An assumption is made that the attacker does not know about or understand the purpose of a decoy wallet. If a sophisticated attacker is able to link an address to the real world identity of the user, they may already know the true balance of the bitcoin holder. If the attacker does not know the balance of the user they are attacking, they may still suspect the user has unlocked a decoy wallet given the lower than anticipated balance. +* In the case that the attacker does not know the wallet opened is a decoy wallet, the attack still results in the loss of bitcoin for the user. Current self-custody solutions do not provide a safe way to respond under physical duress without risking loss of funds. In addition, participants in the Bitcoin ecosystem commonly use both self-hosted and centralized serviceshttps://river.com/learn/how-many-people-use-bitcoin/. There's no mechanism that currently exists that can act as a self-sovereign "kill switch" for both user scenarios of a self-hosted wallet or a user with a self-hosted and centralized wallet. @@ -33,11 +33,11 @@ In addition, existing self-custody solutions do not support integration with a p This proposal introduces an interoperable mechanism to: -- Allow users to trigger a wallet lockdown using a separate device or operation. -- Preserve privacy by decoupling the Guardian Address from wallet addresses. -- Enable wallet software to observe chain state and mempool to react defensively, signalling an active attack. -- Protect a multiple wallet user (e.g., self-custodial wallet, exchange account, institutional wallet, custodian) with a single on-chain emergency trigger. -- Allow businesses or multi-user custodial setups designating a Guardian Address to coordinate responses and align with risk management frameworks. +* Allow users to trigger a wallet lockdown using a separate device or operation. +* Preserve privacy by decoupling the Guardian Address from wallet addresses. +* Enable wallet software to observe chain state and mempool to react defensively, signalling an active attack. +* Protect a multiple wallet user (e.g., self-custodial wallet, exchange account, institutional wallet, custodian) with a single on-chain emergency trigger. +* Allow businesses or multi-user custodial setups designating a Guardian Address to coordinate responses and align with risk management frameworks. ==Specification== @@ -59,10 +59,10 @@ This is the state of an unconfigured Guardian Address in a wallet. No Guardian A * Wallets MUST reject any address that matches a spending address managed by the wallet, to enforce key separation and accidental spending of the Guardian signal UTXO. * Wallets MUST ensure that a Guardian Address maintains at least one reserved UTXO for signalling purposes. * Wallets MUST validate the address by querying the blockchain and mempool for signals: - * MUST Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII raw ≤40 bytes. Signals MUST match the grammar defined in BIP-A (note: placeholder until BIP assignment). - * MUST Sort them by nonce in ascending order. - * MUST Reject if no signals exist (address not instantiated) or if the highest nonce signal sets `Lock=true`. This prevents accidental locking of the wallet with a Guardian Address outside of the user's control. - * MUST Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate a potential nonce exhaustion issue). + ** MUST Collect all valid signals from the Guardian Address with an OP_RETURN signal matching the grammar: guardv1.Lock=(true|false)#, case sensitive, ASCII raw ≤40 bytes. Signals MUST match the grammar defined in BIP-A (note: placeholder until BIP assignment). + ** MUST Sort them by nonce in ascending order. + ** MUST Reject if no signals exist (address not instantiated) or if the highest nonce signal sets Lock=true. This prevents accidental locking of the wallet with a Guardian Address outside of the user's control. + ** MUST Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate a potential nonce exhaustion issue). * If valid, store the address state and its current highest nonce locally. * Wallets MUST transition to Guardian Monitoring if these operations complete. @@ -79,12 +79,12 @@ This is the state of an unconfigured Guardian Address in a wallet. No Guardian A * The configured Guardian Address MUST be checked every time a new block is created, even if the block is produced before the polling interval. * The Guardian Address MUST be polled for transactions that are pending in the mempool. * Signal transactions MUST be treated equally whether they are included in a block or still in the mempool. -* Wallets MUST warn users if the Guardian balance drops to zero or UTXOs are moved without a valid signal `OP_RETURN`. +* Wallets MUST warn users if the Guardian balance drops to zero or UTXOs are moved without a valid signal OP_RETURN. * Wallets MUST validate the address by querying the blockchain and mempool for signals: - * Collect all valid signals from the Guardian Address with an `OP_RETURN` signal matching the grammar: `guardv1.Lock=(true|false)#`, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-ABIP-A https://github.com/bitcoin/bips/ + ** Collect all valid signals from the Guardian Address with an OP_RETURN signal matching the grammar: guardv1.Lock=(true|false)#, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-ABIP-A https://github.com/bitcoin/bips/ (note: placeholder until BIP assignment). - * Sort them by nonce in ascending order. - * Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate potential nonce exhaustion issues). + ** Sort them by nonce in ascending order. + ** Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate potential nonce exhaustion issues). * Wallets MUST store the current block as the previously checked block. This optimizes for speed at wallet startup. * Wallets MUST transition to Guardian State Evaluation if signals present. * Wallets MUST wait for the polling interval before checking for new signals. @@ -116,7 +116,7 @@ Guardian signals use a monotonic nonce to prevent replay attacks and ensure dete =====Mempool Conditions===== * Wallets MUST treat a signal as effective once it is visible in the mempool, without waiting for block inclusion. -* If such a signal later disappears (due to eviction, replacement, or block reorg), wallets MUST retain the resulting state until a higher nonce signal is observed. This ensures wallets are locked in adversarial mempool conditions. Store a local `signal_observed` record that includes `txid`, `nonce`, `observed_time`, and `state` (`Lock`/`Unlock`) so users can audit why the wallet Guardian state has changed. +* If such a signal later disappears (due to eviction, replacement, or block reorg), wallets MUST retain the resulting state until a higher nonce signal is observed. This ensures wallets are locked in adversarial mempool conditions. Store a local signal_observed record that includes txid, nonce, observed_time, and state (Lock/Unlock) so users can audit why the wallet Guardian state has changed. * Wallets MUST NOT revert to an earlier state purely because the mempool transaction disappeared. * To mitigate censorship, users SHOULD broadcast signals to multiple mining pools. @@ -166,7 +166,7 @@ The security team has also been alerted since they monitor the Guardian Address. Guardian Addresses will not protect wallets that are airgapped or otherwise unable to query address state from the latest block height. -If a Guardian Address key is lost or compromised, the user MUST rotate to a new Guardian Address. Wallet funds are unaffected since the Guardian cannot spend UTXOs, but monitoring and `Lock/Unlock` state depends on a secure Guardian. +If a Guardian Address key is lost or compromised, the user MUST rotate to a new Guardian Address. Wallet funds are unaffected since the Guardian cannot spend UTXOs, but monitoring and Lock/Unlock state depends on a secure Guardian. 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. @@ -206,29 +206,29 @@ Guardian Addresses should be considered an additional layer of defense against c ==Compatibility== -The proposal is backwards compatible with existing wallets and Bitcoin nodes as it uses standard address formats and `OP_RETURN`. Non-cooperative wallets will ignore the signalling mechanism. This BIP does not attempt to cryptographically restrict spending conditions at the consensus layer. +The proposal is backwards compatible with existing wallets and Bitcoin nodes as it uses standard address formats and OP_RETURN. Non-cooperative wallets will ignore the signalling mechanism. This BIP does not attempt to cryptographically restrict spending conditions at the consensus layer. -Vault and covenant constructions (e.g., pre-signed vaults, deleted key covenants, or future consensus changes such as `OP_VAULT` or `OP_CHECKTEMPLATEVERIFY`) provide enforceable spending constraints that protect coins even if signing keys are compromised. These tools are powerful for self custody, but they apply only to UTXOs that have been intentionally placed under covenant rules, and they cannot directly influence how centralized custodians manage user balances. +Vault and covenant constructions (e.g., pre-signed vaults, deleted key covenants, or future consensus changes such as OP_VAULT or OP_CHECKTEMPLATEVERIFY) provide enforceable spending constraints that protect coins even if signing keys are compromised. These tools are powerful for self custody, but they apply only to UTXOs that have been intentionally placed under covenant rules, and they cannot directly influence how centralized custodians manage user balances. The Guardian Address standard is intended to be complementary to spending rule mechanisms. It can operate across both self-hosted and custodial wallets, providing a uniform way to trigger emergency responses. This BIP requires no changes to Bitcoin consensus and can be deployed immediately by cooperating wallet software and service providers. It can be combined with vault implementations. For example, a Guardian Lock signal could trigger a watchtower or co-signer to broadcast a pre-signed re-vault transaction, or could instruct a custodian to freeze withdrawals pending further verification. In this layered model, spending rules provide strong technical enforcement, while the Guardian Address provides operational coordination and rapid signalling across diverse custody wallets. Spending rules and Guardian Addresses are synergistic in this respect. -The minimum protocol signalling payload in an `OP_RETURN` output is 19 vBytes for a `Lock` and 20 vBytes for an `Unlock` in version 1 of the protocol. The transaction is built with 20 vBytes for the canonical identifier and operation, and 20 vBytes for the monotonic nonce. The protocol is lightweight enough to ensure Guardian signalling transactions will be relayed by nodes with a default maximum `OP_RETURN` transaction limit of 40 vBytes, such as some Bitcoin Knots deployments. +The minimum protocol signalling payload in an OP_RETURN output is 19 vBytes for a Lock and 20 vBytes for an Unlock in version 1 of the protocol. The transaction is built with 20 vBytes for the canonical identifier and operation, and 20 vBytes for the monotonic nonce. The protocol is lightweight enough to ensure Guardian signalling transactions will be relayed by nodes with a default maximum OP_RETURN transaction limit of 40 vBytes, such as some Bitcoin Knots deployments. ==Security Considerations== This signalling mechanism is an application layer security feature and does not change consensus rules or script enforcement. -A griefing vector exists where an unauthorized third party broadcasts a `Lock` signal from the Guardian Address. This could happen if the griefing attacker gains access to the pre-signed `Lock` signal transaction and broadcasts it to the mempool. However, this lockout is temporary, recoverable, and fully under the user’s control. A monotonic nonce is included in each protocol signal so that even if a pre-signed transaction is obtained and used by an attacker, it may only be used once, limiting the impact of this to a single occurrence. This griefing vector is further mitigated by user education of secure pre-signed transaction storage. The trade off favors wide usability and deployment over strict tamper resistance hardware requirments, since key material is not required to be carried by the user. +A griefing vector exists where an unauthorized third party broadcasts a Lock signal from the Guardian Address. This could happen if the griefing attacker gains access to the pre-signed Lock signal transaction and broadcasts it to the mempool. However, this lockout is temporary, recoverable, and fully under the user's control. A monotonic nonce is included in each protocol signal so that even if a pre-signed transaction is obtained and used by an attacker, it may only be used once, limiting the impact of this to a single occurrence. This griefing vector is further mitigated by user education of secure pre-signed transaction storage. The trade off favors wide usability and deployment over strict tamper resistance hardware requirments, since key material is not required to be carried by the user. -Wallets will always retain the ability to reset their Guardian state by creating a new transaction with `Lock=false` signed by the same Guardian private key and the incrementing monotonic nonce. +Wallets will always retain the ability to reset their Guardian state by creating a new transaction with Lock=false signed by the same Guardian private key and the incrementing monotonic nonce. -Users MUST ensure their pre-signed Lock transactions reference a stable UTXO. Wallets SHOULD warn users if the UTXO required for a pre-signed `Lock` transaction is no longer available. +Users MUST ensure their pre-signed Lock transactions reference a stable UTXO. Wallets SHOULD warn users if the UTXO required for a pre-signed Lock transaction is no longer available. -Non-RBF eliminates the ability to replace pre-signed `Lock` transactions with a tampered `OP_RETURN`, which is crucial for the signal integrity and nonce based replay protection. +Non-RBF eliminates the ability to replace pre-signed Lock transactions with a tampered OP_RETURN, which is crucial for the signal integrity and nonce based replay protection. -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. +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. Users MAY use hardware for managing Guardian key signing with secure storage. @@ -238,17 +238,17 @@ To reduce forced Unlock risks, wallets MAY implement a configurable delay (e.g., The choice of mining pool by the user can affect the response time of the wallets implementing the standard. Private mining pools are sometimes used for transaction privacy so that transactions are only visible on-chain once they are included in a block. If a user broadcasts the pre-signed signal transaction to a such a pool, the wallet lock time could be 10 minutes, or even longer depending on the transaction inclusion interval. For this reason users SHOULD broadcast signals to public mining pools so that wallets are able to view and act on the unconfirmed signal before block inclusion. -State changes of the Guardian Address are limited to `10^21 − 1` transitions, making nonce exhaustion an unlikely event given the infrequent nature of signalling transactions. +State changes of the Guardian Address are limited to 10^21 − 1 transitions, making nonce exhaustion an unlikely event given the infrequent nature of signalling transactions. ==Privacy Considerations== -This BIP avoids any on-chain link between a user's spending wallet and their Guardian Address. Because the Guardian Address appears as an independent address posting infrequent signalling transactions with `OP_RETURN`, it is indistinguishable from any other transaction format. +This BIP avoids any on-chain link between a user's spending wallet and their Guardian Address. Because the Guardian Address appears as an independent address posting infrequent signalling transactions with OP_RETURN, it is indistinguishable from any other transaction format. No PII or linking information is included on-chain. Furthermore, wallets that monitor a Guardian Address do so locally. No external observer can deduce which wallets are watching a given Guardian status. Users MAY also periodically rotate their Guardian Address if additional unlinkability is desired. -Guardian Address transactions are infrequent and non-financial in nature. The presence of a Guardian signal in `OP_RETURN` does not expose anything about balances, identity, IP addresses, physical location or wallet associations. +Guardian Address transactions are infrequent and non-financial in nature. The presence of a Guardian signal in OP_RETURN does not expose anything about balances, identity, IP addresses, physical location or wallet associations. No on-chain link between the Guardian and the spending wallets exists. However, wallets implementing the BIP will periodically poll nodes for the latest Guardian state, which could expose a link between the wallet and the Guardian Address. Wallet users on untrusted networks may elect to use a local or private node in environments where the interception of network traffic is a concern. @@ -278,11 +278,11 @@ The nonce is encoded as a decimal ASCII integer for human readability and ease o Guardian signals must be effective as soon as they are broadcast to the mempool, not after block inclusion. Taproot leaf commitments or covenants are invisible until mined, which makes them unsuitable for realtime coercion response. -`OP_RETURN` of ≤83 bytes is standard and supported in Bitcoin Core. The protocol payload is ≤40 bytes, well under relay limits. This ensures protocol transactions will be relayed irrespective of node configuration for this opcode. +OP_RETURN of ≤83 bytes is standard and supported in Bitcoin Core. The protocol payload is ≤40 bytes, well under relay limits. This ensures protocol transactions will be relayed irrespective of node configuration for this opcode. -Using `OP_RETURN` does not consume a spendable UTXO and does not pollute the UTXO set. Alternatives like “dust” marker outputs would bloat UTXO sets. +Using OP_RETURN does not consume a spendable UTXO and does not pollute the UTXO set. Alternatives like “dust” marker outputs would bloat UTXO sets. -Parsing `OP_RETURN` is trivial for wallets. Using Taproot annexes or witness data would complicate light client parsing and prevent efficient use of BIP-158 filters. +Parsing OP_RETURN is trivial for wallets. Using Taproot annexes or witness data would complicate light client parsing and prevent efficient use of BIP-158 filters. Alternatives considered and rejected: @@ -290,7 +290,7 @@ Alternatives considered and rejected: * PSBT/gossip extensions: off-chain, non-universal, not enforceable. * Dedicated covenant: requires consensus change. -Therefore, `OP_RETURN` is the minimal, mempool visible, backwards compatible choice. +Therefore, OP_RETURN is the minimal, mempool visible, backwards compatible choice. ==Reference Implementation== From c22f3d81765c08ae78ea1c6e0385318b1137ecf5 Mon Sep 17 00:00:00 2001 From: Bitcoin Guardian Date: Tue, 7 Oct 2025 19:33:38 +0700 Subject: [PATCH 09/10] [guardian] Fix indentation --- bip-guardian-wallet.mediawiki | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/bip-guardian-wallet.mediawiki b/bip-guardian-wallet.mediawiki index 2d3d04aa58..3946311bfd 100644 --- a/bip-guardian-wallet.mediawiki +++ b/bip-guardian-wallet.mediawiki @@ -59,10 +59,10 @@ This is the state of an unconfigured Guardian Address in a wallet. No Guardian A * Wallets MUST reject any address that matches a spending address managed by the wallet, to enforce key separation and accidental spending of the Guardian signal UTXO. * Wallets MUST ensure that a Guardian Address maintains at least one reserved UTXO for signalling purposes. * Wallets MUST validate the address by querying the blockchain and mempool for signals: - ** MUST Collect all valid signals from the Guardian Address with an OP_RETURN signal matching the grammar: guardv1.Lock=(true|false)#, case sensitive, ASCII raw ≤40 bytes. Signals MUST match the grammar defined in BIP-A (note: placeholder until BIP assignment). - ** MUST Sort them by nonce in ascending order. - ** MUST Reject if no signals exist (address not instantiated) or if the highest nonce signal sets Lock=true. This prevents accidental locking of the wallet with a Guardian Address outside of the user's control. - ** MUST Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate a potential nonce exhaustion issue). +** MUST Collect all valid signals from the Guardian Address with an OP_RETURN signal matching the grammar: guardv1.Lock=(true|false)#, case sensitive, ASCII raw ≤40 bytes. Signals MUST match the grammar defined in BIP-A (note: placeholder until BIP assignment). +** MUST Sort them by nonce in ascending order. +** MUST Reject if no signals exist (address not instantiated) or if the highest nonce signal sets Lock=true. This prevents accidental locking of the wallet with a Guardian Address outside of the user's control. +** MUST Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate a potential nonce exhaustion issue). * If valid, store the address state and its current highest nonce locally. * Wallets MUST transition to Guardian Monitoring if these operations complete. @@ -81,10 +81,10 @@ This is the state of an unconfigured Guardian Address in a wallet. No Guardian A * Signal transactions MUST be treated equally whether they are included in a block or still in the mempool. * Wallets MUST warn users if the Guardian balance drops to zero or UTXOs are moved without a valid signal OP_RETURN. * Wallets MUST validate the address by querying the blockchain and mempool for signals: - ** Collect all valid signals from the Guardian Address with an OP_RETURN signal matching the grammar: guardv1.Lock=(true|false)#, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-ABIP-A https://github.com/bitcoin/bips/ +** Collect all valid signals from the Guardian Address with an OP_RETURN signal matching the grammar: guardv1.Lock=(true|false)#, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-ABIP-A https://github.com/bitcoin/bips/ (note: placeholder until BIP assignment). - ** Sort them by nonce in ascending order. - ** Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate potential nonce exhaustion issues). +** Sort them by nonce in ascending order. +** Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate potential nonce exhaustion issues). * Wallets MUST store the current block as the previously checked block. This optimizes for speed at wallet startup. * Wallets MUST transition to Guardian State Evaluation if signals present. * Wallets MUST wait for the polling interval before checking for new signals. From 4ce0258973040d09c7cd2009869e723c8ef39b94 Mon Sep 17 00:00:00 2001 From: Bitcoin Guardian Date: Tue, 7 Oct 2025 19:36:57 +0700 Subject: [PATCH 10/10] [guardian] Remove line --- bip-guardian-wallet.mediawiki | 1 - 1 file changed, 1 deletion(-) diff --git a/bip-guardian-wallet.mediawiki b/bip-guardian-wallet.mediawiki index 3946311bfd..95eee4f4cd 100644 --- a/bip-guardian-wallet.mediawiki +++ b/bip-guardian-wallet.mediawiki @@ -82,7 +82,6 @@ This is the state of an unconfigured Guardian Address in a wallet. No Guardian A * Wallets MUST warn users if the Guardian balance drops to zero or UTXOs are moved without a valid signal OP_RETURN. * Wallets MUST validate the address by querying the blockchain and mempool for signals: ** Collect all valid signals from the Guardian Address with an OP_RETURN signal matching the grammar: guardv1.Lock=(true|false)#, case sensitive, ASCII, ≤40 bytes. Signals MUST match the grammar defined in BIP-ABIP-A https://github.com/bitcoin/bips/ - (note: placeholder until BIP assignment). ** Sort them by nonce in ascending order. ** Reject if the highest nonce is 0 (invalid instantiation) or exceeds a practical high value (e.g., >65,535; wallets SHOULD alert users for high values to indicate potential nonce exhaustion issues). * Wallets MUST store the current block as the previously checked block. This optimizes for speed at wallet startup.