SKILL.md — MCW Setup & Operations Guide

Полное руководство по локальной разработке, конфигурации и деплою MultiCurrencyWallet.

Quick Start (Local Dev)

# 1. Установить зависимости
npm install

# 2. Запустить dev-сервер (testnet, localhost:9001)
npm run dev

# 3. Открыть браузер
open http://localhost:9001

Dev-сервер использует testnet конфиг. MetaMask нужно переключить на Sepolia/BSC Testnet.

Config System

Конфиги выбираются через CONFIG env variable при сборке.

src/front/config/
├── mainnet/          # Production config
│   ├── evmNetworks.js  — chainId, networkVersion, chainName для каждой EVM-сети
│   ├── web3.js         — RPC endpoint URLs
│   ├── api.js          — Explorer API keys, WalletConnect Project ID, Infura key
│   └── link.js         — Block explorer URLs для отображения
└── testnet/          # Testnet config (same structure)

Добавить новую EVM chain:

1. mainnet/web3.js — добавь newchain_provider: 'https://rpc.newchain.io'
2. mainnet/evmNetworks.js — добавь объект с currency, chainId, networkVersion, chainName, rpcUrls, blockExplorerUrls
3. mainnet/link.js — добавь explorer URL
4. mainnet/api.js — добавь newchainscan URL и newchain_ApiKey
5. Повтори для testnet/
6. Проверь RPC: curl -X POST <rpcUrl> -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Текущие активные chains (mainnet): ETH, BNB, MATIC, ARBETH, AURETH, XDAI, AVAX, MOVR, ONE, AME

API Keys & Secrets

Все ключи зашиты в конфиге и попадают в бандл — это нормально для open-source crypto wallet.

GitHub Actions secret: buildbot — SSH ключ для деплоя в swaponline.github.io репозиторий.

Build Commands

npm run dev               # Dev server: testnet, localhost:9001 (hot reload)
npm run build:mainnet     # Production build (mainnet config, NODE_ENV=production)
npm run build:testnet     # Testnet build (for WordPress plugin testnet widget)
npm run build:wordpress   # WordPress plugin ZIP (mainnet + testnet widgets)

Webpack конфиг: webpack/webpack.config.js (common + dev/prod overlays). Важно: webpack/rules/jsx.js должен использовать babel-loader (НЕ esbuild-loader — ломает react-css-modules).

Testing

# Unit tests (Jest, jsdom environment)
npm run test:unit
npx jest tests/unit/walletConnect.test.ts   # 39 тестов WalletConnectProviderV2
npx jest tests/unit/appsCatalog.test.ts     # Тесты каталога dApps

# E2E smoke tests (требует запущенного dev-сервера на :9001)
npm run dev &
npm run test:e2e_apps_smoke                 # 9 Puppeteer тестов Apps

E2E тесты медленные (~66 сек): Puppeteer запускает Chromium, 9 тестов последовательно, каждый ждёт React init.

Deployment

Автоматический деплой: push в master → GitHub Actions → build mainnet → push в swaponline.github.io.

Ручная проверка после деплоя:

curl -sf https://swaponline.github.io | grep -c "root" && echo "✅ site up" || echo "❌ site down"

GitHub Actions workflows:

Rollback:

git revert HEAD && git push   # Или: git reset --hard HEAD~1 && git push --force

Wallet Connection Stack

MCW использует Reown AppKit + Wagmi v2 + Viem для подключения внешних кошельков.

@reown/appkit          — UI модал (MetaMask, WalletConnect, injected wallets)
@reown/appkit-adapter-wagmi — мост AppKit ↔ wagmi
wagmi v2 + viem        — EVM wallet state hooks, type-safe RPC
web3 v1.10             — atomic swap механика (отдельно от wallet connection)

Инициализация AppKit: src/front/shared/lib/appkit.ts Хелпер для подключения: src/front/shared/helpers/metamask.ts Header chip: src/front/shared/components/Header/WalletChip/index.tsx

dApp Bridge (walletBridge)

Wallet может работать как EIP-1193 провайдер для внешних dApps через iframe + postMessage.

src/front/shared/pages/Apps/
├── appsCatalog.ts      — каталог dApps (URL, название, иконка, walletBridge: 'eip1193')
├── walletBridge.ts     — EIP-1193 bridge (postMessage с iframe)
└── images/             — PNG иконки для карточек dApps

Добавить новый dApp:

1. appsCatalog.ts — добавить объект в APPS массив
2. EXTERNAL_ALLOWED_HOSTS — добавить hostname
3. tests/e2e/appsSmoke.test.js — добавить в APPS массив (ручная синхронизация!)
4. Добавить images/{app-id}.png
5. Убедиться что dApp поддерживает bridge client (wallet-bridge-init.js в head)

Atomic Swap Architecture

src/core/
├── swap.app/    — центральный синглтон, соединяет все сервисы
├── swap.auth/   — деривация ключей (BIP44) для каждого блокчейна
├── swap.room/   — libp2p pubsub (P2P order book)
├── swap.orders/ — управление ордерами
├── swap.swaps/  — blockchain-specific swap instances
└── swap.flows/  — HTLC протоколы (BTC↔ETH и другие пары)

P2P signaling сервер: star.wpmix.net (WebRTC STAR transport).

WordPress Plugin

MCW можно встраивать в WordPress как виджет:

npm run build:wordpress   # Создаёт dist/wordpress-plugin/*.zip

Deploy: GitHub Actions deploy.yml пушит ZIP в farm.wpmix.net/updates/ и обновляет mcw-info.json. Плагин доступен на: https://farm.wpmix.net

Pre-push Hook

.git/hooks/pre-push выполняет перед каждым push:

1. TypeScript compile check (tsc --noEmit)
2. ESLint на изменённых .ts/.tsx файлах (no-unused-vars, no-debugger, eqeqeq)
3. Prettier --check на изменённых файлах

При ошибке: npx prettier --write <file> для авто-форматирования.

Key File Locations

Обновлено: 2026-03-04