ISIN Conversion

Overview

CrossConversion is the mechanism that makes CrossSecurities hybrid. It is the bridge between two worlds: Solana tokens that live on-chain and ISIN-identified securities held in traditional financial infrastructure at Clearstream.

Two directions, one invariant:

• Cross to Bankable: Lock Solana tokens in the on-chain lockbox → Issue ISIN-identified securities via Clearstream.
• Cross to On-Chain: Cancel the Clearstream position → Unlock Solana tokens from the lockbox.

The 1:1 invariant is the foundation of the entire system:

tokens_locked == isin_outstanding

This is not a target. This is not a guideline. This is a mathematical constraint enforced by smart contract logic on every lock and unlock operation, validated by nightly reconciliation, and audited by an appointed Trustee. If it ever breaks, the system halts and alerts fire. Always. The total supply of a CrossConversion Series is constant — tokens are either circulating on Solana or locked in the lockbox with a corresponding ISIN position at Clearstream. Never both. Never neither.

For the broader architectural context, see the Hybrid Architecture documentation. This page covers the lockbox contract, the step-by-step conversion flows, trustee authentication, reconciliation, and SWIFT messaging in full technical detail.

The Lockbox Contract

The lockbox is an on-chain PDA (Program Derived Address) controlled by the sails_crossconversion program. It holds tokens in escrow during their bankable life. No human has custody of the locked tokens — only the program logic can release them, and only when the correct cryptographic proofs are provided.

Program Instructions

Program: sails_crossconversion
├── init_lockbox(offering_id, isin_code, clearstream_account)
│   → Creates the CrossConversionLockbox PDA for the offering
│   → Links the on-chain lockbox to a specific Clearstream account
│   → Stores the ISIN code in lockbox metadata
│   → Requires Platform Operator NFT authorization
├── lock_tokens(offering_id, amount)
│   → Transfers tokens from investor wallet to lockbox PDA
│   → Increments the locked counter
│   → Emits CrossConversionRequested event
│   → Requires valid KYC Credential NFT on the requesting wallet
├── unlock_tokens(offering_id, amount, trustee_signature, clearstream_proof)
│   → Verifies Clearstream cancellation proof
│   → Validates Trustee NFT signature
│   → Releases tokens from lockbox PDA back to investor wallet
│   → Decrements the locked counter
│   → Emits CrossConversionCompleted event
├── get_lockbox_state(offering_id)
│   → Returns { locked, isin_outstanding, isin_code, clearstream_ref }
│   → Read-only — callable by any authenticated participant
└── reconcile(offering_id, clearstream_snapshot_hash)
    → Trustee-signed reconciliation (periodic, e.g., daily)
    → Compares on-chain state with Clearstream snapshot hash
    → Emits ReconciliationCompleted or ReconciliationFailed event
    → On failure: freezes CrossConversion for the affected offering

CrossConversionLockbox PDA Structure

Each offering with CrossConversion enabled has a dedicated lockbox PDA. The PDA is derived from the offering ID and the sails_crossconversion program address, making it deterministic and verifiable by anyone:

Field	Type	Description
offering_id	Pubkey	The offering this lockbox serves
total_locked	u64	Total tokens currently locked in the PDA
isin_code	String	The ISIN identifier assigned by Clearstream (e.g., XS1234567890)
clearstream_ref	String	Clearstream account reference for settlement
last_reconciliation	i64	Unix timestamp of the last successful reconciliation
reconciliation_hash	[u8; 32]	SHA-256 hash of the last Clearstream snapshot used in reconciliation
frozen	bool	If true, all CrossConversion operations are halted pending resolution

The total_locked field is the on-chain source of truth. It is incremented on every lock_tokens and decremented on every unlock_tokens. The Clearstream side maintains its own isin_outstanding count. The reconciliation engine exists to prove these two numbers are always equal.

Cross to Bankable Flow

An investor holding security tokens on Solana wants them in their brokerage account as ISIN-identified securities. Here is exactly what happens, step by step:

1. Investor requests conversion — Through their Investor Self-Service grain, the investor selects an offering and specifies the number of tokens to convert to bankable format.
2. Tokens locked in lockbox PDA — The lock_tokens instruction transfers the specified tokens from the investor's wallet to the lockbox PDA. The locked counter increments. The tokens are now in escrow — the investor no longer controls them on-chain.
3. CrossConversionRequested event emitted — The Solana program emits an on-chain event containing the offering ID, amount, investor wallet, and conversion direction.
4. Operator Service picks up the event — The CrossConversion Operator Service (a Sandstorm grain subscribed to Solana events via WebSocket RPC) detects the CrossConversionRequested event.
5. KYC validation — The Operator verifies that the investor's KYC Credential NFT is valid, unexpired, and carries the correct accreditation tier and jurisdiction clearance for the offering.
6. Trustee authentication — The Operator routes the conversion request to the appointed Trustee for authentication. The Trustee signs the conversion with their Trustee NFT. For conversions over $1M, 2-of-3 threshold signing is required.
7. ISIN issuance initiated with Clearstream — The Operator submits an MT540 (Receive Free) settlement instruction to Clearstream, instructing them to credit the investor's account with the ISIN-identified securities.
8. Clearstream confirms issuance — Clearstream processes the instruction, credits the investor's securities account, and returns a confirmation with settlement details.
9. Proof stored on-chain — The Operator stores the Clearstream proof-of-issuance in the lockbox PDA metadata, creating an auditable on-chain record that links the locked tokens to the issued ISIN position.
10. Investor sees ISIN in brokerage account — The ISIN-identified securities appear in the investor's brokerage account at their custodian, visible through standard financial infrastructure just like any other security.

From the investor's perspective: tokens disappear from their Solana wallet and securities appear in their brokerage account. From the system's perspective: the invariant holds — total_locked increased by exactly the amount of ISIN securities issued.

Cross to On-Chain Flow

The reverse: an investor holding ISIN-identified securities at Clearstream wants them back as Solana tokens. This flow requires stronger validation because it releases tokens from escrow.

1. Investor requests reverse conversion — Through their Investor Self-Service grain or via their broker, the investor requests conversion of their ISIN position back to on-chain tokens.
2. Trustee verifies the request — The appointed Trustee reviews and authenticates the request. The Trustee confirms that the investor holds the claimed ISIN position and that the conversion is permissible under the offering's compliance rules (lock-up periods, jurisdiction restrictions, transfer limits).
3. Clearstream position cancellation — The Operator submits an MT542 (Deliver Free) settlement instruction to Clearstream, instructing them to cancel the investor's ISIN position for the specified amount.
4. Clearstream provides cancellation proof — Clearstream processes the instruction, debits the investor's securities account, and returns cryptographic proof of cancellation.
5. Operator triggers unlock_tokens — The Operator calls unlock_tokens on the sails_crossconversion program, providing the Trustee's NFT signature and the Clearstream cancellation proof as parameters.
6. Smart contract validates proofs — The program verifies the Trustee NFT signature is valid and the Clearstream proof is authentic before releasing any tokens. Both must pass. No exceptions.
7. Tokens released to wallet — The lockbox PDA transfers the tokens back to the investor's Solana wallet. The locked counter decrements. The CrossConversionCompleted event is emitted.

The asymmetry is intentional. Locking tokens (Cross to Bankable) requires a valid KYC credential and Trustee authentication. Unlocking tokens (Cross to On-Chain) requires Trustee authentication and cryptographic proof from Clearstream that the ISIN position has been cancelled. You cannot unlock tokens without proving the corresponding bankable position no longer exists.

Trustee Authentication

Every CrossConversion — forward or reverse — requires authentication by an appointed Trustee holding a valid Trustee NFT minted by the Melusina authority program. The Trustee is the human-in-the-loop that prevents automated systems from moving securities without oversight.

Authentication Thresholds

Conversion Value	Threshold	Requirement
Standard (≤ $1M)	1-of-1	Single Trustee NFT signature. The appointed Trustee for the offering reviews and signs the conversion request.
Large (> $1M)	2-of-3	Two of three designated Trustees must independently review and sign. Implemented via threshold cryptography from the Melusina program's signing scheme.

Authentication Flow

1. Request routed to Trustee Dashboard — The CrossConversion Operator Service sends the conversion request to the Trustee Dashboard grain via Powerbox capability.
2. Trustee reviews details — The Trustee sees the offering, amount, investor identity (KYC-verified, not PII), conversion direction, and any applicable compliance flags.
3. NFT signature — The Trustee signs the conversion with their Trustee NFT. The signature is verified on-chain by the sails_crossconversion program.
4. Threshold collection — For large conversions, the Operator collects signatures from the required number of Trustees before proceeding. All signatures must be collected within a configurable time window.
5. Audit logged — Every authentication action — approval, rejection, timeout — is logged to the Trustee Dashboard grain's append-only journal. Seven-year retention. No exceptions.

The Trustee cannot initiate conversions — only authenticate them. The Trustee cannot modify conversion amounts or redirect tokens. The Trustee has exactly one power: approve or reject. This separation of concerns is by design. See the Authentication documentation for the full four-layer model and the role NFT hierarchy.

Reconciliation

Trust but verify — every night, automatically, without fail. The Reconciliation Engine is the safety net that proves the 1:1 invariant holds across both systems.

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

Nightly Reconciliation Process

1. Pull Clearstream positions — The Reconciliation Engine 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 engine calls get_lockbox_state to retrieve the current total_locked value.
3. Compare totals — For each offering: tokens_locked must equal isin_outstanding. No tolerance. No rounding. Exact match.
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 with the snapshot hash. The last_reconciliation timestamp updates. Business as usual.
7. On mismatch — The program emits a ReconciliationFailed event. A P0 alert fires (immediate response required). 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.
• Trustee-signed resolution — The Trustee must sign a resolution report before CrossConversion resumes. The resolution is stored on-chain for audit.

SWIFT Messaging

Communication with Clearstream follows established financial messaging standards. The TradFi bridge adapter service handles all message generation, submission, and response parsing — translating between the Sails.to Cap'n Proto schema and the messaging formats that traditional financial infrastructure expects.

Settlement Instructions

Message Type	Standard	Direction	Purpose
MT540	SWIFT	Cross to Bankable	Receive Free — instructs Clearstream to credit the investor's account with ISIN-identified securities. Generated by the Operator after tokens are locked and Trustee authentication is complete.
MT542	SWIFT	Cross to On-Chain	Deliver Free — instructs Clearstream to cancel the investor's ISIN position. Generated by the Operator after the Trustee authenticates the reverse conversion request.

Corporate Actions

Message Standard	Purpose	Examples
ISO 20022	Corporate action notifications and instructions for ISIN-identified positions	Distribution notifications, voting instructions, maturity events, coupon payments, and other corporate events that affect bankable positions held at Clearstream

The TradFi bridge adapter runs as a Go service within the Sandstorm environment (grain or sidecar). It maintains message queues, handles retries on transient failures, validates message schemas before submission, and logs every message sent and received to the grain's append-only journal. Every SWIFT message generated by the platform is traceable to a specific CrossConversion request, a specific Trustee authentication, and a specific on-chain transaction.

Next Steps

• Hybrid Architecture — The broader architectural context for the CrossConversion Engine
• Authentication — The four-layer authentication model and Trustee NFT hierarchy
• Token Standard — How CrossSecurities tokens work on Solana
• Compliance Framework — KYC credentials and transfer enforcement rules
• Transfer Rules — Compliance checks enforced at the protocol level on every transfer
• API Reference — Cap'n Proto schemas for programmatic access to CrossConversion operations