d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: FQDN matrix, public-sector baseline, Chain138 runbooks, eIDAS repo reference
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details

Browse Source 
Made-with: Cursor
This commit is contained in:
defiQUG
2026-03-27 18:46:56 -07:00
parent bad8fdc98c
commit 790e489538
7 changed files with 1254 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
docs/02-architecture/PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md Normal file
View File

@@ -0,0 +1,95 @@
# Public sector tenancy, service catalog, and deployment baseline
**Last Updated:** 2026-03-25
**Status:** Canonical baseline (reconciles assurance, Phoenix intent, and repo boundaries)
**Related:** [NON_GOALS.md](NON_GOALS.md), [EXPECTED_WEB_CONTENT.md](EXPECTED_WEB_CONTENT.md), [SERVICE_DESCRIPTIONS.md](SERVICE_DESCRIPTIONS.md), [BRAND_RELATIONSHIP.md](BRAND_RELATIONSHIP.md), [../11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md](../11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md), [config/public-sector-program-manifest.json](../../config/public-sector-program-manifest.json)
---
## Purpose
This document **closes documented gaps** between:
- **Assurance claims** (e.g. SMOA eIDAS evidence: partial / QTSP pending — see SMOA repo `docs/compliance/evidence/eidas-compliance-evidence.md`)
- **Platform intent** (Phoenix as CSP-style control plane with tenant/IAM/catalog expectations)
- **Repository reality** (Complete Credential / eIDAS connector code lives **outside** this `proxmox` tree)
It does **not** replace legal advice, DPIAs, or national eID supervision requirements.
---
## Official-style descriptors (use in contracts and external comms)
| Avoid (ambiguous) | Prefer |
|-------------------|--------|
| Government client | **Public sector organization**, **procuring entity** (procurement context), **data controller** (GDPR context) |
| Subdivision | **Organizational unit**, **child public body**, **agency** (if legally distinct) |
| Phoenix portal (colloquial) | **Phoenix control plane** / **Phoenix API** (API-first); **Sankofa Portal** for brand site (`sankofa.nexus`) |
| Marketplace (product) | **Service catalog** + **entitlement management** until procurement-backed billing is implemented; use **marketplace** only if contractually defined |
| Wallet (in gov packs) | **Credential holder application**, **authenticator**, **SMOA client** — do not mix with **self-custody cryptocurrency wallet** language from Chain 138 / DeFi docs |
---
## Deployment profiles (flexibility bridge)
| Profile | Use when | Isolation |
|---------|----------|-----------|
| **A — Shared platform** | Pilot, single legal controller, non-qualified flows | Multi-tenant logical separation; **per-tenant** keys and metadata |
| **B — Dedicated stack** | Jurisdiction rule, qualified-trust boundary, or security classification | Separate LXC/VM (or cluster) per **controller** or **Member State** deployment |
| **C — Hybrid** | Shared orchestration (Phoenix), isolated crypto/PII | Phoenix + shared IdP; **connector + HSM/DB** isolated per tenant |
**Promotion path:** tenant IDs and APIs should allow moving **A → B** without rewriting mobile or portal clients.
---
## Illustrative reference topology (time-scoped)
_Label: **Illustrative — as of 2026-Q1**. Per [NON_GOALS.md](NON_GOALS.md) §4, this is not an immutable enterprise diagram; update when VMIDs/FQDNs change._
```
[ Internet / VPN ]
|
NPMplus / Edge
|
+-------------------+-------------------+
| | |
sankofa.nexus phoenix.sankofa.nexus api.smoa… (example)
(Portal 7801) (Phoenix API 7800) (SMOA edge LXC — see SMOA repo)
| | |
Keycloak 7802 GraphQL / health SMOA API / DB (LXC)
|
PostgreSQL 7803
|
[Optional: Complete Credential / eIDAS connector — dedicated LXC; not on Phoenix VMIDs]
```
**SMOA** Proxmox LXC layout (edge, API, DB, optional TURN/signal): see **SMOA** repository `backend/docs/LXC-PROXMOX-CONTAINERS.md` (not duplicated here).
**Complete Credential / eIDAS connector:** register in [public-sector-program-manifest.json](../../config/public-sector-program-manifest.json) and deploy per [COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md](../11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md).
---
## Regulatory-aligned defaults (summary)
1. **Credential / connector deployment:** isolate by **legal controller** and **jurisdiction** for qualified or sensitive PII; use **Profile B** when in doubt.
2. **Service catalog:** **entitlements** tied to **contracts / purchase orders** before automated public payment rails; same **SKU** model can later attach **e-invoicing / payment**.
3. **SMOA APK:** prefer **MDM / managed distribution** for production public-sector devices; public download only for **pilot / low classification** with explicit scope.
---
## Known technical gaps (tracked)
| ID | Gap | Mitigation owner |
|----|-----|------------------|
| G1 | SMOA eIDAS: QTSP, EU trust lists, qualified timestamping — **partial** in evidence doc | SMOA + legal + QTSP partnership |
| G2 | Phoenix: **billing** in EXPECTED_WEB_CONTENT is **roadmap**, not implemented | Phoenix product + procurement counsel |
| G3 | **proxmox** repo does not contain Complete Credential source | Use manifest + sibling clone; deploy via runbook |
| G4 | Terminology: **wallet** in DeFi docs vs **credential app** in gov context | Use this doc + review gov-facing PDFs |
| G5 | Single **sovereign reference diagram** in one place | This file + SERVICE_DESCRIPTIONS VM table; refresh quarterly |
---
## Review cadence
- **Quarterly** or when VMID/DNS/procurement model changes: update manifest FQDN hints and this diagram note.
- **After** QTSP or national eID milestone: update G1 and external-facing assurance statements.

152
docs/03-deployment/CHAIN138_OFFICIAL_STABLE_BLOCKER_REMOVAL_PATH.md Normal file
View File

@@ -0,0 +1,152 @@
# Chain 138 Official Stable Blocker Removal Path
**Purpose:** Remove the last local PMM blocker on Chain 138 by replacing stale placeholder addresses with live quote-side ERC-20 contracts and then redeploying the integration against them.
---
## 1. The blocker, stated plainly
The current local PMM path for:
- `cUSDT / USDT`
- `cUSDC / USDC`
is blocked because the integration is wired to addresses that are **not live ERC-20 contracts on Chain 138**.
That means:
- the pools may exist in metadata
- the integration can still report those addresses
- but liquidity add and swap flows will fail locally because the quote-side token has no bytecode
---
## 2. What is real in the repo today
### Live on Chain 138
- `cUSDT`
- `cUSDC`
- `cXAUC`
- `cXAUT`
- `DODOPMMIntegration`
- live funded `cUSDT / cUSDC`
- live funded XAU-side pools
### Not present as live local ERC-20s
- a real local `USDT` contract for Chain 138 official-pair PMM use
- a real local `USDC` contract for Chain 138 official-pair PMM use
### Not valid for this PMM blocker
- `MainnetTether.sol`
- this is a state anchor, not an ERC-20 token
- `StablecoinReserveVault.sol`
- this is for mainnet reserve custody/redemption, not a local Chain 138 quote token
---
## 3. Exact contract/deploy path
### Step 1. Deploy local Chain 138 quote-side mirrors
Deploy these contracts:
- [OfficialStableMirrorToken.sol](/home/intlc/projects/proxmox/smom-dbis-138/contracts/tokens/OfficialStableMirrorToken.sol)
- [DeployOfficialUSDT138.s.sol](/home/intlc/projects/proxmox/smom-dbis-138/script/DeployOfficialUSDT138.s.sol)
- [DeployOfficialUSDC138.s.sol](/home/intlc/projects/proxmox/smom-dbis-138/script/DeployOfficialUSDC138.s.sol)
These tokens are:
- lightweight ERC-20s
- 6 decimals
- owner-mintable
- meant only to provide live local quote-side assets for Chain 138 PMM pools
They are intentionally separate from the compliant token layer.
### Step 2. Persist live addresses
Write these into `smom-dbis-138/.env`:
```bash
OFFICIAL_USDT_ADDRESS=0x...
OFFICIAL_USDC_ADDRESS=0x...
```
### Step 3. Redeploy PMM integration against the live local quote assets
Use:
- [DeployDODOPMMIntegration.s.sol](/home/intlc/projects/proxmox/smom-dbis-138/script/dex/DeployDODOPMMIntegration.s.sol)
Important: this deploy script no longer falls back to stale hardcoded Chain 138 addresses. The operator must supply real addresses explicitly through env.
### Step 4. Create the stable pools on the new integration
Use:
- [CreateCUSDTUSDTPool.s.sol](/home/intlc/projects/proxmox/smom-dbis-138/script/dex/CreateCUSDTUSDTPool.s.sol)
- [CreateCUSDCUSDCPool.s.sol](/home/intlc/projects/proxmox/smom-dbis-138/script/dex/CreateCUSDCUSDCPool.s.sol)
- [CreateCUSDTCUSDCPool.s.sol](/home/intlc/projects/proxmox/smom-dbis-138/script/dex/CreateCUSDTCUSDCPool.s.sol)
### Step 5. Fund in this order
1. `cUSDT / cUSDC`
2. `cUSDT / USDT`
3. `cUSDC / USDC`
Use:
- [AddLiquidityPMMPoolsChain138.s.sol](/home/intlc/projects/proxmox/smom-dbis-138/script/dex/AddLiquidityPMMPoolsChain138.s.sol)
---
## 4. Verification gates
Before PMM redeploy:
```bash
cast code "$OFFICIAL_USDT_ADDRESS" --rpc-url "$RPC_URL_138"
cast code "$OFFICIAL_USDC_ADDRESS" --rpc-url "$RPC_URL_138"
cast call "$OFFICIAL_USDT_ADDRESS" "symbol()(string)" --rpc-url "$RPC_URL_138"
cast call "$OFFICIAL_USDC_ADDRESS" "symbol()(string)" --rpc-url "$RPC_URL_138"
```
After PMM redeploy:
```bash
cast call "$DODO_PMM_INTEGRATION_ADDRESS" "officialUSDT()(address)" --rpc-url "$RPC_URL_138"
cast call "$DODO_PMM_INTEGRATION_ADDRESS" "officialUSDC()(address)" --rpc-url "$RPC_URL_138"
```
After pool creation:
```bash
cast call "$DODO_PMM_INTEGRATION_ADDRESS" "pools(address,address)(address)" \
"$COMPLIANT_USDT_ADDRESS" "$OFFICIAL_USDT_ADDRESS" --rpc-url "$RPC_URL_138"
cast call "$DODO_PMM_INTEGRATION_ADDRESS" "pools(address,address)(address)" \
"$COMPLIANT_USDC_ADDRESS" "$OFFICIAL_USDC_ADDRESS" --rpc-url "$RPC_URL_138"
```
After funding:
```bash
cast call "$OFFICIAL_USDT_ADDRESS" "balanceOf(address)(uint256)" "$POOL_CUSDTUSDT" --rpc-url "$RPC_URL_138"
cast call "$OFFICIAL_USDC_ADDRESS" "balanceOf(address)(uint256)" "$POOL_CUSDCUSDC" --rpc-url "$RPC_URL_138"
```
---
## 5. Recommendation
The safe path is:
1. stop relying on the stale Chain 138 placeholder addresses
2. deploy explicit local quote-side mirror tokens
3. redeploy PMM integration using those real local token addresses
4. create and fund the stable pools
That is the narrowest change that removes the blocker without redefining the compliant token layer or pretending a non-existent Chain 138 official stable already exists.

475
docs/03-deployment/CHAIN138_PMM_REDEPLOY_AND_POOL_FUNDING_RUNBOOK.md Normal file
View File

@@ -0,0 +1,475 @@
# Chain 138 PMM Redeploy and Pool Funding Runbook
**Purpose:** Execute the live on-chain PMM remediation and funding sequence on Chain 138 in the correct order:
1. deploy live Chain 138 quote-side `USDT` and `USDC` ERC-20 mirror tokens
2. redeploy `DODOPMMIntegration` with those live Chain 138 official stable addresses
3. recreate the usable public stable pools on the new integration
4. create public XAU pools using `cXAUC` or `cXAUT` as the Chain 138 XAU anchor
5. deploy the `PrivatePoolRegistry` and register the XAU private stabilization pools
6. fund the pools in the correct order
**Primary chain:** Chain 138
**Operator requirement:** deployer EOA with `PRIVATE_KEY`, gas, and the required token balances / mint authority.
---
## 0. Preconditions
### 0.1 Required environment
From `smom-dbis-138/.env`:
```bash
PRIVATE_KEY=0x...
RPC_URL_138=http://...
DODO_VENDING_MACHINE_ADDRESS=0x...
COMPLIANT_USDT_ADDRESS=0x93E66202A11B1772E55407B32B44e5Cd8eda7f22
COMPLIANT_USDC_ADDRESS=0xf22258f57794CC8E06237084b353Ab30fFfa640b
OFFICIAL_USDT_ADDRESS=0x...
OFFICIAL_USDC_ADDRESS=0x...
```
### 0.2 XAU anchor selection
Choose one Chain 138 XAU anchor for the PMM and private stabilization pools:
```bash
# Preferred default
XAU_ADDRESS_138=0x290E52a8819A4fbD0714E517225429aA2B70EC6b # cXAUC
# Optional alternate
CXAUT_ADDRESS_138=0x94e408E26c6FD8F4ee00b54dF19082FDA07dC96E # cXAUT
```
If `XAU_ADDRESS_138` is unset, the scripts default to `cXAUC` on Chain 138.
### 0.3 Stop conditions
Stop immediately if any of these checks fail:
```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
source .env
cast wallet address "$PRIVATE_KEY"
cast code "$DODO_VENDING_MACHINE_ADDRESS" --rpc-url "$RPC_URL_138"
cast code "$COMPLIANT_USDT_ADDRESS" --rpc-url "$RPC_URL_138"
cast code "$COMPLIANT_USDC_ADDRESS" --rpc-url "$RPC_URL_138"
cast code "$OFFICIAL_USDT_ADDRESS" --rpc-url "$RPC_URL_138"
cast code "$OFFICIAL_USDC_ADDRESS" --rpc-url "$RPC_URL_138"
cast code "${XAU_ADDRESS_138:-0x290E52a8819A4fbD0714E517225429aA2B70EC6b}" --rpc-url "$RPC_URL_138"
```
Expected result: each `cast code` returns non-empty bytecode.
### 0.4 Important blocker note
Do **not** use the historical placeholder addresses `0x15DF...` or `0xA0b8...` on Chain 138 unless `cast code` proves they are live ERC-20 contracts on Chain 138.
The local PMM integration requires live quote-side ERC-20s on Chain 138. If `OFFICIAL_USDT_ADDRESS` and `OFFICIAL_USDC_ADDRESS` have no bytecode, deploy the local mirror tokens first.
---
## 1. Snapshot the current state
Record the current integration and pool state before redeploying:
```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
source .env
echo "Current integration: ${DODO_PMM_INTEGRATION_ADDRESS:-${DODO_PMM_INTEGRATION:-unset}}"
echo "Current cUSDT/cUSDC pool: ${POOL_CUSDTCUSDC:-unset}"
echo "Current cUSDT/USDT pool: ${POOL_CUSDTUSDT:-unset}"
echo "Current cUSDC/USDC pool: ${POOL_CUSDCUSDC:-unset}"
```
If the current integration exists, record its immutable token addresses:
```bash
INT="${DODO_PMM_INTEGRATION_ADDRESS:-${DODO_PMM_INTEGRATION:-}}"
[ -n "$INT" ] && cast call "$INT" "officialUSDT()(address)" --rpc-url "$RPC_URL_138"
[ -n "$INT" ] && cast call "$INT" "officialUSDC()(address)" --rpc-url "$RPC_URL_138"
```
---
## 1. Deploy the Chain 138 official stable mirrors
Deploy the local quote-side assets first. These are lightweight ERC-20 mirrors used only to unblock local PMM pools on Chain 138.
```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
source .env
forge script script/DeployOfficialUSDT138.s.sol:DeployOfficialUSDT138 \
--rpc-url "$RPC_URL_138" \
--broadcast \
--private-key "$PRIVATE_KEY" \
--with-gas-price "${GAS_PRICE_138:-1000000000}" \
--legacy \
-vv
forge script script/DeployOfficialUSDC138.s.sol:DeployOfficialUSDC138 \
--rpc-url "$RPC_URL_138" \
--broadcast \
--private-key "$PRIVATE_KEY" \
--with-gas-price "${GAS_PRICE_138:-1000000000}" \
--legacy \
-vv
```
Persist the deployed addresses into `.env`:
```bash
OFFICIAL_USDT_ADDRESS=0x...
OFFICIAL_USDC_ADDRESS=0x...
```
Verify both:
```bash
cast code "$OFFICIAL_USDT_ADDRESS" --rpc-url "$RPC_URL_138"
cast code "$OFFICIAL_USDC_ADDRESS" --rpc-url "$RPC_URL_138"
cast call "$OFFICIAL_USDT_ADDRESS" "symbol()(string)" --rpc-url "$RPC_URL_138"
cast call "$OFFICIAL_USDC_ADDRESS" "symbol()(string)" --rpc-url "$RPC_URL_138"
```
Expected result:
- both return non-empty bytecode
- symbols return `USDT` and `USDC`
---
## 2. Redeploy PMM integration on Chain 138
This step creates a fresh `DODOPMMIntegration` using the corrected Chain 138 official stable addresses.
```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
source .env
forge script script/dex/DeployDODOPMMIntegration.s.sol:DeployDODOPMMIntegration \
--rpc-url "$RPC_URL_138" \
--broadcast \
--private-key "$PRIVATE_KEY" \
--with-gas-price "${GAS_PRICE_138:-1000000000}" \
--legacy \
-vv
```
After deployment, update `.env` with the new integration address:
```bash
DODO_PMM_INTEGRATION_ADDRESS=0x...
DODO_PMM_INTEGRATION=0x...
```
Verify the new immutables:
```bash
INT="${DODO_PMM_INTEGRATION_ADDRESS:-${DODO_PMM_INTEGRATION:-}}"
cast call "$INT" "officialUSDT()(address)" --rpc-url "$RPC_URL_138"
cast call "$INT" "officialUSDC()(address)" --rpc-url "$RPC_URL_138"
cast call "$INT" "compliantUSDT()(address)" --rpc-url "$RPC_URL_138"
cast call "$INT" "compliantUSDC()(address)" --rpc-url "$RPC_URL_138"
```
Expected result:
- `officialUSDT` = the live `OFFICIAL_USDT_ADDRESS` you just deployed or verified
- `officialUSDC` = the live `OFFICIAL_USDC_ADDRESS` you just deployed or verified
---
## 3. Create the corrected public stable pools
Create the three public PMM pools on the **new** integration:
```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
source .env
forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool \
--rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "${GAS_PRICE_138:-1000000000}" -vv
forge script script/dex/CreateCUSDTUSDTPool.s.sol:CreateCUSDTUSDTPool \
--rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "${GAS_PRICE_138:-1000000000}" -vv
forge script script/dex/CreateCUSDCUSDCPool.s.sol:CreateCUSDCUSDCPool \
--rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "${GAS_PRICE_138:-1000000000}" -vv
```
Record the new pool addresses:
```bash
INT="${DODO_PMM_INTEGRATION_ADDRESS:-${DODO_PMM_INTEGRATION:-}}"
POOL_CUSDTCUSDC=$(cast call "$INT" "pools(address,address)(address)" \
"$COMPLIANT_USDT_ADDRESS" "$COMPLIANT_USDC_ADDRESS" --rpc-url "$RPC_URL_138" | cast --to-addr)
POOL_CUSDTUSDT=$(cast call "$INT" "pools(address,address)(address)" \
"$COMPLIANT_USDT_ADDRESS" "$OFFICIAL_USDT_ADDRESS" --rpc-url "$RPC_URL_138" | cast --to-addr)
POOL_CUSDCUSDC=$(cast call "$INT" "pools(address,address)(address)" \
"$COMPLIANT_USDC_ADDRESS" "$OFFICIAL_USDC_ADDRESS" --rpc-url "$RPC_URL_138" | cast --to-addr)
echo "$POOL_CUSDTCUSDC"
echo "$POOL_CUSDTUSDT"
echo "$POOL_CUSDCUSDC"
```
Persist them into `.env`.
---
## 4. Create the public XAU pools
Use the new public XAU script so the XAU side is explicit as `cXAUC` or `cXAUT`.
```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
source .env
forge script script/dex/CreatePublicXAUPoolsChain138.s.sol:CreatePublicXAUPoolsChain138 \
--rpc-url "$RPC_URL_138" \
--broadcast \
--private-key "$PRIVATE_KEY" \
--with-gas-price "${GAS_PRICE_138:-1000000000}" \
--legacy \
-vv
```
Optional controls:
```bash
CREATE_CUSDT_XAU=true
CREATE_CUSDC_XAU=true
CREATE_CEURT_XAU=true
```
Verify the created public XAU pools:
```bash
INT="${DODO_PMM_INTEGRATION_ADDRESS:-${DODO_PMM_INTEGRATION:-}}"
XAU="${XAU_ADDRESS_138:-0x290E52a8819A4fbD0714E517225429aA2B70EC6b}"
cast call "$INT" "pools(address,address)(address)" "$COMPLIANT_USDT_ADDRESS" "$XAU" --rpc-url "$RPC_URL_138"
cast call "$INT" "pools(address,address)(address)" "$COMPLIANT_USDC_ADDRESS" "$XAU" --rpc-url "$RPC_URL_138"
cast call "$INT" "pools(address,address)(address)" "0xdf4b71c61E5912712C1Bdd451416B9aC26949d72" "$XAU" --rpc-url "$RPC_URL_138"
```
Persist the returned pool addresses if they are non-zero.
---
## 5. Deploy `PrivatePoolRegistry` and register private XAU pools
```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
source .env
forge script script/dex/DeployPrivatePoolRegistryAndPools.s.sol:DeployPrivatePoolRegistryAndPools \
--rpc-url "$RPC_URL_138" \
--broadcast \
--private-key "$PRIVATE_KEY" \
--with-gas-price "${GAS_PRICE_138:-1000000000}" \
--legacy \
-vv
```
Record:
```bash
PRIVATE_POOL_REGISTRY=0x...
```
Verify registrations:
```bash
REG="$PRIVATE_POOL_REGISTRY"
XAU="${XAU_ADDRESS_138:-0x290E52a8819A4fbD0714E517225429aA2B70EC6b}"
cast call "$REG" "getPool(address,address)(address)" "$COMPLIANT_USDT_ADDRESS" "$XAU" --rpc-url "$RPC_URL_138"
cast call "$REG" "getPool(address,address)(address)" "$COMPLIANT_USDC_ADDRESS" "$XAU" --rpc-url "$RPC_URL_138"
cast call "$REG" "getPool(address,address)(address)" "0xdf4b71c61E5912712C1Bdd451416B9aC26949d72" "$XAU" --rpc-url "$RPC_URL_138"
```
---
## 6. Fund the pools in the correct order
### 6.1 Funding order
Fund in this order:
1. `cUSDT / cUSDC`
2. `cUSDT / USDT`
3. `cUSDC / USDC`
4. public XAU pools:
- `cUSDT / XAU`
- `cUSDC / XAU`
- `cEURT / XAU`
5. private stabilization pools last
Reason:
- `cUSDT/cUSDC` establishes the base compliant market first
- official stable pools come next after the corrected addresses are live
- XAU public pools should discover price before private stabilization paths are seeded
### 6.2 Mint compliant balances
Mint the compliant side first:
```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
source .env
MINT_CUSDT_AMOUNT=2000000 \
MINT_CUSDC_AMOUNT=2000000 \
./scripts/mint-for-liquidity.sh
```
Mint additional compliant assets as needed:
```bash
DEPLOYER=$(cast wallet address "$PRIVATE_KEY")
cast send 0xdf4b71c61E5912712C1Bdd451416B9aC26949d72 \
"mint(address,uint256)" "$DEPLOYER" 1000000000000 \
--rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
```
### 6.3 Acquire / verify non-mintable sides
Before adding liquidity, confirm balances of:
- `OFFICIAL_USDT_ADDRESS`
- `OFFICIAL_USDC_ADDRESS`
- `XAU_ADDRESS_138` (`cXAUC` or `cXAUT`)
```bash
DEPLOYER=$(cast wallet address "$PRIVATE_KEY")
cast call "$OFFICIAL_USDT_ADDRESS" "balanceOf(address)(uint256)" "$DEPLOYER" --rpc-url "$RPC_URL_138"
cast call "$OFFICIAL_USDC_ADDRESS" "balanceOf(address)(uint256)" "$DEPLOYER" --rpc-url "$RPC_URL_138"
cast call "${XAU_ADDRESS_138:-0x290E52a8819A4fbD0714E517225429aA2B70EC6b}" "balanceOf(address)(uint256)" "$DEPLOYER" --rpc-url "$RPC_URL_138"
```
Do **not** proceed on a pool until both sides have sufficient balance.
### 6.4 Fund `cUSDT / cUSDC`
Use the existing add-liquidity script first:
```bash
export ADD_LIQUIDITY_CUSDTCUSDC_BASE=1000000000000
export ADD_LIQUIDITY_CUSDTCUSDC_QUOTE=1000000000000
forge script script/dex/AddLiquidityPMMPoolsChain138.s.sol:AddLiquidityPMMPoolsChain138 \
--rpc-url "$RPC_URL_138" \
--broadcast \
--private-key "$PRIVATE_KEY" \
--with-gas-price "${GAS_PRICE_138:-1000000000}" \
-vv
```
### 6.5 Fund `cUSDT / USDT` and `cUSDC / USDC`
Set per-pool liquidity amounts:
```bash
export ADD_LIQUIDITY_CUSDTUSDT_BASE=1000000000000
export ADD_LIQUIDITY_CUSDTUSDT_QUOTE=1000000000000
export ADD_LIQUIDITY_CUSDCUSDC_BASE=1000000000000
export ADD_LIQUIDITY_CUSDCUSDC_QUOTE=1000000000000
```
Then run the same liquidity script:
```bash
forge script script/dex/AddLiquidityPMMPoolsChain138.s.sol:AddLiquidityPMMPoolsChain138 \
--rpc-url "$RPC_URL_138" \
--broadcast \
--private-key "$PRIVATE_KEY" \
--with-gas-price "${GAS_PRICE_138:-1000000000}" \
-vv
```
### 6.6 Fund public XAU pools
For each public XAU pool:
1. approve both tokens to the integration
2. call `addLiquidity(pool, baseAmount, quoteAmount)`
Example for `cUSDT / XAU`:
```bash
INT="${DODO_PMM_INTEGRATION_ADDRESS:-${DODO_PMM_INTEGRATION:-}}"
XAU="${XAU_ADDRESS_138:-0x290E52a8819A4fbD0714E517225429aA2B70EC6b}"
POOL=$(cast call "$INT" "pools(address,address)(address)" "$COMPLIANT_USDT_ADDRESS" "$XAU" --rpc-url "$RPC_URL_138" | cast --to-addr)
cast send "$COMPLIANT_USDT_ADDRESS" "approve(address,uint256)" "$INT" 1000000000000 --rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
cast send "$XAU" "approve(address,uint256)" "$INT" 1000000000000 --rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
cast send "$INT" "addLiquidity(address,uint256,uint256)" "$POOL" 1000000000000 1000000000000 --rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
```
Repeat for:
- `cUSDC / XAU`
- `cEURT / XAU`
### 6.7 Seed private stabilization pools last
Only after the public pools have been created and seeded:
1. verify private registry entries exist
2. approve both sides
3. fund the corresponding private pool addresses with smaller initial depth than the public pools
Use the same `addLiquidity(address,uint256,uint256)` pattern against the registered pool addresses.
---
## 7. Post-funding verification
### 7.1 Pool reserves
```bash
cast call "$POOL_CUSDTCUSDC" "getVaultReserve()(uint256,uint256)" --rpc-url "$RPC_URL_138"
cast call "$POOL_CUSDTUSDT" "getVaultReserve()(uint256,uint256)" --rpc-url "$RPC_URL_138"
cast call "$POOL_CUSDCUSDC" "getVaultReserve()(uint256,uint256)" --rpc-url "$RPC_URL_138"
```
Repeat for each XAU pool address.
### 7.2 Explorer alignment
After successful execution, update:
- [ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md)
- [DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md](../11-references/DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS.md)
Also update the explorer pool inventory if new pool addresses were created.
---
## 8. Rollback / abort guidance
Abort if any of the following occurs:
- official token bytecode missing on 138
- integration deployed with wrong immutables
- pool creation returns zero or reverts unexpectedly
- deployer lacks balance for either side of a target pool
If the new integration is deployed but pool creation fails, stop there and do **not** fund the old incorrect pools.
---
## 9. References
- [DeployDODOPMMIntegration.s.sol](../../smom-dbis-138/script/dex/DeployDODOPMMIntegration.s.sol)
- [CreateCUSDTCUSDCPool.s.sol](../../smom-dbis-138/script/dex/CreateCUSDTCUSDCPool.s.sol)
- [CreateCUSDTUSDTPool.s.sol](../../smom-dbis-138/script/dex/CreateCUSDTUSDTPool.s.sol)
- [CreateCUSDCUSDCPool.s.sol](../../smom-dbis-138/script/dex/CreateCUSDCUSDCPool.s.sol)
- [CreatePublicXAUPoolsChain138.s.sol](../../smom-dbis-138/script/dex/CreatePublicXAUPoolsChain138.s.sol)
- [DeployPrivatePoolRegistryAndPools.s.sol](../../smom-dbis-138/script/dex/DeployPrivatePoolRegistryAndPools.s.sol)
- [AddLiquidityPMMPoolsChain138.s.sol](../../smom-dbis-138/script/dex/AddLiquidityPMMPoolsChain138.s.sol)
- [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md](/home/intlc/projects/proxmox/docs/03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md)

247
docs/03-deployment/CHAIN138_XAU_POOL_STATUS_AND_PUBLIC_CREATION_PATH.md Normal file
View File

@@ -0,0 +1,247 @@
# Chain 138 XAU Pool Status and Public Creation Path
**Date:** 2026-03-26
**Scope:** Verify live private and public XAU pools on Chain 138 and record the exact creation/funding path used.
## Current live state
### Private XAU pools: live on-chain now
Verified against:
- `PrivatePoolRegistry`: `0xb27057B27db09e8Df353AF722c299f200519882A`
- `cXAUC`: `0x290E52a8819A4fbD0714E517225429aA2B70EC6b`
Registered private pools:
- `cUSDT / cXAUC`
- pool: `0x94316511621430423a2cff0C036902BAB4aA70c2`
- `cUSDC / cXAUC`
- pool: `0x7867D58567948e5b9908F1057055Ee4440de0851`
- `cEURT / cXAUC`
- pool: `0x505403093826D494983A93b43Aa0B8601078A44e`
Code verification:
- all three pool addresses return non-empty bytecode on Chain 138
Observed reserves:
- `cUSDT / cXAUC`
- `cUSDT`: `2,666,965`
- `cXAUC`: `519.477`
- `cUSDC / cXAUC`
- `cUSDC`: `1,000,000`
- `cXAUC`: `194.782554`
- `cEURT / cXAUC`
- `cEURT`: `1,000,000`
- `cXAUC`: `225.577676`
### Public XAU pools: now created and funded in the live PMM integration
Verified against:
- `DODOPMMIntegration`: `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`
Current mapping state:
- `pools(cUSDT, cXAUC) = 0x1AA55E2001E5651349AfF5A63FD7A7Ae44f0F1b0`
- `pools(cUSDC, cXAUC) = 0xEA9Ac6357CaCB42a83b9082B870610363B177cBa`
- `pools(cEURT, cXAUC) = 0xbA99bc1eAAC164569d5AcA96C806934DDaF970Cf`
All three public pool addresses return non-empty bytecode on Chain 138.
Observed public reserves:
- `cUSDT / cXAUC`
- `cUSDT`: `2,666,965`
- `cXAUC`: `519.477`
- `cUSDC / cXAUC`
- `cUSDC`: `1,000,000`
- `cXAUC`: `194.782554`
- `cEURT / cXAUC`
- `cEURT`: `1,000,000`
- `cXAUC`: `225.577676`
The explorer should now show these rows with:
- real pool address
- `Funded (live)`
- notes derived from live integration mapping and reserves
## Exact creation and funding path used for the three public XAU pools
### 1. Preconditions
Confirm the required contracts and tokens are already live:
- `DODOPMMIntegration`: `0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d`
- `cUSDT`: `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22`
- `cUSDC`: `0xf22258f57794CC8E06237084b353Ab30fFfa640b`
- `cEURT`: `0xdf4b71c61E5912712C1Bdd451416B9aC26949d72`
- `cXAUC`: `0x290E52a8819A4fbD0714E517225429aA2B70EC6b`
Recommended env:
```bash
export RPC_URL_138=http://192.168.11.211:8545
export DODOPMM_INTEGRATION=0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d
export COMPLIANT_USDT_ADDRESS=0x93E66202A11B1772E55407B32B44e5Cd8eda7f22
export COMPLIANT_USDC_ADDRESS=0xf22258f57794CC8E06237084b353Ab30fFfa640b
export cEURT_ADDRESS_138=0xdf4b71c61E5912712C1Bdd451416B9aC26949d72
export XAU_ADDRESS_138=0x290E52a8819A4fbD0714E517225429aA2B70EC6b
```
### 2. Create the public XAU pools
Use the existing script:
- [CreatePublicXAUPoolsChain138.s.sol](../../smom-dbis-138/script/dex/CreatePublicXAUPoolsChain138.s.sol)
Run:
```bash
cd /home/intlc/projects/proxmox/smom-dbis-138
source .env
forge script script/dex/CreatePublicXAUPoolsChain138.s.sol:CreatePublicXAUPoolsChain138 \
--rpc-url "$RPC_URL_138" \
--broadcast \
--private-key "$PRIVATE_KEY" \
--with-gas-price "${GAS_PRICE_138:-1000000000}" \
--legacy \
-vv
```
Optional toggles:
```bash
export CREATE_CUSDT_XAU=true
export CREATE_CUSDC_XAU=true
export CREATE_CEURT_XAU=true
```
### 3. Verify creation immediately
```bash
INT="${DODOPMM_INTEGRATION:-$DODOPMM_INTEGRATION_ADDRESS}"
XAU="${XAU_ADDRESS_138:-0x290E52a8819A4fbD0714E517225429aA2B70EC6b}"
cast call "$INT" "pools(address,address)(address)" "$COMPLIANT_USDT_ADDRESS" "$XAU" --rpc-url "$RPC_URL_138"
cast call "$INT" "pools(address,address)(address)" "$COMPLIANT_USDC_ADDRESS" "$XAU" --rpc-url "$RPC_URL_138"
cast call "$INT" "pools(address,address)(address)" "0xdf4b71c61E5912712C1Bdd451416B9aC26949d72" "$XAU" --rpc-url "$RPC_URL_138"
```
Each result should now be a non-zero pool address.
Persist them into `.env` or the relevant operator notes.
### 4. Public pool addresses created
- `cUSDT / cXAUC`
- pool: `0x1AA55E2001E5651349AfF5A63FD7A7Ae44f0F1b0`
- create tx: `0xb38df32e7f51cff2ec283aa70ebf0e98b195721efa58d9b0a6e1df7fb55c05a1`
- `cUSDC / cXAUC`
- pool: `0xEA9Ac6357CaCB42a83b9082B870610363B177cBa`
- create tx: `0xae16081faf9762500d14883be814393695d6a854afe84c9c1521ec5486babe23`
- `cEURT / cXAUC`
- pool: `0xbA99bc1eAAC164569d5AcA96C806934DDaF970Cf`
- create tx: `0x1adaca76b3e34acd0807d5e11e334dd773b2146e4aeb45d67d5a54c1934d0e55`
## Exact funding path for the public XAU pools
### 5. Funding order
Fund public XAU pools before changing private stabilization depth:
1. `cUSDT / cXAUC`
2. `cUSDC / cXAUC`
3. `cEURT / cXAUC`
4. only then revisit private stabilization depth if needed
### 6. Funding method
The public XAU pools use the same PMM integration liquidity path:
1. approve both tokens to `DODOPMMIntegration`
2. call `addLiquidity(pool, baseAmount, quoteAmount)`
Example for `cUSDT / cXAUC`:
```bash
INT="${DODOPMM_INTEGRATION:-$DODOPMM_INTEGRATION_ADDRESS}"
XAU="${XAU_ADDRESS_138:-0x290E52a8819A4fbD0714E517225429aA2B70EC6b}"
POOL=$(cast call "$INT" "pools(address,address)(address)" "$COMPLIANT_USDT_ADDRESS" "$XAU" --rpc-url "$RPC_URL_138" | cast --to-addr)
cast send "$COMPLIANT_USDT_ADDRESS" "approve(address,uint256)" "$INT" 1000000000000 --rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
cast send "$XAU" "approve(address,uint256)" "$INT" 1000000000000 --rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
cast send "$INT" "addLiquidity(address,uint256,uint256)" "$POOL" 1000000000000 1000000000000 --rpc-url "$RPC_URL_138" --private-key "$PRIVATE_KEY"
```
Repeat the same pattern for:
- `cUSDC / cXAUC`
- `cEURT / cXAUC`
### 7. Funding completed
Successful funding transactions:
- `cUSDT / cXAUC`
- fund tx: `0x7e00ec7a97fada7a9c238638bc019c6755feeb68be06c4b69e519b0eec6dd3b6`
- final reserves: `2,666,965 cUSDT / 519.477 cXAUC`
- `cUSDC / cXAUC`
- fund tx: `0x87ec3a710dfb785de6adaa4f191440cd4968e090c0afb1f21ba02c8e0501f7eb`
- final reserves: `1,000,000 cUSDC / 194.782554 cXAUC`
- `cEURT / cXAUC`
- fund tx: `0x995b785ab49f0ffc8f782a7d573259cf09fc57176d4fae19c1f6b274712e9e93`
- final reserves: `1,000,000 cEURT / 225.577676 cXAUC`
Supporting approvals:
- `cXAUC` approval: `0xd194c80b8246816ef88141736eb17dece478183b37053cfbe1fffd6efe2abc99`
- `cEURT` approval: `0x922d530cd65fdd139ff4e8c43a219b254d0c3df4e461a45f02f7832205735983`
### 8. Suggested bootstrap amounts
Use the same scale already proven on the private side unless treasury wants a different public depth target.
Reasonable bootstrap examples:
- `cUSDT / cXAUC`
- base: `1,000,000e6`
- quote: `200e6` to `500e6` depending on desired starting depth
- `cUSDC / cXAUC`
- base: `1,000,000e6`
- quote: `150e6` to `250e6`
- `cEURT / cXAUC`
- base: `1,000,000e6`
- quote: `200e6` to `250e6`
Final quote-side amounts should be treasury/policy-driven. The exact `cXAUC` depth can be calibrated against the current private pool ratios if parity is desired.
## Post-funding verification
After funding, verify:
```bash
cast call "$COMPLIANT_USDT_ADDRESS" "balanceOf(address)(uint256)" "$POOL_CUSDT_XAU" --rpc-url "$RPC_URL_138"
cast call "$COMPLIANT_USDC_ADDRESS" "balanceOf(address)(uint256)" "$POOL_CUSDC_XAU" --rpc-url "$RPC_URL_138"
cast call "0xdf4b71c61E5912712C1Bdd451416B9aC26949d72" "balanceOf(address)(uint256)" "$POOL_CEURT_XAU" --rpc-url "$RPC_URL_138"
cast call "$XAU" "balanceOf(address)(uint256)" "$POOL_CUSDT_XAU" --rpc-url "$RPC_URL_138"
cast call "$XAU" "balanceOf(address)(uint256)" "$POOL_CUSDC_XAU" --rpc-url "$RPC_URL_138"
cast call "$XAU" "balanceOf(address)(uint256)" "$POOL_CEURT_XAU" --rpc-url "$RPC_URL_138"
```
Then verify the explorer `/pools` page shows:
- real pool address
- `Funded (live)`
- a live note path derived from the integration mapping instead of the old `Not created` state
## References
- [CreatePublicXAUPoolsChain138.s.sol](../../smom-dbis-138/script/dex/CreatePublicXAUPoolsChain138.s.sol)
- [DeployPrivatePoolRegistryAndPools.s.sol](../../smom-dbis-138/script/dex/DeployPrivatePoolRegistryAndPools.s.sol)
- [AddLiquidityPMMPoolsChain138.s.sol](../../smom-dbis-138/script/dex/AddLiquidityPMMPoolsChain138.s.sol)
- [CHAIN138_PMM_REDEPLOY_AND_POOL_FUNDING_RUNBOOK.md](./CHAIN138_PMM_REDEPLOY_AND_POOL_FUNDING_RUNBOOK.md)

137
docs/03-deployment/FINAL_UNBLOCK_CHECKLIST_MAINNET_BSC.md Normal file
View File

@@ -0,0 +1,137 @@
# Final Unblock Checklist: Mainnet and BSC
**Date:** 2026-03-26
**Wallet:** `0x4A666F96fC8764181194447A7dFdb7d471b301C8`
This checklist captures the **exact remaining top-up targets** after the live funding pass already completed on Ethereum Mainnet.
## Current post-funding state
### Mainnet
- Deployer ETH: `0.003345428710812742`
- Deployer LINK: `0`
- Deployer WETH9: `0`
- `MAINNET_CCIP_WETH9_BRIDGE` LINK: `0.215485646892774955`
- `MAINNET_CCIP_WETH10_BRIDGE` LINK: `0.215485646892774955`
- `CCIP_RELAY_BRIDGE_MAINNET` WETH: `0.002634280582011289`
- `LiquidityPoolETH` available ETH: `0.015`
- `LiquidityPoolETH` available WETH: `0.001`
### BSC
- Deployer BNB: `0.0091250643`
- Deployer LINK: `0`
- Deployer WETH: `0`
- `CCIPWETH9_BRIDGE_BSC` LINK: `0`
- `CCIPWETH10_BRIDGE_BSC` LINK: `0`
## Exact top-up targets
### 1. Mainnet deployer gas reserve
Repo recommendation: keep **`0.05 ETH`** on the deployer for safe operator headroom.
- Current: `0.003345428710812742 ETH`
- Target: `0.05 ETH`
- **Top up:** `0.046654571289187258 ETH`
### 2. Mainnet CCIP bridge LINK
Repo recommendation: **`10 LINK per bridge`**.
- `MAINNET_CCIP_WETH9_BRIDGE`
- Current: `0.215485646892774955 LINK`
- Target: `10 LINK`
- **Top up:** `9.784514353107225045 LINK`
- `MAINNET_CCIP_WETH10_BRIDGE`
- Current: `0.215485646892774955 LINK`
- Target: `10 LINK`
- **Top up:** `9.784514353107225045 LINK`
- **Mainnet CCIP LINK total top-up:** `19.56902870621445009 LINK`
### 3. Mainnet trustless LP target
Operator runbook example target:
- LP ETH target: **`1 ETH`**
- LP WETH target: **`0.5 WETH`**
Current:
- LP ETH available: `0.015 ETH`
- LP WETH available: `0.001 WETH`
Top-ups:
- **ETH top-up:** `0.985 ETH`
- **WETH top-up:** `0.499 WETH`
### 4. Mainnet relay bridge WETH target
There is no hardcoded repo target for relay inventory, so use a small bootstrap target unless you have a higher payout requirement.
- Suggested bootstrap target: **`0.01 WETH`**
- Current: `0.002634280582011289 WETH`
- **Top up:** `0.007365719417988711 WETH`
### 5. BSC deployer gas reserve
Repo recommendation: keep **`0.06 BNB`** on the deployer.
- Current: `0.0091250643 BNB`
- Target: `0.06 BNB`
- **Top up:** `0.0508749357 BNB`
### 6. BSC CCIP bridge LINK
Repo recommendation: **`10 LINK per bridge`**.
- `CCIPWETH9_BRIDGE_BSC`
- Current: `0 LINK`
- Target: `10 LINK`
- **Top up:** `10 LINK`
- `CCIPWETH10_BRIDGE_BSC`
- Current: `0 LINK`
- Target: `10 LINK`
- **Top up:** `10 LINK`
- **BSC CCIP LINK total top-up:** `20 LINK`
### 7. BSC relay bridge WETH (optional, only if relay mode is used)
If you are operating the BSC relay flow from `services/relay/.env.bsc`, top up the destination relay bridge too.
- Suggested bootstrap target: **`0.01 WETH`**
- Current deployer WETH on BSC: `0`
- **Acquire and transfer:** `0.01 WETH` to `DEST_RELAY_BRIDGE`
## One-pass operator sequence after top-up
1. Fund Mainnet deployer ETH reserve to `0.05 ETH`.
2. Fund Mainnet CCIP bridges to `10 LINK` each:
- `MAINNET_CCIP_WETH9_BRIDGE`
- `MAINNET_CCIP_WETH10_BRIDGE`
3. Fund Mainnet LP to `1 ETH` and `0.5 WETH`.
4. Fund Mainnet relay bridge to `0.01 WETH` minimum.
5. Fund BSC deployer to `0.06 BNB`.
6. Fund BSC CCIP bridges to `10 LINK` each.
7. If relay mode is used on BSC, fund the BSC relay bridge with at least `0.01 WETH`.
8. Set `BOND_MANAGER_MAINNET` and `CHALLENGE_MANAGER_MAINNET` in `.env`.
9. Run the full live bridge test from [`live-test-trustless-bridge.sh`](../../smom-dbis-138/scripts/deployment/live-test-trustless-bridge.sh).
## Scripted paths
- One-command operator wrapper:
- [`run-final-unblock-checklist.sh`](../../smom-dbis-138/scripts/deployment/run-final-unblock-checklist.sh)
- Status-only preflight:
- `./scripts/deployment/run-final-unblock-checklist.sh --status-only`
- JSON preflight for CI/dashboards:
- `./scripts/deployment/run-final-unblock-checklist.sh --status-only --json`
- Mainnet LP funding:
- [`fund-mainnet-lp.sh`](../../smom-dbis-138/scripts/deployment/fund-mainnet-lp.sh)
- Mainnet relay bridge funding:
- [`fund-mainnet-relay-bridge.sh`](../../smom-dbis-138/scripts/bridge/fund-mainnet-relay-bridge.sh)
- BSC relay bridge funding:
- [`fund-bsc-relay-bridge.sh`](../../smom-dbis-138/scripts/bridge/fund-bsc-relay-bridge.sh)
- Multi-chain LINK funding:
- [`fund-ccip-bridges-with-link.sh`](../../smom-dbis-138/scripts/deployment/fund-ccip-bridges-with-link.sh)

119
docs/04-configuration/FQDN_EXPECTED_CONTENT.md Normal file
View File

@@ -0,0 +1,119 @@
# FQDN expected content (what users and clients should see)
**Last Updated:** 2026-03-27 (Sankofa hostname tiers: public / SSO / dash)
**Purpose:** One-page description of **what should be presented** at each public NPM-routed hostname after HTTPS. Use this before pruning evidence or changing proxies so expectations stay aligned with product intent.
**Canonical routing (IPs, VMIDs, ports):** [ALL_VMIDS_ENDPOINTS.md](ALL_VMIDS_ENDPOINTS.md), [RPC_ENDPOINTS_MASTER.md](RPC_ENDPOINTS_MASTER.md).
**Product depth (Sankofa / Phoenix / explorer narrative):** [EXPECTED_WEB_CONTENT.md](../02-architecture/EXPECTED_WEB_CONTENT.md).
**Automated checks:** [E2E_ENDPOINTS_LIST.md](E2E_ENDPOINTS_LIST.md), `scripts/verify/verify-end-to-end-routing.sh`.
---
## Legend
| Kind | Meaning |
|------|---------|
| **Web** | Browser loads HTML (or SPA shell); humans see pages, forms, or dashboards. |
| **API** | Primarily JSON over HTTPS; browsers may see errors unless hitting documented REST paths. |
| **RPC-HTTP** | **No marketing page.** JSON-RPC 2.0 over HTTPS POST to `/` (or provider path); wallets and backends consume JSON. |
| **RPC-WS** | **No HTML.** WebSocket upgrade; JSON-RPC / subscription traffic. |
| **301** | Apex policy: `www.*` redirects to non-www HTTPS (see NPM `advanced_config`). |
---
## sankofa.nexus zone
**Canonical roles:** [EXPECTED_WEB_CONTENT.md](../02-architecture/EXPECTED_WEB_CONTENT.md) (hostname model table).
### Public web (unauthenticated visitors for marketing / division pages)
| FQDN | Kind | What should be displayed or returned |
|------|------|--------------------------------------|
| `sankofa.nexus` | Web | **Sankofa — Sovereign Technologies:** public corporate / brand web (mission, narrative, entry points). |
| `www.sankofa.nexus` | 301 → apex | Browser ends on `https://sankofa.nexus/...`. |
| `phoenix.sankofa.nexus` | Web / API | **Phoenix Cloud Services** (division of Sankofa): public-facing **division web** (intent). Same deployment may still expose API paths (`/health`, `/graphql`, …). E2E verifier may use `/health`. |
| `www.phoenix.sankofa.nexus` | 301 → apex | Browser ends on `https://phoenix.sankofa.nexus/...`. |
### Client SSO (system SSO; Keycloak as IdP)
| FQDN | Kind | What should be displayed or returned |
|------|------|--------------------------------------|
| `keycloak.sankofa.nexus` | Web / IdP | **Identity provider** for client SSO: realm login UI, OIDC/SAML well-known and token endpoints; operator **Keycloak admin** at `/admin`. Backs **`admin`** and **`portal`** redirects—not a substitute for those apps. |
| `admin.sankofa.nexus` | Web | **Client SSO:** administer access (users, roles, org access policy). |
| `portal.sankofa.nexus` | Web | **Client SSO:** Phoenix cloud services, Sankofa Marketplace subscriptions, and other **client-facing** services. |
### Operator / systems (IP-gated + MFA)
| FQDN | Kind | What should be displayed or returned |
|------|------|--------------------------------------|
| `dash.sankofa.nexus` | Web | **IP allowlisting** + **system authentication** + **MFA:** unified admin for Sankofa, Phoenix, Gitea, and related systems (not the client self-service portal). |
### Other properties on the zone
| FQDN | Kind | What should be displayed or returned |
|------|------|--------------------------------------|
| `the-order.sankofa.nexus` | Web | **OSJ / Order management** portal (secure auth); app **the_order**. Upstream: HAProxy **10210** → portal stack. |
| `www.the-order.sankofa.nexus` | 301 → apex | Browser ends on `https://the-order.sankofa.nexus/...`. |
| `studio.sankofa.nexus` | Web | **Sankofa Studio (FusionAI)** UI under `/studio/` (and related API routes on same origin). |
---
## d-bis.org (DBIS + infrastructure)
| FQDN | Kind | What should be displayed or returned |
|------|------|--------------------------------------|
| `explorer.d-bis.org` | Web | **SolaceScanScout / Blockscout** UI: blocks, txs, addresses, tokens, contract verification for **Chain 138**. Public, no login for browse. |
| `docs.d-bis.org` | Web | Same Blockscout nginx host as explorer where configured; may serve docs paths (see explorer deploy runbooks). |
| `dbis-admin.d-bis.org` | Web | DBIS **admin** frontend (dashboard). |
| `secure.d-bis.org` | Web | DBIS **secure** authenticated portal. |
| `dbis-api.d-bis.org` | API | DBIS **core API** (aggregation, OTC, exchange JSON). |
| `dbis-api-2.d-bis.org` | API | Secondary DBIS API instance. |
| `mim4u.org`, `www.mim4u.org`, `secure.mim4u.org`, `training.mim4u.org` | Web | **MIM4U** property sites (nginx on MIM stack). |
| `rpc-http-pub.d-bis.org`, `rpc.d-bis.org`, `rpc2.d-bis.org` | RPC-HTTP | **Public Besu JSON-RPC** (Chain 138); `eth_chainId` → `0x8a`. |
| `rpc-ws-pub.d-bis.org`, `ws.rpc.d-bis.org`, `ws.rpc2.d-bis.org` | RPC-WS | **Public Besu WebSocket** RPC. |
| `rpc-http-prv.d-bis.org` | RPC-HTTP | **Core / private** JSON-RPC (permissioned use). |
| `rpc-ws-prv.d-bis.org` | RPC-WS | **Core / private** WebSocket RPC. |
| `rpc-fireblocks.d-bis.org` | RPC-HTTP | **Fireblocks-dedicated** JSON-RPC endpoint. |
| `ws.rpc-fireblocks.d-bis.org` | RPC-WS | **Fireblocks-dedicated** WebSocket RPC. |
| `rpc-alltra.d-bis.org`, `rpc-alltra-2.d-bis.org`, `rpc-alltra-3.d-bis.org` | RPC-HTTP | **Alltra** RPC fronts (tunnel to NPM); JSON-RPC for Chain 138 (or as configured on those edges). |
| `rpc-hybx.d-bis.org`, `rpc-hybx-2.d-bis.org`, `rpc-hybx-3.d-bis.org` | RPC-HTTP | **HYBX** RPC fronts; same class as Alltra. |
| `cacti-alltra.d-bis.org`, `cacti-hybx.d-bis.org` | Web | **Cacti** monitoring UI (graphs, device views). |
| `mifos.d-bis.org` | Web | **Mifos** banking platform UI (when backend healthy). |
| `dapp.d-bis.org` | Web | **DApp** static/hosted frontend (VMID per ALL_VMIDS). |
| `gitea.d-bis.org` | Web | **Gitea** git forge UI. |
| `dev.d-bis.org` | Web | **Dev** workspace UI (codespaces / dev host). |
| `codespaces.d-bis.org` | Web | **Codespaces / dev** related web entry (as wired on NPM). |
---
## defi-oracle.io (ThirdWeb / public edge)
| FQDN | Kind | What should be displayed or returned |
|------|------|--------------------------------------|
| `rpc.public-0138.defi-oracle.io` | RPC-HTTP | **ThirdWeb-style HTTPS RPC** terminator on VMID 2400; JSON-RPC to Chain 138. |
| `rpc.defi-oracle.io` | RPC-HTTP | Public JSON-RPC alias (same Besu public stack as `rpc.d-bis.org` family when healthy). |
| `wss.defi-oracle.io` | RPC-WS | Public WebSocket RPC companion. |
**Note:** `blockscout.defi-oracle.io` is a **separate Blockscout** hostname (generic / reference). Not the canonical DBIS explorer; same class of **web** explorer UI as Blockscout. See EXPECTED_WEB_CONTENT.
---
## xom-dev.phoenix.sankofa.nexus (gov portals dev)
| FQDN | Kind | What should be displayed or returned |
|------|------|--------------------------------------|
| `dbis.xom-dev.phoenix.sankofa.nexus` | Web | Gov portals **dev** app on port **3001** (VMID 7804 family). |
| `iccc.xom-dev.phoenix.sankofa.nexus` | Web | Idem, port **3002**. |
| `omnl.xom-dev.phoenix.sankofa.nexus` | Web | Idem, port **3003**. |
| `xom.xom-dev.phoenix.sankofa.nexus` | Web | Idem, port **3004**. |
---
## Operator checklist
- **Wrong content** (e.g. explorer UI on `sankofa.nexus`, or HTML on RPC hostname) usually means **NPM upstream** or **DNS** is wrong — fix with `update-npmplus-proxy-hosts-api.sh` and [ALL_VMIDS_ENDPOINTS.md](ALL_VMIDS_ENDPOINTS.md).
- **301 on `www.*`** is intentional; content is judged on the **apex** hostname after redirect.
---
**Inventory alignment:** Public hostnames above follow `DOMAIN_TYPES_ALL` in `scripts/verify/verify-end-to-end-routing.sh` plus `keycloak.sankofa.nexus`, `docs.d-bis.org`, `blockscout.defi-oracle.io`, and xom-dev hosts. **`admin.sankofa.nexus`**, **`portal.sankofa.nexus`**, and **`dash.sankofa.nexus`** are **product-intent** hostnames—add to NPM and the E2E script when upstreams are wired. Add new rows here when you add NPM hosts.

29
docs/11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md Normal file
View File

@@ -0,0 +1,29 @@
# Complete Credential and eIDAS program — repository authority
**Last Updated:** 2026-03-25
**Purpose:** Single **proxmox-repo** pointer for where Complete Credential and **eIDAS SAML connector** source and runbooks live, so deployment truth is not inferred only from chat or scattered ADRs.
---
## Canonical program umbrella
- **Complete Credential** (umbrella program): integration and governance docs typically live in the **Complete Credential** / **DBIS** documentation space (e.g. `complete-credential` umbrella on Gitea). Clone path on operator workstations is often a **sibling** of `proxmox`, not a submodule of this repo.
## eIDAS receiving Member State connector (reference implementation)
- **Component:** SAML **Attribute Consumer Service (ACS)** / connector skeleton (e.g. `cc-eidas-connector` in the Complete Credential monorepo or submodule).
- **This `proxmox` repo:** contains **orchestration, DNS, NPM, Chain 138**, and **Sankofa Phoenix** service descriptions — **not** the Android or Java connector source tree unless explicitly added as a submodule later.
## Machine-readable registry
Authoritative **IDs, doc roles, and clone hints** for automation and runbooks:
[`config/public-sector-program-manifest.json`](../../config/public-sector-program-manifest.json)
## Related architecture baseline
- [PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md](../02-architecture/PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md)
- Phoenix **service catalog** contract (implementation may be out-of-tree): Complete Credential `docs/integrations/PHOENIX_SERVICE_CATALOG_SPEC.md`; machine-readable SKUs: [public-sector-program-manifest.json](../../config/public-sector-program-manifest.json) (`catalogSkus`).
---
**Note:** Default `repoUrl` values in the manifest point at `https://gitea.d-bis.org/Sankofa_Phoenix/…`. If a repo name differs on Gitea, update [`config/public-sector-program-manifest.json`](../../config/public-sector-program-manifest.json).