ercref / ercref/ercref-contracts

FR: Modernize ERC-4527 (QR transmission protocol) and build a reference implementation

Open
#63 18 comments 0 reactions 0 assignees View on GitHub
enhancement help wanted
Dominant language
Solidity
Stars
55
Forks
5
PR merge metrics
No merged PRs in 30d

Description

## Summary

[ERC-4527 "QR Code transmission protocol for wallets"](https://eips.ethereum.org/EIPS/eip-4527) has been **`Stagnant`** since its creation (Created: 2021-12-07, no activity for 6+ months). The standard describes an offline/air-gapped QR-code request–response protocol between dApps/watch-only wallets and offline signers (e.g. Keystone, AirGap Vault, Ngrave), built on **BC-UR** (Blockchain Commons Uniform Resources).

Meanwhile the underlying ecosystem (BC-UR + `crypto-*` / `eth-*` UR types) has kept evolving and is shipping in real hardware wallets — so the formal ERC is out of sync with practice. This issue proposes to (1) **modernize the ERC** and (2) **provide a reference implementation in this repo**.

## Motivation

- The protocol works and is interoperable in shipping wallets, but the ERC text is frozen at 2021 and marked Stagnant, so there is no authoritative, up-to-date spec to point to.
- There is no canonical, vendor-neutral reference implementation that demonstrates the full round-trip (dApp shows QR → offline signer scans → signer shows QR → dApp scans back).
- ERCRef's mission explicitly covers both ERC drafting discussions and reference implementations — this is squarely in scope.

## Scope

### Part 1 — Modernize the ERC
- [ ] Move the proposal out of `Stagnant` (reopen as `Draft` / `Review`).
- [ ] Reconcile the spec with the current **BC-UR** registry and the UR types actually used in production (`eth-sign-request`, `eth-signature`, `crypto-hdkey`, `crypto-account`, etc.).
- [ ] Cover modern signing payloads beyond legacy txs: EIP-1559 typed txs, `personal_sign`, EIP-712 `eth_signTypedData_v4`, and EIP-4337 UserOperations.
- [ ] Specify multi-part / animated QR (UR fragmentation) behavior and versioning.
- [ ] Add interoperability notes vs. WalletConnect (online relay) to clarify the air-gapped niche.
- [ ] Update references, test vectors, and security considerations.

### Part 2 — Reference implementation (this repo)
- [ ] Off-chain TS/JS reference lib demonstrating encode/decode of the UR request/response types (build on the maintained BC-UR libraries, e.g. `@ngraveio/bc-ur` / `@keystonehq/bc-ur-registry-eth`).
- [ ] A minimal demo dApp: render an animated request QR and read back a signed-response QR via webcam.
- [ ] Test vectors covering each payload type (legacy/1559 tx, personal_sign, EIP-712, UserOp).
- [ ] Round-trip / interop tests; document which hardware signers were verified against.
- [ ] README + usage docs, wired into the `@ercref/contracts` packaging conventions.

## Notes / open questions

- ERC-4527 is primarily an **off-chain transmission protocol**, so the "reference implementation" here is a TS/JS library + demo rather than a Solidity contract — confirm desired home/layout in this repo.
- Decide whether to align directly with BC-UR as the normative dependency, or to re-specify the UR types inline in the ERC.
- Coordinate with original author(s) and current BC-UR / hardware-wallet implementers before re-submitting upstream.

## References
- ERC-4527: https://eips.ethereum.org/EIPS/eip-4527
- BC-UR (Blockchain Commons Uniform Resources): https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2020-005-ur.md

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading ERC-4527 and the linked BC-UR paper, then inspect the repository's @ercref/contracts packaging conventions; the payload names no implementation files or tests. Resolve the normative-dependency and home/layout questions with maintainers before proceeding. Done means an updated ERC, TS/JS reference library and demo, payload test vectors, interoperability tests, hardware-signer notes, and README usage documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, solidity, typescript
Domain
blockchain, cryptography, documentation, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.