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: api-support@yourcb.gov
• Emergency Hotline: +1-XXX-XXX-XXXX
• Documentation: 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