TradFi Bridge

Overview

The TradFi Bridge is not a single service. It is the entire integration layer that connects the on-chain world of Solana programs and CrossSecurities to the traditional financial system - Clearstream settlement, SWIFT messaging, SEC regulatory filings, investor notifications, and revenue distribution. Every service that touches an external system or translates between on-chain events and off-chain actions lives here.

The bridge is composed of five cooperating services, each running as a grain or sidecar within the Sandstorm/Melusina OS environment:

All bridge services share two non-negotiable constraints: every action is logged to an append-only journal with 7-year retention, and every service must tolerate restarts via deterministic journal replay. If a grain crashes mid-operation, it recovers to exact state on restart. No data loss. No missed events.

Architecture

The bridge services form a directed pipeline. On-chain events flow in through the Solana Event Watcher, fan out to the appropriate grains, and ultimately produce off-chain effects - settlement instructions, notifications, regulatory filings, and distribution payments.

┌──────────────────────┐
│  Solana Programs     │
│  (sails_securities,  │
│   sails_crossconv,   │
│   sails_distributions│)
└──────────┬───────────┘
           │ WebSocket RPC (program events)
           ▼
┌──────────────────────┐
│  Solana Event        │
│  Watcher (Go grain)  │
│                      │
│  Routes events to:   │
├──────────┬───────────┤
│          │           │
▼          ▼           ▼
┌────────┐ ┌────────┐ ┌────────────────┐
│Offering│ │CrossConv│ │DAO Manager     │
│Grain   │ │Operator │ │Grain           │
└───┬────┘ └───┬────┘ └───┬────────────┘
    │          │           │
    │          ▼           │
    │   ┌────────────────┐ │
    │   │Clearstream     │ │
    │   │Adapter (Go)    │ │
    │   │                │ │
    │   │MT540/MT542     │ │
    │   │ISO 20022       │ │
    │   └───┬────────────┘ │
    │       │              │
    ▼       ▼              ▼
┌──────────────────────────────┐
│  Notification Service (Go)   │
│  Email · Webhook · WebSocket │
└──────────────────────────────┘

The Powerbox capability system governs all inter-grain communication. The Event Watcher holds capabilities to the Offering Grain, CrossConversion Operator, DAO Manager, Broker Grain, and Investor Grains. Each capability is a persistent SturdyRef - surviving grain restarts and session boundaries. No service can call another service it hasn't been explicitly granted access to.

Solana Event Watcher

The Solana Event Watcher is a Go grain that subscribes to program events via WebSocket RPC and routes them to the appropriate grain for processing. It is the single entry point for all on-chain activity into the off-chain platform.

Service: solana-watcher (Go, runs as grain)
├── Subscribe to program events via WebSocket RPC
├── Route events to appropriate grains:
│   ├── SecurityMinted → Offering Grain (update cap table)
│   ├── CrossConversionRequested → CrossConversion Operator
│   ├── DistributionPaid → Investor Grains (notify)
│   ├── ComplianceViolation → DAO Manager (alert)
│   └── TransferCompleted → Broker Grain (settlement confirmation)
├── Maintain local event log for replay
└── Health monitoring & reconnection logic

Event Routing Table

Connection Management

The watcher maintains a persistent WebSocket connection to the Solana RPC node. Connection resilience is critical - a dropped connection means missed events, which means the off-chain state drifts from on-chain reality.

• Reconnection: Exponential backoff with jitter - 1s, 2s, 4s, 8s, up to 60s max. On reconnect, the watcher replays events from the last confirmed slot using the local event log.
• Multi-RPC failover: Configurable list of RPC endpoints. If the primary fails three consecutive health checks, the watcher switches to the next endpoint.
• Local event log: Every event received is written to the grain's append-only journal before routing. On crash recovery, the journal replay re-delivers any events that were received but not yet acknowledged by their destination grain.
• Deduplication: Each event carries a unique (slot, tx_signature, log_index) tuple. Destination grains reject duplicate deliveries idempotently.

Watcher Configuration

# solana-watcher.toml
[rpc]
endpoints = [
  "wss://api.mainnet-beta.solana.com",
  "wss://sails.rpcpool.com"
]
reconnect_max_sec  = 60
health_check_sec   = 10
[programs]
securities     = “SAILSec111111111111111111111111111111111”
crossconversion = “SAILCross1111111111111111111111111111111”
distributions  = “SAILDist11111111111111111111111111111111”
[routing]
security_minted        = “offering-grain”
cross_conversion       = “crossconv-operator”
distribution_paid      = “investor-grains”
compliance_violation   = “dao-manager”
transfer_completed     = “broker-grain”

Notification Service

The Notification Service is a Go grain that delivers messages to every participant in the platform - investors, brokers, trustees, issuers, and compliance officers. It supports three delivery channels: email, webhooks, and in-app WebSocket push.

Service: notification-grain (Go)
├── Email (via Sandstorm email capability or external SMTP)
│   ├── Investor subscription confirmations
│   ├── Distribution payment notifications
│   ├── CrossConversion status updates
│   ├── KYC status changes
│   └── Regulatory notices
├── Webhook notifications to broker systems
└── In-app notifications via WebSocket hub

Notification Types

Email Delivery

The notification grain uses the Sandstorm email capability when available, falling back to external SMTP (e.g., SendGrid, SES) for high-volume delivery. All emails are template-driven, rendered server-side with Go’s html/template package. Templates are versioned in the grain’s journal - every email sent is reproducible from the journal state at send time.

• Delivery tracking: Message ID, send timestamp, delivery status, and bounce handling are logged per recipient.
• Rate limiting: Per-recipient rate limits prevent notification fatigue. Distribution notifications for the same offering are batched into a single daily digest if the investor holds positions in multiple tranches.
• Unsubscribe: Regulatory notices and compliance alerts cannot be unsubscribed. All other notification categories support per-investor preference management.

Webhook Delivery

Broker systems receive real-time event data via authenticated HTTPS webhooks. The notification grain signs each webhook payload with the broker’s shared HMAC secret. Delivery uses at-least-once semantics with exponential backoff retries (1s, 2s, 4s, up to 5 minutes). Brokers must respond with HTTP 2xx within 10 seconds or the delivery is retried.

In-App WebSocket

Real-time notifications are pushed to connected clients via WebSession_WebSocketStream - the Cap’n Proto WebSocket interface native to Sandstorm grains. Each grain maintains its own WebSocket hub. When a notification targets a specific investor, the notification grain sends it to that investor’s Self-Service Grain, which pushes it to any connected browser sessions.

Revenue & Distribution Bridge

The Distribution Bridge connects the on-chain sails_distributions waterfall program to the bankable side of the platform. When revenue enters and the waterfall executes, token holders on-chain claim their distributions directly from the program. But investors who have converted to ISIN-identified securities via CrossConversion are not on-chain - their positions live at Clearstream. The Distribution Bridge ensures they receive their pro-rata share through traditional corporate action channels.

Distribution Flow

1. Revenue enters the Operating Series - Cash from the underlying asset (rent, revenue, interest) is deposited into the Operating Series account via the deposit_revenue instruction on the sails_distributions program.
2. Waterfall executes - The execute_waterfall instruction distributes funds per tranche priority:
   1. Senior debt holders
   2. Investor distributions (pro-rata by token holding)
   3. Platform fee (1%)
   4. Excess to Treasury Series
3. On-chain holders claim - Investors holding tokens in their wallets call claim_distribution to pull their allocation. The program tracks claims via a bitmap per epoch to prevent double-claiming.
4. Bankable holders receive corporate actions - For investors whose tokens are locked in the CrossConversion lockbox, the Distribution Bridge calculates their pro-rata share based on lockbox position records and instructs the Clearstream Adapter to issue a corporate action (ISO 20022 seev.031 notification followed by seev.035 movement confirmation) crediting the investor’s Clearstream cash account.
5. Reconciliation - The reconcile instruction on the distributions program cross-checks on-chain claim records with Clearstream corporate action confirmations. Total distributed must equal total waterfall output for the epoch. The Trustee signs the reconciliation report.

Bankable Distribution Detail

Regulatory Filing Service

The Regulatory Filing Service is a Go grain (compliance-grain) responsible for generating the documents and data feeds that regulators require. Every offering on the platform operates under a specific regulatory exemption - Reg D 506(b), Reg D 506(c), Reg S, Reg A+, or Reg CF - and each exemption carries its own filing and reporting obligations.

Service: compliance-grain (Go)
├── Form D Filing (SEC) - generate XML for EDGAR
├── Blue Sky State Filings - track per-state exemptions
├── Reg S Compliance - non-US investor tracking
├── AML/SAR Reporting - suspicious activity flagging
├── Cap Table Reporting - ownership snapshots for tax season
├── K-1 Generation - for LLC pass-through taxation
└── Audit Export - full audit trail in standard format

Form D (SEC EDGAR)

Every Reg D offering must file Form D with the SEC within 15 days of first sale. The compliance grain generates the complete Form D XML document conforming to the SEC’s EDGAR schema, populated from on-chain offering state and issuer metadata stored in the Offering Grain journal.

• Initial filing: Auto-generated when the first SecurityMinted event is recorded for a Reg D offering. Pre-populated with Series LLC details, offering terms, exemption type, and issuer information.
• Annual amendments: The grain tracks the 12-month filing anniversary and generates amendment XML with updated sales totals, investor counts, and use-of-proceeds data.
• Human review: All generated filings are routed to the compliance officer for review and approval before EDGAR submission. The grain surfaces the filing in the DAO Manager compliance dashboard with a review/approve/reject workflow.

Blue Sky State Filings

Reg D offerings require notice filings in each state where securities are sold. The compliance grain tracks investor jurisdictions (from KYC credential metadata - jurisdiction hash, not raw PII) and maintains a per-state filing status matrix.

AML/SAR Reporting

The compliance grain monitors transaction patterns for suspicious activity. When the sails_securities transfer hook or the KYC grain flags anomalous behavior - unusual transfer volumes, rapid CrossConversion cycling, jurisdiction mismatches - the grain generates a Suspicious Activity Report (SAR) draft for compliance officer review. SAR filing is never automated; the grain produces the draft, the compliance officer decides whether to file.

K-1 Tax Documents

Because the Wyoming DAO Series LLC structure uses pass-through taxation, every investor who received distributions during the tax year needs a Schedule K-1. The compliance grain generates K-1 documents by combining:

• On-chain distribution records (amounts per epoch, per investor)
• Clearstream corporate action confirmations (for bankable holders)
• Investor tax identification data (stored encrypted in the KYC grain journal - accessed via Powerbox capability, never copied)

K-1 documents are generated annually, routed to the issuer’s tax preparer for review, and delivered to investors via the Notification Service.

Monitoring & Health

The TradFi Bridge spans two fundamentally different systems - a blockchain with deterministic state and a traditional settlement infrastructure with batch processing and business-hours operations. Monitoring must cover both sides and the connection between them.

Solana Program Monitoring

Grain Health

CrossConversion Reconciliation Dashboard

A real-time dashboard that visualizes the core 1:1 invariant across every offering with CrossConversion enabled:

• Per-offering view: On-chain lockbox state (tokens_locked) vs. Clearstream position report (isin_outstanding). Green when matched, red on any discrepancy.
• Historical trend: Lockbox and Clearstream totals plotted over time. Any divergence is immediately visible.
• Last reconciliation timestamp: Time since the last Trustee-signed reconciliation per offering. Stale reconciliation (> 36 hours) triggers a P1 alert.
• Pending conversions: CrossConversion requests in flight - submitted but not yet confirmed by Clearstream. Pending > 4 hours triggers a P1 alert.

Alerting Tiers

Next Steps

• Clearstream Integration - Deep dive into the Clearstream Adapter: ISIN registration, SWIFT settlement, reconciliation, and communication protocols
• Hybrid Architecture - The CrossConversion Engine: lockbox contract, conversion flows, and the 1:1 invariant
• ISIN Conversion - The complete CrossConversion lifecycle from on-chain to bankable and back
• Distributions API - Waterfall configuration, revenue deposit, and distribution claiming
• Compliance Framework - KYC credentials, jurisdiction rules, and transfer enforcement
• Platform Overview - The three-pillar architecture and grain types