c336809676
Some checks failed
CI/CD Pipeline / Solidity Contracts (push) Failing after 1m3s
CI/CD Pipeline / Security Scanning (push) Successful in 2m18s
CI/CD Pipeline / Lint and Format (push) Failing after 34s
CI/CD Pipeline / Terraform Validation (push) Failing after 20s
CI/CD Pipeline / Kubernetes Validation (push) Successful in 22s
Deploy ChainID 138 / Deploy ChainID 138 (push) Failing after 40s
HYBX OMNL TypeScript & anchor / token-aggregation build + reconcile artifact (push) Failing after 49s
OMNL reconcile anchor / Run omnl:reconcile and upload artifacts (push) Failing after 21s
Validation / validate-genesis (push) Successful in 25s
Validation / validate-terraform (push) Failing after 21s
Validation / validate-kubernetes (push) Failing after 8s
Validation / validate-smart-contracts (push) Failing after 8s
Validation / validate-security (push) Failing after 1m11s
Validation / validate-documentation (push) Failing after 14s
Verify Deployment / Verify Deployment (push) Failing after 45s
Ship AddressActivityRegistry V1/V2, ISO20022IntakeGateway, Chain138ParticipantSurface, checkpoint hub contracts, checkpoint-core package, aggregator/indexer/sdk services, relay profile guards, M00 diamond bridge facet, and OMNL compliance contracts. Co-authored-by: Cursor <cursoragent@cursor.com>
99 lines
4.8 KiB
Markdown
99 lines
4.8 KiB
Markdown
# 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 |
|