# 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](https://eips.ethereum.org/EIPS/eip-4527) — 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](https://dev.keyst.one/) — integration guides and documentation
- [keystone-sdk-web](https://github.com/KeystoneHQ/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](https://www.npmjs.com/package/@keystonehq/animated-qr) — animated QR code presenting and scanning
- [keystone-sdk-android-demo](https://github.com/KeystoneHQ/keystone-sdk-android-demo/) — Android demo app
- [keystone-sdk-ios-demo](https://github.com/KeystoneHQ/keystone-sdk-ios-demo/) — iOS demo app
- [Shell by Keystone](https://keyst.one/)
- [BIP-44: Multi-Account Hierarchy for Deterministic Wallets](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
- [BIP-49: Derivation scheme for P2WPKH-nested-in-P2SH](https://github.com/bitcoin/bips/blob/master/bip-0049.mediawiki)
- [BIP-84: Derivation scheme for P2WPKH](https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki)

## Potential for Subsequent λPrizes

No follow-up prize is anticipated at this time.