From e01c906e56699b5875418642454dd1458b2f76bf Mon Sep 17 00:00:00 2001 From: defiQUG Date: Fri, 27 Mar 2026 22:12:46 -0700 Subject: [PATCH] docs(ops): submodule hygiene guide, verify script, rule/doc alignment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add docs/00-meta/SUBMODULE_HYGIENE.md (detached HEAD, remotes, JSON refs) - Add scripts/verify/submodules-clean.sh (labeled dirty-tree report) - AGENTS.md + CONTRIBUTOR_GUIDELINES + OPERATOR_READY_CHECKLIST + MASTER_INDEX - chain138-tokens-and-pmm: DODOPMMIntegration 0x5BDc62… per ADDRESS_MATRIX - Bump smom-dbis-138 + explorer-monorepo (config READMEs, explorer env loading) Made-with: Cursor --- .cursor/rules/chain138-tokens-and-pmm.mdc | 2 +- AGENTS.md | 6 ++ docs/00-meta/CONTRIBUTOR_GUIDELINES.md | 18 +++++- docs/00-meta/OPERATOR_READY_CHECKLIST.md | 2 + docs/00-meta/SUBMODULE_HYGIENE.md | 79 +++++++++++++++++++++++ docs/MASTER_INDEX.md | 4 +- explorer-monorepo | 2 +- scripts/verify/submodules-clean.sh | 31 +++++++++ smom-dbis-138 | 2 +- 9 files changed, 139 insertions(+), 7 deletions(-) create mode 100644 docs/00-meta/SUBMODULE_HYGIENE.md create mode 100755 scripts/verify/submodules-clean.sh diff --git a/.cursor/rules/chain138-tokens-and-pmm.mdc b/.cursor/rules/chain138-tokens-and-pmm.mdc index 7d6fa30..dd90942 100644 --- a/.cursor/rules/chain138-tokens-and-pmm.mdc +++ b/.cursor/rules/chain138-tokens-and-pmm.mdc @@ -10,7 +10,7 @@ alwaysApply: true - **cUSDT:** `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` (6 decimals) - **cUSDC:** `0xf22258f57794CC8E06237084b353Ab30fFfa640b` (6 decimals) -**DODOPMMIntegration:** `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` — on-chain verified 2026-03-04: `compliantUSDT()` / `compliantUSDC()` return the canonical addresses above. +**DODOPMMIntegration:** `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d` — reconciled with `docs/11-references/ADDRESS_MATRIX_AND_STATUS.md` (on-chain verification 2026-03-26); `compliantUSDT()` / `compliantUSDC()` return the canonical cUSDT/cUSDC above. **PMM pools (live funded public):** cUSDT/cUSDC `0xff8d3b8fDF7B112759F076B69f4271D4209C0849` | cUSDT/USDT `0x6fc60DEDc92a2047062294488539992710b99D71` | cUSDC/USDC `0x9f74Be42725f2Aa072a9E0CdCce0E7203C510263` — see `docs/11-references/ADDRESS_MATRIX_AND_STATUS.md` / `PMM_DEX_ROUTING_STATUS.md`. diff --git a/AGENTS.md b/AGENTS.md index 3fb7f13..729580f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,8 @@ Orchestration for Proxmox VE, Chain 138 (`smom-dbis-138/`), explorers, NPMplus, | Ops template + JSON | `docs/03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md`, `config/proxmox-operational-template.json` | | Live vs template (read-only SSH) | `bash scripts/verify/audit-proxmox-operational-template.sh` | | Config validation | `bash scripts/validation/validate-config-files.sh` | +| Submodule trees clean (CI / post-merge) | `bash scripts/verify/submodules-clean.sh` | +| Submodule + explorer remotes | `docs/00-meta/SUBMODULE_HYGIENE.md` | | smom-dbis-138 `.env` in bash scripts | Prefer `source smom-dbis-138/scripts/lib/deployment/dotenv.sh` + `load_deployment_env --repo-root "$PROJECT_ROOT"` (trims RPC URL line endings). From an interactive shell: `source smom-dbis-138/scripts/load-env.sh`. Proxmox root scripts: `source scripts/lib/load-project-env.sh` (also trims common RPC vars). | | Sankofa portal → CT 7801 (build + restart) | `./scripts/deployment/sync-sankofa-portal-7801.sh` (`--dry-run` first); sets `NEXTAUTH_URL` on CT via `sankofa-portal-ensure-nextauth-on-ct.sh` | | CCIP relay (r630-01 host) | Unit: `config/systemd/ccip-relay.service` → `/etc/systemd/system/ccip-relay.service`; `systemctl enable --now ccip-relay` | @@ -27,6 +29,10 @@ Orchestration for Proxmox VE, Chain 138 (`smom-dbis-138/`), explorers, NPMplus, | Operator (LAN + secrets) | `./scripts/run-all-operator-tasks-from-lan.sh` (use `--skip-backup` if `NPM_PASSWORD` unset) | | Cloudflare bulk DNS → `PUBLIC_IP` | `./scripts/update-all-dns-to-public-ip.sh` — use **`--dry-run`** and **`--zone-only=sankofa.nexus`** (or `d-bis.org` / `mim4u.org` / `defi-oracle.io`) to limit scope; see script header. Prefer scoped **`CLOUDFLARE_API_TOKEN`** (see `.env.master.example`). | +## Git submodules + +Most submodules are **pinned commits**; `git submodule update --init --recursive` often leaves **detached HEAD** — that is normal. To **change** a submodule: check out a branch inside it, commit, **push the submodule first**, then commit and push the **parent** submodule pointer. Do not embed credentials in `git remote` URLs; use SSH or a credential helper. Explorer Gitea vs GitHub and token cleanup: `docs/00-meta/SUBMODULE_HYGIENE.md`. + ## Rules of engagement - Review scripts before running; prefer `--dry-run` where supported. diff --git a/docs/00-meta/CONTRIBUTOR_GUIDELINES.md b/docs/00-meta/CONTRIBUTOR_GUIDELINES.md index 9396bfd..b72c1a3 100644 --- a/docs/00-meta/CONTRIBUTOR_GUIDELINES.md +++ b/docs/00-meta/CONTRIBUTOR_GUIDELINES.md @@ -1,7 +1,7 @@ # Contributor Guidelines -**Last Updated:** 2025-01-20 -**Document Version:** 1.0 +**Last Updated:** 2026-03-27 +**Document Version:** 1.1 **Status:** Active Documentation --- @@ -195,13 +195,25 @@ This document provides guidelines for contributing to the documentation, includi --- +## Git submodules (proxmox parent repo) + +This workspace vendors many repositories under `git submodule`. Guidelines: + +1. **Detached HEAD** after `git submodule update` is normal when you are not developing inside the submodule. +2. **To contribute code in a submodule:** `cd` into it, `git checkout main` (or the repo’s default branch), branch/commit as usual, **push that submodule’s remote**, then at the **parent** root run `git add ` and commit the updated submodule SHA, then push the parent. +3. **Never commit secrets** in submodule JSON “reference” files under `config/`; those snapshots are for public addresses only. See [SUBMODULE_HYGIENE.md](SUBMODULE_HYGIENE.md). +4. **Verify clean trees** before tagging or CI: `bash scripts/verify/submodules-clean.sh` from the parent root. + +--- + ## Related Documentation - **[DOCUMENTATION_STYLE_GUIDE.md](DOCUMENTATION_STYLE_GUIDE.md)** ⭐⭐⭐ - Style guide - **[MASTER_INDEX.md](../MASTER_INDEX.md)** ⭐⭐⭐ - Documentation index +- **[SUBMODULE_HYGIENE.md](SUBMODULE_HYGIENE.md)** — submodule workflow, explorer remotes, JSON config notes - **[DOCUMENTATION_CONSOLIDATION_PLAN.md](DOCUMENTATION_CONSOLIDATION_PLAN.md)** — consolidation scope; **[DOCUMENTATION_QUALITY_REVIEW.md](DOCUMENTATION_QUALITY_REVIEW.md)** — quality review --- -**Last Updated:** 2025-01-20 +**Last Updated:** 2026-03-27 **Review Cycle:** Quarterly diff --git a/docs/00-meta/OPERATOR_READY_CHECKLIST.md b/docs/00-meta/OPERATOR_READY_CHECKLIST.md index 9cfeb41..6c9c823 100644 --- a/docs/00-meta/OPERATOR_READY_CHECKLIST.md +++ b/docs/00-meta/OPERATOR_READY_CHECKLIST.md @@ -7,6 +7,8 @@ **From anywhere (no LAN):** `./scripts/run-completable-tasks-from-anywhere.sh` +**Submodule working trees (no local edits in submodules):** `bash scripts/verify/submodules-clean.sh` — see [SUBMODULE_HYGIENE.md](SUBMODULE_HYGIENE.md). + **Ensure this machine always has Proxmox SSH access:** `./scripts/security/ensure-proxmox-ssh-access.sh` (verifies key-based SSH to .10, .11, .12; use `--copy` to install key if missing). **NPMplus from this machine (if direct 192.168.11.167:81 unreachable):** `ssh -L 8181:192.168.11.167:81 -N root@192.168.11.11` then use `http://127.0.0.1:8181` for NPMplus API. **If deployer needs gas on currently active public chains:** Run `./scripts/deployment/deployer-gas-auto-route.sh` (optional: `--dry-run`, `--chain 138`). See [DEPLOYER_GAS_AUTO_ROUTE_RUNBOOK.md](../03-deployment/DEPLOYER_GAS_AUTO_ROUTE_RUNBOOK.md). **Current policy:** Wemix is deferred. diff --git a/docs/00-meta/SUBMODULE_HYGIENE.md b/docs/00-meta/SUBMODULE_HYGIENE.md new file mode 100644 index 0000000..a218a39 --- /dev/null +++ b/docs/00-meta/SUBMODULE_HYGIENE.md @@ -0,0 +1,79 @@ +# Submodule and explorer remote hygiene + +**Last Updated:** 2026-03-27 +**Purpose:** Operational notes for the many git submodules under the proxmox parent repo: detached HEAD, remotes, pushes, and non-secret JSON env snapshots. + +--- + +## Detached HEAD is normal + +The parent records each submodule at a **specific commit**. After `git submodule update --init --recursive`, many submodules show `HEAD (no branch)`. That is expected for **read-only** use. + +**If you develop inside a submodule:** check out a named branch first (for example `main` or `master`), commit, push that submodule’s remote, then in the **parent** repo commit the updated submodule pointer and push the parent. + +**Workflow (short):** + +1. `cd ` → `git checkout main` (or the project default) +2. Make changes → `git commit` → `git push ` +3. `cd ..` (parent root) → `git add ` → `git commit` → `git push` + +--- + +## Verify clean submodule trees + +From repo root: + +```bash +bash scripts/verify/submodules-clean.sh +``` + +Stricter than `git status -sb` (fails on any porcelain output). Use after large merges or before release tagging. + +--- + +## explorer-monorepo: Gitea vs GitHub + +- **Parent `.gitmodules` URL:** `https://github.com/Order-of-Hospitallers/chain-138-explorer.git` (canonical clone source for fresh submodules). +- **Day-to-day pushes** may go to **Gitea** (`gitea` remote → `https://gitea.d-bis.org/d-bis/explorer-monorepo.git`) when that is the integration remote. + +**Keep GitHub in sync** if your team pulls from GitHub only: after pushing to Gitea, push the same branch to `origin` on GitHub (or set up mirroring). If `git push origin master` returns **repository not found**, the GitHub repo may be private under another org/name, or may not exist yet — use **`gitea`** as the integration remote until GitHub access is fixed. + +**Do not store credentials in remote URLs.** Use SSH (`git@github.com:...`) or HTTPS with a credential helper. If you see a remote whose name or URL embeds a token, remove it and re-add a clean remote: + +```bash +cd explorer-monorepo +git remote -v +# git remote remove '' +git remote add origin https://github.com/Order-of-Hospitallers/chain-138-explorer.git +``` + +**Rotate** any token that was ever embedded in a saved URL. + +--- + +## gru-docs branch + +`gru-docs` may track **`docs-review-fixes`** (not `main`) while documentation review is open. The parent submodule pointer is intentional until upstream merges to `main` and the pointer is updated. + +--- + +## metamask-integration upstream + +This clone may show `main...gitea/main` when **Gitea** is the configured `origin` or tracking remote. Confirm with your team whether **GitHub** (see `.gitmodules`) or **Gitea** is canonical for pushes; align `branch..remote` if both exist. + +--- + +## JSON reference files (dotenv cleanup) + +In **`smom-dbis-138/config/`** and **`explorer-monorepo/config/`**, files such as `address-inventory*.json` and `runtime-env*.json` are **non-secret reference snapshots**. They are **not** a substitute for `.env` for secrets. When on-chain or deployment addresses change, update the canonical docs (`docs/11-references/ADDRESS_MATRIX_AND_STATUS.md`, etc.) and refresh these JSON files if you rely on them for scripts. + +See each submodule’s `config/README.md` for a short in-tree note. + +--- + +## Related + +- **[AGENTS.md](../../AGENTS.md)** — quick pointers including submodule discipline +- **[CONTRIBUTOR_GUIDELINES.md](CONTRIBUTOR_GUIDELINES.md)** — submodule section for contributors +- **[ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md)** — contract address source of truth +- **`.cursor/rules/chain138-tokens-and-pmm.mdc`** — agent overlay; must stay aligned with the address matrix diff --git a/docs/MASTER_INDEX.md b/docs/MASTER_INDEX.md index cecdba3..eae0d74 100644 --- a/docs/MASTER_INDEX.md +++ b/docs/MASTER_INDEX.md @@ -1,6 +1,6 @@ # Documentation — Master Index -**Last Updated:** 2026-03-25 +**Last Updated:** 2026-03-27 **Purpose:** Single entry point for all project documentation. Use this index to find canonical sources and avoid deprecated or duplicate content. **Status:** Preflight and Chain 138 next steps completed (59/59 on-chain per [check-contracts-on-chain-138.sh](../../scripts/verify/check-contracts-on-chain-138.sh), 12 c* GRU-registered). **2026-03-06:** Contract check list expanded to 59 addresses (PMM, vault/reserve, CompliantFiatTokens); doc refs updated. **2026-03-04:** Celo CCIP bridges deployed; Phase A–D tracked in [03-deployment/REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md](03-deployment/REMAINING_DEPLOYMENTS_FOR_FULL_NETWORK_COVERAGE.md). Phase C: [PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md](03-deployment/PHASE_C_CW_AND_EDGE_POOLS_RUNBOOK.md); Phase D: [PHASE_D_OPTIONAL_CHECKLIST.md](03-deployment/PHASE_D_OPTIONAL_CHECKLIST.md). **On-chain verification:** DODOPMMIntegration canonical cUSDT/cUSDC — [EXPLORER_TOKEN_LIST_CROSSCHECK](11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md) §8. **Remaining:** Wemix 0.4 WEMIX, LINK fund, cW* + edge pools — see [00-meta/TODOS_CONSOLIDATED.md](00-meta/TODOS_CONSOLIDATED.md). @@ -14,6 +14,7 @@ | Purpose | Document | |--------|----------| | **Agent / IDE instructions** | [AGENTS.md](../AGENTS.md) (repo root) | +| **Git submodule hygiene + explorer remotes** | [00-meta/SUBMODULE_HYGIENE.md](00-meta/SUBMODULE_HYGIENE.md) — detached HEAD, push order, Gitea/GitHub, `submodules-clean.sh` | | **What to do next** | [00-meta/NEXT_STEPS_INDEX.md](00-meta/NEXT_STEPS_INDEX.md) — ordered actions, by audience, execution plan | | **Your personal checklist** | [00-meta/NEXT_STEPS_FOR_YOU.md](00-meta/NEXT_STEPS_FOR_YOU.md) | | **Operator runbook (LAN/creds)** | [00-meta/NEXT_STEPS_OPERATOR.md](00-meta/NEXT_STEPS_OPERATOR.md) | @@ -60,6 +61,7 @@ | **03-deployment** | [03-deployment/OPERATIONAL_RUNBOOKS.md](03-deployment/OPERATIONAL_RUNBOOKS.md), [03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md](03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md), **Public sector live checklist:** [03-deployment/PUBLIC_SECTOR_LIVE_DEPLOYMENT_CHECKLIST.md](03-deployment/PUBLIC_SECTOR_LIVE_DEPLOYMENT_CHECKLIST.md), **Proxmox VE ops template:** [03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md](03-deployment/PROXMOX_VE_OPERATIONAL_DEPLOYMENT_TEMPLATE.md) · [`config/proxmox-operational-template.json`](config/proxmox-operational-template.json) | | **04-configuration** | [04-configuration/README.md](04-configuration/README.md), [04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md](04-configuration/ADDITIONAL_PATHS_AND_EXTENSIONS.md) (paths, registry, token-mapping, LiFi/Jumper); **OMNL Indonesia / HYBX-BATCH-001:** [04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md](04-configuration/mifos-omnl-central-bank/HYBX_BATCH_001_OPERATOR_CHECKLIST.md), [04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md](04-configuration/mifos-omnl-central-bank/INDONESIA_PACKAGE_4_995_EVIDENCE_STANDARD.md) | | **06-besu** | [06-besu/MASTER_INDEX.md](06-besu/MASTER_INDEX.md) | +| **Testnet (2138)** | [testnet/DEFI_ORACLE_META_TESTNET_2138_RUNBOOK.md](testnet/DEFI_ORACLE_META_TESTNET_2138_RUNBOOK.md), [testnet/TESTNET_DEPLOYMENT.md](testnet/TESTNET_DEPLOYMENT.md) | | **07-ccip** | [07-ccip/](07-ccip/), [00-meta/CW_BRIDGE_TASK_LIST.md](00-meta/CW_BRIDGE_TASK_LIST.md) | | **11-references** | [11-references/ADDRESS_MATRIX_AND_STATUS.md](11-references/ADDRESS_MATRIX_AND_STATUS.md), [11-references/CONTRACT_ADDRESSES_REFERENCE.md](11-references/CONTRACT_ADDRESSES_REFERENCE.md), [11-references/DEPLOYER_CONTRACTS_INVENTORY_AND_VERIFICATION_STATUS.md](11-references/DEPLOYER_CONTRACTS_INVENTORY_AND_VERIFICATION_STATUS.md) (all contracts by deployer wallet, network, verified/not), [11-references/DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md](11-references/DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md) (tokens, bridges, DODO/Uniswap LPs, full route map), [11-references/DEPLOYER_TO_PUBLIC_STABLECOIN_ROUTES.md](11-references/DEPLOYER_TO_PUBLIC_STABLECOIN_ROUTES.md) (deployer→public stablecoin routes), [11-references/ROUTES_NO_PREFUNDED_BRIDGE_REQUIRED.md](11-references/ROUTES_NO_PREFUNDED_BRIDGE_REQUIRED.md) (routes where bridge pre-fund not required), [11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md](11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md) (per-chain per-token: mint vs receive+forward vs release), [11-references/DEPLOYMENT_DATA_SOURCES_INDEX.md](11-references/DEPLOYMENT_DATA_SOURCES_INDEX.md) (dotenv and config files with contract deployments), [11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md](11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md) (Explorer /tokens vs repo token lists), [11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md](11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md) (Complete Credential / eIDAS connector repo authority + manifest), [11-references/HARDWARE_INVENTORY_MASTER.md](11-references/HARDWARE_INVENTORY_MASTER.md), [11-references/13_NODE_NETWORK_AND_CABLING_CHECKLIST.md](11-references/13_NODE_NETWORK_AND_CABLING_CHECKLIST.md), [11-references/13_NODE_AND_ASSETS_BRING_ONLINE_CHECKLIST.md](11-references/13_NODE_AND_ASSETS_BRING_ONLINE_CHECKLIST.md) | | **Hardware / 13-node** | [11-references/HARDWARE_INVENTORY_MASTER.md](11-references/HARDWARE_INVENTORY_MASTER.md) (R630×13, R750×3, 7920×2, UDM Pro×2, XG×2), [02-architecture/R630_13_NODE_DOD_HA_MASTER_PLAN.md](02-architecture/R630_13_NODE_DOD_HA_MASTER_PLAN.md), [11-references/13_NODE_NETWORK_AND_CABLING_CHECKLIST.md](11-references/13_NODE_NETWORK_AND_CABLING_CHECKLIST.md), [11-references/13_NODE_AND_ASSETS_BRING_ONLINE_CHECKLIST.md](11-references/13_NODE_AND_ASSETS_BRING_ONLINE_CHECKLIST.md) | diff --git a/explorer-monorepo b/explorer-monorepo index 3158c5c..d0f6044 160000 --- a/explorer-monorepo +++ b/explorer-monorepo @@ -1 +1 @@ -Subproject commit 3158c5cd36677129e623e87fd6715642c45df6b8 +Subproject commit d0f6044b9bd87801273cb56213a280712ae9177d diff --git a/scripts/verify/submodules-clean.sh b/scripts/verify/submodules-clean.sh new file mode 100755 index 0000000..8c283b7 --- /dev/null +++ b/scripts/verify/submodules-clean.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +# Exit 0 if every submodule has a clean working tree (no modified/untracked files). +# Use in CI or after merges: bash scripts/verify/submodules-clean.sh +set -euo pipefail +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +cd "$ROOT" + +tmp="$(mktemp)" +trap 'rm -f "$tmp"' EXIT + +dirty=0 +while IFS= read -r subpath; do + [[ -z "$subpath" ]] && continue + if ! git -C "$ROOT/$subpath" rev-parse --git-dir >/dev/null 2>&1; then + continue + fi + out="$(git -C "$ROOT/$subpath" status --porcelain 2>/dev/null || true)" + if [[ -n "$out" ]]; then + dirty=1 + printf '%s\n' "=== $subpath ===" >>"$tmp" + printf '%s\n' "$out" >>"$tmp" + fi +done < <(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' | awk '{print $2}' | sort -u) + +if (( dirty )); then + echo "submodules-clean: dirty submodule working trees:" >&2 + cat "$tmp" >&2 + exit 1 +fi + +echo "submodules-clean: OK (all submodules clean)" diff --git a/smom-dbis-138 b/smom-dbis-138 index 06569b5..c78a9a6 160000 --- a/smom-dbis-138 +++ b/smom-dbis-138 @@ -1 +1 @@ -Subproject commit 06569b5ed73cce3ef960767cdcb66ca5a71988c3 +Subproject commit c78a9a61f803ba76254a7f7628e8f46660f9a983