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:

Service	Role	Interfaces
Solana Event Watcher	Subscribes to on-chain program events, routes them to the correct grains	Solana WebSocket RPC → Cap'n Proto grain calls
Clearstream Adapter	ISIN registration, settlement instructions, daily reconciliation	SWIFT MT5xx, ISO 20022, Clearstream REST API
Notification Service	Email, webhook, and in-app notifications to all participants	SMTP / Sandstorm email, WebSocket hub, broker webhook endpoints
Revenue & Distribution Bridge	Routes waterfall outputs to on-chain holders and bankable holders	sails_distributions program → Clearstream corporate actions
Regulatory Filing Service	Generates Form D XML, Blue Sky filings, AML/SAR reports, K-1 documents	SEC EDGAR, state regulators, compliance grain journal

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

On-Chain Event	Source Program	Destination Grain	Action
SecurityMinted	sails_securities	Offering Grain	Update cap table, record new investor position, trigger subscription confirmation notification
CrossConversionRequested	sails_crossconversion	CrossConversion Operator	Initiate CrossConversion workflow — KYC validation, Trustee authentication, Clearstream settlement
DistributionPaid	sails_distributions	Investor Grains	Notify investors of available distribution, update portfolio view, trigger tax document generation
ComplianceViolation	sails_securities	DAO Manager	P0 alert to compliance team, log violation details, potentially freeze affected accounts
TransferCompleted	sails_securities	Broker Grain	Confirm secondary trade settlement, update broker commission records, notify both counterparties

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

Notification	Trigger	Recipients	Channels
Subscription Confirmation	SecurityMinted event	Investor, placing Broker	Email, in-app, broker webhook
Distribution Available	DistributionPaid event	All token holders for the offering	Email, in-app
CrossConversion Status	Operator state transitions	Requesting investor, Trustee	Email, in-app
KYC Status Change	KYC grain workflow completion	Investor, compliance officer	Email, in-app
Compliance Alert	ComplianceViolation event	DAO Manager, compliance team	Email (P0), in-app, PagerDuty webhook
Regulatory Notice	Filing deadline, regulatory update	Issuer, compliance officer	Email
Reconciliation Report	Nightly reconciliation completion	Trustee, Platform Operator	Email, in-app

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

Step	System	Action
1. Identify bankable holders	CrossConversion Lockbox (PDA)	Query all investors with locked tokens for this offering — these are the bankable holders who cannot claim on-chain
2. Calculate pro-rata amounts	Distribution Bridge (grain)	For each bankable holder: (locked_tokens / total_supply) × epoch_distribution
3. Issue corporate action	Clearstream Adapter	Generate ISO 20022 seev.031 corporate action notification → Clearstream processes cash credit to each investor’s securities account
4. Confirm settlement	Clearstream	Returns seev.035 movement confirmation per investor — cash credited
5. Record on-chain	Distribution Bridge	Writes Clearstream confirmation hashes to the distribution record PDA — proving bankable holders were paid for this epoch

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.

Data Point	Source	Purpose
Investor state	KYC Credential NFT jurisdiction hash	Determine which states require notice filing
Filing deadline	State-specific rules (typically 15 days post-sale)	Generate deadline alerts for compliance officer
Filing fee	State fee schedule (maintained in grain config)	Calculate total filing costs per offering
Filing status	Compliance grain journal	Track pending / submitted / accepted / rejected per state

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

Metric	Source	Alert Threshold
Instruction success rate	Solana Event Watcher	< 99.5% over 5-minute window → P1
Compute unit usage	Transaction metadata	> 80% of limit per instruction → P2
Account size	On-chain account data	> 90% of allocated space → P2
Event delivery latency	Watcher journal timestamps	> 30s from slot confirmation to grain delivery → P1
WebSocket connection status	Watcher health check	Disconnected > 60s → P0

Grain Health

Metric	Source	Alert Threshold
CPU utilization	Sandstorm OS metrics	> 80% sustained for 5 minutes → P2
Memory usage	Sandstorm OS metrics	> 90% of grain allocation → P1
Journal size	Grain storage metrics	> 80% of storage quota → P2
WebSocket connections	Per-grain hub metrics	> 1,000 concurrent connections per grain → P2
Journal replay time	Grain restart metrics	> 30s replay duration → P2 (journal compaction needed)

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

Tier	Response Time	Examples	Notification Channels
P0 — Immediate	< 15 minutes	Supply invariant mismatch, security breach, Solana program failure, Clearstream settlement rejection	PagerDuty, SMS, email to Platform Operator + Trustee + compliance
P1 — Urgent	< 1 hour	KYC service degradation, Clearstream API timeout, threshold signing failure, stale reconciliation, event delivery latency	PagerDuty, email to on-call engineer + Platform Operator
P2 — Operational	< 24 hours	Elevated error rates, approaching account size limits, certificate expiration within 30 days, journal compaction needed	Email to engineering team, in-app dashboard alert

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