deviant/Parameters/WalletConnect

BCH Connector Protocols — folder map

This folder is the project's reference material for all three BCH dApp↔wallet connector protocols, even though it's named "WalletConnect" for historical reasons (the first one we integrated). Each has its own deep-dive file:

Doc	Status in Deviant	One-line
WalletConnect_integration_reference.md	✅ Implemented + on-device validated (snapshot 0057)	wc2-bch-bcr over WC2 relay — pass-through co-sign, the broadest BCH wallet coverage
CashConnect_reference.md	✅ Implemented (handshake, multi-protocol dispatch) (snapshot 0152). Covenant co-sign blocked by V0 — routes through WC. v-next bch_executeAction model is designed to fix this (see doc §10).	CashRPC = the underlying protocol (transport-agnostic); CashConnect = CashRPC + WalletConnect v2. BCH community, @jimtendo proposal (Dec 2023 BCR forum), merged into Cashonize
WizardConnect_reference.md	⚠️ Research deep-dive, partly stale. Its §0/§3.3 licence claim is WRONG (it is LGPL-3.0, not proprietary) — see the guide below.	Nostr NIP-17 E2E transport + WC2-shape tx payload (inputPaths HD-key metadata). Riften Labs. Test wallet: Cashonize v0.9.0+ (chipnet ✓); Paytaca has no chipnet support.
WIZARDCONNECT-INTEGRATION-GUIDE.md	✅ Implemented (snapshots 0193/0194) + blocking bug fixed 2026-07-27. Remaining work + the on-device test are listed in the guide.	Read this first for anything WizardConnect. Status, verified file:line map, protocol reference, the resolved LGPL question, traps, and a completion checklist.

The runtime that uses all of the above lives at shells/app/src/connect/ (the wallet-side responder, ADR-0043 + snapshot 0152) and src/connect/proposer.ts (the dApp-side proposer, snapshot 0057). The files in this folder are reference copies + dApp-developer documentation.

At-a-glance protocol comparison

	WalletConnect (wc2-bch-bcr)	CashConnect (CashRPC over WC2)	WizardConnect — shipping	WizardConnect — vision
Relay	WC2 (relay.walletconnect.com)	WC2 (same)	WC2 (same)	Nostr
Encryption to relay	TLS only	TLS only	TLS only (same as WC2)	E2E NIP-17 gift-wrap
URI scheme	wc:	cc: (rewritten from wc:)	wc: (WC2 pair)	TBD
Namespace	bch	bch (+ protocol: 'CashRPC:0', template, allowedTokens)	bch (WC2 dialect)	N/A — different transport
Methods (shipping)	bch_getAddresses / bch_signMessage / bch_signTransaction	bch_*_V0-suffixed + wc_authRequest	Same as WC2 + inputPaths extension on the tx object	xpub-driven
Methods (v-next)	—	bch_executeAction (template-bound named actions)	—	—
Account format	bch:<chain>:<cashaddr>	bch:<chain>:<pubkeyHex> (sandboxed per dApp domain)	Same as WC2 + inputPaths metadata	xpub (dApp derives)
signTransaction model	Pass-through (dApp builds, wallet co-signs placeholder inputs)	Wallet-orchestrated (V0). v-next: template-bound bch_executeAction (wallet recognizes contract, shows human-readable action label)	HD-aware pass-through — dApp attaches [inputIndex, pathName, addressIndex] triplets; wallet derives child key and signs	TBD
Wire encoding	libauth stringify, JSON tree of EJSON markers	libauth stringify, single EJSON-string blob	Same as WC2 + inputPaths array	Nostr event
Covenant co-sign?	✅ Yes (validated 0057)	❌ No at V0 (structural — see CC §6). v-next: yes via template-bound actions	Should work — pass-through inherits WC2 covenant support	TBD
Standard sends?	✅	✅	✅	TBD
Wallets	Cashonize, Paytaca, others	Cashonize	Cashonize v0.9.0+ (chipnet ✓), Paytaca (mainnet only — no chipnet), Deviant	(future)
dApps	Cauldron, BCH Bull, Tote/Checkers, Flipstarter, …	(CC's audience overlaps with WC)	Anything attaching inputPaths to WC2 tx objects	ParyonUSD
License (SDK)	MIT	MIT	LGPL-3.0-or-later + CLA	Same
Reown project ID needed?	Yes	Yes (same one)	Yes (same one — extends WC2)	No
Author / origin	Reown (formerly WalletConnect Inc.)	BCH community, @jimtendo (2023 BCR proposal)	Riften Labs	Riften Labs

The Deviant routing rule (what users never see) — revised 2026-07-04

Multi-protocol wallets (Cashonize, the Deviant wallet) speak both WC + CC. Users just paste a URI and approve; the wallet routes by proposal/request shape (shells/app/src/connect/classifier.ts):

Flow	Protocol the dApp should choose
User outbound BCH send / token send (wallet → external)	WC or CC — both fine
Position-tolerant dApp covenant (covenant at fixed positions, wallet-added inputs at positions 1+, wallet-added change at positions 1+) — e.g. BCH Guru, position-tolerant Cauldron pools	WC or CC — both fine. CC requires shipping the libauth WalletTemplate at proposal time
Count-strict dApp covenant (exact input/output count invariants that break under wallet auto-orchestration)	WC only — true pass-through per snapshot 0057
Authentication / message-sign	either
Multiple concurrent sessions of either protocol	supported natively (isolated by topic)

Correction to a previous version of this table (2026-07-04): the sweeping "CC V0 can't carry covenant unlockers → WC only for all covenants" rule was wrong. BCH Guru is a live counter-example — their prediction-game covenant ships over CashConnect V0 with Cashonize. See CashConnect_reference.md §6 for the corrected mechanism (dApp ships libauth WalletTemplate at proposal time; wallet compiles via walletTemplateToCompilerBCH; covenant must be position-tolerant).

Folder contents at a glance

Parameters/WalletConnect/
├── README.md                                  ← this map
│
├── WalletConnect_integration_reference.md     ← WC2 (wc2-bch-bcr) full reference
├── CashConnect_reference.md                   ← CashConnect (CashRPC v0) full reference
├── WizardConnect_reference.md                 ← WizardConnect research + future-impl notes
│
├── dapp-side/                                 ← shared proposer-side primitives
│   ├── proposer.ts                            (validated cashscript co-sign helpers)
│   └── index.ts
│
├── wallet-side/                               ← reference responder (multi-protocol)
│   ├── responder.ts                           (live WalletKit listener + dispatcher)
│   ├── classifier.ts                          (WC vs CC routing — pure)
│   ├── signer.ts                              (libauth co-signer w/ isOwnedInput guard)
│   ├── wc-handler.ts                          (bch_getAddresses / signMessage / signTransaction)
│   ├── bch-namespace.ts                       (constants — chains, methods, account formats)
│   └── index.ts
│
└── examples/                                  ← runnable dApp test scripts
    ├── dapp-connect-example.mjs               (pair + getAddresses + signMessage)
    ├── dapp-signtx-example.mjs                (bch_signTransaction co-sign)
    ├── spike-readme.md                        (spike directory README)
    └── spike-testing.md                       (testing notes from real device runs)

A cc-handler.ts should be added to wallet-side/ once the reference snapshot catches up to the current implementation — left as a TODO so the folder stays in sync with shells/app/src/connect/.

Cross-references

• Runtime: shells/app/src/connect/ (multi-protocol responder, ADR-0043)
• dApp side: src/connect/proposer.ts (validated against Cashonize, snapshot 0057)
• Design: wiki/connector.md (full multi-protocol design)
• Decisions: wiki/decisions.md ADR-0041 (WC origin), ADR-0043 (multi-protocol)
• Snapshots: 0055 (WC handshake) → 0057 (WC co-sign) → 0061 (CC API pinned) → 0062 (bundle patch + structural finding) → 0152 (multi-protocol runtime) → 0153 (QR scanner + WizardConnect research)
• Ecosystem context: ../dApp/BitcoinCashExistingEcosystem/ (wallets + dApps that speak any of the above)