From b36cd43b1dc6be2dae8734999ba67c125bb12386 Mon Sep 17 00:00:00 2001 From: defiQUG Date: Tue, 12 May 2026 00:00:48 -0700 Subject: [PATCH] docs: MetaMask design corpus and GRU transport loader specification - Add GRU_TRANSPORT_LOADER_DESIGN_SPEC (API contract, phases, JSON vs tests). - Add METAMASK_PROVIDER_DESIGN_CORPUS (frozen decisions, doc taxonomy). - Cross-link matrix, MASTER_INDEX, EIP-747 checklist sections, cursor rules. - Reference spec from token-mapping-loader.cjs header; bump smom-dbis-138 for jest.config note. Co-authored-by: Cursor --- .../rules/project-doc-and-deployment-refs.mdc | 4 + config/token-mapping-loader.cjs | 4 + .../GRU_TRANSPORT_LOADER_DESIGN_SPEC.md | 165 ++++++++++++++++++ ..._ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md | 4 +- .../metamask/METAMASK_COMPLETE_TASK_LIST.md | 2 + ...P747_CONTRACT_METADATA_REFERENCE_PACKET.md | 9 + .../METAMASK_PROVIDER_DESIGN_CORPUS.md | 36 ++++ docs/MASTER_INDEX.md | 3 +- smom-dbis-138 | 2 +- 9 files changed, 226 insertions(+), 3 deletions(-) create mode 100644 docs/04-configuration/GRU_TRANSPORT_LOADER_DESIGN_SPEC.md create mode 100644 docs/04-configuration/metamask/METAMASK_PROVIDER_DESIGN_CORPUS.md diff --git a/.cursor/rules/project-doc-and-deployment-refs.mdc b/.cursor/rules/project-doc-and-deployment-refs.mdc index 3a5fa70e..81fc47b2 100644 --- a/.cursor/rules/project-doc-and-deployment-refs.mdc +++ b/.cursor/rules/project-doc-and-deployment-refs.mdc @@ -19,6 +19,10 @@ When answering token/PMM/deployment questions, prefer these docs over inferring **Master reference — MetaMask Money/mUSD ↔ GRU, provider cross-links, DefiLlama DODO `dfio_meta_main` TVL:** `docs/00-meta/METAMASK_GRU_DEFILLAMA_CHAIN138_MASTER_REFERENCE.md` — replay steps, upstream **DefiLlama/DefiLlama-Adapters#19198**, touchpoints JSON, and **Part G** remaining tasks. +**MetaMask / provider design corpus (frozen architecture vs execution checklists):** `docs/04-configuration/metamask/METAMASK_PROVIDER_DESIGN_CORPUS.md` + +**GRU transport loader (monorepo `token-mapping-loader.cjs` + overlay JSON):** `docs/04-configuration/GRU_TRANSPORT_LOADER_DESIGN_SPEC.md` + **Gaps and inconsistencies (audit):** `docs/11-references/COSMOS_CHAIN138_GAPS_AND_INCONSISTENCIES.md` **Optional Cosmos / IBC to Chain 138 (streams A–E):** `docs/11-references/COSMOS_ECOSYSTEM_CHAIN138_OPTIONAL_INTEGRATIONS_RUNBOOK.md` — templates: `config/cosmos-chain138-optional/README.md` diff --git a/config/token-mapping-loader.cjs b/config/token-mapping-loader.cjs index de6154db..7c8f6dff 100644 --- a/config/token-mapping-loader.cjs +++ b/config/token-mapping-loader.cjs @@ -2,6 +2,10 @@ * Load token mapping from config/token-mapping.json and config/token-mapping-multichain.json. * Used by relay service, bridge/LP tooling, and docs. Safe to publish (no secrets). * + * GRU Monetary Transport extensions (`getGruTransportMetadata`, `getActiveTransportPairs`, …) are + * specified in docs/04-configuration/GRU_TRANSPORT_LOADER_DESIGN_SPEC.md (design complete; optional + * implementation phases apply). + * * Usage: * const { getRelayTokenMapping, getTokenMappingForPair } = require('../config/token-mapping-loader.cjs'); * const map = getRelayTokenMapping(); // 138 -> Mainnet (chain138Address -> mainnetAddress) diff --git a/docs/04-configuration/GRU_TRANSPORT_LOADER_DESIGN_SPEC.md b/docs/04-configuration/GRU_TRANSPORT_LOADER_DESIGN_SPEC.md new file mode 100644 index 00000000..94365dd6 --- /dev/null +++ b/docs/04-configuration/GRU_TRANSPORT_LOADER_DESIGN_SPEC.md @@ -0,0 +1,165 @@ +# GRU Transport Loader — Design Specification + +Status: **design complete** (architecture, API contract, data flow, acceptance criteria, and delivery phases). **Implementation** remains in `config/token-mapping-loader.cjs` plus a pinned `config/gru-transport-active.json` (or successor path). + +Audience: engineers wiring `smom-dbis-138/services/token-aggregation` to the Proxmox monorepo config layer, CI maintainers, and operators recovering policy from git history. + +## 1. Purpose + +The token-aggregation service resolves GRU Monetary Transport policy through a **CommonJS loader** discovered at runtime (`repo-config-loader.ts`). Today the loader exposes token-mapping helpers only; GRU transport tests expect additional exports backed by an active-policy overlay JSON. + +Goals: + +- Single **machine-readable** source for which canonical↔mirrored pairs, bridge peers, gas families, and public pools are in scope for routing, exposure APIs, and MCP visibility. +- **Deterministic** enrichment: same JSON + same environment variables ⇒ same `getActiveTransportPairs()` and `getGruTransportMetadata()` shapes. +- **No secrets** in the loader or JSON; bridge addresses continue to resolve from environment variables referenced by policy (`env` fields), not from committed secrets. + +Non-goals: + +- Replacing on-chain truth or deployment-status probes. +- Encoding live outstanding balances in JSON (those remain runtime reads where implemented). + +## 2. Placement in the stack + +```mermaid +flowchart LR + subgraph proxmox ["Proxmox repo"] + JSON["config/gru-transport-active.json"] + CJS["config/token-mapping-loader.cjs"] + TM["config/token-mapping.json / token-mapping-multichain.json"] + end + subgraph smom ["smom-dbis-138 token-aggregation"] + RCL["repo-config-loader.ts"] + GT["gru-transport.ts"] + CCB["cross-chain-bridges.ts"] + API["bridge.ts / token-mapping.ts / report.ts"] + end + JSON --> CJS + TM --> CJS + CJS --> RCL + RCL --> GT + RCL --> CCB + GT --> API + CCB --> API +``` + +Resolution order for the loader path is already implemented in `resolveTokenMappingLoaderPath()` (env overrides `TOKEN_MAPPING_LOADER_PATH`, `GRU_TRANSPORT_LOADER_PATH`, `PROXMOX_TOKEN_MAPPING_LOADER_PATH`, then upward `cwd`/`__dirname` candidates). + +**Design decision:** keep one physical file `token-mapping-loader.cjs` and extend it (avoid a second loader file unless bundle size forces a split). Optional later: `config/gru-transport-loader.cjs` required from the main loader for modularity. + +## 3. Exported API contract + +### 3.1 Required for GRU transport gate + +These must exist on the same `module.exports` as the token-mapping functions **together** (see `gru-transport.ts` `loadGruTransportLoader`): + +| Export | Signature | Semantics | +|--------|-----------|-----------| +| `getGruTransportMetadata` | `() => object \| null` | Returns `system`, `terminology`, `enabledCanonicalTokens`, `enabledDestinationChains`, `gasAssetFamilies`, `gasRedeemGroups`, `gasProtocolExposure`, and a **`counts`** object aligned with consumers (see section 6). | +| `getActiveTransportPairs` | `() => array` | Returns fully shaped **GruTransportPair** objects (TypeScript names in `gru-transport.ts`) including join fields not stored denormalized in JSON (selectors, chain names, bridge asset versions where applicable). | + +If either export is missing, `loadGruTransportLoader()` returns null and token-aggregation uses empty defaults for pairs (see existing fallbacks in `report.ts` / deployment-status paths). + +### 3.2 Required for routing registry integration + +`cross-chain-bridges.ts` expects the loader to optionally implement: + +| Export | Purpose | +|--------|---------| +| `getActiveTransportPair(fromChainId, toChainId, criteria)` | Return a single pair for GRU-priority routing (symbol in `criteria`). | +| `resolveConfigRef(ref)` | Resolve `{ env?: string, address?: string }` to a concrete `0x` address from `process.env`. | + +Without these, `getRouteFromRegistry` falls back to legacy registry behaviour for non-GRU assets. + +### 3.3 Optional but used when present + +| Export | Purpose | +|--------|---------| +| `getGasAssetFamilies` / `getGasRedeemGroups` / `getGasProtocolExposure` | Override or augment metadata slices. | +| `isGasRedemptionPathAllowed(fromChainId, toChainId, identifier)` | Gas redemption path policy. | +| `getActivePublicPools`, `isPublicPoolActive`, `isPublicPoolRoutable`, `isPublicPoolMcpVisible`, `shouldExposePublicPool`, `shouldUsePublicPoolForRouting` | Public pool gating (tests expect inactive pools on public chains to be hidden). | +| `getRoutingRegistryRoutes` | Non-GRU routing rows (already optional elsewhere). | + +## 4. Data sources + +### 4.1 Primary overlay + +**File:** `config/gru-transport-active.json` (repo root, same directory convention as other `config/*.json`). + +**Top-level keys** (authoritative schema for implementation; align with file when published): + +- `system`, `terminology`, `nonEvmTransport` +- `enabledCanonicalTokens`, `enabledDestinationChains`, `approvedBridgePeers`, `reserveVerifiers` +- `transportPairs` — dense list of pair **skeletons** (keys, symbols, peer keys, phase, flags, `maxOutstanding`, `publicPoolKeys`, etc.) +- `publicPools`, `gasAssetFamilies`, `gasRedeemGroups`, `gasProtocolExposure` + +**Recovery:** a large example revision exists in Proxmox git history: `git show 'stash@{2}:config/gru-transport-active.json'` (May 2026 codex branch stash). Do not treat stash content as canonical until reviewed and committed on `master`. + +### 4.2 Secondary joins + +Implementations **must** join skeleton `transportPairs` rows with: + +- `enabledDestinationChains` (for `destinationChainName`, CCIP `destinationChainSelector`, activation flags) +- `approvedBridgePeers` / peer templates (for `peer`, `l1Bridge` / `l2Bridge` config refs) +- Canonical token bridge metadata (for `bridgeCanonicalAssetVersion`, `bridgeMirroredAssetVersion` when policy stores them on token records rather than on each pair) + +Exact join keys are part of implementation; preserve outputs required by tests (section 6). + +### 4.3 Environment resolution + +`resolveConfigRef` reads `process.env[ref.env]` when `ref.env` is set; normalise to lowercase `0x` addresses for comparisons. Bridge and reserve readiness flags on each pair are derived by checking presence and format of resolved addresses plus optional numeric env reads (max outstanding, supply caps, etc.). + +**Design rule:** never throw from the loader; return empty strings or `false` for readiness when env is unset so APIs and tests get predictable “not ready” states. + +## 5. Policy vs regression tests (reconciliation) + +`smom-dbis-138/services/token-aggregation/src/config/gru-transport.test.ts` encodes **numeric and structural acceptance criteria**, including: + +- `getActiveTransportPairs().length === 44` +- Specific pair keys present or absent (e.g. `138-1111-cWEMIX-cWWEMIX` absent) +- `metadata.counts` values (`enabledDestinationChains`, `configuredTransportPairs`, `deferredTransportPairs`, gas counts, etc.) +- Gas redemption allow/deny examples +- Public pool visibility for a synthetic pool address on chain `56` + +A **prototype** `gru-transport-active.json` extracted from workspace stash contains **145** `transportPairs` rows (111 `wave1` + 34 `v1`, one deferred WEMIX). That row count **does not** match the 44-pair contract in tests. + +**Design decisions (pick one during implementation, document in changelog):** + +1. **Filter rule in loader** — Derive the 44-row public/eligible slice from the 145-row author file using explicit policy flags (requires schema fields or naming conventions not yet in every row). +2. **Trim author JSON** — Commit a **routing-surface** JSON that lists exactly the 44 pairs plus deferred metadata elsewhere; simpler loader. +3. **Adjust tests** — If business policy legitimately expands beyond 44, update golden assertions and counts in lockstep with JSON. + +Until reconciliation is executed, keep Jest gate: `RUN_GRU_TRANSPORT_LOADER_TESTS=1` (see `services/token-aggregation/jest.config.js`). + +## 6. Frozen acceptance criteria (regression lock) + +Implementation is complete when, with pinned JSON and extended loader, **all** of the following pass locally and in CI (non-exhaustive; see source file for full set): + +- File: `smom-dbis-138/services/token-aggregation/src/config/gru-transport.test.ts` +- File: `smom-dbis-138/services/token-aggregation/src/api/routes/token-mapping.test.ts` (GRU-gated) +- File: `smom-dbis-138/services/token-aggregation/src/api/routes/bridge.test.ts` (GRU-gated) + +**Recommendation:** after first green run, add a lightweight checksum of `gru-transport-active.json` into CI output or a test comment so accidental JSON drift is obvious. + +## 7. Delivery phases + +| Phase | Deliverable | Exit criterion | +|-------|-------------|----------------| +| A | Pin `config/gru-transport-active.json` on Proxmox `master` after legal/policy review | Valid JSON; schema documented; no secrets | +| B | Extend `token-mapping-loader.cjs` to read JSON and return **read-only** metadata + raw pairs without full enrichment | Smoke script or temporary unit test under `scripts/verify/` | +| C | Full enrichment + optional methods (section 3) | `RUN_GRU_TRANSPORT_LOADER_TESTS=1 npm run test:ci` passes in token-aggregation | +| D | Re-enable GRU suites in default `test:ci` (remove `testPathIgnorePatterns` gate) | Same tests pass without env flag | +| E (optional) | Share typed builder in TypeScript | Move join logic into `smom-dbis-138` package and thin-wrap from CJS, **only** if dual maintenance becomes painful | + +## 8. Security and performance + +- Loader runs in Node on every require; use **module-level cache** invalidated only by process restart (acceptable for serverless cold starts). +- JSON size may be large; prefer `fs.readFileSync` once + `JSON.parse` once. +- Do not log resolved env values. + +## 9. Related documents + +- Provider / wallet matrix (narrative, not loader): [metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md](metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md) +- MetaMask / GRU / DefiLlama master replay: [00-meta/METAMASK_GRU_DEFILLAMA_CHAIN138_MASTER_REFERENCE.md](00-meta/METAMASK_GRU_DEFILLAMA_CHAIN138_MASTER_REFERENCE.md) +- Token mapping loader source: [`config/token-mapping-loader.cjs`](../../config/token-mapping-loader.cjs) +- Type contracts: `smom-dbis-138/services/token-aggregation/src/config/gru-transport.ts` diff --git a/docs/04-configuration/metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md b/docs/04-configuration/metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md index 37d3710f..64de2ede 100644 --- a/docs/04-configuration/metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md +++ b/docs/04-configuration/metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md @@ -8,9 +8,11 @@ API feed spider-web packet: [METAMASK_CWUSDC_API_FEED_SPIDER_WEB_RESEARCH.md](ME Provider positioning packet: [../GRU_PROVIDER_POSITIONING_PACKET.md](../GRU_PROVIDER_POSITIONING_PACKET.md). +Design corpus (frozen architecture vs operator execution): [METAMASK_PROVIDER_DESIGN_CORPUS.md](METAMASK_PROVIDER_DESIGN_CORPUS.md). GRU transport overlay loader contract: [../GRU_TRANSPORT_LOADER_DESIGN_SPEC.md](../GRU_TRANSPORT_LOADER_DESIGN_SPEC.md). + Current execution focus: make Etherscan show USD Value for Ethereum Mainnet `cWUSDC` at `0x2de5F116bFcE3d0f922d9C8351e0c5Fc24b9284a`. Use [../etherscan/CWUSDC_ETHERSCAN_VALUE_EXECUTION_PLAN.md](../etherscan/CWUSDC_ETHERSCAN_VALUE_EXECUTION_PLAN.md) as the primary runbook. All other provider work is supporting evidence unless it directly helps Etherscan's trusted upstream price path. -Latest execution status: [../../../reports/status/cwusdc-provider-next-steps-execution-status-latest.md](../../../reports/status/cwusdc-provider-next-steps-execution-status-latest.md). Current public probes show Etherscan page, CMC DEX page, and GeckoTerminal pool APIs visible; CoinGecko token-price API and DexScreener token APIs are still external blockers. GeckoTerminal pool checks retry on HTTP 429 (see `scripts/verify/check-cwusdc-external-trackers-live.py` `--gecko-retries`). +Latest execution status: [../../../reports/status/cwusdc-provider-next-steps-execution-status-latest.md](../../../reports/status/cwusdc-provider-next-steps-execution-status-latest.md). Required public probes: Etherscan token page, CMC DEX, GeckoTerminal pools pass when indexed; **CoinGecko** token-price API remains the primary external gate until listed. **DexScreener** token-level v1 APIs are probed as **optional** supplementary indexing (`summary.dexScreenerTokenApisIndexed` in `cwusdc-external-trackers-live-latest.json`). GeckoTerminal pool checks retry on HTTP 429 (see `scripts/verify/check-cwusdc-external-trackers-live.py` `--gecko-retries`). Non-manual automation: `pnpm cwusdc:provider-checks` runs all public/read-only provider checks and writes `reports/status/cwusdc-provider-handoff-latest.md`; `pnpm cwusdc:provider-ci` is the CI-safe gate that fails only on repo-controlled prerequisites and reports external provider blockers as advisory. diff --git a/docs/04-configuration/metamask/METAMASK_COMPLETE_TASK_LIST.md b/docs/04-configuration/metamask/METAMASK_COMPLETE_TASK_LIST.md index 0a9616fc..bf078bd3 100644 --- a/docs/04-configuration/metamask/METAMASK_COMPLETE_TASK_LIST.md +++ b/docs/04-configuration/metamask/METAMASK_COMPLETE_TASK_LIST.md @@ -4,6 +4,8 @@ **Document Version:** 1.0 **Status:** Active Documentation +**Design note (2026-05-12):** Wallet + price-provider **architecture** for Chain 138 and Mainnet `cWUSDC` is frozen in [METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md](METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md) and [METAMASK_PROVIDER_DESIGN_CORPUS.md](METAMASK_PROVIDER_DESIGN_CORPUS.md). The long checklists below are a **historical / broad backlog** (RPC, DNS, examples, BD); they are not the authoritative gap list for the cWUSDC execution path. + --- **Date**: 2026-01-26 diff --git a/docs/04-configuration/metamask/METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md b/docs/04-configuration/metamask/METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md index 82e57465..fd154b75 100644 --- a/docs/04-configuration/metamask/METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md +++ b/docs/04-configuration/metamask/METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md @@ -173,6 +173,8 @@ Current repo policy: ## Implementation Checklist +### Repo implementation (design-complete) + - [x] Keep Chain 138 wallet payload live. - [x] Emit DBIS-hosted HTTPS logo URLs. - [x] Match V2 wallet symbols to on-chain symbols. @@ -180,12 +182,19 @@ Current repo policy: - [x] Add caveat that MetaMask fiat prices are upstream controlled. - [x] Add CoinGecko/CMC logo fields. - [x] Add supply proof and market-cap fields for tracker packets. + +### External operator checklist (not open design work) + +These are **execution** steps tracked in [METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md](METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md) and provider tickets; unchecked state does not indicate an undecided architecture. + - [ ] Submit/update Etherscan token profile. - [ ] Submit/update CoinGecko token profile. - [ ] Submit/update CMC token profile. - [ ] Submit/update DEX pair metadata where public indexed pools exist. - [ ] Optionally prepare MetaMask contract-metadata PR after Etherscan/tracker posture improves. +Design corpus index: [METAMASK_PROVIDER_DESIGN_CORPUS.md](METAMASK_PROVIDER_DESIGN_CORPUS.md). + ## References - MetaMask contract metadata: https://github.com/MetaMask/contract-metadata diff --git a/docs/04-configuration/metamask/METAMASK_PROVIDER_DESIGN_CORPUS.md b/docs/04-configuration/metamask/METAMASK_PROVIDER_DESIGN_CORPUS.md new file mode 100644 index 00000000..837986dd --- /dev/null +++ b/docs/04-configuration/metamask/METAMASK_PROVIDER_DESIGN_CORPUS.md @@ -0,0 +1,36 @@ +# MetaMask and Provider Surfaces — Design Corpus (Frozen) + +Status: **design work complete** for wallet metadata, price-path boundaries, CAIP discipline, and repo-vs-external responsibilities. Remaining work in linked documents is **execution** (operator submissions, external acceptance, liquidity), not undecided architecture. + +## Frozen decisions + +| Topic | Decision | Where captured | +|-------|----------|----------------| +| Primary wallet path for custom / Chain 138 assets | `wallet_addEthereumChain` + EIP-747 `wallet_watchAsset`; not MetaMask contract-metadata PRs as a blocker | [METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md](METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md), [METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md](METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md) | +| Fiat / USD value in MetaMask | Controlled by MetaMask upstream price providers; repo supplies evidence endpoints and tracker-shaped reports | Matrix sections *Bottom Line*, *MetaMask-Specific Interpretation*, *AssetsController* | +| Asset identity for tickets and tests | CAIP-19 for ERC-20 assets; parallel token-list form for EIP-747 | Matrix *Identifier Types*; EIP-747 packet *Exact cWUSDC Package* | +| Chain 138 token auto-detection | Not assumed; Chain 138 not listed as enhanced-detection network in MetaMask docs summary | EIP-747 packet | +| Snap install | Optional; allowlist is external gate; CSP/eval triage separated from Snap | EIP-747 packet *CSP and Snap Failure Triage* | +| GRU / mUSD narrative vs MetaMask product names | Internal alignment only until MetaMask publishes official bindings | Matrix *MetaMask Money rail and mUSD* | +| Mainnet `cWUSDC` execution focus | Etherscan Value path + CoinGecko listing as primary external gate | Matrix *Current execution focus*; [../etherscan/CWUSDC_ETHERSCAN_VALUE_EXECUTION_PLAN.md](../etherscan/CWUSDC_ETHERSCAN_VALUE_EXECUTION_PLAN.md) | +| GRU transport policy in monorepo | Loader + JSON design frozen; implementation tracked separately | [../GRU_TRANSPORT_LOADER_DESIGN_SPEC.md](../GRU_TRANSPORT_LOADER_DESIGN_SPEC.md) | + +## Document roles (taxonomy) + +| Artifact | Role | Checkbox / list meaning | +|----------|------|-------------------------| +| [METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md](METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md) | Canonical **tracker**: provider priority, status vocabulary, live URLs, submission order | Status columns (`repo_ready`, `blocked`, …) — not a personal todo list | +| [METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md](METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md) | **Rules + constraints** summary from MetaMask sources | `[x]` = repo implementation done; unchecked provider rows = **external operator checklist**, not open design questions | +| [CWUSDC_NON_MANUAL_PROVIDER_TASKS.md](../CWUSDC_NON_MANUAL_PROVIDER_TASKS.md) | Automation commands and CI-safe vs advisory gates | Execution / ops | +| [METAMASK_COMPLETE_TASK_LIST.md](METAMASK_COMPLETE_TASK_LIST.md) | Historical broad checklist (RPC, DNS, examples, BD) | **Superseded for cWUSDC wallet+price path** by the matrix + EIP-747 packet; keep for backlog ideas only | +| [ORACLE_PRICE_FEED_SETUP.md](ORACLE_PRICE_FEED_SETUP.md) | Infra checklist for oracle VM / contract | Operational bring-up, orthogonal to MetaMask provider ingestion | +| [SNAP_NPM_AND_ALLOWLIST_REVIEW.md](SNAP_NPM_AND_ALLOWLIST_REVIEW.md) | Snap submission hygiene | Pre-submit execution checklist | + +## Handoff to implementation + +- **GRU transport:** follow [../GRU_TRANSPORT_LOADER_DESIGN_SPEC.md](../GRU_TRANSPORT_LOADER_DESIGN_SPEC.md). +- **cWUSDC providers:** follow matrix submission order and `pnpm cwusdc:provider-checks` / `pnpm cwusdc:provider-ci` per [../CWUSDC_NON_MANUAL_PROVIDER_TASKS.md](../CWUSDC_NON_MANUAL_PROVIDER_TASKS.md). + +## Maintenance + +When MetaMask or upstream provider behaviour changes materially, update **this corpus** only if a **frozen decision** changes; otherwise update the matrix or EIP-747 packet and add a dated note in `reports/status/` if evidence is required. diff --git a/docs/MASTER_INDEX.md b/docs/MASTER_INDEX.md index 26cdfcba..ff1f5011 100644 --- a/docs/MASTER_INDEX.md +++ b/docs/MASTER_INDEX.md @@ -53,7 +53,8 @@ | **Machine-readable wrapper summaries** | [00-meta/REPO_LOCAL_RECOMMENDATIONS_STATUS.md](00-meta/REPO_LOCAL_RECOMMENDATIONS_STATUS.md) — canonical no-LAN, E2E, Chain 138, and LAN operator wrappers now support `--json-out` summaries under `reports/status/` for per-step timing/status capture | | **cW\* USD pricing (Ethereum Mainnet)** | [03-deployment/CW_TOKEN_USD_PRICING_RUNBOOK.md](03-deployment/CW_TOKEN_USD_PRICING_RUNBOOK.md) — accounting vs PMM vs reserve-implied; script [`scripts/deployment/price-cw-token-mainnet.sh`](../scripts/deployment/price-cw-token-mainnet.sh); multi-chain mid table [03-deployment/CW_PUBLIC_NETWORK_PRICES.md](03-deployment/CW_PUBLIC_NETWORK_PRICES.md) | | **Etherscan “Value” $0 (Mainnet `cW*`)** | [04-configuration/coingecko/ETHERSCAN_USD_VALUE_MAINNET_TOKENS.md](04-configuration/coingecko/ETHERSCAN_USD_VALUE_MAINNET_TOKENS.md), [04-configuration/etherscan/CWUSDC_ETHERSCAN_VALUE_EXECUTION_PLAN.md](04-configuration/etherscan/CWUSDC_ETHERSCAN_VALUE_EXECUTION_PLAN.md), and [04-configuration/etherscan/CWUSDC_ETHERSCAN_BRIDGE_CROSSCHAIN_LAYER_MAP.md](04-configuration/etherscan/CWUSDC_ETHERSCAN_BRIDGE_CROSSCHAIN_LAYER_MAP.md) — focused Mainnet `cWUSDC` Value path, bridge/cross-chain evidence boundaries, and generated dossier at `reports/status/cwusdc-etherscan-value-dossier-latest.md` | -| **MetaMask / wallet price-provider submissions** | [04-configuration/metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md](04-configuration/metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md) (incl. **MetaMask Money / mUSD ↔ GRU hub and `cW*` transport** narrative), [00-meta/METAMASK_GRU_DEFILLAMA_CHAIN138_MASTER_REFERENCE.md](00-meta/METAMASK_GRU_DEFILLAMA_CHAIN138_MASTER_REFERENCE.md) (replay + maintenance), [04-configuration/GRU_PROVIDER_POSITIONING_PACKET.md](04-configuration/GRU_PROVIDER_POSITIONING_PACKET.md), [04-configuration/CWUSDC_PROVIDER_SUBMISSION_PACKET.md](04-configuration/CWUSDC_PROVIDER_SUBMISSION_PACKET.md), and [04-configuration/metamask/METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md](04-configuration/metamask/METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md) — canonical matrix, GRU/Chain 138 provider narrative, cWUSDC cross-provider packet, and source-summary packet for repo-controlled metadata, MetaMask EIP-747, Etherscan, CoinGecko, CMC, Chainlist, wallet registries, and provider acceptance tracking | +| **MetaMask / wallet price-provider submissions** | [04-configuration/metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md](04-configuration/metamask/METAMASK_ASSET_PRICE_PROVIDER_SUBMISSION_MATRIX.md) (incl. **MetaMask Money / mUSD ↔ GRU hub and `cW*` transport** narrative), [04-configuration/metamask/METAMASK_PROVIDER_DESIGN_CORPUS.md](04-configuration/metamask/METAMASK_PROVIDER_DESIGN_CORPUS.md) (**frozen design** vs execution checklist map), [00-meta/METAMASK_GRU_DEFILLAMA_CHAIN138_MASTER_REFERENCE.md](00-meta/METAMASK_GRU_DEFILLAMA_CHAIN138_MASTER_REFERENCE.md) (replay + maintenance), [04-configuration/GRU_PROVIDER_POSITIONING_PACKET.md](04-configuration/GRU_PROVIDER_POSITIONING_PACKET.md), [04-configuration/CWUSDC_PROVIDER_SUBMISSION_PACKET.md](04-configuration/CWUSDC_PROVIDER_SUBMISSION_PACKET.md), and [04-configuration/metamask/METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md](04-configuration/metamask/METAMASK_EIP747_CONTRACT_METADATA_REFERENCE_PACKET.md) — canonical matrix, design corpus index, GRU/Chain 138 provider narrative, cWUSDC cross-provider packet, and source-summary packet for repo-controlled metadata, MetaMask EIP-747, Etherscan, CoinGecko, CMC, Chainlist, wallet registries, and provider acceptance tracking | +| **GRU transport loader (monorepo config)** | [04-configuration/GRU_TRANSPORT_LOADER_DESIGN_SPEC.md](04-configuration/GRU_TRANSPORT_LOADER_DESIGN_SPEC.md) — API contract for `config/token-mapping-loader.cjs` + `config/gru-transport-active.json`, join/enrichment rules, Jest regression targets, phased delivery; pairs with `smom-dbis-138/services/token-aggregation/src/config/gru-transport.ts` | | **DefiLlama metrics ↔ Chain 138 (TVL + optional)** | [04-configuration/defillama/CHAIN138_DEFILLAMA_ECOSYSTEM_MAP.md](04-configuration/defillama/CHAIN138_DEFILLAMA_ECOSYSTEM_MAP.md), [11-references/DEFILLAMA_DFIO_META_MAIN_DODO_ADAPTER_TVL.md](11-references/DEFILLAMA_DFIO_META_MAIN_DODO_ADAPTER_TVL.md), [00-meta/METAMASK_GRU_DEFILLAMA_CHAIN138_MASTER_REFERENCE.md](00-meta/METAMASK_GRU_DEFILLAMA_CHAIN138_MASTER_REFERENCE.md) — maps [docs.llama.fi](https://docs.llama.fi/) metrics to repos, e-money framing vs methodology, **DODO `dfio_meta_main` TVL** (open upstream [DefiLlama/DefiLlama-Adapters#19198](https://github.com/DefiLlama/DefiLlama-Adapters/pull/19198)), and full operator replay; touchpoints JSON [`config/defillama-chain138-touchpoints.json`](../config/defillama-chain138-touchpoints.json); Gitea mirror helper [`scripts/deployment/mirror-github-fork-to-gitea.sh`](../scripts/deployment/mirror-github-fork-to-gitea.sh) | | **Mr. Promod Uniswap V2 first deployment target matrix** | [03-deployment/PROMOD_UNISWAP_V2_FIRST_DEPLOYMENT_TARGET_MATRIX.md](03-deployment/PROMOD_UNISWAP_V2_FIRST_DEPLOYMENT_TARGET_MATRIX.md) — exact first pair per chain, why it goes first, required tokens, and post-deploy commands | | **Mr. Promod Uniswap V2 phase order** | [03-deployment/PROMOD_UNISWAP_V2_PHASE_ORDER.md](03-deployment/PROMOD_UNISWAP_V2_PHASE_ORDER.md) — strict rollout order: phase 1 core rail, phase 2 full cW* wrapped mesh, phase 3 settlement rails | diff --git a/smom-dbis-138 b/smom-dbis-138 index c3ef31d8..6c0328b0 160000 --- a/smom-dbis-138 +++ b/smom-dbis-138 @@ -1 +1 @@ -Subproject commit c3ef31d8f31bf6fa09247adbd333f4494a0e47c4 +Subproject commit 6c0328b040b2e27d138be043fd46edb5170b0919