1. Запустить всю сеть локально (лаборатория)

Один файл docker compose поднимает замкнутую сеть. К интернету она не подключается.

  • два Nostr-реле
  • libp2p-реле
  • bitcoind на собственном signet и Esplora-совместимый API
  • anvil (EVM) с Safe и остальными контрактами
  • четыре фейковых магазина и фейковый платёжный шлюз для карт
  • два покупателя-посредника (shopper), три гаранта (escrow; один за NAT), два оператора (operator)
  • публичное веб-приложение и демо-приложение

Требования: Docker (около 8 ГБ памяти).

Положите 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 Координатор отзывает делегирование оператора, и сочетания из этого списка исчезают из предложений
e Браузер за NAT делает заказ через публичное веб-приложение (личные сообщения идут через Nostr-реле). Запрос статуса доходит до узла гаранта за NAT через libp2p circuit relay
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, ни сертификаты не нужны). На одном экране у пользователя, гаранта, оператора и координатора (coordinator) свои ключи (в локальном хранилище браузера), а покупатель-посредник — это сам всегда работающий 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) разрешаются только внутри контейнеров. Чтобы пользоваться веб-приложением из своего браузера:

  • Откройте локально порт 443 контейнера edge (например, в compose.override.yaml: services: {edge: {ports: ["127.0.0.1:443:443"]}}). При этом открываются и служебные для лаборатории faucet.test и evm.test (любой может начислять балансы и перематывать время), поэтому открывайте их только на localhost.
  • Направьте app.test и остальные имена на 127.0.0.1 в файле hosts.

Сертификаты самоподписанные.

  1. Откройте https://app.test/ и выберите «создать новый» или «восстановить по словам». Выберите парольную фразу (не короче 8 символов), которой шифруется ключ (можно также явно отказаться от шифрования или использовать расширение NIP-07). В следующий раз разблокируйте ключ парольной фразой.
  2. В разделе «заказ» введите URL магазина (например, https://safe-shop.test/), регион магазина (например, JP-13-13104) и товар (например, A-100) и найдите предложения.
  3. Выберите сочетание «покупатель-посредник × гарант», введите адрес доставки и оформите заказ.
  4. Когда придёт предложение цены, проверьте разницу курсов и результат проверки адреса мультиподписи, затем примите его.
  5. В лаборатории пополните кошелёк кнопкой «получить из крана», затем нажмите «пополнить мультиподпись». Каждое действие, которое двигает деньги (пополнение, оплата, встречная подпись), проходит через экран с суммой и получателем.
  6. Когда товар придёт, нажмите «получено», чтобы заплатить покупателю-посреднику. «Завершено» появляется только после того, как платёж подтверждён в блокчейне.

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. Драйвер, который управляет магазинами с помощью ИИ, имеет те же вход и выход (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, поэтому вы (или ИИ-агент, работающий на вас) можете открыть местный рынок в своём городе:

  1. Станьте координатором: создайте ключ (psctl keys --mnemonic-file coordinator.mnemonic). Это всё, что такое координатор.
  2. Делегируйте оператору (своему второму ключу или тому, кому доверяете): psctl delegate --network ps-main --mnemonic-file coordinator.mnemonic --operator <operator pk> --publish wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net
  3. Внесите в список покупателей-посредников и гарантов для своего региона — себя как покупателя-посредника, друга как гаранта: psctl list --network ps-main --mnemonic-file operator.mnemonic --file list.json --publish …
  4. Попросите людей доверять ключу вашего координатора (добавить его в настройках веб-приложения или в PS_COORDINATORS для MCP-сервера). Чтобы вас нашли все, откройте pull request в реестр, добавив coordinators/<name>.json; чтобы так же вести одобрения для своего сообщества, сделайте форк реестра.

Где запускать: достаточно домашнего компьютера. Узел устанавливает только исходящие соединения (Nostr-реле и libp2p circuit relay, когда он за NAT), поэтому открывать порты не нужно. Используйте Tailscale или любой VPN, чтобы с телефона вне дома достучаться до admin API узла и веб-приложения; подойдёт и небольшой VPS.

Что может ИИ-агент: агент может выполнять рутину оператора и покупателя-посредника — следить за заказами через admin API узла или MCP-сервер, поддерживать списки в актуальном состоянии, управлять shopper-bot для магазинов с оплатой картой, сообщать о проблемах, — а ваше знание места (какие магазины, какие регионы, до каких магазинов только за наличные можно дойти пешком) — это то, что никто другой предложить не может. Навык proxy-shopper (npx skills add pad01g/proxy-shopping-go) проводит агента через всё это.

Будьте честны со своими пользователями: публичная сеть новая и работает на BTC signet (тестовые монеты), так что заработок появится, когда ею начнут пользоваться.

Участие в проекте

Pull request’ы приветствуются — во всех репозиториях: драйверы магазинов для shopper-bot, новые способы оплаты и блокчейны, переводы этой документации, ревью протокола, исправления ошибок и записи в реестре. Откройте issue или pull request на GitHub.