> For the complete documentation index, see [llms.txt](https://bsv.brc.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bsv.brc.dev/wallet/0219.md). # Wallet Permission Prompt Liveness Contract Ty Everett () ## Abstract This BRC defines the liveness contract for wallet requests that require user permission. When an application sends a valid wallet request and the wallet requires user consent before responding, the request is allowed to remain pending until the user grants or denies the request. Application developers should treat such pending requests as normal wallet behavior, not as failures to be timed out. Wallets, in turn, must ensure that any permission-dependent pending request is visibly and reliably presented to the user on desktop and mobile. ## Motivation Wallet permissions are a user decision, not a server-side availability problem. A user might read the permission details, compare context, switch apps, take a break, or return several minutes later before deciding. Aborting the request because a timer expired breaks the user experience and forces application developers to handle false failures that should never have existed. The correct abstraction is simple: 1. If a wallet request is pending because user permission is required, the wallet must be asking the user. 2. If the wallet is not asking the user, the request must not remain pending for permission. 3. If a wallet implementation accepts a permission-dependent request but fails to surface the prompt, that is a wallet bug. 4. Applications should not be required to paper over invisible or broken wallet prompts with permission timeouts. This BRC exists to make that contract explicit across desktop wallets, mobile wallets, embedded wallets, browser wallets, and application developers. ## Specification ### Definitions * **Application**: Software that calls a BSV wallet interface, including web apps, native apps, servers, command-line tools, and background workers. * **Wallet**: Software that implements a BSV wallet interface and controls keys, permissions, transactions, baskets, certificates, or related user-owned wallet state. * **Permission-required request**: A valid wallet request that the wallet cannot complete until the user grants or denies permission. * **Prompt**: The wallet-controlled user interface through which the user grants or denies a permission-required request. * **Pending request**: A request for which the application has not yet received a success or error response. * **Interactive wallet**: A wallet implementation with a user interface capable of asking the user for permission. * **Non-interactive wallet**: A wallet implementation without a user interface capable of asking the user for permission, such as a server-side wallet, daemon, or CI wallet. ### Core Contract When an interactive wallet receives a valid permission-required request, it must either: 1. present a prompt to the user and keep the application request pending until the user grants or denies it; or 2. immediately return an error indicating that the wallet cannot request the required permission. An interactive wallet must not accept a permission-required request, fail to present a prompt, and leave the application request pending. Applications should not impose permission-specific timeouts on wallet requests. A pending permission-required request means the wallet is waiting for the user. The application may show its own waiting state, but it should not abort the wallet request merely because the user has not yet answered. Wallets and wallet communication substrates must not abort a permission-required request solely because a fixed amount of wall-clock time elapsed. If the wallet remains connected and the permission request is still active, the request may remain pending for as long as the user has not made a decision. The intended binary is explicit: if a connected wallet request appears to "hang" at the application boundary, the application developer should be able to assume that the wallet is asking the user. If that assumption is false, the wallet is non-compliant. ### Prompt Visibility Requirements If the wallet keeps a permission-required request pending, the prompt must be available to the user. Desktop wallets must make the prompt visible or attention-requesting through normal desktop affordances. This can include focusing or raising the wallet window, opening a modal within an already visible wallet window, bouncing or highlighting the application icon, or otherwise making it clear that the wallet is asking for a decision. Mobile wallets must present the prompt through a native or application-level surface appropriate for the platform. This can include an in-app modal, bottom sheet, native alert, foregrounded wallet activity, notification-driven return path, or equivalent platform mechanism. In all cases, the prompt must identify enough context for the user to make a meaningful decision, including the requesting application or origin where available, the requested capability, and whether the request is one-time, persistent, or renewable where such distinction applies. ### Grant and Deny Semantics When the user grants the request, the wallet must complete the original pending application request with the successful result for the requested wallet method. When the user denies the request, the wallet must complete the original pending application request with an error indicating that permission was denied. The wallet must not require the application to poll a separate endpoint, retry the original request, or infer the decision from side effects. ### Non-Interactive Wallets Non-interactive wallets must not hang waiting for permission. Since there is no user prompt surface, a non-interactive wallet must either: 1. satisfy the request from existing policy, configuration, or pre-granted authority; or 2. reject the request with a clear permission or policy error. Servers, CI systems, and daemons should therefore have deterministic wallet behavior. Permission-pending liveness is an interactive-wallet concept only. ### Requests That Do Not Seek Permission If a request explicitly indicates that permission should not be sought, the wallet must not open a prompt for that request. If the request cannot be completed under existing permissions, the wallet must return a clear error rather than wait for user action. If a request is a wallet status, readiness, network, version, or authentication probe, the wallet must not use that request to trigger a permission prompt. ### Mobile Continuity Mobile wallets must preserve permission-required requests across ordinary mobile lifecycle events where the wallet process and request context remain alive. Backgrounding, app switching, screen lock, short suspension, orientation changes, and navigation within the wallet must not cause the application request to hang silently. After resume, the wallet must either: 1. keep the original prompt available; 2. restore an equivalent prompt for the same pending request; or 3. complete the request with a clear cancellation or lifecycle error if the original request can no longer be represented safely. A mobile wallet must not lose the prompt while leaving the application request pending. ### Disconnections and Process Termination This BRC does not require wallets to preserve an in-memory request after process termination, device restart, browser tab destruction, transport disconnection, or operating-system termination of the wallet process. If the request context is lost, the wallet or substrate should fail the request clearly when possible. If the communication channel itself is destroyed, normal transport failure rules apply. ### Application Developer Expectations Application developers should treat a connected wallet request as having three broad outcomes: 1. success; 2. explicit wallet error, including permission denial; or 3. a pending user decision when the wallet requires permission. Applications should avoid adding custom permission timeout handling. If an application displays a waiting screen, it should explain that the user may need to answer a wallet prompt. Applications may still use ordinary transport-level failure handling for disconnected sockets, closed browser tabs, process exits, HTTP connection failures, or other conditions where the wallet is no longer connected. These are not permission timeouts. ### Wallet Developer Requirements Wallet developers must treat invisible prompts, lost prompts, unresponsive prompt buttons, hidden prompt windows, unresumable mobile prompts, and pending requests without a visible decision path as wallet defects. Wallets should test and instrument the full permission lifecycle: 1. request accepted; 2. prompt rendered or otherwise made available; 3. grant or deny selected; 4. original request resolved or rejected; 5. prompt dismissed and wallet state updated. The purpose of this instrumentation is wallet correctness, not application exception handling. ## Compatibility This BRC is compatible with existing BSV wallet interfaces. It does not define new wallet methods or change the payload shape of existing request and response messages. It clarifies the expected liveness behavior of permission-required requests. Wallets that currently apply fixed permission-request timeouts should remove them or limit them only to transport/session failure conditions where the wallet is no longer capable of showing a prompt or receiving a user decision. Applications that currently abort wallet permission requests after a fixed duration should instead leave the wallet request pending and present user-facing guidance to answer the wallet prompt. ## Implementations Interactive desktop wallets can implement this BRC by making every permission-required request produce a visible wallet prompt and by keeping the original application request open until the user grants or denies it. Interactive mobile wallets can implement this BRC by binding pending permission requests to durable prompt state that survives normal app foreground/background and navigation lifecycle events. Non-interactive wallets can implement this BRC by enforcing deterministic policy and rejecting requests that require unavailable user consent. ## References * [BRC-43: Security Levels, Protocol IDs, Key IDs and Counterparties](/key-derivation/0043.md) * [BRC-56: Unified Abstract Wallet-to-Application Messaging Layer](/wallet/0056.md) * [BRC-73: Group Permissions for App Access](/wallet/0073.md) * [BRC-100: Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface](/wallet/0100.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://bsv.brc.dev/wallet/0219.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.