Documentation

Clearstream Integration

The international central securities depository that provides the bankable side of CrossSecurities — where ISIN-identified securities live in traditional finance.

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

Functional Area Responsibility Interfaces
ISIN Registration Application submission, status tracking, code storage Clearstream registration API → OfferingState PDA
Settlement Credit/cancel investor positions, corporate action processing MT540/MT542 → Clearstream settlement engine
Reconciliation Daily position comparison, discrepancy detection, report generation Clearstream position report → on-chain lockbox state
Communication Message generation, schema validation, retry handling, audit logging SWIFT MT5xx, ISO 20022, webhook listeners

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

Field Description Example
instrument_type Security classification per Clearstream taxonomy Equity, Debt, Fund Unit
issuer_name Legal name of the issuing Series LLC Sails Series A LLC
nominal_value Par value per unit in the denomination currency $100.00 USD
total_supply Maximum issuable quantity (matches on-chain max_supply) 1,000,000
currency Denomination currency (ISO 4217) USD, EUR, GBP
jurisdiction Governing law jurisdiction US-WY (Wyoming)
reg_exemption Applicable regulatory exemption Reg D 506(b), Reg S

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:

Corporate Action Description On-Chain Effect
Distributions Dividend or interest payments to ISIN holders Adapter notifies the Offering grain; the sails_distributions waterfall ensures on-chain holders receive equivalent payouts pro-rata
Voting Governance votes affecting the instrument Adapter routes voting instructions to the DAO Manager grain for coordination with on-chain governance
Maturity Events Bond maturity, fund liquidation, or offering close Triggers the offering close workflow — all ISIN positions must be reverse-converted before final redemption
Coupon Payments Periodic interest payments on debt instruments Processed through the sails_distributions waterfall; Clearstream handles the bankable side, on-chain program handles token holders

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

Source Data Authority
On-Chain Lockbox Total tokens locked per offering, per investor position Solana program state (immutable, auditable)
Clearstream Holdings ISIN positions, settlement status, corporate actions Clearstream daily position report

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)

Message Type Standard Direction Purpose
MT540 SWIFT Cross to Bankable Receive Free of Payment — instructs Clearstream to credit the investor's account with ISIN-identified securities. Generated after tokens are locked and Trustee authentication is complete.
MT541 SWIFT Cross to Bankable Receive Against Payment — used when the CrossConversion involves a cash settlement component (e.g., initial subscription with fiat payment).
MT542 SWIFT Cross to On-Chain Deliver Free of Payment — instructs Clearstream to cancel the investor's ISIN position. Generated after the Trustee authenticates the reverse conversion request.

Corporate Action Messages (ISO 20022)

Message Standard Purpose
seev.031 ISO 20022 Corporate action notification — Clearstream informs the adapter of upcoming events (distributions, votes, maturity) affecting ISIN positions.
seev.033 ISO 20022 Corporate action instruction — The adapter responds with processing instructions for how the platform wishes to handle the event.
seev.035 ISO 20022 Corporate action movement confirmation — Clearstream confirms the corporate action has been processed and positions updated.

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

Requirement Description Lead Time
Clearstream Account Corporate account with Clearstream Banking S.A. The legal entity (the Wyoming DAO Series LLC or its designated custodian) must complete Clearstream's onboarding process including KYC/AML due diligence. 4–8 weeks
API Credentials OAuth 2.0 client credentials for Clearstream's REST and messaging APIs. Separate credentials per environment. Credentials are rotated on a 90-day cycle. Included in account setup
SWIFT BIC Registration Business Identifier Code for SWIFT message routing. Required for MT540/MT542 settlement instructions. 2–4 weeks
Participant Agreement Legal agreement governing the use of Clearstream's settlement and custody services, including fee schedules and liability terms. Concurrent with account setup

Environment Tiers

Environment Clearstream Tier Sails Environment Purpose
Development Clearstream Sandbox (simulated) Local / Devnet Unit and integration testing with mocked Clearstream responses. No real settlement occurs.
Staging Clearstream Sandbox (full) Solana Devnet End-to-end testing with Clearstream's sandbox environment. Real API calls, simulated settlement. ISIN codes are test-only.
Production Clearstream Production Solana Mainnet Live settlement. Real ISIN positions. Real investor accounts. Real money. Every operation is final and auditable.

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