CurrenciCombo/docs/Engineering_Ticket_Breakdown.md

# Engineering Ticket Breakdown

## Overview
This document converts all specifications into PR-ready engineering tickets with acceptance criteria, organized by component (Frontend, Backend, Smart Contracts, Integration, Testing).

---

## Frontend Tickets

### FE-001: Builder UI - Drag & Drop Canvas
**Priority**: P0  
**Estimate**: 8 story points  
**Component**: `webapp/src/components/builder/Canvas.tsx`

**Description**:
Implement drag-and-drop canvas for building financial workflows. Users can drag adapters from palette to canvas, reorder steps, and configure step parameters.

**Acceptance Criteria**:
- ✅ Users can drag adapters from palette to canvas
- ✅ Steps can be reordered by dragging
- ✅ Step cards display step number, icon, type, and summary
- ✅ Drop zone highlights when dragging over it
- ✅ Visual feedback during drag operations
- ✅ Steps can be edited and removed
- ✅ Canvas is responsive (mobile/tablet/desktop)

**Technical Requirements**:
- Use `@dnd-kit/core` and `@dnd-kit/sortable`
- Support both DeFi and Fiat/DTL adapters
- Real-time step dependency visualization

**Dependencies**: None  
**Related**: FE-002, FE-003

---

### FE-002: Builder UI - Adapter Palette
**Priority**: P0  
**Estimate**: 5 story points  
**Component**: `webapp/src/components/builder/StepPalette.tsx`

**Description**:
Implement adapter palette sidebar with filtering capabilities. Show DeFi protocols and Fiat/DTL rails separately, with whitelist filtering option.

**Acceptance Criteria**:
- ✅ Adapters grouped by type (DeFi, Fiat/DTL)
- ✅ Filter options: All, DeFi, Fiat/DTL, Whitelisted Only
- ✅ Search functionality for adapters
- ✅ Adapters show name, icon, and status (Approved, Deprecated, Restricted)
- ✅ Draggable adapters with visual feedback
- ✅ Compliance badge section visible

**Technical Requirements**:
- Fetch adapters from `/api/adapters` endpoint
- Filter based on user selection and whitelist status
- Support drag-and-drop to canvas

**Dependencies**: BE-005 (Adapter Registry API)  
**Related**: FE-001

---

### FE-003: Builder UI - Step Configuration Drawer
**Priority**: P0  
**Estimate**: 6 story points  
**Component**: `webapp/src/components/builder/StepConfigDrawer.tsx`

**Description**:
Implement step configuration drawer that opens when user clicks "Edit" on a step. Show step-specific fields and compliance requirements.

**Acceptance Criteria**:
- ✅ Drawer slides up from bottom (mobile) or from side (desktop)
- ✅ Step-specific fields (token, amount, beneficiary, etc.)
- ✅ Compliance fields auto-populated from user session
- ✅ Real-time validation (balance checks, IBAN format, etc.)
- ✅ Dependency visualization (shows which previous steps feed this step)
- ✅ Save/Cancel buttons

**Technical Requirements**:
- Support all step types: borrow, swap, repay, pay
- Validate inputs before saving
- Show error messages for invalid inputs

**Dependencies**: FE-001, BE-004 (Compliance API)  
**Related**: FE-001

---

### FE-004: Builder UI - Compliance Status Dashboard
**Priority**: P0  
**Estimate**: 4 story points  
**Component**: `webapp/src/components/compliance/ComplianceDashboard.tsx`

**Description**:
Implement compliance status dashboard overlay showing LEI, DID, KYC, AML status. Always visible badge in header, expandable to full details.

**Acceptance Criteria**:
- ✅ Compliance badge in header (✓ LEI, ✓ KYC, ✓ AML, ✓ DID)
- ✅ Expandable overlay with full compliance details
- ✅ Workflow-specific compliance validation
- ✅ Expiration warnings (if KYC/AML expiring soon)
- ✅ Quick links to update identity or run new checks
- ✅ Real-time status updates

**Technical Requirements**:
- Fetch compliance status from `/api/compliance/status`
- Validate compliance for current workflow
- Show warnings for missing requirements

**Dependencies**: BE-004 (Compliance API)  
**Related**: FE-001

---

### FE-005: Builder UI - Optional Simulation Panel
**Priority**: P1  
**Estimate**: 6 story points  
**Component**: `webapp/src/components/simulation/SimulationPanel.tsx`

**Description**:
Implement optional simulation panel for advanced users. Toggleable simulation feature that shows gas estimates, slippage analysis, liquidity checks, and failure predictions.

**Acceptance Criteria**:
- ✅ Simulation toggle in summary panel (optional for advanced users)
- ✅ "Simulate" button appears when toggle enabled
- ✅ Simulation results panel shows:
  - Step-by-step results (success/failure)
  - Gas estimate and cost
  - Slippage analysis
  - Liquidity checks
  - Compliance status
  - Warnings and errors
- ✅ "Run Simulation Again" and "Proceed to Sign" buttons
- ✅ Results panel closes/closes on click outside

**Technical Requirements**:
- Call `/api/plans/{planId}/simulate` endpoint
- Parse and display simulation results
- Show warnings/errors clearly

**Dependencies**: BE-003 (Simulation Engine)  
**Related**: FE-001

---

### FE-006: Preview Page - Plan Summary & Signing
**Priority**: P0  
**Estimate**: 5 story points  
**Component**: `webapp/src/app/builder/preview/page.tsx`

**Description**:
Enhance preview page to show plan summary, compliance status, and signature panel. Allow users to sign plan with wallet before execution.

**Acceptance Criteria**:
- ✅ Display complete plan summary (steps, amounts, fees)
- ✅ Show compliance status for all steps
- ✅ Signature panel with hash computation and wallet signing
- ✅ "Create Plan" button (calls API)
- ✅ "Execute" button (after plan created and signed)
- ✅ Error banners for API failures

**Technical Requirements**:
- Use `useBuilderStore` for plan data
- Integrate `SignaturePanel` component
- Use `useMutation` for API calls

**Dependencies**: FE-001, BE-001 (Plan API)  
**Related**: FE-007

---

### FE-007: Execution Timeline - Real-Time Updates
**Priority**: P0  
**Estimate**: 6 story points  
**Component**: `webapp/src/components/plan/ExecutionTimeline.tsx`

**Description**:
Enhance execution timeline to show real-time status updates via SSE or polling. Display phases (Prepare, Execute DLT, Bank Instruction, Commit) with status indicators.

**Acceptance Criteria**:
- ✅ Real-time status updates via SSE (when enabled) or polling
- ✅ Phase progression visualization (Prepare → Execute DLT → Bank Instruction → Commit)
- ✅ Status indicators (pending, in_progress, complete, failed)
- ✅ Terminal states handled correctly (complete, failed, aborted)
- ✅ DLT transaction hash and ISO message ID displayed
- ✅ Error messages shown for failed phases

**Technical Requirements**:
- Use `createPlanStatusStream` for SSE
- Fallback to polling if SSE disabled
- Handle terminal states correctly (fix Bug 1)

**Dependencies**: BE-002 (Execution Status API), BE-006 (SSE)  
**Related**: FE-006

---

## Backend Tickets

### BE-001: Orchestrator API - Plan Management
**Priority**: P0  
**Estimate**: 8 story points  
**Component**: `orchestrator/src/api/plans.ts`

**Description**:
Implement plan management endpoints: create plan, get plan, add signature, validate plan.

**Acceptance Criteria**:
- ✅ `POST /api/plans` - Create execution plan
- ✅ `GET /api/plans/{planId}` - Get plan details
- ✅ `POST /api/plans/{planId}/signature` - Add user signature
- ✅ Plan validation (recursion depth, LTV, step dependencies)
- ✅ Error responses with clear messages
- ✅ OpenAPI spec documented

**Technical Requirements**:
- Validate plan structure
- Check step dependencies
- Store plan in database
- Return plan with computed hash

**Dependencies**: DB-001 (Plan Schema)  
**Related**: FE-006

---

### BE-002: Orchestrator API - Execution Coordination
**Priority**: P0  
**Estimate**: 10 story points  
**Component**: `orchestrator/src/services/execution.ts`

**Description**:
Implement execution coordination service that manages 2PC (two-phase commit) across DLT and banking rails.

**Acceptance Criteria**:
- ✅ `POST /api/plans/{planId}/execute` - Initiate execution
- ✅ `GET /api/plans/{planId}/status` - Get execution status
- ✅ `POST /api/plans/{planId}/abort` - Abort execution
- ✅ 2PC pattern implementation (prepare, commit, abort)
- ✅ Real-time status updates via SSE
- ✅ Error handling and rollback on failures

**Technical Requirements**:
- Coordinate DLT and bank steps
- Implement prepare/commit/abort phases
- Handle failure modes (DLT fail, bank fail, liquidity denial)
- Emit status events for SSE

**Dependencies**: BE-001, BE-007 (DLT Handler), BE-008 (Bank Connector)  
**Related**: FE-007

---

### BE-003: Simulation Engine API
**Priority**: P1  
**Estimate**: 8 story points  
**Component**: `orchestrator/src/services/simulation.ts`

**Description**:
Implement optional simulation engine that provides dry-run execution, gas estimation, slippage calculation, and liquidity checks.

**Acceptance Criteria**:
- ✅ `POST /api/plans/{planId}/simulate` - Run simulation
- ✅ Gas estimation for all steps
- ✅ Slippage calculation for swaps
- ✅ Liquidity checks for trades
- ✅ Failure prediction
- ✅ Step-by-step results
- ✅ Response time < 5 seconds

**Technical Requirements**:
- Integrate with price oracles
- Calculate gas estimates
- Check liquidity pools
- Predict failures

**Dependencies**: BE-001, External (Price Oracles)  
**Related**: FE-005

---

### BE-004: Compliance Engine API
**Priority**: P0  
**Estimate**: 6 story points  
**Component**: `orchestrator/src/services/compliance.ts`

**Description**:
Implement compliance engine that validates LEI, DID, KYC, AML requirements and injects compliance data into ISO messages.

**Acceptance Criteria**:
- ✅ `GET /api/compliance/status` - Get user compliance status
- ✅ `POST /api/compliance/check` - Validate workflow compliance
- ✅ LEI/DID/KYC/AML validation
- ✅ Compliance data injection into ISO messages
- ✅ Real-time status checks
- ✅ Expiration warnings

**Technical Requirements**:
- Integrate with KYC/AML providers (Onfido, Chainalysis)
- Validate LEI format
- Generate compliance assertions
- Inject into ISO message supplementary data

**Dependencies**: External (KYC/AML Providers)  
**Related**: FE-004, BE-009 (ISO Message Generation)

---

### BE-005: Adapter Registry API
**Priority**: P0  
**Estimate**: 5 story points  
**Component**: `orchestrator/src/api/adapters.ts`

**Description**:
Implement adapter registry API that lists available adapters (DeFi + Fiat/DTL) with filtering and whitelist support.

**Acceptance Criteria**:
- ✅ `GET /api/adapters` - List adapters with filtering
- ✅ `GET /api/adapters/{adapterId}` - Get adapter details
- ✅ Filter by type (DeFi, Fiat/DTL, All)
- ✅ Filter by whitelist status
- ✅ Search functionality
- ✅ Adapter metadata (name, version, status, chainIds)

**Technical Requirements**:
- Fetch from adapter registry contract (on-chain)
- Cache adapter list
- Support filtering and search

**Dependencies**: SC-003 (Adapter Registry Contract)  
**Related**: FE-002

---

### BE-006: Server-Sent Events (SSE) for Real-Time Updates
**Priority**: P1  
**Estimate**: 4 story points  
**Component**: `orchestrator/src/api/sse.ts`

**Description**:
Implement SSE endpoint for real-time execution status updates. Feature flag controlled.

**Acceptance Criteria**:
- ✅ `GET /api/plans/{planId}/status/stream` - SSE endpoint
- ✅ Real-time status events
- ✅ Phase progression updates
- ✅ Error events
- ✅ Graceful connection handling
- ✅ Feature flag controlled

**Technical Requirements**:
- Use EventSource-compatible endpoint
- Emit events on status changes
- Handle disconnections gracefully

**Dependencies**: BE-002  
**Related**: FE-007

---

### BE-007: DLT Handler Service
**Priority**: P0  
**Estimate**: 10 story points  
**Component**: `orchestrator/src/services/dlt.ts`

**Description**:
Implement DLT handler service that interacts with handler smart contract for atomic execution of DLT steps.

**Acceptance Criteria**:
- ✅ Execute DLT steps via handler contract
- ✅ Support 2PC prepare/commit/abort
- ✅ Gas estimation
- ✅ Transaction monitoring
- ✅ Rollback on failure
- ✅ Error handling

**Technical Requirements**:
- Integrate with handler contract (SC-001)
- Use Web3/Ethers.js
- Monitor transaction status
- Handle reentrancy protection

**Dependencies**: SC-001 (Handler Contract)  
**Related**: BE-002

---

### BE-008: Bank Connector Service
**Priority**: P0  
**Estimate**: 10 story points  
**Component**: `orchestrator/src/services/bank.ts`

**Description**:
Implement bank connector service that generates ISO-20022 messages and sends them to banking rails (SWIFT, SEPA, FedNow, etc.).

**Acceptance Criteria**:
- ✅ Generate ISO-20022 pacs.008 messages
- ✅ Inject compliance data (LEI, DID, KYC, AML)
- ✅ Inject plan metadata and digital signature
- ✅ Support 2PC prepare phase (provisional messages)
- ✅ Send to banking rails
- ✅ Monitor settlement status
- ✅ Generate camt.056 for cancellation

**Technical Requirements**:
- ISO-20022 message generation
- Bank API integration
- Compliance data injection
- Error handling

**Dependencies**: BE-004, BE-009 (ISO Message Generation)  
**Related**: BE-002

---

### BE-009: ISO-20022 Message Generation
**Priority**: P0  
**Estimate**: 6 story points  
**Component**: `orchestrator/src/services/iso20022.ts`

**Description**:
Implement ISO-20022 message generation service that creates pacs.008, camt.052/053, camt.056 messages with plan metadata and compliance data.

**Acceptance Criteria**:
- ✅ Generate pacs.008 (payment instruction)
- ✅ Generate camt.052/053 (bank statements)
- ✅ Generate camt.056 (cancellation request)
- ✅ Inject plan ID, digital signature, compliance data
- ✅ Inject DLT transaction reference
- ✅ Inject notary proof
- ✅ Validate XML structure

**Technical Requirements**:
- Use ISO-20022 XML schemas
- Template-based generation
- Compliance data injection
- XML validation

**Dependencies**: BE-004, BE-010 (Notary Service)  
**Related**: BE-008

---

### BE-010: Notary Service Integration
**Priority**: P0  
**Estimate**: 5 story points  
**Component**: `orchestrator/src/services/notary.ts`

**Description**:
Implement notary service integration that registers plans, finalizes executions, and provides audit proofs.

**Acceptance Criteria**:
- ✅ `POST /api/notary/register` - Register plan
- ✅ `GET /api/notary/proof/{planId}` - Get notary proof
- ✅ Register plan with notary contract
- ✅ Finalize plan (success or failure)
- ✅ Retrieve notary proof for audit

**Technical Requirements**:
- Integrate with notary registry contract (SC-002)
- Register plan hashes
- Finalize executions
- Provide audit trail

**Dependencies**: SC-002 (Notary Registry Contract)  
**Related**: BE-001, BE-002

---

### BE-011: Receipt Generation Service
**Priority**: P0  
**Estimate**: 4 story points  
**Component**: `orchestrator/src/services/receipts.ts`

**Description**:
Implement receipt generation service that aggregates DLT transactions, ISO messages, and notary proofs for audit trail.

**Acceptance Criteria**:
- ✅ `GET /api/receipts/{planId}` - Get execution receipts
- ✅ Aggregate DLT transaction receipts
- ✅ Aggregate ISO message receipts
- ✅ Aggregate notary proofs
- ✅ Generate audit trail report

**Technical Requirements**:
- Query DLT transactions
- Query ISO messages
- Query notary proofs
- Aggregate into receipt structure

**Dependencies**: BE-002, BE-009, BE-010  
**Related**: FE-008

---

## Smart Contract Tickets

### SC-001: Handler/Aggregator Contract
**Priority**: P0  
**Estimate**: 13 story points  
**Component**: `contracts/ComboHandler.sol`

**Description**:
Implement handler/aggregator contract that executes multi-step combos atomically, supports 2PC, and integrates with adapter registry.

**Acceptance Criteria**:
- ✅ Execute multi-step combos atomically
- ✅ Support 2PC (prepare, commit, abort)
- ✅ Validate adapter whitelist
- ✅ Reentrancy protection
- ✅ Gas optimization
- ✅ Event emission for off-chain tracking
- ✅ Security audit passed

**Technical Requirements**:
- Use OpenZeppelin contracts (Ownable, ReentrancyGuard)
- Integrate with adapter registry
- Support step execution with error handling
- Emit events for all state changes

**Dependencies**: SC-003 (Adapter Registry)  
**Related**: BE-007

---

### SC-002: Notary Registry Contract
**Priority**: P0  
**Estimate**: 8 story points  
**Component**: `contracts/NotaryRegistry.sol`

**Description**:
Implement notary registry contract that stores plan hashes, codehashes, and provides immutable audit trail.

**Acceptance Criteria**:
- ✅ Register execution plans
- ✅ Finalize plan executions (success/failure)
- ✅ Register adapter codehashes
- ✅ Verify codehash matches
- ✅ Query plans by creator
- ✅ Immutable audit trail

**Technical Requirements**:
- Store plan proofs
- Store codehashes
- Provide query functions
- Emit events for all registrations

**Dependencies**: None  
**Related**: BE-010

---

### SC-003: Adapter Registry Contract
**Priority**: P0  
**Estimate**: 6 story points  
**Component**: `contracts/AdapterRegistry.sol`

**Description**:
Implement adapter registry contract that manages whitelist/blacklist of adapters, tracks versions, and enforces upgrade controls.

**Acceptance Criteria**:
- ✅ Register adapters (DeFi + Fiat/DTL)
- ✅ Whitelist/blacklist adapters
- ✅ Check whitelist status
- ✅ List adapters by type
- ✅ Multi-sig for admin functions
- ✅ Timelock for critical operations

**Technical Requirements**:
- Use OpenZeppelin AccessControl
- Support adapter metadata
- Provide query functions
- Emit events for all changes

**Dependencies**: None  
**Related**: BE-005, SC-001

---

### SC-004: Adapter Interface & Example Adapters
**Priority**: P0  
**Estimate**: 10 story points  
**Component**: `contracts/adapters/`

**Description**:
Implement IAdapter interface and example adapters (Uniswap V3, Aave, ISO-20022 Pay) to demonstrate integration pattern.

**Acceptance Criteria**:
- ✅ IAdapter interface defined
- ✅ Uniswap V3 adapter implemented
- ✅ Aave adapter implemented
- ✅ ISO-20022 Pay adapter implemented
- ✅ All adapters pass tests
- ✅ Documentation for adding new adapters

**Technical Requirements**:
- Follow IAdapter interface
- Support executeStep function
- Support prepareStep (if applicable)
- Emit events for off-chain tracking

**Dependencies**: SC-003  
**Related**: INT-001

---

## Integration Tickets

### INT-001: Bank Connector Integration
**Priority**: P0  
**Estimate**: 8 story points  
**Component**: `orchestrator/src/integrations/bank/`

**Description**:
Implement bank connector adapters for different banking rails (SWIFT, SEPA, FedNow, ISO-20022).

**Acceptance Criteria**:
- ✅ SWIFT MT connector
- ✅ SEPA connector
- ✅ FedNow connector
- ✅ ISO-20022 generic connector
- ✅ Support 2PC prepare phase
- ✅ Error handling and retry logic

**Technical Requirements**:
- Bank API integration
- ISO-20022 message generation
- Error handling
- Retry logic

**Dependencies**: BE-009  
**Related**: BE-008

---

### INT-002: Compliance Provider Integration
**Priority**: P0  
**Estimate**: 6 story points  
**Component**: `orchestrator/src/integrations/compliance/`

**Description**:
Integrate with KYC/AML providers (Onfido, Chainalysis) and Entra Verified ID for compliance verification.

**Acceptance Criteria**:
- ✅ Onfido KYC integration
- ✅ Chainalysis AML integration
- ✅ Entra Verified ID integration
- ✅ LEI validation
- ✅ DID verification
- ✅ Error handling

**Technical Requirements**:
- Provider API integration
- Credential verification
- Status caching
- Error handling

**Dependencies**: External (KYC/AML Providers)  
**Related**: BE-004

---

## Testing Tickets

### TEST-001: E2E Tests - Builder Flow
**Priority**: P0  
**Estimate**: 8 story points  
**Component**: `tests/e2e/builder.spec.ts`

**Description**:
Implement end-to-end tests for builder flow: drag-drop, configure steps, create plan, sign, execute.

**Acceptance Criteria**:
- ✅ Test drag-and-drop from palette to canvas
- ✅ Test step reordering
- ✅ Test step configuration
- ✅ Test plan creation
- ✅ Test plan signing
- ✅ Test plan execution
- ✅ Test error scenarios

**Technical Requirements**:
- Use Playwright
- Test all user flows
- Test error cases
- CI/CD integration

**Dependencies**: FE-001, FE-002, FE-003, BE-001, BE-002  
**Related**: All Frontend/Backend tickets

---

### TEST-002: E2E Tests - Failure Scenarios
**Priority**: P0  
**Estimate**: 6 story points  
**Component**: `tests/e2e/failures.spec.ts`

**Description**:
Implement end-to-end tests for failure scenarios: DLT failure, bank failure, liquidity denial, rollback.

**Acceptance Criteria**:
- ✅ Test DLT failure after bank prepare
- ✅ Test bank failure after DLT commit
- ✅ Test liquidity denial
- ✅ Test rollback mechanisms
- ✅ Test audit trail generation

**Technical Requirements**:
- Mock failure scenarios
- Test recovery mechanisms
- Verify audit logs

**Dependencies**: BE-002, BE-011  
**Related**: BE-002

---

### TEST-003: Smart Contract Tests
**Priority**: P0  
**Estimate**: 10 story points  
**Component**: `contracts/test/`

**Description**:
Implement comprehensive smart contract tests for handler, notary, and adapter registry contracts.

**Acceptance Criteria**:
- ✅ Unit tests for all contracts
- ✅ Integration tests
- ✅ Fuzz tests for edge cases
- ✅ Gas optimization tests
- ✅ Security tests (reentrancy, access control)

**Technical Requirements**:
- Use Hardhat/Foundry
- High test coverage (>90%)
- Security audit ready

**Dependencies**: SC-001, SC-002, SC-003  
**Related**: All Smart Contract tickets

---

## Summary

### Total Tickets: 28
- **Frontend**: 7 tickets
- **Backend**: 11 tickets
- **Smart Contracts**: 4 tickets
- **Integration**: 2 tickets
- **Testing**: 3 tickets
- **Documentation**: 1 ticket (already completed)

### Priority Breakdown
- **P0 (Critical)**: 24 tickets
- **P1 (High)**: 2 tickets (Simulation, SSE - optional features)

### Estimated Story Points
- **Total**: ~180 story points
- **Frontend**: ~40 story points
- **Backend**: ~80 story points
- **Smart Contracts**: ~37 story points
- **Integration**: ~14 story points
- **Testing**: ~24 story points

---

**Document Version**: 1.0  
**Last Updated**: 2025-01-15  
**Author**: Engineering Team