pezkuwi-wallet-utils/ARCHITECTURE.md

Pezkuwi Wallet Utils - Architecture

Nova Base + Pezkuwi Overlay

This repository uses a layered architecture that automatically syncs with Nova Wallet's chain configurations while maintaining Pezkuwi-specific customizations.

┌─────────────────────────────────────────────────────────┐
│                  pezkuwi-wallet-utils                    │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  nova-base/              (Git Submodule - AUTO SYNC)    │
│  ├── chains/v22/chains.json   → 98+ Polkadot chains     │
│  ├── icons/                   → Chain icons             │
│  └── ...                      → Other Nova configs      │
│                                                          │
│  pezkuwi-overlay/        (Manual - Pezkuwi Team)        │
│  ├── chains/pezkuwi-chains.json  → 3 Pezkuwi chains     │
│  ├── icons/                       → Pezkuwi icons       │
│  ├── types/                       → Custom type defs    │
│  └── config/                      → Overrides           │
│                                                          │
│  chains/v22/chains.json  (Generated - DO NOT EDIT)      │
│  └── Merged: Pezkuwi (first) + Nova chains              │
│                                                          │
└─────────────────────────────────────────────────────────┘

Directory Structure

pezkuwi-wallet-utils/
├── nova-base/                 # Git submodule (READ-ONLY)
│   └── chains/v22/chains.json # Nova's official chain configs
│
├── pezkuwi-overlay/           # Pezkuwi-specific configs
│   ├── chains/
│   │   └── pezkuwi-chains.json  # Pezkuwi, Asset Hub, People
│   ├── icons/                   # Pezkuwi chain/token icons
│   ├── types/                   # pezsp_* type definitions
│   └── config/                  # API overrides, settings
│
├── chains/                    # GENERATED (merged output)
│   ├── v22/chains.json        # Combined chains
│   └── chains.json            # Root copy for compatibility
│
├── scripts/
│   ├── merge-chains.py        # Merge script
│   └── update-all.sh          # Full update script
│
└── icons/, global/, etc.      # Other wallet configs

How It Works

1. Nova Base (Automatic)

• Nova's nova-utils repo is added as a git submodule
• Contains all Polkadot ecosystem chains (DOT, KSM, Acala, Moonbeam, etc.)
• Updates pulled automatically with git submodule update --remote

2. Pezkuwi Overlay (Manual)

• Contains ONLY Pezkuwi-specific configurations
• Managed by Pezkuwi team
• Files here override or extend Nova configs

3. Merge Process

• scripts/merge-chains.py combines both sources
• Pezkuwi chains are placed FIRST (appear at top of wallet)
• Nova chains follow after
• Output goes to chains/v22/chains.json

Usage

Update Everything (Recommended)

./scripts/update-all.sh

This will:

1. Pull latest Nova changes
2. Re-merge chain configs
3. Show summary

Manual Merge

python3 scripts/merge-chains.py --version v22

Update Nova Only

git submodule update --remote nova-base

Adding/Modifying Pezkuwi Chains

Edit pezkuwi-overlay/chains/pezkuwi-chains.json:

[
  {
    "chainId": "bb4a61ab...",
    "name": "Pezkuwi",
    "nodes": [...],
    "assets": [...]
  }
]

Then run the merge script.

Benefits

Aspect	Before	After
Chain maintenance	Manual (102 chains)	Auto (3 chains)
Nova updates	Manual copy-paste	git submodule update
Security patches	Manual tracking	Automatic
Pezkuwi focus	Diluted	Clear separation

Important Notes

1. Never edit chains/v22/chains.json directly - it's auto-generated
2. Pezkuwi changes go in pezkuwi-overlay/
3. Run merge after any changes
4. Commit submodule updates to track Nova version

CI/CD Integration

Add to your build pipeline:

- name: Update Nova & Merge
  run: |
    git submodule update --init --remote
    python3 scripts/merge-chains.py --version v22