merge(main): reconcile remote main into x402 verification branch

docs/04-configuration/Z_ECOSYSTEM.md

@@ -0,0 +1,157 @@
+# Z Ecosystem — Z Chain, International Z Wallet, Z Bot
+
+Consumer-facing Z products on OMNL expansion slot **900002**.
+
+## Components
+
+| Product | Route | Config |
+|---------|-------|--------|
+| Z Ecosystem hub | `/z` | `config/z-ecosystem.v1.json` |
+| International Z Wallet | `/z-wallet` | `config/z-chain-integration.v1.json` |
+| Z Bot (in-app chat) | `/z-wallet#z-bot` | `POST /api/v1/z-bot/chat` |
+| Z Online Bank | `/central-bank` | existing z-bank settlement |
+
+## Local Z Chain bootstrap
+
+```bash
+# Start Besu (chainId 900002) on port 8546
+bash scripts/deployment/bootstrap-z-chain-local.sh
+
+# Env
+export CHAIN_900002_RPC_URL=http://127.0.0.1:8546
+export VITE_RPC_URL_900002=http://127.0.0.1:8546
+
+# Deploy contracts (optional)
+export PRIVATE_KEY=0x...
+bash scripts/deployment/deploy-z-chain-contracts.sh
+```
+
+Windows:
+
+```powershell
+.\scripts\deployment\bootstrap-z-chain-local.ps1
+```
+
+Verify: `cast chain-id --rpc-url http://127.0.0.1:8546` → `900002` (hex `0xdbba2`)
+
+### One-command complete setup (Windows)
+
+```powershell
+npm install --legacy-peer-deps
+.\scripts\deployment\complete-z-chain.ps1
+```
+
+Uses Hardhat node when Docker is unavailable. Keeps node running in background (`logs/z-chain-node.pid`).
+
+
+## Frontend env
+
+```env
+VITE_ENABLE_Z_WALLET=true
+VITE_RPC_URL_900002=http://127.0.0.1:8546
+VITE_Z_CHAIN_EXPLORER_URL=https://explorer.z.omdnl.org
+VITE_THIRDWEB_CLIENT_ID=...
+```
+
+## API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/z-wallet/corridors` | International corridor catalog |
+| GET | `/api/v1/z-wallet/status/:ref` | Settlement status proxy |
+| GET | `/api/v1/z-bot/health` | Z Bot + Azure OpenAI config status |
+| POST | `/api/v1/z-bot/chat` | Z Bot assistant |
+
+Z Bot body:
+
+```json
+{
+  "sessionId": "zbot-...",
+  "message": "What is my balance?",
+  "walletAddress": "0x...",
+  "chainId": 900002
+}
+```
+
+## Z Bot LLM (optional)
+
+Set Azure OpenAI for live replies; otherwise rule-based fallback:
+
+```env
+AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com
+AZURE_OPENAI_API_KEY=...
+AZURE_OPENAI_DEPLOYMENT=gpt-4o-mini
+AZURE_OPENAI_API_VERSION=2024-02-15-preview
+```
+
+## International corridors
+
+Defined in `config/z-chain-integration.v1.json`:
+
+- Iraq (USD) — SWIFT, HYBX, CHAIN_MINT
+- Iran (USD) — HYBX, CHAIN_MINT
+- Europe (EUR) — SWIFT, HYBX
+- Global (USD) — SWIFT, HYBX, CHAIN_MINT
+
+Transfers submit to `POST /z-bank/settle-m0-m4` (or `/external-transfer` fallback) with `targetChainId: 900002`.
+
+## Registry
+
+`config/omnl-supported-chains.v1.json` slot **900002** — `name: Z Chain`, `status: active`, `omnlRole: z-chain`.
+
+## Production Besu (LXC / VM)
+
+On the Z Chain host (see `config/z-chain-production.v1.json`):
+
+```bash
+sudo bash scripts/deployment/bootstrap-z-chain-production.sh
+```
+
+Wire nginx/Cloudflare:
+
+- `https://zblockchainsystem.com` → portal (`/z`, `/z-wallet`, `/swap`, `/central-bank`)
+- `https://rpc.zblockchainsystem.com` → `127.0.0.1:8546`
+- `https://explorer.zblockchainsystem.com` → Blockscout (optional)
+
+Set on Z portal host:
+
+```env
+CHAIN_900002_RPC_URL=https://rpc.zblockchainsystem.com
+VITE_RPC_URL_900002=https://rpc.zblockchainsystem.com
+VITE_Z_CHAIN_EXPLORER_URL=https://explorer.zblockchainsystem.com
+VITE_Z_ECOSYSTEM_URL=https://zblockchainsystem.com
+```
+
+Deploy:
+
+```bash
+bash scripts/deployment/deploy-z-ecosystem-production.sh
+bash scripts/deployment/print-z-dns-records.sh
+```
+
+## Local dev without Docker
+
+If Docker Desktop is not running, use Anvil:
+
+```powershell
+.\scripts\deployment\bootstrap-z-chain-anvil.ps1
+```
+
+Default Anvil account #0 key: `0xac0974bec39a17e36ba4a590bcafb95bd05417ff81f81088a92f31fcfcf35588`
+
+```bash
+export PRIVATE_KEY=0xac0974bec39a17e36ba4a590bcafb95bd05417ff81f81088a92f31fcfcf35588
+bash scripts/deployment/deploy-z-chain-contracts.sh
+node scripts/deployment/sync-z-chain-deployed-addresses.mjs
+```
+
+## Contract addresses
+
+After deploy, sync all configs:
+
+```bash
+node scripts/deployment/sync-z-chain-deployed-addresses.mjs
+```
+
+Updates `z-chain-deployed.v1.json`, `z-chain-integration.v1.json`, and `hybx-omnl-cross-chain-lines.json`.
+

docs/deployment/DEPLOYMENT_ISSUES_AND_FIXES.md

@@ -143,7 +143,6 @@ forge script script/DeployTransactionMirror.s.sol \
 3. **RPC Providers**:
    - Alchemy: https://www.alchemy.com/
    - Infura: https://www.infura.io/
-   - QuickNode: https://www.quicknode.com/
 4. **Verification**: Contracts will be automatically verified on Etherscan if `ETHERSCAN_API_KEY` is set
 
 ---

docs/deployment/INFURA_RPC_ISSUE.md

@@ -46,9 +46,6 @@ Switch to Alchemy or another provider:
 # Alchemy
 ETHEREUM_MAINNET_RPC=https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_API_KEY
 
-# QuickNode
-ETHEREUM_MAINNET_RPC=https://your-endpoint.quiknode.pro/YOUR_API_KEY
-
 # Public RPC (not recommended for production)
 ETHEREUM_MAINNET_RPC=https://eth.llamarpc.com
 ```

docs/deployment/INFURA_SETTINGS_FIX.md

@@ -62,11 +62,6 @@ Update `.env` line 18 with alternative provider:
 ETHEREUM_MAINNET_RPC=https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_API_KEY
 ```
 
-**QuickNode**:
-```bash
-ETHEREUM_MAINNET_RPC=https://your-endpoint.quiknode.pro/YOUR_API_KEY
-```
-
 **Public RPC** (not recommended for production):
 ```bash
 ETHEREUM_MAINNET_RPC=https://eth.llamarpc.com