smom-dbis-138/docs/archive/status-reports/operations-legacy/FINANCIAL_TOKENIZATION.md

# Financial File Tokenization

## Overview

The financial tokenization service tokenizes ISO-20022, SWIFT FIN, and other financial files using Hyperledger Firefly. Files are parsed, uploaded to IPFS, and tokenized as NFTs or fungible tokens.

## Supported Formats

### ISO-20022

- **pacs.008**: Payment Instruction
- **pacs.009**: Financial Institution Credit Transfer
- **camt.052**: Bank-to-Customer Account Report
- **camt.053**: Bank-to-Customer Statement
- **camt.054**: Bank-to-Customer Debit Credit Notification
- **paint.001**: Payment Initiation

### SWIFT FIN

- **MT103**: Single Customer Credit Transfer
- **MT202**: General Financial Institution Transfer
- **MT940**: Customer Statement Message
- **MT942**: Interim Transaction Report
- **MT950**: Statement Message

## Architecture

### Components

1. **Financial Tokenization Service**: Main service for tokenization
2. **ISO-20022 Parser**: Parses ISO-20022 messages
3. **SWIFT FIN Parser**: Parses SWIFT FIN messages
4. **Firefly Client**: Integrates with Firefly for tokenization
5. **IPFS**: Stores tokenized files

### Tokenization Flow

1. **Parse File**: Parse ISO-20022 or SWIFT FIN file
2. **Upload to IPFS**: Upload file to IPFS via Firefly
3. **Create NFT**: Create NFT for the file
4. **Store Metadata**: Store parsed metadata on-chain

## Deployment

### Prerequisites

- Firefly deployed
- IPFS deployed
- Besu network deployed

### Deploy Service

```bash
# Deploy tokenization service
./scripts/deployment/deploy-tokenization-service.sh

# Or manually
kubectl apply -f services/financial-tokenization/k8s/deployment.yaml
```

## Usage

### Tokenize ISO-20022 File

```bash
curl -X POST http://financial-tokenization-service:8080/api/v1/tokenize/iso20022 \
  -H "Content-Type: application/json" \
  -d '{
    "xml_content": "<?xml version=\"1.0\"?>...",
    "file_name": "pacs008_001.xml"
  }'
```

### Tokenize SWIFT FIN File

```bash
curl -X POST http://financial-tokenization-service:8080/api/v1/tokenize/swift-fin \
  -H "Content-Type: application/json" \
  -d '{
    "swift_message": "{1:F01...}",
    "file_name": "mt103_001.txt"
  }'
```

## API Endpoints

### POST /api/v1/tokenize/iso20022

Tokenize ISO-20022 message.

**Request**:
```json
{
  "xml_content": "<?xml version=\"1.0\"?>...",
  "file_name": "pacs008_001.xml"
}
```

**Response**:
```json
{
  "status": "success",
  "messageId": "MSG001",
  "nft": {
    "id": "nft-id",
    "tokenId": "1",
    "uri": "ipfs://..."
  },
  "ipfsId": "ipfs-id",
  "parsed": {
    "type": "pacs.008",
    "amount": "1000",
    "currency": "USD",
    ...
  }
}
```

### POST /api/v1/tokenize/swift-fin

Tokenize SWIFT FIN message.

**Request**:
```json
{
  "swift_message": "{1:F01...}",
  "file_name": "mt103_001.txt"
}
```

**Response**:
```json
{
  "status": "success",
  "messageType": "MT103",
  "nft": {
    "id": "nft-id",
    "tokenId": "1",
    "uri": "ipfs://..."
  },
  "ipfsId": "ipfs-id",
  "parsed": {
    "type": "SWIFT_FIN",
    "amount": "1000",
    "currency": "USD",
    ...
  }
}
```

### GET /api/v1/health

Health check endpoint.

**Response**:
```json
{
  "status": "healthy"
}
```

## Parsers

### ISO-20022 Parser

The ISO-20022 parser (`parsers/iso20022_parser.py`) supports:

- **pacs.008**: Payment instructions
- **pacs.009**: Financial institution transfers
- **camt.052/053/054**: Account reports and statements
- **paint.001**: Payment initiation

### SWIFT FIN Parser

The SWIFT FIN parser (`parsers/swift_fin_parser.py`) supports:

- **MT103**: Customer credit transfers
- **MT202**: Institution transfers
- **MT940/942/950**: Statement messages

## Integration

### Firefly Integration

The service integrates with Firefly for:

- **Token Pool Creation**: Create token pools for financial files
- **NFT Minting**: Mint NFTs for tokenized files
- **IPFS Upload**: Upload files to IPFS
- **Metadata Storage**: Store parsed metadata

### Besu Integration

The service connects to Besu via:

- **RPC Endpoint**: Besu RPC nodes
- **Chain ID**: 138
- **Firefly**: Firefly handles blockchain interaction

## Examples

### Tokenize Payment Instruction

```python
from services.financial_tokenization.financial_tokenization_service import FinancialTokenizationService

service = FinancialTokenizationService(firefly_client)

# Tokenize ISO-20022 pacs.008
result = service.tokenize_iso20022(xml_content, "pacs008_001.xml")
print(f"NFT ID: {result['nft']['id']}")
print(f"IPFS ID: {result['ipfsId']}")
```

### Tokenize SWIFT FIN Message

```python
# Tokenize SWIFT FIN MT103
result = service.tokenize_swift_fin(swift_message, "mt103_001.txt")
print(f"NFT ID: {result['nft']['id']}")
print(f"Message Type: {result['messageType']}")
```

## References

- [ISO-20022 Specification](https://www.iso20022.org/)
- [SWIFT FIN Messages](https://www.swift.com/standards/data-standards/mt-message-types)
- [Firefly Documentation](https://hyperledger.github.io/firefly/)
- [IPFS Documentation](https://docs.ipfs.io/)