# 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`.