शुरुआत करें

1. पूरा नेटवर्क लोकल चलाएँ (लैब)

एक ही docker compose फ़ाइल एक बंद नेटवर्क चालू करती है। यह इंटरनेट से नहीं जुड़ता।

दो Nostr रिले
एक libp2p रिले
एक कस्टम signet पर bitcoind, और एक Esplora-संगत API
Safe और बाकी कॉन्ट्रैक्ट के साथ anvil (EVM)
चार नकली दुकानें और एक नकली कार्ड पेमेंट गेटवे
दो प्रॉक्सी शॉपर (shopper), तीन एस्क्रो (escrow; एक NAT के पीछे), दो ऑपरेटर (operator)
सार्वजनिक वेब ऐप और डेमो ऐप

ज़रूरतें: Docker (लगभग 8 GB मेमोरी)।

proxy-shopping-go और proxy-shopping-web को एक ही पैरेंट डायरेक्टरी में साथ-साथ रखें और चलाएँ:

git clone https://github.com/pad01g/proxy-shopping-go
git clone https://github.com/pad01g/proxy-shopping-web
cd proxy-shopping-go
docker compose up -d --build

फिर से शुरू करने के लिए पहले docker compose down -v चलाएँ ताकि नोड्स और रिले का सहेजा हुआ डेटा भी मिट जाए (हर स्टार्ट पर चेन शून्य से शुरू होती हैं, इसलिए बचा हुआ ऑर्डर डेटा उनसे मेल नहीं खाएगा)।

e2e टेस्ट चलाएँ

docker compose run --rm runner         # all scenarios (about 10 minutes)
docker compose run --rm runner a e     # pick some

नतीजे e2e/results/e2e-latest.md में जाते हैं। runner NAT के अंदर से (home नेटवर्क) काम करता है, इसलिए हर परिदृश्य मानता है कि उपयोगकर्ता NAT के पीछे है।

id	परिदृश्य
a	सामान्य सफल रास्ता: BTC (JPY वाली दुकान) और USDC (USD वाली दुकान)। कोटेशन का रेट जाँचा जाता है, एस्क्रो को अग्रिम शुल्क मिलता है, शॉपर को भुगतान मिलता है। बहुत अलग रेट वाले कोटेशन पर कड़ी चेतावनी मिलती है
b	डिलीवरी विफल होती है और उपयोगकर्ता विवाद खोलता है। ईमानदार एस्क्रो रिफ़ंड का फ़ैसला देता है और उपयोगकर्ता काउंटर-साइन करता है (BTC)। एस्क्रो पता डिक्रिप्ट कर सकता है और स्क्रीनशॉट अटैचमेंट के रूप में पाता है
c	एस्क्रो बेईमानी से फ़ैसला देता है। उपयोगकर्ता शिकायत करता है; ऑपरेटर उसे सूची से हटाता है और उनकी शर्तों के तहत उसका बॉन्ड मुआवज़े के रूप में ज़ब्त करता है (USDC)
d	कोऑर्डिनेटर (coordinator) किसी ऑपरेटर का डेलिगेशन रद्द करता है, और उस सूची की जोड़ियाँ ऑफ़र से गायब हो जाती हैं
e	NAT के पीछे का एक ब्राउज़र सार्वजनिक वेब ऐप से ऑर्डर करता है (1:1 मैसेज Nostr रिले से जाते हैं)। एक स्टेटस क्वेरी libp2p circuit relay के ज़रिए NAT के पीछे वाले एस्क्रो नोड तक पहुँचती है
f	शॉपर एक ऐसी दुकान को ठुकराता है जिसे वह जोखिम भरा मानता है, और अपने क्षेत्र के बाहर की एक सिर्फ़-नकद दुकान को भी। उस क्षेत्र का शॉपर नकद वाला ऑर्डर लेता है और डिलीवर करता है
g	T1 के बाद शॉपर अकेले फ़ंड ले सकता है (BTC)
h	अगर शॉपर गायब हो जाए, तो T2 के बाद उपयोगकर्ता अकेले फ़ंड वापस ले लेता है (USDC)
i	ईमानदार एस्क्रो के साथ USDC विवाद। फ़ैसले से पहले कोई Safe में थोड़ी रकम भेज दे, तब भी रिफ़ंड पूरा होता है
j	ऐसा ऑर्डर जिसे दुकान पूरा नहीं कर सकी (स्टॉक ख़त्म)। शॉपर आपसी सहमति वाला रिफ़ंड देता है; उपयोगकर्ता जाँचकर स्वीकार करता है
k	अगर शॉपर गायब हो जाए, तो T2 के बाद उपयोगकर्ता अकेले फ़ंड वापस ले लेता है (BTC)

डेमो में पूरा फ़्लो आज़माएँ

अपने ब्राउज़र में आज़माएँ: https://pad01g.github.io/proxy-shopping-web/ (सब कुछ पेज के अंदर सिम्युलेट होता है)।

लैब चलते हुए, डेमो http://localhost:8888/ पर खोलें (न hosts फ़ाइल की ज़रूरत, न सर्टिफ़िकेट की)। एक ही स्क्रीन पर उपयोगकर्ता, एस्क्रो, ऑपरेटर और कोऑर्डिनेटर की अपनी-अपनी कुंजी होती है (ब्राउज़र के लोकल स्टोरेज में), और शॉपर ख़ुद हमेशा ऑनलाइन रहने वाला Go नोड है। रास्ते असली हैं: Nostr रिले, bitcoind, anvil, Go नोड।

ऊपर एक परिदृश्य चुनें। बाईं ओर की गाइड बताती है कि आगे कौन क्या करेगा, और क्यों।
“इस चरण पर जाएँ” उस भूमिका के टैब पर ले जाता है और दबाने वाला बटन दिखाता है। फ़ॉर्म परिदृश्य के हिसाब से पहले से भरे होते हैं, इसलिए आपको बस क्लिक करके पुष्टि करनी है।
परिदृश्य: सामान्य सफल रास्ता (BTC / USDC), विफल डिलीवरी और रिफ़ंड, स्टॉक ख़त्म और आपसी रिफ़ंड, जोखिम भरी दुकान ठुकराई गई, बेईमान एस्क्रो की शिकायत और सूची से हटाना, और शॉपर के गायब होने पर T2 के बाद रिफ़ंड।
आप हर भूमिका के लिए अलग विंडो भी खोल सकते हैं, जैसे ?role=user और ?role=escrow,operator,coordinator (एक ही ब्राउज़र की विंडो कुंजियाँ और प्रगति साझा करती हैं)।
असल में हर भूमिका कहीं और, अपने ब्राउज़र में होती है। डेमो सिर्फ़ कुंजियों को अलग रखता है।
सिर्फ़ लैब के लिए: जो भी पोर्ट 8888 तक पहुँच सकता है वह faucet, माइनिंग, टाइम वॉर्प और शॉपर की admin API इस्तेमाल कर सकता है (यह सिर्फ़ 127.0.0.1 पर बाउंड है)।

एक e2e भी है जो डेमो की गाइड का पालन करते हुए उसे चलाता है: docker compose run --rm runner demo।

वेब ऐप इस्तेमाल करें

लैब के नाम (*.test) सिर्फ़ कंटेनरों के अंदर रिज़ॉल्व होते हैं। अपने ब्राउज़र से वेब ऐप इस्तेमाल करने के लिए:

edge कंटेनर का पोर्ट 443 लोकल रूप से खोलें (जैसे compose.override.yaml में: services: {edge: {ports: ["127.0.0.1:443:443"]}})। इससे सिर्फ़ लैब के लिए बने faucet.test और evm.test भी खुल जाते हैं (कोई भी बैलेंस बना सकता है और समय आगे बढ़ा सकता है), इसलिए इसे सिर्फ़ localhost पर खोलें।
अपनी hosts फ़ाइल में app.test और बाकी नामों को 127.0.0.1 पर पॉइंट करें।

सर्टिफ़िकेट self-signed हैं।

https://app.test/ खोलें और “नया बनाएँ” या “शब्दों से रिस्टोर करें” चुनें। कुंजी को एन्क्रिप्ट करने वाला पासफ़्रेज़ चुनें (8 या ज़्यादा अक्षर) (आप साफ़ तौर पर एन्क्रिप्ट न करना भी चुन सकते हैं, या NIP-07 एक्सटेंशन इस्तेमाल कर सकते हैं)। अगली बार पासफ़्रेज़ से कुंजी अनलॉक करें।
“ऑर्डर” में दुकान का URL (जैसे https://safe-shop.test/), दुकान का क्षेत्र (जैसे JP-13-13104) और सामान (जैसे A-100) दर्ज करें, और ऑफ़र खोजें।
एक शॉपर × एस्क्रो जोड़ी चुनें, डिलीवरी का पता डालें और ऑर्डर दें।
कोटेशन आने पर रेट का अंतर और मल्टीसिग पते की जाँच का नतीजा देखें, फिर स्वीकार करें।
लैब में “faucet से लें” से अपना वॉलेट भरें, फिर “मल्टीसिग फ़ंड करें” दबाएँ। पैसा हिलाने वाला हर काम (फ़ंडिंग, भुगतान, काउंटर-साइन) राशि और प्राप्तकर्ता दिखाने वाली स्क्रीन से होकर जाता है।
सामान पहुँचने पर शॉपर को भुगतान करने के लिए “मिल गया” दबाएँ। “पूरा हुआ” तभी दिखता है जब भुगतान चेन पर कन्फ़र्म हो जाए।

2. सार्वजनिक नेटवर्क पर चलाएँ

आर्किटेक्चर लैब जैसा ही है। अंतर:

ACME सर्टिफ़िकेट इस्तेमाल करें;
lab/keys की कुंजियाँ इस्तेमाल न करें;
असली signet और EVM चेन इस्तेमाल करें।

प्रॉक्सी शॉपर (shopper)

हमेशा ऑनलाइन; Go नोड और shopper-bot चलाता है।

role: shopper
name: my-shopper
network: ps-main
mnemonic_file: /keys/shopper.mnemonic
nostr: {relays: ["wss://relay.example"], k: 2}
trust: {coordinators: ["<coordinator public key>"]}
chain:
  btc: {network: signet, esplora: "https://mempool.space/signet/api"}
shopper:
  bot_url: "http://shopper-bot:7000"
  cash_regions: [JP-13]
  risk: {allowlist: [shop.example], known_gateways: [pay.example], threshold: 70}

कार्ड की जानकारी सिर्फ़ shopper-bot की कॉन्फ़िग फ़ाइल (BOT_CARDS_FILE) में जाती है; नोड को यह कभी नहीं मिलती।
हर दुकान के चरण shopper-bot के एक ड्राइवर के रूप में लिखे जाते हैं। AI से दुकानें चलाने वाले ड्राइवर का इनपुट और आउटपुट भी वही होता है (PurchaseRequest / PurchaseResult)।

एस्क्रो / ऑपरेटर / कोऑर्डिनेटर

इन्हें हमेशा ऑनलाइन रहने की ज़रूरत नहीं है।

ये वेब ऐप की “Escrow”, “Operator” और “Coordinator” स्क्रीन इस्तेमाल कर सकते हैं।
लगातार चलाने के लिए Go नोड को role: escrow / role: operator के साथ चलाएँ।
सिर्फ़ हस्ताक्षर के लिए psctl भी काम करता है।

वर्ज़न (v) डिफ़ॉल्ट रूप से UNIX समय होता है, इसलिए आम तौर पर इसे देने की ज़रूरत नहीं होती।

psctl keys --mnemonic-file coordinator.mnemonic
psctl delegate --network ps-main --mnemonic-file coordinator.mnemonic --operator <operator public key> --publish wss://relay.example
psctl list --network ps-main --mnemonic-file operator.mnemonic --file list.json --publish wss://relay.example

3. अपनी नेटवर्क भूमिका ख़ुद चलाएँ — कहीं भी, बिना अनुमति के

proxy-shopping का कोई केंद्रीय संचालक नहीं है और न ही कोई साइन-अप। भरोसे की कड़ी बस कुंजियाँ और हस्ताक्षरित Nostr इवेंट हैं, इसलिए आप (या आपके लिए काम करने वाला कोई AI एजेंट) अपने शहर में एक स्थानीय बाज़ार शुरू कर सकते हैं:

कोऑर्डिनेटर बनें: एक कुंजी बनाएँ (psctl keys --mnemonic-file coordinator.mnemonic)। कोऑर्डिनेटर बस इतना ही है।
किसी ऑपरेटर को डेलिगेट करें (अपनी दूसरी कुंजी को, या किसी भरोसेमंद व्यक्ति को): psctl delegate --network ps-main --mnemonic-file coordinator.mnemonic --operator <operator pk> --publish wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net
अपने क्षेत्र के शॉपर और एस्क्रो को सूची में डालें — ख़ुद को शॉपर के रूप में, किसी दोस्त को एस्क्रो के रूप में: psctl list --network ps-main --mnemonic-file operator.mnemonic --file list.json --publish …
लोगों से कहें कि वे आपकी कोऑर्डिनेटर कुंजी पर भरोसा करें (वेब ऐप की Settings में जोड़ें, या MCP सर्वर के लिए PS_COORDINATORS)। सबको दिखने के लिए रजिस्ट्री में coordinators/<name>.json जोड़ने वाला pull request खोलें; अपनी कम्युनिटी के लिए इसी तरह मंज़ूरियाँ चलाने के लिए रजिस्ट्री को fork करें।

इसे कहाँ चलाएँ: घर की एक मशीन काफ़ी है। नोड सिर्फ़ आउटबाउंड कनेक्शन बनाता है (Nostr रिले, और NAT के पीछे होने पर libp2p circuit relay), इसलिए कोई पोर्ट नहीं खोलना पड़ता। बाहर रहते हुए फ़ोन से नोड की admin API और वेब ऐप तक पहुँचने के लिए Tailscale या कोई भी VPN इस्तेमाल करें; एक छोटा VPS भी चलेगा।

AI एजेंट क्या कर सकता है: एजेंट ऑपरेटर और शॉपर का रोज़ का काम संभाल सकता है — नोड की admin API या MCP सर्वर से ऑर्डरों पर नज़र रखना, सूचियाँ अपडेट रखना, कार्ड वाली दुकानों के लिए shopper-bot चलाना, समस्याओं की रिपोर्ट करना — और आपकी अपनी स्थानीय जानकारी (कौन-सी दुकानें, कौन-से क्षेत्र, पैदल पहुँचने लायक सिर्फ़-नकद दुकानें) वह हिस्सा है जो कोई और नहीं दे सकता। स्किल proxy-shopper (npx skills add pad01g/proxy-shopping-go) एजेंट को यह सब क़दम-दर-क़दम समझाता है।

अपने उपयोगकर्ताओं के साथ ईमानदार रहें: सार्वजनिक नेटवर्क नया है और BTC signet (टेस्ट कॉइन) पर चलता है, इसलिए कमाई तभी होगी जब लोग इसे इस्तेमाल करने लगें।

योगदान

Pull request का स्वागत है — सभी रिपॉज़िटरी में: shopper-bot के लिए दुकान ड्राइवर, नए भुगतान तरीके और चेन, इस दस्तावेज़ के अनुवाद, प्रोटोकॉल की समीक्षा, बग फ़िक्स, और रजिस्ट्री में लिस्टिंग। GitHub पर issue या pull request खोलें।