Clearstream Integration

Overview

Clearstream is the international central securities depository (ICSD) that makes CrossSecurities hybrid. When an investor converts on-chain tokens to bankable format via CrossConversion, the resulting ISIN-identified securities are held in custody at Clearstream - visible through standard brokerage infrastructure, settleable through established financial rails, and recognizable by every institution in traditional finance.

The integration is not a wrapper or an abstraction. It is a direct, bidirectional connection between the Sails.to platform and Clearstream's settlement infrastructure. Tokens locked in the on-chain lockbox have a 1:1 corresponding ISIN position at Clearstream. The CrossConversion Engine enforces this invariant. The Clearstream Adapter is the service that makes it operationally real.

Lead time for onboarding: 4–8 weeks from application to production API access. This must be initiated early - Clearstream account setup and API credential provisioning cannot be parallelized with other integration work.

The Clearstream Adapter

The Clearstream Adapter is a Go service that runs as a grain or sidecar within the Sandstorm/Melusina OS environment. It handles all communication between the Sails.to platform and Clearstream, translating between Cap'n Proto RPC calls and the SWIFT/ISO messaging formats that Clearstream expects.

Service: clearstream-adapter (Go, runs as grain or sidecar)
├── ISIN Registration
│   ├── Submit ISIN application for new offerings
│   ├── Track application status through approval
│   └── Store assigned ISIN code in OfferingState PDA
├── Settlement
│   ├── Credit investor's Clearstream account (on CrossConversion)
│   ├── Cancel Clearstream position (on reverse CrossConversion)
│   └── Handle corporate actions (distributions, votes)
├── Reconciliation
│   ├── Pull daily Clearstream position report
│   ├── Compare with on-chain lockbox state
│   └── Generate discrepancy report for Trustee
└── Communication
    ├── MT540/MT542 SWIFT messages (settlement instructions)
    ├── ISO 20022 messages (corporate actions)
    └── Webhook notifications for real-time updates

The adapter maintains its own append-only journal for every message sent and received. Every SWIFT instruction generated by the platform is traceable to a specific CrossConversion request, a specific Trustee authentication, and a specific on-chain transaction. Seven-year retention. No exceptions.

Adapter Capabilities

ISIN Registration

Before any CrossConversion can occur for an offering, the security must have an ISIN - the International Securities Identification Number that makes the instrument recognizable to traditional financial infrastructure. The Clearstream Adapter manages this process end-to-end.

Registration Workflow

1. Issuer configures offering for CrossConversion - In the Offering grain, the issuer enables CrossConversion and provides the required security metadata: instrument type, nominal value, currency, maturity terms, and jurisdiction.
2. Adapter submits ISIN application - The Clearstream Adapter packages the security metadata into a registration request and submits it to Clearstream. Cost: approximately $4,000 per ISIN application.
3. Status tracking - The adapter polls Clearstream for application status updates. Typical turnaround: approximately 1 week from submission to approval. Status transitions are logged to the adapter's journal and surfaced in the Offering grain UI.
4. ISIN assigned - Clearstream assigns the ISIN code (e.g., XS1234567890). The adapter receives the assignment notification.
5. On-chain storage - The adapter writes the assigned ISIN code to the OfferingState PDA on Solana, linking the on-chain offering to its Clearstream identity. This also triggers the initialization of the CrossConversionLockbox PDA via init_lockbox.
6. CrossConversion enabled - With the ISIN registered and the lockbox initialized, the offering is ready for CrossConversion operations.

ISIN Application Data

Settlement Operations

Settlement is where CrossConversion becomes real. When tokens lock on-chain, the Clearstream Adapter ensures the corresponding ISIN position appears in the investor's Clearstream account. When a reverse conversion occurs, the adapter ensures the position is cancelled before tokens are released.

Cross to Bankable (Credit)

When an investor requests a CrossConversion from on-chain to bankable format:

1. Tokens locked - The sails_crossconversion program locks the investor's tokens in the lockbox PDA and emits a CrossConversionRequested event.
2. Trustee authenticates - The Trustee reviews and signs the conversion with their Trustee NFT.
3. Adapter generates MT540 - The Clearstream Adapter constructs an MT540 (Receive Free of Payment) SWIFT message instructing Clearstream to credit the investor's securities account.
4. Clearstream confirms - Clearstream processes the instruction and returns a settlement confirmation with reference details.
5. Proof stored on-chain - The adapter writes the Clearstream proof-of-issuance to the lockbox PDA metadata, linking the locked tokens to the issued ISIN position.

Cross to On-Chain (Cancel)

When an investor requests the reverse - moving their ISIN position back to on-chain tokens:

1. Trustee authenticates - The Trustee verifies the investor holds the claimed ISIN position and that the conversion is permissible under the offering's compliance rules.
2. Adapter generates MT542 - The Clearstream Adapter constructs an MT542 (Deliver Free of Payment) SWIFT message instructing Clearstream to cancel the investor's ISIN position.
3. Clearstream confirms cancellation - Clearstream debits the investor's securities account and returns cryptographic proof of cancellation.
4. Tokens unlocked - The adapter triggers unlock_tokens on the sails_crossconversion program, providing the Trustee's NFT signature and the Clearstream cancellation proof. The lockbox releases the tokens to the investor's wallet.

Corporate Actions

ISIN-identified securities held at Clearstream are subject to corporate actions - events that affect all holders of the instrument. The Clearstream Adapter processes these automatically:

Reconciliation

The reconciliation engine is the safety net that proves the 1:1 invariant holds across both systems - every night, automatically, without fail. The Clearstream Adapter owns the Clearstream side of this process.

tokens_locked == isin_outstanding    // Always. No tolerance. No rounding.

Two Sources of Truth

Daily Reconciliation Process

1. Pull Clearstream positions - The adapter requests the daily position report from Clearstream for all active ISINs linked to Sails offerings.
2. Read on-chain lockbox state - For every offering with CrossConversion enabled, the adapter calls get_lockbox_state to retrieve the current total_locked value.
3. Compare totals - For each offering: tokens_locked must equal isin_outstanding. Exact integer match. No tolerance. No rounding.
4. Generate reconciliation report - A detailed report covering every offering, every position, every discrepancy (if any), timestamped and formatted for audit.
5. Trustee signs the report - The appointed Trustee reviews and signs the reconciliation report. The signature and a SHA-256 hash of the Clearstream snapshot are stored on-chain via the reconcile instruction.
6. On match - The program emits a ReconciliationCompleted event. The last_reconciliation timestamp updates. Business as usual.
7. On mismatch - The program emits a ReconciliationFailed event. A P0 alert fires. The affected offering's CrossConversion capability is frozen until manual resolution by the Trustee.

Discrepancy Handling

A supply mismatch should never happen. The smart contract enforces the invariant on every lock and unlock. But the reconciliation engine exists because defense in depth is not optional when you hold other people's securities. If a discrepancy is detected:

• Immediate freeze - All CrossConversion operations for the affected offering halt. No new locks. No new unlocks.
• P0 alert - The Platform Operator, Trustee, and compliance team receive immediate notification.
• Root cause investigation - Manual review of all transactions since the last successful reconciliation, using the adapter's append-only journal as the audit trail.
• Trustee-signed resolution - The Trustee must sign a resolution report before CrossConversion resumes. The resolution is stored on-chain for audit.

Communication Protocols

The Clearstream Adapter translates between the Sails.to Cap'n Proto schema and the messaging formats that traditional financial infrastructure expects. All messages are validated against their respective schemas before submission.

Settlement Instructions (SWIFT)

Corporate Action Messages (ISO 20022)

Real-Time Notifications

In addition to structured SWIFT and ISO 20022 messaging, the adapter receives real-time webhook notifications from Clearstream for time-sensitive events:

• Settlement confirmations - Immediate notification when an MT540/MT542 instruction has been processed and the investor's account updated.
• Failed settlement alerts - If a settlement instruction is rejected or fails validation, the adapter is notified immediately so the CrossConversion can be rolled back before the on-chain state becomes inconsistent.
• Position change notifications - Any change to ISIN positions outside the normal CrossConversion flow (e.g., regulatory freeze on the Clearstream side) triggers an alert.
• Corporate action deadlines - Advance notice of upcoming corporate action deadlines requiring platform response.

Message Flow

┌──────────────┐       Cap'n Proto        ┌─────────────────────┐
│  CrossConv   │ ─────────────────────►   │  Clearstream        │
│  Operator    │                          │  Adapter            │
│  (Grain)     │ ◄─────────────────────   │  (Grain / Sidecar)  │
└──────────────┘                          └──────────┬──────────┘
                                                     │
                                          SWIFT MT5xx │ ISO 20022
                                          Webhooks    │
                                                     ▼
                                          ┌─────────────────────┐
                                          │  Clearstream        │
                                          │  Settlement Engine  │
                                          │  (ICSD)             │
                                          └─────────────────────┘

The adapter maintains message queues with at-least-once delivery semantics. Transient failures trigger automatic retries with exponential backoff. Every message - sent or received - is logged to the grain's append-only journal with the originating CrossConversion request ID, enabling full end-to-end traceability.

Operational Requirements

Before the Clearstream integration can go live, the following must be in place:

Account Setup

Environment Tiers

Adapter Configuration

# clearstream-adapter.toml (per environment)
[clearstream]
base_url       = "https://api.clearstream.com/v1"     # sandbox or production
client_id      = "${CLEARSTREAM_CLIENT_ID}"
client_secret  = "${CLEARSTREAM_CLIENT_SECRET}"
bic            = "CABORGSAILS"
account_id     = "${CLEARSTREAM_ACCOUNT_ID}"
[settlement]
retry_max      = 5
retry_backoff  = “exponential”       # 1s, 2s, 4s, 8s, 16s
timeout_sec    = 30
[reconciliation]
schedule       = “0 2 * * *”         # Daily at 02:00 UTC
alert_on_fail  = true
freeze_on_fail = true
[webhook]
listen_port    = 8443
tls_cert       = “/etc/certs/clearstream-webhook.pem”
tls_key        = “/etc/certs/clearstream-webhook-key.pem”
verify_sig     = true                # Validate Clearstream webhook signatures

Next Steps

• ISIN Conversion - The complete CrossConversion Engine: lockbox contract, conversion flows, trustee authentication, and SWIFT messaging
• Hybrid Architecture - How on-chain and bankable layers compose into a single regulated system
• Compliance Framework - KYC credentials, jurisdiction rules, and transfer enforcement
• Platform Overview - The three-pillar architecture and grain types
• Authentication - The four-layer authentication model and Trustee NFT hierarchy
• API Reference - Cap’n Proto schemas for programmatic access