# DBIS Nostro/Vostro Network — Central Bank Implementation Guide

## Overview

This guide provides step-by-step instructions for Central Banks (SCBs) to implement and deploy the DBIS Nostro/Vostro Network API for their regulated Financial Institutions (FIs).

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Phased Rollout Strategy](#phased-rollout-strategy)
3. [Infrastructure Setup](#infrastructure-setup)
4. [API Configuration](#api-configuration)
5. [FI Onboarding](#fi-onboarding)
6. [Testing & Validation](#testing--validation)
7. [Production Deployment](#production-deployment)
8. [Best Practices](#best-practices)
9. [Troubleshooting](#troubleshooting)

## Prerequisites

### Technical Requirements

- **API Gateway**: RESTful API gateway supporting OpenAPI 3.0.3
- **Authentication**: OAuth2 server with Mutual TLS (mTLS) support
- **Database**: PostgreSQL 12+ or compatible database
- **Network**: Secure network connectivity to DBIS infrastructure
- **HSM**: Hardware Security Module for key management (recommended)

### Regulatory Requirements

- Central Bank authorization to operate Nostro/Vostro services
- Compliance with local banking regulations
- Data protection and privacy compliance (GDPR, local regulations)
- Audit trail capabilities

### Organizational Requirements

- Designated API administrator
- Technical support team
- Compliance officer
- Relationship manager for FI onboarding

## Phased Rollout Strategy

### Phase 1: Pilot / Sandbox (Months 1-3)

**Objective**: Validate API functionality with limited participants

**Activities**:
1. Deploy sandbox environment
2. Onboard 1-3 Tier-1 FIs
3. Test core endpoints:
   - Participant registration
   - Account creation
   - Transfer initiation
   - Balance queries
4. Collect feedback and iterate

**Success Criteria**:
- All core endpoints functional
- No critical bugs
- Positive FI feedback
- Performance meets SLA requirements

### Phase 2: Expansion (Months 4-6)

**Objective**: Broaden FI participation and add advanced features

**Activities**:
1. Onboard additional Tier-1 and Tier-2 FIs
2. Enable webhook integration
3. Implement reconciliation automation
4. Add GRU/FX endpoints
5. Performance optimization

**Success Criteria**:
- 10+ FIs onboarded
- Webhook delivery success rate > 99%
- Reconciliation accuracy > 99.9%
- API response time < 200ms (p95)

### Phase 3: Full Production (Months 7+)

**Objective**: Full-scale deployment with all features

**Activities**:
1. Onboard all eligible FIs
2. Integration with GRU/FX and GAS
3. Ω-Layer-aligned settlement
4. Advanced monitoring and alerting
5. Continuous improvement

**Success Criteria**:
- All eligible FIs onboarded
- 24/7 availability (99.9% uptime)
- Full GRU/FX integration
- Complete audit trail

## Infrastructure Setup

### 1. API Gateway Configuration

#### Server Configuration

```yaml
# Example configuration
servers:
  - url: https://api.yourcb.gov/api/v1/nostro-vostro
    description: Production
  - url: https://sandbox.yourcb.gov/api/v1/nostro-vostro
    description: Sandbox
```

#### Security Configuration

1. **OAuth2 Setup**:
   - Configure OAuth2 authorization server
   - Set up client credentials flow
   - Configure scopes: `nv.read`, `nv.write`, `nv.reconcile`, `gru.read`, `gru.convert`

2. **Mutual TLS (mTLS)**:
   - Generate server certificates
   - Configure client certificate validation
   - Set up certificate revocation list (CRL) checking

3. **Rate Limiting**:
   - Configure per-FI rate limits
   - Set up burst allowances
   - Monitor and alert on rate limit violations

### 2. Database Setup

#### Schema Migration

```bash
# Run Prisma migrations
npx prisma migrate deploy

# Verify schema
npx prisma studio
```

#### Indexes

Ensure the following indexes are created for optimal performance:
- `participantId` on `nostro_vostro_participants`
- `accountId` on `nostro_vostro_accounts`
- `transferId` and `idempotencyKey` on `nostro_vostro_transfers`
- `reportId` on `nostro_vostro_reconciliations`

### 3. Integration Points

#### DBIS Core Integration

- Connect to DBIS GAS (Global Atomic Settlement) network
- Configure Ω-Layer finality integration
- Set up GRU/FX rate feeds
- Configure webhook delivery infrastructure

#### Internal Systems Integration

- RTGS system integration
- Core banking system integration
- Compliance system integration
- Reporting system integration

## API Configuration

### 1. Environment Variables

```bash
# API Configuration
API_BASE_URL=https://api.yourcb.gov/api/v1/nostro-vostro
API_VERSION=1.0.0

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/nostro_vostro

# Authentication
OAUTH2_TOKEN_URL=https://auth.yourcb.gov/oauth/token
OAUTH2_CLIENT_ID=your_client_id
OAUTH2_CLIENT_SECRET=your_client_secret

# Security
MTLS_ENABLED=true
MTLS_CA_CERT_PATH=/path/to/ca.crt

# Webhooks
WEBHOOK_RETRY_ATTEMPTS=5
WEBHOOK_TIMEOUT_MS=30000

# GRU/FX
GRU_FX_ENABLED=true
GRU_FX_RATE_SOURCE=DBIS_GRU
```

### 2. API Documentation

- Host OpenAPI spec at `/api-docs` endpoint
- Provide interactive Swagger UI
- Generate client SDKs (Java, .NET, Python, Node.js)
- Publish API reference documentation

### 3. Monitoring & Logging

- Set up application performance monitoring (APM)
- Configure structured logging
- Set up alerting for:
  - API errors (> 1% error rate)
  - High latency (> 500ms p95)
  - Failed webhook deliveries
  - Reconciliation breaks

## FI Onboarding

### 1. Pre-Onboarding Checklist

**For Central Bank**:
- [ ] API documentation published
- [ ] Sandbox environment available
- [ ] Test credentials generated
- [ ] Support channels established
- [ ] Onboarding process documented

**For Financial Institution**:
- [ ] Technical team assigned
- [ ] Development environment ready
- [ ] Network connectivity established
- [ ] Security certificates obtained
- [ ] Compliance approval received

### 2. Onboarding Process

#### Step 1: Registration

1. FI submits participant registration request
2. CB reviews and approves
3. CB creates participant record via API
4. CB provides participant ID and credentials

#### Step 2: Account Setup

1. FI requests Nostro/Vostro account creation
2. CB creates account via API
3. CB provides account ID and details
4. FI verifies account in their system

#### Step 3: Integration Testing

1. FI implements API client
2. FI tests in sandbox environment
3. CB validates test transactions
4. Both parties sign off on testing

#### Step 4: Production Access

1. CB grants production credentials
2. FI switches to production endpoint
3. CB monitors initial transactions
4. Both parties confirm successful go-live

### 3. Onboarding Timeline

- **Registration**: 1-2 business days
- **Account Setup**: 1 business day
- **Integration Testing**: 2-4 weeks
- **Production Access**: 1 business day

**Total**: 3-5 weeks

## Testing & Validation

### 1. Test Scenarios

#### Core Functionality Tests

- Participant creation and retrieval
- Account creation and balance queries
- Transfer initiation and status tracking
- Reconciliation report generation
- Webhook subscription and delivery

#### Error Handling Tests

- Invalid authentication
- Insufficient balance
- Duplicate idempotency keys
- Invalid account references
- Network timeouts

#### Performance Tests

- Concurrent request handling
- Large batch transfers
- High-frequency balance queries
- Webhook delivery under load

### 2. Test Playbook

See [Test Playbook](./api-reference.md) for detailed test cases.

### 3. Validation Checklist

- [ ] All endpoints functional
- [ ] Error responses correct
- [ ] Idempotency working
- [ ] Webhooks delivering
- [ ] Reconciliation accurate
- [ ] Performance meets SLA
- [ ] Security validated
- [ ] Audit trail complete

## Production Deployment

### 1. Pre-Deployment Checklist

- [ ] Infrastructure provisioned
- [ ] Database migrated
- [ ] API deployed
- [ ] Monitoring configured
- [ ] Alerting configured
- [ ] Backup strategy in place
- [ ] Disaster recovery tested
- [ ] Security audit completed
- [ ] Documentation published
- [ ] Support team trained

### 2. Deployment Steps

1. **Deploy to Staging**:
   - Deploy latest code
   - Run database migrations
   - Verify all services healthy
   - Run smoke tests

2. **Deploy to Production**:
   - Schedule maintenance window
   - Deploy code (blue-green deployment)
   - Run database migrations
   - Verify services healthy
   - Monitor for issues

3. **Post-Deployment**:
   - Verify API endpoints
   - Check monitoring dashboards
   - Validate webhook delivery
   - Confirm reconciliation working
   - Notify FIs of deployment

### 3. Rollback Plan

- Keep previous version available
- Database migrations reversible
- Feature flags for gradual rollout
- Automated rollback triggers

## Best Practices

### 1. Security

- **Always use mTLS** for production
- **Rotate credentials** regularly
- **Monitor for anomalies** in API usage
- **Implement rate limiting** per FI
- **Log all API calls** for audit

### 2. Performance

- **Cache frequently accessed data** (participants, accounts)
- **Use connection pooling** for database
- **Implement pagination** for large result sets
- **Optimize database queries** with proper indexes
- **Monitor and tune** based on metrics

### 3. Reliability

- **Implement retry logic** for transient failures
- **Use idempotency keys** for all transfers
- **Set up health checks** and monitoring
- **Plan for disaster recovery**
- **Test failover procedures** regularly

### 4. Compliance

- **Maintain complete audit trail**
- **Implement data retention policies**
- **Ensure GDPR/privacy compliance**
- **Regular compliance audits**
- **Document all procedures**

## Troubleshooting

### Common Issues

#### 1. Authentication Failures

**Symptoms**: 401 Unauthorized errors

**Solutions**:
- Verify OAuth2 token is valid
- Check mTLS certificate is valid
- Ensure correct scopes are requested
- Verify token hasn't expired

#### 2. Transfer Failures

**Symptoms**: Transfers stuck in PENDING status

**Solutions**:
- Check account balances
- Verify account status (ACTIVE)
- Check for holds on accounts
- Review rejection reasons

#### 3. Webhook Delivery Failures

**Symptoms**: Webhooks not received by FI

**Solutions**:
- Verify webhook URL is accessible
- Check webhook signature validation
- Review delivery logs
- Test webhook endpoint manually

#### 4. Reconciliation Breaks

**Symptoms**: Reconciliation reports show breaks

**Solutions**:
- Review transaction history
- Check for pending transfers
- Verify account balances
- Compare with internal records

### Support Contacts

- **Technical Support**: To be configured
- **Emergency Hotline**: To be configured
- **Documentation**: To be configured (e.g. https://docs.yourcb.gov/nostro-vostro)

## Next Steps

1. Review this guide with your technical team
2. Set up sandbox environment
3. Begin FI onboarding process
4. Schedule production deployment
5. Monitor and iterate

## Additional Resources

- [API Reference](./api-reference.md)
- [Plugin Development Guide](./plugin-development-guide.md)
- [ISO 20022 Mapping Guide](./iso20022-mapping.md)
- [SWIFT Mapping Guide](./swift-mapping.md)
- [RTGS Mapping Guide](./rtgs-mapping.md)

---

**Version**: 1.0.0  
**Last Updated**: 2024-01-15  
**Contact**: cb-support@dbis.org