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

chore: sync all changes to Gitea
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details

Browse Source 
- Config, docs, scripts, and backup manifests
- Submodule refs unchanged (m = modified content in submodules)

Made-with: Cursor
This commit is contained in:
defiQUG
2026-03-02 11:37:34 -08:00
parent ed85135249
commit b3a8fe4496
883 changed files with 73580 additions and 4796 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
docs/dbis-rail/DBIS_RAIL_ADDONS_CODE_COMPLETION_TASK_LIST.md Normal file
View File

@@ -0,0 +1,164 @@
# DBIS Rail Add-Ons — Full Code Completion Task List
**Purpose:** Single list of **all tasks required to generate the necessary code** to complete all DBIS Rail Add-Ons (Spec v1 + v1.5) and ensure a **full working and operational system**. Use this with [DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md](DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md) and [IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md](IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md).
**References:** [Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md), [Ledger Attestation v1.5](DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md), [Conversion Router Spec v1.5](DBIS_RAIL_CONVERSION_ROUTER_SPEC_V1_5.md), [Stablecoin Policy v1.5](DBIS_RAIL_STABLECOIN_POLICY_V1_5.md), [Hash Canonicalization v1.5](DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md).
---
## Phase 0 — Prerequisites and environment
| # | Task | Output / evidence |
|---|------|-------------------|
| 0.1 | Ensure Chain 138 RPC (VMID 2101) writable; use IP:port in `smom-dbis-138/.env` (e.g. `http://192.168.11.211:8545`). | RPC_URL_138 set; preflight passes. |
| 0.2 | Deployer funded; no stuck txs; POOL_MANAGER_ROLE and other roles as needed. | preflight-chain138-deploy.sh passes. |
| 0.3 | Run `./scripts/deployment/run-before-deploy-checks.sh` (build, test, config validation). | All steps pass. |
| 0.4 | Confirm validator layer: key segregation, multi-entity, monitoring, incident runbook (operational). | Documented in ops runbook. |
---
## Phase 1 — Base DBIS Rail contracts (Technical Spec v1)
| # | Task | Output / evidence |
|---|------|-------------------|
| 1.1 | Implement **DBIS_RootRegistry**: setComponent(bytes32, address), getComponent(bytes32), railVersion; ROOT_ADMIN; ComponentUpdated event. | Contract in `smom-dbis-138/contracts/` (e.g. `dbis/` or `rail/`). |
| 1.2 | Implement **DBIS_ParticipantRegistry**: Participant struct, registerParticipant, setParticipantStatus, add/removeOperationalWallet, isOperationalWallet, getParticipantByWallet; PARTICIPANT_ADMIN; events. | Contract; depends on 1.1 for RootRegistry address resolution or own admin. |
| 1.3 | Implement **DBIS_SignerRegistry** (v1.5-ready): addSigner(signer, category), removeSigner; **effectiveFromBlock** and **revokedAtBlock** per signer (storage + getters); setQuorum; isSigner(signer), isSignerActiveAtBlock(signer, blockNumber); validateSigners(signers); SIGNER_ADMIN; events (SignerAdded, SignerRemoved, QuorumUpdated). | Contract; Ledger Attestation add-on §4. |
| 1.4 | Implement **DBIS_SettlementRouter**: RootRegistry ref; usedMessageIds; policy (maxAmountPerMessage, corridor caps); paused; submitMintAuth(MintAuth, signatures). Validation: paused, chainId 138, verifyingContract, time window, replay, ParticipantRegistry (recipients operational + ACTIVE), **SignerRegistry: each recovered signer active at block.number** (effectiveFromBlock, revokedAtBlock). EIP-712 hash + recover signers + quorum/category. Effects: mark used, update caps, call GRU_MintController.mintFromAuthorization(auth). Events: SettlementRecorded, MintExecuted, MessageIdConsumed, RouterPaused. | Contract; Spec §6.4; Ledger Attestation §4.2. |
| 1.5 | Implement **DBIS_GRU_MintController**: settlementRouter address; gruTokenOrDiamond (or token address); paused; mintFromAuthorization(MintAuth) only callable by settlementRouter; mint amounts to recipients; emit events. | Contract; Spec §6.5. |
| 1.6 | Wire **RootRegistry**: set participantRegistry, signerRegistry, settlementRouter, gruMintController (via setComponent or constructor). | Deployment script or init script. |
| 1.7 | Add **ReentrancyGuard** and **CEI** in SettlementRouter and MintController; enforce caps before mint. | Code review / checklist §5. |
---
## Phase 2 — Mint path lock (audit readiness)
| # | Task | Output / evidence |
|---|------|-------------------|
| 2.1 | Remove or permanently disable **owner mint** on CompliantFiatToken / CompliantUSDT / CompliantUSDC (and any other GRU/c* token used for rail). Option: remove `mint(address,uint256)` or restrict to a dedicated “legacy” role that is never granted. | Contract change in `smom-dbis-138/contracts/`. |
| 2.2 | Grant **MINTER_ROLE** (or equivalent) on GRU/c* tokens **only** to DBIS_GRU_MintController address. Revoke any other minter. | Deployment or post-deploy script + doc. |
| 2.3 | (Optional) Implement **burn** path for post-mint reversal (Rulebook §5.3, Ledger Attestation §3.2): only ROUTER_ADMIN or designated role; call token burn or burnFrom. | Contract or extension; document in runbook. |
---
## Phase 3 — Stablecoin Reference Registry (Stablecoin Policy v1.5)
| # | Task | Output / evidence |
|---|------|-------------------|
| 3.1 | Implement **StablecoinReferenceRegistry** (on-chain): register(tokenAddress, symbol, issuerOrBridge, legalClaimType, redemptionPath, reserveDisclosureRef, riskTier, pauseAuthority); setStatus(tokenAddress, ACTIVE|SUSPENDED|REVOKED); getEntry(tokenAddress); STABLECOIN_REGISTRAR or admin role. | Contract. |
| 3.2 | Register cUSDT, cUSDC, and any other canonical stablecoins on Chain 138 with status ACTIVE; document redemption path and reserve disclosure. | Deployment script or admin script + doc. |
| 3.3 | (Conversion Router will use this in Phase 5) Ensure tokenOut/tokenIn resolution checks registry and status ACTIVE when policy applies. | Integration in Phase 5. |
---
## Phase 4 — Conversion Router (Conversion Router Spec v1.5)
| # | Task | Output / evidence |
|---|------|-------------------|
| 4.1 | Implement **venue allowlist**: mapping or contract that stores allowed venue ids (bytes32); addVenue/removeVenue; only ACTIVE venues accepted by Conversion Router. | Contract or part of Conversion Router. |
| 4.2 | Implement **quote issuer allowlist**: allowed quoteIssuer addresses; addQuoteIssuer/removeQuoteIssuer. | Contract or part of Conversion Router. |
| 4.3 | Implement **blocklist/denylist** hook: contract or oracle that returns whether an address is blocked; Conversion Router checks counterparty (and optionally intermediate) addresses before execution. | Contract or interface + implementation. |
| 4.4 | Implement **DBIS_ConversionRouter**: SwapAuth EIP-712 domain and struct; submitSwapAuth(SwapAuthorization, signatures). Validation: chainId 138, verifyingContract, deadline; venue in allowlist; quoteIssuer in allowlist; tokenOut (and tokenIn if required) in StablecoinReferenceRegistry with ACTIVE status; blocklist check; signatures quorum (2-of-4 small / 3-of-5 + COMPLIANCE large by amountIn threshold). Enforce minAmountOut on execution. | Contract; Conversion Router Spec §2, §3, §6, §7. |
| 4.5 | Emit **ConversionExecuted**(messageId, quoteHash, venue, tokenIn, tokenOut, amountIn, amountOut, quoteIssuer); optionally store quoteHash/messageId for audit. | Event + optional storage. |
| 4.6 | Implement execution policy enforcement: max slippage (revert if output < minAmountOut), deadline (revert if block.timestamp > deadline), and venue allowlist already enforced. | In 4.4. |
| 4.7 | Wire Conversion Router to **StablecoinReferenceRegistry**: resolve tokenOut/tokenIn via registry; revert if not registered or not ACTIVE. | In 4.4. |
---
## Phase 5 — Hash canonicalization and test vectors (Hash Canonicalization v1.5)
| # | Task | Output / evidence |
|---|------|-------------------|
| 5.1 | Publish **LEB.schema.json** (and optionally **LPA.schema.json**) under `docs/dbis-rail/schemas/` with fields and types per Hash Canonicalization doc. | JSON schema files. |
| 5.2 | Implement **canonicalization library** (TypeScript or JS): UTF-8 NFC, sorted keys (JSON canonical), fixed decimal and timestamp format, rounding policy; input LEB → canonical string → lebHash; input LPA → lpaId; input ISO bundle → isoHash. | Code in repo (e.g. `packages/canonicalization` or `scripts/`). |
| 5.3 | Implement **accountingRef** encoding per Rulebook §3.2: keccak256(ledgerSystemId, journalId, batchNumber, postingTimestamp, reserveAccountId); document encoding (ABI-packed or string) in ops; add to canonicalization lib or a small Solidity/JS helper. | Code + doc. |
| 5.4 | Add **test vectors** (input + expected hash) for LEB→lebHash, LPA→lpaId, ISO bundle→isoHash, accountingRef; runnable script (e.g. Node or Forge) that asserts expected hashes. | Script + optional test-vectors.json/md in `docs/dbis-rail/` or `test/`. |
| 5.5 | (Optional) Solidity helper or precompile for on-chain verification of accountingRef or isoHash from raw inputs if needed. | Optional. |
---
## Phase 6 — ISO Gateway and relayer (off-chain)
| # | Task | Output / evidence |
|---|------|-------------------|
| 6.1 | Implement **ISO Gateway** (off-chain): ingest ISO-20022 (pacs/camt/pain); run compliance (KYC/AML/sanctions/limits); post double-entry in ledger; compute accountingRef per Rulebook §3.2 and isoHash from canonical bundle; determine FundsStatus per Good Funds Matrix; build MintAuth (EIP-712); request threshold signatures from allowlisted signers (3-of-5, COMPLIANCE mandatory). | Service (e.g. Node/TS or existing backend). |
| 6.2 | Implement **MintAuth relayer**: receive signed MintAuth + signatures; submit to DBIS_SettlementRouter.submitMintAuth(auth, signatures) on Chain 138. | Script or service. |
| 6.3 | (Optional) **SwapAuth flow**: build SwapAuthorization; get quote (RFQ/TWAP/aggregator); compute quoteHash; get signer signatures (2-of-4 or 3-of-5+COMPLIANCE per amount); submit to DBIS_ConversionRouter.submitSwapAuth. | Optional. |
| 6.4 | Document **signer key management**: HSM or equivalent, key rotation, emergency revoke and key compromise drill (Rulebook §6.4, Ledger Attestation §4.3). | Runbook in repo or ops. |
---
## Phase 7 — Testing
| # | Task | Output / evidence |
|---|------|-------------------|
| 7.1 | **Unit tests** (Forge): RootRegistry, ParticipantRegistry, SignerRegistry (add/remove, effectiveFromBlock/revokedAtBlock, validateSigners, isSignerActiveAtBlock), SettlementRouter (submitMintAuth success/revert: replay, expired, wrong chain, wrong signer set, quorum, participant not ACTIVE, signer not active at block), GRU_MintController (only router, pause), StablecoinReferenceRegistry, Conversion Router (venue/quoteIssuer allowlist, blocklist, SwapAuth validation, ConversionExecuted). | Tests in `smom-dbis-138/test/`. |
| 7.2 | **Integration test**: full MintAuth flow (deploy all, register participant, add signers, submit MintAuth with valid signatures → mint; submit same messageId again → revert). | Single integration test. |
| 7.3 | **Integration test**: signer revoked at block N; MintAuth signed before N, submitted at block >= N → revert. | Test for Ledger Attestation §4. |
| 7.4 | **Integration test**: Conversion Router — SwapAuth with venue not allowlisted → revert; with blocklisted counterparty → revert; with tokenOut not ACTIVE in StablecoinReferenceRegistry → revert. | Tests. |
| 7.5 | **Canonicalization tests**: run test vector script; assert lebHash, lpaId, isoHash, accountingRef match expected values. | Script or test in repo. |
---
## Phase 8 — Deployment and configuration
| # | Task | Output / evidence |
|---|------|-------------------|
| 8.1 | **Deploy script** (Forge): deploy RootRegistry → ParticipantRegistry → SignerRegistry → SettlementRouter → GRU_MintController; set RootRegistry components; grant MINTER to MintController on GRU/c* tokens; revoke other minters. | Script in `smom-dbis-138/script/deploy/`. |
| 8.2 | Deploy **StablecoinReferenceRegistry**; register cUSDT, cUSDC (and others); set ACTIVE. | Same or separate script. |
| 8.3 | Deploy **DBIS_ConversionRouter**; set venue allowlist, quote issuer allowlist, blocklist (or stub); link StablecoinReferenceRegistry. | Script. |
| 8.4 | Configure **RootRegistry** with Conversion Router and Stablecoin Registry addresses if they are part of the same “rail” component set (or document separately). | Config/doc. |
| 8.5 | **Post-deploy**: revoke owner mint on c* tokens (or deploy new token implementation and migrate); grant MINTER_ROLE only to DBIS_GRU_MintController. | Script + verification. |
| 8.6 | Update **CONTRACT_ADDRESSES_REFERENCE.md** and .env with all new addresses (RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController, StablecoinReferenceRegistry, Conversion Router). | Docs + env example. |
---
## Phase 9 — Operational and monitoring
| # | Task | Output / evidence |
|---|------|-------------------|
| 9.1 | **Runbooks**: emergency revoke (SignerRegistry revokedAtBlock), key compromise drill, router pause, mint controller pause, participant suspension, corridor suspension (Rulebook §7, Ledger Attestation §4.3). | Markdown in `docs/` or ops repo. |
| 9.2 | **Monitoring**: peg deviation thresholds for stablecoins (alert/auto-halt per Stablecoin Policy §4.1); bridge health for bridged stablecoins (§4.2); emergency corridor halt procedure (§4.3). | Config + runbook. |
| 9.3 | **Audit trail**: ensure messageId ↔ iso evidence ↔ accountingRef mapping retained off-chain; SettlementRecorded and MintExecuted (and ConversionExecuted) queryable; signer/participant change events logged. | Already in Spec; confirm ops. |
| 9.4 | **Threat Model review**: schedule (e.g. annual) and document; on quorum change, new corridor, or validator model change (Threat Model §6). | Doc. |
---
## Phase 10 — Optional enhancements
| # | Task | Output / evidence |
|---|------|-------------------|
| 10.1 | Idempotency extension: allow resubmission of same messageId with “duplicate accepted” event (Spec §9). | SettlementRouter logic. |
| 10.2 | Periodic Merkle root of SettlementRecorded (and optionally ConversionExecuted) for proof-of-reserves-style attestations. | Contract or off-chain job. |
| 10.3 | On-chain validator governance (rotation + emergency pause) or document operational governance (Spec §3.2, Completion Master B4). | Contract or doc. |
| 10.4 | Public Overview PDF (2–3 pages) for business development (Completion Master B5). | PDF. |
| 10.5 | SOC 2 / ISO 27001 control mapping expansion (Completion Master B6). | Doc. |
| 10.6 | Independent code audit of DBIS Rail contracts (Completion Master B7). | External. |
---
## Summary — Dependency order
```text
Phase 0 (prereqs)
→ Phase 1 (base rail contracts, including SignerRegistry v1.5 + SettlementRouter signer-at-block check)
→ Phase 2 (mint path lock)
→ Phase 3 (StablecoinReferenceRegistry)
→ Phase 4 (Conversion Router; depends on 3 for registry check)
→ Phase 5 (canonicalization + test vectors; can run in parallel with 1–4 for schema/vectors)
→ Phase 6 (ISO Gateway + relayer; depends on 1–2 for MintAuth, 4 for SwapAuth optional)
→ Phase 7 (testing; depends on 1–5, optionally 6 for E2E)
→ Phase 8 (deployment)
→ Phase 9 (ops + monitoring)
→ Phase 10 (optional)
```
---
## Document control
| Field | Value |
|-------|-------|
| Title | DBIS Rail Add-Ons — Full Code Completion Task List |
| Version | 1 |
| Status | Active |

156
docs/dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md Normal file
View File

@@ -0,0 +1,156 @@
# DBIS Rail and Project Completion Master — Status and Full Task List v1
**Purpose:** Single reference for (1) current project and deployment status and (2) the complete list of tasks to reach audit-ready DBIS Rail and full project completion — **including all optional items**.
**Companion:** [Audit Readiness Results v1](DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md), [Deployment Order of Operations](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md), [Complete Required/Optional/Recommended Index](../00-meta/COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md).
**Implementation coordination:** Align all implementations with [Implementation Coordination with Transcript 540ae663](IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md). That transcript completed PMM/DEX (pools, DODOPMMProvider), 10 compliant fiat tokens on Chain 138, GRU registration for all 12 c*, UniversalAssetRegistry upgrade, cWUSDT/cWUSDC on 9 chains, and related scripts/docs. The coordination doc maps which tasks below are already done or partial.
---
## Part 1 — Current Status
### 1.1 Chain 138 deployments (existing)
| Category | Status | Notes |
|----------|--------|------|
| **Core / genesis** | Deployed | WETH9, WETH10, Multicall pre-deployed. |
| **Core contracts** | Deployed | UniversalAssetRegistry, GovernanceController, UniversalCCIPBridge, BridgeOrchestrator, CREATE2Factory, MirrorRegistry, AlltraAdapter. |
| **CCIP** | Deployed | CCIP Router, Sender, CCIPWETH9Bridge, CCIPWETH10Bridge; relay path to mainnet. |
| **Compliance and tokens** | Deployed | ComplianceRegistry, TokenFactory, DebtRegistry, PolicyManager; cUSDT, cUSDC, plus cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT (10 extra via DeployCompliantFiatTokens). c* have **owner mint** (DBIS Rail requires router-only mint). |
| **Bridges and vault** | Deployed | Bridge Vault, Lockbox138, ReserveSystem, ReserveTokenIntegration; RegulatedEntityRegistry, VaultFactory, Ledger, Liquidation, XAU Oracle. |
| **Channels** | Deployed | PaymentChannelManager, GenericStateChannelManager, AddressMapper, MirrorManager. |
| **PMM / DEX** | Deployed | DODOPMMIntegration, DODOPMMProvider; TransactionMirror; three PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC). |
| **Registry** | Deployed | ChainRegistry; UniversalAssetRegistry upgraded (registerGRUCompliantAsset); all 12 c* registered as GRU via RegisterGRUCompliantTokens. |
| **Other** | Deployed | MultiSig, Oracle Aggregator/Proxy, CCIPReceiver, Voting; MerchantSettlementRegistry, WithdrawalEscrow (alltra-lifi-settlement). |
| **Not deployed** | Pending | EnhancedSwapRouter; full trustless stack (InboxETH, BondManager, etc.) on mainnet; DBIS Rail contracts (RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController). |
**Source:** [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md), [GALATIC_SUMMARY](../GALATIC_SUMMARY.md).
### 1.2 DBIS Rail status
| Layer | Status | Notes |
|-------|--------|------|
| **Documentation** | Complete | Spec, Rulebook, Threat Model, Regulator Brief, Audit Readiness Checklist, Results, Control Mapping. |
| **Contracts (code)** | Not implemented | No DBIS_RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController in repo. |
| **Mint path** | Gap | GRU/c* on 138 use owner mint (CompliantFiatToken, CompliantUSDT, CompliantUSDC). Rail requires router-only mint. |
| **Signer / ISO Gateway** | Documented only | Quorum (3-of-5, COMPLIANCE), EIP-712, accountingRef, isoHash defined in Spec/Rulebook; no on-chain signer registry or router. |
| **Validator layer** | Partial | QBFT documented; key segregation, multi-entity, monitoring, incident runbook to be confirmed in ops. |
### 1.3 Project-wide (non–DBIS Rail)
| Area | Status | Notes |
|------|--------|------|
| **Deployment order** | Phase 0–3 applicable | Prerequisites, core, TransactionMirror + PMM pools, provider + liquidity; Phase 4–6 optional. |
| **Verification** | Ongoing | check-contracts-on-chain-138.sh; Blockscout verify; address docs. |
| **Operator / Wave 0–3** | Partially done | NPMplus, backup, sendCrossChain, validation scripts; full Wave 2/3 and recommendations per index. |
| **Optional deployments** | Not done | EnhancedSwapRouter, trustless stack mainnet, CCIP other chains, cW* edge pools (Phase 4–5). |
| **Recommendations** | Many open | R1–R24; ~139 items in ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST; optional VLAN, HA, MetaMask/explorer. |
---
## Part 2 — Full Task List (Required and Optional)
Every task below is to be completed; optional items are explicitly marked so prioritization (required first, then optional) is clear.
---
### A. DBIS Rail — Required (audit readiness)
| # | Task | Evidence / reference |
|---|------|----------------------|
| A1 | Implement and deploy DBIS Rail contracts (RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController) per [Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md). | Spec §2.1, §6; [Audit Results](DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md) § Gap remediation. |
| A2 | Lock GRU/c* mint on Chain 138 to SettlementRouter only: revoke or remove owner mint for rail tokens; grant mint only to DBIS_GRU_MintController with Router as sole caller. | Audit Results §1; CompliantFiatToken.sol, CompliantUSDT, CompliantUSDC. |
| A3 | Add unit and integration tests: direct mint revert, EIP-712 and replay, quorum/category, pause, caps. | Audit Results §2, §5; Checklist §1, §2, §5. |
| A4 | Document signer key management (HSM or equivalent, key rotation) in operational runbook. | Audit Results §3; Checklist §3. |
| A5 | Add accountingRef test vector (and optionally isoHash) per Rulebook; document canonical bundle schema in ops. | Audit Results §4; Rulebook §3.2, §4.4. |
| A6 | Confirm validator layer: key segregation, multi-entity or separation of duties, monitoring, incident runbook. | Audit Results §6; Checklist §6. |
| A7 | Run emergency control drills after rail deployment (router pause, mint controller pause, participant suspension, signer revocation, corridor suspension); record results. | Audit Results §7; Checklist §7; Rulebook §7. |
| A8 | Schedule Threat Model review (e.g. within 12 months) and document review date. | Audit Results §8; Threat Model §6. |
| A9 | When rail contracts are deployed: confirm Spec version matches deployment; add Deployed section or changelog. | Audit Results §8; Checklist §8. |
---
### B. DBIS Rail — Optional (v1.5+ and institutional hardening)
| # | Task | Evidence / reference |
|---|------|----------------------|
| B1 | Implement signer effective-from and revoked-at block semantics (v1.5+); router rejects signatures outside effective window. | Rulebook §6.2; Threat Model §3.A. |
| B2 | Implement idempotency extension: allow resubmission of same messageId with duplicate-accepted event (or keep revert as default). | Spec §9; Rulebook. |
| B3 | Add periodic Merkle root of SettlementRecorded events for external proof exports / proof-of-reserves-style attestations. | Threat Model §3.C (recommendation); Spec. |
| B4 | Implement on-chain validator governance (rotation + emergency pause) or document operational governance and timelock path. | Spec §0, §3.2; Regulator Brief §2; Threat Model §3.E. |
| B5 | Publish DBIS Rail — Public Overview (2–3 page PDF) for business development and counterparties. | Prior conversation: optional, high signal. |
| B6 | Expand control mapping to full SOC 2 / ISO 27001–style matrix (control ID, control objective, evidence, owner). | [Control Mapping v1](DBIS_RAIL_CONTROL_MAPPING_V1.md); Checklist. |
| B7 | Commission independent code audit of DBIS Rail contracts after deployment. | Audit Results; institutional readiness. |
---
### C. Project deployment — Required (Chain 138 and verification)
| # | Task | Evidence / reference |
|---|------|----------------------|
| C1 | Ensure Phase 0 prerequisites: RPC 2101 writable, deployer funded, .env correct, POOL_MANAGER_ROLE, no stuck txs, forge build, test all contracts before deploy. | [DEPLOYMENT_ORDER_OF_OPERATIONS](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) Phase 0. **Partial:** preflight, run-before-deploy-checks, test-all-contracts exist ([coordination](IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md)). |
| C2 | Complete Phase 2 if not done: TransactionMirror, all three PMM pools, register c* as GRU; set addresses in .env. | DEPLOYMENT_ORDER_OF_OPERATIONS Phase 2. **Done** per [coordination](IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md). |
| C3 | Complete Phase 3: DODOPMMProvider deploy and pool registration; token-aggregation env; optional liquidity and MCP allowlist. | DEPLOYMENT_ORDER_OF_OPERATIONS Phase 3. **Done** per [coordination](IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md). |
| C4 | Run on-chain verification: `./scripts/verify/check-contracts-on-chain-138.sh`; target 38/38 when applicable. | DEPLOYMENT_ORDER_OF_OPERATIONS Phase 6.1. |
| C5 | Run Blockscout verification: `./scripts/verify/run-contract-verification-with-proxy.sh`; update CONTRACT_ADDRESSES_REFERENCE and LIQUIDITY_POOLS_MASTER_MAP. | DEPLOYMENT_ORDER_OF_OPERATIONS Phase 6.2–6.3; R1–R3. |
| C6 | Reconcile Multicall vs Oracle Aggregator at `0x99b3511a2d315a497c8112c1fdd8d508d4b1e506` on explorer and document in CONTRACT_ADDRESSES_REFERENCE. | CONTRACT_ADDRESSES_REFERENCE note. |
---
### D. Project deployment — Optional (Phase 4–6 and beyond)
| # | Task | Evidence / reference |
|---|------|----------------------|
| D1 | Deploy EnhancedSwapRouter (Chain 138) when Uniswap V3 / Balancer pools exist; configure post-deploy. | DEPLOYMENT_ORDER_OF_OPERATIONS Phase 4.1; GALATIC_SUMMARY. |
| D2 | Deploy trustless stack (Lockbox138 + Mainnet): InboxETH, BondManager, etc.; set INBOX_ETH, BOND_MANAGER in config. | DEPLOYMENT_ORDER_OF_OPERATIONS Phase 4.2; OPTIONAL_DEPLOYMENTS_START_HERE. |
| D3 | CCIP other chains (Gnosis, Celo, Wemix): deploy WETH bridges per chain; add 138↔chain; fund LINK. | DEPLOYMENT_ORDER_OF_OPERATIONS Phase 4.3. |
| D4 | LINK on Mainnet relay: add LINK support per relay runbook. | DEPLOYMENT_ORDER_OF_OPERATIONS Phase 4.4. |
| D5 | Phase 5 — cW* edge pools: per-chain RPC/env; deploy or bridge cW* tokens; create and fund PMM pools per pool-matrix (11 public chains). | DEPLOYMENT_ORDER_OF_OPERATIONS Phase 5. **Partial:** cWUSDT/cWUSDC deployed on 9 chains; mapping and runbook in place ([coordination](IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md)). |
| D6 | Execute full recommendations R1–R24 and update address docs, runbooks, monitoring, testing, token mapping. | [RECOMMENDATIONS_OPERATOR_CHECKLIST](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md); Phase 6.4. |
| D7 | Optional: run full recommendations list (~139 items) per ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST; OPERATOR_READY_CHECKLIST for copy-paste commands. | [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST](../00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md); Phase 6.5. |
---
### E. Project operational — Optional (Wave 0–3 and infra)
| # | Task | Evidence / reference |
|---|------|----------------------|
| E1 | Wave 0: NPMplus RPC fix (405), sendCrossChain (real), NPMplus backup when LAN/creds available. | [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX](../00-meta/COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md); run-wave0-from-lan.sh. |
| E2 | Wave 1: Run validation (run-all-validation.sh, validate-config-files.sh); complete "Can Be Accomplished Now" steps. | COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX; REMAINING_WORK_DETAILED_STEPS. |
| E3 | Wave 2 / Wave 3: Operator checklist (Proxmox, CCIP, Blockscout, maintenance, liquidity). | [WAVE2_WAVE3_OPERATOR_CHECKLIST](../00-meta/WAVE2_WAVE3_OPERATOR_CHECKLIST.md). |
| E4 | Optional infrastructure: Phase 1 VLAN; NPMplus HA; optional containers. | OPTIONAL_RECOMMENDATIONS_INDEX; NPMPLUS_HA_SETUP_GUIDE. |
| E5 | Optional docs/tooling: documentation consolidation; Paymaster deploy when ready. | COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX. |
| E6 | Optional MetaMask/explorer: token-aggregation, CoinGecko submission, Snap features, explorer enhancements. | COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX; COINGECKO_SUBMISSION. |
| E7 | Still-not-done execution: operator/LAN, dbis_core TS (deferred), security-audit, external (Ledger, CoinGecko), maintenance. | [STILL_NOT_DONE_EXECUTION_CHECKLIST](../00-meta/STILL_NOT_DONE_EXECUTION_CHECKLIST.md). |
| E8 | Schedule and install daily/weekly cron for maintenance (schedule-daily-weekly-cron.sh --install). | COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX. |
---
### F. Identity and chain metadata — Optional
| # | Task | Evidence / reference |
|---|------|----------------------|
| F1 | Update chain metadata so "DBIS Mainnet (Chain 138)" is the authoritative public identity (e.g. eip155-138.json, ChainList, explorer branding, token list name). | Regulator Brief; prior DBIS identity discussion. |
| F2 | Publish Regulator Brief (or Public Overview) as standalone PDF for examiners and counterparties. | Regulator Brief v1; optional Public Overview. |
---
## Part 3 — Suggested execution order
1. **DBIS Rail required (A1–A9):** Unblocks audit readiness; A1–A2 are prerequisites for A3, A7.
2. **Project deployment required (C1–C6):** Ensures Chain 138 and verification are current.
3. **DBIS Rail optional (B1–B7):** v1.5+ and institutional hardening as capacity allows.
4. **Project deployment optional (D1–D7):** Phase 4–6 and full recommendations.
5. **Project operational optional (E1–E8):** Wave 0–3, infra, MetaMask/explorer, still-not-done.
6. **Identity optional (F1–F2):** Chain naming and PDF publication.
---
## Document control
| Field | Value |
|-------|--------|
| Title | DBIS Rail and Project Completion Master — Status and Full Task List v1 |
| Version | 1 |
| Status | Active |

133
docs/dbis-rail/DBIS_RAIL_AUDIT_READINESS_CHECKLIST_V1.md Normal file
View File

@@ -0,0 +1,133 @@
# DBIS Rail — Audit Readiness Checklist v1
**Network:** DBIS Mainnet (ChainID 138)
**Document type:** Control verification checklist (pre-audit)
**Companion documents:** [Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md), [Rulebook v1](DBIS_RAIL_RULEBOOK_V1.md), [Security Threat Model v1](DBIS_RAIL_SECURITY_THREAT_MODEL_V1.md), [Regulator Brief v1](DBIS_RAIL_REGULATOR_BRIEF_V1.md)
**Purpose:** Bridge documentation to operational evidence. Each item is verifiable (code, config, procedure, or test). Use this checklist before external audit or formal control mapping.
---
## 1. Mint Path Integrity
- [ ] All GRU mint roles restricted to SettlementRouter (or Mint Controller called only by Router)
- [ ] Owner mint revoked (no direct owner / MINTER_ROLE mint on GRU/c* tokens except via Router path)
- [ ] No upgrade path allows mint bypass (Mint Controller and token upgrade logic do not introduce alternate mint entry)
- [ ] Unit tests confirm revert on direct mint (e.g., mint call from non-Router address reverts)
**Evidence:** Contract code review, deployment config, test suite results.
---
## 2. Authorization Integrity
- [ ] EIP-712 domain separation validated (domain hash includes chainId 138 and SettlementRouter address)
- [ ] chainId hardcoded or enforced = 138 in MintAuth validation
- [ ] verifyingContract enforced (MintAuth.verifyingContract equals SettlementRouter address)
- [ ] messageId replay protection tested (second submit with same messageId reverts)
- [ ] Expired auth rejected (submission with block.timestamp outside notBefore/expiresAt reverts)
- [ ] Cross-chain replay rejected (auth signed for other chainId or contract fails verification)
- [ ] Quorum category enforcement tested (auth with insufficient signers or missing COMPLIANCE reverts)
**Evidence:** Router contract code, EIP-712 test vectors, integration tests.
---
## 3. Signer Governance
- [ ] 3-of-5 quorum enforced on-chain (SignerRegistry and Router require 3 distinct allowlisted signers)
- [ ] Compliance category mandatory (category mask or validation requires COMPLIANCE signer)
- [ ] Signer allowlist change emits event (e.g., SignerAdded, SignerRemoved)
- [ ] Signer revocation documented (procedure in Rulebook or ops runbook)
- [ ] HSM usage documented (or secure key storage for signer keys)
- [ ] Key rotation procedure documented (how signers are added/removed and keys rotated)
**Evidence:** SignerRegistry and Router code, Rulebook/runbook, key management documentation.
---
## 4. Accounting and Evidence
- [ ] accountingRef deterministic structure documented (Rulebook Section 3.2: keccak256 of ledgerSystemId, journalId, batchNumber, postingTimestamp, reserveAccountId)
- [ ] accountingRef reproducible in test vector (same inputs produce same accountingRef)
- [ ] isoHash reproducible from canonical bundle (schema and hashing rule documented; test vector exists)
- [ ] messageId to accountingRef mapping validated (operational procedure and/or audit trail)
- [ ] One-to-one mint mapping verified (one accountingRef / messageId per mint unless documented exception)
**Evidence:** Rulebook, test vectors, operational procedures, sample audit trail.
---
## 5. Router Controls
- [ ] ReentrancyGuard active (or equivalent; no reentrancy into Router state during submitMintAuth)
- [ ] CEI pattern followed (state updates before external call to Mint Controller)
- [ ] Caps enforced before mint (total amount and corridor usage checked and updated before mint call)
- [ ] Pause modifier functional (when paused, submitMintAuth reverts)
- [ ] Corridor limits enforced (daily or per-corridor cap checked and incremented correctly)
**Evidence:** SettlementRouter contract code, unit/integration tests for pause and caps.
---
## 6. Validator Layer
- [ ] Validator keys segregated (keys not shared with application/signer layer)
- [ ] Multi-entity validator operation (or documented single-entity with separation of duties)
- [ ] Monitoring active (block production, finality, node health)
- [ ] Block finality assumptions documented (QBFT threshold, no reorg of finalized blocks)
- [ ] Incident runbook exists (validator outage, consensus issue, or chain halt)
**Evidence:** Validator config, monitoring dashboards/alerts, ops runbook.
---
## 7. Emergency Controls
- [ ] Router pause tested (ROUTER_ADMIN can pause; submitMintAuth reverts when paused)
- [ ] Mint controller pause tested (mint path reverts or no-op when Mint Controller paused)
- [ ] Participant suspension tested (suspended participant wallets cannot receive new mints)
- [ ] Signer revocation tested (revoked signer signature no longer counts toward quorum)
- [ ] Corridor suspension tested (if supported: corridor cap zero or flag prevents new settlements in corridor)
**Evidence:** Test runs or drill results, contract code for pause and participant/signer checks.
---
## 8. Documentation Integrity
- [ ] Spec version matches deployed contracts (Technical Spec v1 reflects current Router, Mint Controller, registries)
- [ ] Rulebook version current (Rulebook v1 reflects good funds matrix, accountingRef, reversal and signer rules in use)
- [ ] Threat model reviewed within last 12 months (Security Threat Model v1 review date recorded)
- [ ] Regulator brief reflects current quorum and governance (Regulator Brief v1 matches 3-of-5, Compliance mandatory, Router-gated mint)
**Evidence:** Version and date in each doc; change log or review record.
---
## Completion and Sign-Off
| Section | Completed | Date | Verified by |
|---------|-----------|------|-------------|
| 1. Mint Path Integrity | | | |
| 2. Authorization Integrity | | | |
| 3. Signer Governance | | | |
| 4. Accounting and Evidence | | | |
| 5. Router Controls | | | |
| 6. Validator Layer | | | |
| 7. Emergency Controls | | | |
| 8. Documentation Integrity | | | |
**Checklist status:** Pre-audit control sheet. Complete all items and retain evidence before engaging external audit or formal control mapping (e.g., SOC 2, ISO 27001).
---
## Document Control
| Field | Value |
|-------|--------|
| Title | DBIS Rail — Audit Readiness Checklist v1 |
| Network | DBIS Mainnet (ChainID 138) |
| Purpose | Control verification checklist (pre-audit) |
| Version | 1 |
| Status | Active |

162
docs/dbis-rail/DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md Normal file
View File

@@ -0,0 +1,162 @@
# DBIS Rail — Audit Readiness Results v1
**Network:** DBIS Mainnet (ChainID 138)
**Document type:** Checklist run results and gap remediation
**Companion:** [Audit Readiness Checklist v1](DBIS_RAIL_AUDIT_READINESS_CHECKLIST_V1.md)
**Run date:** First run (baseline).
**Purpose:** Record current status of each checklist section and list concrete remediation steps to reach audit-ready state.
---
## Summary
| Section | Status | Notes |
|---------|--------|--------|
| 1. Mint Path Integrity | Gap | DBIS Rail contracts not deployed; current GRU/c* use owner mint |
| 2. Authorization Integrity | Pending deployment | SettlementRouter and MintAuth flow not implemented |
| 3. Signer Governance | Pending deployment | SignerRegistry not implemented; Rulebook documented |
| 4. Accounting and Evidence | Documented | Rulebook defines accountingRef and isoHash; no on-chain router to validate |
| 5. Router Controls | Pending deployment | No SettlementRouter to verify |
| 6. Validator Layer | Partial | QBFT documented; ops runbook and multi-entity to be confirmed |
| 7. Emergency Controls | Pending deployment | Pause/suspension logic in contracts not deployed |
| 8. Documentation Integrity | Complete | Spec, Rulebook, Threat Model, Regulator Brief, Checklist aligned |
**Overall:** Documentation stack is complete and consistent. DBIS Rail contracts (RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController) are specified but not yet implemented in the repo. Current Chain 138 GRU/c* mint path is owner-based (CompliantFiatToken, CompliantUSDT, CompliantUSDC). Closing gaps requires implementing and deploying the rail contracts and locking mint to the router.
---
## 1. Mint Path Integrity
| Item | Status | Evidence / note |
|------|--------|------------------|
| All GRU mint roles restricted to SettlementRouter | Pending deployment | No DBIS_GRU_MintController or SettlementRouter in repo. Existing [CompliantFiatToken.sol](../../smom-dbis-138/contracts/tokens/CompliantFiatToken.sol) has `mint(address to, uint256 amount) public onlyOwner`. |
| Owner mint revoked | Gap | Owner mint is present on CompliantFiatToken (and likely CompliantUSDT/CompliantUSDC). Must be revoked or gated when rail is deployed. |
| No upgrade path allows mint bypass | Pending deployment | Mint Controller and upgrade path not implemented. When implemented, ensure only Router can call mint and upgrades are timelocked. |
| Unit tests confirm revert on direct mint | Pending deployment | No DBIS Rail contracts; no tests for router-only mint. |
**Remediation:** Deploy DBIS Rail contracts per Technical Spec. Restrict GRU/c* mint on Chain 138 to DBIS_GRU_MintController called only by SettlementRouter. Revoke or remove owner mint (and any other MINTER_ROLE) for tokens that are part of the rail. Add unit tests that direct mint from non-Router reverts.
---
## 2. Authorization Integrity
| Item | Status | Evidence / note |
|------|--------|------------------|
| EIP-712 domain separation validated | Pending deployment | Spec defines EIP-712 domain (chainId 138, verifyingContract). No SettlementRouter to validate. |
| chainId = 138 enforced | Pending deployment | To be implemented in Router. |
| verifyingContract enforced | Pending deployment | To be implemented in Router. |
| messageId replay protection tested | Pending deployment | Replay pattern exists elsewhere (e.g. CCIPWETH9Bridge processedTransfers, EtherlinkRelayReceiver messageId). Not in DBIS Router. |
| Expired auth rejected | Pending deployment | To be implemented in Router (notBefore/expiresAt). |
| Cross-chain replay rejected | Pending deployment | EIP-712 domain binding will reject other chainId/contract. |
| Quorum category enforcement tested | Pending deployment | SignerRegistry and Router logic not implemented. |
**Remediation:** Implement SettlementRouter and SignerRegistry per Spec. Add EIP-712 validation, messageId replay map, time window check, and quorum/category checks. Add integration tests for valid auth, replay revert, expired revert, wrong chainId revert, and insufficient signers revert.
---
## 3. Signer Governance
| Item | Status | Evidence / note |
|------|--------|------------------|
| 3-of-5 quorum enforced on-chain | Pending deployment | SignerRegistry not in repo. |
| Compliance category mandatory | Pending deployment | To be implemented in SignerRegistry/Router. |
| Signer allowlist change emits event | Pending deployment | Spec defines SignerAdded, SignerRemoved. |
| Signer revocation documented | Documented | Rulebook Section 6 and Threat Model Section 3.F. |
| HSM usage documented | Operational | To be documented in ops/key management when signers are designated. |
| Key rotation procedure documented | Operational | To be documented in ops runbook. |
**Remediation:** Implement SignerRegistry with addSigner/removeSigner, category mask, and validateSigners. Document HSM (or equivalent) and key rotation in operational runbook.
---
## 4. Accounting and Evidence
| Item | Status | Evidence / note |
|------|--------|------------------|
| accountingRef deterministic structure documented | Complete | Rulebook Section 3.2: keccak256(ledgerSystemId, journalId, batchNumber, postingTimestamp, reserveAccountId). |
| accountingRef reproducible in test vector | Operational | Procedure and encoding must be fixed in ops; test vector can be added to repo or test suite. |
| isoHash reproducible from canonical bundle | Documented | Rulebook and Spec; canonical bundle schema to be fixed in ops; test vector optional. |
| messageId to accountingRef mapping validated | Operational | Rulebook Section 8; mapping maintained off-chain and auditable. |
| One-to-one mint mapping verified | Documented | Rulebook Section 3.3; enforced operationally until Router records on-chain. |
**Remediation:** Add a test vector (or script) that computes accountingRef from sample inputs per Rulebook. Document canonical bundle schema for isoHash in ops. No code gap for rail contracts; Router will accept accountingRef/isoHash when implemented.
---
## 5. Router Controls
| Item | Status | Evidence / note |
|------|--------|------------------|
| ReentrancyGuard active | Pending deployment | Spec and Threat Model require it. Existing [MintController.sol](../../smom-dbis-138/contracts/iso4217w/controllers/MintController.sol) and other contracts use ReentrancyGuard; DBIS Router to follow same pattern. |
| CEI pattern followed | Pending deployment | To be implemented in SettlementRouter (state updates before mint call). |
| Caps enforced before mint | Pending deployment | Spec: maxAmountPerMessage and corridor daily cap checked before calling Mint Controller. |
| Pause modifier functional | Pending deployment | Spec: paused flag and ROUTER_ADMIN. |
| Corridor limits enforced | Pending deployment | Spec: corridor usage tracking and check. |
**Remediation:** Implement SettlementRouter with nonReentrant (or equivalent), CEI, cap checks, pause modifier, and corridor limits. Add tests for pause revert and cap revert.
---
## 6. Validator Layer
| Item | Status | Evidence / note |
|------|--------|------------------|
| Validator keys segregated | Operational | To be confirmed; keys should not be shared with app/signer layer. |
| Multi-entity validator operation | Operational | To be confirmed or documented (single-entity with separation of duties acceptable). |
| Monitoring active | Partial | Monitoring referenced in docs; confirm block production and finality monitoring in place. |
| Block finality assumptions documented | Complete | Spec and Threat Model: QBFT, finality, no reorg of finalized blocks. |
| Incident runbook exists | Operational | General incident/validator runbook to be confirmed; DBIS Rail Rulebook Section 7 covers emergency controls. |
**Remediation:** Confirm validator key segregation and multi-entity (or equivalent) in ops. Ensure monitoring and validator/consensus incident runbook exist and reference rail pause where relevant.
---
## 7. Emergency Controls
| Item | Status | Evidence / note |
|------|--------|------------------|
| Router pause tested | Pending deployment | No Router. |
| Mint controller pause tested | Pending deployment | No DBIS Mint Controller. |
| Participant suspension tested | Pending deployment | No ParticipantRegistry. |
| Signer revocation tested | Pending deployment | No SignerRegistry. |
| Corridor suspension tested | Pending deployment | No Router corridor logic. |
**Remediation:** After deploying DBIS Rail contracts, run drills: pause Router, pause Mint Controller, suspend participant, revoke signer, suspend corridor (if supported). Record results and retain as evidence.
---
## 8. Documentation Integrity
| Item | Status | Evidence / note |
|------|--------|------------------|
| Spec version matches deployed contracts | N/A (no deployment) | Spec v1 is current. When contracts are deployed, confirm they match Spec. |
| Rulebook version current | Complete | Rulebook v1 current. |
| Threat model reviewed within last 12 months | Complete | Threat Model v1 in place; set review date when formally adopted. |
| Regulator brief reflects quorum and governance | Complete | Regulator Brief v1 matches 3-of-5, Compliance mandatory, Router-gated mint. |
**Remediation:** When DBIS Rail contracts are deployed, add a "Deployed" section or changelog to Spec (or deployment doc) and note version. Schedule Threat Model review (e.g. annual).
---
## Gap Remediation (Prioritized)
1. **Implement and deploy DBIS Rail contracts** (RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController) per Technical Spec. This unblocks Sections 1, 2, 3, 5, 7.
2. **Lock GRU/c* mint path on Chain 138** to SettlementRouter only: revoke owner mint (and any other direct mint) for tokens that are part of the rail; grant mint only to DBIS_GRU_MintController with Router as sole caller.
3. **Add tests** for mint path (direct mint reverts), EIP-712 and replay, quorum/category, pause, and caps.
4. **Document signer key management** (HSM or equivalent, key rotation) in operational runbook.
5. **Add accountingRef (and optionally isoHash) test vector** per Rulebook; document canonical bundle schema.
6. **Confirm validator layer** (key segregation, multi-entity or separation of duties, monitoring, incident runbook).
7. **Run emergency control drills** after deployment and record results in this document or appendix.
8. **Schedule Threat Model review** (e.g. within 12 months) and document review date.
---
## Document Control
| Field | Value |
|-------|--------|
| Title | DBIS Rail — Audit Readiness Results v1 |
| Network | DBIS Mainnet (ChainID 138) |
| Version | 1 |
| Status | Active (baseline run) |

55
docs/dbis-rail/DBIS_RAIL_CONTROL_MAPPING_V1.md Normal file
View File

@@ -0,0 +1,55 @@
# DBIS Rail — Control Mapping v1
**Network:** DBIS Mainnet (ChainID 138)
**Document type:** Mapping of controls to checklist, Spec, Rulebook, and Threat Model
**Companion:** [Audit Readiness Checklist v1](DBIS_RAIL_AUDIT_READINESS_CHECKLIST_V1.md), [Audit Readiness Results v1](DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md)
**Purpose:** Lightweight control mapping for internal audit and future SOC 2 / ISO 27001 alignment. Each control is traceable to a checklist section and to the governing document(s).
---
## Control summary
| ID | Control | Checklist | Spec | Rulebook | Threat Model |
|----|---------|-----------|------|----------|--------------|
| C1 | Mint path restricted to SettlementRouter | 1 | 6.5, 2.2 | 4, 5 | 3.D |
| C2 | Owner / direct mint revoked for GRU/c* | 1 | 6.5, 11 | 4 | 3.D |
| C3 | EIP-712 domain separation (chainId, verifyingContract) | 2 | 4.2, 7 | - | 3.A |
| C4 | messageId replay protection (one-time use) | 2 | 6.4 | 9 | 3.A |
| C5 | Time window (notBefore, expiresAt) enforced | 2 | 4.2, 6.4 | 4.6 | 3.A |
| C6 | Quorum and category (3-of-5, COMPLIANCE) enforced | 2, 3 | 6.3, 6.4 | 4.5, 6 | 3.A, 3.F |
| C7 | Signer allowlist and revocation | 3 | 6.3 | 6 | 3.A, 3.F |
| C8 | Deterministic accountingRef | 4 | - | 3.2 | 3.B |
| C9 | Evidence bundle hashed (isoHash) | 4 | 4.2, 5 | 4.4 | 3.B |
| C10 | One-to-one messageId / accountingRef / mint | 4 | 6.4 | 3.3, 8 | 3.B |
| C11 | ReentrancyGuard and CEI on Router | 5 | 6.4 | - | 3.C |
| C12 | Caps enforced before mint | 5 | 6.4 | - | 3.C |
| C13 | Router and Mint Controller pause | 5, 7 | 6.4, 6.5, 8 | 7 | 3.C, 3.D |
| C14 | Corridor limits enforced | 5, 7 | 6.4 | - | 3.C |
| C15 | Participant suspension (no mint to suspended) | 7 | 6.2, 6.4 | 7 | 3.F |
| C16 | Validator segregation and monitoring | 6 | 3 | - | 3.E |
| C17 | Good funds and finality (Rulebook) | 4 | 1, 4 | 2, 4 | 3.B, 5 |
| C18 | Documentation versioning and review | 8 | - | 9 | 6 |
Section numbers refer to the respective document sections (e.g. Spec 6.5 = DBIS_GRU_MintController, Rulebook 3.2 = deterministic accountingRef).
---
## References
- **Spec:** [DBIS_RAIL_TECHNICAL_SPEC_V1.md](DBIS_RAIL_TECHNICAL_SPEC_V1.md)
- **Rulebook:** [DBIS_RAIL_RULEBOOK_V1.md](DBIS_RAIL_RULEBOOK_V1.md)
- **Threat Model:** [DBIS_RAIL_SECURITY_THREAT_MODEL_V1.md](DBIS_RAIL_SECURITY_THREAT_MODEL_V1.md)
- **Checklist:** [DBIS_RAIL_AUDIT_READINESS_CHECKLIST_V1.md](DBIS_RAIL_AUDIT_READINESS_CHECKLIST_V1.md)
- **Results:** [DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md](DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md)
---
## Document control
| Field | Value |
|-------|--------|
| Title | DBIS Rail — Control Mapping v1 |
| Network | DBIS Mainnet (ChainID 138) |
| Version | 1 |
| Status | Active |

164
docs/dbis-rail/DBIS_RAIL_CONVERSION_ROUTER_SPEC_V1_5.md Normal file
View File

@@ -0,0 +1,164 @@
# DBIS Rail Conversion Router Spec v1.5
**Network:** DBIS Mainnet (ChainID 138)
**Document type:** v1.5 Add-on — Swap/conversion governance, best execution, MEV posture, sanctions/AML
**Companion documents:** [DBIS Rail Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md), [DBIS Rail Rulebook v1](DBIS_RAIL_RULEBOOK_V1.md), [DBIS Rail Stablecoin Policy v1.5](DBIS_RAIL_STABLECOIN_POLICY_V1_5.md)
---
## 1. Purpose and Scope
This add-on defines swap/conversion as **governed financial actions** on the DBIS Rail:
- **SwapAuthorization (SwapAuth)** — EIP-712 signed instruction for conversions, with quote provenance and venue allowlist.
- **Best execution and MEV posture** — Execution policy module, quote source priority, slippage and deadline enforcement.
- **Sanctions/AML coverage** — Venue allowlist, pool-address allowlisting, address screening (blocklist/denylist), Compliance signer for elevated swaps and new venues.
The goal is examiner-credible defensibility of execution quality and reasonable prevention of exposure to sanctioned actors or MEV loss.
---
## 2. SwapAuthorization (SwapAuth) — EIP-712
### 2.1 Struct
SwapAuthorization is a compact, deterministic struct signed by an allowlisted signer set, analogous to MintAuth for settlement.
```solidity
struct SwapAuthorization {
bytes32 messageId; // unique; ties to instruction or LPA if conversion is settlement-linked
bytes32 lpaId; // optional; reference to Ledger Posting Authorization if conversion is tied to a settlement
bytes32 venue; // keccak256(venueId) or approved venue identifier
address tokenIn;
address tokenOut;
uint256 amountIn;
uint256 minAmountOut; // minimum output for execution (slippage protection)
uint256 deadline; // unix timestamp; execution must occur before this
bytes32 quoteHash; // hash of the quote used (provenance)
address quoteIssuer; // approved quote source (must be on allowlist)
uint256 chainId; // MUST be 138
address verifyingContract; // Conversion Router address
}
```
### 2.2 EIP-712 Domain
- `name: "DBISConversionRouter"`
- `version: "1"`
- `chainId: 138`
- `verifyingContract: address(DBIS_ConversionRouter)` (or equivalent contract)
### 2.3 Validation Rules
- `chainId == 138`
- `verifyingContract == address(this)` (Conversion Router)
- `block.timestamp <= deadline`
- `venue` must be in the venue allowlist.
- `quoteIssuer` must be in the quote-issuer allowlist.
- `tokenOut` (and optionally `tokenIn`) must resolve to canonical stablecoin IDs when the output is a registered stablecoin (see [DBIS Rail Stablecoin Policy v1.5](DBIS_RAIL_STABLECOIN_POLICY_V1_5.md)).
- Signatures must satisfy the quorum rules in Section 3.
---
## 3. Quorum and Separation of Duties
### 3.1 Base vs Elevated Quorum
| Swap size | Quorum | COMPLIANCE required |
|-----------|--------|----------------------|
| **Small** (amountIn ≤ policy threshold) | 2-of-4 | No (per policy) |
| **Large** (amountIn > policy threshold) | 3-of-5 | Yes |
Threshold and exact category masks are set by policy (e.g. ROUTER_ADMIN or governance). COMPLIANCE signer is mandatory for large swaps and for any new venue enablement (Section 6).
### 3.2 ConversionExecuted Event
Every executed conversion must emit an audit-grade event, for example:
- `ConversionExecuted(bytes32 indexed messageId, bytes32 indexed quoteHash, bytes32 venue, address tokenIn, address tokenOut, uint256 amountIn, uint256 amountOut, address quoteIssuer)`
Optionally store `quoteHash` (and messageId) in an on-chain mapping for audit queries.
---
## 4. Execution Policy Module
### 4.1 Document and Enforceable Fields
The execution policy is documented in operational policy and enforced by the Conversion Router (or routing layer) where applicable. Fields include:
| Field | Description |
|-------|-------------|
| **Quote source priority** | RFQ → on-chain TWAP → aggregator → direct DEX. Lower-priority sources may be used only when higher-priority ones are unavailable or do not meet min liquidity / max slippage. |
| **Max slippage (bps)** | Maximum permitted slippage from quote; e.g. 50 bps. |
| **Max price impact** | Maximum permitted price impact (e.g. bps or percentage). |
| **Min liquidity threshold** | Minimum liquidity (or depth) for the venue/pool to be used. |
| **Deadline** | Short validity; e.g. quote expiry and SwapAuth deadline ≤ 2 minutes from quote time. |
### 4.2 MEV Posture
- **Large trades:** Prefer RFQ/OTC-style venues where available to reduce MEV and sandwich risk.
- **Private submission:** Optional support for private transaction submission (e.g. via protected relayer or chain-specific mechanism) when policy permits.
- **Enforce on-chain:** `minAmountOut` and `deadline` are required in SwapAuth; execution must satisfy them. Venue allowlist restricts which pools/venues may be used (Section 6).
---
## 5. Quote Provenance
- Every SwapAuthorization must include **quoteHash** (hash of the quote payload) and **quoteIssuer** (address or identifier of the approved quote source).
- **QuoteIssuer allowlist:** Only approved quote issuers may be used; the Conversion Router (or policy layer) checks `quoteIssuer` against the allowlist.
- **Audit:** Store `quoteHash` in the ConversionExecuted event and optionally in an on-chain mapping so that auditors can verify which quote was used for a given conversion.
---
## 6. Sanctions/AML for Swap Venues and Counterparties
### 6.1 Venue Allowlist
- **Venue risk review:** Before a venue (DEX, pool, or RFQ provider) is enabled, a venue risk review must be completed per DBIS policy.
- **Pool-address allowlisting:** Only explicitly allowlisted pool (or venue) addresses may be used—not “any pool on Uniswap fork.”
- **Periodic re-approval:** Venues must be re-approved on a defined cadence (e.g. annually or per policy).
### 6.2 Address Screening
- **Blocklist/denylist:** The Conversion Router (or a hooked contract/oracle) must consult a blocklist/denylist before executing a conversion. Counterparty addresses (e.g. recipient or intermediate addresses) that appear on the denylist must cause the transaction to revert.
- **Taint score (optional):** For high-value swaps, policy may require a “taint score” or additional screening gate; implementation may be off-chain (e.g. compliance check before signing SwapAuth) or on-chain if an oracle or contract exposes it.
### 6.3 Compliance Signer Requirements
- **Swaps above threshold:** COMPLIANCE signer category is required for large swaps (Section 3).
- **New venue enablement:** Any change to the venue allowlist (new venue or pool) requires COMPLIANCE sign-off (e.g. 3-of-5 with COMPLIANCE mandatory for the governance action that adds a venue).
---
## 7. Contract / Component Sketch
A **DBIS_ConversionRouter** (or equivalent) may be implemented to:
- Verify SwapAuthorization signatures and quorum (using a signer registry analogous to DBIS_SignerRegistry, or shared registry with category checks).
- Check that `venue` is in the venue allowlist and that `quoteIssuer` is in the quote-issuer allowlist.
- Check counterparty (and optionally intermediate) addresses against the blocklist/denylist.
- Enforce `minAmountOut` and `deadline` on execution.
- Resolve `tokenOut` (and `tokenIn` if applicable) against the Stablecoin Reference Registry so that only canonical stablecoin IDs in ACTIVE status are used when the policy applies (see [DBIS Rail Stablecoin Policy v1.5](DBIS_RAIL_STABLECOIN_POLICY_V1_5.md)).
- Emit ConversionExecuted with quoteHash, venue, amounts, quoteIssuer.
Where a conversion is tied to a settlement (e.g. mint-then-swap or swap-then-mint), the Conversion Router may reference the SettlementRouter and MintAuth flow; the exact integration is deployment-specific.
---
## 8. Cross-References
- **Rulebook** — Compliance (§4.3), signer categories; good funds and finality apply to any settlement leg.
- **Technical Spec** — Participant allowlist, SignerRegistry (shared or analogous for swap signers); ParticipantRegistry for counterparty checks.
- **Threat Model** — Off-chain venue/counterparty risk; MEV and sandwich; sanctions exposure.
- **Stablecoin Policy v1.5** — Canonical stablecoin IDs and registry; only ACTIVE registered stablecoins may be used as tokenOut (or tokenIn) when policy requires it.
---
## 9. Document Control
| Field | Value |
|-------|-------|
| Title | DBIS Rail Conversion Router Spec v1.5 |
| Version | 1.5 |
| Status | Active |

201
docs/dbis-rail/DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md Normal file
View File

@@ -0,0 +1,201 @@
# DBIS Rail Hash Canonicalization and Test Vectors v1.5
**Network:** DBIS Mainnet (ChainID 138)
**Document type:** v1.5 Add-on — LEB/LPA/ISO schemas, canonicalization rules, test vectors for auditor reproducibility
**Companion documents:** [DBIS Rail Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md), [DBIS Rail Rulebook v1](DBIS_RAIL_RULEBOOK_V1.md), [DBIS Rail Ledger Attestation Add-On v1.5](DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md)
---
## 1. Purpose and Scope
This add-on removes hash disputes and enables **auditor reproducibility** by:
- Defining **LEB (Ledger Entry Bundle)** and **LPA (Ledger Posting Authorization)** schemas and their canonical form.
- Specifying **canonicalization rules** for the ISO evidence bundle used to compute `isoHash` (Technical Spec §4.2, Rulebook §4.4).
- Providing **test vectors**: sample inputs and expected hashes for LEB → lebHash, LPA → lpaId (or equivalent), ISO bundle → isoHash, and optional accountingRef (Rulebook §3.2).
Any auditor or implementation can reproduce the same hashes from the same inputs when following these rules.
---
## 2. Canonicalization Rules (General)
All structured data that is hashed for the DBIS Rail must be canonicalized as follows unless a schema specifies otherwise:
| Rule | Application |
|------|-------------|
| **UTF-8 normalization** | All text in UTF-8; use NFC normalization (Unicode Normalization Form C). |
| **Sorted keys** | For JSON-like structures, serialize with keys in lexicographic order (e.g. JSON Canonicalization Scheme [RFC 8785] or equivalent). |
| **Fixed decimal handling** | Decimals: fixed precision and rounding mode (e.g. 6 decimal places, half-up). Document in schema. |
| **Fixed timestamp format** | Use either RFC 3339 (e.g. `2025-03-02T12:00:00Z`) or Unix seconds (integer). Document which is used per field. |
| **Explicit rounding policy** | For amounts: rounding mode (e.g. half-up, truncate) and precision must be fixed and documented. |
---
## 3. LEB (Ledger Entry Bundle)
### 3.1 Purpose
The Ledger Entry Bundle (LEB) is the canonical representation of a ledger entry or batch that may be used to derive a **lebHash** for attestation or linkage to an LPA.
### 3.2 Schema (Conceptual)
LEB is a structured object with at least:
- **ledgerSystemId** (string): Identifies the ledger system.
- **journalId** (string): Unique journal or batch identifier.
- **batchNumber** (integer or string): Batch or sequence number.
- **postingTimestamp** (string or number): RFC 3339 or Unix seconds.
- **reserveAccountId** (string): Reserve or settlement account id.
- **entries** (array): List of line items (e.g. account, amount, currency, side).
Exact types and additional fields are defined in the operational schema. For hashing, use a single canonical serialization (e.g. JSON with sorted keys, UTF-8, no extra whitespace).
### 3.3 LEB Schema Location
- Publish **LEB.schema.json** under `docs/dbis-rail/schemas/` (or equivalent). The schema file defines required fields, types, and encoding for canonical serialization.
- Until the file is added, the canonical form is: JSON object with keys in lexicographic order, UTF-8 NFC, no unnecessary whitespace; decimals and timestamps per Section 2.
### 3.4 Test Vector — LEB → lebHash
**Input (canonical JSON, keys sorted):**
```json
{"batchNumber":1,"journalId":"J-2025-001","ledgerSystemId":"CORE","postingTimestamp":1740931200,"reserveAccountId":"RES-USD-001"}
```
**Encoding:** UTF-8 bytes of the above string (no trailing newline).
**Hash function:** keccak256.
**Expected lebHash (hex):** To be filled by implementation; once fixed, any auditor can recompute:
```
lebHash = keccak256(utf8(canonicalJsonString))
```
Example placeholder (replace with actual keccak256 output when implementation is frozen):
`0x0000000000000000000000000000000000000000000000000000000000000000` → replace with real hash for test vector.
---
## 4. LPA (Ledger Posting Authorization / Attestation)
### 4.1 Purpose
The LPA is the ledger-domain object that attests to a posting and its state (see [DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md](DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md)). The **lpaId** (or equivalent) is a deterministic hash of the canonical LPA representation used to link MintAuth or swap flows to the attestation.
### 4.2 Schema (Conceptual)
LPA includes at least: reference to the LEB (e.g. lebHash or journalId + batchNumber), state (POSTED_FINAL, POSTED_ADJUSTMENT, POSTED_REVERSAL, DISPUTED_HOLD), timestamp of state change, and any required identifiers. Exact fields are defined in **LPA.schema.json** under `docs/dbis-rail/schemas/`.
### 4.3 Test Vector — LPA → lpaId
**Input (canonical JSON, keys sorted):**
```json
{"lebHash":"0x...","state":"POSTED_FINAL","stateTimestamp":1740931200}
```
Use the lebHash from Section 3.4 (or a fixed test value). Then:
**lpaId = keccak256(utf8(canonicalLpaJsonString))**
Document the expected lpaId (hex) once the test LEB hash is fixed so that auditors can reproduce.
---
## 5. ISO Evidence Bundle → isoHash
### 5.1 Purpose
The ISO evidence bundle supports the settlement and is hashed to produce **isoHash** included in the Mint Authorization (Rulebook §4.4, Spec §4.2). It must include at least: message type, identifiers (e.g. UETR, EndToEndId), amount, currency, parties, timestamp consistent with finality.
### 5.2 Canonicalization Rules for ISO Bundle
- **UTF-8 normalization:** NFC.
- **Sorted keys:** If the bundle is JSON, keys in lexicographic order (e.g. RFC 8785).
- **Fixed decimal handling:** As per Section 2; document precision and rounding for amount fields.
- **Fixed timestamp format:** RFC 3339 or Unix seconds consistently.
- **Explicit rounding policy:** Document and apply uniformly.
The exact schema of the bundle (e.g. which ISO-20022 fields are included in the canonical form) must be documented in operational procedures. The hash is then:
**isoHash = keccak256(utf8(canonicalBundleString))**
### 5.3 Test Vector — ISO Bundle → isoHash
**Input (minimal canonical JSON, keys sorted):**
```json
{"amount":"1000.000000","currency":"USD","endToEndId":"E2E-2025-001","messageType":"pacs.008","timestamp":1740931200,"uetr":"550e8400-e29b-41d4-a716-446655440000"}
```
**Encoding:** UTF-8 bytes of the above string.
**Expected isoHash:** To be filled with actual keccak256 output when encoding is frozen. Example (replace with real hash):
```
isoHash = keccak256(utf8(canonicalIsoBundleString))
```
---
## 6. accountingRef (Rulebook §3.2)
### 6.1 Formula
From Rulebook §3.2:
```
accountingRef = keccak256(
ledgerSystemId,
journalId,
batchNumber,
postingTimestamp,
reserveAccountId
)
```
The exact encoding (ABI-packed bytes, ASCII concatenation, or other) must be fixed in operational procedures. Once fixed, the same inputs must always produce the same accountingRef.
### 6.2 Test Vector — accountingRef
**Inputs (example):**
- ledgerSystemId: `"CORE"` (or bytes32 equivalent)
- journalId: `"J-2025-001"`
- batchNumber: `1` (or fixed width string)
- postingTimestamp: `1740931200`
- reserveAccountId: `"RES-USD-001"`
**Encoding (example — ABI-packed):** abi.encodePacked(ledgerSystemId, journalId, batchNumber, postingTimestamp, reserveAccountId) with types and padding defined in ops. Alternatively, a single canonical string concatenation with a defined separator.
**Expected accountingRef (hex):** Document the actual keccak256 result once encoding is frozen so that auditors can reproduce.
---
## 7. Where Schemas and Vectors Live
- **Schemas:** Publish **LEB.schema.json** and **LPA.schema.json** under `docs/dbis-rail/schemas/` when available. This document references them and defines the general canonicalization rules (Section 2).
- **Test vectors:** Inline in this document (Sections 3.4, 4.3, 5.3, 6.2). Optionally, a separate file (e.g. `docs/dbis-rail/test-vectors.json` or `test-vectors.md`) may hold the same inputs and expected hashes for machine-readable verification.
- **ISO bundle schema:** Operational procedures document the exact ISO evidence bundle schema; this add-on specifies the canonicalization rules (Section 2 and 5.2).
---
## 8. Cross-References
- **Rulebook §3.2** — Deterministic accountingRef; this add-on provides the test vector and encoding expectations.
- **Rulebook §4.4** — Evidence bundle and isoHash; this add-on specifies canonicalization and test vector.
- **Technical Spec §4.2** — MintAuth isoHash and accountingRef fields.
- **Ledger Attestation Add-On v1.5** — LPA states and lpaId linkage.
---
## 9. Document Control
| Field | Value |
|-------|-------|
| Title | DBIS Rail Hash Canonicalization and Test Vectors v1.5 |
| Version | 1.5 |
| Status | Active |

121
docs/dbis-rail/DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md Normal file
View File

@@ -0,0 +1,121 @@
# DBIS Rail Ledger Attestation Add-On v1.5
**Network:** DBIS Mainnet (ChainID 138)
**Document type:** v1.5 Add-on — LPA state machine, reversal policy matrix, signer effective/revoked block enforcement
**Companion documents:** [DBIS Rail Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md), [DBIS Rail Rulebook v1](DBIS_RAIL_RULEBOOK_V1.md)
---
## 1. Purpose and Scope
This add-on defines:
- The **LPA (Ledger Posting Authorization / attestation) state machine** so that settlement and reversals have deterministic operational outcomes.
- The **Reversal Policy Matrix** for before-mint and after-mint scenarios (invalidate, offset, burn, dispute).
- **Mandatory signer effective-from and revoked-at block semantics** so that authorization correctness is enforced on-chain under governance churn.
These extensions make outcomes rule-governed and examiner-credible. They implement the Rulebook’s “recommended for v1.5+” signer timing (Rulebook §6.2) as mandatory.
---
## 2. LPA State Machine
### 2.1 States
A Ledger Posting Authorization (LPA) is the ledger-domain object that backs a settlement and, when final, may support issuance of a Mint Authorization. Each LPA has a state from the following set:
| State | Description |
|-------|-------------|
| **POSTED_FINAL** | Posting is final and compliant; a Mint Authorization may be issued for this LPA provided all other preconditions (Rulebook §4) are met. |
| **POSTED_ADJUSTMENT** | An adjustment has been applied to the posting; no new Mint Authorization may reference this LPA until it is resolved (e.g. back to POSTED_FINAL or moved to POSTED_REVERSAL). |
| **POSTED_REVERSAL** | The posting has been reversed in the ledger domain; no Mint Authorization may be issued. If a Mint Authorization was already issued and executed, corrective action follows the Reversal Policy Matrix (Section 3). |
| **DISPUTED_HOLD** | The posting or settlement is under dispute; no Mint Authorization may be issued and no corrective burn/offset may be executed until the dispute is resolved and state is updated. |
### 2.2 Allowed Transitions
- **POSTED_FINAL** → **POSTED_ADJUSTMENT**: Ledger/ops (e.g. correction, reclassification).
- **POSTED_FINAL** → **POSTED_REVERSAL**: Ledger/ops (reversal entry).
- **POSTED_FINAL** → **DISPUTED_HOLD**: Dispute procedure (designated role).
- **POSTED_ADJUSTMENT** → **POSTED_FINAL**: Ledger/ops (adjustment complete).
- **POSTED_ADJUSTMENT** → **POSTED_REVERSAL**: Ledger/ops.
- **POSTED_ADJUSTMENT** → **DISPUTED_HOLD**: Dispute procedure.
- **DISPUTED_HOLD** → **POSTED_FINAL**, **POSTED_ADJUSTMENT**, or **POSTED_REVERSAL**: Per dispute resolution outcome (designated role).
**POSTED_REVERSAL** and **DISPUTED_HOLD** are terminal for “may issue MintAuth”; only POSTED_FINAL (and per policy POSTED_ADJUSTMENT once resolved to POSTED_FINAL) permits issuance.
### 2.3 Link to Mint Authorization
- A Mint Authorization may be issued only when the underlying LPA is in a state that permits settlement (e.g. **POSTED_FINAL**).
- The ISO Gateway and signers must not issue or sign a Mint Authorization for an LPA in **POSTED_ADJUSTMENT**, **POSTED_REVERSAL**, or **DISPUTED_HOLD**.
- Operational procedures must record the LPA identifier (e.g. lpaId or equivalent) and state at the time of MintAuth issuance for audit.
---
## 3. Reversal Policy Matrix
### 3.1 Before Mint (Mint Authorization not yet submitted or not yet executed)
| Scenario | Action |
|----------|--------|
| Reversal or exception identified before Mint Authorization is submitted | **Invalidate Mint Authorization.** Do not submit. Correct the ledger domain per Rulebook §5.1 (reversal entry, adjustment, or exception posting). Any subsequent valid settlement may result in a new Mint Authorization with a new messageId and accountingRef. |
| Reversal after Mint Authorization signed but before on-chain submission or before expiry | **Treat Mint Authorization as invalid.** Do not submit. Withhold or revoke the authorization per Rulebook §5.2. Procedures must ensure it is not submitted later. |
### 3.2 After Mint (Mint executed on-chain)
Once the SettlementRouter has accepted the Mint Authorization and the GRU Mint Controller has executed the mint, on-chain settlement is final from the rail’s perspective. Reversals in the fiat/ledger domain do not automatically reverse the mint. Corrective action is governed by the following matrix:
| Priority | Corrective action | When to use |
|----------|-------------------|-------------|
| **Primary** | Ledger offset + future corridor restriction | Standard reversal; offset the on-chain mint in the ledger domain and restrict the counterparty or corridor for future settlements per DBIS procedures. Documented in operational runbook. |
| **Secondary** | Burn (if token custody permits) | Where policy requires reduction of on-chain supply; burn of GRU per Rulebook §5.3 and Technical Spec / operational procedures. Requires appropriate authorization (e.g. ROUTER_ADMIN or designated burn path). |
| **Tertiary** | Debt/claim ledger entry + dispute handling | When offset or burn is not immediately applicable; record a debt or claim in the ledger domain and follow dispute-resolution procedures. Runbook reference for dispute handling and eventual resolution (e.g. future offset or burn). |
Operational procedures must define who may initiate each corrective action, required sign-offs, and how the choice of primary vs secondary vs tertiary is made and recorded.
---
## 4. Signer Governance Timing (Mandatory for v1.5)
### 4.1 SignerRegistry Extensions
The DBIS_SignerRegistry (Technical Spec §6.3) must be extended for v1.5 with per-signer block semantics:
- **effectiveFromBlock** (uint256): The signer’s signature is valid only for Mint Authorizations submitted on-chain at a block number **greater than or equal to** this value.
- **revokedAtBlock** (uint256): The signer’s signature is **not** valid for Mint Authorizations submitted on-chain at a block number **greater than or equal to** this value. Use a sentinel (e.g. type(uint256).max) to indicate “not revoked.”
Initial semantics when a signer is added: set `effectiveFromBlock` to the current block (or deployment block); set `revokedAtBlock` to the “never” sentinel until revocation.
### 4.2 SettlementRouter Validation
At the block at which `submitMintAuth` is executed, the SettlementRouter must validate for each recovered signer:
- `block.number >= signer.effectiveFromBlock`
- `block.number < signer.revokedAtBlock` (or equivalent “not revoked” check)
If any signer is outside the effective window or is revoked at the current block, the transaction must revert.
### 4.3 Runbook References
- **Emergency revoke sequence:** SIGNER_ADMIN calls SignerRegistry to set `revokedAtBlock = block.number` (or next block) for the compromised or retired signer. In-flight Mint Authorizations that rely on that signer must not be submitted after the revocation block (Rulebook §6.3, §6.4).
- **Key compromise drill:** Follow DBIS security policy: revoke signer immediately, re-evaluate in-flight authorizations, incident reporting, key rotation. See Rulebook §6.4.
---
## 5. Cross-References
- **Rulebook §3.2** — Deterministic accountingRef; LPA and accountingRef must align so that one accountingRef corresponds to at most one LPA/MintAuth unless a documented exception exists.
- **Rulebook §5** — Reversal and exception handling; this add-on’s Reversal Policy Matrix operationalizes Rulebook §5.1–5.3.
- **Rulebook §6.2** — Effective and revoked block semantics (“recommended for v1.5+”) are now **mandatory** in this add-on.
- **Technical Spec §6.3** — DBIS_SignerRegistry; add `effectiveFromBlock` and `revokedAtBlock` state and accessors.
- **Technical Spec §6.4** — DBIS_SettlementRouter; add validation that each recovered signer is active at `block.number` per Section 4.2 above.
- **Hash Canonicalization add-on** — LPA schema and lpaId (or equivalent) hash for attestation; see [DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md](DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md).
---
## 6. Document Control
| Field | Value |
|-------|-------|
| Title | DBIS Rail Ledger Attestation Add-On v1.5 |
| Version | 1.5 |
| Status | Active |

153
docs/dbis-rail/DBIS_RAIL_REGULATOR_BRIEF_V1.md Normal file
View File

@@ -0,0 +1,153 @@
# DBIS Rail — Regulator-Facing Brief v1
**Network:** DBIS Mainnet (ChainID 138)
**Document type:** Institutional narrative summary
**Audience:** Bank counterparties, examiners, external counsel, risk committees, institutional integration teams
**Companion documents:** [Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md), [Rulebook v1](DBIS_RAIL_RULEBOOK_V1.md), [Security Threat Model v1](DBIS_RAIL_SECURITY_THREAT_MODEL_V1.md)
---
## 1. Executive Overview
The DBIS Rail is a programmable settlement rail operating on DBIS Mainnet (ChainID 138). It enables the recording of settlements and the minting of GRU (and linked token) against authorizations that are rooted in ISO-20022 messaging and regulated ledger practice, while keeping finality determination and compliance within the operational and regulatory domain.
**Purpose.** The rail is designed to:
- Provide a deterministic on-chain execution layer for settlement instructions that have been validated off-chain.
- Enforce threshold-controlled mint governance so that GRU is minted only when a defined quorum of authorized signers has approved a Mint Authorization.
- Support institutional finality discipline by tying each on-chain settlement to a unique message identifier, an accounting reference, and a hash of the underlying evidence bundle.
**Core principle.** DBIS Rail enforces authorization integrity on-chain while preserving fiat finality determination within regulated ledger domains. The chain does not decide whether fiat funds are final; it enforces that only properly authorized, replay-protected, and policy-compliant instructions result in settlement and mint.
---
## 2. Network and Governance Model
**Network.** The rail runs on DBIS Mainnet (ChainID 138), a permissioned blockchain using Besu with QBFT (Quorum Byzantine Fault Tolerant) consensus. Block production is performed by a defined validator set under operational governance. The application layer consists of a set of contracts that implement participant registration, signer allowlisting, settlement routing, and mint execution.
**Governance.**
- **Validators:** Produce and order blocks. They do not sign Mint Authorizations and do not execute settlement logic. Validator rotation and emergency measures are governed operationally (and may be augmented by on-chain governance in future).
- **Contract administration:** Role-based (e.g., ROOT_ADMIN, PARTICIPANT_ADMIN, SIGNER_ADMIN, ROUTER_ADMIN) with multisig or timelock where appropriate. Upgrades and critical configuration changes follow defined governance procedures.
- **Signer quorum:** Mint Authorizations require a threshold of allowlisted signers (default: 3-of-5) with mandatory participation from a designated Compliance category. No single role can approve a mint alone.
- **Mint path:** The only on-chain path that can cause GRU to be minted is via the Settlement Router. The Mint Controller accepts instructions solely from the Router after validation of signatures, replay protection, and policy checks.
**Compartmentalization.** Validators, signers, the ISO Gateway (off-chain), the Settlement Router contract, and the GRU Mint Controller are distinct. Validators order transactions; signers attest to authorizations; the Gateway assembles evidence and produces the authorization payload; the Router validates and records; the Mint Controller executes the mint. No single component both determines finality and executes mint.
---
## 3. Settlement Lifecycle (High-Level)
Settlement on the DBIS Rail follows a defined sequence. The following is a high-level description; technical detail is in the Technical Spec.
1. **ISO message receipt.** The ISO Gateway receives one or more ISO-20022 messages (e.g., pacs, camt, pain family) and associated evidence.
2. **Compliance checks.** Required compliance checks (KYC, AML, sanctions, jurisdiction, limits) are performed. No Mint Authorization may be issued for a failing or unresolved case.
3. **Double-entry accounting.** The underlying transaction (or batch) is posted in the DBIS ledger domain with required reserve account tagging. Posting must be complete and immutable before an authorization is issued.
4. **Deterministic accounting reference.** An accounting reference (accountingRef) is generated from the ledger posting using a deterministic formula (ledger system, journal, batch, timestamp, reserve account). This binds the future on-chain settlement to a specific ledger event.
5. **Mint Authorization construction.** A Mint Authorization (MintAuth) is built containing message identifier, evidence hash (isoHash), accounting reference, funds status (ON_LEDGER_FINAL or OFF_LEDGER_FINAL per Rulebook), recipients, amounts, time window, chain identifier, and verifying contract. The construction follows EIP-712 for signing.
6. **Threshold signer approval.** Allowlisted signers from the required categories sign the Mint Authorization. The default rule is 3-of-5 with Compliance mandatory. Signers are expected to sign only when Rulebook preconditions (good funds, accounting, compliance, evidence) are satisfied.
7. **Router validation and recording.** The Settlement Router receives the Mint Authorization and signatures. It verifies signature validity, quorum and category rules, time window, replay (messageId not previously used), policy caps, and participant allowlist. If all checks pass, it records the settlement and calls the Mint Controller.
8. **GRU mint.** The Mint Controller mints the specified amounts to the specified recipient addresses. It is callable only by the Router.
9. **Audit events.** The Router and related contracts emit immutable on-chain events (e.g., SettlementRecorded, MintExecuted) including message identifier, accounting reference, evidence hash, and amounts. These support audit and regulatory reporting.
---
## 4. Good Funds and Finality Framework
Finality of the underlying fiat or ledger position is not determined by the chain. It is determined in the regulated domain and encoded in the Mint Authorization (e.g., via funds status and the evidence bundle). The Rulebook defines when a settlement may be treated as final for the purpose of issuing a Mint Authorization.
**Principle.** The chain enforces authorization integrity (signatures, replay, policy). The Rulebook governs good-funds determination and when ON_LEDGER_FINAL or OFF_LEDGER_FINAL may be asserted for each rail type (wire, ACH, instant, cash, internal). Reversal windows and exception handling are defined in the Rulebook; no Mint Authorization may be issued until the applicable finality trigger and reversal rules are satisfied.
**Funds status.**
- **ON_LEDGER_FINAL:** Funds are final in the DBIS-controlled ledger domain (e.g., core posting complete, irrevocable per policy). The Rulebook specifies the trigger per rail type (e.g., wire: core posting complete; ACH: settlement date plus return window elapsed).
- **OFF_LEDGER_FINAL:** Funds are final via an external rail plus reconciliation as defined by DBIS policy (e.g., SWIFT confirmation and Nostro reconciliation). Used only where policy permits and reconciliation is complete.
**Reversal.** Before a Mint Authorization is submitted, reversals or exceptions prevent issuance or require cancellation of the authorization. After mint execution, on-chain settlement is final from the chain’s perspective. Post-mint reversals in the fiat/ledger domain do not automatically reverse the mint; any corrective action (e.g., burn or offset) follows defined procedures in the Rulebook and operational policy.
---
## 5. Controls and Safeguards
### 5.1 Authorization controls
- **EIP-712 domain separation:** Signatures are bound to chain identifier and the Settlement Router contract address. Authorizations signed for another chain or contract do not verify.
- **Message identifier replay protection:** Each message identifier may be used at most once. A second submission with the same identifier is rejected.
- **Time-bound authorization:** Each Mint Authorization carries a validity window (notBefore, expiresAt). Submissions outside the window are rejected.
- **Required Compliance signer:** The signer set must include a signer from the designated Compliance category. This is enforced on-chain.
- **Signer allowlist and revocation:** Only addresses on the Signer Registry may contribute valid signatures. Signers may be removed; procedures govern handling of in-flight authorizations and compromised keys.
### 5.2 Operational controls
- **Deterministic accounting reference:** The accounting reference is derived from ledger identifiers (system, journal, batch, timestamp, reserve account) so that it can be audited against a unique posting.
- **Evidence bundle and isoHash:** The canonical evidence bundle supporting the settlement is hashed; the hash (isoHash) is included in the Mint Authorization. This links on-chain settlement to the off-chain evidence; procedures require the bundle to reflect actual finality and posting.
- **One-to-one mapping:** Under normal policy, each accounting reference corresponds to at most one Mint Authorization, and each message identifier to one settlement. Exceptions, if any, are documented and auditable.
### 5.3 Technical controls
- **Reentrancy protection:** The Settlement Router is implemented so that state updates occur before external calls (e.g., to the Mint Controller), and reentrancy guards are used where appropriate.
- **Cap enforcement before mint:** Per-message and per-corridor caps are checked and updated before the mint is invoked. Exceeding a cap causes the transaction to revert.
- **Router pause:** An authorized role may pause the Settlement Router, halting new settlements until the pause is lifted.
- **Mint controller isolation:** The Mint Controller accepts mint instructions only from the Settlement Router. Direct mint paths (e.g., owner or other roles on the token) are removed or revoked so that the rail is the sole mint path.
---
## 6. Risk Management and Threat Posture
The DBIS Rail is designed so that unauthorized minting, replay of authorizations, and confusion between chains or contracts are prevented by on-chain checks and operational procedure. A formal threat assessment is maintained (Security Threat Model v1) and is summarized here.
**Threat categories.**
- **Authorization layer:** Forgery, replay, cross-chain replay, expired or wrong-contract authorizations, signer compromise, quorum or category bypass. Mitigations include EIP-712 domain binding, messageId one-time use, time window, Signer Registry and quorum rules, and operational key protection and role separation.
- **Ledger and accounting:** Fake or misused accounting references, misclassification of funds status, good-funds misrepresentation. Mitigations include the deterministic accountingRef, the Rulebook good-funds matrix, hashing of the evidence bundle into isoHash, and reconciliation and audit procedures.
- **Settlement Router:** Reentrancy, overflow, policy-cap or pause bypass. Mitigations include checks-effects-interactions pattern, guards, strict validation of inputs and caps, and paused-state checks.
- **Mint Controller:** Direct mint or role escalation. Mitigations include restriction of mint to the Router only and revocation of other mint paths; upgrades are subject to governance and timelock.
- **Validator layer:** Collusion, censorship, chain halt. Mitigations include QBFT finality, documented validator governance, and the ability to pause the rail in response to availability or integrity concerns.
- **Off-chain:** ISO Gateway compromise, signer key theft, insider collusion, compliance or accounting failure. Mitigations include HSM or secure storage for signer keys, separation of signer and Gateway roles, quorum design with mandatory Compliance, signer revocation procedures, and monitoring and audit.
**Important distinction.** The system is designed to prevent unauthorized minting, replay, and domain confusion. It does not independently determine fiat finality. Finality is determined in the regulated ledger and compliance domain; the chain enforces that only properly authorized and policy-compliant instructions result in settlement and mint.
---
## 7. Audit and Transparency
- **On-chain events:** Settlement and mint execution produce immutable on-chain events (e.g., SettlementRecorded, MintExecuted) that include message identifier, accounting reference, evidence hash, funds status, and amounts. These events support audit and regulatory reporting.
- **Anchoring:** Each settlement is anchored by messageId and accountingRef, with isoHash linking to the off-chain evidence bundle. Mappings (messageId to evidence, messageId to accountingRef, accountingRef to ledger posting) are maintained for audit and examination.
- **Registry and status logging:** Changes to the signer allowlist and to participant status (e.g., registration, suspension, revocation) are recorded on-chain or in controlled logs, with versioned documentation.
- **Review cycle:** The Rulebook, Threat Model, and related documentation are subject to a defined review cycle (e.g., annual and on material change). Versions are published and retained.
---
## 8. Residual Risk Disclosure
The following are relied upon for the intended security and compliance properties of the rail. They are not verified on-chain; their failure is an operational or off-chain risk.
- **ISO Gateway correctness:** The Gateway correctly applies the Rulebook (good funds, finality triggers, reversal windows), builds the evidence bundle, and computes the accounting reference and evidence hash in accordance with the defined rules. The chain does not verify ledger or compliance state.
- **Ledger integrity:** The core (or designated) ledger correctly records postings and the accounting reference is produced only for completed, compliant postings. No tampering or fabrication of postings is assumed.
- **Signer independence and key security:** Signers are distinct from Gateway operators and sign only when preconditions are satisfied. Signer private keys are protected (e.g., HSM or equivalent). Compromise of fewer than a quorum of signers does not by itself yield a valid Mint Authorization.
- **Validator majority honesty:** A sufficient majority of validators (per QBFT) follow the protocol. Finality of blocks is maintained; no reversion of finalized blocks is assumed under normal operation.
- **Governance and administration:** Admin roles and upgrade paths are used in accordance with policy; multisig or timelock is applied where required. No backdoor or unauthorized change to contracts or configuration is assumed.
This disclosure is made to support informed assessment by counterparties, examiners, and risk committees. Mitigation of residual risk is through operational controls, the Rulebook, and independent audit rather than on-chain verification.
---
## 9. Governance and Amendment
- **Technical Spec:** Defines contract behavior, data structures, and on-chain validation rules. Changes to the Spec that affect deployed contracts require deployment or upgrade following governance.
- **Rulebook:** Defines operational and compliance rules (good funds, finality, reversal, signer governance, incident controls, audit). Amendments are approved per DBIS policy and take effect on a stated effective date.
- **Threat Model:** Describes threat categories, mitigations, severity, and residual risk. It is reviewed periodically and when design or deployment changes materially affect risks.
- **Versioning and publication:** Documentation is versioned. Current versions are published (e.g., in docs/dbis-rail/ or an official repository); superseded versions are retained for reference and audit.
---
## Document Control
| Field | Value |
|-------|--------|
| Title | DBIS Rail — Regulator-Facing Brief v1 |
| Network | DBIS Mainnet (ChainID 138) |
| Audience | Bank counterparties, examiners, counsel, risk committees, integration teams |
| Companions | Technical Spec v1, Rulebook v1, Security Threat Model v1 |
| Version | 1 |
| Status | Active |

289
docs/dbis-rail/DBIS_RAIL_RULEBOOK_V1.md Normal file
View File

@@ -0,0 +1,289 @@
# DBIS Rail Rulebook v1
**Network:** DBIS Mainnet (ChainID 138)
**Document type:** Operational and compliance policy
**Companion document:** [DBIS Rail Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md)
---
## 1. Scope and Authority
### 1.1 Purpose
This Rulebook defines the **operational and compliance rules** governing the DBIS Rail on Chain 138. It establishes:
- What constitutes **good funds** and under what conditions settlement is considered **final**.
- How **FundsStatus** (ON_LEDGER_FINAL vs OFF_LEDGER_FINAL) is determined for each rail type.
- The **preconditions** that must be satisfied before a Mint Authorization may be issued.
- **Reversal and exception** handling before and after settlement.
- **Signer governance**, revocation timing, and treatment of in-flight authorizations.
- **Incident and emergency** controls, and **audit and reporting** standards.
The Rulebook does **not** define the technical implementation of the rail; that is set out in the DBIS Rail Technical Spec v1. This document governs the **procedural and policy layer** that underwrites the integrity of Mint Authorizations and the defensibility of settlement finality.
### 1.2 Authority and applicability
- The Rulebook applies to all participants on the DBIS Rail, all signers contributing to Mint Authorizations, and all operators of the ISO Gateway and ledger domain that produce evidence for `isoHash` and `accountingRef`.
- Amendments are governed by Section 9 (Versioning and Amendment Process).
- In the event of conflict between this Rulebook and the Technical Spec, the Technical Spec governs **on-chain behavior**; this Rulebook governs **operational and compliance obligations** and the **meaning** of good funds and finality.
---
## 2. Good Funds Matrix
Settlement finality and the classification of funds as ON_LEDGER_FINAL or OFF_LEDGER_FINAL are determined by rail type and by the completion of defined operational triggers. The following matrix is authoritative for issuance of Mint Authorizations.
| Rail type | ON_LEDGER_FINAL trigger | OFF_LEDGER_FINAL trigger | Reversal window |
|-----------|-------------------------|---------------------------|-----------------|
| **Wire (SWIFT/RTGS)** | Core ledger posting complete and irrevocable per internal policy. | SWIFT (or equivalent) confirmation received and Nostro reconciliation complete per DBIS policy. | None after posting; reversals require separate corrective entry and must not be represented as the original settlement. |
| **ACH** | Settlement date reached and return/chargeback window has fully elapsed per applicable ACH rules. | N/A for typical ACH flows; if external rail is used, OFF_LEDGER_FINAL per reconciliation policy. | Duration of the return window; no Mint Authorization may be issued with ON_LEDGER_FINAL until the window has elapsed. |
| **Instant rail** | Receipt confirmation received and no recall or revocation flag present per rail operator rules. | N/A unless defined for a specific instant scheme. | Per the rules of the instant rail; Mint Authorization must not be issued before recall window has passed if applicable. |
| **Cash** | Vault receipt recorded and dual-control count completed and attested. | N/A. | None after count and attestation; discrepancies must be resolved before any Mint Authorization. |
| **Internal transfer** | Atomic ledger posting within the DBIS ledger domain completed. | N/A. | None; internal transfers are final upon posting. |
### 2.1 Use of the matrix
- The ISO Gateway and signers must not issue or sign a Mint Authorization unless the applicable trigger for the chosen FundsStatus has been met for the rail type in question.
- OFF_LEDGER_FINAL may be used only where DBIS policy explicitly permits it for that rail and where external confirmation and reconciliation have been completed as defined in internal procedures.
- Reversal windows must be respected; no Mint Authorization may assert finality for a rail type until any applicable reversal window has elapsed or has been explicitly waived by policy.
---
## 3. Accounting Sequence Requirements
### 3.1 Required sequence
Before any Mint Authorization may be issued:
1. **Double-entry posting** must be completed in the DBIS ledger domain for the underlying transaction (or batch) that the Mint Authorization will represent.
2. **Reserve account tagging** must be applied as required by DBIS policy (e.g., omnibus, segregated, or designated reserve accounts).
3. **Accounting reference (accountingRef)** must be produced in the deterministic form defined below and must be immutable once the posting is final.
No Mint Authorization may reference an accountingRef that does not correspond to a completed, compliant posting in the ledger domain.
### 3.2 Deterministic accountingRef structure
For auditability and reproducibility, the value placed in the Mint Authorization field `accountingRef` must be derived as follows:
```
accountingRef = keccak256(
ledgerSystemId,
journalId,
batchNumber,
postingTimestamp,
reserveAccountId
)
```
Where:
- **ledgerSystemId** identifies the ledger system (e.g., core banking or designated subsystem).
- **journalId** is the unique identifier of the journal entry or batch.
- **batchNumber** is the batch or sequence number applicable to the posting.
- **postingTimestamp** is the time at which the posting was made final (e.g., Unix seconds or block-consistent value as defined by policy).
- **reserveAccountId** identifies the reserve or settlement account(s) involved.
The exact encoding (e.g., ABI-packed bytes, ASCII concatenation) must be documented in operational procedures and must be consistent so that the same inputs always produce the same accountingRef. This allows external parties to verify that an on-chain accountingRef corresponds to a specific ledger posting.
### 3.3 Ordering and idempotency
- Posting must occur **before** the Mint Authorization is signed and submitted.
- Each accountingRef must correspond to at most one Mint Authorization (one-to-one) unless policy explicitly permits a defined exception (e.g., split instructions with a defined convention). Any such exception must be documented and auditable.
---
## 4. Mint Authorization Preconditions
A Mint Authorization (MintAuth) may be issued only when all of the following are satisfied. The Technical Spec defines the on-chain structure; this section defines the **operational and compliance** preconditions.
### 4.1 Good funds and finality
- For the rail type and corridor in question, the applicable trigger from the Good Funds Matrix (Section 2) for the chosen FundsStatus (ON_LEDGER_FINAL or OFF_LEDGER_FINAL) must have been met.
- No Mint Authorization may be issued with a FundsStatus that does not match the actual state of finality in the ledger or external rail.
### 4.2 Accounting
- Double-entry posting must be complete and the accountingRef must have been computed per Section 3.2.
- The accountingRef must be immutable (no further amendment to the underlying posting that would change the deterministic hash).
### 4.3 Compliance
- All required compliance checks (KYC, AML, sanctions, jurisdiction, limits, and any corridor-specific rules) must have been completed with a clear pass.
- No exception or override may be used unless explicitly permitted by DBIS policy and recorded for audit.
### 4.4 Evidence bundle and isoHash
- The canonical ISO (or equivalent) evidence bundle that supports the settlement must be assembled and hashed to produce `isoHash`.
- The evidence bundle must include at least: message type, identifiers (e.g., UETR, EndToEndId, instruction Id), amount, currency, parties, and timestamp consistent with finality. The exact schema must be documented in operational procedures.
- `isoHash` in the Mint Authorization must equal the hash of this canonical bundle so that on-chain settlement is cryptographically tied to the off-chain evidence.
### 4.5 Signers
- The authorization must be signed by a set of signers that satisfies the quorum rules defined in the Technical Spec (e.g., 3-of-5 with COMPLIANCE mandatory).
- All signers must be allowlisted and effective at the time of signing (see Section 6).
- Signers must not sign until all preconditions in Sections 4.1–4.4 are satisfied.
### 4.6 Time window and domain
- `notBefore` and `expiresAt` must be set so that the authorization is valid only within an acceptable window (e.g., not more than 15 minutes from issuance, per Technical Spec recommendation).
- `chainId` must be 138 and `verifyingContract` must be the DBIS SettlementRouter address. No Mint Authorization may be issued for another chain or contract.
---
## 5. Reversal and Exception Handling
### 5.1 Before Mint Authorization submission
- If a reversal or exception is identified before the Mint Authorization has been submitted on-chain, no Mint Authorization may be issued for that settlement.
- The ledger domain must be corrected (reversal entry, adjustment, or exception posting) as per standard accounting and compliance procedures. Any subsequent new settlement may result in a new, distinct Mint Authorization with a new messageId and accountingRef.
### 5.2 After Mint Authorization issuance but before on-chain submission or before expiry
- If the underlying transaction is reversed or an exception is declared after the Mint Authorization has been signed but before it has been submitted on-chain, or before its `expiresAt` time:
- The Mint Authorization must be treated as invalid and must **not** be submitted.
- Signers or the ISO Gateway must revoke or withhold the authorization. Procedures must ensure that such authorizations are not submitted later by mistake.
### 5.3 After mint execution on-chain
- Once the SettlementRouter has accepted the Mint Authorization and the GRU Mint Controller has executed the mint, the on-chain settlement is **final** from the perspective of the rail contracts.
- Reversals or corrections in the fiat/ledger domain **do not** automatically reverse on-chain mints. Any corrective action (e.g., burn, offset, or recall) must be governed by a separate policy:
- **Burn or offset:** Where policy requires that a mistaken or reversed settlement be corrected, the designated process (e.g., burn of GRU or offsetting journal entry and burn) must be executed in accordance with DBIS procedures and, where applicable, with a new authorization or admin process.
- The Rulebook does not define the technical burn path; the Technical Spec and operational procedures must specify how burns or offsets are authorized and executed.
- Disputes must be handled per Section 5.4 and incident procedures.
### 5.4 Disputes and exceptions
- Participants must report disputes or exceptions in accordance with DBIS incident and dispute procedures.
- No Mint Authorization may be issued for a transaction that is under dispute or exception until the dispute or exception is resolved and good funds are re-established per the Good Funds Matrix.
- Post-mint disputes do not invalidate the on-chain settlement; they trigger the corrective and dispute-resolution procedures defined by DBIS policy.
---
## 6. Signer Governance and Revocation Timing
### 6.1 Signer roles and quorum
- Signers are classified by category (e.g., OPS, COMPLIANCE, CUSTODY, RISK, AUDITOR) as defined in the Technical Spec.
- The default quorum is 3-of-5, with COMPLIANCE mandatory. No Mint Authorization may be issued or submitted unless the signer set satisfies the quorum and category rules in effect at the time of submission.
### 6.2 Effective and revoked block semantics (recommended for v1.5+)
- To avoid timing exploits, DBIS should maintain for each signer:
- **Effective-from block (or time):** The signer’s signature is valid only for Mint Authorizations submitted on-chain at or after this block (or equivalent time).
- **Revoked-at block (or time):** The signer’s signature is not valid for Mint Authorizations submitted on-chain at or after this block (or equivalent time).
- The SettlementRouter (or supporting logic) should accept a signature only if, at the block at which `submitMintAuth` is executed, the signer is within the effective window and not yet revoked.
- Until such block-based (or time-based) checks are implemented on-chain, operational procedures must ensure that:
- No Mint Authorization signed by a signer after the decision to revoke is submitted.
- Any in-flight authorization signed before revocation is either submitted before the revocation takes effect or is cancelled and not submitted.
### 6.3 In-flight authorizations
- When a signer is revoked or suspended, any Mint Authorization that has been signed by that signer but not yet submitted must be treated as follows:
- If the remaining signers still satisfy the quorum and category rules, the authorization may be submitted only if policy permits and only before the signer’s revocation is effective on-chain.
- If the remaining signers no longer satisfy the quorum, the authorization must not be submitted; a new authorization with a new signer set must be produced if the settlement is still valid.
### 6.4 Compromised signer procedure
- If a signer key is suspected or confirmed compromised, SIGNER_ADMIN must revoke the signer immediately via the SignerRegistry.
- All in-flight Mint Authorizations that relied on that signer must be re-evaluated per Section 6.3. Any authorization not yet submitted that no longer meets quorum must not be submitted.
- Incident reporting and key rotation procedures must be followed as per DBIS security policy.
---
## 7. Incident and Emergency Controls
### 7.1 Router pause
- ROUTER_ADMIN may pause the SettlementRouter. When paused, no new Mint Authorizations may be submitted or executed.
- Pause should be used in the event of a security incident, suspected compromise, or operational emergency that requires a halt to settlement execution.
- Procedures must define who may request pause, who may execute it, and the process for resumption (including any required sign-offs or audits).
### 7.2 Mint controller pause
- ROUTER_ADMIN (or the role designated in the Technical Spec) may pause the GRU Mint Controller. When paused, the SettlementRouter may still accept and record Mint Authorizations, but mints will not be executed until the controller is unpaused.
- Use when mint execution must be halted but settlement recording or diagnosis must continue.
### 7.3 Participant suspension
- PARTICIPANT_ADMIN may set a participant’s status to SUSPENDED or REVOKED. Suspended participants’ operational wallets must not receive new mints until the participant is reinstated; the SettlementRouter and ParticipantRegistry enforce this per the Technical Spec.
- Suspension is appropriate when a participant is under investigation, in breach of terms, or poses a compliance or operational risk. Reinstatement must follow defined procedures.
### 7.4 Signer revocation
- SIGNER_ADMIN may remove a signer from the allowlist. Revocation is effective as per Section 6; no new Mint Authorizations may rely on that signer once revocation is effective.
- Used for routine rotation, suspected compromise, or disciplinary action. Procedures must document the effect on in-flight authorizations (Section 6.3).
### 7.5 Corridor or product suspension
- Where the Technical Spec or supporting contracts allow corridor-specific or product-specific caps or suspension, ROUTER_ADMIN (or designated role) may suspend a corridor or product to halt new settlements in that segment while investigation or remediation is performed.
- Procedures must define escalation and resumption.
### 7.6 Coordination and communication
- Incident response procedures must define how pause, suspension, and revocation decisions are communicated to participants, signers, and operators, and how status is restored after the incident is resolved.
---
## 8. Audit and Reporting Standards
### 8.1 Required mappings
The following mappings must be maintained and be available for audit and regulatory examination:
- **messageId ↔ ISO evidence bundle:** For each Mint Authorization submitted (whether accepted or rejected), the messageId must be linked to the full ISO (or equivalent) evidence bundle whose hash is `isoHash`.
- **messageId ↔ accountingRef:** Each messageId must be linked to the accountingRef and thus to the ledger posting(s) that represent the underlying settlement.
- **accountingRef ↔ ledger postings:** Each accountingRef must be traceable to the exact journal/batch and reserve account(s) in the ledger domain, using the deterministic construction in Section 3.2.
### 8.2 Retention
- Evidence bundles, ledger postings, and the mappings above must be retained for the period required by applicable law and regulation and by DBIS policy (e.g., minimum seven years or as specified for financial records).
- On-chain events (SettlementRecorded, MintExecuted, MessageIdConsumed, and related) are immutable; off-chain records must be retained and protected to support the same retention and accessibility requirements.
### 8.3 Reconciliation
- Reconciliation between ledger domain, ISO Gateway state, and on-chain settlement state must be performed at the frequency defined by DBIS policy (e.g., daily or real-time for high-value corridors).
- Discrepancies must be escalated and resolved per incident and exception procedures; no Mint Authorization may be issued against unreconciled or disputed positions unless explicitly permitted by policy and documented.
### 8.4 Reporting extracts
- DBIS must be able to produce camt-like or equivalent extracts for:
- Completed settlements (by period, corridor, participant).
- Rejected or failed authorizations (with reason where available).
- Signer additions, removals, and quorum changes.
- Participant status changes (registration, suspension, revocation).
- Such extracts support regulatory reporting, internal control, and counterparty due diligence.
---
## 9. Versioning and Amendment Process
### 9.1 Version identification
- This document is the DBIS Rail Rulebook v1. Subsequent versions must be clearly versioned (e.g., v1.1, v2) and dated.
- The effective date of each version must be stated in the document or in a companion change log.
### 9.2 Amendment authority
- Amendments to the Rulebook are approved by the governance body or process designated by DBIS (e.g., board, risk committee, or delegated policy owner). The Technical Spec remains the authority for on-chain behavior; the Rulebook may be updated to reflect new operational or compliance requirements without necessarily changing contracts.
### 9.3 Effective date of amendments
- Each amendment must specify its effective date. Until that date, the previous version of the affected sections remains in force.
- Operational procedures (e.g., ISO Gateway configuration, signer training, participant communications) must be updated to align with the new version before the effective date, where possible.
- If an amendment affects the interpretation of FundsStatus, accountingRef, or Mint Authorization preconditions, signers and the ISO Gateway must not issue or sign authorizations under the new interpretation before the effective date.
### 9.4 Publication and accessibility
- The current Rulebook must be published in a location accessible to participants, signers, and auditors (e.g., docs/dbis-rail/ or an official policy repository). Superseded versions should be retained for audit and reference.
---
## Document control
| Field | Value |
|-------|--------|
| Title | DBIS Rail Rulebook v1 |
| Network | DBIS Mainnet (ChainID 138) |
| Companion | [DBIS Rail Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md) |
| Version | 1 |
| Status | Active |

253
docs/dbis-rail/DBIS_RAIL_SECURITY_THREAT_MODEL_V1.md Normal file
View File

@@ -0,0 +1,253 @@
# DBIS Rail Security Threat Model v1
**Network:** DBIS Mainnet (ChainID 138)
**Document type:** Security threat assessment
**Companion documents:** [DBIS Rail Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md), [DBIS Rail Rulebook v1](DBIS_RAIL_RULEBOOK_V1.md)
---
## 1. Scope
### 1.1 Assets protected
- **GRU (and linked c* token) supply integrity:** Unauthorized mint must be impossible without a valid Mint Authorization satisfying signer quorum and router policy.
- **Settlement audit trail:** Immutability and correctness of SettlementRecorded and MintExecuted events; binding of messageId, isoHash, and accountingRef to ledger and ISO evidence.
- **Participant and signer registries:** Integrity of allowlists; only authorized participants receive mints; only allowlisted signers contribute to valid authorizations.
- **Policy enforcement:** Per-message and per-corridor caps, time windows, and replay protection are enforced on-chain.
### 1.2 Trust boundaries
- **On-chain / off-chain:** The chain does not parse ISO-20022; it accepts only compact MintAuth structs and signatures. Finality of fiat/ledger is determined off-chain; the chain enforces authorization integrity and policy.
- **Validator layer / application layer:** QBFT validators produce blocks; DBIS Rail contracts (RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController) execute in those blocks. Compromise of the application layer does not imply compromise of consensus; compromise of consensus can affect availability and ordering.
- **Signer set / ISO Gateway:** Signers produce ECDSA signatures over MintAuth; the ISO Gateway (or relayer) assembles evidence, computes isoHash and accountingRef, and submits to the router. Compromise of the Gateway can lead to incorrect or malicious authorizations if signers sign without independent verification; the chain does not verify ledger or compliance correctness, only signature and policy.
### 1.3 Assumptions
- **QBFT permissioned validators:** The validator set is permissioned and operated under DBIS (or designated) control. We assume Byzantine fault tolerance within the stated threshold (e.g., &lt; 1/3 malicious); we do not assume permissionless or economically secured consensus.
- **EIP-712 and ECDSA:** Signatures over MintAuth use EIP-712 typed data and standard ECDSA. We assume no compromise of the elliptic curve or hash functions used.
- **Off-chain ISO Gateway and ledger:** The ISO Gateway, ledger domain, and compliance systems are in the regulated/operational domain. The threat model treats their compromise as an off-chain threat (Section 3.F); the chain cannot detect misclassification of good funds or forged accountingRef if the evidence bundle and ledger are compromised before signing.
- **Single chain:** MintAuth is bound to chainId 138 and a specific verifyingContract. Cross-chain replay is out of scope for same-MintAuth reuse; multi-chain deployment would require a separate threat analysis.
- **No optional v1.5+ features:** Signer effective/revoked block semantics are recommended in the Rulebook but not assumed in this v1 model; quorum and time window are the primary signer-related mitigations.
---
## 2. System Trust Model
### 2.1 Trust domains
| Domain | Trust level | Description |
|--------|-------------|-------------|
| **Validator layer** | Byzantine tolerant (QBFT) | Block production and ordering. Up to f faulty validators (e.g., f &lt; n/3) tolerated; no finality loss. Validators do not execute DBIS Rail logic beyond inclusion in blocks. |
| **Signer layer** | Threshold enforced | Mint authorization requires a quorum of allowlisted signers (e.g., 3-of-5 with COMPLIANCE mandatory). Trust: signers are independent and keys are protected; compromise of enough signers breaks the model. |
| **ISO Gateway** | Regulated domain | Produces MintAuth inputs (messageId, isoHash, accountingRef, fundsStatus, etc.) and runs compliance. Trust: Gateway and ledger are correct and not compromised; Rulebook is followed. |
| **Settlement router contract** | Deterministic | Enforces signature verification, replay protection, time window, policy caps, participant allowlist. Trust: correct implementation and no reentrancy/overflow bugs; admin keys not abused. |
| **GRU Mint Controller** | Deterministic | Mints only when called by SettlementRouter with validated MintAuth. Trust: only router can call mint; no direct mint path; upgrade path is governed. |
| **Registries (Root, Participant, Signer)** | Admin-controlled | Hold component addresses and allowlists. Trust: admin and governance (multisig/timelock) do not collude to open backdoors or bypass policy. |
### 2.2 Explicit trust separation
- **Validators** do not sign Mint Authorizations; they only order transactions. A malicious validator can censor or reorder but cannot mint without a valid MintAuth.
- **Signers** do not produce blocks; they only sign MintAuth. Compromise of signers can lead to unauthorized authorizations; compromise of validators does not by itself create new GRU.
- **Router** does not decide fiat finality; it enforces that authorizations are properly signed and within policy. Misclassification of funds (e.g., OFF_LEDGER_FINAL used when not justified) is an off-chain/operational failure, not a router bug.
- **Mint Controller** does not validate signatures; it trusts the router. The single point of enforcement for “who can mint” is the router’s access control to the mint path.
---
## 3. Threat Categories
### 3.A Authorization layer attacks
| Threat | Description |
|--------|-------------|
| **Signature forgery** | Attacker produces a valid ECDSA signature over MintAuth without holding a signer key. |
| **Signature replay** | Reuse of a previously submitted MintAuth (same messageId) to mint again. |
| **Cross-chain replay** | Reuse of a MintAuth on another chain (e.g., same messageId on a fork or different chainId). |
| **VerifyingContract spoofing** | MintAuth signed for a different contract or chain is submitted to the router (e.g., wrong chainId or verifyingContract). |
| **Expired auth reuse** | Submission of a MintAuth after expiresAt or before notBefore. |
| **Signer compromise** | One or more signer keys are stolen or coerced; attacker obtains enough signatures to meet quorum. |
| **Quorum manipulation** | Attacker causes the set of signers to satisfy quorum with fewer than intended independent parties (e.g., one entity controlling multiple signer keys). |
| **Category bypass** | Authorization accepted with signer set that does not include required category (e.g., COMPLIANCE) or does not meet category mask rules. |
**Mitigations:**
- **EIP-712 domain separation:** chainId and verifyingContract are part of the signed payload; signatures for other chains or contracts do not verify on this router.
- **messageId replay lock:** Router maintains `usedMessageIds`; second submission of same messageId reverts. One-time use per messageId.
- **Time window:** Router checks `block.timestamp` within [notBefore, expiresAt]; expired or not-yet-valid auths revert.
- **SignerRegistry and quorum:** Only allowlisted signers count; required number of signatures and required category mask (e.g., COMPLIANCE + 2 of OPS/CUSTODY/RISK/AUDITOR) enforced on-chain.
- **Signer effective/revoked block (v1.5+):** Rulebook recommends signer effective-from and revoked-at block; when implemented, router rejects signatures from signers outside the effective window.
- **Operational:** Key hygiene, HSM or secure enclave for signer keys, separation of signer roles from Gateway operators.
---
### 3.B Ledger / accounting attacks
| Threat | Description |
|--------|-------------|
| **Fake accountingRef** | Attacker invents an accountingRef that does not correspond to a real ledger posting, or reuses one from another context. |
| **Off-ledger misclassification** | Funds not yet final (or not final on the declared rail) are marked ON_LEDGER_FINAL or OFF_LEDGER_FINAL to obtain a Mint Authorization. |
| **Good funds misrepresentation** | Reversal window not elapsed, or exception/dispute present, but MintAuth is still issued. |
| **Duplicate ledger posting** | Same underlying settlement is posted twice and two Mint Auths are issued (double mint). |
| **Partial settlement submission** | Only part of a batch or obligation is posted; MintAuth is issued for full amount or wrong recipients. |
**Mitigations:**
- **Deterministic accountingRef:** Rulebook defines accountingRef = keccak256(ledgerSystemId, journalId, batchNumber, postingTimestamp, reserveAccountId). Audit can verify that on-chain accountingRef matches a unique ledger posting; invented or reused refs do not match any valid posting.
- **Rulebook good funds matrix:** Operational requirement that MintAuth is issued only when the correct finality trigger for the rail type and FundsStatus is met; reversal windows and exception handling are policy-enforced before signing.
- **Evidence bundle hashed into isoHash:** The canonical ISO (or equivalent) bundle is hashed; isoHash on-chain ties the authorization to that bundle. Operational procedures require bundle to reflect actual finality and posting; tampering or misclassification is detectable in audit.
- **Operational reconciliation:** Rulebook requires reconciliation between ledger, Gateway, and on-chain state; discrepancies and duplicate postings must be caught before or after submission and handled by incident procedures.
- **One-to-one accountingRef–MintAuth:** Rulebook states each accountingRef corresponds to at most one MintAuth unless a defined exception exists; reduces double-mint from duplicate posting.
---
### 3.C Settlement router attacks
| Threat | Description |
|--------|-------------|
| **Reentrancy** | Attacker causes router to re-enter during submitMintAuth (e.g., via callback from recipient or mint path) and execute logic twice. |
| **Overflows** | Integer overflow in amount aggregation or corridor usage leading to cap bypass or incorrect state. |
| **Multi-recipient edge case** | Mismatch between recipients and amounts; wrong recipient gets wrong amount or length check bypassed. |
| **Policy cap bypass** | Per-message or daily corridor cap exceeded by splitting, wrapping, or exploiting rounding. |
| **Paused state bypass** | Mint or settlement executed while router (or mint controller) is paused. |
| **Corridor limit bypass** | Daily or aggregate corridor usage not correctly incremented or checked. |
**Mitigations:**
- **CEI (Checks-Effects-Interactions):** All state updates (usedMessageIds, corridor usage) before external call to Mint Controller; no reentrancy into router state from mint path.
- **ReentrancyGuard:** Use nonReentrant modifier on submitMintAuth where applicable.
- **Strict array length equality:** Require recipients.length == amounts.length and validate before any use; revert on mismatch.
- **Caps enforced before mint:** Compute total amount and corridor usage; revert if maxAmountPerMessage or corridorDailyCap exceeded; only then call mint controller.
- **Paused modifiers:** Router and Mint Controller check paused flag at entry; ROUTER_ADMIN can pause both; no settlement or mint when paused.
- **Safe math / Solidity 0.8+:** Use checked arithmetic to prevent overflows in aggregation and corridor counters.
- **Audit and tests:** Unit and integration tests for multi-recipient, cap boundary, and pause behavior.
---
### 3.D Mint controller attacks
| Threat | Description |
|--------|-------------|
| **Direct mint bypass** | Actor other than SettlementRouter calls mint (e.g., owner, MINTER_ROLE on token, or public mint function). |
| **Role escalation** | Attacker gains MINTER_ROLE or equivalent on the token or Diamond facet and mints without going through router. |
| **Diamond facet misconfiguration** | GRU mint facet is callable by other contracts or EOAs; or router address not correctly set as sole caller. |
| **Proxy upgrade takeover** | Upgrade of Mint Controller or token implementation to a malicious version that mints to attacker or disables router check. |
**Mitigations:**
- **Only SettlementRouter can mint:** Mint Controller’s mintFromAuthorization checks msg.sender == settlementRouter; no other path to mint. Token or Diamond mint facet must be restricted to Mint Controller (or router) only.
- **Revoke owner mint:** Any direct owner-mint or default MINTER_ROLE on GRU/c* tokens must be removed or permanently revoked; sole mint path is router → Mint Controller.
- **Governance timelock:** Upgrades to Mint Controller, router, or critical facets use timelock and multisig so that a single compromised key cannot push a malicious implementation.
- **Upgrade and config event logging:** Emit events on upgrade and on settlementRouter address change so that monitoring and governance can detect unauthorized changes.
- **Deployment checklist:** Verify that no token or facet exposes a mint (or equivalent) function to the public or to any address other than the Mint Controller.
---
### 3.E Validator layer attacks
| Threat | Description |
|--------|-------------|
| **Validator collusion** | More than f (e.g., ≥ n/3) validators collude to produce incorrect blocks or break finality. |
| **Censorship** | Validators refuse to include DBIS Rail transactions (e.g., submitMintAuth) to disrupt settlement. |
| **Chain halt** | Validators stop producing blocks so that no new settlements can be recorded. |
| **Reorg attempts** | Attacker with sufficient hash power or validator control attempts to reorg blocks containing settlement transactions to double-spend or revert mints. |
| **Validator key compromise** | One or more validator keys are stolen; attacker can sign blocks (within QBFT rules) or attempt to join the set. |
**Mitigations:**
- **QBFT finality:** Once a block is finalized, it is not reverted under normal QBFT assumptions. Reorg of finalized blocks would require violation of the consensus protocol.
- **Documented validator governance:** Validator set and rotation are documented (operationally for v1); multi-operator or multi-party control reduces single-point control.
- **Emergency pause:** If chain halts or censorship is detected, ROUTER_ADMIN can pause router and mint controller; no new mints until chain and governance are restored.
- **Permissioning:** Besu permissions (permissions-nodes-config-file, permissions-accounts-config-file) restrict who can validate; compromise of a non-validator node does not by itself allow block production.
- **Monitoring:** Block production and finality monitored; alerts on extended no-finality or censorship patterns.
---
### 3.F Off-chain threats
| Threat | Description |
|--------|-------------|
| **ISO Gateway compromise** | Attacker controls or compromises the Gateway; produces MintAuth with fake isoHash, wrong accountingRef, or misclassified fundsStatus; obtains signer signatures (e.g., via social engineering or compromised signer workflow). |
| **Signer key theft** | Attacker steals signer private keys (e.g., from HSM or key store) and signs MintAuth without legitimate settlement. |
| **Insider collusion** | Multiple insiders (e.g., Gateway operators + signers) collude to issue authorizations for non-existent or invalid settlements. |
| **Compliance system failure** | Sanctions/AML/KYC checks are bypassed or misconfigured; prohibited party or transaction receives a Mint Authorization. |
| **Accounting system compromise** | Ledger or posting system is tampered so that accountingRef points to a fabricated or altered posting. |
**Mitigations:**
- **HSM or secure enclave for signers:** Signer keys stored and used in HSM or TEE; reduces theft and use by Gateway operators.
- **Role separation:** Signers are distinct from Gateway operators; signers verify (or have independent view of) settlement and compliance before signing; Rulebook requires preconditions to be met before signers sign.
- **Quorum design:** 3-of-5 with COMPLIANCE mandatory ensures at least three independent sign-offs and that compliance is never bypassed by a single role.
- **Signer revocation procedure:** Rulebook defines revocation and in-flight handling; compromised signer is removed and pending auths re-evaluated.
- **Monitoring and audit logs:** Gateway, ledger, and signer actions logged; mapping messageId ↔ evidence ↔ accountingRef retained; anomalies and exceptions investigated.
- **Compliance and audit:** Regular audit of Rulebook adherence, good funds matrix application, and evidence bundle construction; compliance controls tested independently.
---
## 4. Risk Severity Classification
### 4.1 Severity levels
- **Critical:** Unauthorized mint or permanent loss of funds/supply integrity; or complete bypass of authorization or policy. Requires immediate mitigation and may warrant pause.
- **High:** Significant abuse possible (e.g., large unauthorized mint, systemic misclassification) but with containment or detection; or single point of failure that could be exploited.
- **Medium:** Limited scope (e.g., one messageId replay, one signer compromise without quorum) or depends on multiple failures; or availability impact without direct mint abuse.
- **Low:** Theoretical or requires unrealistic assumptions; or operational nuisance with clear procedure.
### 4.2 Threat severity table
| Threat | Severity | Reason |
|--------|----------|--------|
| Signer quorum compromise (enough keys to meet 3-of-5) | Critical | Enables unauthorized MintAuth and thus unauthorized mint. |
| ISO Gateway + signer collusion (bypass good funds) | Critical | Can issue valid MintAuth for non-final or fake settlement; chain cannot detect. |
| Direct mint bypass (token or Mint Controller) | Critical | GRU can be minted without any MintAuth; breaks rail integrity. |
| messageId replay (if not enforced) | Critical | Same MintAuth executed twice; double mint. |
| Signature forgery (break ECDSA or EIP-712) | Critical | Attacker could forge valid signatures; treat as cryptographically infeasible but severity is critical if possible. |
| Fake accountingRef accepted without audit | High | Audit and Rulebook mitigate; if ledger and Gateway both compromised, fake ref can support unauthorized auth. |
| Good funds misrepresentation (e.g., ACH before return window) | High | Operational/Rulebook failure; can lead to mint against reversible settlement. |
| Reentrancy or overflow in router | High | Could allow double mint or cap bypass if not implemented correctly. |
| Router or Mint Controller upgrade to malicious implementation | High | Governance and timelock mitigate; single key compromise could push bad upgrade if governance is weak. |
| Single signer compromise (insufficient for quorum) | Medium | Cannot by itself produce valid MintAuth; must combine with other signers or social engineering. |
| Single validator compromise | Medium | QBFT tolerates f faulty; one validator cannot break finality. |
| Censorship of settlement transactions | Medium | Availability impact; no direct mint; pause and operational response. |
| Expired or wrong-chain MintAuth submitted | Low | Reverts on-chain; no effect if checks are correct. |
| Category bypass (e.g., no COMPLIANCE signer) | Low | Reverts if SignerRegistry and router enforce category mask. |
---
## 5. Residual Risk
The following are **intentionally trusted** in this model. They are not verified on-chain; their failure is an operational or off-chain risk.
- **ISO Gateway correctness:** The Gateway correctly applies the Rulebook good funds matrix, builds the evidence bundle, computes isoHash and accountingRef per the deterministic rule, and does not issue MintAuth until preconditions are satisfied. The chain does not verify ledger or compliance state.
- **Ledger integrity:** The core (or designated) ledger correctly records postings, and accountingRef is produced only for completed, compliant postings. No tampering or fabrication of postings.
- **Compliance process integrity:** KYC, AML, sanctions, and jurisdiction checks are correctly applied and only passing transactions receive signer approval. No bypass or misconfiguration.
- **Validator majority honesty:** At least 2/3 (or the QBFT threshold) of validators follow the protocol. Finality is maintained; no reorg of finalized blocks.
- **Signer independence and key security:** Signers are distinct entities/roles; they do not sign without verifying that preconditions are met; private keys are protected (HSM, procedures). Compromise of fewer than quorum signers does not yield a valid MintAuth.
- **Admin and governance:** ROOT_ADMIN, PARTICIPANT_ADMIN, SIGNER_ADMIN, ROUTER_ADMIN are not abused; multisig or timelock is used for upgrades and critical config; no backdoor deployment or role grant to attacker.
**Institutional implication:** Residual risk is documented so that auditors and counterparts understand that the chain enforces **authorization integrity and policy**, not **fiat finality or compliance correctness**. The Rulebook and operational controls are the mitigation for residual risk; the Threat Model does not assume they are perfect but states that their failure is outside the on-chain threat perimeter.
---
## 6. Versioning and Review Cycle
- **Version:** This document is DBIS Rail Security Threat Model v1.
- **Review frequency:** At least **annual** review; update when design or deployment changes materially affect threats or mitigations.
- **Triggered review:** Revisit and update the threat model when:
- Signer quorum or category rules change (e.g., 2-of-3, 4-of-7, or new category).
- A new corridor or product type is added (new policy or cap structure).
- Validator model or governance changes (e.g., on-chain validator rotation).
- New contracts or facets are added to the DBIS Rail (e.g., new registry or router feature).
- A security incident or audit finding indicates a new threat or ineffective mitigation.
- **Ownership:** Security or risk function maintains the document; changes are approved per DBIS governance (e.g., CISO, risk committee, or delegated owner).
- **Publication:** Current version is published with the other DBIS Rail docs (e.g., docs/dbis-rail/); superseded versions retained for audit.
---
## Document control
| Field | Value |
|-------|--------|
| Title | DBIS Rail Security Threat Model v1 |
| Network | DBIS Mainnet (ChainID 138) |
| Companions | [Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md), [Rulebook v1](DBIS_RAIL_RULEBOOK_V1.md) |
| Version | 1 |
| Status | Active |

99
docs/dbis-rail/DBIS_RAIL_STABLECOIN_POLICY_V1_5.md Normal file
View File

@@ -0,0 +1,99 @@
# DBIS Rail Stablecoin Policy v1.5
**Network:** DBIS Mainnet (ChainID 138)
**Document type:** v1.5 Add-on — Canonical USDC/USDT and stablecoin definition, registry, monitoring
**Companion documents:** [DBIS Rail Technical Spec v1](DBIS_RAIL_TECHNICAL_SPEC_V1.md), [DBIS Rail Rulebook v1](DBIS_RAIL_RULEBOOK_V1.md), [DBIS Rail Conversion Router Spec v1.5](DBIS_RAIL_CONVERSION_ROUTER_SPEC_V1_5.md)
---
## 1. Purpose and Scope
This add-on defines USDC, USDT, and other stablecoins as **legally/operationally defined instruments** with:
- A **Stablecoin Reference Registry** (on-chain and documented) listing token symbol, address, issuer/bridge, legal claim type, redemption path, reserve disclosure, risk tier, pause authority, and status.
- A **Canonical Stablecoin Policy** (Rulebook addendum): only allow swaps and routing into canonical stablecoin IDs that are registered and in ACTIVE status.
- **Monitoring** for peg deviation, bridge health, and emergency corridor halt when stablecoin risk triggers.
The result is that “USDC/USDT” are defined instruments with redemption standing and routing rules, not merely ERC-20 labels.
---
## 2. Stablecoin Reference Registry
### 2.1 On-Chain and Documented
The registry may be implemented as an on-chain contract (e.g. StablecoinReferenceRegistry) and/or maintained in documented form for audit. The following fields are required for each registered stablecoin:
| Field | Description |
|-------|-------------|
| **tokenSymbol** | Symbol (e.g. USDC, USDT, cUSDC). |
| **tokenAddress** | Contract address on Chain 138. |
| **issuerOrBridge** | Issuer or bridge entity responsible for redemption or reserve. |
| **legalClaimType** | Nature of claim (e.g. direct claim on issuer, claim via bridge, custodial). |
| **redemptionPath** | How the holder may redeem (e.g. issuer portal, designated custodian, bridge withdrawal). |
| **reserveDisclosureRef** | Reference to reserve disclosure (e.g. URL or document id). |
| **riskTier** | Policy-defined tier (e.g. 1–3) for limits or treatment. |
| **pauseAuthority** | Address or role that can pause the token (if applicable). |
| **stablecoinStatus** | ACTIVE / SUSPENDED / REVOKED. Only ACTIVE may be used for routing. |
### 2.2 Administration
- Registration and updates (including status changes) are restricted to a defined admin or role (e.g. STABLECOIN_REGISTRAR or governance).
- Only tokens that have completed a registration and risk review may be added. Status may be set to SUSPENDED (e.g. during investigation) or REVOKED (removed from use) without removing the record.
### 2.3 Use in Routing
- The Conversion Router (and any DEX/aggregator integration governed by this policy) must resolve token by **canonical stablecoin ID** (registry key or tokenAddress that appears in the registry with status ACTIVE).
- Swaps or routes into a token that is not in the registry, or whose status is not ACTIVE, must be rejected when this policy applies.
---
## 3. Rulebook Addendum — Canonical Stablecoin Policy
### 3.1 Policy Statement
- Only allow swaps (and, where policy applies, other flows) into **canonical stablecoin IDs** registered in the Stablecoin Reference Registry.
- Require **stablecoinStatus = ACTIVE** to route. Tokens in SUSPENDED or REVOKED status must not be used as output (or input, where policy so requires) until re-approved.
- The Conversion Router and any DEX/aggregator integration must resolve token by registry; use of an unregistered or non-ACTIVE address is a policy violation and must be rejected by the system.
### 3.2 Relation to Good Funds
- The Rulebook’s good funds matrix (Rulebook §2) and finality triggers apply to settlement and mint. This add-on does not change them.
- The Canonical Stablecoin Policy governs **which** stablecoin contracts may be used as destinations (or sources) for conversions and routing, ensuring that only defined instruments with disclosed redemption path and status are permitted.
---
## 4. Monitoring
### 4.1 Peg Deviation Thresholds
- Define alert and, if policy requires, auto-halt thresholds for peg deviation (e.g. ±2% from 1:1 for USD-pegged stablecoins).
- When a threshold is breached, procedures must define: alerting, escalation, and whether conversion or mint into that stablecoin is temporarily halted until the issue is resolved or the token is suspended in the registry.
### 4.2 Bridge Health (Bridged Stablecoins)
- For stablecoins that are bridged (e.g. bridged USDC), monitor bridge health and liquidity.
- If bridge is degraded or compromised per DBIS policy, the token may be set to SUSPENDED in the registry and routing halted until re-approved.
### 4.3 Emergency Corridor Halt
- If stablecoin risk triggers (e.g. depeg, issuer event, bridge failure), a designated role may trigger an **emergency corridor halt** for that token or corridor.
- Procedures must document: who may trigger, how (e.g. set status to SUSPENDED, or invoke a pause on the Conversion Router for that token), and the process for resumption (including any required sign-offs or audits).
---
## 5. Cross-References
- **Technical Spec** — Participant and registry patterns; optional on-chain StablecoinReferenceRegistry follows similar access-control and event patterns.
- **Conversion Router Spec v1.5** — Venue and token allowlist; tokenOut (and tokenIn when required) must resolve to a canonical stablecoin ID in ACTIVE status per this policy.
- **Rulebook** — Good funds (§2), compliance (§4.3); this add-on is a Rulebook addendum for canonical stablecoin definition and routing.
---
## 6. Document Control
| Field | Value |
|-------|-------|
| Title | DBIS Rail Stablecoin Policy v1.5 |
| Version | 1.5 |
| Status | Active |

496
docs/dbis-rail/DBIS_RAIL_TECHNICAL_SPEC_V1.md Normal file
View File

@@ -0,0 +1,496 @@
# DBIS Rail Technical Spec v1
**Network:** DBIS Mainnet (ChainID 138)
**Purpose:** Bank-rail settlement + GRU mint orchestration using ISO-20022–anchored authorizations.
## 0. Scope and Non-Goals
### In-scope
* A standardized **message-to-settlement lifecycle** rooted in ISO-20022 evidence, but executed as **compact on-chain authorizations**.
* On-chain contracts that:
* enforce **participant allowlisting**
* validate **threshold signer** authorization
* provide **replay protection**
* record immutable **settlement + accounting references**
* gate GRU minting so it is only possible after compliant authorization
### Out-of-scope (v1)
* On-chain parsing of ISO-20022 XML/JSON payloads.
* ZK proofs or light-client proofs of bank-rail events.
* Fully automated validator rotation on-chain (documented operationally for v1).
---
## 1. Definitions
### Terms
* **FI**: Financial Institution participant on the DBIS rail (bank, MSB, custodian, trustee, operator).
* **ISO Gateway**: Off-chain service that ingests ISO-20022 messages, runs compliance + accounting, and produces signed on-chain authorizations.
* **Mint Authorization (MintAuth)**: A compact signed instruction authorizing settlement recording and GRU minting.
* **Funds Status**:
* `ON_LEDGER_FINAL`: funds final in DBIS-controlled ledger domain (core/omnibus/segregated reserve).
* `OFF_LEDGER_FINAL`: funds final via external rail + reconciliation per DBIS policy.
* **Accounting Reference (accountingRef)**: Immutable identifier for the journal/batch/posting in DBIS ledger domain.
### Design principle
**The chain never "decides" fiat finality.**
Fiat finality, compliance, and accounting occur in the regulated domain; the chain enforces **authorization integrity and policy**.
---
## 2. System Overview
### 2.1 Contract set (v1)
1. **DBIS_RootRegistry**
2. **DBIS_ParticipantRegistry**
3. **DBIS_SignerRegistry**
4. **DBIS_SettlementRouter**
5. **DBIS_GRU_MintController**
> Note: Existing registries (e.g., UniversalAssetRegistry, ChainRegistry, GRU Diamond facets) remain valid. v1 adds DBIS Rail components in a way that can "wrap" or "gate" existing mint paths.
### 2.2 Roles
* **ROOT_ADMIN**: owns RootRegistry configuration.
* **PARTICIPANT_ADMIN**: can onboard/update participants.
* **SIGNER_ADMIN**: manages signer allowlist and quorum rules.
* **ROUTER_ADMIN**: can pause router, update policy caps.
* **MINTER**: **only** DBIS_SettlementRouter (for GRU mint execution).
---
## 3. Network and Governance Baseline (Chain 138)
### 3.1 Consensus
* **Besu QBFT** (permissioned) with ~2s block time, epoch ~30k blocks (document actual values used in current deployment).
* **Node allowlists** enforced by Besu permissioning config (`permissions-nodes-config-file`, `permissions-accounts-config-file`).
### 3.2 Governance in v1
* Validator management remains operational + infra-managed for v1.
* Contract governance uses a multisig or your GovernanceController/timelock pattern for admin roles.
---
## 4. Data Model
### 4.1 Participant
Participant represents an FI / operator entity allowed to initiate or receive settlement/mint instructions.
**Participant fields**
* `participantId: bytes32` (stable ID, e.g., hash of legal name + jurisdiction)
* `legalName: string`
* `jurisdiction: string`
* `entityType: enum` (BANK, MSB, CUSTODIAN, TRUSTEE, OPERATOR, AUDITOR)
* `status: enum` (ACTIVE, SUSPENDED, REVOKED)
* `policyTags: bytes32[]` (corridors, product permissions)
* `operationalWallets: address[]` (approved wallets for receipts/payouts)
* `signingKeys: address[]` (if participant is also a signer entity)
### 4.2 Mint Authorization (MintAuth)
MintAuth is a compact, deterministic struct signed by an allowlisted signer set.
```solidity
enum FundsStatus { ON_LEDGER_FINAL, OFF_LEDGER_FINAL }
enum AssetClass { GRU_M00, GRU_M0, GRU_M1 } // optional mapping; v1 can use GRU_M00 only
struct MintAuth {
// Identity / Evidence
bytes32 messageId; // unique; derived from UETR/EndToEndId/instructionId
bytes32 isoType; // e.g., keccak256("pacs.008"), keccak256("camt.054")
bytes32 isoHash; // hash of canonical ISO payload bundle (off-chain)
bytes32 accountingRef; // journal/batch/posting reference in DBIS ledger domain
FundsStatus fundsStatus; // ON_LEDGER_FINAL or OFF_LEDGER_FINAL
// Settlement intent
bytes32 corridor; // optional (e.g., USD->XAU->GRU, internal corridor tag)
AssetClass assetClass; // GRU tier/class
address[] recipients; // 1..N
uint256[] amounts; // matched length, base units
// Policy & replay window
uint64 notBefore; // unix seconds
uint64 expiresAt; // unix seconds
// Domain separation
uint256 chainId; // MUST be 138
address verifyingContract;// SettlementRouter address
}
```
**Rules**
* `recipients.length == amounts.length`
* `expiresAt > notBefore`
* `chainId == 138`
* `verifyingContract == address(DBIS_SettlementRouter)`
* `messageId` must be unique (replay protection)
---
## 5. Message Lifecycle
### 5.1 Off-chain (ISO Gateway) steps
1. **Ingest ISO-20022** message(s) and evidence:
* pacs / camt / pain family as applicable
* cash receipt evidence for M0 if used
2. **Canonicalize** and compute:
* `isoHash = hash(canonical_bundle)`
* `messageId = deterministicUniqueId(...)`
* `isoType = keccak256(typeString)`
3. Determine **funds status**:
* ON_LEDGER_FINAL: final posting in DBIS ledger domain
* OFF_LEDGER_FINAL: external finality + reconciliation
4. Perform required **double-entry accounting**:
* must produce `accountingRef`
5. Run compliance gates:
* KYC, sanctions, AML rules, limits, exception flags
6. Emit **MintAuth** and obtain **threshold signatures** from allowlisted signers.
7. Relayer submits to chain calling `submitMintAuth(MintAuth, signatures)`.
### 5.2 On-chain steps (SettlementRouter)
1. Verify signatures meet quorum for the corridor/product/participant class.
2. Check time window + chainId + verifyingContract.
3. Enforce replay protection.
4. Enforce router policy caps.
5. Record settlement.
6. Call GRU mint controller to mint to recipients.
7. Emit events for audit.
---
## 6. Contract Specifications
### 6.1 DBIS_RootRegistry
**Purpose:** Single source of truth for DBIS rail component addresses + versioning.
**State**
* `address participantRegistry`
* `address signerRegistry`
* `address settlementRouter`
* `address gruMintController`
* `string railVersion` (e.g., "v1")
**Functions**
* `setComponent(bytes32 key, address addr)` (admin)
* `getComponent(bytes32 key) returns (address)`
**Events**
* `ComponentUpdated(bytes32 indexed key, address indexed addr, string railVersion)`
---
### 6.2 DBIS_ParticipantRegistry
**Purpose:** Institution onboarding + wallet bindings + policy tags.
**Functions**
* `registerParticipant(Participant calldata p)` (admin)
* `setParticipantStatus(bytes32 participantId, Status s)` (admin)
* `addOperationalWallet(bytes32 participantId, address wallet)` (admin)
* `removeOperationalWallet(bytes32 participantId, address wallet)` (admin)
* `isOperationalWallet(address wallet) returns (bool)`
* `getParticipantByWallet(address wallet) returns (bytes32 participantId)`
**Events**
* `ParticipantRegistered(bytes32 indexed participantId, string legalName, string jurisdiction, uint8 entityType)`
* `ParticipantStatusChanged(bytes32 indexed participantId, uint8 status)`
* `OperationalWalletAdded(bytes32 indexed participantId, address wallet)`
* `OperationalWalletRemoved(bytes32 indexed participantId, address wallet)`
---
### 6.3 DBIS_SignerRegistry
**Purpose:** Maintain signer allowlist + roles + quorum policy.
#### Signer model (v1)
* Allowlisted signer addresses with categories:
* OPS
* COMPLIANCE
* CUSTODY
* RISK
* AUDITOR (optional but recommended)
#### Quorum (default v1)
* `requiredSignatures = 3`
* `requiredCategories`: must include at least:
* COMPLIANCE (mandatory)
* and any 2 of OPS/CUSTODY/RISK/AUDITOR
**Functions**
* `addSigner(address signer, uint8 category)` (admin)
* `removeSigner(address signer)` (admin)
* `setQuorum(uint8 requiredSigs, uint256 categoryMaskRequired, uint256 categoryMaskAllowed)` (admin)
* `isSigner(address signer) returns (bool)`
* `validateSigners(address[] signers) returns (bool ok, string reason)` (view)
**Events**
* `SignerAdded(address indexed signer, uint8 category)`
* `SignerRemoved(address indexed signer)`
* `QuorumUpdated(uint8 requiredSigs, uint256 requiredMask, uint256 allowedMask)`
---
### 6.4 DBIS_SettlementRouter
**Purpose:** Verify MintAuth signatures, enforce rail policy, record settlement, and trigger GRU mint.
#### State
* `RootRegistry root`
* `mapping(bytes32 => bool) usedMessageIds`
* policy:
* `uint256 maxAmountPerMessage`
* `mapping(bytes32 corridor => uint256 corridorDailyCap)`
* `mapping(bytes32 corridor => mapping(uint256 day => uint256 usedToday))`
* `bool paused`
#### Core function
`submitMintAuth(MintAuth calldata auth, bytes[] calldata signatures)`
**Validation**
* `paused == false`
* `auth.chainId == 138`
* `auth.verifyingContract == address(this)`
* `block.timestamp in [auth.notBefore, auth.expiresAt]`
* `!usedMessageIds[auth.messageId]`
* `recipients/amounts lengths match`
* total amount <= `maxAmountPerMessage`
* `ParticipantRegistry` check:
* every recipient must be an operational wallet of an ACTIVE participant **OR**
* allow "unhosted wallets" only if corridor policy permits (default: hosted-only)
* Signature validation:
* EIP-712 typed hash of MintAuth
* recover signers from signatures
* require unique signers
* require signer allowlist + quorum per SignerRegistry
**Effects**
* mark `usedMessageIds[messageId] = true`
* update daily corridor usage
* record settlement data in storage (optional; events are mandatory)
* call `DBIS_GRU_MintController.mintFromAuthorization(auth)`
#### Events (audit-grade)
* `SettlementRecorded(bytes32 indexed messageId, bytes32 indexed isoType, bytes32 isoHash, bytes32 accountingRef, uint8 fundsStatus, bytes32 corridor, uint8 assetClass, uint256 totalAmount)`
* `MintExecuted(bytes32 indexed messageId, address indexed recipient, uint256 amount, uint8 assetClass)`
* `MessageIdConsumed(bytes32 indexed messageId)`
* `RouterPaused(bool paused)`
---
### 6.5 DBIS_GRU_MintController
**Purpose:** Only mint GRU when invoked by SettlementRouter with a validated MintAuth.
#### State
* `address settlementRouter`
* `address gruTokenOrDiamond` (depending on your GRU deployment)
* `bool paused`
#### Function
`mintFromAuthorization(MintAuth calldata auth)`
**Rules**
* `msg.sender == settlementRouter`
* `paused == false`
* mint exactly `amounts[i]` to `recipients[i]`
* emit per-recipient mint event (or rely on SettlementRouter's MintExecuted event)
**Integration notes**
* If GRU is minted via Diamond facets:
* MintController should call the GRU mint facet method.
* If GRU is represented as a CompliantFiatToken (ERC-20):
* MintController must be granted MINTER_ROLE, and **all other direct mint paths must be disabled** or moved behind router gating.
---
## 7. Signature Standard (EIP-712)
### Domain
* `name: "DBISSettlementRouter"`
* `version: "1"`
* `chainId: 138`
* `verifyingContract: DBIS_SettlementRouter`
### Typed data
MintAuth struct fields as defined in §4.2.
### Signature set
* `bytes[] signatures` (each 65-byte ECDSA signature)
* `address[] recoveredSigners` computed on-chain
* signers must be unique and satisfy SignerRegistry quorum rules
> v1 uses "multi-sig by aggregation" (array of signatures). True threshold crypto can be introduced in v2 without changing MintAuth.
---
## 8. Policy Controls
### 8.1 Default policy (recommended v1)
* Hosted wallets only (participants) unless corridor allows unhosted.
* Mandatory COMPLIANCE signer present for all authorizations.
* `expiresAt` maximum horizon (e.g., <= 15 minutes) to reduce replay/exfiltration risk.
* Daily corridor caps + per-message cap.
### 8.2 Emergency controls
* Router pause (ROUTER_ADMIN)
* Mint controller pause (ROUTER_ADMIN)
* Signer revocation (SIGNER_ADMIN)
* Participant suspension (PARTICIPANT_ADMIN)
---
## 9. Replay Protection and Idempotency
### Replay
* `messageId` is consumed once. Submitting same messageId reverts.
### Idempotency (optional extension)
If you want "retry safe" behavior:
* allow resubmission if exact same auth hash and messageId already consumed → return success without minting (but emit a "duplicate accepted" event).
Default v1: revert on reuse.
---
## 10. Reporting and Audit
### Required on-chain audit events
* SettlementRecorded (includes isoHash + accountingRef)
* MintExecuted per recipient (or token Transfer + SettlementRecorded)
### Off-chain reporting (DBIS Rail Rulebook v1)
* Maintain mapping from `messageId → ISO evidence bundle` and `accountingRef → ledger postings`.
* Support camt-like extracts for:
* completed settlements
* exceptions / rejected authorizations
* signer approvals and revocations
* participant status changes
---
## 11. Backward Compatibility / Migration Plan
### Immediate hardening steps (recommended)
* Identify and eliminate "owner mint" pathways for GRU/c* tokens on chain 138:
* Either revoke direct mint permissions or route them exclusively through DBIS_GRU_MintController.
* For any existing MintController pattern:
* adapt it so `MINTER_ROLE` = SettlementRouter only.
* require MintAuth signature validation at router level.
### Naming/identity alignment
* Update chain metadata artifacts so canonical identity is DBIS Mainnet (Chain 138).
* Keep a compatibility alias field if needed, but ensure DBIS is primary.
---
## 12. Open Items for v1 Freeze
These are the only "knobs" that change code/constants:
1. **Quorum rule** (3-of-5 default) and required categories.
2. Hosted-only vs allow unhosted corridors.
3. Per-message and daily caps.
4. Whether messageId reuse reverts or is idempotent.
---
## Appendix A — Recommended Quorum Defaults
**Signer categories:** OPS, COMPLIANCE, CUSTODY, RISK, AUDITOR
**Default quorum:** 3-of-5
**Required:** COMPLIANCE + any 2 of {OPS, CUSTODY, RISK, AUDITOR}
Rationale: ensures compliance sign-off and prevents single-domain control.
---
## Appendix B — Minimal Event Field Set
**SettlementRecorded**
* `messageId`
* `isoType`
* `isoHash`
* `accountingRef`
* `fundsStatus`
* `corridor`
* `assetClass`
* `totalAmount`
**MintExecuted**
* `messageId`
* `recipient`
* `amount`
* `assetClass`
---
## Appendix C — v1.5 Add-Ons (AAA+++)
The v1.5 add-ons extend this Spec for examiner-credible completeness. They are implemented via the following documents; only summary points are repeated here.
1. **[DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md](DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md)** — LPA state machine (POSTED_FINAL, POSTED_ADJUSTMENT, POSTED_REVERSAL, DISPUTED_HOLD), Reversal Policy Matrix (before mint: invalidate; after mint: primary offset/corridor restriction, secondary burn, tertiary debt/dispute), and **mandatory signer effective/revoked block enforcement**: SignerRegistry adds `effectiveFromBlock` and `revokedAtBlock` per signer; SettlementRouter validates each recovered signer is active at `block.number`.
2. **[DBIS_RAIL_CONVERSION_ROUTER_SPEC_V1_5.md](DBIS_RAIL_CONVERSION_ROUTER_SPEC_V1_5.md)** — SwapAuthorization (SwapAuth) EIP-712 struct, quorum (2-of-4 small / 3-of-5 + COMPLIANCE large), best execution and MEV posture, quote provenance (quoteHash, quoteIssuer), venue allowlist, sanctions/AML (blocklist, Compliance for elevated swaps and new venues), and ConversionExecuted event.
3. **[DBIS_RAIL_STABLECOIN_POLICY_V1_5.md](DBIS_RAIL_STABLECOIN_POLICY_V1_5.md)** — Canonical stablecoin definition: Stablecoin Reference Registry (tokenSymbol, tokenAddress, issuer/bridge, legalClaimType, redemptionPath, reserveDisclosureRef, riskTier, pauseAuthority, stablecoinStatus); Rulebook addendum that only ACTIVE registered stablecoins may be used for routing; monitoring (peg deviation, bridge health, emergency corridor halt).
4. **[DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md](DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md)** — LEB/LPA/ISO schemas, canonicalization rules (UTF-8 NFC, sorted keys, fixed decimal and timestamp, rounding policy), and test vectors for lebHash, lpaId, isoHash, and accountingRef so that any auditor can reproduce hashes.

149
docs/dbis-rail/IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md Normal file
View File

@@ -0,0 +1,149 @@
# Implementation Coordination with Transcript 540ae663
**Purpose:** Coordinate all implementations with the work completed in agent transcript **540ae663** (PMM/DEX routing, tokens, GRU registration, cW* deployment, Chain 138 deployments, and related scripts/docs). Use this document so that:
- Implementations do not duplicate or conflict with what was already done.
- The same scripts, env vars, addresses, and flows are used where applicable.
- The [DBIS Rail and Project Completion Master](DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md) task list reflects completed vs remaining work.
**Transcript reference:** `agent-transcripts/540ae663-7cb4-44f3-bc48-4a1d3ea44d54` (PMM/DEX, tokens, GRU, cW*, deployments).
---
## 1. What Was Completed in Transcript 540ae663
### 1.1 PMM / DEX (Chain 138)
| Item | Status | Notes |
|------|--------|------|
| DODOPMMIntegration | Deployed | Mock DVM at `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` |
| Three PMM pools | Created | cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC (addresses in LIQUIDITY_POOLS_MASTER_MAP) |
| DODOPMMProvider | Deployed | `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`; pools registered |
| TransactionMirror | Deployed | Multiple deploys in transcript; use address from CONTRACT_ADDRESSES_REFERENCE / .env |
| Add-liquidity runbook | Added | [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK](../03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md) |
| MCP allowlist-138 | Added | `ai-mcp-pmm-controller/config/allowlist-138.json` |
| PMM_DEX_ROUTING_STATUS | Updated | docs/11-references/PMM_DEX_ROUTING_STATUS.md |
### 1.2 Tokens and Categories
| Item | Status | Notes |
|------|--------|------|
| TOKEN_CATEGORIES_CANONICAL | Created | Categories 1–4 (Canonical 138, ALL Mainnet, cW*, D-WIN W); cCADT/cCADC, ACADT naming |
| DeployCompliantFiatTokens (Chain 138) | Run | 10 tokens: cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT |
| CHAIN138_TOKEN_ADDRESSES | Updated | All 15 compliant fiat tokens |
| canonical-tokens.ts (token-aggregation) | Updated | FALLBACK_ADDRESSES for all 10 new compliant tokens |
| ENV_EXAMPLE_CONTENT | Updated | Compliant token block, CREATE2_FACTORY, cW* and 651940 |
| TOKEN_CONTRACT_DEPLOYMENTS_REMAINING | Created | docs/11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md |
| TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER | Created | docs/11-references/TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md |
| TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS | Created | docs/11-references/TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md |
### 1.3 GRU Registration and Registry
| Item | Status | Notes |
|------|--------|------|
| UniversalAssetRegistry upgrade | Done | New implementation with `registerGRUCompliantAsset`; phased + deterministic proxies upgraded |
| REGISTRAR_ROLE | Granted | To deployer on both registry proxies |
| RegisterGRUCompliantTokens | Run | All 12 c* registered as GRU (cUSDT, cUSDC, cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT) |
| set-dotenv-c-tokens-and-register-gru.sh | Created | Sets c* and token vars in .env, then runs RegisterGRUCompliantTokens |
| EXPLORER_TOKENS_GRU_POLICY | Created | docs/04-configuration/EXPLORER_TOKENS_GRU_POLICY.md; c* on explorer must be GRU |
| Token lists (dbis-138, DUAL_CHAIN) | Updated | cEURC added; all listed c* are GRU-registered |
### 1.4 c* → cW* Mapping and cW* Deployment
| Item | Status | Notes |
|------|--------|------|
| cToCwSymbolMapping | Added | config/token-mapping-multichain.json (c* → cW* symbol map) |
| Compliant_*_cW entries | Added | 138→chain pairs; addressTo updated when cW* deployed |
| C_TO_CW_MAPPER_MAPPING.md | Created | docs/04-configuration/C_TO_CW_MAPPER_MAPPING.md |
| CompliantWrappedToken.sol | Created | MINTER_ROLE, BURNER_ROLE; burnFrom added for bridge |
| DeployCWTokens.s.sol | Created | cWUSDT, cWUSDC per chain |
| CW_BRIDGE_* in .env | Set | Default + per-chain (Mainnet, Cronos, BSC, Polygon, Gnosis, Avalanche, Base, Arbitrum, Optimism) from deployed bridge suite |
| CW_BRIDGE_TASK_LIST | Created | docs/00-meta/CW_BRIDGE_TASK_LIST.md |
| CW_BRIDGE_APPROACH.md | Created | docs/07-ccip/CW_BRIDGE_APPROACH.md (Option 2: dedicated cW* receiver) |
| CW_DEPLOY_AND_WIRE_RUNBOOK.md | Created | docs/07-ccip/CW_DEPLOY_AND_WIRE_RUNBOOK.md |
| run-cw-remaining-steps.sh | Created | --deploy, --update-mapping, --verify |
| cWUSDT/cWUSDC deployed | Done | 9 chains (Mainnet, Cronos, BSC, Polygon, Gnosis, Avalanche, Base, Arbitrum, Optimism); .env and token-mapping updated |
| CW_TOKENS_AND_NETWORKS.md | Created/updated | docs/11-references/CW_TOKENS_AND_NETWORKS.md |
### 1.5 Scripts and Pre-Deploy Flow
| Item | Status | Notes |
|------|--------|------|
| Core RPC | Documented | Use IP:port `http://192.168.11.211:8545` for deploy (RPC_ENDPOINTS_MASTER) |
| run-before-deploy-checks.sh | Created | Preflight, env, forge build, test, config validation, optional --on-chain |
| test-all-contracts-before-deploy.sh | Updated | --skip-build, --no-match, --alltra |
| deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh | Updated | --skip-mirror, treat "pool exists" as success |
| run-all-next-steps-chain138.sh | Created | Preflight → mirror+pool → register c* as GRU → verify |
| RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md | Created | docs/03-deployment/RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md |
| deploy-tokens-and-weth-all-chains-skip-canonical.sh | Updated | --deploy-c, --deploy-cw, 651940 validation |
| run-lint-test-build-deploy.sh | Created | smom-dbis-138/scripts/run-lint-test-build-deploy.sh |
### 1.6 Other (Multi-Chain, Lint, Docs)
| Item | Status | Notes |
|------|--------|------|
| DeployCompliantFiatTokensForChain.s.sol | Created | c* on any chain (cUSDT, cUSDC, optional others) |
| RegisterGRUCompliantTokens.s.sol | Exists | Run after c* deploy; needs REGISTRAR_ROLE |
| UpgradeUniversalAssetRegistry.s.sol | Created | script/deploy/UpgradeUniversalAssetRegistry.s.sol |
| Forge lint fixes | Applied | mixedCase, named imports, unused imports, ERC20 transfer checks, NatSpec, shadowing |
| GRU integration (PoolManager, facet) | Done | registerGRUCompliantAsset, GRUAssetRegistryFacet, GRUCompliantTokensRegistryTest |
---
## 2. Mapping to Completion Master Tasks
When implementing from [DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md](DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md), use this mapping. **Done** = completed in transcript 540ae663. **Partial** = partly done; finish per Master. **Open** = not done in transcript.
### C. Project deployment — Required
| Task | Status | Coordination note |
|------|--------|-------------------|
| C1 | Partial | Preflight, env, test-all-contracts, run-before-deploy-checks exist; ensure RPC 2101 writable, POOL_MANAGER_ROLE per runbook. |
| C2 | Done | TransactionMirror deployed; all three PMM pools created; c* registered as GRU; set-dotenv script and RegisterGRUCompliantTokens run. |
| C3 | Done | DODOPMMProvider deployed and pools registered; token-aggregation env; MCP allowlist-138; add-liquidity runbook. |
| C4 | Partial | check-contracts-on-chain-138.sh used; confirm 38/38 (or current count) after any new deploy. |
| C5 | Partial | Blockscout verification run in transcript; update CONTRACT_ADDRESSES_REFERENCE and LIQUIDITY_POOLS_MASTER_MAP as needed. |
| C6 | Open | Reconcile Multicall vs Oracle Aggregator at documented address. |
### D. Project deployment — Optional
| Task | Status | Coordination note |
|------|--------|-------------------|
| D1 | Open | EnhancedSwapRouter not deployed; deploy when Uniswap/Balancer on 138. |
| D2 | Open | Trustless stack (InboxETH, BondManager, etc.) not deployed. |
| D3 | Open | CCIP other chains per DEPLOYMENT_ORDER. |
| D4 | Open | LINK relay support per runbook. |
| D5 | Partial | cWUSDT/cWUSDC deployed on 9 chains; runbook and mapping in place; other cW* (cWEURC, etc.) and edge pools per pool-matrix still optional. |
| D6–D7 | Open | R1–R24 and full recommendations list. |
### Token deployment (TODOS_CONSOLIDATED T1–T7)
| Task | Status | Coordination note |
|------|--------|-------------------|
| T1 DeployCompliantFiatTokens | Done | 10 tokens deployed on 138; optional cCADT in script (commented). |
| T2 Optional cCADT | Partial | Uncomment in script and re-run when needed. |
| T3–T7 | Open / Partial | cAUSDT, ACADT, cW* (cWUSDT/cWUSDC done; others mapping only), D-WIN W on 138/651940, vault ac*/vdc*/sdc* per TOKEN_CONTRACT_DEPLOYMENTS_REMAINING. |
### DBIS Rail (A, B)
All DBIS Rail tasks (A1–A9, B1–B7) remain **open** in the transcript: no DBIS Rail contracts (RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController) were implemented; owner mint on c* not locked to router. Implement per Completion Master and [Audit Readiness Results](DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md).
---
## 3. How to Use This for New Work
1. **Before changing deployment or token flow:** Check §1 for what’s already done; use the same scripts and env (Core RPC IP:port, run-all-next-steps-chain138.sh, set-dotenv-c-tokens-and-register-gru.sh, run-cw-remaining-steps.sh).
2. **Before adding a new “completion” task:** Check §2; if marked Done or Partial, update the Completion Master or this doc when you finish the remainder.
3. **When implementing DBIS Rail (A/B):** Follow the Completion Master and Spec/Rulebook/Threat Model; ensure new rail contracts and mint path do not conflict with existing GRU registration or c* usage (e.g. UniversalAssetRegistry, RegisterGRUCompliantTokens, explorer GRU policy).
4. **Addresses and .env:** Use CONTRACT_ADDRESSES_REFERENCE, CHAIN138_TOKEN_ADDRESSES, and smom-dbis-138/.env as populated by the transcript’s scripts; do not overwrite with placeholders.
---
## 4. Document Control
| Field | Value |
|-------|-------|
| Title | Implementation Coordination with Transcript 540ae663 |
| Version | 1 |
| Status | Active |
| Related | [DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md](DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md), [DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md](DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md), [DEPLOYMENT_ORDER_OF_OPERATIONS](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) |

18
docs/dbis-rail/README.md Normal file
View File

@@ -0,0 +1,18 @@
# DBIS Rail
This folder holds the **DBIS Rail** technical specification and operational rulebook for Chain 138 (DBIS Mainnet): bank-rail settlement and GRU mint orchestration using ISO-20022–anchored authorizations.
- **Technical Spec:** [DBIS_RAIL_TECHNICAL_SPEC_V1.md](DBIS_RAIL_TECHNICAL_SPEC_V1.md) — contract set, MintAuth, signer quorum, replay protection, audit events.
- **Rulebook:** [DBIS_RAIL_RULEBOOK_V1.md](DBIS_RAIL_RULEBOOK_V1.md) — good funds matrix, finality rules, accounting sequence, reversal handling, signer governance, incident controls, audit standards.
- **Security Threat Model:** [DBIS_RAIL_SECURITY_THREAT_MODEL_V1.md](DBIS_RAIL_SECURITY_THREAT_MODEL_V1.md) — trust boundaries, authorization/ledger/router/mint/validator/off-chain threats, severity classification, residual risk, review cycle.
- **Regulator-Facing Brief:** [DBIS_RAIL_REGULATOR_BRIEF_V1.md](DBIS_RAIL_REGULATOR_BRIEF_V1.md) — institutional narrative for counterparties, examiners, counsel, and risk committees: overview, governance, lifecycle, good funds, controls, risk posture, audit, residual risk, amendment.
- **Audit Readiness Checklist:** [DBIS_RAIL_AUDIT_READINESS_CHECKLIST_V1.md](DBIS_RAIL_AUDIT_READINESS_CHECKLIST_V1.md) — pre-audit control verification: mint path, authorization, signer governance, accounting/evidence, router controls, validator layer, emergency controls, documentation integrity.
- **Audit Readiness Results:** [DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md](DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md) — baseline checklist run: status per section, gaps (e.g. owner mint, rail contracts not deployed), and prioritized remediation.
- **Control Mapping:** [DBIS_RAIL_CONTROL_MAPPING_V1.md](DBIS_RAIL_CONTROL_MAPPING_V1.md) — control IDs mapped to checklist sections, Spec, Rulebook, and Threat Model for audit and SOC 2 / ISO 27001 alignment.
- **Completion Master:** [DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md](DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md) — current project and deployment status; full task list (required and optional) for DBIS Rail audit readiness and project completion.
- **Implementation coordination:** [IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md](IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md) — coordinate all implementations with transcript 540ae663 (PMM/DEX, tokens, GRU, cW*, deployments); maps Completion Master tasks to done/partial/open.
- **v1.5 Ledger Attestation Add-On:** [DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md](DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md) — LPA state machine, reversal policy matrix, mandatory signer effectiveFromBlock/revokedAtBlock enforcement.
- **v1.5 Conversion Router Spec:** [DBIS_RAIL_CONVERSION_ROUTER_SPEC_V1_5.md](DBIS_RAIL_CONVERSION_ROUTER_SPEC_V1_5.md) — SwapAuth (EIP-712), best execution/MEV posture, quote provenance, venue allowlist, sanctions/AML for swaps.
- **v1.5 Stablecoin Policy:** [DBIS_RAIL_STABLECOIN_POLICY_V1_5.md](DBIS_RAIL_STABLECOIN_POLICY_V1_5.md) — Canonical USDC/USDT definition, Stablecoin Reference Registry, canonical stablecoin routing, monitoring.
- **v1.5 Hash Canonicalization and Test Vectors:** [DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md](DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md) — LEB/LPA/ISO schemas, canonicalization rules, test vectors for auditor reproducibility.
- **Add-Ons code completion:** [DBIS_RAIL_ADDONS_CODE_COMPLETION_TASK_LIST.md](DBIS_RAIL_ADDONS_CODE_COMPLETION_TASK_LIST.md) — full task list to implement Spec v1 + v1.5 and achieve an operational system.