dbis_core/SOLACENET_QUICK_REFERENCE.md

SolaceNet Quick Reference

Quick reference guide for the SolaceNet Capability Platform.

Core Concepts

Capability States

• disabled - No execution, gateway blocks
• pilot - Allowlist only
• enabled - Active for entitled scopes
• suspended - Execution blocked, reads allowed
• drain - No new requests, allow in-flight settlement

Scoping Levels

• Tenant
• Program (product line)
• Region (jurisdiction)
• Channel (API/UI/mobile)
• Customer segment (optional)

Rail and external protocol governance

Financial rails (SWIFT, DTC/DTCC, TT, KTT legacy evidence, etc.) and integration contracts for telecom-adjacent stacks (for example SS7 terminated at a carrier boundary) are maintained under SolaceNet: capabilities, policy, audit, Go gateway, and TypeScript adapters in src/core/gateway/adapters/. Full policy, code map, and change process: docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md. Tracked protocol gaps (complete list): docs/solacenet/PROTOCOL_GAPS_CHECKLIST.md.

Gateway REST (dbis_core API)

Authenticated routes under /api/v1/gateway: GET /rails (list adapter IDs), GET /rails/:adapterId/health, POST .../validate, POST .../receive, plus existing instructions and event replay. Optional SolaceNet enforcement: SOLACENET_GATEWAY_RAILS_ENFORCE=1 and SOLACENET_DEFAULT_TENANT_ID — see src/core/gateway/rails/README.md and .env.example. OpenAPI: /api-docs (tag SolaceNet Gateway Rails).

API Quick Reference

Capability Registry

# List capabilities
GET /api/v1/solacenet/capabilities

# Get capability
GET /api/v1/solacenet/capabilities/{id}

# Create capability
POST /api/v1/solacenet/capabilities
{
  "capabilityId": "payment-gateway",
  "name": "Payment Gateway",
  "version": "1.0.0",
  "defaultState": "disabled"
}

Entitlements

# Get entitlements
GET /api/v1/solacenet/tenants/{tenantId}/programs/{programId}/entitlements

# Create entitlement
POST /api/v1/solacenet/entitlements
{
  "tenantId": "tenant-123",
  "capabilityId": "payment-gateway",
  "stateOverride": "enabled"
}

Policy Decisions

# Make decision
POST /api/v1/solacenet/policy/decide
{
  "tenantId": "tenant-123",
  "capabilityId": "payment-gateway",
  "region": "US",
  "channel": "API"
}

# Activate kill switch
POST /api/v1/solacenet/policy/kill-switch/{capabilityId}
{
  "reason": "Emergency shutdown"
}

Risk Assessment

# Assess risk
POST /api/v1/risk/assess
{
  "userId": "user-123",
  "amount": "1000.00",
  "currencyCode": "USD",
  "deviceFingerprint": "abc123",
  "velocityData": {
    "count24h": 5
  }
}

Service SDK Usage

import { requireCapability } from '@/shared/solacenet/sdk';

async function processPayment(...) {
  // Check capability before proceeding
  await requireCapability('payment-gateway', {
    tenantId: 'tenant-123',
    programId: 'program-456',
    region: 'US',
    channel: 'API'
  });
  
  // Proceed with payment processing
  // ...
}

Common Patterns

Registering a New Capability

1. Create capability:

await capabilityRegistryService.createCapability({
  capabilityId: 'my-capability',
  name: 'My Capability',
  version: '1.0.0',
  defaultState: 'disabled',
  dependencies: ['payment-gateway']
});

2. Create entitlement:

await entitlementsService.createEntitlement({
  tenantId: 'tenant-123',
  capabilityId: 'my-capability',
  stateOverride: 'enabled'
});

3. Use in service:

await requireCapability('my-capability', { tenantId: 'tenant-123' });

Creating Policy Rules

await policyEngineService.createPolicyRule({
  ruleId: 'high-risk-block',
  capabilityId: 'payment-gateway',
  scope: 'global',
  condition: {
    and: [
      { gt: { risk_score: 80 } },
      { gt: { amount: 10000 } }
    ]
  },
  decision: 'deny',
  priority: 10
});

Risk Rules

await riskRulesEngine.createRule({
  ruleId: 'velocity-check',
  name: 'High Velocity Detection',
  ruleType: 'velocity',
  condition: {
    gt: { count24h: 20 }
  },
  action: 'block',
  riskScore: 80,
  priority: 50,
  status: 'active'
});

Deployment

Docker Compose

docker-compose -f docker-compose.solacenet.yml up -d

Environment Variables

DATABASE_URL=postgresql://...
REDIS_URL=redis://localhost:6379
SOLACENET_GATEWAY_PORT=8080
JWT_SECRET=your-secret

Troubleshooting

Capability Not Available

1. Check entitlement exists
2. Verify capability state
3. Check policy rules
4. Review audit logs

Policy Decision Caching

• Cache TTL: 120 seconds (configurable)
• Kill switch invalidates cache immediately
• Redis required for caching

Gateway Issues

• Verify Redis connection
• Check backend URL configuration
• Review gateway logs

File Locations

• Services: src/core/solacenet/
• Shared SDK: src/shared/solacenet/
• Gateway: gateway/go/
• Rail adapters: src/core/gateway/adapters/ (governed per docs/solacenet/RAIL_AND_PROTOCOL_GOVERNANCE.md)
• Rail enforcement env: src/core/gateway/rails/README.md
• Console: frontend/solacenet-console/
• Schema: prisma/schema.prisma