5.2 KiB
LP-0010: Shell dApp Integration Proof of Concept [CLOSED]
Logos Circle: N/A
Overview
Build a dApp that integrates directly with Shell through QR codes, 100% airgapped, no browser extension. The dApp demonstrates three things: connecting to Shell by scanning a QR code it presents, displaying the user's public keys and addresses across derivation paths (BIP-44 for EVM and Bitcoin legacy, BIP-84 for native SegWit, BIP-49 for nested SegWit), and signing a simple message with one of those keys.
Motivation
This dApp will serve as a reference implementation showing how any dApp can integrate directly with Shell without a browser extension. A working example that developers can read, run, and fork lowers the barrier to building on Shell significantly.
Success Criteria
Functionality
- The dApp connects to Shell by scanning a QR code, with no browser extension or native app required.
- After connection, the dApp displays the user's public keys and addresses for BIP-44 (EVM and Bitcoin legacy), BIP-84 (native SegWit), and BIP-49 (nested SegWit) derivation paths.
- The dApp asks the user for a message to sign and to choose one of the above keys. The dApp then provides a QR code for Shell to sign this message. personal_sign (EIP-191) is used for EVM, and BIP-322 for Bitcoin. Shell scans the QR and returns the signature to the dApp, completing the full QR-based signing round-trip.
- The entire interaction is airgapped — no data leaves or enters Shell except via QR codes.
- Documentation written as a developer integration guide, and a clean public repository under MIT or Apache-2.0.
Reliability
- If a QR scan fails or times out, the dApp surfaces a clear error and allows the user to retry without losing connection state.
- The dApp handles malformed or unexpected QR payloads gracefully without crashing.
Performance
- The animated QR code display renders at a frame rate sufficient for reliable scanning on common mobile devices, documented with the UR library settings used.
Supportability
- End-to-end integration tests covering the connection, address display, and signing flows are included in CI.
- CI must be green on the default branch.
- A README documents end-to-end usage: local build instructions, step-by-step instructions for connecting Shell and completing a signing round-trip, and the QR exchange format.
- A recorded video demo of the end-to-end flow (QR connection, address display, and message signing) is included in the submission.
Scope
In Scope
- Web dApp integrating with Shell via QR codes: connection, address display across derivation paths, and message signing.
- Developer integration guide covering QR exchange format, connection flow, derivation paths, and signing protocol.
Out of Scope
- Browser extensions, transaction broadcasting, full wallet functionality, mobile-native apps.
Prize Structure
- Total Prize: $400
- Effort: Small
Eligibility
Open to any individual or team. Submissions must be original work. Teams must hold the rights to all submitted code and agree to license it under MIT or Apache-2.0.
Submission Requirements
- Public repository with all dApp code under MIT or Apache-2.0.
- Working demo (video or live link) showing connection, address display, and message signing.
- Developer integration guide covering the QR exchange format, connection flow, and signing protocol.
Evaluation Process
Submissions are evaluated first-come-first-served against the success criteria. The first submission that satisfies all criteria wins.
Evaluators will independently clone the repository and run the application from a clean environment. Evaluators may also ask technical follow-up questions to verify authorship and understanding of the implementation.
Resources
- ERC-4527: QR Code Based Air-Gapped Signer Interface — the standard for QR-based communication between airgapped signers and watch-only wallets, built on UR (Uniform Resources). Keystone pioneered this standard and provides mature SDKs implementing it.
- Keystone Developer Portal — integration guides and documentation
- keystone-sdk-web — TypeScript SDK implementing ERC-4527; handles UR encoding/decoding, animated QR codes, and supports both EVM and Bitcoin (including PSBTs and multi-account derivation paths)
- @keystonehq/animated-qr — animated QR code presenting and scanning
- keystone-sdk-android-demo — Android demo app
- keystone-sdk-ios-demo — iOS demo app
- Shell by Keystone
- BIP-44: Multi-Account Hierarchy for Deterministic Wallets
- BIP-49: Derivation scheme for P2WPKH-nested-in-P2SH
- BIP-84: Derivation scheme for P2WPKH
Potential for Subsequent λPrizes
No follow-up prize is anticipated at this time.