90328ff · pear-l2 · pear-git-v3

Changed files (7) +3503 -0

.gitignore +1 -0

…	…	@@ -0,0 +1 @@
	1	node_modules

ARCHITECTURE.md +939 -0

…	…	@@ -0,0 +1,939 @@
	1	# Technical Architecture
	2
	3	## System Overview
	4
	5	```
	6	┌──────────────────────────────────────────────────────────┐
	7	│ Pear Application │
	8	│ ┌────────────┐ ┌─────────────┐ ┌──────────────┐ │
	9	│ │ Wallet │ │ Channel │ │ Network │ │
	10	│ │ Manager │ │ Manager │ │ Manager │ │
	11	│ └────────────┘ └─────────────┘ └──────────────┘ │
	12	└──────────────────────────────────────────────────────────┘
	13	↓ ↓ ↓
	14	┌──────────────┐ ┌─────────────────┐ ┌───────────────┐
	15	│ wdk-wallet │ │ Hypercore │ │ Hyperswarm │
	16	│ -btc │ │ + Autobase │ │ + Secret- │
	17	│ │ │ │ │ stream │
	18	└──────────────┘ └─────────────────┘ └───────────────┘
	19	↓ ↓ ↓
	20	┌──────────────────────────────────────────────────────┐
	21	│ Bitcoin Blockchain │
	22	└──────────────────────────────────────────────────────┘
	23	```
	24
	25	## Core Components
	26
	27	### 1. Bitcoin Layer (wdk-wallet-btc)
	28
	29	Handles on-chain Bitcoin operations.
	30
	31	#### Multisig Creation
	32
	33	```javascript
	34	import WdkWalletBtc from '@tetherto/wdk-wallet-btc'
	35
	36	class ChannelFunding {
	37	async createMultisig(myKey, peerKey, amount, channelCommitment) {
	38	const wallet = new WdkWalletBtc()
	39
	40	// Create 2-of-2 multisig address
	41	const multisig = await wallet.createMultisig({
	42	keys: [myKey, peerKey],
	43	requiredSignatures: 2,
	44	type: 'p2wsh' // SegWit for lower fees
	45	})
	46
	47	// Create funding transaction
	48	const fundingTx = await wallet.createTransaction({
	49	outputs: [{
	50	address: multisig.address,
	51	amount: amount, // In satoshis
	52	data: channelCommitment // OP_RETURN with channel ID
	53	}]
	54	})
	55
	56	// Sign and broadcast
	57	const signedTx = await wallet.sign(fundingTx, myKey)
	58	const txid = await wallet.broadcast(signedTx)
	59
	60	return {
	61	multisig,
	62	fundingTxid: txid,
	63	fundingOutput: 0
	64	}
	65	}
	66	}
	67	```
	68
	69	#### Bitcoin Script Design
	70
	71	```javascript
	72	// Using Taproot for flexible scripts
	73	const channelScript = {
	74	// Taproot script tree
	75	version: 1, // Taproot
	76
	77	// Default path: Cooperative close (keypath spend)
	78	internalKey: musig2([aliceKey, bobKey]),
	79
	80	// Script paths (for disputes)
	81	scripts: [
	82	// Path 1: Unilateral close with timelock
	83	{
	84	script: `
	85	<channelStateRoot> OP_EQUALVERIFY
	86	<24h_timelock> OP_CHECKLOCKTIMEVERIFY OP_DROP
	87	<party_pubkey> OP_CHECKSIG
	88	`,
	89	weight: 100
	90	},
	91
	92	// Path 2: Penalty path (if fraud detected)
	93	{
	94	script: `
	95	<fraud_proof> OP_VERIFY
	96	<counterparty_pubkey> OP_CHECKSIG
	97	`,
	98	weight: 200
	99	}
	100	]
	101	}
	102	```
	103
	104	#### Commitment Transaction Structure
	105
	106	```javascript
	107	class CommitmentTx {
	108	async create(channelState) {
	109	return {
	110	version: 2,
	111	inputs: [{
	112	txid: fundingTxid,
	113	vout: 0,
	114	sequence: 0xFFFFFFFE, // Enable timelock
	115	witness: [] // Empty for now (filled when broadcasting)
	116	}],
	117	outputs: [
	118	// Alice's output
	119	{
	120	address: aliceAddress,
	121	amount: channelState.balances.alice,
	122	script: this.createTimelockScript(aliceKey, 24 * 60 * 60)
	123	},
	124	// Bob's output
	125	{
	126	address: bobAddress,
	127	amount: channelState.balances.bob,
	128	script: this.createTimelockScript(bobKey, 24 * 60 * 60)
	129	}
	130	],
	131	locktime: 0
	132	}
	133	}
	134
	135	createTimelockScript(pubkey, delay) {
	136	return `
	137	OP_IF
	138	<${delay}> OP_CHECKSEQUENCEVERIFY OP_DROP
	139	<${pubkey}> OP_CHECKSIG
	140	OP_ELSE
	141	<fraud_proof_hash> OP_EQUALVERIFY
	142	<counterparty_pubkey> OP_CHECKSIG
	143	OP_ENDIF
	144	`
	145	}
	146	}
	147	```
	148
	149	### 2. State Channel Layer (Hypercore + Autobase)
	150
	151	Manages off-chain state using append-only logs.
	152
	153	#### Channel State Structure
	154
	155	```javascript
	156	import Hypercore from 'hypercore'
	157	import Autobase from 'autobase'
	158
	159	class PaymentChannel {
	160	constructor(myFeed, peerFeed) {
	161	// Multi-writer Hypercore using Autobase
	162	this.channel = new Autobase([myFeed, peerFeed], {
	163	// Apply function: How to merge both feeds
	164	apply: async (batch, view, base) => {
	165	for (const node of batch) {
	166	const entry = node.value
	167
	168	switch (entry.type) {
	169	case 'payment':
	170	await this.applyPayment(view, entry)
	171	break
	172	case 'open':
	173	await this.applyOpen(view, entry)
	174	break
	175	case 'close':
	176	await this.applyClose(view, entry)
	177	break
	178	}
	179	}
	180	},
	181
	182	// View: Current channel state
	183	open: async (store) => {
	184	return store.get('channel-state', {
	185	balances: { alice: 0, bob: 0 },
	186	nonce: 0,
	187	status: 'pending'
	188	})
	189	}
	190	})
	191	}
	192
	193	async applyPayment(view, entry) {
	194	const state = await view.get()
	195
	196	// Verify signature
	197	if (!this.verifySignature(entry)) {
	198	throw new Error('Invalid signature')
	199	}
	200
	201	// Verify nonce (prevent replay)
	202	if (entry.nonce !== state.nonce + 1) {
	203	throw new Error('Invalid nonce')
	204	}
	205
	206	// Update balances
	207	state.balances[entry.from] -= entry.amount
	208	state.balances[entry.to] += entry.amount
	209	state.nonce = entry.nonce
	210
	211	// Store updated state
	212	await view.set(state)
	213	}
	214	}
	215	```
	216
	217	#### State Entry Format
	218
	219	```javascript
	220	// Opening entry
	221	{
	222	type: 'open',
	223	channelId: hash([myFeed.key, peerFeed.key].sort()),
	224	fundingTxid: '...',
	225	fundingOutput: 0,
	226	capacity: 1000000, // Total sats in channel
	227	balances: {
	228	alice: 500000,
	229	bob: 500000
	230	},
	231	signatures: [aliceSig, bobSig],
	232	timestamp: Date.now()
	233	}
	234
	235	// Payment entry
	236	{
	237	type: 'payment',
	238	from: 'alice',
	239	to: 'bob',
	240	amount: 50000, // sats
	241	nonce: 1,
	242	balances: {
	243	alice: 450000,
	244	bob: 550000
	245	},
	246	signatures: [aliceSig, bobSig],
	247	timestamp: Date.now()
	248	}
	249
	250	// Closing entry
	251	{
	252	type: 'close',
	253	method: 'cooperative' \| 'unilateral',
	254	finalBalances: {
	255	alice: 450000,
	256	bob: 550000
	257	},
	258	closingTxid: '...',
	259	signatures: [aliceSig, bobSig],
	260	timestamp: Date.now()
	261	}
	262	```
	263
	264	#### Merkle Proof Generation
	265
	266	```javascript
	267	class StateProof {
	268	// Generate proof that state exists in Hypercore
	269	async generateProof(channelState) {
	270	const index = this.channel.length - 1
	271	const entry = await this.channel.get(index)
	272
	273	// Get merkle proof
	274	const proof = await this.channel.proof({
	275	block: { index, nodes: 1 }
	276	})
	277
	278	return {
	279	stateRoot: this.channel.tree.hash(),
	280	index: index,
	281	entry: entry,
	282	proof: proof.nodes,
	283	signature: proof.signature
	284	}
	285	}
	286
	287	// Verify proof (for fraud detection)
	288	async verifyProof(proof, claimedState) {
	289	const root = merkleRoot([
	290	proof.entry,
	291	...proof.proof
	292	])
	293
	294	// State root should match
	295	if (root !== proof.stateRoot) {
	296	return { valid: false, reason: 'Invalid merkle proof' }
	297	}
	298
	299	// Entry should match claimed state
	300	if (!deepEqual(proof.entry.balances, claimedState.balances)) {
	301	return {
	302	valid: false,
	303	reason: 'State mismatch',
	304	claimed: claimedState,
	305	actual: proof.entry
	306	}
	307	}
	308
	309	return { valid: true }
	310	}
	311	}
	312	```
	313
	314	### 3. Network Layer (Hyperswarm + Secret-stream)
	315
	316	Handles P2P discovery and encrypted communication.
	317
	318	#### Peer Discovery
	319
	320	```javascript
	321	import Hyperswarm from 'hyperswarm'
	322	import crypto from 'hypercore-crypto'
	323
	324	class ChannelNetwork {
	325	constructor() {
	326	this.swarm = new Hyperswarm()
	327	this.connections = new Map()
	328	}
	329
	330	async discoverPeer(channelId) {
	331	// Derive topic from channel ID
	332	const topic = crypto.hash(Buffer.from(channelId))
	333
	334	// Join DHT topic
	335	const discovery = this.swarm.join(topic, {
	336	server: true, // Accept connections
	337	client: true // Make connections
	338	})
	339
	340	await discovery.flushed() // Wait for DHT announcement
	341
	342	return new Promise((resolve) => {
	343	this.swarm.on('connection', (socket, info) => {
	344	// Found peer!
	345	resolve({
	346	socket,
	347	peer: info.publicKey,
	348	isInitiator: info.client
	349	})
	350	})
	351	})
	352	}
	353	}
	354	```
	355
	356	#### Encrypted Communication
	357
	358	```javascript
	359	import SecretStream from '@hyperswarm/secret-stream'
	360
	361	class ChannelCommunication {
	362	async establishSecureChannel(socket, isInitiator) {
	363	// Encrypt connection using Noise protocol
	364	const stream = new SecretStream(isInitiator, socket)
	365
	366	// Exchange Hypercore keys
	367	stream.write({
	368	type: 'handshake',
	369	myFeedKey: this.myFeed.key,
	370	channelId: this.channelId
	371	})
	372
	373	// Wait for peer's handshake
	374	const peerHandshake = await new Promise((resolve) => {
	375	stream.once('data', resolve)
	376	})
	377
	378	// Verify peer has correct channel
	379	if (peerHandshake.channelId !== this.channelId) {
	380	throw new Error('Channel ID mismatch')
	381	}
	382
	383	return stream
	384	}
	385
	386	async sendPayment(stream, amount) {
	387	// Create payment entry
	388	const entry = {
	389	type: 'payment',
	390	from: 'me',
	391	to: 'peer',
	392	amount: amount,
	393	nonce: this.state.nonce + 1,
	394	timestamp: Date.now()
	395	}
	396
	397	// Sign entry
	398	entry.mySignature = crypto.sign(
	399	Buffer.from(JSON.stringify(entry)),
	400	this.myKey
	401	)
	402
	403	// Send to peer
	404	stream.write(entry)
	405
	406	// Wait for peer's signature
	407	const peerSigned = await new Promise((resolve) => {
	408	stream.once('data', resolve)
	409	})
	410
	411	// Append to Hypercore with both signatures
	412	await this.myFeed.append({
	413	...entry,
	414	signatures: [entry.mySignature, peerSigned.signature]
	415	})
	416
	417	// Update local state
	418	this.state = await this.channel.view.get()
	419	}
	420	}
	421	```
	422
	423	### 4. Fraud Detection & Penalty Mechanism
	424
	425	Monitors blockchain for old state broadcasts.
	426
	427	#### Watchtower Service
	428
	429	```javascript
	430	class FraudMonitor {
	431	constructor(channel, bitcoin) {
	432	this.channel = channel
	433	this.bitcoin = bitcoin
	434	this.monitoring = false
	435	}
	436
	437	async start() {
	438	this.monitoring = true
	439
	440	// Subscribe to mempool and new blocks
	441	this.bitcoin.on('transaction', async (tx) => {
	442	await this.checkTransaction(tx)
	443	})
	444
	445	console.log('Fraud monitoring started')
	446	}
	447
	448	async checkTransaction(tx) {
	449	// Is this transaction spending our channel?
	450	const spendsChannel = tx.inputs.some(input =>
	451	input.txid === this.channel.fundingTxid &&
	452	input.vout === this.channel.fundingOutput
	453	)
	454
	455	if (!spendsChannel) return
	456
	457	// Extract claimed state from transaction
	458	const claimedState = this.extractStateFromTx(tx)
	459
	460	// Get latest state from Hypercore
	461	const latestState = await this.channel.view.get()
	462
	463	// Compare
	464	if (claimedState.nonce < latestState.nonce) {
	465	// FRAUD DETECTED!
	466	console.error('FRAUD: Old state broadcast!')
	467	await this.submitPenaltyTx(tx, latestState)
	468	}
	469	}
	470
	471	async submitPenaltyTx(fraudTx, latestState) {
	472	// Generate proof from Hypercore
	473	const proof = await this.channel.generateProof(latestState)
	474
	475	// Create penalty transaction
	476	const penaltyTx = {
	477	version: 2,
	478	inputs: [{
	479	txid: this.channel.fundingTxid,
	480	vout: this.channel.fundingOutput,
	481	witness: [
	482	proof.signature,
	483	proof.entry,
	484	proof.proof, // Merkle proof
	485	this.penaltyScript
	486	]
	487	}],
	488	outputs: [{
	489	// All funds go to me (penalty)
	490	address: this.myAddress,
	491	amount: this.channel.capacity
	492	}]
	493	}
	494
	495	// Broadcast penalty
	496	await this.bitcoin.broadcast(penaltyTx)
	497	console.log('Penalty transaction submitted!')
	498	}
	499	}
	500	```
	501
	502	### 5. Channel Lifecycle Management
	503
	504	Handles opening, updating, and closing channels.
	505
	506	#### Opening Flow
	507
	508	```javascript
	509	class ChannelManager {
	510	async openChannel(peerKey, amount) {
	511	// 1. Create Hypercore feeds
	512	const myFeed = this.corestore.get({ name: `channel-${peerKey}` })
	513	const peerFeed = this.corestore.get(peerKey)
	514
	515	// 2. Create Autobase channel
	516	const channel = new PaymentChannel(myFeed, peerFeed)
	517
	518	// 3. Create Bitcoin multisig
	519	const funding = await this.createMultisig(
	520	this.myKey,
	521	peerKey,
	522	amount,
	523	channel.channelId
	524	)
	525
	526	// 4. Wait for funding confirmation
	527	await this.bitcoin.waitForConfirmation(funding.txid, 6)
	528
	529	// 5. Append opening entry to Hypercore
	530	await myFeed.append({
	531	type: 'open',
	532	channelId: channel.channelId,
	533	fundingTxid: funding.txid,
	534	fundingOutput: funding.output,
	535	capacity: amount,
	536	balances: {
	537	[this.myId]: amount / 2,
	538	[peerId]: amount / 2
	539	},
	540	timestamp: Date.now()
	541	})
	542
	543	// 6. Start fraud monitoring
	544	const monitor = new FraudMonitor(channel, this.bitcoin)
	545	await monitor.start()
	546
	547	// 7. Discover peer on network
	548	await this.network.discoverPeer(channel.channelId)
	549
	550	return channel
	551	}
	552	}
	553	```
	554
	555	#### Cooperative Close
	556
	557	```javascript
	558	async closeChannel(channel) {
	559	// 1. Get final state
	560	const finalState = await channel.view.get()
	561
	562	// 2. Create closing transaction
	563	const closeTx = {
	564	version: 2,
	565	inputs: [{
	566	txid: channel.fundingTxid,
	567	vout: channel.fundingOutput
	568	}],
	569	outputs: [
	570	{
	571	address: this.myAddress,
	572	amount: finalState.balances[this.myId]
	573	},
	574	{
	575	address: this.peerAddress,
	576	amount: finalState.balances[this.peerId]
	577	}
	578	]
	579	}
	580
	581	// 3. Both parties sign
	582	const mySignature = await this.wallet.sign(closeTx, this.myKey)
	583	const peerSignature = await this.requestPeerSignature(closeTx)
	584
	585	closeTx.witness = [mySignature, peerSignature]
	586
	587	// 4. Broadcast
	588	const txid = await this.bitcoin.broadcast(closeTx)
	589
	590	// 5. Append close entry to Hypercore
	591	await this.myFeed.append({
	592	type: 'close',
	593	method: 'cooperative',
	594	finalBalances: finalState.balances,
	595	closingTxid: txid,
	596	timestamp: Date.now()
	597	})
	598
	599	// 6. Stop monitoring
	600	this.monitor.stop()
	601
	602	console.log(`Channel closed: ${txid}`)
	603	}
	604	```
	605
	606	#### Unilateral Close
	607
	608	```javascript
	609	async forceClose(channel) {
	610	// 1. Get latest state
	611	const latestState = await channel.view.get()
	612
	613	// 2. Generate proof
	614	const proof = await channel.generateProof(latestState)
	615
	616	// 3. Create timelock transaction
	617	const closeTx = {
	618	version: 2,
	619	inputs: [{
	620	txid: channel.fundingTxid,
	621	vout: channel.fundingOutput,
	622	sequence: 0xFFFFFFFE, // Enable timelock
	623	witness: [
	624	this.mySignature,
	625	proof.entry,
	626	proof.proof,
	627	this.timelockScript
	628	]
	629	}],
	630	outputs: [
	631	{
	632	address: this.myAddress,
	633	amount: latestState.balances[this.myId],
	634	script: this.createTimelockScript(24 * 60 * 60) // 24h delay
	635	},
	636	{
	637	address: this.peerAddress,
	638	amount: latestState.balances[this.peerId],
	639	script: this.createTimelockScript(24 * 60 * 60)
	640	}
	641	]
	642	}
	643
	644	// 4. Broadcast
	645	const txid = await this.bitcoin.broadcast(closeTx)
	646
	647	console.log(`Force close initiated: ${txid}`)
	648	console.log('Waiting 24 hours for disputes...')
	649
	650	// 5. Wait for timelock
	651	await this.waitForTimelock(txid, 24 * 60 * 60)
	652
	653	// 6. Claim funds
	654	await this.claimFromTimelock(closeTx)
	655	}
	656	```
	657
	658	## Data Flow Diagrams
	659
	660	### Payment Flow
	661
	662	```
	663	Alice Hypercore Bob
	664	\| \| \|
	665	\|-- Create payment ------>\| \|
	666	\| \|<---- Replicate --------\|
	667	\| \| \|
	668	\|<----- Request sig ------\|----------------------->\|
	669	\| \| \|
	670	\|------- Bob sig -------->\|<----- Sign entry ------\|
	671	\| \| \|
	672	\|<---- Append entry ------\| \|
	673	\| \|---- Replicate -------->\|
	674	\| \| \|
	675	\|<-- Confirm payment -----\|---- Confirm ---------->\|
	676	```
	677
	678	### Fraud Detection Flow
	679
	680	```
	681	Attacker Bitcoin Network Victim's Watchtower
	682	\| \| \|
	683	\|--- Broadcast old ------>\| \|
	684	\| state tx \| \|
	685	\| \|--- Mempool tx ---------->\|
	686	\| \| \|
	687	\| \| [Check Hypercore]
	688	\| \| \|
	689	\| \| [Fraud detected!]
	690	\| \| \|
	691	\| \|<-- Penalty tx -----------\|
	692	\| \| \|
	693	\|<-- All funds lost ------\|---- Confirmed ---------->\|
	694	```
	695
	696	## Storage Schema
	697
	698	### Corestore Layout
	699
	700	```
	701	~/.config/pear/app-storage/
	702	└── channels/
	703	├── feeds/
	704	│ ├── alice-bob-1234.hypercore
	705	│ └── bob-alice-1234.hypercore
	706	├── indexes/
	707	│ └── routing.hyperbee
	708	└── metadata/
	709	└── channel-list.json
	710	```
	711
	712	### Channel Metadata
	713
	714	```json
	715	{
	716	"channelId": "abc123...",
	717	"peers": ["alice", "bob"],
	718	"myFeed": "hypercore://...",
	719	"peerFeed": "hypercore://...",
	720	"fundingTxid": "...",
	721	"fundingOutput": 0,
	722	"capacity": 1000000,
	723	"status": "open",
	724	"openedAt": 1234567890,
	725	"closedAt": null
	726	}
	727	```
	728
	729	## Performance Considerations
	730
	731	### Latency
	732
	733	\| Operation \| Time \| Limiting Factor \|
	734	\|-----------\|------\|----------------\|
	735	\| Payment \| ~100ms \| Hypercore append + signature \|
	736	\| Channel open \| ~10min \| Bitcoin confirmation \|
	737	\| Channel close (coop) \| ~10min \| Bitcoin confirmation \|
	738	\| Channel close (force) \| ~24h \| Timelock period \|
	739	\| Peer discovery \| ~1-5s \| DHT lookup \|
	740
	741	### Throughput
	742
	743	```javascript
	744	// Hypercore can handle ~10,000 appends/sec
	745	// Payment channel limited by:
	746	// 1. Signature generation: ~1000/sec
	747	// 2. Network latency: ~100ms RTT
	748	// 3. Practical limit: ~10 payments/sec per channel
	749
	750	// For high throughput:
	751	// - Batch payments (accumulate, sign once)
	752	// - Use multiple channels
	753	```
	754
	755	### Storage
	756
	757	```javascript
	758	// Per channel:
	759	const storagePerEntry = 256 // bytes (payment entry)
	760	const entriesPerDay = 100 // payments
	761	const daysOpen = 180 // 6 months
	762
	763	const totalStorage = storagePerEntry * entriesPerDay * daysOpen
	764	// = 256 * 100 * 180 = 4.6 MB per channel
	765
	766	// For 10 channels: ~50 MB
	767	// Very lightweight!
	768	```
	769
	770	## Security Considerations
	771
	772	### Key Management
	773
	774	```javascript
	775	class KeyManager {
	776	// NEVER store keys in plaintext
	777	async generateChannelKeys() {
	778	const masterKey = await this.deriveMasterKey()
	779
	780	// Derive channel-specific keys
	781	const channelKey = await crypto.derive(
	782	masterKey,
	783	'channel-' + channelId
	784	)
	785
	786	// Store encrypted
	787	await this.storage.set('encrypted-keys', {
	788	data: await this.encrypt(channelKey),
	789	iv: this.iv,
	790	salt: this.salt
	791	})
	792	}
	793	}
	794	```
	795
	796	### Replay Attack Prevention
	797
	798	```javascript
	799	// Use monotonic nonces
	800	class NonceManager {
	801	async verifyNonce(entry) {
	802	const state = await this.channel.view.get()
	803
	804	// Nonce must be exactly state.nonce + 1
	805	if (entry.nonce !== state.nonce + 1) {
	806	throw new Error('Invalid nonce (replay attack?)')
	807	}
	808
	809	return true
	810	}
	811	}
	812	```
	813
	814	### Sybil Attack Resistance
	815
	816	```javascript
	817	// Require proof-of-work for channel announcements
	818	async announceChannel(channelId) {
	819	const nonce = await this.mineProofOfWork({
	820	data: channelId,
	821	difficulty: 20 // bits
	822	})
	823
	824	await this.routingIndex.put(channelId, {
	825	...channelInfo,
	826	pow: nonce
	827	})
	828	}
	829	```
	830
	831	## Testing Strategy
	832
	833	### Unit Tests
	834
	835	```javascript
	836	import test from 'brittle'
	837
	838	test('payment updates balances', async (t) => {
	839	const channel = await createTestChannel()
	840
	841	await channel.sendPayment({
	842	from: 'alice',
	843	to: 'bob',
	844	amount: 100
	845	})
	846
	847	const state = await channel.view.get()
	848	t.is(state.balances.alice, 400)
	849	t.is(state.balances.bob, 600)
	850	})
	851	```
	852
	853	### Integration Tests
	854
	855	```javascript
	856	import { HyperLab } from 'hyper-lab'
	857
	858	test('multi-device payment', async (t) => {
	859	const lab = new HyperLab()
	860
	861	// Start on two machines
	862	const alice = await lab.spawn('alice', './channel-app.js')
	863	const bob = await lab.spawn('bob', './channel-app.js')
	864
	865	// Alice opens channel
	866	await alice.exec('openChannel', { peer: 'bob', amount: 1000 })
	867
	868	// Bob sees channel
	869	const channels = await bob.exec('listChannels')
	870	t.is(channels.length, 1)
	871
	872	// Alice pays Bob
	873	await alice.exec('pay', { amount: 100 })
	874
	875	// Bob sees payment
	876	const balance = await bob.exec('getBalance')
	877	t.is(balance, 600)
	878	})
	879	```
	880
	881	## Deployment
	882
	883	### Pear App Structure
	884
	885	```
	886	channel-app/
	887	├── package.json
	888	├── index.html
	889	├── app.js
	890	├── lib/
	891	│ ├── channel.js
	892	│ ├── wallet.js
	893	│ └── network.js
	894	└── pear/
	895	└── pear.json
	896	```
	897
	898	### Pear Configuration
	899
	900	```json
	901	{
	902	"name": "hypercore-l2",
	903	"main": "app.js",
	904	"type": "desktop",
	905	"stage": {
	906	"ignore": [] // Don't ignore node_modules!
	907	}
	908	}
	909	```
	910
	911	## Monitoring & Observability
	912
	913	```javascript
	914	class ChannelMetrics {
	915	async collectMetrics() {
	916	return {
	917	channels: {
	918	total: this.channels.size,
	919	open: this.countByStatus('open'),
	920	closing: this.countByStatus('closing'),
	921	closed: this.countByStatus('closed')
	922	},
	923	payments: {
	924	total: await this.countTotalPayments(),
	925	volume: await this.calculateVolume(),
	926	avgAmount: await this.calculateAvgAmount()
	927	},
	928	network: {
	929	peers: this.swarm.connections.size,
	930	bandwidth: this.swarm.stats.bandwidth
	931	}
	932	}
	933	}
	934	}
	935	```
	936
	937	---
	938
	939	This architecture provides a complete technical blueprint for implementing a Bitcoin L2 payment channel system using the Holepunchto stack.

CONCEPT.md +487 -0

…	…	@@ -0,0 +1,487 @@
	1	# Concept: Hypercore Payment Channels
	2
	3	## Core Idea
	4
	5	Combine Bitcoin's script capabilities with Hypercore's append-only logs and Hyperswarm's P2P networking to create a simpler, more private Lightning Network alternative.
	6
	7	## Architecture Components
	8
	9	### 1. On-Chain Anchoring (Bitcoin Layer)
	10
	11	```javascript
	12	// Multi-sig 2-of-2 contract with timelock
	13	// Parties lock BTC in contract
	14	// Contract includes:
	15	// - Cooperative close path (both signatures)
	16	// - Unilateral close path (one signature + timelock)
	17	// - Hypercore feed public key hash commitment
	18	```
	19
	20	Bitcoin Script:
	21	```
	22	OP_IF
	23	// Cooperative close - both parties agree
	24	2 <alice_pubkey> <bob_pubkey> 2 OP_CHECKMULTISIG
	25	OP_ELSE
	26	// Unilateral close - one party exits with fraud protection
	27	<hypercore_merkle_root> OP_EQUALVERIFY
	28	<timelock> OP_CHECKLOCKTIMEVERIFY OP_DROP
	29	<party_pubkey> OP_CHECKSIG
	30	OP_ENDIF
	31	```
	32
	33	### 2. Off-Chain State (Hypercore)
	34
	35	```javascript
	36	// Each channel = shared Hypercore feed (via Autobase)
	37	// Append-only transaction log ensures tamper-proof history
	38	const channel = new Autobase([aliceFeed, bobFeed], {
	39	apply: (batch) => updateChannelState(batch)
	40	})
	41
	42	// Each entry represents a state update:
	43	{
	44	nonce: 42, // Prevents replay attacks
	45	balances: {
	46	alice: 600000, // sats
	47	bob: 400000
	48	},
	49	timestamp: Date.now(),
	50	signatures: [aliceSig, bobSig], // Both parties sign
	51	merkleRoot: '...' // Can commit to Bitcoin if needed
	52	}
	53	```
	54
	55	Key properties:
	56	- Append-only = Cannot rewrite history
	57	- Both parties replicate = Always synced
	58	- Can prove transaction ordering in disputes
	59	- Serves as watchtower (automatic fraud detection)
	60
	61	### 3. P2P Network (Hyperswarm + Secret-stream)
	62
	63	```javascript
	64	// Discover channel partners without central server
	65	const swarm = new Hyperswarm()
	66	swarm.join(channelTopic)
	67
	68	swarm.on('connection', (socket) => {
	69	// Encrypt everything with secret-stream
	70	const stream = new SecretStream(socket)
	71
	72	// Send transactions instantly
	73	stream.write({
	74	type: 'payment',
	75	amount: 500,
	76	newState: {
	77	alice: 550000,
	78	bob: 450000
	79	}
	80	})
	81	})
	82	```
	83
	84	Advantages over Lightning:
	85	- No gossip protocol (Hyperswarm DHT handles discovery)
	86	- NAT hole-punching built-in
	87	- Encrypted by default
	88	- No central coordinator
	89
	90	## How It Works
	91
	92	### Opening a Channel
	93
	94	1. Setup: Alice & Bob create shared Autobase (multi-writer Hypercore)
	95	```javascript
	96	const aliceFeed = corestore.get({ name: 'alice-channel' })
	97	const bobFeed = corestore.get({ name: 'bob-channel' })
	98	const channel = new Autobase([aliceFeed, bobFeed])
	99	```
	100
	101	2. Fund: Deposit BTC to 2-of-2 multisig with Hypercore feed hash
	102	```javascript
	103	const fundingTx = await wallet.createMultisig({
	104	keys: [aliceKey, bobKey],
	105	amount: 1000000, // 0.01 BTC in sats
	106	data: hash(channel.key) // Commit to channel
	107	})
	108	```
	109
	110	3. Connect: Discover each other via Hyperswarm DHT
	111	```javascript
	112	const topic = hash(channel.key)
	113	swarm.join(topic)
	114	```
	115
	116	### Transacting Off-Chain
	117
	118	1. Propose: Alice writes payment to her Hypercore feed
	119	```javascript
	120	await aliceFeed.append({
	121	type: 'payment',
	122	to: 'bob',
	123	amount: 50000,
	124	nonce: currentNonce + 1
	125	})
	126	```
	127
	128	2. Sign: Both parties sign the new state
	129	```javascript
	130	const newState = {
	131	alice: 450000,
	132	bob: 550000,
	133	nonce: currentNonce + 1
	134	}
	135	const signature = sign(newState, [aliceKey, bobKey])
	136	```
	137
	138	3. Instant: No blockchain confirmation needed
	139	- Payment completes in ~1 second
	140	- Both Hypercore feeds replicate automatically
	141	- Encrypted over secret-stream
	142
	143	4. Private: Only parties see the transaction
	144	- Not on Bitcoin blockchain
	145	- Not visible to routing nodes (direct channel)
	146	- Encrypted P2P connection
	147
	148	### Closing Channel
	149
	150	#### Cooperative Close (Happy Path)
	151
	152	```javascript
	153	// Both parties online and agreeing
	154	// Take latest Autobase state
	155	const finalState = await channel.view.get()
	156
	157	// Both sign Bitcoin tx distributing funds
	158	const closeTx = await wallet.createTransaction({
	159	inputs: [fundingTxOut],
	160	outputs: [
	161	{ address: aliceAddress, amount: finalState.alice },
	162	{ address: bobAddress, amount: finalState.bob }
	163	]
	164	})
	165
	166	// Broadcast to Bitcoin
	167	await wallet.broadcast(closeTx)
	168	// Done in ~10 minutes (1 confirmation)
	169	```
	170
	171	#### Non-Cooperative Close (Unilateral Exit)
	172
	173	```javascript
	174	// Alice wants out, Bob is offline
	175	// Submit latest signed state to blockchain
	176	const exitTx = await wallet.createTimelockExit({
	177	state: latestState,
	178	signatures: [aliceSig, bobSig],
	179	timelock: 24 * 60 * 60 // 24 hours
	180	})
	181
	182	await wallet.broadcast(exitTx)
	183
	184	// Bitcoin contract enforces:
	185	// 1. Alice must wait 24 hours
	186	// 2. Bob can dispute if Alice submitted old state
	187	// 3. If no dispute, Alice gets her balance after timelock
	188	```
	189
	190	Fraud Protection:
	191	```javascript
	192	// Bob's computer monitors blockchain
	193	if (detectedOldState) {
	194	// Prove Alice lied using Hypercore log
	195	const fraudProof = {
	196	oldState: aliceSubmitted,
	197	newState: actualLatest,
	198	hypercoreProof: merkleProof // Proves newer state exists
	199	}
	200
	201	// Submit penalty transaction
	202	const penaltyTx = await wallet.createPenalty({
	203	proof: fraudProof,
	204	penalty: 'all' // Bob gets ALL the Bitcoin
	205	})
	206
	207	await wallet.broadcast(penaltyTx)
	208	// Alice loses everything for cheating
	209	}
	210	```
	211
	212	## Key Innovations
	213
	214	### 1. Hypercore as State Channel Log
	215
	216	Advantages:
	217	- Append-only = Tamper-proof history
	218	- Replication = Both parties always synced
	219	- Can prove ordering in disputes
	220	- Merkle proofs = Efficient fraud detection
	221
	222	vs Lightning:
	223	- Lightning: Each party stores commitment transactions separately
	224	- Hypercore: Shared log, always synced, can't diverge
	225
	226	### 2. Hyperswarm for Discovery
	227
	228	Advantages:
	229	- No central coordinator needed
	230	- DHT-based peer finding
	231	- NAT hole-punching built-in
	232	- Can run behind firewalls/NAT
	233
	234	vs Lightning:
	235	- Lightning: Gossip protocol (announces to whole network)
	236	- Hyperswarm: Direct discovery (more private)
	237
	238	### 3. Secret-stream for Privacy
	239
	240	Advantages:
	241	- Encrypted P2P connections
	242	- Perfect forward secrecy (Noise protocol)
	243	- No onion routing needed (direct channels)
	244
	245	vs Lightning:
	246	- Lightning: Onion routing for multi-hop payments (complex)
	247	- Secret-stream: Direct encryption (simpler for 1-hop)
	248
	249	### 4. Hyperbee for Routing (Optional)
	250
	251	For multi-hop payments:
	252
	253	```javascript
	254	// Each node advertises their channels in Hyperbee
	255	const routingIndex = new Hyperbee(corestore.get())
	256
	257	await routingIndex.put(`/channels/${nodeId}`, {
	258	peers: [peer1, peer2],
	259	capacity: [10000, 5000],
	260	fees: [0.1, 0.1] // %
	261	})
	262
	263	// Find route: Alice → Bob → Carol → Dave
	264	const route = await findRoute({
	265	from: 'alice',
	266	to: 'dave',
	267	amount: 1000,
	268	index: routingIndex
	269	})
	270	```
	271
	272	vs Lightning:
	273	- Lightning: Gossip-based routing (everyone knows everything)
	274	- Hyperbee: Query-based routing (privacy-preserving)
	275
	276	## Security Model
	277
	278	### Preventing Fraud
	279
	280	Problem: What stops Alice from broadcasting an old state where she had more money?
	281
	282	Solution: Game theory + timelock + Hypercore proof
	283
	284	1. Timelock: Alice must wait 24 hours
	285	- Gives Bob time to respond
	286	- Can't steal immediately
	287
	288	2. Hypercore Proof: Bob can prove newer state exists
	289	- Hypercore is append-only
	290	- Can create merkle proof of latest state
	291	- Cryptographically proves Alice lied
	292
	293	3. Penalty: Alice loses everything if caught
	294	- Bob gets ALL the Bitcoin (100% penalty)
	295	- Makes cheating economically irrational
	296
	297	Game Theory:
	298	```
	299	Alice's decision:
	300	- Honest: Get $600 (guaranteed)
	301	- Cheat: 5% chance of $1000, 95% chance of $0
	302	- Expected value: $50 vs $600
	303	- Rational choice: Be honest
	304	```
	305
	306	### Watchtower Problem
	307
	308	Lightning's approach: Separate watchtower services monitor blockchain
	309
	310	Hypercore's approach: Replication = automatic watchtower
	311
	312	```javascript
	313	// Bob's computer replicates Alice's feed
	314	// If Alice goes offline, Bob still monitors
	315	// If Alice broadcasts old state, Bob's node automatically:
	316	// 1. Detects the broadcast (watching Bitcoin mempool)
	317	// 2. Compares to Hypercore log (has latest state)
	318	// 3. Submits penalty transaction (if fraud detected)
	319
	320	// This is automatic - no separate service needed
	321	```
	322
	323	Advantage: No need to trust third-party watchtowers
	324
	325	## Advantages Over Lightning
	326
	327	\| Feature \| Lightning \| Hypercore L2 \|
	328	\|---------\|-----------\|--------------\|
	329	\| State storage \| Separate commitment txs \| Shared Hypercore log \|
	330	\| Synchronization \| Manual coordination \| Automatic replication \|
	331	\| Watchtowers \| Separate service needed \| Built-in via replication \|
	332	\| Routing discovery \| Gossip protocol \| Hyperbee query \|
	333	\| Privacy \| Onion routing (multi-hop) \| Secret-stream (direct) \|
	334	\| NAT traversal \| Manual port forwarding \| Built-in (Hyperswarm) \|
	335	\| Deployment \| Complex node setup \| Pear app (one-click) \|
	336	\| Infrastructure \| Lightning Network needed \| Pure P2P (self-hosted) \|
	337
	338	## Challenges
	339
	340	### 1. Bitcoin Script Complexity (HARD)
	341
	342	Problem: Bitcoin's scripting is limited
	343
	344	Need to implement:
	345	- Commitment to Hypercore state
	346	- Timelock for disputes
	347	- Penalty mechanism for fraud
	348
	349	Possible solution: Use Taproot for more flexible scripts, or wait for OP_CTV (covenant opcodes)
	350
	351	### 2. Security Model Design (HARD)
	352
	353	The problem Lightning solves: Revocable commitment transactions
	354	- Lightning: Give peer a "revocation key" for old states
	355	- Hypercore: Can't delete old states (append-only!)
	356
	357	Need different approach:
	358	- Option A: Optimistic rollup style (dispute period)
	359	- Option B: Mutual assured destruction
	360	- Requires careful game theory design
	361
	362	### 3. Liquidity Requirements (MEDIUM)
	363
	364	Same as Lightning:
	365	- Need to lock up capital in channels
	366	- Channels become unbalanced after trading
	367	- Need rebalancing mechanisms
	368
	369	### 4. Mobile/Offline Support (MEDIUM)
	370
	371	Challenge: Must monitor blockchain for fraud
	372	- If offline > 24 hours, could miss fraud attempt
	373	- Need mobile-friendly monitoring
	374
	375	Solution: Hypercore replication helps
	376	- Peer's computer monitors for you
	377	- Better than Lightning (separate watchtower)
	378
	379	## Development Roadmap
	380
	381	### Phase 1: Single Channel (3-6 months)
	382	- Two parties only
	383	- Fixed channel size (0.01 BTC)
	384	- Cooperative close only
	385	- No routing
	386
	387	Tools needed:
	388	- wdk-wallet-btc (Bitcoin signing)
	389	- Hypercore + Autobase (state log)
	390	- Hyperswarm (P2P discovery)
	391	- Secret-stream (encryption)
	392
	393	### Phase 2: Security (3-6 months)
	394	- Unilateral close
	395	- Fraud proofs
	396	- Timelock disputes
	397	- Penalty mechanism
	398
	399	Tools needed:
	400	- Bitcoin script design (Taproot)
	401	- Merkle proof generation
	402	- Blockchain monitoring
	403
	404	### Phase 3: Network (6-12 months)
	405	- Multi-hop payments
	406	- Hyperbee routing index
	407	- Rebalancing logic
	408	- Liquidity marketplace
	409
	410	Tools needed:
	411	- HTLCs (Hash Time-Locked Contracts)
	412	- Route finding algorithms
	413	- Fee market design
	414
	415	## Proof of Concept Components
	416
	417	All tools already available in knowledge base:
	418
	419	- ✅ wdk-wallet-btc - Bitcoin signing, UTXO management, multisig
	420	- ✅ hypercore - Append-only log, replication
	421	- ✅ autobase - Multi-writer coordination
	422	- ✅ hyperswarm - Peer discovery, NAT traversal
	423	- ✅ secret-stream - Encrypted transport
	424	- ✅ hyperbee - Routing index (B-tree)
	425	- ✅ pear - Deployment and runtime
	426
	427	## Minimal Implementation
	428
	429	```javascript
	430	// 1. Open channel
	431	const wallet = new WdkWalletBtc()
	432	const channel = new Autobase([myFeed, peerFeed])
	433	const swarm = new Hyperswarm()
	434
	435	// 2. Fund channel (on-chain Bitcoin transaction)
	436	const fundingTx = await wallet.createMultisig(myKey, peerKey, 1000000)
	437	await wallet.broadcast(fundingTx)
	438
	439	// 3. Discover peer
	440	const topic = crypto.hash([myFeed.key, peerFeed.key].sort())
	441	swarm.join(topic)
	442
	443	// 4. Make payments (off-chain, instant)
	444	swarm.on('connection', async (socket) => {
	445	const stream = new SecretStream(socket)
	446
	447	stream.on('data', async (payment) => {
	448	// Update Autobase with new payment
	449	await channel.append({
	450	from: payment.from,
	451	to: payment.to,
	452	amount: payment.amount,
	453	nonce: state.nonce + 1,
	454	timestamp: Date.now()
	455	})
	456
	457	// Update local state
	458	state = await channel.view.get()
	459	})
	460
	461	// Send payment
	462	stream.write({
	463	type: 'payment',
	464	from: 'me',
	465	to: 'peer',
	466	amount: 50000
	467	})
	468	})
	469
	470	// 5. Close channel (on-chain Bitcoin transaction)
	471	const latestState = await channel.view.get()
	472	const closeTx = await wallet.createFromMultisig(
	473	latestState.balances,
	474	[mySig, peerSig]
	475	)
	476	await wallet.broadcast(closeTx)
	477	```
	478
	479	## Bottom Line
	480
	481	Use Hypercore as Lightning's commitment transaction log, Hyperswarm for peer discovery, secret-stream for encrypted instant payments, and settle to Bitcoin when done.
	482
	483	Result: Self-custodial, private, instant Bitcoin payments, built entirely on Pear infrastructure.
	484
	485	Feasibility: Technically possible, main blockers are Bitcoin script design and security model (both solvable).
	486
	487	Timeline: 6-12 months for working MVP with skilled developers.

HOW_IT_WORKS.md +491 -0

…	…	@@ -0,0 +1,491 @@
	1	# How Payment Channels Work (Plain English)
	2
	3	## The Basic Idea
	4
	5	Think of a payment channel as a shared Bitcoin piggy bank where:
	6	- 🏦 You both put money in (one Bitcoin transaction)
	7	- 🤝 You trade instantly using a private ledger (Hypercore)
	8	- 💸 You split the money when done (one Bitcoin transaction)
	9
	10	## Step-by-Step Example
	11
	12	### Opening the Channel (Putting Money In)
	13
	14	```
	15	Alice has 1 BTC
	16	Bob has 1 BTC
	17
	18	They create a shared Bitcoin address that requires BOTH signatures to spend.
	19
	20	Alice sends 0.01 BTC → Shared address
	21	Bob sends 0.01 BTC → Shared address
	22
	23	Now the box contains: 0.02 BTC
	24	- Alice owns: 0.01 BTC ($1,000)
	25	- Bob owns: 0.01 BTC ($1,000)
	26
	27	This costs $10-20 in Bitcoin fees (one-time)
	28	Takes about 10 minutes (1 Bitcoin confirmation)
	29	```
	30
	31	What just happened?
	32	- Created a "locked box" on the Bitcoin blockchain
	33	- Both people need to agree to unlock it
	34	- Private ledger (Hypercore) tracks who owns what inside
	35
	36	### Making Payments (Trading Privately)
	37
	38	```
	39	Alice wants to pay Bob $100 (0.001 BTC)
	40
	41	Traditional Bitcoin:
	42	❌ Wait 10+ minutes for confirmation
	43	❌ Pay $5-10 in fees
	44	❌ Transaction visible to everyone on blockchain
	45
	46	With Hypercore L2:
	47	✅ Update the private ledger:
	48	- Alice: 0.009 BTC ($900)
	49	- Bob: 0.011 BTC ($1,100)
	50	✅ Takes 1 second
	51	✅ No fees
	52	✅ Nobody can see it except Alice and Bob
	53
	54	They can do this 1000 times instantly!
	55	```
	56
	57	What just happened?
	58	- Updated a private database (Hypercore) that both parties share
	59	- No Bitcoin transaction (nothing posted to blockchain)
	60	- Both parties sign the new balance (prevents cheating)
	61	- Encrypted connection (nobody else can see)
	62
	63	### Closing the Channel (Getting Money Out)
	64
	65	```
	66	After lots of trading, the final balance is:
	67	- Alice: 0.006 BTC ($600)
	68	- Bob: 0.014 BTC ($1,400)
	69
	70	They both sign a Bitcoin transaction:
	71	"Pay 0.006 BTC to Alice's address"
	72	"Pay 0.014 BTC to Bob's address"
	73
	74	Broadcast to Bitcoin blockchain.
	75
	76	Costs: $10-20 in Bitcoin fees (one-time)
	77	Takes: 10 minutes (1 Bitcoin confirmation)
	78	```
	79
	80	What just happened?
	81	- Unlocked the shared box
	82	- Split the Bitcoin according to the final balance
	83	- Alice and Bob get their money in their own wallets
	84
	85	## What Makes It "Private Trading"?
	86
	87	### Yes, it's like a pool
	88
	89	🏊 Shared pool of Bitcoin: Both people put money in a pot
	90
	91	📝 Private ledger: Only you and your friend know the balances
	92	- The ledger is a Hypercore (append-only log)
	93	- Both parties replicate it (always synced)
	94	- Encrypted, tamper-proof
	95
	96	🔄 Trade back and forth: Instantly update who owns what
	97	- Alice pays Bob: Update ledger
	98	- Bob pays Alice: Update ledger
	99	- No waiting, no fees
	100
	101	💰 Settle later: When done, take out your final amount
	102	- Close the channel
	103	- One Bitcoin transaction
	104	- Back to normal Bitcoin
	105
	106	### The Key Trick
	107
	108	The Bitcoin blockchain only sees:
	109	1. "Alice and Bob locked 0.02 BTC together" (opening)
	110	2. [months of silence... could be 1000 transactions inside]
	111	3. "Alice got 0.006 BTC, Bob got 0.014 BTC" (closing)
	112
	113	The blockchain does NOT see:
	114	- How many times they traded (could be 1, could be 10,000)
	115	- What the amounts were (could be $1, could be $100)
	116	- What the trades were for (rent, groceries, coffee, etc.)
	117
	118	Total privacy!
	119
	120	## Real-World Analogy
	121
	122	Think of it like a bar tab:
	123
	124	Normal Bitcoin = Pay cash for every drink
	125	- Every transaction costs fees
	126	- Everyone sees every payment
	127	- Slow (wait for bartender to get change)
	128	- Expensive (tips, fees)
	129
	130	Hypercore L2 = Open a tab with the bartender
	131	- Deposit $100 at start
	132	- Order drinks all night instantly
	133	- Bartender keeps private ledger
	134	- Pay final bill at end
	135	- Only 2 transactions hit your bank (open tab, close tab)
	136
	137	Same concept, just with Bitcoin!
	138
	139	## The Benefits
	140
	141	### 1. Speed
	142
	143	- Normal Bitcoin: 10+ minutes per transaction
	144	- Hypercore L2: 1 second
	145
	146	Example: Paying for coffee
	147	- Bitcoin: Order coffee → wait 10 minutes → coffee is cold
	148	- Channel: Order coffee → paid instantly → coffee is hot!
	149
	150	### 2. Cost
	151
	152	```
	153	Scenario: 100 payments over 6 months
	154
	155	Normal way (on-chain):
	156	100 transactions × $5 fee = $500 in fees
	157	😱 More than your rent!
	158
	159	Hypercore L2 (channel):
	160	Opening fee: $10
	161	100 instant payments: $0
	162	Closing fee: $10
	163	Total: $20 in fees
	164
	165	Savings: $480 (96% cheaper!)
	166	```
	167
	168	### 3. Privacy
	169
	170	Normal Bitcoin: Everyone sees your transactions
	171	- Your landlord knows when you paid rent
	172	- Your ex knows you went to therapy
	173	- Your boss knows you donated to political campaign
	174	- Anyone can look up your address on blockchain explorer
	175
	176	Hypercore L2: Only you and your friend see them
	177	- Nobody knows you paid your friend $500
	178	- Nobody knows it was for rent vs gambling
	179	- Nobody even knows you have a channel (unless you tell them)
	180
	181	### 4. Self-Custodial
	182
	183	- Your keys, your Bitcoin (always)
	184	- No exchange, no middleman
	185	- No one can freeze your account
	186	- No one can reverse your payments
	187
	188	vs Banks:
	189	- ❌ Bank can freeze account
	190	- ❌ Bank can reverse transactions
	191	- ❌ Bank sees everything
	192	- ❌ Bank controls your money
	193
	194	vs Exchanges (Coinbase, Kraken):
	195	- ❌ Exchange holds your Bitcoin
	196	- ❌ Exchange can freeze withdrawals
	197	- ❌ "Not your keys, not your coins"
	198
	199	With payment channels: You ALWAYS control your Bitcoin
	200
	201	### 5. No Intermediaries
	202
	203	Lightning Network: Need routing nodes
	204	- Strangers handle your payment
	205	- They charge fees
	206	- They see amount (though not identities)
	207
	208	Hypercore L2: Direct connection to your friend
	209	- No routing needed (for direct channels)
	210	- No strangers involved
	211	- Totally private
	212
	213	## How Does It Prevent Cheating?
	214
	215	### The Cheating Scenario
	216
	217	```
	218	Channel history:
	219	Day 1: Alice $1,000 \| Bob $1,000 (start)
	220	Day 5: Alice $600 \| Bob $1,400 (after trading)
	221
	222	Current balance: Alice has $600
	223
	224	What if Alice tries to close with the OLD balance from Day 1?
	225	She'd claim she has $1,000 instead of $600 (stealing $400!)
	226	```
	227
	228	### The Protection Mechanism
	229
	230	The Bitcoin smart contract says:
	231
	232	1. ⏰ Timelock: "If Alice closes alone, wait 24 hours"
	233	- Gives Bob time to respond
	234	- Can't steal immediately
	235
	236	2. 🚨 Fraud Proof: "Bob can prove if Alice is lying"
	237	- Hypercore log shows the real balance (Day 5 state)
	238	- Bob shows: "Look, here's a NEWER state signed by both of us"
	239	- Cryptographic proof that Alice submitted old state
	240
	241	3. 💰 Penalty: "If Alice cheated, Bob gets ALL the Bitcoin"
	242	- Alice loses everything ($1,000)
	243	- Bob gets everything ($2,000)
	244	- Cheating is extremely stupid
	245
	246	### Why This Works (Game Theory)
	247
	248	Alice's decision tree:
	249
	250	❌ Try to cheat:
	251	- Need Bob to be offline for 24+ hours (unlikely)
	252	- If caught: Lose $1,000 (everything)
	253	- If succeed: Gain $400
	254	- Probability Bob catches me: 95%
	255	- Expected value: 5% × $400 - 95% × $1,000 = -$930
	256	- Terrible decision!
	257
	258	✅ Be honest:
	259	- Get $600 guaranteed
	260	- No risk
	261	- Good decision!
	262
	263	Result: Rational people never cheat because math says it's stupid.
	264
	265	## Can Someone Take Money Out Early?
	266
	267	Yes - this is actually required!
	268
	269	### The Problem
	270
	271	What if your friend disappears?
	272
	273	```
	274	You have a channel with $600 of your money
	275	Your friend gets hit by a bus / loses phone / hates you
	276	You need your money back
	277
	278	❌ If you need BOTH signatures... you're stuck forever!
	279	```
	280
	281	### The Solution
	282
	283	Either person can force-close the channel:
	284
	285	```
	286	1. You broadcast: "Close channel, I have $600"
	287	2. Bitcoin contract says: "Wait 24 hours for disputes"
	288	3. Your friend has 24 hours to respond
	289	4. If no response: You get your $600 ✅
	290	5. If your friend responds: They can prove if you lied
	291	```
	292
	293	Two ways to close:
	294
	295	Cooperative close (both agree):
	296	- Takes 10 minutes
	297	- Costs $10 in fees
	298	- Best outcome
	299
	300	Unilateral close (one person forces it):
	301	- Takes 24 hours (wait for timelock)
	302	- Costs $20-30 in fees (more complex transaction)
	303	- Still gets you your money
	304
	305	Protection: If you try to cheat during unilateral close:
	306	- Your friend has 24 hours to catch you
	307	- They submit proof you lied
	308	- You lose everything
	309	- Don't cheat!
	310
	311	## What Are the Risks?
	312
	313	### 1. Must Monitor Blockchain (Medium Risk)
	314
	315	The risk: Friend broadcasts old state → You have 24 hours to respond
	316
	317	If you miss it: You might lose money
	318
	319	Solutions:
	320	- ✅ Keep computer online (monitors automatically)
	321	- ✅ Use Hypercore replication (peer monitors for you)
	322	- ✅ Mobile app checks periodically
	323	- ✅ Run on cheap VPS ($5/month)
	324
	325	Hypercore advantage: Your friend's computer monitors for you automatically! (Because Hypercore replicates the log, their computer knows what the latest state is and can detect fraud.)
	326
	327	### 2. Timelock Delay (Minor Inconvenience)
	328
	329	The delay: If partner disappears, must wait 24 hours
	330
	331	```
	332	Cooperative close: 10 minutes ✅
	333	Unilateral close: 24 hours ⏰
	334
	335	Not instant, but you DO get your money
	336	```
	337
	338	### 3. Software Bug Risk (Low Risk)
	339
	340	Possible bugs:
	341	- Bug in fraud detection → Might miss old state
	342	- Bug in penalty transaction → Might fail to punish cheater
	343
	344	Mitigation: Thorough testing, audited code, battle-tested before large amounts
	345
	346	### 4. Loss of Funds if Offline Too Long (Low Risk)
	347
	348	Scenario: You go offline for 48+ hours, friend broadcasts old state
	349
	350	Reality:
	351	- Unlikely friend attacks exactly when you're offline
	352	- Hypercore replication monitors for you
	353	- Would need BOTH you AND all your replicas offline
	354
	355	Mitigation: Keep one device online, or use cloud backup
	356
	357	## Complete Example: Roommates
	358
	359	Alice and Bob share an apartment:
	360
	361	```
	362	Month 1: Open channel
	363	- Alice deposits $1,000 (0.01 BTC)
	364	- Bob deposits $1,000 (0.01 BTC)
	365	- Cost: $20 in fees
	366	- Total in channel: $2,000
	367
	368	Months 2-7: Trade privately (6 months of transactions)
	369	- Bob pays Alice $500 (his half of rent)
	370	- Alice pays Bob $200 (groceries she bought)
	371	- Bob pays Alice $150 (utilities)
	372	- Alice pays Bob $350 (paid him back for dinner)
	373	- Bob pays Alice $75 (his share of cleaning service)
	374	- ... 100+ transactions total
	375
	376	All transactions:
	377	✅ Instant (1 second)
	378	✅ Free ($0 fees)
	379	✅ Private (nobody sees)
	380
	381	Month 8: Close channel
	382	- Final balance: Alice $1,200 \| Bob $800
	383	- Cost: $20 in fees
	384	- Alice gets 0.012 BTC back
	385	- Bob gets 0.008 BTC back
	386
	387	Total fees paid: $40
	388	Time saved: Hours of waiting
	389	Privacy: Priceless
	390
	391	If they'd used normal Bitcoin:
	392	- 100 transactions × $5 fee = $500 in fees
	393	- 100 × 10 minutes waiting = 16 hours of waiting
	394	- Every transaction public on blockchain
	395	```
	396
	397	Savings: $460 in fees, 16 hours of time, total privacy.
	398
	399	## Comparison to Other Payment Methods
	400
	401	### vs Credit Cards
	402
	403	Credit Card:
	404	- ❌ 2-3% merchant fees
	405	- ❌ 3-5 day settlement
	406	- ❌ Chargebacks (fraud risk for merchants)
	407	- ❌ Bank sees everything
	408	- ❌ Not your money (it's credit)
	409
	410	Payment Channel:
	411	- ✅ ~0% fees (after opening/closing)
	412	- ✅ Instant settlement
	413	- ✅ No chargebacks (final)
	414	- ✅ Only you and partner see transactions
	415	- ✅ Your Bitcoin (self-custodial)
	416
	417	### vs PayPal/Venmo
	418
	419	PayPal/Venmo:
	420	- ❌ 2.9% + $0.30 per transaction
	421	- ❌ Company sees everything
	422	- ❌ Can freeze account
	423	- ❌ Not available internationally
	424	- ❌ Requires bank account
	425
	426	Payment Channel:
	427	- ✅ Near-zero fees
	428	- ✅ Only you and partner see transactions
	429	- ✅ Cannot be frozen
	430	- ✅ Works globally (Bitcoin has no borders)
	431	- ✅ No bank account needed
	432
	433	### vs Lightning Network
	434
	435	Lightning Network:
	436	- ✅ Fast, cheap Bitcoin payments
	437	- ❌ Complex to run node
	438	- ❌ Need watchtower service
	439	- ❌ Routing through strangers
	440	- ❌ Liquidity management is hard
	441
	442	Hypercore L2:
	443	- ✅ Fast, cheap Bitcoin payments
	444	- ✅ Easy to run (Pear app)
	445	- ✅ No watchtower (Hypercore replication)
	446	- ✅ Direct channels (no strangers)
	447	- ❌ Still has liquidity challenges (same as Lightning)
	448
	449	### vs Normal Bitcoin
	450
	451	Normal Bitcoin:
	452	- ✅ Decentralized
	453	- ✅ Self-custodial
	454	- ❌ Slow (10+ minutes)
	455	- ❌ Expensive ($5-50 per transaction)
	456	- ❌ Not private (public blockchain)
	457
	458	Payment Channel:
	459	- ✅ Decentralized
	460	- ✅ Self-custodial
	461	- ✅ Fast (1 second)
	462	- ✅ Cheap ($0 per transaction after opening)
	463	- ✅ Private (off-chain)
	464
	465	## Bottom Line
	466
	467	Payment channels are like opening a bar tab with Bitcoin:
	468	- Great if you're a regular customer (recurring payments)
	469	- Wasteful if you only visit once (one-time payment)
	470
	471	Perfect for:
	472	- Roommates splitting bills
	473	- Freelancer + regular client
	474	- Family supporting relatives abroad
	475	- Any two people who transact regularly
	476
	477	Provides:
	478	- 100x faster payments (1 second vs 10 minutes)
	479	- 95% cheaper (avoid per-transaction fees)
	480	- Complete privacy (nobody sees your trades)
	481	- Full control (self-custodial, no middleman)
	482
	483	Uses Hypercore infrastructure:
	484	- Hypercore = Private ledger (append-only log)
	485	- Hyperswarm = Peer discovery (no central server)
	486	- Secret-stream = Encryption (private communication)
	487	- Pear = Easy deployment (one-click app)
	488
	489	Cost to start: About $1,000 per person (minimum practical amount to make fees worthwhile).
	490
	491	The innovation: Using P2P technology (Hypercore) to build what Lightning Network does, but simpler to operate and more private.

README.md +202 -0

…	…	@@ -0,0 +1,202 @@
	1	# Pear L2
	2
	3	Bitcoin Layer 2 payment channels built on the Holepunch stack. A simpler, more private alternative to Lightning Network — self-custodial, instant, cheap Bitcoin payments using Hypercore for state, Hyperswarm for networking, and secret-stream for encryption.
	4
	5	## Status
	6
	7	Research / concept stage — architecture designed, no code yet.
	8
	9	## Core Idea
	10
	11	Instead of posting every Bitcoin transaction on-chain (slow, expensive, public), two parties:
	12
	13	1. Lock Bitcoin in a 2-of-2 multisig (on-chain, once)
	14	2. Trade instantly using a shared Hypercore log (off-chain, unlimited)
	15	3. Settle final balances on-chain when done (on-chain, once)
	16
	17	Result: 100x faster, 95% cheaper, totally private, fully self-custodial.
	18
	19	## Why Not Just Use Lightning?
	20
	21	\| Feature \| Lightning \| Pear L2 \|
	22	\|---------\|-----------\|---------\|
	23	\| State storage \| Separate commitment txs per party \| Shared Hypercore log (always synced) \|
	24	\| Watchtowers \| Separate service needed \| Built-in via Hypercore replication \|
	25	\| Routing \| Gossip protocol (public) \| Hyperbee query (private) \|
	26	\| Privacy \| Onion routing (multi-hop) \| Secret-stream (direct, E2E encrypted) \|
	27	\| NAT traversal \| Manual port forwarding \| Built-in (Hyperswarm DHT) \|
	28	\| Deployment \| Complex node setup \| Pear app (one command install) \|
	29	\| Infrastructure \| Lightning Network required \| Pure P2P (self-hosted) \|
	30
	31	## Architecture
	32
	33	```
	34	┌──────────────────────────────────────────────────┐
	35	│ Pear Application │
	36	│ ┌────────────┐ ┌──────────────┐ ┌──────────┐ │
	37	│ │ Wallet │ │ Channel │ │ Network │ │
	38	│ │ Manager │ │ Manager │ │ Manager │ │
	39	│ └─────┬──────┘ └──────┬───────┘ └────┬─────┘ │
	40	└────────┼────────────────┼───────────────┼────────┘
	41	│ │ │
	42	┌─────▼──────┐ ┌──────▼───────┐ ┌───▼────────┐
	43	│ wdk-wallet │ │ Hypercore │ │ Hyperswarm │
	44	│ -btc │ │ + Autobase │ │ + Secret- │
	45	│ │ │ │ │ stream │
	46	└─────┬──────┘ └──────────────┘ └────────────┘
	47	│
	48	┌─────▼──────────────────────────────────────────┐
	49	│ Bitcoin Blockchain │
	50	└─────────────────────────────────────────────────┘
	51	```
	52
	53	### Components
	54
	55	Bitcoin Layer (wdk-wallet-btc)
	56	- 2-of-2 multisig with Taproot scripts
	57	- Cooperative close (keypath spend, both sign)
	58	- Unilateral close (script path, timelock + fraud proof)
	59	- Penalty mechanism (counterparty gets everything if fraud detected)
	60
	61	State Channel Layer (Hypercore + Autobase)
	62	- Shared append-only log per channel (tamper-proof history)
	63	- Both parties replicate automatically (always synced)
	64	- Merkle proofs for dispute resolution
	65	- Monotonic nonces prevent replay attacks
	66
	67	Network Layer (Hyperswarm + Secret-stream)
	68	- DHT-based peer discovery (no central coordinator)
	69	- NAT hole-punching built-in
	70	- Noise protocol encryption (perfect forward secrecy)
	71	- Direct P2P connections (no routing nodes)
	72
	73	## How It Works
	74
	75	### Opening a Channel
	76
	77	```
	78	Alice Bitcoin Bob
	79	│ │ │
	80	├── Create Autobase ────────────┼──────── Create Autobase ─────┤
	81	│ (shared state log) │ (shared state log) │
	82	│ │ │
	83	├── Fund multisig (0.01 BTC) ──►│ │
	84	│ │◄── Confirm (6 blocks) ──────┤
	85	│ │ │
	86	├── Discover via Hyperswarm ────┼──────── Join DHT topic ──────┤
	87	│ │ │
	88	└── Channel open! ──────────────┼──────── Channel open! ───────┘
	89	```
	90
	91	### Making Payments (Off-Chain)
	92
	93	```
	94	Alice Hypercore Bob
	95	│ │ │
	96	├── Append payment entry ───►│ │
	97	│ (amount, nonce, sig) │ │
	98	│ │──── Replicate ────────────►│
	99	│ │ │
	100	│◄─── Request Bob's sig ─────┼────────────────────────────┤
	101	│ │◄─── Sign + append ─────────┤
	102	│ │ │
	103	└── Done (~100ms) ───────────┼──────── Done (~100ms) ─────┘
	104	```
	105
	106	- Instant — no blockchain confirmation needed
	107	- Private — only Alice and Bob see the transaction
	108	- Free — no on-chain fees for off-chain payments
	109
	110	### Closing a Channel
	111
	112	Cooperative (both online, agree): sign final state, broadcast, done in ~10 min.
	113
	114	Unilateral (one party offline): submit latest state with 24h timelock. If counterparty detects fraud (old state submitted), they submit penalty tx and take everything.
	115
	116	## Fraud Protection
	117
	118	Hypercore's append-only property makes fraud detection automatic:
	119
	120	1. Timelock — unilateral close has 24h delay
	121	2. Hypercore proof — can prove newer state exists via merkle proof
	122	3. Penalty — cheater loses 100% of channel funds
	123	4. No watchtower needed — Hypercore replication monitors automatically
	124
	125	Game theory makes cheating irrational:
	126	- Honest: get your balance (guaranteed)
	127	- Cheat: 5% chance of stealing, 95% chance of losing everything
	128
	129	## Perfect Use Cases
	130
	131	- Roommates splitting bills (100+ transactions/year)
	132	- Freelancer + regular client (52 payments/year)
	133	- Cross-border remittances (monthly family support)
	134	- Content creator subscriptions (private recurring payments)
	135	- Gig economy (instant micropayments per delivery)
	136
	137	## Does NOT Work For
	138
	139	- One-time payments to strangers (channel setup cost too high)
	140	- Retail point-of-sale (too many different customers)
	141	- Large one-time purchases (fees don't matter at $100k scale)
	142
	143	## Liquidity Requirements
	144
	145	- Minimum practical: 0.01 BTC (~$1,000) per person
	146	- Small network (10 friends): 0.1 BTC total (~$10,000)
	147	- On-chain fees are $10-50, need 100+ transactions to amortize
	148
	149	## Performance
	150
	151	\| Operation \| Time \| Limiting Factor \|
	152	\|-----------\|------\|-----------------\|
	153	\| Payment \| ~100ms \| Hypercore append + signature \|
	154	\| Channel open \| ~10 min \| Bitcoin confirmation (6 blocks) \|
	155	\| Channel close (cooperative) \| ~10 min \| Bitcoin confirmation \|
	156	\| Channel close (unilateral) \| ~24h \| Timelock period \|
	157	\| Peer discovery \| ~1-5 sec \| DHT lookup \|
	158	\| Throughput \| ~10 payments/sec \| Signature generation \|
	159	\| Storage \| ~4.6 MB/channel \| 100 payments/day for 6 months \|
	160
	161	## Main Blockers
	162
	163	1. Bitcoin script complexity — need fraud-proof mechanism (solvable with Taproot)
	164	2. Security model design — game theory for penalty transactions (requires careful design)
	165	3. Development time — 6-12 months for MVP
	166
	167	## All Tools Already Exist
	168
	169	Every building block is in the Holepunch ecosystem:
	170
	171	- wdk-wallet-btc — Bitcoin signing, UTXO management, multisig
	172	- hypercore — Append-only log, replication, merkle proofs
	173	- autobase — Multi-writer coordination
	174	- hyperswarm — Peer discovery, NAT traversal
	175	- secret-stream — Encrypted transport (Noise protocol)
	176	- hyperbee — Routing index (B-tree, for multi-hop)
	177	- pear — Deployment and runtime
	178
	179	## Development Roadmap
	180
	181	Phase 1: Single Channel (3-6 months)
	182	- Two parties, fixed channel size, cooperative close only, no routing
	183
	184	Phase 2: Security (3-6 months)
	185	- Unilateral close, fraud proofs, timelock disputes, penalty mechanism
	186
	187	Phase 3: Network (6-12 months)
	188	- Multi-hop payments (HTLCs), Hyperbee routing index, rebalancing, fee market
	189
	190	## Documents
	191
	192	\| Document \| Description \|
	193	\|----------\|-------------\|
	194	\| [CONCEPT.md](./CONCEPT.md) \| Core architecture — Bitcoin scripts, Hypercore state, Hyperswarm networking \|
	195	\| [HOW_IT_WORKS.md](./HOW_IT_WORKS.md) \| Plain English explanation for non-technical readers \|
	196	\| [USE_CASES.md](./USE_CASES.md) \| What works, what doesn't, when to use it \|
	197	\| [ARCHITECTURE.md](./ARCHITECTURE.md) \| Full technical implementation — code samples, data flows, storage schema \|
	198	\| [SOLUTIONS.md](./SOLUTIONS.md) \| Advanced features for edge cases \|
	199
	200	## License
	201
	202	Research documents — no code yet.

SOLUTIONS.md +774 -0

…	…	@@ -0,0 +1,774 @@
	1	# Solutions for Edge Cases
	2
	3	This document describes how to extend the basic payment channel system to handle use cases that don't work well with simple direct channels.
	4
	5	---
	6
	7	## 1. Routing Network (Solves: Strangers, Multiple Recipients, Retail)
	8
	9	### The Problem
	10
	11	```
	12	❌ Can't open channel with coffee shop (they have 1000 customers)
	13	❌ Can't open channel with every merchant
	14	❌ Need to pay people you don't have direct channel with
	15	```
	16
	17	### The Solution: Lightning-Style Routing Using Hypercore
	18
	19	Build a multi-hop payment network where you can pay anyone through intermediaries.
	20
	21	#### Architecture
	22
	23	```javascript
	24	// Use Hyperbee to index available routes
	25	const routingIndex = new Hyperbee(corestore.get())
	26
	27	// Each node publishes their channels and liquidity
	28	await routingIndex.put(`/node/${myId}/channels`, {
	29	peers: ['alice', 'bob', 'carol'],
	30	capacity: [10000, 5000, 8000], // Available liquidity
	31	fees: [0.1, 0.1, 0.1] // 0.1% routing fee
	32	})
	33
	34	// Find route from You → Coffee Shop
	35	const path = await findRoute({
	36	from: 'you',
	37	to: 'coffeeShop',
	38	amount: 500,
	39	index: routingIndex
	40	})
	41
	42	// Result: You → Alice → Bob → Coffee Shop
	43	```
	44
	45	#### How Multi-Hop Works
	46
	47	```javascript
	48	// Use HTLCs (Hash Time-Locked Contracts)
	49	const secret = randomBytes(32)
	50	const hash = sha256(secret)
	51
	52	// Lock payment across route
	53	for (const hop of path) {
	54	await hop.channel.lockPayment({
	55	amount: 500,
	56	secretHash: hash,
	57	timeout: 24 // hours
	58	})
	59	}
	60
	61	// Reveal secret to complete payment
	62	// Each hop unlocks automatically
	63	await coffeeShop.revealSecret(secret)
	64
	65	// Result: Payment flows through route atomically
	66	// Either all succeed or all fail (no partial payments)
	67	```
	68
	69	#### Using Holepunchto Tools
	70
	71	\| Tool \| Purpose \|
	72	\|------\|---------\|
	73	\| Hyperbee \| Index available routes and liquidity \|
	74	\| Hyperswarm \| Discover routing nodes \|
	75	\| Secret-stream \| Encrypted route finding (privacy) \|
	76	\| Autobase \| Multi-party coordination for routes \|
	77
	78	#### Benefits Over Lightning
	79
	80	✅ No gossip protocol - Hyperbee queries instead of broadcasting to everyone
	81	✅ Better privacy - Encrypted route discovery via secret-stream
	82	✅ Simpler node - Runs as Pear app instead of complex Lightning daemon
	83
	84	#### Tradeoffs
	85
	86	⚠️ Still need liquidity providers (same as Lightning)
	87	⚠️ Still need channel rebalancing
	88	⚠️ More complex than direct channels
	89
	90	---
	91
	92	## 2. Custodial Bridge (Solves: Non-Technical Recipients)
	93
	94	### The Problem
	95
	96	```
	97	❌ Your landlord doesn't understand crypto
	98	❌ Won't open channel, won't run software
	99	❌ But you want to pay them in Bitcoin
	100	```
	101
	102	### The Solution: Trusted Bridge Service
	103
	104	A service that opens channels on behalf of non-technical users.
	105
	106	#### Architecture
	107
	108	```javascript
	109	class HypercoreBridge {
	110	async createVirtualChannel(userId) {
	111	// Bridge opens channel with YOU
	112	const channel = await this.openChannel({
	113	user: userId,
	114	bridge: this.identity,
	115	amount: 0.01 // Bridge provides liquidity
	116	})
	117
	118	// User gets virtual "account"
	119	return {
	120	publicKey: userId,
	121	balance: channel.balance,
	122	withdraw: (btcAddress) => this.cashOut(btcAddress),
	123	deposit: (amount) => this.topUp(amount)
	124	}
	125	}
	126
	127	async cashOut(btcAddress) {
	128	// Convert channel balance to on-chain Bitcoin
	129	const tx = await this.closeChannelAndPay(btcAddress)
	130	await this.broadcast(tx)
	131	}
	132
	133	async sendToNonUser(phone, amount) {
	134	// Send SMS: "You received $100 in Bitcoin"
	135	await this.sms.send(phone, {
	136	message: `You received $${amount}. Click to claim: ${link}`
	137	})
	138	}
	139	}
	140	```
	141
	142	#### Use Case Flow
	143
	144	```
	145	1. You open channel with Bridge service ($1000)
	146	2. You pay your landlord: "Pay 555-1234 $500"
	147	3. Bridge sends SMS: "You received $500 BTC"
	148	4. Landlord clicks link, enters bank account
	149	5. Bridge cashes out to their bank (or keeps in BTC wallet)
	150	```
	151
	152	#### Similar To
	153
	154	- Strike - Lightning-to-fiat bridge
	155	- Cash App - Bitcoin payments for non-technical users
	156
	157	#### Using Holepunchto
	158
	159	- Bridge runs on Pear infrastructure
	160	- Uses Hypercore channels with users
	161	- Hyperswarm for peer discovery
	162
	163	#### Tradeoffs
	164
	165	❌ Requires trusting the bridge (custodial)
	166	✅ But: Recipient doesn't need to understand crypto
	167	✅ Onboards non-technical users to Bitcoin economy
	168
	169	---
	170
	171	## 3. Offline Payments (Solves: Airplane, No Internet)
	172
	173	### The Problem
	174
	175	```
	176	❌ No internet connection
	177	❌ Can't update Hypercore
	178	❌ Can't sync channel state
	179	❌ But need to make payment NOW
	180	```
	181
	182	### The Solution: Ecash-Style Tokens
	183
	184	Mint redeemable tokens from your channel balance that work offline.
	185
	186	#### Architecture
	187
	188	```javascript
	189	// Before going offline, mint "tokens" from channel
	190	const tokens = await channel.mintTokens({
	191	amount: 1000, // 1000 sats worth
	192	denominations: [100, 100, 100, 100, 100, 500] // Like cash bills
	193	})
	194
	195	// Each token is a signed promise
	196	const token = {
	197	value: 100,
	198	channelId: 'abc123',
	199	nonce: crypto.randomBytes(16), // Prevents double-spend
	200	signature: sign({ channelId, value, nonce }, [myKey, peerKey])
	201	}
	202
	203	// Offline: Transfer token to merchant via NFC/Bluetooth
	204	await merchant.acceptToken(token)
	205
	206	// Online later: Merchant redeems token in channel
	207	await channel.redeemToken(token) // Updates Hypercore log
	208	```
	209
	210	#### How It Works
	211
	212	1. Online: Pre-mint tokens from channel balance
	213	2. Offline: Transfer tokens like physical cash (NFC, QR code, Bluetooth)
	214	3. Online later: Tokens redeem to channel balance
	215
	216	#### Anti-Double-Spend
	217
	218	```javascript
	219	// Hypercore log tracks issued tokens
	220	const tokenLog = new Hypercore()
	221
	222	// Minting records token
	223	await tokenLog.append({
	224	type: 'mint',
	225	tokenId: hash(nonce),
	226	value: 100,
	227	owner: 'alice'
	228	})
	229
	230	// Redemption marks as spent
	231	await tokenLog.append({
	232	type: 'redeem',
	233	tokenId: hash(nonce),
	234	newOwner: 'bob'
	235	})
	236
	237	// Can't redeem twice (Hypercore shows it's spent)
	238	```
	239
	240	#### Using Holepunchto
	241
	242	- Hypercore: Token issuance log (prevents double-spend)
	243	- Autobase: Multi-party token validation
	244	- Local-first: Tokens stored locally, sync when online
	245
	246	#### Benefits
	247
	248	✅ Truly offline payments (no internet needed at payment time)
	249	✅ Like physical cash (transfer tokens peer-to-peer)
	250	✅ Redeemable when back online
	251
	252	#### Tradeoffs
	253
	254	⚠️ Can't verify double-spend until online (merchant takes risk)
	255	⚠️ Merchant must trust issuer (token backed by channel)
	256
	257	#### Real Examples
	258
	259	- Chaumian Ecash - Original digital cash protocol
	260	- Cashu - Modern Bitcoin ecash implementation
	261
	262	---
	263
	264	## 4. Escrow Contracts (Solves: Untrusted Parties)
	265
	266	### The Problem
	267
	268	```
	269	❌ Want to buy from stranger
	270	❌ Don't trust them
	271	❌ Don't want to lock funds in channel
	272	❌ Need neutral mediator
	273	```
	274
	275	### The Solution: Bitcoin Escrow + Hypercore Evidence
	276
	277	Use 2-of-3 multisig with evidence stored in Hypercore.
	278
	279	#### Architecture
	280
	281	```javascript
	282	// 2-of-3 multisig: Buyer, Seller, Mediator
	283	const escrow = await createEscrow({
	284	buyer: buyerKey,
	285	seller: sellerKey,
	286	mediator: mediatorKey,
	287	amount: 10000, // 0.0001 BTC
	288	terms: 'Deliver laptop by Jan 30'
	289	})
	290
	291	// Store dispute evidence in Hypercore
	292	const disputeLog = new Hypercore()
	293
	294	// Buyer submits evidence
	295	await disputeLog.append({
	296	type: 'evidence',
	297	from: 'buyer',
	298	claim: 'Never received laptop',
	299	proof: photoHash, // IPFS/Hypercore hash of photo
	300	timestamp: Date.now()
	301	})
	302
	303	// Seller submits counter-evidence
	304	await disputeLog.append({
	305	type: 'evidence',
	306	from: 'seller',
	307	claim: 'Delivered to address',
	308	proof: trackingNumber,
	309	timestamp: Date.now()
	310	})
	311
	312	// Mediator reviews Hypercore log
	313	const evidence = disputeLog.createReadStream()
	314	for await (const entry of evidence) {
	315	console.log(entry.claim, entry.proof)
	316	}
	317
	318	// Mediator decides based on evidence
	319	// Signs with 2-of-3 to release funds
	320	```
	321
	322	#### Possible Outcomes
	323
	324	Happy path: Buyer + Seller sign (mediator not needed)
	325	```javascript
	326	const releaseTx = await escrow.release({
	327	signatures: [buyerSig, sellerSig],
	328	recipient: sellerAddress
	329	})
	330	```
	331
	332	Dispute: Mediator + Winner sign
	333	```javascript
	334	const disputeTx = await escrow.release({
	335	signatures: [mediatorSig, buyerSig], // Mediator sided with buyer
	336	recipient: buyerAddress
	337	})
	338	```
	339
	340	Mediator disappears: Timelock releases after 90 days
	341	```javascript
	342	// After 90 days, either party can claim
	343	const timelockTx = await escrow.timelockRelease({
	344	signature: buyerSig OR sellerSig,
	345	timelock: 90 * 24 * 60 * 60
	346	})
	347	```
	348
	349	#### Using Holepunchto
	350
	351	- Hypercore: Tamper-proof evidence log (can't alter history)
	352	- Hyperswarm: Discover mediators
	353	- Hyperbee: Mediator reputation index
	354
	355	#### Benefits
	356
	357	✅ Safe to trade with strangers
	358	✅ Decentralized (anyone can be mediator)
	359	✅ Evidence is cryptographically verifiable (Hypercore proofs)
	360	✅ Mediator can't steal (needs 2-of-3)
	361
	362	---
	363
	364	## 5. Audit Trail Layer (Solves: Business Compliance)
	365
	366	### The Problem
	367
	368	```
	369	❌ Business needs to show accountants every transaction
	370	❌ Channel transactions are private (that's the point!)
	371	❌ IRS requires proof
	372	```
	373
	374	### The Solution: Opt-In Public Transparency
	375
	376	Publish merkle roots to public Hypercore without revealing details.
	377
	378	#### Architecture
	379
	380	```javascript
	381	// Optional: Publish channel state to public Hypercore
	382	const publicLog = new Hypercore({
	383	name: 'business-audit-trail',
	384	encrypted: false // Public!
	385	})
	386
	387	// After each channel transaction
	388	channel.on('update', async (state) => {
	389	// Publish only merkle root (not transaction details)
	390	await publicLog.append({
	391	timestamp: Date.now(),
	392	channelId: 'abc123',
	393	stateRoot: merkleRoot(state), // Hash of full state
	394	parties: ['businessA', 'businessB']
	395	})
	396
	397	// Optionally: Commit to Bitcoin for timestamp proof
	398	await commitToBitcoin(merkleRoot(state))
	399	})
	400
	401	// Auditor can verify timeline
	402	const auditLog = new Hypercore(publicLogKey)
	403	for await (const entry of auditLog.createReadStream()) {
	404	console.log(`Transaction at ${new Date(entry.timestamp)}`)
	405	// Can verify against Bitcoin block headers
	406	}
	407	```
	408
	409	#### Selective Disclosure
	410
	411	```javascript
	412	// Reveal specific transactions to auditor
	413	// Without revealing OTHER transactions
	414	await proveTransaction({
	415	transaction: tx,
	416	merkleProof: proof, // Cryptographic proof
	417	publicRoot: publicLog.get(index)
	418	})
	419
	420	// Auditor verifies:
	421	// 1. Transaction is included in merkle root
	422	// 2. Merkle root is in public log
	423	// 3. Public log is committed to Bitcoin
	424	// Result: Proven without revealing other txs
	425	```
	426
	427	#### Using Holepunchto
	428
	429	- Hypercore: Public audit log (append-only, verifiable)
	430	- Hyperbee: Index transactions by date/party/type
	431	- Merkle proofs: Selective disclosure (privacy + compliance)
	432
	433	#### Benefits
	434
	435	✅ Regulatory compliance (can prove transactions to auditors)
	436	✅ Optional (not required for all users)
	437	✅ Selective disclosure (prove ONE transaction without revealing others)
	438	✅ Privacy preserved (only reveal what's necessary)
	439
	440	---
	441
	442	## 6. Just-In-Time Liquidity (Solves: Large Payments, Don't Want to Lock Funds)
	443
	444	### The Problem
	445
	446	```
	447	❌ Want to make $50k payment
	448	❌ Don't want to lock $50k in channel long-term
	449	❌ Need liquidity available for other uses
	450	```
	451
	452	### The Solution: Ephemeral Channels
	453
	454	Open and close channels quickly for one-time large payments.
	455
	456	#### Architecture
	457
	458	```javascript
	459	class JITChannel {
	460	async pay(recipient, amount) {
	461	// 1. Open channel with high priority (pay higher fee)
	462	const channel = await this.openChannel({
	463	peer: recipient,
	464	amount: amount + fees,
	465	priority: 'high' // Higher on-chain fee for fast confirmation
	466	})
	467
	468	// 2. Make payment immediately (once funded)
	469	await channel.send(amount)
	470
	471	// 3. Close cooperatively (both parties online)
	472	await channel.close()
	473
	474	// Total time: ~20 minutes (2 Bitcoin confirmations)
	475	// Total cost: $20-30 (vs $10 for single on-chain tx)
	476	}
	477	}
	478	```
	479
	480	#### Alternative: Submarine Swaps
	481
	482	```javascript
	483	// Atomic swap: On-chain BTC ↔ Off-chain channel balance
	484	async function submarineSwap(amount) {
	485	// Pay on-chain BTC → Receive in channel
	486	await atomicSwap({
	487	pay: { type: 'onchain', amount },
	488	receive: { type: 'channel', amount: amount - fee }
	489	})
	490
	491	// No trust needed (atomic = both succeed or both fail)
	492	}
	493	```
	494
	495	#### Using Holepunchto
	496
	497	- Hyperswarm: Quick peer discovery
	498	- Hypercore: Fast channel state setup
	499	- Atomic swaps: Trustless on/off-chain conversion
	500
	501	#### Benefits
	502
	503	✅ Don't lock liquidity long-term
	504	✅ Still faster than 2 separate on-chain txs
	505	✅ Slightly cheaper
	506
	507	#### Tradeoffs
	508
	509	⚠️ Only marginally better than regular Bitcoin
	510	⚠️ But enables routing through channel network
	511
	512	---
	513
	514	## 7. KYC/Compliance Wrapper (Solves: Regulated Businesses)
	515
	516	### The Problem
	517
	518	```
	519	❌ Licensed money transmitter
	520	❌ Must verify customer identity (KYC)
	521	❌ Must report to FinCEN
	522	❌ Channels are too private
	523	```
	524
	525	### The Solution: Permissioned Channel Network
	526
	527	Add KYC verification layer on top of channels.
	528
	529	#### Architecture
	530
	531	```javascript
	532	class CompliantChannel {
	533	async openChannel(peer) {
	534	// 1. Both parties submit KYC
	535	const myKYC = await kycService.verify({
	536	name: 'Alice',
	537	ssn: 'xxx-xx-1234',
	538	address: '123 Main St'
	539	})
	540
	541	const peerKYC = await kycService.verify(peer)
	542
	543	// 2. KYC service issues signed credentials
	544	const credential = await kycService.issueCredential({
	545	identity: myKYC,
	546	hypercore: myFeed.key
	547	})
	548
	549	// 3. Open channel with KYC proof attached
	550	const channel = await openChannel({
	551	peer,
	552	kycProof: [myCredential, peerCredential]
	553	})
	554
	555	// 4. Automatically report large transactions
	556	channel.on('update', async (state) => {
	557	if (state.amount > 10000) {
	558	await reportToFinCEN({
	559	amount: state.amount,
	560	parties: [myKYC.name, peerKYC.name],
	561	timestamp: Date.now()
	562	})
	563	}
	564	})
	565	}
	566	}
	567	```
	568
	569	#### Using Zero-Knowledge Proofs
	570
	571	```javascript
	572	// Prove compliance WITHOUT revealing identity
	573	const proof = await createZKProof({
	574	statement: 'I am KYC-verified',
	575	witness: myKYC,
	576	publicInput: hash(myKYC)
	577	})
	578
	579	// Regulator can verify proof
	580	// But doesn't see actual identity (unless required)
	581	```
	582
	583	#### Using Holepunchto
	584
	585	- Hypercore: Store encrypted KYC proofs
	586	- Zero-knowledge proofs: Prove compliance without revealing data
	587	- Hyperbee: Index compliant channels
	588
	589	#### Benefits
	590
	591	✅ Satisfies regulators (KYC/AML compliance)
	592	✅ Still uses channel tech (speed/cost benefits)
	593	✅ Optional (non-regulated users don't need it)
	594
	595	#### Tradeoffs
	596
	597	❌ Loses some privacy (required for regulated entities)
	598	✅ But enables businesses to use channel technology legally
	599
	600	---
	601
	602	## 8. Liquidity Marketplace (Solves: Can't Afford to Lock Funds)
	603
	604	### The Problem
	605
	606	```
	607	❌ Want to use channels
	608	❌ Don't have $1000 to lock up
	609	❌ Need someone to provide liquidity
	610	```
	611
	612	### The Solution: Liquidity-as-a-Service
	613
	614	Rent liquidity from providers who earn fees.
	615
	616	#### Architecture
	617
	618	```javascript
	619	class LiquidityMarket {
	620	async rentLiquidity(amount, duration) {
	621	// Find liquidity providers via Hyperbee
	622	const providers = await this.index.query({
	623	amount: { gte: amount },
	624	duration: { gte: duration },
	625	fee: { lte: 0.01 } // Max 1% fee
	626	})
	627
	628	// Provider opens channel WITH you (they fund it)
	629	const channel = await providers[0].openChannel({
	630	theirSide: amount, // They deposit $1000
	631	yourSide: 0, // You deposit $0
	632	fee: amount * 0.01, // You pay 1% rental fee
	633	duration: duration // Lock for 30 days
	634	})
	635
	636	// You can now RECEIVE payments up to `amount`
	637	// Provider earns fee for providing capital
	638	return channel
	639	}
	640	}
	641	```
	642
	643	#### Liquidity Provider Incentives
	644
	645	```javascript
	646	class LiquidityProvider {
	647	async provideLiquidity() {
	648	// Lock capital, earn fees
	649	const channels = await this.openChannels({
	650	totalCapital: 1.0, // 1 BTC
	651	feeRate: 0.01, // 1%
	652	duration: 30 // days
	653	})
	654
	655	// Expected return: 1% per month = 12% APY
	656	// vs: 0% holding BTC in wallet
	657	}
	658	}
	659	```
	660
	661	#### Using Holepunchto
	662
	663	- Hyperbee: Liquidity marketplace index
	664	- Hyperswarm: Discover providers
	665	- Smart contracts: Enforce fee payment (Bitcoin script)
	666
	667	#### Real Examples
	668
	669	- Lightning Network: Pool, Magma (liquidity marketplaces)
	670	- Similar model works for Hypercore channels
	671
	672	#### Benefits
	673
	674	✅ No capital required (rent instead of buy)
	675	✅ Pay small fee for liquidity rental (1-2%)
	676	✅ Enables receiving payments without locking funds
	677
	678	---
	679
	680	## Complete Architecture
	681
	682	Combining all solutions into a full-featured payment network:
	683
	684	```
	685	┌─────────────────────────────────────────────────────┐
	686	│ Application Layer │
	687	│ - Consumer payments (routing) │
	688	│ - Business payments (compliance wrapper) │
	689	│ - Offline payments (ecash tokens) │
	690	└─────────────────────────────────────────────────────┘
	691	↓
	692	┌─────────────────────────────────────────────────────┐
	693	│ Service Layer │
	694	│ - Routing network (Hyperbee index) │
	695	│ - Liquidity marketplace (rent capital) │
	696	│ - Custodial bridges (onboard non-technical users) │
	697	│ - KYC/compliance services (regulated businesses) │
	698	└─────────────────────────────────────────────────────┘
	699	↓
	700	┌─────────────────────────────────────────────────────┐
	701	│ Payment Channel Layer │
	702	│ - Direct channels (P2P, private) │
	703	│ - Multi-hop channels (routing) │
	704	│ - Escrow contracts (trustless trades) │
	705	└─────────────────────────────────────────────────────┘
	706	↓
	707	┌─────────────────────────────────────────────────────┐
	708	│ Bitcoin Layer │
	709	│ - Final settlement (on-chain) │
	710	│ - Dispute resolution (fraud proofs) │
	711	│ - Timelock enforcement (security) │
	712	└─────────────────────────────────────────────────────┘
	713	```
	714
	715	All built with Holepunchto:
	716	- Hypercore - State logs, evidence, token ledgers
	717	- Hyperbee - Routing index, liquidity marketplace, reputation
	718	- Hyperswarm - Peer discovery, mediator discovery
	719	- Secret-stream - Encrypted communication
	720	- Pear - Deployment and runtime
	721
	722	---
	723
	724	## Summary Table
	725
	726	\| Use Case \| Solution \| Complexity \| Trust Required \| Tools Needed \|
	727	\|----------\|----------\|------------\|----------------\|--------------\|
	728	\| Paying strangers \| Routing network \| High \| Low (trustless HTLCs) \| Hyperbee, Hyperswarm \|
	729	\| Non-technical users \| Custodial bridge \| Medium \| High (trust bridge) \| Pear app, SMS gateway \|
	730	\| Offline payments \| Signed tokens \| Medium \| Medium (anti-double-spend) \| Hypercore, NFC \|
	731	\| Untrusted parties \| Escrow contracts \| Medium \| Low (mediator) \| Bitcoin script, Hypercore \|
	732	\| Business compliance \| Public audit log \| Low \| None \| Hypercore, merkle proofs \|
	733	\| Large payments \| JIT channels \| Low \| None \| Fast open/close \|
	734	\| Regulatory \| KYC wrapper \| High \| Medium (KYC service) \| Zero-knowledge proofs \|
	735	\| No liquidity \| Rent from providers \| Medium \| Medium (provider) \| Hyperbee marketplace \|
	736
	737	---
	738
	739	## What's Still Not Possible?
	740
	741	### 1. True Instant Finality for Large Amounts
	742	- Bitcoin requires confirmations
	743	- Even channels need 24h dispute period
	744	- Solution: Use Bitcoin as-is for $100k+ deals (finality matters more than speed)
	745
	746	### 2. Completely Trustless Offline Payments
	747	- Physical proximity needed
	748	- Can't verify double-spend until online
	749	- Solution: Use ecash tokens with risk awareness
	750
	751	### 3. Perfect Anonymity + Compliance
	752	- Regulators want transparency
	753	- Users want privacy
	754	- Fundamental tension
	755	- Solution: Choose your tradeoff (KYC channels vs private channels)
	756
	757	---
	758
	759	## The Full Vision
	760
	761	A Pear-based payment network combining:
	762
	763	1. Direct channels → Privacy, speed (for regular partners)
	764	2. Routing layer → Pay anyone on network
	765	3. Offline tokens → No internet needed
	766	4. Escrow contracts → Trade with strangers safely
	767	5. Compliance wrapper → Businesses can participate legally
	768	6. Liquidity marketplace → No capital required to start
	769
	770	Result: Self-hosted, P2P payment network using Bitcoin for final settlement.
	771
	772	Complexity: Higher than simple channels, but solves 95%+ of real-world use cases.
	773
	774	Deployment: Runs as Pear app, no complex infrastructure needed.

USE_CASES.md +609 -0

…	…	@@ -0,0 +1,609 @@
	1	# Use Cases: What Works and What Doesn't
	2
	3	## ✅ Perfect Use Cases
	4
	5	### 1. Recurring Payments Between Same People
	6
	7	#### Roommates/Couples
	8
	9	Scenario:
	10	```
	11	Alice and Bob share apartment
	12	- Monthly rent split: $1000 each
	13	- Groceries: $200-300/month
	14	- Utilities: $150/month
	15	- Going out: $100-500/month
	16	- Total: 20-30 transactions/month
	17	```
	18
	19	Without channel:
	20	- 20-30 transactions/month × $5 fee = $100-150/month in fees
	21	- Each payment takes 10+ minutes
	22	- Everyone can see their transactions on blockchain
	23
	24	With channel:
	25	- Open once: $10 fee
	26	- 20-30 instant payments/month: $0
	27	- Close after 6 months: $10 fee
	28	- Total fees: $20 vs $600+
	29	- Every payment instant
	30	- Totally private
	31
	32	Why it's perfect:
	33	- Same two people (don't need routing)
	34	- Frequent transactions (amortize opening/closing fees)
	35	- Want privacy (nobody's business what roommates pay for)
	36
	37	#### Freelancer + Regular Client
	38
	39	Scenario:
	40	```
	41	Designer does work for startup
	42	- Weekly invoices: $500-2000
	43	- 52 payments/year
	44	- Client needs fast payment on completion
	45	```
	46
	47	Without channel: $260/year in fees
	48	With channel: $20/year in fees
	49	Bonus: Client pays instantly on completion (improves cash flow)
	50
	51	Why it's perfect:
	52	- Regular relationship (same client for months/years)
	53	- Predictable payment schedule
	54	- Want fast settlement (no waiting for wire transfers)
	55
	56	#### Family Support
	57
	58	Scenario:
	59	```
	60	Adult child sends money to parents abroad
	61	- Monthly support: $500
	62	- 12 payments/year
	63	- Parents in different country
	64	```
	65
	66	Without channel:
	67	- Traditional: $15-30 Western Union fee × 12 = $180-360/year
	68	- Bitcoin: $60/year + parents see amounts on blockchain
	69
	70	With channel:
	71	- $20/year
	72	- Totally private
	73	- Parents get money instantly
	74
	75	Why it's perfect:
	76	- Recurring payments (monthly)
	77	- Cross-border (Bitcoin ignores borders)
	78	- Privacy matters (family finances are private)
	79
	80	### 2. High-Frequency Trading Partners
	81
	82	#### Business Supply Chain
	83
	84	Scenario:
	85	```
	86	Coffee shop + Bean supplier
	87	- Orders beans 2-3 times/week
	88	- 100+ payments/year
	89	- $200-500 per order
	90	- Need fast settlement (supplier wants payment on delivery)
	91	```
	92
	93	Savings: $400+/year in fees
	94	Benefit: Instant settlement (no net-30 payment terms, better for supplier)
	95
	96	Why it's perfect:
	97	- Ongoing business relationship
	98	- High frequency (weekly)
	99	- Both parties benefit (shop gets credit, supplier gets instant payment)
	100
	101	#### Gig Economy
	102
	103	Scenario:
	104	```
	105	Delivery driver + Platform
	106	- Get paid per delivery
	107	- 20-50 deliveries/day
	108	- Traditional: Wait days/weeks for payout
	109	```
	110
	111	Without channel:
	112	- 50 deliveries × $5 fee = $250/day in fees (IMPOSSIBLE!)
	113	- Or: Wait for batched payout (bad for drivers)
	114
	115	With channel:
	116	- Instant micropayment per delivery
	117	- $0 fees
	118	- Driver has cash immediately
	119
	120	Why it's perfect:
	121	- Extremely high frequency
	122	- Micropayments (channel enables economically)
	123	- Benefits worker (immediate payment vs waiting)
	124
	125	### 3. Privacy-Sensitive Payments
	126
	127	#### Medical/Therapy
	128
	129	Scenario:
	130	```
	131	Patient pays therapist
	132	- Weekly sessions: $150/session
	133	- 52 sessions/year
	134	- Don't want public record of therapy
	135	```
	136
	137	With normal Bitcoin: Anyone can see patient ID pays therapist address every week
	138	With channel: Totally private, only patient and therapist know
	139
	140	Why it's perfect:
	141	- Highly sensitive (medical privacy)
	142	- Regular schedule (weekly)
	143	- HIPAA concerns (public blockchain is problematic)
	144
	145	#### Adult Content/Services
	146
	147	Scenario:
	148	```
	149	Subscriber pays content creator
	150	- Monthly subscription: $10-50
	151	- Don't want public record
	152	```
	153
	154	Why it's perfect:
	155	- Privacy critical (don't want on public blockchain)
	156	- Recurring (monthly)
	157	- Currently expensive (OnlyFans takes 20%, PayPal bans adult content)
	158
	159	#### Political Donations (Controversial Regions)
	160
	161	Scenario:
	162	```
	163	Supporter → Dissident journalist
	164	- Regular support payments
	165	- Dangerous if on public blockchain (authoritarian government tracking)
	166	```
	167
	168	Why it's perfect:
	169	- Extreme privacy needs (life/death)
	170	- Can't use traditional banking (government monitors)
	171	- Recurring support (monthly)
	172
	173	### 4. Cross-Border Remittances
	174
	175	#### Immigrant Worker → Family Abroad
	176
	177	Scenario:
	178	```
	179	Worker in US → Family in Philippines
	180	- Monthly: $300-500
	181	- Western Union fee: $15-30 (5-10%!)
	182	- Bank transfer: $25-50 + 3-5 days
	183	- Bitcoin channel: $1-2 + instant
	184	```
	185
	186	Annual savings: $180-360 in fees
	187	Time savings: No waiting days for transfer
	188
	189	Why it's perfect:
	190	- Recurring (monthly)
	191	- Cross-border (Bitcoin ignores borders)
	192	- High fees with traditional methods
	193	- Family needs money quickly
	194
	195	### 5. Gaming/Virtual Economies
	196
	197	#### In-Game Microtransactions
	198
	199	Scenario:
	200	```
	201	Players trading items
	202	- 100+ trades/day
	203	- $0.50-5 per trade
	204	- Bitcoin fees ($5) would be MORE than item value!
	205	```
	206
	207	With channel:
	208	- Open channel with game server
	209	- Unlimited microtransactions
	210	- Close channel when done playing
	211
	212	Why it's perfect:
	213	- Extremely high frequency
	214	- Micropayments (impossible with on-chain Bitcoin)
	215	- Same trading partners (repeated trades)
	216
	217	#### Streaming Tips
	218
	219	Scenario:
	220	```
	221	Viewers tip streamer
	222	- 50-200 tips/stream @ $1-10 each
	223	- Traditional crypto: $5 fee per tip (insane!)
	224	- Channel: Instant, free
	225	```
	226
	227	Why it's perfect:
	228	- High frequency (hundreds of tips per stream)
	229	- Micropayments ($1 tips)
	230	- Streamer wants immediate access to funds
	231
	232	---
	233
	234	## ❌ Does NOT Work Well For
	235
	236	### 1. One-Time Payments to Strangers
	237
	238	#### Buying from eBay Seller
	239
	240	Scenario:
	241	```
	242	Want to buy laptop for $500 from stranger on eBay
	243	```
	244
	245	With channel:
	246	- Open channel: $10 fee + 10 minutes
	247	- Make payment: $500
	248	- Close channel: $10 fee + 24 hours (if stranger doesn't cooperate)
	249	- Total cost: $520 + time
	250
	251	With regular Bitcoin:
	252	- One transaction: $5 fee + 10 minutes
	253	- Total cost: $505
	254
	255	Why it doesn't work:
	256	- Only 1 transaction (can't amortize opening/closing costs)
	257	- Stranger won't cooperate (won't close channel cooperatively)
	258	- Might need to wait 24 hours for timelock
	259
	260	Better solution: Just use regular Bitcoin
	261
	262	### 2. Paying Someone Who Doesn't Understand Crypto
	263
	264	#### Paying Your Landlord
	265
	266	Scenario:
	267	```
	268	Landlord is 70 years old, doesn't understand Bitcoin
	269	- Won't open channel
	270	- Won't keep computer online
	271	- Won't understand penalty mechanism
	272	- Wants rent in bank account
	273	```
	274
	275	Why it doesn't work:
	276	- Requires both parties to understand technology
	277	- Requires both parties to run software
	278	- Landlord just wants traditional payment
	279
	280	Better solution:
	281	- Bank transfer
	282	- Or: Use custodial bridge (see SOLUTIONS.md)
	283
	284	### 3. Retail/Point-of-Sale (Multiple Different Customers)
	285
	286	#### Coffee Shop Accepting Bitcoin
	287
	288	Problem:
	289	```
	290	Coffee shop has 1000 different customers
	291	- Can't open channel with every customer
	292	- 1000 channels = $10,000 locked up (liquidity problem)
	293	- Opening fees: 1000 × $10 = $10,000
	294	- Only sell $4 coffee (doesn't make sense)
	295	```
	296
	297	Why it doesn't work:
	298	- Too many different customers
	299	- Too much liquidity required
	300	- Payments too small vs channel opening cost
	301
	302	Better solution:
	303	- Lightning Network with routing
	304	- Or: Regular Bitcoin
	305	- Or: Credit cards (still cheaper for small amounts)
	306
	307	### 4. Shopping at Multiple Stores
	308
	309	#### Daily Errands
	310
	311	Scenario:
	312	```
	313	You need: groceries, gas, coffee, dinner
	314	- 4 different merchants
	315	- Need 4 different channels
	316	- Lock up: 4 × $1000 = $4000
	317	- Opening fees: 4 × $10 = $40
	318	```
	319
	320	Why it doesn't work:
	321	- Need separate channel for each merchant
	322	- Too much liquidity locked up
	323	- Too expensive to open many channels
	324
	325	Better solution:
	326	- Lightning Network with routing (one channel, pay anyone)
	327	- Or: Credit card
	328
	329	### 5. Large One-Time Payments
	330
	331	#### Buying a Car
	332
	333	Scenario:
	334	```
	335	Buying car for $20,000
	336	```
	337
	338	With channel:
	339	- Open channel with $20,000: $10 fee
	340	- Make payment: $20,000
	341	- Close channel: $10 fee
	342	- Total: $20,020
	343
	344	With regular Bitcoin:
	345	- One transaction: $10-20 fee
	346	- Total: $20,010-20,020
	347
	348	Why it doesn't work:
	349	- Similar cost to regular Bitcoin
	350	- Channel doesn't save money on large one-time payments
	351	- Added complexity for no benefit
	352
	353	Better solution: Just use regular Bitcoin
	354
	355	Rule of thumb: If payment is > $10,000 and one-time, the $10 fee doesn't matter much
	356
	357	### 6. Truly Offline Payments
	358
	359	#### Paying on Airplane
	360
	361	Scenario:
	362	```
	363	No internet connection
	364	Need to pay for something NOW
	365	Can't update Hypercore log
	366	Can't broadcast to Bitcoin if needed
	367	```
	368
	369	Why it doesn't work:
	370	- Requires internet to synchronize Hypercore
	371	- Requires internet to broadcast Bitcoin transactions
	372	- Both parties need connectivity
	373
	374	Better solution:
	375	- Traditional payment methods (cash, credit card)
	376	- Or: Offline tokens (see SOLUTIONS.md)
	377
	378	Note: You CAN make payments offline, but they only settle when you reconnect
	379
	380	### 7. Payments Requiring Instant Finality
	381
	382	#### Buying House/Car with Immediate Title Transfer
	383
	384	Scenario:
	385	```
	386	Buyer needs FINAL settlement NOW
	387	Seller won't transfer title until payment is irreversible
	388	```
	389
	390	Problem with channel:
	391	- Channel payment can be reversed (unilateral close with old state)
	392	- Need to wait 24+ hours to know it's truly final
	393	- Seller won't transfer title during timelock period
	394
	395	Better solution:
	396	- Regular Bitcoin (final after 6 confirmations = 1 hour)
	397	- Or: Escrow (see SOLUTIONS.md)
	398
	399	### 8. Business Requiring Audit Trails
	400
	401	#### Corporate Accounting/Compliance
	402
	403	Scenario:
	404	```
	405	Business needs to show auditors every transaction
	406	IRS requires proof of income/expenses
	407	Public company needs transparency
	408	```
	409
	410	Problem with channel:
	411	- Channel transactions are PRIVATE (that's the point!)
	412	- Can't prove to auditors what happened inside channel
	413	- Only see opening/closing on blockchain
	414	- No detailed transaction log for tax purposes
	415
	416	Better solution:
	417	- Regular Bitcoin (every tx on blockchain)
	418	- Or: Opt-in audit trail (see SOLUTIONS.md)
	419
	420	### 9. Payments to Untrusted Parties
	421
	422	#### Buying from Potential Scammer
	423
	424	Scenario:
	425	```
	426	Buying electronics from stranger on internet
	427	Don't trust them
	428	They might broadcast old state and steal
	429	You might be offline and miss it
	430	```
	431
	432	Problem:
	433	- Need to lock $1000+ in channel with stranger
	434	- They might try to cheat
	435	- You might be offline when they broadcast old state
	436	- Lose money if you don't catch fraud within 24 hours
	437
	438	Better solution:
	439	- Escrow service (see SOLUTIONS.md)
	440	- Regular Bitcoin with dispute resolution
	441
	442	Rule: Only open channels with people you semi-trust (or can monitor)
	443
	444	### 10. Emergency/Urgent Payments
	445
	446	#### Need Money Immediately
	447
	448	Scenario:
	449	```
	450	Friend in hospital needs money NOW
	451	Your channel partner is offline
	452	Need to force-close
	453	Must wait 24 hours (timelock)
	454	```
	455
	456	Problem:
	457	- Unilateral close requires waiting
	458	- Can't get money instantly in emergency
	459	- Might need funds before timelock expires
	460
	461	Better solution:
	462	- Keep some Bitcoin OUTSIDE channels for emergencies
	463	- Don't lock up 100% of funds in channels
	464
	465	### 11. Regulatory Compliance Requirements
	466
	467	#### Licensed Money Transmitter
	468
	469	Scenario:
	470	```
	471	Registered business accepting payments
	472	KYC/AML laws require identifying customers
	473	Must report to FinCEN/regulators
	474	Payment channels are too private
	475	```
	476
	477	Problem:
	478	- Regulators need to see transactions
	479	- Channels are private
	480	- Can't comply with reporting requirements
	481
	482	Better solution:
	483	- Custodial service
	484	- Or: KYC wrapper (see SOLUTIONS.md)
	485
	486	Note: If you're a licensed business, channels may violate regulations
	487
	488	---
	489
	490	## Quick Decision Matrix
	491
	492	### ✅ Use Payment Channel When:
	493
	494	- ✅ Same person/business repeatedly (5+ transactions)
	495	- ✅ Both parties can be online occasionally
	496	- ✅ Want privacy
	497	- ✅ Want speed (instant payments)
	498	- ✅ Want to avoid fees
	499	- ✅ Trust the other party (somewhat)
	500	- ✅ Small-to-medium amounts ($10-$10,000)
	501
	502	### ❌ Use Regular Bitcoin When:
	503
	504	- ✅ One-time payment
	505	- ✅ Large payment (> $10,000 where fees don't matter)
	506	- ✅ Paying stranger
	507	- ✅ Need audit trail
	508	- ✅ Regulatory compliance required
	509	- ✅ Recipient isn't technical
	510
	511	### 🔀 Use Lightning Network When:
	512
	513	- ✅ Need to pay MANY different people (routing needed)
	514	- ✅ Want to leverage existing network infrastructure
	515	- ✅ Okay with some centralization (watchtowers, routing nodes)
	516	- ✅ Don't mind complexity
	517
	518	---
	519
	520	## Real-World Adoption Predictions
	521
	522	### 🔥 High Adoption Probability
	523
	524	#### 1. Gig Economy ($50B+ market)
	525	Current: Drivers/workers wait days/weeks for payout
	526	With channels: Instant micropayments per ride/delivery
	527	Potential: Millions of users, billions in transaction volume
	528
	529	#### 2. Cross-Border Remittances ($700B market globally)
	530	Current: $25-50 fees via Western Union, 3-5 day delays
	531	With channels: $1-2 fees, instant
	532	Potential: Hundreds of millions of users, massive cost savings
	533
	534	#### 3. Content Creator Payments ($10B+ market)
	535	Current: 20-30% platform fees (OnlyFans, Patreon)
	536	With channels: 1-2% fees
	537	Potential: Hundreds of thousands of creators, direct fan relationships
	538
	539	#### 4. B2B Recurring Payments (Trillions in volume)
	540	Current: 2-3% credit card fees + 3-5 day settlement
	541	With channels: Near-zero fees + instant settlement
	542	Potential: Massive efficiency gains, improved cash flow
	543
	544	### 📉 Low Adoption Probability
	545
	546	#### 1. Retail Point-of-Sale
	547	Why: Too many different customers, can't lock liquidity per customer
	548	Better: Lightning Network or traditional credit cards
	549
	550	#### 2. E-commerce Marketplaces
	551	Why: Too many different merchants, need routing network
	552	Better: Lightning Network or PayPal
	553
	554	#### 3. Large Asset Purchases
	555	Why: One-time payments, fees don't matter at $100k+ scale
	556	Better: Regular Bitcoin (similar cost, simpler)
	557
	558	---
	559
	560	## The "Sweet Spot" Formula
	561
	562	```
	563	Perfect use case = ALL of these:
	564
	565	✅ Payment Frequency: 5-1000 times/year
	566	✅ Payment Amount: $10-$10,000
	567	✅ Relationship: Ongoing (not one-time)
	568	✅ Trust Level: Medium (not enemies, not necessarily best friends)
	569	✅ Technical Level: Both parties can run an app
	570	✅ Privacy Need: High
	571	✅ Speed Need: High
	572	```
	573
	574	### Examples Matching All Criteria:
	575
	576	- ✅ Roommates splitting bills (recurring, trust, privacy)
	577	- ✅ Freelancer + regular client (ongoing, speed, cost)
	578	- ✅ Family member supporting relatives (recurring, cross-border, privacy)
	579	- ✅ Gig worker + platform (high frequency, micropayments, instant)
	580	- ✅ Small business + supplier (B2B, recurring, settlement speed)
	581	- ✅ Content creator + subscriber (recurring, privacy, low fees)
	582
	583	### Examples NOT Matching:
	584
	585	- ❌ Buying coffee at random café (not recurring)
	586	- ❌ Paying grandma (not technical)
	587	- ❌ Buying house (one-time, need finality)
	588	- ❌ Corporate expense reporting (need audit trail)
	589
	590	---
	591
	592	## Bottom Line
	593
	594	### Works Perfectly For:
	595	Repeated payments between same parties who want privacy, speed, and low fees.
	596
	597	### Doesn't Work For:
	598	One-time payments, paying strangers, retail shopping, regulatory compliance, truly offline payments.
	599
	600	### Gray Area:
	601	Small business payments - depends on whether you have repeat customers or not.
	602
	603	### The Key Insight:
	604	Payment channels are like opening a tab at a bar:
	605	- ✅ Great if you're a regular
	606	- ❌ Wasteful if you visit once
	607
	608	If you make < 5 payments, channels aren't worth the opening/closing costs.
	609	If you make 100+ payments, channels save massive amounts of money and time.

pear-l2 commits / 90328ff

Changed files (7) +3503 -0