smom-dbis-138/docs/tokenization/API_DOCUMENTATION.md

# Tokenization API Documentation

## Overview

The Tokenization API provides endpoints for minting, transferring, and redeeming tokenized assets, with integration across SolaceNet, Sub-Volumes, and microservices.

## Base URL

```
https://api.tokenization.chain138.example.com
```

## Authentication

All endpoints require SolaceNet capability checks and may require Indy credentials.

```
Authorization: Bearer <api_key>
X-Tenant-Id: <tenant_id>
X-Program-Id: <program_id>
X-Region: <region>
X-Channel: <channel>
```

## SolaceNet Tokenization Endpoints

### 1. Mint Tokenized Asset

Mint a new tokenized asset (requires `tokenization.mint` capability).

**Endpoint:** `POST /api/v1/solacenet/tokenization/mint`

**Request Body:**
```json
{
  "underlyingAsset": "EUR",
  "amount": "1000000.00",
  "issuer": "0x...",
  "reserveId": "RESERVE-EUR-001",
  "recipient": "0x...",
  "regulatoryFlags": {
    "kyc": true,
    "aml": true,
    "regulatoryApproval": true
  }
}
```

**Response:**
```json
{
  "requestId": "TOKEN-1234567890-abc123",
  "fabricTokenId": "EUR-T-2025-001",
  "fabricTxHash": "0x...",
  "besuTokenAddress": "0x...",
  "besuTxHash": "0x...",
  "status": "COMPLETED"
}
```

### 2. Transfer Tokenized Asset

Transfer tokenized asset (requires `tokenization.transfer` capability).

**Endpoint:** `POST /api/v1/solacenet/tokenization/transfer`

**Request Body:**
```json
{
  "tokenId": "EUR-T-2025-001",
  "from": "0x...",
  "to": "0x...",
  "amount": "100.00"
}
```

**Response:**
```json
{
  "txHash": "0x...",
  "status": "completed"
}
```

### 3. Redeem Tokenized Asset

Redeem tokenized asset back to underlying asset (requires `tokenization.redeem` capability).

**Endpoint:** `POST /api/v1/solacenet/tokenization/redeem`

**Request Body:**
```json
{
  "tokenId": "EUR-T-2025-001",
  "redeemer": "0x...",
  "amount": "100.00"
}
```

**Response:**
```json
{
  "fabricTxHash": "0x...",
  "besuTxHash": "0x...",
  "status": "completed"
}
```

### 4. Get Tokenization Status

Get status of tokenization request (requires `tokenization.view` capability).

**Endpoint:** `GET /api/v1/solacenet/tokenization/status/:requestId`

**Response:**
```json
{
  "requestId": "TOKEN-1234567890-abc123",
  "status": "BESU_MINTED",
  "fabricTokenId": "EUR-T-2025-001",
  "fabricTxHash": "0x...",
  "besuTokenAddress": "0x...",
  "besuTxHash": "0x...",
  "settlementFile": {
    "blockchain": {...},
    "traditional": {...}
  }
}
```

### 5. Get Token Details

Get details of a tokenized asset (requires `tokenization.view` capability).

**Endpoint:** `GET /api/v1/solacenet/tokenization/token/:tokenId`

**Response:**
```json
{
  "tokenId": "EUR-T-2025-001",
  "tokenAddress": "0x...",
  "underlyingAsset": "EUR",
  "totalSupply": "1000000.00",
  "backedAmount": "1000000.00",
  "backingRatio": 1.0,
  "status": "ACTIVE",
  "reserveStatus": {
    "reserveId": "RESERVE-EUR-001",
    "totalReserve": "1000000.00",
    "availableReserve": "0.00",
    "lastAttested": 1234567890
  }
}
```

## FireFly Tokenization Endpoints

### 6. Initiate Minting Workflow

**Endpoint:** `POST /api/tokenization/mint`

**Request Body:**
```json
{
  "requestId": "TOKEN-1234567890-abc123",
  "underlyingAsset": "EUR",
  "amount": "1000000.00",
  "issuer": "0x...",
  "reserveId": "RESERVE-EUR-001"
}
```

### 7. Get Settlement File

**Endpoint:** `GET /api/tokenization/settlement/:txHash`

**Response:**
```json
{
  "blockchain": {
    "hash": "0x...",
    "from": "0x...",
    "to": "0x...",
    "value": "1000000000000000000",
    "gas": "21000",
    "gasPrice": "20000000000",
    "nonce": "0",
    "blockNumber": "12345",
    "transactionIndex": "0",
    "input": "0x...",
    "chainId": "138",
    "usdtErc20": "token"
  },
  "traditional": {
    "swiftReference": "SWIFT-1234567890-ABC",
    "target2Code": "T2-1234567890",
    "regulatoryFlags": {...},
    "identityCode": "42Q GB DD GB 42FOP 36F",
    "permitCode": "PERMIT-1234567890",
    "accessCode": "ACCESS-1234567890"
  }
}
```

## Sub-Volume Integration Endpoints

### 8. GAS Settlement for Tokenized Asset

**Endpoint:** `POST /api/gas/tokenization/settle`

**Request Body:**
```json
{
  "tokenAddress": "0x...",
  "fabricTokenId": "EUR-T-2025-001",
  "sourceBankId": "BANK-001",
  "destinationBankId": "BANK-002",
  "amount": "100.00",
  "currencyCode": "EUR"
}
```

### 9. GRU Valuation for Tokenized Asset

**Endpoint:** `POST /api/gru/tokenization/value`

**Request Body:**
```json
{
  "tokenAddress": "0x...",
  "underlyingAsset": "EUR",
  "amount": "100.00",
  "targetCurrency": "GRU"
}
```

**Response:**
```json
{
  "tokenAddress": "0x...",
  "underlyingAsset": "EUR",
  "amount": "100.00",
  "gruValue": "95.50",
  "gruUnit": "M00",
  "xauRate": "2000.00",
  "triangulationRate": "0.955"
}
```

### 10. Metaverse Virtual Representation

**Endpoint:** `POST /api/metaverse/tokenization/create-virtual`

**Request Body:**
```json
{
  "tokenAddress": "0x...",
  "fabricTokenId": "EUR-T-2025-001",
  "metaverseNodeId": "METAVERSE-DUBAI",
  "virtualAssetId": "VIRTUAL-LAND-001",
  "amount": "100.00",
  "currencyCode": "EUR"
}
```

## Error Responses

All endpoints may return error responses:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}
```

### Error Codes

- `CAPABILITY_NOT_GRANTED`: SolaceNet capability not granted
- `CREDENTIAL_INVALID`: Indy credential invalid or missing
- `RESERVE_INSUFFICIENT`: Insufficient reserve for operation
- `TOKEN_NOT_FOUND`: Tokenized asset not found
- `INVALID_STATUS`: Invalid operation status
- `POLICY_DENIED`: Policy engine denied operation
- `UNAUTHORIZED`: Authentication required
- `FORBIDDEN`: Insufficient permissions

## Rate Limiting

- **Mint/Transfer/Redeem**: 100 requests per minute per tenant
- **View operations**: 1000 requests per minute per tenant

## WebSocket Events

Real-time tokenization status updates:

**Connection:** `wss://api.tokenization.chain138.example.com/ws`

**Subscribe:**
```json
{
  "action": "subscribe",
  "requestId": "TOKEN-1234567890-abc123"
}
```

**Event:**
```json
{
  "event": "tokenization_status_update",
  "requestId": "TOKEN-1234567890-abc123",
  "status": "BESU_MINTING",
  "timestamp": 1234567890
}
```