ATS / BD / TA Interoperability

// ATS calling BD for compliance check
func (a *ATS) checkCompliance(ctx context.Context, orgID, investorID string) error {
    req, _ := http.NewRequestWithContext(ctx, "GET",
        fmt.Sprintf("http://bd.backend.svc.cluster.local:8090/v1/investors/%s/compliance", investorID),
        nil,
    )
    req.Header.Set("Authorization", "Bearer "+a.serviceToken)
    req.Header.Set("X-IAM-Org", orgID)

    resp, err := a.httpClient.Do(req)
    if err != nil {
        return fmt.Errorf("bd: compliance check failed: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return fmt.Errorf("bd: compliance check returned %d", resp.StatusCode)
    }
    return nil
}

func (s *Service) refreshToken(ctx context.Context) error {
    token, err := s.iamClient.ClientCredentials(ctx, sdk.ClientCredentialsRequest{
        ClientID:     s.config.IAMClientID,
        ClientSecret: s.config.IAMClientSecret,
        Scope:        "internal",
    })
    if err != nil {
        return fmt.Errorf("iam: token refresh failed: %w", err)
    }
    s.serviceToken = token.AccessToken
    return nil
}

// In ATS order handler
func (h *Handler) ListOrders(w http.ResponseWriter, r *http.Request) {
    orgID := r.Header.Get("X-IAM-Org")
    if orgID == "" {
        http.Error(w, "missing organization", http.StatusForbidden)
        return
    }

    orders, err := h.store.ListOrders(r.Context(), orgID)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    json.NewEncoder(w).Encode(orders)
}

// In the store layer — organization_id is always in the WHERE clause
func (s *Store) ListOrders(ctx context.Context, orgID string) ([]Order, error) {
    rows, err := s.db.QueryContext(ctx,
        `SELECT id, asset_id, side, quantity, price, status, created_at
         FROM orders
         WHERE organization_id = $1
         ORDER BY created_at DESC`,
        orgID,
    )
    // ...
}

1. Investor places order
        │
        ▼
2. ATS: Pre-trade compliance ──────► BD: KYC/AML/accreditation check
        │                                    │
        │ ◄──── compliance: approved ────────┘
        ▼
3. ATS: Match order (DEX engine)
        │
        ▼
4. ATS: Record trade in PostgreSQL (source of truth)
        │
        ├──► 5a. ATS: Queue settlement intent (pending_settlements table)
        │
        └──► 5b. ATS: Notify BD (webhook: trade.executed)
                       │
                       └──► BD: Post-trade surveillance
                            BD: Regulatory reporting (OATS, CAT)
        │
        ▼
6. Settlement cron (30s interval):
        │
        ├──► MPC: Sign transaction (CGGMP21 threshold signature)
        │
        ├──► Chain: Record on SettlementRegistry contract
        │         │
        │         ▼
        │    BD: Approve settlement (verify compliance)
        │         │
        │         ▼
        │    TA: Record transfer on cap table
        │         │
        │         ▼
        │    Chain: Mint/burn SecurityToken (ERC-20)
        │
        └──► ATS: Update settlement status (PENDING → SETTLED)

// Settlement cron — runs every 30 seconds
func (s *Settler) ProcessPending(ctx context.Context) error {
    settlements, err := s.store.ListPendingSettlements(ctx)
    if err != nil {
        return fmt.Errorf("list pending: %w", err)
    }

    for _, stl := range settlements {
        if err := s.settle(ctx, stl); err != nil {
            // Log and continue — don't block other settlements
            s.logger.Error("settlement failed",
                "settlement_id", stl.ID,
                "error", err,
            )
            continue
        }
    }
    return nil
}

func (s *Settler) settle(ctx context.Context, stl Settlement) error {
    // 1. Sign via MPC
    sig, err := s.mpc.Sign(ctx, stl.TxData)
    if err != nil {
        return fmt.Errorf("mpc sign: %w", err)
    }

    // 2. Submit to chain
    txHash, err := s.chain.SubmitSettlement(ctx, stl, sig)
    if err != nil {
        // Chain down — leave as pending, retry next cron cycle
        return fmt.Errorf("chain submit: %w", err)
    }

    // 3. Notify TA to record transfer
    if err := s.ta.RecordTransfer(ctx, stl); err != nil {
        return fmt.Errorf("ta record: %w", err)
    }

    // 4. Mark settled
    return s.store.MarkSettled(ctx, stl.ID, txHash)
}

NEW → PENDING_COMPLIANCE → OPEN → PARTIALLY_FILLED → FILLED → SETTLING → SETTLED
                                                                    ↓
NEW → PENDING_COMPLIANCE → REJECTED (compliance failure)      SETTLEMENT_FAILED
                                                                    ↓
NEW → PENDING_COMPLIANCE → OPEN → CANCELLED                    REVERSED

// BD routes an order to the optimal venue
route, err := broker.Route(ctx, broker.RouteRequest{
    OrgID:    orgID,
    Symbol:   "AAPL",
    Side:     "buy",
    Quantity: 100,
    Strategy: broker.BestExecution, // FINRA 5310 compliant
})
// route.Venue = "alpaca"
// route.Price = 187.50
// route.Fills = [{qty: 100, price: 187.50}]

// TA records a transfer from seller to buyer
func (ta *TransferAgent) RecordTransfer(ctx context.Context, req TransferRequest) (*Transfer, error) {
    // 1. Validate the transfer instruction
    if err := ta.validate(ctx, req); err != nil {
        return nil, fmt.Errorf("validation failed: %w", err)
    }

    // 2. Check transfer restrictions (Rule 144, lock-up, etc.)
    if err := ta.checkRestrictions(ctx, req); err != nil {
        return nil, fmt.Errorf("restriction check failed: %w", err)
    }

    // 3. Record on cap table
    transfer, err := ta.captable.Transfer(ctx, captable.TransferRequest{
        AssetID:        req.AssetID,
        FromInvestorID: req.SellerID,
        ToInvestorID:   req.BuyerID,
        Quantity:       req.Quantity,
        PricePerShare:  req.PricePerShare,
        OrganizationID: req.OrganizationID,
        SettlementID:   req.SettlementID,
    })
    if err != nil {
        return nil, fmt.Errorf("captable transfer: %w", err)
    }

    // 4. Update shareholder registry
    if err := ta.updateRegistry(ctx, transfer); err != nil {
        return nil, fmt.Errorf("registry update: %w", err)
    }

    return transfer, nil
}

ATS  → http://bd.backend.svc.cluster.local:8090
ATS  → http://ta.backend.svc.cluster.local:8100
BD   → http://ats.backend.svc.cluster.local:8080
TA   → http://ats.backend.svc.cluster.local:8080

{
  "error": {
    "code": "COMPLIANCE_REJECTED",
    "message": "Investor accreditation expired",
    "details": {
      "investor_id": "inv_a1b2c3",
      "check": "accreditation",
      "expired_at": "2026-01-15T00:00:00Z"
    }
  }
}

-- Example: ATS orders table
CREATE TABLE orders (
    id              TEXT PRIMARY KEY,
    organization_id TEXT NOT NULL,
    investor_id     TEXT NOT NULL,
    asset_id        TEXT NOT NULL,
    side            TEXT NOT NULL CHECK (side IN ('buy', 'sell')),
    order_type      TEXT NOT NULL CHECK (order_type IN ('market', 'limit', 'stop', 'stop_limit')),
    quantity        NUMERIC NOT NULL,
    price           NUMERIC,
    status          TEXT NOT NULL DEFAULT 'new',
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_orders_org ON orders (organization_id);
CREATE INDEX idx_orders_org_status ON orders (organization_id, status);
CREATE INDEX idx_orders_org_investor ON orders (organization_id, investor_id);

# ATS
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ats
  namespace: backend
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: ats
          image: ghcr.io/liquidityio/ats:next
          ports:
            - containerPort: 8080
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: ats-db
                  key: url
            - name: IAM_CLIENT_ID
              valueFrom:
                secretKeyRef:
                  name: ats-iam
                  key: client_id
            - name: IAM_CLIENT_SECRET
              valueFrom:
                secretKeyRef:
                  name: ats-iam
                  key: client_secret
            - name: IAM_URL
              value: https://iam.liquidity.io