# Chain 138 → Mainnet checkpoint (v2 maximum)

Upgradeable attestation hub replacing standalone `MainnetTether` + `TransactionMirror`.

**Architecture:** `docs/07-ccip/MAINNET_CHECKPOINT_MAXIMUM_ARCHITECTURE.md`  
**Roadmap:** `docs/07-ccip/MAINNET_CHECKPOINT_RECOMMENDATIONS_AND_ROADMAP.md`

## Contract map

| File | Role |
|------|------|
| `Chain138MainnetCheckpoint.sol` | UUPS hub: submit, CCIP, extensions, pause, relayer EIP-712 |
| `chain138/Chain138BatchEmitter.sol` | 138 commit + CCIP to mainnet |
| `LegacyCheckpointAdapter.sol` | Read-only v1 mirror + tether + v2 unified views |
| `AddressActivityRegistry.sol` | Mainnet participant credit/debit events (ETH wei + USD e8) for Etherscan log indexing |
| `AddressActivityRegistryV2.sol` | ISO 20022 / MT-103+ attestation (`PaymentAttested`: instructionId, UETR, payloadHash) |
| `ISO20022IntakeGateway.sol` | Relayer `submitInbound(CanonicalMessage)` for institutional ISO intake |
| `libraries/ExtensionIds.sol` | Canonical `registerExtension` ids |
| `libraries/CheckpointEIP712.sol` | Typed data for relayer / validators |
| `libraries/CheckpointLeaf.sol` | V1/V2 leaves + Merkle build/verify |
| `extensions/*` | Optional pluggable modules (11 shipped) |

## Extensions (all optional)

| ID (`ExtensionIds`) | Contract | Hooks |
|---------------------|----------|-------|
| `MIRROR_DETAIL` | `MirrorDetailExtension` | afterSubmit |
| `VALIDATOR_SIG` | `ValidatorSigVerifierExtension` | beforeSubmit (ECDSA) |
| `CONTENT_URI` | `AttestationURIExtension` | afterSubmit |
| `RATE_LIMIT` | `SubmitRateLimitExtension` | before/after |
| `TOKEN_FILTER` | `TokenTransferFilterExtension` | beforeSubmit (V2 ERC-20) |
| `CW_LINK` | `CwTransportLinkExtension` | afterSubmit (hints only) |
| `GOV_TIMELOCK` | `TimelockSubmitExtension` | beforeSubmit |
| `METRICS` | `MetricsExtension` | afterSubmit |
| `ZK_STATE_ROOT` | `ZkStateRootVerifierExtension` | beforeSubmit (stub) |
| `PAYMASTER_HINT` | `PaymasterHintExtension` | afterSubmit |
| `L2_ORACLE` | `L2OracleAdapterExtension` | afterSubmit |

## Hub API (highlights)

- `submitCheckpoint` / `submitCheckpointCommitment` / `submitCheckpointWithLeaves`
- `submitCheckpointByRelayer(header, …, submitterSignature)` — EIP-712 attestation
- `forceCheckpoint` — `EMERGENCY_ROLE`
- `getConfig()` / `getFullConfig()` / `getExtensionList()` (use per-batch `getCheckpoint` off-chain for ranges)
- `verifyPaymentInBatch` — core Merkle + extension `verifyLeaf`

## Deploy

Use scoped forge (`FORGE_SCOPE=mainnet-checkpoint`, profile `mainnet-checkpoint`) via repo wrappers:

```bash
# From proxmox repo root (gate + env loaded automatically)
bash scripts/deployment/deploy-checkpoint-mainnet-hub.sh          # fund deployer >= 0.003 ETH
bash scripts/deployment/configure-checkpoint-mainnet-hub.sh
bash scripts/deployment/deploy-checkpoint-extensions-mainnet.sh
bash scripts/deployment/register-checkpoint-extensions-mainnet.sh
bash scripts/deployment/deploy-checkpoint-batch-emitter-138.sh
bash scripts/deployment/deploy-address-activity-registry.sh   # mainnet AddressActivityRegistry (Etherscan participant logs)
bash scripts/deployment/deploy-address-activity-registry-v2.sh   # ISO MT-103 / pacs.008 attestation
bash scripts/deployment/deploy-iso20022-intake-gateway.sh   # optional ISO intake gateway
pnpm etherscan-v2:sync-touchpoints   # after registry env is set
```

Simulate without broadcast: `CHECKPOINT_DRY_RUN=1` on any wrapper above.

**AddressActivityRegistry** is deployed separately (not via `deploy-checkpoint-extensions-mainnet.sh`) to avoid duplicate registry addresses. See `docs/04-configuration/etherscan/CHAIN138_ETHERSCAN_V2_UNSUPPORTED_NETWORK_FRAMEWORK.md`.

## Services

| Service | Path |
|---------|------|
| Aggregator (batch=10) | `services/checkpoint-aggregator/` |
| Indexer REST | `services/checkpoint-indexer/` (`GET /v1/checkpoint/latest`, `/v2/api` Etherscan shim) |

## Tests & CI (run before every deploy)

```bash
# Full gate: compile + all tests + storage layout (+ optional env profile)
pnpm checkpoint:predeploy
pnpm checkpoint:predeploy:hub   # includes mainnet-hub env validation

# Deploy wrappers (gate runs automatically)
bash ../scripts/deployment/deploy-checkpoint-mainnet-hub.sh
bash ../scripts/deployment/configure-checkpoint-mainnet-hub.sh
bash ../scripts/deployment/deploy-checkpoint-batch-emitter-138.sh
```

Granular env reference: `config/checkpoint-hub.example.env`

## On-chain configuration

| API | Purpose |
|-----|---------|
| `applyConfig(HubConfig)` | Atomically set all hub tunables (preferred; per-field setters removed for bytecode size) |
| `getFullConfig()` | Read full `HubConfig` struct |
| `setConfig(...)` | Batch size / wait / flags only (subset) |
| `setExtensionActive` / `updateExtensionHooks` | Extension registry tuning |
| `applyEmitterConfig` (138) | Batch emitter CCIP destination |