dbis_core/docs/nostro-vostro/cb-implementation-guide.md

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
2. Phased Rollout Strategy
3. Infrastructure Setup
4. API Configuration
5. FI Onboarding
6. Testing & Validation
7. Production Deployment
8. Best Practices
9. 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

# 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

# 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

# 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 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
• Plugin Development Guide
• ISO 20022 Mapping Guide
• SWIFT Mapping Guide
• RTGS Mapping Guide

---

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