docs: Ledger Live integration, contract deploy learnings, NEXT_STEPS updates

- ADD_CHAIN138_TO_LEDGER_LIVE: Ledger form done; public code review repo bis-innovations/LedgerLive; init/push commands - CONTRACT_DEPLOYMENT_RUNBOOK: Chain 138 gas price 1 gwei, 36-addr check, TransactionMirror workaround - CONTRACT_*: AddressMapper, MirrorManager deployed 2026-02-12; 36-address on-chain check - NEXT_STEPS_FOR_YOU: Ledger done; steps completable now (no LAN); run-completable-tasks-from-anywhere - MASTER_INDEX, OPERATOR_OPTIONAL, SMART_CONTRACTS_INVENTORY_SIMPLE: updates - LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE: bis-innovations/LedgerLive reference Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-12 15:46:57 -08:00
parent cc8dcaf356
commit fbda1b4beb
5114 changed files with 498901 additions and 4567 deletions
--- a/docs/gru-m1/GRU_M1_MASTER_IMPLEMENTATION_PLAN.md
+++ b/docs/gru-m1/GRU_M1_MASTER_IMPLEMENTATION_PLAN.md
@@ -0,0 +1,289 @@
+# GRU M1 Master Implementation, Testing & Dry-Run Plan
+
+**Last Updated:** 2026-01-31  
+**Document Version:** 1.0  
+**Status:** Active Documentation
+
+---
+
+## Executive Objective
+
+This master plan defines the **end-to-end implementation, testing, and dry-run simulation framework** for launching and validating **GRU M1 compliant settlement instruments (`cISO(C/T)`)** and their **public listings on CoinMarketCap (CMC) and CoinGecko (CG)**.
+
+The plan is designed to:
+
+* Ensure successful third-party listing approval
+* Validate data integrity under real-world market conditions
+* Prevent misclassification, delays, or red flags
+* Produce auditable evidence suitable for institutional, banking, and sovereign review
+
+This document assumes:
+
+* **All `cISO(C/T)` instruments are GRU M1**
+* **All are externally classified as stablecoins / fiat-pegged assets**
+* **CMC/CG methodology is authoritative for public market representation**
+
+---
+
+## Phase I - Canonical Definition & Governance Lock
+
+### 1.1 Naming & Symbol Registry (Authoritative)
+
+Establish and freeze the canonical naming standard:
+
+```
+Symbol: c + ISO-4217 + (C | T)
+```
+
+Examples:
+
+* cUSDC - Compliant USD Coin
+* cUSDT - Compliant USD Token
+* cEURC - Compliant EUR Coin
+
+**Governance Lock:**
+
+* No symbol changes post-submission
+* One ISO code = one unit of account
+* `c` explicitly denotes *compliance*, not wrapping
+
+Deliverables:
+
+* Symbol registry table
+* Naming rationale memo (1 page)
+
+---
+
+### 1.2 External Classification Mapping (CMC/CG-Facing)
+
+| Internal Reality | External Representation  |
+| ---------------- | ------------------------ |
+| GRU M1           | Stablecoin / Fiat-Pegged |
+| Coin (C)         | Native coin              |
+| Token (T)        | Contract token           |
+
+Rules:
+
+* Never reference GRU layers in listing forms
+* Never claim reserve status or dominance exemption
+
+Deliverables:
+
+* External classification matrix
+* Reviewer-safe terminology glossary
+
+---
+
+## Phase II - Issuance Architecture & Supply Controls
+
+### 2.1 Mint/Burn & Supply Disclosure
+
+Define and document:
+
+* Mint authority
+* Burn authority
+* Reserve backing logic
+* Circulating vs non-circulating supply
+
+Required fields (CMC/CG):
+
+* Circulating supply
+* Total supply
+* Max supply (if applicable)
+
+Deliverables:
+
+* Supply mechanics diagram
+* Mint/burn policy
+* Reserve attestation summary
+
+---
+
+### 2.2 Price & Peg Integrity Model
+
+Peg assumptions:
+
+* Target price = 1.0000 (unit of account)
+* Allowed variance band defined
+
+Controls:
+
+* Redemption mechanism
+* Market-making logic (if any)
+* Emergency peg defense policy
+
+Deliverables:
+
+* Peg maintenance memo
+* Stress scenarios
+
+---
+
+## Phase III - CMC & CoinGecko Listing Preparation
+
+### 3.1 Listing Application Package
+
+Prepare **separate but aligned** applications for CMC and CG:
+
+Core components:
+
+* Project description (reviewer-safe)
+* Explorer links
+* Contract / chain data
+* Supply verification documentation
+* Contact & legal entity info
+
+Deliverables:
+
+* CMC application draft
+* CoinGecko application draft
+
+---
+
+### 3.2 Red-Flag Avoidance Checklist
+
+Explicitly avoid:
+
+* "Algorithmic stablecoin" language
+* Yield or rebasing claims
+* Synthetic or derivative framing
+
+Required language:
+
+* "Fiat-referenced settlement instrument"
+* "Mint-and-burn against reserves"
+
+Deliverables:
+
+* Red-flag checklist
+* Approved description text
+
+---
+
+## Phase IV - Pre-Listing Simulation & Dry-Runs
+
+### 4.1 Internal Sandbox Environment
+
+Simulate:
+
+* Mint events
+* Burn events
+* Transfers
+* Explorer indexing
+* Supply updates
+
+Metrics monitored:
+
+* Supply consistency
+* Explorer lag
+* Indexer visibility
+
+Deliverables:
+
+* Sandbox logs
+* Supply reconciliation report
+
+---
+
+### 4.2 Market Data Simulation (Real-World Feeds)
+
+Use live market data to simulate:
+
+* Stablecoin dominance impact
+* Total market cap inclusion
+* BTC/ETH dominance shifts
+
+Scenarios:
+
+* Normal market
+* High volatility
+* Stablecoin expansion
+
+Deliverables:
+
+* Dominance impact model
+* Time-series charts
+
+---
+
+## Phase V - Post-Listing Monitoring & Validation
+
+### 5.1 Live Data Verification (T+1 / T+7 / T+30)
+
+Check:
+
+* Price correctness
+* Supply correctness
+* Category tagging
+* Market cap calculation
+
+Deliverables:
+
+* Verification checklists
+* Screenshot evidence
+
+---
+
+### 5.2 Incident Response Playbook
+
+Triggers:
+
+* Peg deviation
+* Supply mismatch
+* Misclassification
+
+Actions:
+
+* Immediate disclosure
+* Indexer communication
+* Corrective data submission
+
+Deliverables:
+
+* Incident response SOP
+
+---
+
+## Phase VI - Audit, Reporting & Institutional Readiness
+
+### 6.1 Audit-Ready Artifacts
+
+Produce:
+
+* Full methodology
+* Supply attestation history
+* Listing correspondence
+
+---
+
+### 6.2 Optional Enhancements
+
+* Ex-M1 dominance dashboards
+* Internal GRU balance sheet views
+* Regulator-ready disclosure packs
+
+---
+
+## Final Readiness Gate (Go / No-Go)
+
+Launch proceeds only if:
+
+* All dry-runs pass
+* No unresolved red flags
+* CMC & CG reviewers confirm understanding
+
+---
+
+## Related Documentation
+
+* [GRU M1 Real-Data Dominance Addendum](GRU_M1_REAL_DATA_DOMINANCE_ADDENDUM.md)
+* [GRU M1 Listing Dry-Run Runbook](../runbooks/GRU_M1_LISTING_DRY_RUN_RUNBOOK.md)
+* [CoinGecko Submission Guide](../04-configuration/coingecko/COINGECKO_SUBMISSION_GUIDE.md)
+* [Chain 138 Token Addresses](../11-references/CHAIN138_TOKEN_ADDRESSES.md)
+* [CMC & CoinGecko Reporting](../../smom-dbis-138/services/token-aggregation/docs/CMC_COINGECKO_REPORTING.md)
+
+---
+
+## Closing Statement
+
+This master plan ensures that **GRU M1 instruments are launched, listed, and monitored with the same rigor applied to institutional payment rails**, while remaining fully compatible with public crypto market data platforms.
--- a/docs/gru-m1/GRU_M1_REAL_DATA_DOMINANCE_ADDENDUM.md
+++ b/docs/gru-m1/GRU_M1_REAL_DATA_DOMINANCE_ADDENDUM.md
@@ -0,0 +1,174 @@
+# GRU M1 Real-Data Dominance Simulation & Peg Stress-Test Addendum
+
+**Last Updated:** 2026-01-31  
+**Document Version:** 1.0  
+**Status:** Active Documentation
+
+---
+
+## Purpose of This Addendum
+
+This addendum extends the **GRU M1 Master Implementation, Testing & Dry-Run Plan** by providing:
+
+1. A **real-data dominance simulation framework** using current Top-25 crypto market metrics as reference inputs
+2. A **table-driven supply & peg stress-test worksheet** suitable for dry-runs, audits, and pre-listing validation
+
+This addendum is designed to be **executable without internal GRU context by external reviewers**, while still satisfying GRU governance requirements.
+
+---
+
+## SECTION VII — Real-Data Dominance Simulation (Top-25 Referenced)
+
+### 7.1 Objective
+
+To simulate how the introduction and scaling of **GRU M1 stablecoins (`cISO(C/T)`)** affects:
+
+* Total crypto market capitalization
+* Stablecoin dominance
+* BTC / ETH dominance
+
+This simulation uses **current Top-25 market data as a baseline**, without modifying existing asset prices.
+
+---
+
+### 7.2 Baseline Inputs (Reference Snapshot)
+
+Baseline variables (to be populated from live data at run-time):
+
+| Variable              | Description                               |
+| --------------------- | ----------------------------------------- |
+| Total Market Cap      | Aggregate market cap of all crypto assets |
+| BTC Market Cap        | Market cap of Bitcoin                     |
+| ETH Market Cap        | Market cap of Ethereum                    |
+| Stablecoin Market Cap | Aggregate cap of existing stablecoins     |
+| BTC Dominance         | BTC cap / Total cap                       |
+| Stablecoin Dominance  | Stablecoin cap / Total cap                |
+
+**Note:** Values are frozen at simulation start to isolate GRU M1 impact.
+
+---
+
+### 7.3 Simulation Scenarios (Incremental Issuance)
+
+Each scenario introduces new GRU M1 supply while holding all other assets constant.
+
+| Scenario | Added GRU M1 Supply | Description                  |
+| -------- | ------------------- | ---------------------------- |
+| S0       | $0                  | Baseline (no GRU M1)         |
+| S1       | $100M               | Pilot issuance               |
+| S2       | $500M               | Early institutional usage    |
+| S3       | $1B                 | Regional settlement adoption |
+| S4       | $5B                 | Multi-jurisdiction usage     |
+| S5       | $10B                | Systemic settlement scale    |
+
+---
+
+### 7.4 Dominance Recalculation Logic
+
+For each scenario:
+
+```
+New Total Market Cap = Baseline Total + GRU M1 Supply
+New Stablecoin Cap = Baseline Stablecoin Cap + GRU M1 Supply
+BTC Dominance = BTC Cap / New Total
+Stablecoin Dominance = New Stablecoin Cap / New Total
+```
+
+No price changes are assumed.
+
+---
+
+### 7.5 Output Table (Simulation Results Template)
+
+| Scenario | Total Cap | Stablecoin Cap | BTC Dom % | ETH Dom % | Stablecoin Dom % |
+| -------- | --------- | -------------- | --------- | --------- | ---------------- |
+| S0       |           |                |           |           |                  |
+| S1       |           |                |           |           |                  |
+| S2       |           |                |           |           |                  |
+| S3       |           |                |           |           |                  |
+| S4       |           |                |           |           |                  |
+| S5       |           |                |           |           |                  |
+
+---
+
+### 7.6 Interpretation Guidance
+
+* BTC/ETH dominance declines mechanically as GRU M1 grows
+* No implication of speculative capital shift
+* Stablecoin dominance increases without volatility
+* Use **ex-M1 internal metrics** for risk analysis
+
+---
+
+## SECTION VIII — Supply & Peg Stress-Test Worksheet
+
+### 8.1 Objective
+
+To validate that each **cISO(C/T)** instrument maintains peg integrity and supply accuracy under stress.
+
+---
+
+### 8.2 Stress-Test Dimensions
+
+Each test isolates one failure mode.
+
+| Dimension         | Description                       |
+| ----------------- | --------------------------------- |
+| Supply Shock      | Rapid mint or burn                |
+| Redemption Shock  | Large redemption requests         |
+| Market Volatility | External crypto volatility        |
+| Liquidity Drain   | Reduced exchange liquidity        |
+| Operational Delay | Mint/burn latency                 |
+| Custody Event     | Temporary reserve inaccessibility |
+
+---
+
+### 8.3 Peg Stress-Test Worksheet (Per Instrument)
+
+| Test ID | Scenario        | Starting Supply | Stress Event | Peak Supply | Price Deviation | Recovery Time | Pass/Fail | Notes |
+| ------- | --------------- | --------------- | ------------ | ----------- | --------------- | ------------- | --------- | ----- |
+| P1      | Normal Ops      |                 |              |             |                 |               |           |       |
+| P2      | +20% Mint       |                 | Rapid mint   |             |                 |               |           |       |
+| P3      | -20% Burn       |                 | Large burn   |             |                 |               |           |       |
+| P4      | 10% Redemption  |                 | Withdrawals  |             |                 |               |           |       |
+| P5      | Liquidity Shock |                 | Thin books   |             |                 |               |           |       |
+| P6      | Ops Delay       |                 | Mint delay   |             |                 |               |           |       |
+
+---
+
+### 8.4 Acceptance Criteria (Hard Gates)
+
+| Metric                      | Threshold  |
+| --------------------------- | ---------- |
+| Peg Deviation               | ≤ ±0.50%   |
+| Recovery Time               | ≤ 24 hours |
+| Supply Reconciliation Error | 0          |
+| Unexplained Variance        | None       |
+
+Failure requires corrective action before listing or scaling.
+
+---
+
+## SECTION IX — Evidence & Reporting Artifacts
+
+For each dry-run, archive:
+
+* Input data snapshot
+* Completed simulation tables
+* Stress-test worksheets
+* Commentary on outcomes
+* Sign-off by operations & compliance
+
+---
+
+## Related Documentation
+
+* [GRU M1 Master Implementation Plan](GRU_M1_MASTER_IMPLEMENTATION_PLAN.md)
+* [Peg Stress-Test Worksheet](PEG_STRESS_TEST_WORKSHEET.md)
+* [GRU M1 Listing Dry-Run Runbook](../runbooks/GRU_M1_LISTING_DRY_RUN_RUNBOOK.md)
+
+---
+
+## Closing Note
+
+This addendum ensures that **GRU M1 instruments can be demonstrated to function predictably within public market data systems**, even at scale, without introducing instability, distortion, or misinterpretation.
--- a/docs/gru-m1/PEG_STRESS_TEST_WORKSHEET.md
+++ b/docs/gru-m1/PEG_STRESS_TEST_WORKSHEET.md
@@ -0,0 +1,70 @@
+# GRU M1 Peg Stress-Test Worksheet
+
+**Last Updated:** 2026-01-31  
+**Document Version:** 1.0  
+**Status:** Active Documentation
+
+---
+
+## Purpose
+
+This worksheet validates that each **cISO(C/T)** instrument (cUSDC, cUSDT, cEURC, etc.) maintains peg integrity and supply accuracy under stress. Use during dry-runs, pre-listing audits, and periodic validation.
+
+---
+
+## Acceptance Criteria (Hard Gates)
+
+| Metric                      | Threshold  | Notes                          |
+| --------------------------- | ---------- | ------------------------------ |
+| Peg Deviation               | ≤ ±0.50%   | Failure requires corrective action |
+| Recovery Time               | ≤ 24 hours | Time to return to peg band     |
+| Supply Reconciliation Error | 0          | On-chain supply = attested     |
+| Unexplained Variance        | None       | No unexplained supply changes  |
+
+---
+
+## Per-Instrument Worksheet Template
+
+**Instrument:** _________________ (e.g., cUSDC, cUSDT)  
+**Date:** _________________  
+**Tester:** _________________  
+**Dry-Run ID:** _________________
+
+### Test Cases (P1–P6)
+
+| Test ID | Scenario        | Starting Supply | Stress Event | Peak Supply | Price Deviation | Recovery Time | Pass/Fail | Notes |
+| ------- | --------------- | --------------- | ------------ | ----------- | --------------- | ------------- | --------- | ----- |
+| P1      | Normal Ops      |                 | —            |             |                 | —             |           |       |
+| P2      | +20% Mint       |                 | Rapid mint   |             |                 |               |           |       |
+| P3      | -20% Burn       |                 | Large burn   |             |                 |               |           |       |
+| P4      | 10% Redemption  |                 | Withdrawals  |             |                 |               |           |       |
+| P5      | Liquidity Shock |                 | Thin books   |             |                 |               |           |       |
+| P6      | Ops Delay       |                 | Mint delay   |             |                 |               |           |       |
+
+### Stress-Test Dimensions Reference
+
+| Dimension         | Description                       |
+| ----------------- | --------------------------------- |
+| Supply Shock      | Rapid mint or burn                |
+| Redemption Shock  | Large redemption requests         |
+| Market Volatility | External crypto volatility        |
+| Liquidity Drain   | Reduced exchange liquidity        |
+| Operational Delay | Mint/burn latency                 |
+| Custody Event     | Temporary reserve inaccessibility |
+
+---
+
+## Sign-Off
+
+| Role           | Name   | Date | Signature |
+| -------------- | ------ | ---- | --------- |
+| Operations     |        |      |           |
+| Compliance     |        |      |           |
+
+---
+
+## Related Documentation
+
+* [GRU M1 Real-Data Dominance Addendum](GRU_M1_REAL_DATA_DOMINANCE_ADDENDUM.md) — Section VIII
+* [GRU M1 Listing Validation](../compliance/GRU_M1_LISTING_VALIDATION.md)
+* [GRU M1 Listing Dry-Run Runbook](../runbooks/GRU_M1_LISTING_DRY_RUN_RUNBOOK.md)
--- a/docs/gru-m1/README.md
+++ b/docs/gru-m1/README.md
@@ -0,0 +1,61 @@
+# GRU M1 Listing & Validation
+
+**Last Updated:** 2026-01-31  
+**Document Version:** 1.0  
+**Status:** Active Documentation
+
+---
+
+## Overview
+
+This folder contains the **GRU M1 Master Implementation Plan** and supporting documents for launching and validating **GRU M1 compliant settlement instruments** (cUSDC, cUSDT, cEURC, etc.) and their public listings on **CoinMarketCap (CMC)** and **CoinGecko (CG)**.
+
+---
+
+## Documents
+
+| Document | Description |
+| -------- | ----------- |
+| [GRU_M1_MASTER_IMPLEMENTATION_PLAN.md](GRU_M1_MASTER_IMPLEMENTATION_PLAN.md) | End-to-end implementation, testing, and dry-run framework (6 phases) |
+| [GRU_M1_REAL_DATA_DOMINANCE_ADDENDUM.md](GRU_M1_REAL_DATA_DOMINANCE_ADDENDUM.md) | Real-data dominance simulation (Section VII) and peg stress-test worksheet (Section VIII–IX) |
+| [PEG_STRESS_TEST_WORKSHEET.md](PEG_STRESS_TEST_WORKSHEET.md) | Per-instrument peg stress-test template for dry-runs and audits |
+
+---
+
+## Quick Links
+
+### Runbooks & Procedures
+
+* [GRU M1 Listing Dry-Run Runbook](../runbooks/GRU_M1_LISTING_DRY_RUN_RUNBOOK.md) — Step-by-step dry-run procedures
+* [GRU M1 Listing Validation](../compliance/GRU_M1_LISTING_VALIDATION.md) — Acceptance gates and validation criteria
+
+### Configuration & Submission
+
+* [CoinGecko Submission Guide](../04-configuration/coingecko/COINGECKO_SUBMISSION_GUIDE.md) — cUSDC, cUSDT submission templates
+* [CMC & CoinGecko Reporting](../../smom-dbis-138/services/token-aggregation/docs/CMC_COINGECKO_REPORTING.md) — Token aggregation report API
+
+### References
+
+* [Chain 138 Token Addresses](../11-references/CHAIN138_TOKEN_ADDRESSES.md) — cUSDC, cUSDT contract addresses
+* [ISO-20022 E-Money Runbook](../runbooks/MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md) — GRU-M1 base money requirements
+
+---
+
+## Scripts
+
+| Script | Description |
+| ------ | ----------- |
+| [scripts/gru-m1/dominance-simulation.sh](../../scripts/gru-m1/dominance-simulation.sh) | Run Top-25 dominance simulation (S0–S5) |
+| [scripts/gru-m1/check-ciso-supply.sh](../../scripts/gru-m1/check-ciso-supply.sh) | On-chain supply reconciliation for cUSDC/cUSDT |
+
+---
+
+## Terminology
+
+| Term | Meaning |
+| ---- | ------- |
+| **cISO(C/T)** | Compliant fiat-referenced token: `c` + ISO-4217 currency + Coin (`C`) or Token (`T`) |
+| **cUSDC** | Compliant USD Coin |
+| **cUSDT** | Compliant USD Token |
+| **cEURC** | Compliant EUR Coin |
+| **GRU M1** | GRU base money layer; externally represented as stablecoin / fiat-pegged |