proxmox/docs/dbis-rail/DBIS_RAIL_CONVERSION_ROUTER_SPEC_V1_5.md

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 Rulebook v1, DBIS Rail Stablecoin Policy v1.5

---

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.

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).
• 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).
• 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